@ultimat3/cli 20.2.1 → 22.0.0

package/src/cmd-deploy-spec.ts

@@ -0,0 +1,40 @@
+// `x deploy`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-deploy.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const deploySpec: CommandSpec = {
+  name: 'deploy',
+  summary: 'run the container deploy plan: migrate first, then the serving roles',
+  usage:
+    'x deploy --image repo/app:tag [--method compose|helm] [--release name] [--namespace ns] [--timeout 15m] [--dry-run] [--json]',
+  requiresApp: true,
+  flags: [
+    { name: 'image', type: 'string', summary: 'image reference to deploy' },
+    { name: 'method', type: 'string', summary: 'compose | helm', default: 'compose' },
+    { name: 'dry-run', type: 'boolean', summary: 'print the plan, run nothing' },
+    {
+      name: 'release',
+      type: 'string',
+      summary: 'helm release name (default: app.config.ts name)',
+    },
+    { name: 'namespace', type: 'string', summary: 'helm namespace (default: the kube context)' },
+    {
+      name: 'timeout',
+      type: 'string',
+      // No `default:` — the parser would then fill it on every compose deploy too, and the refusal
+      // of a helm-only flag there could not tell an operator's value from its own.
+      summary: 'how long helm waits for the migrate hook and the rollout (default 15m)',
+    },
+    // `--critical` was here and is gone. It parsed, it was echoed into the plan JSON as
+    // `critical: <bool>`, and no file in `packages/` read that field — so the flag changed
+    // nothing about what `x deploy` did, on either method. `flag-reads.ts`'s
+    // `X_CLI_FLAG_UNREAD` passed it, because that gate proves a flag is READ and this one was:
+    // into a field with no reader. It is not coming back: `@ultimat3/pwa`'s
+    // `updateSignal({ reason: 'security' })`, the call it was to have triggered, is **deleted**
+    // as of 9.0.0 for having had no runtime caller of its own, and nothing in the framework
+    // force-navigates a client. A deploy also has no channel to one — the plan is
+    // `docker compose up` / `helm upgrade`, and the client's build id is read by `http` (tier 2)
+    // and `sync` (tier 3), neither of which may import a tier-4 package to act on it.
+  ],
+};

package/src/cmd-deploy.ts

@@ -5,12 +5,22 @@
 import { join } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import { requireAppRoot } from './app-root';
+import {
+  type HelmTarget,
+  helmUpgradeArgs,
+  readHelmTimeout,
+  readLabel,
+  readReleaseName,
+  readRollout,
+} from './cmd-deploy-helm';
+import { deploySpec } from './cmd-deploy-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, UnknownCommandError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
 import { flagBool, flagString } from './parse';
 import { quoteArg } from './shell-quote';
+import { PROD_ENV_FILE } from './templates/scaffold-container-compose';
 
 /**
  * Ordered, and the order is the design. `migrate` GATES — it runs to completion before anything
@@ -104,8 +114,40 @@ export function helmImageOverrides(image: string): readonly string[] {
     : ['--set', `image.repository=${repository}`, '--set', `image.tag=${tag}`];
 }
 
-export function planDeploy(image: string, method: DeployMethod, root: string): DeployPlan {
+/** What was asked for: the method, and for helm the release it is aimed at. */
+export type DeployRequest =
+  | { readonly method: 'compose' }
+  | ({ readonly method: 'helm' } & HelmTarget);
+
+/**
+ * The plan for one method. A helm plan takes its target — release, namespace, timeout — because
+ * the release is read off `app.config.ts`, which only the command can import; the compose plan
+ * needs none, so its three-argument form is unchanged.
+ */
+export function planDeploy(image: string, method: 'compose', root: string): DeployPlan;
+export function planDeploy(
+  image: string,
+  method: 'helm',
+  root: string,
+  target: HelmTarget,
+): DeployPlan;
+export function planDeploy(
+  image: string,
+  method: DeployMethod,
+  root: string,
+  target?: HelmTarget,
+): DeployPlan {
   if (method === 'helm') {
+    // A caller from plain JS can still reach this without one; `app` for every app is the
+    // defect the target exists to end, so it is refused rather than defaulted back.
+    if (target === undefined) {
+      throw new BadFlagError({
+        flag: 'release',
+        command: 'deploy',
+        reason: 'a helm plan names its release, and planDeploy was called with no target',
+        fix: 'x deploy --method helm --release my-app --json',
+      });
+    }
     // `repo@sha256:…` is a reference this chart cannot express: it renders `repository:tag` and
     // has no digest branch, so passing one through would deploy `repo@sha256:…:<appVersion>` —
     // a tag no registry has. Refused here rather than by a `helm upgrade` failing halfway.
@@ -120,19 +162,7 @@ export function planDeploy(image: string, method: DeployMethod, root: string): D
     return {
       image,
       env: {},
-      steps: [
-        {
-          role: 'all',
-          command: [
-            'helm',
-            'upgrade',
-            '--install',
-            'app',
-            join(root, 'docker', 'helm'),
-            ...helmImageOverrides(image),
-          ],
-        },
-      ],
+      steps: [{ role: 'all', command: helmUpgradeArgs(root, target, helmImageOverrides(image)) }],
     };
   }
   return {
@@ -146,6 +176,12 @@ export function planDeploy(image: string, method: DeployMethod, root: string): D
       command: [
         'docker',
         'compose',
+        // Compose interpolates `${SYNC_URL:?…}` and `${POSTGRES_PASSWORD:?…}` from the shell and
+        // `--env-file` only — never from a service's `env_file:`. Without this an operator who put
+        // them in `.env.production`, the one file the compose file tells them to fill, had every
+        // step die on a parse error. Global flag, so it precedes `-f`; the shell still wins over it.
+        '--env-file',
+        join(root, PROD_ENV_FILE),
         '-f',
         join(root, 'docker', 'docker-compose.prod.yml'),
         ONE_SHOT_ROLES.includes(role) ? 'run' : 'up',
@@ -164,33 +200,50 @@ export function planDeploy(image: string, method: DeployMethod, root: string): D
  * renderers and the failure `fix:` go through here, so the plan `--json` reports, the plan the
  * terminal shows and the line the refusal hands back can never name three different deployments.
  */
+/** The flags only a helm deploy reads. Named once: the spec, the refusal and the reader agree. */
+const HELM_ONLY_FLAGS = ['release', 'namespace', 'timeout'] as const;
+
+/**
+ * The method and its target. A helm-only flag on the compose method is REFUSED, never dropped:
+ * `--namespace staging` on a compose deploy would otherwise run against the one box there is and
+ * report success, which is the silent direction every declared-and-ignored knob in this repo took.
+ */
+export async function readDeployRequest(
+  ctx: CommandContext,
+  method: DeployMethod,
+  root: string,
+): Promise<DeployRequest> {
+  if (method === 'compose') {
+    const stray = HELM_ONLY_FLAGS.find((flag) => flagString(ctx.args, flag) !== undefined);
+    if (stray !== undefined) {
+      throw new BadFlagError({
+        flag: stray,
+        command: 'deploy',
+        reason: 'it applies to --method helm only; a compose deploy has one box and no release',
+        fix: 'x deploy --method helm --release my-app --namespace my-namespace --json',
+      });
+    }
+    return { method };
+  }
+  const namespace = flagString(ctx.args, 'namespace');
+  return {
+    method,
+    release: await readReleaseName(root, flagString(ctx.args, 'release')),
+    namespace: namespace === undefined ? undefined : readLabel('namespace', namespace),
+    timeout: readHelmTimeout(flagString(ctx.args, 'timeout')),
+  };
+}
+
 const stepLine = (env: Readonly<Record<string, string>>, command: readonly string[]): string =>
-  [...Object.entries(env).map(([name, value]) => `${name}=${quoteArg(value)}`), ...command].join(
-    ' ',
-  );
+  [
+    ...Object.entries(env).map(([name, value]) => `${name}=${quoteArg(value)}`),
+    // Every word quoted where it must be: the chart and compose paths are joined from the app
+    // root, and a root holding a space or a `$(` pasted back as two words, or as a second command.
+    ...command.map(quoteArg),
+  ].join(' ');
 
 export const deployCommand: CliCommand = {
-  spec: {
-    name: 'deploy',
-    summary: 'run the container deploy plan: migrate first, then the serving roles',
-    usage: 'x deploy --image repo/app:tag [--method compose|helm] [--dry-run] [--json]',
-    requiresApp: true,
-    flags: [
-      { name: 'image', type: 'string', summary: 'image reference to deploy' },
-      { name: 'method', type: 'string', summary: 'compose | helm', default: 'compose' },
-      { name: 'dry-run', type: 'boolean', summary: 'print the plan, run nothing' },
-      // `--critical` was here and is gone. It parsed, it was echoed into the plan JSON as
-      // `critical: <bool>`, and no file in `packages/` read that field — so the flag changed
-      // nothing about what `x deploy` did, on either method. `flag-reads.ts`'s
-      // `X_CLI_FLAG_UNREAD` passed it, because that gate proves a flag is READ and this one was:
-      // into a field with no reader. It is not coming back: `@ultimat3/pwa`'s
-      // `updateSignal({ reason: 'security' })`, the call it was to have triggered, is **deleted**
-      // as of 9.0.0 for having had no runtime caller of its own, and nothing in the framework
-      // force-navigates a client. A deploy also has no channel to one — the plan is
-      // `docker compose up` / `helm upgrade`, and the client's build id is read by `http` (tier 2)
-      // and `sync` (tier 3), neither of which may import a tier-4 package to act on it.
-    ],
-  },
+  spec: deploySpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('deploy', ctx.cwd).dir;
     const image = flagString(ctx.args, 'image') ?? 'ultimate-app:dev';
@@ -201,10 +254,27 @@ export const deployCommand: CliCommand = {
     // `docker/docker-compose.prod.yml`. An app that deleted the chart gets helm's own error through
     // X_DEPLOY_FAILED, whose fix is the exact command to rerun.
     const method = readMethod(flagString(ctx.args, 'method'));
-    const plan = planDeploy(image, method, root);
-    const planJson: JsonValue = {
+    const request = await readDeployRequest(ctx, method, root);
+    const plan =
+      request.method === 'helm'
+        ? planDeploy(image, 'helm', root, request)
+        : planDeploy(image, 'compose', root);
+    // What the helm flags resolved to — the release above all, which is read off `app.config.ts`
+    // and so is not something the operator typed. Absent on compose, which has no release.
+    const target: { readonly [key: string]: JsonValue } =
+      request.method === 'helm'
+        ? {
+            helm: {
+              release: request.release,
+              namespace: request.namespace ?? null,
+              timeout: request.timeout,
+            },
+          }
+        : {};
+    const planJson: { readonly [key: string]: JsonValue } = {
       image: plan.image,
       method,
+      ...target,
       // Reported, because it is what makes `image` above true on the compose method — a dry run
       // that names an image the steps do not carry is the defect this field closed.
       env: { ...plan.env },
@@ -224,8 +294,13 @@ export const deployCommand: CliCommand = {
         ),
       };
     }
+    // helm prints its release record (`--output json`), so the report carries helm's own verdict
+    // and revision rather than an exit code standing in for one. Compose has no such record.
+    let rollout: { readonly [key: string]: JsonValue } = {};
     for (const step of plan.steps) {
       const result = await ctx.runner(step.command, { cwd: root, env: plan.env });
+      if (request.method === 'helm')
+        rollout = { rollout: { ...readRollout(request, result.stdout) } };
       if (!result.ok) {
         return {
           ok: false,
@@ -239,7 +314,7 @@ export const deployCommand: CliCommand = {
               docs: ERROR_DOCS_URL,
             },
           ],
-          data: planJson,
+          data: { ...planJson, ...rollout },
         };
       }
     }
@@ -247,7 +322,7 @@ export const deployCommand: CliCommand = {
       ok: true,
       command: 'deploy',
       summary: msg('cli.deploy.plan', { images: 1, roles }),
-      data: planJson,
+      data: { ...planJson, ...rollout },
     };
   },
 };

package/src/cmd-dev-spec.ts

@@ -0,0 +1,25 @@
+// `x dev`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-dev.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+import { DEV_ROLES } from './role-start-types';
+
+export const devSpec: CommandSpec = {
+  name: 'dev',
+  summary: 'all roles in one process: embedded services, sub-second reload, /_x mounted',
+  usage: 'x dev [--port 3000] [--role web,worker] [--once] [--json]',
+  requiresApp: true,
+  flags: [
+    // No `default`: a default reads exactly like a value the caller typed, and it outranked
+    // `PORT` from the app's `.env.development` — `devPortFor` supplies the 3000 last.
+    { name: 'port', type: 'string', summary: 'HTTP port (default: PORT, else 3000)' },
+    {
+      name: 'role',
+      type: 'string',
+      // `replicator` is named because it is selectable and NOT default — it takes a replication
+      // slot on a shared database, which is not something every `x dev` should do by starting.
+      summary: `roles to run (default: all of ${DEV_ROLES.join(',')}; replicator is opt-in)`,
+    },
+    { name: 'once', type: 'boolean', summary: 'boot, report, exit — for smoke tests and CI' },
+  ],
+};

package/src/cmd-dev.ts

@@ -9,66 +9,60 @@ import { devShellStyle } from '@ultimat3/admin/dev';
 import type { Role } from '@ultimat3/core';
 import { configureTelemetry, METRICS_PATH, noopExporter } from '@ultimat3/core';
 import { setStatementObserver } from '@ultimat3/db';
-import type { OverlayNotice, RequestContext, Route } from '@ultimat3/http';
+import type { OverlayNotice, RequestContext } from '@ultimat3/http';
 import { asCtx } from '@ultimat3/http';
 import type { Manifest } from '@ultimat3/manifest';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
-import { describeRoutes } from '@ultimat3/render';
-import { apiRoutes } from './api-routes';
 import { loadSignInPath } from './app-auth';
 import { appManifest } from './app-manifest';
-import { mountAppMcp } from './app-mcp';
 import { requireAppRoot } from './app-root';
 import { loadAppRuntime } from './app-runtime';
+import { devSpec } from './cmd-dev-spec';
 import type { CliCommand, CommandContext } from './command';
-import { assetRoutes } from './dev-assets';
 import type { DevDashboardInput, DevStatus } from './dev-dashboard';
-import { devDashboardRoutes, devPanels } from './dev-dashboard';
-import { declareDevEnvironment } from './dev-environment';
-import { liveFeedLabel } from './dev-live-feed';
+import { devPanels } from './dev-dashboard';
+import { declareDevEnvironment, needsDevEnvironmentDeclaration } from './dev-environment';
 import { clearLock, preflight, writeLock } from './dev-lock';
 import { createStatementLedger } from './dev-n-plus-one';
+import { devPortFor } from './dev-port';
 import { coalesceReloads } from './dev-reload';
-import { appRoutes } from './dev-render';
-import { replicaOverrides } from './dev-replica';
-import type { RunningRoles } from './dev-roles';
-import { DEV_BINDING, DEV_ROLES, selectRoles, startRoles } from './dev-roles';
-import type { RunningServices } from './dev-runtime';
-import { cdnLabel, describeCdn, describeMail, mailLabel, startServices } from './dev-runtime';
-import type { DevServices } from './dev-services';
-import { describeServices, reportedUrls, resolveServices } from './dev-services';
-import { storageRoutes } from './dev-storage';
+import { devRouteTable } from './dev-route-table';
 import { createTraceRecorder } from './dev-traces';
 import { watchTree } from './dev-watch-tree';
-import { errorPageStyleSources } from './error-page-csp';
-import { intFlagOr, PORT_RANGE } from './flag-number';
 import { holdUntilShutdown } from './hold';
 import type { IslandBundle } from './island-bundle';
 import { buildIslands } from './island-bundle';
 import { FRAME_STYLE } from './island-harness';
-import { islandHarnessRoutes } from './island-harness-route';
-import { islandRoutes } from './island-routes';
-import { loadIslandStates } from './island-states-load';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { findingFrom } from './output';
 import { flagString } from './parse';
-import { loadPwaArtifacts } from './pwa-artifacts';
-import { metricsPortFor } from './serve';
+import type { RunningRoles } from './role-start';
+import { DEV_BINDING, DEV_ROLES, selectRoles, startRoles } from './role-start';
+import type { DevServices } from './runtime-bindings';
+import {
+  describeServices,
+  reportedUrls,
+  resolveServices,
+  withRealtimeEvents,
+} from './runtime-bindings';
+import { liveFeedLabel } from './runtime-live-feed';
+import { replicaOverrides } from './runtime-replica';
+import type { RunningServices } from './runtime-services';
+import { cdnLabel, describeCdn, describeMail, mailLabel, startServices } from './runtime-services';
+import { metricsPortFor, releaseBoot } from './serve';
 import { loopFacts, loopFinding, loopNotice } from './statement-loop';
-import { styleBundle } from './style-bundle';
-import { styleRoutes } from './style-routes';
-import { serviceWorkerArtifacts } from './sw-artifacts';
-import { serviceWorkerRoutes } from './sw-routes';
-import { loadThemeMode, themeBoot } from './theme-boot';
 
-const DEFAULT_PORT = 3000;
+const _DEFAULT_PORT = 3000;
 
 export interface DevServer {
   readonly url: string;
   readonly services: DevServices;
   readonly roles: readonly Role[];
-  /** The manifest as it stands now — a reload that registers a new route moves it. */
+  /**
+   * `BUILD_ID` when stamped — the id every response carries. Otherwise the manifest as it stands
+   * now, so a reload that registers a new route moves it.
+   */
   readonly buildId: string;
   /**
    * Modules that would not import, primitives that would not register, reloads that would not
@@ -133,13 +127,41 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
   // EVERY boot: a scratch server (`x shot`, `ui.shot`) boots here too, and without this a
   // fail-closed dev actor installs nothing — the picture is of a 401. Idempotent.
   declareDevEnvironment(options.env);
-  const services = resolveServices(options.root, options.env);
-  const runtime: RunningServices = await startServices(services, options.env);
+  // The declaration lands on `process.env`; the env this boot passes on must carry it too, or every
+  // service resolved from `options.env` still reads no `ULTIMATE_ENV`.
+  const env = needsDevEnvironmentDeclaration(options.env)
+    ? { ...options.env, ULTIMATE_ENV: 'development' }
+    : options.env;
+  const resolved = resolveServices(options.root, env);
+  const runtime: RunningServices = await startServices(resolved, env);
+  // The events binding the boot line reports is the bus the runtime chose, read off it.
+  const services = withRealtimeEvents(resolved, env, runtime.realtime);
+  // `serve.ts`'s `releaseBoot` shape: everything acquired from here on is released, newest first,
+  // if the boot throws — a failed `x dev` left PGlite holding `.x/pgdata` for the retry to meet.
+  const acquired: (() => void | Promise<void>)[] = [() => runtime.stop()];
+  try {
+    return await bootDev(options, services, runtime, acquired);
+  } catch (error) {
+    await releaseBoot(acquired);
+    throw error;
+  }
+}
+
+async function bootDev(
+  options: StartDevOptions,
+  services: ReturnType<typeof resolveServices>,
+  runtime: RunningServices,
+  acquired: (() => void | Promise<void>)[],
+): Promise<DevServer> {
   // Installed before the app loads, so a span opened during registration is already recorded.
   // Tracing is always on in the framework and free until an exporter is configured; `x dev` is
   // what configures one, which is the whole reason `/_x/timeline` has anything to draw.
   const traces = createTraceRecorder();
   configureTelemetry({ exporter: traces.exporter });
+  acquired.push(() => {
+    configureTelemetry({ exporter: noopExporter });
+    traces.reset();
+  });
   // Installed at the same moment and for the same reason: an observer is the single switch that
   // turns statement instrumentation on at all (`@ultimat3/db`'s `observe.ts`), so the timeline's
   // SQL rows and the repeat counts arrive together rather than through two toggles. `serve.ts`
@@ -147,6 +169,10 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
   // uninstalled, and nothing more (axiom 6).
   const statements = createStatementLedger();
   setStatementObserver(statements.observer);
+  acquired.push(() => {
+    setStatementObserver(undefined);
+    statements.reset();
+  });
   // ONE load at boot, the same call the rebuild below makes: the manifest and the findings are
   // two projections of one scan. Until 2026-09-07 this was `loadApp` for the findings and then
   // `appManifest` — which loads again — for the manifest, so a save landing between the two put
@@ -164,7 +190,12 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
   // boot on purpose: the header is handed to the HTTP config and the render modes once, and a
   // reload cannot re-pin it — `state.manifest.buildId` is what `/_x` and `--json` report, so a
   // divergence between the two is visible rather than silent, and a restart closes it.
-  const buildId = state.manifest.buildId;
+  // `BUILD_ID` wins when set — `serve.ts`'s rule, so an e2e `deploy.newBuild()` can restart `x dev`
+  // as a new build with the same sources.
+  // Stamped, it is ALSO what `server.buildId` answers below: the process serves no other build.
+  const rawStamp = options.env['BUILD_ID'];
+  const stamped = rawStamp !== undefined && rawStamp !== '' ? rawStamp : undefined;
+  const buildId = stamped ?? state.manifest.buildId;
 
   let server: DevServer;
   // Read at request time, never captured at boot: `/_x/services` must report the reload counter
@@ -185,70 +216,14 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
   };
   const panels = devPanels(dashboard).map((panel) => panel.key);
 
-  // Resolved once, before the first route: the manifest's bytes and the three head elements that
-  // name it. `undefined` for an app that is not installable, and then nothing is mounted and no
-  // document changes — the 0kb baseline is not spent on a `<link>` to a file that does not exist.
-  const pwa = await loadPwaArtifacts(options.root);
-  const theme = themeBoot(await loadThemeMode(options.root));
-  const errorStyles = await errorPageStyleSources(options.root);
-  // Built once at boot, from this process's own route table and island bundle. `x dev` rebuilds
-  // islands on the watcher tick and the worker is NOT rebuilt with them, deliberately: a service
-  // worker that changes under a page it already controls is the update path, and re-emitting one
-  // per keystroke would exercise it on every save.
-  const serviceWorker =
-    pwa === undefined
-      ? undefined
-      : serviceWorkerArtifacts({
-          pwa,
-          buildId,
-          routes: describeRoutes(),
-          islands: state.islands,
-          styles: styleBundle(),
-        });
-
-  // The app's own MCP endpoint, discovered from `apps/<app>/mcp.ts` and mounted through the SAME
-  // call `runRole` makes — `POST /mcp` answered 404 in every process the framework booted until
-  // one of them asked. Warned once here when `expose` is true and nothing can be mounted.
-  const mcpMount = await mountAppMcp(options.root);
-  const routes: readonly Route[] = [
-    ...devDashboardRoutes(dashboard),
-    // The same API table the container serves: a read that answers here and 404s in production
-    // is exactly the drift one composition exists to prevent.
-    ...apiRoutes(),
-    ...mcpMount.routes,
-    // The image pipeline's only HTTP surface: the icons the web manifest declares, and the
-    // variants every `srcset` promises. Mounted before the app's own routes so a page route can
-    // never shadow `/icons` or `/media`.
-    ...assetRoutes({
-      root: options.root,
-      storage: runtime.storage,
-      ...(pwa === undefined ? {} : { pwa }),
-    }),
-    ...storageRoutes({ storage: runtime.storage }),
-    // The chunks the documents below name. Mounted before the app's routes for the reason
-    // `/icons` and `/media` are: a page route must not be able to shadow an asset URL.
-    ...islandRoutes(() => state.islands),
-    // And the stylesheet every one of those documents links. Read through the getter for the
-    // reason the islands are: a rebuilt island registers CSS, which mints a new URL, and a table
-    // captured at boot would answer 404 for the href the document now carries.
-    ...styleRoutes(() => styleBundle()),
-    // `x shot --island`'s harness, in the `/_x` dev namespace so no app route can shadow it. It
-    // lives here rather than in a second server because everything it needs is in THIS process:
-    // the built chunks, the app's stylesheet registry, and the one embedded Postgres a checkout
-    // may have. The states are read per REQUEST — an author editing a state and re-running the
-    // command must not need a restart to see it.
-    ...islandHarnessRoutes({
-      islands: () => state.islands,
-      states: () => loadIslandStates(options.root),
-    }),
-    ...(serviceWorker === undefined ? [] : serviceWorkerRoutes(serviceWorker)),
-    ...appRoutes({
-      buildId,
-      resolveIsland: (file) => state.islands.resolverFor(file),
-      themeHead: theme.head,
-      ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
-    }),
-  ];
+  const { routes, theme, errorStyles, mcpPath } = await devRouteTable({
+    root: options.root,
+    env: options.env,
+    buildId,
+    storage: runtime.storage,
+    dashboard,
+    islands: () => state.islands,
+  });
 
   // The app's `apps/<app>/runtime.ts`, composed exactly as `runRole` composes a caller's
   // `runtime`: the replica scope in front, the app's own middleware behind it. Before this the
@@ -287,6 +262,7 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     // standby — so this key does not exist on a homework app's boot at all.
     ...(replicaOverride === undefined ? {} : { overrides: replicaOverride }),
   });
+  acquired.push(() => running.stop());
 
   // One rebuild at a time, and the last save wins: a tick arriving mid-build coalesces into ONE
   // trailing rebuild instead of racing the one in flight for `state.manifest` and `state.islands`.
@@ -320,9 +296,9 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     url: running.url ?? `http://localhost:${options.port}`,
     services,
     roles: running.roles,
-    mcp: mcpMount.path,
+    mcp: mcpPath,
     get buildId(): string {
-      return state.manifest.buildId;
+      return stamped ?? state.manifest.buildId;
     },
     // A getter, not a snapshot: `/_x` and `--json` must show the reload that just failed and the
     // loop the last request tripped, not the findings as they were when the route table was built.
@@ -358,32 +334,12 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
 }
 
 export const devCommand: CliCommand = {
-  spec: {
-    name: 'dev',
-    summary: 'all roles in one process: embedded services, sub-second reload, /_x mounted',
-    usage: 'x dev [--port 3000] [--role web,worker] [--once] [--json]',
-    requiresApp: true,
-    flags: [
-      { name: 'port', type: 'string', summary: 'HTTP port', default: String(DEFAULT_PORT) },
-      {
-        name: 'role',
-        type: 'string',
-        // `replicator` is named because it is selectable and NOT default — it takes a replication
-        // slot on a shared database, which is not something every `x dev` should do by starting.
-        summary: `roles to run (default: all of ${DEV_ROLES.join(',')}; replicator is opt-in)`,
-      },
-      { name: 'once', type: 'boolean', summary: 'boot, report, exit — for smoke tests and CI' },
-    ],
-  },
+  spec: devSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('dev', ctx.cwd).dir;
     // Validated, not `parseInt`'d: `x dev --port abc` handed `NaN` to `Bun.serve`, which binds an
     // arbitrary port — a dev server reachable at an address nothing printed.
-    const port = intFlagOr(
-      ctx.args,
-      { name: 'port', command: 'dev', ...PORT_RANGE, example: `x dev --port ${DEFAULT_PORT}` },
-      DEFAULT_PORT,
-    );
+    const port = devPortFor(ctx.args, ctx.env);
     const roles = selectRoles(flagString(ctx.args, 'role'));
     // BEFORE anything boots. Both failures this catches were reachable and both reported the wrong
     // thing: a taken port surfaced as X_CLI_UNEXPECTED wrapping "Is port 3000 in use?" with a `fix:`

package/src/cmd-docs-spec.ts

@@ -0,0 +1,16 @@
+// `x docs`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-docs.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+/** Matches printed by default. Enough to choose between, few enough to read all of. */
+export const DEFAULT_LIMIT = 5;
+
+export const docsSpec: CommandSpec = {
+  name: 'docs',
+  summary: 'the framework docs, answered offline from the installed packages',
+  usage: 'x docs "<question|topic|symbol>" [--limit <n>] [--json]',
+  flags: [
+    { name: 'limit', type: 'string', summary: `matches to return (default: ${DEFAULT_LIMIT})` },
+  ],
+};

package/src/cmd-docs.ts

@@ -7,6 +7,7 @@
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { DocEntry, DocHit } from '@ultimat3/manifest';
 import { nearestTopics, scanInstalledDocs, searchDocs } from '@ultimat3/manifest';
+import { DEFAULT_LIMIT, docsSpec } from './cmd-docs-spec';
 import type { CliCommand, CommandContext } from './command';
 import { MissingPositionalError } from './errors';
 import { frameworkScopeDir } from './framework-scope';
@@ -15,9 +16,6 @@ import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 import { flagString } from './parse';
 
-/** Matches printed by default. Enough to choose between, few enough to read all of. */
-const DEFAULT_LIMIT = 5;
-
 /** An install where the CLI cannot see its own dependency is broken, not merely undocumented. */
 const unresolvedFinding = (): Finding => ({
   code: 'X_CLI_UNEXPECTED',
@@ -115,14 +113,7 @@ function missResult(query: string, entries: readonly DocEntry[]): CommandResult
 }
 
 export const docsCommand: CliCommand = {
-  spec: {
-    name: 'docs',
-    summary: 'the framework docs, answered offline from the installed packages',
-    usage: 'x docs "<question|topic|symbol>" [--limit <n>] [--json]',
-    flags: [
-      { name: 'limit', type: 'string', summary: `matches to return (default: ${DEFAULT_LIMIT})` },
-    ],
-  },
+  spec: docsSpec,
   // `async` is load-bearing: a synchronous throw would escape every caller that awaits the
   // promise this signature promises, including the dispatcher's own error path.
   async run(ctx: CommandContext): Promise<CommandResult> {