@ultimat3/cli 22.15.0 → 24.0.0

package/src/generate-files.ts

@@ -2,10 +2,12 @@
 // `cmd-generate.ts` so a generator's output can be asserted on — by the generator tests, the
 // scaffold fixture and `x new` — without a command line, an app root or a filesystem.
 
-import { CliNotImplementedError } from './errors';
+import { NotImplementedError } from '@ultimat3/core';
+import { BadFlagError } from './errors';
 import type { Generator } from './generate-kinds';
-import { assertSurfaceSupported, GENERATORS } from './generate-kinds';
+import { assertLiveSupported, assertSurfaceSupported, GENERATORS } from './generate-kinds';
 import { dedupe } from './generate-write';
+import { quoteArg } from './shell-quote';
 import type { GeneratedFile, Surface } from './templates';
 import {
   actionFiles,
@@ -16,12 +18,15 @@ import {
   islandFiles,
   jobFiles,
   kebab,
+  names,
   policyFiles,
   queryFiles,
   resourceFiles,
   routeFiles,
+  shippedGuardFiles,
   taskFiles,
 } from './templates';
+import { adminCatalogFiles } from './templates/admin-catalog';
 
 export interface GenerateOptions {
   readonly kind: Generator;
@@ -56,15 +61,27 @@ export interface GenerateOptions {
    */
   readonly sliceErrors?: string;
   /**
-   * `action`, `mutator`, `job` and `task`: the slice's `entity.ts` as it stands on disk, absent when
+   * `action`, `mutator`, `query`, `job` and `task`: the slice's `entity.ts` as it stands on disk, absent when
    * the feature has no entity yet — and then none is written. Supplied by `run` for `sliceErrors`'s reason — whether the feature is
    * tenant-scoped is a fact about THIS app, and a template that assumed `tenant: 'orgId'` wrote
-   * `repo.byId`/`repo.listByOrg` calls into a feature whose entity names no tenant column. Read at
+   * `repo.byId`/`repo.list` calls into a feature whose entity names no tenant column. Read at
    * `sliceDir(surface, feature)/entity.ts`.
    */
   readonly sliceEntity?: string;
-  /** `job` and `task`: the slice's `repo.ts` as it stands on disk, absent alongside `sliceEntity`. */
+  /** The same kinds: the slice's `repo.ts` as it stands on disk, absent alongside `sliceEntity`. */
   readonly sliceRepo?: string;
+  /**
+   * The app's own db package, `@<app>/db` — what every generated `repo.ts` imports the typed handle
+   * from. Supplied by `run` (`resolveDbModule`) for `catalogModule`'s reason: the name lives in a
+   * manifest on disk. Every kind that can write a slice's `repo.ts` reads it, so it rides on the
+   * shared target rather than on one case.
+   */
+  readonly dbModule?: string;
+  /**
+   * `resource` only: the app has the frame `x new` writes (`apps/web/shared/shell.tsx`), so the
+   * resource's page renders inside it. Read off the disk by `run`, for `catalogModule`'s reason.
+   */
+  readonly shell?: boolean;
 }
 
 const DEFAULT_SURFACE_DIR: Record<Surface, string> = {
@@ -76,6 +93,26 @@ const DEFAULT_SURFACE_DIR: Record<Surface, string> = {
 export const sliceDir = (surface: Surface, feature: string): string =>
   `${DEFAULT_SURFACE_DIR[surface]}/${feature}`;
 
+/**
+ * `x g resource <name> --feature <other>`. A resource IS its feature: every file it composes — the
+ * actions, the live query, the job — names the entity after the slice (`../entity`'s `Run`,
+ * `canRunWrite`), so a slice under a second name is a set of imports that resolve to nothing. The
+ * flag was read and then overwritten with the name, which wrote the slice somewhere the author did
+ * not ask for and said nothing. Refused instead; a value that only restates the name is no second
+ * name.
+ */
+function refuseResourceFeature(options: GenerateOptions, surfaceDir: string): void {
+  if (options.kind !== 'resource' || options.feature === undefined) return;
+  const named = kebab(options.name);
+  if (kebab(options.feature) === named) return;
+  throw new BadFlagError({
+    flag: 'feature',
+    command: 'g resource',
+    reason: `a resource names its own slice — "${options.name}" is written to ${surfaceDir}/${named}/ and its page to ${surfaceDir}/${names(options.name).pluralKebab}/ — so --feature ${options.feature} would be a second name for one slice`,
+    fix: `x g resource ${quoteArg(options.name)}`,
+  });
+}
+
 /**
  * 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.
@@ -83,11 +120,17 @@ export const sliceDir = (surface: Surface, feature: string): string =>
 export function generate(options: GenerateOptions): readonly GeneratedFile[] {
   const surface: Surface = options.surface ?? 'app';
   assertSurfaceSupported(options.kind, surface, options.name);
+  assertLiveSupported(options.kind, options.live === true, options.name);
   const surfaceDir = DEFAULT_SURFACE_DIR[surface];
+  refuseResourceFeature(options, surfaceDir);
   // Kebab, always: `x g entity BlogPost` wrote `app/BlogPost/` while `resource` wrote
   // `app/blog-post/`, so one feature grew two slice directories depending on the generator.
   const feature = kebab(options.feature ?? options.name);
-  const target = { surfaceDir, feature };
+  const target = {
+    surfaceDir,
+    feature,
+    ...(options.dbModule === undefined ? {} : { dbModule: options.dbModule }),
+  };
   switch (options.kind) {
     case 'resource':
       return dedupe(
@@ -96,6 +139,7 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
           admin: options.admin === true,
           ...(options.locales === undefined ? {} : { locales: options.locales }),
           ...(options.catalogModule === undefined ? {} : { catalogModule: options.catalogModule }),
+          ...(options.shell === undefined ? {} : { shell: options.shell }),
         }),
       );
     case 'action':
@@ -104,6 +148,7 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
           ...target,
           ...(options.sliceErrors === undefined ? {} : { sliceErrors: options.sliceErrors }),
           ...(options.sliceEntity === undefined ? {} : { sliceEntity: options.sliceEntity }),
+          ...(options.sliceRepo === undefined ? {} : { sliceRepo: options.sliceRepo }),
         }),
       );
     case 'mutator':
@@ -113,16 +158,35 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
           mutator: true,
           ...(options.sliceErrors === undefined ? {} : { sliceErrors: options.sliceErrors }),
           ...(options.sliceEntity === undefined ? {} : { sliceEntity: options.sliceEntity }),
+          ...(options.sliceRepo === undefined ? {} : { sliceRepo: options.sliceRepo }),
         }),
       );
     case 'backfill':
-      return dedupe(backfillFiles(options.name, target));
+      return dedupe(
+        backfillFiles(options.name, {
+          ...target,
+          ...(options.locales === undefined ? {} : { locales: options.locales }),
+        }),
+      );
     case 'entity':
-      return dedupe(entityFiles(options.name, target));
+      // With the labels the admin reads for it: the entity is an admin screen once it is in the
+      // handle, whether or not a resource was generated around it.
+      return dedupe([
+        ...entityFiles(options.name, target),
+        ...adminCatalogFiles(options.name, target, options.locales),
+      ]);
     case 'policy':
       return dedupe(policyFiles(options.name, target));
     case 'query':
-      return dedupe(queryFiles(options.name, { ...target, live: options.live === true }));
+      return dedupe(
+        queryFiles(options.name, {
+          ...target,
+          live: options.live === true,
+          ...(options.locales === undefined ? {} : { locales: options.locales }),
+          ...(options.sliceEntity === undefined ? {} : { sliceEntity: options.sliceEntity }),
+          ...(options.sliceRepo === undefined ? {} : { sliceRepo: options.sliceRepo }),
+        }),
+      );
     case 'job':
       return dedupe(
         jobFiles(options.name, {
@@ -143,8 +207,11 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
       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.
+    // A name the framework ships a guard under gets THAT guard — how an app adopts one it does
+    // not have (`x doctor` names them). Any other name is the app's own convention, from the blank
+    // template.
     case 'guard':
-      return dedupe(guardFiles(options.name));
+      return dedupe(shippedGuardFiles(kebab(options.name)) ?? guardFiles(options.name));
     case 'admin:page':
       // A default permission, never none: an empty list is `X_ADMIN_PAGE_UNGUARDED` on sight.
       return dedupe(
@@ -167,8 +234,8 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
         }),
       );
     default:
-      throw new CliNotImplementedError({
-        feature: `generator "${String(options.kind)}"`,
+      throw new NotImplementedError({
+        cause: `generator "${String(options.kind)}" is not implemented in this build`,
         fix: `x g ${GENERATORS.join('|')}`,
       });
   }

package/src/generate-grant-findings.ts

@@ -0,0 +1,76 @@
+// What `x g` could NOT grant, said out loud. `generate-grants.ts` performs the role-map edit
+// where the scaffold keeps one; an app whose roles live elsewhere got no grant and no finding, and
+// every generated endpoint answered 403. Apart from that module because this one only REPORTS:
+// it re-asks the same pure edits of the file as it now stands and names what they could not place.
+
+import type { RoleGrant } from './generate-grants';
+import {
+  adminGrantsFor,
+  grantsForWritten,
+  insertGrants,
+  insertPermissions,
+  writtenTables,
+} from './generate-grants';
+import { containedPath } from './generate-write';
+import type { Finding } from './output';
+import { ROLES_FILE } from './permission-grants';
+
+/** `member: 'run:read'; admin: 'run:write', 'runs:read'` — each role, and what its `grants` owes. */
+const linesFor = (grants: readonly RoleGrant[]): string => {
+  const byRole = new Map<string, string[]>();
+  for (const grant of grants) {
+    byRole.set(grant.role, [...(byRole.get(grant.role) ?? []), `'${grant.permission}'`]);
+  }
+  return [...byRole].map(([role, permissions]) => `${role}: ${permissions.join(', ')}`).join('; ');
+};
+
+/** The grants the role map as it stands still lacks: no such role, no `grants`, or undeclared. */
+function stillMissing(source: string, grants: readonly RoleGrant[], admin: readonly RoleGrant[]) {
+  const undeclared = insertPermissions(
+    source,
+    admin.map((grant) => grant.permission),
+  ).skipped;
+  const unplaced = insertGrants(source, grants).skipped;
+  return grants.filter(
+    (grant) => unplaced.includes(grant) || undeclared.includes(grant.permission),
+  );
+}
+
+/**
+ * One finding for everything this run declared and no role holds, or none. Asked AFTER
+ * `grantGeneratedPermissions`, of the file it left: a grant it placed is not reported, and one it
+ * could not place — no role map at the scaffold's path, a map with no such role, a map with no
+ * `definePermissions([…])` to declare an admin permission in — is, with the role each belongs to.
+ */
+export async function ungrantedByGenerator(
+  root: string,
+  written: readonly string[],
+): Promise<readonly Finding[]> {
+  const admin = (await writtenTables(root, written)).flatMap(adminGrantsFor);
+  const grants = [...grantsForWritten(written), ...admin];
+  if (grants.length === 0) return [];
+  const file = Bun.file(containedPath(root, ROLES_FILE));
+  // The file whose declarations nobody granted: where a reader starts when the map is not ours.
+  const declaredIn =
+    written.find((path) => path.endsWith('/policy.ts')) ?? written[0] ?? ROLES_FILE;
+  if (!(await file.exists())) {
+    return [
+      {
+        code: 'X_PERMISSION_UNGRANTED',
+        cause: `${ROLES_FILE} is not in this app, so nothing granted what this run declared — every generated endpoint answers 403 until a role holds: ${linesFor(grants)}`,
+        fix: `x policy list --json   # names the module that calls defineRoles(); add to its roles' grants — ${linesFor(grants)} — then x verify --only policy`,
+        at: declaredIn,
+      },
+    ];
+  }
+  const missing = stillMissing(await file.text(), grants, admin);
+  if (missing.length === 0) return [];
+  return [
+    {
+      code: 'X_PERMISSION_UNGRANTED',
+      cause: `${ROLES_FILE} has no role, no "grants: [...]" list or no definePermissions([...]) these could be added to, so nothing granted: ${linesFor(missing)}`,
+      fix: `edit ${ROLES_FILE} — add to each role's grants (and declare any the map does not know in definePermissions([...])) — ${linesFor(missing)} — then x verify --only policy`,
+      at: ROLES_FILE,
+    },
+  ];
+}

package/src/generate-grants.ts

@@ -2,6 +2,10 @@
 // `<feature>:read` and `<feature>:write`; nothing granted them, so every generated endpoint
 // answered 403 to every actor a role mints. The edit lands in the scaffold's one role map,
 // `apps/web/shared/roles.ts`: `:read` to `member`, `:write` to `admin` (which inherits member).
+//
+// And a generated ENTITY is a screen at `/admin/<table>`, behind `<table>:read|write|delete` —
+// three permissions `defineAdmin()` derives from the table's own name. They are declared in the
+// role map and granted to `admin`, or the role that runs the admin is refused its newest screen.
 
 import { containedPath } from './generate-write';
 import { ROLES_FILE } from './permission-grants';
@@ -33,6 +37,23 @@ export function grantsForWritten(written: readonly string[]): readonly RoleGrant
   });
 }
 
+/** A generated entity file: `<surface>/<feature>/entity.ts`. */
+const ENTITY_PATH = /^apps\/[^/]+\/[^/]+\/[a-z0-9-]+\/entity\.ts$/;
+/** `entity('widgets', {` — the name the admin's permissions are spelled with. */
+const ENTITY_NAME = /\bentity\(\s*'([^']+)'/;
+
+/**
+ * What the admin asks for one table, granted to the role that runs it. The verbs are
+ * `@ultimat3/admin`'s `entityPermissionFor` — `read` to list, open and search, `write` to create
+ * and edit, `delete` to delete — and the resource is the ENTITY's name, never the feature's.
+ */
+export function adminGrantsFor(table: string): readonly RoleGrant[] {
+  return ['read', 'write', 'delete'].map((verb) => ({
+    role: 'admin',
+    permission: `${table}:${verb}`,
+  }));
+}
+
 const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
 /**
@@ -67,16 +88,69 @@ export function insertGrants(
   return { source: next, skipped };
 }
 
-/** Performs `insertGrants` on the app's role map. Answers the paths it rewrote. */
+const DECLARATION = 'definePermissions([';
+
+/**
+ * `source` with each permission added to its first `definePermissions([…])`, re-wrapped the way
+ * Biome prints it. Declared BEFORE it is granted: `can()` refuses a name no call registered, and
+ * `defineRoles()` does not — a grant nothing declares is a 500 on the first request that asks.
+ * A role map with no such call is left alone and every permission returned in `skipped`.
+ */
+export function insertPermissions(
+  source: string,
+  permissions: readonly string[],
+): { readonly source: string; readonly skipped: readonly string[] } {
+  const open = source.indexOf(DECLARATION);
+  const close = open === -1 ? -1 : source.indexOf('])', open);
+  if (open === -1 || close === -1) return { source, skipped: [...permissions] };
+  const current = [...source.slice(open, close).matchAll(/'([^']+)'/g)].map((m) => m[1] ?? '');
+  const added = permissions.filter((permission) => !current.includes(permission));
+  if (added.length === 0) return { source, skipped: [] };
+  const lineStart = source.lastIndexOf('\n', open) + 1;
+  const head = source.slice(lineStart, open);
+  const tail = source.slice(close + 2, source.indexOf('\n', close));
+  const entries = [...current, ...added].map((permission) => `'${permission}'`);
+  const rewritten = wrapList('', `${head}${DECLARATION}`, entries, `])${tail}`);
+  return {
+    source: `${source.slice(0, lineStart)}${rewritten}${source.slice(source.indexOf('\n', close))}`,
+    skipped: [],
+  };
+}
+
+/** The entity names the written `entity.ts` files declare — read off each file, never guessed. */
+export async function writtenTables(
+  root: string,
+  written: readonly string[],
+): Promise<readonly string[]> {
+  const tables: string[] = [];
+  for (const path of written.filter((candidate) => ENTITY_PATH.test(candidate))) {
+    const table = ENTITY_NAME.exec(await Bun.file(containedPath(root, path)).text())?.[1];
+    if (table !== undefined) tables.push(table);
+  }
+  return tables;
+}
+
+/**
+ * Performs both edits on the app's role map: a written policy's grants, and — for each written
+ * entity — the admin's three permissions for its table, declared and granted. Answers the paths
+ * it rewrote.
+ */
 export async function grantGeneratedPermissions(
   root: string,
   written: readonly string[],
 ): Promise<readonly string[]> {
-  const grants = grantsForWritten(written);
+  const admin = (await writtenTables(root, written)).flatMap(adminGrantsFor);
+  const grants = [...grantsForWritten(written), ...admin];
   const file = containedPath(root, ROLES_FILE);
   if (grants.length === 0 || !(await Bun.file(file).exists())) return [];
   const before = await Bun.file(file).text();
-  const { source } = insertGrants(before, grants);
+  const declared = insertPermissions(
+    before,
+    admin.map((grant) => grant.permission),
+  );
+  // Granted only where it could be declared: a grant with no declaration is the 500 above.
+  const grantable = grants.filter((grant) => !declared.skipped.includes(grant.permission));
+  const { source } = insertGrants(declared.source, grantable);
   if (source === before) return [];
   await Bun.write(file, source);
   return [ROLES_FILE];

package/src/generate-kinds.ts

@@ -9,8 +9,9 @@ import {
   MissingSubcommandError,
   UnknownCommandError,
 } from './errors';
+import { quoteArg } from './shell-quote';
 import type { Surface } from './templates';
-import { camel, kebab } from './templates/naming';
+import { camel, kebab, plural, singularOf } from './templates/naming';
 
 export const GENERATORS = [
   'resource',
@@ -49,6 +50,24 @@ export function assertSurfaceSupported(kind: Generator, surface: Surface, name:
   });
 }
 
+/**
+ * `--live` is the query generator's. A resource slice already ships a live list query, so the flag
+ * on any other generator changed nothing — and a flag accepted and ignored is a second spelling of
+ * the same command that an agent then believes did something.
+ */
+export function assertLiveSupported(kind: Generator, live: boolean, name: string): void {
+  if (!live || kind === 'query') return;
+  throw new BadFlagError({
+    flag: 'live',
+    command: `g ${kind}`,
+    reason:
+      kind === 'resource'
+        ? "--live is the query generator's: a resource slice already ships a live list query"
+        : "--live is the query generator's: it declares a query live",
+    fix: `x g query ${quoteArg(`${name}-feed`)} --feature ${quoteArg(name)} --live`,
+  });
+}
+
 /**
  * The generator a spelling reaches, or a refusal that leads with the one it is nearest.
  *
@@ -118,10 +137,42 @@ export function readName(raw: string | undefined, kind: Generator): string {
   // directory that serves it. Every other generator's name is one directory segment.
   if (kind === 'route') return readRoutePath(raw);
   refusePath(raw, 'name', kind);
+  refuseNonAscii(raw, kind);
   refuseBadIdentifier(raw, kind);
+  refusePlural(raw, kind);
   return raw;
 }
 
+/**
+ * Every derived spelling keeps `[a-zA-Z0-9]` and drops the rest as a separator, so a letter
+ * outside ASCII vanished: `x g entity Über` wrote `ber`. Refused, with the name folded to ASCII.
+ */
+function refuseNonAscii(raw: string, kind: Generator): void {
+  if (!/[^\p{ASCII}]/u.test(raw)) return;
+  const folded = kebab(raw.normalize('NFKD').replace(/[^\p{ASCII}]/gu, ''));
+  throw new BadFlagError({
+    flag: 'name',
+    command: `g ${kind}`,
+    reason: `"${raw}" holds a letter outside ASCII, and every file, identifier and table name the generator derives from it keeps ASCII letters and digits only`,
+    fix: folded === '' ? exampleFor(kind) : ['x g', kind, folded].join(' '),
+  });
+}
+
+/** The generators that pluralise their name into a table and a page. */
+const PLURALISED: ReadonlySet<Generator> = new Set<Generator>(['resource', 'entity']);
+
+/** `x g resource posts` declared `entity('postses')`: a plural name is pluralised again. */
+function refusePlural(raw: string, kind: Generator): void {
+  const singular = PLURALISED.has(kind) ? singularOf(raw) : undefined;
+  if (singular === undefined) return;
+  throw new BadFlagError({
+    flag: 'name',
+    command: `g ${kind}`,
+    reason: `"${raw}" is already plural, and the generator pluralises the name for its table and page — "${plural(camel(raw))}"`,
+    fix: ['x g', kind, singular].join(' '),
+  });
+}
+
 /** A static segment, or `[param]` / `[...rest]` — the directory convention `x routes` reads. */
 const ROUTE_SEGMENT = /^(?:[A-Za-z0-9][A-Za-z0-9_-]*|\[(?:\.\.\.)?[A-Za-z][A-Za-z0-9_-]*\])$/;
 

package/src/generate-shadow.ts

@@ -0,0 +1,46 @@
+// A generator name whose type spelling the emitted code ALSO uses as a global or a local alias:
+// `x g resource promise` imports `type { Promise }` beside `Promise<Row>`, and `row` writes
+// `type Row = Row`. Decided on the planned files themselves, so a template that starts using
+// another global is covered the day it does — and the names that clash nowhere stay allowed.
+
+import { BadFlagError } from './errors';
+import type { Generator } from './generate-kinds';
+import type { GeneratedFile } from './templates';
+import { kebab, names } from './templates/naming';
+
+/** The emitted file that imports `type` from the slice AND uses the same name as its own. */
+function shadowingFile(files: readonly GeneratedFile[], type: string): string | undefined {
+  // A pascal spelling is `[A-Za-z0-9]` only (`naming.ts`), so it splices into a pattern as is.
+  const imported = new RegExp(
+    `import\\s+(?:type\\s+)?\\{[^}]*\\b${type}\\b[^}]*\\}\\s+from\\s+'\\.`,
+  );
+  const reused = new RegExp(
+    `\\b${type}<|^\\s*(?:export\\s+)?(?:type\\s+${type}\\s*=|interface\\s+${type}\\b)`,
+    'm',
+  );
+  return files.find(
+    (file) =>
+      typeof file.contents === 'string' &&
+      /\.tsx?$/.test(file.path) &&
+      imported.test(file.contents) &&
+      reused.test(file.contents),
+  )?.path;
+}
+
+/** Refuses `name` when its type spelling would shadow a name the planned files rely on. */
+export function refuseShadowedTypes(
+  files: readonly GeneratedFile[],
+  kind: Generator,
+  name: string,
+): void {
+  const type = names(name).pascal;
+  const file = shadowingFile(files, type);
+  if (file === undefined) return;
+  const noun = kind.split(':').at(-1) ?? kind;
+  throw new BadFlagError({
+    flag: 'name',
+    command: `g ${kind}`,
+    reason: `"${name}" becomes the type ${type}, and ${file} imports it beside its own use of ${type} — the global or local type the template means is shadowed and the file does not compile`,
+    fix: ['x g', kind, `${kebab(name)}-${noun}`].join(' '),
+  });
+}

package/src/generate-write.ts

@@ -9,7 +9,7 @@ import { existsSync } from 'node:fs';
 import { resolve, sep } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import { GenerateJsonInvalidError, ScaffoldPathEscapeError } from './errors';
-import { mergeJsonDeep } from './json-merge';
+import { mergeJsonDeep, mergeJsonInPlace, sortJsonDeep } from './json-merge';
 import type { Finding } from './output';
 import type { GeneratedFile } from './templates';
 
@@ -28,33 +28,18 @@ function parseJsonObject(text: string): Record<string, unknown> | undefined {
 }
 
 /**
- * Every key of every level, sorted. A catalog is authored NESTED (`{ nav: { home: … } }`) and this
- * sorted the top level only, so the keys INSIDE `app` kept the order their generators ran in —
- * `x g route zebra` then `x g route alpha` wrote different bytes from the same two runs in the
- * other order, which is the reordering diff the sort exists to prevent. Arrays keep their order:
- * a list's order is its content.
+ * A generator's OWN catalog bytes: every key of every level sorted, 2-space indent, trailing
+ * newline. A catalog is authored NESTED (`{ nav: { home: … } }`) and sorting the top level only
+ * left the keys inside `app` in the order their generators ran — `x g route zebra` then
+ * `x g route alpha` wrote different bytes from the same two runs in the other order. The sort is
+ * `json-merge.ts`'s `sortJsonDeep`, by code unit: `localeCompare` is `Intl`-backed, so the bytes
+ * would move with the machine's locale and its ICU version.
  *
- * CODE UNIT, never `localeCompare`: it is `Intl`-backed, so the bytes a catalog is written with
- * moved with the machine's locale and its ICU version — `x g route` on a `tr-TR` box and the same
- * command in CI produced two orderings of one file, which is exactly the reordering diff this sort
- * exists to prevent, one layer down. `@ultimat3/render` states the same rule as `byCodeUnit`; the
- * comparison is inlined rather than imported because that one is package-internal and this is the
- * whole of it.
+ * For a fresh file and for `dedupe`, where every contributor is a generator. A file already on
+ * disk is merged in ITS order (`mergeJsonInPlace`), never re-sorted.
  */
-function sortDeep(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(sortDeep);
-  if (typeof value !== 'object' || value === null) return value;
-  return Object.fromEntries(
-    Object.entries(value)
-      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
-      .map(([key, entry]) => [key, sortDeep(entry)]),
-  );
-}
-
-/** 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 {
-  return `${JSON.stringify(sortDeep(value), null, 2)}\n`;
+  return `${JSON.stringify(sortJsonDeep(value), null, 2)}\n`;
 }
 
 /**
@@ -117,7 +102,7 @@ export function containedPath(root: string, path: string): string {
       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`,
+      fix: `x g resource post --dry-run   # name every file relative to the app root, no ".." segment`,
     });
   return target;
 }
@@ -156,10 +141,13 @@ async function planJsonMerge(
   }
   // 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);
+  const { 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) };
+  // In the file's OWN order: the diff a run leaves is the keys it added, never a re-sort of a
+  // catalog somebody keeps grouped by screen.
+  const merged = mergeJsonInPlace(existing, generated);
+  return { kind: 'write', file, absolute, contents: `${JSON.stringify(merged, null, 2)}\n` };
 }
 
 /**
@@ -210,14 +198,56 @@ function planFile(
   return { kind: 'write', file, absolute, contents: file.contents };
 }
 
+/** Every file's plan, decided without touching the disk — the first of `writeFiles`' two passes. */
+async function planAll(
+  root: string,
+  files: readonly GeneratedFile[],
+  force: boolean,
+  invocation: string,
+): Promise<readonly WritePlan[]> {
+  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),
+    );
+  }
+  return plans;
+}
+
+const conflictsOf = (plans: readonly WritePlan[]): readonly Finding[] =>
+  plans.flatMap((plan) => (plan.kind === 'conflict' ? [plan.finding] : []));
+
+/**
+ * What `writeFiles` WOULD do, and nothing else: the paths it would write and the conflicts that
+ * would stop it. `x g --dry-run` answers with this — the bare file list said "would write 33"
+ * where the real run was `X_GENERATE_CONFLICT`, and listed slice modules the run skips as writes.
+ */
+export async function planWrites(
+  root: string,
+  files: readonly GeneratedFile[],
+  force: boolean,
+  invocation = 'x g <kind> <name>',
+): Promise<WriteReport> {
+  const plans = await planAll(root, files, force, invocation);
+  const conflicts = conflictsOf(plans);
+  if (conflicts.length > 0) return { written: [], conflicts };
+  return {
+    written: plans.flatMap((plan) => (plan.kind === 'write' ? [plan.file.path] : [])),
+    conflicts: [],
+  };
+}
+
 /**
  * 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.
+ * catalog can be merged into — and touches nothing (`planWrites` is that pass alone), the second
+ * writes only when the first found no conflict at all.
  */
 export async function writeFiles(
   root: string,
@@ -230,16 +260,8 @@ export async function writeFiles(
    */
   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] : []));
+  const plans = await planAll(root, files, force, invocation);
+  const conflicts = conflictsOf(plans);
   if (conflicts.length > 0) return { written: [], conflicts };
 
   const written: string[] = [];