feat(dev): assign per-worktree dev ports via preflight script (#1963)

* feat(dev): assign per-worktree dev ports via preflight script

Every git worktree gets its own gitignored compass.yaml defaulting to
the same ports (web 9080, backend 3000), so the second worktree's dev
server crashes with EADDRINUSE.

Fix it at config level instead of runtime: dev:web/dev:backend now run
a small preflight (dev:ports) that copies compass.yaml from the main
checkout when missing, and — only when this worktree's ports are
claimed by a sibling worktree's compass.yaml — rewrites web.port,
web.url, backend.port, backend.apiUrl, and the localhost originsAllowed
entries to the next free pair. Comments and secrets are preserved via
the yaml Document API, reruns are no-ops, and customized URLs (tunnels,
real domains) are left alone.

Because each worktree's config stays internally consistent, no app code
changes at all: CORS, SuperTokens domains, and the web bundle's baked
API_BASEURL all keep working through their existing paths. Playwright
is unaffected — it launches dev.ts directly, bypassing the preflight.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat(dev): sync .claude/launch.json ports with assigned worktree ports

.claude/launch.json hardcodes the same default ports as compass.yaml,
so preview tooling was still pointed at 9080/3000 in a worktree that
dev-ports.ts had reassigned elsewhere. The preflight now keeps the
Backend/Web entries in sync via a surgical regex replace of just the
port digits (not JSON.parse + stringify, which would reformat every
line and produce a noisy diff for a two-number change) — mirroring the
minimal-diff approach already used for compass.yaml. Debug Web (a
static http-server on 8080, unrelated to compass config) is untouched.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* refactor(scripts): simplify dev-ports port search and dedupe sibling lookup

Extract siblingConfigPaths() to remove a duplicated filter/map/filter
chain from readSiblingPorts() and ensureConfigExists(), and split the
~50-line main() into findNextPorts() (pure port-search loop) and a
shared isPortsClaimed() predicate, so main() reads as three named
phases instead of one long function with an inline loop.

No behavior change; verified with dev-ports.test.ts and a live run.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: tyler-dane

bun.lock

@@ -124,6 +124,27 @@ Bun build/dev behavior:
 - Mongo persistence
 - SSE stream behavior
 
+## Multiple Worktrees
+
+`bun run dev:web` and `bun run dev:backend` run a small preflight
+(`bun run dev:ports`) that gives each git worktree its own dev ports. If this
+worktree has no `compass.yaml` yet, the preflight copies it from the main
+checkout; if its ports are already claimed by another worktree's
+`compass.yaml`, it rewrites `web.port`, `web.url`, `backend.port`,
+`backend.apiUrl`, and the localhost `originsAllowed` entries to the next free
+pair (9081/3001, 9082/3002, ...). Comments and secrets in the file are
+preserved, and reruns are no-ops. `.claude/launch.json`'s `Backend`/`Web`
+preview-tooling ports are kept in sync the same way.
+
+Notes:
+
+- The main checkout keeps the defaults (9080/3000).
+- If `web.url` or `backend.apiUrl` is customized (e.g. a tunnel or real
+  domain), the preflight leaves the file alone — manage ports manually.
+- Real Google sign-in only works on ports whose redirect URIs are registered
+  in Google Cloud Console; pin a worktree back to the default ports if you
+  need it.
+
 ## Backend Health Probe
 
 When debugging backend startup or connectivity issues, use the health endpoint first:

docs/development/local-development.md

@@ -19,9 +19,10 @@
     "debug:supertokens": "export DEBUG=com.supertokens &&bun run dev:backend",
     "debug:web": "http-server build/web/",
     "dev:backend -verbose": "export DEBUG=* &&bun run dev:backend",
-    "dev:backend": "cd packages/backend && bun --watch src/app.ts",
+    "dev:backend": "bun run dev:ports && cd packages/backend && bun --watch src/app.ts",
+    "dev:ports": "bun packages/scripts/src/commands/dev-ports.ts",
     "dev:update": "git checkout main && git pull &&bun install",
-    "dev:web": "cd packages/web &&bun run dev.ts",
+    "dev:web": "bun run dev:ports && cd packages/web &&bun run dev.ts",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",

package.json

@@ -11,7 +11,8 @@
     "commander": "^10.0.0",
     "inquirer": "^8.0.0",
     "open": "^10.1.0",
-    "umzug": "^3.8.2"
+    "umzug": "^3.8.2",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/inquirer": "^9.0.1",

packages/scripts/package.json

@@ -0,0 +1,148 @@
+import {
+  readPorts,
+  reassignPorts,
+  syncLaunchConfig,
+} from "@scripts/commands/dev-ports";
+
+const SAMPLE_YAML = `# Compass Config
+# hand-written setup notes live here
+
+runtime:
+  nodeEnv: development
+  timezone: Etc/UTC
+
+web:
+  port: 9080
+  url: http://localhost:9080
+
+backend:
+  port: 3000
+  apiUrl: http://localhost:3000/api
+  originsAllowed:
+    - http://localhost:3000
+    - http://localhost:9080
+    - https://staging.example.com
+  compassToken: super-secret-token
+
+mongo:
+  # keep this uri pointed at the dev cluster
+  uri: mongodb+srv://admin:s3cret@cluster0.example.mongodb.net/dev_calendar
+`;
+
+describe("readPorts", () => {
+  it("reads configured ports", () => {
+    expect(readPorts(SAMPLE_YAML)).toEqual({ web: 9080, backend: 3000 });
+  });
+
+  it("falls back to defaults when ports are missing", () => {
+    expect(readPorts("web:\n  url: http://localhost:9080\n")).toEqual({
+      web: 9080,
+      backend: 3000,
+    });
+  });
+
+  it("returns null for malformed yaml", () => {
+    expect(readPorts("{{ not yaml")).toBeNull();
+  });
+});
+
+describe("reassignPorts", () => {
+  const next = { web: 9081, backend: 3001 };
+
+  it("rewrites ports, urls, and localhost origins consistently", () => {
+    const result = reassignPorts(SAMPLE_YAML, next);
+
+    expect(result).toContain("port: 9081");
+    expect(result).toContain("url: http://localhost:9081");
+    expect(result).toContain("port: 3001");
+    expect(result).toContain("apiUrl: http://localhost:3001/api");
+    expect(result).toContain("- http://localhost:3001");
+    expect(result).toContain("- http://localhost:9081");
+    expect(result).not.toContain("9080");
+    expect(result).not.toContain(": 3000");
+  });
+
+  it("preserves comments, secrets, and non-localhost origins", () => {
+    const result = reassignPorts(SAMPLE_YAML, next);
+
+    expect(result).toContain("# hand-written setup notes live here");
+    expect(result).toContain("# keep this uri pointed at the dev cluster");
+    expect(result).toContain("compassToken: super-secret-token");
+    expect(result).toContain(
+      "mongodb+srv://admin:s3cret@cluster0.example.mongodb.net/dev_calendar",
+    );
+    expect(result).toContain("- https://staging.example.com");
+  });
+
+  it("bails when apiUrl is customized (e.g. a tunnel)", () => {
+    const customized = SAMPLE_YAML.replace(
+      "apiUrl: http://localhost:3000/api",
+      "apiUrl: https://example.trycloudflare.com/api",
+    );
+    expect(reassignPorts(customized, next)).toBeNull();
+  });
+
+  it("bails when web.url is customized", () => {
+    const customized = SAMPLE_YAML.replace(
+      "url: http://localhost:9080",
+      "url: https://compass.example.com",
+    );
+    expect(reassignPorts(customized, next)).toBeNull();
+  });
+});
+
+describe("syncLaunchConfig", () => {
+  const SAMPLE_LAUNCH = `{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "Backend",
+      "runtimeExecutable": "/opt/homebrew/bin/bun",
+      "runtimeArgs": ["dev:backend"],
+      "port": 3000
+    },
+    {
+      "name": "Web",
+      "runtimeExecutable": "/opt/homebrew/bin/bun",
+      "runtimeArgs": ["run", "dev:web"],
+      "port": 9080
+    },
+    {
+      "name": "Debug Web",
+      "runtimeExecutable": "/opt/homebrew/bin/bun",
+      "runtimeArgs": ["run", "debug:web"],
+      "port": 8080
+    }
+  ]
+}
+`;
+
+  it("replaces only the port digits, leaving every other line untouched", () => {
+    const result = syncLaunchConfig(SAMPLE_LAUNCH, {
+      web: 9081,
+      backend: 3001,
+    });
+
+    expect(result).toContain(
+      '"runtimeArgs": ["dev:backend"],\n      "port": 3001',
+    );
+    expect(result).toContain(
+      '"runtimeArgs": ["run", "dev:web"],\n      "port": 9081',
+    );
+    expect(result).toContain('"port": 8080'); // Debug Web untouched
+    expect(JSON.parse(result as string)).toEqual(
+      JSON.parse(
+        SAMPLE_LAUNCH.replace('"port": 3000', '"port": 3001').replace(
+          '"port": 9080',
+          '"port": 9081',
+        ),
+      ),
+    );
+  });
+
+  it("returns null when ports already match (no-op)", () => {
+    expect(
+      syncLaunchConfig(SAMPLE_LAUNCH, { web: 9080, backend: 3000 }),
+    ).toBeNull();
+  });
+});