@ultimat3/cli 10.0.0 → 11.0.0

package/src/error-pages.ts

@@ -0,0 +1,79 @@
+// The app's own error page, which only a process with a disk can find: `@ultimat3/http` renders the
+// framework's and declares the seam, this file is the half that reads a file. Rails' `public/404.html`,
+// one directory further in — `apps/web/site/` is already where an app's public files live, which is
+// where `favicon.ico` is overridden too.
+
+// why: Bun exposes no path-join primitive, and the source path is app-root-relative — the same
+// necessity `favicon.ts` records for `FAVICON_SOURCE`.
+import { join } from 'node:path';
+import { renderErrorPage } from '@ultimat3/http';
+import { currentLocale } from '@ultimat3/i18n';
+
+/**
+ * One file per status, named by the status, and NO generic `error.html` beside it: a second rung
+ * would need a precedence rule, and a `{{status}}` slot would be a template language the framework
+ * does not otherwise have. An app that wants one page for three statuses writes three files.
+ */
+export const ERROR_PAGE_DIR = 'apps/web/site/errors';
+
+/** What `x verify`, a `fix:` and this reader all name — never spelled twice. */
+export const errorPageSource = (status: number): string =>
+  `${ERROR_PAGE_DIR}/${String(status)}.html`;
+
+/**
+ * What a static host serves for a path that matches no file. `404.html` at the export root is the
+ * convention S3, Cloudflare Pages, Netlify and nginx already look for, so the artifact needs no
+ * configuration to answer the way the served process does.
+ */
+export const STATIC_ERROR_PAGE = '404.html';
+
+/** A status a `Response` can carry. A number outside it never becomes a path. */
+const isStatus = (status: number): boolean =>
+  Number.isInteger(status) && status >= 100 && status <= 599;
+
+/**
+ * The app's page for one status, or `undefined`.
+ *
+ * Read per REQUEST, never cached at boot, for `favicon.ts`'s reason: `x dev` is a running process
+ * an author drops a file into, and a reader that captured "there was none" at startup would keep
+ * answering the framework's page until the server was restarted.
+ */
+export async function errorPageOverride(root: string, status: number): Promise<string | undefined> {
+  if (!isStatus(status)) return undefined;
+  const file = Bun.file(join(root, errorPageSource(status)));
+  return (await file.exists()) ? file.text() : undefined;
+}
+
+/**
+ * `ServerHooks.errorPage`, bound to one app root. Installed by `startWeb` so `x dev` and the
+ * container cannot answer a browser differently — the rule `assetRoutes` already holds for
+ * `/favicon.ico`.
+ */
+export const errorPageHook =
+  (root: string) =>
+  (status: number): Promise<string | undefined> =>
+    errorPageOverride(root, status);
+
+/**
+ * The document that goes into a static export: the app's file if it has one, the framework's page
+ * otherwise. Its own function because the export has no process to ask, exactly as `faviconBytes`
+ * is — a second rule for which page a static build carries would be an artifact that disagrees
+ * with the server it was built from.
+ *
+ * No request id and no pathname: nothing about this file is per-request, and the renderer omits
+ * both rather than inventing them.
+ */
+export async function errorPageDocument(root: string, status: number): Promise<string> {
+  const own = await errorPageOverride(root, status);
+  return (
+    own ??
+    renderErrorPage({
+      status,
+      // What the served 404 carries, so the artifact and the process name one code.
+      code: 'X_ROUTE_NOT_FOUND',
+      // The app's default, resolved after `loadApp` registered its catalogs — a build has no
+      // request to negotiate against.
+      locale: currentLocale(),
+    })
+  );
+}

package/src/errors.ts

@@ -2,6 +2,7 @@
 // that resolves it — the codes themselves, their titles and their registration are `./error-codes`,
 // so a package importing a class does not pull the table and vice versa.
 import { UltimateError } from '@ultimat3/core';
+import { quoteArg } from './shell-quote';
 
 /** An unknown command or subcommand. Carries a suggestion so the retry is one keystroke away. */
 export class UnknownCommandError extends UltimateError {
@@ -47,6 +48,30 @@ export class MissingPositionalError extends UltimateError {
   }
 }
 
+/**
+ * `x new /srv/apps/shop` — a PATH where a NAME goes.
+ *
+ * `names()` slugifies whatever it is given, so the separators became hyphens and the whole path
+ * turned into ONE directory inside the cwd: `x new /tmp/probe/vision` wrote `tmp-probe-vision`
+ * into the current directory and `git init`-ed it there. Nothing failed, and the app the caller
+ * asked for did not exist.
+ *
+ * `--dir` is the flag that takes a path, so the two are one flag apart and the fix is the
+ * invocation the caller meant — built from what they typed, never a placeholder.
+ */
+export class AppNameIsPathError extends UltimateError {
+  constructor(input: { name: string; parent: string; base: string; invocation?: string }) {
+    // The invocation the caller typed, not the literal `x new`: the same command is the whole of
+    // `bunx create-ultimate`, which runs before `x` is installed.
+    const invocation = input.invocation ?? 'x new';
+    super({
+      code: 'X_CLI_BAD_FLAG',
+      cause: `"${invocation}" takes a NAME and got the path "${input.name}" — it would be slugified into one directory name`,
+      fix: `${invocation} ${quoteArg(input.base)} --dir ${quoteArg(input.parent)}`,
+    });
+  }
+}
+
 /**
  * A command that declares subcommands, invoked with none and declaring no `defaultSubcommand`.
  *

package/src/favicon.ts

@@ -0,0 +1,113 @@
+// `/favicon.ico`, which every browser requests unprompted and no Ultimate app answered: the
+// scaffold wrote no file and neither served surface mounted a route, so a permanent 404 sat in the
+// console of every app the framework produces. The app's own file wins; the framework answers when
+// there is none, so an app inherits a clean console rather than a file it has to remember to add.
+
+// why: Bun exposes no path-join primitive, and `FAVICON_SOURCE` is app-root-relative, so resolving
+// it against the root is string work no `Bun.file` overload does — the same necessity
+// `dev-assets.ts` records for `ICON_SOURCE`.
+import { join } from 'node:path';
+import { createRaster, encodeImage } from '@ultimat3/core';
+import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';
+import { applyCacheHeaders } from '@ultimat3/http';
+
+/** What a browser asks for with no `<link rel="icon">` to tell it otherwise. */
+export const FAVICON_PATH = '/favicon.ico';
+
+/**
+ * The one file an app overrides it with — beside `ICON_SOURCE`, in the same directory, because
+ * `apps/web/site/` is already where an app's public files live. One path, never a search order: a
+ * mechanism that accepted `favicon.png` too would be two ways to do one thing, and an app whose
+ * icon is not there would have to be told which of them won.
+ */
+export const FAVICON_SOURCE = 'apps/web/site/favicon.ico';
+
+/** 32px, which is what a browser tab and a bookmark bar both ask for. */
+const DEFAULT_SIZE = 32;
+
+/**
+ * Not a colour: one mid-grey LEVEL written to all three channels, exactly as
+ * `templates/scaffold-icon.ts` argues — `@ultimat3/ui` owns the colour roles and `cli -> ui` is a
+ * boundary error, so a placeholder here must claim no brand colour to begin with.
+ */
+const MARK_LEVEL = 128;
+const OPAQUE = 255;
+
+const FAVICON_CACHE: CacheHint = { mode: 'public', maxAgeSeconds: 3600 };
+
+/**
+ * The framework's answer when the app declares none: a solid 32x32 PNG, encoded through
+ * `@ultimat3/core`'s own pipeline rather than shipped as an opaque blob — the same encoder
+ * `x new`'s icon goes through, so there is no second image format in the tree and no base64
+ * constant nobody can verify. Served as `image/png` under an `.ico` URL, which every browser reads
+ * by content type; a real ICO container would be a fourth format for one placeholder.
+ *
+ * Deliberately NOT derived from `ICON_SOURCE`: resizing the app's install icon needs
+ * `@ultimat3/pwa`'s pipeline and would make the answer depend on a file that may be missing, which
+ * is a third rung under a mechanism that has exactly two.
+ */
+export function defaultFavicon(): Uint8Array {
+  const raster = createRaster(DEFAULT_SIZE, DEFAULT_SIZE, 'favicon');
+  const { pixels } = raster;
+  for (let i = 0; i < pixels.length; i += 4) {
+    pixels[i] = MARK_LEVEL;
+    pixels[i + 1] = MARK_LEVEL;
+    pixels[i + 2] = MARK_LEVEL;
+    pixels[i + 3] = OPAQUE;
+  }
+  return encodeImage(raster, 'png');
+}
+
+/** Encoded once per process: the bytes are a pure function of two constants. */
+let builtin: Uint8Array | undefined;
+
+const builtinBytes = (): Uint8Array => {
+  builtin ??= defaultFavicon();
+  return builtin;
+};
+
+const iconResponse = (bytes: Uint8Array, contentType: string): Response =>
+  applyCacheHeaders(
+    // Copied, not passed through: a `Uint8Array<ArrayBufferLike>` may be backed by a
+    // `SharedArrayBuffer`, which `Response` does not accept — `dev-assets.ts`'s rule, verbatim.
+    new Response(new Uint8Array(bytes), { headers: { 'content-type': contentType } }),
+    FAVICON_CACHE,
+  );
+
+/** What a surface answers with, and what it says the bytes are. */
+export interface FaviconBytes {
+  readonly bytes: Uint8Array;
+  readonly contentType: string;
+}
+
+/**
+ * Read per REQUEST, never once at boot: `x dev` is a running process an author drops a favicon
+ * into, and a route that captured "there was no file" at startup would keep answering the
+ * placeholder until the server was restarted — the class of dev/prod difference this package's
+ * own header forbids.
+ *
+ * Its own function because the static export has no process to ask: `prerenderSite` writes these
+ * same bytes into the artifact, and a second rule for which favicon a static build carries would
+ * be a build whose tab icon differs from the server's.
+ */
+export async function faviconBytes(root: string): Promise<FaviconBytes> {
+  const own = Bun.file(join(root, FAVICON_SOURCE));
+  if (await own.exists()) return { bytes: await own.bytes(), contentType: 'image/x-icon' };
+  return { bytes: builtinBytes(), contentType: 'image/png' };
+}
+
+export async function faviconResponse(root: string): Promise<Response> {
+  const favicon = await faviconBytes(root);
+  return iconResponse(favicon.bytes, favicon.contentType);
+}
+
+/**
+ * Mounted through `assetRoutes`, so `x dev`, the container and every test that boots either get it
+ * from one place. Public by definition — a browser requests it before anyone has signed in.
+ */
+export const faviconRoute = (root: string): Route => ({
+  method: 'GET',
+  path: FAVICON_PATH,
+  meta: { name: 'assets.favicon', auth: 'public', cache: FAVICON_CACHE, tags: ['assets'] },
+  handler: async (_request: UltimateRequest): Promise<Response> => faviconResponse(root),
+});

package/src/fix-path.ts

@@ -0,0 +1,104 @@
+// The other half of the citation rule: a `fix:` may name a FILE, and nothing resolved it. Only
+// `x <command>` citations were checked (`fix-command.ts`), so a fix telling its reader to open a
+// path that no longer exists — or never did — satisfied every gate the repo has, while a file token
+// is one of the four things that make a fix an instruction at all (`COMMAND_TOKENS`).
+
+// why: Bun exposes no synchronous existence primitive — `Bun.file(p).exists()` is async and answers
+// false for a DIRECTORY, and this rule has to judge both. Delete when Bun ships one.
+import { existsSync } from 'node:fs';
+// why: Bun exposes no path-join or dirname primitive. The same necessity `error-contract.ts`
+// already records for `join`.
+import { dirname, join } from 'node:path';
+
+/**
+ * The extensions a fix line may cite a file by — the SAME set `COMMAND_TOKENS`' file pattern is
+ * built from, exported here so the token that lets a fix count as an instruction and the token this
+ * rule resolves can never drift apart. Two lists would mean a citation that satisfies the first
+ * rule and is invisible to the second, which is the hole this file exists to close.
+ */
+export const CITED_FILE_EXTENSIONS = [
+  'ts',
+  'tsx',
+  'js',
+  'json',
+  'md',
+  'toml',
+  'yaml',
+  'yml',
+  'css',
+  'scss',
+  'sql',
+] as const;
+
+/** `[\w.@-]*\/[\w.@-]+\.(?:ts|…)`, as one source string both rules read. */
+export const FILE_TOKEN_PATTERN = String.raw`[\w.@-]*\/[\w.@-]+\.(?:${CITED_FILE_EXTENSIONS.join('|')})\b`;
+
+/**
+ * A whole path, not the last two segments `FILE_TOKEN_PATTERN` matches: this rule resolves the
+ * citation, so it needs every segment. `*` is in the class because a glob is a citation too.
+ */
+const PATH_CITATION = new RegExp(
+  String.raw`(?:[\w.@*-]+\/)+[\w.@*-]+\.(?:${CITED_FILE_EXTENSIONS.join('|')})\b`,
+  'g',
+);
+
+/** A URL is not a repo path, and `https://ultimate.dev/errors/x.md` is shaped like one. */
+const URL_SPAN = /\b[a-z][\w+.-]*:\/\/\S+/gi;
+
+/**
+ * Whether this repo can judge the citation at all. THREE exclusions, each one a shape that resolves
+ * against something other than the root the gate is running in — reporting any of them would be a
+ * finding nobody can act on:
+ *
+ * - a scoped module specifier (`@ultimat3/ui/global.scss`) resolves through `node_modules`;
+ * - a dot-relative path (`./global.scss`) resolves against the reader's own file, which the fix
+ *   line does not name;
+ * - a path whose PARENT DIRECTORY does not exist here is app-facing by construction — `src/errors.ts`
+ *   means "in the package you are editing", `apps/web/server.ts` and `packages/i18n/catalogs/en.json`
+ *   name directories a generated app has and this repo does not. What is left is the citation this
+ *   root really can answer: a directory that exists, named as holding a file it does not hold.
+ */
+function isJudgeable(token: string, root: string): boolean {
+  if (token.startsWith('@') || token.startsWith('./') || token.startsWith('../')) return false;
+  const star = token.indexOf('*');
+  // A glob's FIXED prefix is what has to exist; the segments a `*` stands for are the answer. Cut
+  // at the separator before the star rather than at the star — `dirname('packages/')` is `.`, and
+  // a glob whose first segment is the wildcard has no prefix to check at all.
+  const cut = star === -1 ? -1 : token.lastIndexOf('/', star);
+  const base = star === -1 ? dirname(token) : token.slice(0, Math.max(cut, 0));
+  return base !== '.' && base !== '' && existsSync(join(root, base));
+}
+
+/** Every path-shaped citation on a fix line that this root can resolve, in the order written. */
+export function pathCitations(fix: string, root: string): readonly string[] {
+  const prose = fix.replaceAll(URL_SPAN, ' ');
+  return [...prose.matchAll(PATH_CITATION)]
+    .map((match) => match[0])
+    .filter((token) => isJudgeable(token, root));
+}
+
+/** A glob matches when at least one file answers it; anything else must exist as written. */
+async function resolves(token: string, root: string): Promise<boolean> {
+  if (!token.includes('*')) return existsSync(join(root, token));
+  for await (const _match of new Bun.Glob(token).scan({ cwd: root, onlyFiles: false })) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * The first path a fix cites that this repo does not have, as one sentence for a `cause:`. One
+ * finding per fix line, never one per token — the same rule `citedCommandProblem` holds to.
+ *
+ * Read off the STATIC form of the fix (the caller blanks `${…}` first): a path assembled at run
+ * time is not a path this can resolve, and guessing at one reports findings nobody can act on.
+ */
+export async function citedPathProblem(fix: string, root: string): Promise<string | undefined> {
+  for (const token of pathCitations(fix, root)) {
+    if (!(await resolves(token, root))) {
+      const kind = token.includes('*') ? 'matches no file' : 'is not a file in this repository';
+      return `cites "${token}", which ${kind}`;
+    }
+  }
+  return undefined;
+}

package/src/hold.ts

@@ -3,7 +3,23 @@
 // before the exit code. Ctrl-C then takes core's own three-phase drain (stop accepting, finish
 // in-flight, close) instead of killing a query mid-round-trip.
 
-import { drain, installSignalHandlers, onShutdown } from '@ultimat3/core';
+import { drain, installSignalHandlers, logger, onShutdown, systemClock } from '@ultimat3/core';
+
+export interface HoldOptions {
+  /**
+   * What to call once the release is done, with `0`. Omit and nothing is called.
+   *
+   * There is exactly one caller: `runRole` in `serve.ts`, which is what `apps/web/server.ts`
+   * awaits — the one entry point with nothing above it to end the process. `bin.ts` ends in
+   * `process.exit(code)`, so `x dev` and `x mcp` need none of this; a container has no such line,
+   * and one non-unref'd interval anywhere in the app then holds an event loop with nothing left to
+   * do until `terminationGracePeriodSeconds` runs out and the kubelet SIGKILLs it.
+   *
+   * A function rather than a boolean because `process.exit` in a library is untestable: this is
+   * the seam the test passes a spy through, and the caller is the one that knows.
+   */
+  readonly exit?: (code: number) => void;
+}
 
 /**
  * Wait for a shutdown, then release what core's lifecycle does not own.
@@ -16,15 +32,29 @@ import { drain, installSignalHandlers, onShutdown } from '@ultimat3/core';
  * `release` runs after the drain completes, so in-flight requests still see the database the
  * handler opened them against. It is the resources core never learned about: the embedded
  * Postgres, the worker, the file watcher.
+ *
+ * It runs INSIDE the drain's own deadline, and that is not a detail. `drain()` ABANDONS a hook
+ * that overruns `ShutdownReason.deadlineAt` — the process is meant to exit without it — and
+ * `release` here re-enters the very same teardown one call later: `app.stop()` ->
+ * `startRoles().stop()` -> `worker.stop()`, memoised in the package that owns it, so awaiting it
+ * is awaiting the promise the drain just walked away from. Unbounded, that hangs forever and the
+ * deadline buys nothing.
  */
-export function holdUntilShutdown(name: string, release: () => Promise<void>): () => Promise<void> {
+export function holdUntilShutdown(
+  name: string,
+  release: () => Promise<void>,
+  options: HoldOptions = {},
+): () => Promise<void> {
   const uninstall = installSignalHandlers({ exit: false });
   let unregister = (): void => {};
-  const shuttingDown = new Promise<void>((resolve) => {
+  // The hook's own `reason`, not a stopwatch of ours: `deadlineAt` is the instant core computed
+  // when the drain began, on the same real monotonic clock, so this budget IS the drain's budget
+  // rather than a second one that happens to be the same length.
+  const shuttingDown = new Promise<number>((resolve) => {
     unregister = onShutdown(
       `cli:${name}:hold`,
-      () => {
-        resolve();
+      (reason) => {
+        resolve(reason.deadlineAt);
       },
       { phase: 'accept' },
     );
@@ -35,14 +65,50 @@ export function holdUntilShutdown(name: string, release: () => Promise<void>): (
     // Memoised: awaiting a hold twice must not release twice, and `dispatch` is not the only
     // caller a test can be.
     held ??= (async () => {
-      await shuttingDown;
+      const deadlineAt = await shuttingDown;
       // Idempotent in core: this joins the drain already in flight and resolves when its last
       // phase is done. Calling it is what makes `release` the step after the drain, not beside it.
       await drain();
       unregister();
       uninstall();
-      await release();
+      await releaseWithin(name, release, deadlineAt - systemClock.monotonic());
+      options.exit?.(0);
     })();
     return held;
   };
 }
+
+/**
+ * `release()` raced against what is left of the drain's budget.
+ *
+ * A local race and not core's `settleWithin`, which is internal to `lifecycle-deadline.ts` and not
+ * on core's barrel. The semantics are deliberately the same, including the one that matters: a
+ * REJECTION still rejects — `dispatch` awaits the hold inside its own `try`, and an embedded
+ * database that would not close is a finding on the way out, never a clean exit over it.
+ *
+ * A budget already spent is `0`, and that abandons immediately by design: past `deadlineAt` the
+ * orchestrator is already counting down to SIGKILL, so the honest move is to say so and exit
+ * rather than to start a second grace period nobody granted.
+ */
+async function releaseWithin(
+  name: string,
+  release: () => Promise<void>,
+  budgetMs: number,
+): Promise<void> {
+  const budget = Math.max(0, budgetMs);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const abandoned = new Promise<'abandoned'>((resolve) => {
+    timer = setTimeout(() => resolve('abandoned'), budget);
+  });
+  try {
+    const outcome = await Promise.race([release().then(() => 'released' as const), abandoned]);
+    if (outcome === 'released') return;
+    logger.warn('X_SHUTDOWN_TIMEOUT', {
+      code: 'X_SHUTDOWN_TIMEOUT',
+      cause: `the "${name}" release was still running ${budget}ms after the drain finished and has been ABANDONED — the process exits without it, so anything it held may not be closed`,
+      fix: 'raise the budget past the slowest teardown — configureLifecycle({ deadlineMs: 600_000 }) for a 10-minute one — and set terminationGracePeriodSeconds to at least as many seconds',
+    });
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}

package/src/index.ts

@@ -116,6 +116,7 @@ export {
 export type { ErrorCatalog } from './error-catalog';
 export {
   buildErrorCatalog,
+  CATALOG_OPTIONAL_HOSTS,
   CATALOG_PACKAGES,
   loadErrorCatalog,
   registeredErrorCodes,
@@ -167,6 +168,13 @@ export {
 } from './errors';
 export type { ExecOptions, ExecResult, Runner } from './exec';
 export { exec, execOutput } from './exec';
+export {
+  defaultFavicon,
+  FAVICON_PATH,
+  FAVICON_SOURCE,
+  faviconResponse,
+  faviconRoute,
+} from './favicon';
 export type { CitationFault, CitationRules, CommandCatalog, FixCitation } from './fix-command';
 export {
   citationFault,
@@ -177,6 +185,12 @@ export {
 } from './fix-command';
 export type { HelperResolver } from './fix-imports';
 export { candidatePaths, createHelperResolver, scanImports } from './fix-imports';
+export {
+  CITED_FILE_EXTENSIONS,
+  citedPathProblem,
+  FILE_TOKEN_PATTERN,
+  pathCitations,
+} from './fix-path';
 export type { FixHelper, FixScan } from './fix-scan';
 export { scanFixes, scanFixHelpers, scanFixSites } from './fix-scan';
 export type { DeclaredFlag } from './flag-reads';

package/src/live-routes.ts

@@ -0,0 +1,181 @@
+// One question only this package can ask: a route SUBSCRIBES to live rows, and does anything on
+// that route ever run in a browser to receive them? `@ultimat3/realtime` cannot see a route and
+// `@ultimat3/render` may not import realtime, so the two halves meet here — beside the island
+// build, which is the other place the route table and the client graph are both in scope.
+//
+// The failure it closes is silent by construction (#271): with no island the page server-renders
+// its `loading` branch, answers 200, and stays that way forever — nothing throws, nothing logs,
+// and every suite passes.
+
+// why: Bun exposes no path API, and a route file's imports are resolved against its own directory.
+import { join, posix } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { RouteEntry } from '@ultimat3/render';
+import { ISLAND_EXTENSION, routeEntries } from '@ultimat3/render';
+import type { Finding } from './output';
+
+/**
+ * The exports that only work with a registered `LiveClient`. Each one either subscribes, mutates
+ * or reads the connection, so a module naming one is a module that needs a browser to have booted
+ * it — `hasLiveClient` and `LiveClient` itself are deliberately absent: the first IS the guard, and
+ * the second is what an island's `mount()` constructs.
+ */
+export const LIVE_HOOKS = [
+  'useLive',
+  'liveHookFor',
+  'useConnection',
+  'useMutation',
+  'useMutationQueue',
+] as const;
+
+/**
+ * The one escape hatch, and it is a call an author writes on purpose: a module that ASKS whether
+ * there is a client has already written what happens when there is none. `app/update-banner.tsx`
+ * in the reference app is the shape — imported by the layout, so by every page, and correct on all
+ * of them.
+ */
+const GUARD = 'hasLiveClient';
+
+/** Value imports only: `import type` is erased, so it boots nothing and needs nothing. */
+const REALTIME_IMPORT = /import\s+([^;]*?)from\s*['"]@ultimat3\/realtime(?:\/[\w-]+)?['"]/g;
+
+const bindingsOf = (clause: string): readonly string[] =>
+  (/\{([^}]*)\}/.exec(clause)?.[1] ?? '')
+    .split(',')
+    .map((entry) => entry.split(/\bas\b/)[0]?.trim() ?? '')
+    .filter((name) => name.length > 0 && !name.startsWith('type '));
+
+/**
+ * Which live hooks one module imports, or `[]` — including for a module that guards, which is a
+ * per-FILE verdict on purpose: the guard is written next to the read it protects.
+ */
+export function liveHooksIn(source: string): readonly string[] {
+  const hooks: string[] = [];
+  for (const match of source.matchAll(REALTIME_IMPORT)) {
+    const clause = match[1] ?? '';
+    if (clause.trimStart().startsWith('type ')) continue;
+    const names = bindingsOf(clause);
+    if (names.includes(GUARD)) return [];
+    for (const hook of LIVE_HOOKS) if (names.includes(hook)) hooks.push(hook);
+  }
+  return hooks;
+}
+
+/** What a relative specifier can be on disk. The list `fix-imports.ts` already resolves against. */
+const candidates = (base: string): readonly string[] => [
+  `${base}.ts`,
+  `${base}.tsx`,
+  `${base}/index.ts`,
+  `${base}/index.tsx`,
+];
+
+async function readModule(
+  root: string,
+  file: string,
+): Promise<{ path: string; source: string } | undefined> {
+  for (const path of file.endsWith('.ts') || file.endsWith('.tsx') ? [file] : candidates(file)) {
+    const handle = Bun.file(join(root, path));
+    if (await handle.exists()) return { path, source: await handle.text() };
+  }
+  return undefined;
+}
+
+/** Where a route's graph first reaches a live hook. */
+export interface LiveReach {
+  /** App-root-relative module that imports it. */
+  readonly at: string;
+  readonly hook: string;
+}
+
+/**
+ * Walk the route module's own import graph and answer the first live hook in it.
+ *
+ * Relative specifiers only. A bare one resolves through `node_modules` or a workspace name, and
+ * following either would mean guessing which package a name came from — the limit `fix-imports.ts`
+ * records for the same walk. So this UNDER-reports rather than over-reports: a finding here is
+ * always a real one, which is what lets the rule ship with no pin table.
+ */
+export async function liveReachOf(root: string, file: string): Promise<LiveReach | undefined> {
+  const seen = new Set<string>();
+  const queue = [file];
+  while (queue.length > 0) {
+    const next = queue.shift();
+    if (next === undefined || seen.has(next)) continue;
+    seen.add(next);
+    const module = await readModule(root, next);
+    if (module === undefined) continue;
+    const hook = liveHooksIn(module.source)[0];
+    if (hook !== undefined) return { at: module.path, hook };
+    const loader = module.path.endsWith('x') ? 'tsx' : 'ts';
+    // Bun's transpiler is the parser, exactly as in `scripts/boundaries.ts`: it erases type-only
+    // imports and finds the dynamic ones, which no regex over this source could do.
+    for (const scanned of new Bun.Transpiler({ loader }).scanImports(module.source)) {
+      if (!scanned.path.startsWith('.')) continue;
+      queue.push(posix.normalize(posix.join(posix.dirname(module.path), scanned.path)));
+    }
+  }
+  return undefined;
+}
+
+export interface LiveRouteGap extends LiveReach {
+  readonly route: string;
+  readonly file: string;
+  /** What the route declares. `'never'` is the second way nothing boots. */
+  readonly hydrate: string;
+  readonly islands: readonly string[];
+}
+
+/** The `x g island` invocation that fixes it, built from this route's own file — never a placeholder. */
+const generatorFor = (file: string): string => {
+  const dir = posix.dirname(file);
+  return `x g island ${posix.basename(dir)} --at ${dir}`;
+};
+
+/**
+ * Every route that reads live rows with nothing to receive them. Two shapes, one condition — no
+ * island at all, and an island the route declares `hydrate: 'never'` for. `X_ISLAND_NOT_HYDRATED`
+ * covers the second only at render time, and only for a render that reaches the island, so a route
+ * can hold the contradiction and never be asked.
+ */
+export async function liveRouteGaps(
+  root: string,
+  entries: readonly RouteEntry[],
+): Promise<readonly LiveRouteGap[]> {
+  const gaps: LiveRouteGap[] = [];
+  for (const entry of entries) {
+    if (entry.surface === 'api') continue;
+    if (entry.islands.length > 0 && entry.config.hydrate !== 'never') continue;
+    const reach = await liveReachOf(root, entry.file);
+    if (reach === undefined) continue;
+    gaps.push({
+      ...reach,
+      route: entry.path,
+      file: entry.file,
+      hydrate: entry.config.hydrate,
+      islands: entry.islands,
+    });
+  }
+  return gaps;
+}
+
+export const liveRouteFindingFor = (gap: LiveRouteGap): Finding => ({
+  code: 'X_LIVE_ROUTE_NO_ISLAND',
+  cause:
+    `${gap.route} reads ${gap.hook}() (${gap.at}) and ` +
+    (gap.islands.length === 0
+      ? 'declares no island'
+      : `declares hydrate: 'never' beside ${gap.islands.join(', ')}`) +
+    ', so no module of this route ever runs in a browser: its rows have nowhere to arrive and the page renders its loading branch forever, at 200',
+  fix:
+    `${generatorFor(gap.file)}, declare it with island({ src: './${posix.basename(posix.dirname(gap.file))}${ISLAND_EXTENSION}' }) above defineRoute in ${gap.file}, ` +
+    `and move the ${gap.hook}() read into its mount() — which is where setLiveClient() can be called`,
+  docs: ERROR_DOCS_URL,
+  at: gap.at,
+});
+
+/**
+ * What this rule contributes to `x verify`'s `budgets` step — the step that already loaded the app
+ * and already asks what JavaScript a route's document boots.
+ */
+export const liveRouteFindings = async (root: string): Promise<readonly Finding[]> =>
+  (await liveRouteGaps(root, routeEntries())).map(liveRouteFindingFor);