@ultimat3/cli 27.6.1 → 27.7.0

package/CLAUDE.md

@@ -91,7 +91,7 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 | `module-imports.ts` | the files a module's source imports, resolved once for both graphs: `referenced` (reload) and `evaluated` (document) |
 | `cmd-dev.ts` / `dev-boot.ts` / `dev-rebuild.ts` / `dev-route-table.ts` | `x dev`: the command (`cmd-dev.ts`, re-exports `startDev`); the boot — every role in one process, `/_x`, the watcher (`dev-boot.ts`); one save rebuilt as one generation (`dev-rebuild.ts`) |
 | `runtime-bindings.ts` | which service each binding points at (embedded or external); events follow `realtime.transport` / `urlEnv` |
-| `runtime-queue.ts` / `runtime-services.ts` | the db + queue pair; everything else and every ambient accessor |
+| `runtime-queue.ts` / `runtime-services.ts` / `runtime-bus.ts` | db + queue; every other accessor; the bus |
 | `framework-schema-apply.ts` / `framework-schema-stamp.ts` | the framework tables: `ROLE=migrate`, `x dev` and every CLI command APPLY them in one transaction behind `MIGRATION_LOCK_KEY` (`pg_advisory_xact_lock`) with a bounded `lock_timeout`, then stamp the build on `x_jobs`' table comment; a serving role on an external database runs no DDL and VERIFIES the stamp (`X_FRAMEWORK_SCHEMA_UNAPPLIED`, a major skew is a warning). A comment, never a table: a new framework table moves every app's schema dump |
 | `runtime-isr.ts` | the ISR controller both boots serve through, ATTACHED to `invalidateTags` and released on stop (`attachedIsr`); `appRoutes` without one builds and attaches its own |
 | `runtime-mfa-warning.ts` / `runtime-idempotency-scope.ts` | boot warnings an operator can act on: unsealed MFA secrets (web role, `x auth seal-mfa`), a per-process idempotency store after the app loaded |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "27.6.1",
+  "version": "27.7.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -39,33 +39,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "27.6.1",
-    "@ultimat3/admin": "27.6.1",
-    "@ultimat3/ai": "27.6.1",
-    "@ultimat3/auth": "27.6.1",
-    "@ultimat3/cache": "27.6.1",
-    "@ultimat3/core": "27.6.1",
-    "@ultimat3/db": "27.6.1",
-    "@ultimat3/entity": "27.6.1",
-    "@ultimat3/flags": "27.6.1",
-    "@ultimat3/http": "27.6.1",
-    "@ultimat3/i18n": "27.6.1",
-    "@ultimat3/jobs": "27.6.1",
-    "@ultimat3/mail": "27.6.1",
-    "@ultimat3/manifest": "27.6.1",
-    "@ultimat3/mcp": "27.6.1",
-    "@ultimat3/money": "27.6.1",
-    "@ultimat3/notify": "27.6.1",
-    "@ultimat3/policy": "27.6.1",
-    "@ultimat3/pwa": "27.6.1",
-    "@ultimat3/query": "27.6.1",
-    "@ultimat3/realtime": "27.6.1",
-    "@ultimat3/render": "27.6.1",
-    "@ultimat3/schema": "27.6.1",
-    "@ultimat3/seo": "27.6.1",
-    "@ultimat3/storage": "27.6.1",
-    "@ultimat3/testing": "27.6.1",
-    "@ultimat3/time": "27.6.1",
+    "@ultimat3/action": "27.7.0",
+    "@ultimat3/admin": "27.7.0",
+    "@ultimat3/ai": "27.7.0",
+    "@ultimat3/auth": "27.7.0",
+    "@ultimat3/cache": "27.7.0",
+    "@ultimat3/core": "27.7.0",
+    "@ultimat3/db": "27.7.0",
+    "@ultimat3/entity": "27.7.0",
+    "@ultimat3/flags": "27.7.0",
+    "@ultimat3/http": "27.7.0",
+    "@ultimat3/i18n": "27.7.0",
+    "@ultimat3/jobs": "27.7.0",
+    "@ultimat3/mail": "27.7.0",
+    "@ultimat3/manifest": "27.7.0",
+    "@ultimat3/mcp": "27.7.0",
+    "@ultimat3/money": "27.7.0",
+    "@ultimat3/notify": "27.7.0",
+    "@ultimat3/policy": "27.7.0",
+    "@ultimat3/pwa": "27.7.0",
+    "@ultimat3/query": "27.7.0",
+    "@ultimat3/realtime": "27.7.0",
+    "@ultimat3/render": "27.7.0",
+    "@ultimat3/schema": "27.7.0",
+    "@ultimat3/seo": "27.7.0",
+    "@ultimat3/storage": "27.7.0",
+    "@ultimat3/testing": "27.7.0",
+    "@ultimat3/time": "27.7.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/admin-registration.ts

@@ -4,8 +4,9 @@
 // Performed here; where the admin is not a `defineAdmin({ … })` this can add to, the finding names
 // the two lines.
 
-import { ERROR_DOCS_URL, stripComments } from '@ultimat3/core';
-import { containedPath } from './generate-write';
+import { ERROR_DOCS_URL, maskLiterals, stripComments } from '@ultimat3/core';
+import type { GenerateDisk } from './generate-disk';
+import { appDisk } from './generate-disk';
 import type { Finding } from './output';
 import { holdsKey, withKeyedLine, withSortedImport } from './source-edit';
 import type { GeneratedFile } from './templates/naming';
@@ -70,7 +71,8 @@ export function insertAdminResources(
   let next = source;
   const missing: AdminResourceEntry[] = [];
   for (const entry of entries) {
-    const masked = stripComments(next);
+    // Literals masked too: a brace inside a string label is not one of the call's.
+    const masked = maskLiterals(next);
     const call = /\bdefineAdmin\(\s*\{/.exec(masked);
     const open = call === null ? -1 : call.index + call[0].length - 1;
     const close = open === -1 ? -1 : closeOf(masked, open);
@@ -140,18 +142,17 @@ export function withAdminResources(
 
 /** The overrides among the written paths, each named by what its file and its entity export. */
 async function entriesFor(
-  root: string,
+  disk: GenerateDisk,
   written: readonly string[],
   webModule: string,
 ): Promise<readonly AdminResourceEntry[]> {
   const entries: AdminResourceEntry[] = [];
   for (const path of written) {
     if (!OVERRIDE_PATH.test(path)) continue;
-    const entity = Bun.file(containedPath(root, entityPathOf(path)));
     const entry = entryOf(
       path,
-      await Bun.file(containedPath(root, path)).text(),
-      (await entity.exists()) ? await entity.text() : undefined,
+      (await disk.read(path)) ?? '',
+      await disk.read(entityPathOf(path)),
       webModule,
     );
     if (entry !== undefined) entries.push(entry);
@@ -169,24 +170,24 @@ export interface AdminRegistration {
 export async function registerAdminResources(
   root: string,
   written: readonly string[],
+  disk: GenerateDisk = appDisk(root),
 ): Promise<AdminRegistration> {
-  const web = await readWorkspace(root, WEB_WORKSPACE);
-  const entries = web === undefined ? [] : await entriesFor(root, written, web.name);
+  const web = await readWorkspace(root, WEB_WORKSPACE, disk);
+  const entries = web === undefined ? [] : await entriesFor(disk, written, web.name);
   if (entries.length === 0) return { edited: [], findings: [] };
-  const file = Bun.file(containedPath(root, ADMIN_FILE));
-  if (!(await file.exists())) {
+  const before = await disk.read(ADMIN_FILE);
+  if (before === undefined) {
     return {
       edited: [],
       findings: entries.map((entry) => adminResourceUnwiredFinding(entry, 'does not exist')),
     };
   }
-  const before = await file.text();
   const { source, missing } = insertAdminResources(before, entries);
   const findings = missing.map((entry) =>
     adminResourceUnwiredFinding(entry, 'holds no defineAdmin({ … }) call to add to'),
   );
   if (source === before) return { edited: [], findings };
-  await Bun.write(containedPath(root, ADMIN_FILE), source);
-  const manifest = await declareWorkspaceDependency(root, ADMIN_WORKSPACE, WEB_WORKSPACE);
+  await disk.write(ADMIN_FILE, source);
+  const manifest = await declareWorkspaceDependency(root, ADMIN_WORKSPACE, WEB_WORKSPACE, disk);
   return { edited: manifest === undefined ? [ADMIN_FILE] : [ADMIN_FILE, manifest], findings };
 }

package/src/api-registration.ts

@@ -6,10 +6,13 @@
 
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import { API_INDEX } from './app-root';
+import type { GenerateDisk } from './generate-disk';
+import { appDisk } from './generate-disk';
 import { containedPath } from './generate-write';
 import type { Finding } from './output';
+import type { SourceList } from './source-list-edit';
+import { appendToList, maskOf, readList, readProperties } from './source-list-edit';
 import { camel } from './templates/naming';
-import { wrapList } from './templates/wrap';
 
 /** One module to import as a namespace and list under a `defineApi` key. */
 export interface ApiEntry {
@@ -56,42 +59,30 @@ export function apiEntriesFor(written: readonly string[]): readonly ApiEntry[] {
 }
 
 /**
- * Every `[...]` entry of a `key: [...]` list in the `defineApi({ ... })` call, and where it sits:
- * `line` is the start of the line holding `key: [`, `start` is just past the `[`, `end` is the `]`.
- *
- * Searched from `from` (the `defineApi({` call), so a `jobs: [` in a comment or an object above the
- * call is never the one edited. `line` is found from the key, never from `start`: in a list already
- * wrapped one entry per line the character AT `start` is the newline after `[`, and a backwards
- * search from there answered the first ITEM's line — the rewrite then nested a second `jobs: [`
- * inside the first and left the old `]` behind.
+ * The `key: [...]` lists of the `defineApi({ ... })` call, read off the MASKED text: a `jobs: [` in
+ * a comment or an object above the call is never the one edited, and a `]` or a comma inside a
+ * comment between two entries ends nothing. (The list was closed at the first `]` in the raw text
+ * and split at every comma — a commented list was rewritten with its comment as an entry.)
  */
-const listOf = (
-  source: string,
-  key: string,
-  from: number,
-): { line: number; start: number; end: number; items: string[] } | undefined => {
-  const open = new RegExp(`\\n([ \\t]*)${key}: \\[`, 'g');
-  open.lastIndex = from;
-  const found = open.exec(source);
-  if (found === null) return undefined;
-  const line = found.index + 1;
-  const start = found.index + found[0].length;
-  const end = source.indexOf(']', start);
-  if (end === -1) return undefined;
-  const items = source
-    .slice(start, end)
-    .split(',')
-    .map((item) => item.trim())
-    .filter((item) => item.length > 0);
-  return { line, start, end, items };
+const listsOf = (source: string): ((key: string) => SourceList | undefined) | undefined => {
+  const masked = maskOf(source);
+  const call = /\bdefineApi\(\s*\{/.exec(masked);
+  if (call === null) return undefined;
+  const properties = readProperties(source, masked, call.index + call[0].length - 1);
+  return (key) => {
+    const property = properties.find((one) => one.key === key);
+    return property === undefined || masked[property.value] !== '['
+      ? undefined
+      : readList(source, masked, property.value);
+  };
 };
 
 /**
  * `source` with each entry imported and listed. The import joins the `import * as` block in sorted
  * position; the binding joins its list, which is created after `actions: [...]` when the call has
- * none. An index that is not the scaffold's shape — no `defineApi({`, no `actions:` list — is
- * returned untouched with the entries in `skipped`, and the `manifest` step's X_JOB_UNREGISTERED
- * names the edit.
+ * none. An index that is not the scaffold's shape — no `defineApi({`, no `actions:` list — or a
+ * list that cannot be edited safely is returned untouched with the entries in `skipped`, and the
+ * `manifest` step's X_JOB_UNREGISTERED names the edit.
  */
 export function insertApiEntries(
   source: string,
@@ -101,28 +92,38 @@ export function insertApiEntries(
   const skipped: ApiEntry[] = [];
   for (const entry of entries) {
     const importLine = `import * as ${entry.binding} from '${entry.specifier}';`;
-    const call = next.indexOf('defineApi({');
-    const actions = call === -1 ? undefined : listOf(next, 'actions', call);
-    if (call === -1 || actions === undefined) {
+    const listOf = listsOf(next);
+    const actions = listOf?.('actions');
+    if (listOf === undefined || actions === undefined) {
       skipped.push(entry);
       continue;
     }
-    const list = listOf(next, entry.key, call);
-    if (list?.items.includes(entry.binding) === true) continue;
+    const list = listOf(entry.key);
+    if (list?.entries.some((one) => one.text === entry.binding) === true) continue;
     if (list === undefined) {
       // In the order `x new` writes — actions, queries, jobs, tasks: after the nearest list
       // before it that the call already holds, which is `actions` at the least.
       const earlier = LIST_ORDER.slice(0, LIST_ORDER.indexOf(entry.key))
-        .map((key) => listOf(next, key, call))
+        .map((key) => listOf(key))
         .findLast((found) => found !== undefined);
-      const after = next.indexOf('\n', (earlier ?? actions).end);
+      const after = next.indexOf('\n', (earlier ?? actions).close);
       const line = `  ${entry.key}: [${entry.binding}],`;
-      next = `${next.slice(0, after + 1)}${line}\n${next.slice(after + 1)}`;
+      const candidate = `${next.slice(0, after + 1)}${line}\n${next.slice(after + 1)}`;
+      // Read back, as every other edit here is: when the earlier list shares its row with the
+      // call's own `});`, "the row after it" is OUTSIDE the call — a property of nothing.
+      const landed = listsOf(candidate)?.(entry.key);
+      if (landed?.entries.some((one) => one.text === entry.binding) !== true) {
+        skipped.push(entry);
+        continue;
+      }
+      next = candidate;
     } else {
-      const items = [...list.items, entry.binding];
-      const indent = /^[ \t]*/.exec(next.slice(list.line))?.[0] ?? '';
-      const rewritten = wrapList(indent, `${entry.key}: [`, items, ']');
-      next = `${next.slice(0, list.line)}${rewritten}${next.slice(list.end + 1)}`;
+      const edited = appendToList(next, list.open, [entry.binding]);
+      if (edited === undefined) {
+        skipped.push(entry);
+        continue;
+      }
+      next = edited;
     }
     if (!next.includes(importLine)) next = withImport(next, importLine);
   }
@@ -236,13 +237,13 @@ export async function indexBindingFindings(
 export async function registerGeneratedPrimitives(
   root: string,
   written: readonly string[],
+  disk: GenerateDisk = appDisk(root),
 ): Promise<readonly string[]> {
   const entries = apiEntriesFor(written);
-  const file = containedPath(root, API_INDEX);
-  if (entries.length === 0 || !(await Bun.file(file).exists())) return [];
-  const before = await Bun.file(file).text();
+  const before = entries.length === 0 ? undefined : await disk.read(API_INDEX);
+  if (before === undefined) return [];
   const { source } = insertApiEntries(before, entries);
   if (source === before) return [];
-  await Bun.write(file, source);
+  await disk.write(API_INDEX, source);
   return [API_INDEX];
 }

package/src/cmd-generate.ts

@@ -4,8 +4,7 @@
 
 import { existsSync } from 'node:fs';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
-import { registerAdminResources } from './admin-registration';
-import { indexBindingFindings, registerGeneratedPrimitives } from './api-registration';
+import { indexBindingFindings } from './api-registration';
 import { writeAppArtifacts } from './app-artifacts';
 import { appManifest } from './app-manifest';
 import { requireAppRoot } from './app-root';
@@ -13,19 +12,19 @@ import { generateSpec } from './cmd-generate-spec';
 import type { CliCommand, CommandContext } from './command';
 import { invocationOf } from './command';
 import { localiseCatalogs } from './generate-catalog-locales';
+import { appDisk, plannedDisk } from './generate-disk';
 import { assertFeatureExists } from './generate-feature';
 import { generate, sliceDir } from './generate-files';
-import { ungrantedByGenerator } from './generate-grant-findings';
-import { grantGeneratedPermissions } from './generate-grants';
+import { followUpEdits } from './generate-follow-ups';
 import type { Generator } from './generate-kinds';
 import { readFeature, readKind, readName, readPermission, readSurface } from './generate-kinds';
 import { refusePluralTable } from './generate-plural';
 import { refuseShadowedTypes, refuseShadowedValues } from './generate-shadow';
+import { declaresOnlyOtherEntities } from './generate-sibling';
 import { containedPath, planWrites, writeFiles } from './generate-write';
-import { declareGeneratedImports } from './generated-imports';
-import { registerGeneratedEntities, resolveDbModule } from './handle-registration';
+import { resolveDbModule } from './handle-registration';
 import { resolveCatalogModule } from './i18n-audit';
-import { catalogLocales, syncI18nIndex } from './i18n-index';
+import { catalogLocales } from './i18n-index';
 import { reproducedFlags } from './invocation-flags';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
@@ -33,6 +32,7 @@ import { flagBool, flagList, flagString } from './parse';
 import { quoteArg } from './shell-quote';
 import type { GeneratedFile } from './templates';
 import { kebab, names, resolveLocales } from './templates';
+import { isEntityModule } from './templates/entity-module';
 
 // One import path for the generator, unchanged by the split: `index.ts`, `x new` and the scaffold
 // fixture reach the kinds, the pure file list and the writer through this module, and a second path
@@ -94,6 +94,11 @@ export const generateCommand: CliCommand = {
     // THIS feature's own `entity.ts`/`repo.ts`, not a default the template gets to assume.
     const sliceEntity = await readSliceFile(root, kind, slice, 'entity.ts');
     const sliceRepo = await readSliceFile(root, kind, slice, 'repo.ts');
+    // A feature's SECOND entity: `entity.ts` is another table's, so this one lands beside it.
+    const sibling =
+      kind === 'entity' &&
+      featureFlag !== undefined &&
+      (await holdsAnotherEntity(root, slice, name));
     const planFor = (planned: string) =>
       generate({
         kind,
@@ -111,6 +116,7 @@ export const generateCommand: CliCommand = {
         ...(catalogModule === undefined ? {} : { catalogModule }),
         ...(dbModule === undefined ? {} : { dbModule }),
         shell,
+        sibling,
       });
     // A non-default locale's strings arrive marked, and a locale with no catalog yet is refused
     // with `x i18n add <locale>` — before a dry run answers, so it answers the same files.
@@ -149,14 +155,43 @@ export const generateCommand: CliCommand = {
     if (flagBool(ctx.args, 'dry-run')) {
       // The write plan, never the bare file list: what the real run would write, skip and refuse.
       const plan = await planWrites(root, files, force, invocation);
-      const findings = [...plan.conflicts, ...bindings];
-      const planned = findings.length === 0 ? plan.written : [];
+      const refused = [...plan.conflicts, ...bindings];
+      // And the edits OUTSIDE the slice — role map, handle, API index, manifests, catalog index —
+      // run for real against the plan held in memory: the same code, so the same list. A dry run
+      // that named five new files while the run rewrote four the caller owns was no plan.
+      const planned = new Map(
+        files.flatMap((file) =>
+          plan.written.includes(file.path) && typeof file.contents === 'string'
+            ? [[file.path, file.contents] as const]
+            : [],
+        ),
+      );
+      const follow =
+        refused.length > 0
+          ? { edited: [], findings: [] }
+          : await followUpEdits(root, plan.written, dbModule, plannedDisk(root, planned));
+      const findings = [...refused, ...follow.findings];
+      const touched = refused.length === 0 ? [...plan.written, ...follow.edited] : [];
+      // Re-projected after a real write, from the loaded app: named, since their bytes are not
+      // knowable without the files on disk.
+      const refreshes =
+        plan.written.length === 0 || refused.length > 0
+          ? []
+          : [MANIFEST_FILENAME, 'openapi.json'].filter((file) =>
+              existsSync(containedPath(root, file)),
+            );
       return {
         ok: findings.length === 0,
         command: 'g',
-        summary: msg('cli.generate.planned', { count: planned.length, kind, name }),
-        data: { files: planned, dryRun: true },
-        lines: planned.map((file) => msg('cli.file.added', { path: file })),
+        summary: msg('cli.generate.planned', { count: touched.length, kind, name }),
+        data: {
+          files: touched,
+          // The subset that already exists and would be EDITED, never created.
+          edits: follow.edited.filter((path) => existsSync(containedPath(root, path))),
+          ...(refreshes.length === 0 ? {} : { refreshes }),
+          dryRun: true,
+        },
+        lines: touched.map((file) => msg('cli.file.added', { path: file })),
         findings,
       };
     }
@@ -164,34 +199,11 @@ export const generateCommand: CliCommand = {
       bindings.length > 0
         ? { written: [], conflicts: bindings }
         : await writeFiles(root, files, force, invocation);
-    // The three edits a generated primitive needs outside its own slice, performed rather than
-    // left as findings: a declared permission granted to a role, a job listed in `defineApi`, and
-    // an entity added to the typed handle its `repo.ts` reads through. Before the manifest load
-    // below, so the projection sees all three — a repo reading a table the handle lacks would not
-    // load at all.
-    const handle = await registerGeneratedEntities(root, report.written, dbModule);
-    // And a fourth, for `--admin`: the override it wrote, listed where `defineAdmin()` reads it.
-    const adminWiring = await registerAdminResources(root, report.written);
-    // And a fifth, last because the others add imports too: every sibling workspace a written file
-    // imports, declared in the manifest it landed under — or `package-shape` refuses the output.
-    const edited = [
-      ...new Set([
-        ...(await grantGeneratedPermissions(root, report.written)),
-        ...(await registerGeneratedPrimitives(root, report.written)),
-        ...handle.edited,
-        ...adminWiring.edited,
-        ...(await declareGeneratedImports(root, report.written)),
-      ]),
-    ];
-    // A grant that edit could not place is said so, with the role each permission belongs to: an
-    // app whose role map is not the scaffold's got no grant and no word, and a 403 on every
-    // endpoint the run had just written.
-    const ungranted = await ungrantedByGenerator(root, report.written);
-    // A locale's catalog existing on disk and the app being able to select it are two different
-    // facts — see `syncI18nIndex`. Runs before the manifest load below so a route or resource
-    // this same invocation just wrote never gets projected against a stale catalog registration.
-    const indexSync =
-      report.written.length > 0 ? await syncI18nIndex(root) : { registered: true, findings: [] };
+    // The edits a generated primitive needs outside its own slice, performed rather than left as
+    // findings (`generate-follow-ups.ts`). Before the manifest load below, so the projection sees
+    // them all — a repo reading a table the handle lacks would not load at all.
+    const follow = await followUpEdits(root, report.written, dbModule, appDisk(root));
+    const edited = follow.edited;
     // Facts, not prose: every `x g` run leaves the route/action/entity/job/policy table current,
     // the same guarantee `x manifest` makes on its own — an agent reading it after `x g` never
     // sees a resource that exists on disk but not in the manifest.
@@ -216,14 +228,7 @@ export const generateCommand: CliCommand = {
         buildId = manifest.buildId;
       } else loadFailures.push(...findings);
     }
-    const findings = [
-      ...report.conflicts,
-      ...handle.findings,
-      ...ungranted,
-      ...adminWiring.findings,
-      ...indexSync.findings,
-      ...loadFailures,
-    ];
+    const findings = [...report.conflicts, ...follow.findings, ...loadFailures];
     // One list behind all three renderings. The manifest was printed as a `+` line while the count
     // beside it came from `report.written` alone, so `x g island` said "wrote 2 file(s)" over three
     // lines — and `--json` carried the shorter list, which is the drift `--json` exists to prevent.
@@ -289,7 +294,7 @@ export function nextSteps(
   edited: readonly string[],
   table: string,
 ): readonly string[] {
-  if (!written.some((path) => path.endsWith('/entity.ts'))) return [];
+  if (!written.some(isEntityModule)) return [];
   return [
     ...(edited.some((path) => path.endsWith('package.json')) ? ['bun install'] : []),
     `bunx x db gen "create ${table}"`,
@@ -322,6 +327,17 @@ async function readSliceErrors(
   return existsSync(file) ? await Bun.file(file).text() : undefined;
 }
 
+/**
+ * Whether the slice's `entity.ts` is there and readably declares only tables OTHER than `name`'s
+ * (`generate-sibling.ts`). The same entity again — or one this cannot read — is the conflict it
+ * always was (`--force` regenerates it); a different one is a second table for the feature, which
+ * `--force` would have written OVER the first.
+ */
+async function holdsAnotherEntity(root: string, slice: string, name: string): Promise<boolean> {
+  const file = containedPath(root, `${slice}/entity.ts`);
+  return existsSync(file) && declaresOnlyOtherEntities(await Bun.file(file).text(), name);
+}
+
 /** The generators whose output depends on what the slice's `entity.ts` / `repo.ts` declare. */
 const READS_SLICE: ReadonlySet<Generator> = new Set([
   'job',

package/src/dev-boot.ts

@@ -113,7 +113,14 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
   // boot passed nothing here and built its own embedded disk, so an app's `/_storage` routes and its
   // actions wrote to two different places in `x dev` and to one in production.
   const appRuntime = await loadAppRuntime(options.root);
-  const runtime: RunningServices = await startServices(resolved, env, appRuntime);
+  // The roles decide whether this boot waits for the bus, exactly as a container's one role does.
+  const runtime: RunningServices = await startServices(
+    resolved,
+    env,
+    appRuntime,
+    'apply',
+    options.roles ?? DEV_ROLES,
+  );
   // The events binding the boot line reports is the bus the runtime chose, read off it.
   const services = withRealtimeEvents(resolved, env, runtime.realtime);
   // `serve.ts`'s `releaseBoot` shape: everything acquired from here on is released, newest first,

package/src/generate-disk.ts

@@ -0,0 +1,38 @@
+// The files a generator's follow-up edits read and write, behind one seam — so `x g --dry-run` can
+// run the SAME edits against the plan and answer every path a real run would touch. The dry run
+// listed the files a generator creates and none it edits: the role map, the typed handle, the API
+// index and two manifests changed under a plan that never named them.
+
+import { containedPath } from './generate-write';
+
+/** App-root-relative reads and writes. A read of a file that is not there answers `undefined`. */
+export interface GenerateDisk {
+  read(path: string): Promise<string | undefined>;
+  write(path: string, contents: string): Promise<void>;
+}
+
+/** The app's own disk. */
+export const appDisk = (root: string): GenerateDisk => ({
+  async read(path) {
+    const file = Bun.file(containedPath(root, path));
+    return (await file.exists()) ? await file.text() : undefined;
+  },
+  async write(path, contents) {
+    await Bun.write(containedPath(root, path), contents);
+  },
+});
+
+/**
+ * The disk as it WOULD stand after a run: `planned` is what the run creates, read before the real
+ * file, and a write lands in memory only. Nothing under `root` changes.
+ */
+export const plannedDisk = (root: string, planned: ReadonlyMap<string, string>): GenerateDisk => {
+  const held = new Map(planned);
+  const real = appDisk(root);
+  return {
+    read: async (path) => held.get(path) ?? (await real.read(path)),
+    async write(path, contents) {
+      held.set(path, contents);
+    },
+  };
+};

package/src/generate-files.ts

@@ -82,6 +82,11 @@ export interface GenerateOptions {
    * resource's page renders inside it. Read off the disk by `run`, for `catalogModule`'s reason.
    */
   readonly shell?: boolean;
+  /**
+   * `entity` only: the feature's `entity.ts` already declares ANOTHER table, so this entity is
+   * written beside it as `entity-<name>.ts` + `repo-<name>.ts`. Read off the disk by `run`.
+   */
+  readonly sibling?: boolean;
 }
 
 const DEFAULT_SURFACE_DIR: Record<Surface, string> = {
@@ -174,7 +179,7 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
       // 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),
+        ...entityFiles(options.name, target, { sibling: options.sibling === true }),
         ...adminCatalogFiles(options.name, target, options.locales),
       ]);
     case 'policy':

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],
+  };
+}