Skill Tracer
Skills › Compound Engineering › ce-polish › dev-server-detection.md

dev-server-detection.md

40 lines · skills/ce-polish/references/dev-server-detection.md at 3449230

Open on GitHub

Most marks come from matching words in the file, so treat them as pointers.

1# Dev-server port detection
2
3Port resolution runs via `scripts/resolve-port.sh`. This document explains the probe order, framework defaults, and the script's intentional parsing choices.
4
5This cascade runs only while the startup tuple's port remains unresolved. A numeric port from the selected launch configuration completes that fact and skips this cascade. When the cascade is needed, it supplies only the port; it never replaces a selected command, working directory, or environment.
6

Dev-server port detection

Port resolution runs via scripts/resolve-port.sh. This document explains the probe order, framework defaults, and the script's intentional parsing choices.

This cascade runs only while the startup tuple's port remains unresolved. A numeric port from the selected launch configuration completes that fact and skips this cascade. When the cascade is needed, it supplies only the port; it never replaces a selected command, working directory, or environment.

Raw lines 1 to 6
Runs code scripts/resolve-port.sh :3
7## Priority order
8
91. **Explicit `--port` flag** -- if the caller passed `--port <n>`, use it directly.
102. **Framework config files** -- `next.config.*`, `vite.config.*`, `nuxt.config.*`, `astro.config.*` scanned with a conservative regex matching only numeric literal port values. Variable references (`process.env.PORT`, `getPort()`) are deliberately not matched.
113. **Rails `config/puma.rb`** -- grep for `port <n>`.
124. **`Procfile.dev`** -- web line scanned for `-p <n>` / `--port <n>` / `-p=<n>` / `--port=<n>`.
135. **`docker-compose.yml`** -- line-anchored grep for `"<n>:<n>"` port mapping patterns. Not full YAML parsing.
146. **`package.json`** -- `dev`/`start` scripts scanned for `--port <n>` / `-p <n>` / `--port=<n>` / `-p=<n>`.
157. **`.env` files** -- checked in override order: `.env.local` -> `.env.development` -> `.env` (first hit wins). Parses `PORT=<n>` with quote stripping and comment truncation.
168. **Framework default lookup table** -- see table below.

Priority order

  1. **Explicit --port flag** -- if the caller passed --port <n>, use it directly.
  2. Framework config files -- next.config.*, vite.config.*, nuxt.config.*, astro.config.* scanned with a conservative regex matching only numeric literal port values. Variable references (process.env.PORT, getPort()) are deliberately not matched.
  3. **Rails config/puma.rb** -- grep for port <n>.
  4. **Procfile.dev** -- web line scanned for -p <n> / --port <n> / -p=<n> / --port=<n>.
  5. **docker-compose.yml** -- line-anchored grep for "<n>:<n>" port mapping patterns. Not full YAML parsing.
  6. **package.json** -- dev/start scripts scanned for --port <n> / -p <n> / --port=<n> / -p=<n>.
  7. **.env files** -- checked in override order: .env.local -> .env.development -> .env (first hit wins). Parses PORT=<n> with quote stripping and comment truncation.
  8. Framework default lookup table -- see table below.
Raw lines 7 to 17
18## Framework defaults
20| Framework | Default port |
21|-----------|-------------|
22| Rails | 3000 |
23| Next.js | 3000 |
24| Nuxt | 3000 |
25| Remix (classic) | 3000 |
26| Vite | 5173 |
27| SvelteKit | 5173 |
28| Astro | 4321 |
29| Procfile | 3000 |
30| Unknown | 3000 |

Framework defaults

FrameworkDefault port
Rails3000
Next.js3000
Nuxt3000
Remix (classic)3000
Vite5173
SvelteKit5173
Astro4321
Procfile3000
Unknown3000
Raw lines 18 to 31
32## `.env` parsing choices
34`resolve-port.sh` makes two deliberate parsing choices for real-world `.env` files; do not "simplify" them away:
36**(a) Quote stripping on `.env` values.** Strips surrounding `"` and `'` from `PORT=` values (so `PORT="3001"` resolves to `3001`), because quoting is common in real `.env` files.
38**(b) Comment stripping on `.env` values.** Truncates at `#` after trimming whitespace (so `PORT=3001 # dev only` resolves to `3001`), because inline comments are common.
40**(c) No instruction-file port grep.** The script does not grep `AGENTS.md`/`CLAUDE.md` for port references. Instruction files carry natural language that may mention ports in contexts unrelated to the dev server (documentation, examples, troubleshooting), producing false positives that are hard to debug; the filename is also harness-specific. Framework config files and `.env` are the reliable sources of truth. The agent may still honor a dev-server port it reads from its in-context project instructions, but the script does not shell-grep named instruction files.

.env parsing choices

resolve-port.sh makes two deliberate parsing choices for real-world .env files; do not "simplify" them away:

**(a) Quote stripping on .env values.** Strips surrounding " and ' from PORT= values (so PORT="3001" resolves to 3001), because quoting is common in real .env files.

**(b) Comment stripping on .env values.** Truncates at # after trimming whitespace (so PORT=3001 # dev only resolves to 3001), because inline comments are common.

(c) No instruction-file port grep. The script does not grep AGENTS.md/CLAUDE.md for port references. Instruction files carry natural language that may mention ports in contexts unrelated to the dev server (documentation, examples, troubleshooting), producing false positives that are hard to debug; the filename is also harness-specific. Framework config files and .env are the reliable sources of truth. The agent may still honor a dev-server port it reads from its in-context project instructions, but the script does not shell-grep named instruction files.

Raw lines 32 to 40
Project instruction file AGENTS.md :40
Project instruction file CLAUDE.md :40