@ultimat3/cli 24.0.0 → 25.1.0

package/src/cmd-dev.ts

@@ -1,372 +1,32 @@
-// `x dev` — the app, booted. Every role in one Bun process, embedded Postgres/events/storage
-// started for real, the app's own modules loaded into the framework's registries, and the route
-// table those registries hold served over HTTP. `@ultimat3/admin`'s `/_x` dashboard is mounted
-// alongside it — mounted, never re-implemented — so an agent can introspect the running app.
+// `x dev` — the app, booted (`dev-boot.ts`), reported and held. Every role in one Bun process,
+// embedded Postgres/events/storage started for real, and `@ultimat3/admin`'s `/_x` dashboard
+// mounted alongside the app — mounted, never re-implemented — so an agent can introspect it.
 // No Docker, no env setup: an unset variable means the embedded default.
 
 import { join } from 'node:path';
-import { devShellStyle } from '@ultimat3/admin/dev';
-import type { Role } from '@ultimat3/core';
-import { configureTelemetry, METRICS_PATH, noopExporter } from '@ultimat3/core';
-import { setStatementObserver } from '@ultimat3/db';
-import type { OverlayNotice, RequestContext } from '@ultimat3/http';
-import { asCtx } from '@ultimat3/http';
-import type { Manifest } from '@ultimat3/manifest';
+import { METRICS_PATH } from '@ultimat3/core';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
-import { loadSignInPath } from './app-auth';
-import { appManifest } from './app-manifest';
-import type { StalePin } from './app-reload-graph';
-import { enableReloadTracking, takeStalePins } from './app-reload-graph';
 import { requireAppRoot } from './app-root';
-import { loadAppRuntime } from './app-runtime';
 import { devSpec } from './cmd-dev-spec';
 import type { CliCommand, CommandContext } from './command';
-import type { DevDashboardInput, DevStatus } from './dev-dashboard';
-import { devPanels } from './dev-dashboard';
-import { declareDevEnvironment, needsDevEnvironmentDeclaration } from './dev-environment';
+import { startDev } from './dev-boot';
 import { clearLock, preflight, writeLock } from './dev-lock';
-import { createStatementLedger } from './dev-n-plus-one';
 import { devPortFor } from './dev-port';
-import { coalesceReloads } from './dev-reload';
-import { devRouteTable } from './dev-route-table';
-import { childRestart, restartFinding } from './dev-supervisor';
-import { createTraceRecorder } from './dev-traces';
-import { watchTree } from './dev-watch-tree';
+import { childRestart } from './dev-supervisor';
 import { holdUntilShutdown } from './hold';
-import type { IslandBundle } from './island-bundle';
-import { buildIslands } from './island-bundle';
-import { FRAME_STYLE } from './island-harness';
 import { msg } from './messages';
-import type { CommandResult, Finding } from './output';
-import { findingFrom } from './output';
+import type { CommandResult } from './output';
 import { flagString } from './parse';
-import type { RunningRoles } from './role-start';
-import { DEV_BINDING, DEV_ROLES, selectRoles, startRoles } from './role-start';
-import type { DevServices } from './runtime-bindings';
-import {
-  describeServices,
-  reportedUrls,
-  resolveServices,
-  withRealtimeEvents,
-} from './runtime-bindings';
-import { attachedIsr } from './runtime-isr';
+import { DEV_BINDING, selectRoles } from './role-start';
+import { describeServices, reportedUrls, resolveServices } from './runtime-bindings';
 import { liveFeedLabel } from './runtime-live-feed';
-import type { RuntimeOverrides } from './runtime-overrides';
-import { replicaOverrides } from './runtime-replica';
-import type { RunningServices } from './runtime-services';
-import { cdnLabel, describeCdn, describeMail, mailLabel, startServices } from './runtime-services';
-import { metricsPortFor, releaseBoot } from './serve';
-import { loopFacts, loopFinding, loopNotice } from './statement-loop';
+import { cdnLabel, describeCdn, describeMail, mailLabel } from './runtime-services';
+import { writeLine } from './write-line';
 
-const _DEFAULT_PORT = 3000;
-
-export interface DevServer {
-  readonly url: string;
-  readonly services: DevServices;
-  readonly roles: readonly Role[];
-  /**
-   * `BUILD_ID` when stamped — the id every response carries. Otherwise the manifest as it stands
-   * now, so 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 — 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;
-  /** Panel keys `/_x` mounted, in tab order. Reported so `--json` names what is reachable. */
-  readonly panels: readonly string[];
-  /** `POST <path>` of the app's default MCP endpoint, or `null` when nothing was mounted. */
-  readonly mcp: string | null;
-  /** `POST <path>` of every mounted MCP endpoint, default first — `[]` when none was. */
-  readonly mcpPaths: readonly string[];
-  stop(): Promise<void>;
-}
-
-interface DevState {
-  manifest: Manifest;
-  reloads: number;
-  /** A save that will not build. Replaced on every attempt, so a fixed file clears it. */
-  reloadFinding: Finding | undefined;
-  /**
-   * Modules that would not import and primitives that would not register, as of the LAST scan —
-   * the boot's, then each rebuild's. A page saved with a syntax error is a finding here until the
-   * save that fixes it, and the boot's list alone would never show it.
-   */
-  appFindings: readonly Finding[];
-  /**
-   * 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. The route module
-   * beside it is re-imported by that same scan (`app-load.ts`) — the two are one generation, or
-   * a save serves a new island under an old page, which is what it did until 2026-09-07.
-   */
-  islands: IslandBundle;
-}
-
-export interface StartDevOptions {
-  readonly root: string;
-  readonly port: number;
-  readonly env: Readonly<Record<string, string | undefined>>;
-  readonly roles?: readonly Role[];
-  readonly onReload?: (file: string, durationMs: number) => void;
-  /**
-   * A save reached a module that defines a primitive, so this process cannot serve it
-   * (`takeStalePins`). Given, it is called INSTEAD of `onReload` — `x dev`'s child drains and exits
-   * for its supervisor to boot a fresh one. Absent, the save is `X_DEV_RESTART_REQUIRED` on `/_x`.
-   */
-  readonly onRestart?: (pins: readonly StalePin[]) => void;
-}
-
-/**
- * The environment `devDashboard` refuses to mount in. Spread conditionally rather than passed as
- * `undefined`: `exactOptionalPropertyTypes` makes "absent" and "explicitly undefined" different
- * answers, and only the absent one lets the dashboard read the process environment itself.
- */
-const envOf = (env: StartDevOptions['env']): { env?: string } => {
-  const value = env['NODE_ENV'] ?? env['X_ENV'];
-  return value === undefined ? {} : { env: value };
-};
-
-/**
- * Boot order is the production order: services first, then the app's modules (importing them IS
- * the registration), then the roles that serve what those modules registered. A module that
- * fails to import becomes a finding rather than a dead process — the point of the dev loop is to
- * still be reachable while something is broken.
- */
-export async function startDev(options: StartDevOptions): Promise<DevServer> {
-  // EVERY boot: a scratch server (`x shot`, `ui.shot`) boots here too, and without this a
-  // fail-closed dev actor installs nothing — the picture is of a 401. Idempotent.
-  declareDevEnvironment(options.env);
-  // Before the first scan: the watcher's rescans evict a saved module AND everything importing it,
-  // and that needs the import graph recorded as each module is first loaded (`app-reload-graph.ts`).
-  enableReloadTracking(true);
-  // The declaration lands on `process.env`; the env this boot passes on must carry it too, or every
-  // service resolved from `options.env` still reads no `ULTIMATE_ENV`.
-  const env = needsDevEnvironmentDeclaration(options.env)
-    ? { ...options.env, ULTIMATE_ENV: 'development' }
-    : options.env;
-  const resolved = resolveServices(options.root, env);
-  // The app's `apps/<app>/runtime.ts`, read ONCE and handed to `startServices` exactly as
-  // `serve.ts`'s `withAppRuntime` does — so the disks (`storage`), the queue, the mail driver and
-  // every other override a deployment declares are the ones development runs too. Until 22.4 this
-  // boot passed nothing here and built its own embedded disk, so an app's `/_storage` routes and its
-  // actions wrote to two different places in `x dev` and to one in production.
-  const appRuntime = await loadAppRuntime(options.root);
-  const runtime: RunningServices = await startServices(resolved, env, appRuntime);
-  // The events binding the boot line reports is the bus the runtime chose, read off it.
-  const services = withRealtimeEvents(resolved, env, runtime.realtime);
-  // `serve.ts`'s `releaseBoot` shape: everything acquired from here on is released, newest first,
-  // if the boot throws — a failed `x dev` left PGlite holding `.x/pgdata` for the retry to meet.
-  const acquired: (() => void | Promise<void>)[] = [() => runtime.stop()];
-  try {
-    return await bootDev(options, services, runtime, acquired, appRuntime);
-  } catch (error) {
-    await releaseBoot(acquired);
-    throw error;
-  }
-}
-
-async function bootDev(
-  options: StartDevOptions,
-  services: ReturnType<typeof resolveServices>,
-  runtime: RunningServices,
-  acquired: (() => void | Promise<void>)[],
-  appRuntime: RuntimeOverrides | undefined,
-): Promise<DevServer> {
-  // Installed before the app loads, so a span opened during registration is already recorded.
-  // Tracing is always on in the framework and free until an exporter is configured; `x dev` is
-  // what configures one, which is the whole reason `/_x/timeline` has anything to draw.
-  const traces = createTraceRecorder();
-  configureTelemetry({ exporter: traces.exporter });
-  acquired.push(() => {
-    configureTelemetry({ exporter: noopExporter });
-    traces.reset();
-  });
-  // 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);
-  acquired.push(() => {
-    setStatementObserver(undefined);
-    statements.reset();
-  });
-  // ONE load at boot, the same call the rebuild below makes: the manifest and the findings are
-  // two projections of one scan. Until 2026-09-07 this was `loadApp` for the findings and then
-  // `appManifest` — which loads again — for the manifest, so a save landing between the two put
-  // `/_x`'s findings and its manifest on different registration states.
-  const app = await appManifest(options.root);
-  const state: DevState = {
-    manifest: app.manifest,
-    reloads: 0,
-    reloadFinding: undefined,
-    appFindings: app.findings,
-    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
-  // boot on purpose: the header is handed to the HTTP config and the render modes once, and a
-  // reload cannot re-pin it — `state.manifest.buildId` is what `/_x` and `--json` report, so a
-  // divergence between the two is visible rather than silent, and a restart closes it.
-  // `BUILD_ID` wins when set — `serve.ts`'s rule, so an e2e `deploy.newBuild()` can restart `x dev`
-  // as a new build with the same sources.
-  // Stamped, it is ALSO what `server.buildId` answers below: the process serves no other build.
-  const rawStamp = options.env['BUILD_ID'];
-  const stamped = rawStamp !== undefined && rawStamp !== '' ? rawStamp : undefined;
-  const buildId = stamped ?? state.manifest.buildId;
-
-  let server: DevServer;
-  // Read at request time, never captured at boot: `/_x/services` must report the reload counter
-  // and the findings as they are now, not as they were when the route table was built.
-  const dashboard: DevDashboardInput = {
-    root: options.root,
-    runtime,
-    status: (): DevStatus => ({
-      url: server.url,
-      services: server.services,
-      roles: server.roles,
-      findings: server.findings,
-      reloads: state.reloads,
-    }),
-    traces,
-    statements,
-    ...envOf(options.env),
-  };
-  const panels = devPanels(dashboard).map((panel) => panel.key);
-
-  // `x dev`'s own, so a reload can empty it (a save otherwise kept a page's first render for its
-  // ttl); attached, so a tag bust reaches it too. Released with the roles.
-  const { isr, release: releaseIsr } = attachedIsr({ buildId });
-  acquired.push(releaseIsr);
-  const { routes, theme, speculation, errorStyles, mcpPath, mcpPaths } = await devRouteTable({
-    isr,
-    root: options.root,
-    env: options.env,
-    buildId,
-    storage: runtime.storage,
-    dashboard,
-    islands: () => state.islands,
-    realtime: runtime.realtime,
-    rateLimitStore: appRuntime?.rateLimitStore ?? runtime.rateLimitStore,
-    appRoutes: appRuntime?.routes,
-  });
-
-  // The app's `apps/<app>/runtime.ts`, composed exactly as `runRole` composes a caller's
-  // `runtime`: the replica scope in front, the app's own middleware behind it. Before this the
-  // first argument was `undefined` here and an app's middleware reached no development process.
-  const replicaOverride = replicaOverrides(appRuntime, services.db, options.env);
-  const running = await startRoles({
-    roles: options.roles ?? DEV_ROLES,
-    port: options.port,
-    // `serve.ts`'s expression, called rather than restated: `METRICS_PORT` was read in the
-    // container and ignored here, so the scrape port an operator moved was the one port `x dev`
-    // could not move — and the second `x dev` on a box died binding the hardcoded 9090.
-    metricsPort: metricsPortFor(options.env, options.port),
-    buildId,
-    runtime,
-    routes,
-    env: options.env,
-    // Read from `app.config.ts` rather than threaded through `DevOptions`: `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 same seam `serve.ts` passes: the app's own error page is a FILE under this root.
-    root: options.root,
-    // The `/_x` shell, the harness's frame, and the app's own error pages — the inline bodies this
-    // process serves; the app's surfaces are content-hashed files `'self'` admits.
-    inlineStyles: [await devShellStyle(), FRAME_STYLE, ...errorStyles],
-    inlineScripts: [theme.cspSource, ...(speculation === undefined ? [] : [speculation.cspSource])],
-    // 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 (axiom 6).
-    devNotices: (ctx: RequestContext): readonly OverlayNotice[] =>
-      statements.repeatsFor(asCtx(ctx)).map(loopFacts).map(loopNotice),
-    // The read-replica scope, opened per request. Absent for every app that names no
-    // `DATABASE_REPLICA_URL` — which is every embedded boot by construction, since PGlite has no
-    // standby — so this key does not exist on a homework app's boot at all.
-    ...(replicaOverride === undefined ? {} : { overrides: replicaOverride }),
-  });
-  acquired.push(() => running.stop());
-
-  // One rebuild at a time, and the last save wins: a tick arriving mid-build coalesces into ONE
-  // trailing rebuild instead of racing the one in flight for `state.manifest` and `state.islands`.
-  const rebuild = coalesceReloads(
-    async (file) => {
-      const started = performance.now();
-      const [{ manifest, findings }, islands] = await Promise.all([
-        appManifest(options.root),
-        buildIslands(options.root),
-      ]);
-      state.manifest = manifest;
-      state.appFindings = findings;
-      state.islands = islands;
-      for (const path of isr.store().paths()) isr.store().delete(path);
-      state.reloads += 1;
-      // Read on EVERY rebuild, so a pin one save reached is never reported against the next save.
-      const pins = takeStalePins();
-      state.reloadFinding =
-        pins.length > 0 && options.onRestart === undefined
-          ? restartFinding(options.root, pins)
-          : undefined;
-      if (pins.length > 0 && options.onRestart !== undefined) options.onRestart(pins);
-      else options.onReload?.(file, Math.round(performance.now() - started));
-    },
-    // Same rule as a module that will not import: a save the manifest cannot be rebuilt from is
-    // a finding on `/_x`, never an unhandled rejection that takes the dev server down.
-    (error: unknown, file: string) => {
-      state.reloadFinding = { ...findingFrom(error), at: file };
-    },
-  );
-  // Watched one directory at a time, so an ignored one costs no descriptor at all — `dev-watch.ts`
-  // decides which, from the app's own `.gitignore`. A recursive watch on the root registered one
-  // inotify descriptor per directory in the tree, `.git/`, `node_modules/` and the `.x/` this
-  // process writes to included, and filtered the events afterwards.
-  const watcher = watchTree({ root: options.root, onChange: rebuild });
-
-  server = {
-    url: running.url ?? `http://localhost:${options.port}`,
-    services,
-    roles: running.roles,
-    mcp: mcpPath,
-    mcpPaths,
-    get buildId(): string {
-      return stamped ?? state.manifest.buildId;
-    },
-    // 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
-        ? [...state.appFindings, ...loops]
-        : [...state.appFindings, state.reloadFinding, ...loops];
-    },
-    running,
-    runtime,
-    panels,
-    async stop() {
-      watcher.close();
-      await running.stop();
-      releaseIsr();
-      await runtime.stop();
-      // Released after the roles: a span opened by an in-flight request still has an exporter to
-      // end into. `configureTelemetry` merges, so handing back the noop is how it is uninstalled —
-      // leaving it in place would keep every span of the next `startDev` in this process's buffer.
-      configureTelemetry({ exporter: noopExporter });
-      traces.reset();
-      // With the exporter, for the same reason: an in-flight statement is observed by the ledger
-      // that counted its request. Left installed, the next `startDev`'s statements land in these
-      // counts — and instrumentation stays on in a process that is no longer a dev server.
-      setStatementObserver(undefined);
-      statements.reset();
-    },
-  };
-  return server;
-}
+// The boot moved to `dev-boot.ts`; its names stay importable from here, where every caller and the
+// package barrel already reach them.
+export type { DevServer, StartDevOptions } from './dev-boot';
+export { startDev } from './dev-boot';
 
 export const devCommand: CliCommand = {
   spec: devSpec,
@@ -400,8 +60,7 @@ export const devCommand: CliCommand = {
       roles,
       env: ctx.env,
       onReload: (file, durationMs) => {
-        if (!ctx.args.json)
-          process.stdout.write(`${msg('cli.dev.hmr', { file, ms: durationMs })}\n`);
+        if (!ctx.args.json) writeLine(msg('cli.dev.hmr', { file, ms: durationMs }));
       },
       // Supervised, a save this process cannot serve is a drain and an exit for a fresh child.
       ...restart.options,
@@ -409,6 +68,8 @@ export const devCommand: CliCommand = {
       release();
       throw error;
     });
+    // A restart retires this worker before it drains, so a save never cancels a running job.
+    restart.adopt(server.running.worker);
     const result: CommandResult = {
       ok: server.findings.length === 0,
       command: 'dev',

package/src/cmd-doctor.ts

@@ -4,20 +4,8 @@
 
 import { existsSync } from 'node:fs';
 import { dirname, join, resolve, sep } from 'node:path';
-import {
-  ENV_EXAMPLE_PATH,
-  ERROR_DOCS_URL,
-  tryResolveEnvironment,
-  usesDevCursorSecret,
-} from '@ultimat3/core';
-import {
-  checkDb,
-  createPostgresClient,
-  PGLITE_FIX,
-  PGLITE_MISSING,
-  PGLITE_PACKAGE,
-} from '@ultimat3/db';
-import { STORAGE_SIGNING_SECRET_KEY, usesDevStorageSecret } from '@ultimat3/storage';
+import { ENV_EXAMPLE_PATH, ERROR_DOCS_URL } from '@ultimat3/core';
+import { checkDb, PGLITE_FIX, PGLITE_MISSING, PGLITE_PACKAGE, postgresClient } from '@ultimat3/db';
 import { findAppRoot, REQUIRED_BUN, versionAtLeast } from './app-root';
 import { doctorSpec } from './cmd-doctor-spec';
 import type { CliCommand, CommandContext } from './command';
@@ -31,6 +19,7 @@ import { offlineFallbackFinding, offlineFallbackProbe } from './doctor-offline';
 import type { SealedKeysFact } from './doctor-sealed';
 import { sealedKeyFindings, sealedKeysProbe } from './doctor-sealed';
 import { PORT_RANGE, portPairAfter, readIntFlag } from './flag-number';
+import { machineSecretFindings } from './framework-env';
 import { ICON_SOURCE } from './icon-assets';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
@@ -40,6 +29,7 @@ import { portFree } from './port-probe';
 import { syncPortFor } from './role-sync';
 import { checkMigrationDrift } from './schema-drift';
 import { portFromEnv } from './serve-env';
+import { quoteArg } from './shell-quote';
 
 /**
  * The injection seam `runDoctor` reads instead of the environment. Not a semver surface —
@@ -54,17 +44,13 @@ export interface DoctorProbe {
   readonly port: number;
   /** `APP_URL` as this environment declares it; `undefined` when unset. */
   readonly appUrl: string | undefined;
-  /** 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.
+   * The framework's own secrets this machine lacks — `framework-env.ts`'s
+   * `machineSecretFindings`, gated by `namedDeployed`: only an environment NAMED staging or
+   * production (an unnamed developer shell owes nothing; `x env check` is the fail-closed answer).
+   * The list's own `needed`/`unsafe` decide; doctor reports.
    */
-  readonly devStorageSecret: boolean;
-  /** True when this process believes it is serving real clients. */
-  readonly production: boolean;
+  readonly frameworkFindings: readonly Finding[];
   exists(relativePath: string): boolean;
   portFree(port: number): Promise<boolean>;
   /**
@@ -191,7 +177,7 @@ async function portFindings(probe: DoctorProbe): Promise<readonly Finding[]> {
       finding(
         'X_PORT_IN_USE',
         `port ${entry.port} is already listening, and \`x dev --port ${probe.port}\` binds it for the ${entry.role} role`,
-        `x dev --port ${portPairAfter(probe.port)}`,
+        `x dev --port ${quoteArg(String(portPairAfter(probe.port)))}`,
       ),
     );
   }
@@ -231,41 +217,14 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
         // `.env.example` is the committed projection of `envSchema`, so the copy lands every
         // declared key with its default and blank secrets; `x env example` writes it where an app
         // has none, and `X_ENV_EXAMPLE_DRIFT` is what reports that.
-        `cp ${ENV_EXAMPLE_PATH} ${ENV_DEVELOPMENT}`,
+        `cp ${quoteArg(ENV_EXAMPLE_PATH)} ${quoteArg(ENV_DEVELOPMENT)}`,
         ENV_DEVELOPMENT,
       ),
     );
   }
-  // Production only, and the gate is the point: every development environment signs with the
-  // shipped key on purpose — that is what lets `x dev` page with no configuration — so an
-  // unconditional finding would make `x doctor` red for every developer on day one and teach the
-  // reader to skim past the report. The key is a defect only where cursors reach real clients,
-  // who can read it out of the published package and forge a page position.
-  // Sits here because it costs two env reads and a comparison — cheaper than binding a port.
-  if (probe.production && probe.devCursorSecret) {
-    findings.push(
-      finding(
-        'X_CURSOR_SECRET_DEV',
-        'cursors are signed with the shipped development key, so a client can forge a page position',
-        'export ULTIMATE_CURSOR_SECRET="$(openssl rand -hex 32)"',
-      ),
-    );
-  }
-  // 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)"',
-      ),
-    );
-  }
+  // Silent in development and on a shell naming no environment; reported where this machine names
+  // a deploy. One list, one wording (`framework-env.ts`, #679).
+  findings.push(...probe.frameworkFindings);
   findings.push(...(await portFindings(probe)));
   findings.push(...appUrlFindings(probe.appUrl, probe.port));
   // `@ultimat3/pwa`'s own codes, not CLI twins of them. `X_PWA_NO_ICON_SOURCE` and
@@ -376,7 +335,7 @@ const installedAbove = (dir: string, specifier: string): boolean => {
  */
 async function probeDatabase(url: string | undefined): Promise<Finding | null> {
   if (externalUrl(url) === undefined) return null;
-  const client = createPostgresClient({ url, applicationName: 'x-doctor' });
+  const client = postgresClient({ url, applicationName: 'x-doctor' });
   try {
     const report = await checkDb(client);
     if (report.ok) return null;
@@ -407,16 +366,7 @@ export function probeFor(
     root,
     port,
     appUrl: env['APP_URL'],
-    devCursorSecret: usesDevCursorSecret(),
-    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',
+    frameworkFindings: machineSecretFindings(env),
     exists: (relativePath) => (root === undefined ? false : existsSync(join(root, relativePath))),
     portFree,
     database: () => probeDatabase(process.env['DATABASE_URL']),

package/src/cmd-env.ts

@@ -15,6 +15,7 @@ import { 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 { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 
@@ -67,33 +68,47 @@ async function writeExample(ctx: CommandContext): Promise<CommandResult> {
 }
 
 /**
- * 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
+ * The values are read from the environment the command was handed (`ctx.env`, the process's own
+ * in `bin.ts`) — one table for the app's keys and the framework's — 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.
+ *
+ * The framework's deploy-required secrets (`framework-env.ts`) are asked exactly where the boot
+ * refuses them — outside development/test, and where no environment is named at all — so `ULTIMATE_ENV=production x env check` answers what
+ * the first deployed boot would, instead of each role crash-looping on one key at a time (#679).
  */
 async function checkProcessEnv(ctx: CommandContext): Promise<CommandResult> {
   const { schema } = await requireSchema(ctx.cwd, 'check');
-  const report = checkEnv(schema);
+  const report = checkEnv(schema, { env: ctx.env });
   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: ERROR_DOCS_URL,
-    at: ENV_EXAMPLE_PATH,
-  }));
+  // A key the app's own declaration already reported is one finding, not two.
+  const reported = new Set(report.issues.map((issue) => issue.key));
+  // Gated by `deployed()` inside — the boot's own rule, so a table naming no environment is
+  // checked as the production process it boots as.
+  const framework = frameworkSecretFindings(ctx.env, reported);
+  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: ERROR_DOCS_URL,
+      at: ENV_EXAMPLE_PATH,
+    })),
+    ...framework,
+  ];
+  const ok = findings.length === 0;
   return {
-    ok: report.ok,
+    ok,
     command: 'env',
-    summary: report.ok
+    summary: ok
       ? msg('cli.env.checked', { count: total })
-      : msg('cli.env.invalid', { count: report.issues.length, total }),
+      : msg('cli.env.invalid', { count: findings.length, total }),
     findings,
     data: {
       variables: total,
       values: maskedEnvValues(schema, report.values) as JsonValue,
     },
-    exitCode: report.ok ? 0 : 1,
+    exitCode: ok ? 0 : 1,
   };
 }
 

package/src/cmd-generate.ts

@@ -12,13 +12,15 @@ import { requireAppRoot } from './app-root';
 import { generateSpec } from './cmd-generate-spec';
 import type { CliCommand, CommandContext } from './command';
 import { invocationOf } from './command';
+import { localiseCatalogs } from './generate-catalog-locales';
 import { assertFeatureExists } from './generate-feature';
 import { generate, sliceDir } from './generate-files';
 import { ungrantedByGenerator } from './generate-grant-findings';
 import { grantGeneratedPermissions } from './generate-grants';
 import type { Generator } from './generate-kinds';
 import { readFeature, readKind, readName, readPermission, readSurface } from './generate-kinds';
-import { refuseShadowedTypes } from './generate-shadow';
+import { refusePluralTable } from './generate-plural';
+import { refuseShadowedTypes, refuseShadowedValues } from './generate-shadow';
 import { containedPath, planWrites, writeFiles } from './generate-write';
 import { declareGeneratedImports } from './generated-imports';
 import { registerGeneratedEntities, resolveDbModule } from './handle-registration';
@@ -110,10 +112,18 @@ export const generateCommand: CliCommand = {
         ...(dbModule === undefined ? {} : { dbModule }),
         shell,
       });
-    const files = planFor(name);
+    // A non-default locale's strings arrive marked, and a locale with no catalog yet is refused
+    // with `x i18n add <locale>` — before a dry run answers, so it answers the same files.
+    const files = await localiseCatalogs(root, planFor(name));
     // On the planned files, before a dry run answers or anything lands: a name whose type spelling
     // the emitted code also uses as a global is a slice that does not compile.
     refuseShadowedTypes(files, kind, name);
+    // And one whose binding a planned file both imports and declares (`x g job job`).
+    refuseShadowedValues(files, kind, name);
+    // And a plural slice name that an `entity.ts` this run writes would pluralise again.
+    refusePluralTable(files, kind, name, featureFlag, (path) =>
+      existsSync(containedPath(root, path)),
+    );
     // The caller's own invocation, EVERY flag it set included: without `--feature` the fix wrote
     // a second slice beside the one that conflicted.
     const flags = reproducedFlags(generateCommand.spec, ctx.args);