@ultimat3/cli 21.0.0 → 22.1.0

package/src/cmd-deploy.ts

@@ -5,13 +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';
+import { PROD_ENV_FILE } from './templates/scaffold-container-compose';
 
 /**
  * Ordered, and the order is the design. `migrate` GATES — it runs to completion before anything
@@ -105,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.
@@ -121,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 {
@@ -171,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';
@@ -208,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 },
@@ -231,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,
@@ -246,7 +314,7 @@ export const deployCommand: CliCommand = {
               docs: ERROR_DOCS_URL,
             },
           ],
-          data: planJson,
+          data: { ...planJson, ...rollout },
         };
       }
     }
@@ -254,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

@@ -17,25 +17,18 @@ import { loadSignInPath } from './app-auth';
 import { appManifest } from './app-manifest';
 import { requireAppRoot } from './app-root';
 import { loadAppRuntime } from './app-runtime';
+import { devSpec } from './cmd-dev-spec';
 import type { CliCommand, CommandContext } from './command';
 import type { DevDashboardInput, DevStatus } from './dev-dashboard';
 import { devPanels } from './dev-dashboard';
-import { declareDevEnvironment } from './dev-environment';
-import { liveFeedLabel } from './dev-live-feed';
+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 { replicaOverrides } from './dev-replica';
-import type { RunningRoles } from './dev-roles';
-import { DEV_BINDING, DEV_ROLES, selectRoles, startRoles } from './dev-roles';
 import { devRouteTable } from './dev-route-table';
-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 { createTraceRecorder } from './dev-traces';
 import { watchTree } from './dev-watch-tree';
-import { intFlagOr, PORT_RANGE } from './flag-number';
 import { holdUntilShutdown } from './hold';
 import type { IslandBundle } from './island-bundle';
 import { buildIslands } from './island-bundle';
@@ -44,10 +37,23 @@ import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { findingFrom } from './output';
 import { flagString } from './parse';
-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';
 
-const DEFAULT_PORT = 3000;
+const _DEFAULT_PORT = 3000;
 
 export interface DevServer {
   readonly url: string;
@@ -121,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`
@@ -135,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
@@ -224,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`.
@@ -295,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> {

package/src/cmd-doctor-spec.ts

@@ -0,0 +1,21 @@
+// `x doctor`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-doctor.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+/** The port `x dev` binds by default, so the probe answers about the port the developer will use. */
+export const DEFAULT_DOCTOR_PORT = 3000;
+
+export const doctorSpec: CommandSpec = {
+  name: 'doctor',
+  summary: 'environment, versions, drift, ports, PWA prerequisites — each with a fix command',
+  usage: 'x doctor [--port 3000] [--json]',
+  flags: [
+    {
+      name: 'port',
+      type: 'string',
+      summary: 'port to test',
+      default: String(DEFAULT_DOCTOR_PORT),
+    },
+  ],
+};

package/src/cmd-doctor.ts

@@ -19,9 +19,9 @@ import {
 } from '@ultimat3/db';
 import { STORAGE_SIGNING_SECRET_KEY, usesDevStorageSecret } from '@ultimat3/storage';
 import { findAppRoot, REQUIRED_BUN, versionAtLeast } from './app-root';
+import { DEFAULT_DOCTOR_PORT, doctorSpec } from './cmd-doctor-spec';
 import type { CliCommand, CommandContext } from './command';
 import { checkMigrationSnapshots } from './db-snapshot';
-import { syncPortFor } from './dev-sync';
 import type { OfflineFallbackFact } from './doctor-offline';
 import { offlineFallbackFinding, offlineFallbackProbe } from './doctor-offline';
 import { intFlagOr, PORT_RANGE, portPairAfter } from './flag-number';
@@ -31,6 +31,7 @@ import type { CommandResult, Finding } from './output';
 import { findingFrom } from './output';
 import type { ParsedArgs } from './parse';
 import { portFree } from './port-probe';
+import { syncPortFor } from './role-sync';
 import { checkMigrationDrift } from './schema-drift';
 
 /**
@@ -129,9 +130,6 @@ export const embeddedDatabaseFinding = (fact: EmbeddedDatabase): Finding | undef
 /** The file `x doctor` reports missing, and the one the reader creates. */
 export const ENV_DEVELOPMENT = '.env.development';
 
-/** The port `x dev` binds by default, so the probe answers about the port the developer will use. */
-const DEFAULT_DOCTOR_PORT = 3000;
-
 /**
  * Both ports `x dev` binds, each labelled with the role that wants it. `x dev --port 3999` printed
  * `web listening on 3999`, then died on 4000 as `X_CLI_UNEXPECTED` with a caught `Error` rendered
@@ -144,7 +142,7 @@ const DEFAULT_DOCTOR_PORT = 3000;
  * N+1 is still not a runnable command. It did not move both until 2026-09 — the line was
  * `neighbouringPort(probe.port)`, which for the sync finding IS the port the finding is about, and
  * a docblock claiming otherwise is how it survived. `portPairAfter` is the one reader of that rule
- * and `dev-sync.ts`'s own refusal shares it.
+ * and `role-sync.ts`'s own refusal shares it.
  *
  * The sync port is `syncPortFor`, never `neighbouringPort` again: that helper answers 65534 for a
  * web port of 65535 — BELOW the web port, and a port `x dev` never binds — where the boot refuses
@@ -400,19 +398,7 @@ export function probeFor(cwd: string, bunVersion: string, port: number): DoctorP
 }
 
 export const doctorCommand: CliCommand = {
-  spec: {
-    name: 'doctor',
-    summary: 'environment, versions, drift, ports, PWA prerequisites — each with a fix command',
-    usage: 'x doctor [--port 3000] [--json]',
-    flags: [
-      {
-        name: 'port',
-        type: 'string',
-        summary: 'port to test',
-        default: String(DEFAULT_DOCTOR_PORT),
-      },
-    ],
-  },
+  spec: doctorSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const port = doctorPort(ctx.args);
     const findings = await runDoctor(probeFor(ctx.cwd, ctx.bunVersion, port));

package/src/cmd-env-spec.ts

@@ -0,0 +1,18 @@
+// `x env`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-env.ts`, which `registry.ts` imports only when the command runs.
+
+import { ENV_SCHEMA_EXPORT } from './app-env';
+import { APP_CONFIG_FILE } from './app-root';
+import type { CommandSpec } from './parse';
+
+export const envSpec: CommandSpec = {
+  name: 'env',
+  summary: `the typed environment declared by ${ENV_SCHEMA_EXPORT} in ${APP_CONFIG_FILE}`,
+  usage: 'x env [check|example] [--json]',
+  requiresApp: true,
+  subcommands: ['check', 'example'],
+  // The bare `x env` answers the question the fix line on every `X_ENV_MISSING` in this
+  // framework already tells its reader to run.
+  defaultSubcommand: 'check',
+  flags: [],
+};

package/src/cmd-env.ts

@@ -5,8 +5,9 @@
 // Bun ships no path-join primitive, and `.env.example` is written app-root-relative.
 import { join } from 'node:path';
 import { checkEnv, ENV_EXAMPLE_PATH, ERROR_DOCS_URL, maskedEnvValues } from '@ultimat3/core';
-import { ENV_SCHEMA_EXPORT, envExampleFor, loadEnvSchema } from './app-env';
-import { APP_CONFIG_FILE, requireAppRoot } from './app-root';
+import { envExampleFor, loadEnvSchema } from './app-env';
+import { requireAppRoot } from './app-root';
+import { envSpec } from './cmd-env-spec';
 import type { CliCommand, CommandContext } from './command';
 import { EnvSchemaMissingError } from './errors';
 import { msg } from './messages';
@@ -73,17 +74,7 @@ async function checkProcessEnv(ctx: CommandContext): Promise<CommandResult> {
 }
 
 export const envCommand: CliCommand = {
-  spec: {
-    name: 'env',
-    summary: `the typed environment declared by ${ENV_SCHEMA_EXPORT} in ${APP_CONFIG_FILE}`,
-    usage: 'x env [check|example] [--json]',
-    requiresApp: true,
-    subcommands: ['check', 'example'],
-    // The bare `x env` answers the question the fix line on every `X_ENV_MISSING` in this
-    // framework already tells its reader to run.
-    defaultSubcommand: 'check',
-    flags: [],
-  },
+  spec: envSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     // `subcommand`, never `positionals[0]`: the parser has already lifted a declared subcommand
     // out of the positionals, so reading the array here matches nothing and every invocation

package/src/cmd-errors-spec.ts

@@ -0,0 +1,23 @@
+// `x errors`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-errors.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const ERRORS_SUBCOMMANDS = ['explain', 'list'] as const;
+
+export const errorsSpec: CommandSpec = {
+  name: 'errors',
+  summary: 'an X_* code, explained: cause, runnable fix, docs URL',
+  usage: 'x errors [explain <CODE>|list] [--json]',
+  subcommands: ERRORS_SUBCOMMANDS,
+  // `explain`, deliberately: the bare `x errors` then answers with `MissingPositionalError`,
+  // which names `<CODE>` and hands back a real invocation. `list` would silently print 200 rows
+  // to a caller who meant to explain one — see `MissingPositionalError`'s own note.
+  defaultSubcommand: 'explain',
+  // `x errors X_PERMISSION_UNKNOWN` is the form every reader tries first — `x help` prints
+  // `errors  an X_* code, explained`, which reads as exactly that — and it answered
+  // `X_CLI_UNKNOWN_COMMAND … fix: x help`, which leads back to the line that suggested it.
+  // Safe to declare here and nowhere else so far: the only thing that is not `explain` or
+  // `list` in this slot is a code, and a near miss of either is still refused (#F16).
+  defaultSubcommandTakesPositional: true,
+};

package/src/cmd-errors.ts

@@ -5,6 +5,7 @@ import { nearestName, singleLine } from '@ultimat3/core';
 // a plausible-sounding explanation an agent would then act on.
 
 import type { ErrorExplanation } from '@ultimat3/mcp';
+import { errorsSpec } from './cmd-errors-spec';
 import type { CliCommand, CommandContext } from './command';
 import type { ErrorCatalog } from './error-catalog';
 import { loadErrorCatalog } from './error-catalog';
@@ -14,7 +15,7 @@ import { explainErrorCode, explainEveryErrorCode } from './mcp-errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
 
-export const ERRORS_SUBCOMMANDS = ['explain', 'list'] as const;
+export { ERRORS_SUBCOMMANDS } from './cmd-errors-spec';
 
 /**
  * `site` is the throw site as DATA, and it is why the `fix:` for a code whose fix is built at run
@@ -85,22 +86,7 @@ function listAll(catalog: ErrorCatalog): CommandResult {
 }
 
 export const errorsCommand: CliCommand = {
-  spec: {
-    name: 'errors',
-    summary: 'an X_* code, explained: cause, runnable fix, docs URL',
-    usage: 'x errors [explain <CODE>|list] [--json]',
-    subcommands: ERRORS_SUBCOMMANDS,
-    // `explain`, deliberately: the bare `x errors` then answers with `MissingPositionalError`,
-    // which names `<CODE>` and hands back a real invocation. `list` would silently print 200 rows
-    // to a caller who meant to explain one — see `MissingPositionalError`'s own note.
-    defaultSubcommand: 'explain',
-    // `x errors X_PERMISSION_UNKNOWN` is the form every reader tries first — `x help` prints
-    // `errors  an X_* code, explained`, which reads as exactly that — and it answered
-    // `X_CLI_UNKNOWN_COMMAND … fix: x help`, which leads back to the line that suggested it.
-    // Safe to declare here and nowhere else so far: the only thing that is not `explain` or
-    // `list` in this slot is a code, and a near miss of either is still refused (#F16).
-    defaultSubcommandTakesPositional: true,
-  },
+  spec: errorsSpec,
   // `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> {