@ultimat3/cli 20.2.1 → 22.0.0

package/src/mcp-ui.ts

@@ -24,17 +24,17 @@ import type {
   UiShotResult,
 } from '@ultimat3/mcp';
 import { describeRoutes } from '@ultimat3/render';
-import type { ScrapeDriver } from '@ultimat3/scraping';
-import { DEFAULT_PAGE_TIMEOUT_MS } from '@ultimat3/scraping';
 import { appBrowser } from './browser-launcher';
-import { DEFAULT_SETTLE_MS, runShot, SHOT_DIR, shotSlug } from './cmd-shot';
+import type { ShotDriver } from './browser-launcher-port';
+import { DEFAULT_PAGE_TIMEOUT_MS } from './cdp-shot-clock';
+import { DEFAULT_SETTLE_MS, readRoute, runShot, SHOT_DIR, shotSlug } from './cmd-shot';
 import { islandShot } from './cmd-shot-island';
-import type { Env } from './dev-services';
 import { islandVerdictJson } from './island-verdict';
 import { diffShots } from './mcp-ui-diff';
 import { inspectRoute } from './mcp-ui-inspect';
 import { interactRoute } from './mcp-ui-interact';
 import { retryMemo } from './retry-memo';
+import type { Env } from './runtime-bindings';
 import { shotBrowserChoice } from './shot-browser';
 import { devServerFor, type ShotServer } from './shot-server';
 import { verdictJson } from './shot-verdict';
@@ -54,7 +54,11 @@ export interface DeclaredRoute {
   readonly budgetJs: string | null;
 }
 
-export function assertBudgetedRoute(route: string, declared: readonly DeclaredRoute[]): void {
+export function assertBudgetedRoute(raw: string, declared: readonly DeclaredRoute[]): string {
+  // `readRoute` FIRST, for every `ui.*` caller: `/\\localhost:9200` matches `/:slug` and a
+  // browser reads it as `//localhost:9200`, another service on the box. `x shot` ran it; the three
+  // MCP tools skipped it, and this is the one function all four pass through.
+  const route = readRoute(raw);
   const path = route.split('?')[0] ?? route;
   const hit = declared.find((entry) => matches(entry.path, path));
   if (hit === undefined) {
@@ -71,6 +75,7 @@ export function assertBudgetedRoute(route: string, declared: readonly DeclaredRo
       fix: `declare budget: { js: '<n>kb' } in ${hit.file}, then: x build --target static --json && x verify --only budgets --json`,
     });
   }
+  return route;
 }
 
 /** `/links/:slug` matches `/links/abc123`; one segment per `:param`, no globbing. */
@@ -87,7 +92,7 @@ export interface UiHostInput {
   /** Injected by a test: the server a picture is of, in place of `devServerFor`. */
   readonly boot?: (() => Promise<ShotServer>) | undefined;
   /** Injected by a test: the browser, in place of `appBrowser` (which needs Chrome). */
-  readonly driver?: ((viewport: UiShotInput['viewport']) => Promise<ScrapeDriver>) | undefined;
+  readonly driver?: ((viewport: UiShotInput['viewport']) => Promise<ShotDriver>) | undefined;
   /** Injected by a test: the route table, in place of the registry. */
   readonly routes?: (() => readonly DeclaredRoute[]) | undefined;
 }
@@ -122,11 +127,10 @@ export function uiCapabilities(input: UiHostInput): UiCapabilities {
   const browser = () => shotBrowserChoice({ cdpFlag: undefined, browserFlag: undefined, env });
   const routes = input.routes ?? describeRoutes;
   // One browser per call, sized to the call: the injected driver in a test, `appBrowser` otherwise.
-  const driverFor = async (viewport: UiShotInput['viewport']): Promise<ScrapeDriver> => {
+  const driverFor = async (viewport: UiShotInput['viewport']): Promise<ShotDriver> => {
     if (input.driver !== undefined) return input.driver(viewport);
     const { cdpUrl, executablePath } = browser();
     return appBrowser({
-      root,
       viewport,
       ...(executablePath === undefined ? {} : { executablePath }),
       ...(cdpUrl === undefined ? {} : { cdpUrl }),
@@ -144,18 +148,18 @@ export function uiCapabilities(input: UiHostInput): UiCapabilities {
     },
 
     async shotRoute(shot) {
-      assertBudgetedRoute(shot.route, routes());
+      const route = assertBudgetedRoute(shot.route, routes());
       const driver = await driverFor(shot.viewport);
       // One directory per (route, viewport, scheme), so two pictures of one route at two widths
       // never overwrite each other and an agent can hold both.
       const outDir = join(
         root,
         SHOT_DIR,
-        shotSlug(shot.route),
+        shotSlug(route),
         `${shot.viewport.width}x${shot.viewport.height}-${shot.colorScheme}`,
       );
       const artifacts = await runShot({
-        route: shot.route,
+        route,
         outDir,
         driver,
         boot,
@@ -175,13 +179,13 @@ export function uiCapabilities(input: UiHostInput): UiCapabilities {
     async inspectRoute(inspect) {
       // The same gate as `ui.shot`, for the same reason: facts about a draft are facts about the
       // wrong thing.
-      assertBudgetedRoute(inspect.route, routes());
-      return inspectRoute({ root, boot, driver: driverFor }, inspect);
+      const route = assertBudgetedRoute(inspect.route, routes());
+      return inspectRoute({ root, boot, driver: driverFor }, { ...inspect, route });
     },
 
     async interactRoute(interact) {
-      assertBudgetedRoute(interact.route, routes());
-      return interactRoute({ root, boot, driver: driverFor }, interact);
+      const route = assertBudgetedRoute(interact.route, routes());
+      return interactRoute({ root, boot, driver: driverFor }, { ...interact, route });
     },
     // No route gate and no boot: the captures were gated when they were taken, and a diff of two
     // files needs neither a server nor a browser.

package/src/measure-database.ts

@@ -0,0 +1,73 @@
+// The database a measurement render reads, when the build has none. A page's `load` reads rows,
+// and a build runs with no `DATABASE_URL`, so every data-reading route was `X_DB_UNAVAILABLE` and
+// never weighed. The answer is `x dev`'s own embedded PGlite on a THROWAWAY state directory, with
+// the app's migrations applied and its `dev`-tier seeds run: `defineSeed` rows are keyed by
+// `seedId(label)`, so the database is the same on every machine — and a dynamic route whose
+// `prerender()` lists paths from its own rows has paths to be weighed at (plan 101 slice 11 m).
+
+// why: Bun has no mkdtemp and no recursive remove; the state directory must not outlive the build.
+import { mkdtemp, rm } from 'node:fs/promises';
+// why: Bun exposes no tmpdir(); the throwaway directory lives in the platform temp root.
+import { tmpdir } from 'node:os';
+// why: Bun ships no path-join primitive.
+import { join } from 'node:path';
+import { migrate, withTransaction } from '@ultimat3/db';
+import { postgresDriver } from '@ultimat3/entity';
+import { discoverSeeds, runSeeds, selectSeeds } from './db-seed';
+import { readMigrations } from './migrations';
+import { resolveServices } from './runtime-bindings';
+import { startQueue } from './runtime-queue';
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+/** One build's database: started on first use, released once. */
+export interface MeasureDatabase {
+  ready(): Promise<void>;
+  close(): Promise<void>;
+}
+
+/**
+ * `x dev`'s embedded database, empty and migrated, for an env with no `DATABASE_URL`. An env that
+ * names one keeps it: `db()` already reaches that server, and a build pointed at a database was
+ * pointed there on purpose.
+ */
+export function measureDatabase(root: string, env: Env = process.env): MeasureDatabase {
+  let started: Promise<() => Promise<void>> | undefined;
+  const start = async (): Promise<() => Promise<void>> => {
+    if ((env['DATABASE_URL'] ?? '') !== '') return async () => undefined;
+    // An app with no migration has no table to read, so it pays for no database: a PGlite boot
+    // is seconds, and every build of such an app (and every prerender test) paid it for nothing.
+    const migrations = await readMigrations(root);
+    if (migrations.length === 0) return async () => undefined;
+    const state = await mkdtemp(join(tmpdir(), 'x-measure-'));
+    const scoped = { ...env, ULTIMATE_STATE_DIR: state };
+    const queue = await startQueue(resolveServices(root, scoped), undefined, scoped);
+    await migrate({ migrations });
+    // The seeds `x db seed` runs in development. A failed seed is a row in its own result and
+    // never a thrown build: a route it starves is reported by the measurement that needed it.
+    const discovered = (await discoverSeeds(root)).seeds;
+    await runSeeds({
+      seeds: selectSeeds({ discovered, environment: 'development' }),
+      driver: postgresDriver(),
+      dryRun: false,
+      env: scoped,
+      transaction: (work) => withTransaction(() => work()),
+    });
+    return async () => {
+      await queue.stop();
+      await rm(state, { recursive: true, force: true });
+    };
+  };
+  return {
+    ready: async () => {
+      started ??= start();
+      await started;
+    },
+    close: async () => {
+      if (started === undefined) return;
+      const stop = await started;
+      started = undefined;
+      await stop();
+    },
+  };
+}

package/src/measure-paths.ts

@@ -0,0 +1,74 @@
+// Which URLs a route rendered only to WEIGH is rendered at. A route with no params is its own
+// path. A route with params is rendered at the paths its own `prerender()` lists — the same list a
+// static route writes files for — and one that lists none is not rendered at all: rendering
+// `/blog/:slug` with an empty `slug` failed the page's own input schema (`X_INPUT_INVALID`), and
+// that was filed as "could not be weighed", a failure of the app dressed as a gap in the build.
+
+import type { RouteEntry } from '@ultimat3/render';
+import { enumeratePrerender } from '@ultimat3/render/server';
+import { quoteArg } from './shell-quote';
+import type { UnmeasuredRoute } from './static-report';
+
+/** One render the measuring pass performs: the URL path and the params it carries. */
+export interface MeasurePath {
+  readonly path: string;
+  readonly params: Readonly<Record<string, string>>;
+}
+
+/**
+ * `pattern` with each `:name` / `*name` segment filled from `params`. Values are URI-encoded per
+ * segment, except a catch-all's, whose slashes are its own.
+ */
+export function fillPath(pattern: string, params: Readonly<Record<string, string>>): string {
+  const segments = pattern.split('/').map((segment) => {
+    const name = segment.slice(1);
+    const value = Object.hasOwn(params, name) ? (params[name] ?? '') : '';
+    if (segment.startsWith(':')) return encodeURIComponent(value);
+    if (segment.startsWith('*')) return value.split('/').map(encodeURIComponent).join('/');
+    return segment;
+  });
+  return segments.join('/') || '/';
+}
+
+/** The distinct finding for a dynamic route that gives the build nothing to render it at. */
+export function paramsUndeclared(entry: RouteEntry, listed: boolean): UnmeasuredRoute {
+  const keys = entry.pattern.keys;
+  const example = keys.map((key) => `${key}: 'a-real-${key}'`).join(', ');
+  const cause = listed
+    ? `${entry.path} has dynamic params and its prerender() listed no path, so the build had nothing to render it at and weighed nothing`
+    : `${entry.path} has dynamic params and declares no prerender(), so the build has no path to render it at and weighed nothing`;
+  return {
+    path: entry.path,
+    reason: cause,
+    code: 'X_BUDGET_PARAMS_UNDECLARED',
+    cause,
+    fix: `add prerender: () => [{ ${example} }] to defineRoute in ${quoteArg(entry.file)}, then x build --target static`,
+  };
+}
+
+/** The paths to render `entry` at, or the finding that says why there are none. */
+export type MeasurePlan =
+  | { readonly paths: readonly MeasurePath[] }
+  | { readonly unmeasured: UnmeasuredRoute };
+
+/**
+ * A `render: 'ssr'` route with params: it may not declare `prerender()` (`X_ROUTE_MODE_INVALID`),
+ * so no build can hold a value to render it at. Reported as unweighable, never as a finding — there
+ * is no edit to the app that a build could then measure.
+ */
+export const perRequestParams = (entry: RouteEntry): UnmeasuredRoute => ({
+  path: entry.path,
+  reason: `${entry.path} renders per request with params (${entry.pattern.keys.join(', ')}) and render: 'ssr' may not declare prerender(), so no build has a value to render it at — its budget is not enforced by x verify`,
+  weighable: false,
+});
+
+export async function measurePaths(entry: RouteEntry): Promise<MeasurePlan> {
+  if (entry.pattern.keys.length === 0) return { paths: [{ path: entry.path, params: {} }] };
+  if (entry.config.render === 'ssr') return { unmeasured: perRequestParams(entry) };
+  if (entry.config.prerender === undefined) return { unmeasured: paramsUndeclared(entry, false) };
+  const sets = await enumeratePrerender(entry);
+  if (sets.length === 0) return { unmeasured: paramsUndeclared(entry, true) };
+  return {
+    paths: sets.map((params) => ({ path: fillPath(entry.pattern.source, params), params })),
+  };
+}

package/src/measure-scope.ts

@@ -0,0 +1,74 @@
+// The request a measurement render runs inside. `x build` renders every app/ route it cannot
+// prerender only to WEIGH it, and that render reads its data the way a real one does: a `load`
+// calls the app's typed client, over `APP_URL`, as the request's own member. So it needs a request
+// context (`useRequestHeader('cookie')` throws X_NO_REQUEST outside one), an actor the app chose
+// (`defineMeasurementActor()` in `app.config.ts`, core's `measurementActor()` otherwise), and a
+// server to answer — the app's own API pipeline, dispatched IN PROCESS through core's
+// `withInProcessFetch`, because no server is listening during a build (plan 101 slice 11 m).
+
+import type { Actor, Ctx } from '@ultimat3/core';
+import { measurementActor, runWithContext, withInProcessFetch } from '@ultimat3/core';
+import {
+  createPipeline,
+  createRequestContext,
+  createRouter,
+  defineHttpConfig,
+} from '@ultimat3/http';
+import { apiRoutes } from './api-routes';
+
+/** One build's measurement scope: its actor, and a runner that renders inside it. */
+export interface MeasureScope {
+  readonly actor: Actor;
+  run<T>(fn: () => T): T;
+}
+
+/**
+ * The scope for `origin`. The pipeline is the app's API table and nothing else: a page's data
+ * comes from its actions and queries, and a route the render reaches that is not one of them
+ * answers 404 — which the render reports, and the route is filed unmeasured with that reason.
+ */
+export async function measureScope(input: {
+  readonly origin: string;
+  readonly buildId: string;
+}): Promise<MeasureScope> {
+  const actor = await measurementActor();
+  // No rate limit: every request here is this build's own render, and a limiter would need a
+  // deployment scope a build does not have (`X_RATE_LIMIT_SCOPE_UNSET`).
+  const config = defineHttpConfig({ buildId: input.buildId, rateLimit: { enabled: false } });
+  const ctx = createRequestContext({
+    url: new URL(input.origin),
+    method: 'GET',
+    role: 'web',
+    config,
+  });
+  ctx.actor = actor;
+  const pipeline = createPipeline({
+    table: createRouter(apiRoutes()),
+    config,
+    hooks: { authenticate: () => actor },
+  });
+  const dispatch = (url: string, init: RequestInit): Promise<Response> =>
+    pipeline.handle(new Request(url, init), { role: 'web' });
+  const request: Ctx = ctx;
+  return {
+    actor,
+    run: <T>(fn: () => T): T => withInProcessFetch(dispatch, () => runWithContext(request, fn)),
+  };
+}
+
+/**
+ * `APP_URL` for the length of `fn`, when the process has none: an app's typed client reads it to
+ * name the origin it posts to, and `withInProcessFetch` answers that origin in process. A value
+ * the process already carries is left alone — it is the app's.
+ */
+export async function withAppUrl<T>(origin: string, fn: () => Promise<T>): Promise<T> {
+  const before = process.env['APP_URL'];
+  if (before !== undefined && before !== '') return fn();
+  process.env['APP_URL'] = origin;
+  try {
+    return await fn();
+  } finally {
+    if (before === undefined) delete process.env['APP_URL'];
+    else process.env['APP_URL'] = before;
+  }
+}

package/src/messages.ts

@@ -69,7 +69,7 @@ const CATALOG = {
   'cli.dev.ready': 'dev ready on {url} — /_x mounted ({panels} panels), {services}',
   // The mail and CDN halves of that boot line. Rendered text, so it lives here — while
   // `describeMail`/`describeCdn` keep the same wording as the fixed vocabulary `x dev --json`
-  // carries, and `dev-runtime.test.ts` pins the two together so neither can drift alone.
+  // carries, and `runtime-services.test.ts` pins the two together so neither can drift alone.
   'cli.dev.cdn.external': 'cdn=external({driver} via {detail})',
   'cli.dev.cdn.none': 'cdn=none',
   'cli.dev.mail.embedded': 'mail=embedded',
@@ -204,8 +204,6 @@ const CATALOG = {
   'cli.shot.pageError': '  threw    {message}  {at}',
   'cli.shot.picture': '  picture  {path}',
   'cli.shot.verdict': '  verdict  {path}',
-  'cli.shot.blind.status':
-    'HTTP response status is not observed — the port records requests, never responses',
   // `--island`. A component capture reports per STATE, so the summary counts pictures and the
   // lines name one state each; nothing here restates a fact `--json` does not carry.
   'cli.shot.island.ok':

package/src/metrics-endpoint.ts

@@ -81,7 +81,7 @@ export interface MetricsEndpoint {
 export function startMetricsEndpoint(options: MetricsEndpointOptions = {}): MetricsEndpoint {
   // Screened here rather than left to `Bun.serve`, which refuses a `NaN` with a bare `RangeError`
   // — no code, no `fix:` — at exactly the boot path the refusal below exists to stop reporting
-  // that way. Floor 0, because 0 asks the kernel for a free port and `dev-roles.ts` passes it for
+  // that way. Floor 0, because 0 asks the kernel for a free port and `role-start.ts` passes it for
   // an ephemeral boot; the ceiling stays Bun's, which names the range it refuses.
   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

package/src/otlp-export.ts

@@ -15,7 +15,7 @@ import {
   startMetricExport,
   tryOtlpEndpoint,
 } from '@ultimat3/core';
-import type { Env } from './dev-services';
+import type { Env } from './runtime-bindings';
 
 /** How often counters are pushed. Core's own default; named here because the boot chose it. */
 export const METRIC_EXPORT_INTERVAL_MS = 60_000;

package/src/output.ts

@@ -13,6 +13,12 @@ export interface Finding {
   readonly docs?: string;
   /** Optional locator: a file, route, or table the finding is about. */
   readonly at?: string;
+  /**
+   * Where the finding's TEXT came from, when not from this process. `'ci-log'` is `x ci` reading
+   * a finding back out of a CI log that anyone who can push a branch writes: its `fix` is fenced
+   * and must never be run as this CLI's own instruction.
+   */
+  readonly source?: 'ci-log';
 }
 
 export interface StepResult {

package/src/page-sync.ts

@@ -0,0 +1,54 @@
+// What a page needs to reach the sync node, composed ONCE for `x dev` and the container alike: the
+// worker bundle and the page boot with their routes, the head a document carries (`ultimate-sync`,
+// `ultimate-build`, `ultimate-sync-worker`, the boot script), and the persisted record types a
+// private document names. One call from both boots, so the two cannot serve different targets.
+
+import { persistedRecordTypes } from '@ultimat3/entity';
+import type { Route } from '@ultimat3/http';
+import type { ClientSyncHead } from '@ultimat3/render';
+import { syncUrlFrom } from './sync-url';
+import {
+  buildPageBoot,
+  buildSyncWorker,
+  type FrameworkScript,
+  pageBootRoutes,
+  syncWorkerRoutes,
+} from './worker-bundle';
+
+export interface PageSync {
+  readonly routes: readonly Route[];
+  /** The scripts those routes serve, for the service worker to precache beside the islands. */
+  readonly scripts: readonly FrameworkScript[];
+  readonly head: ClientSyncHead;
+  /**
+   * The record types the app persists, read per render off the entity registry — the app's modules
+   * register their entities during boot, so a value captured here could predate them.
+   */
+  readonly persisted: () => readonly string[];
+}
+
+/**
+ * Built at boot and never on the watcher tick: the worker is framework code, not the app's, and a
+ * worker that changes under tabs already running it is exactly what a source-addressed URL exists
+ * to keep from happening mid-session.
+ */
+export async function pageSync(
+  root: string,
+  env: Readonly<Record<string, string | undefined>>,
+  buildId: string,
+): Promise<PageSync> {
+  const syncUrl = syncUrlFrom(env);
+  const worker = await buildSyncWorker(root);
+  const boot = await buildPageBoot(root);
+  return {
+    routes: [...syncWorkerRoutes(() => worker), ...pageBootRoutes(() => boot)],
+    scripts: [worker, boot].filter((script): script is FrameworkScript => script !== undefined),
+    head: {
+      syncUrl,
+      buildId,
+      ...(worker === undefined ? {} : { workerUrl: worker.url }),
+      ...(boot === undefined ? {} : { bootUrl: boot.url }),
+    },
+    persisted: persistedRecordTypes,
+  };
+}

package/src/permission-grants.ts

@@ -0,0 +1,86 @@
+// The `policy` step's second question: every permission an action, a query or a route REQUIRES is
+// one some role GRANTS. `x g resource customer` declared `customer:read`/`customer:write`, the
+// actions required them, no role held them, and `x verify` was green over an app whose every
+// generated endpoint answered 403 to the dev actor (plan 101 slice 11 a).
+
+import { listActions } from '@ultimat3/action';
+import type { Policy } from '@ultimat3/policy';
+import { roleDefinitions, rolesGranting } from '@ultimat3/policy';
+import { listQueries } from '@ultimat3/query';
+import { routeEntries } from '@ultimat3/render';
+import type { Finding } from './output';
+import { quoteArg } from './shell-quote';
+
+/** One rule that cannot pass for any actor the role map mints. */
+export interface UngrantedRequirement {
+  readonly permission: string;
+  /** `action createCustomer`, `query customerList`, or the route file. */
+  readonly by: string;
+}
+
+/**
+ * A rule that REQUIRES exactly one permission: a bare `can()`. A composite is not judged — in an
+ * `or(...)` one branch may be granted and the other deliberately not, and a `not(...)` names a
+ * permission the actor must LACK — so a finding there would be an argument, not a fact.
+ */
+const required = (policy: Policy<unknown, unknown>): string | undefined =>
+  policy.kind === 'permission' && policy.permissions.length === 1
+    ? policy.permissions[0]
+    : undefined;
+
+/** Every single-permission rule the app's actions, queries and routes declare. */
+export function requirements(): readonly UngrantedRequirement[] {
+  const rules: UngrantedRequirement[] = [];
+  for (const target of listActions()) {
+    const permission = required(target.policy);
+    if (permission !== undefined) rules.push({ permission, by: `action ${target.name}` });
+  }
+  for (const target of listQueries()) {
+    const permission = required(target.policy);
+    if (permission !== undefined) rules.push({ permission, by: `query ${target.name}` });
+  }
+  for (const entry of routeEntries()) {
+    const permission = entry.config.policy?.permission;
+    if (permission !== undefined) rules.push({ permission, by: entry.file });
+  }
+  return rules;
+}
+
+/**
+ * The requirements no role grants. `rolesGranting` is `@ultimat3/policy`'s own matcher, wildcards
+ * included, so the gate and `can()` agree on what a grant covers. An app that declares no role at
+ * all is not judged: it grants through `Actor.permissions` directly (an API key, a service actor),
+ * and there is no role map for a grant to be missing from.
+ */
+export function ungrantedRequirements(
+  rules: readonly UngrantedRequirement[] = requirements(),
+): readonly UngrantedRequirement[] {
+  const roles = roleDefinitions();
+  if (Object.keys(roles).length === 0) return [];
+  const seen = new Set<string>();
+  return rules
+    .filter((rule) => rolesGranting(rule.permission, roles).length === 0)
+    .filter((rule) => {
+      const key = `${rule.permission} ${rule.by}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    })
+    .sort((a, b) =>
+      a.permission === b.permission
+        ? a.by.localeCompare(b.by)
+        : a.permission.localeCompare(b.permission),
+    );
+}
+
+/** Where the scaffold keeps the role map — the file `x g policy` and `x g resource` edit. */
+export const ROLES_FILE = 'apps/web/shared/roles.ts';
+
+export function ungrantedFinding(rule: UngrantedRequirement): Finding {
+  return {
+    code: 'X_PERMISSION_UNGRANTED',
+    cause: `${rule.by} requires ${quoteArg(rule.permission)}, and no role in the app's role map grants it — no actor a role mints can ever pass`,
+    fix: `add '${rule.permission}' to the grants of a role in ${ROLES_FILE}, then x verify --only policy`,
+    at: ROLES_FILE,
+  };
+}

package/src/prerender-out.ts

@@ -0,0 +1,25 @@
+// The export directory is the build's own, and emptied before every build: `prerenderSite` only
+// ever ADDED files, so a route deleted from the app kept shipping its last HTML from `.x/static`.
+// Refused when `out` is the app root or above it — an `rm -rf` there deletes the app.
+
+import { rm } from 'node:fs/promises'; // why: Bun has no recursive directory delete.
+import { isAbsolute, relative, resolve, sep } from 'node:path'; // why: Bun ships no path resolve/relative.
+import { UltimateError } from '@ultimat3/core';
+
+/** True when `dir` is `root` itself or one of its ancestors. */
+const containsRoot = (dir: string, root: string): boolean => {
+  const up = relative(resolve(dir), resolve(root));
+  return up === '' || (up !== '..' && !up.startsWith(`..${sep}`) && !isAbsolute(up));
+};
+
+/** Empties `out` for a fresh export, or refuses a directory that holds the app. */
+export async function clearPrerenderOut(out: string, root: string): Promise<void> {
+  if (containsRoot(out, root)) {
+    throw new UltimateError({
+      code: 'X_CLI_BAD_FLAG',
+      cause: `the static export directory ${resolve(out)} is the app root or holds it, and every build empties its export directory first`,
+      fix: 'x build --target static --out .x/static --json',
+    });
+  }
+  await rm(out, { recursive: true, force: true });
+}