@ultimat3/cli 1.0.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -34,27 +34,27 @@
     "dev": "bun run src/bin.ts dev"
   },
   "dependencies": {
-    "@ultimat3/action": "1.0.0",
-    "@ultimat3/admin": "1.0.0",
-    "@ultimat3/ai": "1.0.0",
-    "@ultimat3/cache": "1.0.0",
-    "@ultimat3/core": "1.0.0",
-    "@ultimat3/db": "1.0.0",
-    "@ultimat3/entity": "1.0.0",
-    "@ultimat3/http": "1.0.0",
-    "@ultimat3/i18n": "1.0.0",
-    "@ultimat3/jobs": "1.0.0",
-    "@ultimat3/mail": "1.0.0",
-    "@ultimat3/manifest": "1.0.0",
-    "@ultimat3/mcp": "1.0.0",
-    "@ultimat3/policy": "1.0.0",
-    "@ultimat3/pwa": "1.0.0",
-    "@ultimat3/query": "1.0.0",
-    "@ultimat3/realtime": "1.0.0",
-    "@ultimat3/render": "1.0.0",
-    "@ultimat3/seo": "1.0.0",
-    "@ultimat3/storage": "1.0.0",
-    "@ultimat3/testing": "1.0.0",
-    "@ultimat3/time": "1.0.0"
+    "@ultimat3/action": "1.2.0",
+    "@ultimat3/admin": "1.2.0",
+    "@ultimat3/ai": "1.2.0",
+    "@ultimat3/cache": "1.2.0",
+    "@ultimat3/core": "1.2.0",
+    "@ultimat3/db": "1.2.0",
+    "@ultimat3/entity": "1.2.0",
+    "@ultimat3/http": "1.2.0",
+    "@ultimat3/i18n": "1.2.0",
+    "@ultimat3/jobs": "1.2.0",
+    "@ultimat3/mail": "1.2.0",
+    "@ultimat3/manifest": "1.2.0",
+    "@ultimat3/mcp": "1.2.0",
+    "@ultimat3/policy": "1.2.0",
+    "@ultimat3/pwa": "1.2.0",
+    "@ultimat3/query": "1.2.0",
+    "@ultimat3/realtime": "1.2.0",
+    "@ultimat3/render": "1.2.0",
+    "@ultimat3/seo": "1.2.0",
+    "@ultimat3/storage": "1.2.0",
+    "@ultimat3/testing": "1.2.0",
+    "@ultimat3/time": "1.2.0"
   }
 }

package/src/app-load.ts

@@ -22,6 +22,15 @@ const APP_GLOBS = [
   'packages/*/src/**/*.ts',
 ] as const;
 
+/**
+ * The two files that are *entry points*, not app modules: `apps/web/server.ts` starts the process
+ * and `apps/web/prerender.ts` runs the build. Importing either registers nothing — and importing
+ * `server.ts` deadlocks, because that module's own top-level `await runRole()` is what called this
+ * scan, so the dynamic import waits on a module that is waiting on the import. Anchored to the
+ * surface root: `apps/web/app/server.ts` is app code and stays in the scan.
+ */
+const ENTRY_POINT = /^apps\/[^/]+\/(?:server|prerender)\.tsx?$/;
+
 export interface LoadedApp {
   readonly root: string;
   /** App-root-relative POSIX paths of every module that imported, sorted. */
@@ -64,6 +73,7 @@ export async function loadApp(root: string): Promise<LoadedApp> {
     for await (const absolute of new Bun.Glob(pattern).scan({ cwd: root, absolute: true })) {
       if (absolute.includes('node_modules') || absolute.includes('.test.')) continue;
       const file = relative(root, absolute).split(sep).join('/');
+      if (ENTRY_POINT.test(file)) continue;
       let module: Record<string, unknown>;
       try {
         module = (await import(absolute)) as Record<string, unknown>;

package/src/cmd-build.ts

@@ -1,11 +1,12 @@
 // `x build --target docker|binary|static` — three targets, no platform primitives. Deploy anywhere
 // means "anywhere that runs a container or a binary"; nothing here knows the name of a cloud.
 
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { requireAppRoot } from './app-root';
 import { runVerify } from './cmd-verify';
 import type { CliCommand, CommandContext } from './command';
-import { UnknownCommandError } from './errors';
+import { BuildEntryMissingError, UnknownCommandError } from './errors';
 import { execOutput } from './exec';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
@@ -26,9 +27,28 @@ export function readTarget(raw: string | undefined): BuildTarget {
   });
 }
 
+/**
+ * The one file each target builds from, app-root-relative and POSIX. One table, because `x build`
+ * has to refuse a missing entry by name before it spawns anything, and the spawned command has to
+ * name the same file — a second copy is how `binary` came to compile a path `x new` never wrote.
+ */
+export const BUILD_ENTRY: Readonly<Record<BuildTarget, string>> = {
+  docker: 'docker/Dockerfile',
+  binary: 'apps/web/server.ts',
+  static: 'apps/web/prerender.ts',
+};
+
+/** Absolute path of the target's entry, or the error that names the file and what writes it. */
+export function requireEntry(root: string, target: BuildTarget): string {
+  const entry = BUILD_ENTRY[target];
+  const absolute = join(root, entry);
+  if (!existsSync(absolute)) throw new BuildEntryMissingError({ target, entry });
+  return absolute;
+}
+
 /** One image for every role; ROLE selects behaviour at start, so there is one artifact to promote. */
 export function dockerArgs(root: string, tag: string): readonly string[] {
-  return ['docker', 'build', '-f', join(root, 'docker', 'Dockerfile'), '-t', tag, root];
+  return ['docker', 'build', '-f', join(root, BUILD_ENTRY.docker), '-t', tag, root];
 }
 
 export function binaryArgs(root: string, out: string): readonly string[] {
@@ -37,14 +57,14 @@ export function binaryArgs(root: string, out: string): readonly string[] {
     'build',
     '--compile',
     '--minify',
-    join(root, 'apps', 'web', 'server.ts'),
+    join(root, BUILD_ENTRY.binary),
     '--outfile',
     out,
   ];
 }
 
 export function staticArgs(root: string, out: string): readonly string[] {
-  return ['bun', 'run', join(root, 'apps', 'web', 'prerender.ts'), '--out', out];
+  return ['bun', 'run', join(root, BUILD_ENTRY.static), '--out', out];
 }
 
 export function argsFor(
@@ -71,6 +91,10 @@ export const buildCommand: CliCommand = {
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('build', ctx.cwd).dir;
     const target = readTarget(flagString(ctx.args, 'target'));
+    // Before the gate, not after: an entry the app does not have cannot be produced by a green
+    // typecheck, and eight seconds of `tsc` ahead of "that file does not exist" is eight seconds
+    // an agent spends on the wrong question.
+    requireEntry(root, target);
 
     // Run static verify steps before building.
     const staticSteps = ['typecheck', 'lint', 'boundaries', 'filesize', 'package-shape', 'errors'];

package/src/cmd-dev.ts

@@ -8,7 +8,7 @@ import { watch } from 'node:fs';
 import { join } from 'node:path';
 import { listActions, toRoute } from '@ultimat3/action';
 import type { Role } from '@ultimat3/core';
-import { configureTelemetry, noopExporter } from '@ultimat3/core';
+import { configureTelemetry, METRICS_PATH, noopExporter } from '@ultimat3/core';
 import type { Route } from '@ultimat3/http';
 import type { Manifest } from '@ultimat3/manifest';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
@@ -249,6 +249,9 @@ export const devCommand: CliCommand = {
         url: server.url,
         roles: [...server.roles],
         sync: server.running.syncUrl,
+        // The scrape target, on its own port for every role: what an operator points a Prometheus
+        // 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,

package/src/dev-render.ts

@@ -43,7 +43,11 @@ const headFor = async (entry: RouteEntry, data: DevRouteData): Promise<string> =
     headFromMeta(await entry.config.meta(data), seoRenderers({ path: new URL(data.url).pathname })),
   );
 
-async function documentFor(entry: RouteEntry, data: DevRouteData): Promise<string> {
+/**
+ * Head + shell for one route render. Exported because the build's prerenderer must emit the same
+ * document `x dev` serves — two document builders is how a page that works in dev ships broken.
+ */
+export async function routeDocument(entry: RouteEntry, data: DevRouteData): Promise<string> {
   return shellFor(await headFor(entry, data));
 }
 
@@ -63,11 +67,11 @@ async function resultFor(
     case 'static': {
       // Not `renderStatic`: that enumerates every prerendered path for the build. A request
       // names exactly one, and it earns the same content-hashed headers.
-      const body = await documentFor(entry, data);
+      const body = await routeDocument(entry, data);
       return { status: 200, headers: staticHeaders(contentHash(body), options.buildId), body };
     }
     case 'isr': {
-      const served = await isr.serve(url.pathname, () => documentFor(entry, data));
+      const served = await isr.serve(url.pathname, () => routeDocument(entry, data));
       return served.result;
     }
     case 'spa':
@@ -90,7 +94,7 @@ async function resultFor(
       );
     }
     default:
-      return renderSsr({ entry, params: data.params, url, ctx }, () => documentFor(entry, data), {
+      return renderSsr({ entry, params: data.params, url, ctx }, () => routeDocument(entry, data), {
         buildId: options.buildId,
       });
   }

package/src/dev-roles.ts

@@ -29,6 +29,7 @@ import { startReplicator } from './dev-replicator';
 import type { RunningServices } from './dev-runtime';
 import type { Env } from './dev-services';
 import { BadFlagError } from './errors';
+import { DEFAULT_METRICS_PORT, startMetricsEndpoint } from './metrics-endpoint';
 
 /** The roles `x dev` starts when `--role` names none, in boot order. */
 export const DEV_ROLES: readonly Role[] = ['web', 'sync', 'worker', 'scheduler'];
@@ -49,14 +50,38 @@ export interface StartRolesOptions {
   readonly routes: readonly Route[];
   /** The process environment, for the roles that resolve a driver from it. */
   readonly env: Env;
+  /**
+   * How the web role binds and what it admits about itself. `x dev` keeps the default —
+   * loopback, `dev: true`, so a laptop on a café network is not serving the app to the café. A
+   * container passes `{ dev: false, hostname: '0.0.0.0' }`: a process bound to `localhost` inside
+   * a container is unreachable from the port mapping, the load balancer and every PaaS health
+   * probe, which is the same failure in four costumes.
+   */
+  readonly http?: WebBinding;
+  /**
+   * Where the scrape listener binds. Defaults to `DEFAULT_METRICS_PORT`, except when `port` is 0
+   * — a caller asking the kernel for an ephemeral HTTP port is a test, and a test that grabbed
+   * 9090 would fail the next one to run beside it.
+   */
+  readonly metricsPort?: number;
 }
 
+export interface WebBinding {
+  readonly dev: boolean;
+  readonly hostname: string;
+}
+
+/** Loopback and dev-mode. What `x dev` means, and what a container must override. */
+export const DEV_BINDING: WebBinding = { dev: true, hostname: 'localhost' };
+
 export interface RunningRoles {
   readonly roles: readonly Role[];
   /** `http://…` once the web role is up; null when it was not selected. */
   readonly url: string | null;
   /** Where the sync role accepts websockets; null when it was not selected. */
   readonly syncUrl: string | null;
+  /** `http://…` — the scrape base. Never null: every role publishes a signal worth scaling on. */
+  readonly metricsUrl: string;
   readonly server: ServerHandle | null;
   readonly worker: Worker | null;
   readonly scheduler: Scheduler | null;
@@ -99,15 +124,16 @@ export function selectRoles(flag: string | undefined): readonly Role[] {
 }
 
 function startWeb(options: StartRolesOptions): ServerHandle {
+  const binding = options.http ?? DEV_BINDING;
   return createServer({
     routes: options.routes,
     role: 'web',
     hooks: devHooks(),
     config: defineHttpConfig({
       port: options.port,
-      dev: true,
+      dev: binding.dev,
       buildId: options.buildId,
-      hostname: 'localhost',
+      hostname: binding.hostname,
     }),
   }).start();
 }
@@ -186,6 +212,15 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
   // Without this a failed `sync` leaves the web server bound and unreachable by any caller.
   const started: (() => Promise<void>)[] = [];
   try {
+    // First, and for every role rather than only the two that open an HTTP socket: `worker` and
+    // `sync` are precisely the roles whose HPAs read a series the process itself has to publish,
+    // and a `worker` container with no listener is an HPA pinned at `<unknown>` forever.
+    const metrics = startMetricsEndpoint({
+      port: options.metricsPort ?? (options.port === 0 ? 0 : DEFAULT_METRICS_PORT),
+      ...(options.http === undefined ? {} : { hostname: options.http.hostname }),
+    });
+    started.push(async () => metrics.stop());
+
     const server = selected.includes('web') ? startWeb(options) : null;
     if (server !== null) started.push(() => server.stop());
 
@@ -223,6 +258,7 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
       roles: selected,
       url: server === null ? null : server.url(),
       syncUrl: sync?.url ?? null,
+      metricsUrl: metrics.url,
       server,
       worker,
       scheduler,
@@ -234,6 +270,8 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
         await worker?.stop('x dev stopped');
         await sync?.stop();
         await server?.stop();
+        // Last: a scrape taken while the roles above drain is the one that explains the drain.
+        metrics.stop();
       },
     };
   } catch (error) {

package/src/dev-services.ts

@@ -33,10 +33,15 @@ const nonEmpty = (value: string | undefined): string | undefined =>
  */
 export function resolveServices(root: string, env: Env): DevServices {
   const stateDir = join(root, '.x');
-  mkdirSync(stateDir, { recursive: true });
   const databaseUrl = nonEmpty(env['DATABASE_URL']);
   const natsUrl = nonEmpty(env['NATS_URL']);
   const s3Endpoint = nonEmpty(env['S3_ENDPOINT']);
+  // Created only when something will actually live in it. A container whose bindings are all
+  // external runs non-root over a read-only app directory, and an unconditional mkdir there is an
+  // EACCES at boot for a directory that would have stayed empty.
+  if (databaseUrl === undefined || natsUrl === undefined || s3Endpoint === undefined) {
+    mkdirSync(stateDir, { recursive: true });
+  }
   return {
     stateDir,
     db:

package/src/errors.ts

@@ -36,7 +36,14 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_MANIFEST_STALE',
   'X_BUDGET_UNMEASURED',
   'X_BUILD_FAILED',
+  'X_BUILD_ENTRY_MISSING',
   'X_DEPLOY_FAILED',
+  // The two the container's own environment can get wrong. A PaaS injects `PORT` and a supervisor
+  // injects `ROLE`; both arrive as strings from outside the app, so both are validated at boot
+  // rather than defaulted — a web role that quietly bound 3000 when the platform said 8080 fails
+  // its health check with nothing in the log that names the cause.
+  'X_ROLE_UNKNOWN',
+  'X_PORT_INVALID',
   'X_GENERATE_CONFLICT',
   'X_PORT_IN_USE',
   'X_DB_GEN_FAILED',
@@ -100,7 +107,10 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_MANIFEST_STALE: 'openapi.json is stale',
   X_BUDGET_UNMEASURED: 'a route declares a budget the build never measured',
   X_BUILD_FAILED: 'x build failed',
+  X_BUILD_ENTRY_MISSING: "the build target's entry file is not in the app",
   X_DEPLOY_FAILED: 'a deploy step failed',
+  X_ROLE_UNKNOWN: 'ROLE names something that is not a role',
+  X_PORT_INVALID: 'PORT is not a TCP port number',
   X_GENERATE_CONFLICT: 'a generator would overwrite a file',
   X_PORT_IN_USE: 'the dev port is taken',
   X_DB_GEN_FAILED: 'x db gen failed',
@@ -354,6 +364,55 @@ export class FixTargetUnknownError extends UltimateError {
   }
 }
 
+/**
+ * A build target names an entry file the app does not have. `x build` refuses before it spawns the
+ * builder: `bun build`'s own "module not found" says nothing about which file an Ultimate app is
+ * supposed to own, and `docker build`'s says nothing about which target wanted it.
+ */
+export class BuildEntryMissingError extends UltimateError {
+  constructor(input: { target: string; entry: string }) {
+    super({
+      code: 'X_BUILD_ENTRY_MISSING',
+      cause: `x build --target ${input.target} builds from ${input.entry}, and the app does not have it`,
+      fix: `x new <name> writes ${input.entry} — copy it from a fresh scaffold into this app`,
+      docs: docsFor('X_BUILD_ENTRY_MISSING'),
+    });
+  }
+}
+
+/**
+ * `ROLE` selects what a container is. One image runs every role, so a typo is a process that would
+ * otherwise start, serve nothing and report healthy — the one failure a rolling deploy cannot see.
+ */
+export class RoleUnknownError extends UltimateError {
+  constructor(input: { role: string; known: readonly string[] }) {
+    super({
+      code: 'X_ROLE_UNKNOWN',
+      cause: `ROLE="${input.role}" is not a role (known: ${input.known.join(', ')})`,
+      fix: `docker run -e ROLE=web <image>   # one of: ${input.known.join(', ')}`,
+      docs: docsFor('X_ROLE_UNKNOWN'),
+    });
+  }
+}
+
+/**
+ * Every PaaS injects `PORT` and expects the process to bind exactly it. Defaulting past a value
+ * that will not parse is how a deploy comes up on 3000, fails the platform's health probe, and
+ * reports nothing an operator can act on.
+ */
+export class PortInvalidError extends UltimateError {
+  /** `name` so the scrape port reports itself; the code stays one, because the fault is one. */
+  constructor(input: { value: string; name?: string }) {
+    const name = input.name ?? 'PORT';
+    super({
+      code: 'X_PORT_INVALID',
+      cause: `${name}="${input.value}" is not a TCP port number between 0 and 65535`,
+      fix: `docker run -e ${name}=${name === 'PORT' ? 3000 : 9090} <image>`,
+      docs: docsFor('X_PORT_INVALID'),
+    });
+  }
+}
+
 /** An interface-complete command path whose remote/native half is not written yet. */
 export class CliNotImplementedError extends UltimateError {
   constructor(input: { feature: string; fix: string }) {

package/src/index.ts

@@ -24,7 +24,14 @@ export { planBoundaryCuts } from './boundary-cuts';
 export type { BuildStats, RouteStats } from './budgets';
 export { BUILD_STATS_FILE, checkBudgets, readBuildStats } from './budgets';
 export type { BuildTarget } from './cmd-build';
-export { argsFor, BUILD_TARGETS, buildCommand, readTarget } from './cmd-build';
+export {
+  argsFor,
+  BUILD_ENTRY,
+  BUILD_TARGETS,
+  buildCommand,
+  readTarget,
+  requireEntry,
+} from './cmd-build';
 export { branchDatabaseName, branchSql, dbCommand, previewUrl } from './cmd-db';
 export type { DeployPlan } from './cmd-deploy';
 export { deployCommand, planDeploy } from './cmd-deploy';
@@ -64,9 +71,9 @@ export { devHooks } from './dev-hooks';
 export type { DevDbClient, RunningQueue } from './dev-queue';
 export { startQueue } from './dev-queue';
 export type { DevRenderOptions, DevRouteData } from './dev-render';
-export { appRoutes } from './dev-render';
-export type { RunningRoles, StartRolesOptions } from './dev-roles';
-export { DEV_ROLES, selectRoles, startRoles } from './dev-roles';
+export { appRoutes, routeDocument } from './dev-render';
+export type { RunningRoles, StartRolesOptions, WebBinding } from './dev-roles';
+export { DEV_BINDING, DEV_ROLES, selectRoles, startRoles } from './dev-roles';
 export type { RunningServices } from './dev-runtime';
 export { startServices } from './dev-runtime';
 export type { DevServices, ServiceBinding } from './dev-services';
@@ -98,6 +105,7 @@ export {
 export type { CliErrorCode } from './errors';
 export {
   BadFlagError,
+  BuildEntryMissingError,
   BunVersionError,
   CatalogExistsError,
   CLI_ERROR_CODES,
@@ -109,6 +117,8 @@ export {
   JobUnknownError,
   NoTestFilesError,
   NotInAppError,
+  PortInvalidError,
+  RoleUnknownError,
   UnknownCommandError,
   VerifyFailedError,
 } from './errors';
@@ -122,6 +132,9 @@ export { renderJobTable } from './jobs-table';
 export type { CliMcpServer, DevHostInput } from './mcp-host';
 export { createDevMcpServer, DEV_TOOL_SCOPES, localCaller } from './mcp-host';
 export { messageKeys, msg } from './messages';
+export type { MetricsEndpoint, MetricsEndpointOptions } from './metrics-endpoint';
+export { DEFAULT_METRICS_PORT, startMetricsEndpoint } from './metrics-endpoint';
+export { MIGRATIONS_DIR, migrationName, parseMigrationSql, readMigrations } from './migrations';
 export type { CommandResult, Finding, JsonValue, StepResult } from './output';
 export {
   exitCodeFor,
@@ -135,7 +148,20 @@ export {
 } from './output';
 export type { CommandSpec, FlagSpec, ParsedArgs } from './parse';
 export { flagBool, flagList, flagString, GLOBAL_FLAGS, nearest, parseArgs } from './parse';
+export type { PrerenderedPage, PrerenderOptions, PrerenderReport } from './prerender';
+export { DEFAULT_ORIGIN, isPrerenderable, prerenderSite } from './prerender';
 export { CLI_VERSION, COMMANDS, commandFor, SPECS } from './registry';
+export type { MigratedApp, ServedApp, ServeOptions, StartedApp } from './serve';
+export {
+  CONTAINER_BINDING,
+  DEFAULT_PORT,
+  metricsPortFromEnv,
+  portFromEnv,
+  roleFromEnv,
+  runMigrations,
+  runRole,
+  serveApp,
+} from './serve';
 export {
   eachSourceFile,
   isGenerated,

package/src/mcp-errors.ts

@@ -47,7 +47,13 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_MANIFEST_STALE: 'x manifest --json',
   X_BUDGET_UNMEASURED: 'x build --json && x verify --json',
   X_BUILD_FAILED: 'x build --json   # the finding names the failing step',
+  X_BUILD_ENTRY_MISSING:
+    'x new <name> --dry-run --json   # the file list names every entry a build needs',
   X_DEPLOY_FAILED: 'x deploy --json   # the finding carries the command to re-run directly',
+  // The container's own environment, so the answer is the run that sets it — never an `x` command,
+  // which is not what is running when a `ROLE=wroker` pod refuses to boot.
+  X_ROLE_UNKNOWN: 'docker run -e ROLE=web <image>',
+  X_PORT_INVALID: 'docker run -e PORT=3000 <image>',
   X_GENERATE_CONFLICT: 'x g <kind> <name> --force --json',
   X_PORT_IN_USE: 'x dev --port 3001 --json',
   // Not `x db status`: there is no such subcommand (`x db` is gen, migrate, reset, studio, branch),

package/src/metrics-endpoint.ts

@@ -0,0 +1,72 @@
+// 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>`.
+
+import {
+  logger,
+  METRICS_CONTENT_TYPE,
+  METRICS_PATH,
+  markListening,
+  metricsText,
+} from '@ultimat3/core';
+
+/**
+ * A port of its own, and NOT the role's HTTP port, for one reason the chart makes concrete:
+ * `docker/helm/templates/ingress.yaml` routes `path: /` `Prefix` to the web Service, so a
+ * `/metrics` mounted beside `/healthz` on port 3000 is `/metrics` on the internet — route
+ * patterns, request volumes and error rates, published. Nothing in the chart fronts this port:
+ * `service.yaml` only publishes `http`, so the endpoint is cluster-internal by construction
+ * rather than by an ingress exclusion somebody has to remember to write.
+ *
+ * It is also the only thing `worker`, `scheduler` and `replicator` could ever be scraped on —
+ * they open no HTTP socket at all, and `queue_depth` is exactly the signal one of them owns.
+ * 9090 is Prometheus's own convention, so a scrape config that assumes it needs no edit.
+ */
+export const DEFAULT_METRICS_PORT = 9090;
+
+export interface MetricsEndpointOptions {
+  /** 0 asks the kernel for an ephemeral port, which is what a test wants. */
+  readonly port?: number;
+  /** A container must bind every interface; a laptop must not. Same decision as the web role. */
+  readonly hostname?: string;
+}
+
+export interface MetricsEndpoint {
+  /** `http://host:port` — the base the scrape target appends `METRICS_PATH` to. */
+  readonly url: string;
+  stop(): void;
+}
+
+/**
+ * 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
+ * draining process must still be able to say how saturated it is — an autoscaler that loses its
+ * signal at the moment of load is worse than no autoscaler.
+ */
+export function startMetricsEndpoint(options: MetricsEndpointOptions = {}): MetricsEndpoint {
+  const server = Bun.serve({
+    port: options.port ?? DEFAULT_METRICS_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' },
+      });
+    },
+  });
+  // 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);
+  logger.info('ultimate metrics listening', { url: `${server.url.origin}${METRICS_PATH}` });
+  return {
+    url: server.url.origin,
+    stop(): void {
+      server.stop(true);
+      stopListening();
+    },
+  };
+}

package/src/migrations.ts

@@ -0,0 +1,45 @@
+// The app's SQL migrations, read off disk into `@ultimat3/db`'s own `Migration` shape. One reader,
+// because the release phase and the developer must apply the identical list through the identical
+// ledger — a deploy that migrated by some other route is a schema nobody can reconstruct.
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Migration } from '@ultimat3/db';
+
+/** Where `x new` writes them and where `x db gen` adds to. App-root-relative, POSIX. */
+export const MIGRATIONS_DIR = 'packages/db/migrations';
+
+/**
+ * `-- down` alone on a line splits a migration file. Anchored to the whole line so a comment that
+ * merely mentions the word — `-- down migrations are required` — is not mistaken for the marker.
+ */
+const DOWN_MARKER = /^[ \t]*--[ \t]*down[ \t]*$/im;
+
+/** `0000_initial` → the ledger id; `initial` → the name a conflict message prints. */
+export const migrationName = (id: string): string => id.replace(/^\d+_/, '');
+
+export function parseMigrationSql(id: string, sql: string): Migration {
+  const marker = DOWN_MARKER.exec(sql);
+  const up = (marker === null ? sql : sql.slice(0, marker.index)).trim();
+  const down = marker === null ? '' : sql.slice(marker.index + marker[0].length).trim();
+  return { id, name: migrationName(id), up, down };
+}
+
+/**
+ * Sorted by id, because that is the apply order and `pendingMigrations` re-sorts on the same key.
+ * A missing directory is an empty list rather than a throw: an app can legitimately declare no
+ * entity yet, and the count is reported so "nothing was applied" is never silent.
+ */
+export async function readMigrations(root: string): Promise<readonly Migration[]> {
+  const dir = join(root, MIGRATIONS_DIR);
+  if (!existsSync(dir)) return [];
+  const files: string[] = [];
+  for await (const file of new Bun.Glob('*.sql').scan({ cwd: dir })) files.push(file);
+  files.sort();
+  const migrations: Migration[] = [];
+  for (const file of files) {
+    const text = await Bun.file(join(dir, file)).text();
+    migrations.push(parseMigrationSql(file.replace(/\.sql$/, ''), text));
+  }
+  return migrations;
+}