@ultimat3/cli 22.15.0 → 24.0.0

package/src/generated-imports.ts

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

package/src/gh-target.ts

@@ -76,18 +76,23 @@ const PR_VIEW = t.object({ number: t.number });
  * The pull request for the current branch. gh exits non-zero when there is none, with a message
  * that names the branch — so the refusal keeps gh's own sentence and adds the remedy gh has no
  * opinion about: name the number, or open the PR.
+ *
+ * No `--repo`: gh refuses `pr view --repo <slug>` without a number, url or branch before any
+ * network call, so that argv could never succeed. The checkout-scoped form resolves the branch's
+ * tracking remote itself — the same resolution `gh repo view` gave `resolveRepo`. `repo` names the
+ * pull request in the refusal only.
  */
 export async function resolvePrNumber(host: GhHost, repo: GhRepo): Promise<number> {
   try {
-    const viewed = await ghJson(
-      host,
-      ['pr', 'view', '--repo', repo.slug, '--json', 'number'],
-      PR_VIEW,
-      { label: 'gh pr view', fix: 'x pr review --pr 241 --json' },
-    );
+    const viewed = await ghJson(host, ['pr', 'view', '--json', 'number'], PR_VIEW, {
+      label: 'gh pr view',
+      fix: 'x pr review --pr 241 --json',
+    });
     return viewed.number;
   } catch (error) {
-    if (error instanceof GhFailedError) throw new PrNotFoundError({ detail: error.cause });
+    if (error instanceof GhFailedError) {
+      throw new PrNotFoundError({ detail: `${repo.slug}: ${error.cause}` });
+    }
     throw error;
   }
 }

package/src/guard-sources.ts

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

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-audit.ts

@@ -28,13 +28,16 @@ import { CATALOG_ROOT, catalogPath } from './templates/locales';
  * glob set every text-scanning gate step already shares (`errors`, `filesize`) — a second glob
  * here would mean this command and `x verify` disagree on what "the app's source" is. Test files
  * are excluded: a fixture's `t('fixture.key')` is not a gap the shipped catalogs owe an answer to.
+ * So are `guards/`: gate tooling renders nothing, and its fix lines quote `t('…')` as an example.
  * `extractFromFiles` reads by absolute path, so its `file` label is rewritten back to the same
  * root-relative POSIX shape `app-load.ts` uses for every other CLI-reported path.
  */
+const isGuard = (file: string): boolean => file.startsWith('guards/');
+
 export async function scanSource(root: string): Promise<Extraction> {
   const files: string[] = [];
   for await (const file of eachSourceFile(root)) {
-    if (!isTest(file)) files.push(file);
+    if (!isTest(file) && !isGuard(file)) files.push(file);
   }
   const extraction = await extractFromFiles(files.map((file) => join(root, file)));
   const toRelative = (file: string): string => relative(root, file).split(sep).join('/');

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