@ultimat3/cli 11.3.0 → 12.0.0

package/src/dev-replica.ts

@@ -0,0 +1,99 @@
+// Read-replica routing, WIRED. `@ultimat3/db` ships both halves and a booted process reached
+// neither, so the capability was shipped and unactivated — the "declared and never wired" class
+// this release exists to eliminate.
+//
+// Two things had to be false for it to route, and both were:
+//
+// 1. `defaultClient()` is the one place db composes `replicatedClient(primary, replica)` from
+//    `DATABASE_REPLICA_URL`, and it runs only from `baseClient()` — "the client an app installed
+//    none for". Every process the framework boots installs one: `dev-queue.ts` calls
+//    `setDbClient(createPgliteClient(…) | createPostgresClient({ url }))`, so `defaultClient()` was
+//    unreachable from `x dev`, from `apps/web/server.ts` and from every container role.
+// 2. Routing needs an OPEN scope as well as a configured replica, and nothing opened one.
+//
+// This file answers both from the boot, which is the only tier that may know about a request AND
+// about a pool. It is deliberately NOT a change to `@ultimat3/http`'s pipeline: that would make the
+// HTTP tier depend on `@ultimat3/db` — legal downward, and still a package that would then know
+// what a database is.
+
+import type { DbClient, PostgresClient } from '@ultimat3/db';
+import {
+  createPostgresClient,
+  REPLICA_URL_ENV,
+  replicatedClient,
+  withReplicaReads,
+} from '@ultimat3/db';
+import type { Middleware } from '@ultimat3/http';
+import type { ServiceBinding } from './dev-services';
+import type { RuntimeOverrides } from './runtime-overrides';
+
+export type ReplicaEnv = Readonly<Record<string, string | undefined>>;
+
+/**
+ * The replica url this boot should use, or `undefined`. Two conditions, and the second is the one
+ * a homework app depends on: an EMBEDDED database is PGlite in this process, which has no standby
+ * and never will, so a `DATABASE_REPLICA_URL` left over in a shell must not silently open a second
+ * pool beside it.
+ */
+export function replicaUrlFor(binding: ServiceBinding, env: ReplicaEnv): string | undefined {
+  if (binding.mode !== 'external') return undefined;
+  const url = env[REPLICA_URL_ENV];
+  return url === undefined || url.trim() === '' ? undefined : url;
+}
+
+/** What a boot has to hold on to: the ambient client, and the pool `stop()` must close. */
+export interface ReplicaAttachment {
+  /** What `setDbClient()` receives — the pair when one is configured, the primary otherwise. */
+  readonly client: DbClient;
+  /** The standby pool this boot opened, or nothing. `ReplicatedClient` has no `close()`. */
+  readonly replica: PostgresClient | undefined;
+}
+
+/**
+ * The primary as it is, or the primary with a standby behind it. Composed here rather than by
+ * calling `defaultClient()`, because that function builds its own primary from `DATABASE_URL` and
+ * this boot has already RESOLVED which database it is talking to (`resolveServices`) — asking the
+ * environment a second question is how a process ends up with two answers to "which database is
+ * this". The pieces are db's own, so the routing rule is still stated in one place.
+ */
+export function attachReplica(
+  primary: DbClient,
+  replicaUrl: string | undefined,
+): ReplicaAttachment {
+  if (replicaUrl === undefined) return { client: primary, replica: undefined };
+  const replica = createPostgresClient({ url: replicaUrl, applicationName: 'ultimate-replica' });
+  return { client: replicatedClient(primary, replica), replica };
+}
+
+/**
+ * The scope, opened once per request, OUTSIDE the handler — so a write early in a request pins
+ * every later read in it to the primary, which is what read-your-writes means. `compose()` wraps
+ * each route handler, and every read and write a request makes happens inside one.
+ *
+ * EMPTY when no replica is configured, and that is the whole cost argument: a homework app
+ * installs no middleware, allocates no scope object and enters no `AsyncLocalStorage` run per
+ * request. With one configured, the list is a single frame.
+ */
+export function replicaMiddleware(binding: ServiceBinding, env: ReplicaEnv): readonly Middleware[] {
+  if (replicaUrlFor(binding, env) === undefined) return [];
+  return [(request, ctx, next) => withReplicaReads(() => next(request, ctx))];
+}
+
+/**
+ * The boot's `RuntimeOverrides` with the scope middleware laid in FRONT of whatever a host
+ * supplied — `compose([a, b])` runs `a` outermost, and the scope must open outside every read and
+ * write the request makes or a write early in it cannot pin the reads after it.
+ *
+ * Returns the caller's own value UNCHANGED when no replica is configured, which is what keeps a
+ * homework app from paying for this: no key added, no empty array, nothing for `startRoles` to
+ * forward.
+ */
+export function replicaOverrides(
+  overrides: RuntimeOverrides | undefined,
+  binding: ServiceBinding,
+  env: ReplicaEnv,
+): RuntimeOverrides | undefined {
+  const middleware = replicaMiddleware(binding, env);
+  if (middleware.length === 0) return overrides;
+  return { ...overrides, middleware: [...middleware, ...(overrides?.middleware ?? [])] };
+}

package/src/dev-roles-fixture.ts

@@ -7,6 +7,7 @@
 
 import { noopPurgeDriver } from '@ultimat3/cache';
 import { resetLifecycle } from '@ultimat3/core';
+import { resetHttpConfig } from '@ultimat3/http';
 import {
   createMemoryDriver,
   createMemoryEventBus,
@@ -64,4 +65,10 @@ export function resetDevRolesState(): void {
   resetJobsFacade();
   resetTasks();
   resetLifecycle();
+  // `configureHttp()` is a process-global registration made at MODULE scope, so one file that
+  // loads an app leaves that app's CORS origins, body limit and buckets standing for every later
+  // file in the same `bun test` process — and a scaffolded app now ships such a module
+  // (`apps/web/app/http.ts`). Nothing is broken today; this is the same rule the four resets above
+  // already follow, applied to the fifth global before it is the one that costs an afternoon.
+  resetHttpConfig();
 }

package/src/dev-roles.ts

@@ -9,7 +9,13 @@
 import type { Role } from '@ultimat3/core';
 import { createContext, isRole, logger, ROLES } from '@ultimat3/core';
 import type { RateLimitStore, Route, ServerHandle, ServerHooks } from '@ultimat3/http';
-import { configuredAuthenticator, createServer, defineHttpConfig } from '@ultimat3/http';
+import {
+  configuredAuthenticator,
+  configuredHttp,
+  createServer,
+  defineHttpConfig,
+  mergeHttpConfig,
+} from '@ultimat3/http';
 import type { OutboxRelay, Scheduler, Worker } from '@ultimat3/jobs';
 import {
   createOutboxRelay,
@@ -257,37 +263,45 @@ function startWeb(options: StartRolesOptions): ServerHandle {
       ? {}
       : { middleware: options.overrides.middleware }),
     ...(store === undefined ? {} : { rateLimitStore: store }),
-    config: defineHttpConfig({
-      port: options.port,
-      dev: binding.dev,
-      buildId: options.buildId,
-      hostname: binding.hostname,
-      signInPath: options.signInPath ?? null,
-      // One declaration, never half of one: `defineHttpConfig` refuses `trustProxy` without hops.
-      ...(hops === null ? {} : { trustProxy: true, trustedProxyHops: hops }),
-      // `scope` is mandatory since @ultimat3/http made an undeclared limiter a boot error, and it
-      // is DERIVED from the store rather than hardcoded — a literal here would be a second
-      // declaration quietly contradicting the object beside it, and `assertRateLimitScope` holds
-      // the two halves together. It answered `'process'` on every real boot until `startServices`
-      // resolved a store, so the shipped chart's three `web` replicas enforced `login: { limit: 5 }`
-      // as fifteen attempts, with `x verify` green.
-      rateLimit: { scope: store?.scope ?? 'process' },
-      // Hashes, never `'unsafe-inline'`: a `render: 'static'` page is a file on disk, so
-      // nothing can stamp a per-response nonce into it, but its body is fixed and a hash is a
-      // function of that body. Read after `loadApp` — importing the app IS what registered them.
-      // BOTH directives, and the script half is the one that was missing: the hydration runtime
-      // is emitted inline in every document that carries an island, so `script-src 'self'` meant
-      // no island booted anywhere the policy is enforced — which is every container, and never
-      // `x dev`, where it is report-only.
-      security: {
-        csp: {
-          extend: {
-            'style-src': inlineStyleSources(options.inlineStyles ?? []),
-            'script-src': inlineScriptSources(),
+    // The app's own declaration UNDERNEATH, this boot's facts on top. Without the first half the
+    // entire HTTP tuning surface was unreachable from a shipped app — this literal was its only
+    // construction, so `cors.origins` stayed `[]` in every deployment (no cross-origin call could
+    // ever succeed), `bodyLimitBytes` stayed 1 MiB and `requestTimeoutMs` 30s for a bank and a
+    // blog alike. The ORDER is not a preference: `buildId`, the port, the CSP hashes of what this
+    // process emits and the scope of the store it installed are facts only the boot has.
+    config: defineHttpConfig(
+      mergeHttpConfig(configuredHttp(), {
+        port: options.port,
+        dev: binding.dev,
+        buildId: options.buildId,
+        hostname: binding.hostname,
+        signInPath: options.signInPath ?? null,
+        // One declaration, never half of one: `defineHttpConfig` refuses `trustProxy` without hops.
+        ...(hops === null ? {} : { trustProxy: true, trustedProxyHops: hops }),
+        // `scope` is mandatory since @ultimat3/http made an undeclared limiter a boot error, and it
+        // is DERIVED from the store rather than hardcoded — a literal here would be a second
+        // declaration quietly contradicting the object beside it, and `assertRateLimitScope` holds
+        // the two halves together. It answered `'process'` on every real boot until `startServices`
+        // resolved a store, so the shipped chart's three `web` replicas enforced
+        // `login: { limit: 5 }` as fifteen attempts, with `x verify` green.
+        rateLimit: { scope: store?.scope ?? 'process' },
+        // Hashes, never `'unsafe-inline'`: a `render: 'static'` page is a file on disk, so
+        // nothing can stamp a per-response nonce into it, but its body is fixed and a hash is a
+        // function of that body. Read after `loadApp` — importing the app IS what registered them.
+        // BOTH directives, and the script half is the one that was missing: the hydration runtime
+        // is emitted inline in every document that carries an island, so `script-src 'self'` meant
+        // no island booted anywhere the policy is enforced — which is every container, and never
+        // `x dev`, where it is report-only.
+        security: {
+          csp: {
+            extend: {
+              'style-src': inlineStyleSources(options.inlineStyles ?? []),
+              'script-src': inlineScriptSources(),
+            },
           },
         },
-      },
-    }),
+      }),
+    ),
   }).start();
 }
 

package/src/dev-sync.ts

@@ -16,6 +16,7 @@ import {
 } from '@ultimat3/realtime/server';
 import type { StartRolesOptions } from './dev-roles';
 import { neighbouringPort, PORT_RANGE } from './flag-number';
+import { portFree } from './port-probe';
 import { syncAuthenticator } from './sync-authenticator';
 
 /**
@@ -35,6 +36,46 @@ class SyncPortUnavailableError extends UltimateError {
   }
 }
 
+/**
+ * The neighbour was already listening. `X_PORT_IN_USE` is this package's own and is exactly what
+ * `x doctor` reports for the same condition, so one taken port has one name wherever it is found.
+ *
+ * What shipped instead: `listenSyncNode`'s `Bun.serve` threw, `startSync` re-threw, and the
+ * dispatcher rendered the caught value into `X_CLI_UNEXPECTED`'s cause —
+ * `cause: Error: Failed to start server. Is port 4000 in use?`, `fix: x doctor --json`, from a
+ * command that had just printed `web listening on 3999`. Three defects in one output: an
+ * unstable code, a caught value rendered into a refusal, and a `fix:` that answered
+ * "no findings — environment is shippable" when run (#F5).
+ */
+class SyncPortInUseError extends UltimateError {
+  constructor(input: { port: number; webPort: number }) {
+    super({
+      code: 'X_PORT_IN_USE',
+      cause: `the sync role binds PORT + 1, so \`x dev --port ${input.webPort}\` needs port ${input.port} and something is already listening on it`,
+      fix: `x dev --port ${neighbouringPort(input.webPort)}   # or free port ${input.port}: lsof -nP -iTCP:${input.port} -sTCP:LISTEN`,
+      meta: { port: input.port, webPort: input.webPort },
+    });
+  }
+}
+
+/**
+ * What a failed `listenSyncNode` really was, ASKED rather than read off the caught value: the
+ * thrown thing is `Bun.serve`'s own English and interpolating it into a `cause:` is what
+ * `scripts/catch-render.ts` refuses. `undefined` means "not a taken port" and the original value
+ * is re-thrown untouched — a catch-all that renamed every listener failure would be worse than
+ * the bare one it replaced.
+ *
+ * `probe` is injected so a test can be exactly "the port was taken" without racing a real socket.
+ */
+export async function syncBindRefusal(
+  webPort: number,
+  port: number,
+  probe: (value: number) => Promise<boolean> = portFree,
+): Promise<UltimateError | undefined> {
+  if (await probe(port)) return undefined;
+  return new SyncPortInUseError({ port, webPort });
+}
+
 /**
  * The port the sync node listens on. `PORT + 1`, and `0` stays `0` — the kernel picks, and adding
  * one to it would pick a specific port instead.
@@ -131,8 +172,9 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
     }),
   });
   await node.start();
+  const port = syncPortFor(options.port);
   try {
-    const listener = listenSyncNode(node, { port: syncPortFor(options.port) });
+    const listener = listenSyncNode(node, { port });
     return {
       url: listener.url,
       stop: async () => {
@@ -142,6 +184,8 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
     };
   } catch (error) {
     await node.stop();
+    const refusal = await syncBindRefusal(options.port, port);
+    if (refusal !== undefined) throw refusal;
     throw error;
   }
 }

package/src/error-codes.ts

@@ -52,6 +52,13 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_STORAGE_UNWRITABLE',
   'X_STORAGE_SECRET_DEV',
   'X_MANIFEST_STALE',
+  // The other half of the same file, and the one that was silence: `x manifest` writes
+  // `x.manifest.json`, `AGENTS.md` tells an agent that facts live in it, `x dev` prints its path —
+  // and nothing ever ran the command, so the gate's `manifest` step reported green over a file
+  // that has never existed in any app `x new` produced. Its own code because the repair differs
+  // from both neighbours: `X_MANIFEST_DRIFT` means the committed file disagrees with the code and
+  // `X_MANIFEST_STALE` means `openapi.json` does; this one means there is nothing there at all.
+  'X_MANIFEST_MISSING',
   'X_BUDGET_UNMEASURED',
   // The other half of #271, and the half no runtime can raise: a route reads a live hook and boots
   // no module in a browser, so its rows have nowhere to arrive and the page renders its loading
@@ -146,6 +153,14 @@ export const CLI_OWNED_ERROR_CODES = [
  */
 export const CLI_BORROWED_ERROR_CODES = [
   'X_NOT_IMPLEMENTED',
+  // `@ultimat3/policy`'s, and the gate's `policy` step reports it verbatim — cause, fix and the
+  // nearest declared name all come from `permissionUnknown`. A CLI-owned twin would be a second
+  // wording for the condition `can()` already refuses at run time, and the two would drift.
+  'X_PERMISSION_UNKNOWN',
+  // `@ultimat3/db`'s, reported by `x doctor`'s database probe with that package's own two-branch
+  // fix. The CLI is the half that asks BEFORE a pool is opened; the condition and the remedy are
+  // both db's, and a CLI twin would be one unreachable database with two names.
+  'X_DB_UNAVAILABLE',
   'X_CONFIG_INVALID',
   'X_ENV_MISSING',
   'X_ENV_EXAMPLE_DRIFT',
@@ -195,6 +210,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_PACKAGE_UNREFERENCED: 'a published workspace is not in the root tsconfig build graph',
   X_RELEASE_VERSION_SKEW: 'a workspace is not at the lockstep version',
   X_MANIFEST_STALE: 'openapi.json is stale',
+  X_MANIFEST_MISSING: 'the app ships no x.manifest.json',
   X_BUDGET_UNMEASURED: 'a route declares a budget the build never measured',
   X_LIVE_ROUTE_NO_ISLAND: 'a route reads live rows and boots nothing that could receive them',
   X_BUILD_FAILED: 'x build failed',

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