@ultimat3/cli 22.15.0 → 23.0.0

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,142 @@
+// 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 { resolveEnvironment } 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.
+ */
+export const selectDriver = (env: Readonly<Record<string, string | undefined>>): Driver =>
+  resolveEnvironment({ env }) === 'test' ? 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) },
+  ];
+};

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

@@ -2,13 +2,16 @@
 // and the deterministic seed. No business logic — that is the package's own stated boundary, and it
 // is why `example` reaches only the two files describing the slice's table.
 //
-// No migration. `x db gen` is the ONE writer of `packages/db/migrations`, and a scaffold that hand-
-// wrote `0000_initial.sql` was a second one: it declared a `posts` table the generator had never
-// diffed, so the first `x db gen` saw a schema the ledger already claimed and the two disagreed
-// about what "initial" meant. `x db gen "initial"` is the app's first command instead — it writes
-// the `.sql`, the `.snapshot.json` and the `.hash` together, which no hand-written file can.
+// No migration and no schema dump. `x db gen` is the ONE writer of `packages/db/migrations` and
+// of `packages/db/schema`, and a scaffold that hand-wrote `0000_initial.sql` was a second one: it
+// declared a `posts` table the generator had never diffed, so the first `x db gen` saw a schema
+// the ledger already claimed and the two disagreed about what "initial" meant. `x db gen
+// "initial"` is the app's first command instead — it writes the `.sql`, the `.snapshot.json`, the
+// `.hash` and the dump together, which no hand-written file can.
 
+import { sortedImports } from './imports';
 import type { GeneratedFile, NameSet } from './naming';
+import { dbClientFiles } from './scaffold-db-client';
 import { packageShapeFiles, workspacePackageJson } from './scaffold-package-shape';
 
 const DESCRIPTION = 'Entity re-exports and SQL migrations, no business logic';
@@ -45,10 +48,14 @@ const dbPackage = (app: NameSet, example: boolean): string =>
     : workspacePackageJson(app, 'db', DESCRIPTION);
 
 const dbIndex =
-  (): string => `// Schema and migrations only — no business logic lives in this package. The client itself is
-// @ultimat3/db's: one connection pool, sized by ROLE, shared by every package in the app.
+  (): string => `// Schema, migrations and the typed handle — no business logic lives in this package.
+// \`db\` is the handle \`./client\` builds over the app's entities: \`db.<table>\`, which is what a
+// feature's repo.ts reads through. \`sql\` and \`withTransaction\` are @ultimat3/db's own, and the
+// connection pool behind all three is one, sized by ROLE.
 export type { DbClient, SqlFragment } from '@ultimat3/db';
-export { db, sql, withTransaction } from '@ultimat3/db';
+export { sql, withTransaction } from '@ultimat3/db';
+export type { Db } from './client';
+export { db, driver, selectDriver } from './client';
 export * as schema from './schema';
 `;
 
@@ -151,11 +158,86 @@ export const ${app.camel}Seed = defineSeed('${app.kebab}', async () => {
 });
 `;
 
+const dbSeedTest = (app: NameSet, example: boolean): string =>
+  example
+    ? `// The seed, run against the in-memory driver: the rows it writes, whose they are, and that a
+// second run writes nothing. The org is the point — a row seeded under any other id is one the
+// development viewer's tenant policy refuses, and the dashboard then counts zero.
+${sortedImports([
+  `import { DEMO_ORG_ID } from '@${app.kebab}/web/shared/demo-org';`,
+  "import { createContext, runWithContext } from '@ultimat3/core';",
+  "import { testActor } from '@ultimat3/policy';",
+  "import { afterEach, expect, unitTest } from '@ultimat3/testing';",
+])}
+import { db, driver } from './client';
+import { ${app.camel}Seed } from './seed';
+
+/** The development viewer's org: every read below runs as an actor inside it. */
+const asViewer = <T>(run: () => Promise<T>): Promise<T> =>
+  runWithContext(createContext({ actor: testActor('viewer', { orgId: DEMO_ORG_ID }).actor }), run);
+
+// One store per process: without this, one test's rows are the next test's fixtures.
+afterEach(() => {
+  driver.reset?.();
+});
+
+unitTest('the seed writes its posts under the demo org', async () => {
+  const run = await ${app.camel}Seed.run({ driver });
+  expect(run.metrics).toEqual({ inserted: 2, updated: 0, skipped: 0 });
+  const rows = await asViewer(() => db.posts.where({ orgId: DEMO_ORG_ID }).orderBy('title').all());
+  expect(rows.map((row) => row.title)).toEqual(['Hello ${app.pascal}', 'Second post']);
+  expect(rows.map((row) => row.price.minor)).toEqual([0, 1900]);
+});
+
+unitTest('a replay writes nothing: its ids are derived from labels, never generated', async () => {
+  await ${app.camel}Seed.run({ driver });
+  const replay = await ${app.camel}Seed.run({ driver });
+  expect(replay.metrics).toEqual({ inserted: 0, updated: 0, skipped: 2 });
+});
+`
+    : `// The seed as \`x db seed\` finds it: a declared \`defineSeed()\` under this app's name, which
+// writes nothing until an entity exists. The day it inserts a row, the last assertion says so.
+import { isSeed } from '@ultimat3/entity';
+import { expect, unitTest } from '@ultimat3/testing';
+import { driver } from './client';
+import { ${app.camel}Seed } from './seed';
+
+unitTest('the seed is one x db seed discovers, in the dev tier', () => {
+  expect(isSeed(${app.camel}Seed)).toBe(true);
+  expect(${app.camel}Seed.name).toBe('${app.kebab}');
+  // \`dev\`: fixture data, never loaded into production. \`reference\` is the other tier.
+  expect(${app.camel}Seed.tier).toBe('dev');
+});
+
+unitTest('it writes nothing yet', async () => {
+  const run = await ${app.camel}Seed.run({ driver });
+  expect(run.metrics).toEqual({ inserted: 0, updated: 0, skipped: 0 });
+});
+`;
+
+/**
+ * `packages/db/schema/` is written by `x db gen` and held by the `drift` step, so two things about
+ * it are git's to know. `linguist-generated` collapses it in a review — the migration is what a
+ * human reads; the dump is its projection. `text eol=lf` is not cosmetic: the gate compares bytes,
+ * and a checkout that rewrote line endings would be `X_SCHEMA_DUMP_DRIFT` on a correct tree.
+ *
+ * The attributes ship; the directory does not. `x new` scaffolds no migration, so there is nothing
+ * to dump until the first `x db gen` — which creates it.
+ */
+export const DB_GITATTRIBUTES = `# Generated by \`x db gen\` from the migrations and held equal to them by \`x verify\`'s drift
+# step (X_SCHEMA_DUMP_DRIFT). Review the migration, not this projection of it.
+schema/** linguist-generated=true text eol=lf
+`;
+
 /** Every file the `packages/db` workspace ships, in the order `x new` writes them. */
 export const dbPackageFiles = (app: NameSet, example: boolean): readonly GeneratedFile[] => [
   { path: 'packages/db/package.json', contents: dbPackage(app, example) },
+  { path: 'packages/db/.gitattributes', contents: DB_GITATTRIBUTES },
   ...packageShapeFiles(app, 'db', DESCRIPTION),
   { path: 'packages/db/src/index.ts', contents: dbIndex() },
+  // The typed handle and its test — `scaffold-db-client.ts`, shared with `x g entity`.
+  ...dbClientFiles(app, example),
   { path: 'packages/db/src/schema.ts', contents: dbSchema(app, example) },
   { path: 'packages/db/src/seed.ts', contents: dbSeed(app, example) },
+  { path: 'packages/db/src/seed.test.ts', contents: dbSeedTest(app, example) },
 ];