@ultimat3/cli 19.2.0 → 19.3.1

package/src/dev-watch.ts

@@ -1,53 +1,75 @@
-// Which writes under the app root are a source change, and which are noise. Split out of
-// `cmd-dev.ts` because it is a rule with cases rather than four lines of glue, and because the
-// answer needs a test of its own: a watcher that reloads on the wrong write is invisible — the
-// dev server stays correct and merely does the most expensive thing it can do, repeatedly.
+// Which paths under the app root `x dev` must not watch, and the rule is REGISTRATION rather than
+// filtering: `watch(root, { recursive: true })` takes one inotify descriptor per directory before
+// any filter runs, so an answer given after the event has already cost the kernel queue, a JS
+// callback and a slot out of `max_user_watches`. Measured on a monorepo root: 1901 descriptors,
+// 1490 of them under `.git/` and `node_modules/`, and one `git status` delivering 5 events.
 //
-// What it was: `filename.includes('.x/') || filename.includes('node_modules')`. Measured against
-// ai-maxxing, whose checkout carries `.git/`, `.personal/`, `.claude/worktrees/` (two FULL copies
-// of the app) and `coverage/`, every write under any of them ran a whole `appManifest()` plus a
-// `buildIslands()` over ten islands. `git status`, an agent's scratch file and a coverage run each
-// cost a full rebuild, and each rebuild re-minted every island chunk.
-//
-// `includes` was also the wrong operator, not just the wrong list: a directory legitimately named
-// `my-node_modules-notes/` was excluded from the dev loop for a substring, and `notes/.xyz/` for
-// another. The match is on a PATH SEGMENT, so only the directory itself is ever ignored.
+// The ignore set is the app's own `.gitignore`, read with git's own anchoring (`gitignore.ts`),
+// plus a floor of directory names an ignore file need not name. It was seven hand-listed names,
+// and both halves of that were wrong: nothing read `.gitignore`, so `tsconfig.tsbuildinfo` —
+// rewritten by every `bun run typecheck` — ran a full `appManifest()` plus `buildIslands()`; and
+// `dist` and `coverage` were matched at ANY depth, so an app's own `/dist` or `/coverage` route
+// never reloaded at all, silently.
+
+// why: Bun exposes no path-join primitive. The same necessity `fix-path.ts` already records.
+import { join } from 'node:path';
+import type { IgnoreScope } from './gitignore';
+import { ignoreScopes, isGitIgnored } from './gitignore';
+import { pathSegments } from './path-segments';
 
 /**
- * Directories whose writes are never an app source change.
+ * Directory names no `.gitignore` can be relied on to carry, matched as a path SEGMENT at any
+ * depth. Every entry earns its line, and every one is either dotted or `node_modules` — which is
+ * what makes the any-depth match safe: a `site/` subtree is a URL tree, and neither a dot-directory
+ * nor an install is ever a route.
  *
- * Every entry earns its line and none is a guess:
- * - `.x` — the framework's own state directory: PGlite's data, the dev lock, the static export,
- *   `build-stats.json`. `x build` writes here, which made a build trigger reloads of the process
- *   that was running it.
- * - `node_modules` — an install, not an edit. `x dev` does not reload for a dependency change
- *   because it cannot: the modules are already in this process's cache.
- * - `.git` — the reason this list exists. `git status`, `git fetch` and every commit rewrite index
- *   and ref files continuously, and none of them is a source edit; a checkout of a branch IS one,
- *   but it also writes the source files themselves, which this list does not touch.
- * - `.personal` — an app's uncommitted local state (ai-maxxing's fleet file, its inventory, its
- *   credentials). Written by scripts while the dev server runs.
+ * - `.git` — git never names its own directory in an ignore file, and `git status`, `git fetch` and
+ *   every commit rewrite index and ref files continuously. The reason this list exists.
+ * - `.x` — the framework's own state: PGlite's data directory (which THIS process writes
+ *   continuously), the dev lock, the static export, `build-stats.json`.
+ * - `node_modules` — an install, not an edit. `x dev` cannot reload for a dependency change: the
+ *   modules are already in this process's cache.
+ * - `.personal` — an app's uncommitted local state, written by scripts while the dev server runs.
  * - `.claude` — agent scratch, session logs and worktrees. ai-maxxing keeps two entire copies of
  *   the app under `.claude/worktrees/`, so a second agent's edit rebuilt the first agent's islands.
- * - `dist`, `coverage` — build and test output. Both are written by commands an author runs
- *   BESIDE `x dev`, which is exactly when a spurious rebuild costs the most.
+ *
+ * `dist` and `coverage` were here and are deliberately not: both are ordinary build output that
+ * every ignore file already names, and hand-listing them cost an app its own routes.
  */
-export const IGNORED_DIRECTORIES: readonly string[] = [
+export const ALWAYS_IGNORED_DIRECTORIES: readonly string[] = [
+  '.git',
   '.x',
   'node_modules',
-  '.git',
   '.personal',
   '.claude',
-  'dist',
-  'coverage',
 ];
 
+/** The ignore set as one question, so the walk and the event filter cannot disagree. */
+export interface DevIgnore {
+  /** `path` is app-root-relative; `isDirectory` decides every trailing-slash rule git holds. */
+  ignores(path: string, isDirectory: boolean): boolean;
+  /** The `.gitignore` files this set was built from, outermost first — what `--json` can report. */
+  readonly scopes: readonly IgnoreScope[];
+}
+
 /**
- * A path segment, never a substring. `filename` arrives from `node:fs`'s watcher root-relative and
- * with the platform's separator, so both are normalised before the split — a rule that reads
- * `foo/node_modules/bar` and not `foo\\node_modules\\bar` is a rule that does not exist on Windows.
+ * Read once, at boot and again on every write that names `.gitignore`. A snapshot rather than a
+ * live reader: the watcher rebuilds the whole set and re-walks, so a directory the author just
+ * ignored drops its descriptor instead of keeping one nothing will ever read an event from.
+ *
+ * Two limits, both deliberate. An ANCESTOR ignore file is read at boot and is not watched — it sits
+ * outside the app root, so `x dev` has no descriptor there and a restart is the way to pick up an
+ * edit to it. A NESTED one (`apps/web/.gitignore`) is not read at all: `ignoreScopes` walks upward
+ * only, and watching for one would mean a scope per directory in the tree.
  */
-export function isIgnoredPath(filename: string): boolean {
-  const segments = filename.replaceAll('\\', '/').split('/');
-  return segments.some((segment) => IGNORED_DIRECTORIES.includes(segment));
+export function devIgnore(root: string): DevIgnore {
+  const scopes = ignoreScopes(root);
+  return {
+    scopes,
+    ignores(path: string, isDirectory: boolean): boolean {
+      const segments = pathSegments(path);
+      if (segments.some((segment) => ALWAYS_IGNORED_DIRECTORIES.includes(segment))) return true;
+      return isGitIgnored(scopes, join(root, ...segments), isDirectory);
+    },
+  };
 }

package/src/doctor-offline.ts

@@ -0,0 +1,122 @@
+// `x doctor`'s offline-fallback check: the path the app DECLARED, against the routes it really
+// serves. Its own file because answering it needs the app's config and its route table, and
+// `cmd-doctor.ts`'s job is the probe rather than the loading — the `db-backfill.ts` split, one
+// diagnostic over.
+
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { describeRoutes } from '@ultimat3/render';
+import { loadApp } from './app-load';
+import { APP_CONFIG_FILE } from './app-root';
+import type { Finding } from './output';
+import { loadPwaArtifacts } from './pwa-artifacts';
+
+/** A route as this check reads one: the URL it answers, and the surface that answers it. */
+export interface NavigableRoute {
+  readonly path: string;
+  readonly surface: string;
+}
+
+export interface OfflineFallbackFact {
+  /**
+   * `pwa.offline.fallback` as `loadPwaArtifacts` read it, or `null` — which is both "this app
+   * declares no PWA" and "it declares one with no fallback". Either way no service worker is
+   * emitted at all (`serviceWorkerArtifacts` answers `undefined`), so the two share one remedy.
+   */
+  readonly fallback: string | null;
+  /**
+   * Every registered route, or `undefined` when the app would not load. `appEntities`' rule
+   * (`schema-drift.ts`) one registry over: a module that will not import leaves the registry
+   * short, and a short registry reads as "no route serves it" — a generator handed out for a route
+   * the app already has, over one file's syntax error.
+   */
+  readonly routes: readonly NavigableRoute[] | undefined;
+}
+
+/**
+ * The one surface an OFFLINE navigation can land on. `api/` answers a JSON document and `shared/`
+ * is not a URL at all — the pair `sw-artifacts.ts` excludes for the same reason — and `app/` is
+ * excluded for a third: `SURFACE_SPECS` allows it `stream | ssr` and nothing else, only a `static`
+ * route is prerendered, and the service worker precaches a rendered DOCUMENT
+ * (`serviceWorkerArtifacts` reads `documents.get(fallback)`). So an `app/` fallback has nothing
+ * to precache and the offline navigation it is supposed to answer reaches the network and fails —
+ * this check passing for it is the false green it exists to prevent.
+ *
+ * It accepted `app` until 2026-09, on the argument that both surfaces answer the same URL and it
+ * is the FIX that is opinionated. True about URLs and wrong about offline: the fix's own comment
+ * below already refuses `--surface app`, so the check and the remedy disagreed about one code.
+ *
+ * Residual, and NOT closed by this: a `site/` route declaring `render: 'ssr'` is not prerendered
+ * either. `NavigableRoute` carries no render mode, and `describeRoutes()` has one — the narrower
+ * check belongs with it.
+ */
+const NAVIGABLE: ReadonlySet<string> = new Set(['site']);
+
+/**
+ * A fallback `x g route <name> --surface site` can actually create: ONE path segment, which is
+ * what the generator turns into `apps/<app>/site/<name>/page.tsx` and therefore into `/<name>`. A
+ * nested or punctuated path would be slugified into a DIFFERENT url (`/support/offline` →
+ * `/support-offline`), so offering the command there is a fix that runs and leaves the finding
+ * exactly where it was.
+ *
+ * `--surface site`, and never `app`: the document that answers a lost network must render with no
+ * network, no session and no database, which `app/` (`ssr | stream`) cannot promise — the reason
+ * `x new` scaffolds it under `site/` (`wiki/Upgrading.md`) — and it is the line `@ultimat3/pwa`'s
+ * own `X_PWA_NO_OFFLINE_FALLBACK` hands out. Two fixes for one code are two answers.
+ */
+const GENERATABLE = /^\/([a-z][a-z0-9-]*)$/;
+
+const finding = (cause: string, fix: string): Finding => ({
+  code: 'X_PWA_NO_OFFLINE_FALLBACK',
+  cause,
+  fix,
+  docs: ERROR_DOCS_URL,
+  at: APP_CONFIG_FILE,
+});
+
+/**
+ * The declared fallback, judged against the route table — never against a filename.
+ *
+ * It WAS a filename: the literal `apps/web/app/offline.tsx`, which `assertRouteFilename` refuses
+ * outright (the directory is the URL, so a page is `page.tsx`), while `x new` scaffolds
+ * `apps/web/site/offline/page.tsx` and this finding's own `fix:` writes
+ * `apps/web/app/offline/page.tsx`. Every one of the three is a different path, so the check was
+ * red for every app the framework has ever produced and no invocation could clear it — the shape
+ * `budgets.ts` calls a false green read backwards, and the reason a diagnostic is held to being
+ * closable by its own fix.
+ */
+export function offlineFallbackFinding(fact: OfflineFallbackFact): Finding | undefined {
+  if (fact.routes === undefined) return undefined;
+  const fallback = fact.fallback;
+  if (fallback === null) {
+    return finding(
+      'no pwa.offline.fallback is declared, so no service worker is emitted and an offline navigation falls back to the browser error page',
+      `set pwa: { offline: { fallback: '/offline' } } in ${APP_CONFIG_FILE}`,
+    );
+  }
+  if (fact.routes.some((route) => route.path === fallback && NAVIGABLE.has(route.surface))) {
+    return undefined;
+  }
+  const cause = `pwa.offline.fallback is "${fallback}" and no site/ route serves it, so an offline navigation falls back to the browser error page`;
+  const name = GENERATABLE.exec(fallback)?.[1];
+  return name === undefined
+    ? finding(cause, `set pwa.offline.fallback in ${APP_CONFIG_FILE} to a path a route serves`)
+    : finding(cause, `x g route ${name} --surface site`);
+}
+
+/**
+ * The fact, read off a real app root. Both halves come from the framework's own answers — the
+ * config through `loadPwaArtifacts` (the one reader of that file) and the routes through
+ * `describeRoutes()` (the projection `x.manifest.json`, `/_x`, the sitemap and `sw.js` are all
+ * built from), so this check and the service worker cannot disagree about which routes exist.
+ */
+export async function offlineFallbackProbe(root: string): Promise<OfflineFallbackFact> {
+  const pwa = await loadPwaArtifacts(root);
+  const app = await loadApp(root);
+  return {
+    fallback: pwa?.offline.fallback ?? null,
+    routes:
+      app.findings.length > 0
+        ? undefined
+        : describeRoutes().map((route) => ({ path: route.path, surface: route.surface })),
+  };
+}

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/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`;
 }
 
 /**