@ultimat3/cli 1.2.0 → 2.0.0

package/src/cmd-dev.ts

@@ -6,12 +6,16 @@
 
 import { watch } from 'node:fs';
 import { join } from 'node:path';
-import { listActions, toRoute } from '@ultimat3/action';
+import { devShellStyle } from '@ultimat3/admin/dev';
 import type { Role } from '@ultimat3/core';
 import { configureTelemetry, METRICS_PATH, noopExporter } from '@ultimat3/core';
-import type { Route } from '@ultimat3/http';
+import { setStatementObserver } from '@ultimat3/db';
+import type { OverlayNotice, RequestContext, Route } from '@ultimat3/http';
+import { asCtx } from '@ultimat3/http';
 import type { Manifest } from '@ultimat3/manifest';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
+import { apiRoutes } from './api-routes';
+import { loadSignInPath } from './app-auth';
 import { loadApp } from './app-load';
 import { appManifest } from './app-manifest';
 import { requireAppRoot } from './app-root';
@@ -19,19 +23,26 @@ import type { CliCommand, CommandContext } from './command';
 import { assetRoutes } from './dev-assets';
 import type { DevDashboardInput, DevStatus } from './dev-dashboard';
 import { devDashboardRoutes, devPanels } from './dev-dashboard';
+import { createStatementLedger } from './dev-n-plus-one';
 import { appRoutes } from './dev-render';
 import type { RunningRoles } from './dev-roles';
 import { DEV_ROLES, selectRoles, startRoles } from './dev-roles';
 import type { RunningServices } from './dev-runtime';
 import { cdnLabel, describeCdn, describeMail, mailLabel, startServices } from './dev-runtime';
 import type { DevServices } from './dev-services';
-import { describeServices, resolveServices } from './dev-services';
+import { describeServices, reportedUrls, resolveServices } from './dev-services';
+import { storageRoutes } from './dev-storage';
 import { createTraceRecorder } from './dev-traces';
+import { intFlagOr, PORT_RANGE } from './flag-number';
 import { holdUntilShutdown } from './hold';
+import type { IslandBundle } from './island-bundle';
+import { buildIslands } from './island-bundle';
+import { islandRoutes } from './island-routes';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { findingFrom } from './output';
 import { flagString } from './parse';
+import { loopFacts, loopFinding, loopNotice } from './statement-loop';
 
 const DEFAULT_PORT = 3000;
 
@@ -41,7 +52,11 @@ export interface DevServer {
   readonly roles: readonly Role[];
   /** The manifest as it stands now — a reload that registers a new route moves it. */
   readonly buildId: string;
-  /** Modules that would not import, primitives that would not register, reloads that would not build. */
+  /**
+   * Modules that would not import, primitives that would not register, reloads that would not
+   * build — and the statement loops this process has counted so far, which is what puts an N+1 in
+   * `x dev`'s own output and in `--json` without a channel of its own.
+   */
   readonly findings: readonly Finding[];
   readonly running: RunningRoles;
   readonly runtime: RunningServices;
@@ -55,6 +70,12 @@ interface DevState {
   reloads: number;
   /** A save that will not build. Replaced on every attempt, so a fixed file clears it. */
   reloadFinding: Finding | undefined;
+  /**
+   * The client entries, rebuilt on the same tick as the manifest. An island is the one module this
+   * process never imports, so a fresh `Bun.build` is the whole of its reload — no module cache to
+   * invalidate, which is exactly why editing one takes effect where editing a route does not.
+   */
+  islands: IslandBundle;
 }
 
 /** Debounced: a save that touches five files is one reload, not five. */
@@ -105,11 +126,19 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
   // what configures one, which is the whole reason `/_x/timeline` has anything to draw.
   const traces = createTraceRecorder();
   configureTelemetry({ exporter: traces.exporter });
+  // Installed at the same moment and for the same reason: an observer is the single switch that
+  // turns statement instrumentation on at all (`@ultimat3/db`'s `observe.ts`), so the timeline's
+  // SQL rows and the repeat counts arrive together rather than through two toggles. `serve.ts`
+  // installs neither — a production process pays the one `undefined` branch the seam costs
+  // uninstalled, and nothing more (axiom 6).
+  const statements = createStatementLedger();
+  setStatementObserver(statements.observer);
   const app = await loadApp(options.root);
   const state: DevState = {
     manifest: (await appManifest(options.root)).manifest,
     reloads: 0,
     reloadFinding: undefined,
+    islands: await buildIslands(options.root),
   };
   // The manifest's build id is a content hash of every fact below it, so a dev document's
   // `x-ultimate-build` header names the exact shape the client was served against. Pinned at
@@ -132,18 +161,25 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
       reloads: state.reloads,
     }),
     traces,
+    statements,
     ...envOf(options.env),
   };
   const panels = devPanels(dashboard).map((panel) => panel.key);
 
   const routes: readonly Route[] = [
     ...devDashboardRoutes(dashboard),
-    ...listActions().map(toRoute),
+    // The same API table the container serves: a read that answers here and 404s in production
+    // is exactly the drift one composition exists to prevent.
+    ...apiRoutes(),
     // The image pipeline's only HTTP surface: the icons the web manifest declares, and the
     // variants every `srcset` promises. Mounted before the app's own routes so a page route can
     // never shadow `/icons` or `/media`.
     ...assetRoutes({ root: options.root, storage: runtime.storage }),
-    ...appRoutes({ buildId }),
+    ...storageRoutes({ storage: runtime.storage }),
+    // The chunks the documents below name. Mounted before the app's routes for the reason
+    // `/icons` and `/media` are: a page route must not be able to shadow an asset URL.
+    ...islandRoutes(() => state.islands),
+    ...appRoutes({ buildId, resolveIsland: (file) => state.islands.resolverFor(file) }),
   ];
 
   const running = await startRoles({
@@ -153,13 +189,28 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     runtime,
     routes,
     env: options.env,
+    // Read from `app.config.ts` rather than threaded through `DevOptions`: it is the app's own
+    // declaration, and `x dev` and `serve.ts` must not be able to disagree about where the app's
+    // sign-in page is.
+    signInPath: await loadSignInPath(options.root),
+    // The one document this process serves that the app did not write; `startRoles` covers the
+    // app's own surfaces itself. `x dev` sends the policy report-only, so an uncovered `<style>`
+    // here is a console report rather than a blank page — which is how this reached production.
+    inlineStyles: [await devShellStyle()],
+    // The fourth surface, and the only one an author sees without leaving the page they broke:
+    // the overlay renders this request's own loops under the error it is already showing.
+    // `serve.ts` boots through the same `startRoles` and passes nothing, so production has no
+    // diagnostic to call.
+    devNotices: (ctx: RequestContext): readonly OverlayNotice[] =>
+      statements.repeatsFor(asCtx(ctx)).map(loopFacts).map(loopNotice),
   });
 
   const stopWatching = watchApp(options.root, (file) => {
     const started = performance.now();
-    void appManifest(options.root)
-      .then(({ manifest }) => {
+    void Promise.all([appManifest(options.root), buildIslands(options.root)])
+      .then(([{ manifest }, islands]) => {
         state.manifest = manifest;
+        state.islands = islands;
         state.reloads += 1;
         state.reloadFinding = undefined;
         options.onReload?.(file, Math.round(performance.now() - started));
@@ -178,12 +229,15 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     get buildId(): string {
       return state.manifest.buildId;
     },
-    // A getter, not a snapshot: `/_x` and `--json` must show the reload that just failed, not the
-    // findings as they were when the route table was built.
+    // A getter, not a snapshot: `/_x` and `--json` must show the reload that just failed and the
+    // loop the last request tripped, not the findings as they were when the route table was built.
+    // The loops come last and carry their request id, so a boot report reads as a boot report and
+    // a diagnostic that arrived a minute later reads as one too.
     get findings(): readonly Finding[] {
+      const loops = statements.repeats().map(loopFacts).map(loopFinding);
       return state.reloadFinding === undefined
-        ? app.findings
-        : [...app.findings, state.reloadFinding];
+        ? [...app.findings, ...loops]
+        : [...app.findings, state.reloadFinding, ...loops];
     },
     running,
     runtime,
@@ -197,6 +251,12 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
       // leaving it in place would keep every span of the next `startDev` in this process's buffer.
       configureTelemetry({ exporter: noopExporter });
       traces.reset();
+      // Released with the exporter, after the roles, for the same reason: a statement still in
+      // flight is observed by the ledger that counted the rest of its request. Leaving it
+      // installed would keep every statement of the next `startDev` in this process's counts —
+      // and, worse, keep instrumentation on in a process that is no longer a dev server.
+      setStatementObserver(undefined);
+      statements.reset();
     },
   };
   return server;
@@ -220,7 +280,13 @@ export const devCommand: CliCommand = {
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('dev', ctx.cwd).dir;
-    const port = Number.parseInt(flagString(ctx.args, 'port') ?? String(DEFAULT_PORT), 10);
+    // Validated, not `parseInt`'d: `x dev --port abc` handed `NaN` to `Bun.serve`, which binds an
+    // arbitrary port — a dev server reachable at an address nothing printed.
+    const port = intFlagOr(
+      ctx.args,
+      { name: 'port', command: 'dev', ...PORT_RANGE, example: `x dev --port ${DEFAULT_PORT}` },
+      DEFAULT_PORT,
+    );
     const roles = selectRoles(flagString(ctx.args, 'role'));
     const server = await startDev({
       root,
@@ -253,9 +319,10 @@ export const devCommand: CliCommand = {
         // at, and the one url here that must NOT be behind the ingress the app's own url is.
         metrics: `${server.running.metricsUrl}${METRICS_PATH}`,
         stateDir: server.services.stateDir,
-        db: server.services.db.url,
-        events: server.services.events.url,
-        storage: server.services.storage.url,
+        // Redacted, for the reason the mail and cdn lines below already give and this line did
+        // not: `DATABASE_URL`, `NATS_URL` and `S3_ENDPOINT` all carry a password, and this object
+        // is printed, logged and scraped. `reportedUrls` is the one projection that may be shown.
+        ...reportedUrls(server.services),
         // The selecting env key, never the credential behind it: `SMTP_URL` carries a password
         // and this line is printed, logged and scraped.
         mail: describeMail(server.runtime),

package/src/cmd-docs.ts

@@ -0,0 +1,167 @@
+// `x docs <question>` — the framework's documentation, answered offline from what is installed.
+//
+// One step, no filename known in advance, no network. An agent that has a question and no path
+// should not have to guess which of 29 packages holds the answer, and it must never be handed a
+// URL: `node_modules` already contains every doc, because the published artifact IS the source.
+
+import type { DocEntry, DocHit } from '@ultimat3/manifest';
+import { nearestTopics, scanInstalledDocs, searchDocs } from '@ultimat3/manifest';
+import type { CliCommand, CommandContext } from './command';
+import { MissingPositionalError } from './errors';
+import { frameworkScopeDir } from './framework-scope';
+import { msg } from './messages';
+import type { CommandResult, Finding, JsonValue } from './output';
+
+/** Matches printed by default. Enough to choose between, few enough to read all of. */
+const DEFAULT_LIMIT = 5;
+
+/** An install where the CLI cannot see its own dependency is broken, not merely undocumented. */
+const unresolvedFinding = (): Finding => ({
+  code: 'X_CLI_UNEXPECTED',
+  cause: '@ultimat3/core does not resolve from the installed CLI, so no docs could be read',
+  fix: 'bun install && x doctor --json',
+  docs: 'https://ultimate.dev/errors/X_CLI_UNEXPECTED',
+  at: import.meta.dir,
+});
+
+const asJson = (hit: DocHit): JsonValue => ({
+  topic: hit.entry.topic,
+  package: hit.entry.package,
+  version: hit.entry.version,
+  kind: hit.entry.kind,
+  title: hit.entry.title,
+  text: hit.entry.text,
+  symbols: [...hit.entry.symbols],
+  source: hit.entry.source,
+  matched: [...hit.matched],
+  score: hit.score,
+});
+
+/** The exact path an agent opens next — package-relative is ambiguous across 29 packages. */
+const locate = (entry: DocEntry): string => `${entry.package}/${entry.source}`;
+
+function humanLines(hits: readonly DocHit[]): readonly string[] {
+  const lines: string[] = [];
+  for (const hit of hits) {
+    lines.push(`  ${hit.entry.topic}  ${locate(hit.entry)}`);
+    // The title is the package's own header comment, quoted verbatim — source text, not this
+    // command's prose, so it never goes through the catalog.
+    if (hit.entry.title !== '') lines.push(`    ${hit.entry.title}`);
+    if (hit.entry.symbols.length > 0) {
+      lines.push(
+        `    ${msg('cli.docs.exports', { list: hit.entry.symbols.slice(0, 12).join(', ') })}`,
+      );
+    }
+  }
+  return lines;
+}
+
+/**
+ * The two commands that answer what `x docs` does not. The invocation stays inline and only its
+ * explanation is translated: a `fix:`-style command is copied and run verbatim, and a translated
+ * `x errors list --json` is a broken command (the same reason `Finding.fix` is exempt).
+ */
+const alsoTry = (): readonly string[] => [
+  `  x errors list --json          # ${msg('cli.docs.tryErrors')}`,
+  `  x actions list --json         # ${msg('cli.docs.tryActions')}`,
+];
+
+/**
+ * An `X_*` code is not a documentation question — `x errors explain` already answers it offline,
+ * with a runnable fix, and refuses a code nobody registered. Pointing at it costs the agent one
+ * step and beats ranking a code against prose that merely mentions it (axiom 1: one way).
+ */
+const CODE_QUERY = /\bX_[A-Z0-9_]{3,}\b/;
+
+/**
+ * Answered before anything is scanned, because the contract above is only true if nothing else
+ * runs. Ranking a code against prose returned five files for `X_DB_DRIFT` that merely contain
+ * "db" and "drift", with the redirect buried under them — and a code that matched nothing at all
+ * fell into `missResult`, which never carried the redirect. Returning here closes both, and skips
+ * a scan of every installed package for a question that was never about documentation.
+ */
+function codeResult(code: string, query: string): CommandResult {
+  return {
+    ok: true,
+    command: 'docs',
+    summary: msg('cli.docs.code', { code }),
+    lines: [`  x errors explain ${code} --json`],
+    data: { matches: [], suggestions: [], redirect: code, query },
+  };
+}
+
+/**
+ * A miss is still an instruction (axiom 4). Topics that half-matched come first; when nothing
+ * related at all, the honest fallback is the list of packages actually installed — the universe
+ * the question could have been about — rather than five topics picked for sharing letters.
+ */
+function missResult(query: string, entries: readonly DocEntry[]): CommandResult {
+  const suggestions = nearestTopics(entries, query);
+  const packages = [...new Set(entries.map((entry) => entry.package))].sort();
+  const next =
+    suggestions.length > 0
+      ? suggestions.map((topic) => `  x docs ${topic} --json`)
+      : [`  ${msg('cli.docs.installed', { list: packages.join(' ') })}`];
+  return {
+    ok: false,
+    command: 'docs',
+    summary: msg('cli.docs.none', { query }),
+    lines: [...next, ...alsoTry()],
+    data: { matches: [], suggestions: [...suggestions], packages, query },
+  };
+}
+
+export const docsCommand: CliCommand = {
+  spec: {
+    name: 'docs',
+    summary: 'the framework docs, answered offline from the installed packages',
+    usage: 'x docs "<question|topic|symbol>" [--limit <n>] [--json]',
+    flags: [
+      { name: 'limit', type: 'string', summary: `matches to return (default: ${DEFAULT_LIMIT})` },
+    ],
+  },
+  // `async` is load-bearing: a synchronous throw would escape every caller that awaits the
+  // promise this signature promises, including the dispatcher's own error path.
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    // Joined, not `[0]`: an unquoted question arrives as many positionals, and answering only the
+    // first word is the failure an agent cannot see — it gets a plausible answer to "how".
+    const query = ctx.args.positionals.join(' ').trim();
+    if (query === '') {
+      throw new MissingPositionalError({
+        command: 'docs',
+        positional: 'question',
+        example: 'x docs "how does job() retry" --json',
+      });
+    }
+
+    const code = CODE_QUERY.exec(query)?.[0];
+    if (code !== undefined) return codeResult(code, query);
+
+    const scope = frameworkScopeDir();
+    if (scope === undefined) {
+      const finding = unresolvedFinding();
+      return {
+        ok: false,
+        command: 'docs',
+        summary: msg('cli.docs.unresolved'),
+        findings: [finding],
+        data: { matches: [], suggestions: [], query },
+      };
+    }
+
+    const entries = await scanInstalledDocs(scope);
+    const rawLimit = ctx.args.flags.get('limit');
+    const parsed = typeof rawLimit === 'string' ? Number.parseInt(rawLimit, 10) : Number.NaN;
+    const limit = Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_LIMIT;
+    const hits = searchDocs(entries, query, limit);
+    if (hits.length === 0) return missResult(query, entries);
+
+    return {
+      ok: true,
+      command: 'docs',
+      summary: msg('cli.docs.found', { count: hits.length, query }),
+      lines: [...humanLines(hits)],
+      data: { matches: hits.map(asJson), suggestions: [], query },
+    };
+  },
+};

package/src/cmd-doctor.ts

@@ -4,14 +4,16 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { usesDevCursorSecret } from '@ultimat3/core';
+import { tryResolveEnvironment, usesDevCursorSecret } from '@ultimat3/core';
+import { STORAGE_SIGNING_SECRET_KEY, usesDevStorageSecret } from '@ultimat3/storage';
 import { findAppRoot, REQUIRED_BUN, versionAtLeast } from './app-root';
 import type { CliCommand, CommandContext } from './command';
+import { checkMigrationSnapshots } from './db-snapshot';
 import { ICON_SOURCE } from './dev-assets';
-import { checkDrift } from './drift';
+import { checkSourceDrift } from './drift';
+import { intFlagOr, PORT_RANGE } from './flag-number';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
-import { flagString } from './parse';
 
 /**
  * The injection seam `runDoctor` reads instead of the environment. Not a semver surface —
@@ -26,11 +28,24 @@ export interface DoctorProbe {
   readonly port: number;
   /** True while cursors are signed with the key shipped in the published package. */
   readonly devCursorSecret: boolean;
+  /**
+   * True while the local disk WOULD sign upload grants with the key shipped in the published
+   * package. Same semantics as `devCursorSecret`, environment only — an app that passes an
+   * explicit `signingSecret` in `app.config.ts` never consults the env var, so this can read true
+   * for an app that is fine. The finding is worded as a condition to check, not a certainty.
+   */
+  readonly devStorageSecret: boolean;
   /** True when this process believes it is serving real clients. */
   readonly production: boolean;
   exists(relativePath: string): boolean;
   portFree(port: number): Promise<boolean>;
   drift(): Promise<readonly Finding[]>;
+  /**
+   * The other half of the migrations directory: a newest migration with no `.snapshot.json`, which
+   * is what `x db gen` refuses on. Separate from `drift()` because they are separate questions with
+   * separate remedies — one is "generate a migration", the other is "this migration is incomplete".
+   */
+  snapshots(): Promise<readonly Finding[]>;
 }
 
 const docs = (code: string): string => `https://ultimate.dev/errors/${code}`;
@@ -42,6 +57,9 @@ const finding = (code: string, cause: string, fix: string, at?: string): Finding
 
 export const OFFLINE_FALLBACK = 'apps/web/app/offline.tsx';
 
+/** The port `x dev` binds by default, so the probe answers about the port the developer will use. */
+const DEFAULT_DOCTOR_PORT = 3000;
+
 /**
  * Ordered cheapest-first so the first failure is usually the root cause: a wrong Bun explains
  * every other symptom, and running outside an app explains the rest.
@@ -88,6 +106,21 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
       ),
     );
   }
+  // The storage twin of the cursor key above, and the more expensive one to get wrong: the
+  // published string mints a signed `PUT` for any key with any `maxBytes` and `contentType`, and
+  // `acceptSignedUpload` trusts the signed constraints over the app's own `uploadPolicy`.
+  // Production only, for the reason the cursor check gives — every dev environment signs with the
+  // shipped key on purpose. `@ultimat3/storage` refuses this at construction; `x doctor` is what
+  // reports it before a deploy reaches the refusal.
+  if (probe.production && probe.devStorageSecret) {
+    findings.push(
+      finding(
+        'X_STORAGE_SECRET_DEV',
+        `${STORAGE_SIGNING_SECRET_KEY} is unset or holds the shipped development key, so a local-disk deploy would accept forged upload grants that override its own uploadPolicy`,
+        'export STORAGE_SIGNING_SECRET="$(openssl rand -hex 32)"',
+      ),
+    );
+  }
   if (!(await probe.portFree(probe.port))) {
     findings.push(
       finding(
@@ -125,6 +158,10 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
     );
   }
   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
+  // condition this diagnostic could not see at all, so the fix line ran clean over a broken app.
+  findings.push(...(await probe.snapshots()));
   return findings;
 }
 
@@ -145,12 +182,19 @@ export function probeFor(cwd: string, bunVersion: string, port: number): DoctorP
     root,
     port,
     devCursorSecret: usesDevCursorSecret(),
-    // `X_ENV` first, then `NODE_ENV`: the order `@ultimat3/admin`'s dev-server guard already
-    // reads them in, and a second order would be a second convention.
-    production: (Bun.env['X_ENV'] ?? Bun.env['NODE_ENV']) === 'production',
+    devStorageSecret: usesDevStorageSecret(),
+    // `ULTIMATE_ENV`, through core — the one key that says which deploy this is, with `NODE_ENV`
+    // as its documented fallback. This read `X_ENV ?? NODE_ENV`, a spelling nothing else in the
+    // repo reads, so a deploy declaring production the framework's own way was told it was not
+    // production and skipped both secret findings; and the `??` short-circuited, so any non-empty
+    // `X_ENV` shadowed a real `NODE_ENV=production` too. The non-throwing variant because
+    // `ULTIMATE_ENV` is not in the env schema — nothing validates it at boot, and a diagnostic
+    // that crashes on a typo is the one thing worse than a diagnostic that misses.
+    production: tryResolveEnvironment() === 'production',
     exists: (relativePath) => (root === undefined ? false : existsSync(join(root, relativePath))),
     portFree,
-    drift: async () => (root === undefined ? [] : checkDrift(root)),
+    drift: async () => (root === undefined ? [] : checkSourceDrift(root)),
+    snapshots: async () => (root === undefined ? [] : checkMigrationSnapshots(root)),
   };
 }
 
@@ -159,10 +203,21 @@ export const doctorCommand: CliCommand = {
     name: 'doctor',
     summary: 'environment, versions, drift, ports, PWA prerequisites — each with a fix command',
     usage: 'x doctor [--port 3000] [--json]',
-    flags: [{ name: 'port', type: 'string', summary: 'port to test', default: '3000' }],
+    flags: [
+      {
+        name: 'port',
+        type: 'string',
+        summary: 'port to test',
+        default: String(DEFAULT_DOCTOR_PORT),
+      },
+    ],
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
-    const port = Number.parseInt(flagString(ctx.args, 'port') ?? '3000', 10);
+    const port = intFlagOr(
+      ctx.args,
+      { name: 'port', command: 'doctor', ...PORT_RANGE, example: 'x doctor --port 3000' },
+      DEFAULT_DOCTOR_PORT,
+    );
     const findings = await runDoctor(probeFor(ctx.cwd, ctx.bunVersion, port));
     return {
       ok: findings.length === 0,

package/src/cmd-env.ts

@@ -0,0 +1,95 @@
+// `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.
+
+// Bun ships no path-join primitive, and `.env.example` is written app-root-relative.
+import { join } from 'node:path';
+import { checkEnv, ENV_EXAMPLE_PATH, maskedEnvValues } from '@ultimat3/core';
+import { ENV_SCHEMA_EXPORT, envExampleFor, loadEnvSchema } from './app-env';
+import { APP_CONFIG_FILE, requireAppRoot } from './app-root';
+import type { CliCommand, CommandContext } from './command';
+import { EnvSchemaMissingError } from './errors';
+import { msg } from './messages';
+import type { CommandResult, Finding, JsonValue } from './output';
+
+/**
+ * Every subcommand needs the declaration, and an app without one is a usage error rather than an
+ * empty success: `x env example` writing a two-comment file would look like it worked.
+ */
+async function requireSchema(cwd: string, subcommand: string) {
+  const root = requireAppRoot(`env ${subcommand}`, cwd).dir;
+  const schema = await loadEnvSchema(root);
+  if (schema === undefined) throw new EnvSchemaMissingError({ subcommand });
+  return { root, schema };
+}
+
+async function writeExample(ctx: CommandContext): Promise<CommandResult> {
+  const { root, schema } = await requireSchema(ctx.cwd, 'example');
+  const contents = envExampleFor(schema);
+  const path = join(root, ENV_EXAMPLE_PATH);
+  const file = Bun.file(path);
+  const fresh = (await file.exists()) && (await file.text()) === contents;
+  if (!fresh) await Bun.write(path, contents);
+  const count = Object.keys(schema).length;
+  return {
+    ok: true,
+    command: 'env',
+    summary: fresh
+      ? msg('cli.env.fresh', { path: ENV_EXAMPLE_PATH })
+      : msg('cli.env.wrote', { path: ENV_EXAMPLE_PATH, count }),
+    data: { path: ENV_EXAMPLE_PATH, variables: count, written: !fresh },
+  };
+}
+
+/**
+ * The values are read from the real process environment, and only ever printed through
+ * `maskedEnvValues` — `checkEnv().values` holds the actual secrets because `defineEnv()` has to
+ * return them, and a `--json` report is the last place a DSN should appear in full.
+ */
+async function checkProcessEnv(ctx: CommandContext): Promise<CommandResult> {
+  const { schema } = await requireSchema(ctx.cwd, 'check');
+  const report = checkEnv(schema);
+  const total = Object.keys(schema).length;
+  const findings: readonly Finding[] = report.issues.map((issue) => ({
+    code: 'X_ENV_MISSING',
+    cause: `${issue.key} is ${issue.reason} (expected ${issue.expected})`,
+    fix: issue.fix,
+    docs: 'https://ultimate.dev/errors/X_ENV_MISSING',
+    at: ENV_EXAMPLE_PATH,
+  }));
+  return {
+    ok: report.ok,
+    command: 'env',
+    summary: report.ok
+      ? msg('cli.env.checked', { count: total })
+      : msg('cli.env.invalid', { count: report.issues.length, total }),
+    findings,
+    data: {
+      variables: total,
+      values: maskedEnvValues(schema, report.values) as JsonValue,
+    },
+    exitCode: report.ok ? 0 : 1,
+  };
+}
+
+export const envCommand: CliCommand = {
+  spec: {
+    name: 'env',
+    summary: `the typed environment declared by ${ENV_SCHEMA_EXPORT} in ${APP_CONFIG_FILE}`,
+    usage: 'x env [check|example] [--json]',
+    requiresApp: true,
+    subcommands: ['check', 'example'],
+    // 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: [],
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    // `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);
+  },
+};