@mettlecast/domain-cli 0.2.0

package/dist/runtime-stubs/hydrate-local-ctx.d.ts

@@ -0,0 +1,49 @@
+import type { DomainContext } from '@mettlecast/domain-runtime';
+/**
+ * Captured side-effects from a local-dev ctx for test inspection.
+ */
+export interface LocalCtxCaptures {
+    /** Events published via ctx.publish during this invocation. */
+    events: Array<{
+        eventType: string;
+        data: unknown;
+    }>;
+    /** Jobs enqueued via ctx.jobs.enqueue during this invocation. */
+    jobs: Array<{
+        jobName: string;
+        input: unknown;
+    }>;
+    /** Flows started via ctx.flows.start during this invocation. */
+    executions: Array<{
+        flowName: string;
+        input: unknown;
+    }>;
+}
+/**
+ * Options for creating a local dev DomainContext.
+ */
+export interface LocalCtxOptions {
+    /** Absolute path to the domain root (used to read .env.local). */
+    domainRoot: string;
+    /** Override tenant id. Defaults to a placeholder UUID. */
+    tenantId?: string;
+    /** Override actor sub. Defaults to 'local-dev'. */
+    actorSub?: string;
+}
+/**
+ * Result of hydrateLocalCtx — the context plus capture handles.
+ */
+export interface LocalCtxResult {
+    /** The fully hydrated DomainContext with all stubs. */
+    ctx: DomainContext;
+    /** Captures for inspecting published events, enqueued jobs, started flows. */
+    captures: LocalCtxCaptures;
+}
+/**
+ * Hydrates a DomainContext with local-dev stubs — no AWS calls.
+ * Reads .env.local from domainRoot for the secrets stub.
+ * Uses capturing publishers/proxies so test output can inspect side effects.
+ * @param options - LocalCtxOptions controlling domain root and optional overrides.
+ * @returns LocalCtxResult with the hydrated ctx and capture handles.
+ */
+export declare function hydrateLocalCtx(options: LocalCtxOptions): Promise<LocalCtxResult>;

package/dist/runtime-stubs/hydrate-local-ctx.js

@@ -0,0 +1,45 @@
+import { hydrateCtx, noopTracer, createCapturingPublisher, createCapturingJobsProxy, createCapturingFlowsProxy, createNoopIdempotency, createCache, createFetch, createMockDb, createEmptyActionsProxy, createEmptyIntegrationsProxy, createEmptySecrets, } from '@mettlecast/domain-runtime';
+import { createCliLogger } from '../utils/logger.js';
+import { loadLocalSecrets } from './load-secrets.js';
+/**
+ * Hydrates a DomainContext with local-dev stubs — no AWS calls.
+ * Reads .env.local from domainRoot for the secrets stub.
+ * Uses capturing publishers/proxies so test output can inspect side effects.
+ * @param options - LocalCtxOptions controlling domain root and optional overrides.
+ * @returns LocalCtxResult with the hydrated ctx and capture handles.
+ */
+export async function hydrateLocalCtx(options) {
+    const { domainRoot, tenantId = '00000000-0000-7000-8000-000000000000', actorSub = 'local-dev', } = options;
+    const fileSecrets = await loadLocalSecrets(domainRoot);
+    // Use loaded secrets; fall back to empty secrets if none found
+    const secrets = fileSecrets && Object.keys(fileSecrets).length > 0
+        ? fileSecrets
+        : createEmptySecrets();
+    const publisherCapture = createCapturingPublisher();
+    const jobsCapture = createCapturingJobsProxy();
+    const flowsCapture = createCapturingFlowsProxy();
+    const ctx = await hydrateCtx({}, {
+        actor: { type: 'user', sub: actorSub, email: 'dev@local' },
+        tenant: { id: tenantId, workspaceId: tenantId },
+        logger: createCliLogger('domain-dev'),
+        tracer: noopTracer,
+        fetch: createFetch(),
+        cache: createCache(),
+        idempotency: createNoopIdempotency(actorSub),
+        secrets,
+        db: createMockDb(),
+        publish: publisherCapture.publish,
+        actions: createEmptyActionsProxy(),
+        jobs: jobsCapture.proxy,
+        flows: flowsCapture.proxy,
+        integrations: createEmptyIntegrationsProxy(),
+    });
+    return {
+        ctx,
+        captures: {
+            events: publisherCapture.events,
+            jobs: jobsCapture.jobs,
+            executions: flowsCapture.executions,
+        },
+    };
+}

package/dist/runtime-stubs/load-secrets.d.ts

@@ -0,0 +1,11 @@
+import type { SecretsProxy } from '@mettlecast/domain-runtime';
+/**
+ * Read a `.env.local` file from the given domain root directory and return
+ * its entries as a SecretsProxy (Record<string, string>).
+ * Lines starting with `#` are treated as comments and skipped.
+ * Lines without `=` are skipped. Values may be quoted with single or double quotes.
+ * Returns an empty frozen object if the file does not exist.
+ * @param domainRoot - Absolute path to the domain directory.
+ * @returns A frozen SecretsProxy mapping env var names to string values.
+ */
+export declare function loadLocalSecrets(domainRoot: string): Promise<SecretsProxy>;

package/dist/runtime-stubs/load-secrets.js

@@ -0,0 +1,37 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Read a `.env.local` file from the given domain root directory and return
+ * its entries as a SecretsProxy (Record<string, string>).
+ * Lines starting with `#` are treated as comments and skipped.
+ * Lines without `=` are skipped. Values may be quoted with single or double quotes.
+ * Returns an empty frozen object if the file does not exist.
+ * @param domainRoot - Absolute path to the domain directory.
+ * @returns A frozen SecretsProxy mapping env var names to string values.
+ */
+export async function loadLocalSecrets(domainRoot) {
+    const filePath = join(domainRoot, '.env.local');
+    let raw;
+    try {
+        raw = await readFile(filePath, 'utf8');
+    }
+    catch {
+        return Object.freeze({});
+    }
+    const entries = raw
+        .split('\n')
+        .map(line => line.trim())
+        .filter(line => line.length > 0 && !line.startsWith('#') && line.includes('='))
+        .map(line => {
+        const idx = line.indexOf('=');
+        const key = line.slice(0, idx).trim();
+        let value = line.slice(idx + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        return [key, value];
+    })
+        .filter(([key]) => key.length > 0);
+    return Object.freeze(Object.fromEntries(entries));
+}

package/dist/server/api-server.d.ts

@@ -0,0 +1,21 @@
+import { type FastifyInstance } from 'fastify';
+import type { DomainRegistry } from '@mettlecast/domain-cdk-packer';
+/**
+ * Options for creating the local API server.
+ */
+export interface ApiServerOptions {
+    /** Port to listen on. Defaults to 3000. */
+    port?: number;
+    /** Host to bind to. Defaults to '0.0.0.0'. */
+    host?: string;
+    /** The built DomainRegistry. */
+    registry: DomainRegistry;
+    /** Absolute path to the domain root. */
+    domainRoot: string;
+}
+/**
+ * Create and start the local Fastify API server, mounting all routes from the registry.
+ * @param options - ApiServerOptions.
+ * @returns The running FastifyInstance (caller can call server.close() to stop).
+ */
+export declare function createApiServer(options: ApiServerOptions): Promise<FastifyInstance>;

package/dist/server/api-server.js

@@ -0,0 +1,14 @@
+import Fastify from 'fastify';
+import { mountRoutes } from './mount-routes.js';
+/**
+ * Create and start the local Fastify API server, mounting all routes from the registry.
+ * @param options - ApiServerOptions.
+ * @returns The running FastifyInstance (caller can call server.close() to stop).
+ */
+export async function createApiServer(options) {
+    const { port = 3000, host = '0.0.0.0', registry, domainRoot } = options;
+    const server = Fastify({ logger: true });
+    await mountRoutes({ server, registry, domainRoot });
+    await server.listen({ port, host });
+    return server;
+}

package/dist/server/mount-routes.d.ts

@@ -0,0 +1,19 @@
+import type { FastifyInstance } from 'fastify';
+import type { DomainRegistry } from '@mettlecast/domain-cdk-packer';
+/**
+ * Options for mountRoutes.
+ */
+export interface MountRoutesOptions {
+    /** The Fastify server instance. */
+    server: FastifyInstance;
+    /** The built DomainRegistry. */
+    registry: DomainRegistry;
+    /** Absolute path to the domain root (needed for ctx hydration). */
+    domainRoot: string;
+}
+/**
+ * Mount all API routes from the DomainRegistry onto the Fastify server.
+ * Each route dynamically imports its handler file and hydrates a local dev ctx per request.
+ * @param options - MountRoutesOptions.
+ */
+export declare function mountRoutes(options: MountRoutesOptions): Promise<void>;

package/dist/server/mount-routes.js

@@ -0,0 +1,42 @@
+import { join } from 'node:path';
+import { hydrateLocalCtx } from '../runtime-stubs/hydrate-local-ctx.js';
+function toFastifyPath(path) {
+    return path.replace(/\{(\w+)\}/g, ':$1');
+}
+/**
+ * Mount all API routes from the DomainRegistry onto the Fastify server.
+ * Each route dynamically imports its handler file and hydrates a local dev ctx per request.
+ * @param options - MountRoutesOptions.
+ */
+export async function mountRoutes(options) {
+    const { server, registry, domainRoot } = options;
+    for (const api of registry.apis) {
+        const handlerAbsPath = join(domainRoot, api.handlerFile);
+        const fastifyPath = toFastifyPath(api.path);
+        const mod = await import(handlerAbsPath);
+        const def = Object.values(mod).find(v => v && typeof v === 'object' && v['id'] === api.id);
+        if (!def || typeof def['handler'] !== 'function') {
+            server.log.warn({ apiId: api.id, handlerAbsPath }, 'No handler function found, skipping route');
+            continue;
+        }
+        const handler = def['handler'];
+        server.route({
+            method: api.method === 'ANY' ? ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] : [api.method],
+            url: fastifyPath,
+            handler: async (request, reply) => {
+                const { ctx } = await hydrateLocalCtx({ domainRoot });
+                const event = {
+                    method: request.method,
+                    path: request.url,
+                    params: request.params,
+                    query: request.query,
+                    body: request.body,
+                    headers: request.headers,
+                };
+                const result = await handler(event, ctx);
+                await reply.send(result);
+            },
+        });
+        server.log.info({ method: api.method, path: fastifyPath, apiId: api.id }, 'Route mounted');
+    }
+}

package/dist/templates/api-skeleton.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Template for generating API handler skeleton.
+ */
+/**
+ * Generates an API handler skeleton with the given domain, API, and tenancy.
+ * @param domainId - Domain ID in kebab-case.
+ * @param apiId - API ID in kebab-case.
+ * @param tenancy - Tenancy mode: 'required', 'none', or 'system'.
+ * @returns TypeScript source code as a string.
+ */
+export declare function apiSkeletonTemplate(domainId: string, apiId: string, tenancy: string): string;
+/**
+ * Generates a fixture JSON skeleton for API testing.
+ * @param domainId - Domain ID in kebab-case.
+ * @param apiId - API ID in kebab-case.
+ * @returns JSON string with mock event and context for testing.
+ */
+export declare function apiFixtureSkeleton(domainId: string, apiId: string): string;

package/dist/templates/api-skeleton.js

@@ -0,0 +1,69 @@
+/**
+ * Template for generating API handler skeleton.
+ */
+/**
+ * Convert kebab-case to camelCase.
+ * @param s - String in kebab-case.
+ * @returns String in camelCase.
+ */
+function camelCase(s) {
+    return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+/**
+ * Generates an API handler skeleton with the given domain, API, and tenancy.
+ * @param domainId - Domain ID in kebab-case.
+ * @param apiId - API ID in kebab-case.
+ * @param tenancy - Tenancy mode: 'required', 'none', or 'system'.
+ * @returns TypeScript source code as a string.
+ */
+export function apiSkeletonTemplate(domainId, apiId, tenancy) {
+    const tenantPath = tenancy === 'required' ? '/v1/tenants/{tenantId}' : '/v1';
+    return `import { z } from 'zod';
+import { defineApi } from '../../../lib/domain-runtime';
+
+export const ${camelCase(apiId)} = defineApi({
+  id: '${apiId}',
+  path: '${tenantPath}/${domainId}/${apiId}',
+  tenancy: '${tenancy}',
+  versions: {
+    v1: {
+      status: 'stable',
+      input: z.object({}).optional(),
+      output: z.object({ ok: z.boolean() }),
+      handler: async (_input, _ctx) => {
+        return { ok: true };
+      },
+    },
+  },
+});
+`;
+}
+/**
+ * Generates a fixture JSON skeleton for API testing.
+ * @param domainId - Domain ID in kebab-case.
+ * @param apiId - API ID in kebab-case.
+ * @returns JSON string with mock event and context for testing.
+ */
+export function apiFixtureSkeleton(domainId, apiId) {
+    return JSON.stringify({
+        description: `Fixture for ${domainId}.${apiId}`,
+        event: {
+            version: '2.0',
+            requestContext: {
+                http: { method: 'GET', path: `/v1/${domainId}/${apiId}` },
+                authorizer: {
+                    jwt: {
+                        claims: {
+                            sub: '00000000-0000-0000-0000-000000000000',
+                            email: 'test@example.com',
+                            'custom:tenantId': '11111111-1111-1111-1111-111111111111',
+                        },
+                    },
+                },
+            },
+            pathParameters: {},
+            headers: { 'content-type': 'application/json', 'accept-version': '1' },
+            body: null,
+        },
+    }, null, 2) + '\n';
+}

package/dist/templates/claude-md.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Template for generating per-domain CLAUDE.md ownership file.
+ */
+export declare function claudeMdTemplate(id: string): string;

package/dist/templates/claude-md.js

@@ -0,0 +1,7 @@
+/**
+ * Template for generating per-domain CLAUDE.md ownership file.
+ */
+export function claudeMdTemplate(id) {
+    const titleName = id.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+    return `# ${titleName} Domain — Ownership\n\nYou are the domain owner for \`${id}\`.\n\n## Responsibilities\n\n- All source files under \`domains/${id}/\` are owned by you.\n- API handlers must use \`defineApi\` from \`@mettlecast/domain-runtime\`.\n- Cross-domain calls must use \`ctx.actions.call()\`, never direct imports.\n- AWS SDK must never be imported directly — use \`ctx\` helpers.\n\n## Scaffold Rules\n\nSee the root \`CLAUDE.md\` for full scaffold rules, anti-patterns, and workflow commands.\n\n## Domain Config\n\nSee \`domains/${id}/domain.config.ts\` for the domain definition.\n`;
+}

package/dist/templates/dashboard-pages/index.d.ts

@@ -0,0 +1,101 @@
+export declare const PAGE_REGISTRY: readonly [{
+    readonly id: "login";
+    readonly category: "auth";
+    readonly path: "auth/login.tsx";
+    readonly name: "LoginPage";
+}, {
+    readonly id: "signup";
+    readonly category: "auth";
+    readonly path: "auth/signup.tsx";
+    readonly name: "SignupPage";
+}, {
+    readonly id: "verify-email";
+    readonly category: "auth";
+    readonly path: "auth/verify-email.tsx";
+    readonly name: "VerifyEmailPage";
+}, {
+    readonly id: "forgot-password";
+    readonly category: "auth";
+    readonly path: "auth/forgot-password.tsx";
+    readonly name: "ForgotPasswordPage";
+}, {
+    readonly id: "reset-password";
+    readonly category: "auth";
+    readonly path: "auth/reset-password.tsx";
+    readonly name: "ResetPasswordPage";
+}, {
+    readonly id: "mfa-setup";
+    readonly category: "auth";
+    readonly path: "auth/mfa-setup.tsx";
+    readonly name: "MfaSetupPage";
+}, {
+    readonly id: "mfa-verify";
+    readonly category: "auth";
+    readonly path: "auth/mfa-verify.tsx";
+    readonly name: "MfaVerifyPage";
+}, {
+    readonly id: "accept-invitation";
+    readonly category: "auth";
+    readonly path: "auth/accept-invitation.tsx";
+    readonly name: "AcceptInvitationPage";
+}, {
+    readonly id: "choose-org";
+    readonly category: "auth";
+    readonly path: "auth/choose-org.tsx";
+    readonly name: "ChooseOrgPage";
+}, {
+    readonly id: "sign-out";
+    readonly category: "auth";
+    readonly path: "auth/sign-out.tsx";
+    readonly name: "SignOutPage";
+}, {
+    readonly id: "dashboard-home";
+    readonly category: "shell";
+    readonly path: "shell/dashboard-home.tsx";
+    readonly name: "DashboardHomePage";
+}, {
+    readonly id: "not-found";
+    readonly category: "shell";
+    readonly path: "shell/not-found.tsx";
+    readonly name: "NotFoundPage";
+}, {
+    readonly id: "forbidden";
+    readonly category: "shell";
+    readonly path: "shell/forbidden.tsx";
+    readonly name: "ForbiddenPage";
+}, {
+    readonly id: "server-error";
+    readonly category: "shell";
+    readonly path: "shell/server-error.tsx";
+    readonly name: "ServerErrorPage";
+}, {
+    readonly id: "maintenance";
+    readonly category: "shell";
+    readonly path: "shell/maintenance.tsx";
+    readonly name: "MaintenancePage";
+}, {
+    readonly id: "profile";
+    readonly category: "account";
+    readonly path: "account/profile.tsx";
+    readonly name: "ProfilePage";
+}, {
+    readonly id: "workspace-settings";
+    readonly category: "account";
+    readonly path: "account/workspace-settings.tsx";
+    readonly name: "WorkspaceSettingsPage";
+}, {
+    readonly id: "members";
+    readonly category: "account";
+    readonly path: "account/members.tsx";
+    readonly name: "MembersPage";
+}, {
+    readonly id: "api-keys";
+    readonly category: "account";
+    readonly path: "account/api-keys.tsx";
+    readonly name: "ApiKeysPage";
+}, {
+    readonly id: "audit-log";
+    readonly category: "account";
+    readonly path: "account/audit-log.tsx";
+    readonly name: "AuditLogPage";
+}];

package/dist/templates/dashboard-pages/index.js

@@ -0,0 +1,22 @@
+export const PAGE_REGISTRY = [
+    { id: 'login', category: 'auth', path: 'auth/login.tsx', name: 'LoginPage' },
+    { id: 'signup', category: 'auth', path: 'auth/signup.tsx', name: 'SignupPage' },
+    { id: 'verify-email', category: 'auth', path: 'auth/verify-email.tsx', name: 'VerifyEmailPage' },
+    { id: 'forgot-password', category: 'auth', path: 'auth/forgot-password.tsx', name: 'ForgotPasswordPage' },
+    { id: 'reset-password', category: 'auth', path: 'auth/reset-password.tsx', name: 'ResetPasswordPage' },
+    { id: 'mfa-setup', category: 'auth', path: 'auth/mfa-setup.tsx', name: 'MfaSetupPage' },
+    { id: 'mfa-verify', category: 'auth', path: 'auth/mfa-verify.tsx', name: 'MfaVerifyPage' },
+    { id: 'accept-invitation', category: 'auth', path: 'auth/accept-invitation.tsx', name: 'AcceptInvitationPage' },
+    { id: 'choose-org', category: 'auth', path: 'auth/choose-org.tsx', name: 'ChooseOrgPage' },
+    { id: 'sign-out', category: 'auth', path: 'auth/sign-out.tsx', name: 'SignOutPage' },
+    { id: 'dashboard-home', category: 'shell', path: 'shell/dashboard-home.tsx', name: 'DashboardHomePage' },
+    { id: 'not-found', category: 'shell', path: 'shell/not-found.tsx', name: 'NotFoundPage' },
+    { id: 'forbidden', category: 'shell', path: 'shell/forbidden.tsx', name: 'ForbiddenPage' },
+    { id: 'server-error', category: 'shell', path: 'shell/server-error.tsx', name: 'ServerErrorPage' },
+    { id: 'maintenance', category: 'shell', path: 'shell/maintenance.tsx', name: 'MaintenancePage' },
+    { id: 'profile', category: 'account', path: 'account/profile.tsx', name: 'ProfilePage' },
+    { id: 'workspace-settings', category: 'account', path: 'account/workspace-settings.tsx', name: 'WorkspaceSettingsPage' },
+    { id: 'members', category: 'account', path: 'account/members.tsx', name: 'MembersPage' },
+    { id: 'api-keys', category: 'account', path: 'account/api-keys.tsx', name: 'ApiKeysPage' },
+    { id: 'audit-log', category: 'account', path: 'account/audit-log.tsx', name: 'AuditLogPage' },
+];

package/dist/templates/domain-config.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Template for generating domain.config.ts skeleton.
+ */
+/**
+ * Generates a domain.config.ts skeleton with the given ID and tenancy mode.
+ * @param id - Domain ID in kebab-case.
+ * @param tenancy - Tenancy mode: 'required', 'none', or 'system'.
+ * @returns TypeScript source code as a string.
+ */
+export declare function domainConfigTemplate(id: string, tenancy: string): string;

package/dist/templates/domain-config.js

@@ -0,0 +1,19 @@
+/**
+ * Template for generating domain.config.ts skeleton.
+ */
+/**
+ * Generates a domain.config.ts skeleton with the given ID and tenancy mode.
+ * @param id - Domain ID in kebab-case.
+ * @param tenancy - Tenancy mode: 'required', 'none', or 'system'.
+ * @returns TypeScript source code as a string.
+ */
+export function domainConfigTemplate(id, tenancy) {
+    return `import { defineDomain } from '../../lib/domain-runtime';
+
+export const domain = defineDomain({
+  id: '${id}',
+  name: '${id.replace(/-/g, ' ').replace(/\\b\\w/g, c => c.toUpperCase())}',
+  tenancy: '${tenancy}',
+});
+`;
+}

package/dist/templates/events-skeleton.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Template for generating events skeleton.
+ */
+/**
+ * Generates a publishes/events.ts skeleton with an example event.
+ * @param domainId - Domain ID in kebab-case.
+ * @returns TypeScript source code as a string.
+ */
+export declare function eventsSkeletonTemplate(domainId: string): string;

package/dist/templates/events-skeleton.js

@@ -0,0 +1,23 @@
+/**
+ * Template for generating events skeleton.
+ */
+/**
+ * Generates a publishes/events.ts skeleton with an example event.
+ * @param domainId - Domain ID in kebab-case.
+ * @returns TypeScript source code as a string.
+ */
+export function eventsSkeletonTemplate(domainId) {
+    return `import { z } from 'zod';
+import { defineEvent } from '../../../lib/domain-runtime';
+
+export const exampleEvent = defineEvent({
+  id: '${domainId}.example',
+  versions: [
+    {
+      version: 1,
+      schema: z.object({ tenantId: z.string().uuid() }),
+    },
+  ],
+});
+`;
+}

package/dist/templates/patterns/api/create-with-event.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Create-with-event API pattern template.
+ * Produces: POST handler + publishes a domain event after mutation.
+ */
+export declare function createWithEventTemplate(domain: string, id: string, tenancy: string): string;

package/dist/templates/patterns/api/create-with-event.js

@@ -0,0 +1,69 @@
+/**
+ * Create-with-event API pattern template.
+ * Produces: POST handler + publishes a domain event after mutation.
+ */
+function camelCase(s) {
+    return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+export function createWithEventTemplate(domain, id, tenancy) {
+    const varName = camelCase(id);
+    const tenantPath = tenancy === 'required' ? '/v1/tenants/{tenantId}' : '/v1';
+    return `import { z } from 'zod';
+import { defineApi } from '@mettlecast/domain-runtime';
+
+// ── Zod schemas ──────────────────────────────────────────────
+
+const ${varName}Input = z.object({
+  name: z.string().min(1),
+  payload: z.record(z.unknown()).optional(),
+});
+
+const ${varName}Output = z.object({
+  id: z.string().uuid(),
+  status: z.enum(['created', 'pending']),
+});
+
+// ── API definition ───────────────────────────────────────────
+
+export const ${varName} = defineApi({
+  id: '${id}',
+  path: '${tenantPath}/${domain}/${id}',
+  tenancy: '${tenancy}',
+  versions: {
+    v1: {
+      status: 'stable',
+      input: ${varName}Input,
+      output: ${varName}Output,
+      handler: async (input, ctx) => {
+        const entityId = crypto.randomUUID();
+
+        // ── Persist entity ────────────────────────────────────
+        // ctx.db.put({ ... })
+
+        // ── Publish domain event ──────────────────────────────
+        await ctx.publish(
+          '${domain}.${id}.created',
+          {
+            id: entityId,
+            name: input.name,
+            tenantId: ctx.tenantId,
+          },
+          1,
+        );
+
+        await ctx.auditLog({
+          action: '${id}.create',
+          tenantId: ctx.tenantId,
+          entityId,
+        });
+
+        return {
+          id: entityId,
+          status: 'created',
+        };
+      },
+    },
+  },
+});
+`;
+}

package/dist/templates/patterns/api/idempotent-mutation.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Idempotent-mutation API pattern template.
+ * Produces: PUT with idempotency key middleware.
+ */
+export declare function idempotentMutationTemplate(domain: string, id: string, tenancy: string): string;