@ultimat3/cli 29.4.0 → 30.1.0

package/src/docs-section.ts

@@ -0,0 +1,69 @@
+// `x docs Upgrading#28x--2900-entry-by-entry` — a wiki topic, answered with its WHOLE section. A
+// search hit carries a capped excerpt; an agent moving one major needs every entry of that major,
+// and the 386 kB page it lives on is the thing it must not have to read.
+
+// why: Bun ships no path module; the page is joined onto the wiki directory the CLI resolved.
+import { join } from 'node:path';
+import { wikiSection } from '@ultimat3/manifest';
+import type { WikiSource } from './docs-sources';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+
+/**
+ * `Upgrading#anchor` or `wiki.Upgrading#anchor`. The page is a bare file stem — no `/`, no `.` —
+ * so the topic can only ever name a file directly inside the wiki directory.
+ */
+const WIKI_TOPIC = /^(?:wiki\.)?([A-Za-z0-9][A-Za-z0-9-]*)#([^\s#/]+)$/;
+
+export interface WikiTopic {
+  readonly page: string;
+  readonly anchor: string;
+}
+
+export function parseWikiTopic(query: string): WikiTopic | undefined {
+  const match = WIKI_TOPIC.exec(query);
+  if (match === null) return undefined;
+  return { page: match[1] ?? '', anchor: match[2] ?? '' };
+}
+
+/**
+ * The section, or `undefined` when the page or the anchor is not in this install — the caller then
+ * answers as for any question, so a stale anchor still ends in the nearest topics.
+ */
+export async function sectionResult(
+  wiki: WikiSource,
+  topic: WikiTopic,
+  query: string,
+): Promise<CommandResult | undefined> {
+  if (topic.page === 'Error-Codes') return undefined;
+  const file = Bun.file(join(wiki.dir, `${topic.page}.md`));
+  if (!(await file.exists())) return undefined;
+  const text = wikiSection(await file.text(), topic.anchor);
+  if (text === undefined) return undefined;
+  const id = `wiki.${topic.page}#${topic.anchor}`;
+  return {
+    ok: true,
+    command: 'docs',
+    summary: msg('cli.docs.found', { count: 1, query }),
+    // The page's own prose, verbatim: quoted source, not this command's wording.
+    lines: text.split('\n').map((line) => `  ${line}`),
+    data: {
+      matches: [
+        {
+          topic: id,
+          package: '@ultimat3/cli',
+          version: wiki.version,
+          kind: 'guide',
+          title: text.split('\n')[0]?.replace(/^#+\s*/, '') ?? '',
+          text,
+          symbols: [],
+          source: `${wiki.relative}/${topic.page}.md`,
+          matched: [],
+          score: 0,
+        },
+      ],
+      suggestions: [],
+      query,
+    },
+  };
+}

package/src/docs-sources.ts

@@ -0,0 +1,100 @@
+// What `x docs` reads: every framework package the installed CLI can see, and the wiki its tarball
+// ships. Two scope directories, because Bun's isolated layout puts only an app's DIRECT
+// dependencies under its own `node_modules/@ultimat3`: measured on a fresh install, `x docs` saw one
+// package of 28 and answered "nothing" for `upload a file to s3`.
+
+// why: Bun ships no path module and no synchronous existence check for a path.
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { DocEntry } from '@ultimat3/manifest';
+import { scanInstalledDocs, scanWikiDocs } from '@ultimat3/manifest';
+import { posixRelative } from './posix-path';
+
+/** This CLI's own package directory: `src/` is where every module of it lives, installed or not. */
+export const cliPackageDir = (): string => dirname(import.meta.dir);
+
+/**
+ * The wiki pages beside this CLI. Installed, `prepack` copied them into the tarball's `wiki/`; in
+ * this repository they are the checkout's own `wiki/`, two directories up from `packages/cli`, and
+ * nothing is copied. `Home.md` is the page every wiki has, so its absence means no wiki at all.
+ */
+export function wikiDirFor(cliDir: string): string | undefined {
+  const shipped = join(cliDir, 'wiki');
+  if (existsSync(join(shipped, 'Home.md'))) return shipped;
+  // Two up is the repository root only when it holds THIS `packages/cli`. Installed, two up from
+  // `node_modules/@ultimat3/cli` is `node_modules/`, and an npm package named `wiki` is not ours.
+  const root = join(cliDir, '..', '..');
+  if (!isSameDir(join(root, 'packages', 'cli'), cliDir)) return undefined;
+  const checkout = join(root, 'wiki');
+  return existsSync(join(checkout, 'Home.md')) ? checkout : undefined;
+}
+
+const isSameDir = (a: string, b: string): boolean => {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return false;
+  }
+};
+
+/** Where the shipped wiki is, and the CLI version it shipped in: what a wiki entry is dated by. */
+export interface WikiSource {
+  readonly dir: string;
+  /** `dir` relative to the CLI package: what a hit's `source` is written against. */
+  readonly relative: string;
+  readonly version: string;
+}
+
+export interface DocsCorpus {
+  readonly entries: readonly DocEntry[];
+  /** `undefined` when the install ships no wiki — reported by the caller, never silently empty. */
+  readonly wiki: WikiSource | undefined;
+}
+
+async function versionOf(cliDir: string): Promise<string> {
+  const file = Bun.file(join(cliDir, 'package.json'));
+  if (!(await file.exists())) return '';
+  const parsed: unknown = await file.json().catch(() => undefined);
+  const version: unknown =
+    typeof parsed === 'object' && parsed !== null ? Reflect.get(parsed, 'version') : undefined;
+  return typeof version === 'string' ? version : '';
+}
+
+export async function wikiSource(
+  cliDir: string = cliPackageDir(),
+): Promise<WikiSource | undefined> {
+  const dir = wikiDirFor(cliDir);
+  if (dir === undefined) return undefined;
+  // Forward slashes on every OS: `source` is printed and pasted, never handed back to `join`.
+  const fromCli = posixRelative(cliDir, dir);
+  return { dir, relative: fromCli, version: await versionOf(cliDir) };
+}
+
+/**
+ * The app's own scope first, then the CLI's: the CLI's store entry holds the CLI and every package
+ * it depends on, and the app's adds the ones only the app installed (`ui`, `scraping`). A package
+ * in both is read once, from the app's, which is the copy the app runs.
+ */
+export async function loadDocs(
+  appScope: string,
+  cliDir: string = cliPackageDir(),
+): Promise<DocsCorpus> {
+  const seen = new Set<string>();
+  const entries: DocEntry[] = [];
+  for (const scope of new Set([appScope, dirname(cliDir)])) {
+    const scanned = await scanInstalledDocs(scope);
+    entries.push(...scanned.filter((entry) => !seen.has(entry.package)));
+    for (const entry of scanned) seen.add(entry.package);
+  }
+  const wiki = await wikiSource(cliDir);
+  if (wiki !== undefined) {
+    entries.push(
+      ...(await scanWikiDocs(wiki.dir, {
+        package: '@ultimat3/cli',
+        version: wiki.version,
+        dir: wiki.relative,
+      })),
+    );
+  }
+  return { entries, wiki };
+}

package/src/doctor-auth.ts

@@ -69,9 +69,18 @@ export function authStorageFindings(fact: AuthStorageFact): readonly Finding[] {
  * PGlite and takes the single-writer lock the next command needs. A server that does not answer
  * is `database()`'s finding to make, so every failure here is "nothing to report".
  */
-export async function authStorageProbe(url: string | undefined): Promise<AuthStorageFact> {
+export async function authStorageProbe(
+  url: string | undefined,
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): Promise<AuthStorageFact> {
   if (url === undefined || url.trim() === '') return NO_AUTH_STORAGE_FACT;
-  const client = postgresClient({ url, applicationName: 'x-doctor' });
+  let client: ReturnType<typeof postgresClient>;
+  try {
+    client = postgresClient({ url, env, applicationName: 'x-doctor' });
+  } catch {
+    // `poolerProbe`'s finding: a refused `DATABASE_POOLER` or role, said once.
+    return NO_AUTH_STORAGE_FACT;
+  }
   try {
     const present = async (table: string): Promise<boolean> => {
       const rows = await client.query<{ readonly present: boolean }>(

package/src/doctor-chart-alerts.ts

@@ -0,0 +1,55 @@
+// `x doctor`'s chart listing: the monitoring templates an app's Helm chart predates, with the one
+// command that writes them. A LISTING, never a finding: the chart is the app's, and a chart that
+// declines the operator's objects (or keeps its own) is a decision `x doctor` must not overrule.
+
+// why: a synchronous exists check; Bun.file().exists() is async and the probe is not.
+import { existsSync } from 'node:fs';
+// why: Bun exposes no path-join primitive; existsSync takes one already joined.
+import { join } from 'node:path';
+import { CHART_FILE } from './generate-chart-alerts';
+import { msg } from './messages';
+import type { CommandResult, JsonValue } from './output';
+import { names } from './templates';
+import { helmMonitoringFiles } from './templates/scaffold-helm-alerts';
+
+/** The command every row names: it writes only the files the chart lacks. */
+export const CHART_ALERTS_ADD = 'x g chart-alerts';
+
+/** The rule, pure: which monitoring templates are absent from a chart that exists. */
+export function missingMonitoringTemplates(
+  hasChart: boolean,
+  exists: (path: string) => boolean,
+): readonly string[] {
+  if (!hasChart) return [];
+  // The paths only — they do not depend on the chart's name.
+  return helmMonitoringFiles(names('app'))
+    .map((file) => file.path)
+    .filter((path) => !exists(path));
+}
+
+/** The I/O half. An app with no chart deploys some other way, and is listed nothing. */
+export function chartAlertsProbe(root: string): readonly string[] {
+  return missingMonitoringTemplates(existsSync(join(root, CHART_FILE)), (path) =>
+    existsSync(join(root, path)),
+  );
+}
+
+/** The listing, on a result `x doctor` already decided: `ok` and the findings stay as they came. */
+export function withChartAlertsListing(
+  result: CommandResult,
+  missing: readonly string[],
+): CommandResult {
+  if (missing.length === 0) return result;
+  const data = typeof result.data === 'object' && result.data !== null ? result.data : {};
+  const chartAlerts: JsonValue = { missing: [...missing], add: CHART_ALERTS_ADD };
+  return {
+    ...result,
+    data: { ...(data as Record<string, JsonValue>), chartAlerts },
+    lines: [
+      ...(result.lines ?? []),
+      msg('cli.doctor.chartAlerts', { count: missing.length }),
+      ...missing.map((path) => `  ${path}`),
+      `  ${CHART_ALERTS_ADD}`,
+    ],
+  };
+}

package/src/doctor-pooler.ts

@@ -0,0 +1,107 @@
+// `x doctor`'s statement bound: what the session in force actually reads, on demand — the boot's
+// `X_DB_STATEMENT_BOUND_LOST` line, asked without booting. And the one fact a pooler changes about a
+// worker: the wake is off, the poll answers instead. Allowed and cheap, so a line and never a finding.
+
+import { type Role, resolveRole } from '@ultimat3/core';
+import type { PoolerMode, StatementBound } from '@ultimat3/db';
+import { DbError, lostStatementBound, postgresClient, statementBound } from '@ultimat3/db';
+import { IDLE_POLL_CEILING_MS } from '@ultimat3/jobs';
+import { msg } from './messages';
+import type { CommandResult, Finding, JsonValue } from './output';
+import { findingFrom } from './output';
+
+export interface PoolerFact {
+  readonly role: Role | undefined;
+  readonly pooler: PoolerMode | undefined;
+  /** `undefined` when there was no session to read: no external database, or a refusal. */
+  readonly bound: StatementBound | undefined;
+  /** The pooler refused this configuration: every other database probe would only repeat it. */
+  readonly refused: Finding | undefined;
+}
+
+export const NO_POOLER_FACT: PoolerFact = {
+  role: undefined,
+  pooler: undefined,
+  bound: undefined,
+  refused: undefined,
+};
+
+/**
+ * The I/O half, external databases only: `probeDatabase`'s rule. An unreachable server is
+ * `database()`'s finding to make, so only a pooler's own refusal is reported from here.
+ */
+export async function poolerProbe(
+  url: string | undefined,
+  env: Readonly<Record<string, string | undefined>>,
+): Promise<PoolerFact> {
+  if (url === undefined || url.trim() === '') return NO_POOLER_FACT;
+  let role: Role;
+  let client: ReturnType<typeof postgresClient>;
+  try {
+    role = resolveRole({ env });
+    client = postgresClient({ url, role, env, applicationName: 'x-doctor' });
+  } catch (error) {
+    return { ...NO_POOLER_FACT, refused: findingFrom(error) };
+  }
+  // The client's answer, so the mode reported is the mode it connected with.
+  const { pooler } = client;
+  try {
+    return { role, pooler, bound: await statementBound(client), refused: undefined };
+  } catch (error) {
+    const refused =
+      error instanceof DbError && error.code === 'X_DB_POOLER_OPTIONS_REFUSED'
+        ? findingFrom(error)
+        : undefined;
+    return { role, pooler, bound: undefined, refused };
+  } finally {
+    await client.close();
+  }
+}
+
+/** The rule, pure: a refusal, or a bound that is not the role's. */
+export function poolerFindings(fact: PoolerFact): readonly Finding[] {
+  if (fact.refused !== undefined) return [fact.refused];
+  if (fact.bound === undefined || fact.role === undefined) return [];
+  const lost = lostStatementBound(fact.bound, fact.role, fact.pooler);
+  return lost === undefined ? [] : [findingFrom(lost)];
+}
+
+const readingOf = (reading: StatementBound['statementTimeout']): JsonValue => ({
+  appliedMs: reading.applied,
+  expectedMs: reading.expected,
+});
+
+/** The report, on a result `x doctor` already decided: `ok` and the findings stay as they came. */
+export function withPoolerReport(result: CommandResult, fact: PoolerFact): CommandResult {
+  if (fact.bound === undefined || fact.role === undefined) return result;
+  const data = typeof result.data === 'object' && result.data !== null ? result.data : {};
+  const lines: string[] = [];
+  const wakeOff = fact.role === 'worker' && fact.pooler === 'transaction';
+  if (fact.pooler !== undefined) {
+    lines.push(
+      msg('cli.doctor.poolerBound', {
+        pooler: fact.pooler,
+        role: fact.role,
+        statement: fact.bound.statementTimeout.applied,
+        idle: fact.bound.idleInTransaction.applied,
+      }),
+    );
+  }
+  if (wakeOff) lines.push(msg('cli.doctor.poolerWakeOff', { ms: IDLE_POLL_CEILING_MS }));
+  const statement: JsonValue = {
+    role: fact.role,
+    pooler: fact.pooler ?? null,
+    statementTimeout: readingOf(fact.bound.statementTimeout),
+    idleInTransaction: readingOf(fact.bound.idleInTransaction),
+  };
+  const wake: JsonValue = { off: true, pickupWithinMs: IDLE_POLL_CEILING_MS };
+  return {
+    ...result,
+    data: {
+      ...(data as Record<string, JsonValue>),
+      statementBound: statement,
+      ...(wakeOff ? { wake } : {}),
+    },
+    lines: [...(result.lines ?? []), ...lines],
+  };
+}

package/src/doctor-rolling.ts

@@ -0,0 +1,35 @@
+// `x doctor`'s reminder: an app with no `rollingSince` is not judged by the rolling rail, and one
+// line says which id turns it on. A REMINDER, never a finding: the rail is off because an applied
+// migration cannot gain a marker, and a red `x doctor` over that would be a failure nobody can clear.
+
+import { msg } from './messages';
+import { readMigrations } from './migrations';
+import type { CommandResult, JsonValue } from './output';
+import { readVerifyFloor } from './verify-floor';
+
+export interface RollingReminder {
+  /** The newest migration id: what `rollingSince` is set to, judging only what comes after. */
+  readonly newest: string;
+}
+
+/** The I/O half. `undefined` when the rail is on, or when an app has no migration to name. */
+export async function rollingSinceProbe(root: string): Promise<RollingReminder | undefined> {
+  if ((await readVerifyFloor(root))?.rollingSince !== undefined) return undefined;
+  const newest = (await readMigrations(root)).at(-1)?.id;
+  return newest === undefined ? undefined : { newest };
+}
+
+/** The line, on a result `x doctor` already decided: `ok` and the findings stay as they came. */
+export function withRollingReminder(
+  result: CommandResult,
+  reminder: RollingReminder | undefined,
+): CommandResult {
+  if (reminder === undefined) return result;
+  const data = typeof result.data === 'object' && result.data !== null ? result.data : {};
+  const rolling: JsonValue = { unset: true, newest: reminder.newest };
+  return {
+    ...result,
+    data: { ...(data as Record<string, JsonValue>), rolling },
+    lines: [...(result.lines ?? []), msg('cli.doctor.rollingSince', { newest: reminder.newest })],
+  };
+}

package/src/doctor-row-security.ts

@@ -0,0 +1,40 @@
+// Single responsibility: `x doctor`'s row-security question, asked without booting — with
+// `database.rowSecurity` on, is the role `DATABASE_URL` connects as one Postgres applies policies
+// to. The boot refuses the same role (`X_DB_ROW_SECURITY_BYPASSED`); this says so before a deploy.
+
+import { resolveRole } from '@ultimat3/core';
+import { assertRowSecurityBinds, DbError, postgresClient } from '@ultimat3/db';
+import { loadAppConfig } from './app-config-load';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+import { rowSecurityDeclared } from './row-security-boot';
+
+/**
+ * External databases only: an embedded one serves as `x_app` by construction (`serveAsAppRole`).
+ * An unreachable server is `database()`'s finding to make, so only the exemption is reported here.
+ * The flag-against-migrations half is `X_DB_ROW_SECURITY_DRIFT`, reported by the drift probe.
+ */
+export async function rowSecurityProbe(
+  root: string,
+  url: string | undefined,
+  env: Readonly<Record<string, string | undefined>>,
+): Promise<readonly Finding[]> {
+  if (url === undefined || url.trim() === '') return [];
+  if (!rowSecurityDeclared(await loadAppConfig(root))) return [];
+  const client = postgresClient({
+    url,
+    role: resolveRole({ env }),
+    env,
+    applicationName: 'x-doctor',
+  });
+  try {
+    await assertRowSecurityBinds(client);
+    return [];
+  } catch (error) {
+    return error instanceof DbError && error.code === 'X_DB_ROW_SECURITY_BYPASSED'
+      ? [findingFrom(error)]
+      : [];
+  } finally {
+    await client.close();
+  }
+}

package/src/document-options.ts

@@ -85,4 +85,17 @@ export interface DocumentOptions {
    * app declares no favicon — the browser's own `/favicon.ico` request is then the only one.
    */
   readonly faviconHead?: string;
+  /**
+   * Tags on `app/` documents ONLY — `/x-client-errors.js` (`client-errors-routes.ts`) when
+   * `clientErrors.enabled`, and `/x-client-vitals.js` (`client-vitals-route.ts`) when
+   * `clientErrors.vitals` lists `app`. A `site/` document never carries them: the static path
+   * never pays for the app path (axiom 6).
+   */
+  readonly appHead?: string;
+  /**
+   * Tags on `site/` documents ONLY — today `/x-client-vitals.js`, and only when
+   * `clientErrors.vitals.surfaces` lists `site`: the static path opts in by name, and the bytes
+   * are then charged to its own budget (`prerender-served.ts`'s `vitalsMeasure`).
+   */
+  readonly siteHead?: string;
 }

package/src/drill-sync-lane.ts

@@ -0,0 +1,25 @@
+// Where `x drill`'s sync client dials: the fleet's `sync` role binds its socket on PORT + 1
+// (`syncPortFor`, the rule `role-sync.ts` listens by), at the node's `/_x/sync`. A fleet with no
+// sync role has no lane, and `sync-resumes` is then red on no evidence.
+
+import { PROTOCOL_VERSION } from '@ultimat3/realtime';
+import type { DrillFleet, DrillSyncLane } from '@ultimat3/testing';
+import { startDrillSync } from '@ultimat3/testing';
+import { syncPortFor } from './flag-number';
+
+/** The sync node's socket URL for a role handed `origin` as its PORT. */
+export function drillSyncUrl(origin: string): string {
+  const url = new URL(origin);
+  url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+  url.port = String(syncPortFor(Number(url.port)));
+  url.pathname = '/_x/sync';
+  return url.href;
+}
+
+/** The lane `runDrill` starts with the fault, or none when the fleet runs no sync role. */
+export function drillSyncLane(fleet: DrillFleet): (() => DrillSyncLane) | undefined {
+  const sync = fleet.roles.get('sync');
+  if (sync === undefined) return undefined;
+  const url = drillSyncUrl(sync.origin);
+  return () => startDrillSync({ url, protocolVersion: PROTOCOL_VERSION });
+}

package/src/drill-targets.ts

@@ -0,0 +1,39 @@
+// What `x drill`'s load sends: the site's parameterless pages, read anonymously, and the write
+// lane — every action an anonymous POST can reach, each request a fresh input drawn as `x exercise`
+// draws one, the app's `exercise.ts` honoured. The writes are how a job reaches the queue over HTTP.
+
+import { toRoute } from '@ultimat3/action';
+import type { DrillTarget, DrillWrites } from '@ultimat3/testing';
+import { drillWriteTargets } from '@ultimat3/testing';
+import { loadApp } from './app-load';
+import { readExerciseOverrides } from './exercise-overrides';
+import { plainAppRoutes, routeRows } from './route-table';
+
+export interface DrillLoadPlan {
+  readonly targets: readonly DrillTarget[];
+  readonly skipped: DrillWrites['skipped'];
+}
+
+/** The load for the app at `root`; loading it is what fills the registries read here. */
+export async function drillTargets(root: string): Promise<DrillLoadPlan> {
+  await loadApp(root);
+  // Anonymous pages: a non-2xx is the fault's, never a 401's.
+  const reads = routeRows(await plainAppRoutes(root))
+    .filter((route) => route.surface === 'site' && !/[[:*]/.test(route.path))
+    .map((route): DrillTarget => ({ method: 'GET', path: route.path }));
+  const { listActions } = await import('@ultimat3/action');
+  const writes = await drillWriteTargets({
+    actions: listActions().map((action) => {
+      const route = toRoute(action);
+      return {
+        name: action.name,
+        method: route.method,
+        path: route.path,
+        anonymous: route.meta.auth === 'public',
+        input: action.input,
+      };
+    }),
+    overrides: await readExerciseOverrides(root),
+  });
+  return { targets: [...reads, ...writes.targets], skipped: writes.skipped };
+}

package/src/duplicate-packages.ts

@@ -4,7 +4,7 @@
 // `packages/i18n` workspace pinned `@ultimat3/i18n@19.0.0` while its root had 19.1.0 registered
 // every catalog into the workspace's copy, the CLI read the root's, and `x i18n check` answered
 // `X_CATALOG_UNREGISTERED` with a fix that said to move a `defineCatalogs()` call that was already
-// exactly where the fix said to put it (ai-maxxing, 2026-09-05). The same split is the one
+// exactly where the fix said to put it (one adopter, 2026-09-05). The same split is the one
 // `local-cli.ts` hands over for — a global `x` is a second copy of `@ultimat3/entity` — except this
 // one lives inside the app's own `node_modules`, where no hand-over can reach it.
 

package/src/env-production.ts

@@ -0,0 +1,93 @@
+// Single responsibility: the `.env.production` `x env init --production` writes, as text. Pure:
+// the caller hands in the app's env declaration, its compose file and the randomness, so a test
+// can read every line without a filesystem or a real secret.
+
+import type { EnvSchema, EnvVarDecl } from '@ultimat3/core';
+import { VAPID_PRIVATE_KEY_ENV, VAPID_PUBLIC_KEY_ENV } from '@ultimat3/pwa';
+import { composeDatabase, composeRequiredVars, DEFAULT_IMAGE } from './cmd-deploy-compose';
+import { type AppSecretFacts, configOwes, FRAMEWORK_SECRETS } from './framework-env';
+
+/** The two origins one box serves on: the pages on :3000, the sync socket on :3001. */
+export const LOCAL_ORIGINS: Readonly<Record<string, string>> = {
+  APP_URL: 'http://localhost:3000',
+  SYNC_URL: 'ws://localhost:3001/_x/sync',
+};
+
+export interface ProductionEnvInput {
+  readonly schema: EnvSchema;
+  /** `docker/docker-compose.prod.yml`'s text, or `undefined` when the app has none. */
+  readonly compose: string | undefined;
+  readonly facts: AppSecretFacts;
+  /** One fresh secret per call: 32 random bytes as hex, `openssl rand -hex 32`'s shape. */
+  readonly secret: () => string;
+  /** The Web Push pair, minted by the caller only when `facts.push` owes one. */
+  readonly vapid?: { readonly publicKey: string; readonly privateKey: string } | undefined;
+}
+
+export interface ProductionEnv {
+  readonly contents: string;
+  /** Every key written with a value, in file order. Names only: the values are secrets. */
+  readonly written: readonly string[];
+  /** Keys the file must carry and nothing here can know: written empty, for the operator. */
+  readonly unfilled: readonly string[];
+}
+
+/** Required at boot: no default and no `required: false`. A role-scoped key is required there. */
+export const requiredAtBoot = (decl: EnvVarDecl): boolean =>
+  decl.default === undefined && decl.required !== false;
+
+/**
+ * The file. Order is the reader's: the environment, the image, the database, the origins, then
+ * every secret, and last the keys left for the operator, each under the description that says
+ * what it is.
+ */
+export function productionEnvFile(input: ProductionEnvInput): ProductionEnv {
+  const values = new Map<string, string>([
+    ['ULTIMATE_ENV', 'production'],
+    ['IMAGE', DEFAULT_IMAGE],
+  ]);
+  const required = input.compose === undefined ? [] : composeRequiredVars(input.compose);
+  const db = composeDatabase(input.compose);
+  if (db !== undefined) {
+    const password = input.secret();
+    values.set('POSTGRES_PASSWORD', password);
+    values.set(
+      'DATABASE_URL',
+      `postgres://${encodeURIComponent(db.user)}:${password}@db:5432/${encodeURIComponent(db.database)}`,
+    );
+  }
+  for (const [key, origin] of Object.entries(LOCAL_ORIGINS)) {
+    if (required.includes(key) || Object.hasOwn(input.schema, key)) values.set(key, origin);
+  }
+  for (const [key, decl] of Object.entries(input.schema)) {
+    if (decl.secret === true && !values.has(key)) values.set(key, input.secret());
+  }
+  for (const owed of FRAMEWORK_SECRETS) {
+    if (!configOwes(owed, input.facts) || values.has(owed.key)) continue;
+    if (owed.key === VAPID_PUBLIC_KEY_ENV && input.vapid !== undefined) {
+      values.set(owed.key, input.vapid.publicKey);
+    } else if (owed.key === VAPID_PRIVATE_KEY_ENV && input.vapid !== undefined) {
+      values.set(owed.key, input.vapid.privateKey);
+    } else if (owed.secret !== false) {
+      values.set(owed.key, input.secret());
+    }
+  }
+  const unfilled = [
+    ...Object.entries(input.schema)
+      .filter(([key, decl]) => requiredAtBoot(decl) && !values.has(key))
+      .map(([key]) => key),
+    ...required.filter((key) => !values.has(key) && !Object.hasOwn(input.schema, key)),
+  ];
+  const lines = [
+    '# Written by `x env init --production`. Secrets: never commit this file (.gitignore covers it),',
+    '# and keep a copy in a secret store — a new POSTGRES_PASSWORD does not reach a database that',
+    '# already initialised its volume with the old one.',
+    '# APP_URL and SYNC_URL are this box on localhost: set the host your users reach.',
+    ...[...values].map(([key, value]) => `${key}=${value}`),
+    ...unfilled.flatMap((key) => [
+      `# required: ${input.schema[key]?.description ?? 'the compose file refuses to parse without it'}`,
+      `${key}=`,
+    ]),
+  ];
+  return { contents: `${lines.join('\n')}\n`, written: [...values.keys()], unfilled };
+}