@mettlecast/domain-cli 0.2.60 → 0.2.61

package/src/cli.ts

@@ -73,7 +73,7 @@ program
 
 program
   .command('dev <domain>')
-  .description('Start a local HTTP server simulating API Gateway for all defineApi handlers')
+  .description('Start a local HTTP server simulating API Gateway for all API-exposed defineAction handlers')
   .option('--port <n>', 'Port to listen on', '3000')
   .action(async (domain: string, opts: { port?: string }) => {
     await runDev({ domainRoot: domain, port: opts.port ? parseInt(opts.port, 10) : 3000 });

package/src/commands/add-api.ts

@@ -96,7 +96,7 @@ export async function runAddApi(opts: AddApiOptions): Promise<void> {
     throw new Error(`Domain "${opts.domain}" not found at ${domainDir}`);
   }
 
-  const apiFilePath = join(domainDir, 'api', `${opts.id}.ts`);
+  const apiFilePath = join(domainDir, 'actions', `${opts.id}.ts`);
 
   // Refuse if API already exists
   try {
@@ -124,7 +124,7 @@ export async function runAddApi(opts: AddApiOptions): Promise<void> {
   await writeFile(apiFilePath, apiContent);
 
   // Create fixture with the input schema's default shape as the example payload
-  const apiTestDir = join(domainDir, 'api', '__tests__');
+  const apiTestDir = join(domainDir, 'actions', '__tests__');
   await mkdir(apiTestDir, { recursive: true });
   await writeFile(
     join(apiTestDir, `${opts.id}.fixture.json`),

package/src/commands/add-domain.ts

@@ -51,18 +51,18 @@ export async function runAddDomain(opts: AddDomainOptions): Promise<void> {
   }
 
   // Create directory structure
-  await mkdir(join(domainDir, 'api', '__tests__'), { recursive: true });
+  await mkdir(join(domainDir, 'actions', '__tests__'), { recursive: true });
   await mkdir(join(domainDir, 'subscribers'), { recursive: true });
   await mkdir(join(domainDir, 'publishes'), { recursive: true });
 
   // Write skeleton files
   await writeFile(join(domainDir, 'domain.config.ts'), domainConfigTemplate(opts.id, opts.tenancy));
   await writeFile(
-    join(domainDir, 'api', 'example.ts'),
+    join(domainDir, 'actions', 'example.ts'),
     apiSkeletonTemplate(opts.id, 'example', opts.tenancy)
   );
   await writeFile(
-    join(domainDir, 'api', '__tests__', 'example.fixture.json'),
+    join(domainDir, 'actions', '__tests__', 'example.fixture.json'),
     apiFixtureSkeleton(opts.id, 'example')
   );
   await writeFile(join(domainDir, 'publishes', 'events.ts'), eventsSkeletonTemplate(opts.id));
@@ -94,7 +94,7 @@ export async function runAddDomain(opts: AddDomainOptions): Promise<void> {
   cliLogger.info({ id: opts.id, dir: domainDir }, 'Domain scaffolded');
   // eslint-disable-next-line no-console
   console.log(
-    `\n✓ Domain "${opts.id}" added at ${domainDir}\nNext: edit api/example.ts, ` +
+    `\n✓ Domain "${opts.id}" added at ${domainDir}\nNext: edit actions/example.ts, ` +
       `then run \`mc-domain-module build ${opts.id}\` to generate the registry.`
   );
 }

package/src/commands/add-fixture-factory.ts

@@ -47,21 +47,20 @@ export async function runAddFixtureFactory(options: AddFixtureFactoryOptions): P
   const domain = options.domain;
   const apiId = options.apiId;
 
-  const apiFile = join(projectRoot, 'domains', domain, 'api', `${apiId}.ts`);
+  const apiFile = join(projectRoot, 'domains', domain, 'actions', `${apiId}.ts`);
   await access(apiFile).catch(() => {
-    throw new Error(`API file not found: ${apiFile}. Run add-api first.`);
+    throw new Error(`Action file not found: ${apiFile}. Run add-api first.`);
   });
 
-  // Read the API file to extract the input type name
+  // Read the action file to extract the input type name
   const content = await readFile(apiFile, 'utf8');
-  const outputTypeArg = content.match(/import\s+\{\s*[\w\s,]*\s*\}\s+from\s+['"]@mettlecast/);
 
-  const factoryFile = join(projectRoot, 'domains', domain, 'api', '__tests__', `${apiId}.factory.ts`);
+  const factoryFile = join(projectRoot, 'domains', domain, 'actions', '__tests__', `${apiId}.factory.ts`);
   const factoryContent = FACTORY_TEMPLATE
     .replace(/\{domain\}/g, domain)
     .replace(/\{apiId\}/g, apiId);
 
-  await mkdir(join(projectRoot, 'domains', domain, 'api', '__tests__'), { recursive: true });
+  await mkdir(join(projectRoot, 'domains', domain, 'actions', '__tests__'), { recursive: true });
   await writeFile(factoryFile, factoryContent, 'utf8');
 
   cliLogger.info({ factoryFile }, 'add-fixture-factory: factory written');

package/src/commands/build-catalog.ts

@@ -2,27 +2,18 @@ import { readFile, writeFile, readdir, mkdir } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { cliLogger } from '../utils/logger.js';
 
-/** A single API entry in the catalog. */
-export interface CatalogApi {
-  id: string;
-  domainId: string;
-  path: string;
-  method: string;
-  authType: string;
-  description?: string;
-  requestSchema?: Record<string, unknown>;
-  responseSchema?: Record<string, unknown>;
-  versions?: Array<{ version: string; requestSchema?: Record<string, unknown>; responseSchema?: Record<string, unknown> }>;
-  examples?: { request?: Record<string, unknown>; response?: Record<string, unknown> };
-}
-
 /** A single action entry in the catalog. */
 export interface CatalogAction {
   id: string;
   domainId: string;
-  visibility: string;
+  backendAccess: string;
+  exposure: Record<string, unknown>;
+  exposureDeclared?: boolean;
   idempotent: boolean;
   description?: string;
+  handlerFile?: string;
+  deployment?: Record<string, unknown>;
+  outboundAccess?: string;
   inputSchema?: Record<string, unknown>;
   outputSchema?: Record<string, unknown>;
 }
@@ -83,7 +74,6 @@ export interface DomainCatalog {
   version: 2;
   generatedAt: string;
   domains: CatalogDomain[];
-  apis: CatalogApi[];
   actions: CatalogAction[];
   events: CatalogEvent[];
   subscribers: CatalogSubscriber[];
@@ -118,7 +108,6 @@ export async function runBuildCatalog(registryDir?: string): Promise<DomainCatal
     version: 2,
     generatedAt: new Date().toISOString(),
     domains: [],
-    apis: [],
     actions: [],
     events: [],
     subscribers: [],
@@ -152,30 +141,19 @@ export async function runBuildCatalog(registryDir?: string): Promise<DomainCatal
       description: domainEntry['description'] as string | undefined,
     });
 
-    const apis = (registry['apis'] as Record<string, unknown>[] | undefined) ?? [];
-    for (const api of apis) {
-      catalog.apis.push({
-        id: String(api['id']),
-        domainId,
-        path: String(api['path']),
-        method: String(api['method'] ?? 'ANY'),
-        authType: String(api['authType'] ?? 'jwt'),
-        description: api['description'] as string | undefined,
-        requestSchema: api['requestSchema'] as Record<string, unknown> | undefined,
-        responseSchema: api['responseSchema'] as Record<string, unknown> | undefined,
-        versions: api['versions'] as CatalogApi['versions'],
-        examples: api['examples'] as CatalogApi['examples'],
-      });
-    }
-
     const actions = (registry['actions'] as Record<string, unknown>[] | undefined) ?? [];
     for (const action of actions) {
       catalog.actions.push({
         id: String(action['id']),
         domainId,
-        visibility: String(action['visibility'] ?? 'private'),
+        backendAccess: String(action['backendAccess'] ?? 'private'),
+        exposure: (action['exposure'] as Record<string, unknown> | undefined) ?? { type: 'internal' },
+        exposureDeclared: action['exposureDeclared'] as boolean | undefined,
         idempotent: Boolean(action['idempotent'] ?? false),
         description: action['description'] as string | undefined,
+        handlerFile: action['handlerFile'] as string | undefined,
+        deployment: action['deployment'] as Record<string, unknown> | undefined,
+        outboundAccess: action['outboundAccess'] as string | undefined,
         inputSchema: action['inputSchema'] as Record<string, unknown> | undefined,
         outputSchema: action['outputSchema'] as Record<string, unknown> | undefined,
       });
@@ -241,7 +219,7 @@ export async function runBuildCatalog(registryDir?: string): Promise<DomainCatal
   await writeFile(outPath, JSON.stringify(catalog), 'utf8');
 
   cliLogger.info(
-    { outPath, domains: catalog.domains.length, apis: catalog.apis.length, actions: catalog.actions.length, events: catalog.events.length, jobs: catalog.jobs.length, schedules: catalog.schedules.length, integrations: catalog.integrations.length },
+    { outPath, domains: catalog.domains.length, actions: catalog.actions.length, events: catalog.events.length, jobs: catalog.jobs.length, schedules: catalog.schedules.length, integrations: catalog.integrations.length },
     'Domain catalog written'
   );
 

package/src/commands/build.ts

@@ -1,6 +1,6 @@
 import { writeFile, mkdir, readdir, readFile } from 'node:fs/promises';
 import { join, resolve, basename } from 'node:path';
-import type { DomainRegistry } from '@mettlecast/domain-cdk-packer';
+import type { DomainRegistry } from '../types.js';
 import { buildRegistry } from '../builder/build-registry.js';
 import { buildActionsTypes } from '../builder/build-types.js';
 import { cliLogger } from '../utils/logger.js';
@@ -40,7 +40,8 @@ export async function runBuild(options: BuildOptions): Promise<string> {
   await mkdir(join(outFile, '..'), { recursive: true });
   await writeFile(outFile, JSON.stringify(registry), 'utf8');
 
-  cliLogger.info({ outFile, apis: registry.apis.length, events: registry.events.length }, 'Registry written');
+  const apiExposedActions = registry.actions.filter(action => action.exposure.type === 'api').length;
+  cliLogger.info({ outFile, apiExposedActions, events: registry.events.length }, 'Registry written');
 
   // Discover all sibling registries and emit aggregated types
   const registryDir = join(outFile, '..');

package/src/commands/dev.ts

@@ -55,7 +55,7 @@ export async function startDev(options: DevOptions): Promise<DevHandle> {
   }
 
   cliLogger.info(
-    { domain: registry.domain.id, apis: registry.apis.length, port },
+    { domain: registry.domain.id, apiActions: registry.actions.filter(a => a.exposure?.type === 'api').length, port },
     'Starting local dev server'
   );
 

package/src/commands/doctor.ts

@@ -121,8 +121,10 @@ async function checkHandlersUseResult(projectRoot: string): Promise<DoctorCheck>
     const missing: string[] = [];
     for (const file of apiFiles) {
       const content = await readFile(file, 'utf8');
-      // A file contains a handler export — check the return type
-      if (/defineApi\s*\(/.test(content)) {
+      // A file contains a handler export — check the return type.
+      // Issue #4689: defineApi was removed. The action-first
+      // contract uses defineAction with exposure.type='api'.
+      if (/defineAction\s*\(/.test(content)) {
         // Look for Result<T> in the handler's return type annotation
         if (!/: .*Result</.test(content)) {
           missing.push(relative(projectRoot, file));
@@ -448,49 +450,64 @@ async function checkNoCrossDomainImports(projectRoot: string): Promise<DoctorChe
 async function checkApisHaveVersions(projectRoot: string): Promise<DoctorCheck> {
   try {
     const domainsDir = join(projectRoot, 'domains');
-    const allApiFiles: string[] = [];
+    const allActionFiles: string[] = [];
 
-    // Find all API files in all domains
+    // Find API-exposed action files in both actions/ and api/ directories.
+    // Issue #4689: defineApi was removed. API-exposed actions live in
+    // domains/*/actions/ but legacy api/ directories may still exist.
     const entries = await readdir(domainsDir, { withFileTypes: true });
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
-      const apiDir = join(domainsDir, entry.name, 'api');
-      const apiFiles = findFiles(apiDir, /\.ts$/);
-      allApiFiles.push(...apiFiles);
+      for (const dir of ['actions', 'api']) {
+        const actionDir = join(domainsDir, entry.name, dir);
+        const files = findFiles(actionDir, /\.ts$/);
+        allActionFiles.push(...files);
+      }
     }
-    const apiFiles = allApiFiles;
 
-    if (apiFiles.length === 0) {
+    // Only consider files that define an API-exposed action (defineAction
+    // with exposure.type === 'api' or exposure: { type: 'api' }).
+    const apiExposedFiles: string[] = [];
+    for (const file of allActionFiles) {
+      const content = await readFile(file, 'utf8');
+      if (/defineAction\s*\(/.test(content) && /exposure\s*:\s*\{\s*type\s*:\s*['"]api['"]/.test(content)) {
+        apiExposedFiles.push(file);
+      }
+    }
+
+    if (apiExposedFiles.length === 0) {
       return {
         name: 'APIs declare versions',
         status: 'PASS',
-        message: 'No APIs found (optional)',
+        message: 'No API-exposed actions found (optional)',
         kNodeRef: 'K:runbook:add-domain',
       };
     }
 
-    // Simple heuristic: grep for 'versions:' in each API file
-    let missingVersions = 0;
-    for (const file of apiFiles) {
+    // Issue #4689: action-first contract requires input/output Zod schemas
+    // with `.default({...})` example data. Check that each API-exposed
+    // action file contains `.default(` (indicating example data).
+    let missingDefaults = 0;
+    for (const file of apiExposedFiles) {
       const content = await readFile(file, 'utf8');
-      if (!content.includes('versions:')) {
-        missingVersions++;
+      if (!content.includes('.default(')) {
+        missingDefaults++;
       }
     }
 
-    if (missingVersions === 0) {
+    if (missingDefaults === 0) {
       return {
         name: 'APIs declare versions',
         status: 'PASS',
-        message: `All ${apiFiles.length} API files declare versions`,
+        message: `All ${apiExposedFiles.length} API-exposed action(s) have .default() example data`,
         kNodeRef: 'K:runbook:add-domain',
       };
     } else {
       return {
         name: 'APIs declare versions',
         status: 'FAIL',
-        message: `${missingVersions}/${apiFiles.length} API files missing versions: field`,
-        fixHint: 'Add versions: { v1: { ... } } to defineApi calls',
+        message: `${missingDefaults}/${apiExposedFiles.length} API-exposed action(s) missing .default() example data. Add \`.default({...})\` to the top-level input and output Zod schemas in each defineAction({ exposure: { type: 'api', ... } }) call.`,
+        fixHint: "Add `input` and `output` Zod schemas with `.default({...})` to defineAction({ exposure: { type: 'api', ... } }) calls",
         kNodeRef: 'K:runbook:add-domain',
       };
     }
@@ -498,7 +515,7 @@ async function checkApisHaveVersions(projectRoot: string): Promise<DoctorCheck>
     return {
       name: 'APIs declare versions',
       status: 'WARN',
-      message: `Could not check API versions: ${String(err)}`,
+      message: `Could not check API schemas: ${String(err)}`,
       kNodeRef: 'K:runbook:add-domain',
     };
   }
@@ -507,30 +524,42 @@ async function checkApisHaveVersions(projectRoot: string): Promise<DoctorCheck>
 async function checkApisHaveTenancy(projectRoot: string): Promise<DoctorCheck> {
   try {
     const domainsDir = join(projectRoot, 'domains');
-    const allApiFiles: string[] = [];
+    const allActionFiles: string[] = [];
 
-    // Find all API files in all domains
+    // Find API-exposed action files in both actions/ and api/ directories.
+    // Issue #4689: defineApi was removed. Tenancy is now declared on the
+    // action's exposure block via `exposure.tenancy`.
     const entries = await readdir(domainsDir, { withFileTypes: true });
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
-      const apiDir = join(domainsDir, entry.name, 'api');
-      const apiFiles = findFiles(apiDir, /\.ts$/);
-      allApiFiles.push(...apiFiles);
+      for (const dir of ['actions', 'api']) {
+        const actionDir = join(domainsDir, entry.name, dir);
+        const files = findFiles(actionDir, /\.ts$/);
+        allActionFiles.push(...files);
+      }
     }
-    const apiFiles = allApiFiles;
 
-    if (apiFiles.length === 0) {
+    // Only consider files that define an API-exposed action.
+    const apiExposedFiles: string[] = [];
+    for (const file of allActionFiles) {
+      const content = await readFile(file, 'utf8');
+      if (/defineAction\s*\(/.test(content) && /exposure\s*:\s*\{\s*type\s*:\s*['"]api['"]/.test(content)) {
+        apiExposedFiles.push(file);
+      }
+    }
+
+    if (apiExposedFiles.length === 0) {
       return {
         name: 'APIs declare tenancy',
         status: 'PASS',
-        message: 'No APIs found (optional)',
+        message: 'No API-exposed actions found (optional)',
         kNodeRef: 'K:convention:tier-1-foundations',
       };
     }
 
-    // Simple heuristic: grep for 'tenancy:' in each API file
+    // Check for `tenancy:` anywhere in each API-exposed action file.
     let missingTenancy = 0;
-    for (const file of apiFiles) {
+    for (const file of apiExposedFiles) {
       const content = await readFile(file, 'utf8');
       if (!content.includes('tenancy:')) {
         missingTenancy++;
@@ -541,15 +570,15 @@ async function checkApisHaveTenancy(projectRoot: string): Promise<DoctorCheck> {
       return {
         name: 'APIs declare tenancy',
         status: 'PASS',
-        message: `All ${apiFiles.length} API files declare tenancy`,
+        message: `All ${apiExposedFiles.length} API-exposed action(s) declare tenancy`,
         kNodeRef: 'K:convention:tier-1-foundations',
       };
     } else {
       return {
         name: 'APIs declare tenancy',
         status: 'FAIL',
-        message: `${missingTenancy}/${apiFiles.length} API files missing tenancy: field`,
-        fixHint: "Add tenancy: 'required' | 'none' | 'system' to defineApi calls",
+        message: `${missingTenancy}/${apiExposedFiles.length} API-exposed action(s) missing tenancy. Tenancy must be declared on the action's exposure block: \`exposure.tenancy: 'required' | 'none' | 'system'\`.`,
+        fixHint: "Add `exposure.tenancy: 'required' | 'none' | 'system'` to defineAction({ exposure: { type: 'api', ... } }) calls",
         kNodeRef: 'K:convention:tier-1-foundations',
       };
     }
@@ -873,7 +902,7 @@ async function checkAllRoutesUseTanStackRouter(projectRoot: string): Promise<Doc
 
 /**
  * Check W5-4: Lambda handler files contain initOtel() call.
- * Scans `domains/*\/api/*.ts` and FAILs if any handler is missing initOtel().
+  * Scans `domains/*\/actions/*.ts` and `domains/*\/api/*.ts` and FAILs if any handler is missing initOtel().
  */
 async function checkOtelInitInLambdas(projectRoot: string): Promise<DoctorCheck> {
   try {
@@ -890,9 +919,11 @@ async function checkOtelInitInLambdas(projectRoot: string): Promise<DoctorCheck>
     const handlerFiles: string[] = [];
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
-      const apiDir = join(domainsDir, entry.name, 'api');
-      const files = findFiles(apiDir, /\.ts$/);
-      handlerFiles.push(...files);
+      for (const dir of ['actions', 'api']) {
+        const handlerDir = join(domainsDir, entry.name, dir);
+        const files = findFiles(handlerDir, /\.ts$/);
+        handlerFiles.push(...files);
+      }
     }
 
     if (handlerFiles.length === 0) {

package/src/commands/explain.ts

@@ -58,25 +58,25 @@ const RULE_EXPLANATIONS: Record<string, RuleExplanation> = {
     ruleId: 'no-raw-http-server',
     title: 'No raw HTTP server in domain code',
     description:
-      'Domain code must not create raw HTTP servers (express, fastify, etc.). All HTTP handling goes through defineApi which is wired to API Gateway by the scaffold.',
+      'Domain code must not create raw HTTP servers (express, fastify, etc.). All HTTP handling goes through defineAction with exposure.type=\'api\' which is wired to API Gateway by the scaffold.',
     severity: 'error',
     category: 'structure',
     kNodeRef: 'K:convention:tier-1-foundations',
-    fixHint: 'Wrap your HTTP handler with defineApi({ ... }). The scaffold handles API Gateway wiring.',
+    fixHint: 'Wrap your HTTP handler with defineAction({ exposure: { type: \'api\', ... } }). The scaffold handles API Gateway wiring.',
     exampleBad: "import express from 'express';\nconst app = express();",
-    exampleGood: "export const myApi = defineApi({ id: 'my-api', path: '/v1/my-api', ... });",
+    exampleGood: "export const myAction = defineAction({ id: 'my-action', exposure: { type: 'api', path: '/v1/my-action', method: 'GET', auth: 'required', tenancy: 'required' }, ... });",
   },
   'require-define-primitive': {
     ruleId: 'require-define-primitive',
     title: 'Require define primitive factories',
     description:
-      'All domain handlers must use the appropriate factory function: defineApi for HTTP APIs, defineSubscriber for event subscribers, defineAction for cross-domain actions, defineJob for background jobs.',
+      'All domain handlers must use the appropriate factory function: defineAction (HTTP APIs via exposure.type=\'api\', or internal-only actions), defineSubscriber for event subscribers, defineJob for background jobs, defineWebhook for webhooks, defineEvent for event types.',
     severity: 'error',
     category: 'structure',
     kNodeRef: 'K:runbook:add-domain',
     fixHint: "Wrap your handler with the appropriate define* factory from @mettlecast/domain-runtime.",
     exampleBad: "export const handler = async (event) => ({ statusCode: 200 });",
-    exampleGood: "export const myApi = defineApi({ id: 'my-api', ... });",
+    exampleGood: "export const myAction = defineAction({ id: 'my-action', exposure: { type: 'api', ... }, ... });",
   },
   'flow-domain-ownership': {
     ruleId: 'flow-domain-ownership',
@@ -106,25 +106,25 @@ const RULE_EXPLANATIONS: Record<string, RuleExplanation> = {
     ruleId: 'apis-have-versions',
     title: 'APIs declare versions',
     description:
-      'Every defineApi must have a versions field with at least one version entry. Versioning is mandatory for API evolution.',
+      'Every API-exposed action (defineAction with exposure.type=\'api\') must declare input and output Zod schemas with .default() so the runtime has a concrete example payload. The action-first contract replaced legacy defineApi\'s versions map (#4689).',
     severity: 'error',
     category: 'correctness',
     kNodeRef: 'K:runbook:add-domain',
-    fixHint: 'Add versions: { v1: { status, input, output, handler } } to your defineApi call.',
-    exampleBad: "defineApi({ id: 'my-api', path: '/v1/my-api' }) // missing versions",
-    exampleGood: "defineApi({ id: 'my-api', path: '/v1/my-api', versions: { v1: { ... } } });",
+    fixHint: 'Add Zod input/output schemas to your defineAction call (e.g. z.object({...}).default({...})).',
+    exampleBad: "defineAction({ id: 'my-action', exposure: { type: 'api', path: '/v1/my-action', ... }, handler: ... }) // missing input/output schemas",
+    exampleGood: "defineAction({ id: 'my-action', exposure: { type: 'api', ... }, input: z.object({...}).default({...}), output: z.object({...}).default({...}), handler: ... });",
   },
   'apis-have-tenancy': {
     ruleId: 'apis-have-tenancy',
     title: 'APIs declare tenancy',
     description:
-      'Every defineApi must declare its tenancy mode: required (tenant-scoped), none (tenant-agnostic like registration), or system (system-internal admin).',
+      'Every defineAction with exposure.type=\'api\' must declare exposure.tenancy: required (tenant-scoped), none (tenant-agnostic like registration), or system (system-internal admin). The action-first contract enforces this at registration time (#4689).',
     severity: 'error',
     category: 'correctness',
     kNodeRef: 'K:convention:tier-1-foundations',
-    fixHint: "Add tenancy: 'required' | 'none' | 'system' to your defineApi call.",
-    exampleBad: "defineApi({ id: 'my-api', path: '/v1/my-api' }) // missing tenancy",
-    exampleGood: "defineApi({ id: 'my-api', path: '/v1/my-api', tenancy: 'required' });",
+    fixHint: "Add `exposure.tenancy: 'required' | 'none' | 'system'` to your defineAction call.",
+    exampleBad: "defineAction({ id: 'my-action', exposure: { type: 'api', path: '/v1/my-action' }, ... }) // missing exposure.tenancy",
+    exampleGood: "defineAction({ id: 'my-action', exposure: { type: 'api', path: '/v1/my-action', method: 'GET', auth: 'required', tenancy: 'required' }, ... });",
   },
   'no-cross-domain-imports': {
     ruleId: 'no-cross-domain-imports',

package/src/commands/generate-openapi.ts

@@ -1,7 +1,12 @@
 /**
  * generate-openapi — read a domain's registry and produce an OpenAPI 3.1
  * specification as JSON. The registry is consumed at build time; each
- * `defineApi` entry contributes one path under the domain's route prefix.
+ * `defineAction({ exposure: { type: 'api', ... } })` entry contributes
+ * one path under the domain's route prefix.
+ *
+ * Issue #4689: the legacy `defineApi` factory was removed and the
+ * `registry.apis` slot is now always empty in new registries. This
+ * command therefore reads exclusively from `actions[]`.
  *
  * Usage: npx mc-domain-module generate-openapi <domain>
  */
@@ -17,51 +22,24 @@ export interface GenerateOpenapiOptions {
   output?: string;
 }
 
-interface ApiRegistryEntry {
-  id: string;
-  path: string;
-  method: string;
-  tenancy: string;
-  versions: Record<string, {
-    status: string;
-    inputSchema?: unknown;
-    outputSchema?: unknown;
-    input?: unknown;
-    output?: unknown;
-  }>;
-  examples?: { request?: unknown; response?: unknown };
-}
-
 interface DomainRegistry {
   domain: { id: string };
-  apis: ApiRegistryEntry[];
+  actions: Array<{
+    id: string;
+    exposure?: {
+      type: 'api' | 'internal';
+      path?: string;
+      method?: string;
+    };
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+  }>;
 }
 
 /**
- * Extract a Zod schema shape from a registry entry version.
- * The registry may store schemas as `input`/`output` (raw Zod
- * objects) or `inputSchema`/`outputSchema` (JSON Schema shapes).
- * Returns a best-effort JSON Schema object for the OpenAPI spec.
+ * Run the generate-openapi command: read the domain's registry and emit
+ * an OpenAPI 3.1 spec covering every API-exposed action.
  */
-function extractSchema(version: ApiRegistryEntry['versions'][string], field: 'input' | 'output'): unknown {
-  // Prefer JSON Schema if present
-  const schemaField = field === 'input' ? version.inputSchema : version.outputSchema;
-  if (schemaField && typeof schemaField === 'object' && schemaField !== null) {
-    return schemaField;
-  }
-  // Fall back to the raw Zod shape — try to produce a minimal JSON
-  // Schema from the Zod _def. For full support, add zod-to-json-schema
-  // to the CLI dependencies and call `zodToJsonSchema(zodSchema)`.
-  const raw = field === 'input' ? version.input : version.output;
-  if (raw && typeof raw === 'object' && raw !== null) {
-    // Attempt minimal mapping: if the Zod shape has a `type` field
-    // from its _def, describe it as JSON Schema.
-    const def = raw as { type?: string; items?: unknown; properties?: unknown; required?: string[] };
-    return { type: def.type ?? 'object', properties: def.properties, required: def.required };
-  }
-  return { type: 'object' };
-}
-
 export async function runGenerateOpenapi(options: GenerateOpenapiOptions): Promise<string> {
   const projectRoot = options.projectRoot ?? process.cwd();
   const domain = options.domain;
@@ -74,22 +52,22 @@ export async function runGenerateOpenapi(options: GenerateOpenapiOptions): Promi
 
   const paths: Record<string, unknown> = {};
 
-  for (const api of registry.apis) {
-    const method = (api.method ?? 'get').toLowerCase();
-    const fullPath = `/v1/${domain}${api.path}`;
-    const v1 = api.versions['v1'] ?? api.versions[Object.keys(api.versions)[0]];
-    if (!v1) continue;
+  for (const action of registry.actions ?? []) {
+    if (action.exposure?.type !== 'api') continue;
+    const method = (action.exposure.method ?? 'get').toLowerCase();
+    const fullPath = `/v1/${domain}${action.exposure.path}`;
+    const inputSchema = action.inputSchema ?? { type: 'object' };
+    const outputSchema = action.outputSchema ?? { type: 'object' };
 
     if (!paths[fullPath]) paths[fullPath] = {};
-
     (paths[fullPath] as Record<string, unknown>)[method] = {
-      operationId: `${domain}.${api.id}`,
-      summary: `${domain}.${api.id}`,
-      description: `Version: ${v1.status}`,
+      operationId: `${domain}.${action.id}`,
+      summary: `${domain}.${action.id}`,
+      description: 'Action-first contract (defineAction + exposure.type=api).',
       requestBody: {
         content: {
           'application/json': {
-            schema: extractSchema(v1, 'input'),
+            schema: inputSchema,
           },
         },
       },
@@ -98,7 +76,7 @@ export async function runGenerateOpenapi(options: GenerateOpenapiOptions): Promi
           description: 'OK',
           content: {
             'application/json': {
-              schema: extractSchema(v1, 'output'),
+              schema: outputSchema,
             },
           },
         },
@@ -151,4 +129,4 @@ export async function runGenerateOpenapiCli(domain: string, opts: { projectRoot?
   const outputPath = await runGenerateOpenapi({ domain, ...opts });
   // eslint-disable-next-line no-console
   console.log(`OpenAPI spec written to: ${outputPath}`);
-}
+}

package/src/commands/show.ts

@@ -21,10 +21,10 @@ export interface ShowDomainOptions {
 const KEBAB_REGEX = /^[a-z][a-z0-9-]*$/;
 
 /**
- * Represents a primitive entry (API, subscriber, action, or job).
+ * Represents a primitive entry (action, subscriber, or job).
  */
 interface PrimitiveEntry {
-  type: 'api' | 'subscriber' | 'action' | 'job';
+  type: 'subscriber' | 'action' | 'job';
   id: string;
   file: string;
 }
@@ -35,7 +35,6 @@ interface PrimitiveEntry {
 interface DomainSummary {
   domain: string;
   primitives: {
-    apis: PrimitiveEntry[];
     subscribers: PrimitiveEntry[];
     actions: PrimitiveEntry[];
     jobs: PrimitiveEntry[];
@@ -114,7 +113,6 @@ export async function runShowDomain(opts: ShowDomainOptions): Promise<DomainSumm
   }
 
   // Scan primitives
-  const apis = await scanPrimitives(join(domainDir, 'api'), 'api');
   const subscribers = await scanPrimitives(join(domainDir, 'subscribers'), 'subscriber');
   const actions = await scanPrimitives(join(domainDir, 'actions'), 'action');
   const jobs = await scanPrimitives(join(domainDir, 'jobs'), 'job');
@@ -155,7 +153,6 @@ export async function runShowDomain(opts: ShowDomainOptions): Promise<DomainSumm
   const summary: DomainSummary = {
     domain: opts.domain,
     primitives: {
-      apis,
       subscribers,
       actions,
       jobs,