@ultimat3/cli 1.1.0 → 2.0.0

package/src/error-codes.ts

@@ -0,0 +1,186 @@
+// The X_* codes owned by @ultimat3/cli, and nothing else: the two lists, their titles, the one
+// registration call and `docsFor`. Every code 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. The classes that throw these codes live in `./errors`.
+import { registerErrorCodes } 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',
+  // The ratchet's own code. A skipped step is not a failure — unless `x.verify.json` says this
+  // repo already ran it, in which case the suite was deleted and the gate would otherwise print
+  // one more green line for it.
+  'X_VERIFY_SUITE_VANISHED',
+  'X_FILE_TOO_LONG',
+  'X_PACKAGE_SHAPE',
+  // The build graph's own membership rule. `tsc -b` compiles referenced projects and nothing
+  // else, so a workspace no root reference names is one the `typecheck` step passes over without
+  // reading — the hole that let `scripts/` hold seven type errors under a green gate.
+  'X_PACKAGE_UNREFERENCED',
+  'X_RELEASE_VERSION_SKEW',
+  'X_STORAGE_UNWRITABLE',
+  'X_STORAGE_SECRET_DEV',
+  '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',
+  // The boot's own consistency check. `startServices` captures the drivers it built, and
+  // `loadApp` runs AFTER it — so an app module calling `setJobDriver(theirs)` moved the ambient
+  // slot and left the captured object alone: every `handle.enqueue()` went to their queue while
+  // the worker claimed from Postgres, and the `/_x` panel read the ambient one and agreed with
+  // the enqueue side. Nothing failed. Refused here rather than documented, per axiom 3.
+  'X_RUNTIME_DRIVER_SPLIT',
+  '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',
+  // The three ways an app's own guard can fail to be one. A guard is the app's convention made
+  // into a build error, so a guard the gate cannot trust has to be a finding rather than a skip:
+  // an app that believes its rule is enforced and is not is worse off than one with no rule.
+  'X_GUARD_INVALID',
+  'X_GUARD_FAILED',
+  'X_GUARD_FINDING_INVALID',
+  // The two halves of `x secrets edit` that belong to the terminal rather than to the envelope.
+  // `@ultimat3/core` owns every X_SECRETS_* code about the file and the key; an editor is the
+  // CLI's problem alone, and core would have no `fix:` to offer for one.
+  'X_SECRETS_EDITOR_MISSING',
+  'X_SECRETS_EDIT_FAILED',
+] 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.
+ *
+ * The three env codes are core's for the same reason: `defineEnv`, `checkEnv` and the
+ * `.env.example` projection all live in `@ultimat3/core`, and `x env` is the surface that reports
+ * them. A fourth code meaning "the example is stale" would be this package inventing a second name
+ * for a condition core already named.
+ *
+ * `X_ISLAND_INVALID` is `@ultimat3/render`'s and is borrowed for the same reason: "this src cannot
+ * become a client entry" is what that code already means, and the bundler is simply the half that
+ * can see whether the file exists. A CLI-owned twin would be one condition with two names.
+ */
+export const CLI_BORROWED_ERROR_CODES = [
+  'X_NOT_IMPLEMENTED',
+  'X_CONFIG_INVALID',
+  'X_ENV_MISSING',
+  'X_ENV_EXAMPLE_DRIFT',
+  'X_ISLAND_INVALID',
+] 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_STORAGE_UNWRITABLE: 'the storage disk this process needs cannot be written to',
+  X_STORAGE_SECRET_DEV: 'upload grants would be signed with the shipped development key',
+  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_VERIFY_SUITE_VANISHED: 'a step the committed floor requires had nothing left to check',
+  X_FILE_TOO_LONG: 'a source file is over 500 lines',
+  X_PACKAGE_SHAPE: 'a workspace package is missing a contract file',
+  X_PACKAGE_UNREFERENCED: 'a published workspace is not in the root tsconfig build graph',
+  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_RUNTIME_DRIVER_SPLIT: 'the ambient driver is not the one this process serves',
+  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',
+  X_GUARD_INVALID: 'a file in guards/ exports no usable guard',
+  X_GUARD_FAILED: 'an app guard threw instead of returning findings',
+  X_GUARD_FINDING_INVALID: "an app guard's finding breaks the error contract",
+  X_SECRETS_EDITOR_MISSING: 'no $EDITOR to open the decrypted secrets in',
+  X_SECRETS_EDIT_FAILED: 'the editor exited non-zero, so nothing was resealed',
+};
+
+// 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}`;

package/src/error-contract.ts

@@ -6,7 +6,8 @@
 
 // `join` is `node:`-only by necessity: Bun exposes no path-join primitive.
 import { join } from 'node:path';
-import { docsFor } from './errors';
+import { docsFor } from './error-codes';
+import { citedCommandProblem, loadCommandCatalog } from './fix-command';
 import type { Finding } from './output';
 import { eachSourceFile, isGenerated, isTest } from './source-files';
 import type { CodeSite, FixSite } from './ts-scan';
@@ -17,7 +18,12 @@ 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,
+  // The whole family, not one spelling of it. This was `see the docs?` — one article longer than
+  // `see docs`, which `@ultimat3/mcp`'s `server.ts` shipped as a `fix:` and which passed the gate
+  // for that reason alone. Measured against all 740 shipped fix literals: the wider pattern
+  // matches none of them, so it costs nothing and closes `read the docs` and `see documentation`
+  // before either is written.
+  /\b(?:see|read|consult|refer to)\s+(?:the\s+)?(?:docs?|documentation)\b/i,
 ];
 
 /**
@@ -59,13 +65,28 @@ const fixFinding = (site: FixSite, problem: string): Finding => ({
   at: `${site.at}:${site.line}`,
 });
 
-/** Every `fix:` an agent can be handed, read out of shipped source and held to the rule. */
+/**
+ * Every `fix:` an agent can be handed, read out of shipped source and held to BOTH rules: it must
+ * be an instruction, and any `x <command>` it cites must be one this build ships.
+ *
+ * The second rule is the one a text scan could never decide. Six fix lines shipped citing
+ * `x db status`, `x logs tail`, `x trace`, `x metrics`, `x auth whoami` and `x ai prompts` — all
+ * of them named a command, so all of them passed, and every one handed its reader
+ * `X_NOT_IMPLEMENTED` or `X_CLI_UNKNOWN_COMMAND` in place of the fix it promised.
+ *
+ * The catalog is loaded ONCE per run rather than per fix line: it is a dynamic import (see
+ * `fix-command.ts` for the cycle it breaks) and this walks every shipped source file.
+ */
 export async function checkErrorFixes(root: string): Promise<readonly Finding[]> {
   const findings: Finding[] = [];
+  const catalog = await loadCommandCatalog();
   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);
+      // The interpolation-blanked form for both rules: `x ${name}` names no command this can
+      // resolve, and reading `<value>` as one would be a finding nobody can act on.
+      const fix = staticFix(site.fix);
+      const problem = fixProblem(site.fix) ?? citedCommandProblem(fix, catalog);
       if (problem !== undefined) findings.push(fixFinding(site, problem));
     }
   }
@@ -148,8 +169,8 @@ export async function checkErrorCodeRegistry(
  * 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;
+const claim = (site: CodeSite, registry: boolean, borrowed: ReadonlySet<string>): number => {
+  if (!registry) return 1;
   return borrowed.has(site.code) ? 0 : 2;
 };
 
@@ -178,8 +199,9 @@ export async function collectDeclaredCodes(root: string): Promise<readonly CodeS
     if (isTest(source) || isGenerated(source)) continue;
     const text = await Bun.file(join(root, source)).text();
     const borrowed = scanBorrowedCodes(text);
+    const registry = isCodeRegistry(text);
     for (const site of scanCodes(text, source)) {
-      const found: [CodeSite, number] = [site, claim(site, borrowed)];
+      const found: [CodeSite, number] = [site, claim(site, registry, borrowed)];
       const seen = sites.get(site.code);
       sites.set(site.code, seen === undefined ? found : declarationOf(seen, found));
     }

package/src/error-fixes.ts

@@ -0,0 +1,114 @@
+// Every `X_*` code's REAL `fix:`, read off the throw site that raises it. `x errors explain` used
+// to answer `x verify --json` for every code the CLI does not own — 327 of 378 — which is a shrug,
+// not an instruction. The framework already writes an executable fix at each throw site and the
+// `errors` gate step already proves each one runnable, so the answer is to project that text
+// rather than to restate it in a second table nobody keeps current (axiom 2).
+
+// Bun ships no path join: the scan needs an absolute path per globbed, scope-relative entry.
+import { join } from 'node:path';
+import { staticFix } from './error-contract';
+import { frameworkScopeDir } from './framework-scope';
+import { isGenerated, isTest, isVendored } from './source-files';
+import type { CodeFixSite } from './ts-scan';
+import { scanCodeFixSites } from './ts-scan';
+
+/** Every throw site of one code, sorted by file then line so two machines answer identically. */
+export type CodeFixIndex = ReadonlyMap<string, readonly CodeFixSite[]>;
+
+/**
+ * Published packages ship `src` (`"exports": "./src/index.ts"` — the artifact IS the source), so
+ * this glob reaches the same files in `node_modules/@ultimat3` that it reaches in `packages/`.
+ */
+const PACKAGE_SOURCES = '*/src/**/*.{ts,tsx}';
+
+const byPosition = (a: CodeFixSite, b: CodeFixSite): number =>
+  a.at === b.at ? a.line - b.line : a.at.localeCompare(b.at);
+
+/**
+ * `x docs`'s `locate()` spelling, deliberately: `@ultimat3/render/src/errors.ts` is the one form
+ * that is both a resolvable specifier in an app and an unambiguous file in this monorepo, and two
+ * spellings of "where that is" is two things for a reader to learn.
+ */
+const located = (path: string): string => `@ultimat3/${path}`;
+
+/** One scope directory in, one index out — pure enough for a test to point at a fixture tree. */
+export async function scanScopeFixes(scope: string): Promise<CodeFixIndex> {
+  const index = new Map<string, CodeFixSite[]>();
+  // `followSymlinks` defaults to FALSE. `node_modules/@ultimat3/*` is a symlink per package under
+  // `bun link` and under any workspace an app resolves without realpath, and the default answer
+  // there is an empty index — the silent kind of empty, where every code falls back and nothing
+  // says a walk found nothing. The scope is a package directory, so there is no tree to run away
+  // into.
+  const walk = new Bun.Glob(PACKAGE_SOURCES).scan({ cwd: scope, followSymlinks: true });
+  for await (const path of walk) {
+    if (isTest(path) || isGenerated(path) || isVendored(path)) continue;
+    const text = await Bun.file(join(scope, path)).text();
+    for (const site of scanCodeFixSites(text, located(path))) {
+      // `${…}` holds a value only the throw site knows. Blanked to `<value>` — the same shape the
+      // `errors` step judges the line in — because a fix quoting a variable name an agent cannot
+      // resolve reads as a command it can paste, and it is not one.
+      const found: CodeFixSite =
+        site.fix === undefined ? site : { ...site, fix: staticFix(site.fix) };
+      index.set(site.code, [...(index.get(site.code) ?? []), found]);
+    }
+  }
+  for (const sites of index.values()) sites.sort(byPosition);
+  return index;
+}
+
+/**
+ * Whether the walk happened, which an empty index cannot say on its own. `unread` and `read` both
+ * produce no entry for a code and they mean opposite things: "this framework does not raise it"
+ * against "this process never got to look". A fallback line that cannot tell them apart states the
+ * first as fact whenever the second is true.
+ */
+export type CodeFixScan = 'unread' | 'read';
+
+let pending: Promise<CodeFixIndex> | undefined;
+let scanned: CodeFixIndex = new Map();
+let state: CodeFixScan = 'unread';
+
+/**
+ * Best-effort by design, and therefore **never** a throw. One unreadable file under a
+ * `node_modules` an installer left half-written would otherwise reject `loadCodeFixes()`, and its
+ * three callers await it unguarded — so a permission bit would take `x errors explain` and the
+ * whole of `x mcp serve`'s startup down for an index that is a nicety. `pending` caches the
+ * settled promise either way, so a rejection would have been permanent for the process too.
+ */
+async function build(): Promise<CodeFixIndex> {
+  const scope = frameworkScopeDir();
+  if (scope === undefined) return scanned;
+  try {
+    scanned = await scanScopeFixes(scope);
+    state = 'read';
+  } catch {
+    // Deliberately swallowed and deliberately not logged: `explainErrorCode` is the reporter, and
+    // `state` is what makes it say "could not be read" instead of "nothing raises this code".
+    scanned = new Map();
+  }
+  return scanned;
+}
+
+/**
+ * Memoised: one walk of the installed framework per process, for the same reason `loadErrorCatalog`
+ * imports every package once. Callers await this before anything reads `codeFixes()`, exactly as
+ * they await the catalog before reading `listErrorCodes()` — the seam is synchronous because
+ * `@ultimat3/mcp`'s `DevCapabilities.explainError` is.
+ */
+export function loadCodeFixes(): Promise<CodeFixIndex> {
+  pending ??= build();
+  return pending;
+}
+
+/** What has been loaded, synchronously. Empty until `loadCodeFixes()` has resolved. */
+export const codeFixes = (): CodeFixIndex => scanned;
+
+/** Whether the index above is an answer or an absence. */
+export const codeFixScan = (): CodeFixScan => state;
+
+/** Test seam — the counterpart to `resetErrorCatalog`. */
+export function resetCodeFixes(): void {
+  pending = undefined;
+  scanned = new Map();
+  state = 'unread';
+}