@ultimat3/cli 21.0.0 → 22.1.0

package/src/drift.ts

@@ -11,7 +11,10 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { ERROR_DOCS_URL } from '@ultimat3/core';
+// `canonicalJson` is core's, the one serializer every content hash in the framework uses. A private
+// copy here wrote `"key":null` for an unset optional field where core drops the key, so the schema
+// hash agreed with nothing else (plan 101 slice 18 h; 22.0.0 re-stamps every sidecar once).
+import { canonicalJson, ERROR_DOCS_URL } from '@ultimat3/core';
 import { describeEntities } from '@ultimat3/entity';
 import { countDeclaredEntities } from './app-entities';
 import { loadApp } from './app-load';
@@ -23,23 +26,6 @@ import type { Finding } from './output';
 export const DB_PACKAGE = join('packages', 'db');
 const SCHEMA_GLOB = 'packages/db/src/**/*.ts';
 
-/**
- * Canonical JSON: object keys sorted, arrays in their own order. The registry's description is a
- * BUILD INPUT committed to disk as a hash, so a field reordered inside `describe()` upstream would
- * otherwise move every app's hash and report drift over a framework upgrade nobody made.
- */
-function canonicalJson(value: unknown): string {
-  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
-  if (typeof value === 'object' && value !== null) {
-    const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) =>
-      a < b ? -1 : a > b ? 1 : 0,
-    );
-    return `{${entries.map(([key, held]) => `${JSON.stringify(key)}:${canonicalJson(held)}`).join(',')}}`;
-  }
-  // `undefined` has no JSON form and an optional field left unset must hash as absent, not throw.
-  return JSON.stringify(value) ?? 'null';
-}
-
 /**
  * What the app's entities declare, as the registry describes them — the half `SCHEMA_GLOB` cannot
  * see. `x new` puts an entity at `apps/web/app/<feature>/entity.ts` and `packages/db/src/schema.ts`

package/src/error-catalog.ts

@@ -46,22 +46,29 @@ export const CATALOG_PACKAGES = [
 ] as const;
 
 /**
- * The two packages the catalog may import WITHOUT `@ultimat3/cli` declaring them: they reach for a
- * JSX runtime an app has and a bare CLI process does not, so a hard dependency would make the CLI
- * uninstallable where the codes are merely absent today. Every other entry above is a real runtime
- * import and must be a declared dependency — `error-catalog.test.ts` holds the list to exactly that,
- * because an undeclared one resolves through workspace symlinks here and through nothing in an
- * installed app, where `x errors explain X_FLAG_EXPIRED` then refuses a code the wiki promises.
+ * The packages the catalog may import WITHOUT `@ultimat3/cli` declaring them. `admin` and `ui`
+ * reach for a JSX runtime an app has and a bare CLI process does not, so a hard dependency would
+ * make the CLI uninstallable where the codes are merely absent today. `scraping` is an app's own
+ * choice since 22.0.0: `x shot` drives Chrome over raw CDP and imports nothing from it, so its codes
+ * answer where the app installed it and are reported `unavailable` where it did not. Every other
+ * entry above is a real runtime import and must be a declared dependency — `error-catalog.test.ts`
+ * holds the list to exactly that, because an undeclared one resolves through workspace symlinks
+ * here and through nothing in an installed app, where `x errors explain X_FLAG_EXPIRED` then
+ * refuses a code the wiki promises.
  */
-export const CATALOG_OPTIONAL_HOSTS: readonly string[] = ['@ultimat3/admin', '@ultimat3/ui'];
+export const CATALOG_OPTIONAL_HOSTS: readonly string[] = [
+  '@ultimat3/admin',
+  '@ultimat3/scraping',
+  '@ultimat3/ui',
+];
 
 export interface ErrorCatalog {
   /** Packages whose codes are now registered. */
   readonly loaded: readonly string[];
   /**
    * Packages this process could not *resolve*, so their codes are absent from the answer. The one
-   * tolerated case is the optional host: `CATALOG_OPTIONAL_HOSTS` reach for a JSX
-   * runtime an app has and a bare CLI process does not, and a list silently missing their codes is
+   * tolerated case is the optional host (`CATALOG_OPTIONAL_HOSTS`), which a bare CLI process may
+   * not have, and a list silently missing their codes is
    * worse than one that says which packages are missing. A package that resolved and then threw is
    * a defect, not a host gap, and goes to `failed`.
    */

package/src/error-codes.ts

@@ -178,30 +178,26 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_SHOT_ISLAND_UNPHOTOGRAPHABLE',
   'X_SHOT_ISLAND_UNSTUBBED_REQUEST',
   'X_SHOT_ISLAND_MISSING',
-  // The browser-backed e2e driver — `e2e-driver.ts` and the three modules under it. Owned by the
-  // CLI because the ADAPTER is: `@ultimat3/testing` declares `PageLike` and may not import a
-  // browser, `@ultimat3/scraping` owns the browser and may not import the harness, and neither
-  // package can name a failure that only exists where the two meet.
-  'X_E2E_EVALUATE_UNSUPPORTED',
-  'X_E2E_EVALUATE_CAPTURED',
-  'X_E2E_EVALUATE_THREW',
-  'X_E2E_LOCATOR_EMPTY',
-  'X_E2E_LOCATOR_AMBIGUOUS',
-  'X_E2E_SERVICE_WORKER_ABSENT',
-  'X_E2E_APP_FAILED',
-  // The raw-CDP browser under that driver — `cdp-launch.ts`, `cdp-connection.ts`,
-  // `cdp-e2e-page.ts`, `cdp-browser.ts`. Four codes and not one, because the four repairs differ:
-  // install a browser, read the browser's own stderr, look at the page, raise a deadline.
-  'X_CDP_BROWSER_MISSING',
-  'X_CDP_LAUNCH_FAILED',
-  'X_CDP_CALL_FAILED',
-  'X_CDP_TIMEOUT',
+  // The raw-CDP shot page's own refusals (`cdp-shot-errors.ts` holds the classes): which host it
+  // may open, which element it was pointed at, and which key it was asked to press.
+  'X_SHOT_HOST_REFUSED',
+  'X_SHOT_ELEMENT_MISSING',
+  'X_SHOT_ELEMENT_UNREADY',
+  'X_SHOT_KEY_INVALID',
   'X_GH_UNAVAILABLE',
   'X_GH_NOT_AUTHENTICATED',
   'X_GH_COMMAND_FAILED',
   'X_GH_RESPONSE_INVALID',
   'X_PR_NOT_FOUND',
   'X_CI_RUN_NOT_FOUND',
+  'X_APP_NAME_EMPTY',
+  'X_APP_EMPTY',
+  'X_BOUNDARY_SURFACE_IMPORT',
+  'X_PERMISSION_UNGRANTED',
+  'X_JOB_UNREGISTERED',
+  'X_FEATURE_UNKNOWN',
+  'X_ROUTE_ASYNC_PAGE',
+  'X_BUDGET_PARAMS_UNDECLARED',
 ] as const;
 
 /**
@@ -316,7 +312,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   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_BROWSER_MISSING: '`x shot` has no browser to launch',
   X_UI_SHOT_ROUTE_UNKNOWN: 'a ui.* tool was asked for a path no route answers',
   X_UI_SHOT_ROUTE_UNBUDGETED: 'a ui.* tool refused a route that declares no budget.js',
   X_UI_INTERACT_STEPS_INVALID: 'a ui.interact step list is over its bounds or malformed',
@@ -330,23 +326,25 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_SHOT_ISLAND_UNPHOTOGRAPHABLE: 'the island never reached a state worth photographing',
   X_SHOT_ISLAND_UNSTUBBED_REQUEST: 'the island requested something no state stub answers',
   X_SHOT_ISLAND_MISSING: 'a declared island picture is not on disk',
-  X_E2E_EVALUATE_UNSUPPORTED: 'a page.evaluate() closure cannot be sent into the browser',
-  X_E2E_EVALUATE_CAPTURED: 'a page.evaluate() closure named a binding the page does not have',
-  X_E2E_EVALUATE_THREW: 'an expression an e2e page ran threw inside the browser',
-  X_E2E_LOCATOR_EMPTY: 'an e2e locator matched no element',
-  X_E2E_LOCATOR_AMBIGUOUS: 'an e2e locator matched more than one element and was asked to click',
-  X_E2E_SERVICE_WORKER_ABSENT: 'no service worker took control of the page within the budget',
-  X_E2E_APP_FAILED: 'the app an e2e run spawned did not come up',
-  X_CDP_BROWSER_MISSING: 'no Chrome or Chromium is installed for the e2e driver to launch',
-  X_CDP_LAUNCH_FAILED: 'the browser started and never announced a DevTools endpoint',
-  X_CDP_CALL_FAILED: 'the browser refused a DevTools call',
-  X_CDP_TIMEOUT: 'a DevTools call did not answer inside its deadline',
+  X_SHOT_HOST_REFUSED: "x shot was asked to open a host outside the run's allow list",
+  X_SHOT_ELEMENT_MISSING: 'no element matched the selector before the deadline',
+  X_SHOT_ELEMENT_UNREADY: 'the element matched and never became ready to act on',
+  X_SHOT_KEY_INVALID: 'a key chord the browser cannot press',
   X_GH_UNAVAILABLE: 'the GitHub CLI is not runnable from here',
   X_GH_NOT_AUTHENTICATED: 'gh holds no credentials for this host',
   X_GH_COMMAND_FAILED: 'a gh invocation exited non-zero',
   X_GH_RESPONSE_INVALID: "gh's output is not the shape the command reads",
   X_PR_NOT_FOUND: 'no pull request for this checkout',
   X_CI_RUN_NOT_FOUND: 'no workflow run for this branch',
+  X_APP_NAME_EMPTY: 'the app name has no letters or digits',
+  X_APP_EMPTY: 'an app with an app.config.ts registered no primitive',
+  X_BOUNDARY_SURFACE_IMPORT: 'a surface imports one SURFACE_SPECS does not allow',
+  X_PERMISSION_UNGRANTED: 'an action, query or route requires a permission no role grants',
+  X_JOB_UNREGISTERED: 'a job reached the manifest under its positional anonymous name',
+  X_FEATURE_UNKNOWN: 'x g --feature names a slice that does not exist',
+  X_ROUTE_ASYNC_PAGE: 'a route exports an async Page',
+  X_BUDGET_PARAMS_UNDECLARED:
+    'a dynamic route with a budget declares no prerender() paths to weigh it by',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws

package/src/error-pages.ts

@@ -34,9 +34,8 @@ const isStatus = (status: number): boolean =>
 /**
  * The app's page for one status, or `undefined`.
  *
- * Read per REQUEST, never cached at boot, for `favicon.ts`'s reason: `x dev` is a running process
- * an author drops a file into, and a reader that captured "there was none" at startup would keep
- * answering the framework's page until the server was restarted.
+ * One read. How often it is asked is `errorPageHook`'s decision: per request under `x dev`, for
+ * `favicon.ts`'s reason, and once per status in a container.
  */
 export async function errorPageOverride(root: string, status: number): Promise<string | undefined> {
   if (!isStatus(status)) return undefined;
@@ -48,11 +47,24 @@ export async function errorPageOverride(root: string, status: number): Promise<s
  * `ServerHooks.errorPage`, bound to one app root. Installed by `startWeb` so `x dev` and the
  * container cannot answer a browser differently — the rule `assetRoutes` already holds for
  * `/favicon.ico`.
+ *
+ * `perRequest` is `x dev`'s: an author drops a file into a running process. A container's image
+ * cannot change under it, so there each status is read ONCE and kept — per request, a burst of 500s
+ * during an outage paid a file read each, on the path that was already failing (plan 101, 12 g).
  */
-export const errorPageHook =
-  (root: string) =>
-  (status: number): Promise<string | undefined> =>
-    errorPageOverride(root, status);
+export const errorPageHook = (root: string, options: { readonly perRequest: boolean }) => {
+  if (options.perRequest) {
+    return (status: number): Promise<string | undefined> => errorPageOverride(root, status);
+  }
+  const read = new Map<number, Promise<string | undefined>>();
+  return (status: number): Promise<string | undefined> => {
+    const known = read.get(status);
+    if (known !== undefined) return known;
+    const once = errorPageOverride(root, status);
+    read.set(status, once);
+    return once;
+  };
+};
 
 /**
  * The document that goes into a static export: the app's file if it has one, the framework's 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`.
  *

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(' '),
   });
 }