@ultimat3/cli 20.2.1 → 22.0.0

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

package/src/cmd-new.ts

@@ -7,13 +7,16 @@ import { chmod } from 'node:fs/promises';
 import { isAbsolute, join, resolve } from 'node:path';
 import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
 import { dedupe } from './cmd-generate';
+import { newSpec } from './cmd-new-spec';
 import type { CliCommand, CommandContext } from './command';
 import { invocationOf } from './command';
-import { AppNameIsPathError, MissingPositionalError } from './errors';
+import { AppNameEmptyError, AppNameIsPathError, MissingPositionalError } from './errors';
 import type { Runner } from './exec';
+import { reproducedFlags } from './invocation-flags';
 import { msg } from './messages';
 import type { CommandResult } from './output';
 import { flagBool, flagString } from './parse';
+import { quoteArg } from './shell-quote';
 import type { GeneratedFile } from './templates';
 import { appFiles, EXECUTABLE_FILES, names, repoFiles, resourceFiles } from './templates';
 import { loadVersion } from './version-loader';
@@ -59,6 +62,17 @@ const GIT_STEPS: readonly (readonly string[])[] = [
 /** What `--no-git` records, so `data.git` has the same shape whichever way the flag went. */
 const NO_GIT: RepositoryInit = { initialized: false, committed: false, problem: SKIPPED };
 
+/** `--force` into a directory that already existed: its files are not ours to commit. */
+const PRE_EXISTING: RepositoryInit = {
+  initialized: false,
+  committed: false,
+  problem: 'the directory already existed, so nothing was committed — its files are yours',
+};
+
+/** Every flag the caller set, in the spelling that reproduces it (`invocation-flags.ts`). */
+const callerFlags = (ctx: CommandContext): readonly string[] =>
+  reproducedFlags(newCommand.spec, ctx.args);
+
 /**
  * A scaffold is a REPOSITORY, because three surfaces of this CLI already assume one and answered
  * `not a git repository` in a fresh app: `x affected`, `x ci` and `x pr`. It was four —
@@ -151,34 +165,7 @@ export function appNamePath(raw: string): { parent: string; base: string } | und
 }
 
 export const newCommand: CliCommand = {
-  spec: {
-    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' },
-    ],
-  },
+  spec: newSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const raw = ctx.args.positionals[0];
     // The class, not a hand-built finding with the same code: `MissingPositionalError` is what
@@ -202,6 +189,13 @@ export const newCommand: CliCommand = {
       throw new AppNameIsPathError({ name: raw, invocation: invocationOf(ctx, 'new'), ...path });
     }
     const app = names(raw);
+    if (app.kebab === '') {
+      throw new AppNameEmptyError({
+        name: raw,
+        invocation: invocationOf(ctx, 'new'),
+        flags: callerFlags(ctx),
+      });
+    }
     const target = resolve(parentDir(ctx.cwd, flagString(ctx.args, 'dir')), app.kebab);
     const options: NewAppOptions = { name: raw, example: ctx.args.flags.get('example') !== false };
 
@@ -224,22 +218,33 @@ export const newCommand: CliCommand = {
           {
             code: 'X_GENERATE_CONFLICT',
             cause: `${target} already exists`,
-            fix: `x new ${app.kebab} --force, or choose another name`,
+            // The invocation the caller ran, with every flag it set: dropping `--dir` wrote a
+            // second app into the cwd, and the literal `x` is not installed under create-ultimate.
+            fix: `${[invocationOf(ctx, 'new'), quoteArg(app.kebab), ...callerFlags(ctx), '--force'].join(' ')}   # or choose another name`,
             docs: ERROR_DOCS_URL,
             at: target,
           },
         ],
       };
     }
+    // Read BEFORE writing: `--force` into a directory that already held files must never
+    // `git add -A && git commit` them — they are the user's, and `x new` did not write them.
+    const existed = existsSync(target);
     const written = await writeNewApp(target, options);
     const git =
-      ctx.args.flags.get('git') === false ? NO_GIT : await initRepository(ctx.runner, target);
+      ctx.args.flags.get('git') === false
+        ? NO_GIT
+        : existed
+          ? PRE_EXISTING
+          : await initRepository(ctx.runner, target);
     const lines = [msg('cli.new.wrote', { count: written.files.length, dir: target })];
-    if (git.problem !== null && git.problem !== SKIPPED) {
+    if (git.problem !== null && git.problem !== SKIPPED && git !== PRE_EXISTING) {
       lines.push(msg('cli.new.noRepository', { problem: git.problem }));
       // Raw, unlike the two prose lines around it: this one is an instruction to run verbatim, and
       // a translated command is a broken one (`packages/cli/CLAUDE.md`).
-      lines.push(`  run: cd ${target} && git init && git add -A && git commit -m 'x new'`);
+      lines.push(
+        `  run: cd ${quoteArg(target)} && git init && git add -A && git commit -m 'x new'`,
+      );
     }
     return {
       ok: true,

package/src/cmd-policy-spec.ts

@@ -0,0 +1,13 @@
+// `x policy`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-policy.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const policySpec: CommandSpec = {
+  name: 'policy',
+  summary: 'which clause decided a permission, and why',
+  usage: 'x policy [list|explain <subject>] [--json]',
+  requiresApp: true,
+  subcommands: ['list', 'explain'],
+  defaultSubcommand: 'list',
+};

package/src/cmd-policy.ts

@@ -5,11 +5,11 @@
 import { nearestName } from '@ultimat3/core';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
+import { policySpec } from './cmd-policy-spec';
 import type { CliCommand, CommandContext } from './command';
 import { DeclarationUnknownError, MissingPositionalError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
-
 import type { DeclarationExplanation } from './policy-facts';
 import { explainPolicy, knownPolicySubjects, listPolicy } from './policy-facts';
 import { renderTable } from './table';
@@ -123,14 +123,7 @@ function runExplain(ctx: CommandContext, findings: readonly Finding[]): CommandR
 }
 
 export const policyCommand: CliCommand = {
-  spec: {
-    name: 'policy',
-    summary: 'which clause decided a permission, and why',
-    usage: 'x policy [list|explain <subject>] [--json]',
-    requiresApp: true,
-    subcommands: ['list', 'explain'],
-    defaultSubcommand: 'list',
-  },
+  spec: policySpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('policy', ctx.cwd).dir;
     const { findings } = await loadApp(root);

package/src/cmd-pr-spec.ts

@@ -0,0 +1,39 @@
+// `x pr`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-pr.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const PR_SUBCOMMANDS = ['review', 'resolve', 'reply'] as const;
+
+export const prSpec: CommandSpec = {
+  name: 'pr',
+  summary: 'inline review threads: list them with their ids, resolve one, reply in one',
+  usage:
+    'x pr review [--pr <n>] [--repo owner/name] [--all] [--full] | x pr resolve <thread-id> | x pr reply <thread-id> --body "…"',
+  subcommands: PR_SUBCOMMANDS,
+  flags: [
+    { name: 'repo', type: 'string', summary: 'owner/name; the checkout own remote by default' },
+    { name: 'pr', type: 'string', summary: 'pull request number; this branch own by default' },
+    // Scoped to the subcommand each summary already names: `resolve` and `reply` WRITE to
+    // somebody else's pull request, and a flag they silently ignore is a flag whose caller
+    // believed it did something to a request that cannot be re-run.
+    {
+      name: 'all',
+      type: 'boolean',
+      summary: 'review: resolved threads too, not just open ones',
+      subcommands: ['review'],
+    },
+    {
+      name: 'full',
+      type: 'boolean',
+      summary: 'review: whole comment bodies, never truncated',
+      subcommands: ['review'],
+    },
+    {
+      name: 'body',
+      type: 'string',
+      summary: 'reply: the comment text to post in the thread',
+      subcommands: ['reply'],
+    },
+  ],
+};

package/src/cmd-pr.ts

@@ -5,6 +5,7 @@
 // `reviewDecision` outlives the push that answered it, and a RESOLVED thread is a closed
 // conversation rather than a fixed finding.
 
+import { PR_SUBCOMMANDS, prSpec } from './cmd-pr-spec';
 import type { CliCommand, CommandContext } from './command';
 import {
   BadFlagError,
@@ -13,6 +14,7 @@ import {
   UnknownCommandError,
 } from './errors';
 import { parseIntFlag } from './flag-number';
+import { commentBlock } from './foreign-text';
 import { PrNotFoundError, resolvePrNumber, resolveRepo } from './gh-target';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
@@ -20,7 +22,7 @@ import { flagBool, flagString } from './parse';
 import type { PrReviewReport, PrThread } from './pr-threads';
 import { fetchReviewReport, replyToThread, resolveThread, THREAD_PAGE } from './pr-threads';
 
-export const PR_SUBCOMMANDS = ['review', 'resolve', 'reply'] as const;
+export { PR_SUBCOMMANDS } from './cmd-pr-spec';
 
 /**
  * Every catalog key this command renders, declared. `msg()` answers `⟦key⟧` for a key nobody
@@ -51,38 +53,7 @@ export const PR_MESSAGE_KEYS = [
 export const BODY_LINES = 20;
 
 export const prCommand: CliCommand = {
-  spec: {
-    name: 'pr',
-    summary: 'inline review threads: list them with their ids, resolve one, reply in one',
-    usage:
-      'x pr review [--pr <n>] [--repo owner/name] [--all] [--full] | x pr resolve <thread-id> | x pr reply <thread-id> --body "…"',
-    subcommands: PR_SUBCOMMANDS,
-    flags: [
-      { name: 'repo', type: 'string', summary: 'owner/name; the checkout own remote by default' },
-      { name: 'pr', type: 'string', summary: 'pull request number; this branch own by default' },
-      // Scoped to the subcommand each summary already names: `resolve` and `reply` WRITE to
-      // somebody else's pull request, and a flag they silently ignore is a flag whose caller
-      // believed it did something to a request that cannot be re-run.
-      {
-        name: 'all',
-        type: 'boolean',
-        summary: 'review: resolved threads too, not just open ones',
-        subcommands: ['review'],
-      },
-      {
-        name: 'full',
-        type: 'boolean',
-        summary: 'review: whole comment bodies, never truncated',
-        subcommands: ['review'],
-      },
-      {
-        name: 'body',
-        type: 'string',
-        summary: 'reply: the comment text to post in the thread',
-        subcommands: ['reply'],
-      },
-    ],
-  },
+  spec: prSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     // No `defaultSubcommand`: `resolve` and `reply` both WRITE to a pull request, so "whatever the
     // caller left out" is not a safe guess for any of the three.
@@ -201,38 +172,7 @@ function threadLines(thread: PrThread, bodyLines: number): readonly string[] {
   return out;
 }
 
-const BLOCK_OPEN = '<comment id=';
-const BLOCK_CLOSE = '</comment>';
-
-/**
- * The fence, as a READER would parse it rather than as this file spells it.
- *
- * Two literal `replaceAll`s were the whole neutralisation, and markup is not spelled one way:
- * `</comment >`, `</COMMENT>` and `< comment id=` all end or open a block for anything reading
- * tags, and none of the three matched. One pattern over `<`, an optional `/`, and whitespace
- * around a case-insensitive `comment` covers every spelling of the delimiter; the escape goes on
- * the `<`, so what the reviewer wrote after it survives byte for byte.
- */
-const BLOCK_DELIMITER = /<(\s*\/?\s*comment\b)/gi;
-
-/**
- * One comment body, fenced and labelled with the thread id it came from — `@ultimat3/ai`'s
- * `documentBlock` (`rag.ts`), applied to the other place foreign text enters an agent's context.
- * `x pr review` exists because an agent cannot read the GitHub web UI, and a review body is
- * written by anyone who can comment on the pull request: rendered as bare indented text it arrived
- * in that agent's context indistinguishable from the command's own output, which is prompt
- * injection with a shell attached.
- *
- * The fence is neutralised INSIDE the payload rather than deleted, so every word the reviewer
- * wrote still reads, and the label is stripped of the three characters that would end the
- * attribute. Influence only, and deliberately not sold as more: a fence tells a reader this text
- * is data, and it can never stop one that decides otherwise.
- */
-export function commentBlock(id: string, lines: readonly string[]): readonly string[] {
-  const label = id.replaceAll('"', "'").replaceAll('>', ')').replaceAll('<', '(');
-  const body = lines.map((line) => line.replace(BLOCK_DELIMITER, '<\\$1'));
-  return [`${BLOCK_OPEN}"${label}">`, ...body, BLOCK_CLOSE];
-}
+export { commentBlock };
 
 /**
  * A review body is prose written for a browser: the ones in this repo run to six thousand

package/src/cmd-registries-spec.ts

@@ -0,0 +1,32 @@
+// `x actions`, `x queries` and `x entities`' declarations, apart from their body: the parser, `x help`
+// and the `errors` step read them without loading `cmd-registries.ts` and the three registries it
+// projects, which `registry.ts` imports only when one of the commands runs.
+
+import type { CommandSpec } from './parse';
+
+export const actionsSpec: CommandSpec = {
+  name: 'actions',
+  summary: 'the action registry: input/output schema, policy, tags, MCP exposure',
+  usage: 'x actions [list|describe <name>] [--json]',
+  subcommands: ['list', 'describe'],
+  defaultSubcommand: 'list',
+  requiresApp: true,
+};
+
+export const queriesSpec: CommandSpec = {
+  name: 'queries',
+  summary: 'the query registry: schema, policy, live, cache tags',
+  usage: 'x queries [list|describe <name>] [--json]',
+  subcommands: ['list', 'describe'],
+  defaultSubcommand: 'list',
+  requiresApp: true,
+};
+
+export const entitiesSpec: CommandSpec = {
+  name: 'entities',
+  summary: 'the entity registry: columns, invariants, indexes, tenancy',
+  usage: 'x entities [list|describe <name>] [--json]',
+  subcommands: ['list', 'describe'],
+  defaultSubcommand: 'list',
+  requiresApp: true,
+};

package/src/cmd-registries.ts

@@ -13,12 +13,12 @@ import type { AnyQuery, QueryDescriptor } from '@ultimat3/query';
 import { describeQueries, getQuery } from '@ultimat3/query';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
+import { actionsSpec, entitiesSpec, queriesSpec } from './cmd-registries-spec';
 import type { CliCommand, CommandContext } from './command';
 import { DeclarationUnknownError, MissingPositionalError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 import type { CommandSpec } from './parse';
-
 import { renderTable } from './table';
 
 /**
@@ -53,14 +53,7 @@ interface RegistryKind<D extends { readonly name: string }, Raw extends { descri
 const ACTIONS: RegistryKind<ActionDescriptor, AnyAction> = {
   kind: 'actions',
   singular: 'action',
-  spec: {
-    name: 'actions',
-    summary: 'the action registry: input/output schema, policy, tags, MCP exposure',
-    usage: 'x actions [list|describe <name>] [--json]',
-    subcommands: ['list', 'describe'],
-    defaultSubcommand: 'list',
-    requiresApp: true,
-  },
+  spec: actionsSpec,
   header: ['name', 'verb', 'resource', 'path', 'capability', 'mcp'],
   list: describeActions,
   find: getAction,
@@ -71,14 +64,7 @@ const ACTIONS: RegistryKind<ActionDescriptor, AnyAction> = {
 const QUERIES: RegistryKind<QueryDescriptor, AnyQuery> = {
   kind: 'queries',
   singular: 'query',
-  spec: {
-    name: 'queries',
-    summary: 'the query registry: schema, policy, live, cache tags',
-    usage: 'x queries [list|describe <name>] [--json]',
-    subcommands: ['list', 'describe'],
-    defaultSubcommand: 'list',
-    requiresApp: true,
-  },
+  spec: queriesSpec,
   header: ['name', 'live', 'capability', 'tags', 'ttlMs'],
   list: describeQueries,
   find: getQuery,
@@ -97,14 +83,7 @@ const QUERIES: RegistryKind<QueryDescriptor, AnyQuery> = {
 const ENTITIES: RegistryKind<EntityDescription, RegistryEntry> = {
   kind: 'entities',
   singular: 'entity',
-  spec: {
-    name: 'entities',
-    summary: 'the entity registry: columns, invariants, indexes, tenancy',
-    usage: 'x entities [list|describe <name>] [--json]',
-    subcommands: ['list', 'describe'],
-    defaultSubcommand: 'list',
-    requiresApp: true,
-  },
+  spec: entitiesSpec,
   header: ['name', 'table', 'columns', 'invariants', 'indexes', 'orgScoped'],
   list: describeEntities,
   find: getEntity,