@ultimat3/cli 1.0.0

package/src/mcp-host.ts

@@ -0,0 +1,282 @@
+// The `DevCapabilities` half of `@ultimat3/mcp`'s `DevHost`: the shell-side facts no registry
+// holds — a database to query, a migrator, a test runner, the dev log, the committed manifest and
+// the gate. The description half is the framework's own `frameworkIntrospection`, so nothing here
+// is a second catalog of routes, entities, actions, queries or jobs.
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { agentActor, UltimateError } from '@ultimat3/core';
+import type { DbClient } from '@ultimat3/db';
+import { ensureReadOnlyRole, readLedger, readOnlyQuery } from '@ultimat3/db';
+import { inspectJobList, inspectQueues } from '@ultimat3/jobs';
+import { MANIFEST_FILENAME } from '@ultimat3/manifest';
+import type {
+  DevCapabilities,
+  McpCaller,
+  McpServer,
+  QueryLimits,
+  QueryRows,
+  VerifyResult,
+  VerifyStep,
+} from '@ultimat3/mcp';
+import { createDevServer, DEV_SCOPES, devHost, frameworkIntrospection } from '@ultimat3/mcp';
+import { describeRoutes } from '@ultimat3/render';
+import { loadApp } from './app-load';
+import { appManifest, policyFacts } from './app-manifest';
+import { runVerify, VERIFY_STEPS } from './cmd-verify';
+import type { RunningServices } from './dev-runtime';
+import { startServices } from './dev-runtime';
+import type { DevServices, Env } from './dev-services';
+import { resolveServices } from './dev-services';
+import { MIGRATIONS_DIR } from './drift';
+import { CliNotImplementedError } from './errors';
+import type { Runner } from './exec';
+import { execOutput } from './exec';
+import { databaseTarget } from './mcp-db-target';
+import { explainErrorCode } from './mcp-errors';
+import { parseBunTest } from './mcp-test-output';
+
+export interface DevHostInput {
+  readonly root: string;
+  readonly env: Env;
+  readonly runner: Runner;
+}
+
+export interface CliMcpServer {
+  readonly server: McpServer;
+  readonly caller: McpCaller;
+  /** Tool names this caller can see, sorted. The catalog `x mcp tools` prints. */
+  readonly tools: readonly string[];
+  close(): Promise<void>;
+}
+
+/** Every dev scope. Both transports resolve to this set — one surface, one entitlement. */
+export const DEV_TOOL_SCOPES: ReadonlySet<string> = new Set(Object.values(DEV_SCOPES));
+
+/**
+ * The developer's own shell. A stdio peer already owns the process, so there is no network
+ * boundary to defend and the caller carries every dev scope. `kind: 'agent'` because
+ * `transport-http.ts` structurally refuses anything else and both transports must resolve to the
+ * same caller — an MCP call is an agent call, never the human behind it.
+ */
+export function localCaller(): McpCaller {
+  return {
+    actor: agentActor({ id: 'x-cli', scopes: [...DEV_TOOL_SCOPES] }),
+    scopes: DEV_TOOL_SCOPES,
+  };
+}
+
+// ── the lazily booted services ───────────────────────────────────────────────
+
+export interface LazyServices {
+  readonly services: DevServices;
+  running(): Promise<RunningServices>;
+  close(): Promise<void>;
+}
+
+/**
+ * The database boots on FIRST USE, once, and is shared: answering `routes.list` must not pay a
+ * PGlite boot. Same resolver and same drivers as `x dev` — a dev-only second driver is exactly the
+ * bug that design exists to prevent. Exported as the boot seam a test can drive without a server.
+ */
+export function lazyServices(input: DevHostInput): LazyServices {
+  const services = resolveServices(input.root, input.env);
+  let started: Promise<RunningServices> | undefined;
+  let closed = false;
+  return {
+    services,
+    running(): Promise<RunningServices> {
+      // A boot started after close() would hold the PGlite data directory for the life of the
+      // process with nobody left to stop it — the host is closed, so the call is the bug.
+      if (closed) {
+        throw new CliNotImplementedError({
+          feature: 'an MCP tool that needs the database after the host closed',
+          fix: 'x mcp serve --transport stdio   # keep the host open for the whole session',
+        });
+      }
+      started ??= startServices(services, input.env);
+      return started;
+    },
+    async close(): Promise<void> {
+      if (closed) return;
+      closed = true;
+      // A boot that rejected has nothing to stop, and close() must not throw on the way out.
+      await (await started?.catch(() => undefined))?.stop();
+    },
+  };
+}
+
+/** Migration ids on disk (`0001_init.sql` → `0001_init`) that the ledger does not record. */
+async function pendingMigrations(root: string, lazy: LazyServices): Promise<readonly string[]> {
+  const dir = join(root, MIGRATIONS_DIR);
+  if (!existsSync(dir)) return [];
+  const ids: string[] = [];
+  for await (const file of new Bun.Glob('*.sql').scan({ cwd: dir, absolute: false })) {
+    if (!file.endsWith('.down.sql')) ids.push(file.replace(/\.sql$/, ''));
+  }
+  const { db } = await lazy.running();
+  // No ledger table means nothing has been applied. `ensureLedger` would create it, and a dry run
+  // is not allowed to write.
+  const ledger = await readLedger(db).catch(() => []);
+  const applied = new Set(ledger.map((row) => row.id));
+  return ids.filter((id) => !applied.has(id)).sort();
+}
+
+// ── the capabilities ─────────────────────────────────────────────────────────
+
+/**
+ * `db.query`'s layers 1–2 against a real client: a SELECT-only role assumed inside a
+ * `BEGIN READ ONLY` transaction with a statement timeout, then the rows shaped into the tool's
+ * column-major form. Layer 3 (`assertReadOnlyQuery`) and layer 4 (the caps) run in the tool,
+ * before and after this — a second copy here would be a second place to keep right.
+ *
+ * Exported as the seam a test drives with a recording client, so the statement sequence is
+ * asserted without booting a database.
+ */
+export async function readOnlyRows(
+  db: DbClient,
+  sql: string,
+  limits: QueryLimits,
+  role: string | null,
+): Promise<QueryRows> {
+  const { rows, guards } = await readOnlyQuery<Record<string, unknown>>(sql, {
+    client: db,
+    role,
+    timeoutMs: limits.timeoutMs,
+    // One row past the ceiling: the tool needs to know there was more. Asked of the *server*,
+    // through the cursor the pinned read-only transaction already makes available, so a
+    // `select * from events` cannot be paged into this process before layer 4 gets to drop it.
+    // Wrapping the statement in `select * from (…) limit n` instead would change the meaning of
+    // a statement carrying its own LIMIT and fail outright on `EXPLAIN` and `SHOW`.
+    maxRows: limits.maxRows + 1,
+  });
+  const columns = Object.keys(rows[0] ?? {});
+  // `EXPLAIN` and `SHOW` are commands, not cursorable, so they arrive whole — the slice is the
+  // only bound they have.
+  const kept = rows.slice(0, limits.maxRows + 1);
+  return { columns, rows: kept.map((row) => columns.map((column) => row[column])), guards };
+}
+
+function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities {
+  const { root, runner } = input;
+  // Layer 1 is seven idempotent DDL statements, and `db.query` is a tool an agent calls in a
+  // loop — resolve the role once per process and reuse the answer, `null` included.
+  let readOnlyRole: Promise<string | null> | undefined;
+
+  return {
+    database: databaseTarget(lazy.services),
+
+    async runQuery(sql: string, limits: QueryLimits): Promise<QueryRows> {
+      const { db } = await lazy.running();
+      // A managed Postgres may refuse CREATE ROLE; `ensureReadOnlyRole` answers null and the
+      // layer is reported absent in `guards` rather than quietly assumed present.
+      readOnlyRole ??= ensureReadOnlyRole(db);
+      return readOnlyRows(db, sql, limits, await readOnlyRole);
+    },
+
+    async runMigrations(branch: string, dryRun: boolean) {
+      const before = await pendingMigrations(root, lazy);
+      if (dryRun) return { branch, applied: [], pending: before };
+      const result = await runner(['bunx', 'drizzle-kit', 'migrate'], { cwd: root });
+      if (!result.ok) {
+        // Thrown, not returned: `server.ts` renders any X_* error as the three-line
+        // code/cause/fix result, which is what an agent needs to act without a round trip.
+        throw new UltimateError({
+          code: 'X_DB_MIGRATE_FAILED',
+          cause: `${result.command.join(' ')} exited ${result.code}: ${execOutput(result).slice(0, 400)}`,
+          fix: 'x db reset',
+        });
+      }
+      // The ledger is the evidence for "applied" — never the migrator's own stdout.
+      const pending = await pendingMigrations(root, lazy);
+      return { branch, applied: before.filter((id) => !pending.includes(id)), pending };
+    },
+
+    async queueDepth() {
+      const { jobs } = await lazy.running();
+      const report = await inspectQueues(jobs);
+      // `stats()` counts states, and a job is `failed` only until it is retried or dead-lettered;
+      // the honest count comes from the job list. Same reading as /_x's queues panel.
+      const failed =
+        jobs.introspect === undefined ? [] : await inspectJobList(jobs, { state: 'failed' });
+      return report.queues.map((queue) => ({
+        queue: queue.queue,
+        pending: queue.ready + queue.delayed,
+        running: queue.running,
+        failed: failed.filter((record) => record.queue === queue.queue).length,
+      }));
+    },
+
+    // `bun test <filter>` matches on the test path, the same rule `x test`'s `discoverTests` uses.
+    async runTests(filter: string | undefined) {
+      const result = await runner(
+        filter === undefined ? ['bun', 'test'] : ['bun', 'test', filter],
+        {
+          cwd: root,
+        },
+      );
+      return parseBunTest(execOutput(result), result.durationMs);
+    },
+
+    async tailLogs(lines: number, role: string | undefined) {
+      const dir = lazy.services.stateDir;
+      const path = role === undefined ? join(dir, 'dev.log') : join(dir, 'logs', `${role}.log`);
+      const file = Bun.file(path);
+      if (!(await file.exists())) {
+        // `@ultimat3/core`'s `logger` is a module const with no sink seam, so there is nothing to
+        // intercept in-process — a log on disk is the only honest source, and the fix creates one.
+        throw new CliNotImplementedError({
+          feature: `logs.tail without ${path}`,
+          fix:
+            role === undefined
+              ? `x dev > ${path} 2>&1`
+              : `mkdir -p ${join(dir, 'logs')} && x dev --role ${role} > ${path} 2>&1`,
+        });
+      }
+      return (await file.text()).trimEnd().split('\n').slice(-lines);
+    },
+
+    async readManifest() {
+      const file = Bun.file(join(root, MANIFEST_FILENAME));
+      // The contract is "the generated manifest as text", so an app that has never run
+      // `x manifest` gets the current one rather than a failure.
+      if (await file.exists()) return file.text();
+      return JSON.stringify((await appManifest(root)).manifest, null, 2);
+    },
+
+    explainError: explainErrorCode,
+
+    async verify(fix: boolean): Promise<VerifyResult> {
+      // The one safe autofix this repo actually has. Anything more would be the gate rewriting
+      // code it was asked to judge.
+      if (fix) await runner(['bunx', 'biome', 'check', '--write', '.'], { cwd: root });
+      const result = await runVerify(VERIFY_STEPS, { root, runner });
+      return {
+        ok: result.ok,
+        steps: (result.steps ?? []).map((step): VerifyStep => {
+          const detail = step.findings[0]?.cause;
+          // exactOptionalPropertyTypes: omit `detail`, never hand over an explicit undefined.
+          return detail === undefined
+            ? { name: step.name, ok: step.ok }
+            : { name: step.name, ok: step.ok, detail };
+        }),
+      };
+    },
+  };
+}
+
+/**
+ * Loading the app IS the registration, so it happens before the server is built: every
+ * introspection tool then answers from the framework's own registries, not from a scan.
+ */
+export async function createDevMcpServer(input: DevHostInput): Promise<CliMcpServer> {
+  await loadApp(input.root);
+  const lazy = lazyServices(input);
+  const introspection = frameworkIntrospection({
+    routes: () => describeRoutes(),
+    policies: () => policyFacts(),
+  });
+  const server = createDevServer({ host: devHost(introspection, capabilities(input, lazy)) });
+  const caller = localCaller();
+  return { server, caller, tools: server.tools.names(caller), close: () => lazy.close() };
+}

package/src/mcp-test-output.ts

@@ -0,0 +1,57 @@
+// Reading `bun test`'s own summary back into a `TestRun`. Separate from the host because it is a
+// pure string reader with no services behind it — and because the one thing it must never do,
+// report a crashed runner as a green run, is worth pinning on its own.
+
+import type { TestRun } from '@ultimat3/mcp';
+
+const TAIL_LINES = 20;
+const FAIL_LINE = /^\(fail\)\s+(.*?)(?:\s+\[[\d.]+\s*m?s\])?$/;
+const ERROR_LINE = /^\s*error:\s*(.+)$/;
+
+const lastCount = (output: string, label: string): number | undefined => {
+  const last = [...output.matchAll(new RegExp(`^\\s*(\\d+)\\s+${label}\\b`, 'gm'))].at(-1);
+  return last === undefined ? undefined : Number.parseInt(last[1] ?? '0', 10);
+};
+
+const tailOf = (output: string): string => {
+  const lines = output.split('\n').filter((line) => line.trim().length > 0);
+  return lines.length === 0 ? 'bun test produced no output' : lines.slice(-TAIL_LINES).join('\n');
+};
+
+/**
+ * Bun prints its own summary, so this reads it instead of counting anything a second time. Output
+ * it cannot recognise is reported as a FAILED run carrying the raw tail: returning zeros there
+ * would turn a runner that crashed before it started into a green run.
+ */
+export function parseBunTest(output: string, durationMs: number): TestRun {
+  const passed = lastCount(output, 'pass');
+  const failed = lastCount(output, 'fail');
+  if (passed === undefined && failed === undefined) {
+    const failure = { test: 'bun test', message: tailOf(output) };
+    return { passed: 0, failed: 1, skipped: 0, durationMs, failures: [failure] };
+  }
+  const failures: { test: string; message: string }[] = [];
+  let message = '';
+  for (const line of output.split('\n')) {
+    const error = ERROR_LINE.exec(line);
+    if (error !== null) {
+      message = error[1] ?? '';
+      continue;
+    }
+    const fail = FAIL_LINE.exec(line.trimEnd());
+    if (fail === null) continue;
+    failures.push({
+      test: (fail[1] ?? '').trim(),
+      message: message === '' ? 'no error message in the run output' : message,
+    });
+    message = '';
+  }
+  return {
+    passed: passed ?? 0,
+    failed: failed ?? 0,
+    // `skip` and `todo` print on separate lines and both mean "not run".
+    skipped: (lastCount(output, 'skip') ?? 0) + (lastCount(output, 'todo') ?? 0),
+    durationMs,
+    failures,
+  };
+}

package/src/messages.ts

@@ -0,0 +1,119 @@
+// The CLI's own flat message catalog. The CLI must render errors before an app (and therefore
+// an app's i18n runtime) exists — `x new` and `x doctor` run outside any app — so it owns a
+// built-in catalog in the same flat-key/loud-miss shape as @ultimat3/i18n instead of importing
+// one. Missing keys render as ⟦key⟧, never as English fallback.
+
+const CATALOG = {
+  'cli.tagline': 'Ultimate — one command means shippable',
+  'cli.usage': 'usage: x <command> [options]',
+  'cli.hint.help': 'run `x help <command>` for details, add --json to any command',
+  'cli.flags.heading': 'flags',
+  'cli.commands.heading': 'commands',
+  'cli.build.done': 'built {target}',
+  // `describeCron`'s vocabulary. `@ultimat3/time` is tier 1 and reaches no i18n runtime, so the
+  // caller supplies the words — and the caller here is a rendered `x tasks show` line, which is
+  // exactly what this catalog holds. `msg()` leaves an un-supplied `{n}`/`{time}`/`{days}`/
+  // `{months}` intact, so each value arrives at `describeCron` as the template it interpolates.
+  'cli.cron.andMore': 'and {n} more',
+  'cli.cron.at': 'at {time}',
+  'cli.cron.everyDay': 'every day',
+  'cli.cron.everyHour': 'every hour',
+  'cli.cron.everyMinute': 'every minute',
+  'cli.cron.everyNHours': 'every {n} hours',
+  'cli.cron.everyNMinutes': 'every {n} minutes',
+  'cli.cron.inMonths': 'in {months}',
+  'cli.cron.onDaysOfMonth': 'on day {days} of the month',
+  'cli.cron.onWeekdays': 'on {days}',
+  'cli.db.branch.ready': 'branch {name} ready',
+  'cli.dev.ready': 'dev ready on {url} — /_x mounted ({panels} panels), {services}',
+  // The mail and CDN halves of that boot line. Rendered text, so it lives here — while
+  // `describeMail`/`describeCdn` keep the same wording as the fixed vocabulary `x dev --json`
+  // carries, and `dev-runtime.test.ts` pins the two together so neither can drift alone.
+  'cli.dev.cdn.external': 'cdn=external({driver} via {detail})',
+  'cli.dev.cdn.none': 'cdn=none',
+  'cli.dev.mail.embedded': 'mail=embedded',
+  'cli.dev.mail.external': 'mail=external({driver} via {detail})',
+  'cli.dev.hmr': 'reloaded {file} in {ms}ms',
+  'cli.dev.roles': '  roles {roles}',
+  'cli.dev.panels': '  panels {panels}',
+  'cli.dev.introspect': '  introspect {url}',
+  'cli.dev.manifest': '  manifest {path}',
+  'cli.deploy.plan': 'containers only: {images} image, roles {roles}',
+  'cli.doctor.clean': 'no findings — environment is shippable',
+  'cli.doctor.findings': '{count} finding(s)',
+  'cli.errors.count': '{count} registered error code(s)',
+  'cli.errors.explained': '{code} — {title}',
+  'cli.fix.clean': 'no boundary violation involves {file}',
+  'cli.fix.plan': '{count} boundary violation(s) involve {file} — {edits} edit(s) to make',
+  'cli.generate.wrote': 'wrote {count} file(s) for {kind} {name}',
+  'cli.i18n.added': 'added {locale} — {keys} key(s) seeded from {from}',
+  'cli.i18n.dynamic': '{count} dynamic t() call(s) the extractor cannot verify:',
+  'cli.i18n.gaps': '{missing} missing key(s) across {locales} locale(s)',
+  'cli.i18n.ok': '{locales} locale(s), {keys} key(s) used — no gaps',
+  'cli.i18n.synced': 'synced {locale} from {from} — {added} key(s) added, {total} total',
+  'cli.i18n.unused': '{count} key(s) defined in {locale} and never used:',
+  'cli.jobs.deadLetters': '{count} dead letter(s):',
+  'cli.jobs.depth':
+    '{ready} ready · {running} running · {delayed} delayed · {dead} dead across {queues} queue(s)',
+  'cli.jobs.drained': 'drained {count} job(s) from {from} to {to}',
+  'cli.jobs.drainedPartial':
+    'drained {count} job(s) from {from} to {to} — {skipped} left on {from}',
+  'cli.jobs.listed': '{count} job(s)',
+  'cli.jobs.noError': 'no error recorded',
+  'cli.jobs.retried': 'job {id} re-queued — {state}',
+  'cli.jobs.shown': 'job {id} — {state}, attempt {attempt} of {attempts}',
+  'cli.jobs.skipped': '{count} job(s) left on {from} — re-run the drain once each is claimable:',
+  'cli.manifest.blocked': 'manifest not written — {count} module(s) did not load',
+  'cli.manifest.fresh': 'manifest is fresh',
+  'cli.manifest.stale': 'manifest is stale',
+  'cli.manifest.wrote': 'manifest written to {path} ({routes} routes, {actions} actions)',
+  'cli.mcp.serving': 'mcp {transport} serving {tools} tools',
+  'cli.mcp.scopes': '  scopes {scopes}',
+  'cli.new.done': 'created {name} — next: cd {name} && x dev',
+  'cli.policy.count':
+    '{permissions} permission(s), {roles} role(s), {enforced} enforced by a declaration',
+  // One row per (declaration, actor) pair, never per role: a permission two declarations enforce
+  // evaluates every actor twice, so "of N role(s)" over-counted whenever it had more than one.
+  'cli.policy.explained': '{subject} — allowed for {allowed} of {evaluations} actor evaluation(s)',
+  'cli.policy.allow': 'allow',
+  'cli.policy.deny': 'deny',
+  'cli.policy.declaration': '{kind} {name} — policy {label}',
+  /** The empty cell in a `x policy list` column — a value, not a column key. */
+  'cli.policy.none': '-',
+  'cli.policy.noInput':
+    'evaluated with no request input and no row — a rule reading either decides again on the real request',
+  'cli.policy.undecidable': 'not decidable outside a request — this policy reads request input',
+  'cli.policy.unenforced': '{count} permission(s) no action or query enforces:',
+  'cli.registry.count': '{count} {kind}',
+  'cli.registry.described': '{kind} {name}',
+  'cli.routes.count': '{count} routes',
+  'cli.routes.empty': 'no routes in the manifest — run `x manifest` first',
+  'cli.tasks.count': '{count} task(s)',
+  'cli.tasks.shown': '{name} — {cron} ({tz}), next {next}',
+  'cli.test.fail': '{failed} of {workers} shard(s) failed',
+  'cli.test.pass': '{files} test file(s) on {workers} worker(s) passed in {ms}ms',
+  'cli.test.sampled': 'sampled {kept} of {total} {type} file(s)',
+  'cli.test.type.fail': '{type} — {failed} of {workers} shard(s) failed',
+  'cli.test.type.pass': '{type} — {files} test file(s) on {workers} worker(s) passed in {ms}ms',
+  'cli.verify.pass': 'all {count} steps passed in {ms}ms',
+  'cli.verify.fail': '{failed} of {count} steps failed',
+} as const;
+
+export type MessageKey = keyof typeof CATALOG;
+
+export type MessageParams = Readonly<Record<string, string | number>>;
+
+/**
+ * Look up a message and interpolate `{name}` placeholders. An unknown key renders `⟦key⟧` so a
+ * miss is visible in the terminal and in `--json`, never silently papered over.
+ */
+export function msg(key: MessageKey | string, params: MessageParams = {}): string {
+  const template: string | undefined = (CATALOG as Record<string, string>)[key];
+  if (template === undefined) return `⟦${key}⟧`;
+  return template.replace(/\{(\w+)\}/g, (whole, name: string) => {
+    const value = params[name];
+    return value === undefined ? whole : String(value);
+  });
+}
+
+export const messageKeys = (): readonly string[] => Object.keys(CATALOG);

package/src/output.ts

@@ -0,0 +1,174 @@
+// One data shape, two renderers. Every command returns a `CommandResult`; the human renderer
+// and the JSON renderer are projections of it, so `--json` can never drift from the terminal
+// output (axiom 4). The human renderer owns the canonical 3-line error format.
+
+export interface Finding {
+  readonly code: string;
+  readonly cause: string;
+  readonly fix: string;
+  readonly docs?: string;
+  /** Optional locator: a file, route, or table the finding is about. */
+  readonly at?: string;
+}
+
+export interface StepResult {
+  readonly name: string;
+  readonly ok: boolean;
+  readonly durationMs: number;
+  readonly skipped?: boolean;
+  readonly findings: readonly Finding[];
+  /** Captured stdout/stderr, shown on failure or with --verbose. */
+  readonly output?: string;
+}
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+export interface CommandResult {
+  readonly ok: boolean;
+  readonly command: string;
+  /** One line, already localized through `msg()`. */
+  readonly summary: string;
+  readonly steps?: readonly StepResult[];
+  readonly findings?: readonly Finding[];
+  readonly data?: JsonValue;
+  /** Extra human-only lines (tables, file lists). Never carries data JSON does not have. */
+  readonly lines?: readonly string[];
+  readonly exitCode?: number;
+  /**
+   * A long-running command's "still running" handle: `dispatch` renders the result — the command
+   * has already reported that it is up — and then awaits this before the process exits. Neither
+   * renderer carries it, because it is behaviour rather than a fact, and a fact only one of them
+   * could show is how the two drift.
+   */
+  readonly hold?: () => Promise<void>;
+}
+
+export interface UltimateErrorShape {
+  readonly code: string;
+  readonly cause: string;
+  readonly fix: string;
+  readonly docs?: string;
+  readonly message: string;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * Structural check, deliberately not `instanceof`: an error may cross a subprocess or worker
+ * boundary and arrive as a plain object, and the renderer must still produce the fix line.
+ */
+export function isUltimateErrorShape(value: unknown): value is UltimateErrorShape {
+  if (!isRecord(value)) return false;
+  return (
+    typeof value['code'] === 'string' &&
+    value['code'].startsWith('X_') &&
+    typeof value['cause'] === 'string' &&
+    typeof value['fix'] === 'string'
+  );
+}
+
+export function findingFrom(value: unknown): Finding {
+  if (isUltimateErrorShape(value)) {
+    const docs = value.docs;
+    return docs === undefined
+      ? { code: value.code, cause: value.cause, fix: value.fix }
+      : { code: value.code, cause: value.cause, fix: value.fix, docs };
+  }
+  const cause = value instanceof Error ? value.message : String(value);
+  return {
+    code: 'X_CLI_UNEXPECTED',
+    cause,
+    fix: 'x doctor --json',
+    docs: 'https://ultimate.dev/errors/X_CLI_UNEXPECTED',
+  };
+}
+
+const summaryOf = (value: UltimateErrorShape): string =>
+  value.message.length > 0 && value.message !== value.code ? value.message : '';
+
+/**
+ * The 3-line contract format. Identical bytes in the terminal, the browser overlay and CI logs:
+ *
+ * ```
+ * X_DB_DRIFT: schema differs from migrations
+ *   cause: table "posts" has column "publish_at" not present in any migration
+ *   fix:   x db gen "add publish_at"
+ * ```
+ */
+export function renderFinding(finding: Finding, indent = ''): string {
+  const head = finding.at === undefined ? finding.code : `${finding.code} (${finding.at})`;
+  const lines = [
+    `${indent}${head}`,
+    `${indent}  cause: ${finding.cause}`,
+    `${indent}  fix:   ${finding.fix}`,
+  ];
+  if (finding.docs !== undefined) lines.push(`${indent}  docs:  ${finding.docs}`);
+  return lines.join('\n');
+}
+
+/** Same format, but titled with the error's own summary line when it has one. */
+export function renderUltimateError(error: UltimateErrorShape, indent = ''): string {
+  const summary = summaryOf(error);
+  const head = summary === '' ? error.code : `${error.code}: ${summary}`;
+  const docs = error.docs;
+  const finding: Finding =
+    docs === undefined
+      ? { code: head, cause: error.cause, fix: error.fix }
+      : { code: head, cause: error.cause, fix: error.fix, docs };
+  return renderFinding(finding, indent);
+}
+
+const mark = (step: StepResult): string => {
+  if (step.skipped === true) return '-';
+  return step.ok ? '✓' : '✗';
+};
+
+export function renderHuman(result: CommandResult, verbose = false): string {
+  const out: string[] = [];
+  for (const step of result.steps ?? []) {
+    out.push(`  ${mark(step)} ${step.name.padEnd(18)} ${step.durationMs}ms`);
+    for (const finding of step.findings) out.push(renderFinding(finding, '      '));
+    if (step.output !== undefined && step.output.length > 0 && (verbose || !step.ok)) {
+      for (const line of step.output.trimEnd().split('\n')) out.push(`      | ${line}`);
+    }
+  }
+  for (const line of result.lines ?? []) out.push(line);
+  for (const finding of result.findings ?? []) out.push(renderFinding(finding, '  '));
+  out.push(`${result.ok ? '✓' : '✗'} ${result.summary}`);
+  return out.join('\n');
+}
+
+export function renderJson(result: CommandResult): string {
+  const steps = (result.steps ?? []).map((step) => ({
+    name: step.name,
+    ok: step.ok,
+    durationMs: step.durationMs,
+    skipped: step.skipped === true,
+    findings: step.findings,
+  }));
+  const payload = {
+    ok: result.ok,
+    command: result.command,
+    summary: result.summary,
+    ...(result.steps === undefined ? {} : { steps }),
+    ...(result.findings === undefined ? {} : { findings: result.findings }),
+    ...(result.data === undefined ? {} : { data: result.data }),
+  };
+  return JSON.stringify(payload);
+}
+
+export function render(result: CommandResult, json: boolean, verbose = false): string {
+  return json ? renderJson(result) : renderHuman(result, verbose);
+}
+
+export function exitCodeFor(result: CommandResult): number {
+  if (result.exitCode !== undefined) return result.exitCode;
+  return result.ok ? 0 : 1;
+}