@ultimat3/cli 1.0.0

package/src/scaffold-typecheck.ts

@@ -0,0 +1,240 @@
+// Typechecks what `x new` and `x g` write, the way the user's own `tsc` will: real files on disk,
+// the real workspace packages, the real compiler. A template that merely parses has not been
+// checked — it has moved its failure from this gate to the first command the user runs.
+
+// `node:` and not Bun: Bun has no API for a temporary directory (`mkdtempSync` + `tmpdir`), for a
+// symlink (`symlinkSync`, how the sandbox borrows the workspace's node_modules), or for a
+// recursive delete (`rmSync`). `node:path` comes with them — `Bun.write` takes the joined path,
+// but only `resolve`/`sep` can prove that path stayed inside the sandbox.
+import { mkdtempSync, rmSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve, sep } from 'node:path';
+import { ScaffoldPathEscapeError } from './errors';
+import type { Runner } from './exec';
+import { exec } from './exec';
+import { FIXTURE_APP, scaffoldFixture } from './scaffold-fixture';
+import type { GeneratedFile } from './templates';
+
+/** Derived from this file, never from cwd, so the harness works from any working directory. */
+export const workspaceRoot = (): string => resolve(import.meta.dir, '..', '..', '..');
+
+export interface TypeDiagnostic {
+  /** Sandbox-relative path, or '' for a diagnostic the compiler raised about the project itself. */
+  readonly file: string;
+  readonly line: number;
+  readonly code: string;
+  readonly message: string;
+}
+
+const AT_FILE = /^(.+?)\((\d+),(\d+)\): error (TS\d+): (.*)$/;
+const PROJECT_WIDE = /^error (TS\d+): (.*)$/;
+
+/**
+ * Config errors carry no file, so both shapes are collected: a silent harness is a green lie.
+ * Split on `\r?\n`, because a trailing `\r` lands inside the message capture and no `KNOWN_GAPS`
+ * entry would match it — a CRLF `tsc` would turn every pinned gap into an unexplained failure.
+ */
+export function parseDiagnostics(output: string): readonly TypeDiagnostic[] {
+  const found: TypeDiagnostic[] = [];
+  for (const line of output.split(/\r?\n/)) {
+    const at = AT_FILE.exec(line);
+    if (at !== null) {
+      found.push({
+        file: at[1] ?? '',
+        line: Number.parseInt(at[2] ?? '0', 10),
+        code: at[4] ?? '',
+        message: at[5] ?? '',
+      });
+      continue;
+    }
+    const wide = PROJECT_WIDE.exec(line.trim());
+    if (wide !== null)
+      found.push({ file: '', line: 0, code: wide[1] ?? '', message: wide[2] ?? '' });
+  }
+  return found;
+}
+
+export interface KnownGap {
+  /** `ScaffoldVariant.name`. A pin bought by one invocation may not excuse another. */
+  readonly variant: string;
+  readonly code: string;
+  /** Exact sandbox-relative path. A pattern would absolve the same bug in a file nobody pinned. */
+  readonly file: string;
+  /** Exact `tsc` message. Matched literally so a near-miss regression is not absorbed. */
+  readonly message: string;
+  /** Who fixes it, and why the template cannot. */
+  readonly owner: string;
+}
+
+// `InvariantColumns` is an index-signature type, so `c.title` is `ColumnExpr | undefined` under
+// `noUncheckedIndexedAccess`. Every hand-written entity in `examples/dummy` reproduces it
+// identically: the fix is a column proxy typed from the entity's own columns, in @ultimat3/entity
+// — a different template cannot avoid it without dropping to `satisfies()`, which would silently
+// stop emitting the Postgres CHECK.
+//
+// Measured, not guessed: no open-keyed form avoids the `| undefined` (index signature, `Record`,
+// and a mapped type over `string` or a template-literal pattern all produce it), and typing the
+// proxy from `columns` only reaches `c` when the element of `invariants:` is itself
+// context-sensitive. `invariant(name, build)` is a *call*, which TypeScript checks before
+// `entity()`'s own `C` is fixed, so `K` falls back to `string` and nothing changes. Making it
+// reach means changing the shape of `invariants:` — a documented primitive, so a major.
+const INVARIANT_PROXY =
+  '@ultimat3/entity — type the invariant column proxy from the declared columns (needs a major: ' +
+  'the `invariants:` element shape has to become context-sensitive)';
+
+/** Every entity the fixture generates. Each one declares the same two invariants. */
+const FIXTURE_ENTITIES = [
+  'apps/web/app/credit-note/entity.ts',
+  'apps/web/app/invoice/entity.ts',
+  'apps/web/app/post/entity.ts',
+] as const;
+
+/**
+ * Diagnostics a template cannot fix, pinned one occurrence at a time. Pinned, never ignored:
+ * `unexpectedIn` fails on anything not listed here — including a second copy of a listed
+ * diagnostic, because each entry is consumed by exactly one match — and `staleGapsIn` fails when
+ * a listed entry stops reproducing, so an entry cannot outlive the bug it describes.
+ */
+export const KNOWN_GAPS: readonly KnownGap[] = FIXTURE_ENTITIES.flatMap((file) =>
+  ["'c.title' is possibly 'undefined'.", "'c.price' is possibly 'undefined'."].map(
+    (message): KnownGap => ({
+      variant: 'x new',
+      code: 'TS18048',
+      file,
+      message,
+      owner: INVARIANT_PROXY,
+    }),
+  ),
+);
+
+/** The pins one invocation may spend. Another variant's pins are not its to spend. */
+export const gapsFor = (variant: string): readonly KnownGap[] =>
+  KNOWN_GAPS.filter((gap) => gap.variant === variant);
+
+const matches = (diagnostic: TypeDiagnostic, gap: KnownGap): boolean =>
+  diagnostic.code === gap.code &&
+  diagnostic.file === gap.file &&
+  diagnostic.message === gap.message;
+
+export interface GapPartition {
+  /** Diagnostics no unconsumed `KNOWN_GAPS` entry accounts for. */
+  readonly unexpected: readonly TypeDiagnostic[];
+  /** Entries that found no match — the bug is fixed and the pin has to go. */
+  readonly stale: readonly KnownGap[];
+}
+
+/**
+ * One pass, first-fit, each pin spent once. Counting matters: two occurrences of a diagnostic
+ * pinned once means a new regression is hiding behind an old bug, so the surplus is unexpected.
+ */
+export function partitionDiagnostics(
+  diagnostics: readonly TypeDiagnostic[],
+  gaps: readonly KnownGap[] = KNOWN_GAPS,
+): GapPartition {
+  const budget = gaps.map((gap) => ({ gap, spent: false }));
+  const unexpected: TypeDiagnostic[] = [];
+  for (const entry of diagnostics) {
+    const slot = budget.find((pin) => !pin.spent && matches(entry, pin.gap));
+    if (slot === undefined) unexpected.push(entry);
+    else slot.spent = true;
+  }
+  return { unexpected, stale: budget.filter((pin) => !pin.spent).map((pin) => pin.gap) };
+}
+
+/** Everything the gate refuses: a diagnostic no unconsumed `KNOWN_GAPS` entry accounts for. */
+export const unexpectedIn = (
+  diagnostics: readonly TypeDiagnostic[],
+  gaps: readonly KnownGap[] = KNOWN_GAPS,
+): readonly TypeDiagnostic[] => partitionDiagnostics(diagnostics, gaps).unexpected;
+
+/** Entries that no longer reproduce — the bug is fixed and the pin has to go. */
+export const staleGapsIn = (
+  diagnostics: readonly TypeDiagnostic[],
+  gaps: readonly KnownGap[] = KNOWN_GAPS,
+): readonly KnownGap[] => partitionDiagnostics(diagnostics, gaps).stale;
+
+/** Written beside the app's own tsconfig so the gate inherits every flag the app ships with. */
+const OVERLAY = 'tsconfig.scaffold-check.json';
+
+/**
+ * The one thing the sandbox may change about the generated project: where its imports resolve.
+ * `@ultimat3/*` points at workspace source instead of a published tarball, and the app's own
+ * workspace packages resolve without a `bun install` that a sealed test could never run.
+ */
+const overlay = (root: string, app: string): string =>
+  `${JSON.stringify(
+    {
+      extends: './tsconfig.json',
+      compilerOptions: {
+        noEmit: true,
+        paths: {
+          '@ultimat3/*': [`${root}/packages/*/src`],
+          [`@${app}/web/*`]: ['./apps/web/*'],
+          [`@${app}/admin/*`]: ['./apps/admin/*'],
+          [`@${app}/*`]: ['./packages/*/src'],
+        },
+      },
+    },
+    null,
+    2,
+  )}\n`;
+
+export interface TypecheckOptions {
+  readonly files?: readonly GeneratedFile[];
+  readonly app?: string;
+  readonly runner?: Runner;
+  /** Leave the sandbox on disk. For debugging a red gate by hand, never for the gate itself. */
+  readonly keep?: boolean;
+}
+
+export interface TypecheckReport {
+  readonly dir: string;
+  readonly fileCount: number;
+  readonly diagnostics: readonly TypeDiagnostic[];
+  readonly output: string;
+}
+
+/**
+ * `GeneratedFile.path` is documented as relative-POSIX, not enforced as it. A `..` segment would
+ * put template output on the developer's real disk, so the sandbox proves containment before it
+ * writes rather than after.
+ */
+export function sandboxPath(dir: string, path: string): string {
+  const target = resolve(dir, path);
+  if (target !== dir && !target.startsWith(`${dir}${sep}`))
+    throw new ScaffoldPathEscapeError({ path, dir });
+  return target;
+}
+
+export async function typecheckScaffold(options: TypecheckOptions = {}): Promise<TypecheckReport> {
+  const root = workspaceRoot();
+  const app = options.app ?? FIXTURE_APP;
+  const files = options.files ?? scaffoldFixture();
+  const dir = mkdtempSync(join(tmpdir(), 'x-scaffold-'));
+  try {
+    for (const file of files) await Bun.write(sandboxPath(dir, file.path), file.contents);
+    // The sandbox borrows the workspace's installed dependencies. The gate is about the
+    // templates; whether a registry install succeeds is a different question, and a sealed
+    // test cannot ask it.
+    symlinkSync(join(root, 'node_modules'), join(dir, 'node_modules'), 'dir');
+    await Bun.write(join(dir, OVERLAY), overlay(root, app));
+    const result = await (options.runner ?? exec)(
+      [join(root, 'node_modules', '.bin', 'tsc'), '--noEmit', '--pretty', 'false', '-p', OVERLAY],
+      { cwd: dir },
+    );
+    const output = [result.stdout, result.stderr].filter((part) => part.length > 0).join('\n');
+    return { dir, fileCount: files.length, diagnostics: parseDiagnostics(output), output };
+  } finally {
+    if (options.keep !== true) rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** One diagnostic per line, in the shape `tsc` prints — a failed gate is a runnable bug report. */
+export const formatDiagnostics = (diagnostics: readonly TypeDiagnostic[]): string =>
+  diagnostics
+    .map((entry) =>
+      entry.file === ''
+        ? `error ${entry.code}: ${entry.message}`
+        : `${entry.file}:${entry.line} ${entry.code}: ${entry.message}`,
+    )
+    .join('\n');

package/src/source-files.ts

@@ -0,0 +1,38 @@
+// Where a repo's shipped source lives, in both shapes the gate runs against: a package monorepo
+// and an app. One list for every step that walks source, because two steps scanning different sets
+// means a finding one of them can never see.
+
+export const SOURCE_GLOBS = [
+  'packages/*/src/**/*.{ts,tsx}',
+  'scripts/**/*.{ts,tsx}',
+  'site/**/*.{ts,tsx}',
+  'app/**/*.{ts,tsx}',
+  'api/**/*.{ts,tsx}',
+  'shared/**/*.{ts,tsx}',
+  'apps/*/{app,site,api,shared}/**/*.{ts,tsx}',
+] as const;
+
+/**
+ * A nested example app under `examples/` is not scanned — it runs this same gate from its own
+ * root. `dist/` is build output: the sources that produced it are already in the set.
+ */
+export const isVendored = (path: string): boolean =>
+  path.includes('node_modules') || path.includes('/dist/') || path.startsWith('dist/');
+
+/** Emitted declarations, not authored source — a rule about authored code cannot apply to them. */
+export const isGenerated = (path: string): boolean => path.endsWith('.d.ts');
+
+/** Every opt-in suffix (`*.{contract,live,job,eval,e2e}.test.ts`) still ends `.test.ts`. */
+export const isTest = (path: string): boolean => /\.test\.tsx?$/.test(path);
+
+/** Every source file under `root`, repo-relative and deduplicated across the globs. */
+export async function* eachSourceFile(root: string): AsyncGenerator<string> {
+  const seen = new Set<string>();
+  for (const pattern of SOURCE_GLOBS) {
+    for await (const path of new Bun.Glob(pattern).scan({ cwd: root, absolute: false })) {
+      if (isVendored(path) || seen.has(path)) continue;
+      seen.add(path);
+      yield path;
+    }
+  }
+}

package/src/table.ts

@@ -0,0 +1,19 @@
+// The one fixed-width table renderer the introspection commands share. Column widths come from
+// the content, so output diffs cleanly between runs — and every `list` subcommand lines up the
+// same way, which is the whole reason it is one function and not one per command.
+
+/** Header row plus body rows, each padded to the widest cell in its column. */
+export function renderTable(
+  header: readonly string[],
+  rows: readonly (readonly string[])[],
+): readonly string[] {
+  const widths = header.map((title, index) =>
+    Math.max(title.length, ...rows.map((row) => (row[index] ?? '').length)),
+  );
+  const line = (cells: readonly string[]): string =>
+    cells
+      .map((value, index) => value.padEnd(widths[index] ?? 0))
+      .join('  ')
+      .trimEnd();
+  return [line(header), ...rows.map(line)];
+}

package/src/tasks-facts.ts

@@ -0,0 +1,113 @@
+// Pure fact-gathering behind `x tasks`: registered task descriptors plus their next
+// occurrence(s), computed from `@ultimat3/time`'s cron math against an injected `nowMs` — never
+// the wall clock — so a test drives every DST edge with no CLI parsing and no rendering involved.
+
+import type { TaskDescriptor, TaskHandle } from '@ultimat3/jobs';
+import { getTask, registeredTasks } from '@ultimat3/jobs';
+import type { CronPhrases } from '@ultimat3/time';
+import {
+  describeCron,
+  fromEpochMs,
+  nextCronOccurrenceMs,
+  offsetLabel,
+  toZoned,
+} from '@ultimat3/time';
+import { BadFlagError } from './errors';
+
+const DEFAULT_COUNT = 5;
+const MAX_COUNT = 50;
+
+const pad2 = (value: number): string => String(value).padStart(2, '0');
+
+/**
+ * ISO-8601 rendered with the ZONE's OWN offset (`2026-03-08T03:00:00-04:00`), never collapsed to
+ * UTC `Z` — an ambient zone is exactly the bug a task's `tz` exists to prevent. No single
+ * "instant in a zone, as ISO" export exists in `@ultimat3/time` to call instead: `toIso` is
+ * 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.
+ */
+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)}`;
+  return `${date}T${time}${offsetLabel(zoned.offsetMinutes)}`;
+}
+
+/** `x tasks list` row: the descriptor plus the next occurrence, ms and rendered alike. */
+export interface TaskFact extends TaskDescriptor {
+  readonly nextMs: number;
+  readonly next: string;
+}
+
+function toFact(handle: TaskHandle, nowMs: number): TaskFact {
+  const descriptor = handle.describe();
+  const nextMs = nextCronOccurrenceMs(descriptor.cron, descriptor.tz, nowMs);
+  return { ...descriptor, nextMs, next: isoInZone(nextMs, descriptor.tz) };
+}
+
+export function listTaskFacts(nowMs: number): readonly TaskFact[] {
+  return registeredTasks().map((handle) => toFact(handle, nowMs));
+}
+
+export function knownTaskNames(): readonly string[] {
+  return registeredTasks().map((handle) => handle.name);
+}
+
+export function findTaskHandle(name: string): TaskHandle | undefined {
+  return getTask(name);
+}
+
+/**
+ * `--count` for `x tasks show`: how many upcoming occurrences to compute. Default 5, clamped to
+ * 50 — unbounded would let one `* * * * *` task turn a single command into an unbounded response.
+ * Anything that is not a positive integer is refused rather than coerced, same idiom as
+ * `parseLimitFlag` in `jobs-report.ts`: past `Number.MAX_SAFE_INTEGER` or with a fractional part,
+ * "the number typed" and "the number used" would silently differ.
+ */
+export function parseCountFlag(value: string | undefined): number {
+  if (value === undefined) return DEFAULT_COUNT;
+  const digits = value.trim();
+  const parsed = /^\d+$/.test(digits) ? Number(digits) : Number.NaN;
+  if (!Number.isSafeInteger(parsed) || parsed < 1) {
+    throw new BadFlagError({
+      flag: 'count',
+      command: 'tasks',
+      reason: `expects a positive integer, got "${value}"`,
+    });
+  }
+  return Math.min(parsed, MAX_COUNT);
+}
+
+export interface TaskOccurrence {
+  readonly ms: number;
+  readonly at: string;
+}
+
+/** `x tasks show <name>`: the descriptor, the human cron phrase, and the next `count` firings. */
+export interface TaskShowFacts {
+  readonly descriptor: TaskDescriptor;
+  readonly describe: string;
+  readonly upcoming: readonly TaskOccurrence[];
+}
+
+/**
+ * `phrases` is a parameter for the same reason `describeCron` demands one: this module owns cron
+ * math, not words, and a vocabulary hardcoded here would be a second catalog the CLI's own
+ * `messages.ts` could never translate. The caller supplies it — `cmd-tasks.ts` from `cli.cron.*`.
+ */
+export function taskShowFacts(
+  handle: TaskHandle,
+  nowMs: number,
+  count: number,
+  phrases: CronPhrases,
+): TaskShowFacts {
+  const descriptor = handle.describe();
+  const upcoming: TaskOccurrence[] = [];
+  let cursor = nowMs;
+  for (let i = 0; i < count; i += 1) {
+    cursor = nextCronOccurrenceMs(descriptor.cron, descriptor.tz, cursor);
+    upcoming.push({ ms: cursor, at: isoInZone(cursor, descriptor.tz) });
+  }
+  return { descriptor, describe: describeCron(descriptor.cron, 'en-US', phrases), upcoming };
+}

package/src/templates/action.ts

@@ -0,0 +1,193 @@
+// `x g action` / `x g mutator` — a server-authoritative command, its policy, and the test that
+// pins both. One declaration projects to an HTTP route, an OpenAPI operation, a typed client, a
+// job handle, an MCP tool and these tests; the generator writes the declaration and the tests.
+
+import type { FeatureTarget } from './entity';
+import type { GeneratedFile, NameSet } from './naming';
+import { names } from './naming';
+
+const actionSource = (
+  name: NameSet,
+  feature: NameSet,
+): string => `// ${name.camel}: one mutation, server-authoritative. Input is validated before the handler runs
+// and the policy is the same object the MCP tool and the HTTP route evaluate.
+// \`t\` comes from @ultimat3/action, not @ultimat3/schema: an action file imports one package.
+
+import { action, t } from '@ultimat3/action';
+// One directory up: actions live in \`actions/\`, the feature's errors, policy and repo are the
+// slice's own files and are shared by every action in it.
+
+import { ${feature.pascal}NotFoundError } from '../errors';
+import { can${feature.pascal}Write, ${feature.camel}Tag } from '../policy';
+import * as repo from '../repo';
+
+export const ${name.camel} = action({
+  // orgId is part of the input because the policy decides on it — authz reads the declaration,
+  // never the database.
+  input: t.object({ id: t.uuid, orgId: t.uuid }),
+  output: t.object({ id: t.uuid, title: t.string }),
+  policy: can${feature.pascal}Write,
+  cache: { invalidates: [${feature.camel}Tag] },
+  mcp: { expose: true, description: '${name.raw} — generated, edit the description' },
+  async handle({ input }) {
+    const row = await repo.byId(input.id);
+    if (row === undefined) throw new ${feature.pascal}NotFoundError({ id: input.id });
+    return { id: row.id, title: row.title };
+  },
+});
+`;
+
+const mutatorSource = (
+  name: NameSet,
+  feature: NameSet,
+): string => `// ${name.camel}: an action with an optimistic local twin. The local half runs against the client
+// store immediately; the server half is authoritative and reconciles on conflict.
+
+import { mutator, t } from '@ultimat3/action';
+import { ${feature.pascal}NotFoundError } from '../errors';
+import { can${feature.pascal}Write } from '../policy';
+import * as repo from '../repo';
+
+interface Local${feature.pascal} {
+  readonly id: string;
+  readonly title: string;
+  readonly pending: boolean;
+}
+
+export const ${name.camel} = mutator({
+  input: t.object({ id: t.uuid, orgId: t.uuid, title: t.string }),
+  output: t.object({ id: t.uuid, title: t.string }),
+  policy: can${feature.pascal}Write,
+  mcp: { expose: true, description: '${name.raw} — generated, edit the description' },
+  // tx.table(name) rather than tx.${feature.plural}: the typed accessor exists only once the app
+  // augments LocalTables, and generated code cannot assume that has happened yet. The name is the
+  // entity's snake_case table, so the local twin and the server row live under one key.
+  local(tx, input) {
+    tx.table<Local${feature.pascal}>('${feature.table}').update(input.id, {
+      title: input.title,
+      pending: true,
+    });
+  },
+  async server(_ctx, input) {
+    const row = await repo.byId(input.id);
+    if (row === undefined) throw new ${feature.pascal}NotFoundError({ id: input.id });
+    return { id: row.id, title: input.title };
+  },
+  conflict: 'server-wins',
+});
+`;
+
+const errorsSource = (
+  feature: NameSet,
+): string => `// The ${feature.kebab} feature's X_* codes. Never throw a bare Error: an agent reading the failure
+// needs the code, the cause and the exact command that fixes it.
+
+import { UltimateError } from '@ultimat3/core';
+
+export class ${feature.pascal}NotFoundError extends UltimateError {
+  constructor(input: { id: string }) {
+    super({
+      code: 'X_${feature.kebab.toUpperCase().split('-').join('_')}_NOT_FOUND',
+      cause: \`no ${feature.kebab} with id \${input.id}\`,
+      fix: 'x db studio to confirm the row exists, or pass an id from the list query',
+      docs: 'https://ultimate.dev/errors/X_NOT_FOUND',
+    });
+  }
+}
+`;
+
+const ID = '00000000-0000-4000-8000-000000000001';
+const ORG = '00000000-0000-4000-8000-000000000002';
+const OTHER_ORG = '00000000-0000-4000-8000-000000000009';
+
+/** The declaration-shape assertions that differ between the two primitives. */
+const shapeTest = (name: NameSet, isMutator: boolean): string =>
+  isMutator
+    ? `unitTest('${name.camel} projects both halves and a conflict strategy', () => {
+  // The projected names mirror the declaration: local() optimistic, server() authoritative.
+  // server() routes through the same invoke() core as every other surface, so it cannot skip
+  // the input parse, the policy or the output parse.
+  expect(target.describeMutator().kind).toBe('mutator');
+  expect(target.conflict).toBe('server-wins');
+  expect(typeof target.local).toBe('function');
+  expect(typeof target.server).toBe('function');
+});`
+    : `unitTest('${name.camel} is a declared action', () => {
+  expect(target.kind).toBe('action');
+  expect(target.describe().name).toBe('${name.camel}');
+});`;
+
+const actionTest = (
+  name: NameSet,
+  feature: NameSet,
+  isMutator: boolean,
+): string => `import { testActor } from '@ultimat3/policy';
+import { contractTest, expect, unitTest } from '@ultimat3/testing';
+import { ${name.camel} } from './${name.kebab}';
+
+const id = '${ID}';
+const orgId = '${ORG}';
+const input = { id, orgId${isMutator ? ", title: 'a title'" : ''} };
+
+// 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, wrong org. That is the interesting actor: a denial here is the predicate
+// deciding, not the permission check, so this test fails if the tenancy rule is ever dropped.
+const outsider = testActor('outsider', {
+  orgId: '${OTHER_ORG}',
+  permissions: ['${feature.kebab}:write'],
+}).actor;
+
+${shapeTest(name, 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);
+});
+
+contractTest('${name.camel} passes the contract every action owes', async () => {
+  // Three assertions the framework makes for any action, without knowing what this one does:
+  // garbage input is rejected, an anonymous actor is denied, and the operation reaches the
+  // OpenAPI document. \`.contract()\` is the projection; this loop just runs it.
+  for (const contract of target.contract()) await contract.run();
+});
+
+contractTest('${name.camel} denies a foreign org before the handler runs', async () => {
+  // \`.as()\` is the one execution path with the actor swapped, so this denial is the same one
+  // HTTP, MCP and the job surface would produce — and no repo call happened to produce it.
+  const denied = await target.as(outsider, input).catch((error: unknown) => error);
+  expect(denied).toBeUltimateError('X_FORBIDDEN');
+});
+
+contractTest('${name.camel} projects one MCP tool and one OpenAPI operation', () => {
+  // Same policy object on both surfaces — an MCP call cannot reach a different authz path.
+  expect(target.tool().policy).toBe(target.policy);
+  expect(target.tool().description).not.toBe('');
+  expect(target.openapi().operationId).toBe('${name.camel}');
+});
+`;
+
+export interface ActionOptions extends FeatureTarget {
+  readonly mutator?: boolean;
+}
+
+export function actionFiles(rawName: string, target: ActionOptions): readonly GeneratedFile[] {
+  const name = names(rawName);
+  const feature = names(target.feature);
+  const dir = `${target.surfaceDir}/${target.feature}/actions`;
+  const isMutator = target.mutator === true;
+  return [
+    {
+      path: `${dir}/${name.kebab}.ts`,
+      contents: isMutator ? mutatorSource(name, feature) : actionSource(name, feature),
+    },
+    { path: `${dir}/${name.kebab}.test.ts`, contents: actionTest(name, feature, isMutator) },
+    {
+      path: `${target.surfaceDir}/${target.feature}/errors.ts`,
+      contents: errorsSource(feature),
+    },
+  ];
+}

package/src/templates/admin.ts

@@ -0,0 +1,46 @@
+// `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`.
+
+import type { FeatureTarget } from './entity';
+import type { GeneratedFile, NameSet } from './naming';
+import { names } from './naming';
+
+const resourceSource = (
+  feature: NameSet,
+): string => `// Admin override for ${feature.pluralKebab}. Everything not set here — fields, operations,
+// detail layout — is derived from the entity. Wire this in once:
+//   import { ${feature.camel}AdminResource } from '${'@'}app/web/app/${feature.kebab}/admin/resource';
+//   defineAdmin({ entities: [..., ${feature.camel}], resources: { ${feature.table}: ${feature.camel}AdminResource } })
+
+import type { AdminResourceOptions, AdminRow } from '@ultimat3/admin';
+
+export const ${feature.camel}AdminResource: AdminResourceOptions<AdminRow> = {
+  titleKey: 'admin.${feature.kebab}.title',
+  listFields: ['id', 'title', 'createdAt'],
+  pageSize: 25,
+};
+`;
+
+const resourceTest = (
+  feature: NameSet,
+): string => `import { expect, unitTest } from '@ultimat3/testing';
+import { ${feature.camel}AdminResource } from './resource';
+
+unitTest('${feature.camel}AdminResource sets a title key and bounded list fields', () => {
+  expect(${feature.camel}AdminResource.titleKey).toBe('admin.${feature.kebab}.title');
+  expect(${feature.camel}AdminResource.listFields?.length).toBeGreaterThan(0);
+  expect(${feature.camel}AdminResource.pageSize).toBeGreaterThan(0);
+});
+`;
+
+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.test.ts`, contents: resourceTest(feature) },
+  ];
+}

package/src/templates/catalog-json.ts

@@ -0,0 +1,17 @@
+// The one renderer for a generated `packages/i18n/catalogs/<locale>.json`. Every generator that
+// contributes keys goes through it, so no template hand-writes catalog JSON and none of them can
+// emit the flat dot-key form `@ultimat3/i18n` refuses.
+
+import { nestCatalog } from '@ultimat3/i18n';
+
+/**
+ * `{ 'site.home.title': 'Home' }` → the nested JSON a catalog file actually holds.
+ *
+ * Load-bearing, not cosmetic: `parseNestedCatalog` validates every key segment against
+ * `/^[A-Za-z0-9_-]+$/`, so a dot inside a key is `X_CATALOG_INVALID` and a catalog written flat
+ * fails `defineCatalogs` at boot — the app never starts. Templates author in the flat form because
+ * that is how a key reads at the `t('site.home.title')` call site; `nestCatalog` is the framework's
+ * own inverse of the flatten every read does, so the two forms cannot drift.
+ */
+export const catalogJson = (entries: Readonly<Record<string, string>>): string =>
+  `${JSON.stringify(nestCatalog(entries), null, 2)}\n`;