@ultimat3/cli 9.0.0 → 11.0.0

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/flag-reads.ts

@@ -9,7 +9,7 @@
 
 // `join`/`relative` are `node:`-only by necessity: Bun exposes no path-join primitive.
 import { join, relative } from 'node:path';
-import { docsFor } from './error-codes';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Finding } from './output';
 import type { CommandSpec, FlagSpec } from './parse';
 import { GLOBAL_FLAGS } from './parse';
@@ -64,7 +64,7 @@ const unreadFinding = (declared: DeclaredFlag, at: string): Finding => ({
   code: 'X_CLI_FLAG_UNREAD',
   cause: `x ${declared.command} declares --${declared.flag.name} ("${declared.flag.summary}") and no file in the CLI's source reads it, so the flag parses and changes nothing`,
   fix: `read it in ${at} with flag${declared.flag.type === 'boolean' ? 'Bool' : 'String'}(ctx.args, '${declared.flag.name}'), or delete it from the spec's flags`,
-  docs: docsFor('X_CLI_FLAG_UNREAD'),
+  docs: ERROR_DOCS_URL,
   at,
 });
 

package/src/generate-write.ts

@@ -7,6 +7,7 @@
 // app root, and `node:path` is the only API that resolves one. `node:fs` for the exists check.
 import { existsSync } from 'node:fs';
 import { resolve, sep } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import { GenerateJsonInvalidError, ScaffoldPathEscapeError } from './errors';
 import { mergeJsonDeep } from './json-merge';
 import type { Finding } from './output';
@@ -125,7 +126,7 @@ async function planJsonMerge(
         code: 'X_GENERATE_CONFLICT',
         cause: `${file.path} exists but is not a JSON object, so its keys cannot be merged`,
         fix: `edit ${file.path} by hand until it parses as a JSON object, or delete it and re-run x g`,
-        docs: 'https://ultimate.dev/errors/X_GENERATE_CONFLICT',
+        docs: ERROR_DOCS_URL,
         at: file.path,
       },
     };
@@ -178,7 +179,7 @@ function planFile(
         // when run, and a `fix:` is copied and pasted verbatim. Same construction as
         // `generate-kinds.ts`'s `assertSurfaceSupported`.
         fix: `${invocation} --force   # overwrites ${file.path}, or pass a different name`,
-        docs: 'https://ultimate.dev/errors/X_GENERATE_CONFLICT',
+        docs: ERROR_DOCS_URL,
         at: file.path,
       },
     };

package/src/guards.ts

@@ -9,7 +9,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { renderCauseValue, renderThrowable } from '@ultimat3/core';
+import { ERROR_DOCS_URL, renderCauseValue, renderThrowable } from '@ultimat3/core';
 import { fixProblem } from './error-contract';
 import type { Finding } from './output';
 import type { HostCheck } from './verify-step';
@@ -105,7 +105,7 @@ 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',
+  docs: ERROR_DOCS_URL,
   at: path,
 });
 
@@ -113,7 +113,7 @@ 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',
+  docs: ERROR_DOCS_URL,
   at: path,
 });
 
@@ -121,7 +121,7 @@ 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',
+  docs: ERROR_DOCS_URL,
   at: path,
 });
 

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';
@@ -221,12 +235,7 @@ export {
 } from './output';
 export type { CommandSpec, FlagSpec, ParsedArgs } from './parse';
 export { flagBool, flagList, flagString, GLOBAL_FLAGS, nearest, parseArgs } from './parse';
-export type {
-  PrerenderedPage,
-  PrerenderOptions,
-  PrerenderReport,
-  UnmeasuredRoute,
-} from './prerender';
+export type { PrerenderedPage, PrerenderOptions, PrerenderReport } from './prerender';
 export { DEFAULT_ORIGIN, isPrerenderable, prerenderSite } from './prerender';
 export { COMMANDS, cliVersion, commandFor, SPECS } from './registry';
 export type { MigratedApp, ServedApp, ServeOptions, StartedApp } from './serve';
@@ -254,6 +263,7 @@ export type {
   SkippedRoute,
   SkipReason,
   StaticReport,
+  UnmeasuredRoute,
 } from './static-report';
 export {
   parseStaticReport,

package/src/island-bundle.ts

@@ -6,6 +6,7 @@
 // Bun ships no path API. `posix` does the specifier arithmetic (an app-relative route file is
 // POSIX by construction), `join`/`basename` the filesystem side.
 import { basename, join, posix, relative, sep } from 'node:path';
+import { renderThrowable } from '@ultimat3/core';
 import { ISLAND_EXTENSION, IslandInvalidError, islandModuleId } from '@ultimat3/render';
 import { contentHash } from '@ultimat3/render/server';
 import { IslandBuildFailedError } from './errors';
@@ -118,11 +119,38 @@ async function buildOne(root: string, file: string): Promise<IslandChunk> {
  * import or syntax error, and flattening them is what puts the line number in the cause instead of
  * the word "Bundle failed".
  */
-function describeBuildError(error: unknown): string {
-  if (error instanceof AggregateError) {
-    return error.errors.map((one: unknown) => String(one)).join('; ');
+export function describeBuildError(error: unknown): string {
+  // `renderThrowable`, never `instanceof` + `.message` + `String()`. All three run on a value this
+  // process did not build — a `Proxy` traps `getPrototypeOf`, a `message` getter can raise, and
+  // `String()` throws outright on a Symbol — and what comes back is carried in
+  // `IslandBuildFailedError.logs`, which `errors.ts` interpolates straight into a `cause:`. That
+  // is a cross-file hop neither `scripts/catch-render.ts` nor `scripts/error-render.ts` can
+  // follow: a throw here loses the whole refusal and replaces it with a TypeError about reporting.
+  //
+  // The AggregateError branch stays, and it is the reason this function exists: `Bun.build` packs
+  // one entry per unresolved import or syntax error into `errors`, and flattening them is what
+  // puts a line number in the cause instead of the words "Bundle failed". `stringField` decides
+  // whether the value really is that shape, because `instanceof` is a question a Proxy answers.
+  const aggregate = aggregatedErrors(error);
+  if (aggregate !== undefined && aggregate.length > 0) {
+    return aggregate.map((one: unknown) => renderThrowable(one)).join('; ');
+  }
+  return renderThrowable(error);
+}
+
+/**
+ * `value.errors`, read the way `@ultimat3/core`'s `stringField` reads a string field: narrowed
+ * first, dereferenced inside a `try`, `undefined` for anything else. `instanceof AggregateError`
+ * is a question a `Proxy` answers with its own `getPrototypeOf` trap, so it is not a check.
+ */
+function aggregatedErrors(value: unknown): readonly unknown[] | undefined {
+  if (typeof value !== 'object' || value === null) return undefined;
+  try {
+    const held: unknown = (value as Record<string, unknown>)['errors'];
+    return Array.isArray(held) ? held : undefined;
+  } catch {
+    return undefined;
   }
-  return error instanceof Error ? error.message : String(error);
 }
 
 export interface BuildIslandsOptions {

package/src/island-routes.ts

@@ -34,7 +34,13 @@ export function islandRoutes(source: IslandSource): readonly Route[] {
               error: {
                 code: 'X_ROUTE_NOT_FOUND',
                 cause: `no island chunk is built at ${request.pathname} — the document that asked for it was rendered against an older build`,
-                fix: 'x build --target static --json   # then reload, so the page carries this build’s chunk URLs',
+                // No `x` citation, deliberately — `dev-lock.ts`'s shape. This route is mounted
+                // in exactly two places (`cmd-dev.ts`, `serve.ts`) and NEITHER reads `.x/static`:
+                // in `x dev` the chunks are rebuilt on the watcher tick, and in the container they
+                // were built at boot. `x build --target static` — which is what this said — writes
+                // an export directory neither process serves from, so running it changed nothing
+                // for the only two readers this line has ever had.
+                fix: 'reload the page — this process serves only the chunks it built, and the document holding this URL came from an earlier build',
               },
             },
             { status: 404 },

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);

package/src/mcp-errors.ts

@@ -5,7 +5,7 @@
 import { describeErrorCode, hasErrorCode, listErrorCodes } from '@ultimat3/core';
 import type { ErrorExplanation } from '@ultimat3/mcp';
 import type { CliErrorCode } from './error-codes';
-import { CLI_ERROR_CODES, docsFor } from './error-codes';
+import { CLI_ERROR_CODES } from './error-codes';
 import { codeFixes, codeFixScan } from './error-fixes';
 
 /**
@@ -48,6 +48,8 @@ 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_ERROR_FIX_PATH_MISSING:
+    'x verify --json   # the finding names the fix line and the path it cites',
   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',
@@ -89,6 +91,9 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   // this fix builds an image, writes no `.x/build-stats.json`, and the next `x verify` reports the
   // same code. Byte-identical to `checkBudgets`'s own finding, which is the other half of the pair.
   X_BUDGET_UNMEASURED: 'x build --target static --json && x verify --json',
+  // `x routes` first, because the finding is about a ROUTE and the table names its file and its
+  // islands; the generator that fixes it takes the directory that table just printed.
+  X_LIVE_ROUTE_NO_ISLAND: 'x routes --json   # then: x g island <route-dir> --at <route-dir>',
   X_BUILD_FAILED: 'x build --json   # the finding names the failing step',
   X_BUILD_ENTRY_MISSING:
     'x new scratch-app --dry-run --json   # the file list names every entry a build needs',
@@ -214,7 +219,7 @@ export function explainErrorCode(code: string): ErrorExplanation | undefined {
     code,
     cause: described.title,
     fix: cli ? CLI_FIXES[code] : projectedFix(code),
-    docs: cli ? docsFor(code) : described.docs,
+    docs: described.docs,
   };
 }
 

package/src/messages.ts

@@ -135,10 +135,12 @@ const CATALOG = {
   'cli.manifest.wrote': 'manifest written to {path} ({routes} routes, {actions} actions)',
   'cli.mcp.serving': 'mcp {transport} serving {tools} tools',
   'cli.mcp.scopes': '  scopes {scopes}',
-  // `x db gen "initial"` is a first step, not an optional one: the scaffold writes no migration, so
-  // the app has a schema no migration records and `x verify`'s drift step says so until it runs.
-  'cli.new.done':
-    'created {name} — next: cd {name} && bun install && x db gen "initial" && x db migrate && x dev',
+  // `bin/setup` and nothing else: the scaffold ships it, `README.md` and `bin/check` both name it,
+  // and it is the only spelling that is right on a fresh clone — it installs, writes
+  // `.env.development.local`, runs `x db gen "initial"` (the scaffold writes no migration, so the
+  // drift step is red until it has), migrates and seeds. The four-command line this replaced named
+  // `x dev` off a tree where nothing had installed the CLI yet, and skipped the seed entirely.
+  'cli.new.done': 'created {name} — next: cd {name} && bin/setup && x dev',
   // The two prose lines of `x new`'s report. The `run: cd … && git init …` line beneath the second
   // one stays inline in `cmd-new.ts`: it is an instruction to paste verbatim, and a translated
   // command is a broken one — the same split `Finding.fix` already makes.