@ultimat3/cli 11.2.0 → 12.0.0

package/src/i18n-registration.ts

@@ -4,6 +4,9 @@
 // source against files on disk and was green for every string of a shipped app whose catalog
 // module nothing imported (issue #249).
 
+// why: Bun ships no path API, so `join` is the only way to reach the app's own i18n module on
+// the host's separator.
+import { join } from 'node:path';
 import type { Catalog, Extraction, ExtractReport, Locale } from '@ultimat3/i18n';
 import {
   auditCatalogs,
@@ -17,9 +20,10 @@ import {
 } from '@ultimat3/i18n';
 import { loadApp } from './app-load';
 import { auditApp } from './i18n-audit';
+import { I18N_INDEX_PATH } from './i18n-index';
 import type { Finding } from './output';
 import { findingFrom } from './output';
-import { catalogPath } from './templates/locales';
+import { CATALOG_ROOT, catalogPath } from './templates/locales';
 
 /**
  * What this check needs of a boot. The seam is injected so a fixture can be exactly "the app
@@ -75,8 +79,10 @@ export async function checkRegistration(input: RegistrationInput): Promise<Regis
   const app = await (input.load ?? loadApp)(input.root);
 
   const gaps = catalogRegistrationGaps(input.catalogs);
+  const index = await indexSource(input.root);
   const findings: Finding[] = gaps.map((gap) => ({
     ...findingFrom(catalogUnregistered(gap)),
+    ...unregisteredFix(gap.locale, index),
     at: catalogPath(gap.locale),
   }));
   let unregistered = gaps.reduce((sum, gap) => sum + gap.missing.length, 0);
@@ -105,6 +111,42 @@ export async function checkRegistration(input: RegistrationInput): Promise<Regis
   };
 }
 
+/**
+ * `packages/i18n/src/index.ts` as text, or `undefined` where the app has no i18n package. Read
+ * here and nowhere lower down: `@ultimat3/i18n` states that it never reads a file, and the CLI is
+ * the half that knows what an app's directories are.
+ */
+async function indexSource(root: string): Promise<string | undefined> {
+  const file = Bun.file(join(root, I18N_INDEX_PATH));
+  return (await file.exists()) ? file.text() : undefined;
+}
+
+/**
+ * `X_CATALOG_UNREGISTERED` is one code over two causes, and until now it printed one fix for both.
+ * `@ultimat3/i18n`'s is written for the app whose `defineCatalogs()` call is in a module nothing
+ * imports — "move it into packages/i18n/src/index.ts (where `x new` puts it)". For a locale added
+ * by `x i18n add` the call is ALREADY there and the locale is simply not in its `locales:` map, so
+ * that instruction names an edit with nothing to perform: an agent following it verbatim changes
+ * nothing, re-runs, and is red again, on the command whose whole job is adding a locale (#F4).
+ *
+ * The condition is narrow enough that the finding never has to be argued with — the index exists,
+ * and the locale's tag appears nowhere in it — and the replacement is a command that performs the
+ * registration rather than describing it.
+ */
+export function unregisteredFix(
+  locale: string,
+  index: string | undefined,
+): { readonly fix?: string } {
+  if (index === undefined) return {};
+  // The index is GENERATED (`i18nIndex`), so the one spelling that matters is the import it writes
+  // — `catalogs/<tag>.json`. Matching a bare tag instead would read `en` out of the word `key` and
+  // report a registered locale as unregistered, which is the direction that costs trust.
+  if (index.includes(`${CATALOG_ROOT.split('/').pop() ?? 'catalogs'}/${locale}.json`)) return {};
+  return {
+    fix: `x i18n sync ${locale}   # re-derives ${I18N_INDEX_PATH} from the catalogs on disk`,
+  };
+}
+
 /**
  * `⟦key⟧` — `@ultimat3/i18n`'s own loud miss, spelled ONCE for the whole CLI. `x i18n sync <default>`
  * writes it and the two checks below refuse it, so a second spelling would be a placeholder one

package/src/island-bundle.ts

@@ -10,7 +10,6 @@ import { renderThrowable } from '@ultimat3/core';
 import { ISLAND_EXTENSION, IslandInvalidError, islandModuleId } from '@ultimat3/render';
 import { contentHash } from '@ultimat3/render/server';
 import { IslandBuildFailedError } from './errors';
-import { solidProductionPlugin } from './island-solid-production';
 import { islandStylesPlugin } from './island-styles';
 import { solidJsxPlugin } from './solid-loader';
 
@@ -84,12 +83,24 @@ async function buildOne(root: string, file: string): Promise<IslandChunk> {
       // classic `React.createElement` — emitted into a browser chunk that imports no React, with
       // `success: true` and no log. Every island shipped that way through five majors.
       //
-      // The other two close the same shape of failure — a wrong answer `Bun.build` reports as
-      // `success: true`: without the second, `target: 'browser'` resolves the `development`
-      // export condition and the chunk carries Solid's dev build; without the third, Bun's file
-      // loader resolves a `.module.scss` to its asset PATH, so `styles['x']` is `undefined` and
-      // every element renders unclassed.
-      plugins: [solidJsxPlugin, solidProductionPlugin, islandStylesPlugin],
+      // The second closes the same shape of failure — a wrong answer `Bun.build` reports as
+      // `success: true`: without it, Bun's file loader resolves a `.module.scss` to its asset
+      // PATH, so `styles['x']` is `undefined` and every element renders unclassed.
+      plugins: [solidJsxPlugin, islandStylesPlugin],
+      // The third one, and it is a `define` rather than the plugin this used to be: Bun selects
+      // the `development`/`production` export condition from the BUILD PROCESS's own `NODE_ENV`,
+      // and a defined `process.env.NODE_ENV` overrides it. Measured on 1.4.0, `solid-js` plus
+      // `solid-js/web` plus `solid-js/store`: unset → dev build, `test` → dev build, `production`
+      // → production build, this line → production build in all three, byte for byte.
+      //
+      // So without it a chunk built anywhere a container did not run — `x dev`, `x build` on a
+      // laptop, `bun test` — ships Solid's development build, and the island's own
+      // `process.env.NODE_ENV` reads `"development"` in the file a browser downloads.
+      //
+      // Pinned rather than inherited, because an island chunk is only ever built to be shipped:
+      // `x dev` serves the same chunk the container does, and bytes that depend on the ambient
+      // NODE_ENV are a content hash and a byte budget measured on a build nobody ships.
+      define: { 'process.env.NODE_ENV': '"production"' },
     });
   } catch (error) {
     throw new IslandBuildFailedError({ file, logs: describeBuildError(error) });

package/src/mcp-errors.ts

@@ -99,6 +99,18 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_STORAGE_UNWRITABLE: 'x doctor --json',
   X_STORAGE_SECRET_DEV: 'export STORAGE_SIGNING_SECRET="$(openssl rand -hex 32)"',
   X_MANIFEST_STALE: 'x manifest --json',
+  // The file itself, absent. One command writes it, and `bin/setup` now runs that command — so
+  // the fix here is the same one the gate's finding carries rather than a second phrasing.
+  X_MANIFEST_MISSING: 'x manifest --json',
+  // `@ultimat3/policy`'s code, and the CLI is the surface an agent reaches it from: `x policy list`
+  // is the only thing that prints the set the permission is missing from. The declare-it half is
+  // an edit to the app's own `definePermissions([...])`, which no command can perform.
+  X_PERMISSION_UNKNOWN:
+    'x policy list --json   # then add the permission to the app definePermissions([...]) call, or fix the typo',
+  // `@ultimat3/db`'s code, reported by `x doctor`'s probe. Both branches of db's own fix are an
+  // environment edit, so the runnable half is the probe that says which one is needed.
+  X_DB_UNAVAILABLE:
+    'x doctor --json   # set DATABASE_URL to a reachable Postgres url, or unset it for embedded PGlite',
   // `--target static`, not a bare `x build`: `--target` defaults to `docker`, and only the static
   // target runs `apps/web/prerender.ts` — the one caller of `writeBuildStats`. Without the flag
   // this fix builds an image, writes no `.x/build-stats.json`, and the next `x verify` reports the

package/src/messages.ts

@@ -140,7 +140,12 @@ const CATALOG = {
   // `.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.
-  'cli.new.done': 'created {name} — next: cd {name} && bin/setup && x dev',
+  // `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',
   // 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.

package/src/parse.ts

@@ -47,6 +47,19 @@ export interface CommandSpec {
    * sorted first. A command with no defensible default omits this and the parser refuses instead.
    */
   readonly defaultSubcommand?: string;
+  /**
+   * Whether a first word that is NOT a subcommand is an ARGUMENT to `defaultSubcommand` rather
+   * than a misspelt one. Declared per command, never inferred, because only some commands can say
+   * it truthfully: `x errors X_PERMISSION_UNKNOWN` can only be a code, and `x jobs 4f2a` is
+   * genuinely ambiguous with `show`, so an unconditional fallback would turn `x jobs <id>` into a
+   * silent `x jobs ls` that ignores the id.
+   *
+   * `x errors X_PERMISSION_UNKNOWN --json` answered `X_CLI_UNKNOWN_COMMAND … fix: x help`, and
+   * `x help` prints `errors  an X_* code, explained` — which reads as exactly the form that was
+   * refused (#F16). A near miss is still refused with its suggestion, so `x errors explan X_FOO`
+   * does not quietly become a lookup of the code `explan`.
+   */
+  readonly defaultSubcommandTakesPositional?: boolean;
   /**
    * A closed set the FIRST positional must come from, where the command has one. Declarative only:
    * the parser leaves positionals to the command, because `x test`'s own `readOnlyType` already
@@ -232,12 +245,16 @@ export function parseArgs(argv: readonly string[], specs: readonly CommandSpec[]
   // asking what the usage is, on every command that takes a subcommand. Help is answered by
   // `dispatch`, which needs only the command name.
   const help = flags.get('help') === true;
-  const subcommand = help ? undefined : readSubcommand(spec, positionals);
+  const resolved = help ? NO_SUBCOMMAND : readSubcommand(spec, positionals);
+  const subcommand = resolved.name;
   if (subcommand !== undefined) assertFlagsApply(spec, subcommand, given, flags);
   return {
     command: spec.name,
     subcommand,
-    positionals: subcommand === undefined ? positionals : positionals.slice(1),
+    // `consumed`, never `subcommand !== undefined`: a default subcommand the caller did not TYPE
+    // leaves its first positional in place, which is what makes `x errors X_DB_DRIFT` the same
+    // invocation as `x errors explain X_DB_DRIFT` instead of one with its argument eaten.
+    positionals: resolved.consumed ? positionals.slice(1) : positionals,
     flags,
     json: flags.get('json') === true,
     help,
@@ -278,16 +295,32 @@ function splitInline(raw: string): [string, string | undefined] {
   return [raw.slice(0, eq), raw.slice(eq + 1)];
 }
 
-function readSubcommand(spec: CommandSpec, positionals: readonly string[]): string | undefined {
+/** Which subcommand ran, and whether the caller's first positional is what named it. */
+interface ResolvedSubcommand {
+  readonly name: string | undefined;
+  readonly consumed: boolean;
+}
+
+const NO_SUBCOMMAND: ResolvedSubcommand = { name: undefined, consumed: false };
+
+function readSubcommand(spec: CommandSpec, positionals: readonly string[]): ResolvedSubcommand {
   const allowed = spec.subcommands;
-  if (allowed === undefined || allowed.length === 0) return undefined;
+  if (allowed === undefined || allowed.length === 0) return NO_SUBCOMMAND;
   const token = positionals[0];
   if (token === undefined) {
-    if (spec.defaultSubcommand !== undefined) return spec.defaultSubcommand;
+    if (spec.defaultSubcommand !== undefined) {
+      return { name: spec.defaultSubcommand, consumed: false };
+    }
     throw new MissingSubcommandError({ command: spec.name, known: allowed });
   }
-  if (allowed.includes(token)) return token;
+  if (allowed.includes(token)) return { name: token, consumed: true };
   const suggestion = nearestName(token, allowed);
+  // The declared fallback, and only past the near-miss guard: a word within `nearestName`'s edit
+  // budget of a real subcommand is a typo, and reading it as the default subcommand's argument
+  // would answer a question nobody asked.
+  if (spec.defaultSubcommandTakesPositional === true && suggestion === undefined) {
+    return { name: spec.defaultSubcommand, consumed: false };
+  }
   throw new UnknownCommandError(
     suggestion === undefined
       ? { path: `${spec.name} ${token}`, known: allowed }

package/src/port-probe.ts

@@ -0,0 +1,22 @@
+// Can this process bind that port? One implementation, because two commands ask it and they must
+// not disagree: `x doctor` reports it as a finding, and `startSync` asks it after a bind failure to
+// name the real cause instead of rendering a caught `Error` into a refusal.
+
+/**
+ * Binds and immediately releases. `Bun.serve({ port: 0 })` ALWAYS succeeds — the kernel picks —
+ * so 0 is answered `true` without opening anything: a probe that cannot fail is worse than none,
+ * and `x dev --port 0` genuinely has no port to be in use.
+ */
+export async function portFree(port: number): Promise<boolean> {
+  if (port === 0) return true;
+  try {
+    const server = Bun.serve({ port, fetch: () => new Response('') });
+    await server.stop(true);
+    return true;
+  } catch {
+    // Deliberately swallowed and never rendered: the caught value is `Bun.serve`'s own
+    // `Failed to start server. Is port N in use?`, and interpolating it into a `cause:` is exactly
+    // what `scripts/catch-render.ts` refuses. The ANSWER is the boolean; the caller owns the words.
+    return false;
+  }
+}

package/src/serve.ts

@@ -28,6 +28,7 @@ import { appManifest } from './app-manifest';
 import { assetRoutes } from './dev-assets';
 import { startQueue } from './dev-queue';
 import { appRoutes } from './dev-render';
+import { replicaOverrides } from './dev-replica';
 import type { RunningRoles, WebBinding } from './dev-roles';
 import { startRoles } from './dev-roles';
 import type { RunningServices } from './dev-runtime';
@@ -317,6 +318,7 @@ async function bootRoles(boot: {
   // fixed 9090 would fail the next suite to boot beside it. An environment that names the port
   // still wins — that is the deploy talking.
   const metricsPort = metricsPortFor(options.env, port, options.metricsPort);
+  const replicaOverride = replicaOverrides(options.runtime, runtime.services.db, options.env);
   const running = await startRoles({
     roles: [role],
     port,
@@ -332,7 +334,11 @@ async function bootRoles(boot: {
     // process and `x dev` cannot answer a browser differently.
     root: options.root,
     http: CONTAINER_BINDING,
-    ...(options.runtime === undefined ? {} : { overrides: options.runtime }),
+    // The read-replica scope rides in FRONT of whatever the host supplied, or the host's own value
+    // passes through untouched. `DATABASE_REPLICA_URL` was read by no booted process before this:
+    // `defaultClient()` is the one composer of a replicated pair and it runs only when an app
+    // installed no client, which no framework boot leaves true (`dev-queue.ts`).
+    ...(replicaOverride === undefined ? {} : { overrides: replicaOverride }),
   });
   acquired.push(() => running.stop());
   return {

package/src/shot-browser.ts

@@ -0,0 +1,84 @@
+// Which browser a `x shot` run gets: start one in this container, or ATTACH to one somebody else is
+// running. Three rules over plain inputs and no `ParsedArgs`, so each is testable without a boot —
+// the `cmd-jobs.ts` / `jobs-report.ts` split, repeated for the one decision that is easy to get
+// silently wrong.
+
+import {
+  browserBinaryExists,
+  cdpUrlFrom,
+  cdpUrlProblem,
+  executablePathFrom,
+} from './browser-launcher';
+import { BadFlagError } from './errors';
+
+/** A runnable example, not a placeholder: every refusal below hands one of these back. */
+const CDP_FIX = 'x shot / --cdp-url wss://cdp.example.com/session/abc';
+
+/**
+ * Exactly one of these is set. `undefined` on both is the ordinary local run where the library
+ * finds its own Chrome — which is why neither is required rather than a union of two shapes.
+ */
+export interface ShotBrowserChoice {
+  /** Attach here. When set, nothing about a local executable was read. */
+  readonly cdpUrl?: string | undefined;
+  /** Launch this. Already proved to exist on disk. */
+  readonly executablePath?: string | undefined;
+}
+
+export interface ShotBrowserInput {
+  /** `--cdp-url` as typed. The env fallback is applied here, not by the caller. */
+  readonly cdpFlag?: string | undefined;
+  /** `--browser` as typed, before `PUPPETEER_EXECUTABLE_PATH` / `CHROME_PATH`. */
+  readonly browserFlag?: string | undefined;
+  readonly env: Readonly<Record<string, string | undefined>>;
+}
+
+/**
+ * Decided before anything boots, because a typo must not cost an embedded Postgres — and, on the
+ * attach path, a provider session — to report.
+ *
+ * The three rules, each chosen against a silent failure rather than for symmetry:
+ *
+ * 1. **Both FLAGS is refused, never ranked.** One names a Chrome to START and the other says the
+ *    browser is somebody else's, so honouring either ignores what was typed.
+ * 2. **An exported `SCRAPE_CDP_URL` loses to `--browser`.** A shell-wide default is not a typed
+ *    intent. The alternative is a flag that parses, reports nothing and quietly attaches somewhere
+ *    else — the `--critical` defect class `flag-reads.ts` exists for and cannot see here, because
+ *    the flag IS read.
+ * 3. **On an attach, no executable is read at all.** Checking the filesystem for a binary this run
+ *    will never execute is how a correct remote capture gets refused on a box with no Chrome.
+ */
+export function shotBrowserChoice(input: ShotBrowserInput): ShotBrowserChoice {
+  if (input.cdpFlag !== undefined && input.browserFlag !== undefined) {
+    throw new BadFlagError({
+      flag: 'cdp-url',
+      command: 'shot',
+      reason:
+        '--browser names a Chrome to launch here and --cdp-url attaches to one already running',
+      fix: CDP_FIX,
+    });
+  }
+  const cdpUrl = input.browserFlag === undefined ? cdpUrlFrom(input.cdpFlag, input.env) : undefined;
+  if (cdpUrl !== undefined) {
+    const problem = cdpUrlProblem(cdpUrl);
+    if (problem !== undefined) {
+      throw new BadFlagError({
+        flag: 'cdp-url',
+        command: 'shot',
+        reason: `"${cdpUrl}" ${problem}`,
+        fix: CDP_FIX,
+      });
+    }
+    return { cdpUrl };
+  }
+  const executablePath = executablePathFrom(input.browserFlag, input.env);
+  if (executablePath !== undefined && !browserBinaryExists(executablePath)) {
+    throw new BadFlagError({
+      flag: 'browser',
+      command: 'shot',
+      reason: `no executable at "${executablePath}"`,
+      fix: 'x shot / --browser /usr/bin/chromium',
+    });
+  }
+  return executablePath === undefined ? {} : { executablePath };
+}

package/src/templates/scaffold-app.ts

@@ -7,6 +7,7 @@ import type { GeneratedFile, NameSet } from './naming';
 import { apiFiles } from './scaffold-api';
 import { authFiles } from './scaffold-auth';
 import { entryFiles } from './scaffold-entries';
+import { httpFiles } from './scaffold-http';
 import { icon } from './scaffold-icon';
 import { rolesFiles } from './scaffold-roles';
 
@@ -401,6 +402,7 @@ export function appFiles(app: NameSet, example: boolean): readonly GeneratedFile
     // The app's role map, beside the actor that reads it. `shared/` and not a feature folder:
     // `defineRoles()` merges, so a per-feature call is legal and is how an app ends up with no
     // answer to "which roles exist?" — see `scaffold-roles.ts`.
+    ...httpFiles(app),
     ...rolesFiles(),
     { path: 'apps/admin/package.json', contents: adminPackage(app) },
     { path: 'apps/admin/tsconfig.json', contents: tsconfig() },

package/src/templates/scaffold-docs.ts

@@ -63,9 +63,9 @@ Built with [Ultimate](https://github.com/developerz-ai/ultimate). Bun-only, Post
 ## 🚀 Start
 
 \`\`\`sh
-bin/setup     # prerequisites, deps, env, the first migration, migrate, seed
-x dev         # all roles in one process, embedded Postgres, /_x mounted
-x verify      # the gate: typecheck, lint, boundaries, tests, drift, budgets
+bin/setup     # prerequisites, deps, env, the first migration, migrate, seed, the manifest
+bin/dev       # all roles in one process, embedded Postgres, /_x mounted
+bin/check     # the gate: typecheck, lint, boundaries, tests, drift, budgets
 \`\`\`
 
 \`packages/db/migrations\` starts empty and \`x db gen\` is its only writer — \`bin/setup\` runs
@@ -104,7 +104,13 @@ bunx x db migrate "$@"
 # \`postgres:\` DATABASE_URL and so dies on a clone with no Postgres — one line after reporting a
 # successful migration.
 bunx x db seed
-echo "setup complete — next: x dev"
+# The file \`AGENTS.md\` line 3 tells an agent facts live in, and \`x dev\` prints the path of. It
+# is a projection of the loaded app, so \`x new\` cannot write it — node_modules does not exist
+# yet — and nothing else ever ran the command: after \`x new\`, \`bin/setup\` and all 13
+# generators, \`find . -name '*.manifest.json'\` returned nothing while \`x verify\` reported
+# \`\u2713 manifest\`. \`x verify\`'s manifest step now refuses its absence (X_MANIFEST_MISSING).
+bunx x manifest
+echo "setup complete — next: bin/dev"
 `;
 
 const binDev = (): string => `#!/usr/bin/env bash

package/src/templates/scaffold-http.ts

@@ -0,0 +1,84 @@
+// The scaffold's answer to "how does this server bind, and what does it admit?", which it did not
+// have. `configureHttp()` is the one registration site an app has for CORS origins, the body
+// limit, the request deadline, the in-flight ceiling and the rate-limit buckets — and until it
+// shipped, the only `HttpConfig` any process built was a fixed literal inside `@ultimat3/cli`.
+//
+// `DEFAULT_CORS.origins` is `[]`, so a scaffolded app refuses every cross-origin browser call. The
+// most common homework-scale need — a Vite front end on `localhost:5173` calling the app — was
+// inexpressible; now it is one uncommented line, and this file is where an agent finds it.
+
+import type { GeneratedFile, NameSet } from './naming';
+
+const httpConfig = (
+  app: NameSet,
+): string => `// What this app declares about HTTP. Module scope IS the wiring: the boot scan imports every
+// module under \`apps/*\` before a listener binds, and \`x dev\` and the container both read the
+// configured value back at start — the same seam \`app/auth/dev-actor.ts\` installs through.
+//
+// The BOOT lays its own facts over whatever this says: \`port\`, \`hostname\`, \`dev\`, \`buildId\`,
+// \`signInPath\`, \`trustProxy\`, \`trustedProxyHops\` and \`rateLimit.scope\` are all facts about the
+// PROCESS, so writing one here is a type error rather than a value silently overwritten at the
+// next boot.
+
+import { configureHttp } from '@ultimat3/http';
+
+configureHttp({
+  // EMPTY by default, and that is a refusal rather than an oversight: an origin list is a list of
+  // sites allowed to make credentialed calls with this app's cookies, and a framework may not
+  // guess one. A browser app served from another origin — a Vite dev server, a separate marketing
+  // site — goes here, exactly spelled, scheme and port included:
+  //
+  //   cors: { origins: ['http://localhost:5173'] },
+  //
+  // \`credentials\` is \`true\` by default, and \`'*'\` with credentials is the one combination a
+  // browser refuses — \`@ultimat3/http\` refuses it here instead, at the moment you can act on it.
+  cors: { origins: [] },
+  // The two bounds a request is measured against. Both are the framework's defaults spelled out,
+  // so raising one for an endpoint that really does take a 4 MB CSV or five minutes is an edit to
+  // a number that is already in front of you rather than a search for the knob.
+  bodyLimitBytes: 1024 * 1024,
+  requestTimeoutMs: 30_000,
+});
+
+/** Named so the module has an export; importing it for the side effect alone is the wiring. */
+export const ${app.camel}Http = 'configured';
+`;
+
+const httpConfigTest =
+  (): string => `// The declaration reached the registry. \`configureHttp()\` is a module-scope side effect, so the
+// only thing that can go wrong is nobody importing the module — which is exactly how a shipped app
+// rendered every string as ⟦key⟧ for a whole release (issue #249), one seam along.
+import { configuredHttp, resetHttpConfig } from '@ultimat3/http';
+import { expect, unitTest } from '@ultimat3/testing';
+import './http';
+
+unitTest('importing the module IS the registration', () => {
+  const declared = configuredHttp();
+  expect(declared).toBeDefined();
+  // The list is empty on a fresh scaffold and that is the shipped default; what is asserted is
+  // that the KEY reaches the boot, so adding an origin to it takes effect.
+  expect(declared?.cors?.origins).toEqual([]);
+});
+
+unitTest('the boot-owned keys are absent — the boot measures them, an app can only guess', () => {
+  const declared = configuredHttp() ?? {};
+  for (const key of ['port', 'hostname', 'dev', 'buildId', 'signInPath']) {
+    expect({ key, declared: Object.hasOwn(declared, key) }).toEqual({ key, declared: false });
+  }
+});
+
+// The registration is process-global, so a suite that left it set would hand the next file this
+// app's config. \`resetHttpConfig()\` is the seam; this is the one place it is called.
+unitTest('and it is resettable, so no test file inherits the server config of another', () => {
+  resetHttpConfig();
+  expect(configuredHttp()).toBeUndefined();
+});
+`;
+
+/** `apps/web/app/http.ts` and its test. Written by `x new`, with or without the example slice. */
+export function httpFiles(app: NameSet): readonly GeneratedFile[] {
+  return [
+    { path: 'apps/web/app/http.ts', contents: httpConfig(app) },
+    { path: 'apps/web/app/http.test.ts', contents: httpConfigTest() },
+  ];
+}

package/src/templates/scaffold-repo.ts

@@ -82,6 +82,21 @@ const rootPackage = (app: NameSet, version: string): string => `{
 }
 `;
 
+/**
+ * `"incremental": true` is ONE line and it is the difference between a 4.9s typecheck and a 92s
+ * one. `x verify`'s first step is `tsc -b`, and `-b` decides "up to date?" by comparing emitted
+ * OUTPUTS against inputs — with `noEmit` and no `composite`/`references`, the output it looks for
+ * is an `app.config.js` that will never exist (`Project 'tsconfig.json' is out of date because
+ * output file 'app.config.js' does not exist`), so every run rebuilt the whole program from
+ * scratch, forever. Measured on a 166-file scaffold with no source change between runs: 92s wall
+ * / 43s user CPU without it, 4.9s / 8.8s warm with it, and the whole gate at 12s rather than
+ * 24-71s. This was the only tree in the framework without incremental typechecking — the repo
+ * root has 32 `references` and `examples/dummy/tsconfig.json` sets `composite`.
+ *
+ * The note lives HERE and not in the emitted file, for the reason `biome.json` below gives: an
+ * app author has no use for eight lines of framework archaeology in their own tsconfig, and
+ * `*.tsbuildinfo` is already in the scaffold's `.gitignore`.
+ */
 const rootTsconfig = (app: NameSet): string => `{
   "compilerOptions": {
     "target": "ES2023",
@@ -101,6 +116,7 @@ const rootTsconfig = (app: NameSet): string => `{
     "isolatedModules": true,
     "skipLibCheck": true,
     "noEmit": true,
+    "incremental": true,
     "resolveJsonModule": true,
     "jsx": "preserve",
     "jsxImportSource": "solid-js"
@@ -258,6 +274,10 @@ const SCAFFOLD_FLOOR: readonly VerifyStepName[] = [
   'eval',
   'drift',
   'budgets',
+  // Always applicable to a scaffolded app — it has an `app.config.ts`, roles and two guarded
+  // routes — so a run that reports it skipped is a gate that lost the step, not an app with
+  // nothing to check. It is the step that would have caught the 500 `x new` used to ship.
+  'policy',
   'manifest',
 ];
 

package/src/templates/scaffold-roles.ts

@@ -19,7 +19,15 @@ const rolesSource =
 // \`x g policy <feature>\` declares \`<feature>:read\` and \`<feature>:write\`. Granting them is this
 // file's job — a permission no role holds is one no actor can ever exercise.
 
-import { defineRoles } from '@ultimat3/policy';
+import { definePermissions, defineRoles } from '@ultimat3/policy';
+
+// DECLARED before it is granted, and that order is the whole point. \`can()\` calls
+// \`assertPermission\`, which refuses a name no \`definePermissions()\` call registered
+// (X_PERMISSION_UNKNOWN) — and \`defineRoles()\` does NOT: it took \`grants: ['dashboard:read']\`
+// in silence while nothing declared it, so every scaffolded app answered HTTP 500 on /dashboard
+// and /admin from its first \`x dev\`, under a green gate. A permission a role grants and a
+// permission a route requires both belong here.
+export const appPermissions = definePermissions(['admin:read', 'dashboard:read']);
 
 export const roles = defineRoles({
   member: {
@@ -37,9 +45,9 @@ export const roles = defineRoles({
 const rolesTest =
   (): string => `// The app's role map, expanded: what each role grants once inheritance is flattened, and which
 // roles hold a given permission. An undeclared role must grant nothing at all.
-import { expandRoles, rolesGranting } from '@ultimat3/policy';
+import { expandRoles, isKnownPermission, rolesGranting } from '@ultimat3/policy';
 import { expect, unitTest } from '@ultimat3/testing';
-import { roles } from './roles';
+import { appPermissions, roles } from './roles';
 
 // The map is passed explicitly rather than read off the module-global one: a test that depended on
 // which module imported first would pass alone and fail inside a suite.
@@ -57,6 +65,26 @@ unitTest('every permission the app enforces is held by some role', () => {
   expect(rolesGranting('dashboard:read', roles)).toEqual(['admin', 'member']);
   expect(rolesGranting('admin:read', roles)).toEqual(['admin']);
 });
+
+// The assertion whose absence shipped a 500. Expansion above proves the MAP is right and says
+// nothing about the registry \`can()\` actually consults: a grant naming a permission no
+// \`definePermissions()\` declared expands perfectly and then throws X_PERMISSION_UNKNOWN on the
+// first request to the route that requires it.
+unitTest('every granted permission is in the registry can() asks', () => {
+  for (const permission of new Set(Object.values(roles).flatMap((role) => role.grants))) {
+    expect({ permission, known: isKnownPermission(permission) }).toEqual({
+      permission,
+      known: true,
+    });
+  }
+});
+
+unitTest('the routes this app ships require permissions this app declares', () => {
+  // The two \`defineRoute({ policy: { permission } })\` values \`x new\` writes. \`RouteGuard\`
+  // keeps a bare string, so nothing but this holds them to the declared set.
+  expect(appPermissions.has('dashboard:read')).toBe(true);
+  expect(appPermissions.has('admin:read')).toBe(true);
+});
 `;
 
 /** `apps/web/shared/roles.ts` and its test. Written by `x new`, with or without the example slice. */