@ultimat3/cli 5.0.1 → 6.0.0

package/CLAUDE.md

@@ -12,7 +12,7 @@ Tier 5. May import tiers 0–4. Nothing imports this except `create-ultimate`.
 | Bare subcommands | `CommandSpec.defaultSubcommand`, **declared**. The parser answered `subcommands[0]` until 1.2.0, so `x db` ran `gen` — the migration GENERATOR — because it sorted first, and `x mcp` started a server. A command with no defensible default declares none and `MissingSubcommandError` refuses the bare form; `parse.test.ts` pins the set at exactly `db` and `mcp`. Its fix is `x help <command>`, never `x <command> --help`: the subcommand is resolved *after* the flag loop, so the latter throws the same error again — a fix line that reproduced its own failure |
 | Closed flag values | a flag whose values are a closed set is READ through a function that refuses the rest — `cmd-build.ts`'s `readTarget`, `cmd-deploy.ts`'s `readMethod`, `cmd-routes.ts`'s `readSurfaceFilter`, `cmd-mcp.ts`'s `isTransport`. `=== 'helm' ? 'helm' : 'compose'` made `x deploy --method helmm` a COMPOSE deploy reporting `method: "compose"`, and `--surface App` reported `0 routes` and exit 0 — a typo and an empty table rendering identically. The set is the framework's own where one exists (`SURFACES` from `@ultimat3/render`), never a list restated here |
 | App root | `CommandSpec.requiresApp`, **enforced by `dispatch.ts`** before `target.run` — the field's doc said so for 17 commands and nothing read it, so the promise was kept only by each command remembering to call `requireAppRoot` itself. Those 17 calls stay (they hand the command its root, and name subcommands the dispatcher cannot see), but the DECLARATION is what decides, ahead of any check a command makes about its own arguments; `--help` is exempt, because `target` is the help command by then |
-| Result helpers | `command.ts`'s `ok()` / `failed()` write `ok` **after** the `extra` spread: the function's name is the verdict and nothing a caller passes can overturn it. Spread last, `failed('verify', '1 of 17 steps failed', { ok: true })` answered `ok: true` and `exitCodeFor` exited **0** on it — a green CI over a red command (`command.test.ts`) |
+| Result helpers | `command.ts`'s `ok()` / `failed()` write `ok` **after** the `extra` spread: the function's name is the verdict and nothing a caller passes can overturn it. Spread last, `failed('verify', '1 of 19 steps failed', { ok: true })` answered `ok: true` and `exitCodeFor` exited **0** on it — a green CI over a red command (`command.test.ts`) |
 | I/O | only `dispatch.ts` renders or exits; commands return `CommandResult` |
 | Staying up | a command still listening when `run` resolves returns `hold` (`hold.ts`), or `bin.ts` exits out from under it |
 | `--json` | every command, no exceptions — same data as the human render |
@@ -93,7 +93,7 @@ them is answered by this table rather than by a second convention:
 | `x jobs` | `cmd-jobs.ts`, `jobs-{driver,report,drain,json,table}.ts` | `@ultimat3/jobs`' own introspection |
 | `x tasks` | `cmd-tasks.ts`, `tasks-facts.ts` | `registeredTasks()` + `@ultimat3/time`'s cron resolution |
 | `x policy` | `cmd-policy.ts`, `policy-facts.ts` | `@ultimat3/policy`'s `policyMatrix()` over the app's own `Policy` objects |
-| `x i18n` | `cmd-i18n.ts`, `i18n-audit.ts` | `@ultimat3/i18n`'s `extractFromFiles` + `auditCatalogs` |
+| `x i18n` | `cmd-i18n.ts`, `i18n-audit.ts`, `i18n-registration.ts` | `@ultimat3/i18n`'s `extractFromFiles` + `auditCatalogs`, then the live catalog registry |
 
 Each pairs a `cmd-*.ts` of CLI wiring with a facts module that takes plain inputs and returns plain
 data, so the projection is testable without a `ParsedArgs` — the `cmd-jobs.ts` / `jobs-report.ts`
@@ -108,6 +108,29 @@ mode `cmd-planned.ts` closes for planned commands and these close for real ones.
 forbid: a `t()` call is not a primitive and no registry holds it. It uses `source-files.ts`, the
 same walk `errors` and `filesize` use, so the three cannot disagree on what the app's source is.
 
+**And then it asks the question the scan cannot answer.** A catalog complete on disk, its keys used
+everywhere in source, and an audit of one against the other were all green for an app that rendered
+`⟦key⟧` on every page — registration is a side effect of importing the module that calls
+`defineCatalogs()`, and nothing imported it (issue #249). `i18n-registration.ts` loads the app
+through `loadApp` — the same call `serveApp` makes at boot, so it is the boot's own answer and not a
+simulation of one — and compares the catalogs on disk against the live registry, per locale
+(`X_CATALOG_UNREGISTERED`). Two conditions, one code: a shipped catalog no module registered, and
+no catalog anywhere while source calls `t()` — the second is the vacuous green an app with an
+`app.config.ts` and no `packages/i18n/catalogs/` used to get. `loadApp`'s own findings ride along
+ONLY when something is unregistered, because "packages/i18n/src/index.ts: SyntaxError" is the
+evidence for the gap above it and noise on a pass.
+
+`catalogFindings(root)` is the one composition both callers report: `x i18n check` renders it as a
+table with a `registered` column, `x verify`'s **`i18n` step** returns it as findings. One
+implementation, so the command and the gate can never disagree about an app.
+
+**The generators emit `useT()` from the app's own catalog module, never `t` from `@ultimat3/i18n`.**
+The specifier is `resolveCatalogModule(root)` — `packages/i18n/package.json`'s `name`, read off
+disk, because a template is a pure string function and only a package name resolves as an import.
+An app with no such package keeps the framework import: emitting one that cannot resolve trades a
+wrong idiom for a file that does not compile. This is where the reported bug's idiom came from —
+every generated page imported `t` directly, so no page depended on the module that registers.
+
 **A catalog is authored nested and read flat.** `Catalog` (`{ 'nav.home': 'Home' }`) is the
 translator's form; the file on disk holds `{ nav: { home: 'Home' } }`, and `parseNestedCatalog`
 refuses a dot inside a key — so anything writing a catalog goes through `nestCatalog`

package/README.md

@@ -11,7 +11,7 @@ Commands and the `x verify` step count, `As of 2026-08`:
 | `x new <name>` | scaffolds the monorepo | interactive-free; auth, seeded DB, example route |
 | `x dev` | every role in one process | embedded Postgres/events/storage, `/_x` mounted |
 | `x build --target docker\|binary\|static` | one artifact | `ROLE` selects behaviour at start |
-| `x verify` | **the gate** | 17 named steps, each with pass/fail + duration |
+| `x verify` | **the gate** | 19 named steps, each with pass/fail + duration |
 | `x g <primitive> <name>` | scaffolds a primitive **with a passing test** | never a TODO stub |
 | `x db gen\|migrate\|reset\|branch\|backfill` | everything DB | `branch` = copy-on-write clone + preview URL; `backfill` dry-runs unless `--write`. `x db studio` is **planned** — it parses, and exits `X_NOT_IMPLEMENTED` naming `/_x`'s db panel |
 | `x mcp serve` | `@ultimat3/mcp`'s 13 dev tools, over stdio or HTTP | one catalog, one scope set, both transports |
@@ -47,7 +47,7 @@ X_DB_DRIFT: schema differs from migrations
 
 ```sh
 x verify --json
-# {"ok":false,"command":"verify","summary":"1 of 17 steps failed","steps":[...]}
+# {"ok":false,"command":"verify","summary":"1 of 19 steps failed","steps":[...]}
 ```
 
 ## `x verify` steps

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "5.0.1",
+  "version": "6.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -22,6 +22,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "types",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -35,28 +36,30 @@
     "dev": "bun run src/bin.ts dev"
   },
   "dependencies": {
-    "@ultimat3/action": "5.0.1",
-    "@ultimat3/admin": "5.0.1",
-    "@ultimat3/ai": "5.0.1",
-    "@ultimat3/cache": "5.0.1",
-    "@ultimat3/core": "5.0.1",
-    "@ultimat3/db": "5.0.1",
-    "@ultimat3/entity": "5.0.1",
-    "@ultimat3/http": "5.0.1",
-    "@ultimat3/i18n": "5.0.1",
-    "@ultimat3/jobs": "5.0.1",
-    "@ultimat3/mail": "5.0.1",
-    "@ultimat3/manifest": "5.0.1",
-    "@ultimat3/mcp": "5.0.1",
-    "@ultimat3/policy": "5.0.1",
-    "@ultimat3/pwa": "5.0.1",
-    "@ultimat3/query": "5.0.1",
-    "@ultimat3/realtime": "5.0.1",
-    "@ultimat3/render": "5.0.1",
-    "@ultimat3/schema": "5.0.1",
-    "@ultimat3/seo": "5.0.1",
-    "@ultimat3/storage": "5.0.1",
-    "@ultimat3/testing": "5.0.1",
-    "@ultimat3/time": "5.0.1"
+    "@babel/core": "^7.28.4",
+    "@ultimat3/action": "6.0.0",
+    "@ultimat3/admin": "6.0.0",
+    "@ultimat3/ai": "6.0.0",
+    "@ultimat3/cache": "6.0.0",
+    "@ultimat3/core": "6.0.0",
+    "@ultimat3/db": "6.0.0",
+    "@ultimat3/entity": "6.0.0",
+    "@ultimat3/http": "6.0.0",
+    "@ultimat3/i18n": "6.0.0",
+    "@ultimat3/jobs": "6.0.0",
+    "@ultimat3/mail": "6.0.0",
+    "@ultimat3/manifest": "6.0.0",
+    "@ultimat3/mcp": "6.0.0",
+    "@ultimat3/policy": "6.0.0",
+    "@ultimat3/pwa": "6.0.0",
+    "@ultimat3/query": "6.0.0",
+    "@ultimat3/realtime": "6.0.0",
+    "@ultimat3/render": "6.0.0",
+    "@ultimat3/schema": "6.0.0",
+    "@ultimat3/seo": "6.0.0",
+    "@ultimat3/storage": "6.0.0",
+    "@ultimat3/testing": "6.0.0",
+    "@ultimat3/time": "6.0.0",
+    "babel-preset-solid": "^1.9.15"
   }
 }

package/src/cmd-build.ts

@@ -7,6 +7,7 @@ import { frameworkVersion, VERSION_DEFINE } from '@ultimat3/core';
 import { requireAppRoot } from './app-root';
 import { runVerify } from './cmd-verify';
 import type { CliCommand, CommandContext } from './command';
+import { externalArgs } from './compile-externals';
 import { BuildEntryMissingError, UnknownCommandError } from './errors';
 import type { ExecResult } from './exec';
 import { execOutput } from './exec';
@@ -58,6 +59,11 @@ export function dockerArgs(root: string, tag: string): readonly string[] {
  * `frameworkVersion()` has nothing to read and throws — which is exactly how this target came to
  * compile an artifact that could never boot. The value is this CLI's own `@ultimat3/core`, which is
  * the app's too: the packages release in lockstep and `x new` pins them together.
+ *
+ * `externalArgs()` is not optional either, and for the opposite reason: it names the one specifier
+ * this graph must NOT resolve. `apps/web/server.ts` reaches `serve.ts`, which reaches the island
+ * builder, which reaches `@babel/core` — whose `.cts`-config loader requires a package we
+ * deliberately do not install. Bun 1.3 fails the compile on it. See `compile-externals.ts`.
  */
 export function binaryArgs(root: string, out: string): readonly string[] {
   return [
@@ -67,6 +73,7 @@ export function binaryArgs(root: string, out: string): readonly string[] {
     '--minify',
     '--define',
     `${VERSION_DEFINE}=${JSON.stringify(frameworkVersion())}`,
+    ...externalArgs(),
     join(root, BUILD_ENTRY.binary),
     '--outfile',
     out,

package/src/cmd-dev.ts

@@ -23,10 +23,11 @@ import type { CliCommand, CommandContext } from './command';
 import { assetRoutes } from './dev-assets';
 import type { DevDashboardInput, DevStatus } from './dev-dashboard';
 import { devDashboardRoutes, devPanels } from './dev-dashboard';
+import { clearLock, preflight, writeLock } from './dev-lock';
 import { createStatementLedger } from './dev-n-plus-one';
 import { appRoutes } from './dev-render';
 import type { RunningRoles } from './dev-roles';
-import { DEV_ROLES, selectRoles, startRoles } from './dev-roles';
+import { DEV_BINDING, DEV_ROLES, selectRoles, startRoles } from './dev-roles';
 import type { RunningServices } from './dev-runtime';
 import { cdnLabel, describeCdn, describeMail, mailLabel, startServices } from './dev-runtime';
 import type { DevServices } from './dev-services';
@@ -295,6 +296,20 @@ export const devCommand: CliCommand = {
       DEFAULT_PORT,
     );
     const roles = selectRoles(flagString(ctx.args, 'role'));
+    // BEFORE anything boots. Both failures this catches were reachable and both reported the wrong
+    // thing: a taken port surfaced as X_CLI_UNEXPECTED wrapping "Is port 3000 in use?" with a `fix:`
+    // naming `x doctor`, and a second `x dev` on one checkout died later on X_DB_UNAVAILABLE whose
+    // `fix:` named `x dev`. Neither is discoverable from the message; both are trivial once the
+    // preflight has the state directory and the port in front of it.
+    const services = resolveServices(root, ctx.env);
+    const { clearedStale } = await preflight({
+      stateDir: services.stateDir,
+      port,
+      // The address the web role will actually bind, never a wider one: probing `0.0.0.0` would
+      // refuse a boot that a neighbour on one LAN interface does not actually block.
+      hostname: DEV_BINDING.hostname,
+      embeddedDb: services.db.mode === 'embedded',
+    });
     const server = await startDev({
       root,
       port,
@@ -344,13 +359,23 @@ export const devCommand: CliCommand = {
         panels: [...server.panels],
       },
       lines: [
+        // A hard kill leaves the lock behind; clearing it is normal and worth one line, never a
+        // finding. First, because it happened before anything else this run reports.
+        ...(clearedStale ? [msg('cli.dev.staleLock')] : []),
         msg('cli.dev.roles', { roles: server.roles.join(', ') }),
         msg('cli.dev.panels', { panels: server.panels.join(', ') }),
         msg('cli.dev.manifest', { path: join(root, MANIFEST_FILENAME) }),
         msg('cli.dev.introspect', { url: `${server.url}/_x` }),
       ],
     };
+    await writeLock(services.stateDir, {
+      pid: process.pid,
+      port,
+      url: server.url,
+      startedAt: new Date().toISOString(),
+    });
     if (ctx.args.flags.get('once') === true) {
+      clearLock(services.stateDir);
       await server.stop();
       return result;
     }
@@ -358,6 +383,14 @@ export const devCommand: CliCommand = {
     // `/_x` stays reachable. Ctrl-C drains the web role through core's phases first and releases
     // the embedded Postgres, the worker and the watcher after — a hard kill leaves the PGlite
     // directory locked by a process that no longer exists.
-    return { ...result, hold: holdUntilShutdown('dev', () => server.stop()) };
+    return {
+      ...result,
+      hold: holdUntilShutdown('dev', async () => {
+        // The lock first: a stop() that throws must not leave a file claiming this pid still owns
+        // the directory, because the next boot would then refuse for a process that is gone.
+        clearLock(services.stateDir);
+        await server.stop();
+      }),
+    };
   },
 };

package/src/cmd-generate.ts

@@ -2,365 +2,29 @@
 // emits a TODO has moved the work, not done it; every file this writes typechecks, and every
 // primitive arrives with the test that pins its distant invariants (policy, idempotency, budget).
 
-// `resolve`/`sep` and not `join`: only resolving the assembled path can prove it stayed inside the
-// app root, and `node:path` is the only API that resolves one. `node:fs` for the exists check.
 import { existsSync } from 'node:fs';
-import { resolve, sep } from 'node:path';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
 import { appManifest, writeAppManifest } from './app-manifest';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
-import {
-  CliNotImplementedError,
-  GenerateJsonInvalidError,
-  ScaffoldPathEscapeError,
-} from './errors';
-// Re-exported below: `GENERATORS` and `Generator` are imported from this module by the tests, the
-// scaffold fixture and `src/index.ts`, and moving where they are declared must not move where they
-// are read from.
-import type { Generator } from './generate-kinds';
-import {
-  assertSurfaceSupported,
-  GENERATORS,
-  readKind,
-  readName,
-  readSurface,
-} from './generate-kinds';
-import { mergeJsonDeep } from './json-merge';
+import { generate } from './generate-files';
+import { GENERATORS, readKind, readName, readSurface } from './generate-kinds';
+import { containedPath, writeFiles } from './generate-write';
+import { resolveCatalogModule } from './i18n-audit';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { flagBool, flagList, flagString } from './parse';
-import type { GeneratedFile, Surface } from './templates';
-import {
-  actionFiles,
-  adminPageFiles,
-  backfillFiles,
-  CATALOG_ROOT,
-  entityFiles,
-  guardFiles,
-  i18nIndex,
-  islandFiles,
-  jobFiles,
-  kebab,
-  policyFiles,
-  queryFiles,
-  resolveLocales,
-  resourceFiles,
-  routeFiles,
-  taskFiles,
-} from './templates';
+import { CATALOG_ROOT, i18nIndex, resolveLocales } from './templates';
 
+// One import path for the generator, unchanged by the split: `index.ts`, `x new` and the scaffold
+// fixture reach the kinds, the pure file list and the writer through this module, and a second path
+// to any of them would be the ambiguity axiom 1 forbids.
+export type { GenerateOptions } from './generate-files';
+export { generate } from './generate-files';
 export type { Generator } from './generate-kinds';
 export { GENERATORS } from './generate-kinds';
-
-export interface GenerateOptions {
-  readonly kind: Generator;
-  readonly name: string;
-  readonly feature?: string;
-  readonly surface?: Surface;
-  readonly live?: boolean;
-  /** `resource` only: also emit the per-entity admin override. */
-  readonly admin?: boolean;
-  /** Every locale a generated i18n catalog entry ships for. Defaults to `['en']`. */
-  readonly locales?: readonly string[];
-  /**
-   * `island` and `admin:page`: the directory the generated files land in. Named rather than
-   * derived, because neither destination is derivable — `X_ISLAND_INVALID`'s cause already holds
-   * the path a page's `src` resolved to, and an app's admin is wherever its `defineAdmin` is.
-   */
-  readonly at?: string;
-  /** `admin:page` only: the permission the page's own work needs, on top of `admin:read`. */
-  readonly permission?: string;
-}
-
-const DEFAULT_SURFACE_DIR: Record<Surface, string> = {
-  site: 'apps/web/site',
-  app: 'apps/web/app',
-};
-
-/** `undefined` when `text` does not parse as a JSON object — the one shape every catalog, whether
- * generated or hand-edited on disk, must hold. */
-function parseJsonObject(text: string): Record<string, unknown> | undefined {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(text);
-  } catch {
-    return undefined;
-  }
-  return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
-    ? (parsed as Record<string, unknown>)
-    : undefined;
-}
-
-/** Deterministic catalog bytes: sorted keys, 2-space indent, trailing newline — a diff shows only
- * the keys a run actually changed, never a reordering. */
-function prettyJson(value: Record<string, unknown>): string {
-  const sorted = Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)));
-  return `${JSON.stringify(sorted, null, 2)}\n`;
-}
-
-/**
- * Two generators can legitimately produce the same shared file. A plain file (errors.ts) keeps
- * first-write-wins; a `merge: 'json'` catalog instead merges every contributor's keys into one
- * file — `resourceFiles` and `routeFiles` both target the same locale's catalog, and a plain
- * overwrite would drop whichever generator ran first. Later entries fill keys the earlier one
- * lacks; the first occurrence wins a clash, the same rule `writeFiles` applies against the copy
- * already on disk. Exported so `x new` (`cmd-new.ts`) and the scaffold fixture resolve a shared
- * catalog the identical way — one merge rule, not three hand-copied ones.
- *
- * A `merge: 'json'` file's `contents` are the generator's own output, not user data — one that
- * fails to parse as a JSON object is a bug in the template that produced it, so it throws here
- * rather than being silently treated as `{}` and merged into (or written as) a catalog with
- * attribution to nobody. `writeFiles`/`mergeJsonFile` never see a malformed *generated* payload in
- * practice: every production caller (`generate()` below, `cmd-new.ts`'s `planNewApp()`, the
- * scaffold fixture) runs its file list through this function first.
- */
-export function dedupe(files: readonly GeneratedFile[]): readonly GeneratedFile[] {
-  const seen = new Map<string, GeneratedFile>();
-  for (const file of files) {
-    if (file.merge === 'json' && parseJsonObject(file.contents) === undefined) {
-      throw new GenerateJsonInvalidError({ path: file.path });
-    }
-    const prior = seen.get(file.path);
-    if (prior === undefined) {
-      seen.set(file.path, file);
-    } else if (prior.merge === 'json' && file.merge === 'json') {
-      // Both sides already proved parseable above — the fallback only guards a future change to
-      // that invariant, it never fires today. Deep: two generators contributing to one nested
-      // catalog share top-level keys (`app`, `admin`), and a shallow spread drops one of them.
-      const later = parseJsonObject(file.contents) ?? {};
-      const earlier = parseJsonObject(prior.contents) ?? {};
-      const { merged } = mergeJsonDeep(earlier, later);
-      seen.set(file.path, { ...prior, contents: prettyJson(merged) });
-    }
-    // else: not mergeable — first write wins, exactly as it always has.
-  }
-  return [...seen.values()];
-}
-
-/**
- * Pure: returns the files a generator would write. `x g` writes them, the generator test asserts
- * on them, and nothing has to run a filesystem to review what a generator produces.
- */
-export function generate(options: GenerateOptions): readonly GeneratedFile[] {
-  const surface: Surface = options.surface ?? 'app';
-  assertSurfaceSupported(options.kind, surface, options.name);
-  const surfaceDir = DEFAULT_SURFACE_DIR[surface];
-  const feature = options.feature ?? options.name;
-  const target = { surfaceDir, feature };
-  switch (options.kind) {
-    case 'resource':
-      return dedupe(
-        resourceFiles(options.name, {
-          ...target,
-          admin: options.admin === true,
-          ...(options.locales === undefined ? {} : { locales: options.locales }),
-        }),
-      );
-    case 'action':
-      return dedupe(actionFiles(options.name, target));
-    case 'mutator':
-      return dedupe(actionFiles(options.name, { ...target, mutator: true }));
-    case 'backfill':
-      return dedupe(backfillFiles(options.name, target));
-    case 'entity':
-      return dedupe(entityFiles(options.name, target));
-    case 'policy':
-      return dedupe(policyFiles(options.name, target));
-    case 'query':
-      return dedupe(queryFiles(options.name, { ...target, live: options.live === true }));
-    case 'job':
-      return dedupe(jobFiles(options.name, target));
-    case 'task':
-      return dedupe(taskFiles(options.name, target));
-    case 'island':
-      return dedupe(islandFiles(options.name, { dir: options.at ?? `${surfaceDir}/${feature}` }));
-    // No `--at`, no surface, no feature: `guards/` is the one directory the gate discovers, and a
-    // guard that lived anywhere else would need an app-side registration to be found.
-    case 'guard':
-      return dedupe(guardFiles(options.name));
-    case 'admin:page':
-      // A default permission, never none: an empty list is `X_ADMIN_PAGE_UNGUARDED` on sight.
-      return dedupe(
-        adminPageFiles(options.name, {
-          permission: options.permission ?? `${kebab(options.name)}:read`,
-          // The same `--at` `island` takes: an app's admin is wherever its `defineAdmin` is.
-          ...(options.at === undefined ? {} : { dir: options.at }),
-          ...(options.locales === undefined ? {} : { locales: options.locales }),
-        }),
-      );
-    case 'route':
-      // `--locales` reaches the route generator too: its catalog entry is the route's title and
-      // description, and a locale asked for on the command line is a locale that gets a file.
-      return dedupe(
-        routeFiles(options.name, {
-          surface,
-          ...(options.locales === undefined ? {} : { locales: options.locales }),
-        }),
-      );
-    default:
-      throw new CliNotImplementedError({
-        feature: `generator "${String(options.kind)}"`,
-        fix: `x g ${GENERATORS.join('|')}`,
-      });
-  }
-}
-
-export interface WriteReport {
-  readonly written: readonly string[];
-  readonly conflicts: readonly Finding[];
-}
-
-/**
- * `GeneratedFile.path` is documented as relative-POSIX, not enforced as it: `join` would happily
- * walk out of the app on a `..` segment or ignore the root entirely on an absolute path. Proven
- * before the write, once per file, because after the write there is nothing left to prove.
- */
-export function containedPath(root: string, path: string): string {
-  const base = resolve(root);
-  const target = resolve(base, path);
-  if (target !== base && !target.startsWith(`${base}${sep}`))
-    // The default `fix` names the scaffold gate's own test, which repairs nothing for someone
-    // running `x g`: the fix here is the generate command, re-run as a dry run.
-    throw new ScaffoldPathEscapeError({
-      path,
-      dir: base,
-      // Command first, the caveat behind a `#`: the line runs verbatim and the shell drops the
-      // rest. `x g <kind> <name>` pasted into bash is a redirect, not a command.
-      fix: `x g resource posts --dry-run   # name every file relative to the app root, no ".." segment`,
-    });
-  return target;
-}
-
-/**
- * A `merge: 'json'` catalog is never a conflict on existence and never subject to `--force`: an
- * existing key on disk always wins, because it may hold a human translation, and only genuinely
- * new keys are added — so a second, third… generator run keeps growing the same file instead of
- * fighting over it. A file that exists but does not parse as a JSON object cannot be merged into
- * without risking silent data loss, so that alone is reported rather than clobbered or thrown past.
- *
- * Typed to the `merge: 'json'` variant alone, not the general `GeneratedFile` union: a
- * byte-carrying file has no `contents: string` to merge, and this is what stops one from ever
- * reaching `parseJsonObject` even if a future caller forgets the `file.merge === 'json'` guard
- * its one call site already applies.
- */
-async function planJsonMerge(
-  file: Extract<GeneratedFile, { merge: 'json' }>,
-  absolute: string,
-): Promise<WritePlan> {
-  const generated = parseJsonObject(file.contents) ?? {};
-  if (!existsSync(absolute))
-    return { kind: 'write', file, absolute, contents: prettyJson(generated) };
-  const existing = parseJsonObject(await Bun.file(absolute).text());
-  if (existing === undefined) {
-    return {
-      kind: 'conflict',
-      finding: {
-        code: 'X_GENERATE_CONFLICT',
-        cause: `${file.path} exists but is not a JSON object, so its keys cannot be merged`,
-        fix: `edit ${file.path} by hand until it parses as a JSON object, or delete it and re-run x g`,
-        docs: 'https://ultimate.dev/errors/X_GENERATE_CONFLICT',
-        at: file.path,
-      },
-    };
-  }
-  // An existing key wins because it may hold a human translation; only the new keys are added.
-  // Deep, so a nested catalog gains `site.blog.title` without losing the rest of `site`.
-  const { merged, gained } = mergeJsonDeep(existing, generated);
-  // Every key the generator wants is already there — leave the file untouched and unclaimed.
-  if (!gained) return { kind: 'skip' };
-  return { kind: 'write', file, absolute, contents: prettyJson(merged) };
-}
-
-/**
- * What one generated file would do, decided without doing it. The merge case computes its own
- * bytes here rather than at the write, so the two passes below cannot disagree about a file.
- */
-type WritePlan =
-  | {
-      readonly kind: 'write';
-      readonly file: GeneratedFile;
-      readonly absolute: string;
-      readonly contents: string | Uint8Array;
-    }
-  | { readonly kind: 'skip' }
-  | { readonly kind: 'conflict'; readonly finding: Finding };
-
-function planFile(
-  file: GeneratedFile,
-  absolute: string,
-  force: boolean,
-  invocation: string,
-): WritePlan {
-  // A foundation file belongs to the slice, not to the generator that needs it: several generators
-  // emit the same `repo.ts`, so an existing one is the author's — never a conflict, and never
-  // overwritten, `--force` included. `--force` is about the primitive the author named; clobbering
-  // `policy.ts` to regenerate one action would delete every rule they wrote. Regenerating a slice
-  // module is `x g entity|policy`.
-  if (file.merge === 'if-absent') {
-    return existsSync(absolute)
-      ? { kind: 'skip' }
-      : { kind: 'write', file, absolute, contents: file.contents };
-  }
-  if (!force && existsSync(absolute)) {
-    return {
-      kind: 'conflict',
-      finding: {
-        code: 'X_GENERATE_CONFLICT',
-        cause: `${file.path} already exists`,
-        // The caller's own invocation, not `x g <kind>`: `x g --force` is X_CLI_UNKNOWN_COMMAND
-        // when run, and a `fix:` is copied and pasted verbatim. Same construction as
-        // `generate-kinds.ts`'s `assertSurfaceSupported`.
-        fix: `${invocation} --force   # overwrites ${file.path}, or pass a different name`,
-        docs: 'https://ultimate.dev/errors/X_GENERATE_CONFLICT',
-        at: file.path,
-      },
-    };
-  }
-  return { kind: 'write', file, absolute, contents: file.contents };
-}
-
-/**
- * Never clobbers, and never half-writes. A generator that overwrites is a generator nobody runs
- * twice; a generator that lands four of seven files and then reports a conflict is worse, because
- * the next run conflicts on the files the failed one wrote.
- *
- * Two passes, and the split is the point: the first decides — containment, existence, whether a
- * catalog can be merged into — and touches nothing, the second writes only when the first found
- * no conflict at all. Containment was already proven up front and the rest was not.
- */
-export async function writeFiles(
-  root: string,
-  files: readonly GeneratedFile[],
-  force: boolean,
-  /**
-   * The command line that produced these files, so a conflict's `fix:` can hand it back with
-   * `--force` on the end. Optional for a caller assembling files itself; the fallback is the
-   * shape, not a runnable line, and every generator path supplies the real one.
-   */
-  invocation = 'x g <kind> <name>',
-): Promise<WriteReport> {
-  const plans: WritePlan[] = [];
-  for (const file of files) {
-    const absolute = containedPath(root, file.path);
-    plans.push(
-      file.merge === 'json'
-        ? await planJsonMerge(file, absolute)
-        : planFile(file, absolute, force, invocation),
-    );
-  }
-  const conflicts = plans.flatMap((plan) => (plan.kind === 'conflict' ? [plan.finding] : []));
-  if (conflicts.length > 0) return { written: [], conflicts };
-
-  const written: string[] = [];
-  for (const plan of plans) {
-    if (plan.kind !== 'write') continue;
-    // Bun.write creates missing parent directories, so a generator never needs an mkdir step.
-    await Bun.write(plan.absolute, plan.contents);
-    written.push(plan.file.path);
-  }
-  return { written, conflicts: [] };
-}
+export type { WriteReport } from './generate-write';
+export { dedupe, writeFiles } from './generate-write';
 
 const I18N_INDEX_PATH = 'packages/i18n/src/index.ts';
 
@@ -425,6 +89,9 @@ export const generateCommand: CliCommand = {
     const locales = resolveLocales(flagList(ctx.args, 'locales'));
     const at = flagString(ctx.args, 'at');
     const permission = flagString(ctx.args, 'permission');
+    // Read before a file is planned, like the flags above: which module a generated component
+    // imports `useT()` from is a fact about THIS app, and `generate` is a pure function.
+    const catalogModule = await resolveCatalogModule(root);
     const files = generate({
       kind,
       name,
@@ -435,6 +102,7 @@ export const generateCommand: CliCommand = {
       live: flagBool(ctx.args, 'live'),
       admin: flagBool(ctx.args, 'admin'),
       locales,
+      ...(catalogModule === undefined ? {} : { catalogModule }),
     });
     if (flagBool(ctx.args, 'dry-run')) {
       return {