@ultimat3/cli 1.1.0 → 2.0.0

package/src/errors.ts

@@ -1,136 +1,8 @@
-// The X_* codes owned by @ultimat3/cli. Every one names the exact command that resolves it,
-// because the CLI is the surface an agent reads first — a failure here has to be actionable
-// without a doc lookup or a second round-trip.
-import { registerErrorCodes, UltimateError } from '@ultimat3/core';
-
-/** Codes this package declares and owns. */
-export const CLI_OWNED_ERROR_CODES = [
-  'X_CLI_UNKNOWN_COMMAND',
-  'X_CLI_BAD_FLAG',
-  'X_VERIFY_FAILED',
-  'X_NOT_IN_APP',
-  'X_BUN_VERSION',
-  'X_TEST_NO_FILES',
-  'X_TEST_SHARD_FAILED',
-  'X_SCAFFOLD_PATH_ESCAPE',
-  'X_GENERATE_JSON_INVALID',
-  'X_APP_PACKAGE_INVALID',
-  'X_ERROR_CODE_UNKNOWN',
-  'X_DECLARATION_UNKNOWN',
-  'X_JOB_UNKNOWN',
-  'X_FIX_TARGET_UNKNOWN',
-  'X_ERROR_FIX_INVALID',
-  'X_ERROR_CODE_UNDOCUMENTED',
-  'X_ERROR_CODE_UNREGISTERED',
-  // Reported as `Finding`s rather than thrown, and unregistered until now because of it — so
-  // `x errors explain X_TYPECHECK_FAILED` refused a code `x verify` had just printed. A finding
-  // carries an `X_*` code to the same reader a throw does; the registry is what makes that code
-  // explainable, unique and documented-or-fail, so a code the CLI emits is a code the CLI owns.
-  'X_CLI_UNEXPECTED',
-  'X_TYPECHECK_FAILED',
-  'X_LINT_FAILED',
-  'X_TEST_FAILED',
-  'X_FILE_TOO_LONG',
-  'X_PACKAGE_SHAPE',
-  'X_RELEASE_VERSION_SKEW',
-  'X_MANIFEST_STALE',
-  'X_BUDGET_UNMEASURED',
-  'X_BUILD_FAILED',
-  'X_BUILD_ENTRY_MISSING',
-  'X_DEPLOY_FAILED',
-  // The two the container's own environment can get wrong. A PaaS injects `PORT` and a supervisor
-  // injects `ROLE`; both arrive as strings from outside the app, so both are validated at boot
-  // rather than defaulted — a web role that quietly bound 3000 when the platform said 8080 fails
-  // its health check with nothing in the log that names the cause.
-  'X_ROLE_UNKNOWN',
-  'X_PORT_INVALID',
-  'X_GENERATE_CONFLICT',
-  'X_PORT_IN_USE',
-  'X_DB_GEN_FAILED',
-  'X_DB_MIGRATE_FAILED',
-  'X_DB_BRANCH_FAILED',
-  'X_DB_STUDIO_FAILED',
-  // The five app-surface boundary codes. `@ultimat3/render` owns the *rule* (`checkSurfaceBoundary`)
-  // and the CLI owns the diagnostic, because `x verify` and `x fix boundary` are the two commands
-  // that report it — see `app-boundaries.ts`, which holds the one rule-to-code table.
-  'X_BOUNDARY_SITE_TO_APP',
-  'X_BOUNDARY_SHARED_LEAF',
-  'X_BOUNDARY_APP_TO_API',
-  'X_BOUNDARY_ROUTE_TO_DB',
-  'X_BOUNDARY_SERVICE_TO_HTTP',
-] as const;
-
-/**
- * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s — `CliNotImplementedError` and every planned command
- * throw it, and none of them may declare a title for it. The CLI is the process that imports every
- * package (`error-catalog.ts`), so a title declared twice here is the one that would win by load
- * order rather than by ownership.
- */
-export const CLI_BORROWED_ERROR_CODES = ['X_NOT_IMPLEMENTED'] as const;
-
-/** Every code the CLI can throw: the ones it owns plus the one it borrows. */
-export const CLI_ERROR_CODES = [...CLI_OWNED_ERROR_CODES, ...CLI_BORROWED_ERROR_CODES] as const;
-
-export type CliOwnedErrorCode = (typeof CLI_OWNED_ERROR_CODES)[number];
-export type CliErrorCode = (typeof CLI_ERROR_CODES)[number];
-
-/**
- * Registered titles, so `x errors list` enumerates the CLI's codes alongside every other
- * package's instead of leaving a hole an agent has to read source to fill. Typed over
- * `CliOwnedErrorCode`, so adding a code without a title is a build error.
- */
-export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
-  X_CLI_UNKNOWN_COMMAND: 'not a command in the registry',
-  X_CLI_BAD_FLAG: 'unknown flag, missing value, or a value the command refuses',
-  X_VERIFY_FAILED: 'at least one x verify step failed',
-  X_NOT_IN_APP: 'the command needs an app root and found none',
-  X_BUN_VERSION: 'Bun is older than the framework floor',
-  X_TEST_NO_FILES: 'the test selection matched no files',
-  X_TEST_SHARD_FAILED: 'a test shard exited non-zero',
-  X_SCAFFOLD_PATH_ESCAPE: 'a generated path resolves outside the directory it is written into',
-  X_GENERATE_JSON_INVALID: "a generator's own merge: 'json' output does not parse as a JSON object",
-  X_APP_PACKAGE_INVALID: "the app's package.json supplies no name and version",
-  X_ERROR_CODE_UNKNOWN: 'no package registered this error code',
-  X_DECLARATION_UNKNOWN: 'no declaration with this name is registered',
-  X_JOB_UNKNOWN: 'the queue holds no job with this id',
-  X_FIX_TARGET_UNKNOWN: 'the named file is not one of the app source files',
-  X_ERROR_FIX_INVALID: "an error's fix line is not a runnable instruction",
-  X_ERROR_CODE_UNDOCUMENTED: 'a shipped error code has no row in the error reference',
-  X_ERROR_CODE_UNREGISTERED: 'the error reference documents a code no package registers',
-  X_CLI_UNEXPECTED: 'the CLI itself failed',
-  X_TYPECHECK_FAILED: 'tsc failed',
-  X_LINT_FAILED: 'Biome failed',
-  X_TEST_FAILED: 'a test type failed',
-  X_FILE_TOO_LONG: 'a source file is over 500 lines',
-  X_PACKAGE_SHAPE: 'a workspace package is missing a contract file',
-  X_RELEASE_VERSION_SKEW: 'a workspace is not at the lockstep version',
-  X_MANIFEST_STALE: 'openapi.json is stale',
-  X_BUDGET_UNMEASURED: 'a route declares a budget the build never measured',
-  X_BUILD_FAILED: 'x build failed',
-  X_BUILD_ENTRY_MISSING: "the build target's entry file is not in the app",
-  X_DEPLOY_FAILED: 'a deploy step failed',
-  X_ROLE_UNKNOWN: 'ROLE names something that is not a role',
-  X_PORT_INVALID: 'PORT is not a TCP port number',
-  X_GENERATE_CONFLICT: 'a generator would overwrite a file',
-  X_PORT_IN_USE: 'the dev port is taken',
-  X_DB_GEN_FAILED: 'x db gen failed',
-  X_DB_MIGRATE_FAILED: 'x db migrate failed',
-  X_DB_BRANCH_FAILED: 'an x db branch step failed',
-  X_DB_STUDIO_FAILED: 'x db studio failed',
-  X_BOUNDARY_SITE_TO_APP: 'site/ imported app/',
-  X_BOUNDARY_SHARED_LEAF: 'shared/ imported a surface',
-  X_BOUNDARY_APP_TO_API: 'app/ imported api/ at runtime',
-  X_BOUNDARY_ROUTE_TO_DB: 'a route touched the database',
-  X_BOUNDARY_SERVICE_TO_HTTP: 'a service imported HTTP',
-};
-
-// One unconditional call, so a second package claiming one of the CLI's codes throws
-// X_ERROR_CODE_DUPLICATE instead of losing silently to whichever module imported first.
-registerErrorCodes(
-  Object.fromEntries(Object.entries(CLI_ERROR_TITLES).map(([code, title]) => [code, { title }])),
-);
-
-export const docsFor = (code: CliErrorCode): string => `https://ultimate.dev/errors/${code}`;
+// The error classes @ultimat3/cli throws. One class per condition, each naming the exact command
+// that resolves it — the codes themselves, their titles and their registration are `./error-codes`,
+// so a package importing a class does not pull the table and vice versa.
+import { UltimateError } from '@ultimat3/core';
+import { docsFor } from './error-codes';
 
 /** An unknown command or subcommand. Carries a suggestion so the retry is one keystroke away. */
 export class UnknownCommandError extends UltimateError {
@@ -160,6 +32,49 @@ export class BadFlagError extends UltimateError {
   }
 }
 
+/**
+ * A required POSITIONAL argument that was not given. Its own class rather than a `BadFlagError`,
+ * because the cause then names a flag that does not exist — `x errors --json` reported
+ * `--code on "x errors"` and sent an agent straight into a second `X_CLI_BAD_FLAG` for the
+ * `--code` flag it had just been told about — and rather than `X_CLI_UNKNOWN_COMMAND`, which said
+ * "x g route is not a command" about a command form that is. `example` is a REAL invocation:
+ * `x g route <name>` pasted into a shell is a redirect, not a command.
+ */
+export class MissingPositionalError extends UltimateError {
+  constructor(input: { command: string; positional: string; example: string }) {
+    super({
+      code: 'X_CLI_BAD_FLAG',
+      cause: `"x ${input.command}" needs a <${input.positional}> positional and got none`,
+      fix: input.example,
+      docs: docsFor('X_CLI_BAD_FLAG'),
+    });
+  }
+}
+
+/**
+ * A command that declares subcommands, invoked with none and declaring no `defaultSubcommand`.
+ *
+ * `X_CLI_BAD_FLAG` is the code a missing positional already takes (`MissingPositionalError`), and a
+ * subcommand is one — a second code for "you left out an argument" is the synonym the registry
+ * exists to prevent. Its own class because the cause must not name a flag: the parser answered
+ * `subcommands[0]` before this existed, so `x db` ran `gen` and wrote a migration file nobody asked
+ * for. Help is the fix because which of six was meant is exactly what the caller did not say.
+ *
+ * `x help <command>`, never `x <command> --help`: the parser resolves the subcommand AFTER the
+ * flag loop, so `x db --help` throws THIS error again — a fix line that reproduces its own
+ * failure, verbatim, forever. `x help db` prints the subcommand list and the flags.
+ */
+export class MissingSubcommandError extends UltimateError {
+  constructor(input: { command: string; known: readonly string[] }) {
+    super({
+      code: 'X_CLI_BAD_FLAG',
+      cause: `"x ${input.command}" takes a subcommand and got none (one of: ${input.known.join(', ')})`,
+      fix: `x help ${input.command}`,
+      docs: docsFor('X_CLI_BAD_FLAG'),
+    });
+  }
+}
+
 /** At least one `x verify` step failed. The step findings carry the per-step fixes. */
 export class VerifyFailedError extends UltimateError {
   constructor(input: { failed: readonly string[] }) {
@@ -211,7 +126,7 @@ export class NoTestFilesError extends UltimateError {
     super({
       code: 'X_TEST_NO_FILES',
       cause: `no *.test.ts files${where} under ${input.root}`,
-      fix: parts.length === 0 ? 'x test --cwd <repo root>' : 'x test',
+      fix: parts.length === 0 ? 'x test --json   # run it from the repo root' : 'x test',
       docs: docsFor('X_TEST_NO_FILES'),
     });
   }
@@ -282,7 +197,7 @@ export class AppPackageInvalidError extends UltimateError {
     super({
       code: 'X_APP_PACKAGE_INVALID',
       cause: `${input.path} ${input.problem}, so the manifest has no app name or version to gate on`,
-      fix: 'bun pm pkg set name=<app> version=0.1.0',
+      fix: 'bun pm pkg set name=my-app version=0.1.0',
       docs: docsFor('X_APP_PACKAGE_INVALID'),
     });
   }
@@ -374,12 +289,28 @@ export class BuildEntryMissingError extends UltimateError {
     super({
       code: 'X_BUILD_ENTRY_MISSING',
       cause: `x build --target ${input.target} builds from ${input.entry}, and the app does not have it`,
-      fix: `x new <name> writes ${input.entry} — copy it from a fresh scaffold into this app`,
+      fix: `x new scratch-app --dry-run --json   # its file list carries ${input.entry}; copy that file into this app`,
       docs: docsFor('X_BUILD_ENTRY_MISSING'),
     });
   }
 }
 
+/**
+ * A client entry would not compile. `X_BUILD_FAILED`, not a code of its own: an island is a bundle
+ * entry point like any other, and the target's own logs are what says which line. The fix builds
+ * exactly that one file, so the next message an author reads is the compiler's and not the CLI's.
+ */
+export class IslandBuildFailedError extends UltimateError {
+  constructor(input: { file: string; logs: string }) {
+    super({
+      code: 'X_BUILD_FAILED',
+      cause: `${input.file} is an island entry point and would not bundle: ${input.logs}`,
+      fix: `bun build --target browser ${input.file}`,
+      docs: docsFor('X_BUILD_FAILED'),
+    });
+  }
+}
+
 /**
  * `ROLE` selects what a container is. One image runs every role, so a typo is a process that would
  * otherwise start, serve nothing and report healthy — the one failure a rolling deploy cannot see.
@@ -389,28 +320,73 @@ export class RoleUnknownError extends UltimateError {
     super({
       code: 'X_ROLE_UNKNOWN',
       cause: `ROLE="${input.role}" is not a role (known: ${input.known.join(', ')})`,
-      fix: `docker run -e ROLE=web <image>   # one of: ${input.known.join(', ')}`,
+      fix: `docker run -e ROLE=web my-app:latest   # one of: ${input.known.join(', ')}`,
       docs: docsFor('X_ROLE_UNKNOWN'),
     });
   }
 }
 
+/**
+ * The enqueue side and the claim side are looking at two different queues.
+ *
+ * `startServices` builds the drivers and captures them; `loadApp` imports the app's modules after
+ * it, and a module calling `setJobDriver()` at import time moves the ambient slot without touching
+ * the captured object. The worker then claims from what was captured while every
+ * `handle.enqueue()` publishes to what is ambient — jobs that are accepted, acknowledged, visible
+ * in `/_x` and never run. Refused at boot, because the alternative is a deployment that only ever
+ * looks healthy.
+ */
+export class RuntimeDriverSplitError extends UltimateError {
+  constructor(input: { driver: string; ambient: string; captured: string }) {
+    super({
+      code: 'X_RUNTIME_DRIVER_SPLIT',
+      // Both names are printed even when they are the same string — two `memory` drivers are two
+      // queues, and "they match" is exactly the reading that makes this bug invisible.
+      cause: `an app module installed a ${input.driver} driver (ambient: "${input.ambient}") that is not the object this boot captured ("${input.captured}"), so enqueues and claims would use different queues`,
+      fix: `pass the driver to the boot instead of installing it from an app module: runRole({ root, env, runtime: { ${input.driver}: yourDriver } })`,
+      docs: docsFor('X_RUNTIME_DRIVER_SPLIT'),
+    });
+  }
+}
+
 /**
  * Every PaaS injects `PORT` and expects the process to bind exactly it. Defaulting past a value
  * that will not parse is how a deploy comes up on 3000, fails the platform's health probe, and
  * reports nothing an operator can act on.
  */
 export class PortInvalidError extends UltimateError {
-  constructor(input: { value: string }) {
+  /** `name` so the scrape port reports itself; the code stays one, because the fault is one. */
+  constructor(input: { value: string; name?: string }) {
+    const name = input.name ?? 'PORT';
     super({
       code: 'X_PORT_INVALID',
-      cause: `PORT="${input.value}" is not a TCP port number between 0 and 65535`,
-      fix: 'docker run -e PORT=3000 <image>',
+      cause: `${name}="${input.value}" is not a TCP port number between 0 and 65535`,
+      fix: `docker run -e ${name}=${name === 'PORT' ? 3000 : 9090} my-app:latest`,
       docs: docsFor('X_PORT_INVALID'),
     });
   }
 }
 
+/**
+ * `x env` was run in an app whose `app.config.ts` exports no `envSchema`. Not a silent success:
+ * writing a `.env.example` with no variables in it, or reporting "0 declared variables, all
+ * present", both read as a working environment declaration to whoever runs the command next.
+ *
+ * `X_CONFIG_INVALID` is core's code for "a configuration this process cannot boot on — env or
+ * `app.config.ts`", which is exactly this; the CLI names it in `CLI_BORROWED_ERROR_CODES` rather
+ * than minting a synonym.
+ */
+export class EnvSchemaMissingError extends UltimateError {
+  constructor(input: { subcommand: string }) {
+    super({
+      code: 'X_CONFIG_INVALID',
+      cause: `x env ${input.subcommand} needs the env declaration, and app.config.ts exports no "envSchema"`,
+      fix: "add to app.config.ts: export const envSchema = { DATABASE_URL: { type: 'url', description: 'Postgres connection URL' } } satisfies EnvSchema; export const env = defineEnv(envSchema);",
+      docs: docsFor('X_CONFIG_INVALID'),
+    });
+  }
+}
+
 /** An interface-complete command path whose remote/native half is not written yet. */
 export class CliNotImplementedError extends UltimateError {
   constructor(input: { feature: string; fix: string }) {
@@ -422,3 +398,92 @@ export class CliNotImplementedError extends UltimateError {
     });
   }
 }
+
+/**
+ * The process could not obtain a storage disk to write to.
+ *
+ * Thrown at boot rather than at the first upload, and with a `fix` naming the two real options —
+ * a writable volume or an object store — because the failure it replaces was a bare `EROFS` from
+ * inside Bun's `mkdirSync`, with no code, no fix, and no mention of storage. A hardened container
+ * (`readOnlyRootFilesystem: true`) CrashLooped 22 times on it before anyone could tell what the
+ * process wanted.
+ */
+export class StorageUnwritableError extends UltimateError {
+  constructor(cause: string, fix: string) {
+    super({ code: 'X_STORAGE_UNWRITABLE', cause, fix, docs: docsFor('X_STORAGE_UNWRITABLE') });
+  }
+}
+
+/**
+ * A non-local boot that fell through to the embedded disk with no `STORAGE_SIGNING_SECRET`. The
+ * key it would sign with is a string published in this repo, and `acceptSignedUpload` trusts a
+ * signed `maxBytes`/`contentType` over the app's own `uploadPolicy` — so anyone holding it mints
+ * an unlimited upload of any type, for any key, including another org's.
+ *
+ * `X_ENV_MISSING`, the code `@ultimat3/storage` already refuses this with, rather than a CLI twin:
+ * two codes for one condition is what `cmd-doctor.ts` says out loud about the PWA pair. What this
+ * adds is the sentence storage cannot write — that the disk itself was a fallback nobody chose.
+ * The fix names object storage first, because that is the answer for most deployments; the volume
+ * rung is behind the `#`, so the line still runs verbatim.
+ */
+export class LocalDiskUnsafeError extends UltimateError {
+  constructor(input: { environment: string; root: string }) {
+    super({
+      code: 'X_ENV_MISSING',
+      cause:
+        `no S3_ENDPOINT/S3_BUCKET, so this ${input.environment} process fell back to the embedded ` +
+        `disk at ${input.root} — and with no STORAGE_SIGNING_SECRET it would sign upload grants ` +
+        'with the development key published in @ultimat3/storage',
+      fix: 'export S3_ENDPOINT=https://s3.example.com S3_BUCKET=my-app-uploads   # or keep the disk on a mounted volume: export STORAGE_SIGNING_SECRET="$(openssl rand -hex 32)"',
+      docs: docsFor('X_ENV_MISSING'),
+    });
+  }
+}
+
+/**
+ * `x secrets edit` decrypts into a buffer and hands it to `$EDITOR`. There is no fallback editor:
+ * guessing one and opening a decrypted file in it is the last place a surprise belongs.
+ */
+export class SecretsEditorMissingError extends UltimateError {
+  constructor(input: { vars: readonly string[] }) {
+    super({
+      code: 'X_SECRETS_EDITOR_MISSING',
+      cause: `x secrets edit opens the decrypted secrets in an editor and none of ${input.vars.join(', ')} is set`,
+      fix: 'EDITOR=nano x secrets edit',
+      docs: docsFor('X_SECRETS_EDITOR_MISSING'),
+    });
+  }
+}
+
+/**
+ * The editor exited non-zero — a crash, or a deliberate abort. The buffer is discarded either way
+ * and the committed file is left exactly as it was: resealing a buffer whose editor failed would
+ * commit whatever half-written state the crash left behind.
+ */
+export class SecretsEditFailedError extends UltimateError {
+  constructor(input: { editor: string; code: number }) {
+    super({
+      code: 'X_SECRETS_EDIT_FAILED',
+      cause: `"${input.editor}" exited ${input.code}, so the decrypted buffer was discarded and the committed secrets file was not rewritten`,
+      fix: 'x secrets edit',
+      docs: docsFor('X_SECRETS_EDIT_FAILED'),
+    });
+  }
+}
+
+/**
+ * `x secrets init` would overwrite a file that already exists. `X_GENERATE_CONFLICT` is this
+ * package's own code for exactly that, and a second name for "a generator would clobber something"
+ * is the duplication the code registry exists to prevent. Losing a master key is unrecoverable —
+ * the committed file it opens is then ciphertext nobody can read again.
+ */
+export class SecretsExistsError extends UltimateError {
+  constructor(input: { path: string; fix: string }) {
+    super({
+      code: 'X_GENERATE_CONFLICT',
+      cause: `${input.path} already exists, and x secrets init would replace it`,
+      fix: input.fix,
+      docs: docsFor('X_GENERATE_CONFLICT'),
+    });
+  }
+}

package/src/fix-command.ts

@@ -0,0 +1,268 @@
+// The half of the error contract that a text rule cannot decide: a `fix:` may cite `x <command>`
+// and that command may not exist. Six shipped fix lines named `x db status`, `x logs tail`,
+// `x trace`, `x metrics`, `x auth whoami` and `x ai prompts` — every one of them passed the
+// `errors` step, because the step checks that a fix NAMES a command, never that the build ships it.
+//
+// It reads THREE words for the same reason it reads two: `x db branch ls --json` shipped as a fix
+// while `x db branch` had no `ls`, because a rule stopping at the subcommand never saw the word
+// that decided what ran.
+
+import type { CommandSpec } from './parse';
+import { GLOBAL_FLAGS } from './parse';
+
+/**
+ * The rule is CONDITIONAL, and that is the whole design.
+ *
+ * *If* a fix cites `x <something>`, that something must resolve. It does NOT say every fix must
+ * name a command — axiom 4 asks for an executable instruction, and
+ * `set OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318` or
+ * `counter('orders_total', { maxSeries: 4000 })` are executable and correctly cite nothing. A
+ * universal rule would push an author towards citing a command that does not really fix it, which
+ * is a worse error than one with no command in it.
+ */
+// Digits are part of a name, not a boundary: `x i18n check` read through `[a-z-]*` alone cites
+// `x i`, which is not a command — a false finding on three of the framework's own fix lines.
+//
+// The THIRD slot also matches a `<placeholder>`, and only the third. A slot with a closed set is a
+// slot where the reader has nothing to substitute, so `x db branch <name>` — two shipped fix lines
+// in `@ultimat3/mcp` — is `X_CLI_UNKNOWN_COMMAND` when run and resolved clean while a placeholder
+// was invisible to the reader. Second and fourth slots are open positionals (`x new my-app`,
+// `x db branch drop <name>`), where a placeholder is exactly right.
+const CITATION =
+  /(?:^|[\s;|&("'`])x\s+([a-z][a-z\d-]*)(?:\s+([a-z][a-z\d-]*))?(?:\s+([a-z][a-z\d-]*|<[^>]*>))?/g;
+
+/**
+ * A long flag, `--` stripped. `--no-<name>` is the parser's negation of a boolean, so it resolves
+ * against `<name>` — reporting `no-example` as an unknown flag would be a finding about a working
+ * invocation. A `-j` short form is deliberately not read: one letter is too weak a signal in prose.
+ */
+const FLAG = /(?:^|\s)--(?:no-)?([a-z][a-z\d-]*)/g;
+
+/**
+ * Where a citation's argument list ends. `;`, `|` and `&` start a second shell word, `#` starts a
+ * comment, and a backtick or a quote closes the span the citation was written in — past any of
+ * them a `--flag` belongs to something else.
+ */
+const ARGUMENT_END = /[;|&#`'"]/;
+
+/** One `x …` citation, as written. `sub` is the next bare word, which may not be a subcommand. */
+export interface FixCitation {
+  readonly command: string;
+  readonly sub: string | undefined;
+  /** The bare word after `sub`. Judged only against a declared `subcommandPositionals` set. */
+  readonly positional: string | undefined;
+  /** Long flags written after it, in order, `--` and any `no-` stripped. */
+  readonly flags: readonly string[];
+}
+
+/**
+ * Every `x <command> [<word>] [--flag …]` a fix line cites.
+ *
+ * Read off the STATIC form of the fix — the caller blanks `${…}` first — because a command name
+ * assembled at run time is not a name this can resolve, and guessing at one would report findings
+ * nobody can act on. `x` alone, or `x --json`, cites nothing: the regex needs a bare lowercase
+ * word after the space.
+ *
+ * The flag list stops at the NEXT citation as well as at `ARGUMENT_END`: one fix line routinely
+ * names two commands (`x db migrate, then confirm with x db query "…" --json`), and charging the
+ * second command's flags to the first would report a finding on the wrong half of the sentence.
+ */
+export function fixCitations(fix: string): readonly FixCitation[] {
+  const matches = [...fix.matchAll(CITATION)].filter((match) => match[1] !== undefined);
+  return matches.map((match, index) => {
+    const start = match.index + match[0].length;
+    const next = matches[index + 1]?.index ?? fix.length;
+    const tail = fix.slice(start, next);
+    const stop = ARGUMENT_END.exec(tail)?.index;
+    const args = stop === undefined ? tail : tail.slice(0, stop);
+    return {
+      command: match[1] as string,
+      sub: match[2],
+      positional: match[3],
+      flags: [...args.matchAll(FLAG)].map((flag) => flag[1] as string),
+    };
+  });
+}
+
+/** Long flags a spec accepts: its own, plus the four every command takes. */
+const declaredFlags = (spec: CommandSpec): ReadonlySet<string> =>
+  new Set([...GLOBAL_FLAGS, ...(spec.flags ?? [])].map((flag) => flag.name));
+
+export interface CommandCatalog {
+  /** Every spec the registry holds, planned ones included — `x help` lists those too. */
+  readonly specs: readonly CommandSpec[];
+  /** Names that parse but exit `X_NOT_IMPLEMENTED`. Citing one is the bug this check closes. */
+  readonly planned: ReadonlySet<string>;
+  /** `"<command> <subcommand>"` pairs that parse and exit `X_NOT_IMPLEMENTED`. */
+  readonly plannedSubcommands: ReadonlySet<string>;
+}
+
+/**
+ * What a caller accepts from a citation. A `fix:` hands its reader a command to RUN, so a planned
+ * one is a defect; a doc page may legitimately *say* a command is planned, and a rule that refused
+ * that would delete `wiki/CLI-Reference.md`'s planned table one true row at a time.
+ *
+ * `allowPlanned` covers `PLANNED_SUBCOMMANDS` as well as `PLANNED_COMMANDS` — `x db studio` is the
+ * single entry in the first table, and four pages name it as planned.
+ */
+export interface CitationRules {
+  readonly allowPlanned?: boolean;
+}
+
+/**
+ * One citation that did not resolve, split so a caller can key on WHAT failed.
+ *
+ * `subject` is the invocation spelled the way it would be typed — `x db query`, `x env check --fix`
+ * — and it is deliberately stable under a doc edit that only moves the sentence around it. That is
+ * what lets `scripts/doc-commands-allow.ts` allow one page to name one non-command (the pages that
+ * say "there is no `x serve` command" are saying something TRUE) without waiving the rule for the
+ * rest of that page.
+ */
+export interface CitationFault {
+  readonly subject: string;
+  readonly reason: string;
+}
+
+/**
+ * A second word is judged as a subcommand ONLY when the spec declares subcommands at all, or
+ * against a declared closed set of positionals. `x new my-app` and `x g route posts` take open
+ * positionals, and reporting `my-app` as an unknown subcommand would be a finding about a working
+ * example.
+ */
+function wordFault(
+  spec: CommandSpec,
+  word: string,
+  catalog: CommandCatalog,
+  rules: CitationRules,
+): CitationFault | undefined {
+  const subject = `x ${spec.name} ${word}`;
+  if (spec.subcommands !== undefined) {
+    if (!spec.subcommands.includes(word)) {
+      return {
+        subject,
+        reason: `and ${spec.name} has no such subcommand (${spec.subcommands.join(', ')})`,
+      };
+    }
+    if (catalog.plannedSubcommands.has(`${spec.name} ${word}`) && rules.allowPlanned !== true) {
+      return { subject, reason: 'which is planned and exits X_NOT_IMPLEMENTED' };
+    }
+    return undefined;
+  }
+  const choices = spec.positionalChoices;
+  if (choices === undefined || choices.includes(word)) return undefined;
+  return {
+    subject,
+    reason: `and ${word} is not one of ${spec.name}'s positionals (${choices.join(', ')})`,
+  };
+}
+
+/**
+ * The third word, judged ONLY where the subcommand declares a closed set. `x jobs show <id>` and
+ * `x db gen "add publish_at"` take open positionals, so a universal third-word rule would report
+ * findings about working invocations — the same conditionality `wordFault` applies to the second.
+ */
+function positionalFault(spec: CommandSpec, sub: string, word: string): CitationFault | undefined {
+  const choices = spec.subcommandPositionals?.[sub];
+  if (choices === undefined || choices.includes(word)) return undefined;
+  // A placeholder is judged the same as a wrong word, and deliberately: there is nothing the
+  // reader could substitute that would make `x db branch <name>` run, because the slot is a verb.
+  return {
+    subject: `x ${spec.name} ${sub} ${word}`,
+    reason: `and ${spec.name} ${sub} takes one of ${choices.join(', ')}`,
+  };
+}
+
+/**
+ * Why a citation does not resolve, or `undefined` when it does. FIVE levels, because the drift is
+ * mostly BELOW the command name: `x db query` names a real command and an unreal subcommand,
+ * `x env check --fix` names both and an unreal flag, `x test summarize` names a first positional
+ * that is not a `TestType`, and `x db branch ls` named a real subcommand and a third word that
+ * `x db branch` read as a branch NAME. A rule stopping at the command name accepted all four.
+ *
+ * The planned check is the one the whole thing exists for: a PLANNED command is in the registry and
+ * parses, so a resolution that only asked "is this a known name" would accept `x logs tail` — the
+ * exact citation that throws `X_NOT_IMPLEMENTED` at the reader.
+ *
+ * Flags are NOT judged on a planned command. `cmd-planned.ts` builds its spec from a name, a
+ * summary and a usage line and declares no flags at all, so every flag its own usage line documents
+ * would read as unknown — while the real refusal is `X_NOT_IMPLEMENTED` one level up.
+ */
+export function citationFault(
+  citation: FixCitation,
+  catalog: CommandCatalog,
+  rules: CitationRules = {},
+): CitationFault | undefined {
+  const spec = catalog.specs.find(
+    (candidate) =>
+      candidate.name === citation.command || candidate.aliases?.includes(citation.command) === true,
+  );
+  if (spec === undefined) {
+    return { subject: `x ${citation.command}`, reason: 'which is not a command' };
+  }
+  const planned = catalog.planned.has(spec.name);
+  if (planned && rules.allowPlanned !== true) {
+    return {
+      subject: `x ${citation.command}`,
+      reason: 'which is planned and exits X_NOT_IMPLEMENTED',
+    };
+  }
+  if (citation.sub !== undefined) {
+    const fault = wordFault(spec, citation.sub, catalog, rules);
+    if (fault !== undefined) return fault;
+    if (citation.positional !== undefined) {
+      const deeper = positionalFault(spec, citation.sub, citation.positional);
+      if (deeper !== undefined) return deeper;
+    }
+  }
+  if (planned) return undefined;
+  const declared = declaredFlags(spec);
+  const unknown = citation.flags.find((flag) => !declared.has(flag));
+  if (unknown === undefined) return undefined;
+  return {
+    subject: `x ${spec.name} --${unknown}`,
+    reason: `and ${spec.name} declares no such flag — the parser refuses it with X_CLI_BAD_FLAG (known: ${[...declared].join(', ')})`,
+  };
+}
+
+/** The same answer as one sentence, which is what a `cause:` line wants. */
+export function citationProblem(
+  citation: FixCitation,
+  catalog: CommandCatalog,
+  rules: CitationRules = {},
+): string | undefined {
+  const fault = citationFault(citation, catalog, rules);
+  return fault === undefined ? undefined : `cites "${fault.subject}", ${fault.reason}`;
+}
+
+/** The first citation that does not resolve. One finding per fix line, not one per word. */
+export function citedCommandProblem(
+  fix: string,
+  catalog: CommandCatalog,
+  rules: CitationRules = {},
+): string | undefined {
+  for (const citation of fixCitations(fix)) {
+    const problem = citationProblem(citation, catalog, rules);
+    if (problem !== undefined) return problem;
+  }
+  return undefined;
+}
+
+/**
+ * The registry, as this check reads it.
+ *
+ * Imported dynamically because `registry.ts` → `cmd-verify.ts` → `error-contract.ts` closes a
+ * cycle back to the caller. The precedent is `cmd-build.ts`'s `await import('./cmd-verify')`:
+ * one break, inside a function that is already async, rather than a second copy of the command
+ * list here — which would be a catalog that can disagree with the one `x help` prints.
+ */
+export async function loadCommandCatalog(): Promise<CommandCatalog> {
+  const { SPECS } = await import('./registry');
+  const { PLANNED_COMMANDS, PLANNED_SUBCOMMANDS } = await import('./cmd-planned');
+  return {
+    specs: SPECS,
+    planned: new Set(PLANNED_COMMANDS.map((planned) => planned.name)),
+    plannedSubcommands: new Set(
+      PLANNED_SUBCOMMANDS.map((planned) => `${planned.command} ${planned.subcommand}`),
+    ),
+  };
+}