@mettlecast/domain-cli 0.2.60 → 0.2.61

package/dist/commands/generate-openapi.js

@@ -1,7 +1,12 @@
 /**
  * generate-openapi — read a domain's registry and produce an OpenAPI 3.1
  * specification as JSON. The registry is consumed at build time; each
- * `defineApi` entry contributes one path under the domain's route prefix.
+ * `defineAction({ exposure: { type: 'api', ... } })` entry contributes
+ * one path under the domain's route prefix.
+ *
+ * Issue #4689: the legacy `defineApi` factory was removed and the
+ * `registry.apis` slot is now always empty in new registries. This
+ * command therefore reads exclusively from `actions[]`.
  *
  * Usage: npx mc-domain-module generate-openapi <domain>
  */
@@ -9,29 +14,9 @@ import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { cliLogger } from '../utils/logger.js';
 /**
- * Extract a Zod schema shape from a registry entry version.
- * The registry may store schemas as `input`/`output` (raw Zod
- * objects) or `inputSchema`/`outputSchema` (JSON Schema shapes).
- * Returns a best-effort JSON Schema object for the OpenAPI spec.
+ * Run the generate-openapi command: read the domain's registry and emit
+ * an OpenAPI 3.1 spec covering every API-exposed action.
  */
-function extractSchema(version, field) {
-    // Prefer JSON Schema if present
-    const schemaField = field === 'input' ? version.inputSchema : version.outputSchema;
-    if (schemaField && typeof schemaField === 'object' && schemaField !== null) {
-        return schemaField;
-    }
-    // Fall back to the raw Zod shape — try to produce a minimal JSON
-    // Schema from the Zod _def. For full support, add zod-to-json-schema
-    // to the CLI dependencies and call `zodToJsonSchema(zodSchema)`.
-    const raw = field === 'input' ? version.input : version.output;
-    if (raw && typeof raw === 'object' && raw !== null) {
-        // Attempt minimal mapping: if the Zod shape has a `type` field
-        // from its _def, describe it as JSON Schema.
-        const def = raw;
-        return { type: def.type ?? 'object', properties: def.properties, required: def.required };
-    }
-    return { type: 'object' };
-}
 export async function runGenerateOpenapi(options) {
     const projectRoot = options.projectRoot ?? process.cwd();
     const domain = options.domain;
@@ -41,22 +26,23 @@ export async function runGenerateOpenapi(options) {
     const registryJson = await readFile(registryPath, 'utf8');
     const registry = JSON.parse(registryJson);
     const paths = {};
-    for (const api of registry.apis) {
-        const method = (api.method ?? 'get').toLowerCase();
-        const fullPath = `/v1/${domain}${api.path}`;
-        const v1 = api.versions['v1'] ?? api.versions[Object.keys(api.versions)[0]];
-        if (!v1)
+    for (const action of registry.actions ?? []) {
+        if (action.exposure?.type !== 'api')
             continue;
+        const method = (action.exposure.method ?? 'get').toLowerCase();
+        const fullPath = `/v1/${domain}${action.exposure.path}`;
+        const inputSchema = action.inputSchema ?? { type: 'object' };
+        const outputSchema = action.outputSchema ?? { type: 'object' };
         if (!paths[fullPath])
             paths[fullPath] = {};
         paths[fullPath][method] = {
-            operationId: `${domain}.${api.id}`,
-            summary: `${domain}.${api.id}`,
-            description: `Version: ${v1.status}`,
+            operationId: `${domain}.${action.id}`,
+            summary: `${domain}.${action.id}`,
+            description: 'Action-first contract (defineAction + exposure.type=api).',
             requestBody: {
                 content: {
                     'application/json': {
-                        schema: extractSchema(v1, 'input'),
+                        schema: inputSchema,
                     },
                 },
             },
@@ -65,7 +51,7 @@ export async function runGenerateOpenapi(options) {
                     description: 'OK',
                     content: {
                         'application/json': {
-                            schema: extractSchema(v1, 'output'),
+                            schema: outputSchema,
                         },
                     },
                 },

package/dist/commands/show.d.ts

@@ -13,10 +13,10 @@ export interface ShowDomainOptions {
     domainsDir?: string;
 }
 /**
- * Represents a primitive entry (API, subscriber, action, or job).
+ * Represents a primitive entry (action, subscriber, or job).
  */
 interface PrimitiveEntry {
-    type: 'api' | 'subscriber' | 'action' | 'job';
+    type: 'subscriber' | 'action' | 'job';
     id: string;
     file: string;
 }
@@ -26,7 +26,6 @@ interface PrimitiveEntry {
 interface DomainSummary {
     domain: string;
     primitives: {
-        apis: PrimitiveEntry[];
         subscribers: PrimitiveEntry[];
         actions: PrimitiveEntry[];
         jobs: PrimitiveEntry[];

package/dist/commands/show.js

@@ -74,7 +74,6 @@ export async function runShowDomain(opts) {
         throw new Error(`Domain "${opts.domain}" not found at ${domainDir}`);
     }
     // Scan primitives
-    const apis = await scanPrimitives(join(domainDir, 'api'), 'api');
     const subscribers = await scanPrimitives(join(domainDir, 'subscribers'), 'subscriber');
     const actions = await scanPrimitives(join(domainDir, 'actions'), 'action');
     const jobs = await scanPrimitives(join(domainDir, 'jobs'), 'job');
@@ -113,7 +112,6 @@ export async function runShowDomain(opts) {
     const summary = {
         domain: opts.domain,
         primitives: {
-            apis,
             subscribers,
             actions,
             jobs,

package/dist/commands/test.js

@@ -14,7 +14,6 @@ export async function runTest(options) {
     const fixturePath = resolve(options.fixturePath);
     const { registry } = await buildRegistry(domainRoot);
     const allEntries = [
-        ...registry.apis,
         ...registry.webhooks,
         ...registry.subscribers,
         ...registry.schedules,

package/dist/commands/upgrade-backend.js

@@ -4,10 +4,10 @@ const MIGRATIONS = [
     {
         fromMajor: 1,
         toMajor: 2,
-        description: 'Migrate defineApi from v1 to v2: rename `versions.v1.handler` shape',
+        description: 'Audit v1 domain backends for action-first API exposure requirements',
         transform(repoRoot, dryRun) {
-            // Placeholder: real migration uses ts-morph to rewrite handler signatures
-            console.log(`[G20] Would apply: defineApi v1→v2 migration in ${repoRoot}/domains/**`);
+            // Placeholder: real migration uses ts-morph to rewrite handler signatures.
+            console.log(`[G20] Would audit action-first API exposure in ${repoRoot}/domains/**`);
             if (!dryRun) {
                 console.log('[G20] ts-morph transform: (not yet implemented — add jscodeshift transforms here)');
             }

package/dist/commands/validate.js

@@ -90,37 +90,17 @@ async function checkRawPathViolations(_repoRoot, config) {
  * Each rule maps 1:1 to an aspect annotation code so downstream tooling
  * can correlate build-time and synth-time failures.
  *
- * NOTE on `SECURITY_MISSING_SECURITY_EXCEPTION` for legacy `defineApi`
- * entries: the registry builder does not propagate `securityException`
- * from legacy source — that field only exists on action-style API
- * exposures, which are covered by the existing `AUTH_NONE_REQUIRES_EXCEPTION`
- * rule in `checkActionFirstSecurity`. The aspect's corresponding check
- * (`assertAnonymousRoutesHaveException`) catches the legacy case at
- * synth time so a developer migrating to action-style APIs gets the
- * right guidance at the right layer.
+ * Issue #4689: the legacy `defineApi` factory and `registry.apis` field
+ * were removed. Deployment-time API invariants are enforced against the
+ * `actions[]` API-exposure surface — see `checkActionFirstSecurity`.
  */
-function checkDeploymentSecurity(apis, actions) {
-    const errors = [];
-    for (const api of apis) {
-        // Non-anonymous APIs whose path lacks the tenant placeholder cannot
-        // bind `ctx.tenant.id` from the URL. The aspect surfaces this as
-        // `SECURITY_MISSING_TENANT_PATH`; the CLI version is a faster gate so
-        // CI doesn't pay the synth cost.
-        if (api.authType !== 'none' && !api.path.includes('/v1/tenants/{tenantId}/')) {
-            errors.push({
-                code: 'SECURITY_MISSING_TENANT_PATH',
-                message: `API '${api.id}' (${api.method} ${api.path}) is JWT-protected but its path does not include the canonical '/v1/tenants/{tenantId}/' placeholder. The runtime cannot bind ctx.tenant.id from a path that lacks the placeholder.`,
-            });
-        }
-    }
+function checkDeploymentSecurity(_actions) {
     // Action API exposures are already covered by `checkActionFirstSecurity`
     // for `tenancy: 'required'` paths and `auth: 'none'` exceptions. The
     // codes there (TENANT_API_PATH_REQUIRED, AUTH_NONE_REQUIRES_EXCEPTION)
     // are kept stable for back-compat — they map to the same aspect codes.
-    // Suppress the unused-actions lint while keeping the parameter shape
-    // for the future where actions gain new deployment-time invariants.
-    void actions;
-    return errors;
+    //
+    return [];
 }
 /**
  * Action-first security validation rules (#4619, Wave 6 Task 6.1).
@@ -229,29 +209,6 @@ function checkApiExposureSecurity(actionId, exposure) {
     }
     return errors;
 }
-/**
- * DEFINE_API_LEGACY_USAGE — the action-first migration replaces
- * standalone `defineApi` calls with `defineAction` + `exposure.type:
- * 'api'`. Every `defineApi` call still in the source produces a row in
- * `registry.apis`; the validator emits one error per legacy API to
- * enforce the alpha breaking migration. The validate command's fixture
- * suite intentionally does not use `defineApi`, so this rule does not
- * break existing unit tests.
- */
-function checkDefineApiLegacyUsage(apiCount, apis) {
-    if (apiCount === 0)
-        return [];
-    const errors = [];
-    for (const api of apis) {
-        if (api.kind !== 'api')
-            continue;
-        errors.push({
-            code: 'DEFINE_API_LEGACY_USAGE',
-            message: `API '${api.id}' uses legacy \`defineApi\`. Migrate to \`defineAction\` with \`exposure: { type: 'api', path, method, auth, tenancy }\` (#4619).`,
-        });
-    }
-    return errors;
-}
 /**
  * Run the validate command: build the registry and perform structural validation.
  * Exits the process with code 1 if validation fails (CI gate usage).
@@ -267,9 +224,8 @@ export async function runValidate(domainRoot, exitOnFailure = true, config = { m
     for (const w of warnings) {
         cliLogger.warn(w);
     }
-    errors.push(...checkDuplicateIds(registry.apis, 'api'), ...checkDuplicateIds(registry.webhooks, 'webhook'), ...checkDuplicateIds(registry.subscribers, 'subscriber'), ...checkDuplicateIds(registry.schedules, 'schedule'), ...checkDuplicateIds(registry.jobs, 'job'), ...checkDuplicateIds(registry.actions, 'action'), ...checkDuplicateIds(registry.integrations, 'integration'), ...checkDuplicateIds(registry.events, 'event'));
+    errors.push(...checkDuplicateIds(registry.webhooks, 'webhook'), ...checkDuplicateIds(registry.subscribers, 'subscriber'), ...checkDuplicateIds(registry.schedules, 'schedule'), ...checkDuplicateIds(registry.jobs, 'job'), ...checkDuplicateIds(registry.actions, 'action'), ...checkDuplicateIds(registry.integrations, 'integration'), ...checkDuplicateIds(registry.events, 'event'));
     const entriesWithFiles = [
-        ...registry.apis,
         ...registry.webhooks,
         ...registry.subscribers,
         ...registry.schedules,
@@ -291,54 +247,20 @@ export async function runValidate(domainRoot, exitOnFailure = true, config = { m
         }
     }));
     errors.push(...checkSubscriberSemverRanges(registry.subscribers));
-    const VALID_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']);
-    for (const api of registry.apis) {
-        const entry = api;
-        errors.push(...checkLifecycleConsistency(entry, `api '${api.id}'`));
-        if (!api.requestSchema) {
-            errors.push({
-                code: 'MISSING_API_REQUEST_SCHEMA',
-                message: `API '${api.id}' (${api.method} ${api.path}) has no request schema. Define input/output in defineApi versions.`,
-            });
-        }
-        if (!api.responseSchema) {
-            errors.push({
-                code: 'MISSING_API_RESPONSE_SCHEMA',
-                message: `API '${api.id}' (${api.method} ${api.path}) has no response schema. Define input/output in defineApi versions.`,
-            });
-        }
-        if (!VALID_METHODS.has(api.method)) {
-            errors.push({
-                code: 'INVALID_API_METHOD',
-                message: `API '${api.id}' (${api.method} ${api.path}) has invalid method "${api.method}". Use one of: ${[...VALID_METHODS].join(', ')}.`,
-            });
-        }
-        const isVoidInput = api.requestSchema?.type === 'null';
-        if (!isVoidInput && !api.examples?.request) {
-            errors.push({
-                code: 'MISSING_API_REQUEST_EXAMPLE',
-                message: `API '${api.id}' (${api.method} ${api.path}) has no request example. Add examples: { request: {...}, response: {...} } to the defineApi config.`,
-            });
-        }
-        if (!api.examples?.response) {
-            errors.push({
-                code: 'MISSING_API_RESPONSE_EXAMPLE',
-                message: `API '${api.id}' (${api.method} ${api.path}) has no response example. Add examples: { request: {...}, response: {...} } to the defineApi config.`,
-            });
-        }
-    }
+    // Issue #4689: defineApi and registry.apis were removed. The action-first
+    // validation rules in `checkActionFirstSecurity` cover the action surface
+    // that now owns all HTTP endpoints.
     const rawPathErrors = await checkRawPathViolations(registry.domainRoot, config);
     errors.push(...rawPathErrors);
     // Wave 6 Task 6.1: action-first security validation gates (#4619).
     // Runs against the registry built above so the rules see the same
     // shape the CDK packer will eventually consume.
     errors.push(...checkActionFirstSecurity(registry.actions));
-    errors.push(...checkDefineApiLegacyUsage(registry.apis.length, registry.apis));
     // Issue #4662 Task D — deployment-time security gates. These mirror
     // the CDK synth-time `SecurityAssertionAspect` so violations are
     // caught before any AWS deployment is attempted.
-    errors.push(...checkDeploymentSecurity(registry.apis, registry.actions));
-    const totalPrimitives = registry.apis.length + registry.webhooks.length +
+    errors.push(...checkDeploymentSecurity(registry.actions));
+    const totalPrimitives = registry.webhooks.length +
         registry.subscribers.length + registry.schedules.length +
         registry.jobs.length + registry.actions.length;
     if (totalPrimitives === 0) {

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

@@ -1,5 +1,5 @@
 import { type FastifyInstance } from 'fastify';
-import type { DomainRegistry } from '@mettlecast/domain-cdk-packer';
+import type { DomainRegistry } from '../types.js';
 /**
  * Options for creating the local API server.
  */

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

@@ -1,5 +1,5 @@
 import type { FastifyInstance } from 'fastify';
-import type { DomainRegistry } from '@mettlecast/domain-cdk-packer';
+import type { DomainRegistry } from '../types.js';
 /**
  * Options for mountRoutes.
  */
@@ -13,7 +13,16 @@ export interface MountRoutesOptions {
 }
 /**
  * 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.
+ *
+ * Issue #4689: the only HTTP endpoint surface in the new registry is
+ * `actions[]` whose `exposure.type === 'api'`. `defineApi` was removed
+ * and `registry.apis` is always empty in fresh registries, so the
+ * dev server iterates the action array and mounts each API exposure
+ * directly. Internal-only actions are intentionally skipped — they
+ * are reachable only through `ctx.actions`.
+ *
+ * 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

@@ -5,23 +5,35 @@ function toFastifyPath(path) {
 }
 /**
  * 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.
+ *
+ * Issue #4689: the only HTTP endpoint surface in the new registry is
+ * `actions[]` whose `exposure.type === 'api'`. `defineApi` was removed
+ * and `registry.apis` is always empty in fresh registries, so the
+ * dev server iterates the action array and mounts each API exposure
+ * directly. Internal-only actions are intentionally skipped — they
+ * are reachable only through `ctx.actions`.
+ *
+ * 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);
+    for (const action of registry.actions) {
+        if (action.exposure?.type !== 'api')
+            continue;
+        const exposure = action.exposure;
+        const handlerAbsPath = join(domainRoot, action.handlerFile);
+        const fastifyPath = toFastifyPath(exposure.path);
         const mod = await import(handlerAbsPath);
-        const def = Object.values(mod).find(v => v && typeof v === 'object' && v['id'] === api.id);
+        const def = Object.values(mod).find(v => v && typeof v === 'object' && v['id'] === action.id);
         if (!def || typeof def['handler'] !== 'function') {
-            server.log.warn({ apiId: api.id, handlerAbsPath }, 'No handler function found, skipping route');
+            server.log.warn({ actionId: action.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],
+            method: [exposure.method],
             url: fastifyPath,
             handler: async (request, reply) => {
                 const { ctx } = await hydrateLocalCtx({ domainRoot });
@@ -37,6 +49,6 @@ export async function mountRoutes(options) {
                 await reply.send(result);
             },
         });
-        server.log.info({ method: api.method, path: fastifyPath, apiId: api.id }, 'Route mounted');
+        server.log.info({ method: exposure.method, path: fastifyPath, actionId: action.id }, 'Route mounted');
     }
 }

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

@@ -1,5 +1,10 @@
 /**
  * Template for generating API handler skeleton.
+ *
+ * Action-first contract: HTTP endpoints are declared with `defineAction`
+ * + `exposure: { type: 'api', ... }`. The legacy `defineApi` factory was
+ * removed in #4689 — the only public HTTP endpoint primitive is now an
+ * action whose exposure type is `'api'`.
  */
 /**
  * Generates an API handler skeleton with the given domain, API, and tenancy.

package/dist/templates/api-skeleton.js

@@ -1,5 +1,10 @@
 /**
  * Template for generating API handler skeleton.
+ *
+ * Action-first contract: HTTP endpoints are declared with `defineAction`
+ * + `exposure: { type: 'api', ... }`. The legacy `defineApi` factory was
+ * removed in #4689 — the only public HTTP endpoint primitive is now an
+ * action whose exposure type is `'api'`.
  */
 /**
  * Convert kebab-case to camelCase.
@@ -19,45 +24,41 @@ function camelCase(s) {
 export function apiSkeletonTemplate(domainId, apiId, tenancy) {
     const tenantPath = tenancy === 'required' ? '/v1/tenants/{tenantId}' : '/v1';
     const outputType = `${camelCase(domainId)}${camelCase(apiId)}Output`;
+    // The `auth` posture must be set explicitly per the action-first contract:
+    //   - 'required' for tenant-scoped or any authenticated endpoint.
+    //   - 'none' for anonymous endpoints (then add `securityException`).
+    //   - 'service' for service-to-service only.
+    const authPosture = tenancy === 'system' ? 'service' : 'required';
     return `import { z } from 'zod';
-import { defineApi } from '@mettlecast/domain-runtime';
-import { createKyClient, initOtel } from '@mettlecast/domain-runtime';
+import { defineAction, initOtel } from '@mettlecast/domain-runtime';
 import type { Result, AppError } from '@mettlecast/domain-runtime';
 import { ok, err, notFound } from '@mettlecast/domain-runtime';
 
 // Initialise OpenTelemetry tracing for the process.  Idempotent —
 // safe to call at module scope.  Sets up OTLP export (when
-// OTEL_EXPORTER_OTLP_ENDPOINT is set) or console-export for
-// local dev.  Auto-instruments outbound HTTP calls via ky.
+// OTEL_EXPORTER_OTLP_ENDPOINT is set) or console-export for local dev.
 initOtel();
 
-// Shared HTTP client with retry on 503/429.  Replace this with
-// your own client if you need custom headers or auth.
-const http = createKyClient();
-
 const outputSchema = z.object({ ok: z.boolean() }).default({ ok: true });
 
-export const ${camelCase(apiId)} = defineApi({
+export const ${camelCase(apiId)} = defineAction({
   id: '${apiId}',
-  path: '${tenantPath}/${domainId}/${apiId}',
-  method: 'POST',
-  tenancy: '${tenancy}',
-  outboundAccess: 'internal',
-  versions: {
-    v1: {
-      status: 'stable',
-      input: z.object({}).default({}),
-      output: outputSchema,
-      handler: async (_input, _ctx): Promise<Result<z.infer<typeof outputSchema>, AppError>> => {
-        // Replace this with your handler logic.
-        // Return ok(value) on success, err({ ... }) on failure.
-        return ok({ ok: true });
-      },
-    },
+  backendAccess: 'domain',
+  exposure: {
+    type: 'api',
+    path: '${tenantPath}/${domainId}/${apiId}',
+    method: 'POST',
+    auth: '${authPosture}',
+    tenancy: '${tenancy}',
   },
-  examples: {
-    request: {},
-    response: { ok: true },
+  outboundAccess: 'internal',
+  idempotent: false,
+  input: z.object({}).default({}),
+  output: outputSchema,
+  handler: async (_input, _ctx): Promise<Result<z.infer<typeof outputSchema>, AppError>> => {
+    // Replace this with your handler logic.
+    // Return ok(value) on success, err({ ... }) on failure.
+    return ok({ ok: true });
   },
 });
 `;

package/dist/templates/claude-md.js

@@ -3,5 +3,5 @@
  */
 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`;
+    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- Public HTTP endpoints must use \`defineAction({ exposure: { type: 'api', ... } })\` from \`@mettlecast/domain-runtime\`. The legacy \`defineApi\` factory is no longer scaffolded for public handlers.\n- Internal-only callable handlers must use \`defineAction({ exposure: { type: 'internal' } })\`.\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/patterns/api/create-with-event.d.ts

@@ -1,6 +1,10 @@
 /**
  * Create-with-event API pattern template.
  * Produces: POST handler + publishes a domain event after mutation.
+ *
+ * Action-first: HTTP endpoints are declared with `defineAction` +
+ * `exposure: { type: 'api', ... }`. The legacy `defineApi` factory was
+ * removed in #4689.
  */
 export declare function createWithEventTemplate(domain: string, id: string, tenancy: string): string;
 /**

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

@@ -1,6 +1,10 @@
 /**
  * Create-with-event API pattern template.
  * Produces: POST handler + publishes a domain event after mutation.
+ *
+ * Action-first: HTTP endpoints are declared with `defineAction` +
+ * `exposure: { type: 'api', ... }`. The legacy `defineApi` factory was
+ * removed in #4689.
  */
 function camelCase(s) {
     return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
@@ -8,9 +12,9 @@ function camelCase(s) {
 export function createWithEventTemplate(domain, id, tenancy) {
     const varName = camelCase(id);
     const tenantPath = tenancy === 'required' ? '/v1/tenants/{tenantId}' : '/v1';
+    const authPosture = tenancy === 'system' ? 'service' : 'required';
     return `import { z } from 'zod';
-import { defineApi } from '@mettlecast/domain-runtime';
-import { createKyClient, initOtel } from '@mettlecast/domain-runtime';
+import { defineAction, initOtel } from '@mettlecast/domain-runtime';
 import type { Result, AppError } from '@mettlecast/domain-runtime';
 import { ok, err, notFound } from '@mettlecast/domain-runtime';
 
@@ -31,43 +35,45 @@ const ${varName}Output = z.object({
   status: 'created',
 });
 
-// ── API definition ───────────────────────────────────────────
+// ── Action definition (API exposure) ─────────────────────────
 
-export const ${varName} = defineApi({
+export const ${varName} = defineAction({
   id: '${id}',
-  path: '${tenantPath}/${domain}/${id}',
-  tenancy: '${tenancy}',
+  backendAccess: 'domain',
+  exposure: {
+    type: 'api',
+    path: '${tenantPath}/${domain}/${id}',
+    method: 'POST',
+    auth: '${authPosture}',
+    tenancy: '${tenancy}',
+  },
   outboundAccess: 'internal',
-  versions: {
-    v1: {
-      status: 'stable',
-      input: ${varName}Input,
-      output: ${varName}Output,
-      handler: async (input, ctx) => {
-        const entityId = crypto.randomUUID();
+  idempotent: false,
+  input: ${varName}Input,
+  output: ${varName}Output,
+  handler: async (input, ctx) => {
+    const entityId = crypto.randomUUID();
 
-        // ── Persist entity ────────────────────────────────────
-        await ctx.store.put(entityId, { id: entityId, name: input.name });
+    // ── Persist entity ────────────────────────────────────
+    await ctx.store.put(entityId, { id: entityId, name: input.name });
 
-        // ── Publish domain event ──────────────────────────────
-        await ctx.publish(
-          '${domain}.${id}.created',
-          {
-            id: entityId,
-            name: input.name,
-            tenantId: ctx.tenant.id,
-          },
-          1,
-        );
+    // ── Publish domain event ──────────────────────────────
+    await ctx.publish(
+      '${domain}.${id}.created',
+      {
+        id: entityId,
+        name: input.name,
+        tenantId: ctx.tenant.id,
+      },
+      1,
+    );
 
-        await ctx.audit.log('${id}.create', entityId, { tenantId: ctx.tenant.id });
+    await ctx.audit.log('${id}.create', entityId, { tenantId: ctx.tenant.id });
 
-        return {
-          id: entityId,
-          status: 'created',
-        };
-      },
-    },
+    return {
+      id: entityId,
+      status: 'created',
+    };
   },
 });
 `;

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

@@ -1,6 +1,10 @@
 /**
  * Idempotent-mutation API pattern template.
  * Produces: PUT with idempotency key middleware.
+ *
+ * Action-first: HTTP endpoints are declared with `defineAction` +
+ * `exposure: { type: 'api', ... }`. The legacy `defineApi` factory was
+ * removed in #4689.
  */
 export declare function idempotentMutationTemplate(domain: string, id: string, tenancy: string): string;
 /**