@ultimat3/cli 1.0.0

package/src/dev-dashboard.ts

@@ -0,0 +1,242 @@
+// Mounting `@ultimat3/admin`'s `/_x` dashboard in the `x dev` process. The CLI contributes only
+// what no registry holds — a SQL runner on the live dev database, the caught outbox, the committed
+// manifest, and two panels of process facts — and projects the dashboard onto HTTP routes.
+// A panel implemented here instead of in `admin` would be the second copy this seam exists to ban.
+
+import type {
+  DevPanel,
+  DevSources,
+  InvalidationFact,
+  MailFact,
+  ManifestFact,
+  PolicyFact,
+  RequestTrace,
+  SqlResult,
+} from '@ultimat3/admin/dev';
+import { DEV_BASE_PATH, DEV_PANELS, defaultDevSources, devDashboard } from '@ultimat3/admin/dev';
+import { recentInvalidations } from '@ultimat3/cache';
+import type { Role } from '@ultimat3/core';
+import type { Route, UltimateRequest } from '@ultimat3/http';
+import { json as jsonResponse } from '@ultimat3/http';
+import type { MemoryMailDriver } from '@ultimat3/mail';
+import { isMemoryDriver } from '@ultimat3/mail';
+import type { Manifest } from '@ultimat3/manifest';
+import { checkAppBoundaries } from './app-boundaries';
+import { appManifest, readAppManifest } from './app-manifest';
+import { devPolicyMatrix } from './dev-policy';
+import type { RunningServices } from './dev-runtime';
+import type { DevServices } from './dev-services';
+import type { TraceRecorder } from './dev-traces';
+import type { Finding } from './output';
+
+export interface DevStatus {
+  readonly url: string;
+  readonly services: DevServices;
+  readonly roles: readonly Role[];
+  readonly findings: readonly Finding[];
+  readonly reloads: number;
+}
+
+export interface DevDashboardInput {
+  readonly root: string;
+  readonly runtime: RunningServices;
+  /** Read at request time: the process's live facts change while the dashboard is mounted. */
+  status(): DevStatus;
+  /** NODE_ENV/X_ENV as x dev saw it; `devDashboard` refuses to mount in production. */
+  readonly env?: string | undefined;
+  /** The spans this process recorded. Absent when `x dev` did not install the exporter. */
+  readonly traces?: TraceRecorder | undefined;
+}
+
+/**
+ * Read-only is already enforced by `assertReadOnly` inside `dbPanel`, before `runSql` is ever
+ * reached. A second gate here would be a second authz: two places to update when `x db psql
+ * --write` changes what is allowed, and one of them would eventually disagree.
+ */
+async function runSql(input: DevDashboardInput, sql: string): Promise<SqlResult> {
+  const started = performance.now();
+  const rows = await input.runtime.db.query<Readonly<Record<string, unknown>>>({
+    text: sql,
+    values: [],
+  });
+  const elapsedMs = Math.round(performance.now() - started);
+  // Columns come from the first row because the driver returns objects, not a described result
+  // set; no rows means no columns to name, which the panel renders as an empty grid.
+  const columns = Object.keys(rows[0] ?? {});
+  return { columns, rows: rows.map((row) => columns.map((column) => row[column])), elapsedMs };
+}
+
+/** `MailMessage.locale` is non-optional in `@ultimat3/mail`, so the panel never has to guess. */
+function mailFacts(outbox: MemoryMailDriver): readonly MailFact[] {
+  return outbox.outbox().map((entry) => ({
+    id: entry.result.id,
+    to: entry.message.to.join(', '),
+    subject: entry.message.subject,
+    locale: entry.message.locale,
+    html: entry.message.html,
+    text: entry.message.text,
+    sentAt: entry.at.toISOString(),
+  }));
+}
+
+/** Top-level keys only: that is the granularity `manifestPanel` splits into added/removed/changed. */
+const topLevel = (manifest: Manifest | undefined): ReadonlyMap<string, unknown> =>
+  new Map<string, unknown>(manifest === undefined ? [] : Object.entries(manifest));
+
+/**
+ * A side that is missing stays `undefined` rather than becoming `null`: `manifestPanel` reads
+ * exactly that distinction to tell an added key from a changed one.
+ */
+function manifestDiff(emitted: Manifest, committed: Manifest | undefined): ManifestFact['diff'] {
+  const left = topLevel(emitted);
+  const right = topLevel(committed);
+  return [...new Set([...left.keys(), ...right.keys()])]
+    .filter((key) => JSON.stringify(left.get(key)) !== JSON.stringify(right.get(key)))
+    .map((key) => ({ path: key, emitted: left.get(key), committed: right.get(key) }));
+}
+
+async function manifestFact(root: string): Promise<ManifestFact> {
+  const [{ manifest: emitted }, committed] = await Promise.all([
+    appManifest(root),
+    readAppManifest(root),
+  ]);
+  return { emitted, committed: committed ?? null, diff: manifestDiff(emitted, committed) };
+}
+
+/**
+ * `@ultimat3/cache` keeps the report of every `invalidateTags` fan-out; the panel reads it back
+ * as its log. Only the shape differs — the cache owns the facts, /_x owns the rendering.
+ */
+const invalidationFacts = (): readonly InvalidationFact[] =>
+  recentInvalidations().map((event) => ({
+    at: event.at,
+    tags: event.tags,
+    busted: event.busted,
+    source: event.source,
+  }));
+
+/**
+ * Every source only this process can answer. It owns the SQL connection, the caught outbox, the
+ * committed manifest on disk, the span exporter and the app's registries — no other host can.
+ *
+ * `subscribers` is the one left unwired, and stays that way until `@ultimat3/realtime` records a
+ * subscriber's matcher decision: `LiveSubscriberFact.trace` is the live panel's whole question,
+ * and nothing in the registry retains it. `defaultDevSources` rejects it with `X_NOT_IMPLEMENTED`
+ * and the wiring line, which the live panel degrades into its own `dev.live.no-sync-node` note —
+ * a bare empty list would claim nobody is subscribed, which is a different and unearned answer.
+ */
+export function devSources(input: DevDashboardInput): DevSources {
+  const traces = input.traces;
+  // Only the memory driver retains what it accepted. Once a credential selects a real transport
+  // the messages are at the provider, so the hook is omitted rather than answered with `[]` —
+  // an empty outbox claims nobody was mailed, which is a different and unearned answer.
+  const outbox = isMemoryDriver(input.runtime.mail) ? input.runtime.mail : undefined;
+  return defaultDevSources({
+    hooks: {
+      runSql: (sql: string): Promise<SqlResult> => runSql(input, sql),
+      ...(outbox === undefined
+        ? {}
+        : { mail: (): Promise<readonly MailFact[]> => Promise.resolve(mailFacts(outbox)) }),
+      manifest: (): Promise<ManifestFact> => manifestFact(input.root),
+      invalidations: (): Promise<readonly InvalidationFact[]> =>
+        Promise.resolve(invalidationFacts()),
+      // Read through the app's own policies at request time, so a reload that changes a rule
+      // changes the matrix without a remount.
+      policyMatrix: (): Promise<readonly PolicyFact[]> => Promise.resolve(devPolicyMatrix()),
+      // Spread, never passed as `undefined`: a host with no recorder must fall back to the
+      // refusal `defaultDevSources` already carries, not to an empty timeline.
+      ...(traces === undefined
+        ? {}
+        : { traces: (): Promise<readonly RequestTrace[]> => Promise.resolve(traces.traces()) }),
+    },
+  });
+}
+
+interface ServicesPanelData extends DevStatus {
+  readonly stateDir: string;
+}
+
+/**
+ * Both CLI panels ignore the `DevSources` argument, and must: these are facts about this
+ * process — which port it bound, which roles it started, which files would not import — not
+ * introspection of the app's registries. No registry could answer them.
+ */
+const servicesPanel = (input: DevDashboardInput): DevPanel<ServicesPanelData> => ({
+  key: 'services',
+  titleKey: 'dev.panel.services',
+  question: 'which services is this process talking to, and did anything fail to load?',
+  data(): Promise<ServicesPanelData> {
+    const status = input.status();
+    return Promise.resolve({ ...status, stateDir: status.services.stateDir });
+  },
+});
+
+interface BoundariesPanelData {
+  readonly findings: readonly Finding[];
+}
+
+const boundariesPanel = (input: DevDashboardInput): DevPanel<BoundariesPanelData> => ({
+  key: 'boundaries',
+  titleKey: 'dev.panel.boundaries',
+  question: 'does any file import across a boundary the build will reject?',
+  async data(): Promise<BoundariesPanelData> {
+    return { findings: await checkAppBoundaries(input.root) };
+  },
+});
+
+export function devPanels(input: DevDashboardInput): readonly DevPanel[] {
+  return [...DEV_PANELS, servicesPanel(input), boundariesPanel(input)];
+}
+
+/**
+ * `handle` answers `null` only for a path outside `basePath`, and every path below was generated
+ * from it — unreachable, answered anyway. A `!` here would turn a future `basePath` change into a
+ * runtime crash instead of a payload that names the mismatch.
+ */
+const notClaimed = (path: string): Response =>
+  jsonResponse(
+    {
+      panel: path,
+      ok: false,
+      error: {
+        code: 'X_ROUTE_NOT_FOUND',
+        cause: `x dev mounted ${path} but the /_x dashboard did not claim it`,
+        fix: 'x dev --json   # then report the DEV_BASE_PATH / route table mismatch',
+      },
+    },
+    { status: 404 },
+  );
+
+const devRoute = (path: string, name: string, handler: Route['handler']): Route => ({
+  method: 'GET',
+  path,
+  // Public: /_x exists to be read without credentials by whatever drives the dev loop, and
+  // `devDashboard` refuses to construct at all outside development.
+  meta: { name, auth: 'public', tags: ['_x'] },
+  handler,
+});
+
+/**
+ * One route for the base path plus one per panel, because the router matches exact paths. The
+ * dashboard is built once — its sources close over this process, and rebuilding per request would
+ * re-run `assertDevOnly` on every hit for no new answer.
+ */
+export function devDashboardRoutes(input: DevDashboardInput): readonly Route[] {
+  const panels = devPanels(input);
+  const dashboard = devDashboard({
+    basePath: DEV_BASE_PATH,
+    panels,
+    sources: devSources(input),
+    ...(input.env === undefined ? {} : { env: input.env }),
+  });
+
+  const handler = async (request: UltimateRequest): Promise<Response> =>
+    (await dashboard.handle(request.raw)) ?? notClaimed(request.pathname);
+
+  return [
+    devRoute(DEV_BASE_PATH, 'dev._x', handler),
+    ...panels.map((panel) =>
+      devRoute(`${DEV_BASE_PATH}/${panel.key}`, `dev._x.${panel.key}`, handler),
+    ),
+  ];
+}

package/src/dev-hooks.ts

@@ -0,0 +1,51 @@
+// The two seams `@ultimat3/http` leaves open, bound to the packages that own them. `authorize`
+// decides for pages only, from the SAME `Policy` object every other surface evaluates — the route
+// table's declared permission — so a denial in `x dev` is the one production produces.
+
+import { actorOf } from '@ultimat3/action';
+import type { AuthzDecision, ServerHooks } from '@ultimat3/http';
+import { asCtx } from '@ultimat3/http';
+import type { KnownPermission, Policy } from '@ultimat3/policy';
+import { can, evaluate } from '@ultimat3/policy';
+import { routeFor } from '@ultimat3/render';
+
+/**
+ * `RouteGuard.permission` is a bare string — `@ultimat3/render` keeps policy structural on
+ * purpose. `can()` checks the name against the registry; this only checks the shape, so a
+ * malformed guard denies with "no policy registered" instead of throwing inside the pipeline.
+ */
+const isPermission = (value: string): value is KnownPermission => /^[^:]+:[^:]+$/.test(value);
+
+/** A page carries only the permission label, because that is all `RouteGuard` keeps. */
+function policyFor(path: string): Policy<unknown, unknown> | undefined {
+  const permission = routeFor(path)?.config.policy?.permission;
+  return permission !== undefined && isPermission(permission) ? can(permission) : undefined;
+}
+
+export function devHooks(): ServerHooks {
+  return {
+    authorize: (route, _request, ctx): AuthzDecision => {
+      // An action route never arrives here: it carries `enforcedBy: 'handler'`, so the pipeline
+      // never asks. `invoke` is its one evaluation, and the only one holding the row a row-level
+      // rule reads — reconstructing it here would be a second authz system, one row short.
+      const policy = policyFor(route.path);
+      if (policy === undefined) {
+        return {
+          allowed: false,
+          reason: `no policy is registered under ${route.meta.policy ?? route.meta.name}`,
+        };
+      }
+      // `actorOf` is the framework's own anonymous → null mapping, so "nobody" denies with
+      // X_UNAUTHENTICATED here exactly as it does inside `invoke`. The decision is passed
+      // straight through: `PolicyDecision` and `AuthzDecision` are the same shape by design,
+      // and an adapter here would be the beginning of a second authz model.
+      const context = asCtx(ctx);
+      return evaluate(policy, {
+        input: ctx.input,
+        actor: actorOf(context),
+        row: null,
+        ctx: context,
+      }).decision;
+    },
+  };
+}

package/src/dev-policy.ts

@@ -0,0 +1,82 @@
+// The `/_x` policy panel's source: the app's own policies, decided by `@ultimat3/policy`'s own
+// `policyMatrix()` — the same function `x g policy` generates a test against. The CLI supplies
+// only the two things no registry holds: which actors to ask about, and which capability each
+// policy gates. Re-deriving a verdict here would be the second authz the framework bans.
+
+import { listActions } from '@ultimat3/action';
+import type { PolicyFact } from '@ultimat3/admin/dev';
+import type { NamedActor, Policy } from '@ultimat3/policy';
+import { policyMatrix, roleDefinitions, testActor } from '@ultimat3/policy';
+import { listQueries } from '@ultimat3/query';
+
+/**
+ * One capability and the policy that decides it. A primitive's `capability` IS its policy's own
+ * label (`policyCapability` returns exactly that), so the capability identifies the gate: two
+ * primitives reporting the same one are two call sites of one rule, not two answers to one cell.
+ */
+interface PolicyGate {
+  readonly permission: string;
+  readonly policy: Policy;
+  /** The primitives that gate on it — the panel's answer to "where is this enforced?". */
+  readonly usedBy: readonly string[];
+}
+
+/**
+ * Every actor the matrix is computed for: one per role the app declared with `defineRoles`, plus
+ * the anonymous caller. Derived rather than flagged, because the roles ARE the app's declaration
+ * of who exists — a `--actor` flag would be a second place to keep that list.
+ */
+export function devActors(): readonly NamedActor[] {
+  const roles = Object.keys(roleDefinitions()).sort();
+  return [
+    { name: 'anonymous', actor: null },
+    ...roles.map((role) => testActor(role, { roles: [role] })),
+  ];
+}
+
+/** Every gated capability in the app, actions and queries alike, sorted for a stable panel. */
+export function devPolicyGates(): readonly PolicyGate[] {
+  const gates = new Map<string, { permission: string; policy: Policy; usedBy: string[] }>();
+  const add = (permission: string, policy: Policy, primitive: string): void => {
+    // A policy that gates on nothing reports an empty capability; there is no cell to draw for it.
+    if (permission.length === 0) return;
+    const existing = gates.get(permission);
+    if (existing === undefined) gates.set(permission, { permission, policy, usedBy: [primitive] });
+    else existing.usedBy.push(primitive);
+  };
+
+  for (const target of listActions())
+    add(target.describe().capability, target.policy, `action:${target.name}`);
+  for (const target of listQueries())
+    add(target.describe().capability, target.policy, `query:${target.name}`);
+
+  return [...gates.values()].sort((a, b) => a.permission.localeCompare(b.permission));
+}
+
+/**
+ * The matrix, actor by actor and capability by capability.
+ *
+ * Evaluated with no row on purpose: `/_x` asks whether an actor may reach a capability at all, and
+ * there is no row to hand a row-level rule outside a real request. A rule that needs one therefore
+ * shows its no-row verdict, and the trace says so rather than letting the cell read as a flat deny.
+ */
+export function devPolicyMatrix(): readonly PolicyFact[] {
+  const actors = devActors();
+  return devPolicyGates().flatMap((gate) => {
+    const matrix = policyMatrix(gate.policy, { actors, input: {} });
+    return matrix.rows.map(
+      (row): PolicyFact => ({
+        permission: gate.permission,
+        actorId: row.actor,
+        allowed: row.allowed,
+        trace: [
+          `${gate.policy.label}: ${row.allowed ? 'allow' : 'deny'}`,
+          ...(row.deciding === null ? [] : [`deciding rule: ${row.deciding}`]),
+          ...(row.reason === null ? [] : [`reason: ${row.reason}`]),
+          `enforced in: ${gate.usedBy.join(', ')}`,
+          'evaluated with no row — a row-level rule decides again on the real request',
+        ],
+      }),
+    );
+  });
+}

package/src/dev-queue.ts

@@ -0,0 +1,109 @@
+// The database and the job queue, started together and released together. Split from
+// `dev-runtime.ts` because `x jobs` needs exactly this pair and nothing else — and because a
+// process that installs two ambient accessors (`db()`, `jobDriver()`) must have one place that
+// takes both back, or the next command in the same process inherits a driver over a closed socket.
+
+import type { PgliteClient, PostgresClient, SqlFragment } from '@ultimat3/db';
+import {
+  createPgliteClient,
+  createPostgresClient,
+  pgliteDataDir,
+  raw,
+  setDbClient,
+} from '@ultimat3/db';
+import type { JobDriver, PgExecutor } from '@ultimat3/jobs';
+import { createPgDriver, resetJobDriver, SQL_JOBS_TABLE, setJobDriver } from '@ultimat3/jobs';
+import type { DevServices } from './dev-services';
+
+/** Both embedded and external clients boot lazily and close explicitly. */
+export type DevDbClient = PgliteClient | PostgresClient;
+
+export interface RunningQueue {
+  readonly db: DevDbClient;
+  readonly jobs: JobDriver;
+  stop(): Promise<void>;
+}
+
+function startDb(services: DevServices): DevDbClient {
+  const binding = services.db;
+  const client =
+    binding.mode === 'embedded'
+      ? // `pgliteDataDir` is `@ultimat3/db`'s own reader of the `pglite://` form; a second parser
+        // here is a second thing to keep right when the form changes.
+        createPgliteClient({ dataDir: pgliteDataDir(binding.url) })
+      : createPostgresClient({ url: binding.url });
+  setDbClient(client);
+  return client;
+}
+
+/**
+ * `@ultimat3/jobs` deliberately depends on no database package: Postgres reaches it as an
+ * injected `PgExecutor`. Boot code is what supplies one, and this is the boot.
+ *
+ * The fragment is assembled by hand rather than through `sql`` ` because the driver hands over
+ * `$1..$n` text it wrote itself plus already-bound values — there is no interpolation to guard.
+ */
+function executorFor(client: DevDbClient): PgExecutor {
+  return {
+    query: <R>(text: string, values: readonly unknown[]): Promise<readonly R[]> =>
+      client.query<R>({ text, values } satisfies SqlFragment),
+  };
+}
+
+/**
+ * The dev queue is the real Postgres queue on the embedded Postgres — claiming, leases and the
+ * one-live-job-per-key index all behave here exactly as in production. A memory queue in dev
+ * would hide every bug this driver exists to make impossible.
+ *
+ * PGlite speaks the extended protocol, which carries one statement per round trip, so the DDL
+ * is applied statement by statement. Safe to split on `;`: `SQL_JOBS_TABLE` is a fixed constant
+ * with no semicolon inside a literal, and `driver-pg-sql.test.ts` is where that stays true.
+ */
+async function startJobs(client: DevDbClient): Promise<JobDriver> {
+  for (const statement of SQL_JOBS_TABLE.split(';')) {
+    if (statement.trim().length > 0) await client.execute(raw(statement));
+  }
+  const driver = createPgDriver({ executor: executorFor(client) });
+  setJobDriver(driver);
+  return driver;
+}
+
+/**
+ * Release both ambient accessors, then the resources behind them, in that order: a driver reset
+ * after its database is closed leaves a window where `jobDriver()` answers over a dead socket.
+ * A stale driver is worse than none — the next command sees one installed and skips queue
+ * startup entirely, so every query it makes fails on a connection this process already dropped.
+ */
+async function releaseQueue(db: DevDbClient, jobs: JobDriver | undefined): Promise<void> {
+  resetJobDriver();
+  setDbClient(undefined);
+  await jobs?.close?.();
+  await db.close();
+}
+
+/**
+ * The db + jobs half of `startServices`, alone: `x jobs` needs a real queue and nothing else —
+ * no transport, no storage, no mail — and booting those for a command that never reports on them
+ * would pay for services it cannot even use. `startServices` builds on this so there is one boot
+ * path for "which database" and "which queue", not two.
+ */
+export async function startQueue(services: DevServices): Promise<RunningQueue> {
+  const db = startDb(services);
+  try {
+    // Pay the Postgres boot here, so the first request is not the slow one and a broken database
+    // fails at boot rather than on some later query.
+    await db.ping();
+    const jobs = await startJobs(db);
+    return { db, jobs, stop: () => releaseQueue(db, jobs) };
+  } catch (error) {
+    // `db.ping()` or `startJobs` is where a broken database is supposed to fail. Without this,
+    // the caller exits holding the PGlite lock and the ambient accessors, and nothing is left to
+    // release them. The rejection that started the unwind is the one worth reporting.
+    try {
+      await releaseQueue(db, undefined);
+    } catch {
+      // Cleanup noise never replaces the boot failure.
+    }
+    throw error;
+  }
+}

package/src/dev-render.ts

@@ -0,0 +1,129 @@
+// Projecting the route table onto HTTP routes `x dev` can serve. Every mode goes through
+// `@ultimat3/render`'s own function for that mode — the CLI picks the mode and supplies the
+// document, it never decides what a mode means or what headers it earns.
+//
+// The document is head + shell. Islands are the compiled client graph's, and there is no
+// compiled graph before `x build`, so a dev page serves its real `<head>`, its real status and
+// its real cache headers around an empty root — never a 404.
+
+import type { Ctx } from '@ultimat3/core';
+import type { RouteMeta as HttpRouteMeta, Route, RouteParams } from '@ultimat3/http';
+import { asCtx, html, stream } from '@ultimat3/http';
+import type { IsrController, RenderResult, RouteEntry } from '@ultimat3/render';
+import {
+  contentHash,
+  createIsrController,
+  headFromMeta,
+  renderHead,
+  renderSpa,
+  renderSsr,
+  routeEntries,
+  SPA_ROOT_ID,
+  seoRenderers,
+  staticHeaders,
+  streamResult,
+} from '@ultimat3/render';
+
+export interface DevRenderOptions {
+  readonly buildId: string;
+  /** Injected so a test can drive the ISR store without a timer. */
+  readonly isr?: IsrController;
+}
+
+/** What a route's `meta(data)` is given. `url` is a string because that is what `ld.*` embeds. */
+export interface DevRouteData extends Record<string, unknown> {
+  readonly url: string;
+  readonly params: RouteParams;
+}
+
+const LANG = 'en';
+
+const headFor = async (entry: RouteEntry, data: DevRouteData): Promise<string> =>
+  renderHead(
+    headFromMeta(await entry.config.meta(data), seoRenderers({ path: new URL(data.url).pathname })),
+  );
+
+async function documentFor(entry: RouteEntry, data: DevRouteData): Promise<string> {
+  return shellFor(await headFor(entry, data));
+}
+
+const shellFor = (head: string): string =>
+  `<!doctype html><html lang="${LANG}"><head>${head}</head>` +
+  `<body><div id="${SPA_ROOT_ID}"></div></body></html>`;
+
+async function resultFor(
+  entry: RouteEntry,
+  data: DevRouteData,
+  options: DevRenderOptions,
+  isr: IsrController,
+  ctx: Ctx,
+): Promise<RenderResult> {
+  const url = new URL(data.url);
+  switch (entry.config.render) {
+    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);
+      return { status: 200, headers: staticHeaders(contentHash(body), options.buildId), body };
+    }
+    case 'isr': {
+      const served = await isr.serve(url.pathname, () => documentFor(entry, data));
+      return served.result;
+    }
+    case 'spa':
+      return renderSpa({
+        entry,
+        buildId: options.buildId,
+        head: await headFor(entry, data),
+        chunks: [],
+        lang: LANG,
+      });
+    case 'stream': {
+      const head = await headFor(entry, data);
+      return streamResult(
+        {
+          head: `<!doctype html><html lang="${LANG}"><head>${head}</head><body>`,
+          shell: `<div id="${SPA_ROOT_ID}"></div>`,
+          holes: [],
+        },
+        { buildId: options.buildId },
+      );
+    }
+    default:
+      return renderSsr({ entry, params: data.params, url, ctx }, () => documentFor(entry, data), {
+        buildId: options.buildId,
+      });
+  }
+}
+
+const responseOf = (result: RenderResult): Response =>
+  typeof result.body === 'string'
+    ? html(result.body, { status: result.status, headers: result.headers })
+    : stream(result.body, { status: result.status, headers: result.headers });
+
+/**
+ * `auth` follows the route's own guard, so a gated page is gated in dev by the same pipeline
+ * stage that gates it in production. A route that declares no policy is public by declaration.
+ */
+const metaOf = (entry: RouteEntry): HttpRouteMeta => ({
+  name: entry.file,
+  auth: entry.config.policy === undefined ? 'public' : 'required',
+  render: entry.config.render,
+  tags: [entry.surface],
+  ...(entry.config.policy === undefined ? {} : { policy: entry.config.policy.permission }),
+});
+
+/** One HTTP route per registered `route` primitive, in the table's own order. */
+export function appRoutes(options: DevRenderOptions): readonly Route[] {
+  const isr = options.isr ?? createIsrController({ buildId: options.buildId });
+  return routeEntries().map((entry) => ({
+    method: 'GET' as const,
+    path: entry.path,
+    meta: metaOf(entry),
+    // `ctx.params` is the router's own match — the CLI never re-parses a path it did not match.
+    handler: async (request, ctx): Promise<Response> => {
+      const data: DevRouteData = { url: request.url.href, params: ctx.params };
+      return responseOf(await resultFor(entry, data, options, isr, asCtx(ctx)));
+    },
+  }));
+}