@ultimat3/cli 20.2.1 → 22.0.0

package/src/scaffold-fixture.ts

@@ -46,6 +46,16 @@ export async function list(limit = 50): Promise<readonly ShortLink[]> {
 }
 `;
 
+/**
+ * The `invoice` resource's own `entity.ts`, as `x g` would read it off disk after the resource
+ * below ran — the generators writing INTO that slice are handed it, because a slice with no entity
+ * now gets the neutral body and no invented table.
+ */
+export const INVOICE_ENTITY = String(
+  generate({ kind: 'entity', name: 'invoice' }).find((file) => file.path.endsWith('/entity.ts'))
+    ?.contents,
+);
+
 /**
  * One realistic invocation of every generator, on top of `x new --example`. Names differ from
  * their feature on purpose: `x g query invoice --feature invoice` would collide with the entity
@@ -59,19 +69,31 @@ export const FIXTURE_GENERATORS: readonly GenerateOptions[] = [
   { kind: 'resource', name: 'invoice', admin: true },
   { kind: 'entity', name: 'credit-note', feature: 'credit-note' },
   { kind: 'policy', name: 'credit-note', feature: 'credit-note' },
-  { kind: 'action', name: 'send-invoice', feature: 'invoice' },
-  { kind: 'mutator', name: 'rename-invoice', feature: 'invoice' },
+  { kind: 'action', name: 'send-invoice', feature: 'invoice', sliceEntity: INVOICE_ENTITY },
+  { kind: 'mutator', name: 'rename-invoice', feature: 'invoice', sliceEntity: INVOICE_ENTITY },
   // The other shape both templates have: a slice whose `errors.ts` is the author's and declares
   // no `InvoiceNotFoundError`. The resource's own `errors.ts` still lands in the sandbox (it does
   // declare one), which is the point — this compiles the file `x g action` writes when it must
   // not import that class, beside the one it writes when it may.
-  { kind: 'action', name: 'ping-invoice', feature: 'invoice', sliceErrors: HANDWRITTEN_ERRORS },
-  { kind: 'mutator', name: 'touch-invoice', feature: 'invoice', sliceErrors: HANDWRITTEN_ERRORS },
+  {
+    kind: 'action',
+    name: 'ping-invoice',
+    feature: 'invoice',
+    sliceErrors: HANDWRITTEN_ERRORS,
+    sliceEntity: INVOICE_ENTITY,
+  },
+  {
+    kind: 'mutator',
+    name: 'touch-invoice',
+    feature: 'invoice',
+    sliceErrors: HANDWRITTEN_ERRORS,
+    sliceEntity: INVOICE_ENTITY,
+  },
   { kind: 'query', name: 'invoice-search', feature: 'invoice' },
   { kind: 'query', name: 'invoice-feed', feature: 'invoice', live: true },
-  { kind: 'job', name: 'sweep-invoices', feature: 'invoice' },
+  { kind: 'job', name: 'sweep-invoices', feature: 'invoice', sliceEntity: INVOICE_ENTITY },
   { kind: 'backfill', name: 'reindex-invoices', feature: 'invoice' },
-  { kind: 'task', name: 'nightly-sweep', feature: 'invoice' },
+  { kind: 'task', name: 'nightly-sweep', feature: 'invoice', sliceEntity: INVOICE_ENTITY },
   // The other shape both templates have: a feature whose entity names no tenant column, so the
   // job/task must not assume one — compiled here beside the tenant-scoped pair above, exactly as
   // `ping-invoice`/`touch-invoice` compile the action's other shape beside `send-invoice`.

package/src/scaffold-typecheck.ts

@@ -146,11 +146,14 @@ const overlay = (root: string, app: string): string =>
       compilerOptions: {
         noEmit: true,
         paths: {
-          // The two subpath exports a generated app reaches for, spelled the way the packages'
-          // own `exports` maps spell them — the wildcard below would read `ui/icons/zap` as a
-          // package name. Longest prefix wins, so these are consulted first.
+          // The subpath exports a generated app reaches for, spelled the way the packages' own
+          // `exports` maps spell them — the wildcard below would read `ui/icons/zap` as a package
+          // name, and `cli/serve` as `packages/cli/serve`. Longest prefix wins, so these are
+          // consulted first. `@ultimat3/cli/serve` is what `x new`'s `apps/web/server.ts` imports.
           '@ultimat3/ui/icons/*': [`${root}/packages/ui/src/icons/glyphs/*`],
           '@ultimat3/render/server': [`${root}/packages/render/src/server`],
+          '@ultimat3/cli/serve': [`${root}/packages/cli/src/serve-entry`],
+          '@ultimat3/testing/test-types': [`${root}/packages/testing/src/test-types`],
           '@ultimat3/*': [`${root}/packages/*/src`],
           [`@${app}/web/*`]: ['./apps/web/*'],
           [`@${app}/admin/*`]: ['./apps/admin/*'],

package/src/schema-drift.ts

@@ -89,8 +89,14 @@ function repairFix(
  * never get what the app declares; `undeclared` means the database holds what nothing declares.
  * One "drift" verdict over both teaches a reader neither.
  */
+/** A table difference names the table once: `table "customers" on table "customers"` did not. */
+export const schemaDifferenceCause = (difference: SchemaDifference): string =>
+  difference.part === 'table'
+    ? `table "${difference.table}" ${difference.detail}`
+    : `${difference.part} "${difference.name}" on table "${difference.table}" ${difference.detail}`;
+
 function findingFor(difference: SchemaDifference, fix: string): Finding {
-  const cause = `${difference.part} "${difference.name}" on table "${difference.table}" ${difference.detail}`;
+  const cause = schemaDifferenceCause(difference);
   return difference.direction === 'unmigrated'
     ? { code: 'X_DB_SCHEMA_UNMIGRATED', cause, fix, docs: ERROR_DOCS_URL, at: MIGRATIONS_DIR }
     : { code: 'X_DB_SCHEMA_UNDECLARED', cause, fix, docs: ERROR_DOCS_URL, at: MIGRATIONS_DIR };

package/src/script-csp.ts

@@ -5,7 +5,7 @@
 // invisible in `x dev`, where the policy is report-only.
 
 import { cspHashSource } from '@ultimat3/http';
-import { HYDRATE_RUNTIME_BODIES } from '@ultimat3/render';
+import { HYDRATE_RUNTIME_BODIES, STREAM_REVEAL_BODIES } from '@ultimat3/render';
 
 /**
  * Hashes, never a nonce: a `render: 'static'` page is a file on disk, so no per-response value can
@@ -16,5 +16,8 @@ import { HYDRATE_RUNTIME_BODIES } from '@ultimat3/render';
  * which `theme-boot.ts` derives from the same string it inlines.
  */
 export function inlineScriptSources(extra: readonly string[] = []): readonly string[] {
-  return [...new Set([...HYDRATE_RUNTIME_BODIES.map(cspHashSource), ...extra])].sort();
+  // The stream reveal too: a `render: 'stream'` page swaps each Suspense boundary in with a
+  // constant inline `$X()` call, and unhashed it is blocked under the enforced policy.
+  const bodies = [...HYDRATE_RUNTIME_BODIES, ...STREAM_REVEAL_BODIES];
+  return [...new Set([...bodies.map(cspHashSource), ...extra])].sort();
 }

package/src/secrets-rotation.ts

@@ -0,0 +1,59 @@
+// A master-key rotation in an order a crash cannot turn into data loss. The new key is STAGED at
+// `<key>.next` (0600) before anything is sealed with it, the committed file is sealed second, and
+// the rename that makes the new key live is last. Interrupted anywhere, some key on disk opens the
+// committed file — and `recoverRotation`, which every `x secrets` command runs first, finishes or
+// abandons the move by asking the file which key it answers to.
+
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'; // why: the staged key is written and renamed synchronously at 0600, and Bun has no mode-setting write or rename.
+import type { MasterKeyRef, SecretValues } from '@ultimat3/core';
+import {
+  generateMasterKey,
+  isUltimateError,
+  masterKeyPath,
+  readSecretsFile,
+  SECRETS_KEY_MODE,
+  stagedMasterKeyPath,
+  writeSecretsFile,
+} from '@ultimat3/core';
+
+const fileKey = (root: string, hex: string): MasterKeyRef => ({
+  hex,
+  source: 'file',
+  at: masterKeyPath(root),
+});
+
+/** Stage, seal, then make live. Returns the key now in force. */
+export async function rotateMasterKey(root: string, values: SecretValues): Promise<MasterKeyRef> {
+  const staged = stagedMasterKeyPath(root);
+  const hex = generateMasterKey();
+  rmSync(staged, { force: true });
+  // `wx`: the mode applies only when a write CREATES the file, and a leftover could be 0644.
+  writeFileSync(staged, `${hex}\n`, { encoding: 'utf-8', mode: SECRETS_KEY_MODE, flag: 'wx' });
+  const next = fileKey(root, hex);
+  await writeSecretsFile(root, values, next);
+  renameSync(staged, masterKeyPath(root));
+  return next;
+}
+
+/**
+ * A staged key left by an interrupted rotation: whichever of the two keys opens the committed file
+ * is the live one. The staged key wins only by opening it, and is then moved into place; otherwise
+ * it never sealed anything and is dropped. With no staged key this is `key`, unchanged.
+ */
+export async function recoverRotation(root: string, key: MasterKeyRef): Promise<MasterKeyRef> {
+  const staged = stagedMasterKeyPath(root);
+  if (!existsSync(staged)) return key;
+  try {
+    await readSecretsFile(root, key);
+    rmSync(staged, { force: true });
+    return key;
+  } catch (error) {
+    if (!isUltimateError(error) || error.code !== 'X_SECRETS_KEY_MISMATCH') throw error;
+    const candidate = fileKey(root, readFileSync(staged, 'utf-8').trim());
+    // Throws the staged key's own mismatch when neither opens it — the committed file's problem,
+    // which `X_SECRETS_KEY_MISMATCH`'s fix (restore it from git) answers.
+    await readSecretsFile(root, candidate);
+    renameSync(staged, masterKeyPath(root));
+    return candidate;
+  }
+}

package/src/serve-boot.ts

@@ -0,0 +1,192 @@
+// The web and background roles' boot, after the services are up: the app loaded, its route table
+// built, the roles started. Split from `serve.ts` (the entry points) at its line ceiling; the rules
+// that file's header states — the SAME boot `x dev` runs, minus the watcher, `/_x` and `dev: true`
+// — are this file's.
+
+import type { Role } from '@ultimat3/core';
+import type { Route } from '@ultimat3/http';
+import { describeRoutes } from '@ultimat3/render';
+import { createIsrController } from '@ultimat3/render/server';
+import { apiRoutes } from './api-routes';
+import { loadSignInPath } from './app-auth';
+import { loadApp } from './app-load';
+import { appManifest } from './app-manifest';
+import { mountAppMcp } from './app-mcp';
+import { errorPageStyleSources } from './error-page-csp';
+import { islandRoutes } from './island-routes';
+import { loadOrBuildIslands } from './island-store';
+import type { MetricsEndpoint } from './metrics-endpoint';
+import { startOtlpExport } from './otlp-export';
+import { pageSync } from './page-sync';
+import { loadPwaArtifacts } from './pwa-artifacts';
+import { startRoles } from './role-start';
+import { assetRoutes } from './runtime-assets';
+import { appRoutes } from './runtime-render';
+import { replicaOverrides } from './runtime-replica';
+import type { RunningServices } from './runtime-services';
+import { storageRoutes } from './runtime-storage';
+import { loadDrainConfig } from './serve-drain';
+import { configureReporting, containerBinding, metricsPortFor, portFromEnv } from './serve-env';
+import type { ServedApp, ServeOptions } from './serve-types';
+import { styleBundle } from './style-bundle';
+import { styleRoutes } from './style-routes';
+import { serviceWorkerArtifacts } from './sw-artifacts';
+import { serviceWorkerRoutes } from './sw-routes';
+import { loadThemeMode, themeBoot } from './theme-boot';
+
+/** The half of `serveApp` whose every acquisition is registered for rollback. */
+export async function bootRoles(boot: {
+  readonly options: ServeOptions;
+  readonly role: Role;
+  readonly runtime: RunningServices;
+  readonly acquired: (() => void | Promise<void>)[];
+  /** The scrape listener `serveApp` opened before any of this work; `startRoles` adopts it. */
+  readonly metrics: MetricsEndpoint;
+}): Promise<ServedApp> {
+  const { options, role, runtime, acquired, metrics } = boot;
+  // Importing the app's modules IS the registration: every route, action and job below is
+  // whatever this call put in the registries.
+  await loadApp(options.root);
+  // The build stamps `BUILD_ID` into the image; unstamped, the manifest's content hash is the same
+  // answer computed here, so `x-ultimate-build` is never absent and never a lie. Projected only
+  // when unstamped, because a stamped image already paid for it at build time and a replica's boot
+  // should not repeat it — the load above is the part every boot needs either way.
+  const stamped = options.env['BUILD_ID'];
+  const buildId =
+    stamped !== undefined && stamped.length > 0
+      ? stamped
+      : (await appManifest(options.root)).manifest.buildId;
+  // Before the first socket opens: everything above this line fails loudly into the container's
+  // own logs, everything below it is a served request, a claimed job or a routed frame.
+  configureReporting(options.env, buildId);
+  // Beside error reporting, and for the same reason it is here: `OTEL_EXPORTER_OTLP_ENDPOINT` is
+  // in the shipped chart and nothing read it, so every deployment that configured a collector got
+  // an empty dashboard. `x dev` keeps its own recorder — the `/_x` timeline is a different sink
+  // with a different lifetime — so this is the production boot's alone (axiom 6).
+  const stopOtlp = startOtlpExport(options.env);
+  acquired.push(stopOtlp);
+  // Only the web role serves pages, so only it builds islands and assembles a route table: a
+  // worker, scheduler, sync or replicator pod compiled every island of the app on every boot for
+  // nothing it would ever serve (plan 101, slice 12 e).
+  const web = role === 'web' ? await webSurface(options, runtime, buildId) : undefined;
+  const port = options.port ?? portFromEnv(options.env);
+  // An in-process caller asking for an ephemeral app port is a test, and a test that grabbed the
+  // fixed 9090 would fail the next suite to boot beside it. An environment that names the port
+  // still wins — that is the deploy talking.
+  const metricsPort = metricsPortFor(options.env, port, options.metricsPort);
+  const drain = await loadDrainConfig(options.root);
+  const replicaOverride = replicaOverrides(options.runtime, runtime.services.db, options.env);
+  const running = await startRoles({
+    roles: [role],
+    port,
+    metricsPort,
+    metrics,
+    buildId,
+    runtime,
+    routes: web?.routes ?? [],
+    env: options.env,
+    // Same declaration `x dev` reads. Without it a container answers a browser that opened a
+    // guarded page with the problem document, rendered as raw JSON in the viewport.
+    signInPath: await loadSignInPath(options.root),
+    // The enforced policy this process sends must admit the app's own error pages' `<style>` and
+    // the theme boot the documents carry; `x dev` is report-only, so only here was it a blank page.
+    inlineStyles: web === undefined ? [] : await errorPageStyleSources(options.root),
+    inlineScripts: web === undefined ? [] : [web.themeCsp],
+    // The app's own `apps/web/site/errors/<status>.html`, resolved inside `startWeb` so this
+    // process and `x dev` cannot answer a browser differently.
+    root: options.root,
+    http: containerBinding(options.env, options.hostname),
+    // `app.config.ts`'s drain section: the readiness grace the chart's grace period is sized for.
+    ...(drain === undefined ? {} : { drain }),
+    // The read-replica scope rides in FRONT of whatever the host supplied, or the host's own value
+    // passes through untouched. `DATABASE_REPLICA_URL` was read by no booted process before this:
+    // `defaultClient()` is the one composer of a replicated pair and it runs only when an app
+    // installed no client, which no framework boot leaves true (`runtime-queue.ts`).
+    ...(replicaOverride === undefined ? {} : { overrides: replicaOverride }),
+  });
+  acquired.push(() => running.stop());
+  return {
+    kind: 'served',
+    role,
+    url: running.url,
+    buildId,
+    running,
+    runtime,
+    async stop() {
+      await running.stop();
+      await runtime.stop();
+      // Last: the exporters outlive the roles they were recording, so the drain's own spans and
+      // the final counter snapshot still have somewhere to go.
+      stopOtlp();
+    },
+  };
+}
+
+/** What only the web role serves: its islands, its documents and every route beside them. */
+async function webSurface(
+  options: ServeOptions,
+  runtime: RunningServices,
+  buildId: string,
+): Promise<{ readonly routes: readonly Route[]; readonly themeCsp: string }> {
+  // Read from the store `x build --target docker` wrote and VERIFIED against this app and this
+  // runtime (`island-store.ts`); built here only when there is no store to trust, which is correct
+  // and slower, and logged with its reason.
+  const islands = await loadOrBuildIslands(options.root);
+  // The same two strings `x dev` resolves, from the same reader: a `<link rel="manifest">` served
+  // on a laptop and absent in the image is exactly the dev/prod difference this file exists to
+  // prevent, and it is the one an operator cannot see without installing the app.
+  const pwa = await loadPwaArtifacts(options.root);
+  const theme = themeBoot(await loadThemeMode(options.root));
+  // The page's sync target and its scripts — the same call `x dev` makes, so the two cannot differ.
+  // Before the service worker, which precaches those scripts.
+  const sync = await pageSync(options.root, options.env, buildId);
+  // The worker, from the SAME route table this process is about to serve — `describeRoutes()` is
+  // the one projection `x.manifest.json`, `/_x`, the sitemap and `sw.js` are all built from, so a
+  // route added here cannot be missing from the precache manifest.
+  const serviceWorker =
+    pwa === undefined
+      ? undefined
+      : serviceWorkerArtifacts({
+          pwa,
+          buildId,
+          routes: describeRoutes(),
+          islands,
+          styles: styleBundle(),
+          scripts: sync.scripts,
+        });
+  // The app's own MCP endpoint, through the same call `x dev` makes — see `app-mcp.ts`.
+  const mcpMount = await mountAppMcp(options.root);
+  const routes: readonly Route[] = [
+    ...apiRoutes(),
+    ...mcpMount.routes,
+    ...(serviceWorker === undefined ? [] : serviceWorkerRoutes(serviceWorker)),
+    ...assetRoutes({
+      root: options.root,
+      storage: runtime.storage,
+      ...(options.runtime?.images === undefined ? {} : { images: options.runtime.images }),
+      ...(pwa === undefined ? {} : { pwa }),
+    }),
+    ...storageRoutes({ storage: runtime.storage }),
+    ...islandRoutes(() => islands),
+    // The surface stylesheets the documents link. Built from the registry the `loadApp` above
+    // filled, so this process serves exactly the CSS it renders against.
+    ...styleRoutes(() => styleBundle()),
+    // The page's one socket: its worker script, served beside the islands for their reason.
+    ...sync.routes,
+    ...appRoutes({
+      buildId,
+      resolveIsland: (file) => islands.resolverFor(file),
+      sync: sync.head,
+      persisted: sync.persisted,
+      themeHead: theme.head,
+      ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
+      // Only when a store was supplied. `createIsrController` defaults to a per-process memory
+      // store, so twelve replicas hold twelve of them and a purge tag regenerates one twelfth of
+      // the fleet while the other eleven keep serving the page it just invalidated.
+      ...(options.runtime?.isrStore === undefined
+        ? {}
+        : { isr: createIsrController({ buildId, store: options.runtime.isrStore }) }),
+    }),
+  ];
+  return { routes, themeCsp: theme.cspSource };
+}

package/src/serve-drain.ts

@@ -0,0 +1,24 @@
+// `app.config.ts`'s `drain` section, read for the production boot — the same import every other
+// config reader here makes (`theme-boot.ts`, `app-auth.ts`), because the config is a module.
+
+import type { DrainConfig } from '@ultimat3/core';
+import { APP_CONFIG_EXPORT } from './app-auth';
+import { APP_CONFIG_FILE } from './app-root';
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * The declared section, or `undefined` when the app has none (a config not built by
+ * `defineConfig`, or no config file): `@ultimat3/http` then keeps core's own default. A value that
+ * is not a number is left for core to refuse, where the rule lives, rather than dropped here.
+ */
+export async function loadDrainConfig(root: string): Promise<Partial<DrainConfig> | undefined> {
+  const path = `${root}/${APP_CONFIG_FILE}`;
+  if (!(await Bun.file(path).exists())) return undefined;
+  const module = (await import(path)) as Record<string, unknown>;
+  const config = module[APP_CONFIG_EXPORT];
+  const drain = isRecord(config) ? config['drain'] : undefined;
+  if (!isRecord(drain) || !Object.hasOwn(drain, 'readinessGraceMs')) return undefined;
+  return { readinessGraceMs: drain['readinessGraceMs'] as number };
+}

package/src/serve-entry.ts

@@ -0,0 +1,6 @@
+// `@ultimat3/cli/serve`: what a container's `apps/web/server.ts` imports, and nothing else. The
+// `@ultimat3/cli` barrel is 1,349 modules — every command, every template, the e2e driver — and a
+// production process that booted through it loaded all of them to call one function.
+
+export { runRole } from './serve';
+export type { MigratedApp, ServedApp, ServeOptions, StartedApp } from './serve-types';

package/src/serve-env.ts

@@ -0,0 +1,116 @@
+// What a container's environment decides about a boot: which role, which port, which interface,
+// and where errors are reported. Split from `serve.ts`, which re-exports every name here.
+
+import type { Role } from '@ultimat3/core';
+import { configureErrorReporting, isRole, ROLES, sentryErrorReporter } from '@ultimat3/core';
+import { PortInvalidError, RoleUnknownError } from './errors';
+import { DEFAULT_METRICS_PORT } from './metrics-endpoint';
+import type { WebBinding } from './role-start';
+import type { Env } from './runtime-bindings';
+
+export const DEFAULT_PORT = 3000;
+
+/**
+ * Every interface, which is what a role binds when nothing says otherwise: a container bound to
+ * loopback is unreachable through its own port mapping. `HOST` and `ServeOptions.hostname` are the
+ * two ways of saying otherwise — see `hostnameFromEnv`.
+ */
+export const CONTAINER_BINDING: WebBinding = { dev: false, hostname: '0.0.0.0' };
+
+/**
+ * The interface the `web` and `sync` roles bind, and the metrics endpoint with them (`WebBinding`
+ * is one decision). Read the way `PORT` is: empty or whitespace is the default.
+ *
+ * Exists because a container had exactly one binding, `0.0.0.0`, and an app whose auth mode is
+ * "nobody logs in, one implicit actor" must refuse a public interface — so it could not run in a
+ * container at all. `HOST=127.0.0.1` is unreachable through `docker run -p` (the proxy connects to
+ * the container's bridge address, never its loopback); it is reachable where the container shares
+ * the host's network namespace (`--network host`), or through a sidecar and `ssh -L` inside it —
+ * which is the exposure such an app wants. Not `HOSTNAME`: Docker sets that to the container id.
+ */
+export function hostnameFromEnv(env: Env): string {
+  const raw = env['HOST']?.trim();
+  return raw === undefined || raw.length === 0 ? CONTAINER_BINDING.hostname : raw;
+}
+
+/** What `serveApp` hands `startRoles`: the caller's hostname, else `HOST`, else every interface. */
+export const containerBinding = (env: Env, hostname?: string): WebBinding => ({
+  dev: false,
+  hostname: hostname ?? hostnameFromEnv(env),
+});
+
+/**
+ * `ROLE` is the one knob one image exposes. Validated rather than defaulted: a typo that fell back
+ * to `web` would start a process that serves nothing the operator asked for and reports healthy.
+ */
+export function roleFromEnv(env: Env): Role {
+  const raw = env['ROLE'] ?? 'web';
+  if (!isRole(raw)) throw new RoleUnknownError({ role: raw, known: ROLES });
+  return raw;
+}
+
+/**
+ * `Number.parseInt` would read `80abc` as 80, so the whole string has to be a port — a
+ * partially-parsed port is a deploy that binds somewhere nobody asked for.
+ */
+function portValue(env: Env, name: string, fallback: number): number {
+  const raw = env[name];
+  if (raw === undefined || raw.trim().length === 0) return fallback;
+  const port = Number(raw.trim());
+  if (!Number.isInteger(port) || port < 0 || port > 65_535)
+    throw new PortInvalidError({ value: raw, name });
+  return port;
+}
+
+/** Every PaaS injects `PORT` and routes traffic to exactly it. */
+export function portFromEnv(env: Env): number {
+  return portValue(env, 'PORT', DEFAULT_PORT);
+}
+
+/**
+ * The scrape port, deliberately its own env var and not `PORT + n`: an operator who moves the app
+ * port must not silently move the port their Prometheus is configured against, and the roles that
+ * set no `PORT` at all — `worker`, `scheduler`, `replicator` — still need this one.
+ */
+export function metricsPortFromEnv(env: Env): number {
+  return portValue(env, 'METRICS_PORT', DEFAULT_METRICS_PORT);
+}
+
+/**
+ * The scrape port a boot uses, given the app port it already resolved. One expression, and it is
+ * exported because `x dev` is the second caller: `cmd-dev.ts` passed no `metricsPort` at all, so
+ * `METRICS_PORT` was honoured in the container and ignored on a laptop — the dev/prod parity break
+ * `role-start.ts`'s own header forbids, and a second copy of this rule would be the same break
+ * one edit later.
+ *
+ * An in-process caller asking for an ephemeral app port is a test, and a test that grabbed the
+ * fixed 9090 would fail the next suite to boot beside it. An environment that names the port still
+ * wins — that is the deploy talking.
+ */
+export const metricsPortFor = (env: Env, port: number, override?: number): number =>
+  override ?? (port === 0 && env['METRICS_PORT'] === undefined ? 0 : metricsPortFromEnv(env));
+
+/**
+ * The one env var that turns error monitoring on, and the only vendor-shaped name in the boot
+ * path. Not a platform primitive (axiom 7): the value is a URL to whatever the operator runs, the
+ * wire format behind it is documented and self-hostable, and `SENTRY_DSN` is what every monitor
+ * that speaks it already documents — inventing a second spelling would mean an operator's existing
+ * tooling sets a variable this framework ignores. Exactly the precedent
+ * `OTEL_EXPORTER_OTLP_ENDPOINT` already sets in `docker/helm/values.yaml`.
+ */
+export const ERROR_DSN_KEY = 'SENTRY_DSN';
+
+/**
+ * Switch reporting on for this process. Unset DSN leaves core's no-op reporter in place, so a
+ * laptop and a CI run pay nothing and page nobody — and the release every event carries is the
+ * build id this boot already computed, never a second identity for the same deploy.
+ */
+export function configureReporting(env: Env, buildId: string): void {
+  const dsn = env[ERROR_DSN_KEY]?.trim();
+  configureErrorReporting({
+    release: buildId,
+    // A malformed DSN throws here, at boot, rather than at the first outage: a monitor that was
+    // never connected looks exactly like an app that never failed.
+    ...(dsn === undefined || dsn.length === 0 ? {} : { reporter: sentryErrorReporter({ dsn }) }),
+  });
+}

package/src/serve-types.ts

@@ -0,0 +1,55 @@
+// The shapes a production boot takes and answers. Split from `serve.ts`, which re-exports them.
+
+import type { Role } from '@ultimat3/core';
+import type { DriftReport, MigrationReport } from '@ultimat3/db';
+import type { RunningRoles } from './role-start';
+import type { Env } from './runtime-bindings';
+import type { RuntimeOverrides } from './runtime-overrides';
+import type { RunningServices } from './runtime-services';
+
+export interface ServeOptions {
+  readonly root: string;
+  readonly env: Env;
+  /** Overrides `ROLE`; `runRole` reads the environment when this is absent. */
+  readonly role?: Role;
+  /** Overrides `PORT`. 0 asks the kernel for an ephemeral one, which is what a test wants. */
+  readonly port?: number;
+  /** Overrides `METRICS_PORT`, on the same terms. */
+  readonly metricsPort?: number;
+  /**
+   * Overrides `HOST`: the interface the HTTP roles bind. An app that must never answer on a public
+   * interface passes `'127.0.0.1'` here rather than trusting the deployment to set the variable.
+   */
+  readonly hostname?: string;
+  /**
+   * The drivers this deployment supplies instead of the ones the environment would select.
+   *
+   * This field is why `apps/web/server.ts` can stay three lines and still run a custom queue, a
+   * shared ISR store or an app's own middleware. Before it there was nowhere to hand the framework
+   * a driver, so the only way was an ambient setter from an app module — which `loadApp` imports
+   * AFTER `startServices` has captured its own, giving a process that enqueues to one queue and
+   * claims from another. `startRoles` now refuses that split outright.
+   */
+  readonly runtime?: RuntimeOverrides;
+}
+
+export interface ServedApp {
+  readonly kind: 'served';
+  readonly role: Role;
+  /** `http://…` for the web role; null for the roles that open no HTTP socket. */
+  readonly url: string | null;
+  readonly buildId: string;
+  readonly running: RunningRoles;
+  readonly runtime: RunningServices;
+  stop(): Promise<void>;
+}
+
+export interface MigratedApp {
+  readonly kind: 'migrated';
+  readonly role: 'migrate';
+  readonly report: MigrationReport;
+  /** The post-condition: the live schema against the ledger this run just wrote. */
+  readonly drift: DriftReport;
+}
+
+export type StartedApp = ServedApp | MigratedApp;