@mettlecast/domain-cli 0.2.59 → 0.2.61

package/dist/commands/doctor.js

@@ -59,8 +59,10 @@ async function checkHandlersUseResult(projectRoot) {
         const missing = [];
         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));
@@ -157,15 +159,14 @@ async function checkGeneratedClientsFresh(projectRoot) {
  */
 export async function runDoctor(opts = {}) {
     const projectRoot = opts.projectRoot ?? process.cwd();
-    // --relocate runs ONLY the relocation routine (existing behaviour).
-    // --fix is a superset: it runs relocation first, then the full report.
+    // --relocate is retained as a safe no-op for older automation.
+    // --fix runs that no-op preflight first, then the full report.
     // When both are set, --fix takes precedence so the report still runs.
     if (opts.relocate && !opts.fix) {
         return runRelocate(projectRoot);
     }
-    // --fix preflight: run the relocation routine and merge its checks into
-    // the doctor report. On a clean project (no files outside .mc/ to move)
-    // runRelocate returns a no-op summary check (0 moved, 0 warned, 8 skipped).
+    // --fix preflight: run the legacy relocation no-op and merge its check into
+    // the doctor report.
     let preflightChecks = [];
     if (opts.fix) {
         const relocationReport = await runRelocate(projectRoot);
@@ -362,38 +363,52 @@ async function checkNoCrossDomainImports(projectRoot) {
 async function checkApisHaveVersions(projectRoot) {
     try {
         const domainsDir = join(projectRoot, 'domains');
-        const allApiFiles = [];
-        // Find all API files in all domains
+        const allActionFiles = [];
+        // 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 = [];
+        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',
             };
         }
@@ -401,8 +416,8 @@ async function checkApisHaveVersions(projectRoot) {
             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',
             };
         }
@@ -411,7 +426,7 @@ async function checkApisHaveVersions(projectRoot) {
         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',
         };
     }
@@ -419,28 +434,39 @@ async function checkApisHaveVersions(projectRoot) {
 async function checkApisHaveTenancy(projectRoot) {
     try {
         const domainsDir = join(projectRoot, 'domains');
-        const allApiFiles = [];
-        // Find all API files in all domains
+        const allActionFiles = [];
+        // 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 = [];
+        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++;
@@ -450,7 +476,7 @@ async function checkApisHaveTenancy(projectRoot) {
             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',
             };
         }
@@ -458,8 +484,8 @@ async function checkApisHaveTenancy(projectRoot) {
             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',
             };
         }
@@ -475,13 +501,21 @@ async function checkApisHaveTenancy(projectRoot) {
 }
 async function checkScaffoldConfigMatchesDisk(projectRoot) {
     try {
-        const configPath = join(projectRoot, '.tib', 'scaffold-config.json');
+        const configPath = join(projectRoot, '.mc', 'scaffold-config.json');
         const domainsDir = join(projectRoot, 'domains');
         let configDomains = [];
         try {
             const configContent = await readFile(configPath, 'utf8');
             const config = JSON.parse(configContent);
-            configDomains = config.domainIds ?? [];
+            if (!Array.isArray(config.domainIds)) {
+                return {
+                    name: 'scaffold-config.json matches on-disk',
+                    status: 'PASS',
+                    message: '.mc/scaffold-config.json has no domainIds array — domain list sync check skipped',
+                    kNodeRef: 'K:runbook:add-domain',
+                };
+            }
+            configDomains = config.domainIds;
         }
         catch {
             return {
@@ -769,7 +803,7 @@ async function checkAllRoutesUseTanStackRouter(projectRoot) {
 }
 /**
  * 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) {
     try {
@@ -787,9 +821,11 @@ async function checkOtelInitInLambdas(projectRoot) {
         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) {
             return { name: 'OTel init in Lambdas', status: 'PASS',
@@ -1114,7 +1150,7 @@ async function checkDomainBrainReachable(projectRoot) {
  */
 async function checkActionsHaveTypes(projectRoot) {
     try {
-        const typesPath = join(projectRoot, '.tib', 'actions-types.d.ts');
+        const typesPath = join(projectRoot, '.mc', 'actions-types.d.ts');
         const domainsDir = join(projectRoot, 'domains');
         const discoveredActions = [];
         try {
@@ -1347,7 +1383,7 @@ async function checkSeedPagesHaveNoHeaders(projectRoot) {
 }
 /**
  * Check Part C: Layout validation checks
- * 1. owned files in unexpected locations
+ * 1. managed files are not registered in obsolete legacy locations
  * 2. tracked/seed files inside .mc/
  * 3. manifest entries pointing at missing files
  * 4. scaffold-tracked files (with @mc-scaffold: header) that lack manifest entries
@@ -1361,25 +1397,26 @@ async function checkLayoutPolicy(projectRoot) {
         // No manifest — skip layout checks
         return [];
     }
-    // Check 1: owned files in unexpected locations
-    // Policy: owned files should be in .mc/ OR .github/workflows/tib-*
-    const ownedOutsideTib = manifest.files.filter(f => f.policy === 'managed' &&
-        !f.path.startsWith('.mc/') &&
-        !/^\.github\/workflows\/tib-/.test(f.path));
-    if (ownedOutsideTib.length === 0) {
+    // Check 1: managed files should not be registered in obsolete legacy
+    // locations. Current scaffold manifests intentionally track managed files at
+    // their installed paths (infra/modules, domains, .github, CLAUDE.md, etc.).
+    const legacyManagedLocations = manifest.files.filter(f => f.policy === 'managed' && (f.path.startsWith('.tib/') ||
+        f.path.startsWith('.mc/infra/') ||
+        f.path === 'mc-deploy.yml'));
+    if (legacyManagedLocations.length === 0) {
         results.push({
-            name: 'Layout: owned files in .mc/',
+            name: 'Layout: no managed files in legacy locations',
             status: 'PASS',
-            message: 'All owned scaffold files are under .mc/ or .github/workflows/tib-*',
+            message: 'Managed scaffold files use current manifest paths',
         });
     }
     else {
-        for (const f of ownedOutsideTib) {
+        for (const f of legacyManagedLocations) {
             results.push({
-                name: 'Layout: owned files in .mc/',
+                name: 'Layout: no managed files in legacy locations',
                 status: 'FAIL',
-                message: `Owned scaffold file outside .mc/: ${f.path}`,
-                fixHint: `Run 'tib doctor --relocate' to migrate ${f.path} to .mc/`,
+                message: `Managed scaffold file registered in legacy location: ${f.path}`,
+                fixHint: 'Run `npx mc-domain-module upgrade` to refresh scaffold metadata',
                 file: f.path,
             });
         }
@@ -1428,7 +1465,7 @@ async function checkLayoutPolicy(projectRoot) {
             name: 'Layout: manifest entries exist on disk',
             status: 'FAIL',
             message: `${missingFiles.length} manifest entry/entries point to missing files:\n  ${missingFiles.join('\n  ')}`,
-            fixHint: 'Run tib doctor --relocate or tib upgrade to fix missing files',
+            fixHint: 'Run `npx mc-domain-module upgrade` to refresh scaffold metadata, or restore the missing files',
         });
     }
     // Check 4: scaffold-tracked files (with @mc-scaffold: header) that lack manifest entries
@@ -1483,154 +1520,25 @@ async function checkLayoutPolicy(projectRoot) {
             name: 'Layout: scaffold-tracked files have manifest entries',
             status: 'WARN',
             message: `${untracked.length} file(s) with @mc-scaffold: header not in manifest:\n  ${untracked.join('\n  ')}`,
-            fixHint: 'Run tib upgrade or tib doctor --relocate to register these files',
+            fixHint: 'Run `npx mc-domain-module upgrade` to refresh scaffold metadata',
         });
     }
     return results;
 }
 /**
- * Old path → new path mapping for known scaffold files
- */
-const RELOCATION_MAP = [
-    { oldPath: 'infra/modules/app.ts', newPath: '.mc/infra/modules/app.ts', policy: 'managed' },
-    { oldPath: 'infra/modules/shared/SharedStack.ts', newPath: '.mc/infra/modules/shared/SharedStack.ts', policy: 'managed' },
-    { oldPath: 'infra/modules/domains/dispatch-middleware.ts', newPath: '.mc/infra/modules/domains/dispatch-middleware.ts', policy: 'managed' },
-    { oldPath: 'infra/modules/PowerTuningStack.ts', newPath: '.mc/infra/modules/PowerTuningStack.ts', policy: 'managed' },
-    { oldPath: 'infra/cdk.json', newPath: '.mc/infra/cdk.json', policy: 'managed' },
-    { oldPath: 'infra/tsconfig.json', newPath: '.mc/infra/tsconfig.json', policy: 'managed' },
-    { oldPath: 'infra/package.json', newPath: '.mc/infra/package.json', policy: 'managed' },
-    { oldPath: 'mc-deploy.yml', newPath: '.github/workflows/mc-deploy.yml', policy: 'managed' },
-];
-/**
- * Run relocation of old-layout scaffold files to new layout
+ * Legacy relocation entrypoint retained for older automation.
+ *
+ * Earlier scaffold versions tried to move generated infra into .mc/infra. The
+ * current scaffold contract keeps generated infra under infra/modules and uses
+ * .mc/manifest.json plus .mc/modules-hashes.json for ownership/drift tracking.
+ * Moving files here would corrupt modern projects, so relocation is now a no-op.
  */
 async function runRelocate(projectRoot) {
-    const checks = [];
-    const { readManifest, writeManifest, upsertManifestFile } = await import('../utils/manifest.js');
-    const { readFile, writeFile, mkdir, unlink } = await import('node:fs/promises');
-    const { computeChecksumFile, computeChecksumString } = await import('../utils/checksum.js');
-    const { join, dirname } = await import('node:path');
-    const manifest = await readManifest(projectRoot);
-    if (!manifest) {
-        checks.push({
-            name: 'Relocate: manifest present',
-            status: 'FAIL',
-            message: '.mc/manifest.json not found — cannot relocate without a manifest',
-            fixHint: 'This project may not be a TIB scaffold project',
-        });
-        return { checks, exitCode: 1, pass: false };
-    }
-    let moved = 0;
-    let warned = 0;
-    let skipped = 0;
-    for (const { oldPath, newPath, policy } of RELOCATION_MAP) {
-        const oldAbsPath = join(projectRoot, oldPath);
-        const newAbsPath = join(projectRoot, newPath);
-        // Check if old file exists
-        const { access: fsAccess } = await import('node:fs/promises');
-        try {
-            await fsAccess(oldAbsPath);
-        }
-        catch {
-            skipped++;
-            continue;
-        }
-        // Check if it has the scaffold header (confirm it's scaffold-owned)
-        let content;
-        try {
-            content = await readFile(oldAbsPath, 'utf-8');
-        }
-        catch {
-            skipped++;
-            continue;
-        }
-        if (!content.includes('@mc-scaffold:')) {
-            // File exists but no header — user-owned, leave it
-            checks.push({
-                name: 'Relocate: checking ' + oldPath,
-                status: 'WARN',
-                message: `${oldPath} has no @mc-scaffold: header — left in place (user-owned)`,
-                file: oldPath,
-            });
-            warned++;
-            continue;
-        }
-        // Check for user drift
-        const manifestEntry = manifest.files.find(f => f.path === oldPath);
-        if (manifestEntry) {
-            const diskSha = await computeChecksumFile(oldAbsPath);
-            if (diskSha && diskSha !== manifestEntry.sha256) {
-                // File has been modified — leave with warning
-                checks.push({
-                    name: 'Relocate: checking ' + oldPath,
-                    status: 'WARN',
-                    message: `${oldPath} has local modifications — left in place. Migrate manually: move to ${newPath}`,
-                    file: oldPath,
-                });
-                warned++;
-                continue;
-            }
-        }
-        // Check if destination already exists
-        try {
-            await fsAccess(newAbsPath);
-            checks.push({
-                name: 'Relocate: ' + oldPath,
-                status: 'WARN',
-                message: `${newPath} already exists — skipping move of ${oldPath}`,
-                file: newPath,
-            });
-            warned++;
-            continue;
-        }
-        catch { /* destination doesn't exist, good */ }
-        // Move the file
-        try {
-            await mkdir(dirname(newAbsPath), { recursive: true });
-            // Copy + delete (rename may fail across filesystems)
-            await writeFile(newAbsPath, content, 'utf-8');
-            // Update manifest: remove old entry, add new with new path + policy
-            manifest.files = manifest.files.filter(f => f.path !== oldPath);
-            const sha256 = manifestEntry?.sha256 ?? computeChecksumString(content);
-            upsertManifestFile(manifest, {
-                path: newPath,
-                module: manifestEntry?.module ?? 'domain',
-                moduleVersion: manifestEntry?.moduleVersion ?? '1.0.0',
-                sha256,
-                wasTemplate: manifestEntry?.wasTemplate ?? false,
-                installedAt: manifestEntry?.installedAt ?? new Date().toISOString(),
-                policy,
-            });
-            // Delete old file
-            await unlink(oldAbsPath);
-            checks.push({
-                name: 'Relocate: ' + oldPath,
-                status: 'PASS',
-                message: `Moved ${oldPath} → ${newPath} (policy: ${policy})`,
-                file: newPath,
-            });
-            moved++;
-        }
-        catch (err) {
-            checks.push({
-                name: 'Relocate: ' + oldPath,
-                status: 'FAIL',
-                message: `Failed to move ${oldPath} → ${newPath}: ${String(err)}`,
-                file: oldPath,
-            });
-        }
-    }
-    // Write updated manifest
-    if (moved > 0) {
-        await writeManifest(projectRoot, manifest);
-    }
-    // Summary check
-    checks.push({
-        name: 'Relocate: summary',
-        status: warned > 0 ? 'WARN' : 'PASS',
-        message: `Relocation complete: ${moved} file(s) moved, ${warned} warning(s), ${skipped} skipped (not present)`,
-    });
-    const hasFail = checks.some(c => c.status === 'FAIL');
-    const exitCode = hasFail ? 1 : 0;
-    return { checks, exitCode, pass: exitCode === 0 };
+    void projectRoot;
+    const checks = [{
+            name: 'Relocate: deprecated no-op',
+            status: 'PASS',
+            message: 'No files moved. Current scaffold layout keeps generated files at their installed paths and tracks ownership via .mc/manifest.json.',
+        }];
+    return { checks, exitCode: 0, pass: true };
 }

package/dist/commands/explain.js

@@ -31,24 +31,24 @@ const RULE_EXPLANATIONS = {
     'no-raw-http-server': {
         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.',
+        description: '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.',
+        description: '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',
@@ -75,24 +75,24 @@ const RULE_EXPLANATIONS = {
     'apis-have-versions': {
         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.',
+        description: '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).',
+        description: '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/dist/commands/generate-openapi.d.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>
  */
@@ -11,6 +16,10 @@ export interface GenerateOpenapiOptions {
     /** Output path. Defaults to domains/<domain>/api/openapi.generated.json */
     output?: string;
 }
+/**
+ * Run the generate-openapi command: read the domain's registry and emit
+ * an OpenAPI 3.1 spec covering every API-exposed action.
+ */
 export declare function runGenerateOpenapi(options: GenerateOpenapiOptions): Promise<string>;
 /**
  * CLI entry point.