@mettlecast/domain-cli 0.2.60 → 0.2.62

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;
 /**

package/dist/templates/patterns/api/idempotent-mutation.js

@@ -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.
  */
 function camelCase(s) {
     return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
@@ -8,9 +12,9 @@ function camelCase(s) {
 export function idempotentMutationTemplate(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';
 
@@ -36,53 +40,55 @@ const ${varName}Output = z.object({
   idempotencyKey: '00000000-0000-0000-0000-000000000000',
 });
 
-// ── 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: 'PUT',
+    auth: '${authPosture}',
+    tenancy: '${tenancy}',
+  },
   outboundAccess: 'internal',
-  versions: {
-    v1: {
-      status: 'stable',
-      input: ${varName}Input,
-      output: ${varName}Output,
-      handler: async (input, ctx) => {
-        // ── Check for duplicate (idempotency key = input.id) ──
-        const existing = await ctx.store.get('IDEMPOTENT#' + input.id);
+  idempotent: true,
+  input: ${varName}Input,
+  output: ${varName}Output,
+  handler: async (input, ctx) => {
+    // ── Check for duplicate (idempotency key = input.id) ──
+    const existing = await ctx.store.get('IDEMPOTENT#' + input.id);
 
-        if (existing) {
-          await ctx.audit.log('${id}.idempotent.duplicate', input.id);
-          return {
-            id: input.id,
-            status: 'already-processed',
-            idempotencyKey: input.id,
-          };
-        }
+    if (existing) {
+      await ctx.audit.log('${id}.idempotent.duplicate', input.id);
+      return {
+        id: input.id,
+        status: 'already-processed',
+        idempotencyKey: input.id,
+      };
+    }
 
-        // ── Apply mutation ────────────────────────────────────
-        await ctx.store.put(
-          '${id.toUpperCase()}#' + input.id,
-          { id: input.id, payload: input.payload, createdAt: new Date().toISOString() },
-        );
+    // ── Apply mutation ────────────────────────────────────
+    await ctx.store.put(
+      '${id.toUpperCase()}#' + input.id,
+      { id: input.id, payload: input.payload, createdAt: new Date().toISOString() },
+    );
 
-        // ── Record idempotency token with 24h TTL ─────────────
-        await ctx.store.put(
-          'IDEMPOTENT#' + input.id,
-          { entityId: input.id },
-          { ttl: Math.floor(Date.now() / 1000) + 86400 },
-        );
+    // ── Record idempotency token with 24h TTL ─────────────
+    await ctx.store.put(
+      'IDEMPOTENT#' + input.id,
+      { entityId: input.id },
+      { ttl: Math.floor(Date.now() / 1000) + 86400 },
+    );
 
-        await ctx.audit.log('${id}.idempotent.applied', input.id, { tenantId: ctx.tenant.id });
+    await ctx.audit.log('${id}.idempotent.applied', input.id, { tenantId: ctx.tenant.id });
 
-        return {
-          id: input.id,
-          status: 'applied',
-          idempotencyKey: input.id,
-        };
-      },
-    },
+    return {
+      id: input.id,
+      status: 'applied',
+      idempotencyKey: input.id,
+    };
   },
 });
 `;

package/dist/templates/patterns/api/paginated-list.d.ts

@@ -1,6 +1,10 @@
 /**
  * Paginated-list API pattern template.
  * Produces: GET with cursor/limit, pagination contract, EMF metrics.
+ *
+ * Action-first: HTTP endpoints are declared with `defineAction` +
+ * `exposure: { type: 'api', ... }`. The legacy `defineApi` factory was
+ * removed in #4689.
  */
 export declare function paginatedListTemplate(domain: string, id: string, tenancy: string): string;
 /**

package/dist/templates/patterns/api/paginated-list.js

@@ -1,6 +1,10 @@
 /**
  * Paginated-list API pattern template.
  * Produces: GET with cursor/limit, pagination contract, EMF metrics.
+ *
+ * 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 paginatedListTemplate(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';
 
@@ -35,34 +39,36 @@ const PageOutput = z.object({
   total: z.number().int().optional(),
 }).default({ items: [], nextCursor: undefined, total: undefined });
 
-// ── 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: 'GET',
+    auth: '${authPosture}',
+    tenancy: '${tenancy}',
+  },
   outboundAccess: 'internal',
-  versions: {
-    v1: {
-      status: 'stable',
-      input: PageInput,
-      output: PageOutput,
-      handler: async (input, ctx) => {
-        const { cursor, limit, filter } = input;
+  idempotent: true,
+  input: PageInput,
+  output: PageOutput,
+  handler: async (input, ctx) => {
+    const { cursor, limit, filter } = input;
 
-        await ctx.audit.log('${id}.list', ctx.tenant.id, { cursor, limit });
+    await ctx.audit.log('${id}.list', ctx.tenant.id, { cursor, limit });
 
-        // ── paginated data fetch ──────────────────────────────
-        const items: Array<{ id: string }> = [];
-        const nextCursor = items.length === limit ? btoa(items[items.length - 1].id) : undefined;
+    // ── paginated data fetch ──────────────────────────────
+    const items: Array<{ id: string }> = [];
+    const nextCursor = items.length === limit ? btoa(items[items.length - 1].id) : undefined;
 
-        return {
-          items,
-          nextCursor,
-          total: undefined,
-        };
-      },
-    },
+    return {
+      items,
+      nextCursor,
+      total: undefined,
+    };
   },
 });
 `;

package/dist/templates/patterns/api/simple-crud.d.ts

@@ -1,6 +1,10 @@
 /**
  * Simple CRUD API pattern template.
  * Produces: GET / POST / PUT / DELETE with Zod schemas and audit logging.
+ *
+ * Action-first: HTTP endpoints are declared with `defineAction` +
+ * `exposure: { type: 'api', ... }`. The legacy `defineApi` factory was
+ * removed in #4689.
  */
 export declare function simpleCrudTemplate(domain: string, id: string, tenancy: string): string;
 export declare function simpleCrudListTemplate(domain: string, id: string, tenancy: string): string;

package/dist/templates/patterns/api/simple-crud.js

@@ -1,6 +1,10 @@
 /**
  * Simple CRUD API pattern template.
  * Produces: GET / POST / PUT / DELETE with Zod schemas and audit logging.
+ *
+ * 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 simpleCrudTemplate(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';
 
@@ -37,28 +41,30 @@ const ${varName}ListOutput = z.object({
   nextCursor: z.string().optional(),
 }).default({ items: [], nextCursor: undefined });
 
-// ── 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) => {
-        // Create / Read / Update / Delete based on method
-        await ctx.audit.log('${id}.v1', ctx.tenant.id, { input });
-        return {
-          id: input.id ?? crypto.randomUUID(),
-          createdAt: new Date().toISOString(),
-          updatedAt: new Date().toISOString(),
-        };
-      },
-    },
+  idempotent: false,
+  input: ${varName}Input,
+  output: ${varName}Output,
+  handler: async (input, ctx) => {
+    // Create / Read / Update / Delete based on method
+    await ctx.audit.log('${id}.v1', ctx.tenant.id, { input });
+    return {
+      id: input.id ?? crypto.randomUUID(),
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
   },
 });
 `;
@@ -66,8 +72,11 @@ export const ${varName} = defineApi({
 export function simpleCrudListTemplate(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 { defineAction, initOtel } from '@mettlecast/domain-runtime';
+
+initOtel();
 
 const ${varName}ListInput = z.object({
   cursor: z.string().optional(),
@@ -89,21 +98,23 @@ const ${varName}ListOutput = z.object({
   nextCursor: z.string().optional(),
 }).default({ items: [], nextCursor: undefined });
 
-export const ${varName}List = defineApi({
+export const ${varName}List = defineAction({
   id: '${id}-list',
-  path: '${tenantPath}/${domain}/${id}-list',
-  tenancy: '${tenancy}',
+  backendAccess: 'domain',
+  exposure: {
+    type: 'api',
+    path: '${tenantPath}/${domain}/${id}-list',
+    method: 'GET',
+    auth: '${authPosture}',
+    tenancy: '${tenancy}',
+  },
   outboundAccess: 'internal',
-  versions: {
-    v1: {
-      status: 'stable',
-      input: ${varName}ListInput,
-      output: ${varName}ListOutput,
-      handler: async (input, ctx) => {
-        await ctx.audit.log('${id}-list.v1', ctx.tenant.id);
-        return { items: [], nextCursor: undefined };
-      },
-    },
+  idempotent: true,
+  input: ${varName}ListInput,
+  output: ${varName}ListOutput,
+  handler: async (input, ctx) => {
+    await ctx.audit.log('${id}-list.v1', ctx.tenant.id);
+    return { items: [], nextCursor: undefined };
   },
 });
 `;

package/dist/templates/patterns/api/streaming-list.d.ts

@@ -19,6 +19,10 @@
  *   - API Gateway HTTP API with 2.0 payload format (not REST API)
  *   - Lambda runtime v20+
  *
+ * Action-first: HTTP endpoints are declared with `defineAction` +
+ * `exposure: { type: 'api', ... }`. The legacy `defineApi` factory was
+ * removed in #4689.
+ *
  * @param domain - Domain ID in kebab-case
  * @param apiId - API ID in kebab-case
  * @param itemName - Singular item name (e.g. 'ticket', 'member')