@mettlecast/domain-cli 0.2.21 → 0.2.23

package/src/commands/doctor.ts

@@ -2,6 +2,14 @@ import { readdir, readFile, access, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { relative } from 'node:path';
 import { readdirSync, existsSync } from 'node:fs';
+import ky from 'ky';
+
+/**
+ * Canonical option-string constant for the --fix flag on the doctor command.
+ * Exported so the cli-integration task (packages/domain-cli/src/index.ts) can
+ * register the same flag string in commander without string drift.
+ */
+export const DOCTOR_FIX_FLAG = '--fix';
 
 /**
  * Options for the doctor command.
@@ -12,6 +20,22 @@ export interface DoctorOptions {
   projectRoot?: string;
   /** Flag to run relocation of old-layout scaffold files to new layout. */
   relocate?: boolean;
+  /**
+   * Auto-remediate before reporting. --fix is a superset of --relocate: it
+   * first runs the relocation routine (auto-moves owned scaffold files outside
+   * .mc/ into .mc/ and updates .mc/manifest.json), then continues with the
+   * full doctor report. On a project that is already clean, --fix is a no-op
+   * (0 files moved, exit 0). Does NOT auto-generate missing fixtures
+   * (deferred).
+   */
+  fix?: boolean;
+  /**
+   * Explicit strict mode. Doctor is ALWAYS strict — any FAIL causes exit 1.
+   * This flag exists so CI can pass `--strict` as a self-documenting,
+   * fail-closed gate. Currently informational only; behaviour is identical
+   * with or without the flag.
+   */
+  strict?: boolean;
 }
 
 /**
@@ -62,17 +86,132 @@ function findFiles(dir: string, pattern: RegExp): string[] {
         const fullPath = join(currentPath, entry.name);
         if (entry.isDirectory()) {
           walk(fullPath);
-        } else if (pattern.test(entry.name)) {
-          result.push(fullPath);
+         } else if (pattern.test(entry.name)) {
+           result.push(fullPath);
+         }
+       }
+     } catch {
+       // Silently skip inaccessible directories
+     }
+   }
+
+   walk(dir);
+   return result;
+ }
+
+ /**
+ * Check W6-1: All domain handler return types reference `Result`.
+ * Scans `domains/*\/api/*.ts` for handler function signatures that
+ * lack `Result` in their return type annotation.
+ */
+async function checkHandlersUseResult(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const domainsDir = join(projectRoot, 'domains');
+    if (!existsSync(domainsDir)) {
+      return { name: 'Handlers use Result<T>', status: 'PASS',
+        message: 'No domains/ — check skipped (optional)',
+        kNodeRef: 'K:convention:typed-errors' };
+    }
+
+    const apiFiles = findFiles(domainsDir, /\/api\/[^/]+\.ts$/);
+    if (apiFiles.length === 0) {
+      return { name: 'Handlers use Result<T>', status: 'PASS',
+        message: 'No handler files — check skipped (optional)',
+        kNodeRef: 'K:convention:typed-errors' };
+    }
+
+    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)) {
+        // Look for Result<T> in the handler's return type annotation
+        if (!/: .*Result</.test(content)) {
+          missing.push(relative(projectRoot, file));
         }
       }
-    } catch {
-      // Silently skip inaccessible directories
     }
+
+    if (missing.length === 0) {
+      return { name: 'Handlers use Result<T>', status: 'PASS',
+        message: `All ${apiFiles.length} handler(s) reference Result<T> in their return type`,
+        kNodeRef: 'K:convention:typed-errors' };
+    } else {
+      return { name: 'Handlers use Result<T>', status: 'FAIL',
+        message: `${missing.length}/${apiFiles.length} handler(s) missing Result<T> return type:\n  ${missing.join('\n  ')}\nEach handler's return type must reference \`Result<T, AppError>\`. Replace bare \`return\` values with \`return ok(value)\` and errors with \`return err({...})\`.`,
+        fixHint: 'Add `: Promise<Result<T, AppError>>` to the handler\'s return type and import `{ Result, ok, err }` from `@mettlecast/domain-runtime`',
+        kNodeRef: 'K:convention:typed-errors' };
+    }
+  } catch (err) {
+    return { name: 'Handlers use Result<T>', status: 'WARN',
+      message: `Could not check handler return types: ${String(err)}`,
+      kNodeRef: 'K:convention:typed-errors' };
   }
+}
 
-  walk(dir);
-  return result;
+/**
+ * Check W6-2: Generated API clients are fresh.
+ * Compares .genhash files against the registry hash to ensure the
+ * generated client has not drifted from the source schemas.
+ */
+async function checkGeneratedClientsFresh(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const genDir = join(projectRoot, 'frontend', 'src', 'sdk', 'generated');
+    if (!existsSync(genDir)) {
+      return { name: 'Generated clients fresh', status: 'PASS',
+        message: 'No generated clients — check skipped (optional)',
+        kNodeRef: 'K:runbook:generated-clients' };
+    }
+
+    const hashFiles = findFiles(genDir, /\.genhash$/);
+    if (hashFiles.length === 0) {
+      return { name: 'Generated clients fresh', status: 'WARN',
+        message: 'Generated client directory exists but no .genhash files — cannot verify freshness',
+        kNodeRef: 'K:runbook:generated-clients' };
+    }
+
+    const stale: string[] = [];
+    for (const hashFile of hashFiles) {
+      const content = await readFile(hashFile, 'utf8').catch(() => null);
+      if (!content) {
+        stale.push(`${relative(projectRoot, hashFile)} (unreadable)`);
+        continue;
+      }
+      // A .genhash file contains: "<domain> <sha256-of-registry>"
+      const parts = content.trim().split(/\s+/);
+      if (parts.length !== 2) {
+        stale.push(`${relative(projectRoot, hashFile)} (invalid format)`);
+        continue;
+      }
+      const [domain, expectedHash] = parts;
+      const registryPath = join(projectRoot, '.mc', `${domain}-registry.json`);
+      const registryJson = await readFile(registryPath, 'utf8').catch(() => null);
+      if (!registryJson) {
+        stale.push(`${relative(projectRoot, hashFile)} (registry ${domain}-registry.json not found)`);
+        continue;
+      }
+      const { createHash } = await import('node:crypto');
+      const actualHash = createHash('sha256').update(registryJson).digest('hex');
+      if (actualHash !== expectedHash) {
+        stale.push(`${relative(projectRoot, hashFile)} (stale — run \`npx mc-domain-module generate-sdk ${domain}\`)`);
+      }
+    }
+
+    if (stale.length === 0) {
+      return { name: 'Generated clients fresh', status: 'PASS',
+        message: `All ${hashFiles.length} generated client(s) are up to date`,
+        kNodeRef: 'K:runbook:generated-clients' };
+    } else {
+      return { name: 'Generated clients fresh', status: 'FAIL',
+        message: `${stale.length}/${hashFiles.length} generated client(s) are stale:\n  ${stale.join('\n  ')}`,
+        fixHint: 'Run `npx mc-domain-module generate-sdk <domain>` for each stale domain',
+        kNodeRef: 'K:runbook:generated-clients' };
+    }
+  } catch (err) {
+    return { name: 'Generated clients fresh', status: 'WARN',
+      message: `Could not check generated client freshness: ${String(err)}`,
+      kNodeRef: 'K:runbook:generated-clients' };
+  }
 }
 
 /**
@@ -85,12 +224,23 @@ function findFiles(dir: string, pattern: RegExp): string[] {
 export async function runDoctor(opts: DoctorOptions = {}): Promise<DoctorReport> {
   const projectRoot = opts.projectRoot ?? process.cwd();
 
-  // Handle --relocate flag early
-  if (opts.relocate) {
+  // --relocate runs ONLY the relocation routine (existing behaviour).
+  // --fix is a superset: it runs relocation 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);
   }
 
-  const checks: DoctorCheck[] = [];
+  // --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).
+  let preflightChecks: DoctorCheck[] = [];
+  if (opts.fix) {
+    const relocationReport = await runRelocate(projectRoot);
+    preflightChecks = relocationReport.checks;
+  }
+
+  const checks: DoctorCheck[] = [...preflightChecks];
 
   // Check 1: Domain configs valid
   checks.push(await checkDomainConfigsValid(projectRoot));
@@ -117,7 +267,7 @@ export async function runDoctor(opts: DoctorOptions = {}): Promise<DoctorReport>
   checks.push(await checkRootLevelFlows(projectRoot));
 
   // W2 new assertions
-  checks.push(await checkApiFixtures(projectRoot));
+  checks.push(await checkEveryApiHasFixture(projectRoot));
   checks.push(await checkEventConsumers(projectRoot));
   checks.push(await checkMigrationTenancyTrio(projectRoot));
   checks.push(await checkDomainRlsTest(projectRoot));
@@ -125,6 +275,16 @@ export async function runDoctor(opts: DoctorOptions = {}): Promise<DoctorReport>
   checks.push(await checkActionsHaveTypes(projectRoot));
   checks.push(await checkConventionEvidence(projectRoot));
 
+  // W5 new checks (scaffolder modernize — 4 new + 1 reuse of checkApiFixtures)
+  checks.push(await checkAllHttpClientsUseKy(projectRoot));
+  checks.push(await checkAllRoutesUseTanStackRouter(projectRoot));
+  checks.push(await checkOtelInitInLambdas(projectRoot));
+  checks.push(await checkFrontendUsesStrictTypescript(projectRoot));
+
+  // W6 (post-review) new checks
+  checks.push(await checkHandlersUseResult(projectRoot));
+  checks.push(await checkGeneratedClientsFresh(projectRoot));
+
   // W1 tracked-files boundary checks
   checks.push(...await checkScaffoldTrackedFilesHaveHeaders(projectRoot));
   checks.push(...await checkSeedPagesHaveNoHeaders(projectRoot));
@@ -597,6 +757,212 @@ async function checkApiFixtures(projectRoot: string): Promise<DoctorCheck> {
   }
 }
 
+// ---- W5 new checks (scaffolder modernize) ----
+
+/**
+ * Check W5-1: All HTTP clients in domains/ use ky or ctx.fetch (no raw fetch()).
+ * Reuses the W2 fixture check. Per plan-reviewer WARN #6, this is the
+ * "5th new check" counted as a reuse of checkApiFixtures — the
+ * `checkEveryApiHasFixture` wrapper below invokes the same logic.
+ */
+async function checkEveryApiHasFixture(projectRoot: string): Promise<DoctorCheck> {
+  return checkApiFixtures(projectRoot);
+}
+
+/**
+ * Check W5-2: All HTTP clients in domains/ use ky or ctx.fetch.
+ * Detects raw `fetch(` calls (the global browser/node fetch) and FAILs.
+ * Allows `ctx.fetch(` (domain-runtime helper) and `ky.fetch(` (ky API).
+ */
+/**
+ * Check W5-1: All domain + CLI HTTP clients use ky (no raw fetch).
+ * Scans domains/ AND packages/domain-cli/src/commands/ for raw
+ * `fetch(` calls.  Excludes `ctx.fetch`, `globalThis.fetch`, and
+ * comments.
+ */
+
+async function checkAllHttpClientsUseKy(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const scanDirs = [
+      { dir: join(projectRoot, 'domains'), label: 'domains' },
+      { dir: join(projectRoot, 'packages', 'domain-cli', 'src', 'commands'), label: 'CLI commands' },
+    ];
+
+    const violations: string[] = [];
+    let totalFiles = 0;
+
+    for (const { dir, label } of scanDirs) {
+      if (!existsSync(dir)) continue;
+      const files = findFiles(dir, /\.ts$/);
+      totalFiles += files.length;
+
+      for (const file of files) {
+        const content = await readFile(file, 'utf8');
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+          const line = lines[i];
+          const code = line.replace(/\/\/.*$/, '');
+          if (/(?<![\w$.])fetch\s*\(/.test(code)) {
+            violations.push(`${relative(projectRoot, file)}:${i + 1} (${label})`);
+          }
+        }
+      }
+    }
+
+    if (violations.length === 0) {
+      return { name: 'All HTTP clients use ky', status: 'PASS',
+        message: `No raw fetch() calls across ${totalFiles} file(s) in domains/ and CLI — all HTTP clients use ky or ctx.fetch`,
+        kNodeRef: 'K:convention:http-client-ky' };
+    } else {
+      return { name: 'All HTTP clients use ky', status: 'FAIL',
+        message: `Found ${violations.length} raw fetch() call(s):\n  ${violations.join('\n  ')}`,
+        fixHint: 'Use ky or ctx.fetch from @mettlecast/domain-runtime instead of raw fetch()',
+        kNodeRef: 'K:convention:http-client-ky' };
+    }
+  } catch (err) {
+    return { name: 'All HTTP clients use ky', status: 'WARN',
+      message: `Could not check HTTP clients: ${String(err)}`,
+      kNodeRef: 'K:convention:http-client-ky' };
+  }
+}
+
+/**
+ * Check W5-3: All frontend routes use TanStack Router (no react-router-dom imports).
+ * Scans frontend/ for `from 'react-router-dom'` (or double-quoted) imports.
+ */
+async function checkAllRoutesUseTanStackRouter(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const frontendDir = join(projectRoot, 'frontend');
+    if (!existsSync(frontendDir)) {
+      return { name: 'Routes use TanStack Router', status: 'PASS',
+        message: 'No frontend/ directory — check skipped (optional)',
+        kNodeRef: 'K:convention:tanstack-router' };
+    }
+
+    const files = findFiles(frontendDir, /\.(ts|tsx|js|jsx)$/);
+    const violations: string[] = [];
+
+    for (const file of files) {
+      const content = await readFile(file, 'utf8');
+      if (/from\s+['"]react-router-dom['"]/.test(content)) {
+        violations.push(relative(projectRoot, file));
+      }
+    }
+
+    if (violations.length === 0) {
+      return { name: 'Routes use TanStack Router', status: 'PASS',
+        message: 'No react-router-dom imports in frontend/',
+        kNodeRef: 'K:convention:tanstack-router' };
+    } else {
+      return { name: 'Routes use TanStack Router', status: 'FAIL',
+        message: `Found ${violations.length} react-router-dom import(s) in frontend/:\n  ${violations.join('\n  ')}`,
+        fixHint: 'Migrate from react-router-dom to @tanstack/react-router',
+        kNodeRef: 'K:convention:tanstack-router' };
+    }
+  } catch (err) {
+    return { name: 'Routes use TanStack Router', status: 'WARN',
+      message: `Could not check frontend router: ${String(err)}`,
+      kNodeRef: 'K:convention:tanstack-router' };
+  }
+}
+
+/**
+ * Check W5-4: Lambda handler files contain initOtel() call.
+ * Scans `domains/*\/api/*.ts` and FAILs if any handler is missing initOtel().
+ */
+async function checkOtelInitInLambdas(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const domainsDir = join(projectRoot, 'domains');
+    let entries: { name: string; isDirectory: () => boolean }[] = [];
+    try {
+      entries = await readdir(domainsDir, { withFileTypes: true });
+    } catch {
+      return { name: 'OTel init in Lambdas', status: 'PASS',
+        message: 'No domains/ — check skipped (optional)',
+        kNodeRef: 'K:convention:otel-init' };
+    }
+
+    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);
+    }
+
+    if (handlerFiles.length === 0) {
+      return { name: 'OTel init in Lambdas', status: 'PASS',
+        message: 'No Lambda handler files in domains/ (optional)',
+        kNodeRef: 'K:convention:otel-init' };
+    }
+
+    const missing: string[] = [];
+    for (const file of handlerFiles) {
+      const content = await readFile(file, 'utf8');
+      if (!/initOtel\s*\(/.test(content)) {
+        missing.push(relative(projectRoot, file));
+      }
+    }
+
+    if (missing.length === 0) {
+      return { name: 'OTel init in Lambdas', status: 'PASS',
+        message: `All ${handlerFiles.length} Lambda handler(s) call initOtel()`,
+        kNodeRef: 'K:convention:otel-init' };
+    } else {
+      return { name: 'OTel init in Lambdas', status: 'FAIL',
+        message: `${missing.length}/${handlerFiles.length} Lambda handler(s) missing initOtel():\n  ${missing.join('\n  ')}`,
+        fixHint: 'Add initOtel() (from @mettlecast/domain-runtime) to each Lambda handler file',
+        kNodeRef: 'K:convention:otel-init' };
+    }
+  } catch (err) {
+    return { name: 'OTel init in Lambdas', status: 'WARN',
+      message: `Could not check OTel init: ${String(err)}`,
+      kNodeRef: 'K:convention:otel-init' };
+  }
+}
+
+/**
+ * Check W5-5: Frontend tsconfig.json has `strict: true`.
+ * Reads frontend/tsconfig.json and verifies compilerOptions.strict === true.
+ */
+async function checkFrontendUsesStrictTypescript(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const tsconfigPath = join(projectRoot, 'frontend', 'tsconfig.json');
+    if (!existsSync(tsconfigPath)) {
+      return { name: 'Frontend uses strict TypeScript', status: 'PASS',
+        message: 'No frontend/tsconfig.json — check skipped (optional)',
+        kNodeRef: 'K:convention:typescript-strict' };
+    }
+
+    const content = await readFile(tsconfigPath, 'utf8');
+    let config: { compilerOptions?: { strict?: unknown } };
+    try {
+      config = JSON.parse(content);
+    } catch (err) {
+      return { name: 'Frontend uses strict TypeScript', status: 'FAIL',
+        message: `frontend/tsconfig.json is not valid JSON: ${String(err)}`,
+        fixHint: 'Fix tsconfig.json JSON syntax',
+        kNodeRef: 'K:convention:typescript-strict' };
+    }
+
+    const strict = config.compilerOptions?.strict === true;
+    if (strict) {
+      return { name: 'Frontend uses strict TypeScript', status: 'PASS',
+        message: 'frontend/tsconfig.json has strict: true',
+        kNodeRef: 'K:convention:typescript-strict' };
+    } else {
+      return { name: 'Frontend uses strict TypeScript', status: 'FAIL',
+        message: 'frontend/tsconfig.json does not have strict: true',
+        fixHint: "Add \"strict\": true to compilerOptions in frontend/tsconfig.json",
+        kNodeRef: 'K:convention:typescript-strict' };
+    }
+  } catch (err) {
+    return { name: 'Frontend uses strict TypeScript', status: 'WARN',
+      message: `Could not check tsconfig: ${String(err)}`,
+      kNodeRef: 'K:convention:typescript-strict' };
+  }
+}
+
 /**
  * Check 10: Every event has consumer or @no-consumers annotation.
  */
@@ -796,9 +1162,10 @@ async function checkDomainBrainReachable(projectRoot: string): Promise<DoctorChe
     try {
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), 3000);
-      const response = await fetch(`${brainEndpoint}/api/graph/nodes`, {
-        method: 'GET', signal: controller.signal,
+      const response = await ky.get(`${brainEndpoint}/api/graph/nodes`, {
+        signal: controller.signal,
         headers: { 'Content-Type': 'application/json' },
+        timeout: 3000,
       });
       clearTimeout(timeoutId);
 

package/src/commands/generate-openapi.ts

@@ -0,0 +1,154 @@
+/**
+ * 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.
+ *
+ * Usage: npx mc-domain-module generate-openapi <domain>
+ */
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { cliLogger } from '../utils/logger.js';
+
+export interface GenerateOpenapiOptions {
+  domain: string;
+  projectRoot?: string;
+  /** Output path. Defaults to domains/<domain>/api/openapi.generated.json */
+  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[];
+}
+
+/**
+ * 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.
+ */
+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;
+  const outputPath = options.output ?? join(projectRoot, 'domains', domain, 'api', 'openapi.generated.json');
+
+  // Read the domain registry
+  const registryPath = join(projectRoot, '.mc', `${domain}-registry.json`);
+  const registryJson = await readFile(registryPath, 'utf8');
+  const registry = JSON.parse(registryJson) as DomainRegistry;
+
+  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;
+
+    if (!paths[fullPath]) paths[fullPath] = {};
+
+    (paths[fullPath] as Record<string, unknown>)[method] = {
+      operationId: `${domain}.${api.id}`,
+      summary: `${domain}.${api.id}`,
+      description: `Version: ${v1.status}`,
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: extractSchema(v1, 'input'),
+          },
+        },
+      },
+      responses: {
+        '200': {
+          description: 'OK',
+          content: {
+            'application/json': {
+              schema: extractSchema(v1, 'output'),
+            },
+          },
+        },
+        '400': {
+          description: 'Validation error',
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                properties: {
+                  error: {
+                    type: 'object',
+                    properties: {
+                      kind: { type: 'string', enum: ['validation'] },
+                      message: { type: 'string' },
+                      fieldErrors: { type: 'object' },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+  }
+
+  const openapi = {
+    openapi: '3.1.0',
+    info: {
+      title: `${domain} API`,
+      version: '1.0.0',
+      description: `Generated from ${domain}-registry.json at build time. Do not edit manually.`,
+    },
+    paths,
+  };
+
+  const dir = join(outputPath, '..');
+  await mkdir(dir, { recursive: true });
+  await writeFile(outputPath, JSON.stringify(openapi, null, 2), 'utf8');
+
+  cliLogger.info({ outputPath }, 'generate-openapi: spec written');
+  return outputPath;
+}
+
+/**
+ * CLI entry point.
+ */
+export async function runGenerateOpenapiCli(domain: string, opts: { projectRoot?: string; output?: string } = {}): Promise<void> {
+  const outputPath = await runGenerateOpenapi({ domain, ...opts });
+  // eslint-disable-next-line no-console
+  console.log(`OpenAPI spec written to: ${outputPath}`);
+}