@ultimat3/cli 21.0.0 → 22.0.0

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'],
+    },
+  ],
+};

package/src/cmd-jobs.ts

@@ -7,6 +7,7 @@
 import type { JobDriver } from '@ultimat3/jobs';
 import { cancelJob, createNatsDriver, createRedisDriver } from '@ultimat3/jobs';
 import { requireAppRoot } from './app-root';
+import { DRAIN_TARGETS, jobsSpec } from './cmd-jobs-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, JobUnknownError, MissingPositionalError } from './errors';
 import type { DrainOutcome } from './jobs-drain';
@@ -27,13 +28,7 @@ import { msg } from './messages';
 import type { CommandResult } from './output';
 import { flagBool, flagString } 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 { DRAIN_TARGETS, JOBS_SUBCOMMANDS } from './cmd-jobs-spec';
 
 /**
  * `memory` was on that list until 2026-09 and could not be: `createMemoryDriver()` is a `Map` in
@@ -252,49 +247,7 @@ async function runDrain(
 }
 
 export const jobsCommand: CliCommand = {
-  spec: {
-    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'],
-      },
-    ],
-  },
+  spec: jobsSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('jobs', ctx.cwd).dir;
     const sub = ctx.args.subcommand ?? 'ls';

package/src/cmd-manifest-spec.ts

@@ -0,0 +1,15 @@
+// `x manifest`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-manifest.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const manifestSpec: CommandSpec = {
+  name: 'manifest',
+  summary: 'regenerate x.manifest.json and openapi.json from the code',
+  usage: 'x manifest [--check] [--json]',
+  requiresApp: true,
+  flags: [
+    { name: 'check', type: 'boolean', summary: 'fail if the committed files are stale' },
+    { name: 'openapi', type: 'boolean', summary: 'also write openapi.json', default: true },
+  ],
+};

package/src/cmd-manifest.ts

@@ -5,9 +5,11 @@
 import { join } from 'node:path';
 import type { Manifest } from '@ultimat3/manifest';
 import { assertNoDrift, MANIFEST_FILENAME } from '@ultimat3/manifest';
-import { appManifest, writeAppManifest } from './app-manifest';
-import { OPENAPI_FILE, openApiJson } from './app-openapi';
+import { writeAppArtifacts } from './app-artifacts';
+import { appManifest } from './app-manifest';
+import { openApiStaleness } from './app-openapi';
 import { requireAppRoot } from './app-root';
+import { manifestSpec } from './cmd-manifest-spec';
 import type { CliCommand, CommandContext } from './command';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
@@ -41,28 +43,24 @@ async function staleness(root: string, manifest: Manifest): Promise<Finding | un
 }
 
 export const manifestCommand: CliCommand = {
-  spec: {
-    name: 'manifest',
-    summary: 'regenerate x.manifest.json and openapi.json from the code',
-    usage: 'x manifest [--check] [--json]',
-    requiresApp: true,
-    flags: [
-      { name: 'check', type: 'boolean', summary: 'fail if the committed files are stale' },
-      { name: 'openapi', type: 'boolean', summary: 'also write openapi.json', default: true },
-    ],
-  },
+  spec: manifestSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('manifest', ctx.cwd).dir;
     const { manifest, findings } = await appManifest(root);
     const counts = countsOf(manifest);
 
     if (flagBool(ctx.args, 'check')) {
-      const stale = await staleness(root, manifest);
+      // BOTH files the command writes: `--check` compared only `x.manifest.json`, so a stale
+      // `openapi.json` — the one the typed client is generated from — read as fresh.
+      const stale = [
+        ...[await staleness(root, manifest)].filter((one) => one !== undefined),
+        ...(await openApiStaleness(root, manifest)),
+      ];
       return {
-        ok: stale === undefined && findings.length === 0,
+        ok: stale.length === 0 && findings.length === 0,
         command: 'manifest',
-        summary: stale === undefined ? msg('cli.manifest.fresh') : msg('cli.manifest.stale'),
-        findings: stale === undefined ? findings : [...findings, stale],
+        summary: stale.length === 0 ? msg('cli.manifest.fresh') : msg('cli.manifest.stale'),
+        findings: [...findings, ...stale],
         data: { buildId: manifest.buildId, counts },
       };
     }
@@ -79,10 +77,11 @@ export const manifestCommand: CliCommand = {
       };
     }
 
-    const path = await writeAppManifest(root, manifest);
-    if (ctx.args.flags.get('openapi') !== false) {
-      await Bun.write(join(root, OPENAPI_FILE), openApiJson(manifest));
-    }
+    await writeAppArtifacts(root, manifest, {
+      openapi: ctx.args.flags.get('openapi') !== false,
+      onlyExisting: false,
+    });
+    const path = join(root, MANIFEST_FILENAME);
     return {
       ok: true,
       command: 'manifest',

package/src/cmd-mcp-spec.ts

@@ -0,0 +1,21 @@
+// `x mcp`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-mcp.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const DEFAULT_PORT = 9229;
+
+export const mcpSpec: CommandSpec = {
+  name: 'mcp',
+  summary: 'serve the dev tools: routes, schema, policies, db, queues, logs, tests, verify',
+  usage: 'x mcp tools | x mcp serve [--transport stdio|http] [--port 9229] [--json]',
+  requiresApp: true,
+  subcommands: ['serve', 'tools'],
+  // No default, deliberately: `wiki/CLI-Reference.md` already says to write `x mcp serve` rather
+  // than a bare `x mcp`, and the parser's old first-element guess made the bare form START A
+  // SERVER — the one thing a word typed by mistake must not do. Refusing enforces the guidance.
+  flags: [
+    { name: 'transport', type: 'string', summary: 'stdio | http', default: 'stdio' },
+    { name: 'port', type: 'string', summary: 'HTTP port', default: String(DEFAULT_PORT) },
+  ],
+};

package/src/cmd-mcp.ts

@@ -6,6 +6,7 @@
 import { markListening, nanoid, timingSafeEqual } from '@ultimat3/core';
 import { mcpHttpRoute, serveStdio } from '@ultimat3/mcp';
 import { requireAppRoot } from './app-root';
+import { DEFAULT_PORT, mcpSpec } from './cmd-mcp-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError } from './errors';
 import { intFlagOr, PORT_RANGE } from './flag-number';
@@ -16,7 +17,6 @@ import { msg } from './messages';
 import type { CommandResult } from './output';
 import { flagString } from './parse';
 
-const DEFAULT_PORT = 9229;
 const TRANSPORTS = ['stdio', 'http'] as const;
 type Transport = (typeof TRANSPORTS)[number];
 
@@ -156,20 +156,7 @@ const readPort = (ctx: CommandContext): number =>
   );
 
 export const mcpCommand: CliCommand = {
-  spec: {
-    name: 'mcp',
-    summary: 'serve the dev tools: routes, schema, policies, db, queues, logs, tests, verify',
-    usage: 'x mcp tools | x mcp serve [--transport stdio|http] [--port 9229] [--json]',
-    requiresApp: true,
-    subcommands: ['serve', 'tools'],
-    // No default, deliberately: `wiki/CLI-Reference.md` already says to write `x mcp serve` rather
-    // than a bare `x mcp`, and the parser's old first-element guess made the bare form START A
-    // SERVER — the one thing a word typed by mistake must not do. Refusing enforces the guidance.
-    flags: [
-      { name: 'transport', type: 'string', summary: 'stdio | http', default: 'stdio' },
-      { name: 'port', type: 'string', summary: 'HTTP port', default: String(DEFAULT_PORT) },
-    ],
-  },
+  spec: mcpSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('mcp', ctx.cwd).dir;
     const transport = flagString(ctx.args, 'transport') ?? 'stdio';

package/src/cmd-new-spec.ts

@@ -0,0 +1,33 @@
+// `x new`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-new.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const newSpec: CommandSpec = {
+  name: 'new',
+  summary: 'scaffold a new Ultimate monorepo that already runs',
+  // Every flag the table below declares, in the spelling that turns it off where the default is
+  // on: the usage line offered `--no-example` while the table listed `--example`, and a reader
+  // had to reconcile the two to answer "which one do I get if I type neither".
+  usage: 'x new <name> [--dir path] [--no-example] [--no-git] [--dry-run] [--force] [--json]',
+  flags: [
+    { name: 'dir', type: 'string', summary: 'parent directory (default: cwd)' },
+    {
+      // The summary carries the default and the negation because the page has to answer "which
+      // one do I get if I type neither": the usage line offered `--no-example`, this table said
+      // `--example`, and `default: true` is a field only `--json` renders. 136 files against 109.
+      name: 'example',
+      type: 'boolean',
+      summary: 'include the example feature slice (default: on; --no-example for an empty app/)',
+      default: true,
+    },
+    {
+      name: 'git',
+      type: 'boolean',
+      summary: 'git init and commit the scaffold (default: on; --no-git for a bare directory)',
+      default: true,
+    },
+    { name: 'dry-run', type: 'boolean', summary: 'print the file list, write nothing' },
+    { name: 'force', type: 'boolean', summary: 'write into a directory that already exists' },
+  ],
+};