@ultimat3/cli 29.3.2 → 30.0.0

package/src/templates/shapes/blog-slice.ts

@@ -0,0 +1,265 @@
+// The `blog` shape's `post` slice: an entity with no tenant (a blog is one publication), the repo,
+// two public reads the site renders, and the seed. Writes go through `/admin`, which derives its
+// screens from the entity, so the slice declares no write action of its own.
+
+import type { GeneratedFile, NameSet } from '../naming';
+
+const DIR = 'apps/web/app/post';
+
+const entity =
+  (): string => `// A post: a slug, a title and a body, published when \`publishedAt\` is set. No \`tenant:\` — a blog
+// is one publication, so every reader reads the same rows.
+
+import { entity, invariant, text, timestamp, uuid } from '@ultimat3/entity';
+
+export const post = entity('posts', {
+  columns: {
+    id: uuid().primaryKey(),
+    slug: text({ max: 120 }).unique(),
+    title: text({ max: 200 }),
+    body: text(),
+    /** Null is a draft: no read below returns it, so no page renders it. */
+    publishedAt: timestamp().nullable(),
+    createdAt: timestamp().defaultNow(),
+  },
+  invariants: (c) => [
+    invariant('post_title_not_blank', c.title.trimmed().minLength(1)),
+    invariant('post_slug_not_blank', c.slug.trimmed().minLength(1)),
+  ],
+  indexes: [{ on: ['publishedAt'] }],
+});
+
+export type Post = typeof post.$row;
+`;
+
+const entityTest =
+  (): string => `// The table as declared: shared by every reader, with its two invariants.
+import { expect, unitTest } from '@ultimat3/testing';
+import { post } from './entity';
+
+unitTest('post is one table every reader shares, with its two invariants', () => {
+  expect(post.$name).toBe('posts');
+  expect(post.$tenantColumn).toBeNull();
+  expect(post.$invariants.map((rule) => rule.name)).toEqual([
+    'post_title_not_blank',
+    'post_slug_not_blank',
+  ]);
+});
+`;
+
+const repo = (
+  app: NameSet,
+): string => `// The only reads of \`posts\`: published rows, newest first, and one by its slug.
+
+import { db } from '@${app.kebab}/db';
+import type { Post } from './entity';
+
+export async function published(limit: number): Promise<readonly Post[]> {
+  return db.posts
+    .andWhere('publishedAt', 'is-not-null')
+    .orderBy('publishedAt', 'desc')
+    .orderBy('id', 'desc')
+    .limit(limit)
+    .all();
+}
+
+export async function publishedBySlug(slug: string): Promise<readonly Post[]> {
+  return db.posts.where({ slug }).andWhere('publishedAt', 'is-not-null').limit(1).all();
+}
+`;
+
+const repoTest = (
+  app: NameSet,
+): string => `// The repo's two reads, against the in-memory driver: never a draft, newest first.
+import { db, driver } from '@${app.kebab}/db';
+import { afterEach, expect, unitTest } from '@ultimat3/testing';
+import * as repo from './repo';
+
+const at = (iso: string): Date => new Date(iso);
+
+afterEach(() => {
+  driver.reset?.();
+});
+
+const write = async (slug: string, publishedAt: Date | null): Promise<void> => {
+  await db.posts.insert({ slug, title: slug, body: 'body', publishedAt });
+};
+
+unitTest('published is newest first, bounded, and never a draft', async () => {
+  await write('old', at('2026-01-01T00:00:00Z'));
+  await write('new', at('2026-02-01T00:00:00Z'));
+  await write('draft', null);
+  expect((await repo.published(10)).map((row) => row.slug)).toEqual(['new', 'old']);
+  expect((await repo.published(1)).map((row) => row.slug)).toEqual(['new']);
+});
+
+unitTest('publishedBySlug answers one published row, and nothing for a draft', async () => {
+  await write('live', at('2026-01-01T00:00:00Z'));
+  await write('draft', null);
+  expect((await repo.publishedBySlug('live')).map((row) => row.slug)).toEqual(['live']);
+  expect(await repo.publishedBySlug('draft')).toEqual([]);
+});
+`;
+
+const publishedPosts =
+  (): string => `// The blog index: published posts, newest first. Public — \`allow('public')\` says so out loud.
+
+import { allow } from '@ultimat3/policy';
+import { from, query, t } from '@ultimat3/query';
+import type { Post } from '../entity';
+import * as repo from '../repo';
+
+export const publishedPosts = query({
+  input: t.object({ limit: t.number.int().min(1).max(50).default(20) }),
+  policy: allow('public'),
+  mcp: { expose: true, description: 'The published posts, newest first' },
+  sql: ({ limit }) =>
+    from<Post>('posts', () => repo.published(limit))
+      .compare('publishedAt', '!=', null)
+      .orderBy('publishedAt', 'desc')
+      .orderBy('id', 'desc')
+      .limit(limit),
+});
+`;
+
+const publishedPost =
+  (): string => `// One published post by its slug: a page of at most one row, so a missing slug is an empty page
+// (the route answers 404) rather than an error every crawler logs.
+
+import { allow } from '@ultimat3/policy';
+import { from, query, t } from '@ultimat3/query';
+import type { Post } from '../entity';
+import * as repo from '../repo';
+
+export const publishedPost = query({
+  input: t.object({ slug: t.string.max(120) }),
+  policy: allow('public'),
+  mcp: { expose: true, description: 'One published post, by its slug' },
+  sql: ({ slug }) =>
+    from<Post>('posts', () => repo.publishedBySlug(slug))
+      .where({ slug })
+      .compare('publishedAt', '!=', null)
+      .limit(1),
+});
+`;
+
+const queriesTest = (
+  app: NameSet,
+): string => `// The two public reads, called as an anonymous visitor: published rows only.
+import { db, driver } from '@${app.kebab}/db';
+import { anonymousActor } from '@ultimat3/core';
+import { afterEach, expect, unitTest } from '@ultimat3/testing';
+import { publishedPost } from './published-post';
+import { publishedPosts } from './published-posts';
+
+const index = publishedPosts.named('publishedPosts');
+const one = publishedPost.named('publishedPost');
+
+afterEach(() => {
+  driver.reset?.();
+});
+
+unitTest('anyone reads the published posts, and no draft', async () => {
+  await db.posts.insert({ slug: 'hello', title: 'Hello', body: 'b', publishedAt: new Date(0) });
+  await db.posts.insert({ slug: 'wip', title: 'Wip', body: 'b', publishedAt: null });
+  const rows = await index.as(anonymousActor(), {});
+  expect(rows.map((row) => row.slug)).toEqual(['hello']);
+  expect((await one.as(anonymousActor(), { slug: 'hello' })).map((row) => row.title)).toEqual([
+    'Hello',
+  ]);
+  expect(await one.as(anonymousActor(), { slug: 'wip' })).toEqual([]);
+});
+`;
+
+const seed = (app: NameSet): string => `import { defineSeed } from '@ultimat3/entity';
+import { post } from './schema';
+
+/** Stable across runs: \`id('post:hello')\` is a UUID v5 of the label, not a random one. */
+export const ${app.camel}Seed = defineSeed('${app.kebab}', async ({ insert, id }) => {
+  await insert(post, [
+    {
+      id: id('post:hello'),
+      slug: 'hello',
+      title: 'Hello, world',
+      body: 'The first post. Edit it, or write the next one, at /admin.',
+      publishedAt: new Date('2026-01-01T00:00:00Z'),
+    },
+    {
+      id: id('post:draft'),
+      slug: 'draft',
+      title: 'A draft',
+      body: 'Unpublished: no page renders it until publishedAt is set.',
+      publishedAt: null,
+    },
+  ]);
+});
+`;
+
+const seedTest = (
+  app: NameSet,
+): string => `// The seed, run against the in-memory driver: what it writes, and that a second run writes nothing.
+import { isSeed } from '@ultimat3/entity';
+import { afterEach, expect, unitTest } from '@ultimat3/testing';
+import { db, driver } from './client';
+import { ${app.camel}Seed } from './seed';
+
+afterEach(() => {
+  driver.reset?.();
+});
+
+unitTest('the seed is one x db seed discovers, in the dev tier', () => {
+  expect(isSeed(${app.camel}Seed)).toBe(true);
+  expect(${app.camel}Seed.tier).toBe('dev');
+});
+
+unitTest('it writes one published post and one draft, once', async () => {
+  const first = await ${app.camel}Seed.run({ driver });
+  expect(first.metrics.inserted).toBe(2);
+  const rows = await db.posts.orderBy('slug').all();
+  expect(rows.map((row) => [row.slug, row.publishedAt === null])).toEqual([
+    ['draft', true],
+    ['hello', false],
+  ]);
+  expect((await ${app.camel}Seed.run({ driver })).metrics.inserted).toBe(0);
+});
+`;
+
+const authTest =
+  (): string => `// The auth instance is built once per process, on first use. Built here over a MIGRATED database,
+// never the process default: the adapter keeps the client it was built over, so an instance first
+// built with no database installed is the one every later sign-in test in this process reaches —
+// unable to reach any database, in a file that installed its own.
+import { migratedDatabase } from '@ultimat3/cli';
+import { setDbClient } from '@ultimat3/db';
+import { afterAll, beforeAll, expect, reusableDatabase, unitTest } from '@ultimat3/testing';
+import { appAuth } from './auth';
+
+// A template restore is ~0.5 s; its first build (initdb plus every migration) is what this bounds.
+const BOOT_MS = 120_000;
+
+const workerDatabase = reusableDatabase(() => migratedDatabase({ root: import.meta.dir }));
+beforeAll(async () => {
+  setDbClient(await workerDatabase());
+}, BOOT_MS);
+afterAll(() => setDbClient(undefined));
+
+unitTest('appAuth builds one instance and hands it back every time', () => {
+  expect(appAuth()).toBe(appAuth());
+});
+`;
+
+/** The slice, its tests, and the seed that replaces the empty one. */
+export function blogSliceFiles(app: NameSet): readonly GeneratedFile[] {
+  return [
+    { path: `${DIR}/entity.ts`, contents: entity() },
+    { path: `${DIR}/entity.test.ts`, contents: entityTest() },
+    { path: `${DIR}/repo.ts`, contents: repo(app) },
+    { path: `${DIR}/repo.test.ts`, contents: repoTest(app) },
+    { path: `${DIR}/queries/published-posts.ts`, contents: publishedPosts() },
+    { path: `${DIR}/queries/published-post.ts`, contents: publishedPost() },
+    { path: `${DIR}/queries/queries.test.ts`, contents: queriesTest(app) },
+    { path: 'packages/db/src/seed.ts', contents: seed(app) },
+    { path: 'packages/db/src/seed.test.ts', contents: seedTest(app) },
+    { path: 'apps/web/app/auth/auth.test.ts', contents: authTest() },
+  ];
+}

package/src/templates/shapes/blog.ts

@@ -0,0 +1,114 @@
+// `x new <name> --shape blog`: a publication. `site/` is the only rendered surface — an `isr` index
+// and one page per post, zero JavaScript on every route — over a `post` slice with no tenant,
+// written at `/admin`. No `app/` page, no island, no sign-in page, no dashboard.
+
+import type { GeneratedFile, NameSet } from '../naming';
+import { blogSiteFiles } from './blog-site';
+import { blogSliceFiles } from './blog-slice';
+import type { ShapeEdit, ShapeOverlay } from './overlay';
+import { claudeRows, shapeLines } from './shared-edits';
+
+const apiIndex = (): string => `/**
+ * The API surface: every primitive this app exposes, registered in one call. The site's pages
+ * read these two over HTTP through \`shared/client.ts\`; MCP lists both (\`mcp.expose\`).
+ */
+
+import { defineApi } from '@ultimat3/action';
+import * as publishedPost from '../app/post/queries/published-post';
+import * as publishedPosts from '../app/post/queries/published-posts';
+import * as health from './health';
+
+export const api = defineApi({
+  actions: [health],
+  queries: [publishedPosts, publishedPost],
+});
+
+/** What the typed client is shaped from — imported as a TYPE only by \`shared/client.ts\`. */
+export type Api = typeof api;
+`;
+
+const apiIndexTest =
+  (): string => `// The registration, read back: a read left out of the list is a route that answers 404.
+import { expect, unitTest } from '@ultimat3/testing';
+import { api } from './index';
+
+unitTest('health and both public reads are registered under their export names', () => {
+  expect(api.actions.health.describe().name).toBe('health');
+  expect(api.queries.publishedPosts.describe().name).toBe('publishedPosts');
+  expect(api.queries.publishedPost.describe().name).toBe('publishedPost');
+});
+`;
+
+const edits = (app: NameSet): readonly ShapeEdit[] => [
+  {
+    path: 'packages/db/src/client.ts',
+    find: 'const entities = {};',
+    replace: 'const entities = {\n  posts: post,\n};',
+  },
+  {
+    path: 'packages/db/src/client.ts',
+    find: "import { storeMode } from '@ultimat3/core';",
+    replace: `import { post } from '@${app.kebab}/web/app/post/entity';\nimport { storeMode } from '@ultimat3/core';`,
+  },
+  {
+    path: 'packages/db/src/schema.ts',
+    find: 'export {};',
+    replace: `export { post } from '@${app.kebab}/web/app/post/entity';`,
+  },
+  {
+    path: 'packages/db/package.json',
+    find: '  "scripts": {',
+    replace: `  "dependencies": {\n    "@${app.kebab}/web": "0.0.0"\n  },\n  "scripts": {`,
+  },
+  {
+    path: 'apps/web/package.json',
+    find: '  "dependencies": {\n',
+    replace: `  "dependencies": {\n    "@${app.kebab}/db": "0.0.0",\n`,
+  },
+  // The admin's resource screens for `posts` are where a post is written.
+  {
+    path: 'apps/web/shared/roles.ts',
+    find: "  'dashboard:read',\n]);",
+    replace: "  'dashboard:read',\n  'posts:read',\n  'posts:write',\n  'posts:delete',\n]);",
+  },
+  {
+    path: 'apps/web/shared/roles.ts',
+    find: "    grants: ['admin:read', 'admin:write', 'admin:destroy', 'job:read', 'audit:read'],",
+    replace: [
+      '    grants: [',
+      ...['admin:read', 'admin:write', 'admin:destroy', 'job:read', 'audit:read'].map(
+        (grant) => `      '${grant}',`,
+      ),
+      "      'posts:read',",
+      "      'posts:write',",
+      "      'posts:delete',",
+      '    ],',
+    ].join('\n'),
+  },
+  ...claudeRows({
+    page: '`apps/web/site/page.test.ts`',
+    island: 'none in this shape: `bunx x g island <name>` writes one with its states',
+  }),
+  ...shapeLines(
+    'blog',
+    'a publication — `apps/web/site/` renders the `post` slice (`apps/web/app/post/`) with zero JavaScript, and `/admin` writes it',
+  ),
+];
+
+export const blogShape: ShapeOverlay = {
+  example: false,
+  drop: [
+    'apps/web/app/dashboard/',
+    'apps/web/shared/shell',
+    'apps/web/shared/theme-toggle.island',
+    'apps/web/shared/browser-client',
+  ],
+  dropKeys: ['app.dashboard', 'shell', 'site.home'],
+  edits,
+  files: (app): readonly GeneratedFile[] => [
+    ...blogSliceFiles(app),
+    ...blogSiteFiles(app),
+    { path: 'apps/web/api/index.ts', contents: apiIndex() },
+    { path: 'apps/web/api/index.test.ts', contents: apiIndexTest() },
+  ],
+};

package/src/templates/shapes/dashboard-detail.ts

@@ -0,0 +1,242 @@
+// `--shape dashboard`'s detail: one post by id, read through a `single` query as the request's
+// actor, and the page `/posts` links each title to. Tests beside each, against the in-memory driver.
+
+import type { GeneratedFile, NameSet } from '../naming';
+
+const DIR = 'apps/web/app/post/queries';
+const PAGE = 'apps/web/app/posts/[id]';
+
+const postById =
+  (): string => `// postById: one post of the caller's org, by id — the row a detail page reads. A page of at
+// most one row: an id the org does not hold reads empty, so another org's post is "not found",
+// never a refusal that confirms it exists. \`single\` makes the wire answer the row itself.
+
+import { from, query, t } from '@ultimat3/query';
+import type { Post } from '../entity';
+import { canPostRead } from '../policy';
+import * as repo from '../repo';
+
+export const postById = query({
+  input: t.object({ id: t.uuid }),
+  policy: canPostRead,
+  single: true,
+  // The refusals a caller may branch on, closed: add each code this read comes to throw.
+  errors: [],
+  sql: ({ id }) =>
+    from<Post>('posts', async () => {
+      const row = await repo.byId(id);
+      return row === undefined ? [] : [row];
+    })
+      .where({ id })
+      .limit(1),
+});
+`;
+
+const postByIdTest = (
+  app: NameSet,
+): string => `// postById, READ: one row of the caller's org, and nothing of another org's.
+import { driver } from '@${app.kebab}/db';
+import { ctxOf, frozenClock, runWithContext } from '@ultimat3/core';
+import { testActor } from '@ultimat3/policy';
+import { afterEach, expect, unitTest } from '@ultimat3/testing';
+import * as repo from '../repo';
+import { postById } from './post-by-id';
+
+const orgId = '00000000-0000-4000-8000-000000000002';
+const otherOrg = '00000000-0000-4000-8000-000000000009';
+const target = postById.named('postById');
+const read = 'post:read';
+const member = testActor('member', { orgId, permissions: [read] }).actor;
+const clock = frozenClock('2026-01-01T00:00:00.000Z');
+
+const store = (owner: string, title: string) => {
+  const draft = { orgId: owner, title, price: { minor: 0, currency: 'USD' } };
+  const writer = ctxOf({ actor: testActor('writer', { orgId: owner }).actor, clock });
+  return runWithContext(writer, () => repo.insert(draft));
+};
+
+afterEach(() => {
+  driver.reset?.();
+});
+
+unitTest('a caller with no grant is refused before the read', async () => {
+  const stranger = testActor('stranger', { orgId }).actor;
+  const id = '00000000-0000-4000-8000-000000000001';
+  const refused = await target.as(stranger, { id }).catch((error: unknown) => error);
+  expect(refused).toBeUltimateError('X_FORBIDDEN');
+});
+
+unitTest('the row by its id, and another org’s id reads empty', async () => {
+  const ours = await store(orgId, 'ours');
+  const theirs = await store(otherOrg, 'theirs');
+  expect((await target.as(member, { id: ours.id })).map((row) => row.title)).toEqual(['ours']);
+  expect(await target.as(member, { id: theirs.id })).toEqual([]);
+});
+`;
+
+const page = (
+  app: NameSet,
+): string => `// /posts/:id: one post of the org that is looking — the row /posts links each title to. Read
+// through the slice's own query as the request's actor, so the policy and the tenancy are the
+// query's: another org's id is the not-found state, never its row.
+
+import { useT } from '@${app.kebab}/i18n';
+import type { AsyncState } from '@ultimat3/core';
+import type { KnownPermission } from '@ultimat3/policy';
+import { defineRoute } from '@ultimat3/render';
+import {
+  DateTime,
+  DescriptionList,
+  EmptyState,
+  ErrorState,
+  Money,
+  PageHeader,
+  Section,
+} from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import { Shell } from '../../../shared/shell';
+import type { Post } from '../../post/entity';
+import { postById } from '../../post/queries/post-by-id';
+import styles from './page.module.scss';
+
+/** The read's outcome as DATA: the row, none (not this org's, or no such id), or the refusal. */
+export type PageData = AsyncState<Post | undefined>;
+
+/** A refusal or a malformed id is the page's error branch, never a 500 for the whole document. */
+export async function postState(read: () => Promise<readonly Post[]>): Promise<PageData> {
+  try {
+    return { status: 'ready', data: (await read())[0] };
+  } catch (error) {
+    return { status: 'failed', error };
+  }
+}
+
+export const config = defineRoute({
+  // Per request, by id: no build holds an id to render it at, and \`stream\` would need a
+  // \`prerender()\` list of every row. \`ssr\` with a param is reported unweighable, never a finding.
+  render: 'ssr',
+  hydrate: 'visible',
+  offline: 'runtime',
+  policy: { permission: 'post:read' satisfies KnownPermission },
+  // The dashboard's own figure: this page hydrates the same one island, the shell's theme toggle,
+  // and the post itself is server markup.
+  budget: { js: '60kb' },
+  load: ({ params }) => postState(() => postById({ id: params.id ?? '' })),
+  meta: ({ t }) => ({
+    title: t('app.post.detail'),
+    description: t('app.posts.description'),
+  }),
+});
+
+function Body(props: { readonly data: PageData }): JSX.Element {
+  const t = useT();
+  const state = props.data;
+  if (state.status === 'failed') return <ErrorState error={state.error} />;
+  const row = state.status === 'ready' ? state.data : undefined;
+  if (row === undefined) return <EmptyState title={t('app.post.missing')} />;
+  return (
+    <Section title={row.title}>
+      <DescriptionList
+        items={[
+          { term: t('app.post.priceLabel'), detail: <Money value={row.price} /> },
+          {
+            term: t('app.post.created'),
+            detail: <DateTime value={row.createdAt} timeZone="UTC" dateStyle="medium" />,
+          },
+        ]}
+      />
+    </Section>
+  );
+}
+
+export function Page(props: { readonly data: PageData }): JSX.Element {
+  const t = useT();
+  return (
+    <Shell>
+      <div class={styles.page}>
+        <PageHeader title={t('app.post.detail')} />
+        <Body data={props.data} />
+        <a href="/posts">{t('app.post.back')}</a>
+      </div>
+    </Shell>
+  );
+}
+`;
+
+const pageTest = (
+  app: NameSet,
+): string => `// /posts/:id, rendered as a request renders it: the row, the not-found state for an id the
+// org does not hold, and the refusal for a caller without the grant.
+import { driver } from '@${app.kebab}/db';
+import { useT } from '@${app.kebab}/i18n';
+import { ctxOf, frozenClock, runWithContext } from '@ultimat3/core';
+import { testActor } from '@ultimat3/policy';
+import { afterEach, expect, renderRoute, unitTest } from '@ultimat3/testing';
+// The app's API, as boot loads it: \`defineApi\` names the query the page reads.
+import '../../../api';
+import * as repo from '../../post/repo';
+import * as page from './page';
+
+const orgId = '00000000-0000-4000-8000-000000000002';
+const otherOrg = '00000000-0000-4000-8000-000000000009';
+const read = 'post:read';
+const member = testActor('member', { orgId, permissions: [read] }).actor;
+const clock = frozenClock('2026-01-01T00:00:00.000Z');
+
+const store = (owner: string, title: string) => {
+  const draft = { orgId: owner, title, price: { minor: 1200, currency: 'USD' } };
+  const writer = ctxOf({ actor: testActor('writer', { orgId: owner }).actor, clock });
+  return runWithContext(writer, () => repo.insert(draft));
+};
+
+const at = (id: string) => ({ url: \`https://example.test/posts/\${id}\`, params: { id } });
+
+afterEach(() => {
+  driver.reset?.();
+});
+
+unitTest('the post, its price and when it was created', async () => {
+  const row = await store(orgId, 'first post');
+  const view = await renderRoute(page, { ...at(row.id), actor: member });
+  expect(view.text).toContain('first post');
+  expect(view.text).toContain('$12.00');
+  expect(view.meta.title).toBe(useT()('app.post.detail'));
+});
+
+unitTest('another org’s post is not found, never its row', async () => {
+  const theirs = await store(otherOrg, 'theirs');
+  const view = await renderRoute(page, { ...at(theirs.id), actor: member });
+  expect(view.text).not.toContain('theirs');
+  expect(view.text).toContain(useT()('app.post.missing'));
+});
+
+unitTest('a caller the read refuses sees the refusal, and the page around it', async () => {
+  const row = await store(orgId, 'ours');
+  const stranger = testActor('stranger', { orgId }).actor;
+  const view = await renderRoute(page, { ...at(row.id), actor: stranger });
+  expect(view.html).toContain('X_FORBIDDEN');
+  expect(view.text).toContain(useT()('app.post.back'));
+});
+`;
+
+const pageStyles =
+  (): string => `// Semantic tokens only — a raw hex here is refused by the boundaries step (guards/raw-colour.ts).
+@use '@ultimat3/ui/tokens' as tokens;
+
+.page {
+  display: grid;
+  gap: tokens.space(4);
+  padding: tokens.space(6);
+  background: tokens.role('bg');
+  color: tokens.role('fg');
+}
+`;
+
+/** The read, the page, and a test beside each. */
+export const dashboardDetailFiles = (app: NameSet): readonly GeneratedFile[] => [
+  { path: `${DIR}/post-by-id.ts`, contents: postById() },
+  { path: `${DIR}/post-by-id.test.ts`, contents: postByIdTest(app) },
+  { path: `${PAGE}/page.tsx`, contents: page(app) },
+  { path: `${PAGE}/page.test.ts`, contents: pageTest(app) },
+  { path: `${PAGE}/page.module.scss`, contents: pageStyles() },
+];

package/src/templates/shapes/dashboard.ts

@@ -0,0 +1,53 @@
+// `x new <name> --shape dashboard`: an internal tool. The default scaffold's dashboard, the `post`
+// table and its job, `/admin` — plus a detail page each row links to, and sign-in, written by
+// `x g sign-in --password` itself. The marketing `site/` stays a home page and the error documents.
+
+import { catalogJson } from '../catalog-json';
+import { catalogPath } from '../locales';
+import type { GeneratedFile, NameSet } from '../naming';
+import { dashboardDetailFiles } from './dashboard-detail';
+import type { ShapeEdit, ShapeOverlay } from './overlay';
+import { shapeLines } from './shared-edits';
+
+const API = 'apps/web/api/index.ts';
+const LIST_IMPORT = "import * as postList from '../app/post/live/post-list';\n";
+
+const edits = (): readonly ShapeEdit[] => [
+  {
+    path: API,
+    find: LIST_IMPORT,
+    replace: `${LIST_IMPORT}import * as postById from '../app/post/queries/post-by-id';\n`,
+  },
+  { path: API, find: 'queries: [postList],', replace: 'queries: [postList, postById],' },
+  // Each title is the link to its own page; the table stays links, no script.
+  {
+    path: 'apps/web/app/posts/page.tsx',
+    find: 'cell: (row) => row.title,',
+    replace: `cell: (row) => <a href={\`/posts/\${row.id}\`}>{row.title}</a>,`,
+  },
+  ...shapeLines(
+    'dashboard',
+    'an internal tool — the `post` table at `/posts` links each row to `apps/web/app/posts/[id]/page.tsx`, and `x g sign-in --password` wrote the sign-in',
+  ),
+];
+
+/** The keys the detail page reads, merged into the catalog the base wrote. */
+const catalog = (): GeneratedFile => ({
+  path: catalogPath('en'),
+  merge: 'json',
+  contents: catalogJson({
+    'app.post.back': 'All posts',
+    'app.post.created': 'Created',
+    'app.post.detail': 'Post',
+    'app.post.missing': 'No such post in this organisation.',
+  }),
+});
+
+export const dashboardShape: ShapeOverlay = {
+  example: true,
+  drop: [],
+  dropKeys: [],
+  edits,
+  files: (app: NameSet): readonly GeneratedFile[] => [...dashboardDetailFiles(app), catalog()],
+  generate: [['sign-in', '--password']],
+};