@mettlecast/domain-cli 0.2.60 → 0.2.62

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

package/dist/templates/patterns/api/webhook-receiver-style.js

@@ -1,15 +1,21 @@
 /**
  * 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) {
     return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 }
 export function webhookReceiverStyleTemplate(domain, id, tenancy) {
     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';
 
@@ -47,46 +53,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.
+  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();
+    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);
+    // ── 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,
-        });
+    await ctx.audit.log('${id}.webhook.received', ctx.tenant.id, {
+      provider: input.provider,
+      eventType: input.eventType,
+      eventId,
+    });
 
-        return {
-          received: true,
-          eventId,
-          provider: input.provider,
-        };
-      },
-    },
+    return {
+      received: true,
+      eventId,
+      provider: input.provider,
+    };
   },
 });
 `;

package/dist/types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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';
+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/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/file-helpers.d.ts

@@ -7,8 +7,6 @@
 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/. */

package/dist/utils/file-helpers.js

@@ -44,9 +44,8 @@ export async function walkDomainDir(domainRoot) {
             return undefined;
         }
     }
-    const [domain, apis, webhooks, subscribers, actions, schedules, jobs, integrations, publishes] = await Promise.all([
+    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')),
@@ -55,5 +54,5 @@ export async function walkDomainDir(domainRoot) {
         tsFiles(join(domainRoot, 'integrations')),
         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/dist/utils/manifest.d.ts

@@ -26,3 +26,4 @@ export declare function upsertManifestFile(manifest: TibManifest, entry: Manifes
 export declare function removeManifestFile(manifest: TibManifest, filePath: string): void;
 export declare function getManifestFile(manifest: TibManifest, filePath: string): ManifestFileEntry | undefined;
 export declare function isScaffoldManaged(manifest: TibManifest, filePath: string): boolean;
+export declare function pruneManifest(projectRoot: string, manifest: TibManifest): Promise<number>;

package/dist/utils/manifest.js

@@ -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';
 const MANIFEST_PATH = '.mc/manifest.json';
@@ -132,3 +132,18 @@ export function isScaffoldManaged(manifest, filePath) {
     // Returns true only when the file is in the manifest with policy 'managed'
     return entry != null && entry.policy === 'managed';
 }
+export async function pruneManifest(projectRoot, manifest) {
+    let pruned = 0;
+    const survivors = [];
+    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/dist/utils/scaffold-config.d.ts

@@ -29,10 +29,14 @@ export interface CostOptions {
     xRaySamplingRate?: number;
     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. */
 export interface LifecycleOptions {
@@ -92,6 +96,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;
 }
 export declare function readScaffoldConfig(projectRoot: string): Promise<ScaffoldConfig>;
 export declare function writeScaffoldConfig(projectRoot: string, config: ScaffoldConfig): Promise<void>;

package/dist/utils/scaffold-config.js

@@ -18,7 +18,9 @@ const DEFAULT_SCAFFOLD_CONFIG = {
     logRetentionDays: 30,
     monitoringOptions: {
         enhanced: false,
+        disableCloudWatchDashboards: false,
     },
+    natInstanceType: 't4g.nano',
 };
 const CONFIG_PATH = '.mc/scaffold-config.json';
 export async function readScaffoldConfig(projectRoot) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mettlecast/domain-cli",
-  "version": "0.2.60",
+  "version": "0.2.62",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",