@ultimat3/cli 22.15.0 → 24.0.0

package/src/templates/scaffold-container.ts

@@ -7,6 +7,7 @@
 // buildpack, a Render blueprint or a fly.toml would be the primitive that never ships.
 
 import { SECRETS_KEY_FILE } from '@ultimat3/core';
+import { PREBUILT_COMMAND } from '../serve-prebuilt-paths';
 import type { GeneratedFile, NameSet } from './naming';
 import { composeProdFile, PROD_ENV_FILE } from './scaffold-container-compose';
 import { helmFiles } from './scaffold-helm';
@@ -29,14 +30,16 @@ const dockerfile = (
 # install refuses. \`bunfig.toml\` survives because its \`[install]\` section is input to the install,
 # and so does a \`.tgz\`: a \`file:\` tarball dependency (a vendored or private package) is resolved
 # from the file itself, and without it the frozen install cannot find what the lockfile names.
-FROM oven/bun:1.4-alpine AS manifests
+# The tag names the series for the reader; the digest is what builds — a tag is a pointer its
+# publisher can move. Dependabot's docker ecosystem moves the digest together with the tag.
+FROM oven/bun:1.4-alpine@sha256:d888c0ae6c86d7866ff10c5aafdd9077b36aee6455b33dd270fb93c0dd5cef6f AS manifests
 WORKDIR /app
 COPY . .
 RUN find . ! -type d ! -name package.json ! -name bunfig.toml ! -name '*.tgz' -delete \\
  && find . -type d -empty -delete
 
 # ---------- deps: runtime dependencies only, cached on the lockfile and the manifests ----------
-FROM oven/bun:1.4-alpine AS deps
+FROM oven/bun:1.4-alpine@sha256:d888c0ae6c86d7866ff10c5aafdd9077b36aee6455b33dd270fb93c0dd5cef6f AS deps
 WORKDIR /app
 COPY --from=manifests /app ./
 COPY bun.lock ./
@@ -56,6 +59,16 @@ FROM deps AS runtime
 WORKDIR /app
 COPY . .
 
+# ---------- prebuilt: every island chunk and compiled stylesheet, made once, here ----------
+# What a web pod otherwise makes on EVERY boot — Babel over every island, Sass over every
+# stylesheet: seconds of CPU and a compiler's worth of memory, per replica, per start. It runs in
+# the image build because the store is valid only for the Bun and the paths that wrote it; above
+# BUILD_ID, so two images differing only by their stamp share this layer; and above
+# NODE_ENV=production, because it imports the app with no deployment environment and app.config.ts
+# must ask for none — exactly as on a fresh clone. An image without this line still serves, and
+# every boot logs X_IMAGE_NOT_PREBUILT naming it.
+RUN ${PREBUILT_COMMAND}
+
 # The immutable content hash this image serves. Stamped by CI (\`--build-arg BUILD_ID=$(git rev-parse HEAD)\`);
 # without one the server computes the same hash from the manifest at boot. Never \`latest\`.
 ARG BUILD_ID=
@@ -153,6 +166,11 @@ docker run --rm -e ROLE=migrate -e DATABASE_URL=postgres://... ${app.kebab}:dev
 docker run -p 3000:3000 -e DATABASE_URL=postgres://... ${app.kebab}:dev
 \`\`\`
 
+The image build runs \`x build --target prebuilt\` after \`COPY . .\`: every island chunk and every
+compiled stylesheet is made once, there, by the image's own Bun — so a pod builds nothing at boot.
+Without that line every boot runs Babel and Sass over the whole app and logs
+\`X_IMAGE_NOT_PREBUILT\`, naming it.
+
 ## One box, every role
 
 \`\`\`sh

package/src/templates/scaffold-dashboard-bare.ts

@@ -33,7 +33,7 @@ ${themeIsland}
 
 ${routeConfig('')}
 
-export function DashboardPage() {
+export function Page() {
   const t = useT();
   const locale = currentLocale();
   // Read at render, not at import: the registries are filled by the boot scan, after this module.
@@ -174,9 +174,71 @@ unitTest('formatCount follows the locale', () => {
 });
 `;
 
-/** The bare dashboard's page, view module and view test. */
+const barePageTest = (
+  app: NameSet,
+): string => `// The dashboard, rendered as a request renders it. Its facts are the framework's registries, so
+// the test registers the one route it renders — the boot scan's job in a running app — and reads
+// the tiles and the route table back off the markup.
+${sortedImports([
+  `import { catalogs, useT } from '@${app.kebab}/i18n';`,
+  "import { frameworkVersion } from '@ultimat3/core';",
+  "import { clearRoutes, registerRoute } from '@ultimat3/render';",
+  "import { afterAll, beforeAll, expect, renderRoute, unitTest } from '@ultimat3/testing';",
+])}
+import { roles } from '../../shared/roles';
+import * as page from './page';
+
+const url = 'https://example.test/dashboard';
+
+/** The figure a tile shows, read off the markup by the \`stat\` the page gave it. */
+const stat = (html: string, name: string): string | undefined =>
+  html.match(new RegExp(\`data-stat="\${name}">([^<]*)<\`))?.[1];
+
+// The route table is process-global and a test process starts with none: this file registers the
+// page it renders, and takes it back out so no later file inherits a route it never declared.
+beforeAll(() => {
+  registerRoute({ file: 'apps/web/app/dashboard/page.tsx', config: page.config });
+});
+afterAll(clearRoutes);
+
+unitTest('the dashboard is gated, renders per request, and hydrates one island', async () => {
+  const view = await renderRoute(page, { url });
+  expect(page.config.render).toBe('ssr');
+  expect(page.config.policy?.permission).toBe('dashboard:read');
+  expect(page.config.offline).toBe('runtime');
+  expect(page.config.budget.js).toBe('60kb');
+  // What the render emitted, beside what the config declares: the theme toggle, and only it.
+  expect(view.islands.map((island) => [island.moduleId, island.strategy])).toEqual([
+    ['shared-theme-toggle', 'visible'],
+  ]);
+});
+
+unitTest('the tiles are the framework registries, counted', async () => {
+  const view = await renderRoute(page, { url });
+  expect(stat(view.html, 'routes')).toBe('1');
+  expect(stat(view.html, 'locales')).toBe(String(catalogs.locales.length));
+  expect(stat(view.html, 'roles')).toBe(String(Object.keys(roles).length));
+  expect(stat(view.html, 'version')).toBe(frameworkVersion());
+});
+
+unitTest('the table is the route table: path, surface and render mode per route', async () => {
+  const t = useT();
+  const view = await renderRoute(page, { url });
+  expect(view.html.match(/<tr data-row=/g)).toHaveLength(1);
+  expect(view.html).toMatch(
+    /<tr data-row="\\/dashboard"><td>\\/dashboard<\\/td><td>app<\\/td><td>ssr<\\/td>/,
+  );
+  expect(view.text).toContain(t('app.dashboard.routesCaption'));
+  expect(view.meta.title).toBe(t('app.dashboard.title'));
+  // The sidebar knows where it is.
+  expect(view.html).toMatch(/<a href="\\/dashboard" aria-current="page"/);
+});
+`;
+
+/** The bare dashboard's page, view module and the tests beside both. */
 export const bareDashboardFiles = (app: NameSet): readonly GeneratedFile[] => [
   { path: `${DASHBOARD_DIR}/page.tsx`, contents: barePage(app) },
   { path: `${DASHBOARD_DIR}/dashboard-view.ts`, contents: bareView() },
   { path: `${DASHBOARD_DIR}/dashboard-view.test.ts`, contents: bareViewTest() },
+  { path: `${DASHBOARD_DIR}/page.test.ts`, contents: barePageTest(app) },
 ];

package/src/templates/scaffold-dashboard-example.ts

@@ -34,7 +34,6 @@ ${sortedImports([
     "} from '@ultimat3/ui';",
   ].join('\n'),
 ])}
-import { DEMO_ORG_ID } from '../../shared/demo-org';
 import { Shell } from '../../shared/shell';
 import * as repo from '../post/repo';
 import {
@@ -47,14 +46,6 @@ import {
 } from './dashboard-view';
 import styles from './page.module.scss';
 
-/**
- * Whose posts. The route's policy decides who may open this page; which org's rows it aggregates
- * is a decision the load makes, and until this app issues sessions the only org with rows is the
- * one \`packages/db/src/seed.ts\` writes. The day sessions exist, this becomes the actor's org and
- * the read becomes \`postList.as(actor, …)\` — the query already declares the tenancy rule.
- */
-const DEMO_ORG = DEMO_ORG_ID;
-
 /** The stat row counts what it can see. Past this many posts, write an aggregate query. */
 const ROW_LIMIT = 500;
 
@@ -68,29 +59,40 @@ export interface DashboardData {
   readonly now: string;
 }
 
-async function load(): Promise<DashboardData> {
+/**
+ * What \`load\` answers, with the read as a parameter. The one branch a running app never takes is
+ * the build's: \`x build --target static\` renders every route once to measure its JS budget with
+ * no database wired, and that render gets the real empty branches — which weigh the same markup —
+ * instead of a route the budget step cannot measure. Any other failure still propagates.
+ */
+export async function dashboardData(
+  read: () => Promise<readonly Parameters<typeof toPostRow>[0][]>,
+): Promise<DashboardData> {
   const now = new Date().toISOString();
   try {
-    const rows = await repo.listByOrg(DEMO_ORG, ROW_LIMIT);
-    return { rows: rows.map(toPostRow), now };
+    return { rows: (await read()).map(toPostRow), now };
   } catch (error) {
-    // \`x build --target static\` renders every route once to measure its JS budget, with no
-    // database wired — so this is that measurement pass, not a request. Empty rows render the
-    // real empty branches, which measure the same markup. Any other failure still propagates.
     if (isUltimateError(error) && error.code === 'X_DB_UNAVAILABLE') return { rows: [], now };
     throw error;
   }
 }
 
+/**
+ * Whose posts: the ACTOR's org. The repo names none — the typed handle scopes every read to the
+ * request's actor — so the viewer \`auth/dev-actor.ts\` resolves sees the rows
+ * \`packages/db/src/seed.ts\` wrote, and a real session sees its own org's the day one exists.
+ */
+const load = (): Promise<DashboardData> => dashboardData(() => repo.list(ROW_LIMIT));
+
 ${themeIsland}
 
 ${routeConfig('\n  load,')}
 
-export interface DashboardPageProps {
+export interface PageProps {
   readonly data: DashboardData;
 }
 
-export function DashboardPage(props: DashboardPageProps) {
+export function Page(props: PageProps) {
   const t = useT();
   const locale = currentLocale();
   const now = new Date(props.data.now);
@@ -176,20 +178,15 @@ export interface PostRow {
 }
 
 /**
- * Duck-typed rather than the entity's own row: the page only ever reads these three columns.
- *
- * BOTH spellings of the timestamp, and that is a measured fact rather than caution: the repo's
- * \`select *\` hands back column names as Postgres has them (\`created_at\`) while its row type
- * says \`createdAt\`, so the typed property is \`undefined\` on a real row. Until the repo aliases
- * its columns — dz-showcase's does — the page reads whichever one arrived.
+ * Duck-typed rather than the entity's own row: the page only ever reads these three columns. The
+ * repo reads through the typed handle, so \`createdAt\` arrives as the \`Date\` the entity declares.
  */
 export function toPostRow(row: {
   readonly id: string;
   readonly title: string;
-  readonly createdAt?: Date | string | undefined;
-  readonly created_at?: Date | string | undefined;
+  readonly createdAt: Date | string;
 }): PostRow {
-  const at = row.createdAt ?? row.created_at ?? '';
+  const at = row.createdAt;
   return {
     id: row.id,
     title: row.title,
@@ -303,13 +300,10 @@ unitTest('bucketByDay is one bar per day, oldest first, quiet days included', ()
   expect(bucketByDay([], NOW, 3).map((point) => point.value)).toEqual([0, 0, 0]);
 });
 
-unitTest('toPostRow serialises a Date, passes ISO text through, and reads the raw column', () => {
+unitTest('toPostRow serialises a Date and passes ISO text through', () => {
   const at = new Date('2026-01-02T03:04:05.000Z');
   expect(toPostRow({ id: 'x', title: 't', createdAt: at }).createdAt).toBe(at.toISOString());
   expect(toPostRow({ id: 'x', title: 't', createdAt: '2026-01-01' }).createdAt).toBe('2026-01-01');
-  // What \`select *\` really returns: the snake_case column, and no \`createdAt\` at all.
-  expect(toPostRow({ id: 'x', title: 't', created_at: at }).createdAt).toBe(at.toISOString());
-  expect(toPostRow({ id: 'x', title: 't' }).createdAt).toBe('');
 });
 
 unitTest('formatCount follows the locale', () => {
@@ -318,9 +312,108 @@ unitTest('formatCount follows the locale', () => {
 });
 `;
 
-/** The example dashboard's page, view module and view test. */
+const examplePageTest = (
+  app: NameSet,
+): string => `// The dashboard, rendered as a request renders it: \`load\` reads the actor's org through the
+// slice's repo — the in-memory driver under test — and the page turns the rows into tiles, a chart
+// and a table. Losing the policy is the other regression worth a test: the page still renders, to
+// anyone.
+${sortedImports([
+  `import { driver } from '@${app.kebab}/db';`,
+  `import { useT } from '@${app.kebab}/i18n';`,
+  "import { createContext, frozenClock, runWithContext } from '@ultimat3/core';",
+  "import { testActor } from '@ultimat3/policy';",
+  "import { dbUnavailable } from '@ultimat3/db';",
+  "import { afterEach, expect, renderRoute, unitTest } from '@ultimat3/testing';",
+])}
+import { DEMO_ORG_ID } from '../../shared/demo-org';
+import * as repo from '../post/repo';
+import * as page from './page';
+
+const url = 'https://example.test/dashboard';
+const viewer = testActor('viewer', { orgId: DEMO_ORG_ID }).actor;
+const stranger = testActor('stranger', { orgId: '00000000-0000-4000-8000-000000000009' }).actor;
+
+const DAY_MS = 86_400_000;
+
+/**
+ * One post in the viewer's org, written the way the app writes one — \`daysAgo\` days before now.
+ * The request's clock is what stamps \`createdAt\`, so the test chooses the instant.
+ */
+const post = (title: string, daysAgo: number) => {
+  const clock = frozenClock(new Date(Date.now() - daysAgo * DAY_MS));
+  const draft = { orgId: DEMO_ORG_ID, title, price: { minor: 0, currency: 'USD' } };
+  return runWithContext(createContext({ actor: viewer, clock }), () => repo.insert(draft));
+};
+
+/** The figure a tile shows, read off the markup by the \`stat\` the page gave it. */
+const stat = (html: string, name: string): string | undefined =>
+  html.match(new RegExp(\`data-stat="\${name}">([^<]*)<\`))?.[1];
+
+// One store per process: without this, one test's rows are the next test's fixtures.
+afterEach(() => {
+  driver.reset?.();
+});
+
+unitTest('the dashboard is gated, renders per request, and hydrates one island', async () => {
+  const view = await renderRoute(page, { url, actor: viewer });
+  expect(page.config.render).toBe('ssr');
+  expect(page.config.policy?.permission).toBe('dashboard:read');
+  expect(page.config.offline).toBe('runtime');
+  expect(page.config.budget.js).toBe('60kb');
+  // What the render emitted, beside what the config declares: the theme toggle, and only it.
+  expect(view.islands.map((island) => [island.moduleId, island.strategy])).toEqual([
+    ['shared-theme-toggle', 'visible'],
+  ]);
+});
+
+unitTest('it counts and lists the posts of the org that is looking', async () => {
+  await post('Last month', 30);
+  await post('This week', 3);
+  await post('Today', 0);
+  const view = await renderRoute(page, { url, actor: viewer });
+  // Newest first, as the repo orders them — and each tile counts its own window.
+  expect(view.data.rows.map((row) => row.title)).toEqual(['Today', 'This week', 'Last month']);
+  expect(stat(view.html, 'posts-total')).toBe('3');
+  expect(stat(view.html, 'posts-week')).toBe('2');
+  expect(stat(view.html, 'posts-today')).toBe('1');
+  // One table row per post, and one bar per day of the window whether or not it has posts.
+  expect(view.html.match(/<tr data-row=/g)).toHaveLength(3);
+  expect(view.html.match(/data-bar="true"/g)).toHaveLength(14);
+  expect(view.text).toContain('This week');
+  // The sidebar knows where it is.
+  expect(view.html).toMatch(/<a href="\\/dashboard" aria-current="page"/);
+});
+
+unitTest('another org sees none of them: the page says so instead of an empty table', async () => {
+  const t = useT();
+  await post('Not theirs', 0);
+  const view = await renderRoute(page, { url, actor: stranger });
+  expect(view.data.rows).toEqual([]);
+  expect(stat(view.html, 'posts-total')).toBe('0');
+  expect(view.html).not.toContain('<tr data-row=');
+  expect(view.text).toContain(t('app.dashboard.emptyTitle'));
+  expect(view.meta.title).toBe(t('app.dashboard.title'));
+  expect(view.meta.description).toBe(t('app.dashboard.description'));
+});
+
+unitTest('the build measures the empty page: no database is not a failure there', async () => {
+  const measured = await page.dashboardData(() => Promise.reject(dbUnavailable('no database')));
+  // The clock is frozen under test, so the instant the windows are cut at is this one.
+  expect(measured).toEqual({ rows: [], now: new Date().toISOString() });
+});
+
+unitTest('any other failure of the read propagates', async () => {
+  const cause = new TypeError('the read broke');
+  const read = (): Promise<never> => Promise.reject(cause);
+  expect(await page.dashboardData(read).catch((error: unknown) => error)).toBe(cause);
+});
+`;
+
+/** The example dashboard's page, view module and the tests beside both. */
 export const exampleDashboardFiles = (app: NameSet): readonly GeneratedFile[] => [
   { path: `${DASHBOARD_DIR}/page.tsx`, contents: examplePage(app) },
   { path: `${DASHBOARD_DIR}/dashboard-view.ts`, contents: exampleView() },
   { path: `${DASHBOARD_DIR}/dashboard-view.test.ts`, contents: exampleViewTest() },
+  { path: `${DASHBOARD_DIR}/page.test.ts`, contents: examplePageTest(app) },
 ];

package/src/templates/scaffold-dashboard-shared.ts

@@ -1,6 +1,6 @@
 // What both dashboards share — `scaffold-dashboard.ts` picks one of `scaffold-dashboard-example.ts`
 // and `scaffold-dashboard-bare.ts` per invocation, and everything the two must agree on lives here:
-// the route declaration, the theme island, the stylesheet and the config test.
+// the route declaration, the theme island and the stylesheet.
 
 export const DASHBOARD_DIR = 'apps/web/app/dashboard';
 
@@ -56,22 +56,3 @@ export const dashboardStyle = (): string => `@use '@ultimat3/ui/tokens' as token
   color: tokens.role('fg');
 }
 `;
-
-export const dashboardPageTest =
-  (): string => `// The dashboard renders per request, is gated by a policy, hydrates its one island, and stays
-// under its budget. Losing the policy is the interesting regression: the page still renders, to
-// anyone.
-import { expect, unitTest } from '@ultimat3/testing';
-import { config } from './page';
-
-unitTest('the dashboard renders on the server, is gated, and has an offline strategy', () => {
-  expect(config.render).toBe('ssr');
-  expect(config.policy?.permission).toBe('dashboard:read');
-  expect(config.offline).toBe('runtime');
-});
-
-unitTest('the dashboard hydrates its one island inside a stated budget', () => {
-  expect(config.hydrate).toBe('visible');
-  expect(config.budget.js).toBe('60kb');
-});
-`;

package/src/templates/scaffold-dashboard.ts

@@ -15,13 +15,12 @@
 import type { GeneratedFile, NameSet } from './naming';
 import { bareDashboardFiles } from './scaffold-dashboard-bare';
 import { exampleDashboardFiles } from './scaffold-dashboard-example';
-import { DASHBOARD_DIR, dashboardPageTest, dashboardStyle } from './scaffold-dashboard-shared';
+import { DASHBOARD_DIR, dashboardStyle } from './scaffold-dashboard-shared';
 
 /** `apps/web/app/dashboard/`, in the shape the invocation earns. */
 export function dashboardFiles(app: NameSet, example: boolean): readonly GeneratedFile[] {
   return [
     ...(example ? exampleDashboardFiles(app) : bareDashboardFiles(app)),
     { path: `${DASHBOARD_DIR}/page.module.scss`, contents: dashboardStyle() },
-    { path: `${DASHBOARD_DIR}/page.test.ts`, contents: dashboardPageTest() },
   ];
 }

package/src/templates/scaffold-db-client.ts

@@ -0,0 +1,144 @@
+// The generated app's `packages/db/src/client.ts`: the ONE typed database handle, and the entity
+// set `x g entity` / `x g resource` add to. Its own module rather than a section of
+// `scaffold-db-package.ts` because `handle-registration.ts` writes the same file into an app that
+// predates it — one template, two writers.
+
+import { sortedImports } from './imports';
+import type { GeneratedFile, NameSet } from './naming';
+import { names } from './naming';
+
+/** Where the handle lives, relative to the app root. The generators' one anchor. */
+export const HANDLE_FILE = 'packages/db/src/client.ts';
+
+/** The scope a pure call that names no app writes — `x g` and `x new` always name theirs. */
+export const PLACEHOLDER_DB_MODULE = '@app/db';
+
+/** One entity in the handle's set. */
+export interface HandleEntry {
+  /** The key on the handle — the table's name, camelCase: `db.posts`. */
+  readonly key: string;
+  /** The entity's exported binding: `post`. */
+  readonly binding: string;
+  /** Where the binding is imported from: `@myapp/web/app/post/entity`. */
+  readonly specifier: string;
+}
+
+/** The line an entity takes in the set. Spelled once: the template and the registrar both write it. */
+export const handleEntryLine = (entry: HandleEntry): string => `  ${entry.key}: ${entry.binding},`;
+
+/** The import that line needs. */
+export const handleImportLine = (entry: HandleEntry): string =>
+  `import { ${entry.binding} } from '${entry.specifier}';`;
+
+/**
+ * The web workspace's package name, from the db package's: both carry the app's scope, which is
+ * how `x new` names them and how the root tsconfig's `paths` resolves them.
+ */
+export const webModuleOf = (dbModule: string): string =>
+  `${dbModule.slice(0, dbModule.lastIndexOf('/'))}/web`;
+
+/**
+ * The entry for the entity `x g entity <rawName>` writes into `<surfaceDir>/<feature>/entity.ts`.
+ * The key is `NameSet.plural` — the same word `repo.ts` reads the table under.
+ */
+export function handleEntryFor(
+  rawName: string,
+  target: { readonly surfaceDir: string; readonly feature: string; readonly dbModule: string },
+): HandleEntry {
+  const name = names(rawName);
+  // `apps/web/app` → `app`: the web workspace's own root is what its package name stands for.
+  const inWorkspace = target.surfaceDir.split('/').slice(2).join('/');
+  return {
+    key: name.plural,
+    binding: name.camel,
+    specifier: `${webModuleOf(target.dbModule)}/${inWorkspace}/${target.feature}/entity`,
+  };
+}
+
+const entitySet = (entries: readonly HandleEntry[]): string =>
+  entries.length === 0
+    ? 'const entities = {};'
+    : `const entities = {\n${entries.map(handleEntryLine).join('\n')}\n};`;
+
+/**
+ * The handle, over `entries`. The set is a named, one-entry-per-line object on purpose: it is the
+ * anchor `x g entity` inserts a line into, and an expanded object literal is a shape Biome leaves
+ * alone at any length — an inline `database({ a, b }, …)` re-wraps as it grows.
+ */
+export const dbClientSource = (
+  entries: readonly HandleEntry[],
+): string => `// The one typed database handle. \`db.<table>\` exists because the entity is in the set below —
+// nobody writes a repository class per entity, and nobody can reach a table that is not listed.
+//
+// \`x g entity\` and \`x g resource\` add their entity to \`entities\`. One written by hand is the
+// same two lines: its import, and \`<tableName>: <entity>,\` in the set.
+
+${sortedImports([
+  "import { storeMode } from '@ultimat3/core';",
+  "import { type Driver, database, memoryDriver, postgresDriver } from '@ultimat3/entity';",
+  ...entries.map(handleImportLine),
+])}
+
+/**
+ * One driver, NAMED rather than defaulted, and exported so a test resets the same object the app
+ * reads through (\`driver.reset?.()\`).
+ *
+ * \`postgresDriver()\` takes no connection: it resolves \`@ultimat3/db\`'s process client, which is
+ * the embedded PGlite under \`x dev\` and the \`DATABASE_URL\` pool in a container. \`bun test\`
+ * installs no client, so a test gets the in-memory driver — the same contract, no database.
+ * \`storeMode\` is core's one answer to that question, shared with every other seam that has a
+ * memory and a database store.
+ */
+export const selectDriver = (env: Readonly<Record<string, string | undefined>>): Driver =>
+  storeMode(env) === 'memory' ? memoryDriver() : postgresDriver();
+
+export const driver = selectDriver(Bun.env);
+
+/** Every entity the handle serves, keyed by the name its table takes on \`db\`. */
+${entitySet(entries)}
+
+/**
+ * Only a feature's \`repo.ts\`, a \`query\`'s \`sql\` or a seed may use this. A route importing it is
+ * \`X_BOUNDARY_ROUTE_TO_DB\`.
+ */
+export const db = database(entities, { driver });
+
+export type Db = typeof db;
+`;
+
+const clientTest = (
+  app: NameSet,
+): string => `// Which store the handle reads: memory under \`bun test\`, the process's Postgres client
+// everywhere else. A handle that silently took the memory driver in a container would serve an
+// empty database with a green gate.
+import { expect, unitTest } from '@ultimat3/testing';
+import { db, driver, selectDriver } from './client';
+
+unitTest('${app.kebab} reads memory under test and Postgres everywhere else', () => {
+  // Only the in-memory driver can empty itself — a Postgres driver that could truncate an app's
+  // rows from a test eventually would — so \`reset\` is what tells the two apart.
+  expect(selectDriver({ NODE_ENV: 'test' }).reset).toBeDefined();
+  expect(selectDriver({ NODE_ENV: 'production' }).reset).toBeUndefined();
+  expect(selectDriver({ ULTIMATE_ENV: 'development' }).reset).toBeUndefined();
+});
+
+unitTest('the handle is built over the driver this module exports', () => {
+  expect(driver.reset).toBeDefined();
+  expect(typeof db).toBe('object');
+});
+`;
+
+/**
+ * `packages/db/src/client.ts` and its test. With the example slice the set holds `post`; under
+ * `--no-example` it is empty and the first `x g entity` fills it.
+ */
+export const dbClientFiles = (app: NameSet, example: boolean): readonly GeneratedFile[] => {
+  const dbModule = `@${app.kebab}/db`;
+  const entries = example
+    ? [handleEntryFor('post', { surfaceDir: 'apps/web/app', feature: 'post', dbModule })]
+    : [];
+  return [
+    { path: HANDLE_FILE, contents: dbClientSource(entries) },
+    { path: 'packages/db/src/client.test.ts', contents: clientTest(app) },
+  ];
+};