@ultimat3/cli 27.6.1 → 27.8.0

package/src/generate-follow-ups.ts

@@ -0,0 +1,64 @@
+// Everything `x g` edits OUTSIDE the files it creates, in the one order they have to happen: a
+// declared permission granted to a role, a primitive listed in `defineApi`, an entity added to the
+// typed handle, an `--admin` override wired, each new workspace edge declared, and every catalog
+// made selectable. One function over one disk seam, so a real run and a dry run are the same code
+// — and the dry run's list of touched files is what the run touches, not a second guess at it.
+
+import { registerAdminResources } from './admin-registration';
+import { registerGeneratedPrimitives } from './api-registration';
+import type { GenerateDisk } from './generate-disk';
+import { ungrantedByGenerator } from './generate-grant-findings';
+import { grantGeneratedPermissions } from './generate-grants';
+import { declareGeneratedImports } from './generated-imports';
+import { registerGeneratedEntities } from './handle-registration';
+import { syncI18nIndex } from './i18n-index';
+import type { Finding } from './output';
+import { CATALOG_ROOT } from './templates';
+
+export interface FollowUps {
+  /** App-root-relative paths edited or created beyond the generator's own files, each once. */
+  readonly edited: readonly string[];
+  readonly findings: readonly Finding[];
+}
+
+/** The locale each written catalog file is for: a dry run's catalogs are not on the disk yet. */
+const writtenLocales = (written: readonly string[]): readonly string[] =>
+  written.flatMap((path) => {
+    const stem = path.startsWith(`${CATALOG_ROOT}/`) ? path.slice(CATALOG_ROOT.length + 1) : '';
+    return stem.endsWith('.json') && !stem.includes('/') ? [stem.slice(0, -'.json'.length)] : [];
+  });
+
+export async function followUpEdits(
+  root: string,
+  written: readonly string[],
+  dbModule: string | undefined,
+  disk: GenerateDisk,
+): Promise<FollowUps> {
+  const handle = await registerGeneratedEntities(root, written, dbModule, disk);
+  const adminWiring = await registerAdminResources(root, written, disk);
+  const granted = await grantGeneratedPermissions(root, written, disk);
+  const listed = await registerGeneratedPrimitives(root, written, disk);
+  // Last of the manifest writers, because the others add imports too: every sibling workspace a
+  // written file imports, declared in the manifest it landed under.
+  const imports = await declareGeneratedImports(root, written, disk);
+  // A grant that edit could not place is said so, with the role each permission belongs to.
+  const ungranted = await ungrantedByGenerator(root, written, disk);
+  // A catalog on disk and a locale the app can select are two facts — see `syncI18nIndex`.
+  const indexSync =
+    written.length > 0
+      ? await syncI18nIndex(root, disk, writtenLocales(written))
+      : { registered: true, findings: [] };
+  return {
+    edited: [
+      ...new Set([
+        ...granted,
+        ...listed,
+        ...handle.edited,
+        ...adminWiring.edited,
+        ...imports,
+        ...(indexSync.edited ?? []),
+      ]),
+    ].filter((path) => !written.includes(path)),
+    findings: [...handle.findings, ...ungranted, ...adminWiring.findings, ...indexSync.findings],
+  };
+}

package/src/generate-grant-findings.ts

@@ -3,6 +3,8 @@
 // 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 { GenerateDisk } from './generate-disk';
+import { appDisk } from './generate-disk';
 import type { RoleGrant } from './generate-grants';
 import {
   adminGrantsFor,
@@ -11,7 +13,6 @@ import {
   insertPermissions,
   writtenTables,
 } from './generate-grants';
-import { containedPath } from './generate-write';
 import type { Finding } from './output';
 import { ROLES_FILE } from './permission-grants';
 
@@ -45,15 +46,16 @@ function stillMissing(source: string, grants: readonly RoleGrant[], admin: reado
 export async function ungrantedByGenerator(
   root: string,
   written: readonly string[],
+  disk: GenerateDisk = appDisk(root),
 ): Promise<readonly Finding[]> {
-  const admin = (await writtenTables(root, written)).flatMap(adminGrantsFor);
+  const admin = (await writtenTables(root, written, disk)).flatMap(adminGrantsFor);
   const grants = [...grantsForWritten(written), ...admin];
   if (grants.length === 0) return [];
-  const file = Bun.file(containedPath(root, ROLES_FILE));
+  const source = await disk.read(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())) {
+  if (source === undefined) {
     return [
       {
         code: 'X_PERMISSION_UNGRANTED',
@@ -63,12 +65,12 @@ export async function ungrantedByGenerator(
       },
     ];
   }
-  const missing = stillMissing(await file.text(), grants, admin);
+  const missing = stillMissing(source, 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)}`,
+      cause: `${ROLES_FILE} has no role, no "grants: [...]" list or no definePermissions([...]) these could be safely 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

@@ -7,9 +7,11 @@
 // 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 type { GenerateDisk } from './generate-disk';
+import { appDisk } from './generate-disk';
 import { ROLES_FILE } from './permission-grants';
-import { wrapList } from './templates/wrap';
+import { absentFrom, appendToList, maskOf, readList, readProperties } from './source-list-edit';
+import { isEntityModule } from './templates/entity-module';
 
 /** One permission to add to one role's `grants`. */
 export interface RoleGrant {
@@ -37,8 +39,6 @@ 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*'([^']+)'/;
 
@@ -56,11 +56,31 @@ export function adminGrantsFor(table: string): readonly RoleGrant[] {
 
 const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
+const quoted = (permission: string): string => `'${permission}'`;
+
+/**
+ * Where the object of role `name` opens: a property of the `defineRoles({ … })` call, or — in a
+ * map handed to it by name — the scaffold's own `  <role>: {` row. Read off the masked text, so a
+ * role named in a comment or a string is prose and never the one edited.
+ */
+function roleObject(source: string, masked: string, name: string): number | undefined {
+  const call = /\bdefineRoles\(\s*\{/.exec(masked);
+  if (call !== null) {
+    const role = readProperties(source, masked, call.index + call[0].length - 1).find(
+      (property) => property.key === name,
+    );
+    return role !== undefined && masked[role.value] === '{' ? role.value : undefined;
+  }
+  const row = new RegExp(`\\n  ${escapeRegExp(name)}: \\{`).exec(masked);
+  return row === null ? undefined : row.index + row[0].length - 1;
+}
+
 /**
- * `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.
+ * `source` with each grant added to its role's `grants: [...]`. A list on one line is re-wrapped
+ * the way Biome prints it; a list over several lines gains a row and keeps every comment it holds.
+ * A role or a `grants` array the map does not have — or one that cannot be edited safely — is left
+ * alone and returned in `skipped`: the finding names the edit, so a guess here would be a second,
+ * worse answer.
  */
 export function insertGrants(
   source: string,
@@ -69,62 +89,63 @@ export function insertGrants(
   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)}`;
+    const masked = maskOf(next);
+    const role = roleObject(next, masked, grant.role);
+    const list =
+      role === undefined
+        ? undefined
+        : readProperties(next, masked, role).find((property) => property.key === 'grants');
+    const edited =
+      list === undefined || masked[list.value] !== '['
+        ? undefined
+        : appendToList(next, list.value, [quoted(grant.permission)]);
+    if (edited === undefined) skipped.push(grant);
+    else next = edited;
   }
   return { source: next, skipped };
 }
 
-const DECLARATION = 'definePermissions([';
+/** Every `definePermissions([` in the masked text: the index of each call's opening `[`. */
+const declarationLists = (masked: string): readonly number[] =>
+  [...masked.matchAll(/\bdefinePermissions\(\s*\[/g)].map(
+    (found) => found.index + found[0].length - 1,
+  );
 
 /**
- * `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`.
+ * `source` with each permission added to its first `definePermissions([…])`. 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. One ANY call already declares is left
+ * alone. A role map with no such call, or one that cannot be edited safely, 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));
+  const masked = maskOf(source);
+  const lists = declarationLists(masked).flatMap((open) => readList(source, masked, open) ?? []);
+  const first = lists[0];
+  if (first === undefined) return { source, skipped: [...permissions] };
+  const added = lists.reduce<readonly string[]>(
+    (absent, list) => absentFrom(list, absent),
+    permissions.map(quoted),
+  );
   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: [],
-  };
+  const edited = appendToList(source, first.open, added);
+  return edited === undefined
+    ? { source, skipped: [...permissions] }
+    : { source: edited, skipped: [] };
 }
 
-/** The entity names the written `entity.ts` files declare — read off each file, never guessed. */
+/** The entity names the written entity files declare — read off each file, never guessed. */
 export async function writtenTables(
   root: string,
   written: readonly string[],
+  disk: GenerateDisk = appDisk(root),
 ): 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];
+  for (const path of written.filter(isEntityModule)) {
+    const table = ENTITY_NAME.exec((await disk.read(path)) ?? '')?.[1];
     if (table !== undefined) tables.push(table);
   }
   return tables;
@@ -134,24 +155,30 @@ export async function writtenTables(
  * 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.
+ *
+ * A permission is declared only where its grant can be placed. An app with no `admin` role got
+ * three permissions declared that no role held — `X_PERMISSION_UNGRANTED` on the next gate, for
+ * names the author never asked for — beside the finding that said nothing was granted.
  */
 export async function grantGeneratedPermissions(
   root: string,
   written: readonly string[],
+  disk: GenerateDisk = appDisk(root),
 ): Promise<readonly string[]> {
-  const admin = (await writtenTables(root, written)).flatMap(adminGrantsFor);
+  const admin = (await writtenTables(root, written, disk)).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 before = grants.length === 0 ? undefined : await disk.read(ROLES_FILE);
+  if (before === undefined) return [];
+  const unplaced = insertGrants(before, grants).skipped;
+  const placeable = grants.filter((grant) => !unplaced.includes(grant));
   const declared = insertPermissions(
     before,
-    admin.map((grant) => grant.permission),
+    admin.filter((grant) => placeable.includes(grant)).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 grantable = placeable.filter((grant) => !declared.skipped.includes(grant.permission));
   const { source } = insertGrants(declared.source, grantable);
   if (source === before) return [];
-  await Bun.write(file, source);
+  await disk.write(ROLES_FILE, source);
   return [ROLES_FILE];
 }

package/src/generate-kinds.ts

@@ -244,18 +244,23 @@ const exampleFor = (kind: Generator): string =>
  * 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.
  *
+ * Two segments or MORE: `admin:blog:write` is a `${string}:${string}` like any other, an app's
+ * staff console declares its permissions that way, and one colon exactly refused every one of them
+ * — the page was then generated under `blog:write` and renamed by hand in three places. An empty
+ * segment (`ops::read`, `ops:`) is still no permission.
+ *
  * 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;
+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}"`,
+    reason: `expects a permission of the form <resource>:<verb> — or namespaced, <area>:<resource>:<verb> — got "${raw}"`,
     fix: `${exampleFor(kind)} --permission ops:read`,
   });
 }

package/src/generate-plural.ts

@@ -33,6 +33,17 @@ export function refusePluralTable(
   feature: string | undefined,
   exists: (path: string) => boolean,
 ): void {
+  // A feature's second entity (`entity-<name>.ts`) is named by the NAME, never by the slice.
+  const sibling = files.find((file) => /\/entity-[a-z0-9-]+\.ts$/.test(file.path));
+  const single = sibling === undefined ? undefined : singularOf(kebab(name));
+  if (single !== undefined && feature !== undefined) {
+    throw new BadFlagError({
+      flag: 'name',
+      command: `g ${kind}`,
+      reason: `"${name}" is already plural, and the entity this run writes pluralises it again for its table — "${names(name).table}"`,
+      fix: ['x g', kind, single, '--feature', feature].join(' '),
+    });
+  }
   for (const slice of writtenEntitySlices(files, exists)) {
     const singular = singularOf(slice);
     if (singular === undefined) continue;

package/src/generate-sibling.ts

@@ -0,0 +1,34 @@
+// Whether a feature's `entity.ts` makes the next `x g entity --feature` a SIBLING
+// (`entity-<name>.ts`). Decided on what the file READABLY declares, and conservatively: the
+// sibling path skips the conflict on `entity.ts`, so taking the same table for "another one" —
+// because it is spelled as a template literal, or held in a constant — wrote a second module for
+// one table where the run should have refused.
+
+import { endOfLiteral, maskLiterals, QUOTES } from '@ultimat3/core';
+import { names } from './templates/naming';
+
+/** `entity(` as a call of the imported function — never a member (`schema.entity(`). */
+const ENTITY_CALL = /(?<![.\w$])entity\(\s*/g;
+
+/**
+ * True only when `source` declares at least one entity, EVERY `entity(…)` call in it names its
+ * table as a plain string literal, none of those tables is `name`'s, and no binding in the file
+ * is `name`'s own. Anything this cannot read — a constant, an interpolation — answers false: the
+ * run then takes the ordinary path, and an existing `entity.ts` is the conflict it always was.
+ */
+export function declaresOnlyOtherEntities(source: string, name: string): boolean {
+  const masked = maskLiterals(source);
+  const calls = [...masked.matchAll(ENTITY_CALL)];
+  if (calls.length === 0) return false;
+  const { table, camel } = names(name);
+  // A camel spelling is `[A-Za-z0-9]` only (`naming.ts`), so it splices into a pattern as is.
+  if (new RegExp(`\\b(?:const|let|var)\\s+${camel}\\b`).test(masked)) return false;
+  return calls.every((call) => {
+    const at = call.index + call[0].length;
+    if (!QUOTES.has(masked[at] ?? '')) return false;
+    const end = endOfLiteral(source, at);
+    if (end === at + 1) return false;
+    const value = source.slice(at + 1, end - 1);
+    return !value.includes('${') && !value.includes('\\') && value !== table;
+  });
+}

package/src/generated-imports.ts

@@ -3,7 +3,8 @@
 // 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 type { GenerateDisk } from './generate-disk';
+import { appDisk } from './generate-disk';
 import { isGenerated, isTest } from './source-files';
 import { withDependency } from './workspace-dep-edit';
 import { importedPackages, scanWorkspaces, type WorkspaceNode } from './workspace-graph';
@@ -14,6 +15,7 @@ const SOURCE = /\.tsx?$/;
 async function missingEdges(
   root: string,
   written: readonly string[],
+  disk: GenerateDisk,
 ): Promise<Map<WorkspaceNode, Map<string, string>>> {
   const missing = new Map<WorkspaceNode, Map<string, string>>();
   const sources = written.filter(
@@ -27,7 +29,7 @@ async function missingEdges(
   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();
+    const text = (await disk.read(path)) ?? '';
     for (const name of importedPackages(text, path)) {
       const target = byName.get(name);
       if (target === undefined || target === owner || owner.dependencies.includes(name)) continue;
@@ -43,16 +45,17 @@ async function missingEdges(
 export async function declareGeneratedImports(
   root: string,
   written: readonly string[],
+  disk: GenerateDisk = appDisk(root),
 ): Promise<readonly string[]> {
   const edited: string[] = [];
-  for (const [owner, edges] of await missingEdges(root, written)) {
+  for (const [owner, edges] of await missingEdges(root, written, disk)) {
     const path = `${owner.dir}/package.json`;
-    const file = Bun.file(containedPath(root, path));
-    const before = await file.text();
+    // Through the seam, not `owner.dependencies`: an earlier edit of this run may already hold it.
+    const before = (await disk.read(path)) ?? '';
     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);
+    await disk.write(path, after);
     edited.push(path);
   }
   return edited;

package/src/handle-registration.ts

@@ -5,9 +5,12 @@
 // the two lines.
 
 import { ERROR_DOCS_URL, stripComments } from '@ultimat3/core';
-import { containedPath } from './generate-write';
+import type { GenerateDisk } from './generate-disk';
+import { appDisk } from './generate-disk';
 import type { Finding } from './output';
 import { holdsKey, withKeyedLine, withSortedImport } from './source-edit';
+import { closingBracket, maskOf, readList } from './source-list-edit';
+import { entityModuleIn } from './templates/entity-module';
 import type { GeneratedFile } from './templates/naming';
 import { plural } from './templates/naming';
 import type { HandleEntry } from './templates/scaffold-db-client';
@@ -27,7 +30,6 @@ export const DB_WORKSPACE = 'packages/db';
 const WEB_WORKSPACE = 'apps/web';
 const INDEX_FILE = `${DB_WORKSPACE}/src/index.ts`;
 
-const ENTITY_PATH = /^apps\/web\/(?<rest>[^/]+\/[^/]+)\/entity\.ts$/;
 const ENTITY_EXPORT = /\bexport const ([A-Za-z_$][\w$]*) = entity\(/;
 const IDENTIFIER = '[A-Za-z_$][\\w$]*';
 
@@ -44,19 +46,34 @@ export const handleUnregisteredFinding = (entry: HandleEntry, reason: string): F
   at: HANDLE_FILE,
 });
 
-/** The object literal `database(<name>, …)` is called with: where it opens and where it closes. */
+/**
+ * The object literal `database(<name>, …)` is called with: where it opens and where it closes.
+ * Found on the MASKED text and closed by bracket depth — the first `}` after the `{` was the end
+ * of the set, so one in a comment or in an entry's own value cut the set short.
+ */
 function entitySetOf(
   source: string,
 ): { readonly open: number; readonly close: number } | undefined {
-  const call = new RegExp(`\\bdatabase\\(\\s*(${IDENTIFIER})\\s*[,)]`).exec(source);
+  const masked = maskOf(source);
+  const call = new RegExp(`\\bdatabase\\(\\s*(${IDENTIFIER})\\s*[,)]`).exec(masked);
   if (call === null) return undefined;
-  const declared = new RegExp(`\\bconst ${call[1]}\\s*=\\s*\\{`).exec(source);
+  const declared = new RegExp(`\\bconst ${call[1]}\\s*=\\s*\\{`).exec(masked);
   if (declared === null) return undefined;
   const open = declared.index + declared[0].length;
-  const close = source.indexOf('}', open);
+  const close = closingBracket(masked, open - 1);
   return close === -1 ? undefined : { open, close };
 }
 
+/** Whether the set opening before `open` reads back as what it held plus `line`'s entry. */
+function setGained(before: string, after: string, open: number, line: string): boolean {
+  const was = readList(before, maskOf(before), open - 1);
+  const now = readList(after, maskOf(after), open - 1);
+  if (was === undefined || now === undefined) return false;
+  const expected = [...was.entries.map((entry) => entry.text), line.trim().replace(/,$/, '')];
+  const held = now.entries.map((entry) => entry.text);
+  return held.length === expected.length && expected.every((text) => held.includes(text));
+}
+
 /**
  * `source` with each entry imported and listed. An entry whose key the set already holds is left
  * alone; a file with no `const <set> = { … }` handed to `database()` is returned untouched with
@@ -77,21 +94,24 @@ export function insertHandleEntries(
     const body = next.slice(set.open, set.close);
     if (holdsKey(stripComments(body), entry.key)) continue;
     const listed = withKeyedLine(body, entry.key, handleEntryLine(entry), '  ');
-    next = withSortedImport(
-      `${next.slice(0, set.open)}${listed}${next.slice(set.close)}`,
-      handleImportLine(entry),
-      entry.specifier,
-    );
+    const edited = `${next.slice(0, set.open)}${listed}${next.slice(set.close)}`;
+    // Read back: a set this line-edit misread (a comment shaped like an entry, a value spanning
+    // rows) is refused with the two lines named, never written wrong.
+    if (!setGained(next, edited, set.open, handleEntryLine(entry))) {
+      missing.push(entry);
+      continue;
+    }
+    next = withSortedImport(edited, handleImportLine(entry), entry.specifier);
   }
   return { source: next, missing };
 }
 
 /** The entry an `entity.ts` implies, named by what the file exports; `undefined` for any other path. */
 function entryOf(path: string, source: string, webModule: string): HandleEntry | undefined {
-  const rest = ENTITY_PATH.exec(path)?.groups?.['rest'];
+  const module = entityModuleIn(path, WEB_WORKSPACE);
   const binding = ENTITY_EXPORT.exec(source)?.[1];
-  if (rest === undefined || binding === undefined) return undefined;
-  return { key: plural(binding), binding, specifier: `${webModule}/${rest}/entity` };
+  if (module === undefined || binding === undefined) return undefined;
+  return { key: plural(binding), binding, specifier: `${webModule}/${module}` };
 }
 
 /**
@@ -117,14 +137,14 @@ export function withHandleEntries(
 
 /** The entries the written files imply: one per `entity.ts` this run put on disk. */
 async function entriesFor(
-  root: string,
+  disk: GenerateDisk,
   written: readonly string[],
   webModule: string,
 ): Promise<readonly HandleEntry[]> {
   const entries: HandleEntry[] = [];
   for (const path of written) {
-    if (!ENTITY_PATH.test(path)) continue;
-    const entry = entryOf(path, await Bun.file(containedPath(root, path)).text(), webModule);
+    if (entityModuleIn(path, WEB_WORKSPACE) === undefined) continue;
+    const entry = entryOf(path, (await disk.read(path)) ?? '', webModule);
     if (entry !== undefined) entries.push(entry);
   }
   return entries;
@@ -136,11 +156,26 @@ export interface HandleRegistration {
   readonly findings: readonly Finding[];
 }
 
+const exportsHandle = (index: string): boolean => /from\s+'\.\/client'/.test(stripComments(index));
+
+/**
+ * The db package is the app's OWN: it has an index, no handle, and exports none. A handle written
+ * into it is a file nothing imports — `packages/db/src/client.ts` appeared in an app whose db
+ * package is a schema and a seed, beside a finding that said the index did not export it. Said
+ * instead, with what the generated repo expects, and nothing is created.
+ */
+const ownDbPackageFinding = (entry: HandleEntry, dbModule: string): Finding => ({
+  code: 'X_DB_HANDLE_UNREGISTERED',
+  cause: `${DB_WORKSPACE} has its own ${INDEX_FILE} and no typed handle (${HANDLE_FILE}), so "import { db } from '${dbModule}'" in the generated repo is not database()'s and db.${entry.key} does not exist — no handle was created in a package that does not export one`,
+  // Command first, the edit behind a `#`: the line runs as printed and names what it then proves.
+  fix: `x verify --only typecheck   # after rewriting the generated repo over this app's own client, or adopting the typed handle: create ${HANDLE_FILE} exporting "db = database({ ${entry.key}: ${entry.binding} }, { driver })" with ${handleImportLine(entry)} and add export { db, driver, selectDriver } from './client'; to ${INDEX_FILE}`,
+  docs: ERROR_DOCS_URL,
+  at: INDEX_FILE,
+});
+
 /** The handle exists but the package does not export it: the repo's import reaches something else. */
-async function indexFindings(root: string, dbModule: string): Promise<readonly Finding[]> {
-  const file = Bun.file(containedPath(root, INDEX_FILE));
-  const source = (await file.exists()) ? await file.text() : '';
-  if (/from\s+'\.\/client'/.test(stripComments(source))) return [];
+async function indexFindings(disk: GenerateDisk, dbModule: string): Promise<readonly Finding[]> {
+  if (exportsHandle((await disk.read(INDEX_FILE)) ?? '')) return [];
   return [
     {
       code: 'X_DB_HANDLE_UNREGISTERED',
@@ -154,7 +189,10 @@ async function indexFindings(root: string, dbModule: string): Promise<readonly F
 
 /**
  * Performs the registration for every entity among `written`: the handle's set and import, then
- * the manifest lines the new edges need. Creates the handle in an app that has none.
+ * the manifest lines the new edges need. Creates the handle in an app that has none AND whose db
+ * package would export it — an index that names `./client`, or no index at all. A db package with
+ * its own index and no handle is the app's own layout: nothing is created there, and the finding
+ * says what the generated repo expects.
  *
  * PLANNED, then written — all of it or none. A handle with no `const <set> = { … }` refuses the
  * entry, and a run that then went on to edit `packages/db/package.json` left a manifest line for
@@ -170,15 +208,19 @@ export async function registerGeneratedEntities(
   root: string,
   written: readonly string[],
   dbModule: string | undefined,
+  disk: GenerateDisk = appDisk(root),
 ): Promise<HandleRegistration> {
-  const web = await readWorkspace(root, WEB_WORKSPACE);
+  const web = await readWorkspace(root, WEB_WORKSPACE, disk);
   const module = dbModule ?? PLACEHOLDER_DB_MODULE;
   const webModule = web?.name ?? webModuleOf(module);
-  const entries = await entriesFor(root, written, webModule);
+  const entries = await entriesFor(disk, written, webModule);
   if (entries.length === 0) return { edited: [], findings: [] };
   const planned: PlannedEdit[] = [];
-  const file = Bun.file(containedPath(root, HANDLE_FILE));
-  const before = (await file.exists()) ? await file.text() : undefined;
+  const before = await disk.read(HANDLE_FILE);
+  const index = before === undefined ? await disk.read(INDEX_FILE) : undefined;
+  if (index !== undefined && !exportsHandle(index)) {
+    return { edited: [], findings: entries.map((entry) => ownDbPackageFinding(entry, module)) };
+  }
   const { source, missing } =
     before === undefined
       ? { source: dbClientSource(entries), missing: [] }
@@ -202,16 +244,16 @@ export async function registerGeneratedEntities(
       docs: ERROR_DOCS_URL,
       at: `${DB_WORKSPACE}/package.json`,
     });
-  } else findings.push(...(await indexFindings(root, dbModule)));
+  } else findings.push(...(await indexFindings(disk, dbModule)));
   const importsWeb = stripComments(source).includes(`from '${webModule}/`);
   const edges = [
     ...(importsWeb ? [[DB_WORKSPACE, WEB_WORKSPACE] as const] : []),
     [WEB_WORKSPACE, DB_WORKSPACE] as const,
   ];
   for (const [from, to] of edges) {
-    const manifest = await planWorkspaceDependency(root, from, to);
+    const manifest = await planWorkspaceDependency(root, from, to, disk);
     if (manifest !== undefined) planned.push(manifest);
   }
-  for (const edit of planned) await Bun.write(containedPath(root, edit.path), edit.contents);
+  for (const edit of planned) await disk.write(edit.path, edit.contents);
   return { edited: planned.map((edit) => edit.path), findings };
 }