@ultimat3/cli 29.4.0 → 30.1.0

package/src/cmd-doctor.ts

@@ -6,16 +6,23 @@ import { existsSync } from 'node:fs';
 import { dirname, join, resolve, sep } from 'node:path';
 import { ENV_EXAMPLE_PATH, ERROR_DOCS_URL } from '@ultimat3/core';
 import { checkDb, PGLITE_FIX, PGLITE_MISSING, PGLITE_PACKAGE, postgresClient } from '@ultimat3/db';
+import { loadApp } from './app-load';
+import { IMPORT_UNRESOLVED } from './app-load-unresolved';
 import { findAppRoot, REQUIRED_BUN, versionAtLeast } from './app-root';
 import { doctorSpec } from './cmd-doctor-spec';
 import type { CliCommand, CommandContext } from './command';
 import { checkMigrationSnapshots } from './db-snapshot';
 import { appUrlFindings } from './doctor-app-url';
 import { type AuthStorageFact, authStorageFindings, authStorageProbe } from './doctor-auth';
+import { chartAlertsProbe, withChartAlertsListing } from './doctor-chart-alerts';
 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 { PoolerFact } from './doctor-pooler';
+import { NO_POOLER_FACT, poolerFindings, poolerProbe, withPoolerReport } from './doctor-pooler';
+import { rollingSinceProbe, withRollingReminder } from './doctor-rolling';
+import { rowSecurityProbe } from './doctor-row-security';
 import type { SealedKeysFact } from './doctor-sealed';
 import { sealedKeyFindings, sealedKeysProbe } from './doctor-sealed';
 import { PORT_RANGE, portPairAfter, readIntFlag } from './flag-number';
@@ -97,6 +104,10 @@ export interface DoctorProbe {
    * secrets, and tables no release reads. Asked of an external database only.
    */
   authStorage(): Promise<AuthStorageFact>;
+  /** The statement bound the session really reads, and what a pooler refused (`doctor-pooler.ts`). */
+  pooler(): Promise<PoolerFact>;
+  /** With `database.rowSecurity` on, whether the serving role is exempt (`doctor-row-security.ts`). */
+  rowSecurity?(): Promise<readonly Finding[]>;
 }
 
 /** What `x doctor` reads about the embedded database, without opening it. */
@@ -201,7 +212,12 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
   }
   if (probe.root === undefined) {
     findings.push(
-      finding('X_NOT_IN_APP', 'no app.config.ts at or above the working directory', 'x new myapp'),
+      // Not `x new`: outside an app `x` is on no PATH, and `bunx x` fetches an unrelated npm package.
+      finding(
+        'X_NOT_IN_APP',
+        'no app.config.ts at or above the working directory',
+        'bunx create-ultimate myapp && cd myapp',
+      ),
     );
     return findings;
   }
@@ -250,12 +266,19 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
   // holds the rule and the reasons.
   const offline = offlineFallbackFinding(await probe.offlineFallback());
   if (offline !== undefined) findings.push(offline);
-  const database = await probe.database();
+  const pooler = await probe.pooler();
+  findings.push(...poolerFindings(pooler));
+  // A pooler's refusal is every other database probe's answer too, and its fix is the true one: this
+  // one's says "set DATABASE_URL" to an operator whose URL is right.
+  const database = pooler.refused === undefined ? await probe.database() : null;
   if (database !== null) findings.push(database);
   // The other half of the same question, and the half a bare VM lands on: `database()` is silent
   // where there is no `DATABASE_URL`, and that silence IS the bare-VM configuration.
   const embedded = embeddedDatabaseFinding(await probe.embeddedDatabase());
   if (embedded !== undefined) findings.push(embedded);
+  // Asked only of a database that answered: an unreachable one is already the finding above.
+  const reachable = pooler.refused === undefined && database === null;
+  if (reachable) findings.push(...((await probe.rowSecurity?.()) ?? []));
   findings.push(...(await probe.drift()));
   // Last, and it is why `X_CLI_UNEXPECTED`'s `fix: x doctor --json` is not a dead end on the path an
   // author reaches it from: `x db gen` throwing `X_MIGRATION_SNAPSHOT_MISSING` used to be a
@@ -333,9 +356,17 @@ const installedAbove = (dir: string, specifier: string): boolean => {
  * The pool is CLOSED on every path — this command exits, and a held pool is a connection slot the
  * next `x db migrate` cannot have.
  */
-async function probeDatabase(url: string | undefined): Promise<Finding | null> {
+async function probeDatabase(
+  url: string | undefined,
+  env: Readonly<Record<string, string | undefined>>,
+): Promise<Finding | null> {
   if (externalUrl(url) === undefined) return null;
-  const client = postgresClient({ url, applicationName: 'x-doctor' });
+  let client: ReturnType<typeof postgresClient>;
+  try {
+    client = postgresClient({ url, env, applicationName: 'x-doctor' });
+  } catch (error) {
+    return findingFrom(error);
+  }
   try {
     const report = await checkDb(client);
     if (report.ok) return null;
@@ -369,7 +400,7 @@ export function probeFor(
     frameworkFindings: machineSecretFindings(env),
     exists: (relativePath) => (root === undefined ? false : existsSync(join(root, relativePath))),
     portFree,
-    database: () => probeDatabase(process.env['DATABASE_URL']),
+    database: () => probeDatabase(process.env['DATABASE_URL'], env),
     // `root ?? cwd` because the walk needs a directory that exists; outside an app `runDoctor`
     // returns on `X_NOT_IN_APP` before this is ever asked, so the value only has to be honest.
     embeddedDatabase: async () => ({
@@ -377,23 +408,36 @@ export function probeFor(
       resolved: installedAbove(root ?? cwd, PGLITE_PACKAGE),
     }),
     drift: async () => (root === undefined ? [] : checkMigrationDrift(root)),
-    snapshots: async () => (root === undefined ? [] : checkMigrationSnapshots(root)),
+    // The import half too: `X_CLI_UNEXPECTED` used to send a reader here and find this silent.
+    snapshots: async () =>
+      root === undefined
+        ? []
+        : [...(await unresolvedImportFindings(root)), ...(await checkMigrationSnapshots(root))],
     // `routes: undefined` outside an app is "not judged", which is what the caller already is:
     // `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),
-    authStorage: () => authStorageProbe(process.env['DATABASE_URL']),
+    authStorage: () => authStorageProbe(process.env['DATABASE_URL'], env),
+    pooler: () => poolerProbe(process.env['DATABASE_URL'], env),
+    rowSecurity: async () =>
+      root === undefined ? [] : rowSecurityProbe(root, process.env['DATABASE_URL'], env),
   };
 }
 
+/** What a load reports, narrowed to the one failure a doctor can name a repair for. */
+const unresolvedImportFindings = async (root: string): Promise<readonly Finding[]> =>
+  (await loadApp(root)).findings.filter((finding) => finding.code === IMPORT_UNRESOLVED);
+
 export const doctorCommand: CliCommand = {
   spec: doctorSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const port = doctorPort(ctx.args, ctx.env);
     const probe = probeFor(ctx.cwd, ctx.bunVersion, port, ctx.env);
-    const findings = await runDoctor(probe);
+    // Asked once: `runDoctor` reads the verdict and the report beside it reads the numbers.
+    const pooler = probe.root === undefined ? NO_POOLER_FACT : await probe.pooler();
+    const findings = await runDoctor({ ...probe, pooler: async () => pooler });
     const listed = withGuardListing(
       {
         ok: findings.length === 0,
@@ -409,9 +453,22 @@ export const doctorCommand: CliCommand = {
       probe.root === undefined ? [] : await shippedGuardsProbe(probe.root),
     );
     // The second listing: what the coverage floor does not see (`doctor-coverage.ts`).
-    return withCoverageExcludes(
+    const covered = withCoverageExcludes(
       listed,
       probe.root === undefined ? [] : await coverageExcludesProbe(probe.root),
     );
+    // The third: the monitoring templates the app's chart predates (`doctor-chart-alerts.ts`).
+    const charted = withChartAlertsListing(
+      covered,
+      probe.root === undefined ? [] : chartAlertsProbe(probe.root),
+    );
+    // A reminder, not a finding: the rolling rail is off until this is set (`doctor-rolling.ts`).
+    return withPoolerReport(
+      withRollingReminder(
+        charted,
+        probe.root === undefined ? undefined : await rollingSinceProbe(probe.root),
+      ),
+      pooler,
+    );
   },
 };

package/src/cmd-drill-spec.ts

@@ -0,0 +1,25 @@
+// `x drill`'s declaration, apart from its body: the parser, `x help` and the `errors` step read it
+// without loading `cmd-drill.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const drillSpec: CommandSpec = {
+  name: 'drill',
+  summary:
+    'fault the real services under web and worker processes, and fail on any framework contract that does not hold',
+  usage: 'x drill [<name>] [--list] [--budget-ms n] [--json]',
+  requiresApp: true,
+  flags: [
+    {
+      name: 'list',
+      type: 'boolean',
+      summary: 'print every drill, its fault and the properties it holds the app to; run nothing',
+    },
+    {
+      name: 'budget-ms',
+      type: 'string',
+      summary:
+        'the request deadline the drills judge against, in place of the one derived from the app; printed in the verdict',
+    },
+  ],
+};

package/src/cmd-drill.ts

@@ -0,0 +1,176 @@
+// `x drill [<name>] [--list] [--budget-ms n]` — the app's web and worker roles as real processes on
+// real services, each fault in `@ultimat3/testing`'s drill table played through a proxy or a
+// signal, red on any framework contract that does not hold. CLI wiring only: the table, the fleet
+// and the verdict are testing's. Not a gate step: it needs Postgres, and `x verify` needs nothing.
+
+import type { AppConfig } from '@ultimat3/core';
+import { DRAIN_DEADLINE_DEFAULT_MS, MAX_TIMER_MS } from '@ultimat3/core';
+import type { Drill, DrillConfig, DrillDeclarations, DrillReport } from '@ultimat3/testing';
+import {
+  bunDrillSql,
+  DRILL_NAMES,
+  DRILLS,
+  DrillFailedError,
+  DrillServiceMissingError,
+  drillBudgets,
+  drillNamed,
+  drillRoles,
+  drillServices,
+  runDrill,
+  startDrillFleet,
+} from '@ultimat3/testing';
+import { loadAppConfig } from './app-config-load';
+import { requireAppRoot } from './app-root';
+import { drillSpec } from './cmd-drill-spec';
+import type { CliCommand, CommandContext } from './command';
+import { drillSyncLane } from './drill-sync-lane';
+import { drillTargets } from './drill-targets';
+import { UnknownCommandError } from './errors';
+import { readIntFlag } from './flag-number';
+import { msg } from './messages';
+import type { CommandResult, Finding, JsonValue } from './output';
+import { flagBool } from './parse';
+
+/** Read through `readIntFlag`, which refuses `5s`, `NaN` and a fraction with the flag's name. */
+const BUDGET_FLAG = 'budget-ms';
+
+/** How long a role may take to boot: a cold Bun over a whole app, islands included. */
+const READY_TIMEOUT_MS = 90_000;
+
+/** `@ultimat3/http`'s own default — the app's `configureHttp` is runtime code, not config. */
+const HTTP_DEFAULT_DEADLINE_MS = 30_000;
+
+const declarationsOf = (config: AppConfig | undefined): DrillDeclarations => ({
+  redis: config?.cache.tiers.includes('redis') ?? false,
+  nats:
+    config?.realtime.transport === 'nats'
+      ? { env: config.realtime.urlEnv ?? 'NATS_URL' }
+      : undefined,
+});
+
+/** The facts the thresholds derive from; `drillBudgets` screens every number it is handed. */
+const drillConfigOf = (config: AppConfig | undefined): DrillConfig =>
+  config === undefined
+    ? {
+        requestTimeoutMs: HTTP_DEFAULT_DEADLINE_MS,
+        drainDeadlineMs: DRAIN_DEADLINE_DEFAULT_MS,
+        readinessGraceMs: 0,
+        readiness: 'dependencies',
+      }
+    : {
+        requestTimeoutMs: HTTP_DEFAULT_DEADLINE_MS,
+        drainDeadlineMs: config.drain.deadlineMs,
+        readinessGraceMs: config.drain.readinessGraceMs,
+        readiness: config.health.readiness,
+      };
+
+const listing = (drill: Drill): JsonValue => ({
+  name: drill.name,
+  fault:
+    drill.fault.kind === 'service'
+      ? { service: drill.fault.service }
+      : { role: drill.fault.role, signal: drill.fault.signal },
+  holds: [...drill.holds],
+});
+
+const reportJson = (report: DrillReport): JsonValue =>
+  JSON.parse(
+    JSON.stringify(report, (_key, value: unknown) =>
+      value instanceof Map ? Object.fromEntries(value) : value,
+    ),
+  ) as JsonValue;
+
+const findingsOf = (report: DrillReport): readonly Finding[] =>
+  report.verdict.failures.map((failure) => {
+    const error = new DrillFailedError({ drill: report.name, failure });
+    return { code: error.code, cause: error.cause, fix: error.fix };
+  });
+
+export const drillCommand: CliCommand = {
+  spec: drillSpec,
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('drill', ctx.cwd).dir;
+    if (flagBool(ctx.args, 'list')) {
+      return {
+        ok: true,
+        command: 'drill',
+        summary: msg('cli.drill.listed', { count: DRILLS.length }),
+        lines: DRILLS.map((drill) => `  ${drill.name}  ${drill.holds.join(', ')}`),
+        data: { drills: DRILLS.map(listing) },
+      };
+    }
+    const override = readIntFlag(ctx.args, {
+      name: BUDGET_FLAG,
+      command: 'drill',
+      min: 1,
+      max: MAX_TIMER_MS,
+      example: 'x drill pg-blackhole --budget-ms 5000 --json',
+    });
+    const name = ctx.args.positionals[0];
+    const named = name === undefined ? undefined : drillNamed(name);
+    if (name !== undefined && named === undefined) {
+      throw new UnknownCommandError({
+        path: `drill ${name}`,
+        known: DRILL_NAMES,
+        suggestion: 'drill --list --json',
+      });
+    }
+    const config = await loadAppConfig(root);
+    const declared = declarationsOf(config);
+    // Every drill's services, decided before any process starts. A named drill's gap is thrown; in
+    // a whole run an undeclared service is stated as not run — an unset URL still refuses it all.
+    const planned: { drill: Drill; services: ReturnType<typeof drillServices> }[] = [];
+    const notRun: string[] = [];
+    for (const drill of named === undefined ? DRILLS : [named]) {
+      try {
+        planned.push({ drill, services: drillServices(drill, ctx.env, declared) });
+      } catch (error) {
+        const undeclared =
+          named === undefined &&
+          error instanceof DrillServiceMissingError &&
+          error.meta?.['gap'] === 'undeclared';
+        if (!undeclared) throw error;
+        notRun.push(drill.name);
+      }
+    }
+    const budgets = drillBudgets(drillConfigOf(config), override);
+    const { targets, skipped } = await drillTargets(root);
+    const reports: DrillReport[] = [];
+    for (const { drill, services } of planned) {
+      const fleet = await startDrillFleet({
+        root,
+        services,
+        roles: drillRoles(drill),
+        readyTimeoutMs: READY_TIMEOUT_MS,
+      });
+      const sql = bunDrillSql(fleet.databaseUrl);
+      try {
+        const sync = drillSyncLane(fleet);
+        reports.push(await runDrill({ drill, fleet, budgets, targets, sql, sync }));
+      } finally {
+        await sql.close();
+        await fleet.stop();
+      }
+    }
+    const held = reports.filter((report) => report.verdict.ok).length;
+    const findings = reports.flatMap(findingsOf);
+    return {
+      ok: findings.length === 0 && held === reports.length,
+      command: 'drill',
+      summary: msg('cli.drill.summary', { held, ran: reports.length, notRun: notRun.length }),
+      lines: [
+        ...reports.map((report) => `  ${report.verdict.ok ? 'held' : 'FAILED'}  ${report.name}`),
+        ...notRun.map((drill) => `  not run  ${drill}`),
+      ],
+      findings,
+      data: {
+        budgets: { ...budgets, override: override ?? null },
+        targets: targets.map((target) => `${target.method} ${target.path}`),
+        // The actions the write lane left out, each with why: an empty lane is never a silent one.
+        skippedWrites: skipped.map((entry) => ({ ...entry })),
+        drills: reports.map(reportJson),
+        notRun,
+      },
+    };
+  },
+};

package/src/cmd-env-init.ts

@@ -0,0 +1,102 @@
+// `x env init --production`: the one writer of `.env.production`, the file `x deploy --method
+// compose` reads and nothing else wrote. Values come from the app's own compose file and env
+// declaration (`env-production.ts`); secrets are minted here, written once, and never printed.
+
+// why: Bun.write takes neither an exclusive-create flag nor a file mode, and a secrets file needs
+// both: `wx` refuses a file that appeared since the check, 0600 keeps it from other users.
+import { writeFile } from 'node:fs/promises';
+// why: Bun ships no path-join primitive, and both files are app-root-relative.
+import { join } from 'node:path';
+import { UltimateError } from '@ultimat3/core';
+import { generateVapidKeys } from '@ultimat3/pwa';
+import { appSecretFacts, loadEnvSchema } from './app-env';
+import { requireAppRoot } from './app-root';
+import { readComposeFile } from './cmd-deploy-compose';
+import type { CommandContext } from './command';
+import { productionEnvFile } from './env-production';
+import { BadFlagError } from './errors';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import { flagBool } from './parse';
+import { PROD_ENV_FILE } from './templates/scaffold-container-compose';
+
+/**
+ * The file exists. Never overwritten: it holds the password the database volume was initialised
+ * with and the keys every session and cursor is signed with, so new ones lock the running deploy
+ * out of its own data.
+ */
+export class EnvFileExistsError extends UltimateError {
+  constructor(input: { path: string }) {
+    super({
+      code: 'X_ENV_FILE_EXISTS',
+      cause: `${input.path} already exists, and x env init would replace the secrets this deploy runs with`,
+      // `NODE_ENV=production` is what makes Bun load `.env.production` into the check's process.
+      fix: `NODE_ENV=production x env check --json   # the file is kept: edit a value in ${input.path} by hand`,
+    });
+  }
+}
+
+/** 32 random bytes as hex — `openssl rand -hex 32`, without needing openssl on the box. */
+export const randomSecret = (): string =>
+  Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString('hex');
+
+/** `.gitignore` gains the file unless a line already names it; the scaffold's ignores `.env` only. */
+async function ignoreEnvFile(root: string): Promise<boolean> {
+  const path = join(root, '.gitignore');
+  const file = Bun.file(path);
+  const text = (await file.exists()) ? await file.text() : '';
+  const lines = text.split(/\r?\n/).map((line) => line.trim());
+  if (lines.includes(PROD_ENV_FILE) || lines.includes(`/${PROD_ENV_FILE}`)) return false;
+  const separator = text === '' || text.endsWith('\n') ? '' : '\n';
+  await Bun.write(path, `${text}${separator}${PROD_ENV_FILE}\n`);
+  return true;
+}
+
+export async function initProductionEnv(
+  ctx: CommandContext,
+  secret: () => string = randomSecret,
+): Promise<CommandResult> {
+  if (!flagBool(ctx.args, 'production')) {
+    throw new BadFlagError({
+      flag: 'production',
+      command: 'env init',
+      reason: `init writes ${PROD_ENV_FILE}, the one environment a compose deploy reads`,
+      fix: 'x env init --production --json',
+    });
+  }
+  const root = requireAppRoot('env init', ctx.cwd).dir;
+  const path = join(root, PROD_ENV_FILE);
+  if (await Bun.file(path).exists()) throw new EnvFileExistsError({ path: PROD_ENV_FILE });
+  const facts = await appSecretFacts(root);
+  const env = productionEnvFile({
+    schema: (await loadEnvSchema(root)) ?? {},
+    compose: await readComposeFile(join(root, 'docker', 'docker-compose.prod.yml')),
+    facts,
+    secret,
+    vapid: facts.push ? await generateVapidKeys() : undefined,
+  });
+  // Ignored before it is written: a crash between the two must not leave secrets to `git add -A`.
+  const ignored = await ignoreEnvFile(root);
+  await writeFile(path, env.contents, { flag: 'wx', mode: 0o600 });
+  const complete = env.unfilled.length === 0;
+  return {
+    // Written either way — a rerun refuses the file — and red until every required key has a value.
+    ok: complete,
+    command: 'env',
+    summary: msg('cli.env.initialised', { path: PROD_ENV_FILE, count: env.written.length }),
+    lines: env.unfilled.map((key) => msg('cli.env.unfilled', { key, path: PROD_ENV_FILE })),
+    findings: env.unfilled.map((key) => ({
+      code: 'X_ENV_MISSING',
+      cause: `${key} is required, and nothing in this app says what its production value is`,
+      fix: `NODE_ENV=production x env check --json   # after setting ${key} in ${PROD_ENV_FILE}`,
+      at: PROD_ENV_FILE,
+    })),
+    data: {
+      path: PROD_ENV_FILE,
+      written: [...env.written],
+      unfilled: [...env.unfilled],
+      gitignored: ignored,
+    },
+    exitCode: complete ? 0 : 1,
+  };
+}

package/src/cmd-env-spec.ts

@@ -8,11 +8,18 @@ import type { CommandSpec } from './parse';
 export const envSpec: CommandSpec = {
   name: 'env',
   summary: `the typed environment declared by ${ENV_SCHEMA_EXPORT} in ${APP_CONFIG_FILE}`,
-  usage: 'x env [check|example] [--json]',
+  usage: 'x env [check|example] [--json] | x env init --production [--json]',
   requiresApp: true,
-  subcommands: ['check', 'example'],
+  subcommands: ['check', 'example', 'init'],
   // The bare `x env` answers the question the fix line on every `X_ENV_MISSING` in this
   // framework already tells its reader to run.
   defaultSubcommand: 'check',
-  flags: [],
+  flags: [
+    {
+      name: 'production',
+      type: 'boolean',
+      summary: 'write .env.production: what x deploy --method compose reads, secrets generated',
+      subcommands: ['init'],
+    },
+  ],
 };

package/src/cmd-env.ts

@@ -1,6 +1,6 @@
-// `x env` — the two things a typed environment owes an agent: the committed `.env.example` that
-// says which variables exist, and the answer to "does this process have them?". Both are
-// projections of the one `defineEnv` declaration in `app.config.ts`; neither reads a second list.
+// `x env` — the things a typed environment owes an agent: the committed `.env.example` that says
+// which variables exist, the answer to "does this process have them?", and (`init`,
+// `cmd-env-init.ts`) the deploy's `.env.production`. All read the one `defineEnv` declaration.
 
 // Bun ships no path-join primitive, and `.env.example` is written app-root-relative.
 import { join } from 'node:path';
@@ -15,7 +15,7 @@ import { appSecretFacts, envExampleFor, loadEnvSchema } from './app-env';
 import { requireAppRoot } from './app-root';
 import { envSpec } from './cmd-env-spec';
 import type { CliCommand, CommandContext } from './command';
-import { frameworkSecretFindings } from './framework-env';
+import { frameworkSecretFindings, namesNoEnvironment } from './framework-env';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 
@@ -97,12 +97,17 @@ async function checkProcessEnv(ctx: CommandContext): Promise<CommandResult> {
     ...framework,
   ];
   const ok = findings.length === 0;
+  const verdict = ok
+    ? msg('cli.env.checked', { count: total })
+    : msg('cli.env.invalid', { count: findings.length, total });
   return {
     ok,
     command: 'env',
-    summary: ok
-      ? msg('cli.env.checked', { count: total })
-      : msg('cli.env.invalid', { count: findings.length, total }),
+    // `x doctor` asks about this machine and stays quiet on the same shell, so an exit 1 here over
+    // a table that named nothing reads as a contradiction until this line says which question ran.
+    summary: namesNoEnvironment(ctx.env)
+      ? `${verdict} — ${msg('cli.env.checkedAsProduction')}`
+      : verdict,
     findings,
     data: {
       variables: total,
@@ -118,8 +123,8 @@ export const envCommand: CliCommand = {
     // `subcommand`, never `positionals[0]`: the parser has already lifted a declared subcommand
     // out of the positionals, so reading the array here matches nothing and every invocation
     // silently ran the default.
-    return (ctx.args.subcommand ?? 'check') === 'example'
-      ? writeExample(ctx)
-      : checkProcessEnv(ctx);
+    const subcommand = ctx.args.subcommand ?? 'check';
+    if (subcommand === 'init') return (await import('./cmd-env-init')).initProductionEnv(ctx);
+    return subcommand === 'example' ? writeExample(ctx) : checkProcessEnv(ctx);
   },
 };

package/src/cmd-errors-recent.ts

@@ -0,0 +1,60 @@
+// `x errors explain <CODE> --recent` — the code's explanation, then what this app has seen of it:
+// its groups in `x_error_groups` (count, first and last seen) and the replayable bundles
+// `x_failures` holds, each with the `x repro` line that turns it into a failing test.
+
+import { postgresErrorGroupsStore } from '@ultimat3/admin/error-groups';
+import { postgresFailureStore } from '@ultimat3/db';
+import { requireAppRoot } from './app-root';
+import type { CommandContext } from './command';
+import { withJobDriver } from './jobs-driver';
+import type { CommandResult, JsonValue } from './output';
+
+/** The newest groups read to find this code's: the store's own ceiling (`ERROR_GROUPS_MAX_LIMIT`). */
+const GROUPS_READ = 500;
+
+/** `explained` with the app's own sightings of `code` folded into its lines and its data. */
+export function withRecent(
+  ctx: CommandContext,
+  code: string,
+  explained: CommandResult,
+): Promise<CommandResult> {
+  const root = requireAppRoot('errors explain --recent', ctx.cwd).dir;
+  return withJobDriver(root, ctx, async () => {
+    const groups = (await postgresErrorGroupsStore().list({ limit: GROUPS_READ })).filter(
+      (group) => group.code === code,
+    );
+    const bundles = await postgresFailureStore().list({ code });
+    const recent: JsonValue = {
+      groups: groups.map((group) => ({
+        fingerprint: group.fingerprint,
+        operation: group.operation,
+        count: group.count,
+        firstSeen: group.firstSeen,
+        lastSeen: group.lastSeen,
+        status: group.status,
+      })),
+      bundles: bundles.map((bundle) => ({
+        ...bundle,
+        repro: `x repro ${bundle.id} --write --verify`,
+      })),
+    };
+    const lines = [
+      ...(explained.lines ?? []),
+      `  recent: ${groups.length} group(s), ${bundles.length} captured bundle(s)`,
+      ...groups.map(
+        (group) =>
+          `    ${group.fingerprint}  ${String(group.count).padStart(6)}×  last ${group.lastSeen}  ${group.operation ?? ''}`,
+      ),
+      ...bundles.map(
+        (bundle) => `    x repro ${bundle.id} --write --verify   # ${bundle.name} at ${bundle.at}`,
+      ),
+    ];
+    const data =
+      typeof explained.data === 'object' &&
+      explained.data !== null &&
+      !Array.isArray(explained.data)
+        ? explained.data
+        : {};
+    return { ...explained, lines, data: { ...data, recent } };
+  });
+}

package/src/cmd-errors-spec.ts

@@ -8,7 +8,7 @@ export const ERRORS_SUBCOMMANDS = ['explain', 'list'] as const;
 export const errorsSpec: CommandSpec = {
   name: 'errors',
   summary: 'an X_* code, explained: cause, runnable fix, docs URL',
-  usage: 'x errors [explain <CODE>|list] [--json]',
+  usage: 'x errors [explain <CODE> [--recent]|list] [--json]',
   subcommands: ERRORS_SUBCOMMANDS,
   // `explain`, deliberately: the bare `x errors` then answers with `MissingPositionalError`,
   // which names `<CODE>` and hands back a real invocation. `list` would silently print 200 rows
@@ -20,4 +20,12 @@ export const errorsSpec: CommandSpec = {
   // Safe to declare here and nowhere else so far: the only thing that is not `explain` or
   // `list` in this slot is a code, and a near miss of either is still refused (#F16).
   defaultSubcommandTakesPositional: true,
+  flags: [
+    {
+      name: 'recent',
+      type: 'boolean',
+      summary: "explain: this app's groups of the code and the captured bundles x repro replays",
+      subcommands: ['explain'],
+    },
+  ],
 };

package/src/cmd-errors.ts

@@ -5,6 +5,7 @@ import { nearestName, singleLine } from '@ultimat3/core';
 // a plausible-sounding explanation an agent would then act on.
 
 import type { ErrorExplanation } from '@ultimat3/mcp';
+import { withRecent } from './cmd-errors-recent';
 import { errorsSpec } from './cmd-errors-spec';
 import type { CliCommand, CommandContext } from './command';
 import type { ErrorCatalog } from './error-catalog';
@@ -14,6 +15,7 @@ import { ErrorCodeUnknownError, MissingPositionalError } from './errors';
 import { explainErrorCode, explainEveryErrorCode } from './mcp-errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
+import { flagBool } from './parse';
 
 export { ERRORS_SUBCOMMANDS } from './cmd-errors-spec';
 
@@ -106,6 +108,8 @@ export const errorsCommand: CliCommand = {
         example: 'x errors list --json',
       });
     }
+    // `--recent`: what THIS app has seen of the code — groups and the bundles `x repro` replays.
+    if (flagBool(ctx.args, 'recent')) return withRecent(ctx, code, explainOne(code));
     return explainOne(code);
   },
 };

package/src/cmd-exercise-spec.ts

@@ -0,0 +1,19 @@
+// `x exercise`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-exercise.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const exerciseSpec: CommandSpec = {
+  name: 'exercise',
+  summary: 'run every action, query and job once on generated rows, with no test written',
+  usage: 'x exercise [<name>] [--seed n] [--json]',
+  requiresApp: true,
+  flags: [
+    {
+      name: 'seed',
+      type: 'string',
+      summary:
+        'the integer the seed graph and every generated input are drawn from; same seed, same pass',
+    },
+  ],
+};