@ultimat3/cli 22.14.0 → 23.0.0

package/src/budgets.ts

@@ -10,7 +10,13 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Manifest, RouteFact } from '@ultimat3/manifest';
-import { formatBytes, parseByteBudget, themeScriptBody } from '@ultimat3/render';
+import {
+  describeRoutes,
+  formatBytes,
+  parseByteBudget,
+  SPECULATION_RULES_TYPE,
+  themeScriptBody,
+} from '@ultimat3/render';
 import type { Finding } from './output';
 import type { UnmeasuredRoute } from './static-report';
 import { SW_REGISTER_PATH } from './sw-artifacts';
@@ -69,6 +75,25 @@ const chainOf = (stats: RouteStats): string =>
 
 const jsBudgetOf = (route: RouteFact): number | null => parseByteBudget(route.budget?.js);
 
+/** 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'`;
+}
+
 /** 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[] = [];
@@ -164,11 +189,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,
@@ -200,7 +229,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'`,
+        fix: exceededJsFix(route.url, fileOf(route.url), measured.jsBytes),
         docs: ERROR_DOCS_URL,
         at: route.url,
       });
@@ -242,7 +271,10 @@ const carriesJson = (attrs: string): boolean => {
   // `type="application/ld+json; charset=utf-8"`, which does not END with `json`, so the suffix
   // test alone charged an SEO structured-data block as executable JavaScript all over again.
   const [type = ''] = (TYPE_ATTR.exec(attrs)?.groups?.['type'] ?? '').split(';');
-  return type.trim().toLowerCase().endsWith('json');
+  const declared = type.trim().toLowerCase();
+  // Speculation rules are JSON under a type that does not say so: read by the browser's
+  // prefetcher, never executed — the one script a 0kb page may carry for free.
+  return declared.endsWith('json') || declared === SPECULATION_RULES_TYPE;
 };
 
 /**

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,5 +1,6 @@
-// `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';
@@ -9,13 +10,13 @@ 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, BuildEntryMissingError, 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 { flagString } from './parse';
+import { PREBUILT_DIR } from './serve-prebuilt-paths';
 import type { StaticReport } from './static-report';
 import {
   readStaticReport,
@@ -24,10 +25,13 @@ import {
   staticReportData,
 } from './static-report';
 
-export const BUILD_TARGETS = ['docker', 'binary', 'static'] as const;
+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 +52,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 +115,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,6 +190,45 @@ export function buildResult(input: {
   };
 }
 
+/**
+ * `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(ctx: CommandContext, root: string): Promise<CommandResult> {
+  // The boot reads ONE place; a flag that seemed to move it would write a store no pod opens.
+  for (const flag of ['tag', 'out']) {
+    if (flagString(ctx.args, flag) === undefined) continue;
+    throw new BadFlagError({
+      flag,
+      command: 'build',
+      reason: `the prebuilt target writes ${PREBUILT_DIR}, the one place a container boots from, and takes no --${flag}`,
+      fix: 'x build --target prebuilt',
+    });
+  }
+  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[] = [
   'typecheck',
@@ -203,6 +248,7 @@ 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);
+    if (target === 'prebuilt') return buildPrebuilt(ctx, 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 +273,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.ts

@@ -22,6 +22,13 @@ import { plannedSubcommand } from './cmd-planned';
 import type { CliCommand, CommandContext } from './command';
 import { stepFinding } from './db-finding';
 import { generateAppMigration, unrenderedJson, unrenderedLines } from './db-generate';
+import { liveObjectDrift } from './db-object-drift';
+import {
+  afterWrittenMigration,
+  refreshSchemaDump,
+  type SchemaDumpRefresh,
+  schemaDumpJson,
+} from './db-schema-refresh';
 import type { SeedPassRow } from './db-seed';
 import {
   discoverSeeds,
@@ -109,34 +116,52 @@ async function runGen(ctx: CommandContext, root: string, name: string): Promise<
   // `x i18n add fr` failure, repeated. The count is the verdict; the gate's own `drift` step is
   // where a red belongs, and it reads the same list to decide that `x db gen` is not the fix.
   const lost = unrenderedLines(generated.unrendered);
+  // After the migration, from the migrations alone: the dump is what replaying them produces, so
+  // it is rewritten on all three outcomes — `unchanged` included, which is what makes this
+  // command the `fix:` on `X_SCHEMA_DUMP_DRIFT` when a framework table or a hand edit moved it.
+  const dump = await refreshSchemaDump(root, ctx.env);
+  const dumpFindings = dump.finding === undefined ? [] : [dump.finding];
   const migration = generated.migration;
   if (migration === undefined) {
     return {
-      ok: generated.findings.length === 0,
+      ok: generated.findings.length === 0 && dumpFindings.length === 0,
       command: 'db',
       // The sidecar path, never a bare id: `hash-recorded` writes exactly one, and it is the file
       // the `drift` step reads back.
+      // `blocked` FIRST: the app did not load, so nothing was diffed, and every sentence below
+      // it is a claim about a comparison that never ran. It read "entities and migrations agree"
+      // over an exit 1.
       summary:
-        generated.outcome === 'hash-recorded'
-          ? msg('cli.db.gen.recorded', { file: generated.files[0] ?? '' })
-          : msg('cli.db.gen.unchanged'),
-      findings: generated.findings,
+        generated.outcome === 'blocked'
+          ? msg('cli.db.gen.blocked', { count: generated.findings.length })
+          : generated.outcome === 'hash-recorded'
+            ? msg('cli.db.gen.recorded', { file: generated.files[0] ?? '' })
+            : dump.status === 'written'
+              ? msg('cli.db.gen.dumped', { count: dump.written.length + dump.removed.length })
+              : msg('cli.db.gen.unchanged'),
+      findings: [...generated.findings, ...dumpFindings],
       // `files` is what this command WROTE, so the empty array here was a false claim.
-      lines: [...generated.files.map((file) => `  ${file}`), ...lost],
+      lines: [...generated.files.map((file) => `  ${file}`), ...dumpLines(dump), ...lost],
       data: {
         outcome: generated.outcome,
         migration: null,
         files: [...generated.files],
         schemaHash: generated.schemaHash ?? null,
         unrendered: unrenderedJson(generated.unrendered),
+        schemaDump: schemaDumpJson(dump),
       },
     };
   }
   return {
-    ok: true,
+    ok: dumpFindings.length === 0,
     command: 'db',
-    summary: msg('cli.db.gen.written', { id: migration.id }),
-    lines: [...generated.files.map((file) => `  ${file}`), ...lost],
+    summary:
+      dumpFindings.length === 0
+        ? msg('cli.db.gen.written', { id: migration.id })
+        : msg('cli.db.gen.writtenDumpFailed', { id: migration.id }),
+    // Exit 1 with a migration on disk: the finding has to say so, or the next move is a duplicate.
+    findings: dumpFindings.map((finding) => afterWrittenMigration(finding, migration.id)),
+    lines: [...generated.files.map((file) => `  ${file}`), ...dumpLines(dump), ...lost],
     data: {
       outcome: generated.outcome,
       migration: migration.id,
@@ -144,10 +169,20 @@ async function runGen(ctx: CommandContext, root: string, name: string): Promise<
       files: [...generated.files],
       schemaHash: generated.schemaHash ?? null,
       unrendered: unrenderedJson(generated.unrendered),
+      schemaDump: schemaDumpJson(dump),
     },
   };
 }
 
+/**
+ * What the dump refresh did, one path per line — the same list `data.schemaDump` carries, so the
+ * human render and `--json` report one fact. A refresh that changed nothing prints nothing.
+ */
+const dumpLines = (dump: SchemaDumpRefresh): readonly string[] => [
+  ...dump.written.map((file) => `  ${file}`),
+  ...dump.removed.map((file) => `  - ${file}`),
+];
+
 /**
  * The post-migrate report, rendered. Through `driftError` rather than a second literal: the
  * three-line `X_DB_DRIFT` output is pinned by the framework contract, and this command must not be
@@ -175,16 +210,30 @@ async function runMigrate(
   try {
     const migrated = await runMigrations({ root, env: ctx.env });
     const report = migrated.report;
+    // A hand-written or pulled migration reaches the dump here, with no `x db gen` in between.
+    const dump = await refreshSchemaDump(root, ctx.env);
+    // The half a snapshot cannot hold: a trigger, function, view, type or sequence this database
+    // carries and no migration creates. Asked only when the replay produced a catalog to ask
+    // against — without one there is nothing that says what the migrations create.
+    const objects =
+      dump.catalog === undefined ? [] : await liveObjectDrift(root, ctx.env, dump.catalog);
+    const findings = [
+      ...driftFindings(migrated.drift),
+      ...objects.map((difference) => findingFrom(driftError(difference))),
+      ...(dump.finding === undefined ? [] : [dump.finding]),
+    ];
     return {
-      ok: migrated.drift.ok,
+      ok: findings.length === 0,
       command: 'db',
       summary,
-      findings: driftFindings(migrated.drift),
+      findings,
+      lines: dumpLines(dump),
       data: {
         applied: report.applied.map((entry) => entry.id),
         skipped: report.skipped.length,
         appVersion: report.appVersion,
         durationMs: report.durationMs,
+        schemaDump: schemaDumpJson(dump),
       },
     };
   } catch (error) {

package/src/cmd-dev.ts

@@ -242,7 +242,7 @@ async function bootDev(
   // `x dev`'s own, so a reload can empty it: an `isr` page's first render was otherwise served for
   // its whole ttl after every save, whatever the modules behind it now said.
   const isr = createIsrController({ buildId });
-  const { routes, theme, errorStyles, mcpPath, mcpPaths } = await devRouteTable({
+  const { routes, theme, speculation, errorStyles, mcpPath, mcpPaths } = await devRouteTable({
     isr,
     root: options.root,
     env: options.env,
@@ -278,7 +278,7 @@ async function bootDev(
     // The `/_x` shell, the harness's frame, and the app's own error pages — the inline bodies this
     // process serves; the app's surfaces are content-hashed files `'self'` admits.
     inlineStyles: [await devShellStyle(), FRAME_STYLE, ...errorStyles],
-    inlineScripts: [theme.cspSource],
+    inlineScripts: [theme.cspSource, ...(speculation === undefined ? [] : [speculation.cspSource])],
     // The overlay renders this request's own loops under the error it is already showing.
     // `serve.ts` boots through the same `startRoles` and passes nothing (axiom 6).
     devNotices: (ctx: RequestContext): readonly OverlayNotice[] =>

package/src/cmd-doctor.ts

@@ -22,8 +22,12 @@ import { findAppRoot, REQUIRED_BUN, versionAtLeast } from './app-root';
 import { DEFAULT_DOCTOR_PORT, doctorSpec } from './cmd-doctor-spec';
 import type { CliCommand, CommandContext } from './command';
 import { checkMigrationSnapshots } from './db-snapshot';
+import { coverageExcludesProbe, withCoverageExcludes } from './doctor-coverage';
+import { shippedGuardsProbe, withGuardListing } from './doctor-guards';
 import type { OfflineFallbackFact } from './doctor-offline';
 import { offlineFallbackFinding, offlineFallbackProbe } from './doctor-offline';
+import type { SealedKeysFact } from './doctor-sealed';
+import { sealedKeyFindings, sealedKeysProbe } from './doctor-sealed';
 import { intFlagOr, PORT_RANGE, portPairAfter } from './flag-number';
 import { ICON_SOURCE } from './icon-assets';
 import { msg } from './messages';
@@ -91,6 +95,12 @@ export interface DoctorProbe {
    * reaching the disk — the same split `drift()` makes one question over.
    */
   offlineFallback(): Promise<OfflineFallbackFact>;
+  /**
+   * The app's `.sealed()` columns and the master keys this environment declares. A FACT, for the
+   * reason `offlineFallback` is one: loading the app and opening the secrets file is IO, and what
+   * a retired key beside a sealed column means is `sealedKeyFindings`' pure rule.
+   */
+  sealedKeys(): Promise<SealedKeysFact>;
 }
 
 /** What `x doctor` reads about the embedded database, without opening it. */
@@ -281,6 +291,8 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
   // author reaches it from: `x db gen` throwing `X_MIGRATION_SNAPSHOT_MISSING` used to be a
   // condition this diagnostic could not see at all, so the fix line ran clean over a broken app.
   findings.push(...(await probe.snapshots()));
+  // Sealed columns against the key ring: no key at all, or a rotation whose re-seal is pending.
+  findings.push(...sealedKeyFindings(await probe.sealedKeys()));
   return findings;
 }
 
@@ -394,6 +406,8 @@ export function probeFor(cwd: string, bunVersion: string, port: number): DoctorP
     // `runDoctor` returns on `X_NOT_IN_APP` before this can be asked.
     offlineFallback: async () =>
       root === undefined ? { fallback: null, routes: undefined } : offlineFallbackProbe(root),
+    sealedKeys: async () =>
+      root === undefined ? { columns: undefined, keys: undefined } : sealedKeysProbe(root),
   };
 }
 
@@ -401,16 +415,26 @@ export const doctorCommand: CliCommand = {
   spec: doctorSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const port = doctorPort(ctx.args);
-    const findings = await runDoctor(probeFor(ctx.cwd, ctx.bunVersion, port));
-    return {
-      ok: findings.length === 0,
-      command: 'doctor',
-      summary:
-        findings.length === 0
-          ? msg('cli.doctor.clean')
-          : msg('cli.doctor.findings', { count: findings.length }),
-      findings,
-      data: { count: findings.length, codes: findings.map((entry) => entry.code) },
-    };
+    const probe = probeFor(ctx.cwd, ctx.bunVersion, port);
+    const findings = await runDoctor(probe);
+    const listed = withGuardListing(
+      {
+        ok: findings.length === 0,
+        command: 'doctor',
+        summary:
+          findings.length === 0
+            ? msg('cli.doctor.clean')
+            : msg('cli.doctor.findings', { count: findings.length }),
+        findings,
+        data: { count: findings.length, codes: findings.map((entry) => entry.code) },
+      },
+      // A listing beside the verdict, never part of it (`doctor-guards.ts` says why).
+      probe.root === undefined ? [] : await shippedGuardsProbe(probe.root),
+    );
+    // The second listing: what the coverage floor does not see (`doctor-coverage.ts`).
+    return withCoverageExcludes(
+      listed,
+      probe.root === undefined ? [] : await coverageExcludesProbe(probe.root),
+    );
   },
 };