@ultimat3/cli 22.15.0 → 24.0.0

package/src/budgets.ts

@@ -11,6 +11,7 @@ import { join } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Manifest, RouteFact } from '@ultimat3/manifest';
 import {
+  describeRoutes,
   formatBytes,
   parseByteBudget,
   SPECULATION_RULES_TYPE,
@@ -38,15 +39,6 @@ export interface RouteStats {
    * older build simply did not count it, and `checkBudgets` reads `jsBytes` either way.
    */
   readonly frameworkJsBytes?: number;
-  /**
-   * **Written by nothing, `As of 2026-08`.** `apps/web/prerender.ts` is the only producer of this
-   * file and it emits static HTML — there is no browser in the build to observe a paint. So the
-   * comparison in `checkBudgets` below is reachable only for an app that writes its own stats, and
-   * `x new` no longer scaffolds an `lcp` budget for exactly that reason: a budget the build cannot
-   * weigh passes silently the moment a stats row exists, which is the false green this file's
-   * header is about. `RouteBudget.lcp` still accepts one — that key is `@ultimat3/render`'s.
-   */
-  readonly lcpMs?: number;
   /** Import chain that pulled the heaviest module into this route. */
   readonly heaviestChain?: readonly string[];
 }
@@ -66,20 +58,32 @@ export interface BuildStats {
  * `examples/dummy` was charged 250 B for `/x-sw-register.js` by a file written before
  * `FRAMEWORK_SCRIPTS` exempted it. `2`: that exemption and the page-boot decision (ledger #28).
  * `3`: an island entry's imported chunks are charged, each once per document (shared chunks).
+ * `4`: the exempt theme script's bytes moved — it also stamps `data-theme-default` (plan 101, 09).
  */
-export const BUILD_STATS_RULES = 3;
+export const BUILD_STATS_RULES = 4;
 
 const chainOf = (stats: RouteStats): string =>
   stats.heaviestChain === undefined ? 'unknown import chain' : stats.heaviestChain.join(' -> ');
 
 const jsBudgetOf = (route: RouteFact): number | null => parseByteBudget(route.budget?.js);
 
-/** Which budgets the route declared, for a cause line that names what went unmeasured. */
-function declaredBudgets(js: number | null, lcp: number | undefined): string {
-  const labels: string[] = [];
-  if (js !== null) labels.push('JS');
-  if (lcp !== undefined) labels.push('LCP');
-  return labels.join(' and ');
+/** Which file declares a route, by URL — the loaded app's route table, read when the step runs. */
+export type RouteFileOf = (url: string) => string | undefined;
+
+const declaredFileOf: RouteFileOf = (url) =>
+  describeRoutes().find((route) => route.path === url && route.mount === undefined)?.file;
+
+const KB = 1024;
+
+/**
+ * The paste, not the advice: the file, the literal to set (the measured bytes rounded UP to a
+ * whole kb, so the raise is the smallest that clears) and the comment `bun run budget-raises`
+ * reads above it. The other way out stays beside it — a raise is axiom 9's to allow, not to force.
+ */
+function exceededJsFix(url: string, file: string | undefined, bytes: number): string {
+  const where = file ?? `the file declaring ${url}`;
+  const kb = Math.ceil(bytes / KB);
+  return `edit ${where} — set budget: { js: '${String(kb)}kb' } with // measured: ${String(bytes)} B (x build --target static) — why: <the function it buys> directly above it; or x routes --json for the chain and move the heavy import behind hydrate: 'interaction'`;
 }
 
 /**
@@ -169,11 +173,15 @@ function ownCodeFinding(url: string, unmeasured: readonly UnmeasuredRoute[]): Fi
  * each failure's code when it had one. Optional because the report is written beside the stats
  * and can be absent for the same reason; with it, a route whose measurement failed on a code in
  * `REPORTED_BY_OWN_CODE` is reported under that code, with the build's own cause and fix.
+ *
+ * `fileOf` names the file an `X_BUDGET_EXCEEDED` fix edits: the step runs after the app loaded,
+ * so render's route table already holds it. A test hands its own.
  */
 export function checkBudgets(
   manifest: Manifest,
   stats: BuildStats | undefined,
   unmeasured: readonly UnmeasuredRoute[] = [],
+  fileOf: RouteFileOf = declaredFileOf,
 ): readonly Finding[] {
   const byPath = new Map((stats?.routes ?? []).map((route) => [route.path, route]));
   // Routes no build can weigh by construction (`UnmeasuredRoute.weighable`): printed by the step,
@@ -186,17 +194,11 @@ export function checkBudgets(
     if (unweighable.has(route.url)) continue;
     const measured = byPath.get(route.url);
     const js = jsBudgetOf(route);
-    const lcp = route.budget?.lcp;
     if (measured === undefined) {
-      if (js !== null || lcp !== undefined) {
+      if (js !== null) {
         findings.push(
           ownCodeFinding(route.url, unmeasured) ??
-            unmeasuredFinding(
-              route.url,
-              declaredBudgets(js, lcp),
-              stats !== undefined,
-              stats?.stale === true,
-            ),
+            unmeasuredFinding(route.url, 'JS', stats !== undefined, stats?.stale === true),
         );
       }
       continue;
@@ -205,16 +207,7 @@ export function checkBudgets(
       findings.push({
         code: 'X_BUDGET_EXCEEDED',
         cause: `${route.url} ships ${formatBytes(measured.jsBytes)} of JS (minified, uncompressed) over a ${formatBytes(js)} budget via ${chainOf(measured)}`,
-        fix: `x routes --json to see the chain, then move the heavy import behind hydrate: 'interaction'`,
-        docs: ERROR_DOCS_URL,
-        at: route.url,
-      });
-    }
-    if (lcp !== undefined && measured.lcpMs !== undefined && measured.lcpMs > lcp) {
-      findings.push({
-        code: 'X_BUDGET_EXCEEDED',
-        cause: `${route.url} LCP ${measured.lcpMs}ms over the ${lcp}ms budget`,
-        fix: `raise the budget in defineRoute, or switch render to 'isr' to serve it prebuilt`,
+        fix: exceededJsFix(route.url, fileOf(route.url), measured.jsBytes),
         docs: ERROR_DOCS_URL,
         at: route.url,
       });

package/src/cdp-shot-driver.ts

@@ -91,7 +91,9 @@ export function cdpShotDriver(options: CdpShotDriverOptions): ShotDriver {
       throw new CdpBrowserMissingError({ tried: CHROME_CANDIDATES });
     }
     const launched = await launch(options.executablePath, timeoutMs);
-    return { connection: launched.connection, end: async () => launched.close() };
+    // Awaited by `close` below: `x shot` exits right after its last picture, and a reap still
+    // running then is a Chrome child left behind and a profile directory it re-creates.
+    return { connection: launched.connection, end: () => launched.close() };
   };
 
   return {

package/src/cmd-auth-spec.ts

@@ -0,0 +1,16 @@
+// `x auth`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-auth.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const AUTH_SUBCOMMANDS = ['seal-mfa'] as const;
+
+export const authSpec: CommandSpec = {
+  name: 'auth',
+  summary: 'one-shot maintenance of the auth tables: seal every plaintext second-factor secret',
+  usage: 'x auth seal-mfa [--json]',
+  requiresApp: true,
+  // No default: the one subcommand WRITES, and a bare `x auth` must not.
+  subcommands: [...AUTH_SUBCOMMANDS],
+  flags: [],
+};

package/src/cmd-auth.ts

@@ -0,0 +1,65 @@
+// `x auth seal-mfa` — seal every `x_users.mfa_secret` still stored in the clear, in place, under
+// the app's master key. The one-shot an upgrade onto sealed second-factor secrets owes: readers
+// refuse a plaintext value (`X_MFA_SECRET_UNSEALED`), and this is the command that refusal names.
+// Idempotent — a sealed value is counted and left alone — so an interrupted run is finished by
+// running it again.
+
+import type { MfaSecretStore } from '@ultimat3/auth';
+import { BuiltinAdapter, sealMfaSecrets } from '@ultimat3/auth';
+import { requireAppRoot } from './app-root';
+import { authSpec } from './cmd-auth-spec';
+import type { CliCommand, CommandContext } from './command';
+import { ok } from './command';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import { resolveServices } from './runtime-bindings';
+import { startQueue } from './runtime-queue';
+
+export interface OpenAuthStore extends MfaSecretStore {
+  close(): Promise<void>;
+}
+
+/**
+ * The app's own database, opened the way every other command opens it (`startQueue`: the
+ * framework's tables are applied first, so `x_users` exists) and ALWAYS released — a CLI that
+ * exits holding the PGlite lock breaks the next command run against this app.
+ */
+async function openAppAuthStore(root: string, ctx: CommandContext): Promise<OpenAuthStore> {
+  const queue = await startQueue(resolveServices(root, ctx.env), undefined, ctx.env);
+  return { adapter: new BuiltinAdapter(queue.db), close: () => queue.stop() };
+}
+
+/** `open` is the seam a test supplies a store through; the shipped command opens the app's. */
+export const authCommandOver = (
+  open: (root: string, ctx: CommandContext) => Promise<OpenAuthStore>,
+): CliCommand => ({
+  spec: authSpec,
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('auth', ctx.cwd).dir;
+    const store = await open(root, ctx);
+    try {
+      // The key is read from the command's own environment and the app's `.secrets.key`: with
+      // neither, the first seal refuses (`X_SEAL_KEY_MISSING`) before any row is written.
+      const report = await sealMfaSecrets(store, { root, env: ctx.env });
+      return ok(
+        'auth',
+        msg('cli.auth.sealed', {
+          sealed: report.sealed,
+          already: report.alreadySealed,
+          skipped: report.skipped,
+        }),
+        {
+          data: {
+            sealed: report.sealed,
+            alreadySealed: report.alreadySealed,
+            skipped: report.skipped,
+          },
+        },
+      );
+    } finally {
+      await store.close();
+    }
+  },
+});
+
+export const authCommand: CliCommand = authCommandOver(openAppAuthStore);

package/src/cmd-build-spec.ts

@@ -5,12 +5,19 @@ import type { CommandSpec } from './parse';
 
 export const buildSpec: CommandSpec = {
   name: 'build',
-  summary: 'build a container image, a single binary, or a prerendered static site',
+  summary:
+    'build a container image, a single binary, a prerendered static site, or the store an image boots from',
   usage:
-    'x build --target docker|binary|static [--tag name] [--out path] [--no-preflight] [--json]',
+    'x build --target docker|binary|static|prebuilt [--tag name] [--out path] [--no-preflight] [--json]',
   requiresApp: true,
   flags: [
-    { name: 'target', type: 'string', summary: 'docker | binary | static', default: 'docker' },
+    {
+      name: 'target',
+      type: 'string',
+      summary:
+        'docker | binary | static | prebuilt — prebuilt is the line a Dockerfile runs inside the image build',
+      default: 'docker',
+    },
     { name: 'tag', type: 'string', summary: 'image tag (docker target)' },
     { name: 'out', type: 'string', summary: 'output path (binary and static targets)' },
     {

package/src/cmd-build.ts

@@ -1,21 +1,24 @@
-// `x build --target docker|binary|static` — three targets, no platform primitives. Deploy anywhere
-// means "anywhere that runs a container or a binary"; nothing here knows the name of a cloud.
+// `x build --target docker|binary|static|prebuilt` — no platform primitives. Deploy anywhere means
+// "anywhere that runs a container or a binary"; nothing here knows the name of a cloud. `prebuilt`
+// is the docker target's other half: the line the Dockerfile runs INSIDE the image build.
 
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { ERROR_DOCS_URL, frameworkVersion, VERSION_DEFINE } from '@ultimat3/core';
+import { ERROR_DOCS_URL, frameworkVersion, UltimateError, VERSION_DEFINE } from '@ultimat3/core';
 import { requireAppRoot } from './app-root';
 import { buildSpec } from './cmd-build-spec';
 import { runVerify } from './cmd-verify';
 import type { CliCommand, CommandContext } from './command';
 import { externalArgs } from './compile-externals';
-import { BuildEntryMissingError, UnknownCommandError } from './errors';
+import { BadFlagError, UnknownCommandError } from './errors';
 import type { ExecResult } from './exec';
 import { execOutput } from './exec';
-import { prepareImage } from './image-prepare';
 import { msg } from './messages';
 import type { CommandResult } from './output';
+import type { ParsedArgs } from './parse';
 import { flagString } from './parse';
+import { PREBUILT_DIR } from './serve-prebuilt-paths';
+import { quoteArg } from './shell-quote';
 import type { StaticReport } from './static-report';
 import {
   readStaticReport,
@@ -23,11 +26,30 @@ import {
   renderStaticReport,
   staticReportData,
 } from './static-report';
+import type { VerifyStepName } from './verify-step';
 
-export const BUILD_TARGETS = ['docker', 'binary', 'static'] as const;
+/**
+ * A build target names an entry file the app does not have. `x build` refuses before it spawns the
+ * builder: `bun build`'s own "module not found" says nothing about which file an Ultimate app is
+ * supposed to own, and `docker build`'s says nothing about which target wanted it.
+ */
+export class BuildEntryMissingError extends UltimateError {
+  constructor(input: { target: string; entry: string }) {
+    super({
+      code: 'X_BUILD_ENTRY_MISSING',
+      cause: `x build --target ${input.target} builds from ${input.entry}, and the app does not have it`,
+      fix: `x new scratch-app --dry-run --json   # its file list carries ${input.entry}; copy that file into this app`,
+    });
+  }
+}
+
+export const BUILD_TARGETS = ['docker', 'binary', 'static', 'prebuilt'] as const;
 
 export type BuildTarget = (typeof BUILD_TARGETS)[number];
 
+/** The targets whose builder is a subprocess. `prebuilt` is this process, inside `docker build`. */
+export type SpawnedTarget = Exclude<BuildTarget, 'prebuilt'>;
+
 export function readTarget(raw: string | undefined): BuildTarget {
   const targets: readonly string[] = BUILD_TARGETS;
   if (raw === undefined) return 'docker';
@@ -48,6 +70,8 @@ export const BUILD_ENTRY: Readonly<Record<BuildTarget, string>> = {
   docker: 'docker/Dockerfile',
   binary: 'apps/web/server.ts',
   static: 'apps/web/prerender.ts',
+  // What boots from the store: an image with no server entry has nothing to prebuild for.
+  prebuilt: 'apps/web/server.ts',
 };
 
 /** Absolute path of the target's entry, or the error that names the file and what writes it. */
@@ -109,7 +133,7 @@ export function staticArgs(root: string, out: string): readonly string[] {
 }
 
 export function argsFor(
-  target: BuildTarget,
+  target: SpawnedTarget,
   paths: {
     readonly root: string;
     readonly tag: string;
@@ -184,8 +208,77 @@ export function buildResult(input: {
   };
 }
 
+/** The flags only some targets read. */
+const TARGET_SCOPED_FLAGS = ['tag', 'out', 'preflight'] as const;
+
+type TargetScopedFlag = (typeof TARGET_SCOPED_FLAGS)[number];
+
+/** The optional flags each target READS. One table, so a flag cannot be read by one and ignored. */
+const TARGET_FLAGS: ReadonlyMap<BuildTarget, readonly TargetScopedFlag[]> = new Map([
+  ['docker', ['tag', 'preflight']],
+  ['binary', ['out', 'preflight']],
+  ['static', ['out', 'preflight']],
+  // The boot reads ONE place, and the image holds no devDependencies to run a gate with.
+  ['prebuilt', []],
+]);
+
+/** Why a target takes no `--<flag>`, in the words its refusal prints. */
+const UNREAD_BECAUSE: Readonly<Record<TargetScopedFlag, string>> = {
+  tag: 'only the docker target tags an image',
+  out: 'the docker target writes an image, not a path',
+  preflight: 'the prebuilt target runs no gate: `x verify` ran before `docker build` was called',
+};
+
+/**
+ * A flag the chosen target never reads is refused before the gate runs. Accepted and dropped, it
+ * printed a green build: `--out dist` on `docker` and `--tag` on `binary` read as if they landed.
+ */
+function refuseUnreadFlags(args: ParsedArgs, target: BuildTarget): void {
+  for (const flag of TARGET_SCOPED_FLAGS) {
+    if (!args.flags.has(flag) || TARGET_FLAGS.get(target)?.includes(flag) === true) continue;
+    throw new BadFlagError({
+      flag,
+      command: 'build',
+      reason:
+        target === 'prebuilt' && flag !== 'preflight'
+          ? `the prebuilt target writes ${PREBUILT_DIR}, the one place a container boots from, and takes no --${flag}`
+          : `--target ${target} never reads it: ${UNREAD_BECAUSE[flag]}`,
+      fix: `x build --target ${quoteArg(target)}`,
+    });
+  }
+}
+
+/**
+ * `x build --target prebuilt`: the island chunks and compiled stylesheets, written by the process
+ * `docker build` runs after the source is copied in. No gate and no subprocess — the image holds
+ * no devDependencies to typecheck with, and `x verify` ran before `docker build` was called.
+ *
+ * A module that would not import fails the image build rather than warning into a build log
+ * nobody reads: its stylesheets are missing from the store, and every pod would compile them.
+ */
+async function buildPrebuilt(root: string): Promise<CommandResult> {
+  const started = Bun.nanoseconds();
+  const { prebuildImage } = await import('./image-prepare');
+  const built = await prebuildImage(root);
+  const ok = built.findings.length === 0;
+  return {
+    ok,
+    command: 'build',
+    summary: msg(ok ? 'cli.build.done' : 'cli.build.failed', { target: 'prebuilt' }),
+    findings: built.findings,
+    data: {
+      target: 'prebuilt',
+      artifact: built.dir,
+      durationMs: Math.round((Bun.nanoseconds() - started) / 1e6),
+      islands: built.islands,
+      stylesheets: built.stylesheets,
+    },
+    lines: [],
+  };
+}
+
 /** The static steps `x build` runs before it builds, and `--no-preflight` leaves to the gate. */
-export const PREFLIGHT_STEPS: readonly string[] = [
+export const PREFLIGHT_STEPS: readonly VerifyStepName[] = [
   'typecheck',
   'lint',
   'boundaries',
@@ -203,6 +296,8 @@ export const buildCommand: CliCommand = {
     // typecheck, and eight seconds of `tsc` ahead of "that file does not exist" is eight seconds
     // an agent spends on the wrong question.
     requireEntry(root, target);
+    refuseUnreadFlags(ctx.args, target);
+    if (target === 'prebuilt') return buildPrebuilt(root);
 
     // Run static verify steps before building — unless the caller is a gate that runs the same
     // six steps itself right after (`bin/check`: `x build --no-preflight && x verify`), where the
@@ -227,9 +322,10 @@ export const buildCommand: CliCommand = {
         ? join(root, '.x', target === 'static' ? 'static' : 'app')
         : resolve(ctx.cwd, outFlag);
     const tag = flagString(ctx.args, 'tag') ?? 'ultimate-app:dev';
-    // The docker target stamps the manifest's build id into the image, and writes the island
-    // chunks the image serves, so a container boot neither re-derives the one nor rebuilds the other.
-    const buildId = target === 'docker' ? await prepareImage(root) : undefined;
+    // The docker target stamps the manifest's build id into the image, so no role derives one at
+    // boot. The island chunks and stylesheets are the image build's own (`--target prebuilt`).
+    const buildId =
+      target === 'docker' ? await (await import('./image-prepare')).imageBuildId(root) : undefined;
     const command = argsFor(target, {
       root,
       tag,

package/src/cmd-db-backfill.ts

@@ -23,7 +23,7 @@ import { BadFlagError } from './errors';
 import { withJobDriver } from './jobs-driver';
 import { backfillToJson } from './jobs-json';
 import { msg } from './messages';
-import type { CommandResult } from './output';
+import type { CommandResult, Finding } from './output';
 import { findingFrom } from './output';
 import type { ParsedArgs } from './parse';
 import { flagBool, flagString } from './parse';
@@ -171,15 +171,22 @@ async function runBackfillList(ctx: CommandContext, root: string): Promise<Comma
  * The alarm the framework did not have. Non-zero when anything is unswept, so a cron or a deploy
  * check can read the exit code — a `--json` nobody has to parse to know something is wrong.
  * `loadApp` first: importing the app's modules IS the declaration, and a diff run without it
- * would report a clean database against an empty declaration list.
+ * would report a clean database against an empty declaration list. Its findings fail the run for
+ * the same reason: a module that would not import may be the one declaring the unswept backfill.
  */
 async function runBackfillPending(ctx: CommandContext, root: string): Promise<CommandResult> {
-  await loadApp(root);
+  const { findings: loadFindings } = await loadApp(root);
   const environment = resolveEnvironment({ env: ctx.env });
   return withJobDriver(root, ctx, async (driver) => {
     const report = await pendingReport(driver, environment);
+    const findings = [
+      ...report.pending.map((row) =>
+        findingFrom(new BackfillPendingError({ backfill: row.name, environment })),
+      ),
+      ...loadFindings,
+    ];
     return {
-      ok: report.pending.length === 0,
+      ok: findings.length === 0,
       command: 'db',
       summary:
         report.pending.length === 0
@@ -188,9 +195,7 @@ async function runBackfillPending(ctx: CommandContext, root: string): Promise<Co
               count: report.pending.length,
               declared: report.rows.length,
             }),
-      findings: report.pending.map((row) =>
-        findingFrom(new BackfillPendingError({ backfill: row.name, environment })),
-      ),
+      findings,
       lines: report.rows.length === 0 ? [] : renderPendingTable(report).map((line) => `  ${line}`),
       data: pendingToJson(report),
     };
@@ -208,7 +213,7 @@ async function runBackfillPass(
   root: string,
   names: readonly string[] | 'all',
 ): Promise<CommandResult> {
-  await loadApp(root);
+  const { findings: loadFindings } = await loadApp(root);
   const environment = resolveEnvironment({ env: ctx.env });
   const write = flagBool(ctx.args, 'write');
   return withJobDriver(root, ctx, async (driver) => {
@@ -220,16 +225,24 @@ async function runBackfillPass(
       environment,
       appliedMigrations: await readAppliedMigrations(),
     });
-    return backfillPassResult(rows, write);
+    return backfillPassResult(rows, write, loadFindings);
   });
 }
 
 /**
  * A blocked or deduped name is a finding and a non-zero exit, and every OTHER name still ran —
- * that isolation is what stops one wedged cleanup blocking every later one forever.
+ * that isolation is what stops one wedged cleanup blocking every later one forever. A module that
+ * would not import fails the pass too: `--all` over it plans every backfill but the unloaded ones.
  */
-function backfillPassResult(rows: readonly BackfillPlanRow[], write: boolean): CommandResult {
-  const findings = rows.flatMap((row) => (row.finding === null ? [] : [row.finding]));
+function backfillPassResult(
+  rows: readonly BackfillPlanRow[],
+  write: boolean,
+  loadFindings: readonly Finding[],
+): CommandResult {
+  const findings = [
+    ...rows.flatMap((row) => (row.finding === null ? [] : [row.finding])),
+    ...loadFindings,
+  ];
   // Counted per action, never derived from the total: a deduped pass is neither enqueued nor
   // blocked, and `rows.length - enqueued` reported it as blocked while `--json` reported it as
   // deduped. `planToJson` is the same list, so the two renders now add up to the same run.