@ultimat3/cli 7.0.0 → 8.0.0

package/src/parse.ts

@@ -2,7 +2,19 @@
 // same way and `--json` / `--help` behave identically everywhere. Pure: no I/O, no process
 // access, so the parser is unit-testable and the dispatcher owns all side effects.
 
+import { nearestName } from '@ultimat3/core';
 import { BadFlagError, MissingSubcommandError, UnknownCommandError } from './errors';
+// `shell-quote.ts` is a leaf — it imports nothing — so the parser stays pure and importable from
+// anywhere while still refusing with a fix line a shell reads as one argument.
+import { quoteArg } from './shell-quote';
+
+/**
+ * The historical name for `@ultimat3/core`'s `nearestName`, kept because it shipped on this
+ * package's exported surface and removing it would be a major for a rename. One implementation
+ * behind both — this is a delegation, not the second copy of the algorithm that `@ultimat3/policy`
+ * used to carry. New callers import `nearestName` from core.
+ */
+export const nearest = nearestName;
 
 export type FlagValue = string | boolean;
 
@@ -12,6 +24,15 @@ export interface FlagSpec {
   readonly summary: string;
   readonly short?: string;
   readonly default?: FlagValue;
+  /**
+   * The subcommands that READ this flag, where it is not command-wide. Absent means every one —
+   * opt-in, because most flags really are. Declared from the same fact the summary states, and
+   * enforced: `x db gen --dry-run` parsed, ran the generator and WROTE the migration, because the
+   * parser validates a flag against the COMMAND and nothing then validates it against the word
+   * that decides what runs. A dry run that writes a file is the direction a mistake may never
+   * fail in. `parse.test.ts` pins that every entry names a subcommand its command declares.
+   */
+  readonly subcommands?: readonly string[];
 }
 
 export interface CommandSpec {
@@ -87,41 +108,11 @@ export const wantsJson = (argv: readonly string[]): boolean =>
 const HELP_ALIASES = new Set(['--help', '-h', 'help']);
 const VERSION_ALIASES = new Set(['--version', '-v', '-V']);
 
-function distance(a: string, b: string): number {
-  const rows = a.length + 1;
-  const cols = b.length + 1;
-  const grid: number[] = new Array<number>(rows * cols).fill(0);
-  const at = (r: number, c: number): number => grid[r * cols + c] ?? 0;
-  for (let r = 0; r < rows; r += 1) grid[r * cols] = r;
-  for (let c = 0; c < cols; c += 1) grid[c] = c;
-  for (let r = 1; r < rows; r += 1) {
-    for (let c = 1; c < cols; c += 1) {
-      const cost = a[r - 1] === b[c - 1] ? 0 : 1;
-      grid[r * cols + c] = Math.min(at(r - 1, c) + 1, at(r, c - 1) + 1, at(r - 1, c - 1) + cost);
-    }
-  }
-  return at(rows - 1, cols - 1);
-}
-
-/** Nearest known name within an edit distance of 3, so the error can suggest a retry. */
-export function nearest(input: string, candidates: readonly string[]): string | undefined {
-  let best: string | undefined;
-  let bestScore = 4;
-  for (const candidate of candidates) {
-    const score = distance(input, candidate);
-    if (score < bestScore) {
-      best = candidate;
-      bestScore = score;
-    }
-  }
-  return best;
-}
-
 function resolveCommand(token: string, specs: readonly CommandSpec[]): CommandSpec {
   const found = specs.find((spec) => spec.name === token || (spec.aliases ?? []).includes(token));
   if (found !== undefined) return found;
   const names = specs.map((spec) => spec.name);
-  const suggestion = nearest(token, names);
+  const suggestion = nearestName(token, names);
   throw new UnknownCommandError(
     suggestion === undefined
       ? { path: token, known: names }
@@ -168,6 +159,9 @@ export function parseArgs(argv: readonly string[], specs: readonly CommandSpec[]
   const spec = resolveCommand(first, specs);
   const flags = defaults(spec);
   const positionals: string[] = [];
+  // What argv actually SET, as against what `defaults()` seeded: a default is nobody's request,
+  // and refusing a flag the caller never typed would refuse the command itself.
+  const given = new Set<string>();
   let index = 1;
 
   while (index < tokens.length) {
@@ -183,7 +177,7 @@ export function parseArgs(argv: readonly string[], specs: readonly CommandSpec[]
     const flag = findFlag(name, spec);
     if (flag === undefined) {
       const known = [...GLOBAL_FLAGS, ...(spec.flags ?? [])].map((entry) => entry.name);
-      const suggestion = nearest(name, known);
+      const suggestion = nearestName(name, known);
       throw new BadFlagError({
         flag: name,
         command: spec.name,
@@ -193,6 +187,7 @@ export function parseArgs(argv: readonly string[], specs: readonly CommandSpec[]
             : `unknown flag — did you mean --${suggestion}?`,
       });
     }
+    given.add(flag.name);
     if (flag.type === 'boolean') {
       if (inlineValue !== undefined) {
         throw new BadFlagError({
@@ -204,30 +199,79 @@ export function parseArgs(argv: readonly string[], specs: readonly CommandSpec[]
       flags.set(flag.name, !negated);
       continue;
     }
+    // `--no-<string flag>` used to fall through to the value read below, so `--no-name feat` set
+    // `name` to `feat`: the caller asked for the flag to be OFF and argv's next token became its
+    // value. There is nothing a string flag can be negated to, so this is a refusal.
+    if (negated) {
+      throw new BadFlagError({
+        flag: flag.name,
+        command: spec.name,
+        reason: `--no- negates a boolean flag, and --${flag.name} takes a value`,
+      });
+    }
     const value = inlineValue ?? tokens[index];
-    if (value === undefined || value.startsWith('--')) {
+    if (value === undefined) {
+      throw new BadFlagError({ flag: flag.name, command: spec.name, reason: 'expects a value' });
+    }
+    // A value beginning `--` is a flag as far as this loop can tell, and the caller who really
+    // meant it as a value has one form available — so the refusal names it rather than leaving
+    // `--filter --json` looking like a parser that cannot express the input.
+    if (value.startsWith('--')) {
       throw new BadFlagError({
         flag: flag.name,
         command: spec.name,
-        reason: 'expects a value',
+        reason: `expects a value, and "${value}" is a flag — write --${flag.name}=${value} to pass it as the value`,
       });
     }
     if (inlineValue === undefined) index += 1;
     flags.set(flag.name, value);
   }
 
-  const subcommand = readSubcommand(spec, positionals);
+  // Before `readSubcommand`, which THROWS on a missing or unknown one: `x db --help`, `x mcp
+  // --help` and `x pr --help` all exited 1 with `X_CLI_BAD_FLAG` — usage refused to the caller
+  // asking what the usage is, on every command that takes a subcommand. Help is answered by
+  // `dispatch`, which needs only the command name.
+  const help = flags.get('help') === true;
+  const subcommand = help ? undefined : readSubcommand(spec, positionals);
+  if (subcommand !== undefined) assertFlagsApply(spec, subcommand, given, flags);
   return {
     command: spec.name,
     subcommand,
     positionals: subcommand === undefined ? positionals : positionals.slice(1),
     flags,
     json: flags.get('json') === true,
-    help: flags.get('help') === true,
+    help,
     passthrough,
   };
 }
 
+/**
+ * A flag the resolved subcommand does not read is refused, never ignored. Only what argv SET is
+ * judged, and only against a flag that declared a scope: an undeclared flag stays command-wide.
+ *
+ * The fix carries the caller's own value through `quoteArg`, because it is pasted into a shell
+ * verbatim — `x db backfill --status 'a b'` runs, `--status a b` runs something else.
+ */
+function assertFlagsApply(
+  spec: CommandSpec,
+  subcommand: string,
+  given: ReadonlySet<string>,
+  flags: ReadonlyMap<string, FlagValue>,
+): void {
+  for (const flag of spec.flags ?? []) {
+    const only = flag.subcommands;
+    if (only === undefined || only.includes(subcommand) || !given.has(flag.name)) continue;
+    const value = flags.get(flag.name);
+    const argument = typeof value === 'string' ? ` ${quoteArg(value)}` : '';
+    throw new BadFlagError({
+      flag: flag.name,
+      command: `${spec.name} ${subcommand}`,
+      reason: `read by ${only.map((word) => `x ${spec.name} ${word}`).join(' / ')} only — "${subcommand}" would ignore it`,
+      fix: `x ${spec.name} ${only[0]} --${flag.name}${argument}`,
+    });
+  }
+}
+
 function splitInline(raw: string): [string, string | undefined] {
   const eq = raw.indexOf('=');
   if (eq === -1) return [raw, undefined];
@@ -243,7 +287,7 @@ function readSubcommand(spec: CommandSpec, positionals: readonly string[]): stri
     throw new MissingSubcommandError({ command: spec.name, known: allowed });
   }
   if (allowed.includes(token)) return token;
-  const suggestion = nearest(token, allowed);
+  const suggestion = nearestName(token, allowed);
   throw new UnknownCommandError(
     suggestion === undefined
       ? { path: `${spec.name} ${token}`, known: allowed }

package/src/realtime-browser-probe-fixture.ts

@@ -0,0 +1,9 @@
+// The browser island `wiki/Realtime.md` promises: one live hook and nothing else. It is a real
+// module rather than a string a test writes to a temp path, because module resolution is the thing
+// under test — `@ultimat3/realtime`'s client entry must reach neither the bus nor the WAL decoder.
+// Bundled AND imported by `realtime-browser-barrel.test.ts` — the import is what gives it an lcov
+// record, since `Bun.build()` reads this file without evaluating it.
+
+import { useLive } from '@ultimat3/realtime';
+
+export const probeUseLive = useLive;

package/src/runtime-overrides.ts

@@ -8,7 +8,7 @@ import type { PurgeDriver } from '@ultimat3/cache';
 import type { Middleware, RateLimitStore } from '@ultimat3/http';
 import type { JobDriver } from '@ultimat3/jobs';
 import type { MailDriver } from '@ultimat3/mail';
-import type { SyncAuthenticator, Transport } from '@ultimat3/realtime';
+import type { SyncAuthenticator, Transport } from '@ultimat3/realtime/server';
 import type { IsrStore } from '@ultimat3/render';
 import type { ImageTransformDriver } from '@ultimat3/seo';
 import type { Storage } from '@ultimat3/storage';
@@ -45,6 +45,11 @@ export interface RuntimeOverrides {
    * Where the HTTP rate limiter keeps its counters. It also DECIDES `rateLimit.scope`: a store
    * that says `'shared'` is a deployment declaring fleet-wide numbers, and `assertRateLimitScope`
    * holds the two halves together rather than a literal in the boot contradicting the store.
+   *
+   * Omitted, the boot installs `postgresRateLimitStore` over the pool it already opened
+   * (`startServices`) — so this replaces a SHARED default, not an absent one. A store whose scope
+   * is `'process'` is legal and warned about: it is every declared limit enforced once per
+   * replica, and `docker/helm/values.yaml` runs three.
    */
   readonly rateLimitStore?: RateLimitStore;
   /**
@@ -59,8 +64,11 @@ export interface RuntimeOverrides {
   readonly images?: ImageTransformDriver;
   /**
    * Who is dialling the `sync` node. Omitted, the app's own `configureAuthenticator()` is adapted
-   * — this field exists because that adapter can only ever answer `{ actor }`, and a real
-   * deployment's token has an `expiresAt` and a `refresh`, which is the whole of re-authorization.
+   * — and that adapter now carries `expiresAt` and `refresh` of its own (`SYNC_GRANT_TTL_MS`),
+   * re-asking the app's resolver with the upgrade's own `cookie`/`authorization`. So this field is
+   * no longer the only way to get re-authorization; it is how a deployment states a window the
+   * credential itself declares (a token's `exp`), or resolves identity from a header the adapter
+   * deliberately does not retain per socket.
    */
   readonly syncAuthenticate?: SyncAuthenticator;
 }

package/src/shot-settle.ts

@@ -0,0 +1,57 @@
+// When a shot may be TAKEN: the two rules that decide whether the page has finished hydrating,
+// separated from both the command that drives a browser and the verdict that judges what came
+// back. Plain values and an injected sleep, so the whole loop is proved with neither.
+
+import type { IslandCount } from './shot-verdict';
+
+/**
+ * When there is nothing left to wait for. `booted` counts the islands whose chunk the runtime
+ * ASKED for; `mounted` and `failed` are the two ways that request can end — so the outcome of
+ * every boot exists exactly when they add up to it. An island that never booted is not something
+ * to wait for (`visible` with nothing scrolled to it, `never` by declaration), and `null` is "the
+ * page answered no probe", which no amount of waiting turns into an answer.
+ */
+export const islandsSettled = (islands: IslandCount | null): boolean =>
+  islands === null || islands.mounted + islands.failed >= islands.booted;
+
+/**
+ * How often the island probe is re-read while the page settles. Short enough that a page whose
+ * mounts have already resolved pays one extra read and nothing else.
+ */
+export const SETTLE_POLL_MS = 100;
+
+export interface SettleOptions {
+  /** The extra budget a mount gets AFTER the boot deadline. Bounded: a picture is still owed. */
+  readonly windowMs: number;
+  readonly pollMs: number;
+  /** Injected by the test, so the poll is proved without spending its own window in real time. */
+  readonly sleep?: ((ms: number) => Promise<void>) | undefined;
+}
+
+/**
+ * Read the probe until every booted island has settled, or the window runs out.
+ *
+ * `DEFAULT_SETTLE_MS` is the deadline at which the hydration runtime CALLS `import()` — `mounted`
+ * and `failed` land after it — so a single read at that instant reports `mounted: 0` for a page
+ * that hydrates perfectly and the verdict was taken one tick before the outcome existed. Polling
+ * is the only shape that ends EARLY on a fast page and still bounds a slow one.
+ *
+ * A `null` answer never overwrites a real count: `null` means "not counted", and a probe that
+ * fails once would otherwise turn a page with islands into a page reported to have none.
+ */
+export async function settleIslands(
+  probe: () => Promise<IslandCount | null>,
+  options: SettleOptions,
+): Promise<IslandCount | null> {
+  const sleep = options.sleep ?? ((ms: number): Promise<void> => Bun.sleep(ms));
+  let answer = await probe();
+  let waited = 0;
+  while (!islandsSettled(answer) && waited < options.windowMs) {
+    // At least 1ms, or a `pollMs` of zero is a loop with no exit while the window stands.
+    const step = Math.max(1, Math.min(options.pollMs, options.windowMs - waited));
+    await sleep(step);
+    waited += step;
+    answer = (await probe()) ?? answer;
+  }
+  return answer;
+}

package/src/shot-verdict.ts

@@ -33,6 +33,7 @@ export const SHOT_MESSAGE_KEYS = [
   'cli.shot.canvasUnreadable',
   'cli.shot.islands',
   'cli.shot.islandsUnknown',
+  'cli.shot.islandFailed',
   'cli.shot.network',
   'cli.shot.console',
   'cli.shot.threw',
@@ -176,19 +177,28 @@ const levelCount = (lines: readonly ConsoleLine[], level: ConsoleLine['level']):
   lines.filter((line) => line.level === level).length;
 
 /**
- * `ok` is three conditions, and every one is something a picture cannot show: nothing on the page
- * logged an error, nothing THREW, and the document photographed is the route that was asked for.
+ * `ok` is four conditions, and every one is something a picture cannot show: nothing on the page
+ * logged an error, nothing THREW, no island's `mount()` REJECTED, and the document photographed is
+ * the route that was asked for.
  *
  * The throw is its own clause rather than folded into `errors` because an uncaught exception calls
  * no console method — a page whose island died can log nothing at all, and `errors === 0` would
- * then pass it. A redirect is a failure of the CAPTURE rather than of the app: an agent that
+ * then pass it. A rejected mount is a third silent one and was read by NOTHING until 2026-08-22:
+ * the prelude pays 129 B an island to write `data-x-failed`, the probe counted it into the
+ * artifact, and every island on a page could reject while the run reported "clean". `?? 0` keeps
+ * an uncounted probe (`null`) out of the verdict — "not counted" is not "none failed".
+ * A redirect is a failure of the CAPTURE rather than of the app: an agent that
  * photographs the sign-in page and files "the island did not mount" is the outcome this prevents.
  */
 export function buildVerdict(input: ShotInput): ShotVerdict {
   const errors = levelCount(input.console, 'error');
   return {
     ...input,
-    ok: errors === 0 && input.pageErrors.length === 0 && input.requestedUrl === input.finalUrl,
+    ok:
+      errors === 0 &&
+      input.pageErrors.length === 0 &&
+      (input.islands?.failed ?? 0) === 0 &&
+      input.requestedUrl === input.finalUrl,
     redirected: input.requestedUrl !== input.finalUrl,
     errors,
     warnings: levelCount(input.console, 'warn'),
@@ -328,6 +338,19 @@ export const shotSummary = (verdict: ShotVerdict): string => {
       first: verdict.pageErrors[0]?.message ?? '',
     });
   }
+  // Ahead of the console count for the same reason, and it is the same silence: a rejected mount
+  // promise calls no console method either, so a page whose every island died can read `errors: 0`.
+  // The first failure is NAMED — "1 island failed" sends a reader back to the artifact for the one
+  // fact they need to start.
+  const failure = verdict.islands?.failures[0];
+  if (failure !== undefined) {
+    return msg('cli.shot.islandFailed', {
+      route: verdict.route,
+      failed: verdict.islands?.failed ?? 0,
+      island: failure.island,
+      message: failure.message,
+    });
+  }
   if (verdict.errors > 0) {
     return msg('cli.shot.errors', { route: verdict.route, errors: verdict.errors });
   }

package/src/sync-authenticator.ts

@@ -4,7 +4,8 @@
 // per-tenant subscription cap all decided against an anonymous actor. Realtime was single-tenant
 // by wiring, not by design.
 
-import type { Actor } from '@ultimat3/core';
+import type { Actor, Clock } from '@ultimat3/core';
+import { systemClock } from '@ultimat3/core';
 import type { HttpConfig } from '@ultimat3/http';
 import {
   configuredAuthenticator,
@@ -12,7 +13,37 @@ import {
   defineHttpConfig,
   UltimateRequest,
 } from '@ultimat3/http';
-import type { SyncAuthenticator, SyncGrant } from '@ultimat3/realtime';
+import type { SyncAuthenticator, SyncGrant } from '@ultimat3/realtime/server';
+
+/**
+ * How long one grant stands before the node re-decides it.
+ *
+ * A grant with no expiry never appears in `GrantBook.expired()`, so `sweepGrants` — the only path
+ * to `hub.onActorChange` and `registry.reauthorize` — never fired for a socket this adapter opened.
+ * `logout`, `revokeSession`, `disableUser` and `updatePrivileges` closed the HTTP session and never
+ * the websocket, and the client's 15s heartbeat beats the 120s idle sweep, so the socket stayed up
+ * with the revoked actor's authority for as long as the tab was open.
+ *
+ * Five minutes, against `DEFAULT_REAUTH_INTERVAL_MS` (30s): the window a revoked actor keeps its
+ * socket is this plus one sweep, and the cost is one resolver call per socket per window — 167/s
+ * on the 50,000-socket node this repo has measured, against 1,667/s at a 30s TTL. A deployment
+ * whose credential has a shorter real lifetime passes `runtime.syncAuthenticate` and states it.
+ */
+export const SYNC_GRANT_TTL_MS = 5 * 60_000;
+
+/**
+ * The credential this adapter retains per socket, and nothing else.
+ *
+ * `sync-auth.ts` says the seam is a closure precisely so a node does not hold one `Request` per
+ * connection for the life of that connection: `SyncSocket`'s budget is ~1KB and the grant sits
+ * beside it. Two header values is what an app that closes over a token string would hold.
+ *
+ * Dropping the rest can only make a refresh MORE restrictive, never more permissive: an app that
+ * resolves identity from some other header sees its refresh answer `null`, which closes the socket
+ * with `1008` and the client re-dials carrying that header again. One reconnect per window, not an
+ * escalation — and `runtime.syncAuthenticate` is the declared seam for stating something else.
+ */
+const CREDENTIAL_HEADERS = ['cookie', 'authorization'] as const;
 
 /**
  * The upgrade request, dressed as the request an `Authenticator` reads.
@@ -27,33 +58,74 @@ function upgradeConfig(buildId: string): HttpConfig {
   return defineHttpConfig({ buildId, rateLimit: { enabled: false, scope: 'process' } });
 }
 
+/** What the closure keeps: enough to ask the app's resolver the same question a second time. */
+interface Credential {
+  readonly url: string;
+  readonly method: string;
+  readonly headers: Headers;
+}
+
+function credentialOf(request: Request): Credential {
+  const headers = new Headers();
+  for (const name of CREDENTIAL_HEADERS) {
+    const value = request.headers.get(name);
+    if (value !== null) headers.set(name, value);
+  }
+  return { url: request.url, method: request.method, headers };
+}
+
+export interface SyncAuthenticatorOptions {
+  /** The clock a grant's window is measured on. Injected so a re-auth is provable without sleeping. */
+  readonly clock?: Clock;
+  /** Overrides `SYNC_GRANT_TTL_MS`. A test names its own window; nothing in the boot passes one. */
+  readonly ttlMs?: number;
+}
+
 /**
  * What the sync node is given when the app configured an authenticator, and `undefined` when it
  * did not — which keeps `x dev` anonymous and makes the node log that it is, exactly as
  * `createSyncNode` documents. A stub that answered `{ actor: anonymous }` would look configured.
  *
- * The grant carries **no `expiresAt` and no `refresh`**, and that is the honest limit of this
- * adapter rather than an omission: `configureAuthenticator()` resolves an `Actor` and says nothing
- * about how long it stays true, so inventing a window here would either close live sockets that
- * are still authorized or claim a lifetime the app never promised. A deployment whose credential
- * has a real expiry passes `runtime.syncAuthenticate` and gets re-authorization; the timer for it
- * already lives in `createSyncNode.start()`.
+ * The grant carries an `expiresAt` and a `refresh`, and both are the app's own resolver asked
+ * again: `configureAuthenticator` says who is dialling, and the only honest way to learn that it
+ * has stopped being true is to ask. A `null` second answer is a revocation the node turns into a
+ * `1008`; a THROW is a backend failure, and `sweepGrants` keeps the grant and retries — the
+ * adapter must not collapse those two, here or on the refresh path.
  */
-export function syncAuthenticator(buildId: string): SyncAuthenticator | undefined {
+export function syncAuthenticator(
+  buildId: string,
+  options: SyncAuthenticatorOptions = {},
+): SyncAuthenticator | undefined {
   const authenticate = configuredAuthenticator();
   if (authenticate === undefined) return undefined;
   // Once per node, not once per upgrade: resolving a config is pure and a 50k-socket node pays
   // this per connection otherwise.
   const config = upgradeConfig(buildId);
-  return async (request: Request): Promise<SyncGrant | null> => {
+  const clock = options.clock ?? systemClock;
+  const ttlMs = options.ttlMs ?? SYNC_GRANT_TTL_MS;
+
+  const resolve = async (credential: Credential): Promise<SyncGrant | null> => {
+    const request = new Request(credential.url, {
+      method: credential.method,
+      headers: credential.headers,
+    });
     const ctx = createRequestContext({
-      url: new URL(request.url),
-      method: request.method,
+      url: new URL(credential.url),
+      method: credential.method,
       role: 'sync',
       config,
-      requestHeaders: request.headers,
+      requestHeaders: credential.headers,
     });
     const actor: Actor | null = await authenticate(new UltimateRequest(request, ctx), ctx);
-    return actor === null ? null : { actor };
+    if (actor === null) return null;
+    return {
+      // The window is measured from the answer, not from the upgrade: a refreshed grant that
+      // returned its original instant would be expired again on the very next pass.
+      actor,
+      expiresAt: clock.now().getTime() + ttlMs,
+      refresh: () => resolve(credential),
+    };
   };
+
+  return async (request: Request): Promise<SyncGrant | null> => resolve(credentialOf(request));
 }

package/src/templates/guard-bare-error.ts

@@ -0,0 +1,122 @@
+// The `bare-error` guard `x new` ships: no shipped module throws a bare `Error`.
+// `AGENTS.md` has always stated the rule and NOTHING enforced it — `throw new Error(...)` in a
+// scaffolded `repo.ts` was green on `x verify`, and it reaches an agent as a stack trace with no
+// code, no cause and nothing to run.
+
+import { guardCode } from './guard';
+import type { GeneratedFile } from './naming';
+
+/**
+ * Derived from the guard's name, never written as a literal — the same rule `x g guard` follows.
+ * An `X_*` literal in framework source is a FRAMEWORK code: `error-catalog.test.ts` refuses one the
+ * registry does not hold, and `wiki/Error-Codes.md` would owe it a row. The APP owns the codes its
+ * own conventions raise, so this one is spelled by the file it lands in and nowhere else.
+ */
+const NAME = 'bare-error';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// bare-error: a failure this app raises carries a code, a cause and an executable fix.
+// \`x verify\` discovers every file in \`guards/\` and runs its \`guard\` inside the \`boundaries\`
+// step — nothing registers this file, so nothing can forget to.
+
+import type { Finding, Guard } from '@ultimat3/cli';
+
+/** The app owns the codes its own conventions raise — this one is named for the guard. */
+const CODE = '${CODE}';
+
+/**
+ * A THROW, never a construction. \`new Error(…)\` handed to something as INPUT is legitimate — a
+ * test fixture, an \`AbortSignal\` reason, a rejection this module is passing along — and only the
+ * throw is this module stating its own verdict.
+ */
+const BARE_THROW = /\\bthrow\\s+new\\s+(Error|TypeError|RangeError|SyntaxError)\\s*\\(/g;
+
+export interface SourceFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly source: string;
+}
+
+/** Comments blanked IN PLACE — not deleted — so a reported line number still points at the source. */
+const blank = (text: string): string =>
+  text
+    .replaceAll(/\\/\\*[\\s\\S]*?\\*\\//g, (match) => match.replaceAll(/[^\\n]/g, ' '))
+    .replaceAll(/(?<![:\\w])\\/\\/[^\\n]*/g, (match) => ' '.repeat(match.length));
+
+const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function bareThrows(files: readonly SourceFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const text = blank(file.source);
+    for (const match of text.matchAll(BARE_THROW)) {
+      const line = lineOf(text, match.index);
+      const thrown = match[1] ?? 'Error';
+      findings.push({
+        code: CODE,
+        cause: \`\${file.path}:\${line} throws a bare \${thrown} — it reaches its reader as a stack trace with no code, no cause and nothing to run\`,
+        fix: \`subclass UltimateError in \${file.path} with an X_SCREAMING_SNAKE code, a cause and a fix naming a command, then: x verify\`,
+        at: file.path,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a failure carries a code, a cause and an executable fix — never a bare Error',
+  async check(root) {
+    const files: SourceFile[] = [];
+    for await (const entry of new Bun.Glob('{apps,packages}/**/*.{ts,tsx}').scan({
+      cwd: root,
+      absolute: false,
+    })) {
+      const path = entry.split('\\\\').join('/');
+      // A test states its verdict with \`expect.unreachable()\`, which the suite reports on its own
+      // terms; \`node_modules\` is not this app's source.
+      if (path.includes('node_modules/') || /\\.(?:test|d)\\.tsx?$/.test(path)) continue;
+      files.push({ path, source: await Bun.file(\`\${root}/\${path}\`).text() });
+    }
+    return bareThrows(files);
+  },
+};
+`;
+
+const test =
+  (): string => `// The rule, driven directly. Failure case first: a guard whose rule silently stopped matching is
+// a green gate over the convention it was written to enforce.
+
+import { expect, unitTest } from '@ultimat3/testing';
+import { bareThrows } from './bare-error';
+
+const file = (source: string) => [{ path: 'apps/web/app/post/repo.ts', source }];
+
+unitTest('a bare throw is refused, and the finding names the line', () => {
+  const findings = bareThrows(file("const x = 1;\\nthrow new Error('no post');"));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.cause).toContain(':2');
+});
+
+unitTest('TypeError and RangeError are the same rule', () => {
+  expect(bareThrows(file("throw new TypeError('x');"))).toHaveLength(1);
+  expect(bareThrows(file("throw new RangeError('x');"))).toHaveLength(1);
+});
+
+unitTest('an UltimateError subclass is what the rule asks for', () => {
+  expect(bareThrows(file('throw new PostError(missingPost(id));'))).toEqual([]);
+});
+
+unitTest('a bare Error that is INPUT is not a verdict', () => {
+  expect(bareThrows(file("controller.abort(new Error('cancelled'));"))).toEqual([]);
+  expect(bareThrows(file("// throw new Error('x');"))).toEqual([]);
+});
+`;
+
+/** `guards/bare-error.ts` and its test. No index, no registry — the directory registers it. */
+export const bareErrorGuardFiles = (): readonly GeneratedFile[] => [
+  { path: 'guards/bare-error.ts', contents: source() },
+  { path: 'guards/bare-error.test.ts', contents: test() },
+];