@ultimat3/cli 1.2.0 → 3.0.0

package/src/cmd-deploy.ts

@@ -6,12 +6,35 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
-import { CliNotImplementedError } from './errors';
+import { BadFlagError, CliNotImplementedError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
 import { flagBool, flagString } from './parse';
 
-export const DEPLOY_ROLES = ['migrate', 'web', 'sync', 'worker', 'scheduler'] as const;
+/**
+ * Ordered, and the order is the design. `migrate` GATES — it runs to completion before anything
+ * serves, and a schema difference after it fails the deploy. `backfill` is last and TRIGGERS: a
+ * data sweep put inside a release gate holds the deploy open while a slow UPDATE runs against a
+ * database still serving the PREVIOUS release, so it runs after the new pods are up and the
+ * workers already draining the queue are what perform it. That is also why it is not wired into
+ * `runMigrations()` and never will be.
+ *
+ * `backfill` is a one-shot like `migrate`, so it takes the same `run --rm` shape; the compose
+ * service behind it runs `x db backfill --all --write --json` rather than a `ROLE`, because
+ * `@ultimat3/core`'s `ROLES` is a closed list of process shapes and a sweep trigger is a command.
+ *
+ * ORDER HERE IS NECESSARY AND NOT SUFFICIENT. `docker compose up -d` returns when a container has
+ * STARTED, not when the application inside it is serving, so this list alone puts the trigger after
+ * the serving roles were asked to start and not after they are ready. The barrier that makes
+ * "after" true is declarative and belongs to the compose file, not to this plan: the `backfill`
+ * service needs `depends_on: { web: { condition: service_healthy } }`, which `docker compose run`
+ * honours. Both compose definitions — `docker/docker-compose.prod.yml` and the one
+ * `templates/scaffold-container.ts` scaffolds — still owe that service and that condition.
+ */
+export const DEPLOY_ROLES = ['migrate', 'web', 'sync', 'worker', 'scheduler', 'backfill'] as const;
+
+/** The roles that run to completion and exit, as against the ones that stay up serving. */
+const ONE_SHOT_ROLES: readonly string[] = ['migrate', 'backfill'];
 
 export interface DeployPlan {
   readonly image: string;
@@ -19,8 +42,39 @@ export interface DeployPlan {
   readonly steps: readonly { readonly role: string; readonly command: readonly string[] }[];
 }
 
+/**
+ * The chart declares `image` as a MAP — `repository`, `tag`, `pullPolicy` — and `_helpers.tpl`
+ * renders `printf "%s:%s" .Values.image.repository (default .Chart.AppVersion .Values.image.tag)`.
+ * `--set image=<ref>` replaces that map with a string, so every workload template fails on
+ * `.repository` and the deploy that was asked to ship one image ships nothing. The reference is
+ * split into the two keys the chart actually reads; a reference with no tag sets only the
+ * repository, which leaves the chart's own `default .Chart.AppVersion` in force.
+ *
+ * The last `:` after the last `/`, because a registry may carry a port: `localhost:5000/app` is a
+ * repository with no tag and `localhost:5000/app:1.2.3` is the same repository with one.
+ */
+export function helmImageOverrides(image: string): readonly string[] {
+  const colon = image.lastIndexOf(':');
+  const tag = colon > image.lastIndexOf('/') ? image.slice(colon + 1) : '';
+  const repository = tag === '' ? image : image.slice(0, colon);
+  return tag === ''
+    ? ['--set', `image.repository=${repository}`]
+    : ['--set', `image.repository=${repository}`, '--set', `image.tag=${tag}`];
+}
+
 export function planDeploy(image: string, method: 'compose' | 'helm', root: string): DeployPlan {
   if (method === 'helm') {
+    // `repo@sha256:…` is a reference this chart cannot express: it renders `repository:tag` and
+    // has no digest branch, so passing one through would deploy `repo@sha256:…:<appVersion>` —
+    // a tag no registry has. Refused here rather than by a `helm upgrade` failing halfway.
+    if (image.lastIndexOf('@') > image.lastIndexOf('/')) {
+      throw new BadFlagError({
+        flag: 'image',
+        command: 'deploy',
+        reason: `"${image}" pins a digest, and docker/helm renders repository:tag with no digest branch`,
+        fix: `x deploy --method helm --image ${image.slice(0, image.lastIndexOf('@'))}:<tag> --json`,
+      });
+    }
     return {
       image,
       steps: [
@@ -32,8 +86,7 @@ export function planDeploy(image: string, method: 'compose' | 'helm', root: stri
             '--install',
             'app',
             join(root, 'docker', 'helm'),
-            '--set',
-            `image=${image}`,
+            ...helmImageOverrides(image),
           ],
         },
       ],
@@ -48,8 +101,8 @@ export function planDeploy(image: string, method: 'compose' | 'helm', root: stri
         'compose',
         '-f',
         join(root, 'docker', 'docker-compose.prod.yml'),
-        role === 'migrate' ? 'run' : 'up',
-        role === 'migrate' ? '--rm' : '-d',
+        ONE_SHOT_ROLES.includes(role) ? 'run' : 'up',
+        ONE_SHOT_ROLES.includes(role) ? '--rm' : '-d',
         role,
       ],
     })),

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,27 @@ 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 { metricsPortFor } from './serve';
+import { loopFacts, loopFinding, loopNotice } from './statement-loop';
 
 const DEFAULT_PORT = 3000;
 
@@ -41,7 +53,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 +71,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 +127,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,34 +162,60 @@ 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({
     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`: 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 +234,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 +256,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;
@@ -206,21 +271,29 @@ export const devCommand: CliCommand = {
   spec: {
     name: 'dev',
     summary: 'all roles in one process: embedded services, sub-second reload, /_x mounted',
-    usage: 'x dev [--port 3000] [--role web,worker] [--json]',
+    usage: 'x dev [--port 3000] [--role web,worker] [--once] [--json]',
     requiresApp: true,
     flags: [
       { name: 'port', type: 'string', summary: 'HTTP port', default: String(DEFAULT_PORT) },
       {
         name: 'role',
         type: 'string',
-        summary: `roles to run (default: all of ${DEV_ROLES.join(',')})`,
+        // `replicator` is named because it is selectable and NOT default — it takes a replication
+        // slot on a shared database, which is not something every `x dev` should do by starting.
+        summary: `roles to run (default: all of ${DEV_ROLES.join(',')}; replicator is opt-in)`,
       },
       { name: 'once', type: 'boolean', summary: 'boot, report, exit — for smoke tests and CI' },
     ],
   },
   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 +326,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,17 @@
 
 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, neighbouringPort, PORT_RANGE } from './flag-number';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
-import { flagString } from './parse';
+import type { ParsedArgs } from './parse';
 
 /**
  * The injection seam `runDoctor` reads instead of the environment. Not a semver surface —
@@ -26,11 +29,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 +58,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,12 +107,27 @@ 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(
         'X_PORT_IN_USE',
         `port ${probe.port} is already listening`,
-        `x dev --port ${probe.port + 1}`,
+        `x dev --port ${neighbouringPort(probe.port)}`,
       ),
     );
   }
@@ -125,9 +159,25 @@ 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;
 }
 
+/**
+ * The port to TEST, and the one place `x doctor` reads it. `PORT_RANGE.min` is 0 because `x dev
+ * --port 0` means "let the kernel pick"; here 0 means nothing, and `Bun.serve({ port: 0 })` always
+ * succeeds — so the port check could not fail, which is worse than not running it.
+ */
+export const doctorPort = (args: ParsedArgs): number =>
+  intFlagOr(
+    args,
+    { name: 'port', command: 'doctor', ...PORT_RANGE, min: 1, example: 'x doctor --port 3000' },
+    DEFAULT_DOCTOR_PORT,
+  );
+
 const portFree = async (port: number): Promise<boolean> => {
   try {
     const server = Bun.serve({ port, fetch: () => new Response('') });
@@ -145,12 +195,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 +216,17 @@ 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 = doctorPort(ctx.args);
     const findings = await runDoctor(probeFor(ctx.cwd, ctx.bunVersion, port));
     return {
       ok: findings.length === 0,