@mettlecast/domain-cli 0.2.60 → 0.2.62

package/src/templates/patterns/api/system-admin.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.
  */
 
 function camelCase(s: string): string {
@@ -11,8 +15,7 @@ export function systemAdminTemplate(domain: string, id: string, tenancy: string)
   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';
 
@@ -30,7 +33,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']),
@@ -41,64 +44,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: [],
+    };
   },
 });
 `;
@@ -108,4 +115,4 @@ export const ${varName}Health = defineApi({
  * Example body string used as the event body in the add-api fixture for the
  * system-admin pattern. Mirrors the default shape of the input schema.
  */
-export const systemAdminExampleBody = JSON.stringify({ command: 'status' });
+export const systemAdminExampleBody = JSON.stringify({ command: 'status' });

package/src/templates/patterns/api/webhook-receiver-style.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.
  */
 
 function camelCase(s: string): string {
@@ -9,10 +13,12 @@ function camelCase(s: string): string {
 
 export function webhookReceiverStyleTemplate(domain: string, id: string, tenancy: string): string {
   const varName = camelCase(id);
+  // Webhook receivers are typically public; pair `auth: 'none'` with a
+  // securityException.reason so the validator does not flag the route.
+  const securityException = `\n    securityException: { reason: 'webhook receiver; signature verification handled by authorizer' },`;
 
   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';
 
@@ -50,46 +56,48 @@ const ${varName}Output = z.object({
   provider: 'stripe',
 });
 
-// ── API definition ───────────────────────────────────────────
+// ── Action definition (API exposure) ─────────────────────────
 
-export const ${varName} = defineApi({
+export const ${varName} = defineAction({
   id: '${id}',
-  path: '/webhooks/${domain}/${id}',
-  tenancy: '${tenancy}',
+  backendAccess: 'domain',
+  exposure: {
+    type: 'api',
+    path: '/webhooks/${domain}/${id}',
+    method: 'POST',
+    auth: 'none',${securityException}
+    tenancy: '${tenancy}',
+  },
   outboundAccess: 'internal',
-  versions: {
-    v1: {
-      status: 'stable',
-      input: ${varName}Input,
-      output: ${varName}Output,
-      handler: async (input, ctx) => {
-        // Signature verification belongs in a Lambda authorizer (x-webhook-signature header
-        // is not accessible here). Wire an HttpLambdaAuthorizer in DomainStack for production.
-
-        const eventId = crypto.randomUUID();
-
-        // ── Publish event for downstream processing ───────────
-        await ctx.publish('${domain}.webhook.received', {
-          eventId,
-          provider: input.provider,
-          eventType: input.eventType,
-          payload: input.payload,
-          tenantId: ctx.tenant.id,
-        }, 1);
-
-        await ctx.audit.log('${id}.webhook.received', ctx.tenant.id, {
-          provider: input.provider,
-          eventType: input.eventType,
-          eventId,
-        });
-
-        return {
-          received: true,
-          eventId,
-          provider: input.provider,
-        };
-      },
-    },
+  idempotent: false,
+  input: ${varName}Input,
+  output: ${varName}Output,
+  handler: async (input, ctx) => {
+    // Signature verification belongs in a Lambda authorizer (x-webhook-signature header
+    // is not accessible here). Wire an HttpLambdaAuthorizer in DomainStack for production.
+
+    const eventId = crypto.randomUUID();
+
+    // ── Publish event for downstream processing ───────────
+    await ctx.publish('${domain}.webhook.received', {
+      eventId,
+      provider: input.provider,
+      eventType: input.eventType,
+      payload: input.payload,
+      tenantId: ctx.tenant.id,
+    }, 1);
+
+    await ctx.audit.log('${id}.webhook.received', ctx.tenant.id, {
+      provider: input.provider,
+      eventType: input.eventType,
+      eventId,
+    });
+
+    return {
+      received: true,
+      eventId,
+      provider: input.provider,
+    };
   },
 });
 `;
@@ -103,4 +111,4 @@ export const webhookReceiverStyleExampleBody = JSON.stringify({
   provider: 'stripe',
   eventType: 'example.event',
   payload: {},
-});
+});

package/src/types.ts

@@ -0,0 +1,128 @@
+/**
+ * packages/domain-cli/src/types.ts
+ *
+ * Local re-declaration of registry types used by the CLI's
+ * build/dev/mount-routes pipeline.
+ *
+ * Issue #4689 removed the legacy `defineApi` primitive and the
+ * `registry.apis` field in favour of the action-first model (#4619).
+ * The CLI's own source defines the action-first shape here so the
+ * pipeline can compile even when the published
+ * `@mettlecast/domain-cdk-packer` on npm still carries the legacy
+ * shape (i.e. `DomainRegistry` still requires `apis`, and
+ * `ActionRegistryEntry` lacks the `exposure` field).
+ *
+ * Once the npm-published packer catches up, the two local types below
+ * can collapse back to a single re-export from
+ * `@mettlecast/domain-cdk-packer`.
+ */
+import type {
+  DomainRegistry as PackerDomainRegistry,
+  ActionRegistryEntry as PackerActionRegistryEntry,
+  SchemaSnapshot,
+  WebhookRegistryEntry,
+  SubscriberRegistryEntry,
+  ScheduleRegistryEntry,
+  JobRegistryEntry,
+  IntegrationRegistryEntry,
+  EventRegistryEntry,
+  DomainRegistryEntry,
+  SerialDeploymentConfig,
+  BaseRegistryEntry,
+} from '@mettlecast/domain-cdk-packer';
+
+// Re-export the unchanged registry entry types so callers can import
+// everything from a single local module.
+export type {
+  SchemaSnapshot,
+  WebhookRegistryEntry,
+  SubscriberRegistryEntry,
+  ScheduleRegistryEntry,
+  JobRegistryEntry,
+  IntegrationRegistryEntry,
+  EventRegistryEntry,
+  DomainRegistryEntry,
+  SerialDeploymentConfig,
+  BaseRegistryEntry,
+};
+
+/**
+ * Backend invocation permission for an action. Re-declared locally
+ * because the legacy published packer does not export this union yet
+ * (it was introduced as part of the action-first migration #4619).
+ */
+export type ActionBackendAccess = 'private' | 'domain' | 'platform';
+
+/**
+ * API-exposure metadata for an action whose `exposure.type === 'api'`.
+ * Carries the route, method, auth, tenancy, and any documented security
+ * exception that downstream CDK/contract generation needs to wire the
+ * route safely. Mirrors the canonical `ActionApiExposure` shape from
+ * `@mettlecast/domain-cdk-packer`.
+ */
+export interface ActionApiExposure {
+  /** Discriminant. */
+  type: 'api';
+  /** HTTP route path, e.g. '/v1/tenants/{tenantId}/billing/invoices'. */
+  path: string;
+  /** HTTP method. One of: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. */
+  method: string;
+  /** Authentication requirement for the route. */
+  auth: 'required' | 'none' | 'service';
+  /** Tenancy requirement for the route. */
+  tenancy: 'required' | 'none' | 'system';
+  /** Required role(s) for `auth: 'required'` routes (system tenancy requires this). */
+  roles?: string[];
+  /** Documented exception when auth or tenancy is intentionally not required. */
+  securityException?: { reason: string };
+  /**
+   * True if the source code explicitly declared `auth`. False if the
+   * builder fell back to the safe default (`'required'`). Validation-only.
+   */
+  authDeclared?: boolean;
+  /**
+   * True if the source code explicitly declared `tenancy`. False if the
+   * builder fell back to the safe default (`'required'`). Validation-only.
+   */
+  tenancyDeclared?: boolean;
+}
+
+/**
+ * Discriminated union for an action's external exposure shape.
+ * `internal` actions are reachable only through `ctx.actions`. `api`
+ * actions are exposed via API Gateway and carry the route + auth
+ * metadata needed for safe route generation.
+ */
+export type ActionExposure = ActionApiExposure | { type: 'internal' };
+
+/**
+ * Local `DomainRegistry` for the CLI. Drops the legacy `apis` slot
+ * that was removed in issue #4689's action-first migration, and pins
+ * the `actions` array to the local `ActionRegistryEntry` shape (which
+ * carries the action-first `exposure` field). The CLI builds an object
+ * literal that satisfies this type and then serialises it to
+ * `.mc/<domain>-registry.json`; downstream consumers (CDK packer,
+ * OpenAPI generator, dev server) only ever see the JSON.
+ */
+export type DomainRegistry = Omit<PackerDomainRegistry, 'apis' | 'actions'> & {
+  /** All callable actions (local shape with action-first `exposure`). */
+  actions: ActionRegistryEntry[];
+};
+
+/**
+ * Local `ActionRegistryEntry` for the CLI. Augments the packer's shape
+ * with the `exposure` field and its `exposureDeclared` flag from the
+ * action-first migration (#4619) so the build/dev/mount-routes
+ * pipeline can read these properties regardless of which packer
+ * version is linked. The `backendAccess` field is also surfaced here
+ * (the CLI is the canonical writer of this field) even when the
+ * linked packer only exposes the legacy `visibility` alias.
+ */
+export type ActionRegistryEntry = PackerActionRegistryEntry & {
+  /** External exposure shape for the action (see ActionExposure). */
+  exposure: ActionExposure;
+  /** True if the source code explicitly declared `exposure`. */
+  exposureDeclared?: boolean;
+  /** Backend invocation permission for the action. */
+  backendAccess?: ActionBackendAccess;
+};

package/src/utils/file-helpers.ts

@@ -10,8 +10,6 @@ import { join } from 'node:path';
 export interface DomainFilePaths {
   /** Path to domain.config.ts if present. */
   domain: string | undefined;
-  /** API handler file paths under api/. */
-  apis: string[];
   /** Webhook handler file paths under webhooks/. */
   webhooks: string[];
   /** Subscriber handler file paths under subscribers/. */
@@ -74,10 +72,9 @@ export async function walkDomainDir(domainRoot: string): Promise<DomainFilePaths
     }
   }
 
-  const [domain, apis, webhooks, subscribers, actions, schedules, jobs, integrations, publishes] =
+  const [domain, webhooks, subscribers, actions, schedules, jobs, integrations, publishes] =
     await Promise.all([
       singleTs(join(domainRoot, 'domain.config.ts')),
-      tsFiles(join(domainRoot, 'api')),
       tsFiles(join(domainRoot, 'webhooks')),
       tsFiles(join(domainRoot, 'subscribers')),
       tsFiles(join(domainRoot, 'actions')),
@@ -87,5 +84,5 @@ export async function walkDomainDir(domainRoot: string): Promise<DomainFilePaths
       singleTs(join(domainRoot, 'publishes', 'events.ts')),
     ]);
 
-  return { domain, apis, webhooks, subscribers, actions, schedules, jobs, integrations, publishes };
+  return { domain, webhooks, subscribers, actions, schedules, jobs, integrations, publishes };
 }

package/src/utils/manifest.ts

@@ -1,4 +1,4 @@
-import { readFile, writeFile, mkdir } from 'fs/promises';
+import { readFile, writeFile, mkdir, access } from 'fs/promises';
 import path from 'path';
 import { cliLogger } from './logger.js';
 
@@ -179,3 +179,18 @@ export function isScaffoldManaged(manifest: TibManifest, filePath: string): bool
   // Returns true only when the file is in the manifest with policy 'managed'
   return entry != null && entry.policy === 'managed';
 }
+
+export async function pruneManifest(projectRoot: string, manifest: TibManifest): Promise<number> {
+  let pruned = 0;
+  const survivors: ManifestFileEntry[] = [];
+  for (const entry of manifest.files) {
+    try {
+      await access(path.join(projectRoot, entry.path));
+      survivors.push(entry);
+    } catch {
+      pruned++;
+    }
+  }
+  manifest.files = survivors;
+  return pruned;
+}

package/src/utils/scaffold-config.ts

@@ -50,10 +50,15 @@ export interface CostOptions {
   reservedConcurrencyPerDomain?: Record<string, number>;
 }
 
+/** NAT instance type options for cost control. */
+export type NatInstanceType = 't4g.nano' | 't4g.micro' | 't4g.small';
+
 /** Monitoring / observability feature opt-ins. */
 export interface MonitoringOptions {
   /** Replace basic MonitoringStack with full ObservabilityStack (Grafana + Cost Explorer + CloudWatch). ~$9–18/month */
   enhanced: boolean;
+  /** Disable auto-generated per-domain CloudWatch dashboards. Removes existing dashboards on next deploy. */
+  disableCloudWatchDashboards?: boolean;
 }
 
 /** Lifecycle tunables — Phase B. Schema only in Phase A. */
@@ -114,6 +119,8 @@ export interface ScaffoldConfig {
   environments?: EnvironmentsConfig;
   /** When true, CORS responses include Allow-Credentials: true (requires non-wildcard origins). */
   allowCredentials?: boolean;
+  /** NAT instance type for the shared NAT instance. Defaults to the smallest: t4g.nano. */
+  natInstanceType?: NatInstanceType;
 }
 
 const DEFAULT_SCAFFOLD_CONFIG: Omit<ScaffoldConfig, 'domainIds' | 'flowIds'> = {
@@ -134,7 +141,9 @@ const DEFAULT_SCAFFOLD_CONFIG: Omit<ScaffoldConfig, 'domainIds' | 'flowIds'> = {
   logRetentionDays: 30,
   monitoringOptions: {
     enhanced: false,
+    disableCloudWatchDashboards: false,
   },
+  natInstanceType: 't4g.nano',
 };
 
 const CONFIG_PATH = '.mc/scaffold-config.json';