@ultimat3/cli 1.2.0 → 3.0.0

package/src/fix-command.ts

@@ -0,0 +1,268 @@
+// The half of the error contract that a text rule cannot decide: a `fix:` may cite `x <command>`
+// and that command may not exist. Six shipped fix lines named `x db status`, `x logs tail`,
+// `x trace`, `x metrics`, `x auth whoami` and `x ai prompts` — every one of them passed the
+// `errors` step, because the step checks that a fix NAMES a command, never that the build ships it.
+//
+// It reads THREE words for the same reason it reads two: `x db branch ls --json` shipped as a fix
+// while `x db branch` had no `ls`, because a rule stopping at the subcommand never saw the word
+// that decided what ran.
+
+import type { CommandSpec } from './parse';
+import { GLOBAL_FLAGS } from './parse';
+
+/**
+ * The rule is CONDITIONAL, and that is the whole design.
+ *
+ * *If* a fix cites `x <something>`, that something must resolve. It does NOT say every fix must
+ * name a command — axiom 4 asks for an executable instruction, and
+ * `set OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318` or
+ * `counter('orders_total', { maxSeries: 4000 })` are executable and correctly cite nothing. A
+ * universal rule would push an author towards citing a command that does not really fix it, which
+ * is a worse error than one with no command in it.
+ */
+// Digits are part of a name, not a boundary: `x i18n check` read through `[a-z-]*` alone cites
+// `x i`, which is not a command — a false finding on three of the framework's own fix lines.
+//
+// The THIRD slot also matches a `<placeholder>`, and only the third. A slot with a closed set is a
+// slot where the reader has nothing to substitute, so `x db branch <name>` — two shipped fix lines
+// in `@ultimat3/mcp` — is `X_CLI_UNKNOWN_COMMAND` when run and resolved clean while a placeholder
+// was invisible to the reader. Second and fourth slots are open positionals (`x new my-app`,
+// `x db branch drop <name>`), where a placeholder is exactly right.
+const CITATION =
+  /(?:^|[\s;|&("'`])x\s+([a-z][a-z\d-]*)(?:\s+([a-z][a-z\d-]*))?(?:\s+([a-z][a-z\d-]*|<[^>]*>))?/g;
+
+/**
+ * A long flag, `--` stripped. `--no-<name>` is the parser's negation of a boolean, so it resolves
+ * against `<name>` — reporting `no-example` as an unknown flag would be a finding about a working
+ * invocation. A `-j` short form is deliberately not read: one letter is too weak a signal in prose.
+ */
+const FLAG = /(?:^|\s)--(?:no-)?([a-z][a-z\d-]*)/g;
+
+/**
+ * Where a citation's argument list ends. `;`, `|` and `&` start a second shell word, `#` starts a
+ * comment, and a backtick or a quote closes the span the citation was written in — past any of
+ * them a `--flag` belongs to something else.
+ */
+const ARGUMENT_END = /[;|&#`'"]/;
+
+/** One `x …` citation, as written. `sub` is the next bare word, which may not be a subcommand. */
+export interface FixCitation {
+  readonly command: string;
+  readonly sub: string | undefined;
+  /** The bare word after `sub`. Judged only against a declared `subcommandPositionals` set. */
+  readonly positional: string | undefined;
+  /** Long flags written after it, in order, `--` and any `no-` stripped. */
+  readonly flags: readonly string[];
+}
+
+/**
+ * Every `x <command> [<word>] [--flag …]` a fix line cites.
+ *
+ * Read off the STATIC form of the fix — the caller blanks `${…}` first — because a command name
+ * assembled at run time is not a name this can resolve, and guessing at one would report findings
+ * nobody can act on. `x` alone, or `x --json`, cites nothing: the regex needs a bare lowercase
+ * word after the space.
+ *
+ * The flag list stops at the NEXT citation as well as at `ARGUMENT_END`: one fix line routinely
+ * names two commands (`x db migrate, then confirm with x db query "…" --json`), and charging the
+ * second command's flags to the first would report a finding on the wrong half of the sentence.
+ */
+export function fixCitations(fix: string): readonly FixCitation[] {
+  const matches = [...fix.matchAll(CITATION)].filter((match) => match[1] !== undefined);
+  return matches.map((match, index) => {
+    const start = match.index + match[0].length;
+    const next = matches[index + 1]?.index ?? fix.length;
+    const tail = fix.slice(start, next);
+    const stop = ARGUMENT_END.exec(tail)?.index;
+    const args = stop === undefined ? tail : tail.slice(0, stop);
+    return {
+      command: match[1] as string,
+      sub: match[2],
+      positional: match[3],
+      flags: [...args.matchAll(FLAG)].map((flag) => flag[1] as string),
+    };
+  });
+}
+
+/** Long flags a spec accepts: its own, plus the four every command takes. */
+const declaredFlags = (spec: CommandSpec): ReadonlySet<string> =>
+  new Set([...GLOBAL_FLAGS, ...(spec.flags ?? [])].map((flag) => flag.name));
+
+export interface CommandCatalog {
+  /** Every spec the registry holds, planned ones included — `x help` lists those too. */
+  readonly specs: readonly CommandSpec[];
+  /** Names that parse but exit `X_NOT_IMPLEMENTED`. Citing one is the bug this check closes. */
+  readonly planned: ReadonlySet<string>;
+  /** `"<command> <subcommand>"` pairs that parse and exit `X_NOT_IMPLEMENTED`. */
+  readonly plannedSubcommands: ReadonlySet<string>;
+}
+
+/**
+ * What a caller accepts from a citation. A `fix:` hands its reader a command to RUN, so a planned
+ * one is a defect; a doc page may legitimately *say* a command is planned, and a rule that refused
+ * that would delete `wiki/CLI-Reference.md`'s planned table one true row at a time.
+ *
+ * `allowPlanned` covers `PLANNED_SUBCOMMANDS` as well as `PLANNED_COMMANDS` — `x db studio` is the
+ * single entry in the first table, and four pages name it as planned.
+ */
+export interface CitationRules {
+  readonly allowPlanned?: boolean;
+}
+
+/**
+ * One citation that did not resolve, split so a caller can key on WHAT failed.
+ *
+ * `subject` is the invocation spelled the way it would be typed — `x db query`, `x env check --fix`
+ * — and it is deliberately stable under a doc edit that only moves the sentence around it. That is
+ * what lets `scripts/doc-commands-allow.ts` allow one page to name one non-command (the pages that
+ * say "there is no `x serve` command" are saying something TRUE) without waiving the rule for the
+ * rest of that page.
+ */
+export interface CitationFault {
+  readonly subject: string;
+  readonly reason: string;
+}
+
+/**
+ * A second word is judged as a subcommand ONLY when the spec declares subcommands at all, or
+ * against a declared closed set of positionals. `x new my-app` and `x g route posts` take open
+ * positionals, and reporting `my-app` as an unknown subcommand would be a finding about a working
+ * example.
+ */
+function wordFault(
+  spec: CommandSpec,
+  word: string,
+  catalog: CommandCatalog,
+  rules: CitationRules,
+): CitationFault | undefined {
+  const subject = `x ${spec.name} ${word}`;
+  if (spec.subcommands !== undefined) {
+    if (!spec.subcommands.includes(word)) {
+      return {
+        subject,
+        reason: `and ${spec.name} has no such subcommand (${spec.subcommands.join(', ')})`,
+      };
+    }
+    if (catalog.plannedSubcommands.has(`${spec.name} ${word}`) && rules.allowPlanned !== true) {
+      return { subject, reason: 'which is planned and exits X_NOT_IMPLEMENTED' };
+    }
+    return undefined;
+  }
+  const choices = spec.positionalChoices;
+  if (choices === undefined || choices.includes(word)) return undefined;
+  return {
+    subject,
+    reason: `and ${word} is not one of ${spec.name}'s positionals (${choices.join(', ')})`,
+  };
+}
+
+/**
+ * The third word, judged ONLY where the subcommand declares a closed set. `x jobs show <id>` and
+ * `x db gen "add publish_at"` take open positionals, so a universal third-word rule would report
+ * findings about working invocations — the same conditionality `wordFault` applies to the second.
+ */
+function positionalFault(spec: CommandSpec, sub: string, word: string): CitationFault | undefined {
+  const choices = spec.subcommandPositionals?.[sub];
+  if (choices === undefined || choices.includes(word)) return undefined;
+  // A placeholder is judged the same as a wrong word, and deliberately: there is nothing the
+  // reader could substitute that would make `x db branch <name>` run, because the slot is a verb.
+  return {
+    subject: `x ${spec.name} ${sub} ${word}`,
+    reason: `and ${spec.name} ${sub} takes one of ${choices.join(', ')}`,
+  };
+}
+
+/**
+ * Why a citation does not resolve, or `undefined` when it does. FIVE levels, because the drift is
+ * mostly BELOW the command name: `x db query` names a real command and an unreal subcommand,
+ * `x env check --fix` names both and an unreal flag, `x test summarize` names a first positional
+ * that is not a `TestType`, and `x db branch ls` named a real subcommand and a third word that
+ * `x db branch` read as a branch NAME. A rule stopping at the command name accepted all four.
+ *
+ * The planned check is the one the whole thing exists for: a PLANNED command is in the registry and
+ * parses, so a resolution that only asked "is this a known name" would accept `x logs tail` — the
+ * exact citation that throws `X_NOT_IMPLEMENTED` at the reader.
+ *
+ * Flags are NOT judged on a planned command. `cmd-planned.ts` builds its spec from a name, a
+ * summary and a usage line and declares no flags at all, so every flag its own usage line documents
+ * would read as unknown — while the real refusal is `X_NOT_IMPLEMENTED` one level up.
+ */
+export function citationFault(
+  citation: FixCitation,
+  catalog: CommandCatalog,
+  rules: CitationRules = {},
+): CitationFault | undefined {
+  const spec = catalog.specs.find(
+    (candidate) =>
+      candidate.name === citation.command || candidate.aliases?.includes(citation.command) === true,
+  );
+  if (spec === undefined) {
+    return { subject: `x ${citation.command}`, reason: 'which is not a command' };
+  }
+  const planned = catalog.planned.has(spec.name);
+  if (planned && rules.allowPlanned !== true) {
+    return {
+      subject: `x ${citation.command}`,
+      reason: 'which is planned and exits X_NOT_IMPLEMENTED',
+    };
+  }
+  if (citation.sub !== undefined) {
+    const fault = wordFault(spec, citation.sub, catalog, rules);
+    if (fault !== undefined) return fault;
+    if (citation.positional !== undefined) {
+      const deeper = positionalFault(spec, citation.sub, citation.positional);
+      if (deeper !== undefined) return deeper;
+    }
+  }
+  if (planned) return undefined;
+  const declared = declaredFlags(spec);
+  const unknown = citation.flags.find((flag) => !declared.has(flag));
+  if (unknown === undefined) return undefined;
+  return {
+    subject: `x ${spec.name} --${unknown}`,
+    reason: `and ${spec.name} declares no such flag — the parser refuses it with X_CLI_BAD_FLAG (known: ${[...declared].join(', ')})`,
+  };
+}
+
+/** The same answer as one sentence, which is what a `cause:` line wants. */
+export function citationProblem(
+  citation: FixCitation,
+  catalog: CommandCatalog,
+  rules: CitationRules = {},
+): string | undefined {
+  const fault = citationFault(citation, catalog, rules);
+  return fault === undefined ? undefined : `cites "${fault.subject}", ${fault.reason}`;
+}
+
+/** The first citation that does not resolve. One finding per fix line, not one per word. */
+export function citedCommandProblem(
+  fix: string,
+  catalog: CommandCatalog,
+  rules: CitationRules = {},
+): string | undefined {
+  for (const citation of fixCitations(fix)) {
+    const problem = citationProblem(citation, catalog, rules);
+    if (problem !== undefined) return problem;
+  }
+  return undefined;
+}
+
+/**
+ * The registry, as this check reads it.
+ *
+ * Imported dynamically because `registry.ts` → `cmd-verify.ts` → `error-contract.ts` closes a
+ * cycle back to the caller. The precedent is `cmd-build.ts`'s `await import('./cmd-verify')`:
+ * one break, inside a function that is already async, rather than a second copy of the command
+ * list here — which would be a catalog that can disagree with the one `x help` prints.
+ */
+export async function loadCommandCatalog(): Promise<CommandCatalog> {
+  const { SPECS } = await import('./registry');
+  const { PLANNED_COMMANDS, PLANNED_SUBCOMMANDS } = await import('./cmd-planned');
+  return {
+    specs: SPECS,
+    planned: new Set(PLANNED_COMMANDS.map((planned) => planned.name)),
+    plannedSubcommands: new Set(
+      PLANNED_SUBCOMMANDS.map((planned) => `${planned.command} ${planned.subcommand}`),
+    ),
+  };
+}

package/src/flag-number.ts

@@ -0,0 +1,67 @@
+// One integer-flag reader for every command that takes one. `Number.parseInt` alone accepts a
+// prefix and answers `NaN` for the rest, and three commands took it bare: `x doctor --port abc`
+// probed `NaN`, which `portFree` reports as free — a check that CANNOT FAIL — `x dev --port abc`
+// handed `NaN` to `Bun.serve` and bound an arbitrary port, and `x test --workers 4abc` ran four.
+
+import { BadFlagError } from './errors';
+import type { ParsedArgs } from './parse';
+import { flagString } from './parse';
+
+export interface IntFlag {
+  readonly name: string;
+  /** The command as it appears in the cause line, e.g. `doctor` for `x doctor`. */
+  readonly command: string;
+  readonly min: number;
+  readonly max?: number;
+  /** A runnable invocation carrying a good value — never a `<placeholder>`. */
+  readonly example: string;
+}
+
+const bound = (flag: IntFlag): string =>
+  flag.max === undefined ? `>= ${flag.min}` : `from ${flag.min} to ${flag.max}`;
+
+/** `/^\d+$/` first: it is the only test that refuses `4abc`, `4.9`, `0x10`, `+4` and ` 4`. */
+export function parseIntFlag(raw: string, flag: IntFlag): number {
+  const value = /^\d+$/.test(raw) ? Number.parseInt(raw, 10) : Number.NaN;
+  if (
+    !Number.isInteger(value) ||
+    value < flag.min ||
+    (flag.max !== undefined && value > flag.max)
+  ) {
+    throw new BadFlagError({
+      flag: flag.name,
+      command: flag.command,
+      reason: `expects an integer ${bound(flag)}, got "${raw}"`,
+      fix: flag.example,
+    });
+  }
+  return value;
+}
+
+/** The flag's value, or `undefined` when it was not given. Throws `X_CLI_BAD_FLAG` on a bad one. */
+export function readIntFlag(args: ParsedArgs, flag: IntFlag): number | undefined {
+  const raw = flagString(args, flag.name);
+  return raw === undefined ? undefined : parseIntFlag(raw, flag);
+}
+
+/** The same, with a default — for a flag whose spec already declares one. */
+export const intFlagOr = (args: ParsedArgs, flag: IntFlag, fallback: number): number =>
+  readIntFlag(args, flag) ?? fallback;
+
+/**
+ * Every port flag answers to the same bounds `serve.ts`'s `portValue` already enforces on `PORT`,
+ * 0 included — 0 is "let the kernel pick", which is how `x dev --port 0` boots a test server on a
+ * free port. Two ranges for one concept is the drift this constant exists to prevent.
+ */
+export const PORT_RANGE = { min: 0, max: 65_535 } as const;
+
+/**
+ * A free-port suggestion the thing being fixed will actually accept. `port + 1` at the top of the
+ * range names 65536, which is not a port — so a `fix:` built that way reproduces a failure instead
+ * of ending one: `x doctor` emitted `x dev --port 65536`, which `x dev` refuses with
+ * `X_CLI_BAD_FLAG`. The neighbour below is a port; the one above does not exist. Here rather than
+ * beside either caller, because two ports-are-bounded rules is the drift `PORT_RANGE` above
+ * already exists to prevent.
+ */
+export const neighbouringPort = (port: number): number =>
+  port < PORT_RANGE.max ? port + 1 : PORT_RANGE.max - 1;

package/src/framework-scope.ts

@@ -0,0 +1,49 @@
+// Where the `@ultimat3` packages THIS `x` is pinned against live on disk. One resolver, because
+// two answers to "which framework is installed" is two answers to every question read off it —
+// the docs `x docs` quotes and the `fix:` lines `x errors explain` projects come from the same
+// directory or they describe different builds.
+
+// `node:fs`/`node:path` because Bun ships neither: `dirname` walks a resolved module up to the
+// directory that owns it, and `existsSync` is what says which directory that is.
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/**
+ * Deep enough for `src/index.ts` and for any entry an `exports` map could point at, shallow enough
+ * that a resolver answering something unexpected stops rather than walking to `/`.
+ */
+const MAX_DEPTH = 6;
+
+/**
+ * Resolved from the CLI's own dependency on `@ultimat3/core` rather than from the user's cwd:
+ * these are the packages this `x` would actually run. Resolution follows the symlink, so a
+ * workspace-linked app lands on the same `packages/` this monorepo does — one code path for both,
+ * and a directory listing rather than a hardcoded package list, because an app installs the
+ * subset it uses.
+ *
+ * The **exported entry** is what gets resolved, never `@ultimat3/core/package.json`: every package
+ * here declares `"exports": { ".": "./src/index.ts" }` and nothing else, so a subpath specifier is
+ * asking a resolver for something the package does not publish. Bun 1.3 happens to answer it
+ * anyway; a resolver that enforced `exports` would answer `undefined`, and the failure would be
+ * silent — `x docs` reporting no installed packages and `x errors explain` reporting that no
+ * framework raises the code. Walking up from the entry to the directory that owns its
+ * `package.json` depends on nothing but the entry that is already imported.
+ *
+ * `undefined` means the CLI cannot see its own dependency, which is a broken install and not
+ * merely an undocumented one; every caller reports that rather than answering emptily.
+ */
+export function frameworkScopeDir(): string | undefined {
+  let dir: string;
+  try {
+    dir = dirname(Bun.resolveSync('@ultimat3/core', import.meta.dir));
+  } catch {
+    return undefined;
+  }
+  for (let depth = 0; depth < MAX_DEPTH; depth += 1) {
+    if (existsSync(join(dir, 'package.json'))) return dirname(dir);
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+  return undefined;
+}

package/src/generate-kinds.ts

@@ -0,0 +1,97 @@
+// Which generators exist, and how one is named on a command line. Split from `cmd-generate.ts`
+// because "what a generator emits" and "which spelling reaches it" are two jobs — and the file
+// that held both had reached the 500-line ceiling, one generator short of failing its own gate.
+
+import { BadFlagError, MissingPositionalError, UnknownCommandError } from './errors';
+import type { Surface } from './templates';
+
+export const GENERATORS = [
+  'resource',
+  'action',
+  'mutator',
+  'backfill',
+  'job',
+  'route',
+  'policy',
+  'entity',
+  'query',
+  'task',
+  'island',
+  'admin:page',
+  'guard',
+] as const;
+
+export type Generator = (typeof GENERATORS)[number];
+
+/**
+ * A resource slice is app-surface by construction: it ships a live query, a form with a signal,
+ * two actions and a policy, and `site/` is the 0kb, never-hydrated surface that may not import
+ * `app/`. The documented shape is the slice in `app/` plus a separate public route
+ * (`docs/architecture/15-adding-a-feature.md`), so the flag is refused before anything is written
+ * rather than emitting a slice that fails the app's own budget and boundary gates.
+ */
+export function assertSurfaceSupported(kind: Generator, surface: Surface, name: string): void {
+  if (kind !== 'resource' || surface !== 'site') return;
+  throw new BadFlagError({
+    flag: 'surface',
+    command: 'g resource',
+    reason: 'a resource slice is app-surface — site/ ships 0kb JS and may not import app/',
+    // The caller's own name, not `<name>`: a `fix:` is copied and run verbatim, and `x g resource
+    // <name>` is a shell redirect (`bash: name: No such file or directory`), not a command.
+    fix: `x g resource ${name} && x g route ${name} --surface site`,
+  });
+}
+
+export function readKind(raw: string | undefined): Generator {
+  const kinds: readonly string[] = GENERATORS;
+  if (raw !== undefined && kinds.includes(raw)) return raw as Generator;
+  throw new UnknownCommandError({
+    path: `g ${raw ?? ''}`.trim(),
+    known: GENERATORS,
+    suggestion: 'g resource',
+  });
+}
+
+/** Two surfaces, spelled exactly. A typo that fell through to `app` would scaffold the wrong one. */
+export function readSurface(raw: string | undefined, kind: Generator, name: string): Surface {
+  if (raw === undefined || raw === 'app') return 'app';
+  if (raw === 'site') return 'site';
+  throw new BadFlagError({
+    flag: 'surface',
+    command: 'g',
+    reason: `"${raw}" is not a surface (site, app)`,
+    fix: `x g ${kind} ${name} --surface app`,
+  });
+}
+
+/**
+ * The missing `<name>` positional. It used to throw `X_CLI_UNKNOWN_COMMAND` — for a command form
+ * that IS known — with `fix: "x g route <name>"`, which pasted into a shell is a redirect
+ * (`bash: name: No such file or directory`). The code now says what is actually wrong, and the fix
+ * is a command that runs.
+ */
+export function readName(raw: string | undefined, kind: Generator): string {
+  if (raw !== undefined) return raw;
+  throw new MissingPositionalError({
+    command: `g ${kind}`,
+    positional: 'name',
+    example: `x g ${kind} ${EXAMPLE_NAME[kind]}`,
+  });
+}
+
+/** One runnable example per generator, so the `fix:` is a command and not a shape. */
+const EXAMPLE_NAME: Readonly<Record<Generator, string>> = {
+  resource: 'invoice',
+  action: 'publish-post',
+  mutator: 'rename-post',
+  backfill: 'backfill-slugs',
+  job: 'send-digest',
+  route: 'posts',
+  policy: 'post',
+  entity: 'post',
+  query: 'recent-posts',
+  task: 'nightly-digest',
+  island: 'counter',
+  'admin:page': 'ops',
+  guard: 'migration-safety',
+};

package/src/guards.ts

@@ -0,0 +1,186 @@
+// An app's own convention, made into a build error (axiom 3). A file in `guards/` exports one
+// `guard`; the gate discovers the directory and runs each one inside the `boundaries` step. The
+// framework decides what a guard IS — a function returning findings, held to the error contract —
+// and nothing about what a guard may check.
+
+// Bun ships no equivalent for either: `existsSync` answers whether this app has a guards
+// directory, `join` builds the host-separator path, and `pathToFileURL` is the only spelling of an
+// absolute path `import()` accepts on every host.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { renderCauseValue, renderThrowable } from '@ultimat3/core';
+import { fixProblem } from './error-contract';
+import type { Finding } from './output';
+import type { HostCheck } from './verify-step';
+
+/** The directory IS the registration. An app-side list is a list an app can forget to add to. */
+export const GUARD_DIR = 'guards';
+
+export interface Guard {
+  /** What this app refuses, in one line. It names the rule when the guard itself is the problem. */
+  readonly summary: string;
+  /**
+   * The rule, over the app root. Returns findings — it never prints, never decides an exit code
+   * and never throws for a normal result, because `--json`, the step table and the exit code are
+   * all projections of what it returns (axiom 2).
+   */
+  check(root: string): Promise<readonly Finding[]> | readonly Finding[];
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+const isGuard = (value: unknown): value is Guard =>
+  isRecord(value) &&
+  typeof value['summary'] === 'string' &&
+  value['summary'].trim() !== '' &&
+  typeof value['check'] === 'function';
+
+const CODE = /^X_[A-Z0-9_]+$/;
+
+/**
+ * A value named in a cause, without ever throwing to name it — the one thing this validator may
+ * never do is fail while it is explaining a failure, because then a bug in an app's guard reaches
+ * its author as a stack trace out of framework internals. The rendering itself is
+ * `@ultimat3/core`'s `renderCauseValue`: the local copy this used to hold called `String(value)` on
+ * an unnarrowed `unknown`, so a guard returning an object with a throwing `toString` destroyed the
+ * refusal — the case a scan over `String(` cannot see, because the call is one helper away.
+ * The `typeof` prefix stays: "object null" and "number 42" say what a bare literal does not.
+ */
+const shown = (value: unknown): string =>
+  typeof value === 'string' ? `"${value}"` : `${typeof value} ${renderCauseValue(value)}`;
+
+/**
+ * Why a returned value is not a finding, or `undefined` when it is one. The `fix:` half is
+ * `fixProblem` — the identical rule `x verify`'s `errors` step applies to every shipped `fix:` in
+ * the framework — because a mechanism for producing errors that are not instructions is worse than
+ * no mechanism. It runs on the returned value rather than on the source, which is the half a
+ * static scan cannot reach: a `fix` assembled at run time has no literal to read.
+ */
+export function findingProblem(value: unknown): string | undefined {
+  if (!isRecord(value)) return `${shown(value)} is not a finding object`;
+  const code = value['code'];
+  if (typeof code !== 'string' || !CODE.test(code)) {
+    return `${shown(code)} is not an X_SCREAMING_SNAKE code, so nothing can explain it`;
+  }
+  const cause = value['cause'];
+  if (typeof cause !== 'string' || cause.trim() === '') return `${code} states no cause`;
+  const fix = value['fix'];
+  if (typeof fix !== 'string') return `${code} carries no fix line`;
+  return fixProblem(fix);
+}
+
+/** Only what a finding may carry, so a guard cannot smuggle fields the renderers never show. */
+function findingOf(value: Record<string, unknown>, at: string): Finding {
+  const docs = value['docs'];
+  const located = value['at'];
+  return {
+    code: value['code'] as string,
+    cause: value['cause'] as string,
+    fix: value['fix'] as string,
+    ...(typeof docs === 'string' ? { docs } : {}),
+    at: typeof located === 'string' && located !== '' ? located : at,
+  };
+}
+
+/**
+ * Every guard file, app-root-relative and sorted, so two machines report the same findings in the
+ * same order. A `*.test.ts` beside a guard is its test, never a second guard — the generator emits
+ * one, and importing it would run the suite inside the gate.
+ */
+export async function guardPaths(root: string): Promise<readonly string[]> {
+  const dir = join(root, GUARD_DIR);
+  if (!existsSync(dir)) return [];
+  const paths: string[] = [];
+  for await (const entry of new Bun.Glob('*.{ts,tsx}').scan({ cwd: dir, absolute: false })) {
+    const path = entry.split('\\').join('/');
+    if (/\.(?:test|d)\.tsx?$/.test(path)) continue;
+    paths.push(`${GUARD_DIR}/${path}`);
+  }
+  return paths.sort();
+}
+
+const failed = (path: string, cause: string): Finding => ({
+  code: 'X_GUARD_FAILED',
+  cause,
+  fix: `return a finding from ${path} instead of throwing, then: x verify`,
+  docs: 'https://ultimate.dev/errors/X_GUARD_FAILED',
+  at: path,
+});
+
+const invalid = (path: string, cause: string): Finding => ({
+  code: 'X_GUARD_INVALID',
+  cause,
+  fix: `export a \`guard\` object — { summary, check } — from ${path}, then: x verify`,
+  docs: 'https://ultimate.dev/errors/X_GUARD_INVALID',
+  at: path,
+});
+
+const findingInvalid = (path: string, cause: string): Finding => ({
+  code: 'X_GUARD_FINDING_INVALID',
+  cause: `${path} returned a finding that is not one: ${cause}`,
+  fix: `rewrite what ${path} returns as a code, a cause and a fix naming a command or a file, then: x verify`,
+  docs: 'https://ultimate.dev/errors/X_GUARD_FINDING_INVALID',
+  at: path,
+});
+
+/** Same reason as `shown`: an app's guard may throw a value that fights every way of reading it. */
+const messageOf = (error: unknown): string => renderThrowable(error);
+
+/** One guard: import it, run it, and hold what it returns to the contract. Never throws. */
+async function runGuard(root: string, path: string): Promise<readonly Finding[]> {
+  let loaded: unknown;
+  try {
+    loaded = await import(pathToFileURL(join(root, path)).href);
+  } catch (error) {
+    return [failed(path, `${path} could not be imported: ${messageOf(error)}`)];
+  }
+  const exported = isRecord(loaded) ? loaded['guard'] : undefined;
+  if (!isGuard(exported)) {
+    return [
+      invalid(
+        path,
+        exported === undefined
+          ? `${path} exports no \`guard\`, so a file in ${GUARD_DIR}/ enforces nothing`
+          : `${path} exports a \`guard\` with no summary and no check()`,
+      ),
+    ];
+  }
+  let returned: unknown;
+  try {
+    returned = await exported.check(root);
+  } catch (error) {
+    return [failed(path, `${path} ("${exported.summary}") threw: ${messageOf(error)}`)];
+  }
+  if (!Array.isArray(returned)) {
+    return [findingInvalid(path, `check() answered ${typeof returned}, not a list of findings`)];
+  }
+  const findings: Finding[] = [];
+  for (const candidate of returned as readonly unknown[]) {
+    // Reading a candidate can throw on its own — a getter that raises, a proxy that refuses — and
+    // `findingProblem` is total only for values it can read. Per candidate, so one unreadable
+    // entry costs its own line and not the readable findings beside it.
+    try {
+      const problem = findingProblem(candidate);
+      if (problem !== undefined) findings.push(findingInvalid(path, problem));
+      else findings.push(findingOf(candidate as Record<string, unknown>, path));
+    } catch (error) {
+      findings.push(findingInvalid(path, `it could not be read: ${messageOf(error)}`));
+    }
+  }
+  return findings;
+}
+
+/**
+ * Every guard this app declares, as findings the step it rides on adds to its own. Typed as a
+ * `HostCheck` because that is exactly the seam's shape — a rule the repo enforces on itself,
+ * contributed to a step that already exists. A guard can never add, remove, reorder or skip a
+ * step, which is what keeps "green" meaning one thing (axiom 5) while the app still gets to make
+ * its own convention a build error.
+ */
+export const guardFindings: HostCheck = async (root) => {
+  const findings: Finding[] = [];
+  for (const path of await guardPaths(root)) findings.push(...(await runGuard(root, path)));
+  return findings;
+};