@ultimat3/cli 29.4.0 → 30.0.0

package/src/island-disposer.ts

@@ -0,0 +1,116 @@
+// An island's `mount` hands back its disposer, made a build error: the client router disposes an
+// island by calling what `mount` resolved to (`disposeIslands`), so a `mount(): void` is never
+// released and its listeners, hotkey tables and live reads stay registered across navigations.
+// Pure over the `boundaries` step's one read; no type can carry it, an island is a specifier.
+
+import { ERROR_DOCS_URL, maskLiterals } from '@ultimat3/core';
+import { ISLAND_EXTENSION } from '@ultimat3/render';
+import type { SourceFile } from './app-boundaries';
+import { commentSafe } from './comment-safe';
+import type { Finding } from './output';
+
+/** `function mount(` and `async function mount<T>(` — the declaration form. */
+const DECLARED = /\b(?:async\s+)?function\s+mount\s*(?:<[^>]*>)?\s*\(/;
+/** `const mount = (`, `= async (`, `= function (` — an unannotated binding. */
+const BOUND = /\b(?:const|let|var)\s+mount\s*=\s*(?:async\s+)?(?:function\b[^(]*)?\(/;
+/** The annotations that SAY nothing comes back; any other one is the type checker's to hold. */
+const VOID_ANNOTATION = /^:\s*(?:void|undefined|Promise\s*<\s*(?:void|undefined)\s*>)\s*$/;
+/** A `(…) {` that opens a statement block, not a function's body. */
+const CONTROL_WORDS: ReadonlySet<string> = new Set([
+  'if',
+  'for',
+  'while',
+  'switch',
+  'catch',
+  'with',
+]);
+
+/** The index closing the bracket opened at `open`, or `-1`. Exact over `maskLiterals` output. */
+function closeOf(masked: string, open: number): number {
+  const opener = masked[open];
+  const closer = opener === '(' ? ')' : '}';
+  let depth = 0;
+  for (let index = open; index < masked.length; index += 1) {
+    if (masked[index] === opener) depth += 1;
+    else if (masked[index] === closer) {
+      depth -= 1;
+      if (depth === 0) return index;
+    }
+  }
+  return -1;
+}
+
+/** The `(` matching the `)` at `close`, scanning backwards. */
+function openOf(masked: string, close: number): number {
+  let depth = 0;
+  for (let index = close; index >= 0; index -= 1) {
+    if (masked[index] === ')') depth += 1;
+    else if (masked[index] === '(') {
+      depth -= 1;
+      if (depth === 0) return index;
+    }
+  }
+  return -1;
+}
+
+/** Whether the `{` at `brace` opens a nested function's body: `=> {`, `function f() {`, `m() {`. */
+function opensFunction(masked: string, brace: number): boolean {
+  const before = masked.slice(0, brace).trimEnd();
+  if (before.endsWith('=>')) return true;
+  if (!before.endsWith(')')) return false;
+  const open = openOf(masked, before.length - 1);
+  const word = /([\w$]+)\s*$/.exec(masked.slice(0, Math.max(0, open)))?.[1];
+  return word !== undefined && !CONTROL_WORDS.has(word);
+}
+
+/** Whether the body opened at `brace` returns a value from its OWN scope, not a nested function's. */
+function returnsValue(masked: string, brace: number): boolean {
+  const end = closeOf(masked, brace);
+  const stack: boolean[] = [];
+  for (let index = brace + 1; index < (end < 0 ? masked.length : end); index += 1) {
+    const char = masked[index];
+    if (char === '{') stack.push(opensFunction(masked, index));
+    else if (char === '(' || char === '[') stack.push(false);
+    else if (char === '}' || char === ')' || char === ']') stack.pop();
+    else if (stack.includes(true) || !masked.startsWith('return', index)) continue;
+    else if (/[\w$]/.test(masked[index - 1] ?? '') || /[\w$]/.test(masked[index + 6] ?? '')) {
+    } else if (/^[ \t]*[^\s;}]/.test(masked.slice(index + 6))) return true;
+  }
+  return false;
+}
+
+/** Why `masked`'s mount returns no disposer, or `undefined` when it does or none is declared. */
+function missingDisposer(masked: string): string | undefined {
+  const match = DECLARED.exec(masked) ?? BOUND.exec(masked);
+  if (match === null) return undefined;
+  const close = closeOf(masked, match.index + match[0].length - 1);
+  if (close < 0) return undefined;
+  const after = masked.slice(close + 1);
+  const arrow = DECLARED.exec(masked) === null;
+  const head = arrow ? after.slice(0, Math.max(0, after.indexOf('=>'))) : after.split('{')[0];
+  const annotation = (head ?? '').trim();
+  if (VOID_ANNOTATION.test(annotation)) return `is typed \`${annotation.slice(1).trim()}\``;
+  if (annotation !== '') return undefined;
+  const bodyAt = arrow ? close + 1 + after.indexOf('=>') + 2 : close + 1 + after.indexOf('{');
+  const lead = masked.slice(bodyAt).match(/^\s*/)?.[0].length ?? 0;
+  if (masked[bodyAt + lead] !== '{') return undefined;
+  return returnsValue(masked, bodyAt + lead) ? undefined : 'returns nothing from its own body';
+}
+
+/** One `X_ISLAND_DISPOSER_MISSING` per `.island.tsx` whose `mount` hands back no disposer. */
+export function islandDisposerFindings(files: readonly SourceFile[]): readonly Finding[] {
+  return files.flatMap(({ path, source }): Finding[] => {
+    if (!path.endsWith(ISLAND_EXTENSION) || !source.includes('mount')) return [];
+    const why = missingDisposer(maskLiterals(source));
+    if (why === undefined) return [];
+    return [
+      {
+        code: 'X_ISLAND_DISPOSER_MISSING',
+        cause: `${path}'s mount() ${why}, so the client router has nothing to call when it navigates away and the island's listeners, hotkeys and live reads stay registered`,
+        fix: `x verify --only boundaries --json   # in ${commentSafe(path)}, end mount() with return render(() => <Island {...props} />, el) — Solid's disposer, which the router calls`,
+        docs: ERROR_DOCS_URL,
+        at: path,
+      },
+    ];
+  });
+}

package/src/island-realtime-state.ts

@@ -4,6 +4,7 @@
 // whole realtime use is a channel's events, a roster or the connection reads neither: its server
 // markup is as current as any other island's, so hiding it only delayed the page's content.
 
+import { registeredEntities } from '@ultimat3/entity';
 import { firstInGraph } from './live-routes';
 
 const REALTIME = '@ultimat3/realtime';
@@ -20,6 +21,8 @@ export const FOLLOW_ONLY_EXPORTS: readonly string[] = [
   'hasPageSocket',
   // Hears THAT records moved and renders none of them, so a restored store contradicts nothing.
   'useRecordChanges',
+  // A timer value for `useQuery`'s `poll`: it reads nothing, so it adds no reason to hold.
+  'pollEvery',
   'readPresence',
   'channel',
   'channelRef',
@@ -63,17 +66,42 @@ export function realtimeBindings(source: string, path: string): readonly string[
  */
 export type IslandRealtime = 'restores' | 'follows';
 
+/**
+ * The reads that restore something only when the app keeps a record type on disk: with none, the
+ * boot restores no record their server markup could be older than. `useMutation` is not here —
+ * the outbox rebuilds a queued write's overlay whatever the app persists.
+ */
+export const NO_DISK_FOLLOW_EXPORTS: readonly string[] = ['useQuery', 'useRecord'];
+
+/**
+ * Whether the loaded app keeps any record type on disk (`entity(…, { persist: true })`), read off
+ * the entity registry the build process loaded the app into. An empty registry is `undefined`: an
+ * app that registered nothing and a build that never loaded it look the same, so it is unknown.
+ */
+export function appPersistsRecords(): boolean | undefined {
+  const entries = registeredEntities();
+  if (entries.length === 0) return undefined;
+  return entries.some((entry) => entry.persist === true);
+}
+
 /**
  * Whether a realtime island restores nothing: every module of its relative graph takes only
- * `FOLLOW_ONLY_EXPORTS` from the barrel. One unknown name, or one statement with no names, and it
- * restores — the answer every realtime island had before. Pure: asked per build, of that build's
- * root. The blind spot is `reachesRealtime`'s own: a PACKAGE reading the store for the island is
- * not seen.
+ * `FOLLOW_ONLY_EXPORTS` from the barrel — plus `NO_DISK_FOLLOW_EXPORTS` when `persists` is
+ * `false`. One unknown name, or one statement with no names, and it restores — the answer every
+ * realtime island had before; `persists` unknown keeps that answer. Pure: asked per build, of that
+ * build's root. The blind spot is `reachesRealtime`'s own: a PACKAGE reading the store for the
+ * island is not seen.
  */
-export async function followsOnly(root: string, file: string): Promise<boolean> {
+export async function followsOnly(
+  root: string,
+  file: string,
+  persists?: boolean,
+): Promise<boolean> {
+  const allowed =
+    persists === false ? [...FOLLOW_ONLY_EXPORTS, ...NO_DISK_FOLLOW_EXPORTS] : FOLLOW_ONLY_EXPORTS;
   const restores = await firstInGraph(root, file, (source, path) => {
     const names = realtimeBindings(source, path);
-    const follows = names?.every((name) => FOLLOW_ONLY_EXPORTS.includes(name)) === true;
+    const follows = names?.every((name) => allowed.includes(name)) === true;
     return follows ? undefined : true;
   });
   return restores !== true;

package/src/island-realtime.ts

@@ -50,14 +50,18 @@ export async function reachesRealtime(root: string, file: string): Promise<boole
  * Both of a build's answers about one island, for its chunk to carry (`IslandChunk.realtime`):
  * `undefined` when its graph never reaches realtime. A page needs realtime's page boot only if one
  * of ITS islands does — `settings` paid 34.9 kB of boot script for an island that never touched a
- * record — and holds only the ones that restore.
+ * record — and holds only the ones that restore. `persists` is REQUIRED, and the build passes the
+ * loaded app's registry's answer (`appPersistsRecords`): every boot that builds islands has imported
+ * the app first. As a default it read process-wide state here, so one test's entities changed
+ * another's answer (`bun test ./packages/cli`, alone, went red); `undefined` is "unknown".
  */
 export async function realtimeKind(
   root: string,
   file: string,
+  persists: boolean | undefined,
 ): Promise<IslandRealtime | undefined> {
   if (!(await reachesRealtime(root, file))) return undefined;
-  return (await followsOnly(root, file)) ? 'follows' : 'restores';
+  return (await followsOnly(root, file, persists)) ? 'follows' : 'restores';
 }
 
 /**

package/src/island-routes.ts

@@ -3,7 +3,7 @@
 // would be a page that boots in `x dev` and 404s in the image.
 
 import type { Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders, jsonResponse, NO_STORE } from '@ultimat3/http';
+import { applyCacheHeaders, jsonResponse, NO_STORE, textResponse } from '@ultimat3/http';
 import type { IslandBundle } from './island-bundle';
 import { ISLAND_BASE_PATH } from './island-bundle';
 
@@ -51,7 +51,8 @@ export function islandRoutes(source: IslandSource): readonly Route[] {
           return applyCacheHeaders(missing, NO_STORE);
         }
         return applyCacheHeaders(
-          new Response(chunk.code, { headers: { 'content-type': 'text/javascript' } }),
+          // `textResponse` for the length it declares: `compress` reads nothing undeclared.
+          textResponse(chunk.code, { headers: { 'content-type': 'text/javascript' } }),
           { mode: 'immutable' },
         );
       },

package/src/isr-query-advice.ts

@@ -1,7 +1,7 @@
 // What `x verify` says about the query an `isr` route keys on. Advice and not a finding: the scan
 // reads source text, so it can miss a read made through a helper and can name one that is not a
-// query read at all — and a route that declared nothing works as it always did. Both are exactly
-// what a reader should hear about before a visitor finds it.
+// query read at all. A read the key omits is still what a reader should hear about before a
+// visitor finds it.
 
 // why: Bun exposes no path-join primitive; Bun.file takes one already joined.
 import { join } from 'node:path';
@@ -32,20 +32,15 @@ export function queryReads(source: string): readonly string[] {
 const listed = (names: readonly string[]): string => names.map((name) => `'${name}'`).join(', ');
 
 /**
- * One line per `isr` route with no `revalidate.query` — it renders and stores a page for every
- * distinct query string, so `?x=1`, `?x=2`, … evict its real pages and cost a render each — and
- * one per parameter a route's module reads and its declaration omits: the page is stored under a
- * key without it, so every visitor gets the document rendered for whichever value arrived first.
+ * One line per parameter an `isr` route's module reads and its declaration omits, no declaration
+ * being none: the page is stored under a key without it, so every visitor gets the document
+ * rendered for whichever value arrived first.
  */
 export async function isrQueryAdvice(root: string): Promise<readonly string[]> {
   const advice: string[] = [];
   for (const route of describePages()) {
     if (route.mode !== 'isr') continue;
-    const declared = route.revalidateQuery ?? null;
-    if (declared === null) {
-      advice.push(msg('cli.verify.isrQueryUndeclared', { file: route.file }));
-      continue;
-    }
+    const declared = route.revalidateQuery ?? [];
     const module = Bun.file(join(root, route.file));
     if (!(await module.exists())) continue;
     for (const name of queryReads(await module.text())) {

package/src/isr-query-guard.ts

@@ -1,5 +1,5 @@
-// The `query` object a page component is handed. For an `isr` route that declared
-// `revalidate.query` it holds the declared parameters only — and, outside production, it says so
+// The `query` object a page component is handed. For an `isr` route it holds the parameters
+// `revalidate.query` declared, none when it declares none — and, outside production, it says so
 // once when the page reads any other one: that read is a document varying on something its stored
 // key does not carry, which is one visitor's page answered to every visitor after.
 
@@ -22,7 +22,8 @@ export function routeQuery(
   env?: ResolveEnvironmentOptions['env'],
 ): Query {
   const query: Query = Object.fromEntries(url.searchParams);
-  const declared = entry.config.render === 'isr' ? entry.config.revalidate?.query : undefined;
+  const declared =
+    entry.config.render === 'isr' ? (entry.config.revalidate?.query ?? []) : undefined;
   if (declared === undefined) return query;
   // Production pays nothing: the plain object, no trap. (`undefined`: an unreadable environment,
   // which is not a development one either.)

package/src/job-budget.ts

@@ -0,0 +1,95 @@
+// The `manifest` step's drain half: a job's declared `timeout` against what a deploy gives the worker
+// holding it. Over that, the job is cut while still inside its own limit, on every deploy that
+// lands during it. A job with no `timeout` is not graded: a limit nobody declared is not comparable.
+
+import type { DrainConfig } from '@ultimat3/core';
+import {
+  APP_CONFIG_FILE,
+  DRAIN_DEADLINE_DEFAULT_MS,
+  finiteCount,
+  isUltimateError,
+  WORKER_DRAIN_DEADLINE_MAX_MS,
+  WORKER_RETIRE_DEFAULT_MS,
+} from '@ultimat3/core';
+import { cutoffTimes, registeredJobs } from '@ultimat3/jobs';
+import { loadApp } from './app-load';
+import type { AppLoader } from './app-permissions';
+import type { Finding } from './output';
+import { loadDrainConfig } from './serve-drain';
+
+/** The two facts graded; a job handle has both. */
+export interface BudgetedJob {
+  readonly name: string;
+  readonly timeoutMs: number | undefined;
+}
+
+type WorkerDrain = Pick<Partial<DrainConfig>, 'deadlineMs' | 'workerDeadlineMs' | 'workerRetireMs'>;
+
+/**
+ * The retire when on, for it aborts nothing; else when a SIGTERM drain CANCELS a held job, which is
+ * the cut-off's `cancelAt` (`worker-drain-cutoff.ts`), a margin before the deadline itself.
+ */
+export function workerBudgetMs(drain: WorkerDrain | undefined): number {
+  // Screened here, not trusted: `defineConfig` screens an app's config, but this is exported, and a
+  // NaN compares false against every timeout, which would grade every job as within budget.
+  const retire = finiteCount(
+    'the worker budget',
+    'drain.workerRetireMs',
+    drain?.workerRetireMs ?? WORKER_RETIRE_DEFAULT_MS,
+  );
+  if (retire > 0) return retire;
+  const deadline = finiteCount(
+    'the worker budget',
+    'drain.workerDeadlineMs',
+    drain?.workerDeadlineMs ?? drain?.deadlineMs ?? DRAIN_DEADLINE_DEFAULT_MS,
+    1,
+  );
+  return cutoffTimes(deadline, 0).cancelAt;
+}
+
+function outlastsFinding(job: BudgetedJob, limitMs: number, budgetMs: number): Finding {
+  return {
+    code: 'X_JOB_OUTLASTS_DRAIN',
+    cause: `${job.name} declares a timeout of ${limitMs} ms, and the worker's budget is ${budgetMs} ms, so a deploy cuts it while it is inside its own limit`,
+    // Past the ceiling no config value clears it, and a fix that cannot be applied is not a fix.
+    fix:
+      limitMs > WORKER_DRAIN_DEADLINE_MAX_MS
+        ? `timeout: '24h',   // on job ${job.name}: past a day no budget can hold it, so move the rest into step.run() calls, then x verify --only manifest --json`
+        : `drain: { workerRetireMs: ${limitMs} },   // in ${APP_CONFIG_FILE}, then x verify --only manifest --json`,
+    at: APP_CONFIG_FILE,
+  };
+}
+
+/** One finding per job over budget, sorted: the verdict never reads the registration order. */
+export function jobBudgetFindings(
+  jobs: readonly BudgetedJob[],
+  drain: WorkerDrain | undefined,
+): readonly Finding[] {
+  const budgetMs = workerBudgetMs(drain);
+  const findings: Finding[] = [];
+  for (const job of [...jobs].sort((a, b) => (a.name < b.name ? -1 : 1))) {
+    if (job.timeoutMs !== undefined && job.timeoutMs > budgetMs) {
+      findings.push(outlastsFinding(job, job.timeoutMs, budgetMs));
+    }
+  }
+  return findings;
+}
+
+/**
+ * The step's answer: the registry once the app is loaded, as `job-registration.ts` reads it, and
+ * nothing when the load or the config failed, for those are reported by what loaded them.
+ */
+export async function readJobBudgetFindings(
+  root: string,
+  load: AppLoader = loadApp,
+): Promise<readonly Finding[]> {
+  if ((await load(root)).findings.length > 0) return [];
+  let drain: WorkerDrain | undefined;
+  try {
+    drain = await loadDrainConfig(root);
+  } catch (error) {
+    if (!isUltimateError(error) || error.code !== 'X_CONFIG_INVALID') throw error;
+    return [];
+  }
+  return jobBudgetFindings(registeredJobs(), drain);
+}

package/src/jobs-json.ts

@@ -13,6 +13,7 @@ import type {
   StepTrace,
   WorkerRecord,
 } from '@ultimat3/jobs';
+import { consumerRow } from '@ultimat3/jobs';
 import type { JsonValue } from './output';
 
 function stepTraceToJson(step: StepTrace): JsonValue {
@@ -48,6 +49,12 @@ export function backfillToJson(progress: BackfillProgress): JsonValue {
   };
 }
 
+/** A consumer run's row, spelled out field by field for the reason `backfillToJson` is. */
+export function consumerToJson(trace: JobTrace): JsonValue {
+  const row = consumerRow(trace);
+  return row === null ? null : { key: row.key, lastBatchAt: row.lastBatchAt, lag: row.lag };
+}
+
 export function jobTraceToJson(trace: JobTrace): JsonValue {
   return {
     id: trace.id,
@@ -82,6 +89,9 @@ export function jobTraceToJson(trace: JobTrace): JsonValue {
     // `null` for every job that is not a `backfill()` pass. Dropped, `x jobs show <id> --json`
     // would answer "how far has it got" with silence for the one job kind that can say.
     backfill: trace.backfill === null ? null : backfillToJson(trace.backfill),
+    // `null` for every job that is not a `consumer()` run: its key, when it last committed a batch,
+    // and its lag when the declaration has a `lag()` — read off the run's own progress.
+    consumer: consumerToJson(trace),
   };
 }
 
@@ -107,6 +117,7 @@ export function workerToJson(worker: WorkerRecord): JsonValue {
   return {
     id: worker.id,
     host: worker.host,
+    build: worker.build ?? null,
     startedAt: worker.startedAt,
     heartbeatAt: worker.heartbeatAt,
     queues: [...worker.queues],

package/src/lint-findings.ts

@@ -0,0 +1,104 @@
+// `biome check --reporter=json` read as findings, one per diagnostic. `X_LINT_FAILED` alone said
+// `bunx biome check --write .`, and that exits "Skipped 1 suggested fixes", still red, with what was
+// wrong in the step's `output` where a reader of `findings` never looks.
+
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { commentSafe } from './comment-safe';
+import type { ExecResult } from './exec';
+import { execOutput } from './exec';
+import type { Finding } from './output';
+import { quoteArg } from './shell-quote';
+import type { StepOutcome } from './verify-step';
+
+export const LINT_ARGV = [
+  'bunx',
+  'biome',
+  'check',
+  '--reporter=json',
+  '--max-diagnostics=none',
+  '.',
+] as const;
+
+interface Diagnostic {
+  readonly category: string;
+  readonly message: string;
+  readonly path: string;
+  readonly line: number;
+}
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null;
+
+/** Only what fails the step. `info` and `warning` exit 0, so they cannot be why it is red. */
+const diagnosticFrom = (value: unknown): Diagnostic | undefined => {
+  if (!isRecord(value) || !isRecord(value['location'])) return undefined;
+  const { severity, category, message, location } = value as {
+    severity?: unknown;
+    category?: unknown;
+    message?: unknown;
+    location: Readonly<Record<string, unknown>>;
+  };
+  if (severity !== 'error' && severity !== 'fatal') return undefined;
+  const { path, start } = location;
+  if (typeof category !== 'string' || typeof path !== 'string') return undefined;
+  const line = isRecord(start) && typeof start['line'] === 'number' ? start['line'] : 0;
+  return { category, message: typeof message === 'string' ? message : category, path, line };
+};
+
+/**
+ * The only categories `--write` always repairs. Biome's JSON does not say which lint rules carry a
+ * safe fix, and telling a rule whose fix is "unsafe" to run `--write` is the no-op this replaced, so
+ * a lint rule is an edit: true for all of them, and for the safe ones a little more work.
+ */
+const REPAIRED_BY_WRITE = (category: string): boolean =>
+  category === 'format' || category.startsWith('assist/');
+
+const findingOf = ({ category, message, path, line }: Diagnostic): Finding => {
+  const place = line > 0 ? `${path}:${String(line)}` : path;
+  return {
+    code: 'X_LINT_FAILED',
+    cause: `${place} ${category}: ${message}`,
+    fix: REPAIRED_BY_WRITE(category)
+      ? `bunx biome check --write ${quoteArg(path)}`
+      : `bunx biome check ${quoteArg(path)}   # ${category}: edit ${commentSafe(place)}, ${commentSafe(message)}`,
+    docs: ERROR_DOCS_URL,
+    at: path,
+  };
+};
+
+/** Every failing diagnostic, or `undefined` when the output is not the report it should be. */
+export function lintFindings(stdout: string): readonly Finding[] | undefined {
+  let report: unknown;
+  try {
+    report = JSON.parse(stdout);
+  } catch {
+    return undefined;
+  }
+  if (!isRecord(report) || !Array.isArray(report['diagnostics'])) return undefined;
+  return report['diagnostics'].flatMap((value) => {
+    const diagnostic = diagnosticFrom(value);
+    return diagnostic === undefined ? [] : [findingOf(diagnostic)];
+  });
+}
+
+/**
+ * A red exit with no diagnostic to read (a config biome refused, a binary that would not start) stays
+ * one finding pointing at the command, whose own output says what happened.
+ */
+export function lintOutcome(result: ExecResult): StepOutcome {
+  if (result.ok) return { ok: true, findings: [] };
+  const findings = lintFindings(result.stdout);
+  if (findings !== undefined && findings.length > 0) return { ok: false, findings };
+  return {
+    ok: false,
+    findings: [
+      {
+        code: 'X_LINT_FAILED',
+        cause: 'biome exited red and reported no diagnostic to read',
+        fix: 'bunx biome check .',
+        docs: ERROR_DOCS_URL,
+      },
+    ],
+    output: execOutput(result),
+  };
+}

package/src/local-cli.ts

@@ -13,10 +13,11 @@
 
 // why: `realpathSync` is the whole decision — Bun ships no symlink-resolving stat of its own, and
 // `Bun.file(path).exists()` follows a link without saying where it went.
-import { existsSync, realpathSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 // why: Bun exposes no path-join primitive; the local bin is assembled from the app root.
-import { join } from 'node:path';
-import { findAppRoot } from './app-root';
+import { dirname, join } from 'node:path';
+import { stringField } from '@ultimat3/core';
+import { findAppRoot, versionAtLeast } from './app-root';
 
 /**
  * Set to any value to keep the CLI that was invoked. Nothing in this repository's CI needs it —
@@ -31,11 +32,34 @@ export const LOCAL_CLI_BIN = join('node_modules', '@ultimat3', 'cli', 'src', 'bi
 export interface LocalCliIo {
   exists(path: string): boolean;
   realpath(path: string): string;
+  /** The text of a file, `package.json` here. Throwing is the same answer as an unreadable file. */
+  read(path: string): string;
 }
 
 const nodeIo: LocalCliIo = {
   exists: existsSync,
   realpath: (path) => realpathSync(path),
+  read: (path) => readFileSync(path, 'utf8'),
+};
+
+/**
+ * The one command the app's own CLI must not answer when it is the older of the two: an app with no
+ * `x upgrade` yet is told `bunx @ultimat3/cli@latest upgrade`, and handing that to the app's CLI
+ * answers `X_NOT_IMPLEMENTED` from the very version it exists to move off. It is safe because of what
+ * it does not do: it loads no app, so there is no second registry — the gate is the installed CLI's.
+ */
+const OUTLIVES_THE_APP_CLI = 'upgrade';
+
+const versionOfBin = (bin: string, io: LocalCliIo): string | undefined => {
+  const parsed: unknown = JSON.parse(io.read(join(dirname(dirname(bin)), 'package.json')));
+  return stringField(parsed, 'version');
+};
+
+/** Strictly older: an equal or newer app CLI has the command too, and the usual rule stands. */
+const appCliIsOlder = (local: string, self: string, io: LocalCliIo): boolean => {
+  const held = versionOfBin(io.realpath(local), io);
+  const running = versionOfBin(io.realpath(self), io);
+  return held !== undefined && running !== undefined && !versionAtLeast(held, running);
 };
 
 /**
@@ -55,6 +79,8 @@ export function resolveLocalCli(
     readonly cwd: string;
     readonly selfPath: string;
     readonly env: Readonly<Record<string, string | undefined>>;
+    /** The word after the binary, `Bun.argv[2]` as `bin.ts` reads it for `dev`. */
+    readonly command?: string | undefined;
   },
   io: LocalCliIo = nodeIo,
 ): string | undefined {
@@ -64,7 +90,11 @@ export function resolveLocalCli(
   const local = join(root.dir, LOCAL_CLI_BIN);
   if (!io.exists(local)) return undefined;
   try {
-    return io.realpath(local) === io.realpath(input.selfPath) ? undefined : local;
+    if (io.realpath(local) === io.realpath(input.selfPath)) return undefined;
+    if (input.command === OUTLIVES_THE_APP_CLI && appCliIsOlder(local, input.selfPath, io)) {
+      return undefined;
+    }
+    return local;
   } catch {
     return undefined;
   }

package/src/loopback-host.ts

@@ -2,12 +2,12 @@
 // to loopback) or a loopback address literal. One answer for `x dev`'s Host check and `x doctor`'s
 // APP_URL rule, which ask the same question about two different headers.
 
-import { classifyAddress } from '@ultimat3/core';
+import { peerAddressClass } from '@ultimat3/core';
 
 /** `hostname` as `URL` spells it — `[::1]` bracketed, no port. */
 export const isLoopbackHostname = (hostname: string): boolean => {
   const name = hostname.toLowerCase();
   return (
-    name === 'localhost' || name.endsWith('.localhost') || classifyAddress(name) === 'loopback'
+    name === 'localhost' || name.endsWith('.localhost') || peerAddressClass(name) === 'loopback'
   );
 };

package/src/mail-preview-findings.ts

@@ -0,0 +1,24 @@
+// Single responsibility: every declared mail preview rendered in every shipped locale, as `x verify`'s
+// `i18n` step findings — so a preview is a test too: a key a locale lacks, or a preview its own
+// schema refuses, is red at the gate instead of in a customer's inbox.
+
+import { mailKeyMissing, previewableMailIds, previewMail } from '@ultimat3/mail';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+
+export function mailPreviewFindings(locales: readonly string[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const id of previewableMailIds()) {
+    for (const locale of locales) {
+      try {
+        const preview = previewMail(id, { locale });
+        if (preview.misses.length > 0) {
+          findings.push(findingFrom(mailKeyMissing(id, locale, preview.misses)));
+        }
+      } catch (error) {
+        findings.push(findingFrom(error));
+      }
+    }
+  }
+  return findings;
+}