@ultimat3/cli 19.1.3 → 19.3.1

package/src/duplicate-packages.ts

@@ -0,0 +1,278 @@
+// Two installed copies of one registry-holding framework package, found before either registry is
+// asked anything. `@ultimat3/i18n`, `@ultimat3/policy` and `@ultimat3/entity` each keep their
+// registry at MODULE scope, so a second module instance is a second, EMPTY registry: an app whose
+// `packages/i18n` workspace pinned `@ultimat3/i18n@19.0.0` while its root had 19.1.0 registered
+// every catalog into the workspace's copy, the CLI read the root's, and `x i18n check` answered
+// `X_CATALOG_UNREGISTERED` with a fix that said to move a `defineCatalogs()` call that was already
+// exactly where the fix said to put it (ai-maxxing, 2026-09-05). The same split is the one
+// `local-cli.ts` hands over for — a global `x` is a second copy of `@ultimat3/entity` — except this
+// one lives inside the app's own `node_modules`, where no hand-over can reach it.
+
+// why: Bun ships no symlink-resolving stat and no path API of its own. `realpathSync` is the whole
+// decision — two symlinks to one directory are one module instance, and two store entries at one
+// version are still two — and `dirname`/`join` walk a resolved entry up to the package that owns it.
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+// why: Bun exposes no path API — `dirname` walks a resolved entry up to the package that owns it,
+// `join` reaches its manifest, and `relative` is what turns an absolute hit into the repo-relative
+// path a finding names.
+import { dirname, join, relative } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { Finding } from './output';
+import { readWorkspaceGraph } from './workspace-graph';
+
+/**
+ * The packages whose registry is a module-scope table, and what that table is called in a finding.
+ * A second copy of any other `@ultimat3/*` package is a mixed-version install the CHANGELOG already
+ * warns against; a second copy of one of these is an app that registers into a registry nothing
+ * reads.
+ */
+export const REGISTRY_PACKAGES: Readonly<Record<string, string>> = {
+  '@ultimat3/i18n': 'catalog registry',
+  '@ultimat3/policy': 'permission registry',
+  '@ultimat3/entity': 'entity registry',
+};
+
+/** One resolution of one package from one directory. `dir` is the package's REAL directory. */
+export interface InstalledCopy {
+  readonly pkg: string;
+  /** Where the resolution started, app-root-relative: `.`, a workspace dir, or `CLI_ORIGIN`. */
+  readonly from: string;
+  readonly dir: string;
+  readonly version: string;
+}
+
+/** The `from` label of the copy the running CLI itself imports. */
+export const CLI_ORIGIN = 'the x CLI';
+
+/** One distinct copy of a duplicated package, and every origin that resolves to it. */
+export interface DuplicateCopy {
+  readonly dir: string;
+  readonly version: string;
+  readonly from: readonly string[];
+}
+
+export interface DuplicateInstall {
+  readonly pkg: string;
+  /** Newest version first; ties in `dir` order, so a report is stable across runs. */
+  readonly copies: readonly DuplicateCopy[];
+}
+
+/**
+ * Semver order, through Bun's own comparator so `19.1.0-beta.1` sorts BELOW `19.1.0` and
+ * `19.10.0` above `19.9.0`; a string that is not a version falls back to its text, because the
+ * report still has to be stable over whatever a hand-edited manifest carries.
+ */
+function compareVersions(left: string, right: string): number {
+  try {
+    return Bun.semver.order(left, right);
+  } catch {
+    return left.localeCompare(right);
+  }
+}
+
+/**
+ * The pure half: every package that resolves to more than one real directory. Keyed by REALPATH,
+ * never by version — two workspace symlinks to one checkout are one instance whatever the labels
+ * say, and two store entries both stamped `19.1.0` are two instances all the same, because a
+ * module registry is per module instance and not per version string.
+ */
+export function duplicateInstalls(copies: readonly InstalledCopy[]): readonly DuplicateInstall[] {
+  const byPackage = new Map<string, Map<string, { version: string; from: string[] }>>();
+  for (const copy of copies) {
+    const dirs = byPackage.get(copy.pkg) ?? new Map<string, { version: string; from: string[] }>();
+    const entry = dirs.get(copy.dir) ?? { version: copy.version, from: [] };
+    if (!entry.from.includes(copy.from)) entry.from.push(copy.from);
+    dirs.set(copy.dir, entry);
+    byPackage.set(copy.pkg, dirs);
+  }
+  const duplicates: DuplicateInstall[] = [];
+  for (const [pkg, dirs] of byPackage) {
+    if (dirs.size < 2) continue;
+    const sorted = [...dirs.entries()]
+      .map(([dir, entry]) => ({ dir, version: entry.version, from: [...entry.from].sort() }))
+      .sort(
+        (left, right) =>
+          compareVersions(right.version, left.version) || left.dir.localeCompare(right.dir),
+      );
+    duplicates.push({ pkg, copies: sorted });
+  }
+  return duplicates.sort((left, right) => left.pkg.localeCompare(right.pkg));
+}
+
+/** The filesystem this reader touches, injectable so a fixture needs no install. */
+export interface DuplicateIo {
+  /** The resolved entry file, or throws — `Bun.resolveSync`'s contract. */
+  resolve(specifier: string, from: string): string;
+  realpath(path: string): string;
+  exists(path: string): boolean;
+  readText(path: string): string;
+}
+
+const nodeIo: DuplicateIo = {
+  resolve: (specifier, from) => Bun.resolveSync(specifier, from),
+  realpath: (path) => realpathSync(path),
+  exists: (path) => existsSync(path),
+  readText: (path) => readFileSync(path, 'utf8'),
+};
+
+/**
+ * Deep enough for `src/index.ts` and for any entry an `exports` map could point at, shallow enough
+ * that a resolver answering something unexpected stops rather than walking to `/` — the same bound
+ * `framework-scope.ts` walks under.
+ */
+const MAX_DEPTH = 6;
+
+/**
+ * The real directory owning `entry`, judged by the `package.json` that NAMES `pkg`. The entry alone
+ * is not enough: a workspace checkout resolves to `packages/i18n/src/index.ts` and a published
+ * install to `…/dist/index.js`, and the first `package.json` upward from either is the one that
+ * says which package it is — a stray manifest in a `src/` would otherwise be reported as a copy.
+ */
+function packageDirOf(
+  pkg: string,
+  entry: string,
+  io: DuplicateIo,
+): { dir: string; version: string } | undefined {
+  let dir = dirname(entry);
+  for (let depth = 0; depth < MAX_DEPTH; depth += 1) {
+    const manifest = join(dir, 'package.json');
+    if (io.exists(manifest)) {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(io.readText(manifest));
+      } catch {
+        return undefined;
+      }
+      if (typeof parsed !== 'object' || parsed === null) return undefined;
+      const fields = parsed as Record<string, unknown>;
+      if (fields['name'] !== pkg) return undefined;
+      const version = fields['version'];
+      return { dir: io.realpath(dir), version: typeof version === 'string' ? version : '0.0.0' };
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+  return undefined;
+}
+
+/**
+ * One resolution per (package, origin), for every origin that IMPORTS the package in a real boot:
+ * the app root, every workspace the root manifest claims, and this CLI's own directory — which is
+ * what `x i18n check` reads its registry through. A directory that cannot resolve the package
+ * contributes nothing: a workspace with no dependency on `@ultimat3/policy` is not a copy of it.
+ *
+ * `cliDir` is injectable so a test can stand the CLI somewhere with no framework under it;
+ * production passes nothing, and the only defensible base is this module's own directory.
+ */
+export async function installedCopies(
+  root: string,
+  packages: readonly string[],
+  io: DuplicateIo = nodeIo,
+  cliDir: string = import.meta.dir,
+): Promise<readonly InstalledCopy[]> {
+  const origins: { from: string; dir: string }[] = [{ from: '.', dir: root }];
+  for (const node of await readWorkspaceGraph(root)) {
+    origins.push({ from: node.dir, dir: join(root, node.dir) });
+  }
+  origins.push({ from: CLI_ORIGIN, dir: cliDir });
+
+  const copies: InstalledCopy[] = [];
+  for (const pkg of packages) {
+    for (const origin of origins) {
+      let entry: string;
+      try {
+        entry = io.resolve(pkg, origin.dir);
+      } catch {
+        continue;
+      }
+      const owner = packageDirOf(pkg, entry, io);
+      if (owner === undefined) continue;
+      copies.push({ pkg, from: origin.from, dir: owner.dir, version: owner.version });
+    }
+  }
+  return copies;
+}
+
+/** The two steps composed — what `x i18n check` and the gate's `policy` step call. */
+export async function findDuplicateInstalls(
+  root: string,
+  packages: readonly string[],
+): Promise<readonly DuplicateInstall[]> {
+  return duplicateInstalls(await installedCopies(root, packages));
+}
+
+/** What a caller injects in place of `findDuplicateInstalls`, so a fixture needs no install. */
+export type DuplicateProbe = (
+  root: string,
+  packages: readonly string[],
+) => Promise<readonly DuplicateInstall[]>;
+
+/** `<dir>@<version> (resolved from ., packages/i18n)` — one clause per copy. */
+const renderCopy = (root: string, copy: DuplicateCopy): string => {
+  const shown = relative(root, copy.dir).replaceAll('\\', '/');
+  const dir = shown === '' || shown.startsWith('..') ? copy.dir : shown;
+  return `${dir}@${copy.version} (resolved from ${copy.from.join(', ')})`;
+};
+
+/** The manifest an origin pins its dependencies in — the file the fix names an edit to. */
+const manifestOf = (from: string): string | undefined =>
+  from === CLI_ORIGIN ? undefined : from === '.' ? 'package.json' : `${from}/package.json`;
+
+/**
+ * The one sentence both findings share: which copies, where each is read from, and why that is
+ * an empty registry rather than a version skew. `root` is what turns a store path into the
+ * app-relative one an agent can open.
+ */
+export function duplicateCause(root: string, duplicate: DuplicateInstall): string {
+  const registry = REGISTRY_PACKAGES[duplicate.pkg] ?? 'registry';
+  const copies = duplicate.copies.map((copy) => renderCopy(root, copy)).join(' and ');
+  return (
+    `${duplicate.copies.length} copies of ${duplicate.pkg} are installed: ${copies} — each is ` +
+    `its own module instance with its own ${registry}, so what the app registers into one, the ` +
+    'other never sees'
+  );
+}
+
+/**
+ * The command that leaves ONE copy, then the command that re-checks. Two shapes, because the two
+ * causes repair differently: copies at different versions are a workspace pinning an older
+ * range, and the fix names that manifest and the version to pin; copies at ONE version are two
+ * resolutions of one range — a stale nested `node_modules`, or two peer sets in the store — and
+ * the only edit that can collapse them is the install itself.
+ */
+export function duplicateFix(duplicate: DuplicateInstall, recheck: string): string {
+  const newest = duplicate.copies[0];
+  const older = duplicate.copies.filter((copy) => copy.version !== newest?.version);
+  if (newest !== undefined && older.length > 0) {
+    const manifests = [
+      ...new Set(older.flatMap((copy) => copy.from.map(manifestOf)).filter(Boolean)),
+    ];
+    const where = manifests.length === 0 ? 'every package.json that pins it' : manifests.join(', ');
+    return `set "${duplicate.pkg}": "${newest.version}" in ${where}, then: bun install && ${recheck}`;
+  }
+  return `bun install --force   # one resolution of ${duplicate.pkg} for every workspace; then: ${recheck}`;
+}
+
+/**
+ * The finding both steps report. Its own code rather than the registry's own (`X_CATALOG_UNREGISTERED`,
+ * `X_PERMISSION_UNKNOWN`): those name a symptom that has a source-level repair, and this names an
+ * install with no source-level repair at all — an agent handed the registry's fix edits a file that
+ * is already right, re-runs, and is red again.
+ */
+export function duplicateFinding(
+  root: string,
+  duplicate: DuplicateInstall,
+  recheck: string,
+): Finding {
+  const at = duplicate.copies
+    .flatMap((copy) => copy.from.map(manifestOf))
+    .find((manifest): manifest is string => manifest !== undefined);
+  return {
+    code: 'X_PACKAGE_DUPLICATED',
+    cause: duplicateCause(root, duplicate),
+    fix: duplicateFix(duplicate, recheck),
+    docs: ERROR_DOCS_URL,
+    ...(at === undefined ? {} : { at }),
+  };
+}

package/src/error-catalog.ts

@@ -3,7 +3,7 @@
 // commands actually need — so without this, `x errors explain X_UNAUTHENTICATED` answered "not a
 // registered error code" for a code the framework throws on every unauthenticated request.
 
-import { listErrorCodes } from '@ultimat3/core';
+import { listErrorCodes, stringField } from '@ultimat3/core';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 
@@ -82,10 +82,9 @@ let cached: Promise<ErrorCatalog> | undefined;
  * the host gap. Anything else escaped the package's own module evaluation and is its defect.
  */
 const isUnresolved = (thrown: unknown): boolean =>
-  typeof thrown === 'object' &&
-  thrown !== null &&
-  'code' in thrown &&
-  thrown.code === 'ERR_MODULE_NOT_FOUND';
+  // `stringField`, never `'code' in thrown && thrown.code`: see `cmd-i18n.ts`'s `isAlreadyExists`
+  // — an `in` guard narrows the type and reads the property off a foreign value all the same.
+  stringField(thrown, 'code') === 'ERR_MODULE_NOT_FOUND';
 
 /** The package's own error, named and located, so the report says what broke and what to run. */
 function initFailure(specifier: string, thrown: unknown): Finding {

package/src/error-codes.ts

@@ -148,6 +148,11 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_SECRETS_EDITOR_MISSING',
   'X_SECRETS_EDIT_FAILED',
   'X_WORKSPACE_DEP_UNDECLARED',
+  // Two module instances of a registry-holding package inside ONE app's `node_modules`. Its own
+  // code and not the registry's (`X_CATALOG_UNREGISTERED`, `X_PERMISSION_UNKNOWN`): those carry a
+  // source-level fix, and an agent following it here edits a file that is already right — the
+  // repair is an install, and only `duplicate-packages.ts` can see that.
+  'X_PACKAGE_DUPLICATED',
   'X_SHOT_BROWSER_MISSING',
   // `x shot --island` — one code per way a component's named state fails to become a picture.
   // The last of the four is the one that gates: it is checked against the expansion computed
@@ -290,6 +295,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_SECRETS_EDITOR_MISSING: 'no $EDITOR to open the decrypted secrets in',
   X_SECRETS_EDIT_FAILED: 'the editor exited non-zero, so nothing was resealed',
   X_WORKSPACE_DEP_UNDECLARED: 'a workspace imports another workspace it does not declare',
+  X_PACKAGE_DUPLICATED: 'two copies of one registry-holding framework package are installed',
   X_SHOT_BROWSER_MISSING: 'x shot found no browser library in the app',
   X_SHOT_ISLAND_STATES_EMPTY: 'an island states file declares no manifest',
   X_SHOT_ISLAND_UNPHOTOGRAPHABLE: 'the island never reached a state worth photographing',

package/src/fix-command.ts

@@ -45,6 +45,18 @@ const CITATION = new RegExp(
  */
 const FLAG = /(?:^|\s)--(?:no-)?([a-z][a-z\d-]*)/g;
 
+/**
+ * A bare `--`: the boundary past which the words belong to ANOTHER tool, not to `x`. Only `x test`
+ * declares one (`CommandSpec.passthrough`), and every other command refuses a non-empty tail — so
+ * this is read for two reasons at once: the tail's flags are not the command's, and a tail cited
+ * on a command that hands nothing on is a documented `X_CLI_BAD_FLAG`.
+ *
+ * Without it, `x test unit -- --coverage --bail` — the only spelling that reaches bun's own flags
+ * — read as `x test --coverage`, and the one line documenting the passthrough was a standing
+ * false finding on the rule written to keep documented invocations runnable.
+ */
+const BARE_TAIL = /(?:^|\s)--(?=\s|$)/;
+
 /**
  * Where a citation's argument list ends. `;`, `|` and `&` start a second shell word, `#` starts a
  * comment, and a backtick or a quote closes the span the citation was written in — past any of
@@ -60,6 +72,11 @@ export interface FixCitation {
   readonly positional: string | undefined;
   /** Long flags written after it, in order, `--` and any `no-` stripped. */
   readonly flags: readonly string[];
+  /**
+   * The words after a bare `--`, when the citation has one. Absent otherwise, so a citation with
+   * no tail is the same object it has always been.
+   */
+  readonly tail?: readonly string[];
 }
 
 /**
@@ -82,11 +99,24 @@ export function fixCitations(fix: string): readonly FixCitation[] {
     const tail = fix.slice(start, next);
     const stop = ARGUMENT_END.exec(tail)?.index;
     const args = stop === undefined ? tail : tail.slice(0, stop);
+    // The tail is split off BEFORE the flags are read: `--coverage` after a bare `--` is bun's
+    // flag, and charging it to `x test` is the same error as charging a second citation's flags
+    // to the first one, which the slice above already exists to prevent.
+    const cut = BARE_TAIL.exec(args);
+    const head = cut === null ? args : args.slice(0, cut.index);
+    const handed =
+      cut === null
+        ? undefined
+        : args
+            .slice(cut.index + cut[0].length)
+            .split(/\s+/)
+            .filter((word) => word !== '');
     return {
       command: match[1] as string,
       sub: match[2],
       positional: match[3],
-      flags: [...args.matchAll(FLAG)].map((flag) => flag[1] as string),
+      flags: [...head.matchAll(FLAG)].map((flag) => flag[1] as string),
+      ...(handed === undefined ? {} : { tail: handed }),
     };
   });
 }
@@ -222,6 +252,15 @@ export function citationFault(
     }
   }
   if (planned) return undefined;
+  // Judged before the flags, because a tail is why they are not the command's. A command that
+  // declares no `passthrough` refuses a non-empty `--` outright (`parse.ts`), so a page handing a
+  // reader one is handing them `X_CLI_BAD_FLAG` — the same class as an undeclared flag.
+  if (citation.tail !== undefined && citation.tail.length > 0 && spec.passthrough !== true) {
+    return {
+      subject: `x ${spec.name} --`,
+      reason: `and ${spec.name} hands nothing to another tool — the parser refuses the -- with X_CLI_BAD_FLAG rather than dropping ${citation.tail.join(' ')}`,
+    };
+  }
   const declared = declaredFlags(spec);
   const unknown = citation.flags.find((flag) => !declared.has(flag));
   if (unknown === undefined) return undefined;

package/src/fix-path.ts

@@ -5,10 +5,11 @@
 
 // why: Bun exposes no synchronous existence primitive — `Bun.file(p).exists()` is async and answers
 // false for a DIRECTORY, and this rule has to judge both. Delete when Bun ships one.
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 // why: Bun exposes no path-join or dirname primitive. The same necessity `error-contract.ts`
 // already records for `join`.
 import { dirname, join } from 'node:path';
+import { readIgnoreFile } from './gitignore';
 
 /**
  * The extensions a fix line may cite a file by — the SAME set `COMMAND_TOKENS`' file pattern is
@@ -77,22 +78,20 @@ function isJudgeable(token: string, root: string): boolean {
 /**
  * The directories the root `.gitignore` lists as ignored, as `dir/` prefixes. Only the plain
  * directory form is read (`.personal/`, `/tmp/`, `dist`): a negation, a glob or a nested pattern
- * is a rule about files the repo may still hold, and this exclusion errs towards judging.
+ * is a rule about files the repo may still hold, and this exclusion errs towards judging — which
+ * is why it keeps its own narrow policy over `parseGitignore`'s answer rather than asking
+ * `isGitIgnored`. What it may NOT keep is a second PARSER: `dev-watch.ts` needs full gitignore
+ * semantics, and two readers of one file are two answers to what an app committed.
  */
 const ignoredDirs = new Map<string, readonly string[]>();
 
 function ignoredDirectories(root: string): readonly string[] {
   const known = ignoredDirs.get(root);
   if (known !== undefined) return known;
-  const file = join(root, '.gitignore');
-  const lines = existsSync(file) ? readFileSync(file, 'utf8').split('\n') : [];
-  const dirs = lines
-    .map((line) => line.trim())
-    .filter((line) => line !== '' && !line.startsWith('#') && !line.startsWith('!'))
-    .filter((line) => !/[*?[\]]/.test(line))
-    .map((line) => line.replace(/^\//, '').replace(/\/$/, ''))
-    .filter((line) => line !== '' && !line.includes('/'))
-    .map((dir) => `${dir}/`);
+  const dirs = readIgnoreFile(root)
+    .filter((pattern) => !pattern.negated)
+    .filter((pattern) => !/[*?[\]]/.test(pattern.glob) && !pattern.glob.includes('/'))
+    .map((pattern) => `${pattern.glob}/`);
   ignoredDirs.set(root, dirs);
   return dirs;
 }

package/src/flag-number.ts

@@ -65,3 +65,18 @@ export const PORT_RANGE = { min: 0, max: 65_535 } as const;
  */
 export const neighbouringPort = (port: number): number =>
   port < PORT_RANGE.max ? port + 1 : PORT_RANGE.max - 1;
+
+/**
+ * The same suggestion for a caller that binds a PAIR. `x dev --port N` occupies N and N + 1, so
+ * `neighbouringPort` hands back the neighbour — which, when it is the neighbour that was taken, is
+ * the very socket the refusal is about: `x dev --port 3999` died on 4000 and its `fix:` said
+ * `x dev --port 4000`, and `x doctor` said it too, about the same pair (both pinned by a test
+ * named "its fix is a command that ends the failure"). Two above is the nearest base whose own
+ * pair touches neither.
+ *
+ * Downward at the top of the range, for `neighbouringPort`'s reason and one further: the answer's
+ * OWN neighbour has to be a port, or `syncPortFor` refuses the suggestion with `X_PORT_INVALID`.
+ * Only reachable above 65532, so the subtraction can never go below the range.
+ */
+export const portPairAfter = (port: number): number =>
+  port + 2 < PORT_RANGE.max ? port + 2 : port - 2;

package/src/generate-kinds.ts

@@ -3,7 +3,12 @@
 // that held both had reached the 500-line ceiling, one generator short of failing its own gate.
 
 import { nearestName } from '@ultimat3/core';
-import { BadFlagError, MissingPositionalError, UnknownCommandError } from './errors';
+import {
+  BadFlagError,
+  MissingPositionalError,
+  MissingSubcommandError,
+  UnknownCommandError,
+} from './errors';
 import type { Surface } from './templates';
 
 export const GENERATORS = [
@@ -57,14 +62,26 @@ export function assertSurfaceSupported(kind: Generator, surface: Surface, name:
  * pins for a command that resembles nothing, and the reason `nearestName` is never asked about an
  * ABSENT kind: the empty string is within the cutoff of `job`, so `x g` would "suggest" a
  * generator nobody typed.
+ *
+ * And a THIRD rule, for the word that is not there at all: no generator is a missing subcommand,
+ * never an unknown command — see the branch below.
  */
 export function readKind(raw: string | undefined): Generator {
   const kinds: readonly string[] = GENERATORS;
   if (raw !== undefined && kinds.includes(raw)) return raw as Generator;
-  const near = raw === undefined ? undefined : nearestName(raw, kinds);
+  // A MISSING generator is not an unknown command. `x g --json` answered `X_CLI_UNKNOWN_COMMAND:
+  // "x g" is not a command` — false, and it sends an agent hunting a typo it did not make: `g` is
+  // in `x help`, the parser reaches it, and `x g route foo` runs. The same argument `readName`
+  // makes below about the missing `<name>`, one word earlier. `MissingSubcommandError` because
+  // the generator is a closed vocabulary the caller did not choose from — its cause lists every
+  // one, which is the answer to "which of these did I leave out"; the near-miss reader below is
+  // deliberately never asked about an absent word, since the empty string is within `job`'s
+  // cutoff and would "suggest" a generator nobody typed.
+  if (raw === undefined) throw new MissingSubcommandError({ command: 'g', known: GENERATORS });
+  const near = nearestName(raw, kinds);
   const suggestion = GENERATORS.find((kind) => kind === near);
   throw new UnknownCommandError({
-    path: `g ${raw ?? ''}`.trim(),
+    path: `g ${raw}`.trim(),
     known: GENERATORS,
     suggestion: suggestion === undefined ? 'help g' : `g ${suggestion} ${EXAMPLE_NAME[suggestion]}`,
   });
@@ -93,7 +110,40 @@ export function readName(raw: string | undefined, kind: Generator): string {
   throw new MissingPositionalError({
     command: `g ${kind}`,
     positional: 'name',
-    example: `x g ${kind} ${EXAMPLE_NAME[kind]}`,
+    example: exampleFor(kind),
+  });
+}
+
+/**
+ * The one read of `EXAMPLE_NAME`, and it is guarded: `kind` is a validated union today, which is
+ * the argument every instance `scripts/proto-index.ts` reports had before it stopped being true —
+ * a `Record` object literal answers an `Object.prototype` member for a key nobody declared, and
+ * this string is pasted into a shell. Two callers, one read.
+ */
+const exampleFor = (kind: Generator): string =>
+  `x g ${kind} ${Object.hasOwn(EXAMPLE_NAME, kind) ? EXAMPLE_NAME[kind] : '<name>'}`;
+
+/**
+ * `resource:verb`, or nothing is written. `--permission` reaches the generated page in three
+ * places — the `permissions:` array, a `definePermissions()` call and a `PermissionRegistry`
+ * augmentation — and `@ultimat3/policy`'s `Permission` type is `${string}:${string}`, so
+ * `x g admin:page ops --permission ops` used to emit a page that does not compile. A quote or a
+ * space is refused for the same reason one step earlier: the value is spliced into a string
+ * literal in emitted source, and neither is a permission any app declares.
+ *
+ * It cannot ask whether the app DECLARES the permission — `x g` writes files against a root, it
+ * never loads the app, and an app that will not import is exactly when a generator is reached for.
+ * The generated page declaring it is what closes that half (`templates/admin-page.ts`).
+ */
+const PERMISSION_SHAPE = /^[a-z0-9][a-z0-9_.-]*:[a-z0-9*][a-z0-9_.*-]*$/i;
+
+export function readPermission(raw: string | undefined, kind: Generator): string | undefined {
+  if (raw === undefined || PERMISSION_SHAPE.test(raw)) return raw;
+  throw new BadFlagError({
+    flag: 'permission',
+    command: 'g',
+    reason: `expects a permission of the form <resource>:<verb>, got "${raw}"`,
+    fix: `${exampleFor(kind)} --permission ops:read`,
   });
 }
 

package/src/generate-write.ts

@@ -27,11 +27,34 @@ function parseJsonObject(text: string): Record<string, unknown> | undefined {
     : 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.
+ *
+ * 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.
+ */
+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 {
-  const sorted = Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)));
-  return `${JSON.stringify(sorted, null, 2)}\n`;
+  return `${JSON.stringify(sortDeep(value), null, 2)}\n`;
 }
 
 /**