@ultimat3/cli 1.0.0

package/src/templates/entity.ts

@@ -0,0 +1,157 @@
+// `x g entity <name>` — a table, its domain type and its invariants, plus the repo that owns the
+// only DB access for the feature. Emitted as strings rather than copied fixture files so the
+// generator output is typed, diffable and testable from a unit test.
+
+import type { GeneratedFile, NameSet } from './naming';
+import { names } from './naming';
+
+export interface FeatureTarget {
+  /** `apps/web/app` or `apps/web/site` — the surface the feature lives in. */
+  readonly surfaceDir: string;
+  readonly feature: string;
+}
+
+const entitySource = (
+  name: NameSet,
+  snake: string,
+  table: string,
+): string => `// The ${name.camel} table, its domain type and its invariants. No I/O beyond the column
+// definitions: repo.ts owns every query that touches this table.
+
+import { entity, invariant, money, text, timestamp, uuid } from '@ultimat3/entity';
+
+export const ${name.camel} = entity('${table}', {
+  // Naming the tenant column is what turns tenancy on: a read without an org predicate then
+  // fails with X_TENANCY_UNSCOPED instead of leaking another org's rows.
+  tenant: 'orgId',
+  columns: {
+    id: uuid().primaryKey(),
+    orgId: uuid(),
+    title: text({ max: 200 }),
+    // One property, two physical columns: price_minor bigint + price_currency char(3).
+    // Money is integer minor units plus an ISO code, never a float.
+    price: money(),
+    // Always timestamptz. Stored UTC; formatted at the edge with an explicit IANA time zone.
+    createdAt: timestamp().defaultNow(),
+  },
+  // Each rule runs in the app on write AND as a Postgres CHECK — one declaration, both sides.
+  invariants: [
+    invariant('${snake}_title_not_blank', (c) => c.title.trimmed().minLength(1)),
+    invariant('${snake}_price_non_negative', (c) => c.price.minor.atLeast(0)),
+  ],
+  indexes: [{ on: ['orgId', 'createdAt'] }],
+});
+
+export type ${name.pascal} = typeof ${name.camel}.$row;
+
+// What leaves the server: an action writes \`output: ${name.pascal}View\` and the shape is the
+// columns', never a second declaration to keep in sync. The tenant column is not in it — an org
+// id is the caller's context, not the client's data.
+export const ${name.pascal}View = ${name.camel}.$view(['id', 'title', 'price', 'createdAt']);
+export type ${name.pascal}View = typeof ${name.pascal}View.$row;
+`;
+
+const repoSource = (
+  name: NameSet,
+  table: string,
+): string => `// The only module allowed to query the ${name.pluralKebab} table. Routes call actions and
+// queries; actions call services; services call this.
+// \`db()\` is the ambient handle: inside a transaction it IS the transaction, so these functions
+// join the caller's transaction without knowing one is open.
+
+import { db, sql } from '@ultimat3/db';
+import { dbDrift, newId } from '@ultimat3/entity';
+import type { ${name.pascal} } from './entity';
+
+export async function byId(id: string): Promise<${name.pascal} | undefined> {
+  const row = await db().one<${name.pascal}>(sql\`select * from ${table} where id = \${id}\`);
+  return row ?? undefined;
+}
+
+export async function listByOrg(orgId: string, limit = 50): Promise<readonly ${name.pascal}[]> {
+  // Ordered and bounded: an unordered page is a different page on every request.
+  return db().query<${name.pascal}>(
+    sql\`select * from ${table} where org_id = \${orgId} order by created_at desc limit \${limit}\`,
+  );
+}
+
+export async function insert(row: Omit<${name.pascal}, 'id' | 'createdAt'>): Promise<${name.pascal}> {
+  // Money is two physical columns — integer minor units plus the ISO code, never a float.
+  const created = await db().one<${name.pascal}>(sql\`
+    insert into ${table} (id, org_id, title, price_minor, price_currency)
+    values (\${newId()}, \${row.orgId}, \${row.title}, \${row.price.minor}, \${row.price.currency})
+    returning *\`);
+  if (created === null) throw dbDrift('${table}', 'id');
+  return created;
+}
+`;
+
+const entityTest = (
+  name: NameSet,
+  snake: string,
+  table: string,
+): string => `import { expect, unitTest } from '@ultimat3/testing';
+import type { ${name.pascal} } from './entity';
+import { ${name.pascal}View, ${name.camel} } from './entity';
+
+const row = (over: Partial<${name.pascal}> = {}): ${name.pascal} => ({
+  id: '00000000-0000-4000-8000-000000000001',
+  orgId: '00000000-0000-4000-8000-000000000002',
+  title: 'valid title',
+  // \`money()\` puts \`MoneyValue\` on the row, whose minor units are bigint — the column is a
+  // Postgres bigint, and a JS number would silently lose precision above 2^53 minor units.
+  price: { minor: 1000n, currency: 'USD' },
+  createdAt: new Date(0),
+  ...over,
+});
+
+unitTest('${name.camel} declares a table with invariants', () => {
+  expect(${name.camel}.$name).toBe('${table}');
+  expect(${name.camel}.$tenantColumn).toBe('orgId');
+  const named = ${name.camel}.$invariants.map((rule) => rule.name);
+  expect(named).toContain('${snake}_title_not_blank');
+});
+
+unitTest('${name.camel} describes itself for the manifest', () => {
+  // \`$describe()\` is what x manifest, /_x and the MCP dev tools all read — one projection, so
+  // a column added below reaches every one of them without a second declaration.
+  const described = ${name.camel}.$describe();
+  expect(described.orgScoped).toBe(true);
+  // One \`price\` property, two physical columns: integer minor units plus the ISO code. The
+  // description is where that shows, and it is what fails here if money ever becomes a float.
+  expect(described.columns.map((column) => column.column)).toContain('price_minor');
+  expect(described.columns.map((column) => column.column)).toContain('price_currency');
+  expect(described.invariants.map((rule) => rule.name)).toContain('${snake}_price_non_negative');
+});
+
+unitTest('${name.pascal}View projects the row an action returns, without the tenant', () => {
+  expect(${name.pascal}View.$keys).toEqual(['id', 'title', 'price', 'createdAt']);
+  // The org id is the caller's context, never the client's data: a view that leaked it would
+  // let a response carry a tenant boundary the policy already decided.
+  expect(${name.pascal}View.$keys).not.toContain('orgId');
+});
+
+unitTest('${name.camel} invariants reject a blank title and a negative price', () => {
+  expect(() => ${name.camel}.$assert(row())).not.toThrow();
+  expect(() => ${name.camel}.$assert(row({ title: '   ' }))).toThrow();
+  expect(() => ${name.camel}.$assert(row({ price: { minor: -1n, currency: 'USD' } }))).toThrow();
+});
+
+unitTest('${name.camel} parses a row through its own columns', () => {
+  // \`$parse\` is the entity's own coercion, so a row read back from SQL and a row built in a
+  // test go through the same code — a drifting column type fails here first.
+  const parsed = ${name.camel}.$parse(row());
+  expect(parsed.title).toBe('valid title');
+  expect(parsed.price.currency).toBe('USD');
+});
+`;
+
+export function entityFiles(rawName: string, target: FeatureTarget): readonly GeneratedFile[] {
+  const name = names(rawName);
+  const dir = `${target.surfaceDir}/${target.feature}`;
+  return [
+    { path: `${dir}/entity.ts`, contents: entitySource(name, name.snake, name.table) },
+    { path: `${dir}/entity.test.ts`, contents: entityTest(name, name.snake, name.table) },
+    { path: `${dir}/repo.ts`, contents: repoSource(name, name.table) },
+  ];
+}

package/src/templates/index.ts

@@ -0,0 +1,23 @@
+// Public surface of the template modules. Templates are string modules, not copied fixture files,
+// so `x g` output is typed, reviewable in a diff and testable without touching the filesystem.
+
+export type { ActionOptions } from './action';
+export { actionFiles } from './action';
+export { adminFiles } from './admin';
+export type { FeatureTarget } from './entity';
+export { entityFiles } from './entity';
+export { jobFiles, taskFiles } from './job';
+export { CATALOG_ROOT, catalogPath, DEFAULT_LOCALES, resolveLocales } from './locales';
+export type { GeneratedFile, NameSet } from './naming';
+export { camel, kebab, names, pascal, plural, titleKey } from './naming';
+export { policyFiles } from './policy';
+export type { QueryOptions } from './query';
+export { queryFiles } from './query';
+export type { ResourceOptions } from './resource';
+export { resourceFiles } from './resource';
+export type { RouteOptions, Surface } from './route';
+export { routeFiles } from './route';
+export { appFiles } from './scaffold-app';
+export { docsFiles, EXECUTABLE_FILES } from './scaffold-docs';
+export { i18nIndex } from './scaffold-i18n';
+export { repoFiles } from './scaffold-repo';

package/src/templates/job.ts

@@ -0,0 +1,148 @@
+// `x g job` / `x g task` — durable background work and the cron trigger that enqueues it. The
+// idempotency key is required by the type, so the generator always emits one; the generated test
+// pins it through a real driver, because a key that is not stable is a job that runs twice.
+
+import type { FeatureTarget } from './entity';
+import type { GeneratedFile, NameSet } from './naming';
+import { names } from './naming';
+
+const jobSource = (
+  name: NameSet,
+): string => `// ${name.camel}: multi-step durable work. Each step is retried independently and its result is
+// stored under its name — step names are stable identifiers, not labels.
+// \`t\` comes from @ultimat3/jobs, not @ultimat3/schema: a job file imports one package.
+
+import { job, t } from '@ultimat3/jobs';
+import * as repo from '../repo';
+
+export const ${name.camel} = job({
+  input: t.object({ id: t.uuid }),
+  idempotencyKey: ({ id }) => \`${name.kebab}:\${id}\`,
+  retry: { attempts: 5, backoff: 'exponential' },
+  async run({ input, step }) {
+    const row = await step.run('load', () => repo.byId(input.id));
+    if (row === undefined) return { skipped: true };
+    await step.run('process', async () => {
+      await repo.listByOrg(row.orgId, 1);
+    });
+    return { skipped: false };
+  },
+});
+`;
+
+const taskSource = (
+  name: NameSet,
+  jobName: NameSet,
+): string => `// ${name.camel}: a scheduled trigger. Tasks only enqueue jobs — the work itself is durable and
+// retryable, and the schedule carries an explicit IANA time zone.
+
+import { task } from '@ultimat3/jobs';
+import { ${jobName.camel} } from '../jobs/${jobName.kebab}';
+
+export const ${name.camel} = task({
+  cron: '0 3 * * *',
+  tz: 'UTC',
+  enqueue: () => [[${jobName.camel}, { id: '00000000-0000-4000-8000-000000000001' }]],
+});
+`;
+
+const jobTest = (
+  name: NameSet,
+): string => `import { createMemoryDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
+import { afterAll, beforeAll, expect, jobTest } from '@ultimat3/testing';
+import { ${name.camel} } from './${name.kebab}';
+
+const id = '00000000-0000-4000-8000-000000000001';
+
+// The driver is process-global, so it is installed and released around this file rather than
+// left behind for whichever test happens to run next.
+beforeAll(() => {
+  setJobDriver(createMemoryDriver());
+});
+afterAll(resetJobDriver);
+
+jobTest('${name.camel} declares an idempotency key and a retry policy', () => {
+  expect(${name.camel}.kind).toBe('job');
+  expect(${name.camel}.idempotencyKeyFor({ id })).toBe(\`${name.kebab}:\${id}\`);
+  expect(${name.camel}.retry.attempts).toBeGreaterThan(1);
+});
+
+jobTest('${name.camel} derives the same key for the same input', () => {
+  expect(${name.camel}.idempotencyKeyFor({ id })).toBe(${name.camel}.idempotencyKeyFor({ id }));
+});
+
+jobTest('${name.camel} projects itself into the manifest', () => {
+  const described = ${name.camel}.describe();
+  expect(described.queue).toBe('default');
+  expect(described.retry.attempts).toBe(5);
+});
+
+jobTest('${name.camel} enqueues once, and dedupes the retry', async () => {
+  // The whole point of the key: an at-least-once caller may enqueue twice and the work still
+  // happens once. \`.enqueue()\` is the one queue path — a job is never run inline.
+  const first = await ${name.camel}.enqueue({ id });
+  expect(first.deduped).toBe(false);
+  const again = await ${name.camel}.enqueue({ id });
+  expect(again.deduped).toBe(true);
+});
+`;
+
+const taskTest = (
+  name: NameSet,
+  jobName: NameSet,
+): string => `import { createMemoryDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
+import { afterAll, beforeAll, expect, jobTest } from '@ultimat3/testing';
+import { ${jobName.camel} } from '../jobs/${jobName.kebab}';
+import { ${name.camel} } from './${name.kebab}';
+
+beforeAll(() => {
+  setJobDriver(createMemoryDriver());
+});
+afterAll(resetJobDriver);
+
+jobTest('${name.camel} declares a cron with an explicit time zone', () => {
+  expect(${name.camel}.kind).toBe('task');
+  expect(${name.camel}.cron.split(' ')).toHaveLength(5);
+  expect(${name.camel}.tz).toBe('UTC');
+});
+
+jobTest('${name.camel} enqueues ${jobName.camel} and nothing else', () => {
+  const pairs = ${name.camel}.entries();
+  expect(pairs).toHaveLength(1);
+  expect(pairs[0]?.[0]).toBe(${jobName.camel});
+});
+
+jobTest('${name.camel} describes its schedule and its jobs', () => {
+  const described = ${name.camel}.describe();
+  expect(described.tz).toBe('UTC');
+  expect(described.jobs).toHaveLength(1);
+});
+
+jobTest('${name.camel} fires its entries onto the same queue the scheduler would', async () => {
+  // \`.enqueue()\` is the backfill path: the declared entries, through the facade a job handle
+  // uses, with no scheduler and no leader involved.
+  const results = await ${name.camel}.enqueue();
+  expect(results).toHaveLength(1);
+  expect(results[0]?.job).toBe(${jobName.camel}.name);
+});
+`;
+
+export function jobFiles(rawName: string, target: FeatureTarget): readonly GeneratedFile[] {
+  const name = names(rawName);
+  const dir = `${target.surfaceDir}/${target.feature}/jobs`;
+  return [
+    { path: `${dir}/${name.kebab}.ts`, contents: jobSource(name) },
+    { path: `${dir}/${name.kebab}.test.ts`, contents: jobTest(name) },
+  ];
+}
+
+export function taskFiles(rawName: string, target: FeatureTarget): readonly GeneratedFile[] {
+  const name = names(rawName);
+  const jobName = names(`${rawName}-job`);
+  const dir = `${target.surfaceDir}/${target.feature}/tasks`;
+  return [
+    { path: `${dir}/${name.kebab}.ts`, contents: taskSource(name, jobName) },
+    { path: `${dir}/${name.kebab}.test.ts`, contents: taskTest(name, jobName) },
+    ...jobFiles(`${rawName}-job`, target),
+  ];
+}

package/src/templates/locales.ts

@@ -0,0 +1,93 @@
+// The one locale resolver for generated catalogs: the default set, validation, canonical form and
+// dedupe. A locale is not a label here, it is a file stem — `packages/i18n/catalogs/<locale>.json`
+// — so an unvalidated tag is a path, and `--locales=../../../../tmp` would write outside the app.
+
+import { BadFlagError, ScaffoldPathEscapeError } from '../errors';
+
+/** What a generated catalog ships for when the caller names no locale. */
+export const DEFAULT_LOCALES: readonly string[] = ['en'];
+
+/** Where every generated catalog lands. The locale is the file's stem, hence the containment. */
+export const CATALOG_ROOT = 'packages/i18n/catalogs';
+
+/** The catalog layout, written down once: `x g route` and `x g resource` both merge into it. */
+export const catalogPath = (locale: string): string => `${CATALOG_ROOT}/${locale}.json`;
+
+/** The runnable form of the flag, used as the fix on every rejection below. */
+const LOCALES_FIX = 'x g resource <name> --locales=en,es';
+
+/**
+ * Anything that could steer a write out of `CATALOG_ROOT`. A path segment is safe exactly when it
+ * holds no separator, no NUL and is not a dot segment, so this is a complete check at this level —
+ * `writeFiles` proves containment again on the assembled path.
+ */
+const escapesCatalogRoot = (tag: string): boolean =>
+  tag.startsWith('.') || tag.includes('/') || tag.includes('\\') || tag.includes('\0');
+
+/**
+ * The repo's own definition of a BCP-47 tag — the predicate `defineConfig` validates `locales`
+ * with. `Intl` canonicalizes (`EN` → `en`, `zh-Hant` stays) and throws on anything that is not a
+ * tag, which is why `x-priv`, `en_US` and `1234` never reach the filesystem.
+ */
+const canonicalTag = (tag: string): string | undefined => {
+  try {
+    const canonical = Intl.getCanonicalLocales(tag);
+    return canonical.length === 1 ? canonical[0] : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * The invocation a rejection is reported against. `x g --locales=…` is not the only caller —
+ * `x i18n add <locale>` reaches this same validator — and a cause naming a command and a flag the
+ * user never typed is the misdirection axiom 4 exists to refuse.
+ */
+export interface LocaleFlagContext {
+  /** The runnable fix printed on a rejection. Defaults to the `x g` form. */
+  readonly fix?: string;
+  /** The command as typed, without the `x`. */
+  readonly command?: string;
+  /** The flag or argument the locale arrived on. */
+  readonly flag?: string;
+}
+
+/**
+ * Every locale a generated catalog ships for: trimmed, validated, lowercased and deduped, or the
+ * default when the caller names none. Loud rather than lenient — a typo silently resolved to `en`
+ * writes a catalog the app never reads, and a traversal silently dropped writes one it never sees.
+ */
+export function resolveLocales(
+  requested?: readonly string[],
+  // A bare string is still the fix, so every `x g` call site reads exactly as it did.
+  context: string | LocaleFlagContext = LOCALES_FIX,
+): readonly string[] {
+  if (requested === undefined) return DEFAULT_LOCALES;
+  const options: LocaleFlagContext = typeof context === 'string' ? { fix: context } : context;
+  const fix = options.fix ?? LOCALES_FIX;
+  const command = options.command ?? 'g';
+  const flag = options.flag ?? 'locales';
+  const resolved: string[] = [];
+  for (const raw of requested) {
+    const tag = raw.trim();
+    // `--locales=en,,es` is a typing artefact, not a request for a nameless catalog.
+    if (tag.length === 0) continue;
+    if (escapesCatalogRoot(tag)) {
+      throw new ScaffoldPathEscapeError({ path: `${CATALOG_ROOT}/${tag}`, dir: CATALOG_ROOT, fix });
+    }
+    const canonical = canonicalTag(tag);
+    if (canonical === undefined) {
+      throw new BadFlagError({
+        flag,
+        command,
+        reason: `"${tag}" is not a BCP-47 locale`,
+        fix,
+      });
+    }
+    // Lowercase, because the tag is a file stem: `en-US.json` and `en-us.json` are one file on a
+    // case-insensitive filesystem, and `zh-hant` is the normalized form @ultimat3/i18n resolves to.
+    const stem = canonical.toLowerCase();
+    if (!resolved.includes(stem)) resolved.push(stem);
+  }
+  return resolved.length === 0 ? DEFAULT_LOCALES : resolved;
+}

package/src/templates/naming.ts

@@ -0,0 +1,97 @@
+// Name derivation for generators. One place, because `x g resource post` has to agree with itself
+// across eight emitted files — a second casing helper is how `Post`/`post`/`posts` drift apart.
+
+/**
+ * A catalog is one file per locale that many generators contribute keys to; a whole-file write
+ * would delete every key already in it, so a `'json'` file merges instead of overwriting. Always
+ * text: `cmd-generate.ts`'s `dedupe`/`mergeJsonFile` parse and merge `contents` as a JSON object,
+ * a step that only ever runs against this variant.
+ */
+export interface GeneratedJsonFile {
+  /** POSIX path relative to the app root. */
+  readonly path: string;
+  readonly contents: string;
+  readonly merge: 'json';
+}
+
+/**
+ * Every other generated file. Text in almost every case, but the scaffolded app icon is bytes,
+ * not prose: a PNG cannot survive a UTF-8 string round-trip (every byte above 0x7F comes back
+ * mangled), so `contents` has to admit raw bytes too — `Bun.write` already accepts either, so
+ * nothing downstream needs a second write path.
+ */
+export interface GeneratedSourceFile {
+  /** POSIX path relative to the app root. */
+  readonly path: string;
+  readonly contents: string | Uint8Array;
+  readonly merge?: undefined;
+}
+
+/**
+ * Split on `merge` rather than widening one shape's `contents` in place, so the split is
+ * load-bearing, not cosmetic: a `merge: 'json'` file's `contents` stays a plain `string` at the
+ * type level, which is what stops a byte-carrying file from ever reaching
+ * `cmd-generate.ts`'s JSON parser — the compiler refuses the call before the code can run.
+ */
+export type GeneratedFile = GeneratedJsonFile | GeneratedSourceFile;
+
+const words = (input: string): readonly string[] =>
+  input
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .split(/[^a-zA-Z0-9]+/)
+    .filter((part) => part.length > 0)
+    .map((part) => part.toLowerCase());
+
+export const kebab = (input: string): string => words(input).join('-');
+
+export const camel = (input: string): string =>
+  words(input)
+    .map((word, index) => (index === 0 ? word : `${word[0]?.toUpperCase() ?? ''}${word.slice(1)}`))
+    .join('');
+
+export const pascal = (input: string): string => {
+  const value = camel(input);
+  return (value[0]?.toUpperCase() ?? '') + value.slice(1);
+};
+
+/** Deliberately naive: English -s/-es/-ies. A generator name is one word in practice. */
+export const plural = (input: string): string => {
+  if (/(s|x|z|ch|sh)$/.test(input)) return `${input}es`;
+  if (/[^aeiou]y$/.test(input)) return `${input.slice(0, -1)}ies`;
+  return `${input}s`;
+};
+
+export const titleKey = (input: string): string => `app.${kebab(input)}.title`;
+
+export interface NameSet {
+  readonly raw: string;
+  readonly kebab: string;
+  readonly camel: string;
+  readonly pascal: string;
+  readonly plural: string;
+  readonly pluralKebab: string;
+  /** Singular snake_case. Constraint and index names. */
+  readonly snake: string;
+  /**
+   * The table identifier: plural snake_case. Derived here rather than at each call site because
+   * the entity, the repo SQL, the query source and the mutator's local table all name the same
+   * table — and Postgres lowercases every unquoted identifier, so a hyphen would have to be
+   * quoted forever.
+   */
+  readonly table: string;
+}
+
+export function names(input: string): NameSet {
+  const base = camel(input);
+  const pluralKebab = kebab(plural(base));
+  return {
+    raw: input,
+    kebab: kebab(input),
+    camel: base,
+    pascal: pascal(input),
+    plural: plural(base),
+    pluralKebab,
+    snake: kebab(input).split('-').join('_'),
+    table: pluralKebab.split('-').join('_'),
+  };
+}

package/src/templates/policy.ts

@@ -0,0 +1,120 @@
+// `x g policy <feature>` — one authz rule set, evaluated identically by the HTTP route, the live
+// query, the job and the MCP tool. Two authz systems is how frameworks die; the generated test
+// pins the denial branch, because a policy that only has passing tests is a policy nobody trusts.
+
+import type { GeneratedFile, NameSet } from './naming';
+import { names } from './naming';
+
+/** Biome would rewrap this itself, so the generator emits the already-formatted form. */
+const permissionSet = (feature: NameSet): string => {
+  const read = `'${feature.kebab}:read'`;
+  const write = `'${feature.kebab}:write'`;
+  const line = `export const ${feature.camel}Permissions = definePermissions([${read}, ${write}]);`;
+  return line.length <= 100
+    ? line
+    : `export const ${feature.camel}Permissions = definePermissions([\n  ${read},\n  ${write},\n]);`;
+};
+
+const policySource = (
+  feature: NameSet,
+): string => `// Authz for the ${feature.kebab} feature. Every branch here is reachable from every surface.
+// Predicates are synchronous on purpose: a live query re-evaluates one per subscriber per patch,
+// so an await here would be a database round trip per row per connected client.
+//
+// A predicate always receives { input, actor, row, ctx }, whichever surface called it. These rules
+// decide on the input, so row is null. A rule about an already-loaded row reads row instead —
+// never reach for a row through input:
+//   can<${feature.pascal}Scope, ${feature.pascal}Row>('${feature.kebab}:write', ({ actor, row }) =>
+//     row?.ownerId === actor?.id)
+
+import { tag } from '@ultimat3/cache';
+import { can, definePermissions } from '@ultimat3/policy';
+
+// The permission set, declared rather than assumed. The augmentation narrows \`can()\` to these
+// strings, so a typo is a build error instead of a rule that silently never matches; the
+// definePermissions() call is the same set at runtime, and it has to run before any can() below.
+declare module '@ultimat3/policy' {
+  interface PermissionRegistry {
+    '${feature.kebab}:read': true;
+    '${feature.kebab}:write': true;
+  }
+}
+
+${permissionSet(feature)}
+
+/** What a write invalidates and a read depends on — one tag, both directions. */
+export const ${feature.camel}Tag = tag('${feature.kebab}');
+
+/** What every ${feature.kebab} rule needs to decide. Actions and queries both accept it. */
+export interface ${feature.pascal}Scope {
+  readonly orgId: string;
+}
+
+// \`can()\` checks the grant first and the predicate second, so a denial distinguishes "you may
+// never do this" from "you may, but not in that org" — an agent can act on the difference.
+// The predicates below add tenancy only; the grant is never re-checked by hand.
+
+/** Read is org-scoped: an actor sees rows in their own org and nothing else. */
+export const can${feature.pascal}Read = can<${feature.pascal}Scope>(
+  '${feature.kebab}:read',
+  ({ actor, input }) => actor !== null && actor.orgId === input.orgId,
+);
+
+/** Write is the same tenancy rule on a second permission — grant the two separately in roles. */
+export const can${feature.pascal}Write = can<${feature.pascal}Scope>(
+  '${feature.kebab}:write',
+  ({ actor, input }) => actor !== null && actor.orgId === input.orgId,
+);
+`;
+
+const policyTest = (feature: NameSet): string => `import { testActor } from '@ultimat3/policy';
+import { expect, unitTest } from '@ultimat3/testing';
+import { can${feature.pascal}Read, can${feature.pascal}Write } from './policy';
+
+const org = '00000000-0000-4000-8000-000000000002';
+const otherOrg = '00000000-0000-4000-8000-000000000009';
+
+// Direct grants rather than roles: the role map is app-global and defineRoles() replaces it
+// wholesale, so a generated test that installed one would decide authz for every other test in
+// the process. \`permissions\` is the same check one layer down.
+const reader = testActor('reader', { orgId: org, permissions: ['${feature.kebab}:read'] }).actor;
+const writer = testActor('writer', {
+  orgId: org,
+  permissions: ['${feature.kebab}:read', '${feature.kebab}:write'],
+}).actor;
+const outsider = testActor('outsider', {
+  orgId: otherOrg,
+  permissions: ['${feature.kebab}:read', '${feature.kebab}:write'],
+}).actor;
+
+unitTest('${feature.camel} read denies anonymous and cross-org actors', async () => {
+  await expect(can${feature.pascal}Read).toDenyPolicy({ actor: null, input: { orgId: org } });
+  await expect(can${feature.pascal}Read).toDenyPolicy({ actor: outsider, input: { orgId: org } });
+  await expect(can${feature.pascal}Read).not.toDenyPolicy({ actor: reader, input: { orgId: org } });
+});
+
+unitTest('${feature.camel} write denies an actor holding only the read grant', async () => {
+  // The outsider holds the grant and is still denied: the predicate is a second, independent
+  // gate, and this is the assertion that fails if someone deletes it.
+  await expect(can${feature.pascal}Write).toDenyPolicy({ actor: reader, input: { orgId: org } });
+  await expect(can${feature.pascal}Write).toDenyPolicy({ actor: outsider, input: { orgId: org } });
+  await expect(can${feature.pascal}Write).not.toDenyPolicy({ actor: writer, input: { orgId: org } });
+});
+
+unitTest('${feature.camel} rules name the permission they require', () => {
+  expect(can${feature.pascal}Read.permissions).toEqual(['${feature.kebab}:read']);
+  expect(can${feature.pascal}Write.permissions).toEqual(['${feature.kebab}:write']);
+});
+`;
+
+export function policyFiles(
+  rawName: string,
+  target: { readonly surfaceDir: string; readonly feature: string },
+): readonly GeneratedFile[] {
+  const feature = names(rawName.length > 0 ? rawName : target.feature);
+  const dir = `${target.surfaceDir}/${target.feature}`;
+  return [
+    { path: `${dir}/policy.ts`, contents: policySource(feature) },
+    { path: `${dir}/policy.test.ts`, contents: policyTest(feature) },
+  ];
+}