@ultimat3/cli 29.3.2 → 30.0.0

package/src/mcp-errors.ts

@@ -28,7 +28,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_CLI_FLAG_UNREAD:
     'bun test packages/cli/src/flag-reads.test.ts   # the finding names the flag and the file to read it in',
   X_VERIFY_FAILED: 'x verify --json',
-  X_NOT_IN_APP: 'x new myapp --json && cd myapp',
+  // Outside an app `x` is on no PATH, and `bunx x` fetches an unrelated npm package named `x`.
+  X_NOT_IN_APP: 'bunx create-ultimate myapp --json && cd myapp',
   X_BUN_VERSION: 'bun upgrade',
   X_NOT_IMPLEMENTED: 'x doctor --json',
   // Core's three env codes, answered by the command that covers each. `X_CONFIG_INVALID` gets
@@ -125,7 +126,7 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_CLI_UNEXPECTED: 'x doctor --json',
   // `-p .`: an app root has no `references`, so the gate's own step runs this form (#450).
   X_TYPECHECK_FAILED: 'bunx tsc -p . --pretty false',
-  X_LINT_FAILED: 'bunx biome check --write .',
+  X_LINT_FAILED: 'bunx biome check .',
   X_TEST_FAILED: 'x test --json   # the finding carries the exact bun test invocation that failed',
   // The same two edits `vanishedSuiteFinding` names, verbatim, so both surfaces of this code hand
   // an agent one instruction. Neither edit is scripted here on purpose: a command that rewrites
@@ -312,6 +313,85 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x i18n check --json   # the finding names the locale and the key still carrying the reference value',
   X_WORKER_QUEUE_UNKNOWN:
     'x jobs list --json   # set WORKER_QUEUES to queues it lists, or add the queue to jobs.queues in app.config.ts',
+  X_UPGRADE_DIRTY_TREE: 'git status --short   # then commit or stash, and re-run: x upgrade --json',
+  X_UPGRADE_MIXED_PINS: 'x upgrade --dry-run --json   # the refusal names the exact --to to paste',
+  X_UPGRADE_HOP_TOO_WIDE:
+    'x upgrade --dry-run --json   # with no --to, it answers the one hop this app may take',
+  X_UPGRADE_REGISTRY_UNREACHABLE:
+    'bun pm view @ultimat3/cli version   # once this answers, re-run: x upgrade --json',
+  X_UPGRADE_PIN_UNREADABLE:
+    'x upgrade --json   # after editing the package.json the cause names, so every @ultimat3/* carries a version',
+  X_UPGRADE_VERSION_UNPUBLISHED:
+    'bun pm view @ultimat3/cli versions --json   # then: x upgrade --to <one of them> --json',
+  X_UPGRADE_INSTALL_FAILED:
+    'git restore .   # undoes the pins, since the tree was clean; then fix what the cause names and re-run: x upgrade --json',
+  X_UPGRADE_GATE_UNREADABLE: 'bun node_modules/@ultimat3/cli/src/bin.ts verify --json',
+  X_DEPLOY_BUILD_UNSTAMPED:
+    "x build --target docker --json   # stamps BUILD_ID into the image; or set BUILD_ID in the image's environment",
+  X_DEPLOY_UNSTABLE:
+    'x deploy verify --url https://app.example.com --json   # samples.byStatus and samples.byBuild name what interrupted it',
+  X_DEPLOY_QUEUE_UNSERVED:
+    'x jobs list --json   # then WORKER_QUEUES=<queue> on a worker Deployment, or --idle-ok <queue> on x deploy verify for a scale-to-zero pool',
+  X_DEPLOY_BUILD_MISMATCH:
+    'x deploy verify --url https://app.example.com --build "$BUILD_ID" --json   # the id CI stamped; meta.byBuild names what answered',
+  X_JOB_OUTLASTS_DRAIN:
+    "drain: { workerRetireMs: 7200000 },   // at least the job's timeout, in app.config.ts, then x verify --only manifest --json",
+  X_FEATURE_REQUIRED:
+    'x help g --json   # then the query generator with --feature <slice>, or the resource generator for a new table',
+  X_BOUNDARY_PACKAGE_TO_APP:
+    'x verify --only boundaries --json   # after moving the shared code into the package, or importing in the opposite direction',
+  X_APP_IMPORT_UNRESOLVED:
+    'x doctor --json   # names the package to bun add, or the file whose import to edit',
+  X_STREAM_ALREADY_FLUSHED:
+    'load: async () => { setCookie(name, value); return data; },   // in defineRoute, never inside a Hole',
+  X_QUERY_SLICE_ENTITY:
+    'x queries list --json   # then declare the read by hand over the entity the slice declares',
+  X_DEPLOY_ENV_MISSING: 'x env init --production --json',
+  X_ENV_FILE_EXISTS:
+    'NODE_ENV=production x env check --json   # the file is kept: edit a value in it by hand',
+  X_DEV_STOP_TIMEOUT:
+    'x stop --timeout 2m --json   # still running: kill -9 the pid its cause names, then x dev --json',
+  X_DEV_STOP_DENIED: 'cat .x/dev.lock   # then, as the user who owns that pid: x stop --json',
+  X_ASSET_RETAIN_FAILED: 'x doctor --json',
+  X_APP_MODULE_LOAD_FAILED:
+    'x manifest --json   # names each module that does not load and why; fix it, then restart the role',
+  X_CHART_MISSING: 'x g chart-alerts --print --json',
+  X_ENTITY_VIEW_DRIFT:
+    "x verify --only drift --json   # the cause names the view entity and both column lists: make columns name exactly the view's output, or change view.sql and x db gen",
+  X_CLIENT_SPEC_UNSUPPORTED:
+    'x help client --json   # then rerun with --only naming the tags around the pointer the cause names, or pin a corrected source.json',
+  X_CLIENT_STALE:
+    'x verify --only drift --json   # each finding names the line that regenerates its client',
+  X_CLIENT_EDITED:
+    'x verify --only drift --json   # regenerate with the command the finding names, and keep custom code in a file of your own that wraps the client',
+  X_GRAPH_NODE_UNKNOWN: 'x graph --json   # every node id is in data.nodes',
+  X_CLIENT_SPEC_INVALID:
+    'x help client --json   # then point --from at the OpenAPI 3.0 or 3.1 document itself',
+  X_REPRO_UNKNOWN: 'x repro --list --json',
+  X_REPRO_NOT_REPRODUCED:
+    'x repro --list --json   # re-read the bundle (x repro ID --json), then set its listed masked fields and unread rows by hand in the written test',
+  X_REPRO_CAPTURE_OFF:
+    'x jobs list --json   # a job id replays with capture off; for requests set failureCapture: { enabled: true } in app.config.ts',
+  X_ENTITY_RETAIN_UNSWEPT:
+    "add export const retention = purge({ entities: 'declared' }) to a jobs module named in jobs: [...] in apps/web/api/index.ts, then x verify",
+  X_NEW_SHAPE_UNKNOWN: 'bunx @ultimat3/cli help new',
+  X_NEW_SHAPE_CONFLICT: 'bunx @ultimat3/cli new myapp --shape blog',
+  X_SEO_CARD_ROUTE_UNKNOWN:
+    'x routes --json   # list the site/ routes; add apps/web/site/<the capture path>/page.tsx at 1200 x 630 with robots: { index: false }, or correct the og.capture path',
+  X_SEO_CARD_BROWSER_MISSING:
+    'export CHROME_PATH=/usr/bin/google-chrome   # any Chrome, Chromium or Edge binary; or drop og.capture from the route; the gate build passes --no-capture and needs none',
+  X_IMAGE_SOURCE_UNREADABLE:
+    "x build --target static --json   # lists the export; put the file under apps/web/site/assets/ and pass asset('assets/<file>') as src, or give an absolute https:// URL",
+  X_VERIFY_SKIPS_OVER_CEILING:
+    'x test unit --json   # then set what the skipped tests need, or raise skipCeiling in x.verify.json with the reason in the diff',
+  X_ASSET_VARIANT_UNDECLARED:
+    "responsiveImage({ src: asset('assets/hero.png'), width, height, alt })   # no widths/formats override for a site asset; an upload under /media answers any width",
+  X_NEW_SHAPE_GENERATE_FAILED:
+    'bunx x g sign-in --password --json   # in the app x new wrote, reproduces it; then bun test packages/cli/src/templates/shapes',
+  X_ISLAND_DISPOSER_MISSING:
+    'x verify --only boundaries --json   # names the file; end its mount() with return render(() => <Island {...props} />, el)',
+  X_SOCKET_HAND_ROLLED:
+    'x verify --only boundaries --json — names the file and line; delete the upgrade and declare the socket with deviceSocket({ path, resolveToken, onFrame }) from @ultimat3/realtime/server',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>

package/src/mcp-host.ts

@@ -25,9 +25,10 @@ import {
   readOnlyQuery,
 } from '@ultimat3/db';
 import { inspectJobList, inspectQueues } from '@ultimat3/jobs';
-import { MANIFEST_FILENAME } from '@ultimat3/manifest';
+import { impactOf, MANIFEST_FILENAME, pathBetween } from '@ultimat3/manifest';
 import type {
   DevCapabilities,
+  DevGraphQuestion,
   McpCaller,
   McpServer,
   QueryLimits,
@@ -38,6 +39,7 @@ import type {
 import { DEV_SCOPES, devHost, devMcpServer, frameworkIntrospection } from '@ultimat3/mcp';
 import { loadApp } from './app-load';
 import { appManifest, policyFacts } from './app-manifest';
+import { loadAppGraph, resolveNode } from './cmd-graph-load';
 import { runVerify, VERIFY_STEPS } from './cmd-verify';
 import { declareDevEnvironment } from './dev-environment';
 import { loadCodeFixes } from './error-fixes';
@@ -312,6 +314,14 @@ function capabilities(
 
     explainError: explainErrorCode,
 
+    // Loaded per question, as `x impact` loads it: an agent asks between edits, and a graph held
+    // for the session would answer for the code as it was when the host started.
+    async queryGraph(question: DevGraphQuestion) {
+      const { graph } = await loadAppGraph(root);
+      if (question.kind === 'impact') return impactOf(graph, resolveNode(graph, question.node));
+      return pathBetween(graph, resolveNode(graph, question.from), resolveNode(graph, question.to));
+    },
+
     ...ui,
 
     async verify(fix: boolean): Promise<VerifyResult> {

package/src/mcp-lock-findings.ts

@@ -0,0 +1,57 @@
+// The `manifest` step's remote-MCP half: every `mcpTools()` the app declares, its live server
+// compared with `tools.lock.json` — what `x mcp lock <name> --check` does, for every name at once.
+// A drift is the convention's build error (`X_MCP_REMOTE_TOOL_CHANGED`); a server that cannot be
+// reached is a warning, because a third party's outage must not block an unrelated change.
+
+// why: Bun exposes no path-join primitive; the lock sits at the app root.
+import { join } from 'node:path';
+import { ERROR_DOCS_URL, isUltimateError, renderThrowable } from '@ultimat3/core';
+import type { DeclaredMcpServer } from '@ultimat3/mcp';
+import {
+  declaredMcpServers,
+  lockChanges,
+  McpRemoteToolChangedError,
+  readToolsLock,
+  TOOLS_LOCK_FILE,
+} from '@ultimat3/mcp';
+import { loadApp } from './app-load';
+import type { AppLoader } from './app-permissions';
+import type { Finding } from './output';
+
+export interface McpLockReport {
+  readonly findings: readonly Finding[];
+  /** One line per server whose live list could not be read. */
+  readonly warnings: readonly string[];
+}
+
+/** Says nothing when the load failed: a missing lock is already the load's finding. */
+export async function mcpLockFindings(
+  root: string,
+  load: AppLoader = loadApp,
+  servers: () => ReadonlyMap<string, DeclaredMcpServer> = declaredMcpServers,
+): Promise<McpLockReport> {
+  if ((await load(root)).findings.length > 0) return { findings: [], warnings: [] };
+  const declared = [...servers().values()];
+  if (declared.length === 0) return { findings: [], warnings: [] };
+  const file = Bun.file(join(root, TOOLS_LOCK_FILE));
+  const lock = readToolsLock((await file.exists()) ? ((await file.json()) as unknown) : undefined);
+  const findings: Finding[] = [];
+  const warnings: string[] = [];
+  for (const server of declared) {
+    let live: Awaited<ReturnType<DeclaredMcpServer['client']['listTools']>>;
+    try {
+      live = await server.client.listTools();
+    } catch (error) {
+      const code = isUltimateError(error) ? error.code : 'unknown';
+      warnings.push(
+        `${TOOLS_LOCK_FILE}: "${server.name}" was not checked, its server did not list its tools (${code}: ${renderThrowable(error)})`,
+      );
+      continue;
+    }
+    const changes = lockChanges(lock.get(server.name), server.url, server.allow, live);
+    if (changes.length === 0) continue;
+    const drift = new McpRemoteToolChangedError({ server: server.name, changes });
+    findings.push({ code: drift.code, cause: drift.message, fix: drift.fix, docs: ERROR_DOCS_URL });
+  }
+  return { findings, warnings };
+}

package/src/measure-paths.ts

@@ -4,8 +4,8 @@
 // `/blog/:slug` with an empty `slug` failed the page's own input schema (`X_INPUT_INVALID`), and
 // that was filed as "could not be weighed", a failure of the app dressed as a gap in the build.
 
-import type { RouteEntry } from '@ultimat3/render';
-import { enumeratePrerender } from '@ultimat3/render/server';
+import type { PrerenderEntry, RouteEntry } from '@ultimat3/render';
+import { enumeratePrerenderEntries } from '@ultimat3/render/server';
 import { quoteArg } from './shell-quote';
 import type { UnmeasuredRoute } from './static-report';
 
@@ -62,11 +62,19 @@ export const perRequestParams = (entry: RouteEntry): UnmeasuredRoute => ({
   weighable: false,
 });
 
-export async function measurePaths(entry: RouteEntry): Promise<MeasurePlan> {
+/**
+ * `enumerate` is where a dynamic route's pages come from: the build passes the one enumeration it
+ * shares with `siteSeo`'s entries, so a budgeted route's `prerender()` runs once per build, not once
+ * to weigh and again to list. Omitted, `prerender()` is asked here.
+ */
+export async function measurePaths(
+  entry: RouteEntry,
+  enumerate: (entry: RouteEntry) => Promise<readonly PrerenderEntry[]> = enumeratePrerenderEntries,
+): Promise<MeasurePlan> {
   if (entry.pattern.keys.length === 0) return { paths: [{ path: entry.path, params: {} }] };
   if (entry.config.render === 'ssr') return { unmeasured: perRequestParams(entry) };
   if (entry.config.prerender === undefined) return { unmeasured: paramsUndeclared(entry, false) };
-  const sets = await enumeratePrerender(entry);
+  const sets = (await enumerate(entry)).map((page) => page.params);
   if (sets.length === 0) return { unmeasured: paramsUndeclared(entry, true) };
   return {
     paths: sets.map((params) => ({ path: fillPath(entry.pattern.source, params), params })),

package/src/measure-scope.ts

@@ -17,16 +17,13 @@ export interface MeasureScope {
   run<T>(fn: () => T): T;
 }
 
-/**
- * The scope for `origin`. The pipeline is the app's API table and nothing else: a page's data
- * comes from its actions and queries, and a route the render reaches that is not one of them
- * answers 404 — which the render reports, and the route is filed unmeasured with that reason.
- */
-export async function measureScope(input: {
+/** A scope's in-process API: the app's own table, as `actor` — or, `null`, as nobody. */
+interface ScopeInput {
   readonly origin: string;
   readonly buildId: string;
-}): Promise<MeasureScope> {
-  const actor = await measurementActor();
+}
+
+function inProcessRunner(input: ScopeInput, actor: Actor | null): <T>(fn: () => T) => T {
   // No rate limit: every request here is this build's own render, and a limiter would need a
   // deployment scope a build does not have (`X_RATE_LIMIT_SCOPE_UNSET`).
   const config = defineHttpConfig({ buildId: input.buildId, rateLimit: { enabled: false } });
@@ -36,7 +33,7 @@ export async function measureScope(input: {
     role: 'web',
     config,
   });
-  ctx.actor = actor;
+  if (actor !== null) ctx.actor = actor;
   const pipeline = httpPipeline({
     table: httpRouter(apiRoutes()),
     config,
@@ -45,10 +42,27 @@ export async function measureScope(input: {
   const dispatch = (url: string, init: RequestInit): Promise<Response> =>
     pipeline.handle(new Request(url, init), { role: 'web' });
   const request: Ctx = ctx;
-  return {
-    actor,
-    run: <T>(fn: () => T): T => withInProcessFetch(dispatch, () => runWithContext(request, fn)),
-  };
+  return <T>(fn: () => T): T => withInProcessFetch(dispatch, () => runWithContext(request, fn));
+}
+
+/**
+ * The scope for `origin`. The pipeline is the app's API table and nothing else: a page's data
+ * comes from its actions and queries, and a route the render reaches that is not one of them
+ * answers 404 — which the render reports, and the route is filed unmeasured with that reason.
+ * For a render that is WEIGHED and discarded only: its output is never published.
+ */
+export async function measureScope(input: ScopeInput): Promise<MeasureScope> {
+  const actor = await measurementActor();
+  return { actor, run: inProcessRunner(input, actor) };
+}
+
+/**
+ * The same in-process API, authenticating NOBODY: what a read whose answer is PUBLISHED runs in —
+ * a `site/` route's `prerender()` (sitemap.xml) and an llms.txt page's `load`. Run as the
+ * measurement actor, those listed rows only that actor may read (a demo owner's drafts).
+ */
+export function publicScope(input: ScopeInput): <T>(fn: () => T) => T {
+  return inProcessRunner(input, null);
 }
 
 /**

package/src/messages-client.ts

@@ -0,0 +1,23 @@
+// The `x client`, `x graph` and `x impact` rows of the CLI catalog (`messages.ts` composes them):
+// what a generation wrote, what the app graph holds, what a change reaches. Data only.
+
+export const CLIENT_MESSAGES = {
+  'cli.client.vendor.written':
+    '{name}: {operations} operation(s), {types} type(s) compiled from {source} into {dir}',
+  'cli.client.customer.written':
+    '{operations} operation(s), {types} type(s) compiled from {source} into {dir}',
+  'cli.client.file': '  wrote {path}',
+  'cli.graph.summary': '{nodes} node(s), {edges} edge(s) ({provenance}); {opaque} opaque file(s)',
+  'cli.graph.kind': '  {kind}: {count}',
+  'cli.graph.path': '{from} → {to} in {steps} step(s)',
+  'cli.graph.pathStep': '  {from} —{rel} ({provenance})→ {to}',
+  'cli.graph.noPath': 'no known path between {from} and {to} (searched: {searched})',
+  'cli.impact.summary':
+    '{node} reaches {routes} route(s), {actions} action(s), {queries} query(ies), {jobs} job(s), {tests} test(s)',
+  'cli.impact.published':
+    '  published: {operations} — contract-diff will have an opinion about this change',
+  'cli.impact.section': '  {section}: {names}',
+  'cli.affected.tests': '{count} test file(s) in this app import a changed file, transitively',
+  'cli.affected.testsAll':
+    'every test file in this app: {files} changed and no import says who reads it',
+} as const;

package/src/messages-db.ts

@@ -0,0 +1,56 @@
+// The `x db` family's rows of the CLI catalog (`messages.ts` composes them): migrations, seeds,
+// backfills, branches, diagnostics. Data only — `msg()` is the one lookup.
+
+export const DB_MESSAGES = {
+  'cli.db.backfill.empty': 'no backfill has run against this database yet',
+  'cli.db.backfill.listed': '{count} backfill pass(es)',
+  /** The empty cell in a `x db backfill --list` column — a value, not a column key. */
+  'cli.db.backfill.none': '-',
+  'cli.db.backfill.pending': '{count} of {declared} declared backfill(s) never completed',
+  'cli.db.backfill.swept': 'every one of {declared} declared backfill(s) has completed',
+  // Every action counted, never derived: `count - enqueued` folded a deduped pass into "blocked",
+  // so the summary said blocked while `--json` said deduped for the same row — two renderers
+  // stating different facts about one run, which is the thing `--json` exists to make impossible.
+  'cli.db.backfill.planned':
+    '{count} backfill(s): {enqueued} enqueued, {deduped} already live, {blocked} blocked',
+  'cli.db.backfill.dryRun': '{count} backfill(s) would run — nothing written without --write',
+  'cli.db.branch.ready': 'branch {name} ready',
+  'cli.db.branch.dropped': 'branch {name} dropped',
+  'cli.db.branch.failed': 'branch command failed',
+  'cli.db.branch.listed': '{count} branch(es) of this database',
+  'cli.db.branch.none': 'this database has no branch',
+  /** The empty cell in an `x db branch list` column — a value, not a column key. */
+  'cli.db.branch.unknown': '-',
+  'cli.db.diagnostics.done': '{available} of {total} diagnostic section(s) answered',
+  'cli.db.recount.drift': '{target}: {count} row(s) drifted from the true count',
+  'cli.db.recount.repaired': '{target}: {count} row(s) set to the true count',
+  'cli.db.diagnostics.section': '{section}: {count} row(s)',
+  'cli.db.diagnostics.unavailable': '{section}: unavailable, {code} — {reason}  fix: {fix}',
+  'cli.db.gen.failed': 'migration not generated',
+  'cli.db.gen.unchanged': 'entities and migrations agree — nothing to generate',
+  'cli.db.gen.blocked':
+    'nothing was compared — the app did not load ({count} finding(s)); fix them, then run x db gen again',
+  // A THIRD outcome, and it is neither of the other two: nothing to generate, but the sidecar the
+  // `drift` step reads did move — an edit under `packages/db/src` that implies no DDL. Rendering it
+  // as `written` would name a migration nobody can apply; as `unchanged`, it would hide a file this
+  // command wrote. `GeneratedFiles.outcome` is what `--json` carries the same distinction on.
+  'cli.db.gen.recorded': 'no migration needed — schema hash re-recorded in {file}',
+  // The fourth: no DDL and no sidecar moved, but `packages/db/schema/` did — a hand edit repaired,
+  // or a framework table that changed under an upgrade. `unchanged` would deny a write the lines
+  // below it list, and this command is `X_SCHEMA_DUMP_DRIFT`'s whole `fix:`.
+  'cli.db.gen.dumped': 'no migration needed — schema dump rewritten ({count} file(s))',
+  'cli.db.gen.written': 'migration {id} generated',
+  // Exit 1 and a migration on disk at once: the summary carries the half the exit code hides.
+  'cli.db.gen.writtenDumpFailed':
+    'migration {id} generated and written — the schema dump was not; do not generate it again',
+  'cli.db.migrate.applied': 'migrations applied',
+  'cli.db.migrate.failed': 'migration failed',
+  'cli.db.reset.done': 'database reset and migrated',
+  // Every seed counted per outcome, exactly as the backfill summary is: a replayed seed writes
+  // nothing and skips everything, and a total that hid that would make the second run look idle.
+  'cli.db.seed.done':
+    '{count} seed(s): {inserted} inserted, {updated} updated, {skipped} already stored',
+  'cli.db.seed.dryRun': '{count} seed(s) would run — nothing written while --dry-run is set',
+  'cli.db.seed.failed': '{failed} of {count} seed(s) failed',
+  'cli.db.seed.none': 'no seed matched — nothing to run',
+} as const;

package/src/messages-gate.ts

@@ -0,0 +1,107 @@
+// The gate's rows of the CLI catalog (`messages.ts` composes them): `x verify`, `x ci`, `x pr`
+// and `x affected`. Data only — `msg()` is the one lookup.
+
+export const GATE_MESSAGES = {
+  'cli.affected.count':
+    '{count} workspace(s) affected by {base}...HEAD, from {changed} changed file(s)',
+  'cli.affected.dirty':
+    '  including the working tree (--dirty): every uncommitted change in this checkout, whoever made it',
+  'cli.affected.none': 'no workspace is affected by {base}...HEAD, from {changed} changed file(s)',
+  'cli.affected.rootWide':
+    '  every workspace: {files} belongs to none of them and changes what all of them compile',
+  'cli.ci.failed':
+    '{failed} of {runs} workflow run(s) on {branch} failed — {findings} finding(s) recovered from the log',
+  'cli.ci.green': 'every one of {runs} workflow run(s) on {branch} passed',
+  'cli.ci.job': '  {conclusion}  {job}  ({steps})',
+  'cli.ci.jobs.other': '  {count} other job(s) in this run',
+  'cli.ci.logs.empty': '  the failed step wrote no log — {url}',
+  /** The conclusion of a run GitHub has not finished — a value, not a column key. */
+  'cli.ci.pending': 'pending',
+  'cli.ci.run': '{conclusion}  {workflow}  {url}',
+  'cli.ci.running':
+    '{running} of {runs} workflow run(s) on {branch} has not finished — nothing has failed yet',
+  'cli.ci.tail': '  log tail, {job}:',
+  // `x ci tested`, one reason per condition (`TESTED_CONDITIONS`): what reused, or why it ran all.
+  'cli.ci.tested.tested':
+    'tested: PR #{pr} merged this tree, and {workflow} run {run} passed on its head — the jobs it ran are reused',
+  'cli.ci.tested.subject':
+    'not tested: the subject does not end (#N), so no pull request merged this commit — a full run',
+  'cli.ci.tested.merged': 'not tested: PR #{pr} was not merged as this commit — a full run',
+  'cli.ci.tested.fork':
+    "not tested: PR #{pr}'s head is not in {repo}, and a fork's run is never reused — a full run",
+  'cli.ci.tested.tree':
+    "not tested: this tree is not PR #{pr}'s head tree, so its base moved after the run — a full run",
+  'cli.ci.tested.run': "not tested: no green {workflow} run on PR #{pr}'s head — a full run",
+  'cli.ci.tested.stale':
+    'not tested: {workflow} run {run} for PR #{pr} is older than {maxAge} — a full run',
+  'cli.ci.tested.api': 'not tested: GitHub did not answer ({detail}) — a full run',
+  'cli.ci.tested.sha':
+    'not tested: no GITHUB_SHA, and git rev-parse HEAD named no commit — a full run',
+  'cli.pr.body.truncated': '      … {hidden} more line(s) — re-run with --full',
+  /** The line of a thread whose anchor GitHub answers null for — a value, not a column key. */
+  'cli.pr.line.unknown': '-',
+  'cli.pr.replied': 'replied on thread {id}: {url}',
+  // Resolving closes a CONVERSATION. Whether the finding is fixed is a fact about the code that
+  // no GitHub mutation observes, and a summary saying "addressed" would assert one from the other.
+  'cli.pr.resolved':
+    'thread {id} is marked resolved on GitHub — that records the conversation, not that the finding is fixed',
+  'cli.pr.review.count':
+    '{unresolved} unresolved and {resolved} resolved review thread(s) on {repo}#{pr}',
+  'cli.pr.review.current': '  submitted against the current head {head}',
+  'cli.pr.review.decision': '  review: {decision} by {author} at {submitted}',
+  'cli.pr.review.none': 'no review thread is anchored to a line on {repo}#{pr}',
+  'cli.pr.review.stale':
+    '  submitted against {commit}; the head is now {head} ({committed}) — this decision predates the current code',
+  'cli.pr.review.truncated':
+    '  more than {count} threads — this is the first page, not the whole review',
+  'cli.pr.review.undecided': '  GitHub reports no review decision yet',
+  'cli.pr.thread.closed': '  resolved    {path}:{line}  {id}',
+  'cli.pr.thread.comment': '    {author} at {createdAt}',
+  'cli.pr.thread.more': '    {hidden} more comment(s) on this thread',
+  'cli.pr.thread.open': '  unresolved  {path}:{line}  {id}',
+  'cli.pr.thread.outdated':
+    '    the diff has moved under this thread — {line} is where the comment was written',
+  // The banner a `--only` run carries, in front of whichever summary above it renders. Rendered
+  // output, so it lives here — `data.notAGateRun` is the machine marker, and a reader testing for
+  // one narrowed run reads that boolean rather than substring-matching this line.
+  'cli.verify.notAGateRun': 'NOT A GATE RUN — {summary}',
+  'cli.verify.pass': 'all {count} steps passed in {ms}ms',
+  'cli.verify.fail': '{failed} of {count} steps failed',
+  // The budgets step built before it weighed (`verify-budgets-build.ts`): which stats state made it.
+  'cli.verify.budgets.built':
+    'built first: build stats were {state} — x build --target static --out {out} ({ms}ms)',
+  // A skipped step is not a passed one, so the two counts never share a sentence — and the skipped
+  // ones are named, because "which suite has nothing to run here?" is the question a green gate
+  // over a missing suite has to answer on its own line. Whole sentences per case rather than a
+  // clause the caller glues on: a catalog clause cannot know the sentence it lands in.
+  'cli.verify.passSkipped':
+    '{passed} of {count} steps passed in {ms}ms — {skipped} skipped: {names}',
+  'cli.verify.failSkipped': '{failed} of {count} steps failed — {skipped} skipped: {names}',
+  // The `errors` step's own coverage, in `output`: a scan without a parser reads most fix lines
+  // and not all of them, and a step that reports findings alone claims a completeness it lacks.
+  'cli.verify.fixCoverage': 'checked {checked} fix line(s), could not read {unreadable}',
+  // Why a skipped step is a dash when the step can say so: the suite exists and not one of its
+  // tests ran. Each test's own name carries the reason it skipped, and `bun test` prints only the
+  // counts — so the line says how many and `x test <type>` prints the names.
+  'cli.verify.allSkipped': 'found {skipped} test(s) and every one skipped itself',
+  'cli.verify.warnings': '{count} warning(s) — --verbose or --json lists them',
+  'cli.verify.slowest': 'slowest: {files}',
+  'cli.verify.isrQueryOmitted':
+    '{file}: reads the query parameter "{name}", which revalidate.query does not list — the page is stored under a key without it, so every visitor gets the document rendered for whichever value arrived first. Declare query: [{declared}], or stop reading it',
+  // The other shape the same counts can take: a suite that reported no test at all, skipped ones
+  // included. Its own line and not `allSkipped` with a zero, because the repair differs — there is
+  // no skipped test to read a reason off, so the files the step selected hold no test.
+  'cli.verify.ranNothing': 'found no test to run in the file(s) it selected',
+  'cli.verify.merged': 'merged {parts} part(s) — {summary}',
+  // The heartbeat `verify-progress.ts` writes while a step is still running: `{steps}` is
+  // `unit (12m 3s), live (4m 0s)`, each step with the time since it started.
+  'cli.verify.stillRunning': 'still running: {steps}',
+  // The `unit` step's own measurement, in `output`: what the suite covered of the app's whole
+  // source tree, beside the floor it was held to. A shard says it measured a slice instead.
+  'cli.verify.coverage':
+    'coverage: {lines}% of lines, {funcs}% of functions over {files} source file(s) — floor {floor}',
+  'cli.verify.coverageDeferred':
+    'coverage: this shard measured its own slice — x verify merge folds every shard and judges the floor',
+  'cli.verify.serial': 'serial',
+  'cli.verify.workers': '{workers} workers',
+} as const;

package/src/messages-repro.ts

@@ -0,0 +1,11 @@
+// The `x repro` rows of the CLI catalog (`messages.ts` composes them). Data only — `msg()` is the
+// one lookup.
+
+export const REPRO_MESSAGES = {
+  'cli.repro.job': 'job {name} ({id}) died with {code} at step {step}',
+  'cli.repro.request': '{primitive} {name} answered {code} — fingerprint {fingerprint}',
+  'cli.repro.written': '  wrote {file}',
+  'cli.repro.reproduced': '  reproduced: {file} fails with {code}',
+  'cli.repro.notReproduced': '  not reproduced: {file} ended in {got}',
+  'cli.repro.listed': '{count} captured bundle(s)',
+} as const;

package/src/messages-shot.ts

@@ -0,0 +1,51 @@
+// The `x shot` rows of the CLI catalog (`messages.ts` composes them): capture, compare and the
+// verdict lines. Data only — `msg()` is the one lookup.
+
+export const SHOT_MESSAGES = {
+  // `x shot` — the picture is the `lines`, the verdict is the artifact. The summary names the
+  // GATING fact, and a redirect comes first: a photograph of the sign-in page with every island
+  // missing reads as a bug in the app, and it is a bug in the capture.
+  'cli.shot.ok': '{route} clean — {islands} island(s) mounted, nothing logged and nothing threw',
+  'cli.shot.errors': '{route}: {errors} console error(s) — verdict.json names each one',
+  'cli.shot.redirected': '{route} redirected to {url} — the picture is not the route asked for',
+  // After the redirect and before everything else: a 404 page can be spotless, and a picture of
+  // "Not found" read as the route is the capture lying about its subject.
+  'cli.shot.status':
+    '{route} answered HTTP {status}, expected {expected} — the picture is that response, not the page',
+  'cli.shot.document': '  document HTTP {status}',
+  'cli.shot.documentUnknown': '  document status not seen — the driver recorded no response for it',
+  'cli.shot.server.booted': '  server   booted for this shot on {url}',
+  'cli.shot.server.reused': '  server   the x dev already running on {url}',
+  'cli.shot.canvas': '  canvas   {width}x{height}',
+  'cli.shot.canvasUnreadable': '  canvas   unreadable — {bytes} byte(s), not a decodable image',
+  'cli.shot.islands': '  islands  {booted} of {declared} mounted ({strategies})',
+  'cli.shot.islandsUnknown': '  islands  not counted — the page answered no probe',
+  // The failure a picture cannot show and a console count cannot see: a rejected mount promise
+  // calls no console method, so the FIRST one is named here rather than left to verdict.json.
+  'cli.shot.islandFailed': '{route}: {failed} island(s) failed to mount — {island}: {message}',
+  'cli.shot.network': '  network  {requests} request(s), {refused} refused, {dropped} dropped',
+  'cli.shot.console': '  console  {level}: {text}',
+  'cli.shot.threw': '{route}: {thrown} uncaught exception(s) — {first}',
+  'cli.shot.pageError': '  threw    {message}  {at}',
+  'cli.shot.picture': '  picture  {path}',
+  'cli.shot.verdict': '  verdict  {path}',
+  // `--viewport`: one route at several sizes. The summary is ONE size's verdict, so it says which
+  // size; each size line leads with its size and the per-size detail lines sit indented beneath.
+  'cli.shot.viewport.summary': '{size}: {summary}',
+  'cli.shot.viewport.line': '{size}  {summary}',
+  // `--island`. A component capture reports per STATE, so the summary counts pictures and the
+  // lines name one state each; nothing here restates a fact `--json` does not carry.
+  'cli.shot.island.ok':
+    '{island} clean — {pictures} picture(s), every one mounted, nothing logged and nothing threw',
+  'cli.shot.island.failed':
+    '{island}: {taken} of {expected} declared picture(s) taken — verdict.json names each refusal',
+  'cli.shot.island.state': '  {state}  {theme}  {width}x{height}  {file}',
+  'cli.shot.island.missing': '  missing  {file} — no picture was taken for this declared state',
+  'cli.shot.island.picture': '  pictures {path}',
+  'cli.shot.island.verdict': '  verdict  {path}',
+  'cli.shot.island.index': '  index    {path}',
+  'cli.shot.island.blind.crop':
+    "the picture is the crop target and a thin margin around it — anything further out, including the space a component's own fault sits in, is outside the frame; content that overflows the box is recorded per state as overflow, never shown",
+  'cli.shot.island.blind.locale':
+    'toLocaleString() on a Date resolves its zone inside the engine — only an explicit timeZone is pinned by this harness',
+} as const;

package/src/messages-upgrade.ts

@@ -0,0 +1,45 @@
+// The `x upgrade` rows of the CLI catalog (`messages.ts` composes them): the hop walk, its stages
+// and its `then:` lines. Data only — `msg()` is the one lookup.
+
+export const UPGRADE_MESSAGES = {
+  'cli.upgrade.atLatest': 'already at {version}, the newest release',
+  'cli.upgrade.atTarget': 'already at {version}; {next} is the next release',
+  'cli.upgrade.noApp.done':
+    '{from} -> {to}: no app.config.ts, so no x verify ran; {count} script(s) passed',
+  'cli.upgrade.noApp.none':
+    '{from} -> {to}: nothing checked: no app.config.ts, and no typecheck or test script',
+  'cli.upgrade.noApp.red': '{from} -> {to}: no app.config.ts, and a script failed: {names}',
+  'cli.upgrade.scriptRed': 'failed, re-run it: bun run {name}',
+  'cli.upgrade.then.atTarget':
+    'nothing to do at {version}; a bare x upgrade --json takes the next release, {next}',
+  'cli.upgrade.then.dryRunNoApp':
+    'no app.config.ts, so on a clean tree x upgrade --json moves the pins and runs {scripts} in place of x verify',
+  'cli.upgrade.then.noProof':
+    'nothing checked this hop: confirm {to} works by hand, commit it, then re-run x upgrade --json for the next one',
+  'cli.upgrade.then.scriptsGreen':
+    'the scripts passed, which is less than x verify would say: review the diff, commit this hop to {to}, then re-run x upgrade --json for the next one',
+  'cli.upgrade.then.scriptsRed':
+    'read the section, make each failed script pass, commit this hop to {to}, then re-run x upgrade --json for the next one',
+  'cli.upgrade.agentsMd.link':
+    'AGENTS.md: byte-identical to CLAUDE.md, so this hop makes it a symlink to it',
+  'cli.upgrade.agentsMd.differs':
+    'AGENTS.md: differs from CLAUDE.md, left alone. Merge what only AGENTS.md says into CLAUDE.md, then: ln -sf CLAUDE.md AGENTS.md',
+  'cli.upgrade.bunEdited': 'bun floor: {path} {from} -> {to}',
+  'cli.upgrade.bunManual': 'bun floor, by hand: {path}:{line} — {why}',
+  'cli.upgrade.done': '{from} -> {to}: the gate is green',
+  'cli.upgrade.dryRun': '{from} -> {to}: nothing written, no gate run',
+  'cli.upgrade.guard': 'guard, yours to take or leave: {fix}',
+  'cli.upgrade.read': 'read: {title} — {url}',
+  'cli.upgrade.red': '{from} -> {to}: not done, the gate says: {summary}',
+  'cli.upgrade.stillRunning': 'x upgrade: still in {stage} ({elapsed})',
+  'cli.upgrade.then': 'then: {then}',
+  'cli.upgrade.then.atLatest':
+    'nothing to do: this app is on {version}, and no newer release is published',
+  'cli.upgrade.then.dryRun': 'on a clean tree, run the hop: x upgrade --json',
+  'cli.upgrade.then.last':
+    'review the diff and commit this hop to {to}: it is the newest release, so the walk is over',
+  'cli.upgrade.then.red':
+    'read the section, close each finding by its fix, re-check with x verify --json, commit this hop to {to}, then re-run x upgrade --json for the next one',
+  'cli.upgrade.then.walk':
+    'review the diff and commit this hop to {to}, then re-run x upgrade --json to take the next one, {next}',
+} as const;