@ultimat3/cli 22.15.0 → 23.0.0

package/src/serve-web.ts

@@ -0,0 +1,164 @@
+// What only the web role serves: its islands, its documents and every route beside them. A file
+// of its own so the roles that render nothing never import it — `serve-boot.ts` loads it with
+// `await import()` for `ROLE=web` alone, and `serve-graph.test.ts` pins what every other role is
+// spared: render's server half, the PWA, SEO, MCP and island subsystems.
+
+import type { Route } from '@ultimat3/http';
+import { describeRoutes } from '@ultimat3/render';
+import { createIsrController } from '@ultimat3/render/server';
+import { apiMountRoutes, apiRoutes, pagePostRoutes } from './api-routes';
+import { loadSignInPath } from './app-auth';
+import { mountAppMcp } from './app-mcp';
+import { errorPageStyleSources } from './error-page-csp';
+import { islandRoutes } from './island-routes';
+import type { LoadedIslands } from './island-store';
+import { loadOrBuildIslands } from './island-store';
+import { loadNavigation, pageNavigation } from './page-navigation';
+import { loadSpeculation, pageSpeculation } from './page-speculation';
+import { pageSync } from './page-sync';
+import { loadPwaArtifacts } from './pwa-artifacts';
+import { adminMountRoutes } from './runtime-admin';
+import { assetRoutes } from './runtime-assets';
+import { appRoutes } from './runtime-render';
+import type { RunningServices } from './runtime-services';
+import { servedStorage, storageRoutes } from './runtime-storage';
+import { seoRoutes } from './seo-routes';
+import type { ServeOptions } from './serve-types';
+import { loadSiteSettings, publicOrigin } from './site-config';
+import { styleBundle } from './style-bundle';
+import { styleRoutes } from './style-routes';
+import { serviceWorkerArtifacts } from './sw-artifacts';
+import { serviceWorkerRoutes } from './sw-routes';
+import { loadThemeMode, themeBoot } from './theme-boot';
+
+/** Everything `startRoles` is handed that only a process serving documents has. */
+export interface WebSurface {
+  readonly routes: readonly Route[];
+  /** The theme boot and the speculation rules: the two inline bodies every document may carry. */
+  readonly inlineScripts: readonly string[];
+  /** The app's own error pages' `<style>` bodies, which the enforced policy must admit. */
+  readonly inlineStyles: readonly string[];
+  /** Where a browser that opened a guarded page is sent — the declaration `x dev` reads. */
+  readonly signInPath: string | null;
+  /** Present when this boot built the islands itself: how many chunks, and why not the store. */
+  readonly islandsBuilt?: LoadedIslands['built'];
+}
+
+export async function webSurface(
+  options: ServeOptions,
+  runtime: RunningServices,
+  buildId: string,
+): Promise<WebSurface> {
+  // Read from the store the image build wrote and VERIFIED against this app and this runtime
+  // (`island-store.ts`); built here only when there is no store to trust, which is correct and
+  // slower — the reason travels back to the boot, which reports it.
+  const { bundle: islands, built: islandsBuilt } = await loadOrBuildIslands(options.root);
+  // The same two strings `x dev` resolves, from the same reader: a `<link rel="manifest">` served
+  // on a laptop and absent in the image is exactly the dev/prod difference this file exists to
+  // prevent, and it is the one an operator cannot see without installing the app.
+  const pwa = await loadPwaArtifacts(options.root);
+  const theme = themeBoot(await loadThemeMode(options.root));
+  // `site.origin` and `seo.robots.disallow`: the absolute URLs every document and the sitemap carry.
+  const site = await loadSiteSettings(options.root);
+  const origin = publicOrigin(options.env, site);
+  // The page's sync target and its scripts — the same call `x dev` makes, so the two cannot differ.
+  // Before the service worker, which precaches those scripts.
+  const sync = await pageSync(options.root, options.env, buildId, runtime.realtime);
+  // The client router, when a surface opted in (`navigation.client`) — the same call in both boots.
+  const declared = await loadNavigation(options.root);
+  const navigation = await pageNavigation(options.root, declared, buildId);
+  // The browser's own prefetch, for the documents that carry no router (`navigation.speculation`).
+  const speculation = pageSpeculation({
+    config: await loadSpeculation(options.root),
+    client: declared.surfaces,
+  });
+  // The worker, from the SAME route table this process is about to serve — `describeRoutes()` is
+  // the one projection `x.manifest.json`, `/_x`, the sitemap and `sw.js` are all built from, so a
+  // route added here cannot be missing from the precache manifest.
+  const serviceWorker =
+    pwa === undefined
+      ? undefined
+      : serviceWorkerArtifacts({
+          pwa,
+          buildId,
+          routes: describeRoutes(),
+          islands,
+          styles: styleBundle(),
+          scripts: [
+            ...sync.scripts,
+            ...(navigation.script === undefined ? [] : [navigation.script]),
+          ],
+        });
+  // The app's own MCP endpoint, through the same call `x dev` makes — see `app-mcp.ts`.
+  const mcpMount = await mountAppMcp(options.root);
+  // The app's own disks when it declared any (`defineStorage` in an app module), else this boot's.
+  const served = servedStorage(runtime.storage);
+  const routes: readonly Route[] = [
+    ...apiRoutes(),
+    // The bearer doors onto a cut of the same routes (`defineApi({ http: { mounts } })`), counted
+    // on the store this boot's limiter uses, so one token's allowance is one number fleet-wide.
+    ...apiMountRoutes(options.runtime?.rateLimitStore ?? runtime.rateLimitStore),
+    ...mcpMount.routes,
+    // The app's own plain routes (`apps/<app>/runtime.ts` `routes`), before any page can shadow one.
+    ...(options.runtime?.routes ?? []),
+    ...(serviceWorker === undefined ? [] : serviceWorkerRoutes(serviceWorker)),
+    ...assetRoutes({
+      root: options.root,
+      storage: served,
+      ...(options.runtime?.images === undefined ? {} : { images: options.runtime.images }),
+      ...(pwa === undefined ? {} : { pwa }),
+    }),
+    ...storageRoutes({ storage: served }),
+    ...islandRoutes(() => islands),
+    // The surface stylesheets the documents link. Built from the registry the `loadApp` above
+    // filled, so this process serves exactly the CSS it renders against.
+    ...styleRoutes(() => styleBundle()),
+    // `robots.txt` and `sitemap.xml`, the same two files the static export writes (`site-seo.ts`).
+    ...seoRoutes({ env: options.env, site, root: options.root }),
+    // The page's one socket: its worker script, served beside the islands for their reason.
+    ...sync.routes,
+    ...navigation.routes,
+    // A page's `POST`, bound to an action (`defineRoute({ post })`) — beside the page's `GET`.
+    ...pagePostRoutes(),
+    // The app's generated admin, when it declared one (`defineAdmin`): every screen under its base
+    // path, served through the same document builder as the pages below. Nothing for an app with
+    // no admin — the registry is asked, the package is not imported.
+    ...adminMountRoutes({
+      buildId: buildId,
+      themeHead: theme.head,
+      ...(origin === undefined ? {} : { origin }),
+    }),
+    ...appRoutes({
+      buildId,
+      resolveIsland: (file) => islands.resolverFor(file),
+      ...(sync.head === undefined ? {} : { sync: sync.head }),
+      persisted: sync.persisted,
+      ...(navigation.head === undefined ? {} : { navigation: navigation.head }),
+      themeHead: theme.head,
+      ...(speculation === undefined ? {} : { speculationHead: speculation.head }),
+      // A `static` page is the same bytes for every request of this process: rendered once.
+      memoStatic: true,
+      ...(origin === undefined ? {} : { origin }),
+      ...(pwa === undefined
+        ? {}
+        : { pwaHead: (locale: string) => pwa.headFor(locale) + (serviceWorker?.head ?? '') }),
+      // Only when a store was supplied. `createIsrController` defaults to a per-process memory
+      // store, so twelve replicas hold twelve of them and a purge tag regenerates one twelfth of
+      // the fleet while the other eleven keep serving the page it just invalidated.
+      ...(options.runtime?.isrStore === undefined
+        ? {}
+        : { isr: createIsrController({ buildId, store: options.runtime.isrStore }) }),
+    }),
+  ];
+  return {
+    routes,
+    inlineScripts: [theme.cspSource, ...(speculation === undefined ? [] : [speculation.cspSource])],
+    // The enforced policy this process sends must admit the app's own error pages' `<style>` and
+    // the theme boot the documents carry; `x dev` is report-only, so only here was it a blank page.
+    inlineStyles: await errorPageStyleSources(options.root),
+    // Same declaration `x dev` reads. Without it a container answers a browser that opened a
+    // guarded page with the problem document, rendered as raw JSON in the viewport.
+    signInPath: await loadSignInPath(options.root),
+    ...(islandsBuilt === undefined ? {} : { islandsBuilt }),
+  };
+}

package/src/serve.ts

@@ -13,8 +13,6 @@ import { startMetricsEndpoint } from './metrics-endpoint';
 import { readMigrations } from './migrations';
 import { resolveServices } from './runtime-bindings';
 import { startQueue } from './runtime-queue';
-import { startServices } from './runtime-services';
-import { bootRoles } from './serve-boot';
 import { containerBinding, metricsPortFor, portFromEnv, roleFromEnv } from './serve-env';
 import type { MigratedApp, ServedApp, ServeOptions, StartedApp } from './serve-types';
 
@@ -144,17 +142,16 @@ export async function serveApp(input: ServeOptions): Promise<ServedApp> {
   const metrics = startMetricsEndpoint({
     port: metricsPortFor(options.env, port, options.metricsPort),
     hostname: containerBinding(options.env, options.hostname).hostname,
+    role,
   });
   // Everything acquired from here down, in order, so a throw anywhere below gives it all back.
   const acquired: (() => void | Promise<void>)[] = [() => metrics.stop()];
   try {
-    const runtime = await startServices(
-      resolveServices(options.root, options.env),
-      options.env,
-      options.runtime,
-    );
-    acquired.push(() => runtime.stop());
-    return await bootRoles({ options, role, runtime, acquired, metrics });
+    // Behind `await import()`: `ROLE=migrate` runs in this module too, applies SQL files and
+    // exits, and the services and the role boot are ~240 modules it never calls
+    // (`serve-graph.test.ts` pins the count each role is left with).
+    const { bootServing } = await import('./serve-boot');
+    return await bootServing({ options, role, acquired, metrics });
   } catch (error) {
     await releaseBoot(acquired);
     throw error;

package/src/server-barrels.ts

@@ -0,0 +1,54 @@
+// A package barrel a browser must not import, and the entry it imports instead. `@ultimat3/entity`'s
+// barrel reaches the SQL renderer and `@ultimat3/db` — about a megabyte in an island — while
+// `@ultimat3/entity/record` is the browser half. DERIVED from each manifest's `exports`: a package
+// that publishes a `./record`, `./browser` or `./client` subpath has said its barrel is the server
+// half, so a new browser entry enters this rule by being published, never by being listed here.
+
+import { stripComments } from '@ultimat3/core';
+import { lineIndex } from './ts-scan';
+
+/** The subpath names that declare "this is the browser entry of the package". */
+export const BROWSER_ENTRY_SUBPATHS: ReadonlySet<string> = new Set(['record', 'browser', 'client']);
+
+/** Barrel specifier → the browser entry that replaces it, read off the published specifiers. */
+export function serverBarrels(specifiers: Iterable<string>): ReadonlyMap<string, string> {
+  const barrels = new Map<string, string>();
+  for (const spec of specifiers) {
+    const match = /^(@[\w-]+\/[\w-]+)\/([\w-]+)$/.exec(spec);
+    if (match?.[1] === undefined || !BROWSER_ENTRY_SUBPATHS.has(match[2] ?? '')) continue;
+    barrels.set(match[1], spec);
+  }
+  return barrels;
+}
+
+export interface BarrelImport {
+  readonly line: number;
+  readonly barrel: string;
+  readonly entry: string;
+}
+
+/** `import` / `export … from` / `import()` of a VALUE from the barrel. `import type` runs nothing. */
+const IMPORTS =
+  /\b(?:import|export)\s+(?!type\s)[^;'"]*?\bfrom\s*(['"])([^'"]+)\1|\bimport\s*\(\s*(['"])([^'"]+)\3\s*\)/g;
+
+export function barrelImports(
+  source: string,
+  barrels: ReadonlyMap<string, string>,
+): readonly BarrelImport[] {
+  // Most files import no barrel at all; say so before paying for a comment-stripped copy.
+  if (![...barrels.keys()].some((barrel) => source.includes(barrel))) return [];
+  const code = stripComments(source);
+  const lineAt = lineIndex(code);
+  const found: BarrelImport[] = [];
+  for (const match of code.matchAll(IMPORTS)) {
+    const spec = match[2] ?? match[4] ?? '';
+    const entry = barrels.get(spec);
+    if (entry === undefined) continue;
+    // `import { type A, type B } from …` binds nothing at runtime either.
+    const clause = /\{([^}]*)\}/.exec(match[0])?.[1];
+    const typesOnly = clause?.split(',').every((part) => /^\s*(?:type\s|$)/.test(part));
+    if (typesOnly === true) continue;
+    found.push({ line: lineAt(match.index), barrel: spec, entry });
+  }
+  return found;
+}

package/src/source-edit.ts

@@ -0,0 +1,49 @@
+// The two text edits a generator makes to a file the app owns: one keyed line added to an object
+// literal, and one import added where the formatter's sorted block would have it. Shared by the
+// registrars (`handle-registration.ts`, `admin-registration.ts`) so "in key order, expanded" means
+// one thing in both.
+
+const IDENTIFIER = '[A-Za-z_$][\\w$]*';
+
+const keyOf = (item: string): string => item.split(':')[0]?.trim() ?? '';
+
+/** Whether the object body already holds `key` — as `key: value` or as a shorthand. */
+export const holdsKey = (body: string, key: string): boolean =>
+  new RegExp(`(^|[\\s,{])${key}\\s*[:,]`).test(`${body},`);
+
+/**
+ * An object literal's body with `line` on its own row, in key order. A body the author keeps on
+ * one line is expanded — an expanded literal is the shape a formatter leaves alone at any length.
+ * `indent` is what an entry of this literal is indented by.
+ */
+export function withKeyedLine(body: string, key: string, line: string, indent: string): string {
+  if (!body.includes('\n')) {
+    const items = body
+      .split(',')
+      .map((item) => item.trim())
+      .filter((item) => item !== '');
+    const lines = [...items.map((item) => `${indent}${item},`), line].sort((a, b) =>
+      keyOf(a) < keyOf(b) ? -1 : 1,
+    );
+    return `\n${lines.join('\n')}\n${indent.slice(2)}`;
+  }
+  const lines = body.split('\n');
+  const isEntry = (text: string): boolean => new RegExp(`^\\s*${IDENTIFIER}\\s*[:,]`).test(text);
+  const after = lines.findIndex((text) => isEntry(text) && keyOf(text) > key);
+  // Past the last entry when none sorts later: the row before the closing brace's own indent.
+  lines.splice(after === -1 ? lines.length - 1 : after, 0, line);
+  return lines.join('\n');
+}
+
+/** `source` with `line` imported, placed where a sorted import block would have it. */
+export function withSortedImport(source: string, line: string, specifier: string): string {
+  if (source.includes(`from '${specifier}'`)) return source;
+  const imports = [...source.matchAll(/^import\b[^;]*?from\s+'([^']+)';\n/gm)];
+  // Packages only: a relative import is a LATER group, so it is never what this line sorts against.
+  const packages = imports.filter((match) => !(match[1] ?? '').startsWith('.'));
+  const later = packages.find((match) => (match[1] ?? '') > specifier);
+  const last = packages.at(-1);
+  const first = imports[0]?.index ?? 0;
+  const at = later?.index ?? (last === undefined ? first : last.index + last[0].length);
+  return `${source.slice(0, at)}${line}\n${source.slice(at)}`;
+}

package/src/tasks-facts.ts

@@ -26,8 +26,11 @@ const pad2 = (value: number): string => String(value).padStart(2, '0');
  * UTC-`Z` only, `isoDateInZone` is date-only, and `formatWithOffset` renders locale prose, not
  * ISO. So this composes the package's own instant→zoned-wall-clock conversion (`toZoned`) and
  * zone-label helper (`offsetLabel`) rather than a fresh `Intl.DateTimeFormat` call here.
+ *
+ * Exported for `cmd-tasks.ts`'s `last` column: the occurrence a task last fired and the one it
+ * fires next are one clock, so they are one function.
  */
-function isoInZone(ms: number, zone: string): string {
+export function isoInZone(ms: number, zone: string): string {
   const zoned = toZoned(fromEpochMs(ms), zone);
   const date = `${String(zoned.year).padStart(4, '0')}-${pad2(zoned.month)}-${pad2(zoned.day)}`;
   const time = `${pad2(zoned.hour)}:${pad2(zoned.minute)}:${pad2(zoned.second)}`;

package/src/templates/action.ts

@@ -3,9 +3,11 @@
 // job handle, an MCP tool and these tests; the generator writes the declaration and the tests.
 
 import type { FeatureTarget } from './entity';
+import { sortedImports } from './imports';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
-import { sliceExports, sliceFoundation } from './slice-foundation';
+import { PLACEHOLDER_DB_MODULE } from './scaffold-db-client';
+import { sliceExports, sliceFoundation, sliceTakesScaffoldRow } from './slice-foundation';
 import { wrapImport } from './wrap';
 
 /**
@@ -104,6 +106,10 @@ ${
 });
 `;
 
+/** The code the slice's `errors.ts` declares for a missing row. */
+const notFoundCode = (feature: NameSet): string =>
+  `X_${feature.kebab.toUpperCase().split('-').join('_')}_NOT_FOUND`;
+
 const ID = '00000000-0000-4000-8000-000000000001';
 const ORG = '00000000-0000-4000-8000-000000000002';
 const OTHER_ORG = '00000000-0000-4000-8000-000000000009';
@@ -160,20 +166,137 @@ const outsider = testActor('outsider', {
     : ''
 }`;
 
-const actionUnitTest = (
-  name: NameSet,
-  feature: NameSet,
-  isMutator: boolean,
-): string => `// ${name.camel}: its declared shape and the input it refuses. Both are answered by the declaration
-// alone, so they belong to the \`unit\` step — the contract projections are next door.
-${preamble(name, feature, isMutator, 'expect, unitTest', false)}
-${shapeTest(name, isMutator)}
+/** What the unit test may do with the slice the declaration lives in. */
+interface HandlerShape {
+  readonly isMutator: boolean;
+  /** The handler reads a row by id and throws `<Feature>NotFoundError` when there is none. */
+  readonly lookup: boolean;
+  /** The slice still takes the row `x g entity` scaffolds, so the test may store one. */
+  readonly storesRow: boolean;
+  readonly dbModule: string;
+}
+
+/**
+ * The optimistic half, run against the client store `@ultimat3/testing` ships. A twin is replayed
+ * on every rebase, so the two facts worth failing on are the row one application leaves and that a
+ * second leaves the same one — and that a row the store never held is not invented.
+ */
+const localTwinTests = (): string => `
+unitTest('the local twin marks the row pending, and a replay lands in the same place', () => {
+  const store = memoryLocalTx({ [TABLE]: { [id]: { id, title: 'before', pending: false } } });
+  target.local(store.tx, input);
+  const once = store.rows(TABLE);
+  expect(once).toEqual({ [id]: { id, title: 'a title', pending: true } });
+  // A rebase replays the queued write: twice through must equal once through.
+  target.local(store.tx, input);
+  expect(store.rows(TABLE)).toEqual(once);
+});
+
+unitTest('the local twin invents no row the store never held', () => {
+  const store = memoryLocalTx();
+  target.local(store.tx, input);
+  expect(store.rows(TABLE)).toEqual({});
+});
+`;
+
+/** The authoritative half's cases, refusal first, in the shape the slice earns. */
+const handlerTests = (feature: NameSet, shape: HandlerShape): string => {
+  const answer = shape.isMutator ? "{ id, title: 'a title' }" : '{ id }';
+  if (!shape.lookup) {
+    return `
+unitTest('an actor without the grant is refused before the handler runs', async () => {
+  const stranger = testActor('stranger', { orgId }).actor;
+  const refused = await target.as(stranger, input).catch((error: unknown) => error);
+  expect(refused).toBeUltimateError('X_FORBIDDEN');
+});
+
+unitTest('the handler answers a writer in the org', async () => {
+  expect(await target.as(writer, input)).toEqual(${answer});
+});
+`;
+  }
+  const found = shape.isMutator
+    ? "{ id: row.id, title: 'a title' }"
+    : "{ id: row.id, title: 'kept' }";
+  const call = shape.isMutator
+    ? "{ id: row.id, orgId, title: 'a title' }"
+    : '{ id: row.id, orgId }';
+  return `
+unitTest('the handler refuses an id nothing holds', async () => {
+  const refused = await target.as(writer, input).catch((error: unknown) => error);
+  expect(refused).toBeUltimateError('${notFoundCode(feature)}');
+});
+${
+  shape.storesRow
+    ? `
+unitTest('the handler answers the row it found', async () => {
+  const draft = { orgId, title: 'kept', price: { minor: 0, currency: 'USD' } };
+  const row = await runWithContext(createContext({ actor: writer }), () => repo.insert(draft));
+  const answer = await target.as(writer, ${call});
+  expect(answer).toEqual(${found});
+});
+`
+    : ''
+}`;
+};
+
+/**
+ * The unit test: the declaration's shape, the input it refuses, and the HANDLER — run through
+ * `.as()`, the one execution path, against the in-memory driver. A mutator's local twin runs
+ * against `memoryLocalTx`. The contract projections are next door, in their own suite.
+ *
+ * A row is stored only in a slice whose row this generator can spell (`sliceTakesScaffoldRow`): a
+ * slice an author reshaped has its own columns, and a test that inserted `{ title, price }` into
+ * it would be a guess about someone else's table.
+ */
+const actionUnitTest = (name: NameSet, feature: NameSet, shape: HandlerShape): string => {
+  const stores = shape.lookup && shape.storesRow;
+  const testing = [
+    ...(stores ? ['afterEach'] : []),
+    'expect',
+    ...(shape.isMutator ? ['memoryLocalTx'] : []),
+    'unitTest',
+  ].join(', ');
+  return `// ${name.camel}: its declared shape, the input it refuses, and what its handler answers — in
+// process, so all three belong to the \`unit\` step. The contract projections are next door.
+${sortedImports([
+  ...(stores ? ["import { createContext, runWithContext } from '@ultimat3/core';"] : []),
+  "import { testActor } from '@ultimat3/policy';",
+  `import { ${testing} } from '@ultimat3/testing';`,
+  ...(stores ? [`import { driver } from '${shape.dbModule}';`] : []),
+])}${stores ? "\nimport * as repo from '../repo';" : ''}
+import { ${name.camel} } from './${name.kebab}';
+
+const id = '${ID}';
+const orgId = '${ORG}';
+const input = { id, orgId${shape.isMutator ? ", title: 'a title'" : ''} };
+${shape.isMutator ? `\n// The client store's table: the entity's own, so the twin and the server row share one key.\nconst TABLE = '${feature.table}';\n` : ''}
+// Named here because every projection needs a stable name and this file does not boot the app.
+// At boot \`registerActions(await import('./actions'))\` stamps the same name onto the same
+// object, so \`${name.camel}.tool()\` works there with nothing to remember.
+const target = ${name.camel}.named('${name.camel}');
+
+// Holds the grant in the org the input names: past the policy, so what answers is the handler.
+const grant = ['${feature.kebab}:write'];
+const writer = testActor('writer', { orgId, permissions: grant }).actor;
+${
+  stores
+    ? `
+// One store per process: without this, one test's rows are the next test's fixtures.
+afterEach(() => {
+  driver.reset?.();
+});
+`
+    : ''
+}
+${shapeTest(name, shape.isMutator)}
 
 unitTest('${name.camel} rejects input that is not a uuid', async () => {
   await expect(target.input).toRejectInput({ ...input, id: 'not-a-uuid' });
   await expect(target.input).toAcceptInput(input);
 });
-`;
+${shape.isMutator ? localTwinTests() : ''}${handlerTests(feature, shape)}`;
+};
 
 const actionContractTest = (
   name: NameSet,
@@ -218,6 +341,8 @@ export interface ActionOptions extends FeatureTarget {
    * data. `x g resource` passes the entity it is writing in the same run.
    */
   readonly sliceEntity?: string;
+  /** The slice's `repo.ts` as it stands on disk, or absent alongside `sliceEntity`. */
+  readonly sliceRepo?: string;
 }
 
 export function actionFiles(rawName: string, target: ActionOptions): readonly GeneratedFile[] {
@@ -246,7 +371,15 @@ export function actionFiles(rawName: string, target: ActionOptions): readonly Ge
     // suites: the input parse is a `unit` assertion and the three projections are `contract` ones.
     // Emitted as one file, the contract half ran under `unit` and `x test contract` answered
     // X_TEST_NO_FILES; renaming that one file would have put the `unitTest` in the same bind.
-    { path: `${dir}/${name.kebab}.test.ts`, contents: actionUnitTest(name, feature, isMutator) },
+    {
+      path: `${dir}/${name.kebab}.test.ts`,
+      contents: actionUnitTest(name, feature, {
+        isMutator,
+        lookup,
+        storesRow: sliceTakesScaffoldRow(target, target.sliceEntity, target.sliceRepo),
+        dbModule: target.dbModule ?? PLACEHOLDER_DB_MODULE,
+      }),
+    },
     {
       path: `${dir}/${name.kebab}.contract.test.ts`,
       contents: actionContractTest(name, feature, isMutator),

package/src/templates/admin-catalog.ts

@@ -0,0 +1,58 @@
+// The catalog keys the admin reads for a generated entity. An entity in the app's handle IS an
+// admin screen — `defineAdmin({ entities: adminEntitiesOf(db) })` — and that screen resolves
+// `admin.<table>.title` and one `admin.<table>.field.<column>` per column. Nothing emitted them, so
+// a generated list rendered `⟦admin.widgets.field.title⟧` in every header.
+
+import { catalogJson } from './catalog-json';
+import type { FeatureTarget } from './entity';
+import { entityFiles } from './entity';
+import { catalogPath, resolveLocales } from './locales';
+import type { GeneratedFile } from './naming';
+import { kebab, names } from './naming';
+
+/** `    title: text({ max: 200 }),` — one column of the entity this same run writes. */
+const COLUMN_LINE = /^ {4}([A-Za-z_$][\w$]*): [A-Za-z_$][\w$]*\(/gm;
+
+/** `createdAt` → `Created at`, `orgId` → `Org ID`: a label a person reads, in sentence case. */
+export const columnLabel = (property: string): string => {
+  const words = kebab(property)
+    .split('-')
+    .map((word) => (word === 'id' ? 'ID' : word));
+  const [first = '', ...rest] = words;
+  return [`${first[0]?.toUpperCase() ?? ''}${first.slice(1)}`, ...rest].join(' ');
+};
+
+/**
+ * The entries, keyed exactly as `@ultimat3/admin` derives them: both read the entity's own name
+ * (`$name`, the table) and its property names. The columns come off the entity this run writes —
+ * never a second list typed here — so a column added to the template is a label added with it.
+ */
+export function adminCatalogEntries(
+  rawName: string,
+  target: FeatureTarget,
+): Readonly<Record<string, string>> {
+  const name = names(rawName);
+  const source = String(
+    entityFiles(rawName, target).find((file) => file.path.endsWith('/entity.ts'))?.contents ?? '',
+  );
+  const entries: Record<string, string> = {
+    [`admin.${name.table}.title`]: columnLabel(name.plural),
+  };
+  for (const match of source.matchAll(COLUMN_LINE)) {
+    const property = match[1] ?? '';
+    entries[`admin.${name.table}.field.${property}`] = columnLabel(property);
+  }
+  return entries;
+}
+
+/** One mergeable catalog file per locale — for `x g entity`, which has no other catalog entry. */
+export const adminCatalogFiles = (
+  rawName: string,
+  target: FeatureTarget,
+  locales: readonly string[] | undefined,
+): readonly GeneratedFile[] =>
+  resolveLocales(locales).map((locale) => ({
+    path: catalogPath(locale),
+    contents: catalogJson(adminCatalogEntries(rawName, target)),
+    merge: 'json' as const,
+  }));

package/src/templates/admin-page.ts

@@ -4,15 +4,27 @@
 // table and `guardedPage()` is the one thing that decides it. A scaffold that wrote a route
 // declaration here would hand back the unguarded second way in that seam exists to close.
 
+import { ADMIN_FILE } from '../admin-registration';
 import { catalogJson } from './catalog-json';
 import { sortedImports } from './imports';
 import { catalogPath, resolveLocales } from './locales';
 import type { GeneratedFile } from './naming';
 import { camel, kebab, pascal } from './naming';
-import { LINE_WIDTH } from './wrap';
+import { LINE_WIDTH, wrapImport } from './wrap';
 
-/** Where an admin lives when the caller does not say. `x new` scaffolds this layout. */
-export const DEFAULT_ADMIN_PAGE_DIR = 'apps/admin/src/pages';
+/** The directory `defineAdmin` is declared in — the admin's one home, inside the app scan. */
+const ADMIN_HOME = ADMIN_FILE.slice(0, ADMIN_FILE.lastIndexOf('/'));
+
+/**
+ * Where a page lands when the caller does not say: beside the declaration `x new` writes, under the
+ * directory the app scan imports. `apps/admin/src/pages` was outside it, and an admin kept there was
+ * never mounted (`X_ADMIN_UNSCANNED`).
+ */
+export const DEFAULT_ADMIN_PAGE_DIR = `${ADMIN_HOME}/pages`;
+
+/** The import a `defineAdmin` in `ADMIN_FILE` writes for a page in `dir`, when one can be derived. */
+const specifierFor = (dir: string, name: string): string =>
+  dir.startsWith(`${ADMIN_HOME}/`) ? `./${dir.slice(ADMIN_HOME.length + 1)}/${name}` : `./${name}`;
 
 export interface AdminPageOptions {
   /** The permission the page's own work needs. `admin:read` is composed in front of it. */
@@ -115,8 +127,8 @@ const pageSource = (
 // so a route declaration in this file would be a second, unguarded way in.
 //
 // Wire it in once, and add \`navGroup\` to link it in the sidebar — this file is ${dir}/${name}.tsx,
-// so the specifier is relative to wherever \`defineAdmin\` lives:
-//   import { ${declaration}Page } from './${name}';
+// so the specifier is relative to wherever \`defineAdmin\` lives (${ADMIN_FILE} in a scaffolded app):
+//   import { ${declaration}Page } from '${specifierFor(dir, name)}';
 //   defineAdmin({ …, pages: […, ${declaration}Page] })
 //
 // The permission below is declared here AND has to be decided: an authz map built from a fixed
@@ -146,11 +158,27 @@ export const ${declaration}Page: AdminCustomPage = {
 
 const pageTest = (name: string, permission: string): string => {
   const declaration = camel(name);
+  const Name = pascal(name);
+  const url = `http://localhost/admin/${name}`;
   return `// The ${name} admin page is guarded and owns no route of its own — the two facts that separate an
-// admin screen from a page, and the two an edit here is most likely to break.
+// admin screen from a page, and the two an edit here is most likely to break — and it renders
+// from the request it is handed.
+import { adminTestCtx } from '@ultimat3/admin';
 import { knownPermissions } from '@ultimat3/policy';
-import { expect, unitTest } from '@ultimat3/testing';
-import { ${declaration}Page } from './${name}';
+import { expect, renderView, unitTest } from '@ultimat3/testing';
+${wrapImport([`${Name}Page`, `${declaration}Page`], `./${name}`)}
+
+// The component, called the way the admin's frame calls it once the guard has passed: a ctx for
+// an actor holding the page's own permission, the route params, and the request URL.
+unitTest('the ${name} admin page renders', async () => {
+  const view = await renderView(${Name}Page, {
+    ctx: adminTestCtx({ granted: ['admin:read', '${permission}'] }),
+    params: {},
+    url: '${url}',
+  });
+  expect(view.html).toContain('<h1>');
+  expect(view.text).toContain('${url}');
+});
 
 // Both facts the frame reads off the declaration, so both are decidable without a request: a path
 // that is not rooted is X_ADMIN_PAGE_PATH_INVALID, and no permission at all is