@ultimat3/cli 20.2.1 → 22.0.0

package/src/error-unthrown.ts

@@ -0,0 +1,130 @@
+// A registered code nothing constructs. The registry and the reference keep a shipped code alive
+// forever — which is right — and that is exactly why a code can outlive its last thrower with no
+// gate noticing: `X_RPC_FAILED` sat registered and documented as live after the transport change
+// took its only throw site away. The reference row has to SAY so, or this reports it.
+
+import { join } from 'node:path';
+import { ERROR_DOCS_URL, maskLiterals, stripComments } from '@ultimat3/core';
+import { RESERVED_HEADING } from './error-contract';
+import type { Finding } from './output';
+import { eachSourceFile, isGenerated, isTest } from './source-files';
+import { isCodeRegistry } from './ts-scan';
+
+const CODE_LITERAL = /(['"`])(X_[A-Z0-9_]+)\1/g;
+const TITLE_KEY = /^[\t ]*(X_[A-Z0-9_]+)\s*:/gm;
+/** A registry's own code LIST line — `'X_FOO',` — declares a code and throws nothing. */
+const LIST_LINE = /^[\t ]*(['"`])X_[A-Z0-9_]+\1\s*,?\s*$/;
+/** `metaMissing: 'X_SEO_META_MISSING'` — the table `@ultimat3/seo` and `@ultimat3/ui` raise from. */
+const TABLE_ENTRY = /\b([a-z][A-Za-z0-9]*)\s*:\s*(['"`])(X_[A-Z0-9_]+)\2/g;
+const MEMBER_READ = /\.([A-Za-z_$][\w$]*)/g;
+
+/** Phrases a reference row uses to say, in words, that nothing throws the code any more. */
+const DECLARED_UNTHROWN = /thrown by nothing|not thrown/i;
+
+export interface CodeUse {
+  /** Every code a package registry names. */
+  readonly registered: ReadonlySet<string>;
+  /** Every code shipped source constructs, compares or raises outside a registry's declaration. */
+  readonly used: ReadonlySet<string>;
+}
+
+/**
+ * One file's contribution. A registry file's code LIST and title KEYS declare; any other literal in
+ * it is a use (a class's `code:`, a `?? 'X_…'` fallback, a comparison). A table entry counts only
+ * once something reads that member — which is how two packages raise every code they own.
+ */
+export function codeUseOf(source: string): {
+  readonly registered: readonly string[];
+  readonly used: readonly string[];
+  readonly table: ReadonlyMap<string, string>;
+  readonly members: readonly string[];
+} {
+  const text = stripComments(source);
+  const members = [...maskLiterals(source).matchAll(MEMBER_READ)].map((m) => m[1] ?? '');
+  if (!isCodeRegistry(text)) {
+    return {
+      registered: [],
+      used: [...text.matchAll(CODE_LITERAL)].map((m) => m[2] ?? ''),
+      table: new Map(),
+      members,
+    };
+  }
+  const registered = [
+    ...[...text.matchAll(TITLE_KEY)].map((m) => m[1] ?? ''),
+    ...[...text.matchAll(CODE_LITERAL)].map((m) => m[2] ?? ''),
+  ];
+  const table = new Map<string, string>();
+  for (const m of text.matchAll(TABLE_ENTRY)) {
+    // `code: 'X_…'` is a class or a factory constructing the code, never a table entry.
+    if (m[1] !== 'code') table.set(m[1] ?? '', m[3] ?? '');
+  }
+  const tableCodes = new Set(table.values());
+  const used: string[] = [];
+  for (const line of text.split('\n')) {
+    if (LIST_LINE.test(line)) continue;
+    for (const m of line.matchAll(CODE_LITERAL)) {
+      const code = m[2] ?? '';
+      if (!tableCodes.has(code)) used.push(code);
+    }
+  }
+  return { registered, used, table, members };
+}
+
+/** Shipped package source only: `scripts/` never ships, so a code only a gate script names is unthrown. */
+export async function collectCodeUse(root: string): Promise<CodeUse> {
+  const registered = new Set<string>();
+  const used = new Set<string>();
+  const table = new Map<string, string>();
+  const members = new Set<string>();
+  for await (const source of eachSourceFile(root)) {
+    if (!/^packages\/[^/]+\/src\//.test(source) || isTest(source) || isGenerated(source)) continue;
+    const use = codeUseOf(await Bun.file(join(root, source)).text());
+    for (const code of use.registered) registered.add(code);
+    for (const code of use.used) used.add(code);
+    for (const [member, code] of use.table) table.set(member, code);
+    for (const member of use.members) members.add(member);
+  }
+  for (const [member, code] of table) if (members.has(member)) used.add(code);
+  return { registered, used };
+}
+
+/** Codes whose reference row says nothing throws them, or that sit under the reserved heading. */
+export function declaredUnthrown(markdown: string): ReadonlySet<string> {
+  const out = new Set<string>();
+  let reserved = false;
+  for (const line of markdown.split('\n')) {
+    if (line.trim() === RESERVED_HEADING) reserved = true;
+    const row = /^\|\s*`(X_[A-Z0-9_]+)`\s*\|/.exec(line);
+    if (row !== null && (reserved || DECLARED_UNTHROWN.test(line))) out.add(row[1] ?? '');
+  }
+  return out;
+}
+
+const unthrownFinding = (code: string, page: string): Finding => ({
+  code: 'X_ERROR_CODE_UNTHROWN',
+  cause: `${code} is registered and ${page} presents it as live, but no shipped source constructs it — a reader matching on it waits for an error that cannot arrive`,
+  // Never "delete the registration": a shipped code is stable forever, and an old log line must
+  // still explain. The row is what has to change.
+  fix: `write "registered, thrown by nothing since <version>" into ${code}'s row in ${page}, naming the code that replaced it — or throw it again where it belongs`,
+  docs: ERROR_DOCS_URL,
+  at: page,
+});
+
+/**
+ * Registered, used by nothing, and not declared unthrown on the reference. A host check — the page
+ * is the host repo's to name, and only a monorepo's walk sees every package's source; in a
+ * generated app every framework code would read as unthrown.
+ */
+export async function checkErrorCodesThrown(
+  root: string,
+  page: string,
+): Promise<readonly Finding[]> {
+  const reference = Bun.file(join(root, page));
+  if (!(await reference.exists())) return [];
+  const exempt = declaredUnthrown(await reference.text());
+  const { registered, used } = await collectCodeUse(root);
+  return [...registered]
+    .filter((code) => !used.has(code) && !exempt.has(code))
+    .sort()
+    .map((code) => unthrownFinding(code, page));
+}

package/src/errors.ts

@@ -72,6 +72,20 @@ export class AppNameIsPathError extends UltimateError {
   }
 }
 
+/**
+ * `x new '!!!'`: a name that slugifies to nothing names no directory, and the scaffold landed in
+ * the cwd itself — where `--force` then committed every file the user already had there.
+ */
+export class AppNameEmptyError extends UltimateError {
+  constructor(input: { name: string; invocation: string; flags: readonly string[] }) {
+    super({
+      code: 'X_APP_NAME_EMPTY',
+      cause: `"${input.name}" has no letters or digits, so it names no directory`,
+      fix: [input.invocation, '<name-with-letters>', ...input.flags].join(' '),
+    });
+  }
+}
+
 /**
  * A command that declares subcommands, invoked with none and declaring no `defaultSubcommand`.
  *
@@ -287,35 +301,14 @@ export class FixTargetUnknownError extends UltimateError {
   }
 }
 
-/**
- * A build target names an entry file the app does not have. `x build` refuses before it spawns the
- * builder: `bun build`'s own "module not found" says nothing about which file an Ultimate app is
- * supposed to own, and `docker build`'s says nothing about which target wanted it.
- */
-export class BuildEntryMissingError extends UltimateError {
-  constructor(input: { target: string; entry: string }) {
-    super({
-      code: 'X_BUILD_ENTRY_MISSING',
-      cause: `x build --target ${input.target} builds from ${input.entry}, and the app does not have it`,
-      fix: `x new scratch-app --dry-run --json   # its file list carries ${input.entry}; copy that file into this app`,
-    });
-  }
-}
-
-/**
- * A client entry would not compile. `X_BUILD_FAILED`, not a code of its own: an island is a bundle
- * entry point like any other, and the target's own logs are what says which line. The fix builds
- * exactly that one file, so the next message an author reads is the compiler's and not the CLI's.
- */
-export class IslandBuildFailedError extends UltimateError {
-  constructor(input: { file: string; logs: string }) {
-    super({
-      code: 'X_BUILD_FAILED',
-      cause: `${input.file} is an island entry point and would not bundle: ${input.logs}`,
-      fix: `bun build --target browser ${input.file}`,
-    });
-  }
-}
+// The build and bundle refusals live in `build-errors.ts` (split at the 500-line ceiling); re-exported
+// here so every existing `from './errors'` import keeps resolving.
+export type { FrameworkScriptKind } from './build-errors';
+export {
+  BuildEntryMissingError,
+  FrameworkScriptBuildFailedError,
+  IslandBuildFailedError,
+} from './build-errors';
 
 /**
  * `ROLE` selects what a container is. One image runs every role, so a typo is a process that would

package/src/favicon.ts

@@ -5,7 +5,7 @@
 
 // why: Bun exposes no path-join primitive, and `FAVICON_SOURCE` is app-root-relative, so resolving
 // it against the root is string work no `Bun.file` overload does — the same necessity
-// `dev-assets.ts` records for `ICON_SOURCE`.
+// `runtime-assets.ts` records for `ICON_SOURCE`.
 import { join } from 'node:path';
 import { createRaster, encodeImage } from '@ultimat3/core';
 import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';
@@ -69,7 +69,7 @@ const builtinBytes = (): Uint8Array => {
 const iconResponse = (bytes: Uint8Array, contentType: string): Response =>
   applyCacheHeaders(
     // Copied, not passed through: a `Uint8Array<ArrayBufferLike>` may be backed by a
-    // `SharedArrayBuffer`, which `Response` does not accept — `dev-assets.ts`'s rule, verbatim.
+    // `SharedArrayBuffer`, which `Response` does not accept — `runtime-assets.ts`'s rule, verbatim.
     new Response(new Uint8Array(bytes), { headers: { 'content-type': contentType } }),
     FAVICON_CACHE,
   );

package/src/fix-imports.ts

@@ -4,9 +4,9 @@
 
 // `dirname`/`join` are `node:`-only by necessity: Bun exposes no path-join primitive.
 import { dirname, join } from 'node:path';
+import { endOfLiteral, maskLiterals } from '@ultimat3/core';
 import type { FixHelper } from './fix-scan';
 import { scanFixHelpers } from './fix-scan';
-import { endOfLiteral, maskLiterals } from './ts-scan';
 
 /**
  * A named import, matched over the MASKED source and anchored at the start of a line, so an

package/src/fix-scan.ts

@@ -3,16 +3,9 @@
 // class's constructor. Split out of `ts-scan.ts` when the third shape and cross-file resolution
 // (`fix-imports.ts`) took the file past the 500-line ceiling; the masking primitives stay there.
 
+import { endOfLiteral, maskLiterals, QUOTES } from '@ultimat3/core';
 import type { FixSite } from './ts-scan';
-import {
-  CLOSERS,
-  endOfLiteral,
-  lineIndex,
-  maskLiterals,
-  OPENERS,
-  QUOTES,
-  valueLiterals,
-} from './ts-scan';
+import { CLOSERS, lineIndex, OPENERS, valueLiterals } from './ts-scan';
 
 /** The lookbehind rejects member access: `cond ? e.fix : ''` is a ternary, not a declaration. */
 const FIX_KEY = /(?<![.\w$])fix\s*:\s*/g;

package/src/flag-reads.ts

@@ -9,11 +9,10 @@
 
 // `join`/`relative` are `node:`-only by necessity: Bun exposes no path-join primitive.
 import { join, relative } from 'node:path';
-import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { ERROR_DOCS_URL, stripComments } from '@ultimat3/core';
 import type { Finding } from './output';
 import type { CommandSpec, FlagSpec } from './parse';
 import { GLOBAL_FLAGS } from './parse';
-import { stripComments } from './ts-scan';
 
 /** A flag as declared, with the command that declares it. */
 export interface DeclaredFlag {

package/src/foreign-text.ts

@@ -0,0 +1,36 @@
+// The one fence for foreign text an agent reads: a PR review body (`x pr review`) and a CI log
+// (`x ci`) are both written by anyone who can comment or push, and rendered bare they arrive in the
+// agent's context indistinguishable from this CLI's own output. A leaf, so both commands share it.
+
+const BLOCK_OPEN = '<comment id=';
+const BLOCK_CLOSE = '</comment>';
+
+/**
+ * The fence, as a READER would parse it rather than as this file spells it.
+ *
+ * Two literal `replaceAll`s were the whole neutralisation, and markup is not spelled one way:
+ * `</comment >`, `</COMMENT>` and `< comment id=` all end or open a block for anything reading
+ * tags, and none of the three matched. One pattern over `<`, an optional `/`, and whitespace
+ * around a case-insensitive `comment` covers every spelling of the delimiter; the escape goes on
+ * the `<`, so what the reviewer wrote after it survives byte for byte.
+ */
+const BLOCK_DELIMITER = /<(\s*\/?\s*comment\b)/gi;
+
+/**
+ * One comment body, fenced and labelled with the thread id it came from — `@ultimat3/ai`'s
+ * `documentBlock` (`rag.ts`), applied to the other place foreign text enters an agent's context.
+ * `x pr review` exists because an agent cannot read the GitHub web UI, and a review body is
+ * written by anyone who can comment on the pull request: rendered as bare indented text it arrived
+ * in that agent's context indistinguishable from the command's own output, which is prompt
+ * injection with a shell attached.
+ *
+ * The fence is neutralised INSIDE the payload rather than deleted, so every word the reviewer
+ * wrote still reads, and the label is stripped of the three characters that would end the
+ * attribute. Influence only, and deliberately not sold as more: a fence tells a reader this text
+ * is data, and it can never stop one that decides otherwise.
+ */
+export function commentBlock(id: string, lines: readonly string[]): readonly string[] {
+  const label = id.replaceAll('"', "'").replaceAll('>', ')').replaceAll('<', '(');
+  const body = lines.map((line) => line.replace(BLOCK_DELIMITER, '<\\$1'));
+  return [`${BLOCK_OPEN}"${label}">`, ...body, BLOCK_CLOSE];
+}

package/src/framework-schema.ts

@@ -78,12 +78,11 @@ export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
   /**
    * The five tables `BuiltinAdapter` reads, and the oldest hole in this list.
    *
-   * `packages/auth/src/tables.ts` exports them "so an app can paste them into a migration", and
-   * nothing in the framework has ever applied them — while `x db gen` diffs `describeEntities()`
-   * and these are not `entity()` declarations, so neither half was a file anybody could
-   * hand-write. `examples/dummy/CLAUDE.md` records the consequence in its own words: nobody can
-   * hold a session in the reference app. Applied here on exactly the rule the rate-limit and audit
-   * rows already follow.
+   * Until this row nothing applied them, in dev or in production: they are not `entity()`
+   * declarations, so `x db gen` never saw them, and an app was left to paste per-table exports
+   * into a migration nobody wrote — nobody could hold a session in the reference app. Those
+   * exports are gone; `AUTH_TABLES` is the whole DDL, the 1.3 `x_users` upgrade included, applied
+   * here on exactly the rule the rate-limit and audit rows already follow.
    *
    * `AUTH_TABLE_NAMES` rather than five literals: @ultimat3/auth already publishes the list, and a
    * second copy is a second thing to keep right when a table is added.

package/src/generate-feature.ts

@@ -0,0 +1,42 @@
+// `x g <kind> --feature <f>` writes INTO a slice, and a slice that does not exist is refused rather
+// than invented. It was invented: `x g task nightly --feature reports` laid down an
+// `entity('reports', { title, price })` nobody asked for, and the `drift` step then demanded a
+// migration for the table. Only `x g entity` and `x g resource` create a feature's data.
+
+import { existsSync } from 'node:fs'; // why: a synchronous directory probe; Bun.file answers files, not directories.
+import { UltimateError } from '@ultimat3/core';
+import type { Generator } from './generate-kinds';
+import { containedPath } from './generate-write';
+import { quoteArg } from './shell-quote';
+
+/** The generators whose `--feature` names an existing slice to write into. */
+const WRITES_INTO_SLICE: ReadonlySet<Generator> = new Set<Generator>([
+  'action',
+  'mutator',
+  'query',
+  'job',
+  'task',
+]);
+
+/** Declared beside its one thrower: `errors.ts` sits at its 500-line ceiling. */
+export class FeatureUnknownError extends UltimateError {
+  constructor(input: { readonly feature: string; readonly slice: string }) {
+    super({
+      code: 'X_FEATURE_UNKNOWN',
+      cause: `--feature ${quoteArg(input.feature)} names ${input.slice}, which does not exist — a generator writing into a slice never invents one, or its entity table`,
+      fix: `x g resource ${quoteArg(input.feature)}`,
+    });
+  }
+}
+
+/** Refuses a `--feature` whose slice directory is absent, for the kinds that write into one. */
+export function assertFeatureExists(
+  root: string,
+  kind: Generator,
+  feature: string | undefined,
+  slice: string,
+): void {
+  if (feature === undefined || !WRITES_INTO_SLICE.has(kind)) return;
+  if (existsSync(containedPath(root, slice))) return;
+  throw new FeatureUnknownError({ feature, slice });
+}

package/src/generate-files.ts

@@ -56,8 +56,8 @@ export interface GenerateOptions {
    */
   readonly sliceErrors?: string;
   /**
-   * `job` and `task`: the slice's `entity.ts` as it stands on disk, absent when the feature has no
-   * entity yet. Supplied by `run` for `sliceErrors`'s reason — whether the feature is
+   * `action`, `mutator`, `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
    * `sliceDir(surface, feature)/entity.ts`.
@@ -84,7 +84,9 @@ 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;
+  // 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 };
   switch (options.kind) {
     case 'resource':
@@ -101,6 +103,7 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
         actionFiles(options.name, {
           ...target,
           ...(options.sliceErrors === undefined ? {} : { sliceErrors: options.sliceErrors }),
+          ...(options.sliceEntity === undefined ? {} : { sliceEntity: options.sliceEntity }),
         }),
       );
     case 'mutator':
@@ -109,6 +112,7 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
           ...target,
           mutator: true,
           ...(options.sliceErrors === undefined ? {} : { sliceErrors: options.sliceErrors }),
+          ...(options.sliceEntity === undefined ? {} : { sliceEntity: options.sliceEntity }),
         }),
       );
     case 'backfill':

package/src/generate-grants.ts

@@ -0,0 +1,83 @@
+// `x g policy` / `x g resource` grant what they declare. A generated `policy.ts` declares
+// `<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).
+
+import { containedPath } from './generate-write';
+import { ROLES_FILE } from './permission-grants';
+import { wrapList } from './templates/wrap';
+
+/** One permission to add to one role's `grants`. */
+export interface RoleGrant {
+  readonly role: string;
+  readonly permission: string;
+}
+
+/** A generated policy file: `<surface>/<feature>/policy.ts`, never a test beside it. */
+const POLICY_PATH = /^apps\/[^/]+\/[^/]+\/(?<feature>[a-z0-9-]+)\/policy\.ts$/;
+
+/**
+ * The grants a written file set implies: the lowest role that makes sense for each verb. `member`
+ * reads, `admin` writes — the scaffold's dev actor is `admin`, so both reach it through
+ * `inherits`, and a `member` cookie still cannot write.
+ */
+export function grantsForWritten(written: readonly string[]): readonly RoleGrant[] {
+  return written.flatMap((path) => {
+    const feature = POLICY_PATH.exec(path)?.groups?.['feature'];
+    return feature === undefined
+      ? []
+      : [
+          { role: 'member', permission: `${feature}:read` },
+          { role: 'admin', permission: `${feature}:write` },
+        ];
+  });
+}
+
+const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * `source` with each grant added to its role's `grants: [...]`, re-wrapped the way Biome prints
+ * it. A role or a `grants` array the scaffold's shape does not have is left alone and returned in
+ * `skipped` — the `policy` step's X_PERMISSION_UNGRANTED names the edit, so a guess here would be
+ * a second, worse answer.
+ */
+export function insertGrants(
+  source: string,
+  grants: readonly RoleGrant[],
+): { readonly source: string; readonly skipped: readonly RoleGrant[] } {
+  let next = source;
+  const skipped: RoleGrant[] = [];
+  for (const grant of grants) {
+    const role = new RegExp(`\\n  ${escapeRegExp(grant.role)}: \\{`).exec(next);
+    const open = role === null ? -1 : next.indexOf('grants: [', role.index);
+    const close = open === -1 ? -1 : next.indexOf(']', open);
+    const blockEnd = role === null ? -1 : next.indexOf('\n  },', role.index);
+    if (role === null || open === -1 || close === -1 || (blockEnd !== -1 && open > blockEnd)) {
+      skipped.push(grant);
+      continue;
+    }
+    const current = [...next.slice(open, close).matchAll(/'([^']+)'/g)].map((m) => m[1] ?? '');
+    if (current.includes(grant.permission)) continue;
+    const entries = [...current, grant.permission].map((permission) => `'${permission}'`);
+    const lineStart = next.lastIndexOf('\n', open) + 1;
+    const indent = next.slice(lineStart, open);
+    const rewritten = wrapList(indent, 'grants: [', entries, ']').slice(indent.length);
+    next = `${next.slice(0, open)}${rewritten}${next.slice(close + 1)}`;
+  }
+  return { source: next, skipped };
+}
+
+/** Performs `insertGrants` on the app's role map. Answers the paths it rewrote. */
+export async function grantGeneratedPermissions(
+  root: string,
+  written: readonly string[],
+): Promise<readonly string[]> {
+  const grants = grantsForWritten(written);
+  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);
+  if (source === before) return [];
+  await Bun.write(file, source);
+  return [ROLES_FILE];
+}

package/src/generate-kinds.ts

@@ -10,6 +10,7 @@ import {
   UnknownCommandError,
 } from './errors';
 import type { Surface } from './templates';
+import { camel, kebab } from './templates/naming';
 
 export const GENERATORS = [
   'resource',
@@ -106,11 +107,62 @@ export function readSurface(raw: string | undefined, kind: Generator, name: stri
  * is a command that runs.
  */
 export function readName(raw: string | undefined, kind: Generator): string {
-  if (raw !== undefined) return raw;
-  throw new MissingPositionalError({
+  if (raw === undefined) {
+    throw new MissingPositionalError({
+      command: `g ${kind}`,
+      positional: 'name',
+      example: exampleFor(kind),
+    });
+  }
+  refusePath(raw, 'name', kind);
+  refuseBadIdentifier(raw, kind);
+  return raw;
+}
+
+/** `--feature`, refused where it is a path: it is a DIRECTORY under the surface, one segment. */
+export function readFeature(raw: string | undefined, kind: Generator): string | undefined {
+  if (raw !== undefined) refusePath(raw, 'feature', kind);
+  return raw;
+}
+
+/** A name is one directory segment: `x g action ../../../evil` wrote outside `apps/`. */
+function refusePath(raw: string, flag: string, kind: Generator): void {
+  if (!/[\\/]/.test(raw) && raw.trim() !== '..' && raw.trim() !== '.') return;
+  throw new BadFlagError({
+    flag,
+    command: `g ${kind}`,
+    reason: `"${raw}" is a path, and a generator ${flag} is one directory segment under the surface`,
+    fix: exampleFor(kind),
+  });
+}
+
+/** Strict-mode reserved words: `export const delete = …` does not parse. */
+const RESERVED = new Set(
+  (
+    'break case catch class const continue debugger default delete do else enum export extends ' +
+    'false finally for function if import in instanceof new null return super switch this throw ' +
+    'true try typeof var void while with yield let static implements interface package private ' +
+    'protected public await arguments eval'
+  ).split(' '),
+);
+
+/**
+ * The name becomes `camel(name)` in emitted source, so it has to be an identifier there: not a
+ * reserved word, not starting with a digit. The fix is the same run with a name that is one — the
+ * kind appended to a reserved word, prepended to a leading digit.
+ */
+function refuseBadIdentifier(raw: string, kind: Generator): void {
+  const identifier = camel(raw);
+  const digit = /^[0-9]/.test(identifier);
+  if (identifier !== '' && !digit && !RESERVED.has(identifier)) return;
+  const noun = kind.split(':').at(-1) ?? kind;
+  const suggestion = digit ? `${noun}-${kebab(raw)}` : `${kebab(raw)}-${noun}`;
+  throw new BadFlagError({
+    flag: 'name',
     command: `g ${kind}`,
-    positional: 'name',
-    example: exampleFor(kind),
+    reason: `"${raw}" becomes the identifier "${identifier}" in generated source, which ${digit ? 'starts with a digit' : identifier === '' ? 'is empty' : 'is a reserved word'}`,
+    // Joined, never spliced: the suggestion is kebab output, and the rule reads the shape.
+    fix: ['x g', kind, suggestion].join(' '),
   });
 }
 

package/src/i18n-index.ts

@@ -10,7 +10,8 @@
 // whether to write at all, before any await the caller could interleave with.
 import { existsSync } from 'node:fs';
 import { containedPath } from './generate-write';
-import { CATALOG_ROOT, i18nIndex } from './templates';
+import type { Finding } from './output';
+import { CATALOG_ROOT, i18nIndex, localeEntry, localeImport } from './templates';
 
 export const I18N_INDEX_PATH = 'packages/i18n/src/index.ts';
 
@@ -25,16 +26,64 @@ export async function catalogLocales(root: string): Promise<readonly string[]> {
   return locales.sort();
 }
 
+/** What a sync did: whether every catalog on disk is now selectable, and why not when it is not. */
+export interface IndexSync {
+  /** False for an app with no i18n package, or an index this writer refused to edit. */
+  readonly registered: boolean;
+  readonly findings: readonly Finding[];
+}
+
+const CATALOG_IMPORT = /^import (\w+) from '\.\.\/catalogs\/([^']+)\.json';$/gm;
+const LOCALES_OBJECT = /(locales:\s*\{)([^{}]*)(\})/;
+
+/** The tags the index imports a catalog for, in file order. */
+const importedLocales = (source: string): readonly string[] =>
+  [...source.matchAll(CATALOG_IMPORT)].map((match) => match[2] ?? '');
+
 /**
- * Re-derives the FULL locale set from `packages/i18n/catalogs/` — never just the locale one
- * invocation asked for — and rewrites the index to match. It bypasses `writeFiles` on purpose:
- * this file is a projection of the catalog directory, never app-authored content a conflict check
- * should protect. An app with no i18n package (deleted, or never scaffolded) is left alone, and
- * that is what `written` reports.
+ * Makes every catalog on disk selectable, and touches the index no more than that takes.
+ *
+ * An index that IS the template's output (for the locales it imports) is the framework's file and
+ * is re-derived whole. Anything else is the author's: each missing locale gets its import and its
+ * `locales: { … }` entry and nothing else moves — the declared `default`, and any code beside it,
+ * stay. A shape with no `locales: { … }` object to add to is refused with the edit named, never
+ * overwritten: it was, on every `x g`, with a template hard-coding `default: 'en'`.
  */
-export async function syncI18nIndex(root: string): Promise<boolean> {
+export async function syncI18nIndex(root: string): Promise<IndexSync> {
   const indexAbsolute = containedPath(root, I18N_INDEX_PATH);
-  if (!existsSync(indexAbsolute)) return false;
-  await Bun.write(indexAbsolute, i18nIndex(await catalogLocales(root)));
-  return true;
+  if (!existsSync(indexAbsolute)) return { registered: false, findings: [] };
+  const current = await Bun.file(indexAbsolute).text();
+  const onDisk = await catalogLocales(root);
+  const imported = importedLocales(current);
+  if (current === i18nIndex(imported)) {
+    await Bun.write(indexAbsolute, i18nIndex(onDisk));
+    return { registered: true, findings: [] };
+  }
+  const missing = onDisk.filter((locale) => !imported.includes(locale));
+  if (missing.length === 0) return { registered: true, findings: [] };
+  const edited = withLocales(current, missing);
+  if (edited === undefined) return { registered: false, findings: [refusal(missing)] };
+  await Bun.write(indexAbsolute, edited);
+  return { registered: true, findings: [] };
+}
+
+/** Each import after the last catalog import (or at the top), each entry at the object's end. */
+function withLocales(source: string, locales: readonly string[]): string | undefined {
+  const object = LOCALES_OBJECT.exec(source);
+  if (object === null) return undefined;
+  const body = (object[2] ?? '').trim().replace(/,$/, '');
+  const entries = [body, ...locales.map(localeEntry)].filter((part) => part !== '').join(', ');
+  const withEntries = source.replace(LOCALES_OBJECT, `$1 ${entries} $3`);
+  const imports = locales.map(localeImport).join('\n');
+  const lastImport = [...withEntries.matchAll(CATALOG_IMPORT)].at(-1);
+  if (lastImport === undefined) return `${imports}\n${withEntries}`;
+  const at = lastImport.index + lastImport[0].length;
+  return `${withEntries.slice(0, at)}\n${imports}${withEntries.slice(at)}`;
 }
+
+const refusal = (locales: readonly string[]): Finding => ({
+  code: 'X_CATALOG_UNREGISTERED',
+  cause: `${I18N_INDEX_PATH} is hand-written in a shape this writer cannot add ${locales.join(', ')} to, so those catalogs are on disk and not selectable`,
+  fix: `edit ${I18N_INDEX_PATH} — add ${locales.map(localeImport).join(' ')} and ${locales.map(localeEntry).join(', ')} to the locales passed to defineCatalogs`,
+  at: I18N_INDEX_PATH,
+});

package/src/icon-assets.ts

@@ -1,6 +1,6 @@
 // Single responsibility: the one source image every generated icon derives from, where the matrix
 // is served, and the renderer that turns one into the other. Its own module so the two things that
-// need it — `dev-assets.ts`, which SERVES the matrix, and `pwa-artifacts.ts`, which NAMES it in the
+// need it — `runtime-assets.ts`, which SERVES the matrix, and `pwa-artifacts.ts`, which NAMES it in the
 // web manifest — can share it without importing each other.
 
 // why: Bun exposes no path-join primitive, and `ICON_SOURCE` is app-root-relative, so resolving it