@ultimat3/cli 23.0.0 → 25.0.0

package/src/messages.ts

@@ -86,6 +86,9 @@ const CATALOG = {
   'cli.dev.mail.refused': 'mail=refused({detail})',
   'cli.dev.hmr': 'reloaded {file} in {ms}ms',
   'cli.dev.restart': 'restarting: {reason} — a module that defines a primitive holds the old code',
+  // The restart's wait, said while it waits: a save never cancels a running job (issue #677).
+  'cli.dev.restartWaiting':
+    'restart waits for {count} running job(s) to finish — no new job is claimed; Ctrl-C stops now (a job still running is cut off at the drain deadline and requeued)',
   // A hard kill leaves the lock behind and that is normal, not a fault — worth one line so a
   // reader knows why the boot paused, and never a finding.
   'cli.dev.staleLock': 'cleared a stale dev.lock — the previous x dev did not shut down cleanly',
@@ -143,9 +146,6 @@ const CATALOG = {
   'cli.jobs.deadLetters': '{count} dead letter(s):',
   'cli.jobs.depth':
     '{ready} ready · {running} running · {delayed} delayed · {dead} dead across {queues} queue(s)',
-  'cli.jobs.drained': 'drained {count} job(s) from {from} to {to}',
-  'cli.jobs.drainedPartial':
-    'drained {count} job(s) from {from} to {to} — {skipped} left on {from}',
   'cli.jobs.listed': '{count} job(s)',
   'cli.jobs.nextPage': 'more — next page: x jobs ls --after {cursor}',
   'cli.jobs.noError': 'no error recorded',
@@ -156,24 +156,30 @@ const CATALOG = {
   'cli.jobs.resumed': 'queue {queue} resumed',
   'cli.jobs.retried': 'job {id} re-queued — {state}',
   'cli.jobs.shown': 'job {id} — {state}, attempt {attempt} of {attempts}',
-  'cli.jobs.skipped': '{count} job(s) left on {from} — re-run the drain once each is claimable:',
   'cli.manifest.blocked': 'manifest not written — {count} module(s) did not load',
   'cli.manifest.fresh': 'manifest is fresh',
   'cli.manifest.stale': 'manifest is stale',
   'cli.manifest.wrote': 'manifest written to {path} ({routes} routes, {actions} actions)',
   'cli.mcp.serving': 'mcp {transport} serving {tools} tools',
   'cli.mcp.scopes': '  scopes {scopes}',
-  // `bin/setup` and nothing else: the scaffold ships it, `README.md` and `bin/check` both name it,
-  // and it is the only spelling that is right on a fresh clone — it installs, writes
-  // `.env.development.local`, runs `x db gen "initial"` (the scaffold writes no migration, so the
-  // drift step is red until it has), migrates and seeds. The four-command line this replaced named
-  // `x dev` off a tree where nothing had installed the CLI yet, and skipped the seed entirely.
-  // `bin/dev`, never `x dev`: `bun install` links the binary into `./node_modules/.bin` and
-  // nowhere else, so the bare `x` this line printed is not on PATH in the shell it is pasted into
-  // (proved with `env -i PATH=… command -v x`). The scaffold's own `bin/` wrappers are the form
-  // that works from a fresh clone, and `bin/setup` already uses `bunx x` internally for this
-  // reason.
-  'cli.new.done': 'created {name} — next: cd {name} && bin/setup && bin/dev',
+  // `bun run setup` and nothing else: the scaffold ships it (`bin/setup.ts`), `README.md` and
+  // `bun run check` both name it, and it is the only spelling that is right on a fresh clone — it
+  // installs, writes `.env.development.local`, runs `x db gen "initial"` (the scaffold writes no
+  // migration, so the drift step is red until it has), migrates and seeds. The four-command line
+  // this replaced named `x dev` off a tree where nothing had installed the CLI yet, and skipped the
+  // seed entirely.
+  // `bun run dev`, never `x dev`: `bun install` links the binary into `./node_modules/.bin` and
+  // nowhere else, so a bare `x` is not on PATH in the shell it is pasted into (proved with
+  // `env -i PATH=… command -v x`); `bun run` puts that directory on PATH for the script. And
+  // `bun run`, never a `bin/` path: Bun runs the line identically in PowerShell, cmd and bash.
+  // `{cd}` is the resolved target as the caller's shell reaches it — `--dir` included, relative to
+  // the cwd when under it, shell-quoted (`cmd-new.ts`'s `cdTarget`). `cd {name}` entered the wrong
+  // directory, or none, whenever `--dir` put the app somewhere else.
+  'cli.new.done': 'created {name} — next: cd {cd} && bun run setup && bun run dev',
+  // `--dry-run`'s own summary: nothing landed, so "created" was a claim an agent branching on the
+  // summary would act on. `{dir}` is the resolved target, `--dir` included.
+  'cli.new.dryRun':
+    'would create {name} in {dir} — nothing written; after a real run: cd {cd} && bun run setup && bun run dev',
   // The two prose lines of `x new`'s report. The `run: cd … && git init …` line beneath the second
   // one stays inline in `cmd-new.ts`: it is an instruction to paste verbatim, and a translated
   // command is a broken one — the same split `Finding.fix` already makes.
@@ -197,6 +203,8 @@ const CATALOG = {
   'cli.registry.described': '{kind} {name}',
   'cli.routes.count': '{count} routes',
   'cli.routes.empty': 'no routes in the manifest — run `x manifest` first',
+  'cli.auth.sealed':
+    'sealed {sealed} second-factor secret(s); {already} already sealed, {skipped} changed mid-run and left alone',
   'cli.tasks.count': '{count} task(s)',
   'cli.tasks.shown': '{name} — {cron} ({tz}), next {next}',
   'cli.affected.count':
@@ -233,6 +241,10 @@ const CATALOG = {
   'cli.shot.pageError': '  threw    {message}  {at}',
   'cli.shot.picture': '  picture  {path}',
   'cli.shot.verdict': '  verdict  {path}',
+  // `--viewport`: one route at several sizes. The summary is ONE size's verdict, so it says which
+  // size; each size line leads with its size and the per-size detail lines sit indented beneath.
+  'cli.shot.viewport.summary': '{size}: {summary}',
+  'cli.shot.viewport.line': '{size}  {summary}',
   // `--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':
@@ -302,7 +314,7 @@ const CATALOG = {
   // A skipped step is not a passed one, so the two counts never share a sentence — and the skipped
   // ones are named, because "which suite has nothing to run here?" is the question a green gate
   // over a missing suite has to answer on its own line. Whole sentences per case rather than a
-  // clause the caller glues on, the same shape `cli.jobs.drained`/`drainedPartial` already uses.
+  // clause the caller glues on: a catalog clause cannot know the sentence it lands in.
   'cli.verify.passSkipped':
     '{passed} of {count} steps passed in {ms}ms — {skipped} skipped: {names}',
   'cli.verify.failSkipped': '{failed} of {count} steps failed — {skipped} skipped: {names}',
@@ -313,6 +325,7 @@ const CATALOG = {
   // tests ran. Each test's own name carries the reason it skipped, and `bun test` prints only the
   // counts — so the line says how many and `x test <type>` prints the names.
   'cli.verify.allSkipped': 'found {skipped} test(s) and every one skipped itself',
+  'cli.verify.warnings': '{count} warning(s) — --verbose or --json lists them',
   // The other shape the same counts can take: a suite that reported no test at all, skipped ones
   // included. Its own line and not `allSkipped` with a zero, because the repair differs — there is
   // no skipped test to read a reason off, so the files the step selected hold no test.

package/src/metrics-endpoint.ts

@@ -5,16 +5,20 @@
 
 import {
   finiteCount,
+  type HealthPayload,
+  healthzPayload,
   logger,
   METRICS_CONTENT_TYPE,
   METRICS_PATH,
   markListening,
   metricsText,
+  readyzPayload,
   startProcessMetrics,
   stringField,
   UltimateError,
 } from '@ultimat3/core';
 import { neighbouringPort } from './flag-number';
+import { quoteArg } from './shell-quote';
 
 /**
  * A port of its own, and NOT the role's HTTP port, for one reason the chart makes concrete:
@@ -45,7 +49,7 @@ export class MetricsPortInUseError extends UltimateError {
     super({
       code: 'X_PORT_IN_USE',
       cause: `the metrics port ${input.port} is already bound, so no role could open its scrape listener`,
-      fix: `METRICS_PORT=${neighbouringPort(input.port)} x dev --json`,
+      fix: `METRICS_PORT=${quoteArg(String(neighbouringPort(input.port)))} x dev --json`,
     });
   }
 }
@@ -111,7 +115,7 @@ export function bindScrapePort<T>(
     logger.warn('ultimate metrics port taken', {
       port,
       cause: `the metrics port ${String(port)} is already bound — another x dev, or a Prometheus — so this process listens on a free one`,
-      fix: `METRICS_PORT=${String(neighbouringPort(port))} x dev --json`,
+      fix: `METRICS_PORT=${quoteArg(String(neighbouringPort(port)))} x dev --json`,
     });
     return bind(0);
   }
@@ -123,6 +127,18 @@ export interface MetricsEndpoint {
   stop(): void;
 }
 
+/**
+ * `/healthz` and `/readyz` for the roles whose only socket this is — `worker`, `scheduler`,
+ * `replicator` — so the replicator's readiness check (`role-replicator.ts`) is read by a probe.
+ * The verdict only, never the report: this port is unauthenticated, and check names are topology.
+ */
+function healthResponse(payload: HealthPayload, role: string): Response {
+  return Response.json(
+    { state: payload.body.state, ready: payload.body.ready, role },
+    { status: payload.status, headers: { 'cache-control': 'no-store' } },
+  );
+}
+
 /**
  * Answers outside the request pipeline, exactly as `/healthz` and `/readyz` do in
  * `@ultimat3/http`'s `server.ts`: no auth, no rate limit, no locale negotiation. A saturated or
@@ -142,7 +158,16 @@ export function startMetricsEndpoint(options: MetricsEndpointOptions = {}): Metr
       port: candidate,
       hostname: options.hostname ?? 'localhost',
       fetch(request: Request): Response {
-        if (new URL(request.url).pathname !== METRICS_PATH) {
+        const url = new URL(request.url);
+        const role = options.role ?? 'unknown';
+        if (url.pathname === '/healthz') return healthResponse(healthzPayload(), role);
+        if (url.pathname === '/readyz') {
+          return healthResponse(
+            readyzPayload({ deep: url.searchParams.get('deep') === '1' }),
+            role,
+          );
+        }
+        if (url.pathname !== METRICS_PATH) {
           return new Response('not found', { status: 404 });
         }
         // `collectMetrics()` is cumulative and never reset by a read, so two scrapers cannot

package/src/migration-extensions.ts

@@ -24,6 +24,6 @@ export function migrationExtensions(migrations: readonly Migration[]): readonly
   return [...names].sort();
 }
 
-/** The same list for an app on disk — what an embedded boot hands `createPgliteClient`. */
+/** The same list for an app on disk — what an embedded boot hands `pgliteClient`. */
 export const appExtensions = async (root: string): Promise<readonly string[]> =>
   migrationExtensions(await readMigrations(root));

package/src/otlp-export.ts

@@ -36,7 +36,7 @@ export const METRIC_EXPORT_INTERVAL_MS = 60_000;
  * merge into process-global state, so stopping the timer and dropping the drain hooks left the
  * first boot's exporter configured: a second `serveApp` in the same process exported its spans
  * into a released exporter — queued against a collector nothing will flush to, on a timer nothing
- * clears. `cmd-dev.ts`'s `stop()` hands back `noopExporter` for exactly this reason. Per signal and
+ * clears. `dev-boot.ts`'s `stop()` hands back `noopExporter` for exactly this reason. Per signal and
  * never unconditionally: `x dev` configures a trace RECORDER before calling this, and a boot that
  * installed no exporter must not uninstall one it never owned.
  */
@@ -52,7 +52,7 @@ export function startOtlpExport(env: Env = process.env): () => void {
     const exporter = otlpSpanExporter({ endpoint: traces });
     configureTelemetry({ exporter });
     // Pushed first, so the reversed run below applies it LAST — after the drain hook is dropped,
-    // the same order `cmd-dev.ts` releases the recorder in.
+    // the same order `dev-boot.ts` releases the recorder in.
     releases.push(() => configureTelemetry({ exporter: noopExporter }));
     releases.push(onShutdown('otlp-traces', () => exporter.shutdown(), { phase: 'close' }));
     logger.info('ultimate otlp traces', { endpoint: traces });

package/src/output.ts

@@ -29,6 +29,12 @@ export interface Finding {
    * and must never be run as this CLI's own instruction.
    */
   readonly source?: 'ci-log';
+  /**
+   * Structured facts behind `cause`, for a `--json` reader that would otherwise parse the sentence:
+   * `X_VERIFY_STEP_TIMEOUT` carries the processes it killed and the files still in flight. Never
+   * the only home of a fact — the human render prints `cause` and `fix`, and both already say it.
+   */
+  readonly meta?: { readonly [key: string]: JsonValue };
 }
 
 export interface StepResult {
@@ -44,6 +50,12 @@ export interface StepResult {
    * coverage is `data.coverage.unit`), where `--json` and the terminal both always have it.
    */
   readonly output?: string;
+  /**
+   * Advice that does not fail the step — a file inside `filesize`'s band below the ceiling. Unlike
+   * `output`, carried by both renderers on a PASS too: advice a green run hides reaches nobody
+   * until it has become the failure it warns about. One line of text per warning.
+   */
+  readonly warnings?: readonly string[];
   /** Worker processes the step used; `1` means it ran serially. Absent for a non-test step. */
   readonly workers?: number;
   /** Why the width is what it is — `4 workers (budget 4.0 GB)`. */
@@ -224,6 +236,14 @@ export function renderHuman(result: CommandResult, verbose = false): string {
       `  ${mark(step)} ${step.name.padEnd(18)} ${step.durationMs}ms${width(step)}${why(step)}`,
     );
     for (const finding of step.findings) out.push(renderFinding(finding, '      '));
+    // Escaped like every other line text reaches fd 1 through: a warning names a file path. A
+    // green terminal run shows the count, not the list: `filesize`'s band alone is ~150 lines,
+    // and a wall of advice on every run is read by nobody. `--json` always carries the list.
+    const warnings = step.warnings ?? [];
+    if (verbose) for (const warning of warnings) out.push(`      ! ${singleLine(warning)}`);
+    else if (warnings.length > 0) {
+      out.push(`      ! ${msg('cli.verify.warnings', { count: warnings.length })}`);
+    }
     // NOT escaped, and that is the one exception: `output` is this process's own captured
     // subprocess stdout — `bun test`'s colour is the reason a human reads it at all, and it is
     // already split on its real newlines rather than carrying them inside one entry.
@@ -250,6 +270,10 @@ export function renderJson(result: CommandResult, verbose = false): string {
     durationMs: step.durationMs,
     skipped: step.skipped === true,
     findings: step.findings,
+    // Never gated on `ok` or `--verbose`, unlike `output` below: see `StepResult.warnings`.
+    ...(step.warnings === undefined || step.warnings.length === 0
+      ? {}
+      : { warnings: [...step.warnings] }),
     ...(step.workers === undefined ? {} : { workers: step.workers }),
     ...(step.widthReason === undefined ? {} : { widthReason: step.widthReason }),
     ...(step.shard === undefined

package/src/page-navigation.ts

@@ -6,12 +6,9 @@
 // check a soft visit gets before `load`. No surface opted in: nothing is built, served or named — a
 // `site/` page that did not ask stays 0kb (axiom 6).
 
-// why: Bun exposes no path-join primitive, and the config path is app-root-relative — the same
-// necessity `theme-boot.ts` records.
-import { join } from 'node:path';
 import { clientScopeOf } from '@ultimat3/auth';
 import type { Ctx, NavigationSurface } from '@ultimat3/core';
-import { CLIENT_NAVIGATION_SCOPE_HEADER, NAVIGATION_SURFACES } from '@ultimat3/core';
+import { CLIENT_NAVIGATION_SCOPE_HEADER } from '@ultimat3/core';
 import type { Route, RouteNavigation, UltimateRequest } from '@ultimat3/http';
 import { locationFor, navigationPurpose, relocate } from '@ultimat3/http';
 import type { ClientNavigationHead, HeadTag, RouteEntry } from '@ultimat3/render';
@@ -22,8 +19,7 @@ import {
   routeEntries,
 } from '@ultimat3/render';
 import { ssrHeaders } from '@ultimat3/render/server';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 import { FrameworkScriptBuildFailedError } from './errors';
 import {
   buildNavigationScript,
@@ -56,26 +52,14 @@ export interface NavigationDeclaration {
   readonly surfaces: readonly NavigationSurface[];
 }
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
-const isSurface = (value: unknown): value is NavigationSurface =>
-  NAVIGATION_SURFACES.some((surface) => surface === value);
-
 /**
- * `navigation.client` and `name`, as `defineConfig` validated them — no surfaces when the app says
- * nothing or has no config file. Structural, never `instanceof`, for `loadThemeMode`'s reason.
+ * `navigation.client` and `name`, off the one loader (`app-config-load.ts`) — no surfaces, and the
+ * app called `app`, for a root with no config file.
  */
 export async function loadNavigation(root: string): Promise<NavigationDeclaration> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(configPath).exists())) return { app: 'app', surfaces: [] };
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  if (!isRecord(config)) return { app: 'app', surfaces: [] };
-  const app = typeof config['name'] === 'string' ? config['name'] : 'app';
-  const navigation = config['navigation'];
-  const client = isRecord(navigation) ? navigation['client'] : undefined;
-  return { app, surfaces: Array.isArray(client) ? client.filter(isSurface) : [] };
+  const config = await loadAppConfig(root);
+  if (config === undefined) return { app: 'app', surfaces: [] };
+  return { app: config.name, surfaces: config.navigation.client };
 }
 
 /**

package/src/page-speculation.ts

@@ -5,42 +5,27 @@
 // the next page's document on pointer rest, so a full-page navigation between prerendered pages
 // paints from memory — and the page still ships 0kb of JavaScript (axiom 6).
 
-// why: Bun exposes no path-join primitive, and the config path is app-root-relative — the same
-// necessity `theme-boot.ts` records.
-import { join } from 'node:path';
 import type { NavigationSurface, SpeculationConfig } from '@ultimat3/core';
-import { DEFAULT_SPECULATION, localeSegment, resolveSpeculation } from '@ultimat3/core';
+import { DEFAULT_SPECULATION, localeSegment } from '@ultimat3/core';
 import { cspHashSource } from '@ultimat3/http';
-import { localeConfig, routedLocales } from '@ultimat3/i18n';
+import type { AppLocaleSet } from '@ultimat3/i18n/app-catalogs';
 import type { RouteDescriptor, RouteEntry } from '@ultimat3/render';
 import {
-  describeRoutes,
+  describePages,
   renderHead,
   routeEntries,
   speculationPattern,
   speculationRulesBody,
   speculationRulesTag,
 } from '@ultimat3/render';
-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;
+import { loadAppConfig } from './app-config-load';
 
 /**
- * `navigation.speculation` — the default (on, `'moderate'`) when the app says nothing or has no
- * config file. Structural, for `loadThemeMode`'s reason, and so possibly NOT what `defineConfig`
- * validated: what it finds goes through core's `resolveSpeculation`, the one validator, which
- * REFUSES (`X_CONFIG_INVALID`) a value `defineConfig` would refuse. Never coerced: an `'eager'`
- * quietly served as `'moderate'` is a rule the app did not write.
+ * `navigation.speculation` off the one loader (`app-config-load.ts`), which holds it to core's
+ * `resolveSpeculation` — the default (on, `'moderate'`) for a root with no config file.
  */
 export async function loadSpeculation(root: string): Promise<SpeculationConfig> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(configPath).exists())) return DEFAULT_SPECULATION;
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  const navigation = isRecord(config) ? config['navigation'] : undefined;
-  return resolveSpeculation(isRecord(navigation) ? navigation['speculation'] : undefined);
+  return (await loadAppConfig(root))?.navigation.speculation ?? DEFAULT_SPECULATION;
 }
 
 /**
@@ -82,15 +67,18 @@ export interface PageSpeculationInput {
   readonly client: readonly NavigationSurface[];
   readonly entries?: readonly RouteEntry[];
   readonly described?: readonly RouteDescriptor[];
-  /** The NON-default routed locales' URL segments. Read from `@ultimat3/i18n` when absent. */
-  readonly localeSegments?: readonly string[];
+  /**
+   * The NON-default routed locales' URL segments — `otherLocaleSegments(appLocaleSet)`, the set the
+   * manifest, the worker and the prerender read. Every caller passes it: no build reads the
+   * ambient locale config.
+   */
+  readonly localeSegments: readonly string[];
 }
 
-const otherLocaleSegments = (): readonly string[] => {
-  const fallback = localeSegment(localeConfig().fallback);
-  return routedLocales()
-    .map(localeSegment)
-    .filter((segment) => segment !== fallback);
+/** Every routed locale but the default, as the URL segment a prefix is spelled in. */
+export const otherLocaleSegments = (set: AppLocaleSet): readonly string[] => {
+  const fallback = localeSegment(set.defaultLocale);
+  return set.locales.map(localeSegment).filter((segment) => segment !== fallback);
 };
 
 /**
@@ -101,9 +89,9 @@ const otherLocaleSegments = (): readonly string[] => {
 export function pageSpeculation(input: PageSpeculationInput): PageSpeculation | undefined {
   if (input.config.prefetch === false) return undefined;
   const entries = input.entries ?? routeEntries();
-  const described = new Map((input.described ?? describeRoutes()).map((one) => [one.file, one]));
+  const described = new Map((input.described ?? describePages()).map((one) => [one.file, one]));
   const client = new Set<string>(input.client);
-  const segments = input.localeSegments ?? otherLocaleSegments();
+  const segments = input.localeSegments;
   const include = entries
     .filter((entry) => {
       const facts = described.get(entry.file);

package/src/parse.ts

@@ -8,14 +8,6 @@ import { BadFlagError, MissingSubcommandError, UnknownCommandError } from './err
 // anywhere while still refusing with a fix line a shell reads as one argument.
 import { quoteArg } from './shell-quote';
 
-/**
- * The historical name for `@ultimat3/core`'s `nearestName`, kept because it shipped on this
- * package's exported surface and removing it would be a major for a rename. One implementation
- * behind both — this is a delegation, not the second copy of the algorithm that `@ultimat3/policy`
- * used to carry. New callers import `nearestName` from core.
- */
-export const nearest = nearestName;
-
 export type FlagValue = string | boolean;
 
 export interface FlagSpec {

package/src/permission-grants.ts

@@ -7,7 +7,7 @@ import { listActions } from '@ultimat3/action';
 import type { Policy } from '@ultimat3/policy';
 import { roleDefinitions, rolesGranting } from '@ultimat3/policy';
 import { listQueries } from '@ultimat3/query';
-import { describeRoutes, routeEntries } from '@ultimat3/render';
+import { describePages, routeEntries } from '@ultimat3/render';
 import type { Finding } from './output';
 import { quoteArg } from './shell-quote';
 
@@ -46,12 +46,12 @@ export function requirements(): readonly UngrantedRequirement[] {
   // A route a package MOUNTED — the admin's — is in no file and so in no `routeEntries()` row. Its
   // screen decides on every permission of the mount, not only the coarse gate its route config
   // carries, so each one is a requirement: a hand-written entity nobody granted `<table>:read`
-  // for was a green gate and a 403 on its first open. `describeRoutes()` is memoized by the
+  // for was a green gate and a 403 on its first open. `describePages()` is memoized by the
   // registry, so this loop reads a list every other step already built.
   // One requirement per permission per mount, naming the first route that asks it: `posts:write`
   // gates the create form and the edit form, and one missing grant is one finding.
   const asked = new Map<string, { permission: string; by: string; first: string; more: number }>();
-  for (const route of describeRoutes()) {
+  for (const route of describePages()) {
     if (route.mount === undefined) continue;
     for (const permission of route.mount.permissions) {
       const key = `${route.mount.by} ${permission}`;

package/src/posix-path.ts

@@ -0,0 +1,30 @@
+// One answer to "this host path, written with `/`". `relative()` and `Bun.Glob` answer in the
+// host's separator, so on Windows a `\` reached an import specifier (`x fix` wrote
+// `import '..\\foo'`, which breaks every Linux teammate), a fix line and a sort key. Every such
+// result passes through here — `bun run posix-relative` refuses a `relative(` that does not.
+
+// why: Bun ships no path API; `node:path` owns `relative`, and a test hands in its `win32` half to
+// prove the Windows answer on a Linux runner.
+import * as hostPath from 'node:path';
+
+/**
+ * The one method `posixRelative` asks of a path module — structural, not `PlatformPath`: the
+ * scaffold's typecheck resolves `node:path` without that name exported (TS2305).
+ */
+export interface RelativeHost {
+  readonly relative: (from: string, to: string) => string;
+}
+
+/**
+ * `path` with every `\` written as `/`. Unconditional rather than keyed to the host's `sep`: a key,
+ * a specifier and a fix line are POSIX on every host, and a Windows-shaped path handed to a Linux
+ * process (a CI log, a test fixture) must come out the same as it would on Windows.
+ */
+export function toPosix(path: string): string {
+  return path.replaceAll('\\', '/');
+}
+
+/** `relative(from, to)` in POSIX form. `host` is the platform's own path module but for a test. */
+export function posixRelative(from: string, to: string, host: RelativeHost = hostPath): string {
+  return toPosix(host.relative(from, to));
+}

package/src/prerender-locales.ts

@@ -2,7 +2,8 @@
 // paths and files `renderStatic` computed; every other locale's are served at `/<locale>/<path>`
 // and written to `<locale>/<file>` — the layout every static host resolves with no rewrite rule.
 
-import { localeSegment, localizedPath } from '@ultimat3/i18n';
+import { localeSegment, localizePath } from '@ultimat3/core';
+import type { AppLocaleSet } from '@ultimat3/i18n/app-catalogs';
 import type { StaticArtifact } from '@ultimat3/render/server';
 
 /** A `StaticArtifact` placed for one locale: its served path and its file under `<locale>/`. */
@@ -10,8 +11,7 @@ export type LocalizedArtifact = StaticArtifact & { readonly locale: string };
 
 /** The default's artifacts first, so a report lists the unprefixed page before its translations. */
 export async function localizedArtifacts(
-  locales: readonly string[],
-  defaultLocale: string,
+  { locales, defaultLocale }: AppLocaleSet,
   renderIn: (locale: string) => Promise<readonly StaticArtifact[]>,
 ): Promise<readonly LocalizedArtifact[]> {
   const out: LocalizedArtifact[] = [];
@@ -21,7 +21,9 @@ export async function localizedArtifacts(
       out.push({
         ...artifact,
         locale,
-        path: isDefault ? artifact.path : localizedPath(artifact.path, locale, defaultLocale),
+        path: isDefault
+          ? artifact.path
+          : localizePath(artifact.path, locale, locales, defaultLocale),
         outputPath: isDefault
           ? artifact.outputPath
           : `${localeSegment(locale)}/${artifact.outputPath}`,

package/src/prerender-out.ts

@@ -1,25 +1,52 @@
 // 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.
+// Emptied only when it is provably the build's: absent, empty, or marked by an earlier build —
+// `--out apps` deleted the app's pages and `--out .x` its embedded dev database.
 
-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 { lstat, readdir, rm } from 'node:fs/promises'; // why: Bun has no recursive delete or readdir.
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'; // why: Bun ships no path resolve/relative.
 import { UltimateError } from '@ultimat3/core';
 
+/** Written into every export directory a build empties: the proof the next build may empty it. */
+export const EXPORT_MARKER = '.x-export';
+
+/**
+ * The export directory `x build --target static` chooses itself. Exempt from the marker: a build
+ * from before the marker existed left it full and unmarked, and the build owns this path by name.
+ */
+const DEFAULT_EXPORT = join('.x', 'static');
+
+const MARKER_TEXT =
+  'Written by x build --target static. This directory is emptied before every static build.\n';
+
 /** 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. */
+/** Why `out` is not the build's to empty, or `undefined` when it is. */
+async function unsafeReason(out: string, root: string): Promise<string | undefined> {
+  if (containsRoot(out, root)) return 'is the app root or holds it';
+  const stat = await lstat(out).catch(() => undefined);
+  if (stat === undefined) return undefined;
+  if (!stat.isDirectory()) return 'is not a directory';
+  const entries = await readdir(out);
+  if (entries.length === 0 || entries.includes(EXPORT_MARKER)) return undefined;
+  if (resolve(out) === resolve(root, DEFAULT_EXPORT)) return undefined;
+  return `already holds ${entries.length} entr${entries.length === 1 ? 'y' : 'ies'} and no ${EXPORT_MARKER} a previous build wrote`;
+}
+
+/** Empties `out` for a fresh export and marks it, or refuses a directory the build did not write. */
 export async function clearPrerenderOut(out: string, root: string): Promise<void> {
-  if (containsRoot(out, root)) {
+  const reason = await unsafeReason(out, root);
+  if (reason !== undefined) {
     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`,
+      code: 'X_BUILD_OUT_UNSAFE',
+      cause: `the static export directory ${resolve(out)} ${reason}, and every build empties its export directory first`,
       fix: 'x build --target static --out .x/static --json',
     });
   }
   await rm(out, { recursive: true, force: true });
+  await Bun.write(join(out, EXPORT_MARKER), MARKER_TEXT);
 }

package/src/prerender-report.ts

@@ -0,0 +1,58 @@
+// What `x build --target static` reports: every page it wrote, every route it did not and why, and
+// where the stats and the inventory landed. Split from `prerender.ts`, which decides what is
+// written; this file only names the shapes the report carries.
+
+import type { SkippedRoute, UnmeasuredRoute } from './static-report';
+
+export interface PrerenderedPage {
+  /** The DECLARED route, `/blog/:slug` — one route can write many pages, and the report groups them. */
+  readonly route: string;
+  /** The URL the page is served at — `/en/pricing` for a non-default locale. */
+  readonly path: string;
+  /** The locale the page was rendered in. */
+  readonly locale: string;
+  /** Relative to `out`, POSIX — under `<locale>/` for a non-default locale. */
+  readonly file: string;
+  readonly hash: string;
+  readonly bytes: number;
+}
+
+export interface PrerenderReport {
+  readonly out: string;
+  readonly buildId: string;
+  readonly pages: readonly PrerenderedPage[];
+  /**
+   * Every declared route that wrote no file, WITH the cause. A bare path list was the whole of
+   * #242: `.x/static/` held a partial site, the report said only which paths were missing, and a
+   * screenshot tool pointed at the directory filed "the island did not mount" against a route that
+   * had never been in the artifact. The reason is what tells an author whether an edit exists.
+   */
+  readonly skipped: readonly SkippedRoute[];
+  /**
+   * Routes whose budget this build could not weigh, with the reason. `X_BUDGET_UNMEASURED` is what
+   * the gate then reports for each; this is the half that says WHY, which a per-route finding read
+   * off a stats file cannot know.
+   */
+  readonly unmeasured: readonly UnmeasuredRoute[];
+  /** Where the measured stats landed, for the `budgets` gate step to read. */
+  readonly stats: string;
+  /** Where the emitted/skipped inventory landed, for `x build --target static` to read back. */
+  readonly report: string;
+  /** Client entries emitted, one chunk each. Reported so "which JS shipped?" needs no unzip. */
+  readonly islands: readonly string[];
+  /** Surface stylesheets emitted, one file each — the CSS half of the same question. */
+  readonly styles: readonly string[];
+  /**
+   * What the service worker could not express, and what its precache manifest weighs too much of.
+   *
+   * `PrecacheManifest.warnings` had no reader anywhere in the tree — the precache budget was, in
+   * `wiki/Troubleshooting.md`'s own words, "a designed thing that is not one" (#390). An install
+   * that stalls on a bad connection is invisible on a laptop and fatal on a phone, so the number
+   * has to reach the build's own report. Empty for an app with no service worker.
+   */
+  readonly serviceWorkerWarnings: readonly string[];
+  /** What this build could not get right on its own — today, a production build with no origin. */
+  readonly warnings: readonly string[];
+  /** The origin every absolute URL in the export was built against — hand it to `siteSeo`. */
+  readonly origin: string;
+}