@ultimat3/cli 1.2.0 → 3.0.0

package/src/prerender.ts

@@ -4,11 +4,16 @@
 // only which routes qualify and where the bytes land.
 
 import { join } from 'node:path';
+import { renderThrowable } from '@ultimat3/core';
 import type { RouteEntry } from '@ultimat3/render';
 import { renderStatic, routeEntries } from '@ultimat3/render';
 import { loadApp } from './app-load';
 import { appManifest } from './app-manifest';
+import type { RouteStats } from './budgets';
+import { measureDocumentJs, writeBuildStats } from './budgets';
 import { routeDocument } from './dev-render';
+import type { IslandBundle } from './island-bundle';
+import { buildIslands, writeIslands } from './island-bundle';
 
 /**
  * `static` only. `isr` revalidates and `ssr`/`stream`/`spa` need a process, so writing any of them
@@ -32,16 +37,66 @@ export interface PrerenderedPage {
   readonly bytes: number;
 }
 
+/** A route that declared a budget and could not be rendered here, and what stopped it. */
+export interface UnmeasuredRoute {
+  readonly path: string;
+  readonly reason: string;
+}
+
 export interface PrerenderReport {
   readonly out: string;
   readonly buildId: string;
   readonly pages: readonly PrerenderedPage[];
   /** Routes that exist and are not static. Reported, so "only 2 pages" is never a mystery. */
   readonly skipped: readonly string[];
+  /**
+   * Routes whose budget this build could not weigh, with the reason. `X_BUDGET_UNMEASURED` is what
+   * the gate then reports for each; this is the half that says WHY, which a per-route finding read
+   * off a stats file cannot know.
+   */
+  readonly unmeasured: readonly UnmeasuredRoute[];
+  /** Where the measured stats landed, for the `budgets` gate step to read. */
+  readonly stats: string;
+  /** Client entries emitted, one chunk each. Reported so "which JS shipped?" needs no unzip. */
+  readonly islands: readonly string[];
+}
+
+/**
+ * The heaviest thing the document actually boots, named by the source file an author can open.
+ * An island chunk is content-addressed, so its URL says nothing on its own — mapping it back
+ * through the bundle is what turns `X_BUDGET_EXCEEDED` from a number into an instruction.
+ */
+function heaviestSource(
+  bundle: IslandBundle,
+  entries: readonly { readonly url: string; readonly bytes: number }[],
+): readonly string[] | undefined {
+  const heaviest = entries.reduce<{ url: string; bytes: number } | undefined>(
+    (max, entry) => (max === undefined || entry.bytes > max.bytes ? entry : max),
+    undefined,
+  );
+  if (heaviest === undefined) return undefined;
+  const chunk = bundle.chunkAt(heaviest.url);
+  return chunk === undefined ? [heaviest.url] : [chunk.file];
 }
 
 export const DEFAULT_ORIGIN = 'https://localhost';
 
+/**
+ * Prerendering and measuring are two questions, and conflating them made `X_BUDGET_UNMEASURED`
+ * unclosable by any invocation: only `static` was ever rendered, so a `budget:` on an ssr, isr,
+ * stream or spa route produced no `build-stats.json` entry however the build was run, and a gate
+ * whose finding no command can close is a gate an author learns to ignore.
+ *
+ * The first question decides what lands on a CDN — `isPrerenderable`, unchanged, because a page
+ * whose staleness nothing can correct must not be published. The second asks what a browser
+ * executes, and every render mode makes that promise. So a budgeted route is rendered IN MEMORY
+ * through the same `routeDocument` a request takes, weighed, and thrown away.
+ */
+const declaresBudget = (entry: RouteEntry): boolean => {
+  const budget = entry.config.budget;
+  return budget !== undefined && (budget.js !== undefined || budget.lcp !== undefined);
+};
+
 export async function prerenderSite(options: PrerenderOptions): Promise<PrerenderReport> {
   // The same load `x dev` and `x manifest` perform: importing the app's modules IS what fills the
   // route registry, so there is no route table to prerender before this runs.
@@ -50,22 +105,76 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   const origin = options.origin ?? DEFAULT_ORIGIN;
   const pages: PrerenderedPage[] = [];
   const skipped: string[] = [];
+  const routes: RouteStats[] = [];
+  const unmeasured: UnmeasuredRoute[] = [];
+
+  // Before the first document: a page's `data-x-entry` is a built chunk's URL, so the chunks have
+  // to exist to be named. Written into `out` too — a static export is served with no process
+  // behind it, so the artifact carries every byte the browser will ask for.
+  const islands = await buildIslands(options.root);
+  await writeIslands(islands, options.out);
 
   for (const entry of routeEntries()) {
     if (!isPrerenderable(entry)) {
       skipped.push(entry.path);
+      if (!declaresBudget(entry)) continue;
+      // Non-fatal, and that is deliberate: an ssr page's `load` may want a request, a session or a
+      // database this build does not have, and a `x build --target static` that started failing on
+      // routes it never used to touch would be a worse regression than the gap it closes. A route
+      // that will not render here is reported, gets no stats entry, and stays `X_BUDGET_UNMEASURED`.
+      try {
+        const html = await routeDocument(
+          entry,
+          { url: new URL(entry.path, origin).href, params: {} },
+          { resolveIsland: (file: string) => islands.resolverFor(file) },
+        );
+        const measured = await measureDocumentJs(html, options.out);
+        const chain = heaviestSource(islands, measured.entries);
+        routes.push({
+          path: entry.path,
+          jsBytes: measured.jsBytes,
+          ...(chain === undefined ? {} : { heaviestChain: chain }),
+        });
+      } catch (error) {
+        // `renderThrowable`, never `String(error)`: this is a caught unknown, and a hostile
+        // `toString` here would take the whole build down instead of one route's measurement.
+        unmeasured.push({ path: entry.path, reason: renderThrowable(error) });
+      }
       continue;
     }
     const artifacts = await renderStatic(
       entry,
-      ({ path, params }) => routeDocument(entry, { url: new URL(path, origin).href, params }),
+      ({ path, params }) =>
+        routeDocument(
+          entry,
+          { url: new URL(path, origin).href, params },
+          { resolveIsland: (file: string) => islands.resolverFor(file) },
+        ),
       { buildId },
     );
     for (const artifact of artifacts) {
       const file = join(options.out, artifact.outputPath);
       const bytes = await Bun.write(file, artifact.html);
       pages.push({ path: artifact.path, file: artifact.outputPath, hash: artifact.hash, bytes });
+      // Measured from the document that was just written, so the `budgets` step compares a
+      // declared budget against bytes that exist on disk rather than against a graph's estimate.
+      const measured = await measureDocumentJs(artifact.html, options.out);
+      const chain = heaviestSource(islands, measured.entries);
+      routes.push({
+        path: artifact.path,
+        jsBytes: measured.jsBytes,
+        ...(chain === undefined ? {} : { heaviestChain: chain }),
+      });
     }
   }
-  return { out: options.out, buildId, pages, skipped };
+  const stats = await writeBuildStats(options.root, { routes });
+  return {
+    out: options.out,
+    buildId,
+    pages,
+    skipped,
+    unmeasured,
+    stats,
+    islands: islands.chunks.map((chunk) => chunk.file),
+  };
 }

package/src/registry.ts

@@ -5,7 +5,9 @@ import { buildCommand } from './cmd-build';
 import { dbCommand } from './cmd-db';
 import { deployCommand } from './cmd-deploy';
 import { devCommand } from './cmd-dev';
+import { docsCommand } from './cmd-docs';
 import { doctorCommand } from './cmd-doctor';
+import { envCommand } from './cmd-env';
 import { errorsCommand } from './cmd-errors';
 import { fixCommand } from './cmd-fix';
 import { generateCommand } from './cmd-generate';
@@ -19,6 +21,7 @@ import { plannedCommands } from './cmd-planned';
 import { policyCommand } from './cmd-policy';
 import { actionsCommand, entitiesCommand, queriesCommand } from './cmd-registries';
 import { routesCommand } from './cmd-routes';
+import { secretsCommand } from './cmd-secrets';
 import { tasksCommand } from './cmd-tasks';
 import { testCommand } from './cmd-test';
 import { verifyCommand } from './cmd-verify';
@@ -26,8 +29,20 @@ import type { CliCommand } from './command';
 import type { CommandSpec } from './parse';
 import { loadVersion } from './version-loader';
 
-/** Single source of truth for the framework version — loaded from root package.json. */
-export const CLI_VERSION = loadVersion();
+let cliVersionCache: string | undefined;
+
+/**
+ * Single source of truth for the CLI's own version — loaded from its package.json, lazily.
+ * `index.ts` re-exports this module, so importing `@ultimat3/cli` for `runRole` alone — what a
+ * compiled `apps/web/server.ts` does — must not read a manifest a `--compile` binary does not
+ * carry. An eager `const` here reintroduced exactly the failure `frameworkVersion()` was made
+ * lazy to fix, one file over: it compiled clean and threw at import on the first boot that
+ * actually ran the artifact.
+ */
+export function cliVersion(): string {
+  if (cliVersionCache === undefined) cliVersionCache = loadVersion();
+  return cliVersionCache;
+}
 
 const CORE: readonly CliCommand[] = [
   newCommand,
@@ -40,6 +55,8 @@ const CORE: readonly CliCommand[] = [
   mcpCommand,
   doctorCommand,
   deployCommand,
+  envCommand,
+  secretsCommand,
   manifestCommand,
   routesCommand,
   actionsCommand,
@@ -50,6 +67,7 @@ const CORE: readonly CliCommand[] = [
   policyCommand,
   i18nCommand,
   errorsCommand,
+  docsCommand,
   fixCommand,
 ];
 
@@ -62,7 +80,7 @@ export const COMMANDS: readonly CliCommand[] = [
   ...CORE,
   ...plannedCommands(),
   createHelpCommand(() => SPECS),
-  createVersionCommand(CLI_VERSION),
+  createVersionCommand(cliVersion),
 ];
 
 export const SPECS: readonly CommandSpec[] = COMMANDS.map((command) => command.spec);

package/src/runtime-overrides.ts

@@ -0,0 +1,66 @@
+// The one place a host hands the framework a driver. `ServeOptions` had `{ root, env, role, port,
+// metricsPort }` and nothing else, so the ONLY way to install a driver was to call an ambient
+// setter from an app module — which `loadApp` imports *after* `startServices` has already captured
+// its own. This type is the seam that removes the need to, and every field is read exactly once,
+// as the first arm of `overrides?.x ?? <the env-selected default>`.
+
+import type { PurgeDriver } from '@ultimat3/cache';
+import type { Middleware, RateLimitStore } from '@ultimat3/http';
+import type { JobDriver } from '@ultimat3/jobs';
+import type { MailDriver } from '@ultimat3/mail';
+import type { SyncAuthenticator, Transport } from '@ultimat3/realtime';
+import type { IsrStore } from '@ultimat3/render';
+import type { ImageTransformDriver } from '@ultimat3/seo';
+import type { Storage } from '@ultimat3/storage';
+
+/**
+ * What a deployment may substitute for a boot decision the environment would otherwise make.
+ *
+ * Every field is OPTIONAL and every field REPLACES the default rather than sitting beside it: the
+ * env switch each one used to be is now the `??` arm of one expression, so there is exactly one
+ * answer to "which driver is this process running" (axiom 1). A field nothing consumes is not
+ * here — the entity `Driver` in particular, because `@ultimat3/entity` exposes no installer for
+ * one (`database(entities, { driver })` is the app's own call), and a slot the boot cannot honour
+ * is the class of defect this seam exists to end.
+ */
+export interface RuntimeOverrides {
+  /**
+   * The queue every enqueue AND every claim uses. Installed as the ambient driver too, so
+   * `jobDriver()` and the worker cannot disagree — `startRoles` refuses to boot when they do.
+   */
+  readonly jobs?: JobDriver;
+  /** Replaces the `S3_ENDPOINT`/embedded-disk decision whole: disks, default disk and all. */
+  readonly storage?: Storage;
+  /** Replaces the `SMTP_URL` / `RESEND_API_KEY` selection. */
+  readonly mail?: MailDriver;
+  /**
+   * Replaces the `NATS_URL` selection. Already connected when it arrives, and NOT closed by
+   * `stop()`: whoever built it owns its socket, exactly as `createServer` does not close a
+   * `rateLimitStore` it was handed.
+   */
+  readonly transport?: Transport;
+  /** Replaces the `CLOUDFLARE_*` / `FASTLY_*` selection behind the `cdn` cache tier. */
+  readonly purge?: PurgeDriver;
+  /**
+   * Where the HTTP rate limiter keeps its counters. It also DECIDES `rateLimit.scope`: a store
+   * that says `'shared'` is a deployment declaring fleet-wide numbers, and `assertRateLimitScope`
+   * holds the two halves together rather than a literal in the boot contradicting the store.
+   */
+  readonly rateLimitStore?: RateLimitStore;
+  /**
+   * Where regenerated ISR pages live. Omitted, `createIsrController` keeps a per-process memory
+   * store — twelve replicas then hold twelve of them, and a purge tag reaches one twelfth of the
+   * fleet.
+   */
+  readonly isrStore?: IsrStore;
+  /** Prepended to the pipeline by `createServer`, which `startRoles` never passed one. */
+  readonly middleware?: readonly Middleware[];
+  /** The `/media/*` transform. Omitted, `builtinImageDriver` — core's PNG/JPEG pipeline. */
+  readonly images?: ImageTransformDriver;
+  /**
+   * Who is dialling the `sync` node. Omitted, the app's own `configureAuthenticator()` is adapted
+   * — this field exists because that adapter can only ever answer `{ actor }`, and a real
+   * deployment's token has an `expiresAt` and a `refresh`, which is the whole of re-authorization.
+   */
+  readonly syncAuthenticate?: SyncAuthenticator;
+}

package/src/safe-url-label.ts

@@ -0,0 +1,24 @@
+// Single responsibility: a connection URL rendered so it can be printed, logged and scraped —
+// scheme, host, path, and never the userinfo, query or fragment that carry the password.
+// DATABASE_URL, NATS_URL and S3_ENDPOINT all reach `x dev --json` as raw strings, so the redaction
+// has one implementation rather than one per caller that remembers.
+
+/**
+ * `fallback` is the caller's, not this file's: a string that does not parse as a URL is a fact
+ * about that binding, and only the caller knows which binding it was. Never the raw string — an
+ * unparseable value is exactly where a hand-written credential ends up.
+ */
+export function safeUrlLabel(url: string, fallback: string): string {
+  let label: string;
+  try {
+    const parsed = new URL(url);
+    label = `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+  } catch {
+    return fallback;
+  }
+  // A scheme with no `//` is parsed as ONE opaque path — `app:user:pw@host/db` keeps its whole
+  // credential in `pathname` and `username` is empty, so dropping the userinfo fields is not
+  // enough. Any surviving `@` is treated as userinfo we failed to split, and the fallback wins: a
+  // host printed with a `@` in it is a redaction that did not happen.
+  return label.includes('@') ? fallback : label;
+}

package/src/scaffold-fixture.ts

@@ -28,9 +28,19 @@ export const FIXTURE_GENERATORS: readonly GenerateOptions[] = [
   { kind: 'query', name: 'invoice-search', feature: 'invoice' },
   { kind: 'query', name: 'invoice-feed', feature: 'invoice', live: true },
   { kind: 'job', name: 'sweep-invoices', feature: 'invoice' },
+  { kind: 'backfill', name: 'reindex-invoices', feature: 'invoice' },
   { kind: 'task', name: 'nightly-sweep', feature: 'invoice' },
   { kind: 'route', name: 'pricing', surface: 'site' },
   { kind: 'route', name: 'billing', surface: 'app' },
+  // `--at`, pointed at the `site/` route above: an island's whole reason to exist is a 0kb page
+  // that needs one interactive control, so the fixture places it where that is true.
+  { kind: 'island', name: 'currency-picker', at: 'apps/web/site/pricing' },
+  // The one screen the admin derives from nothing — and the one generator that must NOT emit a
+  // `defineRoute`, so compiling it is how that stays true.
+  { kind: 'admin:page', name: 'reconcile', permission: 'ledger:reconcile' },
+  // The app's own convention. It is the only generated file that imports `@ultimat3/cli` for its
+  // types, so compiling it is what proves a scaffolded app can actually write one.
+  { kind: 'guard', name: 'migration-safety' },
 ];
 
 /** The whole scaffolded surface: a new app, then every generator run inside it. */

package/src/scaffold-typecheck.ts

@@ -66,50 +66,28 @@ export interface KnownGap {
   readonly owner: string;
 }
 
-// `InvariantColumns` is an index-signature type, so `c.title` is `ColumnExpr | undefined` under
-// `noUncheckedIndexedAccess`. Every hand-written entity in `examples/dummy` reproduces it
-// identically: the fix is a column proxy typed from the entity's own columns, in @ultimat3/entity
-// — a different template cannot avoid it without dropping to `satisfies()`, which would silently
-// stop emitting the Postgres CHECK.
-//
-// Measured, not guessed: no open-keyed form avoids the `| undefined` (index signature, `Record`,
-// and a mapped type over `string` or a template-literal pattern all produce it), and typing the
-// proxy from `columns` only reaches `c` when the element of `invariants:` is itself
-// context-sensitive. `invariant(name, build)` is a *call*, which TypeScript checks before
-// `entity()`'s own `C` is fixed, so `K` falls back to `string` and nothing changes. Making it
-// reach means changing the shape of `invariants:` — a documented primitive, so a major.
-const INVARIANT_PROXY =
-  '@ultimat3/entity — type the invariant column proxy from the declared columns (needs a major: ' +
-  'the `invariants:` element shape has to become context-sensitive)';
-
-/** Every entity the fixture generates. Each one declares the same two invariants. */
-const FIXTURE_ENTITIES = [
-  'apps/web/app/credit-note/entity.ts',
-  'apps/web/app/invoice/entity.ts',
-  'apps/web/app/post/entity.ts',
-] as const;
-
 /**
  * Diagnostics a template cannot fix, pinned one occurrence at a time. Pinned, never ignored:
  * `unexpectedIn` fails on anything not listed here — including a second copy of a listed
  * diagnostic, because each entry is consumed by exactly one match — and `staleGapsIn` fails when
  * a listed entry stops reproducing, so an entry cannot outlive the bug it describes.
+ *
+ * Empty, and that is the point: `invariants:` is one callback over the whole list, so `c` is typed
+ * from the entity's own columns and the six `TS18048 'c.title' is possibly 'undefined'` pins this
+ * list used to carry are gone. A new entry here is a template shipping a diagnostic, which needs
+ * an owner who can remove it — not a permanent exemption.
  */
-export const KNOWN_GAPS: readonly KnownGap[] = FIXTURE_ENTITIES.flatMap((file) =>
-  ["'c.title' is possibly 'undefined'.", "'c.price' is possibly 'undefined'."].map(
-    (message): KnownGap => ({
-      variant: 'x new',
-      code: 'TS18048',
-      file,
-      message,
-      owner: INVARIANT_PROXY,
-    }),
-  ),
-);
-
-/** The pins one invocation may spend. Another variant's pins are not its to spend. */
-export const gapsFor = (variant: string): readonly KnownGap[] =>
-  KNOWN_GAPS.filter((gap) => gap.variant === variant);
+export const KNOWN_GAPS: readonly KnownGap[] = [];
+
+/**
+ * The pins one invocation may spend. Another variant's pins are not its to spend. `gaps` is a
+ * parameter for the same reason it is on `unexpectedIn` and `staleGapsIn`: with `KNOWN_GAPS`
+ * legitimately empty, the bookkeeping is only testable against a list a test supplies.
+ */
+export const gapsFor = (
+  variant: string,
+  gaps: readonly KnownGap[] = KNOWN_GAPS,
+): readonly KnownGap[] => gaps.filter((gap) => gap.variant === variant);
 
 const matches = (diagnostic: TypeDiagnostic, gap: KnownGap): boolean =>
   diagnostic.code === gap.code &&