@mettlecast/domain-cli 0.2.60 → 0.2.61

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/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.61",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/__tests__/build-registry.test.ts

@@ -24,7 +24,6 @@ describe('buildRegistry', () => {
   it('throws if domain.config.ts is missing', async () => {
     mockWalkDomainDir.mockResolvedValue({
       domain: undefined,
-      apis: [],
       webhooks: [],
       subscribers: [],
       actions: [],
@@ -40,7 +39,6 @@ describe('buildRegistry', () => {
   it('throws if domain.config.ts has no domain export', async () => {
     mockWalkDomainDir.mockResolvedValue({
       domain: '/fake/domains/billing/domain.config.ts',
-      apis: [],
       webhooks: [],
       subscribers: [],
       actions: [],
@@ -54,13 +52,15 @@ describe('buildRegistry', () => {
     await expect(buildRegistry(DOMAIN_ROOT)).rejects.toThrow("no 'domain' export found");
   });
 
-  it('builds a registry with domain + one api', async () => {
+  it('builds a registry with domain + one API-exposed action', async () => {
+    // Issue #4689: defineApi was removed; the canonical HTTP endpoint
+    // surface is `defineAction({ exposure: { type: 'api', ... } })`.
+    // The action is recorded under `registry.actions` with API exposure metadata.
     mockWalkDomainDir.mockResolvedValue({
       domain: '/fake/domains/billing/domain.config.ts',
-      apis: ['/fake/domains/billing/api/get-invoice.ts'],
       webhooks: [],
       subscribers: [],
-      actions: [],
+      actions: ['/fake/domains/billing/actions/get-invoice.ts'],
       schedules: [],
       jobs: [],
       integrations: [],
@@ -72,7 +72,20 @@ describe('buildRegistry', () => {
         { _kind: 'domain', _exportName: 'default', id: 'billing', name: 'Billing', tenancy: 'required' },
       ])
       .mockResolvedValueOnce([
-        { _kind: 'api', _exportName: 'getInvoice', id: 'get-invoice', path: '/invoices/:id', method: 'GET', auth: { type: 'jwt' } },
+        {
+          _kind: 'action',
+          _exportName: 'getInvoice',
+          id: 'get-invoice',
+          backendAccess: 'domain',
+          exposure: {
+            type: 'api',
+            path: '/v1/tenants/{tenantId}/billing/invoices/{id}',
+            method: 'GET',
+            auth: 'required',
+            tenancy: 'required',
+          },
+          idempotent: true,
+        },
       ]);
 
     const { registry, warnings } = await buildRegistry(DOMAIN_ROOT);
@@ -80,21 +93,18 @@ describe('buildRegistry', () => {
     expect(warnings).toHaveLength(0);
     expect(registry.schemaVersion).toBe('1');
     expect(registry.domain.id).toBe('billing');
-    expect(registry.apis).toHaveLength(1);
-    expect(registry.apis[0]!.id).toBe('get-invoice');
-    expect(registry.apis[0]!.path).toBe('/invoices/:id');
-    expect(registry.apis[0]!.authType).toBe('jwt');
-    expect(registry.apis[0]!.handlerFile.replaceAll('\\', '/')).toBe('api/get-invoice.ts');
-    expect(registry.apis[0]!.outboundAccess).toBe('internal');
+    expect(registry.actions).toHaveLength(1);
+    expect(registry.actions[0]!.id).toBe('get-invoice');
+    expect(registry.actions[0]!.backendAccess).toBe('domain');
+    expect(registry.actions[0]!.exposure.type).toBe('api');
   });
 
-  it('preserves explicit outboundAccess on primitives', async () => {
+  it('preserves explicit outboundAccess on actions', async () => {
     mockWalkDomainDir.mockResolvedValue({
       domain: '/fake/domains/billing/domain.config.ts',
-      apis: ['/fake/domains/billing/api/sync-invoice.ts'],
       webhooks: [],
       subscribers: [],
-      actions: [],
+      actions: ['/fake/domains/billing/actions/sync-invoice.ts'],
       schedules: [],
       jobs: [],
       integrations: [],
@@ -106,21 +116,34 @@ describe('buildRegistry', () => {
         { _kind: 'domain', _exportName: 'default', id: 'billing', name: 'Billing', tenancy: 'required' },
       ])
       .mockResolvedValueOnce([
-        { _kind: 'api', _exportName: 'syncInvoice', id: 'sync-invoice', path: '/invoices/sync', method: 'POST', auth: { type: 'jwt' }, outboundAccess: 'internet' },
+        {
+          _kind: 'action',
+          _exportName: 'syncInvoice',
+          id: 'sync-invoice',
+          backendAccess: 'domain',
+          exposure: {
+            type: 'api',
+            path: '/v1/tenants/{tenantId}/billing/invoices/sync',
+            method: 'POST',
+            auth: 'required',
+            tenancy: 'required',
+          },
+          outboundAccess: 'internet',
+          idempotent: false,
+        },
       ]);
 
     const { registry } = await buildRegistry(DOMAIN_ROOT);
 
-    expect(registry.apis[0]!.outboundAccess).toBe('internet');
+    expect(registry.actions[0]!.outboundAccess).toBe('internet');
   });
 
   it('collects warnings when a file fails to load', async () => {
     mockWalkDomainDir.mockResolvedValue({
       domain: '/fake/domains/billing/domain.config.ts',
-      apis: ['/fake/domains/billing/api/broken.ts'],
       webhooks: [],
       subscribers: [],
-      actions: [],
+      actions: ['/fake/domains/billing/actions/broken.ts'],
       schedules: [],
       jobs: [],
       integrations: [],
@@ -137,6 +160,6 @@ describe('buildRegistry', () => {
 
     expect(warnings).toHaveLength(1);
     expect(warnings[0]).toContain('tsx error');
-    expect(registry.apis).toHaveLength(0);
+    expect(registry.actions).toHaveLength(0);
   });
 });

package/src/__tests__/build-types.test.ts

@@ -8,7 +8,6 @@ describe('buildActionsTypes', () => {
       schemaVersion: '1',
       domainRoot: '/test/auth',
       domain: { id: 'auth', kind: 'domain', name: 'Auth', tenancy: 'required' },
-      apis: [],
       webhooks: [],
       subscribers: [],
       schedules: [],
@@ -18,7 +17,8 @@ describe('buildActionsTypes', () => {
           id: 'verify-token',
           kind: 'action',
           handlerFile: 'verify-token.ts',
-          visibility: 'domain',
+          backendAccess: 'domain',
+          exposure: { type: 'internal' },
           idempotent: false,
         },
       ],
@@ -39,13 +39,12 @@ describe('buildActionsTypes', () => {
       schemaVersion: '1',
       domainRoot: '/test/auth',
       domain: { id: 'auth', kind: 'domain', name: 'Auth', tenancy: 'required' },
-      apis: [],
       webhooks: [],
       subscribers: [],
       schedules: [],
       jobs: [],
       actions: [
-        { id: 'verify', kind: 'action', handlerFile: 'verify.ts', visibility: 'workspace', idempotent: true },
+        { id: 'verify', kind: 'action', handlerFile: 'verify.ts', backendAccess: 'platform', exposure: { type: 'internal' }, idempotent: true },
       ],
       integrations: [],
       events: [],
@@ -55,13 +54,12 @@ describe('buildActionsTypes', () => {
       schemaVersion: '1',
       domainRoot: '/test/payments',
       domain: { id: 'payments', kind: 'domain', name: 'Payments', tenancy: 'required' },
-      apis: [],
       webhooks: [],
       subscribers: [],
       schedules: [],
       jobs: [],
       actions: [
-        { id: 'charge', kind: 'action', handlerFile: 'charge.ts', visibility: 'domain', idempotent: false },
+        { id: 'charge', kind: 'action', handlerFile: 'charge.ts', backendAccess: 'domain', exposure: { type: 'internal' }, idempotent: false },
       ],
       integrations: [],
       events: [],
@@ -78,7 +76,6 @@ describe('buildActionsTypes', () => {
       schemaVersion: '1',
       domainRoot: '/test',
       domain: { id: 'test', kind: 'domain', name: 'Test', tenancy: 'none' },
-      apis: [],
       webhooks: [],
       subscribers: [],
       schedules: [],

package/src/__tests__/builder/walkDomainDir.test.ts

@@ -19,59 +19,59 @@ describe('walkDomainDir recursive walk', () => {
     }
   });
 
-  it('should find .ts files at root of api directory', async () => {
-    const apiDir = join(tmpDir, 'api');
-    await mkdir(apiDir, { recursive: true });
-    await writeFile(join(apiDir, 'simple.ts'), 'export const api = {}');
+  it('should find .ts files at root of actions directory', async () => {
+    const actionDir = join(tmpDir, 'actions');
+    await mkdir(actionDir, { recursive: true });
+    await writeFile(join(actionDir, 'simple.ts'), 'export const action = {}');
 
     const paths = await walkDomainDir(tmpDir);
 
-    expect(paths.apis).toContain(join(apiDir, 'simple.ts'));
+    expect(paths.actions).toContain(join(actionDir, 'simple.ts'));
   });
 
-  it('should recursively find .ts files in nested api directories', async () => {
-    const nestedDir = join(tmpDir, 'api', 'users', 'v1');
+  it('should recursively find .ts files in nested action directories', async () => {
+    const nestedDir = join(tmpDir, 'actions', 'users', 'v1');
     await mkdir(nestedDir, { recursive: true });
-    await writeFile(join(nestedDir, 'get.ts'), 'export const api = {}');
+    await writeFile(join(nestedDir, 'get.ts'), 'export const action = {}');
 
     const paths = await walkDomainDir(tmpDir);
 
-    expect(paths.apis).toContain(join(nestedDir, 'get.ts'));
+    expect(paths.actions).toContain(join(nestedDir, 'get.ts'));
   });
 
   it('should skip __tests__ directories', async () => {
-    const testDir = join(tmpDir, 'api', '__tests__');
+    const testDir = join(tmpDir, 'actions', '__tests__');
     await mkdir(testDir, { recursive: true });
     await writeFile(join(testDir, 'test.ts'), 'export const test = {}');
 
     const paths = await walkDomainDir(tmpDir);
 
-    expect(paths.apis).not.toContain(join(testDir, 'test.ts'));
+    expect(paths.actions).not.toContain(join(testDir, 'test.ts'));
   });
 
   it('should skip dist directories', async () => {
-    const distDir = join(tmpDir, 'api', 'dist');
+    const distDir = join(tmpDir, 'actions', 'dist');
     await mkdir(distDir, { recursive: true });
     await writeFile(join(distDir, 'bundle.ts'), 'export const bundle = {}');
 
     const paths = await walkDomainDir(tmpDir);
 
-    expect(paths.apis).not.toContain(join(distDir, 'bundle.ts'));
+    expect(paths.actions).not.toContain(join(distDir, 'bundle.ts'));
   });
 
   it('should skip node_modules directories', async () => {
-    const nodeModulesDir = join(tmpDir, 'api', 'node_modules');
+    const nodeModulesDir = join(tmpDir, 'actions', 'node_modules');
     await mkdir(nodeModulesDir, { recursive: true });
     await writeFile(join(nodeModulesDir, 'dep.ts'), 'export const dep = {}');
 
     const paths = await walkDomainDir(tmpDir);
 
-    expect(paths.apis).not.toContain(join(nodeModulesDir, 'dep.ts'));
+    expect(paths.actions).not.toContain(join(nodeModulesDir, 'dep.ts'));
   });
 
   it('should discover files in all domain primitive directories', async () => {
     // Create files in all conventional directories
-    const dirs = ['api', 'webhooks', 'subscribers', 'actions', 'schedules', 'jobs', 'integrations'];
+    const dirs = ['webhooks', 'subscribers', 'actions', 'schedules', 'jobs', 'integrations'];
 
     for (const dir of dirs) {
       const dirPath = join(tmpDir, dir, 'nested', 'deep');
@@ -82,7 +82,6 @@ describe('walkDomainDir recursive walk', () => {
     const paths = await walkDomainDir(tmpDir);
 
     // Verify files are found in correct slots
-    expect(paths.apis.some(p => p.includes('api-handler.ts'))).toBe(true);
     expect(paths.webhooks.some(p => p.includes('webhooks-handler.ts'))).toBe(true);
     expect(paths.subscribers.some(p => p.includes('subscribers-handler.ts'))).toBe(true);
     expect(paths.actions.some(p => p.includes('actions-handler.ts'))).toBe(true);
@@ -112,7 +111,6 @@ describe('walkDomainDir recursive walk', () => {
   it('should return empty arrays for missing directories', async () => {
     const paths = await walkDomainDir(tmpDir);
 
-    expect(paths.apis).toEqual([]);
     expect(paths.webhooks).toEqual([]);
     expect(paths.subscribers).toEqual([]);
     expect(paths.actions).toEqual([]);
@@ -129,12 +127,12 @@ describe('walkDomainDir recursive walk', () => {
   });
 
   it('should handle deeply nested files', async () => {
-    const deepPath = join(tmpDir, 'api', 'v1', 'users', 'admin', 'permissions');
+    const deepPath = join(tmpDir, 'actions', 'v1', 'users', 'admin', 'permissions');
     await mkdir(deepPath, { recursive: true });
-    await writeFile(join(deepPath, 'check.ts'), 'export const api = {}');
+    await writeFile(join(deepPath, 'check.ts'), 'export const action = {}');
 
     const paths = await walkDomainDir(tmpDir);
 
-    expect(paths.apis.some(p => p.includes('check.ts'))).toBe(true);
+    expect(paths.actions.some(p => p.includes('check.ts'))).toBe(true);
   });
 });

package/src/__tests__/commands/add-api.test.ts

@@ -11,7 +11,7 @@ describe('add-api command', () => {
   beforeEach(async () => {
     tmpDir = await mkdtemp(join(tmpdir(), 'tib-add-api-test-'));
     domainDir = join(tmpDir, 'demo');
-    await mkdir(join(domainDir, 'api'), { recursive: true });
+    await mkdir(join(domainDir, 'actions'), { recursive: true });
     await writeFile(
       join(domainDir, 'domain.config.ts'),
       `export default { id: 'demo', tenancy: 'required' };\n`,
@@ -34,8 +34,8 @@ describe('add-api command', () => {
       domainsDir: tmpDir,
     });
 
-    const apiFile = join(domainDir, 'api', 'ping-thing.ts');
-    const fixtureFile = join(domainDir, 'api', '__tests__', 'ping-thing.fixture.json');
+    const apiFile = join(domainDir, 'actions', 'ping-thing.ts');
+    const fixtureFile = join(domainDir, 'actions', '__tests__', 'ping-thing.fixture.json');
 
     const apiContent = await readFile(apiFile, 'utf8');
     const fixtureContent = await readFile(fixtureFile, 'utf8');
@@ -45,9 +45,11 @@ describe('add-api command', () => {
     const parsed = JSON.parse(fixtureContent) as { event: { body: string } };
     expect(parsed.event.body).toBe('{}');
 
-    // The API file must contain .default() on input and output.
+    // The API file must contain .default() on input. Output uses a variable.
     expect(apiContent).toMatch(/input:\s*z\.object\(\{\}\)\.default\(\{\}\)/);
-    expect(apiContent).toMatch(/output:\s*z\.object\(\{\s*ok:\s*z\.boolean\(\)\s*\}\)\.default\(\{\s*ok:\s*true\s*\}\)/);
+    // The output schema is assigned to a variable then referenced via `output: outputSchema`.
+    expect(apiContent).toMatch(/output:\s*outputSchema/);
+    expect(apiContent).toMatch(/const outputSchema = z\.object\(\{\s*ok:\s*z\.boolean\(\)\s*\}\)\.default\(\{\s*ok:\s*true\s*\}\)/);
   });
 
   it('scaffolds a simple-crud pattern API with .default() on schemas', async () => {
@@ -59,8 +61,8 @@ describe('add-api command', () => {
       domainsDir: tmpDir,
     });
 
-    const apiFile = join(domainDir, 'api', 'widget.ts');
-    const fixtureFile = join(domainDir, 'api', '__tests__', 'widget.fixture.json');
+    const apiFile = join(domainDir, 'actions', 'widget.ts');
+    const fixtureFile = join(domainDir, 'actions', '__tests__', 'widget.fixture.json');
 
     const apiContent = await readFile(apiFile, 'utf8');
     const fixtureContent = await readFile(fixtureFile, 'utf8');
@@ -83,8 +85,8 @@ describe('add-api command', () => {
       domainsDir: tmpDir,
     });
 
-    const apiFile = join(domainDir, 'api', 'order.ts');
-    const fixtureFile = join(domainDir, 'api', '__tests__', 'order.fixture.json');
+    const apiFile = join(domainDir, 'actions', 'order.ts');
+    const fixtureFile = join(domainDir, 'actions', '__tests__', 'order.fixture.json');
 
     const apiContent = await readFile(apiFile, 'utf8');
     const fixtureContent = await readFile(fixtureFile, 'utf8');
@@ -106,7 +108,7 @@ describe('add-api command', () => {
       domainsDir: tmpDir,
     });
 
-    const apiFile = join(domainDir, 'api', 'console.ts');
+    const apiFile = join(domainDir, 'actions', 'console.ts');
     const apiContent = await readFile(apiFile, 'utf8');
 
     // First API: input defaults to command: 'status'; output defaults to { ok: true }.