@ultimat3/cli 6.0.0 → 8.0.0

package/src/i18n-registration.ts

@@ -12,6 +12,7 @@ import {
   catalogRegistrationGaps,
   catalogsNeverRegistered,
   catalogUnregistered,
+  pluralVariantsOf,
   registeredLocales,
 } from '@ultimat3/i18n';
 import { loadApp } from './app-load';
@@ -105,9 +106,68 @@ export async function checkRegistration(input: RegistrationInput): Promise<Regis
 }
 
 /**
- * The file half: a key source uses that a locale's catalog does not define. Built here rather than
- * in `cmd-i18n.ts` because `x verify`'s `i18n` step reports the same finding, and a second
- * construction of it is two renderers of one fact waiting to drift.
+ * `⟦key⟧` — `@ultimat3/i18n`'s own loud miss, spelled ONCE for the whole CLI. `x i18n sync <default>`
+ * writes it and the two checks below refuse it, so a second spelling would be a placeholder one
+ * half of this package writes and the other half cannot see.
+ */
+const MISS_OPEN = '\u27E6';
+const MISS_CLOSE = '\u27E7';
+
+/** What `x i18n sync` seeds a key with when there is no catalog above it to copy a value from. */
+export const loudMiss = (key: string): string => `${MISS_OPEN}${key}${MISS_CLOSE}`;
+
+/**
+ * A value that is a placeholder rather than a translation. Any `⟦…⟧`, not just `⟦<this key>⟧`:
+ * an author who renames a key and leaves the old marker behind still ships a placeholder.
+ */
+export const isLoudMiss = (value: string | undefined): boolean =>
+  value?.startsWith(MISS_OPEN) === true && value.endsWith(MISS_CLOSE);
+
+/**
+ * Whether `locale` answers `key` with a placeholder. Every spelling `definesKey` accepts is
+ * checked — `pluralVariantsOf` is `@ultimat3/i18n`'s own list, the same one `auditCatalogs` uses,
+ * so "defined" and "defined with a real string" can never disagree about which entries count.
+ * `some`, not `every`: a plural family with one untranslated category renders `⟦items_many⟧` on
+ * exactly the rows that hit it.
+ */
+const answersWithPlaceholder = (catalog: Catalog, key: string): boolean =>
+  [key, ...pluralVariantsOf(key)].some(
+    (candidate) => Object.hasOwn(catalog, candidate) && isLoudMiss(catalog[candidate]),
+  );
+
+/**
+ * The audit, with every placeholder counted as the missing key it stands in for.
+ *
+ * `auditCatalogs` asks `Object.hasOwn` and nothing else, so a key present with ANY value is not
+ * missing — including `⟦key⟧`, which is the value `x i18n sync <defaultLocale>` writes for every
+ * gap it closes. Without this, following `X_CATALOG_MISSING_KEYS`'s own `fix:` turns the `i18n`
+ * gate step green over strings no human has ever read: issue #249's ending, reached by running the
+ * command the error recommends. The hole predates the seeding — a hand-written `"TODO"` bought the
+ * same green — but one command now writes sixteen of them, so it is a hole with a shortcut to it.
+ *
+ * Applied HERE and not in `auditCatalogs`: `⟦…⟧` is what the CLI writes, and `@ultimat3/i18n`'s
+ * audit answering "is this key defined" is a different question from "is this app shippable".
+ */
+export function withPlaceholdersMissing(
+  report: ExtractReport,
+  catalogs: Readonly<Record<Locale, Catalog>>,
+): ExtractReport {
+  const locales = report.locales.map((audit) => {
+    const catalog = catalogs[audit.locale] ?? {};
+    const known = new Set(audit.missing);
+    const placeheld = report.used.filter(
+      (key) => !known.has(key) && answersWithPlaceholder(catalog, key),
+    );
+    if (placeheld.length === 0) return audit;
+    return { ...audit, missing: [...audit.missing, ...placeheld].sort() };
+  });
+  return { ...report, locales, ok: locales.every((audit) => audit.missing.length === 0) };
+}
+
+/**
+ * The file half: a key source uses that a locale's catalog does not define, or defines with a
+ * placeholder. Built here rather than in `cmd-i18n.ts` because `x verify`'s `i18n` step reports
+ * the same finding, and a second construction of it is two renderers of one fact waiting to drift.
  */
 export function missingKeyFindings(report: ExtractReport): readonly Finding[] {
   return report.locales
@@ -126,5 +186,8 @@ export function missingKeyFindings(report: ExtractReport): readonly Finding[] {
 export async function catalogFindings(root: string): Promise<readonly Finding[]> {
   const { report, catalogs, extraction, ignoreUnused } = await auditApp(root);
   const registration = await checkRegistration({ root, catalogs, extraction, ignoreUnused });
-  return [...missingKeyFindings(report), ...registration.findings];
+  return [
+    ...missingKeyFindings(withPlaceholdersMissing(report, catalogs)),
+    ...registration.findings,
+  ];
 }

package/src/index.ts

@@ -60,6 +60,12 @@ export {
   plannedCommands,
   plannedSubcommand,
 } from './cmd-planned';
+// `shotCommand`, `prCommand` and `ciCommand` are deliberately NOT re-exported here. They reach
+// `x` through `registry.ts`, which is the only thing that makes a command exist — and the barrel
+// is the surface an APP imports. Exporting them puts `cmd-shot.ts` in the module graph of every
+// app that imports `@ultimat3/cli`, which then has to resolve `@ultimat3/scraping` — a browser
+// driver it never uses. Measured: it reds `tsc -b` on `dummy/social-media-clone` with five
+// TS2307s in files that app never calls. The app path does not pay for the tool path.
 export { actionsCommand, entitiesCommand, queriesCommand } from './cmd-registries';
 export { renderRouteTable, routesCommand } from './cmd-routes';
 export { testCommand } from './cmd-test';
@@ -177,6 +183,13 @@ export type { DeclaredFlag } from './flag-reads';
 export { checkFlagReads, declaredFlags, readsFlag } from './flag-reads';
 export type { Guard } from './guards';
 export { findingProblem, GUARD_DIR, guardFindings, guardPaths } from './guards';
+// The island bundler, and only its entry point. An island is the one module Ultimate ships to a
+// browser, so an app has to be able to build one to TEST one — `mountIsland` from
+// `@ultimat3/testing` takes this function as its `build` parameter (issue #260). `discoverIslands`,
+// `islandBundle`, `writeIslands`, `ISLAND_BASE_PATH` and `ISLAND_GLOB` stay internal: they are
+// `x build`'s and `x dev`'s wiring, and every name here is a semver promise forever.
+export type { IslandBundle, IslandChunk } from './island-bundle';
+export { buildIslands } from './island-bundle';
 export type { DrainFailure, DrainOutcome, DrainSkip } from './jobs-drain';
 export { drainJobs } from './jobs-drain';
 export type { JobsListFilter, JobsListResult } from './jobs-report';
@@ -235,6 +248,24 @@ export {
   isVendored,
   SOURCE_GLOBS,
 } from './source-files';
+export type {
+  EmittedPage,
+  RouteFacts,
+  SkippedRoute,
+  SkipReason,
+  StaticReport,
+} from './static-report';
+export {
+  parseStaticReport,
+  readStaticReport,
+  removeStaticReport,
+  renderStaticReport,
+  SKIP_REASONS,
+  STATIC_REPORT_FILE,
+  skippedRoute,
+  skipReasonFor,
+  writeStaticReport,
+} from './static-report';
 export type { TestCounts } from './test-counts';
 export { countsOf } from './test-counts';
 export type { TestFile } from './test-select';
@@ -286,4 +317,10 @@ export {
   SEMVER,
   workspacePackages,
 } from './workspace-checks';
-export { writeLine } from './write-line';
+export type { WorkspaceNode, WorkspaceScan } from './workspace-graph';
+// The graph itself, not just the gate's verdict on it: issue #239's complaint is that a
+// scaffolded repo's dependency graph exists only inside `tsc`, so an app's own tooling has
+// nothing to read. `checkWorkspaceDependencies` stays internal — it is reached through
+// `x verify`, which is the one way a rule is enforced here.
+export { readWorkspaceGraph, scanWorkspaces } from './workspace-graph';
+export { writeErrorLine, writeLine } from './write-line';

package/src/island-bundle.ts

@@ -13,6 +13,8 @@ import {
   islandModuleId,
 } from '@ultimat3/render';
 import { IslandBuildFailedError } from './errors';
+import { solidProductionPlugin } from './island-solid-production';
+import { islandStylesPlugin } from './island-styles';
 import { solidJsxPlugin } from './solid-loader';
 
 /**
@@ -84,7 +86,13 @@ async function buildOne(root: string, file: string): Promise<IslandChunk> {
       // an island. The app's tsconfig says `jsx: "preserve"`, which makes the bundler fall back to
       // classic `React.createElement` — emitted into a browser chunk that imports no React, with
       // `success: true` and no log. Every island shipped that way through five majors.
-      plugins: [solidJsxPlugin],
+      //
+      // The other two close the same shape of failure — a wrong answer `Bun.build` reports as
+      // `success: true`: without the second, `target: 'browser'` resolves the `development`
+      // export condition and the chunk carries Solid's dev build; without the third, Bun's file
+      // loader resolves a `.module.scss` to its asset PATH, so `styles['x']` is `undefined` and
+      // every element renders unclassed.
+      plugins: [solidJsxPlugin, solidProductionPlugin, islandStylesPlugin],
     });
   } catch (error) {
     throw new IslandBuildFailedError({ file, logs: describeBuildError(error) });
@@ -121,13 +129,64 @@ function describeBuildError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+export interface BuildIslandsOptions {
+  /**
+   * Build ONE island, named app-root-relative — the whole option surface. A test that mounts a
+   * single island otherwise pays every OTHER island's Babel pass and `Bun.build` on every file,
+   * and the reference app is the one that feels it.
+   *
+   * Optional, and it must stay optional: `buildIslands` is on `@ultimat3/cli`'s public surface and
+   * `@ultimat3/testing`'s `IslandBuilder` satisfies it STRUCTURALLY as `(root: string) => …`, which
+   * is what keeps the `cli -> testing` edge pointing the one legal way.
+   */
+  readonly only?: string;
+}
+
 /** Build every island in the app. An app with none returns an empty bundle and costs one glob. */
-export async function buildIslands(root: string): Promise<IslandBundle> {
-  const files = await discoverIslands(root);
+export async function buildIslands(
+  root: string,
+  options: BuildIslandsOptions = {},
+): Promise<IslandBundle> {
+  const discovered = await discoverIslands(root);
+  const only = options.only;
+  const files = only === undefined ? discovered : discovered.filter((file) => file === only);
+  // A filter that matches nothing is a typo in the CALLER, never an app with no islands. Answering
+  // an empty bundle here would surface two steps later, as a chunk table with no entry for a file
+  // the caller can see on disk.
+  if (only !== undefined && files.length === 0) throw onlyMissing(only, discovered);
   const chunks = await Promise.all(files.map((file) => buildOne(root, file)));
   return islandBundle(chunks);
 }
 
+/**
+ * Same code as an unbuildable `src`: "this path cannot become a client entry" is one condition.
+ *
+ * Two fixes, because there are two causes and only one of them can be repaired by naming a path.
+ * The line was `pass only: '<app-root-relative path>.island.tsx'` — a placeholder nobody can run,
+ * which no gate could see: `fixProblem` fails a fix only for ADVICE with no command token, and a
+ * sentence with neither is not advice. Both forms below are constructed from what the caller
+ * already handed in, so neither can name a path this app does not have.
+ */
+function onlyMissing(only: string, discovered: readonly string[]): IslandInvalidError {
+  const cause =
+    `buildIslands was asked for ${JSON.stringify(only)} alone, which is not one of the ` +
+    `${discovered.length} islands this app has (${discovered.length === 0 ? 'none' : discovered.join(', ')})`;
+  // The basename match first: a filter that misses normally missed on the PREFIX — a route-relative
+  // specifier where `discoverIslands`' app-root-relative path was wanted — and the filename
+  // survives that. Falling back to the first keeps the fix a real path rather than a shape.
+  const nearest =
+    discovered.find((file) => posix.basename(file) === posix.basename(only)) ?? discovered[0];
+  // An app with no islands cannot be pointed at one, so the fix WRITES the file that was asked
+  // for — the same command `entryMissing` hands back, split off the same path.
+  if (nearest === undefined) {
+    return new IslandInvalidError(
+      cause,
+      `x g island ${posix.basename(only, ISLAND_EXTENSION)} --at ${posix.dirname(only)}`,
+    );
+  }
+  return new IslandInvalidError(cause, `buildIslands(root, { only: '${nearest}' })`);
+}
+
 export function islandBundle(chunks: readonly IslandChunk[]): IslandBundle {
   const byFile = new Map(chunks.map((chunk) => [chunk.file, chunk]));
   const byUrl = new Map(chunks.map((chunk) => [chunk.url, chunk]));

package/src/island-solid-production.ts

@@ -0,0 +1,129 @@
+// Every `solid-js` import in an island chunk resolves to Solid's PRODUCTION browser build.
+// `Bun.build({ target: 'browser' })` always adds the `development` export condition and offers no
+// option that removes it — `conditions`, `production`, `env` and `define` were each measured under
+// Bun 1.4 and none of them does — so without this seam an island ships the dev bundle silently.
+
+// `node:path` by necessity: Bun ships no path API, and this file resolves a package entry back
+// to the directory its `exports` map is relative to.
+import { dirname, join } from 'node:path';
+import type { BunPlugin } from 'bun';
+import { IslandBuildFailedError } from './errors';
+
+/**
+ * The conditions an island's `solid-js` subpath is resolved under. `development` is the one NOT in
+ * the set, which is the whole point of the file; `production` is in it because an island chunk is
+ * only ever built to be shipped — `x dev` serves the same chunk the container does, so a second
+ * answer here would be a bundle the byte budget never measured.
+ */
+const ISLAND_CONDITIONS: ReadonlySet<string> = new Set([
+  'production',
+  'browser',
+  'module',
+  'import',
+  'default',
+]);
+
+/** `solid-js` and its subpaths, and nothing else: Solid is the runtime an island is compiled for. */
+const SOLID_SPECIFIER = /^solid-js(?:\/|$)/;
+
+/**
+ * Node's conditional-exports walk, restricted to what this file needs: the first key of the object
+ * that the build's condition set contains, depth-first, with an array as an ordered fallback list.
+ * Written out rather than delegated to `Bun.resolveSync` because the ONE thing it has to do
+ * differently from Bun's resolver is refuse `development` — and `types` with it, which would
+ * otherwise win on Solid's map and hand the bundler a `.d.ts`.
+ */
+export function selectCondition(node: unknown, conditions: ReadonlySet<string>): string | null {
+  if (typeof node === 'string') return node;
+  if (Array.isArray(node)) {
+    for (const alternative of node as readonly unknown[]) {
+      const picked = selectCondition(alternative, conditions);
+      if (picked !== null) return picked;
+    }
+    return null;
+  }
+  if (typeof node !== 'object' || node === null) return null;
+  for (const [condition, value] of Object.entries(node)) {
+    if (!conditions.has(condition)) continue;
+    const picked = selectCondition(value, conditions);
+    if (picked !== null) return picked;
+  }
+  return null;
+}
+
+/** One parse per manifest: an island imports Solid from several files, and every file asks again. */
+const exportsCache = new Map<string, unknown>();
+
+async function exportsOf(manifest: string): Promise<unknown> {
+  const hit = exportsCache.get(manifest);
+  if (hit !== undefined || exportsCache.has(manifest)) return hit;
+  const parsed: unknown = JSON.parse(await Bun.file(manifest).text());
+  const field =
+    typeof parsed === 'object' && parsed !== null && 'exports' in parsed
+      ? (parsed as { readonly exports?: unknown }).exports
+      : undefined;
+  exportsCache.set(manifest, field);
+  return field;
+}
+
+/** Test seam: the cache is process-global because `x dev` rebuilds in one process. */
+export function clearSolidExportsCache(): void {
+  exportsCache.clear();
+}
+
+/**
+ * The absolute file `specifier` must resolve to, or `null` for "Bun's own answer is already the
+ * right one" — which is every subpath Solid declares as a plain string or a pattern, since a
+ * declaration with no conditions on it cannot select the development build.
+ */
+export async function solidProductionEntry(
+  specifier: string,
+  resolveDir: string,
+  importer: string,
+): Promise<string | null> {
+  let manifest: string;
+  try {
+    // `solid-js/package.json` is an `exports` entry of Solid's own map, so this reaches the exact
+    // copy the island would have imported — not a hoisted sibling at a different version.
+    manifest = Bun.resolveSync('solid-js/package.json', resolveDir);
+  } catch {
+    // Solid is not installed here. Bun's resolver says so, in its own words, naming the importer.
+    return null;
+  }
+  const field = await exportsOf(manifest);
+  const subpath = specifier === 'solid-js' ? '.' : `.${specifier.slice('solid-js'.length)}`;
+  if (typeof field !== 'object' || field === null || !(subpath in field)) return null;
+
+  const entry = selectCondition((field as Record<string, unknown>)[subpath], ISLAND_CONDITIONS);
+  const file = entry === null ? null : join(dirname(manifest), entry);
+  if (file === null || !(await Bun.file(file).exists())) {
+    throw new IslandBuildFailedError({
+      file: importer.length > 0 ? importer : specifier,
+      logs:
+        `${specifier} has no production browser entry: ${manifest} answers ` +
+        `${entry === null ? 'nothing' : JSON.stringify(entry)} under ` +
+        `[${[...ISLAND_CONDITIONS].join(', ')}], and an island may not ship Solid's ` +
+        'development build',
+    });
+  }
+  return file;
+}
+
+/**
+ * The plugin `island-bundle.ts` hands `Bun.build`, beside `solidJsxPlugin`. Stateless apart from
+ * the manifest cache, so one frozen descriptor serves every concurrent island build.
+ *
+ * The absolute path it answers with no longer matches `SOLID_SPECIFIER`, so Solid's own internal
+ * `import … from 'solid-js'` is the only re-entry — and that one is wanted: it is how `web.js`
+ * reaches `solid.js` rather than `dev.js`.
+ */
+export const solidProductionPlugin: BunPlugin = {
+  name: 'ultimate-island-solid-production',
+  setup(build): void {
+    build.onResolve({ filter: SOLID_SPECIFIER }, async ({ path, importer, resolveDir }) => {
+      const from = resolveDir.length > 0 ? resolveDir : dirname(importer);
+      const entry = await solidProductionEntry(path, from, importer);
+      return entry === null ? undefined : { path: entry };
+    });
+  },
+};

package/src/island-styles.ts

@@ -0,0 +1,41 @@
+// The stylesheet half of an island build: `import styles from './x.module.scss'` answers the class
+// map the SERVER hashed, and the CSS lands in the same registry a document renders from. Bun's
+// default loader answers the asset PATH — a string — so `styles['track']` is `undefined`, every
+// element renders unclassed, and `Bun.build` reports `success: true` with no log.
+
+import { renderThrowable, UltimateError } from '@ultimat3/core';
+import { loadStylesheet } from '@ultimat3/render';
+import type { BunPlugin } from 'bun';
+import { IslandBuildFailedError } from './errors';
+
+/**
+ * The same spelling `installRenderLoader` filters on, so there is ONE answer to "what is a
+ * stylesheet import" across the server loader and the island bundler. A plain `.css`/`.scss` is in
+ * deliberately: it compiles to an empty class map and registers its rules, which is what a global
+ * stylesheet an island imports has to do.
+ */
+const STYLESHEET = /\.s?css$/;
+
+/**
+ * `loadStylesheet`, not `compileStylesheet`: compiling alone answers the class names and drops the
+ * RULES on the floor, and an island is the one importer a document's own module graph never sees.
+ * Registering here is what puts them in `stylesFor(surface)` — `buildIslands` runs before the first
+ * document is rendered, in `x dev` and in `prerenderSite` alike.
+ */
+export const islandStylesPlugin: BunPlugin = {
+  name: 'ultimate-island-styles',
+  setup(build): void {
+    build.onLoad({ filter: STYLESHEET }, async ({ path }) => {
+      const source = await Bun.file(path).text();
+      try {
+        return { contents: loadStylesheet(path, source), loader: 'js' };
+      } catch (error) {
+        // A coded failure already names the file and carries a fix — re-wrapping it would bury
+        // both. Anything else is rendered through `renderThrowable`, because this is the plugin's
+        // last frame and a value that fights being read would escape a Bun plugin as a bare throw.
+        if (error instanceof UltimateError) throw error;
+        throw new IslandBuildFailedError({ file: path, logs: renderThrowable(error) });
+      }
+    });
+  },
+};

package/src/jobs-report.ts

@@ -18,23 +18,20 @@ import {
   inspectJob,
   inspectJobList,
   inspectQueues,
+  isJobState,
+  JOB_STATES,
   retryFromStep,
 } from '@ultimat3/jobs';
 import { BadFlagError, JobUnknownError } from './errors';
 
-/** Mirrors `JobState` from `@ultimat3/jobs`, which exports the type but no runtime list. */
-export const JOB_STATES: readonly JobState[] = [
-  'ready',
-  'delayed',
-  'running',
-  'suspended',
-  'done',
-  'failed',
-  'dead',
-];
-
-const isJobState = (value: string): value is JobState =>
-  (JOB_STATES as readonly string[]).includes(value);
+/**
+ * The queue's own vocabulary, re-exported rather than restated — this file carried a copy of it,
+ * and the copy was one member short. `cancelled` shipped in `@ultimat3/jobs` and never here, so
+ * `x jobs cancel` created a state `x jobs ls --state cancelled` then refused to filter on: two
+ * commands of one CLI disagreeing about what a job can be. Kept on this module's surface because
+ * `index.ts` exports it from here.
+ */
+export { JOB_STATES } from '@ultimat3/jobs';
 
 export function parseStateFlag(value: string | undefined): JobState | undefined {
   if (value === undefined) return undefined;

package/src/mcp-errors.ts

@@ -48,6 +48,15 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_JOB_UNKNOWN: 'x jobs ls --json',
   X_FIX_TARGET_UNKNOWN: 'x fix boundary apps/web/site/page.tsx --json',
   X_ERROR_FIX_INVALID: 'x verify --json   # the finding names the file, the line and the fix text',
+  X_WORKSPACE_DEP_UNDECLARED:
+    'x verify --json   # the package-shape finding carries the dependency line to add',
+  X_SHOT_BROWSER_MISSING: 'bun add -d puppeteer-core',
+  X_GH_UNAVAILABLE: 'gh auth login   # install first from https://cli.github.com',
+  X_GH_NOT_AUTHENTICATED: 'gh auth login',
+  X_GH_COMMAND_FAILED: 'x ci --json   # the finding carries the gh invocation that failed',
+  X_GH_RESPONSE_INVALID: 'x pr review --json   # the finding names the field that did not parse',
+  X_PR_NOT_FOUND: 'x pr review --pr 1 --json   # or open one first with: gh pr create',
+  X_CI_RUN_NOT_FOUND: 'x ci --branch main --json',
   X_ERROR_CODE_UNDOCUMENTED: 'x verify --json   # the finding names the code and the missing page',
   X_ERROR_CODE_UNREGISTERED:
     'x errors list --json   # register the code in its package src/errors.ts, or move its row under "Reserved codes"',
@@ -93,6 +102,9 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_PORT_IN_USE: 'x dev --port 3001 --json',
   X_DEV_ALREADY_RUNNING:
     'x dev --json   # after stopping the x dev that already owns this checkout',
+  // The path, not `x dev`: the boot has already refused and rerunning it refuses again. The
+  // error's own `fix:` carries the resolved `.x/dev.lock`; this table cannot know the state dir.
+  X_DEV_LOCK_UNREADABLE: 'rm .x/dev.lock   # then: x dev --json',
   // Not `x db status`: there is no such subcommand (`x db` is gen, migrate, reset, studio, branch),
   // so the fix answered a failed step with X_CLI_UNKNOWN_COMMAND. `x doctor` is what reports
   // reachability and drift, and is already this table's answer for X_DB_STUDIO_FAILED.

package/src/messages.ts

@@ -139,6 +139,11 @@ const CATALOG = {
   // the app has a schema no migration records and `x verify`'s drift step says so until it runs.
   'cli.new.done':
     'created {name} — next: cd {name} && bun install && x db gen "initial" && x db migrate && x dev',
+  // The two prose lines of `x new`'s report. The `run: cd … && git init …` line beneath the second
+  // one stays inline in `cmd-new.ts`: it is an instruction to paste verbatim, and a translated
+  // command is a broken one — the same split `Finding.fix` already makes.
+  'cli.new.wrote': '  {count} files in {dir}',
+  'cli.new.noRepository': '  no repository — {problem}',
   '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
@@ -159,11 +164,82 @@ const CATALOG = {
   '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.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',
+  // `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',
+  '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}',
+  'cli.shot.blind.status':
+    'HTTP response status is not observed — the port records requests, never responses',
+  '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}:',
+  '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',
   'cli.test.fail': '{failed} of {workers} shard(s) failed',
+  'cli.test.affected.none': 'nothing is affected by {base}...HEAD — 0 test file(s) ran',
   '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',
+  // 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',
   // A skipped step is not a passed one, so the two counts never share a sentence — and the skipped

package/src/output.ts

@@ -52,6 +52,17 @@ export interface CommandResult {
    * could show is how the two drift.
    */
   readonly hold?: () => Promise<void>;
+  /**
+   * Which fd this result is written to. `stdout` for every command, absent included — and
+   * `stderr` for the one case where fd 1 is not the command's to write on: `x mcp serve
+   * --transport stdio`, whose stdout carries JSON-RPC frames, and where the `✓ mcp stdio serving
+   * 13 tools` line printed after the loop exits is a malformed frame to whatever is reading.
+   *
+   * Behaviour, not a fact, exactly like `hold` above — so NEITHER renderer carries it. It says
+   * where a rendered line goes, and a payload that also claimed it would be a second answer to a
+   * question `dispatch` has already answered by choosing the sink.
+   */
+  readonly stream?: 'stdout' | 'stderr';
 }
 
 export interface UltimateErrorShape {
@@ -158,13 +169,22 @@ export function renderHuman(result: CommandResult, verbose = false): string {
   for (const step of result.steps ?? []) {
     out.push(`  ${mark(step)} ${step.name.padEnd(18)} ${step.durationMs}ms${width(step)}`);
     for (const finding of step.findings) out.push(renderFinding(finding, '      '));
+    // NOT escaped, and that is the one exception: `output` is this process's own captured
+    // subprocess stdout — `bun test`'s colour is the reason a human reads it at all, and it is
+    // already split on its real newlines rather than carrying them inside one entry.
     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);
+  // Every free-text line through the SAME `singleLine` the 3-line format runs, because this is
+  // where text the CLI did not write reaches fd 1: a GitHub review body (`x pr`), a CI log tail
+  // (`x ci`), a page's own console (`x shot`). It was emitted verbatim, so an ESC byte in a PR
+  // comment retitled the window and cleared the screen, and a newline in one entry printed a
+  // second line a reader — or the agent this command exists for — takes for the renderer's own.
+  for (const line of result.lines ?? []) out.push(singleLine(line));
   for (const finding of result.findings ?? []) out.push(renderFinding(finding, '  '));
-  out.push(`${result.ok ? '✓' : '✗'} ${result.summary}`);
+  // The summary is foreign too: `cli.shot.threw` interpolates a page's own error message.
+  out.push(`${result.ok ? '✓' : '✗'} ${singleLine(result.summary)}`);
   return out.join('\n');
 }