@mettlecast/domain-cli 0.2.60 → 0.2.61

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')

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

@@ -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')
@@ -26,7 +30,7 @@
  */
 export function streamingListPattern(domain, apiId, itemName) {
     return `import { z } from 'zod';
-import { defineApi } from '@mettlecast/domain-runtime';
+import { defineAction } from '@mettlecast/domain-runtime';
 import type { Result, AppError } from '@mettlecast/domain-runtime';
 
 const ${itemName}Schema = z.object({ id: z.string() });
@@ -39,53 +43,54 @@ const outputSchema = z.object({
   nextCursor: z.string().optional(),
 }).default({ items: [] });
 
-export const ${apiId.replace(/-/g, '_')} = defineApi({
+export const ${apiId.replace(/-/g, '_')} = defineAction({
   id: '${apiId}',
-  path: '/v1/${domain}/${apiId}',
-  method: 'GET',
-  tenancy: 'required',
+  backendAccess: 'domain',
+  exposure: {
+    type: 'api',
+    path: '/v1/tenants/{tenantId}/${domain}/${apiId}',
+    method: 'GET',
+    auth: 'required',
+    tenancy: 'required',
+  },
   outboundAccess: 'internal',
-  versions: {
-    v1: {
-      status: 'stable',
-      input: inputSchema,
-      output: outputSchema,
-      handler: async (input, ctx): Promise<Result<z.infer<typeof outputSchema>, AppError>> => {
-        // Streaming response: each item is yielded as a JSON line
-        // before the full query completes.  The runtime handler
-        // wrapper converts this generator into a chunked response.
-        //
-        //   GET /v1/${domain}/${apiId}?limit=100
-        //   Transfer-Encoding: chunked
-        //   Content-Type: application/x-ndjson
-        //
-        //   {"id":"1"}\\n
-        //   {"id":"2"}\\n
-        //   {"id":"3"}\\n
+  idempotent: true,
+  input: inputSchema,
+  output: outputSchema,
+  handler: async (input, ctx): Promise<Result<z.infer<typeof outputSchema>, AppError>> => {
+    // Streaming response: each item is yielded as a JSON line
+    // before the full query completes.  The runtime handler
+    // wrapper converts this generator into a chunked response.
+    //
+    //   GET /v1/${domain}/${apiId}?limit=100
+    //   Transfer-Encoding: chunked
+    //   Content-Type: application/x-ndjson
+    //
+    //   {"id":"1"}\\n
+    //   {"id":"2"}\\n
+    //   {"id":"3"}\\n
 
-        let nextCursor: string | undefined;
-        const items: unknown[] = [];
+    let nextCursor: string | undefined;
+    const items: unknown[] = [];
 
-        // Replace this query with your actual data source.
-        const rows = await ctx.db.query(
-          '${domain}',
-          'SELECT id FROM ${domain}s LIMIT $1 OFFSET $2',
-          [input.limit + 1, input.cursor ? parseInt(input.cursor, 10) : 0],
-        );
+    // Replace this query with your actual data source.
+    const rows = await ctx.db.query(
+      '${domain}',
+      'SELECT id FROM ${domain}s LIMIT $1 OFFSET $2',
+      [input.limit + 1, input.cursor ? parseInt(input.cursor, 10) : 0],
+    );
 
-        for (let i = 0; i < Math.min(rows.length, input.limit); i++) {
-          items.push(rows[i]);
-        }
+    for (let i = 0; i < Math.min(rows.length, input.limit); i++) {
+      items.push(rows[i]);
+    }
 
-        if (rows.length > input.limit) {
-          nextCursor = String(
-            (input.cursor ? parseInt(input.cursor, 10) : 0) + input.limit,
-          );
-        }
+    if (rows.length > input.limit) {
+      nextCursor = String(
+        (input.cursor ? parseInt(input.cursor, 10) : 0) + input.limit,
+      );
+    }
 
-        return { ok: true, value: { items, nextCursor } };
-      },
-    },
+    return { ok: true, value: { items, nextCursor } };
   },
 });
 `;

package/dist/templates/patterns/api/system-admin.d.ts

@@ -1,6 +1,10 @@
 /**
  * System-admin API pattern template.
  * Produces: GET/POST with tenancy: 'system', no tenant context.
+ *
+ * Action-first: HTTP endpoints are declared with `defineAction` +
+ * `exposure: { type: 'api', ... }`. The legacy `defineApi` factory was
+ * removed in #4689.
  */
 export declare function systemAdminTemplate(domain: string, id: string, tenancy: string): string;
 /**

package/dist/templates/patterns/api/system-admin.js

@@ -1,6 +1,10 @@
 /**
  * System-admin API pattern template.
  * Produces: GET/POST with tenancy: 'system', no tenant context.
+ *
+ * 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,8 +12,7 @@ function camelCase(s) {
 export function systemAdminTemplate(domain, id, tenancy) {
     const varName = camelCase(id);
     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';
 
@@ -27,7 +30,7 @@ const ${varName}Output = z.object({
   data: z.record(z.unknown()).optional(),
 }).default({ ok: true });
 
-// ── System health input ──────────────────────────────────────
+// ── System health output ─────────────────────────────────────
 
 const SystemHealthOutput = z.object({
   status: z.enum(['healthy', 'degraded', 'down']),
@@ -38,64 +41,68 @@ const SystemHealthOutput = z.object({
   })),
 }).default({ status: 'healthy', uptime: 0, domains: [] });
 
-// ── API definitions ──────────────────────────────────────────
+// ── Action definitions (API exposure) ────────────────────────
 
-export const ${varName} = defineApi({
+export const ${varName} = defineAction({
   id: '${id}',
-  path: '/system/${domain}/${id}',
-  tenancy: '${tenancy}',
+  backendAccess: 'platform',
+  exposure: {
+    type: 'api',
+    path: '/system/${domain}/${id}',
+    method: 'POST',
+    auth: 'service',
+    tenancy: '${tenancy}',
+  },
   outboundAccess: 'internal',
-  versions: {
-    v1: {
-      status: 'stable',
-      input: ${varName}Input,
-      output: ${varName}Output,
-      handler: async (input, ctx) => {
-        await ctx.audit.log('${id}.system', 'system', { command: input.command });
+  idempotent: false,
+  input: ${varName}Input,
+  output: ${varName}Output,
+  handler: async (input, ctx) => {
+    await ctx.audit.log('${id}.system', 'system', { command: input.command });
 
-        switch (input.command) {
-          case 'status':
-            return {
-              ok: true,
-              data: { status: 'healthy', domains: [] },
-            };
-          case 'metrics':
-            return {
-              ok: true,
-              data: {
-                requestCount: 0,
-                errorCount: 0,
-                p99LatencyMs: 0,
-              },
-            };
-          case 'health':
-            return { ok: true, data: { status: 'healthy' } };
-          default:
-            return { ok: false };
-        }
-      },
-    },
+    switch (input.command) {
+      case 'status':
+        return {
+          ok: true,
+          data: { status: 'healthy', domains: [] },
+        };
+      case 'metrics':
+        return {
+          ok: true,
+          data: {
+            requestCount: 0,
+            errorCount: 0,
+            p99LatencyMs: 0,
+          },
+        };
+      case 'health':
+        return { ok: true, data: { status: 'healthy' } };
+      default:
+        return { ok: false };
+    }
   },
 });
 
-export const ${varName}Health = defineApi({
+export const ${varName}Health = defineAction({
   id: '${id}-health',
-  path: '/system/${domain}/${id}-health',
-  tenancy: '${tenancy}',
+  backendAccess: 'platform',
+  exposure: {
+    type: 'api',
+    path: '/system/${domain}/${id}-health',
+    method: 'GET',
+    auth: 'service',
+    tenancy: '${tenancy}',
+  },
   outboundAccess: 'internal',
-  versions: {
-    v1: {
-      status: 'stable',
-      input: z.object({}).default({}),
-      output: SystemHealthOutput,
-      handler: async (_input, _ctx) => {
-        return {
-          status: 'healthy',
-          uptime: process.uptime(),
-          domains: [],
-        };
-      },
-    },
+  idempotent: true,
+  input: z.object({}).default({}),
+  output: SystemHealthOutput,
+  handler: async (_input, _ctx) => {
+    return {
+      status: 'healthy',
+      uptime: process.uptime(),
+      domains: [],
+    };
   },
 });
 `;

package/dist/templates/patterns/api/webhook-receiver-style.d.ts

@@ -1,6 +1,10 @@
 /**
  * Webhook-receiver-style API pattern template.
  * Produces: POST with signature verification, provider enum.
+ *
+ * Action-first: HTTP endpoints are declared with `defineAction` +
+ * `exposure: { type: 'api', ... }`. The legacy `defineApi` factory was
+ * removed in #4689.
  */
 export declare function webhookReceiverStyleTemplate(domain: string, id: string, tenancy: string): string;
 /**