@ultimat3/cli 1.0.0

package/src/error-contract.ts

@@ -0,0 +1,212 @@
+// The error contract, enforced (axiom 3: a convention that is not a build error does not exist).
+// Axiom 4 says an error is an instruction, so a `fix:` an agent cannot act on is a defect in the
+// error, not a matter of taste — and a code no reference page documents strands whoever hits it.
+// Both halves are decidable before the code runs, which is why they are a gate step and not a
+// runtime assertion nobody sees until the failure they describe has already happened.
+
+// `join` is `node:`-only by necessity: Bun exposes no path-join primitive.
+import { join } from 'node:path';
+import { docsFor } from './errors';
+import type { Finding } from './output';
+import { eachSourceFile, isGenerated, isTest } from './source-files';
+import type { CodeSite, FixSite } from './ts-scan';
+import { isCodeRegistry, scanBorrowedCodes, scanCodes, scanFixes } from './ts-scan';
+
+/** Advice, not instruction. The list is the one in `docs/architecture/04-error-contract.md`. */
+export const BANNED_PHRASES: readonly RegExp[] = [
+  /\bcheck(s|ed|ing)?\b/i,
+  /\bmake sure\b/i,
+  /\btry(ing)?\b/i,
+  /\bsee the docs?\b/i,
+];
+
+/**
+ * What makes a fix actionable as written: the `x` CLI, a tool the machine already has, a call the
+ * reader can paste, or a file they can open. A banned phrase is only a failure without one of
+ * these — "check the gateway, then: x actions describe posts.publish --json" names the observation
+ * *and* the command, which is the shape the contract wants.
+ */
+export const COMMAND_TOKENS: readonly RegExp[] = [
+  /(?:^|[\s;|&("'`])x\s+[a-z][a-z-]*/,
+  /\b(?:bun|bunx|npm|npx|node|git|docker|kubectl|helm|psql|curl|openssl|biome|tsc)\b/,
+  /\b[A-Za-z_$][\w$]*\(/,
+  /[\w.@-]*\/[\w.@-]+\.(?:ts|tsx|js|json|md|toml|yaml|yml|css|scss|sql)\b/,
+  /\b(?:app\.config\.ts|package\.json|tsconfig\.json|bunfig\.toml|\.env(?:\.[\w.-]+)?)\b/,
+];
+
+/**
+ * `${…}` holds a value only the throw site knows, so it is blanked before the rule runs. Without
+ * this, `check egress to ${new URL(url).host}` reads as a call expression and passes as a command
+ * — the interpolation would launder pure advice into an instruction.
+ */
+export const staticFix = (raw: string): string => raw.replaceAll(/\$\{[^}]*\}/g, '<value>');
+
+/** The rule, on one fix line. `undefined` means it holds. */
+export function fixProblem(raw: string): string | undefined {
+  const fix = staticFix(raw);
+  if (fix.trim() === '') return 'the fix line is empty';
+  const banned = BANNED_PHRASES.find((phrase) => phrase.test(fix));
+  if (banned === undefined) return undefined;
+  if (COMMAND_TOKENS.some((token) => token.test(fix))) return undefined;
+  return `fix "${fix}" says "${fix.match(banned)?.[0] ?? ''}" and names no command, call or file`;
+}
+
+const fixFinding = (site: FixSite, problem: string): Finding => ({
+  code: 'X_ERROR_FIX_INVALID',
+  cause: problem,
+  fix: `rewrite the fix at ${site.at}:${site.line} as a command to run, a call to paste, or an edit naming a file`,
+  docs: docsFor('X_ERROR_FIX_INVALID'),
+  at: `${site.at}:${site.line}`,
+});
+
+/** Every `fix:` an agent can be handed, read out of shipped source and held to the rule. */
+export async function checkErrorFixes(root: string): Promise<readonly Finding[]> {
+  const findings: Finding[] = [];
+  for await (const path of eachSourceFile(root)) {
+    if (isTest(path) || isGenerated(path)) continue;
+    for (const site of scanFixes(await Bun.file(join(root, path)).text(), path)) {
+      const problem = fixProblem(site.fix);
+      if (problem !== undefined) findings.push(fixFinding(site, problem));
+    }
+  }
+  return findings;
+}
+
+/**
+ * A code is documented when the reference page names it. Deliberately not "owns a table row": the
+ * page legitimately groups near-identical codes onto one row, and a rule that forbade that would
+ * be a rule about formatting rather than about coverage.
+ */
+export const documentedCodes = (markdown: string): ReadonlySet<string> =>
+  new Set([...markdown.matchAll(/`(X_[A-Z0-9_]+)`/g)].map((match) => match[1] as string));
+
+const undocumentedFinding = (code: string, at: string, line: number, page: string): Finding => ({
+  code: 'X_ERROR_CODE_UNDOCUMENTED',
+  cause: `${code} is declared at ${at}:${line} and ${page} has no entry for it`,
+  fix: `add a row for ${code} to ${page}, with its cause and the command that fixes it`,
+  docs: docsFor('X_ERROR_CODE_UNDOCUMENTED'),
+  at: page,
+});
+
+/**
+ * The heading below which the reference stops making live claims. What follows is a code that is
+ * reserved (documented, nothing throws it yet) or a superseded name kept so an old log line still
+ * resolves. Both earn their rows; neither is a code an agent can be handed today, which is the
+ * only thing the registry rule below is about.
+ */
+export const RESERVED_HEADING = '## Reserved codes';
+
+/**
+ * The codes the reference presents as live: every one named above the reserved section.
+ *
+ * The heading is matched as a whole line, never as a substring. The same text is quoted in prose,
+ * in a fenced sample and in this file's own `unregisteredFinding` fix — and `indexOf` would cut the
+ * page at the first of those mentions, silently exempting every live code below it from the
+ * registry rule. A gate that stops reading halfway through the page reads green over the half it
+ * never saw.
+ */
+export function liveCodes(markdown: string): ReadonlySet<string> {
+  const lines = markdown.split('\n');
+  const cut = lines.findIndex((line) => line.trim() === RESERVED_HEADING);
+  return documentedCodes(cut === -1 ? markdown : lines.slice(0, cut).join('\n'));
+}
+
+const unregisteredFinding = (code: string, page: string): Finding => ({
+  code: 'X_ERROR_CODE_UNREGISTERED',
+  cause: `${page} documents ${code} as a live code and nothing registers it, so "x errors explain ${code}" refuses a code this page promises`,
+  fix: `register ${code} through registerErrorCodes() in its package's src/errors.ts, or move its row under "${RESERVED_HEADING}" in ${page}`,
+  docs: docsFor('X_ERROR_CODE_UNREGISTERED'),
+  at: page,
+});
+
+/**
+ * The other direction of the same contract, and the half nothing enforced: a code the reference
+ * documents that no package registers. `X_ERROR_CODE_UNDOCUMENTED` stops a shipped code losing its
+ * page; this stops a page inventing a code — a row an agent reads, acts on, and then cannot look
+ * up, because `x errors explain` answers from the registry and the registry never heard of it.
+ *
+ * `known` is what the host can answer for: the process-wide registry, plus whatever codes the host
+ * repo's own gate scripts declare (`X_ROADMAP_*` and friends never ship, so no package may own
+ * them). A missing page is `checkErrorCodeDocs`'s finding to report, not a second copy here.
+ */
+export async function checkErrorCodeRegistry(
+  root: string,
+  page: string,
+  known: ReadonlySet<string>,
+): Promise<readonly Finding[]> {
+  const reference = Bun.file(join(root, page));
+  if (!(await reference.exists())) return [];
+  return [...liveCodes(await reference.text())]
+    .filter((code) => !known.has(code))
+    .sort()
+    .map((code) => unregisteredFinding(code, page));
+}
+
+/**
+ * How strong a claim one site has on being *the* declaration of its code. A package declares the
+ * codes it owns in its own registry (`docs/architecture/04-error-contract.md`), and names the ones
+ * it borrows in that same file — so a registry that owns the code outranks a throw site, and a
+ * registry that has said the code is somebody else's ranks below both.
+ */
+const claim = (site: CodeSite, borrowed: ReadonlySet<string>): number => {
+  if (!isCodeRegistry(site.at)) return 1;
+  return borrowed.has(site.code) ? 0 : 2;
+};
+
+/**
+ * The stronger claim wins; equal claims settle by path, then line. Deliberately not glob order:
+ * `Bun.Glob` yields in directory order, which differs by filesystem, and a committed manifest
+ * keyed on the answer would drift between two machines reading the same tree.
+ */
+const declarationOf = (a: [CodeSite, number], b: [CodeSite, number]): [CodeSite, number] => {
+  if (a[1] !== b[1]) return a[1] > b[1] ? a : b;
+  if (a[0].at !== b[0].at) return a[0].at < b[0].at ? a : b;
+  return a[0].line <= b[0].line ? a : b;
+};
+
+/**
+ * Every `X_*` code shipped source declares, with the file and line that declares it — one walk of
+ * the whole source set, sorted by code, one entry per code. The answer to "which codes exist?"
+ * has exactly one implementation: the docs check below reads it, and so does the framework's
+ * generated manifest. A scanner that looked only at a package's own `src/errors.ts` would miss
+ * every code a gate script or a non-registry module throws, and two lists that disagree mean
+ * whichever one a reader trusts is the wrong one.
+ */
+export async function collectDeclaredCodes(root: string): Promise<readonly CodeSite[]> {
+  const sites = new Map<string, [CodeSite, number]>();
+  for await (const source of eachSourceFile(root)) {
+    if (isTest(source) || isGenerated(source)) continue;
+    const text = await Bun.file(join(root, source)).text();
+    const borrowed = scanBorrowedCodes(text);
+    for (const site of scanCodes(text, source)) {
+      const found: [CodeSite, number] = [site, claim(site, borrowed)];
+      const seen = sites.get(site.code);
+      sites.set(site.code, seen === undefined ? found : declarationOf(seen, found));
+    }
+  }
+  return [...sites.values()].map(([site]) => site).sort((a, b) => a.code.localeCompare(b.code));
+}
+
+/**
+ * Every `X_*` code shipped source declares must appear on the repo's error reference. The page is
+ * the host repo's to name — a framework monorepo publishes one, a generated app does not — which
+ * is why this arrives through the same host-check seam the tier table uses on `boundaries`.
+ */
+export async function checkErrorCodeDocs(root: string, page: string): Promise<readonly Finding[]> {
+  const reference = Bun.file(join(root, page));
+  if (!(await reference.exists())) {
+    return [
+      {
+        code: 'X_ERROR_CODE_UNDOCUMENTED',
+        cause: `the error reference ${page} does not exist, so no code can be documented`,
+        fix: `create ${page} with a row per X_* code, or stop naming it as the error reference`,
+        docs: docsFor('X_ERROR_CODE_UNDOCUMENTED'),
+        at: page,
+      },
+    ];
+  }
+  const documented = documentedCodes(await reference.text());
+  return (await collectDeclaredCodes(root))
+    .filter((site) => !documented.has(site.code))
+    .map((site) => undocumentedFinding(site.code, site.at, site.line, page));
+}

package/src/errors.ts

@@ -0,0 +1,367 @@
+// 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_DEPLOY_FAILED',
+  '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_DEPLOY_FAILED: 'a deploy step failed',
+  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}`;
+
+/** An unknown command or subcommand. Carries a suggestion so the retry is one keystroke away. */
+export class UnknownCommandError extends UltimateError {
+  constructor(input: { path: string; known: readonly string[]; suggestion?: string }) {
+    super({
+      code: 'X_CLI_UNKNOWN_COMMAND',
+      cause: `"x ${input.path}" is not a command (known: ${input.known.join(', ')})`,
+      fix: input.suggestion === undefined ? 'x help' : `x ${input.suggestion}`,
+      docs: docsFor('X_CLI_UNKNOWN_COMMAND'),
+    });
+  }
+}
+
+/**
+ * An unknown flag, a missing value, a value on a boolean flag, or a value the command refuses.
+ * `fix` defaults to the command's help; a caller that knows the working invocation passes it,
+ * because a runnable command beats a page to read.
+ */
+export class BadFlagError extends UltimateError {
+  constructor(input: { flag: string; command: string; reason: string; fix?: string }) {
+    super({
+      code: 'X_CLI_BAD_FLAG',
+      cause: `--${input.flag} on "x ${input.command}": ${input.reason}`,
+      fix: input.fix ?? `x ${input.command} --help`,
+      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[] }) {
+    super({
+      code: 'X_VERIFY_FAILED',
+      cause: `${input.failed.length} verify step(s) failed: ${input.failed.join(', ')}`,
+      fix: 'x verify --json',
+      docs: docsFor('X_VERIFY_FAILED'),
+    });
+  }
+}
+
+/** The command needs an app root (a directory containing `app.config.ts`) and found none. */
+export class NotInAppError extends UltimateError {
+  constructor(input: { command: string; from: string }) {
+    super({
+      code: 'X_NOT_IN_APP',
+      cause: `"x ${input.command}" must run inside an Ultimate app; no app.config.ts at or above ${input.from}`,
+      fix: 'x new myapp && cd myapp',
+      docs: docsFor('X_NOT_IN_APP'),
+    });
+  }
+}
+
+/** Bun is older than the framework floor. Nothing else can be trusted until this is fixed. */
+export class BunVersionError extends UltimateError {
+  constructor(input: { found: string; required: string }) {
+    super({
+      code: 'X_BUN_VERSION',
+      cause: `Bun ${input.found} is older than the required ${input.required}`,
+      fix: 'bun upgrade',
+      docs: docsFor('X_BUN_VERSION'),
+    });
+  }
+}
+
+/**
+ * `x test` discovered nothing. A green run over zero files is the most expensive false pass, so
+ * the selection that found nothing is named in full — a caller that cannot see whether the type
+ * or the filter emptied the set has to guess which one to drop.
+ */
+export class NoTestFilesError extends UltimateError {
+  constructor(input: { root: string; type?: string; filter?: string }) {
+    const parts = [
+      input.type === undefined ? undefined : `of type ${input.type}`,
+      input.filter === undefined ? undefined : `matching "${input.filter}"`,
+    ].filter((part): part is string => part !== undefined);
+    const where = parts.length === 0 ? '' : ` ${parts.join(' ')}`;
+    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',
+      docs: docsFor('X_TEST_NO_FILES'),
+    });
+  }
+}
+
+/**
+ * A generated path resolves outside the directory it is being written into — the scaffold gate's
+ * sandbox, the app root `x g` writes into, or the catalog root a `--locales` segment names. `..`
+ * or a separator would put template output on the developer's real disk, so it fails before the
+ * write, not after. `fix` names the invocation that works when the caller knows it.
+ */
+export class ScaffoldPathEscapeError extends UltimateError {
+  constructor(input: { path: string; dir: string; fix?: string }) {
+    super({
+      code: 'X_SCAFFOLD_PATH_ESCAPE',
+      cause: `generated path "${input.path}" resolves outside ${input.dir}`,
+      fix:
+        input.fix ??
+        `make the path relative to the app root with no ".." segment, then re-run: bun test packages/cli/src/scaffold-typecheck.contract.test.ts`,
+      docs: docsFor('X_SCAFFOLD_PATH_ESCAPE'),
+    });
+  }
+}
+
+/**
+ * A `merge: 'json'` `GeneratedFile` whose own `contents` do not parse as a JSON object — a bug in
+ * the template that produced it, not a recoverable end-user situation. `dedupe()` (`cmd-generate.ts`)
+ * throws this before the bad contributor can be silently treated as `{}` and merged into (or
+ * written as) a catalog with attribution to nobody.
+ */
+export class GenerateJsonInvalidError extends UltimateError {
+  constructor(input: { path: string }) {
+    super({
+      code: 'X_GENERATE_JSON_INVALID',
+      cause: `${input.path} is declared merge: 'json' but the generator's own contents for it do not parse as a JSON object`,
+      fix: `fix the template that emits ${input.path}, then re-run: bun test packages/cli/src/cmd-generate.test.ts`,
+      docs: docsFor('X_GENERATE_JSON_INVALID'),
+    });
+  }
+}
+
+/**
+ * `x i18n add <locale>` refuses to clobber a catalog that already exists — a human translation lost
+ * to a second run is unrecoverable. `X_GENERATE_CONFLICT` is this package's own code, used until now
+ * only as a `Finding` literal inside `cmd-generate.ts`'s `writeFiles`; this is the same registered
+ * code thrown as a real `UltimateError`. The path arrives already computed rather than derived from
+ * `catalogPath` here: `templates/locales.ts` imports this file, so calling back into it would close
+ * an import cycle.
+ */
+export class CatalogExistsError extends UltimateError {
+  constructor(input: { locale: string; path: string }) {
+    super({
+      code: 'X_GENERATE_CONFLICT',
+      cause: `${input.path} already exists`,
+      fix: `x i18n sync ${input.locale}`,
+      docs: docsFor('X_GENERATE_CONFLICT'),
+    });
+  }
+}
+
+/**
+ * The app's `package.json` cannot supply a name and a version. Defaulting to `app@0.0.0` would put
+ * a fabricated identity into `x.manifest.json`, whose version IS the semver compatibility gate —
+ * so the contract would be overwritten with a lie no downstream check could catch.
+ */
+export class AppPackageInvalidError extends UltimateError {
+  constructor(input: { path: string; problem: string }) {
+    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',
+      docs: docsFor('X_APP_PACKAGE_INVALID'),
+    });
+  }
+}
+
+/**
+ * `x errors explain` was handed a code no package registered. Inventing an explanation is the one
+ * answer worse than none: an agent would act on it. The suggestion makes the retry one keystroke.
+ */
+export class ErrorCodeUnknownError extends UltimateError {
+  constructor(input: { code: string; suggestion?: string }) {
+    super({
+      code: 'X_ERROR_CODE_UNKNOWN',
+      cause: `"${input.code}" is not a registered error code`,
+      fix:
+        input.suggestion === undefined
+          ? 'x errors list --json'
+          : `x errors explain ${input.suggestion}`,
+      docs: docsFor('X_ERROR_CODE_UNKNOWN'),
+    });
+  }
+}
+
+/**
+ * `x actions|queries|entities describe <name>` named a declaration the registries do not hold —
+ * a typo, or a module that never imported. `known` is the count, not the list: a 200-action app
+ * would bury the fix line under names nobody asked for, and `list` is one command away.
+ */
+export class DeclarationUnknownError extends UltimateError {
+  constructor(input: {
+    kind: string;
+    singular: string;
+    name: string;
+    known: readonly string[];
+    suggestion?: string;
+    /** The subcommand that takes one name. `describe` for the registries, `show` for `x tasks`. */
+    verb?: string;
+  }) {
+    super({
+      code: 'X_DECLARATION_UNKNOWN',
+      cause: `no ${input.singular} named "${input.name}" is registered (${input.known.length} known)`,
+      fix:
+        input.suggestion === undefined
+          ? `x ${input.kind} list --json`
+          : `x ${input.kind} ${input.verb ?? 'describe'} ${input.suggestion}`,
+      docs: docsFor('X_DECLARATION_UNKNOWN'),
+    });
+  }
+}
+
+/** `x jobs show|retry <id>` against an id the queue does not hold — wrong id, or already reaped. */
+export class JobUnknownError extends UltimateError {
+  constructor(input: { id: string; driver: string }) {
+    super({
+      code: 'X_JOB_UNKNOWN',
+      cause: `the "${input.driver}" queue holds no job with id "${input.id}"`,
+      fix: 'x jobs ls --json',
+      docs: docsFor('X_JOB_UNKNOWN'),
+    });
+  }
+}
+
+/**
+ * `x fix boundary <file>` was pointed at something outside the app's surface graph. `suggestion`
+ * is the nearest real path: repeating the caller's own failing argument back at them as the fix
+ * is the shape "errors are instructions" exists to ban.
+ */
+export class FixTargetUnknownError extends UltimateError {
+  constructor(input: { file: string; scanned: number; suggestion?: string }) {
+    super({
+      code: 'X_FIX_TARGET_UNKNOWN',
+      cause: `"${input.file}" is not one of the ${input.scanned} source file(s) under apps/*/{site,app,api,shared}`,
+      fix:
+        input.suggestion === undefined
+          ? 'x routes --json   # every registered route file, app-root-relative'
+          : `x fix boundary ${input.suggestion}`,
+      docs: docsFor('X_FIX_TARGET_UNKNOWN'),
+    });
+  }
+}
+
+/** An interface-complete command path whose remote/native half is not written yet. */
+export class CliNotImplementedError extends UltimateError {
+  constructor(input: { feature: string; fix: string }) {
+    super({
+      code: 'X_NOT_IMPLEMENTED',
+      cause: `${input.feature} is not implemented in this build`,
+      fix: input.fix,
+      docs: docsFor('X_NOT_IMPLEMENTED'),
+    });
+  }
+}

package/src/exec.ts

@@ -0,0 +1,70 @@
+// The single subprocess boundary for the CLI. Every shell-out goes through `exec` so timing,
+// output capture and the "command not found" failure mode are identical everywhere, and so a
+// test can substitute a fake runner instead of spawning anything.
+
+// `UltimateError` straight from core rather than a class in `./errors`: this module is imported by
+// every command, and `./errors` runs `registerErrorCodes` on import — a subprocess boundary must
+// not decide when the CLI's registry is populated. `X_CLI_UNEXPECTED` is owned there all the same.
+import { UltimateError } from '@ultimat3/core';
+
+export interface ExecResult {
+  readonly command: readonly string[];
+  readonly code: number;
+  readonly ok: boolean;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly durationMs: number;
+}
+
+export interface ExecOptions {
+  readonly cwd: string;
+  readonly env?: Readonly<Record<string, string>>;
+  readonly stdin?: string;
+}
+
+export type Runner = (command: readonly string[], options: ExecOptions) => Promise<ExecResult>;
+
+/** performance.now(), not Date.now(): the test preload freezes the wall clock on purpose. */
+const now = (): number => performance.now();
+
+export const exec: Runner = async (command, options) => {
+  const started = now();
+  const [head, ...rest] = command;
+  // A caller bug, never a user's: an empty argv reaches `Bun.spawn` as "spawn nothing" and there is
+  // no shell-out to report on. Coded like every other CLI failure, because a bare Error here would
+  // surface as an unexplained crash from the one boundary every command goes through.
+  if (head === undefined) {
+    throw new UltimateError({
+      code: 'X_CLI_UNEXPECTED',
+      cause: 'exec() was called with an empty command, so there is no program to spawn',
+      fix: 'pass the program as the first element: exec(["bun", "test"], { cwd })',
+    });
+  }
+  const proc = Bun.spawn([head, ...rest], {
+    cwd: options.cwd,
+    env: options.env === undefined ? Bun.env : { ...Bun.env, ...options.env },
+    stdin: options.stdin === undefined ? 'ignore' : new TextEncoder().encode(options.stdin),
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return {
+    command,
+    code,
+    ok: code === 0,
+    stdout,
+    stderr,
+    durationMs: Math.round(now() - started),
+  };
+};
+
+/** Merged stream, trimmed — what a human wants to read under a failed step. */
+export const execOutput = (result: ExecResult): string =>
+  [result.stdout, result.stderr]
+    .filter((part) => part.trim().length > 0)
+    .join('\n')
+    .trimEnd();