feat(dev-ports): 485 — derive every dev port from the branch name

[randomdevpete]

Summary

Adopts <root>/TODOS/DEV-SERVERS.md's port scheme in jarl. One module (scripts/devPorts.mts)
derives every dev/preview/e2e port from the worktree's branch name; every Vite server, the
Playwright fixture and the docs custom SSR dev server now read from it instead of a hardcoded
port. npm run ports prints the block (--write-env writes gitignored .env.ports).

Confirmed ordinal and block: jarl is row 2 of board/projects.md (PROJECT_ORDINAL = 2),
giving master the block 9970–9979 with 9960–9969 reserved (the old integration block) —
matches both board/projects.md's dev port block column and DEV-SERVERS.md's worked table.
scripts/__tests__/devPorts.test.mts asserts devPortBase(-1) === 9970 with no ordinal argument
passed, so a copy-paste of headrooms' PROJECT_ORDINAL = 1 fails the suite rather than silently
colliding with headrooms' own master.

Offset map (this worktree's block, base = the block above):

offset	service
+0	docs site SSR dev server (npm run dev)
+5	docs production-build preview (npm run docs:preview)
+6	Playwright fixture app (e2e/fixture-app, dialled by e2e/playwright.config.ts)

No dev-server port literal survives: swept the branch with
rg '4173|4321|:3000|--port|strict-port|strictPort|baseURL|webServer|localhost|127\.0\.0\.1'
and every remaining hit is either a derived value, a production port (see Exceptions), or
prose/test assertions against baseURL passed in by Playwright.

Exceptions

Four deliberate deviations, called out here rather than silently applied:

1. No -2/integration mapping.parseTaskId never produces -2 from a branch name;
   devPortBase(-2) still computes the reserved slot if ever passed explicitly. This diverges
   from headrooms' reference devPorts.ts, which still has an integration case — that module is
   stale against DEV-SERVERS.md ("-2 stays reserved and unassigned") and TODOS CLAUDE.md
   ("There is no integration branch"). Tracked as ticket 877; not fixed here.
2. Two production 3000 literals survive, both outside any dev-server path:
   infra/lib/jarl-stacks.ts's ssrPort (written into the jarl-ssr systemd unit's
   Environment=PORT=) and the matching curl http://localhost:3000/healthz in
   .github/workflows/ci.yml's deploy job. packages/docs/src/prod-server.ts now requires PORT
   and throws without it — safe, because the systemd unit always sets it.
3. Root npm test is now vitest run && npm run test --workspaces --if-present, with a new
   root vitest.config.ts scoped to scripts/**/__tests__/**/*.test.mts only — it does not
   re-collect packages/jarl-atoms/packages/jarl-react's own workspace-scoped vitest configs.
4. .mts rather than .ts for the new scripts/ modules, because jarl's root package.json
   has no "type": "module". Root tsconfig.json includes scripts/**/*.mts;
   tsconfig.base.json gains allowImportingTsExtensions, which is inert under its existing
   noEmit: true.

Test plan

• oxfmt --check clean over every file the branch touches (run from master's binary against
  absolute paths — this worktree has no node_modules)
• Literal-port sweep, see above
• CI (ci) — watching after this PR opens

[randomdevpete]

Summary

Adopts <root>/TODOS/DEV-SERVERS.md's port scheme in jarl. One module (scripts/devPorts.mts)
derives every dev/preview/e2e port from the worktree's branch name; every Vite server, the
Playwright fixture and the docs custom SSR dev server now read from it instead of a hardcoded
port. npm run ports prints the block (--write-env writes gitignored .env.ports).

Confirmed ordinal and block: jarl is row 2 of board/projects.md (PROJECT_ORDINAL = 2),
giving master the block 9970–9979 with 9960–9969 reserved (the old integration block) —
matches both board/projects.md's dev port block column and DEV-SERVERS.md's worked table.
scripts/__tests__/devPorts.test.mts asserts devPortBase(-1) === 9970 with no ordinal argument
passed, so a copy-paste of headrooms' PROJECT_ORDINAL = 1 fails the suite rather than silently
colliding with headrooms' own master.

Offset map (this worktree's block, base = the block above):

offset	service
+0	docs site SSR dev server (npm run dev)
+5	docs production-build preview (npm run docs:preview)
+6	Playwright fixture app (e2e/fixture-app, dialled by e2e/playwright.config.ts)

No dev-server port literal survives: swept the branch with
rg '4173|4321|:3000|--port|strict-port|strictPort|baseURL|webServer|localhost|127\.0\.0\.1'
and every remaining hit is either a derived value, a production port (see Exceptions), or
prose/test assertions against baseURL passed in by Playwright.

Exceptions

Four deliberate deviations, called out here rather than silently applied:

1. No -2/integration mapping.parseTaskId never produces -2 from a branch name;
   devPortBase(-2) still computes the reserved slot if ever passed explicitly. This diverges
   from headrooms' reference devPorts.ts, which still has an integration case — that module is
   stale against DEV-SERVERS.md ("-2 stays reserved and unassigned") and TODOS CLAUDE.md
   ("There is no integration branch"). Tracked as ticket 877; not fixed here.
2. Two production 3000 literals survive, both outside any dev-server path:
   infra/lib/jarl-stacks.ts's ssrPort (written into the jarl-ssr systemd unit's
   Environment=PORT=) and the matching curl http://localhost:3000/healthz in
   .github/workflows/ci.yml's deploy job. packages/docs/src/prod-server.ts now requires PORT
   and throws without it — safe, because the systemd unit always sets it.
3. Root npm test is now vitest run && npm run test --workspaces --if-present, with a new
   root vitest.config.ts scoped to scripts/**/__tests__/**/*.test.mts only — it does not
   re-collect packages/jarl-atoms/packages/jarl-react's own workspace-scoped vitest configs.
4. .mts rather than .ts for the new scripts/ modules, because jarl's root package.json
   has no "type": "module". Root tsconfig.json includes scripts/**/*.mts;
   tsconfig.base.json gains allowImportingTsExtensions, which is inert under its existing
   noEmit: true.

Test plan

• oxfmt --check clean over every file the branch touches (run from master's binary against
  absolute paths — this worktree has no node_modules)
• Literal-port sweep, see above
• CI (ci) — watching after this PR opens

[randomdevpete]

Summary

Adopts <root>/TODOS/DEV-SERVERS.md's port scheme in jarl. One module (scripts/devPorts.mts)
derives every dev/preview/e2e port from the worktree's branch name; every Vite server, the
Playwright fixture and the docs custom SSR dev server now read from it instead of a hardcoded
port. npm run ports prints the block (--write-env writes gitignored .env.ports).

Confirmed ordinal and block: jarl is row 2 of board/projects.md (PROJECT_ORDINAL = 2),
giving master the block 9970–9979 with 9960–9969 reserved (the old integration block) —
matches both board/projects.md's dev port block column and DEV-SERVERS.md's worked table.
scripts/__tests__/devPorts.test.mts asserts devPortBase(-1) === 9970 with no ordinal argument
passed, so a copy-paste of headrooms' PROJECT_ORDINAL = 1 fails the suite rather than silently
colliding with headrooms' own master.

Offset map (this worktree's block, base = the block above):

offset	service
+0	docs site SSR dev server (npm run dev)
+5	docs production-build preview (npm run docs:preview)
+6	Playwright fixture app (e2e/fixture-app, dialled by e2e/playwright.config.ts)

No dev-server port literal survives: swept the branch with
rg '4173|4321|:3000|--port|strict-port|strictPort|baseURL|webServer|localhost|127\.0\.0\.1'
and every remaining hit is either a derived value, a production port (see Exceptions), or
prose/test assertions against baseURL passed in by Playwright.

Exceptions

Four deliberate deviations, called out here rather than silently applied:

1. No -2/integration mapping.parseTaskId never produces -2 from a branch name;
   devPortBase(-2) still computes the reserved slot if ever passed explicitly. This diverges
   from headrooms' reference devPorts.ts, which still has an integration case — that module is
   stale against DEV-SERVERS.md ("-2 stays reserved and unassigned") and TODOS CLAUDE.md
   ("There is no integration branch"). Tracked as ticket 877; not fixed here.
2. Two production 3000 literals survive, both outside any dev-server path:
   infra/lib/jarl-stacks.ts's ssrPort (written into the jarl-ssr systemd unit's
   Environment=PORT=) and the matching curl http://localhost:3000/healthz in
   .github/workflows/ci.yml's deploy job. packages/docs/src/prod-server.ts now requires PORT
   and throws without it — safe, because the systemd unit always sets it.
3. Root npm test is now vitest run && npm run test --workspaces --if-present, with a new
   root vitest.config.ts scoped to scripts/**/__tests__/**/*.test.mts only — it does not
   re-collect packages/jarl-atoms/packages/jarl-react's own workspace-scoped vitest configs.
4. .mts rather than .ts for the new scripts/ modules, because jarl's root package.json
   has no "type": "module". Root tsconfig.json includes scripts/**/*.mts;
   tsconfig.base.json gains allowImportingTsExtensions, which is inert under its existing
   noEmit: true.

Test plan

• oxfmt --check clean over every file the branch touches (run from master's binary against
  absolute paths — this worktree has no node_modules)
• Literal-port sweep, see above
• CI (ci) — watching after this PR opens

[randomdevpete]

Summary

Adopts <root>/TODOS/DEV-SERVERS.md's port scheme in jarl. One module (scripts/devPorts.mts)
derives every dev/preview/e2e port from the worktree's branch name; every Vite server, the
Playwright fixture and the docs custom SSR dev server now read from it instead of a hardcoded
port. npm run ports prints the block (--write-env writes gitignored .env.ports).

Confirmed ordinal and block: jarl is row 2 of board/projects.md (PROJECT_ORDINAL = 2),
giving master the block 9970–9979 with 9960–9969 reserved (the old integration block) —
matches both board/projects.md's dev port block column and DEV-SERVERS.md's worked table.
scripts/__tests__/devPorts.test.mts asserts devPortBase(-1) === 9970 with no ordinal argument
passed, so a copy-paste of headrooms' PROJECT_ORDINAL = 1 fails the suite rather than silently
colliding with headrooms' own master.

Offset map (this worktree's block, base = the block above):

offset	service
+0	docs site SSR dev server (npm run dev)
+5	docs production-build preview (npm run docs:preview)
+6	Playwright fixture app (e2e/fixture-app, dialled by e2e/playwright.config.ts)

No dev-server port literal survives: swept the branch with
rg '4173|4321|:3000|--port|strict-port|strictPort|baseURL|webServer|localhost|127\.0\.0\.1'
and every remaining hit is either a derived value, a production port (see Exceptions), or
prose/test assertions against baseURL passed in by Playwright.

Exceptions

Four deliberate deviations, called out here rather than silently applied:

1. No -2/integration mapping.parseTaskId never produces -2 from a branch name;
   devPortBase(-2) still computes the reserved slot if ever passed explicitly. This diverges
   from headrooms' reference devPorts.ts, which still has an integration case — that module is
   stale against DEV-SERVERS.md ("-2 stays reserved and unassigned") and TODOS CLAUDE.md
   ("There is no integration branch"). Tracked as ticket 877; not fixed here.
2. Two production 3000 literals survive, both outside any dev-server path:
   infra/lib/jarl-stacks.ts's ssrPort (written into the jarl-ssr systemd unit's
   Environment=PORT=) and the matching curl http://localhost:3000/healthz in
   .github/workflows/ci.yml's deploy job. packages/docs/src/prod-server.ts now requires PORT
   and throws without it — safe, because the systemd unit always sets it.
3. Root npm test is now vitest run && npm run test --workspaces --if-present, with a new
   root vitest.config.ts scoped to scripts/**/__tests__/**/*.test.mts only — it does not
   re-collect packages/jarl-atoms/packages/jarl-react's own workspace-scoped vitest configs.
4. .mts rather than .ts for the new scripts/ modules, because jarl's root package.json
   has no "type": "module". Root tsconfig.json includes scripts/**/*.mts;
   tsconfig.base.json gains allowImportingTsExtensions, which is inert under its existing
   noEmit: true.

Test plan

• oxfmt --check clean over every file the branch touches (run from master's binary against
  absolute paths — this worktree has no node_modules)
• Literal-port sweep, see above
• CI (ci) — watching after this PR opens

[randomdevpete]

Summary

Adopts <root>/TODOS/DEV-SERVERS.md's port scheme in jarl. One module (scripts/devPorts.mts)
derives every dev/preview/e2e port from the worktree's branch name; every Vite server, the
Playwright fixture and the docs custom SSR dev server now read from it instead of a hardcoded
port. npm run ports prints the block (--write-env writes gitignored .env.ports).

Confirmed ordinal and block: jarl is row 2 of board/projects.md (PROJECT_ORDINAL = 2),
giving master the block 9970–9979 with 9960–9969 reserved (the old integration block) —
matches both board/projects.md's dev port block column and DEV-SERVERS.md's worked table.
scripts/__tests__/devPorts.test.mts asserts devPortBase(-1) === 9970 with no ordinal argument
passed, so a copy-paste of headrooms' PROJECT_ORDINAL = 1 fails the suite rather than silently
colliding with headrooms' own master.

Offset map (this worktree's block, base = the block above):

offset	service
+0	docs site SSR dev server (npm run dev)
+5	docs production-build preview (npm run docs:preview)
+6	Playwright fixture app (e2e/fixture-app, dialled by e2e/playwright.config.ts)

No dev-server port literal survives: swept the branch with
rg '4173|4321|:3000|--port|strict-port|strictPort|baseURL|webServer|localhost|127\.0\.0\.1'
and every remaining hit is either a derived value, a production port (see Exceptions), or
prose/test assertions against baseURL passed in by Playwright.

Exceptions

Four deliberate deviations, called out here rather than silently applied:

1. No -2/integration mapping.parseTaskId never produces -2 from a branch name;
   devPortBase(-2) still computes the reserved slot if ever passed explicitly. This diverges
   from headrooms' reference devPorts.ts, which still has an integration case — that module is
   stale against DEV-SERVERS.md ("-2 stays reserved and unassigned") and TODOS CLAUDE.md
   ("There is no integration branch"). Tracked as ticket 877; not fixed here.
2. Two production 3000 literals survive, both outside any dev-server path:
   infra/lib/jarl-stacks.ts's ssrPort (written into the jarl-ssr systemd unit's
   Environment=PORT=) and the matching curl http://localhost:3000/healthz in
   .github/workflows/ci.yml's deploy job. packages/docs/src/prod-server.ts now requires PORT
   and throws without it — safe, because the systemd unit always sets it.
3. Root npm test is now vitest run && npm run test --workspaces --if-present, with a new
   root vitest.config.ts scoped to scripts/**/__tests__/**/*.test.mts only — it does not
   re-collect packages/jarl-atoms/packages/jarl-react's own workspace-scoped vitest configs.
4. .mts rather than .ts for the new scripts/ modules, because jarl's root package.json
   has no "type": "module". Root tsconfig.json includes scripts/**/*.mts;
   tsconfig.base.json gains allowImportingTsExtensions, which is inert under its existing
   noEmit: true.

Test plan

• oxfmt --check clean over every file the branch touches (run from master's binary against
  absolute paths — this worktree has no node_modules)
• Literal-port sweep, see above
• CI (ci) — watching after this PR opens

[randomdevpete]

Summary

Adopts <root>/TODOS/DEV-SERVERS.md's port scheme in jarl. One module (scripts/devPorts.mts)
derives every dev/preview/e2e port from the worktree's branch name; every Vite server, the
Playwright fixture and the docs custom SSR dev server now read from it instead of a hardcoded
port. npm run ports prints the block (--write-env writes gitignored .env.ports).

Confirmed ordinal and block: jarl is row 2 of board/projects.md (PROJECT_ORDINAL = 2),
giving master the block 9970–9979 with 9960–9969 reserved (the old integration block) —
matches both board/projects.md's dev port block column and DEV-SERVERS.md's worked table.
scripts/__tests__/devPorts.test.mts asserts devPortBase(-1) === 9970 with no ordinal argument
passed, so a copy-paste of headrooms' PROJECT_ORDINAL = 1 fails the suite rather than silently
colliding with headrooms' own master.

Offset map (this worktree's block, base = the block above):

offset	service
+0	docs site SSR dev server (npm run dev)
+5	docs production-build preview (npm run docs:preview)
+6	Playwright fixture app (e2e/fixture-app, dialled by e2e/playwright.config.ts)

No dev-server port literal survives: swept the branch with
rg '4173|4321|:3000|--port|strict-port|strictPort|baseURL|webServer|localhost|127\.0\.0\.1'
and every remaining hit is either a derived value, a production port (see Exceptions), or
prose/test assertions against baseURL passed in by Playwright.

Exceptions

Four deliberate deviations, called out here rather than silently applied:

1. No -2/integration mapping.parseTaskId never produces -2 from a branch name;
   devPortBase(-2) still computes the reserved slot if ever passed explicitly. This diverges
   from headrooms' reference devPorts.ts, which still has an integration case — that module is
   stale against DEV-SERVERS.md ("-2 stays reserved and unassigned") and TODOS CLAUDE.md
   ("There is no integration branch"). Tracked as ticket 877; not fixed here.
2. Two production 3000 literals survive, both outside any dev-server path:
   infra/lib/jarl-stacks.ts's ssrPort (written into the jarl-ssr systemd unit's
   Environment=PORT=) and the matching curl http://localhost:3000/healthz in
   .github/workflows/ci.yml's deploy job. packages/docs/src/prod-server.ts now requires PORT
   and throws without it — safe, because the systemd unit always sets it.
3. Root npm test is now vitest run && npm run test --workspaces --if-present, with a new
   root vitest.config.ts scoped to scripts/**/__tests__/**/*.test.mts only — it does not
   re-collect packages/jarl-atoms/packages/jarl-react's own workspace-scoped vitest configs.
4. .mts rather than .ts for the new scripts/ modules, because jarl's root package.json
   has no "type": "module". Root tsconfig.json includes scripts/**/*.mts;
   tsconfig.base.json gains allowImportingTsExtensions, which is inert under its existing
   noEmit: true.

Test plan

• oxfmt --check clean over every file the branch touches (run from master's binary against
  absolute paths — this worktree has no node_modules)
• Literal-port sweep, see above
• CI (ci) — watching after this PR opens

[randomdevpete]

Summary

Adopts <root>/TODOS/DEV-SERVERS.md's port scheme in jarl. One module (scripts/devPorts.mts)
derives every dev/preview/e2e port from the worktree's branch name; every Vite server, the
Playwright fixture and the docs custom SSR dev server now read from it instead of a hardcoded
port. npm run ports prints the block (--write-env writes gitignored .env.ports).

Confirmed ordinal and block: jarl is row 2 of board/projects.md (PROJECT_ORDINAL = 2),
giving master the block 9970–9979 with 9960–9969 reserved (the old integration block) —
matches both board/projects.md's dev port block column and DEV-SERVERS.md's worked table.
scripts/__tests__/devPorts.test.mts asserts devPortBase(-1) === 9970 with no ordinal argument
passed, so a copy-paste of headrooms' PROJECT_ORDINAL = 1 fails the suite rather than silently
colliding with headrooms' own master.

Offset map (this worktree's block, base = the block above):

offset	service
+0	docs site SSR dev server (npm run dev)
+5	docs production-build preview (npm run docs:preview)
+6	Playwright fixture app (e2e/fixture-app, dialled by e2e/playwright.config.ts)

No dev-server port literal survives: swept the branch with
rg '4173|4321|:3000|--port|strict-port|strictPort|baseURL|webServer|localhost|127\.0\.0\.1'
and every remaining hit is either a derived value, a production port (see Exceptions), or
prose/test assertions against baseURL passed in by Playwright.

Exceptions

Four deliberate deviations, called out here rather than silently applied:

1. No -2/integration mapping.parseTaskId never produces -2 from a branch name;
   devPortBase(-2) still computes the reserved slot if ever passed explicitly. This diverges
   from headrooms' reference devPorts.ts, which still has an integration case — that module is
   stale against DEV-SERVERS.md ("-2 stays reserved and unassigned") and TODOS CLAUDE.md
   ("There is no integration branch"). Tracked as ticket 877; not fixed here.
2. Two production 3000 literals survive, both outside any dev-server path:
   infra/lib/jarl-stacks.ts's ssrPort (written into the jarl-ssr systemd unit's
   Environment=PORT=) and the matching curl http://localhost:3000/healthz in
   .github/workflows/ci.yml's deploy job. packages/docs/src/prod-server.ts now requires PORT
   and throws without it — safe, because the systemd unit always sets it.
3. Root npm test is now vitest run && npm run test --workspaces --if-present, with a new
   root vitest.config.ts scoped to scripts/**/__tests__/**/*.test.mts only — it does not
   re-collect packages/jarl-atoms/packages/jarl-react's own workspace-scoped vitest configs.
4. .mts rather than .ts for the new scripts/ modules, because jarl's root package.json
   has no "type": "module". Root tsconfig.json includes scripts/**/*.mts;
   tsconfig.base.json gains allowImportingTsExtensions, which is inert under its existing
   noEmit: true.

Test plan

• oxfmt --check clean over every file the branch touches (run from master's binary against
  absolute paths — this worktree has no node_modules)
• Literal-port sweep, see above
• CI (ci) — watching after this PR opens

[randomdevpete]

Summary

Adopts <root>/TODOS/DEV-SERVERS.md's port scheme in jarl. One module (scripts/devPorts.mts)
derives every dev/preview/e2e port from the worktree's branch name; every Vite server, the
Playwright fixture and the docs custom SSR dev server now read from it instead of a hardcoded
port. npm run ports prints the block (--write-env writes gitignored .env.ports).

Confirmed ordinal and block: jarl is row 2 of board/projects.md (PROJECT_ORDINAL = 2),
giving master the block 9970–9979 with 9960–9969 reserved (the old integration block) —
matches both board/projects.md's dev port block column and DEV-SERVERS.md's worked table.
scripts/__tests__/devPorts.test.mts asserts devPortBase(-1) === 9970 with no ordinal argument
passed, so a copy-paste of headrooms' PROJECT_ORDINAL = 1 fails the suite rather than silently
colliding with headrooms' own master.

Offset map (this worktree's block, base = the block above):

offset	service
+0	docs site SSR dev server (npm run dev)
+5	docs production-build preview (npm run docs:preview)
+6	Playwright fixture app (e2e/fixture-app, dialled by e2e/playwright.config.ts)

No dev-server port literal survives: swept the branch with
rg '4173|4321|:3000|--port|strict-port|strictPort|baseURL|webServer|localhost|127\.0\.0\.1'
and every remaining hit is either a derived value, a production port (see Exceptions), or
prose/test assertions against baseURL passed in by Playwright.

Exceptions

Four deliberate deviations, called out here rather than silently applied:

1. No -2/integration mapping.parseTaskId never produces -2 from a branch name;
   devPortBase(-2) still computes the reserved slot if ever passed explicitly. This diverges
   from headrooms' reference devPorts.ts, which still has an integration case — that module is
   stale against DEV-SERVERS.md ("-2 stays reserved and unassigned") and TODOS CLAUDE.md
   ("There is no integration branch"). Tracked as ticket 877; not fixed here.
2. Two production 3000 literals survive, both outside any dev-server path:
   infra/lib/jarl-stacks.ts's ssrPort (written into the jarl-ssr systemd unit's
   Environment=PORT=) and the matching curl http://localhost:3000/healthz in
   .github/workflows/ci.yml's deploy job. packages/docs/src/prod-server.ts now requires PORT
   and throws without it — safe, because the systemd unit always sets it.
3. Root npm test is now vitest run && npm run test --workspaces --if-present, with a new
   root vitest.config.ts scoped to scripts/**/__tests__/**/*.test.mts only — it does not
   re-collect packages/jarl-atoms/packages/jarl-react's own workspace-scoped vitest configs.
4. .mts rather than .ts for the new scripts/ modules, because jarl's root package.json
   has no "type": "module". Root tsconfig.json includes scripts/**/*.mts;
   tsconfig.base.json gains allowImportingTsExtensions, which is inert under its existing
   noEmit: true.

Test plan

• oxfmt --check clean over every file the branch touches (run from master's binary against
  absolute paths — this worktree has no node_modules)
• Literal-port sweep, see above
• CI (ci) — watching after this PR opens