@ultimat3/cli 11.3.0 → 13.0.0

package/src/framework-schema.ts

@@ -0,0 +1,152 @@
+// The framework's OWN tables, as one table: which package declares each, which relations it
+// creates, and the DDL. One list, read by the one applier, so "installed in dev and not in
+// production" is not a state this framework can be in — `startQueue` is on every boot path there
+// is, `ROLE=migrate` included.
+//
+// A framework table an app has to install by hand is a table that will be missing in production on
+// the one code path that needs it, and it surfaces as a Postgres `42P01` from inside a worker.
+
+import { SQL_AUDIT_TABLE, SQL_IDEMPOTENCY_TABLE } from '@ultimat3/action';
+import { AUTH_TABLE_NAMES, AUTH_TABLES, SQL_AUTH_LIMIT_TABLES } from '@ultimat3/auth';
+import { SQL_RATE_LIMIT_TABLE } from '@ultimat3/http';
+import { SQL_JOBS_TABLE } from '@ultimat3/jobs';
+import { SQL_NOTIFY_DELIVERIES_TABLE, SQL_NOTIFY_INBOX_TABLE } from '@ultimat3/notify';
+import { FrameworkSchemaFailedError } from './schema-errors';
+
+export interface FrameworkSchema {
+  /** The package whose source declares the DDL — where to look when a column is wrong. */
+  readonly pkg: string;
+  /**
+   * Every relation this entry creates. Read by the refusal below, so an operator learns which
+   * tables were being installed rather than only which statement failed — and pinned against the
+   * DDL text by `framework-schema.test.ts`, so a row cannot claim a table its SQL never creates.
+   */
+  readonly tables: readonly string[];
+  /** One or more statements each; `;` separates. */
+  readonly ddl: readonly string[];
+}
+
+/**
+ * Applied unconditionally, whether or not this boot installs a store behind it.
+ *
+ * `create table if not exists` on an unused table costs one round trip at boot. The alternative
+ * costs a request: a store installed later must never be the thing that discovers the schema was
+ * never applied, and several of these are installed AFTER this runs — `defineAuth` builds its
+ * limiter when the app's modules import, and `setNotifyStores` is an app's boot line.
+ *
+ * Ordered so a foreign key never precedes its target. Only `AUTH_TABLES` has any, and they are
+ * internal to that entry, which is why it ships as an ordered list rather than one string.
+ */
+export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
+  Object.freeze({
+    pkg: '@ultimat3/jobs',
+    tables: Object.freeze([
+      'x_jobs',
+      'x_job_steps',
+      'x_backfills',
+      'x_outbox',
+      'x_scheduler_state',
+      'x_scheduler_leader',
+      'x_job_leases',
+      'x_job_events',
+    ]),
+    ddl: Object.freeze([SQL_JOBS_TABLE]),
+  }),
+  Object.freeze({
+    pkg: '@ultimat3/action',
+    tables: Object.freeze(['x_idempotency']),
+    ddl: Object.freeze([SQL_IDEMPOTENCY_TABLE]),
+  }),
+  // The DDL only, and deliberately NO `setAuditSink`: there is no default audit sink on purpose,
+  // so `X_AUDIT_SINK_MISSING` keeps firing at boot for an app that declares `audit: true` and
+  // installs none.
+  Object.freeze({
+    pkg: '@ultimat3/action',
+    tables: Object.freeze(['x_audit']),
+    ddl: Object.freeze([SQL_AUDIT_TABLE]),
+  }),
+  Object.freeze({
+    pkg: '@ultimat3/http',
+    tables: Object.freeze(['x_rate_limit']),
+    ddl: Object.freeze([SQL_RATE_LIMIT_TABLE]),
+  }),
+  Object.freeze({
+    pkg: '@ultimat3/auth',
+    tables: Object.freeze(['x_auth_failures', 'x_auth_lockouts']),
+    ddl: Object.freeze([SQL_AUTH_LIMIT_TABLES]),
+  }),
+  /**
+   * The five tables `BuiltinAdapter` reads, and the oldest hole in this list.
+   *
+   * `packages/auth/src/tables.ts` exports them "so an app can paste them into a migration", and
+   * nothing in the framework has ever applied them — while `x db gen` diffs `describeEntities()`
+   * and these are not `entity()` declarations, so neither half was a file anybody could
+   * hand-write. `examples/dummy/CLAUDE.md` records the consequence in its own words: nobody can
+   * hold a session in the reference app. Applied here on exactly the rule the rate-limit and audit
+   * rows already follow.
+   *
+   * `AUTH_TABLE_NAMES` rather than five literals: @ultimat3/auth already publishes the list, and a
+   * second copy is a second thing to keep right when a table is added.
+   */
+  Object.freeze({
+    pkg: '@ultimat3/auth',
+    tables: AUTH_TABLE_NAMES,
+    ddl: AUTH_TABLES,
+  }),
+  /**
+   * The delivery ledger is what stops a replayed notifier job sending twice, and it is the entry
+   * whose absence is least visible: without the table the ledger's first `claim` raises `42P01`
+   * from inside a worker, which reads as a dead-lettered notification rather than as a missing
+   * schema. Installed whether or not this boot calls `setNotifyStores`, for the same reason as
+   * every row above it — that call is an APP's boot line and runs after this one.
+   */
+  Object.freeze({
+    pkg: '@ultimat3/notify',
+    tables: Object.freeze(['x_notify_deliveries']),
+    ddl: Object.freeze([SQL_NOTIFY_DELIVERIES_TABLE]),
+  }),
+  Object.freeze({
+    pkg: '@ultimat3/notify',
+    tables: Object.freeze(['x_notify_inbox']),
+    ddl: Object.freeze([SQL_NOTIFY_INBOX_TABLE]),
+  }),
+]);
+
+/** Every relation this boot creates, flattened. */
+export const frameworkTableNames = (): readonly string[] =>
+  FRAMEWORK_SCHEMA.flatMap((entry) => [...entry.tables]);
+
+/**
+ * PGlite speaks the extended protocol, which carries one statement per round trip, so the DDL is
+ * applied statement by statement. Safe to split on `;`: every constant is fixed, with no semicolon
+ * inside a literal, and each package's own SQL test is where that stays true.
+ */
+export const schemaStatements = (ddl: readonly string[]): readonly string[] =>
+  ddl.flatMap((text) => text.split(';')).filter((statement) => statement.trim().length > 0);
+
+/** One statement, executed. The caller owns the connection; this file owns no database import. */
+export type SchemaExecutor = (statement: string) => Promise<unknown>;
+
+/**
+ * Apply every entry, in order, and answer what was created.
+ *
+ * The refusal is the point of the `pkg`/`tables` columns: a raw `permission denied for schema
+ * public` names neither the framework table it was creating nor the package that wants it, and a
+ * boot failure is read by an operator who has no source tree open.
+ */
+export async function applyFrameworkSchema(execute: SchemaExecutor): Promise<readonly string[]> {
+  for (const entry of FRAMEWORK_SCHEMA) {
+    for (const statement of schemaStatements(entry.ddl)) {
+      try {
+        await execute(statement);
+      } catch (error) {
+        throw new FrameworkSchemaFailedError({
+          pkg: entry.pkg,
+          tables: entry.tables,
+          cause: error,
+        });
+      }
+    }
+  }
+  return frameworkTableNames();
+}

package/src/i18n-index.ts

@@ -0,0 +1,40 @@
+// The one writer of `packages/i18n/src/index.ts`, shared by `x g` and `x i18n add|sync`.
+//
+// A catalog file existing on disk and the app being able to SELECT that locale are two different
+// facts, and only this closes the gap: the index hardcodes `locales: { en }`, so a locale whose
+// catalog nothing registered renders `⟦key⟧` — which the gate's `i18n` step refuses outright
+// (`X_CATALOG_UNREGISTERED`). `x i18n add fr` wrote the file, touched nothing else, and left
+// `x verify` red with a fix line that named an edit nobody could perform (#F4).
+
+// why: Bun has no synchronous existence check — `Bun.file(p).exists()` is async, and this decides
+// whether to write at all, before any await the caller could interleave with.
+import { existsSync } from 'node:fs';
+import { containedPath } from './generate-write';
+import { CATALOG_ROOT, i18nIndex } from './templates';
+
+export const I18N_INDEX_PATH = 'packages/i18n/src/index.ts';
+
+/** Every locale with a catalog on disk, sorted — the file names are the tags. */
+export async function catalogLocales(root: string): Promise<readonly string[]> {
+  const catalogDir = containedPath(root, CATALOG_ROOT);
+  if (!existsSync(catalogDir)) return [];
+  const locales: string[] = [];
+  for await (const entry of new Bun.Glob('*.json').scan({ cwd: catalogDir, absolute: false })) {
+    locales.push(entry.replace(/\.json$/, ''));
+  }
+  return locales.sort();
+}
+
+/**
+ * Re-derives the FULL locale set from `packages/i18n/catalogs/` — never just the locale one
+ * invocation asked for — and rewrites the index to match. It bypasses `writeFiles` on purpose:
+ * this file is a projection of the catalog directory, never app-authored content a conflict check
+ * should protect. An app with no i18n package (deleted, or never scaffolded) is left alone, and
+ * that is what `written` reports.
+ */
+export async function syncI18nIndex(root: string): Promise<boolean> {
+  const indexAbsolute = containedPath(root, I18N_INDEX_PATH);
+  if (!existsSync(indexAbsolute)) return false;
+  await Bun.write(indexAbsolute, i18nIndex(await catalogLocales(root)));
+  return true;
+}

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/index.ts

@@ -196,6 +196,15 @@ export type { FixHelper, FixScan } from './fix-scan';
 export { scanFixes, scanFixHelpers, scanFixSites } from './fix-scan';
 export type { DeclaredFlag } from './flag-reads';
 export { checkFlagReads, declaredFlags, readsFlag } from './flag-reads';
+export type { FrameworkSchema, SchemaExecutor } from './framework-schema';
+// The framework's own tables, as data. Exported so `scripts/` can read the applier's list without
+// re-deriving it — the shape a ratchet over declared-but-never-applied DDL needs.
+export {
+  applyFrameworkSchema,
+  FRAMEWORK_SCHEMA,
+  frameworkTableNames,
+  schemaStatements,
+} from './framework-schema';
 export type { Guard } from './guards';
 export { findingProblem, GUARD_DIR, guardFindings, guardPaths } from './guards';
 // The island bundler, and only its entry point. An island is the one module Ultimate ships to a
@@ -239,6 +248,7 @@ export { flagBool, flagList, flagString, GLOBAL_FLAGS, nearest, parseArgs } from
 export type { PrerenderedPage, PrerenderOptions, PrerenderReport } from './prerender';
 export { DEFAULT_ORIGIN, isPrerenderable, prerenderSite } from './prerender';
 export { COMMANDS, cliVersion, commandFor, SPECS } from './registry';
+export { FrameworkSchemaFailedError } from './schema-errors';
 export type { MigratedApp, ServedApp, ServeOptions, StartedApp } from './serve';
 export {
   CONTAINER_BINDING,

package/src/mcp-errors.ts

@@ -96,9 +96,24 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_RELEASE_VERSION_SKEW: 'bun run scripts/release.ts --bump patch --dry-run --json',
   // Two real remedies and the command cannot know which one this deployment wants, so it names
   // the one that inspects the binding rather than guessing between a volume and a bucket.
+  // `x db migrate --json` and not `x doctor`: this fires from inside `startQueue`, so the command
+  // that re-runs exactly the failing step is the migrate role, and it reports what it applied.
+  X_FRAMEWORK_SCHEMA_FAILED: 'x db migrate --json',
   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/schema-errors.ts

@@ -0,0 +1,28 @@
+// The one code raised while installing the framework's own tables. Apart from `errors.ts` for the
+// reason `packages/jobs/src/backfill-errors.ts` is apart from that package's: one file, one job,
+// and `errors.ts` is at 486 lines against the 500 the `filesize` step enforces. The code, its
+// title and its registration stay in `error-codes.ts`, where every other CLI code lives.
+
+import { renderThrowable, UltimateError } from '@ultimat3/core';
+
+/**
+ * A statement in `FRAMEWORK_SCHEMA` did not apply. Raised in place of the driver's own rejection,
+ * which names neither the framework table being created nor the package that wants it — and a boot
+ * failure is read by an operator with no source tree open.
+ *
+ * `renderThrowable` and never `${cause}`: a `catch` binding is annotated by nobody, and a pool
+ * rejection is routinely an object whose `toString` throws.
+ */
+export class FrameworkSchemaFailedError extends UltimateError {
+  constructor(input: { pkg: string; tables: readonly string[]; cause: unknown }) {
+    super({
+      code: 'X_FRAMEWORK_SCHEMA_FAILED',
+      cause: `${input.pkg} could not create ${input.tables.join(', ')}: ${renderThrowable(input.cause)}`,
+      // An EDIT plus the command that CONFIRMS it, which is the house shape for a repair the gate
+      // cannot perform: the two real causes are a role without `create`, and a relation of that
+      // name already present with an incompatible shape.
+      fix: `grant create on schema public to the role in DATABASE_URL, then re-run: x db migrate`,
+      meta: { pkg: input.pkg, tables: [...input.tables] },
+    });
+  }
+}

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/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() },
+  ];
+}