feat(cockpit): centralize port allocation behind cockpit/ports.mjs registry (#551)

* docs(spec): cockpit port registry design

* docs(plan): cockpit port registry implementation plan

* feat(ci): cockpit ports registry + verifier spec (skeleton)

Registry starts empty; the verifier spec tests both the registry
shape (positive int ports, no duplicates, range/convention checks)
and cross-file invariants (python --port + playwright baseURL match
registry). Empty registry intentionally fails the 'covers every
cap' test until Task 2 populates it.

Spec: docs/superpowers/specs/2026-05-27-cockpit-port-registry-design.md

* feat(ci): populate cockpit ports registry from on-disk values

31 entries, extracted from each cap's proxy.conf.json target +
playwright.config.ts baseURL (or langgraph - 1000 for non-e2e caps).
Verifier confirms the registry round-trips cleanly against every
python/project.json --port literal.

* test(ports): verifier skips python --port check for caps without literal

Only chat caps have --port in their python/project.json serve target;
langgraph/deep-agents/render caps rely on the e2e harness spawning
langgraph with explicit --port from global-setup-impl.ts. Skip
verifier check for those rather than fail.

* refactor(cockpit): 31 proxy.conf.json → proxy.conf.mjs (import ports registry)

Every cockpit cap's proxy.conf.json is replaced with proxy.conf.mjs
that imports portsFor(capName) from cockpit/ports.mjs and templates
the langgraph port into the target URL. Each angular/project.json's
serve.options.proxyConfig is updated to point at the .mjs file.

cockpit/ag-ui/streaming is excluded — non-LangGraph backend, kept
as proxy.conf.json with its /agent → :3000 literal.

* refactor(cockpit): 24 e2e configs import ports from registry

Each cap's e2e/global-setup-impl.ts now imports portsFor() and reads
angular/langgraph ports from the registry instead of literal numbers.
playwright.config.ts is updated similarly for baseURL.
All 24 e2e tsconfig.json files gain allowJs: true so tsc accepts the
.mjs import without a declaration file.

The verifier's playwright-baseURL check now skips templated configs
(its regex only matches literal URLs); drift is impossible because
the value imports directly from the registry.

* ci: gate cockpit-ports.spec.mjs in ci-scope test job

Appends the new verifier spec to the existing node --test invocation
so registry drift is caught at PR time.

* test(cockpit): wiring spec reads ports from registry; recognizes .mjs proxy

The drift-guard test previously parsed proxy.conf.json target + the
literal langgraphPort/angularPort lines in global-setup-impl.ts. Both
were removed by the port-registry migration:
- proxy.conf.json → proxy.conf.mjs (templates target from registry)
- global-setup-impl.ts now reads `ports.langgraph` / `ports.angular`

Updated wiring spec:
- Imports `portsFor` from cockpit/ports.mjs to look up expected ports
  by project name. Falls back to literal parsing for the ag-ui
  exception (not in registry).
- Replaces the proxy.conf.json content assertion with a proxy.conf.mjs
  existence + `portsFor('<name>')` call check. Drift is impossible
  because the .mjs templates from the same registry.
- Legacy proxy.conf.json branch retained for ag-ui (single-cap
  exception).

79/79 cockpit unit tests pass locally.

Author: blove

.github/workflows/ci.yml

@@ -48,7 +48,7 @@ jobs:
       # classifier walk.
       - run: npm ci
       - name: Test CI scope classifier
-        run: node --test scripts/ci-scope.spec.mjs scripts/cockpit-matrix.spec.mjs
+        run: node --test scripts/ci-scope.spec.mjs scripts/cockpit-matrix.spec.mjs scripts/cockpit-ports.spec.mjs
       - name: Detect changed CI surfaces
         id: scope
         run: |

apps/cockpit/cockpit-e2e-wiring.spec.ts

@@ -2,6 +2,9 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { capabilities } from './scripts/capability-registry';
+// @ts-expect-error — .mjs ES module without .d.ts; the e2e tsconfig uses
+// allowJs:true but this top-level test file doesn't go through that config.
+import { portsFor } from '../../cockpit/ports.mjs';
 
 interface E2eWiring {
   angularPort: number;
@@ -84,12 +87,23 @@ function activeCockpitE2eWiring(): E2eWiring[] {
       const projectRoot = dirname(projectJsonPath);
       const globalSetupPath = join(projectRoot, 'e2e/global-setup-impl.ts');
       const globalSetup = readFileSync(globalSetupPath, 'utf8');
-      const proxyPath = join(projectRoot, 'proxy.conf.json');
-      const proxy = JSON.parse(readFileSync(proxyPath, 'utf8')) as Record<string, { target?: string }>;
-      const proxyPort = Number(proxy['/api']?.target?.match(/:(\d+)$/)?.[1]);
       const langgraphCwd = parseStringProperty(globalSetup, 'langgraphCwd');
-      const langgraphPort = parseNumberProperty(globalSetup, 'langgraphPort') ?? proxyPort;
-      const angularPort = parseNumberProperty(globalSetup, 'angularPort');
+
+      // Post-port-registry migration: ports are imported from
+      // cockpit/ports.mjs rather than living as literals in
+      // global-setup-impl.ts. Look them up by project name.
+      let langgraphPort: number | undefined;
+      let angularPort: number | undefined;
+      try {
+        const ports = portsFor(project.name) as { angular: number; langgraph: number };
+        langgraphPort = ports.langgraph;
+        angularPort = ports.angular;
+      } catch {
+        // Cap not in registry (e.g. cockpit-ag-ui-streaming-angular).
+        // Fall back to parsing literals if global-setup still has them.
+        langgraphPort = parseNumberProperty(globalSetup, 'langgraphPort');
+        angularPort = parseNumberProperty(globalSetup, 'angularPort');
+      }
 
       if (!project.name || !langgraphCwd || !langgraphPort || !angularPort) {
         throw new Error(`Unable to parse e2e wiring for ${relative(repoRoot, projectJsonPath)}`);
@@ -153,16 +167,29 @@ describe('cockpit e2e wiring', () => {
         errors.push(`${wiring.project}: registry pythonDir ${capability.pythonDir} != global setup langgraphCwd ${wiring.langgraphCwd}`);
       }
 
-      const proxyPath = join(wiring.projectRoot, 'proxy.conf.json');
-      if (!existsSync(proxyPath)) {
-        errors.push(`${wiring.project}: missing proxy.conf.json`);
-      } else {
-        const proxy = JSON.parse(readFileSync(proxyPath, 'utf8')) as Record<string, { target?: string }>;
+      // Post-port-registry: proxy.conf.mjs templates the target from
+      // cockpit/ports.mjs at runtime. Drift is impossible because the
+      // value comes from the same registry the test already checks via
+      // wiring.langgraphPort. So we just assert the .mjs file exists +
+      // imports portsFor with this cap's name.
+      const proxyMjs = join(wiring.projectRoot, 'proxy.conf.mjs');
+      const proxyJson = join(wiring.projectRoot, 'proxy.conf.json');
+      if (existsSync(proxyMjs)) {
+        const text = readFileSync(proxyMjs, 'utf8');
+        if (!text.includes(`portsFor('${wiring.project}')`)) {
+          errors.push(`${wiring.project}: proxy.conf.mjs does not call portsFor('${wiring.project}')`);
+        }
+      } else if (existsSync(proxyJson)) {
+        // Legacy (allowed for ag-ui exception only); not expected for any
+        // cap reaching this code path.
+        const proxy = JSON.parse(readFileSync(proxyJson, 'utf8')) as Record<string, { target?: string }>;
         const target = proxy['/api']?.target;
         const expectedTarget = `http://localhost:${wiring.langgraphPort}`;
         if (target !== expectedTarget) {
           errors.push(`${wiring.project}: proxy target ${target} != ${expectedTarget}`);
         }
+      } else {
+        errors.push(`${wiring.project}: missing proxy.conf (no .mjs or .json)`);
       }
 
       const scriptsDir = join(wiring.projectRoot, 'e2e/scripts');

cockpit/chat/a2ui/angular/e2e/global-setup-impl.ts

@@ -1,11 +1,14 @@
 // SPDX-License-Identifier: MIT
 import { resolve } from 'node:path';
+import { portsFor } from '../../../../../cockpit/ports.mjs';
 import { createGlobalSetup } from '@threadplane-internal/e2e-harness';
 
+const ports = portsFor('cockpit-chat-a2ui-angular');
+
 export default createGlobalSetup({
   langgraphCwd: 'cockpit/chat/a2ui/python',
-  langgraphPort: 5511,
+  langgraphPort: ports.langgraph,
   angularProject: 'cockpit-chat-a2ui-angular',
-  angularPort: 4511,
+  angularPort: ports.angular,
   fixturesDir: resolve(__dirname, 'fixtures'),
 });

cockpit/chat/a2ui/angular/e2e/playwright.config.ts

@@ -1,5 +1,9 @@
 // SPDX-License-Identifier: MIT
 import { defineConfig, devices } from '@playwright/test';
+import { portsFor } from '../../../../../cockpit/ports.mjs';
+
+const { angular: angularPort } = portsFor('cockpit-chat-a2ui-angular');
+
 
 export default defineConfig({
   testDir: '.',
@@ -9,7 +13,7 @@ export default defineConfig({
   retries: process.env.CI ? 2 : 0,
   reporter: process.env.CI ? [['list'], ['html', { open: 'never' }]] : 'list',
   use: {
-    baseURL: 'http://localhost:4511',
+    baseURL: `http://localhost:${angularPort}`,
     trace: 'retain-on-failure',
   },
   projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],

cockpit/chat/a2ui/angular/e2e/tsconfig.json

@@ -18,7 +18,8 @@
       "@threadplane-internal/e2e-harness/global-teardown": [
         "libs/e2e-harness/src/global-teardown.ts"
       ]
-    }
+    },
+    "allowJs": true
   },
   "include": [
     "**/*.ts"

cockpit/chat/a2ui/angular/project.json

@@ -78,7 +78,7 @@
       },
       "defaultConfiguration": "development",
       "options": {
-        "proxyConfig": "cockpit/chat/a2ui/angular/proxy.conf.json"
+        "proxyConfig": "cockpit/chat/a2ui/angular/proxy.conf.mjs"
       }
     },
     "smoke": {

cockpit/chat/a2ui/angular/proxy.conf.json

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MIT
+import { portsFor } from '../../../../cockpit/ports.mjs';
+
+const { langgraph } = portsFor('cockpit-chat-a2ui-angular');
+
+export default {
+  "/api": {
+    target: `http://localhost:${langgraph}`,
+    secure: false,
+    changeOrigin: true,
+    pathRewrite: {"^/api":""},
+    ws: true,
+  },
+};

cockpit/chat/a2ui/angular/proxy.conf.mjs

@@ -78,7 +78,7 @@
       },
       "defaultConfiguration": "development",
       "options": {
-        "proxyConfig": "cockpit/chat/debug/angular/proxy.conf.json"
+        "proxyConfig": "cockpit/chat/debug/angular/proxy.conf.mjs"
       }
     },
     "smoke": {