@ultimat3/cli 22.15.0 → 23.0.0

package/src/generate-files.ts

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

package/src/generate-grant-findings.ts

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

package/src/generate-grants.ts

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

package/src/generate-kinds.ts

@@ -9,6 +9,7 @@ import {
   MissingSubcommandError,
   UnknownCommandError,
 } from './errors';
+import { quoteArg } from './shell-quote';
 import type { Surface } from './templates';
 import { camel, kebab } from './templates/naming';
 
@@ -49,6 +50,24 @@ export function assertSurfaceSupported(kind: Generator, surface: Surface, name:
   });
 }
 
+/**
+ * `--live` is the query generator's. A resource slice already ships a live list query, so the flag
+ * on any other generator changed nothing — and a flag accepted and ignored is a second spelling of
+ * the same command that an agent then believes did something.
+ */
+export function assertLiveSupported(kind: Generator, live: boolean, name: string): void {
+  if (!live || kind === 'query') return;
+  throw new BadFlagError({
+    flag: 'live',
+    command: `g ${kind}`,
+    reason:
+      kind === 'resource'
+        ? "--live is the query generator's: a resource slice already ships a live list query"
+        : "--live is the query generator's: it declares a query live",
+    fix: `x g query ${quoteArg(`${name}-feed`)} --feature ${quoteArg(name)} --live`,
+  });
+}
+
 /**
  * The generator a spelling reaches, or a refusal that leads with the one it is nearest.
  *

package/src/generate-write.ts

@@ -9,7 +9,7 @@ import { existsSync } from 'node:fs';
 import { resolve, sep } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import { GenerateJsonInvalidError, ScaffoldPathEscapeError } from './errors';
-import { mergeJsonDeep } from './json-merge';
+import { mergeJsonDeep, mergeJsonInPlace, sortJsonDeep } from './json-merge';
 import type { Finding } from './output';
 import type { GeneratedFile } from './templates';
 
@@ -28,33 +28,18 @@ function parseJsonObject(text: string): Record<string, unknown> | undefined {
 }
 
 /**
- * Every key of every level, sorted. A catalog is authored NESTED (`{ nav: { home: … } }`) and this
- * sorted the top level only, so the keys INSIDE `app` kept the order their generators ran in —
- * `x g route zebra` then `x g route alpha` wrote different bytes from the same two runs in the
- * other order, which is the reordering diff the sort exists to prevent. Arrays keep their order:
- * a list's order is its content.
+ * A generator's OWN catalog bytes: every key of every level sorted, 2-space indent, trailing
+ * newline. A catalog is authored NESTED (`{ nav: { home: … } }`) and sorting the top level only
+ * left the keys inside `app` in the order their generators ran — `x g route zebra` then
+ * `x g route alpha` wrote different bytes from the same two runs in the other order. The sort is
+ * `json-merge.ts`'s `sortJsonDeep`, by code unit: `localeCompare` is `Intl`-backed, so the bytes
+ * would move with the machine's locale and its ICU version.
  *
- * CODE UNIT, never `localeCompare`: it is `Intl`-backed, so the bytes a catalog is written with
- * moved with the machine's locale and its ICU version — `x g route` on a `tr-TR` box and the same
- * command in CI produced two orderings of one file, which is exactly the reordering diff this sort
- * exists to prevent, one layer down. `@ultimat3/render` states the same rule as `byCodeUnit`; the
- * comparison is inlined rather than imported because that one is package-internal and this is the
- * whole of it.
+ * For a fresh file and for `dedupe`, where every contributor is a generator. A file already on
+ * disk is merged in ITS order (`mergeJsonInPlace`), never re-sorted.
  */
-function sortDeep(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(sortDeep);
-  if (typeof value !== 'object' || value === null) return value;
-  return Object.fromEntries(
-    Object.entries(value)
-      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
-      .map(([key, entry]) => [key, sortDeep(entry)]),
-  );
-}
-
-/** Deterministic catalog bytes: sorted keys, 2-space indent, trailing newline — a diff shows only
- * the keys a run actually changed, never a reordering. */
 function prettyJson(value: Record<string, unknown>): string {
-  return `${JSON.stringify(sortDeep(value), null, 2)}\n`;
+  return `${JSON.stringify(sortJsonDeep(value), null, 2)}\n`;
 }
 
 /**
@@ -156,10 +141,13 @@ async function planJsonMerge(
   }
   // An existing key wins because it may hold a human translation; only the new keys are added.
   // Deep, so a nested catalog gains `site.blog.title` without losing the rest of `site`.
-  const { merged, gained } = mergeJsonDeep(existing, generated);
+  const { gained } = mergeJsonDeep(existing, generated);
   // Every key the generator wants is already there — leave the file untouched and unclaimed.
   if (!gained) return { kind: 'skip' };
-  return { kind: 'write', file, absolute, contents: prettyJson(merged) };
+  // In the file's OWN order: the diff a run leaves is the keys it added, never a re-sort of a
+  // catalog somebody keeps grouped by screen.
+  const merged = mergeJsonInPlace(existing, generated);
+  return { kind: 'write', file, absolute, contents: `${JSON.stringify(merged, null, 2)}\n` };
 }
 
 /**

package/src/generated-imports.ts

@@ -0,0 +1,59 @@
+// The workspace edges `x g` just wrote, declared in the manifest of the workspace each file landed
+// in. `package-shape` refuses an import its owner does not declare (X_WORKSPACE_DEP_UNDECLARED), and
+// a generator that emits one hands the author a red gate for the generator's own output — the edit
+// is mechanical, so the generator makes it. Shipped source only, the checker's own scope.
+
+import { containedPath } from './generate-write';
+import { isGenerated, isTest } from './source-files';
+import { withDependency } from './workspace-dep-edit';
+import { importedPackages, scanWorkspaces, type WorkspaceNode } from './workspace-graph';
+
+const SOURCE = /\.tsx?$/;
+
+/** Per owning workspace, the sibling workspaces its new files import and it does not declare. */
+async function missingEdges(
+  root: string,
+  written: readonly string[],
+): Promise<Map<WorkspaceNode, Map<string, string>>> {
+  const missing = new Map<WorkspaceNode, Map<string, string>>();
+  const sources = written.filter(
+    (path) => SOURCE.test(path) && !isTest(path) && !isGenerated(path),
+  );
+  if (sources.length === 0) return missing;
+  const { nodes } = await scanWorkspaces(root);
+  const byName = new Map(nodes.map((node) => [node.name, node]));
+  // Deepest directory first, as the checker reads it: a nested workspace's files are its own.
+  const owners = [...nodes].sort((left, right) => right.dir.length - left.dir.length);
+  for (const path of sources) {
+    const owner = owners.find((node) => path.startsWith(`${node.dir}/`));
+    if (owner === undefined) continue;
+    const text = await Bun.file(containedPath(root, path)).text();
+    for (const name of importedPackages(text, path)) {
+      const target = byName.get(name);
+      if (target === undefined || target === owner || owner.dependencies.includes(name)) continue;
+      const edges = missing.get(owner) ?? new Map<string, string>();
+      edges.set(name, target.version ?? '0.0.0');
+      missing.set(owner, edges);
+    }
+  }
+  return missing;
+}
+
+/** Writes each owning manifest once, holding every new edge; answers the manifests it rewrote. */
+export async function declareGeneratedImports(
+  root: string,
+  written: readonly string[],
+): Promise<readonly string[]> {
+  const edited: string[] = [];
+  for (const [owner, edges] of await missingEdges(root, written)) {
+    const path = `${owner.dir}/package.json`;
+    const file = Bun.file(containedPath(root, path));
+    const before = await file.text();
+    let after = before;
+    for (const [name, version] of edges) after = withDependency(after, name, version) ?? after;
+    if (after === before) continue;
+    await Bun.write(containedPath(root, path), after);
+    edited.push(path);
+  }
+  return edited;
+}

package/src/guard-sources.ts

@@ -0,0 +1,104 @@
+// One read of the app per gate run, shared by every guard. Every guard `SHIPPED_GUARD_NAMES` lists
+// (`templates/scaffold-guards.ts`), each walking the tree and re-reading every stylesheet, is one
+// walk per guard for one answer, and two guards compiling the same module is Sass run twice — so
+// the runner hands each `check` these, memoised for the run.
+
+// why: `join` builds the host-separator path a glob entry is read at; Bun ships no path API.
+import { join } from 'node:path';
+
+export interface GuardFile {
+  /** App-root-relative POSIX path, so a finding names the file an author opens. */
+  readonly path: string;
+  readonly text: string;
+}
+
+/** A stylesheet as the build compiles it. */
+export interface GuardStylesheet {
+  readonly css: string;
+  /** `hero` → its scoped name. Empty for a sheet that is not a `.module.scss`. */
+  readonly classes: Readonly<Record<string, string>>;
+}
+
+export interface GuardSources {
+  /**
+   * Every file under the app root matching `glob`, sorted. Dependencies, build output and caches
+   * are never the app, so they are never returned. Asked twice, walked once.
+   */
+  files(glob: string): Promise<readonly GuardFile[]>;
+  /**
+   * The stylesheet at an app-root-relative path, compiled by the compiler the build uses.
+   * `undefined` when the file is absent or does not compile: that refusal is the build's
+   * (`X_PRERENDER_FAILED`, with the Sass error), never a guard's to repeat.
+   */
+  compiled(path: string): Promise<GuardStylesheet | undefined>;
+}
+
+/** Path segments that are never the app's own source. */
+const NOT_SOURCE = /(?:^|\/)(?:node_modules|dist|\.x|\.git)\//;
+
+/**
+ * `seed` is text the gate step ALREADY read — the `boundaries` step reads every surface file for
+ * its own import rules before any guard runs, and a guard that walks `apps/**` would read each of
+ * them a second time. Seeded, a path is read at most once per step; anything the seed does not
+ * hold (a stylesheet, a test, a package) is read here on first ask, as before.
+ */
+export function guardSources(
+  root: string,
+  seed: readonly { readonly path: string; readonly source: string }[] = [],
+): GuardSources {
+  const texts = new Map<string, Promise<string>>();
+  for (const file of seed) texts.set(file.path, Promise.resolve(file.source));
+  const walks = new Map<string, Promise<readonly GuardFile[]>>();
+  const sheets = new Map<string, Promise<GuardStylesheet | undefined>>();
+
+  const textOf = (path: string): Promise<string> => {
+    let text = texts.get(path);
+    if (text === undefined) {
+      text = Bun.file(join(root, path)).text();
+      texts.set(path, text);
+    }
+    return text;
+  };
+
+  const walk = async (glob: string): Promise<readonly GuardFile[]> => {
+    const paths: string[] = [];
+    for await (const entry of new Bun.Glob(glob).scan({ cwd: root, absolute: false })) {
+      const path = entry.split('\\').join('/');
+      if (!NOT_SOURCE.test(path)) paths.push(path);
+    }
+    paths.sort();
+    return Promise.all(paths.map(async (path) => ({ path, text: await textOf(path) })));
+  };
+
+  const compile = async (path: string): Promise<GuardStylesheet | undefined> => {
+    try {
+      const source = await textOf(path);
+      // Imported here, not at the top: Sass loads on the first compile, and a gate run whose
+      // guards compile nothing must not pay for the compiler (`sass-lazy.test.ts`).
+      const { compileStylesheet } = await import('@ultimat3/render/server');
+      const { css, classes } = compileStylesheet(join(root, path), source);
+      return { css, classes };
+    } catch {
+      return undefined;
+    }
+  };
+
+  return {
+    files(glob) {
+      let found = walks.get(glob);
+      if (found === undefined) {
+        found = walk(glob);
+        walks.set(glob, found);
+      }
+      return found;
+    },
+    compiled(path) {
+      let sheet = sheets.get(path);
+      if (sheet === undefined) {
+        sheet = compile(path);
+        sheets.set(path, sheet);
+      }
+      return sheet;
+    },
+  };
+}