@ultimat3/cli 5.0.1 → 7.0.0

package/src/i18n-registration.ts

@@ -0,0 +1,130 @@
+// Every finding about an app's strings, and the one composition `x i18n check` and `x verify`'s
+// `i18n` step both report — two callers, one answer, so the command and the gate can never
+// disagree. The runtime half is here because nothing else could ask it: `i18n-audit.ts` compares
+// source against files on disk and was green for every string of a shipped app whose catalog
+// module nothing imported (issue #249).
+
+import type { Catalog, Extraction, ExtractReport, Locale } from '@ultimat3/i18n';
+import {
+  auditCatalogs,
+  catalogFor,
+  catalogMissingKeys,
+  catalogRegistrationGaps,
+  catalogsNeverRegistered,
+  catalogUnregistered,
+  registeredLocales,
+} from '@ultimat3/i18n';
+import { loadApp } from './app-load';
+import { auditApp } from './i18n-audit';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+import { catalogPath } from './templates/locales';
+
+/**
+ * What this check needs of a boot. The seam is injected so a fixture can be exactly "the app
+ * loaded and registered nothing" — the shipped shape of the bug — without a temp directory that
+ * can resolve `@ultimat3/*`. `loadApp` is the production value, and it is the same call
+ * `serveApp` makes: asking a different loader than the server uses would prove nothing.
+ */
+export type AppLoader = (root: string) => Promise<{
+  readonly findings: readonly Finding[];
+  readonly defaultLocale: string;
+}>;
+
+export interface RegistrationInput {
+  readonly root: string;
+  /** The catalogs on disk, parsed — `packages/i18n/catalogs/*.json`. */
+  readonly catalogs: Readonly<Record<Locale, Catalog>>;
+  readonly extraction: Extraction;
+  readonly ignoreUnused: readonly string[];
+  readonly load?: AppLoader;
+}
+
+export interface RegistrationReport {
+  readonly ok: boolean;
+  readonly findings: readonly Finding[];
+  /** Keys that would render a loud miss because registration never happened. */
+  readonly unregistered: number;
+  /** How many locales are affected — one row of the summary's "across N locale(s)". */
+  readonly locales: number;
+  /** Which shipped locales the registry cannot fully answer — the `registered` column's `no`. */
+  readonly unregisteredLocales: readonly Locale[];
+  /** Every locale the registry holds after the load, sorted. Empty is not possible in a real
+   * boot: the framework's own catalog is the base layer, so `['en']` is the floor. */
+  readonly registered: readonly Locale[];
+}
+
+/**
+ * The app ships nothing on disk, so there is no file to diff — the only evidence left is whether
+ * the keys source actually uses resolve. Audited through `auditCatalogs` rather than a fresh
+ * `hasOwn` loop, because a plural family is defined as `n_one`/`n_other` and a bare lookup of the
+ * stem `n` would report every plural in the app as unresolved.
+ */
+function unresolvedUsedKeys(input: RegistrationInput, locale: Locale): readonly string[] {
+  const report = auditCatalogs({
+    extraction: input.extraction,
+    catalogs: { [locale]: catalogFor(locale) },
+    ignoreUnused: input.ignoreUnused,
+  });
+  return report.locales[0]?.missing ?? [];
+}
+
+export async function checkRegistration(input: RegistrationInput): Promise<RegistrationReport> {
+  // Importing the app's modules IS the registration, in this process exactly as in the server's.
+  const app = await (input.load ?? loadApp)(input.root);
+
+  const gaps = catalogRegistrationGaps(input.catalogs);
+  const findings: Finding[] = gaps.map((gap) => ({
+    ...findingFrom(catalogUnregistered(gap)),
+    at: catalogPath(gap.locale),
+  }));
+  let unregistered = gaps.reduce((sum, gap) => sum + gap.missing.length, 0);
+  let locales = gaps.length;
+
+  if (Object.keys(input.catalogs).length === 0) {
+    const unresolved = unresolvedUsedKeys(input, app.defaultLocale);
+    if (unresolved.length > 0) {
+      findings.push(findingFrom(catalogsNeverRegistered(app.defaultLocale, unresolved)));
+      unregistered += unresolved.length;
+      locales += 1;
+    }
+  }
+
+  return {
+    ok: findings.length === 0,
+    // The load's own findings ride along ONLY when something is unregistered, and that condition is
+    // the whole value: a module that would not import registers nothing, so "packages/i18n/src/
+    // index.ts: SyntaxError" is the evidence for the gap above it. With every catalog registered, a
+    // broken route file is not this command's business and reporting it would be noise on a pass.
+    findings: findings.length === 0 ? findings : [...findings, ...app.findings],
+    unregistered,
+    locales,
+    unregisteredLocales: gaps.map((gap) => gap.locale),
+    registered: registeredLocales(),
+  };
+}
+
+/**
+ * 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.
+ */
+export function missingKeyFindings(report: ExtractReport): readonly Finding[] {
+  return report.locales
+    .filter((audit) => audit.missing.length > 0)
+    .map((audit) => ({
+      ...findingFrom(catalogMissingKeys(audit.locale, audit.missing)),
+      at: catalogPath(audit.locale),
+    }));
+}
+
+/**
+ * Both halves of one question — does every string this app renders resolve? — for a caller that
+ * wants the verdict and not the table. `x verify`'s `i18n` step is that caller; `cmd-i18n.ts`
+ * composes the same two pieces itself because it also renders per-locale rows.
+ */
+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];
+}

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 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 { writeLine } from './write-line';

package/src/island-bundle.ts

@@ -13,6 +13,9 @@ 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';
 
 /**
  * Where a chunk is served from, in `x dev`, in the container and in a static export — one base
@@ -78,6 +81,18 @@ async function buildOne(root: string, file: string): Promise<IslandChunk> {
       format: 'esm',
       splitting: false,
       minify: true,
+      // A build with no `plugins` is a build with no JSX transform: `Bun.plugin` installs into the
+      // RUNTIME's loader and `Bun.build` walks its own graph, so render's `.tsx` loader never sees
+      // 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.
+      //
+      // 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) });
@@ -114,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/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"',
@@ -91,6 +100,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_RUNTIME_DRIVER_SPLIT: 'x dev --json   # the boot names the driver the app installed twice',
   X_GENERATE_CONFLICT: 'x g route posts --force --json',
   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',
   // 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

@@ -72,6 +72,9 @@ const CATALOG = {
   'cli.dev.mail.external': 'mail=external({driver} via {detail})',
   'cli.dev.mail.refused': 'mail=refused({detail})',
   'cli.dev.hmr': 'reloaded {file} in {ms}ms',
+  // A hard kill leaves the lock behind and that is normal, not a fault — worth one line so a
+  // reader knows why the boot paused, and never a finding.
+  'cli.dev.staleLock': 'cleared a stale dev.lock — the previous x dev did not shut down cleanly',
   'cli.dev.roles': '  roles {roles}',
   'cli.dev.panels': '  panels {panels}',
   'cli.dev.introspect': '  introspect {url}',
@@ -156,7 +159,71 @@ 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',
+  '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',