@ultimat3/cli 1.2.0 → 2.0.0

package/src/output.ts

@@ -2,6 +2,9 @@
 // and the JSON renderer are projections of it, so `--json` can never drift from the terminal
 // output (axiom 4). The human renderer owns the canonical 3-line error format.
 
+import { renderThrowable, stringField } from '@ultimat3/core';
+import { msg } from './messages';
+
 export interface Finding {
   readonly code: string;
   readonly cause: string;
@@ -19,6 +22,8 @@ export interface StepResult {
   readonly findings: readonly Finding[];
   /** Captured stdout/stderr, shown on failure or with --verbose. */
   readonly output?: string;
+  /** Worker processes the step used; `1` means it ran serially. Absent for a non-test step. */
+  readonly workers?: number;
 }
 
 export type JsonValue =
@@ -57,34 +62,39 @@ export interface UltimateErrorShape {
   readonly message: string;
 }
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
 /**
  * Structural check, deliberately not `instanceof`: an error may cross a subprocess or worker
  * boundary and arrive as a plain object, and the renderer must still produce the fix line.
+ *
+ * Every field goes through core's `stringField`, because the value is a caught throwable and the
+ * probe itself is a property read: a getter that throws, or a `Proxy` trapping `get`, raised HERE
+ * — one line before the total renderer below, in the function whose whole job is deciding what the
+ * terminal shows.
  */
 export function isUltimateErrorShape(value: unknown): value is UltimateErrorShape {
-  if (!isRecord(value)) return false;
   return (
-    typeof value['code'] === 'string' &&
-    value['code'].startsWith('X_') &&
-    typeof value['cause'] === 'string' &&
-    typeof value['fix'] === 'string'
+    stringField(value, 'code')?.startsWith('X_') === true &&
+    stringField(value, 'cause') !== undefined &&
+    stringField(value, 'fix') !== undefined
   );
 }
 
 export function findingFrom(value: unknown): Finding {
-  if (isUltimateErrorShape(value)) {
-    const docs = value.docs;
-    return docs === undefined
-      ? { code: value.code, cause: value.cause, fix: value.fix }
-      : { code: value.code, cause: value.cause, fix: value.fix, docs };
+  // Read once and carry the values, rather than narrowing and reading the same properties again:
+  // a getter is a function, and nothing promises it answers the same way twice.
+  const code = stringField(value, 'code');
+  const cause = stringField(value, 'cause');
+  const fix = stringField(value, 'fix');
+  if (code?.startsWith('X_') === true && cause !== undefined && fix !== undefined) {
+    const docs = stringField(value, 'docs');
+    return docs === undefined ? { code, cause, fix } : { code, cause, fix, docs };
   }
-  const cause = value instanceof Error ? value.message : String(value);
+  // This is the LAST renderer between a thrown value and the terminal: a hostile `toString`, a
+  // throwing `message` getter or a trapped `instanceof` here loses the whole report, not one line
+  // of it. `renderThrowable` is total on all three.
   return {
     code: 'X_CLI_UNEXPECTED',
-    cause,
+    cause: renderThrowable(value),
     fix: 'x doctor --json',
     docs: 'https://ultimate.dev/errors/X_CLI_UNEXPECTED',
   };
@@ -130,10 +140,20 @@ const mark = (step: StepResult): string => {
   return step.ok ? '✓' : '✗';
 };
 
+/**
+ * How the step was run, when that is a fact about the step rather than about the machine. A gate
+ * that silently went parallel is a gate whose failures a reader would blame on flakiness, so a
+ * serial step says so and a parallel one names its width.
+ */
+const width = (step: StepResult): string => {
+  if (step.workers === undefined || step.skipped === true) return '';
+  return `  ${step.workers === 1 ? msg('cli.verify.serial') : msg('cli.verify.workers', { workers: step.workers })}`;
+};
+
 export function renderHuman(result: CommandResult, verbose = false): string {
   const out: string[] = [];
   for (const step of result.steps ?? []) {
-    out.push(`  ${mark(step)} ${step.name.padEnd(18)} ${step.durationMs}ms`);
+    out.push(`  ${mark(step)} ${step.name.padEnd(18)} ${step.durationMs}ms${width(step)}`);
     for (const finding of step.findings) out.push(renderFinding(finding, '      '));
     if (step.output !== undefined && step.output.length > 0 && (verbose || !step.ok)) {
       for (const line of step.output.trimEnd().split('\n')) out.push(`      | ${line}`);
@@ -152,6 +172,16 @@ export function renderJson(result: CommandResult): string {
     durationMs: step.durationMs,
     skipped: step.skipped === true,
     findings: step.findings,
+    ...(step.workers === undefined ? {} : { workers: step.workers }),
+    // A FAILED step carries its captured stdout, exactly as the human renderer prints it. CI runs
+    // `--json`, and without this the log said only "one or more unit tests failed" with a generic
+    // fix line — the failing test's name and its assertion diff existed and were thrown away, so
+    // the only way to learn what broke was to re-run it somewhere else. CI output is a prompt:
+    // whoever reads it next, agent or human, must be able to act without reproducing first.
+    // Success stays quiet (`--verbose` is the human's opt-in) so a green run is not a wall of text.
+    ...(step.ok || step.output === undefined || step.output.length === 0
+      ? {}
+      : { output: step.output }),
   }));
   const payload = {
     ok: result.ok,

package/src/parse.ts

@@ -2,7 +2,7 @@
 // same way and `--json` / `--help` behave identically everywhere. Pure: no I/O, no process
 // access, so the parser is unit-testable and the dispatcher owns all side effects.
 
-import { BadFlagError, UnknownCommandError } from './errors';
+import { BadFlagError, MissingSubcommandError, UnknownCommandError } from './errors';
 
 export type FlagValue = string | boolean;
 
@@ -20,6 +20,32 @@ export interface CommandSpec {
   readonly usage: string;
   readonly aliases?: readonly string[];
   readonly subcommands?: readonly string[];
+  /**
+   * What a bare `x <command>` means, when it means anything. Declared, never inferred: the parser
+   * used to answer `subcommands[0]`, so `x db` ran `gen` — the migration GENERATOR — because it
+   * sorted first. A command with no defensible default omits this and the parser refuses instead.
+   */
+  readonly defaultSubcommand?: string;
+  /**
+   * A closed set the FIRST positional must come from, where the command has one. Declarative only:
+   * the parser leaves positionals to the command, because `x test`'s own `readOnlyType` already
+   * refuses an unknown type with the list. What this adds is a set `fix-command.ts` can resolve a
+   * citation against. `packages/ai/src/eval-errors.ts` avoids `x test <eval-name>` by hand, with a
+   * three-line comment explaining that it is `X_CLI_BAD_FLAG` — a convention held by memory,
+   * because nothing outside `cmd-test.ts` knew what `x test` accepts. Declare it from the SAME
+   * constant the command validates against, never a second literal.
+   */
+  readonly positionalChoices?: readonly string[];
+  /**
+   * The same closed set, one level down: the set a named SUBCOMMAND's first positional must come
+   * from. `positionalChoices` cannot express it, because `fix-command.ts` only consults that field
+   * where a command declares NO subcommands — so `x db branch ls` resolved as command +
+   * subcommand and nothing ever looked at `ls`. That is how a shipped `fix:` told an agent to run
+   * a listing while `x db branch` read `ls` as a branch name and created a database from it.
+   * Declarative only, exactly like `positionalChoices`: the command still refuses an unknown word
+   * itself, and this is declared from the SAME constant it validates against.
+   */
+  readonly subcommandPositionals?: Readonly<Record<string, readonly string[]>>;
   readonly flags?: readonly FlagSpec[];
   /** Command needs an app root (`app.config.ts`) — the dispatcher enforces it. */
   readonly requiresApp?: boolean;
@@ -44,6 +70,15 @@ export const GLOBAL_FLAGS: readonly FlagSpec[] = [
   { name: 'verbose', type: 'boolean', summary: 'include step output on success' },
 ];
 
+/**
+ * Whether raw argv asked for JSON, readable BEFORE the parse succeeds. The parse-failure path in
+ * `dispatch.ts` has no `ParsedArgs` to read `--json` off — and it used to test `argv.includes`
+ * for the long form only, so `x doctor -j --bogusflag` rendered its `X_CLI_BAD_FLAG` as prose to
+ * an agent that had asked for JSON and then called `JSON.parse` on it. One detection, two callers.
+ */
+export const wantsJson = (argv: readonly string[]): boolean =>
+  argv.some((token) => token === '--json' || token === '-j');
+
 const HELP_ALIASES = new Set(['--help', '-h', 'help']);
 const VERSION_ALIASES = new Set(['--version', '-v', '-V']);
 
@@ -118,7 +153,7 @@ export function parseArgs(argv: readonly string[], specs: readonly CommandSpec[]
   // `help` and `version` short-circuit the flag loop below, so `--json` has to be read here or the
   // two commands silently print prose to an agent that asked for JSON — and every `fix:` naming
   // `x help --json` would be a command that does not do what it says.
-  const json = tokens.some((token) => token === '--json' || token === '-j');
+  const json = wantsJson(tokens);
   if (VERSION_ALIASES.has(first)) return blank('version', specs, json);
   if (HELP_ALIASES.has(first)) {
     const rest = tokens.slice(1).filter((token) => !token.startsWith('-'));
@@ -198,7 +233,10 @@ function readSubcommand(spec: CommandSpec, positionals: readonly string[]): stri
   const allowed = spec.subcommands;
   if (allowed === undefined || allowed.length === 0) return undefined;
   const token = positionals[0];
-  if (token === undefined) return allowed[0];
+  if (token === undefined) {
+    if (spec.defaultSubcommand !== undefined) return spec.defaultSubcommand;
+    throw new MissingSubcommandError({ command: spec.name, known: allowed });
+  }
   if (allowed.includes(token)) return token;
   const suggestion = nearest(token, allowed);
   throw new UnknownCommandError(

package/src/policy-facts.ts

@@ -12,12 +12,30 @@ import { devActors } from './dev-policy';
 
 const isDefined = <T>(value: T | undefined): value is T => value !== undefined;
 
-/** Descriptor names whose `capability` is exactly this permission — shared by list and explain. */
-const namesEnforcing = <D extends { readonly name: string; readonly capability: string }>(
+/**
+ * Descriptor names whose policy references this permission — shared by list and explain.
+ *
+ * Matched on `permissions` and never on `capability`. `capability` is the DISPLAY label, and a
+ * composite policy renders as `and(post:publish, org:administer)` — never a bare permission — so
+ * an equality test against it reported every action guarded by a composite as enforcing nothing.
+ * That is `unenforced`: "this grant does nothing", printed about every non-trivial rule in a real
+ * app, to the compliance engineer reading it before an access review.
+ */
+const namesEnforcing = <
+  D extends { readonly name: string; readonly permissions: readonly string[] },
+>(
   descriptors: readonly D[],
   permission: string,
 ): readonly string[] =>
-  descriptors.filter((descriptor) => descriptor.capability === permission).map((d) => d.name);
+  descriptors
+    .filter((descriptor) => descriptor.permissions.includes(permission))
+    .map((d) => d.name);
+
+/** The same rule as `namesEnforcing`, for the two `explain` filters that keep the descriptor. */
+const enforces = (
+  descriptor: { readonly permissions: readonly string[] },
+  permission: string,
+): boolean => descriptor.permissions.includes(permission);
 
 // ── list ──────────────────────────────────────────────────────────────────
 
@@ -66,7 +84,14 @@ export type SubjectKind = 'permission' | DeclarationKind;
 export interface DeclarationExplanation {
   readonly name: string;
   readonly kind: DeclarationKind;
+  /** The policy's DISPLAY label — `and(post:publish, org:administer)` for a composite. */
   readonly capability: string;
+  /**
+   * Every permission the policy tree references, flattened. What a grant is MATCHED against; the
+   * label above is what a person reads. Published because `grantingRoles` is derived from it —
+   * `rolesGranting('and(a:b, c:d)')` is a lookup that can only ever answer nothing.
+   */
+  readonly permissions: readonly string[];
   readonly label: string;
   /**
    * Whether this policy can be decided at all outside a request. `false` when evaluating it
@@ -117,6 +142,7 @@ const explainAction = (action: AnyAction): DeclarationExplanation => {
     name: descriptor.name,
     kind: 'action',
     capability: descriptor.capability,
+    permissions: descriptor.permissions,
     label: action.policy.label,
     ...matrixFor(action.policy),
   };
@@ -128,6 +154,7 @@ const explainQuery = (query: AnyQuery): DeclarationExplanation => {
     name: descriptor.name,
     kind: 'query',
     capability: descriptor.capability,
+    permissions: descriptor.permissions,
     label: query.policy.label,
     ...matrixFor(query.policy),
   };
@@ -168,12 +195,12 @@ export function explainPolicy(name: string): SubjectExplanation | undefined {
     const { permission } = resolved;
     const declarations = [
       ...describeActions()
-        .filter((descriptor) => descriptor.capability === permission)
+        .filter((descriptor) => enforces(descriptor, permission))
         .map((descriptor) => getAction(descriptor.name))
         .filter(isDefined)
         .map(explainAction),
       ...describeQueries()
-        .filter((descriptor) => descriptor.capability === permission)
+        .filter((descriptor) => enforces(descriptor, permission))
         .map((descriptor) => getQuery(descriptor.name))
         .filter(isDefined)
         .map(explainQuery),
@@ -190,7 +217,12 @@ export function explainPolicy(name: string): SubjectExplanation | undefined {
   return {
     subject: name,
     kind: resolved.kind,
-    grantingRoles: rolesGranting(declaration.capability),
+    // The union over every permission the policy references, not a lookup on the label: a
+    // composite-guarded action reported NO granting roles at all, which reads as "nobody can do
+    // this" about a declaration half the roles in the app can reach.
+    grantingRoles: [
+      ...new Set(declaration.permissions.flatMap((permission) => rolesGranting(permission))),
+    ].sort(),
     declarations: [declaration],
   };
 }

package/src/policy-fixture.ts

@@ -15,19 +15,26 @@ interface PostRow {
 }
 
 /**
- * Three permissions, three roles, two actions and two queries — each fact earning its place.
+ * Four permissions, three roles, two actions and two queries — each fact earning its place.
  *
- * `post:read` is declared but enforced by nothing: `archivePost`'s policy grants that permission
- * to its second clause, but the compound policy's own capability is `and(post:publish, post:read)`
- * — a different string — so `post:read` alone stays unenforced. `post:publish` is enforced by an
- * action AND a query at once, so the aggregation across declarations has something to aggregate.
+ * `archivePost` is guarded by a COMPOSITE, and that is the point of it: its display capability is
+ * the label `and(post:publish, post:read)`, which is not any permission, so a report that matched
+ * on the label counted this action as enforcing nothing and printed both of its permissions as
+ * dead grants. It enforces two, and the facts say so.
+ *
+ * `post:delete` is the control: declared, granted to `admin`, enforced by nothing at all. It is
+ * what a genuinely dead grant looks like, and it is what keeps `unenforced` a claim worth making
+ * now that a composite no longer lands in it by accident.
+ *
+ * `post:publish` is enforced by two actions AND a query, so the aggregation across declarations
+ * has something to aggregate.
  *
  * Registers only; the registries are process-global, so the caller clears them first.
  */
 export function registerPolicyFixture(): void {
-  definePermissions(['post:publish', 'post:read', 'feed:read'] as const);
+  definePermissions(['post:publish', 'post:read', 'post:delete', 'feed:read'] as const);
   defineRoles({
-    admin: { grants: ['post:publish', 'post:read', 'feed:read'] },
+    admin: { grants: ['post:publish', 'post:read', 'post:delete', 'feed:read'] },
     editor: { grants: ['post:publish', 'post:read'] },
     reader: { grants: ['post:read', 'feed:read'] },
   });

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. */