@ultimat3/cli 22.14.0 → 23.0.0

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/static-document.ts

@@ -0,0 +1,108 @@
+// How a served process answers a `render: 'static'` page: a 304 when the browser already holds
+// these bytes, and — in the container — the document it rendered the first time, from memory.
+// A static page is one file in the export; the served process answering it must not cost a render
+// per request, nor a body per revalidation. No other mode comes through here.
+
+import type { UltimateRequest } from '@ultimat3/http';
+import { html } from '@ultimat3/http';
+import type { RenderResult, RouteEntry } from '@ultimat3/render';
+import { etagMatches } from './runtime-storage';
+
+/** A rendered static document: always a string body, never a stream. */
+export type StaticResult = RenderResult & { readonly body: string };
+
+/**
+ * The entries one process keeps. A static route has no params here and no query, so the real count
+ * is routes × locales; the cap is what a forged `Host` (part of the key when the app declares no
+ * origin) can cost — past it a page is rendered per request, as before, never refused.
+ */
+export const STATIC_MEMO_LIMIT = 1024;
+
+/**
+ * The BYTES one process keeps, the cache tiers' `maxBytes` idea: a count alone lets 1,024 rotated
+ * `Host` headers retain 1,024 whole documents, whatever each weighs. Past it, as past the count, a
+ * page is rendered per request.
+ */
+export const STATIC_MEMO_MAX_BYTES = 32 * 1024 * 1024;
+
+export interface StaticMemo {
+  get(key: string): StaticResult | undefined;
+  set(key: string, result: StaticResult): void;
+  readonly size: number;
+  /** UTF-8 bytes of the kept keys and bodies. */
+  readonly bytes: number;
+}
+
+const encoder = new TextEncoder();
+const weigh = (key: string, result: StaticResult): number =>
+  encoder.encode(key).byteLength + encoder.encode(result.body).byteLength;
+
+export function createStaticMemo(
+  limit: number = STATIC_MEMO_LIMIT,
+  maxBytes: number = STATIC_MEMO_MAX_BYTES,
+): StaticMemo {
+  const kept = new Map<string, { readonly result: StaticResult; readonly weight: number }>();
+  let bytes = 0;
+  return {
+    get: (key) => kept.get(key)?.result,
+    set(key, result) {
+      // Only a 200 is the page: a loader's 404 or 500 is an answer about one moment.
+      if (result.status !== 200) return;
+      const held = kept.get(key);
+      if (held === undefined && kept.size >= limit) return;
+      const weight = weigh(key, result);
+      // A replacement gives its old weight back first; one that no longer fits is not kept, and
+      // neither is the stale document it would have replaced.
+      const after = bytes - (held?.weight ?? 0) + weight;
+      if (after > maxBytes) {
+        if (held !== undefined) {
+          kept.delete(key);
+          bytes -= held.weight;
+        }
+        return;
+      }
+      kept.set(key, { result, weight });
+      bytes = after;
+    },
+    get size() {
+      return kept.size;
+    },
+    get bytes() {
+      return bytes;
+    },
+  };
+}
+
+/**
+ * The key a request's document is kept under, or `undefined` when it must be rendered: a query
+ * string is part of what `meta` reads (`data.url`), and a dynamic segment is an unbounded set an
+ * anonymous visitor chooses. The origin is in the key because canonical and `og:url` are absolute
+ * against the request's own when the app declares none.
+ */
+export function staticMemoKey(
+  entry: Pick<RouteEntry, 'config' | 'pattern'>,
+  url: URL,
+  locale: string,
+): string | undefined {
+  if (entry.config.render !== 'static') return undefined;
+  if (entry.pattern.keys.length > 0 || url.search !== '') return undefined;
+  return `${locale}\n${url.origin}${url.pathname}`;
+}
+
+/**
+ * The document, or a bodiless 304 when `If-None-Match` names its ETag. The 304 repeats the
+ * validators and the cache posture (RFC 9110 §15.4.5) and drops `content-type`: it has no content.
+ * Only a 200 revalidates — a 404 rendered under `static` is sent whole.
+ */
+export function staticResponse(request: UltimateRequest, result: StaticResult): Response {
+  const etag = result.headers['etag'];
+  if (
+    result.status === 200 &&
+    etag !== undefined &&
+    etagMatches(request.header('if-none-match'), etag)
+  ) {
+    const { 'content-type': _dropped, ...headers } = result.headers;
+    return new Response(null, { status: 304, headers });
+  }
+  return html(result.body, { status: result.status, headers: result.headers });
+}

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

package/src/templates/admin.ts

@@ -1,50 +1,90 @@
-// `x g resource <name> --admin` — the per-entity half of the admin screen. `defineAdmin()` derives
-// list/detail/create/edit from the entity itself; this file is only the override an app author
-// would otherwise hand-write — title, list columns, page size. Wiring it in is one line in
-// `apps/admin/src/index.ts` (`entities: [..., ${feature}]`, `resources: { ${feature}: ... }`),
-// the same "define once, register once" shape as `packages/db/src/schema.ts`.
+// `x g resource <name> --admin` — the per-entity admin override. `defineAdmin()` already serves
+// list/detail/create/edit for the entity with nothing written; this file is only what an app
+// author would otherwise hand-write on top — the list columns, a page size, and from there scopes,
+// a row scope and computed columns. `admin-registration.ts` lists it under `resources:` in the
+// app's `defineAdmin()` call in the same run, so nothing is left to wire.
 
 import type { FeatureTarget } from './entity';
+import { entityFiles } from './entity';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
+import { wrapList } from './wrap';
+
+/** `    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;
+const TENANT = /^\s*tenant: '([^']+)'/m;
+
+/**
+ * The list columns, read off the ENTITY the generator writes for this name — never a second list
+ * typed here. It used to be `['id', 'title', 'createdAt']`, which named whatever the entity
+ * template held on the day it was written: a column renamed there became
+ * `X_ADMIN_FIELD_UNSUPPORTED` on the first request to an app that had just been generated.
+ *
+ * The key and the tenant column are left out: the list's first column already links the row by
+ * its id, and every row an operator sees carries the same tenant.
+ */
+export function adminListFields(rawName: string, target: FeatureTarget): readonly string[] {
+  const source = String(
+    entityFiles(rawName, target).find((file) => file.path.endsWith('/entity.ts'))?.contents ?? '',
+  );
+  const tenant = TENANT.exec(source)?.[1];
+  return [...source.matchAll(COLUMN_LINE)]
+    .filter((line) => !line[0].includes('.primaryKey()') && line[1] !== tenant)
+    .map((line) => line[1] ?? '');
+}
 
 const resourceSource = (
   feature: NameSet,
-): string => `// Admin override for ${feature.pluralKebab}. Everything not set here — fields, operations,
-// detail layout — is derived from the entity. Wire it in once, importing ${feature.camel}AdminResource
-// through this app's own tsconfig path alias for apps/web/app/${feature.kebab}/admin/resource:
-//   defineAdmin({ entities: [..., ${feature.camel}], resources: { ${feature.table}: ${feature.camel}AdminResource } })
+  listFields: readonly string[],
+): string => `// Admin override for ${feature.pluralKebab}. The admin already serves /admin/${feature.table} with nothing written
+// here — its fields, filters, operations and forms are derived from the entity. This file is what
+// the entity cannot say, listed under \`resources: { ${feature.table}: … }\` in the app's defineAdmin().
 
 import type { AdminResourceOptions, AdminRow } from '@ultimat3/admin';
 
 export const ${feature.camel}AdminResource: AdminResourceOptions<AdminRow> = {
-  titleKey: 'admin.${feature.kebab}.title',
-  listFields: ['id', 'title', 'createdAt'],
+  // Columns of the entity, in its own order. A name that is not one is X_ADMIN_FIELD_UNSUPPORTED
+  // at boot — delete the line to let the admin pick them.
+${wrapList(
+  '  ',
+  'listFields: [',
+  listFields.map((field) => `'${field}'`),
+  '],',
+)}
   pageSize: 25,
 };
 `;
 
 const resourceTest = (
   feature: NameSet,
-): string => `// The ${feature.kebab} admin override says what the entity cannot derive: a title key, the list
-// columns, a bounded page size. Everything unset here is derived, and needs no test.
+): string => `// The ${feature.kebab} admin override says what the entity cannot derive: the list columns and a
+// bounded page size. The columns it lists must BE columns — a name that is not one is
+// X_ADMIN_FIELD_UNSUPPORTED on the first request.
 import { expect, unitTest } from '@ultimat3/testing';
+import { ${feature.camel} } from '../entity';
 import { ${feature.camel}AdminResource } from './resource';
 
 const resource = ${feature.camel}AdminResource;
 
-unitTest('${feature.camel}AdminResource sets a title key and list fields', () => {
-  expect(resource.titleKey).toBe('admin.${feature.kebab}.title');
-  expect(resource.listFields?.length).toBeGreaterThan(0);
+unitTest('${feature.camel}AdminResource sets a bounded page size', () => {
   expect(resource.pageSize).toBeGreaterThan(0);
 });
+
+unitTest('every list field is a column of the ${feature.camel} entity', () => {
+  const columns = Object.keys(${feature.camel}.$columns);
+  expect(resource.listFields?.length).toBeGreaterThan(0);
+  for (const field of resource.listFields ?? []) expect(columns).toContain(field);
+});
 `;
 
 export function adminFiles(rawName: string, target: FeatureTarget): readonly GeneratedFile[] {
   const feature = names(rawName.length > 0 ? rawName : target.feature);
   const dir = `${target.surfaceDir}/${target.feature}/admin`;
   return [
-    { path: `${dir}/resource.ts`, contents: resourceSource(feature) },
+    {
+      path: `${dir}/resource.ts`,
+      contents: resourceSource(feature, adminListFields(rawName, target)),
+    },
     { path: `${dir}/resource.test.ts`, contents: resourceTest(feature) },
   ];
 }