@ultimat3/cli 22.15.0 → 24.0.0

package/src/json-merge.ts

@@ -38,3 +38,49 @@ export function mergeJsonDeep(
   }
   return { merged, gained };
 }
+
+/** Code units, never `localeCompare`: the bytes must not move with the machine's ICU. */
+const byCodeUnit = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+const isSorted = (keys: readonly string[]): boolean =>
+  keys.every((key, index) => index === 0 || byCodeUnit(keys[index - 1] ?? '', key) <= 0);
+
+/** Every key of every level, sorted — the order a generator's own fresh output is written in. */
+export function sortJsonDeep(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortJsonDeep);
+  if (!isObject(value)) return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort(byCodeUnit)
+      .map((key) => [key, sortJsonDeep(value[key])]),
+  );
+}
+
+/**
+ * `mergeJsonDeep`, for a file that is ALREADY ON DISK: the same union, written back in the order
+ * the file is in. A catalog a team keeps grouped by screen was re-sorted wholesale by a merge
+ * that sorted every level — 424 changed lines for 22 added keys — which buries the keys a run
+ * added and turns every generator run into a merge conflict.
+ *
+ * Per level: a held key stays where it is. A new key takes its SORTED place when that level is
+ * sorted already — which is every level a generator wrote, so two runs in either order still write
+ * the same bytes — and goes to the END, in sorted order among the new ones, when it is not. A
+ * wholly new subtree is the generator's own and arrives sorted.
+ */
+export function mergeJsonInPlace(held: JsonObject, incoming: JsonObject): JsonObject {
+  const heldKeys = Object.keys(held);
+  const added = Object.keys(incoming)
+    .filter((key) => !Object.hasOwn(held, key))
+    .sort(byCodeUnit);
+  const order = isSorted(heldKeys)
+    ? [...heldKeys, ...added].sort(byCodeUnit)
+    : [...heldKeys, ...added];
+  return Object.fromEntries(
+    order.map((key) => {
+      if (!Object.hasOwn(held, key)) return [key, sortJsonDeep(incoming[key])];
+      const current = held[key];
+      const next = incoming[key];
+      return [key, isObject(current) && isObject(next) ? mergeJsonInPlace(current, next) : current];
+    }),
+  );
+}

package/src/loopback-host.ts

@@ -0,0 +1,13 @@
+// Whether a hostname is this machine: `localhost`, a `*.localhost` name (RFC 6761 reserves both
+// to loopback) or a loopback address literal. One answer for `x dev`'s Host check and `x doctor`'s
+// APP_URL rule, which ask the same question about two different headers.
+
+import { classifyAddress } from '@ultimat3/core';
+
+/** `hostname` as `URL` spells it — `[::1]` bracketed, no port. */
+export const isLoopbackHostname = (hostname: string): boolean => {
+  const name = hostname.toLowerCase();
+  return (
+    name === 'localhost' || name.endsWith('.localhost') || classifyAddress(name) === 'loopback'
+  );
+};

package/src/manifest-staleness.ts

@@ -0,0 +1,62 @@
+// Do the committed generated files still describe the code? ONE check, asked by `x manifest
+// --check` and by the gate's `manifest` step through this function — two commands answering
+// differently about one file is itself the drift these files exist to prevent.
+
+// why: Bun has no synchronous existence probe, and `hasCommittedContract` guards an app load.
+import { existsSync } from 'node:fs';
+// why: Bun exposes no path-join primitive; Bun.file takes a path already joined.
+import { join } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { Manifest } from '@ultimat3/manifest';
+import { assertNoDrift, MANIFEST_FILENAME } from '@ultimat3/manifest';
+import { OPENAPI_FILE, openApiStaleness } from './app-openapi';
+import { APP_CONFIG_FILE } from './app-root';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+
+/** Whether there is any committed contract here to judge — the cheap question, asked first. */
+export const hasCommittedContract = (root: string): boolean =>
+  existsSync(join(root, MANIFEST_FILENAME)) || existsSync(join(root, OPENAPI_FILE));
+
+/**
+ * `x.manifest.json` was never written. An app root only: the framework monorepo emits
+ * `framework.manifest.json` and has no `x.manifest.json` to be missing. `AGENTS.md` tells an agent
+ * that facts live in this file, and after `x new` and every generator nothing had run the one
+ * command that writes it while the gate reported green (#F7).
+ */
+export function manifestMissingFindings(root: string): readonly Finding[] {
+  if (!existsSync(join(root, APP_CONFIG_FILE))) return [];
+  if (existsSync(join(root, MANIFEST_FILENAME))) return [];
+  return [
+    {
+      code: 'X_MANIFEST_MISSING',
+      cause: `${MANIFEST_FILENAME} does not exist, so every fact an agent reads about this app — route table, action schemas, policies, error codes — is unavailable`,
+      fix: 'x manifest',
+      docs: ERROR_DOCS_URL,
+      at: MANIFEST_FILENAME,
+    },
+  ];
+}
+
+/**
+ * Every way the committed files disagree with `manifest`, the app as the code declares it now:
+ * `x.manifest.json` missing (`X_MANIFEST_MISSING`) or drifted (`X_MANIFEST_DRIFT` — a body that no
+ * longer hashes to its own `buildId` included), and `openapi.json` or a bearer mount's document
+ * stale (`X_MANIFEST_STALE`). The spec is judged whether or not the manifest is there: it is a
+ * published contract on its own, and the typed client is generated from it.
+ */
+export async function manifestStaleness(
+  root: string,
+  manifest: Manifest,
+): Promise<readonly Finding[]> {
+  const path = join(root, MANIFEST_FILENAME);
+  const findings: Finding[] = [...manifestMissingFindings(root)];
+  if (existsSync(path)) {
+    try {
+      await assertNoDrift({ manifest, path });
+    } catch (error) {
+      findings.push({ ...findingFrom(error), at: MANIFEST_FILENAME });
+    }
+  }
+  return [...findings, ...(await openApiStaleness(root, manifest))];
+}

package/src/mcp-errors.ts

@@ -43,7 +43,17 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_VERIFY_MERGE_INCOMPLETE:
     'x verify merge parts/*.json --json   # after every CI job uploaded its part',
   X_VERIFY_MERGE_INPUT: 'x verify --only unit --json > part.json   # one document per part',
-  X_TEST_SHARD_FAILED: 'x test --workers 1 --json',
+  X_VERIFY_STEP_TIMEOUT:
+    'x verify --only unit --json   # reproduce the step alone; one that needs longer states it under "stepTimeoutMs" in x.verify.json',
+  X_COVERAGE_BELOW_FLOOR:
+    'x verify --only unit --json   # names the ten files losing the most lines; cover the worst with a test beside it',
+  X_COVERAGE_FLOOR_UNSTATED:
+    'x verify --only unit --json   # the finding carries the measured numbers and the "coverage" line to add to x.verify.json',
+  X_COVERAGE_FLOOR_STALE:
+    'x verify --only unit --json   # the finding carries the measured numbers; raise "coverage" in x.verify.json to them',
+  // Unthrown since `--worker` was deleted, and kept only because this record is typed over every
+  // registered code: `--shard i/n` is the one way to rerun a slice.
+  X_TEST_SHARD_FAILED: 'x verify --only unit --shard 1/2 --json',
   X_SCAFFOLD_PATH_ESCAPE: 'x g route posts --json   # a path with no ".." segment',
   X_GENERATE_JSON_INVALID:
     'bun test packages/cli/src/cmd-generate.test.ts   # the error names the template to fix',
@@ -110,8 +120,7 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x errors list --json   # register the code in its package src/errors.ts, or move its row under "Reserved codes"',
   X_ERROR_CODE_UNRESOLVED:
     'x verify --json   # the finding names the file, the line and the name it could not resolve',
-  X_ERROR_CODE_UNTHROWN:
-    'x errors explain X_ERROR_CODE_UNTHROWN --json   # then mark the row "registered, thrown by nothing since <version>"',
+  X_ERROR_CODE_UNTHROWN: 'x errors explain X_ERROR_CODE_UNTHROWN --json',
   X_CLI_UNEXPECTED: 'x doctor --json',
   // `-p .`: an app root has no `references`, so the gate's own step runs this form (#450).
   X_TYPECHECK_FAILED: 'bunx tsc -p . --pretty false',
@@ -233,18 +242,30 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_GUARD_FAILED: 'x verify --json   # the cause carries the throw the guard raised, verbatim',
   X_GUARD_FINDING_INVALID:
     'x verify --json   # then give the finding an X_ code, a cause and a fix naming a command',
+  // The finding's own `fix:` is this command plus the edit — the line, and what replaces the call.
+  X_BROWSER_TRANSPORT_BYPASS:
+    'x verify --only boundaries --json   # each finding names the line and the transport to use instead',
+  X_BROWSER_SERVER_BARREL:
+    'x verify --only boundaries --json   # each finding names the import and the browser entry to import instead',
   // `EDITOR=` inline rather than `export`: the variable is only needed for the one invocation, and
   // an agent copying this line gets a working command instead of a shell it has to keep.
   X_SECRETS_EDITOR_MISSING: 'EDITOR=nano x secrets edit',
   X_SECRETS_EDIT_FAILED: 'x secrets show --json   # then re-open the buffer: x secrets edit',
+  X_SEAL_RESEAL_PENDING:
+    'x doctor --json   # names the sealed columns and the retired key; re-seal with a backfill(), then: x secrets rotate --drop <keyId>',
   // Render's code, thrown here by the bundler half: the cause names the specifier and the file it
   // resolved to, and `x g island` is what puts that file where the page already says it is.
   X_ISLAND_INVALID: 'x routes --json   # the cause names the src; then: x g island <name>',
   // The four slice-11 codes: generated code that passed the gate and failed at runtime.
+  // The role map's file is the app's: the finding's `at` names it, so this line never guesses one.
   X_PERMISSION_UNGRANTED:
-    'x verify --only policy --json   # then add the permission to a role in apps/web/shared/roles.ts',
+    'x verify --only policy --json   # then add the permission to a role in the file the finding names (at)',
   X_JOB_UNREGISTERED:
     'x manifest --json   # after listing the module under jobs: [...] in apps/web/api/index.ts',
+  // The boot's twin of the line above: the worker or scheduler loaded only what the API index
+  // imports, and the manifest names a job or task that load did not register.
+  X_ROLE_LOAD_INCOMPLETE:
+    'x manifest --json   # after importing the module the cause names from apps/web/api/index.ts',
   X_FEATURE_UNKNOWN:
     'x entities --json   # then x g resource <feature> for the one the cause names',
   X_BUDGET_PARAMS_UNDECLARED:
@@ -256,6 +277,22 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_DEV_RESTART_REQUIRED:
     'x dev --json   # a fresh process; the supervised x dev restarts itself on such a save',
   X_DEV_ROOT_GONE: 'x dev --json   # from the app root, once it exists again',
+  X_DB_HANDLE_UNREGISTERED:
+    'x g entity widget --dry-run --json   # lists the files; the finding names the two lines to add to packages/db/src/client.ts',
+  X_ADMIN_RESOURCE_UNWIRED:
+    'x g resource widget --admin --dry-run --json   # lists the files; the finding names the two lines to add to apps/admin/app/admin/admin.ts',
+  X_IMAGE_NOT_PREBUILT:
+    'edit docker/Dockerfile: add RUN bun node_modules/@ultimat3/cli/src/bin.ts build --target prebuilt after COPY . . in the runtime stage, then rebuild the image',
+  X_ADMIN_UNSCANNED:
+    'git mv apps/admin/src/index.ts apps/admin/app/admin/admin.ts   # then repoint its relative imports and x verify --only manifest --json',
+  X_FRAMEWORK_TABLE_ORPHANED: 'x doctor --json',
+  X_BUILD_OUT_UNSAFE: 'x build --target static --out .x/static --json',
+  X_FRAMEWORK_SCHEMA_UNAPPLIED: 'x db migrate --json',
+  X_APP_URL_PORT_MISMATCH: 'export APP_URL=http://localhost:3000',
+  X_DEV_HOST_REFUSED: "curl -sS -H 'accept: application/json' http://localhost:3000/_x",
+  X_TRUSTED_PROXY_HOPS_INVALID: 'TRUSTED_PROXY_HOPS=1 ROLE=web bun apps/web/server.ts',
+  X_PERMISSION_BORROWED: 'x verify --only policy --json',
+  X_ERROR_CODE_UNTHROWN_STALE: 'x errors explain X_ERROR_CODE_UNTHROWN_STALE --json',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>

package/src/mcp-host.ts

@@ -7,7 +7,13 @@
 // or prints inside a `fix:` an operator runs — the dev log, a per-role log, the committed
 // manifest — and string concatenation would answer a different path on a Windows checkout.
 import { join } from 'node:path';
-import { agentActor, isUltimateError, renderThrowable, UltimateError } from '@ultimat3/core';
+import {
+  agentActor,
+  isUltimateError,
+  NotImplementedError,
+  renderThrowable,
+  UltimateError,
+} from '@ultimat3/core';
 import type { DbClient } from '@ultimat3/db';
 import {
   ensureReadOnlyRole,
@@ -35,12 +41,11 @@ import { appManifest, policyFacts } from './app-manifest';
 import { runVerify, VERIFY_STEPS } from './cmd-verify';
 import { declareDevEnvironment } from './dev-environment';
 import { loadCodeFixes } from './error-fixes';
-import { BadFlagError, CliNotImplementedError } from './errors';
+import { BadFlagError } from './errors';
 import type { Runner } from './exec';
-import { execOutput } from './exec';
 import { databaseTarget } from './mcp-db-target';
 import { explainErrorCode } from './mcp-errors';
-import { parseBunTest } from './mcp-test-output';
+import { testRunOf } from './mcp-test-run';
 import { type UiCapabilities, uiCapabilities } from './mcp-ui';
 import { readMigrations } from './migrations';
 import { retryMemo } from './retry-memo';
@@ -107,8 +112,9 @@ export function lazyServices(input: DevHostInput): LazyServices {
       // A boot started after close() would hold the PGlite data directory for the life of the
       // process with nobody left to stop it — the host is closed, so the call is the bug.
       if (closed) {
-        throw new CliNotImplementedError({
-          feature: 'an MCP tool that needs the database after the host closed',
+        throw new NotImplementedError({
+          cause:
+            'an MCP tool that needs the database after the host closed is not implemented in this build',
           fix: 'x mcp serve --transport stdio   # keep the host open for the whole session',
         });
       }
@@ -271,7 +277,8 @@ function capabilities(
         cwd: root,
         ...(Object.keys(envOverrides).length === 0 ? {} : { env: envOverrides }),
       });
-      return parseBunTest(execOutput(result), result.durationMs);
+      // The whole result, exit code included: `0 fail` beside `1 error` is a red run.
+      return testRunOf(result);
     },
 
     async tailLogs(lines: number, role: string | undefined) {
@@ -281,8 +288,8 @@ function capabilities(
       if (!(await file.exists())) {
         // `@ultimat3/core`'s `logger` is a module const with no sink seam, so there is nothing to
         // intercept in-process — a log on disk is the only honest source, and the fix creates one.
-        throw new CliNotImplementedError({
-          feature: `logs.tail without ${path}`,
+        throw new NotImplementedError({
+          cause: `logs.tail without ${path} is not implemented in this build`,
           fix:
             role === undefined
               ? `x dev > ${path} 2>&1`

package/src/mcp-test-run.ts

@@ -0,0 +1,38 @@
+// `test.run`'s answer from the whole `bun test` result, not from its pass/fail lines alone: bun
+// counts an error raised OUTSIDE any test on a line of its own (`1 error`) beside `0 fail`, and
+// says the run failed only through its exit code.
+
+import type { TestRun } from '@ultimat3/mcp';
+import type { ExecResult } from './exec';
+import { execOutput } from './exec';
+import { parseBunTest } from './mcp-test-output';
+
+/** Bun's own `N error` / `N errors` summary line: the last one, as `parseBunTest` reads the rest. */
+export const errorsIn = (output: string): number => {
+  const last = [...output.matchAll(/^\s*(\d+)\s+errors?\s*$/gm)].at(-1);
+  return last === undefined ? 0 : Number.parseInt(last[1] ?? '0', 10);
+};
+
+/**
+ * Every error outside a test is one failure, carried with the run's own message; a non-zero exit
+ * with nothing else counted is one more, so a red process can never answer `failed: 0`.
+ */
+export function testRunOf(result: ExecResult): TestRun {
+  const output = execOutput(result);
+  const run = parseBunTest(output, result.durationMs);
+  const errors = errorsIn(output);
+  const outside = Array.from({ length: errors }, () => ({
+    test: 'bun test',
+    message: 'an error outside any test — a file that threw while loading, or a failed hook',
+  }));
+  const counted = run.failed + errors;
+  const exitOnly =
+    result.code !== 0 && counted === 0
+      ? [{ test: 'bun test', message: `bun test exited ${String(result.code)} with no failure` }]
+      : [];
+  return {
+    ...run,
+    failed: counted + exitOnly.length,
+    failures: [...run.failures, ...outside, ...exitOnly],
+  };
+}

package/src/messages.ts

@@ -50,12 +50,21 @@ const CATALOG = {
   'cli.db.branch.unknown': '-',
   'cli.db.gen.failed': 'migration not generated',
   'cli.db.gen.unchanged': 'entities and migrations agree — nothing to generate',
+  'cli.db.gen.blocked':
+    'nothing was compared — the app did not load ({count} finding(s)); fix them, then run x db gen again',
   // A THIRD outcome, and it is neither of the other two: nothing to generate, but the sidecar the
   // `drift` step reads did move — an edit under `packages/db/src` that implies no DDL. Rendering it
   // as `written` would name a migration nobody can apply; as `unchanged`, it would hide a file this
   // command wrote. `GeneratedFiles.outcome` is what `--json` carries the same distinction on.
   'cli.db.gen.recorded': 'no migration needed — schema hash re-recorded in {file}',
+  // The fourth: no DDL and no sidecar moved, but `packages/db/schema/` did — a hand edit repaired,
+  // or a framework table that changed under an upgrade. `unchanged` would deny a write the lines
+  // below it list, and this command is `X_SCHEMA_DUMP_DRIFT`'s whole `fix:`.
+  'cli.db.gen.dumped': 'no migration needed — schema dump rewritten ({count} file(s))',
   'cli.db.gen.written': 'migration {id} generated',
+  // Exit 1 and a migration on disk at once: the summary carries the half the exit code hides.
+  'cli.db.gen.writtenDumpFailed':
+    'migration {id} generated and written — the schema dump was not; do not generate it again',
   'cli.db.migrate.applied': 'migrations applied',
   'cli.db.migrate.failed': 'migration failed',
   'cli.db.reset.done': 'database reset and migrated',
@@ -88,6 +97,11 @@ const CATALOG = {
   'cli.deploy.plan': 'containers only: {images} image, roles {roles}',
   'cli.doctor.clean': 'no findings — environment is shippable',
   'cli.doctor.findings': '{count} finding(s)',
+  'cli.doctor.guards':
+    '{count} shipped guard(s) this app does not hold — each line adds one, then x verify reports what it finds:',
+  // `x doctor`'s other listing: what the coverage floor in x.verify.json does not see, and why.
+  'cli.doctor.coverageExclude':
+    '{count} path(s) x.verify.json excludes from the coverage floor — each with the reason it gives:',
   'cli.docs.code': '{code} is an error code — x errors explain answers it',
   'cli.docs.exports': 'exports: {list}',
   'cli.docs.installed': 'installed: {list}',
@@ -110,6 +124,8 @@ const CATALOG = {
   'cli.fix.plan':
     '{count} boundary violation(s) involve {file} — {edits} edit(s) to make, nothing written',
   'cli.generate.wrote': 'wrote {count} file(s) for {kind} {name}',
+  // The run that declared a table: `{next}` is commands, joined with `&&`, that run as printed.
+  'cli.generate.wroteNext': 'wrote {count} file(s) for {kind} {name} — next: {next}',
   // A distinct key, not the same sentence with a flag beside it: `--dry-run` reported "wrote 4
   // file(s)" while `data.dryRun` said nothing had landed, so an agent branching on `summary`
   // believed the files were on disk.
@@ -131,7 +147,13 @@ const CATALOG = {
   'cli.jobs.drainedPartial':
     'drained {count} job(s) from {from} to {to} — {skipped} left on {from}',
   'cli.jobs.listed': '{count} job(s)',
+  'cli.jobs.nextPage': 'more — next page: x jobs ls --after {cursor}',
   'cli.jobs.noError': 'no error recorded',
+  'cli.jobs.paused': 'queue {queue} paused — no worker claims from it; enqueues still land',
+  'cli.jobs.pausedQueues': 'paused queue(s): {queues}',
+  'cli.jobs.promoted': 'job {id} promoted — due now',
+  'cli.jobs.removed': 'job {id} removed — it was {state}',
+  'cli.jobs.resumed': 'queue {queue} resumed',
   'cli.jobs.retried': 'job {id} re-queued — {state}',
   'cli.jobs.shown': 'job {id} — {state}, attempt {attempt} of {attempts}',
   'cli.jobs.skipped': '{count} job(s) left on {from} — re-run the drain once each is claimable:',
@@ -175,6 +197,8 @@ const CATALOG = {
   'cli.registry.described': '{kind} {name}',
   'cli.routes.count': '{count} routes',
   'cli.routes.empty': 'no routes in the manifest — run `x manifest` first',
+  'cli.auth.sealed':
+    'sealed {sealed} second-factor secret(s); {already} already sealed, {skipped} changed mid-run and left alone',
   'cli.tasks.count': '{count} task(s)',
   'cli.tasks.shown': '{name} — {cron} ({tz}), next {next}',
   'cli.affected.count':
@@ -296,6 +320,12 @@ const CATALOG = {
   // no skipped test to read a reason off, so the files the step selected hold no test.
   'cli.verify.ranNothing': 'found no test to run in the file(s) it selected',
   'cli.verify.merged': 'merged {parts} part(s) — {summary}',
+  // The `unit` step's own measurement, in `output`: what the suite covered of the app's whole
+  // source tree, beside the floor it was held to. A shard says it measured a slice instead.
+  'cli.verify.coverage':
+    'coverage: {lines}% of lines, {funcs}% of functions over {files} source file(s) — floor {floor}',
+  'cli.verify.coverageDeferred':
+    'coverage: this shard measured its own slice — x verify merge folds every shard and judges the floor',
   'cli.verify.serial': 'serial',
   'cli.verify.workers': '{workers} workers',
   'cli.env.checked': '{count} declared variable(s), all present and valid',
@@ -314,6 +344,11 @@ const CATALOG = {
   'cli.secrets.set': 'sealed {name} into {path} — {count} secret(s)',
   'cli.secrets.rotated':
     'rotated {path} from master key {from} to {to} — {count} secret(s) resealed',
+  'cli.secrets.retired':
+    '  master key {kid} is retired, not gone: values it sealed still open — once they are re-sealed, x secrets rotate --drop {kid}',
+  'cli.secrets.dropped':
+    'dropped retired master key {kid} from {path} — {count} retired key(s) still declared',
+  'cli.secrets.ring': 'retired master key(s) that still open sealed values: {kids}',
 } as const;
 
 export type MessageKey = keyof typeof CATALOG;

package/src/metrics-endpoint.ts

@@ -1,14 +1,19 @@
 // Single responsibility: the scrape listener every role opens. `@ultimat3/core` declares the
 // series and renders the body; this is the one place a process answers `METRICS_PATH` with it, so
-// `docker/helm`'s HPAs read a number instead of `<unknown>`.
+// `docker/helm`'s HPAs read a number instead of `<unknown>`. Opening it starts the process's own
+// series (`process_*`): a role that can be scraped reports what it costs.
 
 import {
   finiteCount,
+  type HealthPayload,
+  healthzPayload,
   logger,
   METRICS_CONTENT_TYPE,
   METRICS_PATH,
   markListening,
   metricsText,
+  readyzPayload,
+  startProcessMetrics,
   stringField,
   UltimateError,
 } from '@ultimat3/core';
@@ -64,6 +69,55 @@ export interface MetricsEndpointOptions {
   readonly port?: number;
   /** A container must bind every interface; a laptop must not. Same decision as the web role. */
   readonly hostname?: string;
+  /**
+   * The `process_info{role}` label: `ROLE` in a container, the roles `x dev` runs joined by `+`.
+   * A host that opens the listener itself and names none is labelled `unknown`.
+   */
+  readonly role?: string;
+  /**
+   * What a taken port means. `refuse` (the default, and every container's): `X_PORT_IN_USE` —
+   * Prometheus is configured against the declared port, so listening anywhere else is a scrape
+   * that silently finds nothing. `free`: bind whichever port the kernel hands out and say which —
+   * `x dev` with no `METRICS_PORT`, where two apps on one laptop both default to 9090.
+   */
+  readonly whenTaken?: 'refuse' | 'free';
+}
+
+/**
+ * Which answer a boot gives. A laptop that named no port takes a free one when 9090 is another
+ * app's; a declared `METRICS_PORT` — and every container — is the port a scraper was told, so it
+ * refuses rather than listen where nothing will look.
+ */
+export const whenMetricsPortTaken = (
+  dev: boolean,
+  env: Readonly<Record<string, string | undefined>>,
+): 'refuse' | 'free' => {
+  const declared = env['METRICS_PORT'];
+  return dev && (declared === undefined || declared.trim().length === 0) ? 'free' : 'refuse';
+};
+
+/**
+ * The bind and its one retry. `bind` is `Bun.serve` behind a seam: whether a kernel refuses a
+ * second bind is the OS's answer, and the rule here is testable without racing a socket for it.
+ * Port 0 is never retried — the kernel chose it, so a refusal there is not a collision.
+ */
+export function bindScrapePort<T>(
+  port: number,
+  whenTaken: 'refuse' | 'free',
+  bind: (port: number) => T,
+): T {
+  try {
+    return bind(port);
+  } catch (error) {
+    if (!isAddressInUse(error)) throw error;
+    if (whenTaken === 'refuse' || port === 0) throw new MetricsPortInUseError({ port });
+    logger.warn('ultimate metrics port taken', {
+      port,
+      cause: `the metrics port ${String(port)} is already bound — another x dev, or a Prometheus — so this process listens on a free one`,
+      fix: `METRICS_PORT=${String(neighbouringPort(port))} x dev --json`,
+    });
+    return bind(0);
+  }
 }
 
 export interface MetricsEndpoint {
@@ -72,6 +126,18 @@ export interface MetricsEndpoint {
   stop(): void;
 }
 
+/**
+ * `/healthz` and `/readyz` for the roles whose only socket this is — `worker`, `scheduler`,
+ * `replicator` — so the replicator's readiness check (`role-replicator.ts`) is read by a probe.
+ * The verdict only, never the report: this port is unauthenticated, and check names are topology.
+ */
+function healthResponse(payload: HealthPayload, role: string): Response {
+  return Response.json(
+    { state: payload.body.state, ready: payload.body.ready, role },
+    { status: payload.status, headers: { 'cache-control': 'no-store' } },
+  );
+}
+
 /**
  * Answers outside the request pipeline, exactly as `/healthz` and `/readyz` do in
  * `@ultimat3/http`'s `server.ts`: no auth, no rate limit, no locale negotiation. A saturated or
@@ -86,29 +152,33 @@ export function startMetricsEndpoint(options: MetricsEndpointOptions = {}): Metr
   const port = finiteCount('startMetricsEndpoint', 'port', options.port ?? DEFAULT_METRICS_PORT);
   // `startRoles` opens this FIRST, before any role, so `Bun.serve`'s own bare `Error` was what a
   // second `x dev` on one machine reported: no code, no fix, at the boot path this package owns.
-  // The return type is inferred, keeping `Bun.serve`'s own shape stated once.
-  function listen() {
-    try {
-      return Bun.serve({
-        port,
-        hostname: options.hostname ?? 'localhost',
-        fetch(request: Request): Response {
-          if (new URL(request.url).pathname !== METRICS_PATH) {
-            return new Response('not found', { status: 404 });
-          }
-          // `collectMetrics()` is cumulative and never reset by a read, so two scrapers cannot
-          // steal each other's samples — but a cache would hand the second one a stale window.
-          return new Response(metricsText(), {
-            headers: { 'content-type': METRICS_CONTENT_TYPE, 'cache-control': 'no-store' },
-          });
-        },
-      });
-    } catch (error) {
-      if (!isAddressInUse(error)) throw error;
-      throw new MetricsPortInUseError({ port });
-    }
-  }
-  const server = listen();
+  const server = bindScrapePort(port, options.whenTaken ?? 'refuse', (candidate) =>
+    Bun.serve({
+      port: candidate,
+      hostname: options.hostname ?? 'localhost',
+      fetch(request: Request): Response {
+        const url = new URL(request.url);
+        const role = options.role ?? 'unknown';
+        if (url.pathname === '/healthz') return healthResponse(healthzPayload(), role);
+        if (url.pathname === '/readyz') {
+          return healthResponse(
+            readyzPayload({ deep: url.searchParams.get('deep') === '1' }),
+            role,
+          );
+        }
+        if (url.pathname !== METRICS_PATH) {
+          return new Response('not found', { status: 404 });
+        }
+        // `collectMetrics()` is cumulative and never reset by a read, so two scrapers cannot
+        // steal each other's samples — but a cache would hand the second one a stale window.
+        return new Response(metricsText(), {
+          headers: { 'content-type': METRICS_CONTENT_TYPE, 'cache-control': 'no-store' },
+        });
+      },
+    }),
+  );
+  // After the bind: a port that was taken starts no sampler nobody would stop.
+  const stopProcessMetrics = startProcessMetrics({ role: options.role ?? 'unknown' });
   // Same rule as every other socket the framework opens: announce it, so a request back to it is
   // recognisably this process calling itself rather than egress the test seal must refuse.
   const stopListening = markListening(server.url.origin);
@@ -118,6 +188,7 @@ export function startMetricsEndpoint(options: MetricsEndpointOptions = {}): Metr
     stop(): void {
       server.stop(true);
       stopListening();
+      stopProcessMetrics();
     },
   };
 }

package/src/migration-extensions.ts

@@ -0,0 +1,29 @@
+// Which Postgres extensions an app's migrations create. One reader for the two embedded boots
+// that must agree — `x dev`'s database (`runtime-queue.ts`) and the schema dump's scratch replay
+// (`db-schema-dump.ts`): PGlite links an extension only when it is named at boot, and an app that
+// replays in the gate and fails in `x dev` was the result of only one of them asking.
+
+import type { Migration } from '@ultimat3/db';
+import { readMigrations } from './migrations';
+
+const CREATE_EXTENSION = /\bcreate\s+extension\s+(?:if\s+not\s+exists\s+)?"?([a-z][a-z0-9_-]*)"?/gi;
+
+/**
+ * Every extension the migrations create, sorted. Matched on the raw text, comments included, on
+ * purpose: over-reading costs one bundle that is never created, and a name nothing ships is
+ * refused later by `create extension` itself. Blanking quoted identifiers first would lose
+ * `"uuid-ossp"`, the one spelling that needs its quotes.
+ */
+export function migrationExtensions(migrations: readonly Migration[]): readonly string[] {
+  const names = new Set<string>();
+  for (const migration of migrations) {
+    for (const match of migration.up.matchAll(CREATE_EXTENSION)) {
+      if (match[1] !== undefined) names.add(match[1].toLowerCase());
+    }
+  }
+  return [...names].sort();
+}
+
+/** The same list for an app on disk — what an embedded boot hands `createPgliteClient`. */
+export const appExtensions = async (root: string): Promise<readonly string[]> =>
+  migrationExtensions(await readMigrations(root));

package/src/module-imports.ts

@@ -0,0 +1,47 @@
+// The files one module's source imports, resolved the way Bun will resolve them. One function for
+// the two graphs built over it: the reload graph (`app-reload-graph.ts`), which follows every file
+// a module NAMES, and the document graph (`document-graph.ts`), which follows only what
+// EVALUATING the module evaluates. Each caller keeps its own rule for which targets it walks.
+
+// why: Bun ships no path API; an import specifier resolves against the importing file's directory.
+import { dirname } from 'node:path';
+
+/**
+ * `referenced`: every file the module names, an `await import()` target included — a save to one
+ * must reload its importer. `evaluated`: what importing the module evaluates, so the lazy targets
+ * are left out. Each keeps the transpiler pass its graph was built on (`scanImports`, the fast
+ * one, and `scan`); measured on Bun 1.4.0 the two agree on every static shape — both drop
+ * `import type` and an inline `type` specifier, both keep a value import used only as a type.
+ */
+export type ImportEdges = 'referenced' | 'evaluated';
+
+const transpilers = {
+  ts: new Bun.Transpiler({ loader: 'ts' }),
+  tsx: new Bun.Transpiler({ loader: 'tsx' }),
+};
+
+/**
+ * Absolute paths, in source order. A file that will not parse imports nothing yet, and a
+ * specifier that will not resolve contributes no edge: the module's own import reports both.
+ */
+export function resolvedImports(path: string, source: string, edges: ImportEdges): string[] {
+  const transpiler = path.endsWith('x') ? transpilers.tsx : transpilers.ts;
+  let specifiers: readonly { readonly path: string; readonly kind: string }[];
+  try {
+    specifiers =
+      edges === 'referenced'
+        ? transpiler.scanImports(source)
+        : transpiler.scan(source).imports.filter((one) => one.kind !== 'dynamic-import');
+  } catch {
+    return [];
+  }
+  const found: string[] = [];
+  for (const { path: specifier } of specifiers) {
+    try {
+      found.push(Bun.resolveSync(specifier, dirname(path)));
+    } catch {
+      // Unresolvable: no edge.
+    }
+  }
+  return found;
+}