@ultimat3/cli 22.14.0 → 23.0.0

package/src/guards.ts

@@ -11,8 +11,8 @@ import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { ERROR_DOCS_URL, renderCauseValue, renderThrowable } from '@ultimat3/core';
 import { fixProblem } from './error-contract';
+import { type GuardSources, guardSources } from './guard-sources';
 import type { Finding } from './output';
-import type { HostCheck } from './verify-step';
 
 /** The directory IS the registration. An app-side list is a list an app can forget to add to. */
 export const GUARD_DIR = 'guards';
@@ -24,8 +24,13 @@ export interface Guard {
    * The rule, over the app root. Returns findings — it never prints, never decides an exit code
    * and never throws for a normal result, because `--json`, the step table and the exit code are
    * all projections of what it returns (axiom 2).
+   *
+   * `sources` is the run's ONE read of the app (`guard-sources.ts`): a guard that asks it for
+   * files or a compiled stylesheet shares the walk, the read and the compile with every other
+   * guard in the directory. A guard that reads something else — a migration, a lockfile — still
+   * may, from `root`.
    */
-  check(root: string): Promise<readonly Finding[]> | readonly Finding[];
+  check(root: string, sources: GuardSources): Promise<readonly Finding[]> | readonly Finding[];
 }
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -129,7 +134,11 @@ const findingInvalid = (path: string, cause: string): Finding => ({
 const messageOf = (error: unknown): string => renderThrowable(error);
 
 /** One guard: import it, run it, and hold what it returns to the contract. Never throws. */
-async function runGuard(root: string, path: string): Promise<readonly Finding[]> {
+async function runGuard(
+  root: string,
+  path: string,
+  sources: GuardSources,
+): Promise<readonly Finding[]> {
   let loaded: unknown;
   try {
     loaded = await import(pathToFileURL(join(root, path)).href);
@@ -149,7 +158,7 @@ async function runGuard(root: string, path: string): Promise<readonly Finding[]>
   }
   let returned: unknown;
   try {
-    returned = await exported.check(root);
+    returned = await exported.check(root, sources);
   } catch (error) {
     return [failed(path, `${path} ("${exported.summary}") threw: ${messageOf(error)}`)];
   }
@@ -173,14 +182,21 @@ async function runGuard(root: string, path: string): Promise<readonly Finding[]>
 }
 
 /**
- * Every guard this app declares, as findings the step it rides on adds to its own. Typed as a
+ * Every guard this app declares, as findings the step it rides on adds to its own. Shaped as a
  * `HostCheck` because that is exactly the seam's shape — a rule the repo enforces on itself,
  * contributed to a step that already exists. A guard can never add, remove, reorder or skip a
  * step, which is what keeps "green" meaning one thing (axiom 5) while the app still gets to make
  * its own convention a build error.
  */
-export const guardFindings: HostCheck = async (root) => {
+export const guardFindings = async (
+  root: string,
+  /** Files the step already read (`guardSources`' seed), so no guard reads one a second time. */
+  seed: readonly { readonly path: string; readonly source: string }[] = [],
+): Promise<readonly Finding[]> => {
   const findings: Finding[] = [];
-  for (const path of await guardPaths(root)) findings.push(...(await runGuard(root, path)));
+  const sources = guardSources(root, seed);
+  for (const path of await guardPaths(root)) {
+    findings.push(...(await runGuard(root, path, sources)));
+  }
   return findings;
 };

package/src/handle-registration.ts

@@ -0,0 +1,217 @@
+// `x g entity` / `x g resource` hand the entity they wrote to the app's typed database handle. The
+// generated `repo.ts` reads `db.<table>`, and a table is on the handle only when its entity is in
+// the set `packages/db/src/client.ts` passes to `database()` — an edit nothing made, so the repo
+// did not compile. Performed here; where the file is not the scaffold's shape, the finding names
+// the two lines.
+
+import { ERROR_DOCS_URL, stripComments } from '@ultimat3/core';
+import { containedPath } from './generate-write';
+import type { Finding } from './output';
+import { holdsKey, withKeyedLine, withSortedImport } from './source-edit';
+import type { GeneratedFile } from './templates/naming';
+import { plural } from './templates/naming';
+import type { HandleEntry } from './templates/scaffold-db-client';
+import {
+  dbClientSource,
+  HANDLE_FILE,
+  handleEntryLine,
+  handleImportLine,
+  PLACEHOLDER_DB_MODULE,
+  webModuleOf,
+} from './templates/scaffold-db-client';
+import type { PlannedEdit } from './workspace-dep-edit';
+import { planWorkspaceDependency, readWorkspace } from './workspace-dep-edit';
+
+/** The two workspaces the handle joins: it lives in one and imports entities from the other. */
+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$]*';
+
+/** The `@<app>/db` a generated `repo.ts` imports the handle from; absent when the app names none. */
+export const resolveDbModule = async (root: string): Promise<string | undefined> =>
+  (await readWorkspace(root, DB_WORKSPACE))?.name;
+
+/** The finding for an entity the handle does not serve, carrying the edit that makes it. */
+export const handleUnregisteredFinding = (entry: HandleEntry, reason: string): Finding => ({
+  code: 'X_DB_HANDLE_UNREGISTERED',
+  cause: `${HANDLE_FILE} ${reason}, so db.${entry.key} does not exist and the generated repo.ts does not compile`,
+  fix: `add ${handleImportLine(entry)} and the line "${handleEntryLine(entry).trim()}" to the entity set passed to database() in ${HANDLE_FILE}`,
+  docs: ERROR_DOCS_URL,
+  at: HANDLE_FILE,
+});
+
+/** The object literal `database(<name>, …)` is called with: where it opens and where it closes. */
+function entitySetOf(
+  source: string,
+): { readonly open: number; readonly close: number } | undefined {
+  const call = new RegExp(`\\bdatabase\\(\\s*(${IDENTIFIER})\\s*[,)]`).exec(source);
+  if (call === null) return undefined;
+  const declared = new RegExp(`\\bconst ${call[1]}\\s*=\\s*\\{`).exec(source);
+  if (declared === null) return undefined;
+  const open = declared.index + declared[0].length;
+  const close = source.indexOf('}', open);
+  return close === -1 ? undefined : { open, close };
+}
+
+/**
+ * `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
+ * every entry in `missing`.
+ */
+export function insertHandleEntries(
+  source: string,
+  entries: readonly HandleEntry[],
+): { readonly source: string; readonly missing: readonly HandleEntry[] } {
+  let next = source;
+  const missing: HandleEntry[] = [];
+  for (const entry of entries) {
+    const set = entitySetOf(next);
+    if (set === undefined) {
+      missing.push(entry);
+      continue;
+    }
+    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,
+    );
+  }
+  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 binding = ENTITY_EXPORT.exec(source)?.[1];
+  if (rest === undefined || binding === undefined) return undefined;
+  return { key: plural(binding), binding, specifier: `${webModule}/${rest}/entity` };
+}
+
+/**
+ * The same registration over a file LIST, for a caller that composes generators without a disk —
+ * the scaffold fixture runs every generator on top of `x new` and compiles the result, and a
+ * handle that listed only the example entity would fail that compile on every other repo.
+ */
+export function withHandleEntries(
+  files: readonly GeneratedFile[],
+  dbModule: string,
+): readonly GeneratedFile[] {
+  const entries = files.flatMap((file) => {
+    if (typeof file.contents !== 'string') return [];
+    const entry = entryOf(file.path, file.contents, webModuleOf(dbModule));
+    return entry === undefined ? [] : [entry];
+  });
+  return files.map((file) =>
+    file.path === HANDLE_FILE && typeof file.contents === 'string' && file.merge === undefined
+      ? { ...file, contents: insertHandleEntries(file.contents, entries).source }
+      : file,
+  );
+}
+
+/** The entries the written files imply: one per `entity.ts` this run put on disk. */
+async function entriesFor(
+  root: string,
+  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 (entry !== undefined) entries.push(entry);
+  }
+  return entries;
+}
+
+export interface HandleRegistration {
+  /** App-root-relative paths this rewrote or created. */
+  readonly edited: readonly string[];
+  readonly findings: readonly Finding[];
+}
+
+/** 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 [];
+  return [
+    {
+      code: 'X_DB_HANDLE_UNREGISTERED',
+      cause: `${INDEX_FILE} does not export the typed handle, so "import { db } from '${dbModule}'" in the generated repo.ts is not database()'s`,
+      fix: `add export { db, driver, selectDriver } from './client'; to ${INDEX_FILE} and drop db from its '@ultimat3/db' re-export`,
+      docs: ERROR_DOCS_URL,
+      at: INDEX_FILE,
+    },
+  ];
+}
+
+/**
+ * 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.
+ *
+ * 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
+ * an import nobody wrote: `packages/db` depending on the app, behind a finding that said nothing
+ * was registered.
+ *
+ * And the edge from the db package to the app is declared only for the import that needs it. The
+ * handle imports each entity from the web workspace, so that edge is real exactly when the handle
+ * this run leaves names that workspace; the other one — the app's `repo.ts` importing the handle —
+ * is every entity's.
+ */
+export async function registerGeneratedEntities(
+  root: string,
+  written: readonly string[],
+  dbModule: string | undefined,
+): Promise<HandleRegistration> {
+  const web = await readWorkspace(root, WEB_WORKSPACE);
+  const module = dbModule ?? PLACEHOLDER_DB_MODULE;
+  const webModule = web?.name ?? webModuleOf(module);
+  const entries = await entriesFor(root, 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 { source, missing } =
+    before === undefined
+      ? { source: dbClientSource(entries), missing: [] }
+      : insertHandleEntries(before, entries);
+  if (missing.length > 0) {
+    // Refused: nothing this registrar would have written is written.
+    return {
+      edited: [],
+      findings: missing.map((entry) =>
+        handleUnregisteredFinding(entry, 'passes database() no "const <set> = { … }" to add to'),
+      ),
+    };
+  }
+  if (source !== before) planned.push({ path: HANDLE_FILE, contents: source });
+  const findings: Finding[] = [];
+  if (dbModule === undefined) {
+    findings.push({
+      code: 'X_DB_HANDLE_UNREGISTERED',
+      cause: `${DB_WORKSPACE}/package.json supplies no "name", so the generated repo.ts imports the placeholder ${PLACEHOLDER_DB_MODULE}`,
+      fix: `add "name": "@<app>/db" to ${DB_WORKSPACE}/package.json, then re-run this command with --force`,
+      docs: ERROR_DOCS_URL,
+      at: `${DB_WORKSPACE}/package.json`,
+    });
+  } else findings.push(...(await indexFindings(root, 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);
+    if (manifest !== undefined) planned.push(manifest);
+  }
+  for (const edit of planned) await Bun.write(containedPath(root, edit.path), edit.contents);
+  return { edited: planned.map((edit) => edit.path), findings };
+}

package/src/i18n-registration.ts

@@ -18,6 +18,7 @@ import {
   pluralVariantsOf,
   registeredLocales,
 } from '@ultimat3/i18n';
+import { mountedAdminKeys } from './admin-catalog-keys';
 import { loadApp } from './app-load';
 import type { DuplicateProbe } from './duplicate-packages';
 import { duplicateCause, duplicateFinding, findDuplicateInstalls } from './duplicate-packages';
@@ -50,6 +51,8 @@ export interface RegistrationInput {
   readonly load?: AppLoader;
   /** The duplicate-install probe; `findDuplicateInstalls` is the production value. */
   readonly duplicates?: DuplicateProbe;
+  /** Keys a mounted admin derives, read after the load; `mountedAdminKeys` is the production value. */
+  readonly adminKeys?: () => Promise<readonly string[]>;
 }
 
 export interface RegistrationReport {
@@ -126,6 +129,18 @@ export async function checkRegistration(input: RegistrationInput): Promise<Regis
     }
   }
 
+  // A key `defineAdmin` derives is spelled in no source file, so the source audit cannot see it.
+  // Judged against the REGISTRY — the framework's base layer answers `admin.group.data` in `en` —
+  // and only for a locale that registered: an unregistered one is already a finding above.
+  const unregisteredSet = new Set(gaps.map((gap) => gap.locale));
+  const adminKeys = await (input.adminKeys ?? mountedAdminKeys)();
+  for (const locale of Object.keys(input.catalogs)
+    .filter((tag) => !unregisteredSet.has(tag))
+    .sort()) {
+    const missing = unanswered(catalogFor(locale), adminKeys);
+    if (missing.length > 0) findings.push(adminKeysFinding(locale, missing));
+  }
+
   return {
     ok: findings.length === 0,
     // The load's own findings ride along ONLY when something is unregistered, and that condition is
@@ -140,6 +155,27 @@ export async function checkRegistration(input: RegistrationInput): Promise<Regis
   };
 }
 
+/** Keys the catalog does not define, or defines with a placeholder. Labels are never plurals. */
+const unanswered = (catalog: Catalog, keys: readonly string[]): readonly string[] =>
+  keys.filter((key) => !Object.hasOwn(catalog, key) || isLoudMiss(catalog[key]));
+
+/**
+ * `X_CATALOG_MISSING_KEYS` — the same fact, a catalog without keys it is asked for — with the
+ * cause naming who asks and a fix that is an EDIT: `x i18n sync`, the code's own fix, seeds the
+ * keys SOURCE uses and cannot know these.
+ */
+function adminKeysFinding(locale: Locale, missing: readonly string[]): Finding {
+  const path = catalogPath(locale);
+  const shown = missing.slice(0, 12).map((key) => `"${key}"`);
+  const more = missing.length > shown.length ? `, +${missing.length - shown.length} more` : '';
+  return {
+    ...findingFrom(catalogMissingKeys(locale, missing)),
+    cause: `${path} is missing ${missing.length} key(s) the mounted admin renders (defineAdmin derives them, so no source file names one): ${shown.join(', ')}${more}`,
+    fix: `add to ${path}, each with its real label: ${shown.join(', ')}${more} — then x i18n check --json`,
+    at: path,
+  };
+}
+
 /**
  * `packages/i18n/src/index.ts` as text, or `undefined` where the app has no i18n package. Read
  * here and nowhere lower down: `@ultimat3/i18n` states that it never reads a file, and the CLI is

package/src/image-prepare.ts

@@ -1,14 +1,57 @@
-// What `x build --target docker` does before `docker build`: stamp the image with the manifest's
-// build id and write the island chunks it will serve (`island-store.ts`), so a container boot
-// neither re-derives the one nor rebuilds the other.
+// The two halves of an image build that are this framework's. On the host, `x build --target
+// docker` stamps the image with the manifest's build id. INSIDE the image build, `x build --target
+// prebuilt` writes what every web pod would otherwise make on every boot: the island chunks and
+// the compiled stylesheets (`serve-prebuilt-paths.ts` names the store and why it is where it is).
 
+// why: Bun ships no recursive remove; a previous store must not survive beside the new one.
+import { rm } from 'node:fs/promises';
+// why: Bun ships no path-join primitive.
+import { join } from 'node:path';
+import { sassCompilations, setSassCacheDir } from '@ultimat3/render/server';
+import { scanAppModules } from './app-load';
 import { appManifest } from './app-manifest';
 import { buildIslands } from './island-bundle';
 import { writeIslandStore } from './island-store';
+import type { Finding } from './output';
+import { PREBUILT_DIR, PREBUILT_SASS_DIR } from './serve-prebuilt-paths';
 
-/** Writes `.x/islands/` and answers the build id the image is stamped with. */
-export async function prepareImage(root: string): Promise<string> {
-  const { manifest } = await appManifest(root);
-  await writeIslandStore(root, await buildIslands(root));
-  return manifest.buildId;
+/** The build id `docker build` is handed as `--build-arg BUILD_ID=…`. */
+export async function imageBuildId(root: string): Promise<string> {
+  return (await appManifest(root)).manifest.buildId;
+}
+
+export interface PrebuiltImage {
+  /** App-root-relative, POSIX. */
+  readonly dir: string;
+  /** Island chunks written, shared chunks included. */
+  readonly islands: number;
+  /** Stylesheets compiled into the store. */
+  readonly stylesheets: number;
+  /** A module that would not import: its stylesheets are not in the store. */
+  readonly findings: readonly Finding[];
+}
+
+/**
+ * Where it runs is the design. The store is valid for one Bun, one framework version and one set
+ * of absolute paths — a chunk is verified against the runtime that built it, and a Sass entry is
+ * keyed by the sheet's path — so it is written by the image's own Bun, at the image's own
+ * `WORKDIR`, after the source is in place. Built on a laptop and copied in, it was a store for a
+ * different runtime; and under `.x/` it was dropped by the ignore file before that mattered.
+ *
+ * The app is imported the way the web role imports it (`scanAppModules`, every module), because
+ * importing a page is what compiles its stylesheet: what this scan compiles is what a pod reads.
+ */
+export async function prebuildImage(root: string): Promise<PrebuiltImage> {
+  await rm(join(root, PREBUILT_DIR), { recursive: true, force: true });
+  setSassCacheDir(join(root, PREBUILT_SASS_DIR));
+  const compiled = sassCompilations();
+  const scan = await scanAppModules(root, { track: false });
+  const bundle = await buildIslands(root);
+  await writeIslandStore(root, bundle);
+  return {
+    dir: PREBUILT_DIR,
+    islands: bundle.chunks.length + bundle.shared.length,
+    stylesheets: sassCompilations() - compiled,
+    findings: scan.findings,
+  };
 }

package/src/import-closure.ts

@@ -0,0 +1,165 @@
+// The modules a set of entry files can EXECUTE, followed name by name through barrels. A package
+// barrel re-exports its whole surface by name (the house forbids `export *`), so a closure taken
+// module by module reaches every server file of every package an island touches — `@ultimat3/action`'s
+// barrel reaches `http.ts` — while a bundler with honest `sideEffects` keeps only the modules the
+// imported NAMES live in. This follows the names, which is what makes "browser-reachable" a
+// question with a useful answer instead of "everything".
+//
+// Pure over an injected reader, so a test's fixture tree is a Map rather than files on disk.
+
+import { stripComments } from '@ultimat3/core';
+
+/** What a module asks of another: named bindings, or the whole module (`*`). */
+export type Wanted = '*' | ReadonlySet<string>;
+
+export interface ModuleShape {
+  /** `import … from`, `import('x')` — followed only when this module's body runs. */
+  readonly imports: readonly { readonly spec: string; readonly names: Wanted }[];
+  /** `export { local as exported } from 'x'` — followed only for the names somebody wants. */
+  readonly reexports: readonly {
+    readonly spec: string;
+    readonly map: ReadonlyMap<string, string>;
+  }[];
+  /** `export * from 'x'` — searched for a wanted name this module does not name itself. */
+  readonly stars: readonly string[];
+  /** `import 'x'` — runs whenever this module is touched at all, which is what a barrel's is for. */
+  readonly effects: readonly string[];
+}
+
+export interface ClosureHost {
+  /** The file's text, or `undefined` when there is no such file. Paths are root-relative POSIX. */
+  read(path: string): string | undefined;
+  /**
+   * A bare specifier's file (`@ultimat3/core` → `packages/core/src/index.ts`), or `undefined` —
+   * which ENDS the walk there: an installed package is past the boundary this closure reads.
+   */
+  alias(spec: string, from: string): string | undefined;
+}
+
+const IMPORT_FROM = /\bimport\s+(?!type\s)([^;'"]*?)\s*from\s*(['"])([^'"]+)\2/g;
+const IMPORT_BARE = /\bimport\s*(['"])([^'"]+)\1/g;
+const IMPORT_DYNAMIC = /\bimport\s*\(\s*(['"])([^'"]+)\1\s*\)/g;
+const EXPORT_FROM = /\bexport\s+(?!type\s)\{([^}]*)\}\s*from\s*(['"])([^'"]+)\2/g;
+const EXPORT_STAR = /\bexport\s+\*\s*(?:as\s+[\w$]+\s*)?from\s*(['"])([^'"]+)\1/g;
+
+/** `a, type b, c as d` → the value names, `type` members dropped. */
+const members = (list: string): readonly (readonly [string, string])[] =>
+  list
+    .split(',')
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0 && !part.startsWith('type '))
+    .map((part) => {
+      const [local = part, exported = local] = part.split(/\s+as\s+/);
+      return [local.trim(), exported.trim()] as const;
+    });
+
+/** The names an import clause binds: `default`, the braced members, or `*` for a namespace. */
+function clauseNames(clause: string): Wanted {
+  if (/\*\s*as\s/.test(clause)) return '*';
+  const names = new Set<string>();
+  const braced = /\{([^}]*)\}/.exec(clause);
+  for (const [local] of members(braced?.[1] ?? '')) names.add(local);
+  const head = clause
+    .replace(/\{[^}]*\}/, '')
+    .replace(/,/g, ' ')
+    .trim();
+  if (head.length > 0) names.add('default');
+  return names;
+}
+
+export function parseModule(source: string): ModuleShape {
+  const code = stripComments(source);
+  const imports: { spec: string; names: Wanted }[] = [];
+  for (const found of code.matchAll(IMPORT_FROM)) {
+    const names = clauseNames(found[1] ?? '');
+    // `import type { A }` is caught above; `import { type A }` alone binds nothing at runtime.
+    if (names !== '*' && names.size === 0) continue;
+    imports.push({ spec: found[3] ?? '', names });
+  }
+  const effects = [...code.matchAll(IMPORT_BARE)].map((found) => found[2] ?? '');
+  for (const found of code.matchAll(IMPORT_DYNAMIC)) {
+    imports.push({ spec: found[2] ?? '', names: '*' });
+  }
+  const reexports = [...code.matchAll(EXPORT_FROM)].map((found) => ({
+    spec: found[3] ?? '',
+    map: new Map(members(found[1] ?? '').map(([local, exported]) => [exported, local])),
+  }));
+  const stars = [...code.matchAll(EXPORT_STAR)].map((found) => found[2] ?? '');
+  return { imports, reexports, stars, effects };
+}
+
+const CANDIDATES = ['', '.ts', '.tsx', '/index.ts', '/index.tsx'];
+
+/** A relative specifier against the importing file, extension-less as TypeScript writes it. */
+function resolveRelative(host: ClosureHost, from: string, spec: string): string | undefined {
+  const base = from.split('/').slice(0, -1);
+  for (const part of spec.split('/')) {
+    if (part === '.' || part === '') continue;
+    if (part === '..') base.pop();
+    else base.push(part);
+  }
+  const joined = base.join('/').replace(/\.js$/, '');
+  for (const suffix of CANDIDATES) {
+    const path = `${joined}${suffix}`;
+    if (/\.tsx?$/.test(path) && host.read(path) !== undefined) return path;
+  }
+  return undefined;
+}
+
+export function resolveSpec(host: ClosureHost, from: string, spec: string): string | undefined {
+  return spec.startsWith('.') ? resolveRelative(host, from, spec) : host.alias(spec, from);
+}
+
+/**
+ * Every module whose BODY an entry set can run. A module reached only for names it re-exports is
+ * passed through, not included: its own statements are the re-export lines and nothing else.
+ */
+export function importClosure(host: ClosureHost, entries: readonly string[]): readonly string[] {
+  const shapes = new Map<string, ModuleShape>();
+  const bodies = new Set<string>();
+  const asked = new Map<string, Set<string>>();
+  const queue: { path: string; names: Wanted }[] = entries.map((path) => ({ path, names: '*' }));
+
+  const shapeOf = (path: string): ModuleShape | undefined => {
+    const known = shapes.get(path);
+    if (known !== undefined) return known;
+    const source = host.read(path);
+    if (source === undefined) return undefined;
+    const shape = parseModule(source);
+    shapes.set(path, shape);
+    return shape;
+  };
+  const follow = (from: string, spec: string, names: Wanted): void => {
+    const path = resolveSpec(host, from, spec);
+    if (path !== undefined) queue.push({ path, names });
+  };
+
+  for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
+    const { path, names } = next;
+    const shape = shapeOf(path);
+    if (shape === undefined) continue;
+    let needsBody = names === '*';
+    const seen = asked.get(path) ?? new Set<string>();
+    if (!asked.has(path)) for (const effect of shape.effects) follow(path, effect, '*');
+    asked.set(path, seen);
+    for (const name of names === '*' ? [] : names) {
+      if (seen.has(name)) continue;
+      seen.add(name);
+      const source = shape.reexports.find((entry) => entry.map.has(name));
+      if (source !== undefined) {
+        follow(path, source.spec, new Set([source.map.get(name) ?? name]));
+        continue;
+      }
+      needsBody = true;
+      for (const star of shape.stars) follow(path, star, new Set([name]));
+    }
+    if (names === '*') {
+      for (const entry of shape.reexports) follow(path, entry.spec, new Set(entry.map.values()));
+      for (const star of shape.stars) follow(path, star, '*');
+    }
+    if (!needsBody || bodies.has(path)) continue;
+    bodies.add(path);
+    for (const entry of shape.imports) follow(path, entry.spec, entry.names);
+  }
+  return [...bodies].sort();
+}

package/src/index.ts

@@ -8,11 +8,10 @@
 import './error-codes';
 
 /** The app's own API over HTTP — the one table `x dev` and a container both mount. */
-export { apiRoutes } from './api-routes';
+export { apiMountRoutes, apiRoutes } from './api-routes';
 export type { SourceFile } from './app-boundaries';
 export {
   appImportGraph,
-  checkAppBoundaries,
   readAppSources,
   resolveSpecifier,
   scanRuntimeImports,
@@ -46,6 +45,11 @@ export type { BranchRow } from './db-branch';
 export { BRANCH_SUBCOMMANDS, branchDatabaseName, branchNameOf } from './db-branch';
 export type { GeneratedFiles } from './db-generate';
 export { generateAppMigration } from './db-generate';
+// The schema dump's two verbs for a caller that holds an app root and no command context —
+// `scripts/schema-dumps.ts` regenerates and checks every tracked app's through them.
+export { SCHEMA_DUMP_DIR } from './db-schema-dump';
+export type { SchemaDumpRefresh } from './db-schema-refresh';
+export { refreshSchemaDump } from './db-schema-refresh';
 export { QuerySubscribesUnknownError, replicaIdentityTables } from './db-subscribes';
 export { dispatch } from './dispatch';
 export { checkSourceDrift, reconcileSchemaHash, writeSchemaHash } from './drift';
@@ -99,6 +103,10 @@ export { checkFlagReads } from './flag-reads';
 // The framework's own tables, as data. Exported so `scripts/` can read the applier's list without
 // re-deriving it — the shape a ratchet over declared-but-never-applied DDL needs.
 export { FRAMEWORK_SCHEMA } from './framework-schema';
+// What a guard's `check(root, sources)` is handed: the run's one read of the app. Types an app's
+// `guards/*.ts` names, and the constructor a test of one needs.
+export type { GuardFile, GuardSources, GuardStylesheet } from './guard-sources';
+export { guardSources } from './guard-sources';
 export type { Guard } from './guards';
 export { findingProblem, guardFindings, guardPaths } from './guards';
 export { ICON_BASE_PATH, ICON_SOURCE } from './icon-assets';
@@ -134,6 +142,7 @@ export type { RunningServices } from './runtime-services';
 export { startServices } from './runtime-services';
 // The drift a hash cannot see, and the composition both the gate step and `x doctor` read.
 export { checkMigrationDrift, checkSnapshotDrift } from './schema-drift';
+export { checkSchemaDump } from './schema-dump-drift';
 export { FrameworkSchemaFailedError } from './schema-errors';
 export type { MigratedApp, ServeOptions } from './serve';
 export {