@mettlecast/domain-cli 0.2.22 → 0.2.24

package/dist/commands/doctor.js

@@ -2,6 +2,13 @@ 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';
 /**
  * Recursively find all files matching a pattern.
  * @param dir - Directory to search
@@ -30,6 +37,117 @@ function findFiles(dir, pattern) {
     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) {
+    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 = [];
+        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));
+                }
+            }
+        }
+        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' };
+    }
+}
+/**
+ * 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) {
+    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 = [];
+        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' };
+    }
+}
 /**
  * Run all structural checks for the current TIB project.
  * Each check runs independently; failure of one does not abort the rest.
@@ -39,11 +157,21 @@ function findFiles(dir, pattern) {
  */
 export async function runDoctor(opts = {}) {
     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 = [];
+    // --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 = [];
+    if (opts.fix) {
+        const relocationReport = await runRelocate(projectRoot);
+        preflightChecks = relocationReport.checks;
+    }
+    const checks = [...preflightChecks];
     // Check 1: Domain configs valid
     checks.push(await checkDomainConfigsValid(projectRoot));
     // Check 2: No raw AWS SDK in domains
@@ -61,13 +189,21 @@ export async function runDoctor(opts = {}) {
     // Check 8: No root-level flows (deprecated)
     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));
     checks.push(await checkDomainBrainReachable(projectRoot));
     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));
@@ -529,6 +665,204 @@ async function checkApiFixtures(projectRoot) {
             kNodeRef: 'K:exit-gate:domain-complete' };
     }
 }
+// ---- 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) {
+    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) {
+    try {
+        const scanDirs = [
+            { dir: join(projectRoot, 'domains'), label: 'domains' },
+            { dir: join(projectRoot, 'packages', 'domain-cli', 'src', 'commands'), label: 'CLI commands' },
+        ];
+        const violations = [];
+        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) {
+    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 = [];
+        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) {
+    try {
+        const domainsDir = join(projectRoot, 'domains');
+        let entries = [];
+        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 = [];
+        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 = [];
+        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) {
+    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;
+        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.
  */
@@ -739,9 +1073,10 @@ async function checkDomainBrainReachable(projectRoot) {
         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);
             if (response.ok) {

package/dist/commands/generate-openapi.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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>
+ */
+export interface GenerateOpenapiOptions {
+    domain: string;
+    projectRoot?: string;
+    /** Output path. Defaults to domains/<domain>/api/openapi.generated.json */
+    output?: string;
+}
+export declare function runGenerateOpenapi(options: GenerateOpenapiOptions): Promise<string>;
+/**
+ * CLI entry point.
+ */
+export declare function runGenerateOpenapiCli(domain: string, opts?: {
+    projectRoot?: string;
+    output?: string;
+}): Promise<void>;

package/dist/commands/generate-openapi.js

@@ -0,0 +1,117 @@
+/**
+ * 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';
+/**
+ * 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, field) {
+    // 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;
+        return { type: def.type ?? 'object', properties: def.properties, required: def.required };
+    }
+    return { type: 'object' };
+}
+export async function runGenerateOpenapi(options) {
+    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);
+    const paths = {};
+    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][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, opts = {}) {
+    const outputPath = await runGenerateOpenapi({ domain, ...opts });
+    // eslint-disable-next-line no-console
+    console.log(`OpenAPI spec written to: ${outputPath}`);
+}

package/dist/commands/generate-sdk.d.ts

@@ -0,0 +1,25 @@
+/**
+ * generate-sdk — read a domain's OpenAPI 3.1 spec and produce a typed
+ * TypeScript client that returns `Result<T, AppError>` from every API
+ * call. Uses the domain-runtime's Result types for compile-time safe
+ * error handling.
+ *
+ * Usage: npx mc-domain-module generate-sdk <domain>
+ */
+export interface GenerateSdkOptions {
+    domain: string;
+    projectRoot?: string;
+    /** Path to the OpenAPI spec. Defaults to domains/<domain>/api/openapi.generated.json */
+    input?: string;
+    /** Output directory. Defaults to frontend/src/sdk/generated/<domain>/ */
+    output?: string;
+}
+export declare function runGenerateSdk(options: GenerateSdkOptions): Promise<string>;
+/**
+ * CLI entry point.
+ */
+export declare function runGenerateSdkCli(domain: string, opts?: {
+    projectRoot?: string;
+    input?: string;
+    output?: string;
+}): Promise<void>;

package/dist/commands/generate-sdk.js

@@ -0,0 +1,98 @@
+/**
+ * generate-sdk — read a domain's OpenAPI 3.1 spec and produce a typed
+ * TypeScript client that returns `Result<T, AppError>` from every API
+ * call. Uses the domain-runtime's Result types for compile-time safe
+ * error handling.
+ *
+ * Usage: npx mc-domain-module generate-sdk <domain>
+ */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { cliLogger } from '../utils/logger.js';
+export async function runGenerateSdk(options) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const domain = options.domain;
+    const inputPath = options.input ?? join(projectRoot, 'domains', domain, 'api', 'openapi.generated.json');
+    const outputDir = options.output ?? join(projectRoot, 'frontend', 'src', 'sdk', 'generated', domain);
+    const specJson = await readFile(inputPath, 'utf8');
+    const spec = JSON.parse(specJson);
+    const functions = [];
+    let functionCount = 0;
+    if (spec.paths) {
+        for (const [path, methods] of Object.entries(spec.paths)) {
+            for (const [method, op] of Object.entries(methods)) {
+                const operationId = op?.operationId ?? `${method}_${path.replace(/[^a-zA-Z0-9]/g, '_')}`;
+                const fnName = camelCase(operationId.replace(/\./g, '_'));
+                functions.push(generateApiFunction(fnName, path, method, operationId));
+                functionCount++;
+            }
+        }
+    }
+    const output = generateSdkFile(domain, functions);
+    await mkdir(outputDir, { recursive: true });
+    const indexFile = join(outputDir, 'index.ts');
+    await writeFile(indexFile, output, 'utf8');
+    // Write a .genhash file so the doctor check can verify freshness
+    const registryPath = join(projectRoot, '.mc', `${domain}-registry.json`);
+    const registryJson = await readFile(registryPath, 'utf8');
+    const hash = createHash('sha256').update(registryJson).digest('hex');
+    const genhashFile = join(outputDir, '.genhash');
+    await writeFile(genhashFile, `${domain} ${hash}`, 'utf8');
+    cliLogger.info({ outputDir, functionCount }, 'generate-sdk: client written');
+    return outputDir;
+}
+/**
+ * Generate a single API function body.
+ */
+function generateApiFunction(name, path, method, _operationId) {
+    const payloadParam = method === 'get' ? '' : ', body: unknown';
+    return `
+/**
+ * ${_operationId}
+ * @returns Result containing the typed response or an AppError.
+ */
+export async function ${name}(
+  ${method === 'get' ? '' : 'body: unknown'}
+): Promise<Result<unknown, AppError>> {
+  const res = await fetch('${path}', {
+    method: '${method.toUpperCase()}',
+    headers: { 'Content-Type': 'application/json' },
+    ${method !== 'get' ? 'body: JSON.stringify(body),' : ''}
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ kind: 'internal', traceId: '', message: res.statusText }));
+    return err as unknown as Result<never, AppError>;
+  }
+  const value = await res.json();
+  return ok(value as unknown);
+}`;
+}
+/**
+ * Generate the full SDK file.
+ */
+function generateSdkFile(domain, functions) {
+    return `// Generated from domains/${domain}/api/openapi.generated.json — do not edit
+// Re-run npx mc-domain-module generate-sdk ${domain} after schema changes.
+import type { Result, AppError } from '@mettlecast/domain-runtime';
+import { ok } from '@mettlecast/domain-runtime';
+
+${functions.join('\n')}
+`;
+}
+/**
+ * Convert kebab-case or dot-separated to camelCase.
+ */
+function camelCase(s) {
+    return s
+        .replace(/[-._]([a-z])/g, (_, c) => c.toUpperCase())
+        .replace(/^./, (c) => c.toLowerCase());
+}
+/**
+ * CLI entry point.
+ */
+export async function runGenerateSdkCli(domain, opts = {}) {
+    const outputDir = await runGenerateSdk({ domain, ...opts });
+    // eslint-disable-next-line no-console
+    console.log(`SDK client written to: ${outputDir}`);
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,14 @@
+/**
+ * init — bootstrap a freshly scaffolded project so it is ready for
+ * local development and CI.  Runs npm install, builds the CLI, and
+ * runs a baseline doctor check.
+ *
+ * Usage: npx mc-domain-module init
+ */
+export interface InitOptions {
+    projectRoot?: string;
+    /** Skip npm install if node_modules already exists. Default: true */
+    skipInstallIfExists?: boolean;
+}
+export declare function runInit(options?: InitOptions): Promise<void>;
+export declare function runInitCli(opts?: InitOptions): Promise<void>;