@ultimat3/cli 20.2.1 → 22.0.0

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> {

package/src/cmd-fix-spec.ts

@@ -0,0 +1,18 @@
+// `x fix`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-fix.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const FIX_SUBCOMMANDS = ['boundary'] as const;
+
+export const fixSpec: CommandSpec = {
+  name: 'fix',
+  // Says "plan" in the one line `x help` prints. The name is kept — five packages' `fix:` lines
+  // cite `x fix boundary <file>` and renaming a shipped command breaks every one of them — so
+  // the honest move is to stop the summary from promising a repair the command never performs.
+  summary: 'plan the minimal cut for an import that crossed a surface boundary (never rewrites)',
+  usage: 'x fix boundary <file> [--json]',
+  requiresApp: true,
+  subcommands: FIX_SUBCOMMANDS,
+  defaultSubcommand: 'boundary',
+};

package/src/cmd-fix.ts

@@ -8,16 +8,17 @@ import { appImportGraph, readAppSources } from './app-boundaries';
 import { requireAppRoot } from './app-root';
 import type { BoundaryCut } from './boundary-cuts';
 import { planBoundaryCuts } from './boundary-cuts';
+import { fixSpec } from './cmd-fix-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, FixTargetUnknownError, MissingPositionalError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 
+export { FIX_SUBCOMMANDS } from './cmd-fix-spec';
+
 export type { BoundaryCut };
 export { planBoundaryCuts };
 
-export const FIX_SUBCOMMANDS = ['boundary'] as const;
-
 /**
  * Accept either an app-root-relative path or a suffix that matches exactly one scanned file —
  * an agent copying the path out of a `fix:` line has the short form
@@ -88,17 +89,7 @@ const editCount = (cuts: readonly BoundaryCut[]): number =>
   new Set(cuts.map((cut) => JSON.stringify([cut.edge.from, cut.edge.to]))).size;
 
 export const fixCommand: CliCommand = {
-  spec: {
-    name: 'fix',
-    // Says "plan" in the one line `x help` prints. The name is kept — five packages' `fix:` lines
-    // cite `x fix boundary <file>` and renaming a shipped command breaks every one of them — so
-    // the honest move is to stop the summary from promising a repair the command never performs.
-    summary: 'plan the minimal cut for an import that crossed a surface boundary (never rewrites)',
-    usage: 'x fix boundary <file> [--json]',
-    requiresApp: true,
-    subcommands: FIX_SUBCOMMANDS,
-    defaultSubcommand: 'boundary',
-  },
+  spec: fixSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('fix', ctx.cwd).dir;
     // Refused before the scan, never defaulted to `''`: an empty string reached `resolveTarget` as

package/src/cmd-generate-spec.ts

@@ -0,0 +1,31 @@
+// `x generate`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-generate.ts`, which `registry.ts` imports only when the command runs.
+
+import { GENERATORS } from './generate-kinds';
+import type { CommandSpec } from './parse';
+
+export const generateSpec: CommandSpec = {
+  name: 'g',
+  aliases: ['generate'],
+  summary: 'scaffold a primitive with its passing test',
+  // Projected from `GENERATORS`, never restated: the literal that used to live here had already
+  // drifted — it omitted `backfill` — and a usage line that can disagree with the list it
+  // describes is exactly the second source of truth axiom 2 forbids.
+  usage: `x g ${GENERATORS.join('|')} <name> [--feature f]`,
+  // Declared from the SAME constant `readKind` validates against: without it `fix-command.ts`
+  // has no set to judge the word after `x g`, and two shipped `@ultimat3/admin` fix lines said
+  // `x g migration` — a generator that has never existed — straight through the `errors` gate.
+  positionalChoices: GENERATORS,
+  requiresApp: true,
+  flags: [
+    { name: 'feature', type: 'string', summary: 'feature slice to write into' },
+    { name: 'surface', type: 'string', summary: 'site | app', default: 'app' },
+    { name: 'live', type: 'boolean', summary: 'subscribable query' },
+    { name: 'admin', type: 'boolean', summary: 'resource: also emit the admin override' },
+    { name: 'locales', type: 'string', summary: 'comma-separated locales, default en' },
+    { name: 'at', type: 'string', summary: 'island, admin:page: directory to write into' },
+    { name: 'permission', type: 'string', summary: 'admin:page: the permission it needs' },
+    { name: 'force', type: 'boolean', summary: 'overwrite existing files' },
+    { name: 'dry-run', type: 'boolean', summary: 'print the file list, write nothing' },
+  ],
+};

package/src/cmd-generate.ts

@@ -4,19 +4,27 @@
 
 import { existsSync } from 'node:fs';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
-import { appManifest, writeAppManifest } from './app-manifest';
+import { registerGeneratedPrimitives } from './api-registration';
+import { writeAppArtifacts } from './app-artifacts';
+import { appManifest } from './app-manifest';
 import { requireAppRoot } from './app-root';
+import { generateSpec } from './cmd-generate-spec';
 import type { CliCommand, CommandContext } from './command';
+import { invocationOf } from './command';
+import { assertFeatureExists } from './generate-feature';
 import { generate, sliceDir } from './generate-files';
+import { grantGeneratedPermissions } from './generate-grants';
 import type { Generator } from './generate-kinds';
-import { GENERATORS, readKind, readName, readPermission, readSurface } from './generate-kinds';
+import { readFeature, readKind, readName, readPermission, readSurface } from './generate-kinds';
 import { containedPath, writeFiles } from './generate-write';
 import { resolveCatalogModule } from './i18n-audit';
 import { syncI18nIndex } from './i18n-index';
+import { reproducedFlags } from './invocation-flags';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { flagBool, flagList, flagString } from './parse';
-import { resolveLocales } from './templates';
+import { quoteArg } from './shell-quote';
+import { kebab, resolveLocales } from './templates';
 
 // One import path for the generator, unchanged by the split: `index.ts`, `x new` and the scaffold
 // fixture reach the kinds, the pure file list and the writer through this module, and a second path
@@ -29,36 +37,12 @@ export type { WriteReport } from './generate-write';
 export { dedupe, writeFiles } from './generate-write';
 
 export const generateCommand: CliCommand = {
-  spec: {
-    name: 'g',
-    aliases: ['generate'],
-    summary: 'scaffold a primitive with its passing test',
-    // Projected from `GENERATORS`, never restated: the literal that used to live here had already
-    // drifted — it omitted `backfill` — and a usage line that can disagree with the list it
-    // describes is exactly the second source of truth axiom 2 forbids.
-    usage: `x g ${GENERATORS.join('|')} <name> [--feature f]`,
-    // Declared from the SAME constant `readKind` validates against: without it `fix-command.ts`
-    // has no set to judge the word after `x g`, and two shipped `@ultimat3/admin` fix lines said
-    // `x g migration` — a generator that has never existed — straight through the `errors` gate.
-    positionalChoices: GENERATORS,
-    requiresApp: true,
-    flags: [
-      { name: 'feature', type: 'string', summary: 'feature slice to write into' },
-      { name: 'surface', type: 'string', summary: 'site | app', default: 'app' },
-      { name: 'live', type: 'boolean', summary: 'subscribable query' },
-      { name: 'admin', type: 'boolean', summary: 'resource: also emit the admin override' },
-      { name: 'locales', type: 'string', summary: 'comma-separated locales, default en' },
-      { name: 'at', type: 'string', summary: 'island, admin:page: directory to write into' },
-      { name: 'permission', type: 'string', summary: 'admin:page: the permission it needs' },
-      { name: 'force', type: 'boolean', summary: 'overwrite existing files' },
-      { name: 'dry-run', type: 'boolean', summary: 'print the file list, write nothing' },
-    ],
-  },
+  spec: generateSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('g', ctx.cwd).dir;
     const kind = readKind(ctx.args.positionals[0]);
     const name = readName(ctx.args.positionals[1], kind);
-    const featureFlag = flagString(ctx.args, 'feature');
+    const featureFlag = readFeature(flagString(ctx.args, 'feature'), kind);
     // Both flags are resolved before a single file is planned: a bad surface or a locale that is
     // really a path fails here, with nothing written and nothing to undo.
     const surface = readSurface(flagString(ctx.args, 'surface'), kind, name);
@@ -72,7 +56,9 @@ export const generateCommand: CliCommand = {
     // imports `useT()` from is a fact about THIS app, and `generate` is a pure function.
     const catalogModule = await resolveCatalogModule(root);
     // Read for the same reason: which errors the slice declares is written on THIS app's disk.
-    const slice = sliceDir(surface, featureFlag ?? name);
+    const slice = sliceDir(surface, kebab(featureFlag ?? name));
+    // A named slice that is not there is refused, never invented (X_FEATURE_UNKNOWN).
+    assertFeatureExists(root, kind, featureFlag, slice);
     const sliceErrors = await readSliceErrors(root, kind, slice);
     // Same reason again: whether `job`/`task` may assume the tenant-scoped shape is a fact about
     // THIS feature's own `entity.ts`/`repo.ts`, not a default the template gets to assume.
@@ -102,16 +88,27 @@ export const generateCommand: CliCommand = {
         lines: files.map((file) => msg('cli.file.added', { path: file.path })),
       };
     }
-    const report = await writeFiles(
-      root,
-      files,
-      flagBool(ctx.args, 'force'),
-      `x g ${kind} ${name}`,
-    );
+    // The caller's own invocation, EVERY flag it set included: without `--feature` the fix wrote
+    // a second slice beside the one that conflicted.
+    const invocation = [
+      invocationOf(ctx, 'g'),
+      kind,
+      quoteArg(name),
+      ...reproducedFlags(generateCommand.spec, ctx.args),
+    ].join(' ');
+    const report = await writeFiles(root, files, flagBool(ctx.args, 'force'), invocation);
+    // The two edits a generated primitive needs outside its own slice, performed rather than left
+    // as findings: a declared permission granted to a role, and a job listed in `defineApi`.
+    // Before the manifest load below, so the projection sees both.
+    const edited = [
+      ...(await grantGeneratedPermissions(root, report.written)),
+      ...(await registerGeneratedPrimitives(root, report.written)),
+    ];
     // A locale's catalog existing on disk and the app being able to select it are two different
     // facts — see `syncI18nIndex`. Runs before the manifest load below so a route or resource
     // this same invocation just wrote never gets projected against a stale catalog registration.
-    if (report.written.length > 0) await syncI18nIndex(root);
+    const indexSync =
+      report.written.length > 0 ? await syncI18nIndex(root) : { registered: true, findings: [] };
     // Facts, not prose: every `x g` run leaves the route/action/entity/job/policy table current,
     // the same guarantee `x manifest` makes on its own — an agent reading it after `x g` never
     // sees a resource that exists on disk but not in the manifest.
@@ -124,18 +121,23 @@ export const generateCommand: CliCommand = {
     // partial load would replace the compatibility contract with a subset of the app. The scaffold
     // stays on disk — only the projection is withheld, and the load failures travel as findings.
     const loadFailures: Finding[] = [];
+    // `openapi.json` rides with it (`writeAppArtifacts`): refreshing one contract and not the other
+    // made this command's own output fail the `contract-diff` step.
+    const artifacts: string[] = [];
     if (report.written.length > 0 && existsSync(containedPath(root, MANIFEST_FILENAME))) {
       const { manifest, findings } = await appManifest(root);
       if (findings.length === 0) {
-        await writeAppManifest(root, manifest);
+        artifacts.push(
+          ...(await writeAppArtifacts(root, manifest, { openapi: true, onlyExisting: true })),
+        );
         buildId = manifest.buildId;
       } else loadFailures.push(...findings);
     }
-    const findings = [...report.conflicts, ...loadFailures];
+    const findings = [...report.conflicts, ...indexSync.findings, ...loadFailures];
     // One list behind all three renderings. The manifest was printed as a `+` line while the count
     // beside it came from `report.written` alone, so `x g island` said "wrote 2 file(s)" over three
     // lines — and `--json` carried the shorter list, which is the drift `--json` exists to prevent.
-    const written = [...report.written, ...(buildId === undefined ? [] : [MANIFEST_FILENAME])];
+    const written = [...report.written, ...edited, ...artifacts];
     return {
       ok: findings.length === 0,
       command: 'g',
@@ -166,7 +168,7 @@ async function readSliceErrors(
 }
 
 /**
- * `job` and `task` only: the slice's `entity.ts`/`repo.ts` as they stand on disk, absent when the
+ * `job`, `task`, `action` and `mutator`: the slice's `entity.ts`/`repo.ts` as they stand on disk, absent when the
  * generator's kind is neither or the file does not exist yet. `readSliceErrors`'s reason —
  * whichever generator reads it decides on THIS app's disk, not on a default the template assumes.
  */
@@ -176,7 +178,9 @@ async function readSliceFile(
   slice: string,
   name: 'entity.ts' | 'repo.ts',
 ): Promise<string | undefined> {
-  if (kind !== 'job' && kind !== 'task') return undefined;
+  if (kind !== 'job' && kind !== 'task' && kind !== 'action' && kind !== 'mutator') {
+    return undefined;
+  }
   const file = containedPath(root, `${slice}/${name}`);
   return existsSync(file) ? await Bun.file(file).text() : undefined;
 }

package/src/cmd-i18n-spec.ts

@@ -0,0 +1,16 @@
+// `x i18n`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-i18n.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const I18N_SUBCOMMANDS = ['check', 'add', 'sync'] as const;
+
+export const i18nSpec: CommandSpec = {
+  name: 'i18n',
+  summary: 'catalogs: add a locale, sync keys, check for gaps',
+  usage: 'x i18n [check|add <locale>|sync <locale>] [--json]',
+  requiresApp: true,
+  subcommands: I18N_SUBCOMMANDS,
+  // The bare `x i18n` audits; `add` and `sync` write catalogs and must be asked for.
+  defaultSubcommand: 'check',
+};

package/src/cmd-i18n.ts

@@ -13,6 +13,7 @@ import type { Catalog } from '@ultimat3/i18n';
 import { auditCatalogs, catalogKeys } from '@ultimat3/i18n';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
+import { i18nSpec } from './cmd-i18n-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, CatalogExistsError, MissingPositionalError } from './errors';
 import {
@@ -36,7 +37,7 @@ import type { CommandResult, Finding, JsonValue } from './output';
 import { renderTable } from './table';
 import { catalogPath, resolveLocales } from './templates/locales';
 
-export const I18N_SUBCOMMANDS = ['check', 'add', 'sync'] as const;
+export { I18N_SUBCOMMANDS } from './cmd-i18n-spec';
 
 /** `ExtractReport` is plain JSON by construction — same idiom as `cmd-registries.ts`'s `asJson`. */
 const asJson = (value: object): Record<string, JsonValue> => value as Record<string, JsonValue>;
@@ -192,7 +193,7 @@ async function runAdd(root: string, ctx: CommandContext): Promise<CommandResult>
   // answered `X_CATALOG_UNREGISTERED` with a fix naming an edit that had already been made. Same
   // writer `x g --locales` already uses, so a catalog on disk and a selectable locale can never be
   // two different sets (#F4).
-  const registered = await syncI18nIndex(root);
+  const { registered, findings: indexFindings } = await syncI18nIndex(root);
 
   const keys = catalogKeys(seeded).length;
   return {
@@ -202,7 +203,7 @@ async function runAdd(root: string, ctx: CommandContext): Promise<CommandResult>
     ok: true,
     command: 'i18n',
     summary: msg('cli.i18n.added', { locale, keys, from: from ?? locale }),
-    findings: app.findings,
+    findings: [...indexFindings, ...app.findings],
     // `registered` is false only for an app with no `packages/i18n` at all — a fact a caller has
     // to be able to read, because it is the one case where the locale is on disk and unselectable.
     data: { locale, from: from ?? locale, keys, path, registered },
@@ -270,7 +271,7 @@ async function runSync(root: string, ctx: CommandContext): Promise<CommandResult
   // hand-created file, a `git merge` — is exactly the unregistered locale the gate refuses, and
   // this is the command its `fix:` names. Re-deriving an index that is already correct writes the
   // same bytes.
-  const registered = await syncI18nIndex(root);
+  const { registered, findings: indexFindings } = await syncI18nIndex(root);
 
   const total = catalogKeys(merged).length;
   return {
@@ -282,7 +283,7 @@ async function runSync(root: string, ctx: CommandContext): Promise<CommandResult
     // The keys themselves, raw — `runCheck` lists gaps the same way, because a key is a value an
     // author copies and never prose the catalog owns.
     lines: seeded ? added.map((key) => `  ${key}`) : [],
-    findings: app.findings,
+    findings: [...indexFindings, ...app.findings],
     data: {
       locale,
       from: from ?? locale,
@@ -298,15 +299,7 @@ async function runSync(root: string, ctx: CommandContext): Promise<CommandResult
 }
 
 export const i18nCommand: CliCommand = {
-  spec: {
-    name: 'i18n',
-    summary: 'catalogs: add a locale, sync keys, check for gaps',
-    usage: 'x i18n [check|add <locale>|sync <locale>] [--json]',
-    requiresApp: true,
-    subcommands: I18N_SUBCOMMANDS,
-    // The bare `x i18n` audits; `add` and `sync` write catalogs and must be asked for.
-    defaultSubcommand: 'check',
-  },
+  spec: i18nSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('i18n', ctx.cwd).dir;
     const sub = ctx.args.subcommand ?? 'check';

package/src/cmd-jobs-spec.ts

@@ -0,0 +1,56 @@
+// `x jobs`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-jobs.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const JOBS_SUBCOMMANDS = ['ls', 'show', 'retry', 'cancel', 'drain'] as const;
+
+/**
+ * The drivers a drain may move work ONTO — every one of them durable, and that is the whole rule.
+ * Closed, and read three ways: the flag summary, the refusal, and the `memory` case below.
+ */
+export const DRAIN_TARGETS = ['redis', 'nats'] as const;
+
+export const jobsSpec: CommandSpec = {
+  name: 'jobs',
+  summary: 'list, show, retry, cancel and drain the job queue',
+  usage:
+    'x jobs [ls|show <id>|retry <id>|cancel <id>|drain --to <driver>] [--queue q] [--state s] [--limit n] [--from-step name] [--reason text] [--to driver] [--dry-run] [--json]',
+  requiresApp: true,
+  subcommands: JOBS_SUBCOMMANDS,
+  // The bare `x jobs` lists; it never retries, cancels or drains anything.
+  defaultSubcommand: 'ls',
+  flags: [
+    { name: 'queue', type: 'string', summary: 'filter by queue name' },
+    { name: 'state', type: 'string', summary: 'filter by job state' },
+    { name: 'limit', type: 'string', summary: 'max rows to return' },
+    { name: 'name', type: 'string', summary: 'filter by job name' },
+    // Each of these is read by ONE subcommand — `retryJob`, `cancelJob`, `runDrain` — and says
+    // so in its own summary. The scope is what makes the parser refuse it anywhere else instead
+    // of accepting it and ignoring it: `x db gen --dry-run` parsed and wrote the migration.
+    {
+      name: 'from-step',
+      type: 'string',
+      summary: 'retry: drop this step so it re-executes',
+      subcommands: ['retry'],
+    },
+    {
+      name: 'reason',
+      type: 'string',
+      summary: 'cancel: why, recorded on the job',
+      subcommands: ['cancel'],
+    },
+    {
+      name: 'to',
+      type: 'string',
+      summary: `drain: target driver — ${DRAIN_TARGETS.join(', ')}`,
+      subcommands: ['drain'],
+    },
+    {
+      name: 'dry-run',
+      type: 'boolean',
+      summary: 'drain: report the plan, move nothing',
+      subcommands: ['drain'],
+    },
+  ],
+};