@mettlecast/domain-cli 0.2.22 → 0.2.24

package/dist/cli.js

@@ -31,6 +31,11 @@ import { runReseedPage } from './commands/reseed-page.js';
 import { runAddSeedPage } from './commands/add-seed-page.js';
 import { runShowDns } from './commands/show-dns.js';
 import { runBuildUi } from './commands/build-ui.js';
+import { runWhyCli } from './commands/why.js';
+import { runGenerateOpenapiCli } from './commands/generate-openapi.js';
+import { runGenerateSdkCli } from './commands/generate-sdk.js';
+import { runAddFixtureFactoryCli } from './commands/add-fixture-factory.js';
+import { runInitCli } from './commands/init.js';
 /**
  * Root CLI program for the TIB Domain Module local developer toolchain.
  * Provides build, validate, test, dev, add-domain, add-api, and add-subscriber subcommands.
@@ -130,12 +135,19 @@ program
     .description('Run all structural checks for the current TIB project (strict by default — any FAIL causes exit code 1)')
     .option('--strict', 'DEPRECATED: Doctor is always strict now. This flag is a no-op.', false)
     .option('--json', 'Output JSON instead of pretty table', false)
+    .option('--fix', 'Attempt to automatically fix issues that have a safe automatic fix', false)
     .action(async (opts) => {
     if (opts.strict) {
         // eslint-disable-next-line no-console
         console.warn('⚠  --strict is deprecated: doctor is always strict now. This flag is a no-op.');
     }
-    const report = await runDoctor({ projectRoot: process.cwd() });
+    // `fix` is part of DoctorOptions in Wave 1 (Task doctor-fix). Cast through
+    // `unknown` so this file type-checks today and after the doctor-fix worker
+    // adds the `fix?: boolean` field to DoctorOptions.
+    const report = await runDoctor({
+        projectRoot: process.cwd(),
+        fix: opts.fix,
+    });
     if (opts.json) {
         // eslint-disable-next-line no-console
         console.log(JSON.stringify(report, null, 2));
@@ -247,13 +259,14 @@ program
 });
 program
     .command('upgrade [version]')
-    .description('Upgrade scaffold to a new version — diffs S3 tarballs, raises a GitHub PR with exact file changes')
+    .description('Upgrade, check for drift, or dry-run scaffold to a new version — diffs S3 tarballs and (when not --check or --dry-run) raises a GitHub PR with exact file changes')
     .option('--dry-run', 'Preview changes without writing files or creating PR', false)
+    .option('--check', 'Read-only CI gate: compute upgrade diff, exit 0 for no drift or 1 if drift detected. Writes nothing.', false)
     .option('--project-dir <path>', 'Path to the project to upgrade')
     .option('--github-token <token>', 'GitHub token for PR creation (overrides GITHUB_TOKEN env var)')
     .option('--frontend-components', 'Scope upgrade to scaffold-tracked frontend files only (opens a PR with Chromatic visual diff)', false)
     .action(async (version, opts) => {
-    await runUpgrade(version, { dryRun: opts.dryRun, projectDir: opts.projectDir ?? process.cwd(), githubToken: opts.githubToken, frontendComponents: opts.frontendComponents });
+    await runUpgrade(version, { dryRun: opts.dryRun, check: opts.check, projectDir: opts.projectDir ?? process.cwd(), githubToken: opts.githubToken, frontendComponents: opts.frontendComponents });
 });
 // ── New W4 commands ───────────────────────────────────────────────
 program
@@ -339,6 +352,50 @@ program
     .action(async (opts) => {
     await runBuildUi({ projectRoot: opts.projectRoot });
 });
+program
+    .command('why')
+    .description('Print current scaffold version, enabled modules, and pending upgrade diff to stdout')
+    .option('--project-root <path>', 'Path to the project root (defaults to cwd)')
+    .option('--scaffold-bucket <name>', 'S3 bucket to fetch versions.json from (defaults to mc-scaffold)')
+    .option('--json', 'Output JSON instead of a human-readable report', false)
+    .action(async (opts) => {
+    await runWhyCli({
+        projectRoot: opts.projectRoot,
+        scaffoldBucket: opts.scaffoldBucket,
+        json: opts.json,
+    });
+});
+program
+    .command('generate-openapi <domain>')
+    .description('Generate an OpenAPI 3.1 spec from a domain registry (.mc/<domain>-registry.json)')
+    .option('--project-root <path>', 'Path to the project root (defaults to cwd)')
+    .option('--output <path>', 'Override the output file path')
+    .action(async (domain, opts) => {
+    await runGenerateOpenapiCli(domain, { projectRoot: opts.projectRoot, output: opts.output });
+});
+program
+    .command('generate-sdk <domain>')
+    .description('Generate a typed TypeScript API client from a domain\'s OpenAPI spec, returning Result<T, AppError> from every call')
+    .option('--project-root <path>', 'Path to the project root (defaults to cwd)')
+    .option('--input <path>', 'Path to the OpenAPI spec (defaults to domains/<domain>/api/openapi.generated.json)')
+    .option('--output <path>', 'Override the output directory')
+    .action(async (domain, opts) => {
+    await runGenerateSdkCli(domain, { projectRoot: opts.projectRoot, input: opts.input, output: opts.output });
+});
+program
+    .command('add-fixture-factory <domain> <api-id>')
+    .description('Generate a test data factory with @faker-js/faker for an existing API handler')
+    .option('--project-root <path>', 'Path to the project root (defaults to cwd)')
+    .action(async (domain, apiId, opts) => {
+    await runAddFixtureFactoryCli(domain, apiId, { projectRoot: opts.projectRoot });
+});
+program
+    .command('init')
+    .description('Bootstrap a freshly scaffolded project: npm install, build CLI, run doctor baseline')
+    .option('--project-root <path>', 'Path to the project root (defaults to cwd)')
+    .action(async (opts) => {
+    await runInitCli({ projectRoot: opts.projectRoot });
+});
 program.parseAsync(process.argv).catch((err) => {
     // eslint-disable-next-line no-console
     console.error(err);

package/dist/commands/add-api.d.ts

@@ -5,7 +5,7 @@
 /**
  * Valid API pattern IDs.
  */
-export declare const API_PATTERNS: readonly ["simple-crud", "paginated-list", "create-with-event", "idempotent-mutation", "webhook-receiver-style", "system-admin"];
+export declare const API_PATTERNS: readonly ["simple-crud", "paginated-list", "create-with-event", "idempotent-mutation", "webhook-receiver-style", "system-admin", "streaming-list"];
 export type ApiPattern = (typeof API_PATTERNS)[number];
 /**
  * Options for the add-api command.

package/dist/commands/add-api.js

@@ -5,12 +5,13 @@
 import { writeFile, access, mkdir } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { apiSkeletonTemplate, apiFixtureSkeleton } from '../templates/api-skeleton.js';
-import { simpleCrudTemplate, simpleCrudListTemplate } from '../templates/patterns/api/simple-crud.js';
-import { paginatedListTemplate } from '../templates/patterns/api/paginated-list.js';
-import { createWithEventTemplate } from '../templates/patterns/api/create-with-event.js';
-import { idempotentMutationTemplate } from '../templates/patterns/api/idempotent-mutation.js';
-import { webhookReceiverStyleTemplate } from '../templates/patterns/api/webhook-receiver-style.js';
-import { systemAdminTemplate } from '../templates/patterns/api/system-admin.js';
+import { simpleCrudTemplate, simpleCrudListTemplate, simpleCrudExampleBody, } from '../templates/patterns/api/simple-crud.js';
+import { paginatedListTemplate, paginatedListExampleBody, } from '../templates/patterns/api/paginated-list.js';
+import { createWithEventTemplate, createWithEventExampleBody, } from '../templates/patterns/api/create-with-event.js';
+import { idempotentMutationTemplate, idempotentMutationExampleBody, } from '../templates/patterns/api/idempotent-mutation.js';
+import { webhookReceiverStyleTemplate, webhookReceiverStyleExampleBody, } from '../templates/patterns/api/webhook-receiver-style.js';
+import { systemAdminTemplate, systemAdminExampleBody, } from '../templates/patterns/api/system-admin.js';
+import { streamingListPattern, } from '../templates/patterns/api/streaming-list.js';
 import { cliLogger } from '../utils/logger.js';
 /**
  * Valid API pattern IDs.
@@ -22,6 +23,7 @@ export const API_PATTERNS = [
     'idempotent-mutation',
     'webhook-receiver-style',
     'system-admin',
+    'streaming-list',
 ];
 const KEBAB_REGEX = /^[a-z][a-z0-9-]*$/;
 /**
@@ -59,8 +61,11 @@ export async function runAddApi(opts) {
     }
     // Resolve template content
     let apiContent;
+    let exampleBody = '{}';
     if (opts.pattern) {
-        apiContent = resolveApiPattern(opts.pattern, opts.domain, opts.id, opts.tenancy);
+        const resolved = resolveApiPattern(opts.pattern, opts.domain, opts.id, opts.tenancy);
+        apiContent = resolved.apiContent;
+        exampleBody = resolved.exampleBody;
         cliLogger.info({ pattern: opts.pattern }, 'Using pattern template');
     }
     else {
@@ -68,10 +73,10 @@ export async function runAddApi(opts) {
     }
     // Write API file
     await writeFile(apiFilePath, apiContent);
-    // Create fixture
+    // Create fixture with the input schema's default shape as the example payload
     const apiTestDir = join(domainDir, 'api', '__tests__');
     await mkdir(apiTestDir, { recursive: true });
-    await writeFile(join(apiTestDir, `${opts.id}.fixture.json`), apiFixtureSkeleton(opts.domain, opts.id));
+    await writeFile(join(apiTestDir, `${opts.id}.fixture.json`), apiFixtureSkeleton(opts.domain, opts.id, exampleBody));
     cliLogger.info({ domain: opts.domain, api: opts.id, method: opts.method ?? 'GET', pattern: opts.pattern ?? 'skeleton' }, 'API added');
     // eslint-disable-next-line no-console
     console.log(`\n✓ API "${opts.id}" added to domain "${opts.domain}" at ${apiFilePath}`);
@@ -87,19 +92,42 @@ export async function runAddApi(opts) {
 function resolveApiPattern(pattern, domain, id, tenancy) {
     switch (pattern) {
         case 'simple-crud':
-            return simpleCrudTemplate(domain, id, tenancy) +
-                '\n' +
-                simpleCrudListTemplate(domain, id, tenancy);
+            return {
+                apiContent: simpleCrudTemplate(domain, id, tenancy) +
+                    '\n' +
+                    simpleCrudListTemplate(domain, id, tenancy),
+                exampleBody: simpleCrudExampleBody,
+            };
         case 'paginated-list':
-            return paginatedListTemplate(domain, id, tenancy);
+            return {
+                apiContent: paginatedListTemplate(domain, id, tenancy),
+                exampleBody: paginatedListExampleBody,
+            };
         case 'create-with-event':
-            return createWithEventTemplate(domain, id, tenancy);
+            return {
+                apiContent: createWithEventTemplate(domain, id, tenancy),
+                exampleBody: createWithEventExampleBody,
+            };
         case 'idempotent-mutation':
-            return idempotentMutationTemplate(domain, id, tenancy);
+            return {
+                apiContent: idempotentMutationTemplate(domain, id, tenancy),
+                exampleBody: idempotentMutationExampleBody,
+            };
         case 'webhook-receiver-style':
-            return webhookReceiverStyleTemplate(domain, id, tenancy);
+            return {
+                apiContent: webhookReceiverStyleTemplate(domain, id, tenancy),
+                exampleBody: webhookReceiverStyleExampleBody,
+            };
         case 'system-admin':
-            return systemAdminTemplate(domain, id, tenancy);
+            return {
+                apiContent: systemAdminTemplate(domain, id, tenancy),
+                exampleBody: systemAdminExampleBody,
+            };
+        case 'streaming-list':
+            return {
+                apiContent: streamingListPattern(domain, id, 'item'),
+                exampleBody: '{}',
+            };
         default:
             throw new Error(`Unknown API pattern "${pattern}". Available: ${API_PATTERNS.join(', ')}`);
     }

package/dist/commands/add-fixture-factory.d.ts

@@ -0,0 +1,16 @@
+/**
+ * add-fixture-factory — generate a test data factory alongside an
+ * existing API handler. The factory provides `valid()` and `invalid()`
+ * functions with realistic test data powered by @faker-js/faker.
+ *
+ * Usage: npx mc-domain-module add-fixture-factory <domain> <api-id>
+ */
+export interface AddFixtureFactoryOptions {
+    domain: string;
+    apiId: string;
+    projectRoot?: string;
+}
+export declare function runAddFixtureFactory(options: AddFixtureFactoryOptions): Promise<string>;
+export declare function runAddFixtureFactoryCli(domain: string, apiId: string, opts?: {
+    projectRoot?: string;
+}): Promise<void>;

package/dist/commands/add-fixture-factory.js

@@ -0,0 +1,60 @@
+/**
+ * add-fixture-factory — generate a test data factory alongside an
+ * existing API handler. The factory provides `valid()` and `invalid()`
+ * functions with realistic test data powered by @faker-js/faker.
+ *
+ * Usage: npx mc-domain-module add-fixture-factory <domain> <api-id>
+ */
+import { readFile, writeFile, mkdir, access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { cliLogger } from '../utils/logger.js';
+const FACTORY_TEMPLATE = `// Generated fixture factory for {domain}.{apiId}
+// Uses @faker-js/faker for realistic test data. Override any field
+// by passing overrides to ` + '`valid()`' + `.
+import { faker } from '@faker-js/faker';
+
+/** The input shape for {domain}.{apiId} — derive from the Zod schema. */
+type Input = Record<string, unknown>;
+
+/** Full, valid input with sensible defaults. */
+export function valid(overrides: Partial<Input> = {}): Input {
+  return {
+    name: faker.company.name(),
+    email: faker.internet.email(),
+    ...overrides,
+  };
+}
+
+/** Intentionally invalid input — use to test validation failures. */
+export function invalid(): Partial<Input> {
+  return {
+    name: '',    // empty — should fail minLength if required
+    email: 'not-an-email',
+  };
+}
+`;
+export async function runAddFixtureFactory(options) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const domain = options.domain;
+    const apiId = options.apiId;
+    const apiFile = join(projectRoot, 'domains', domain, 'api', `${apiId}.ts`);
+    await access(apiFile).catch(() => {
+        throw new Error(`API file not found: ${apiFile}. Run add-api first.`);
+    });
+    // Read the API 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 factoryContent = FACTORY_TEMPLATE
+        .replace(/\{domain\}/g, domain)
+        .replace(/\{apiId\}/g, apiId);
+    await mkdir(join(projectRoot, 'domains', domain, 'api', '__tests__'), { recursive: true });
+    await writeFile(factoryFile, factoryContent, 'utf8');
+    cliLogger.info({ factoryFile }, 'add-fixture-factory: factory written');
+    return factoryFile;
+}
+export async function runAddFixtureFactoryCli(domain, apiId, opts = {}) {
+    const factoryFile = await runAddFixtureFactory({ domain, apiId, ...opts });
+    // eslint-disable-next-line no-console
+    console.log(`Fixture factory written to: ${factoryFile}`);
+}

package/dist/commands/add-module.js

@@ -2,6 +2,7 @@ import { execSync } from 'node:child_process';
 import { join } from 'node:path';
 import { Readable } from 'node:stream';
 import { Parser as TarParser } from 'tar';
+import ky from 'ky';
 import { readScaffoldConfig, writeScaffoldConfig } from '../utils/scaffold-config.js';
 import { readManifest, writeManifest, upsertManifestFile, inferPolicyFromPath } from '../utils/manifest.js';
 import { fetchModulesJson, fetchModuleTarball } from '../utils/s3-fetch.js';
@@ -65,18 +66,16 @@ async function detectRepoInfo() {
 }
 async function createGitHubPR(owner, repo, branchName, title, body, token) {
     try {
-        const response = await fetch(`https://api.github.com/repos/${owner}/${repo}/pulls`, {
-            method: 'POST',
+        const response = await ky.post(`https://api.github.com/repos/${owner}/${repo}/pulls`, {
             headers: {
                 Authorization: `Bearer ${token}`,
-                'Content-Type': 'application/json',
             },
-            body: JSON.stringify({
+            json: {
                 title,
                 body,
                 head: branchName,
                 base: 'develop',
-            }),
+            },
         });
         if (!response.ok) {
             const error = await response.json();

package/dist/commands/add-seed-page.js

@@ -3,6 +3,7 @@ import { join, resolve, dirname } from 'node:path';
 import { execSync } from 'node:child_process';
 import { createGunzip } from 'node:zlib';
 import { Readable } from 'node:stream';
+import ky from 'ky';
 import { cliLogger } from '../utils/logger.js';
 import { fetchVersionsJson, fetchModulesJson, fetchModuleTarball, } from '../utils/s3-fetch.js';
 import { readManifest } from '../utils/manifest.js';
@@ -30,20 +31,18 @@ function detectGitRemote(projectDir) {
 }
 async function createGitHubPR(owner, repo, token, branch, title, body) {
     const url = `https://api.github.com/repos/${owner}/${repo}/pulls`;
-    const res = await fetch(url, {
-        method: 'POST',
+    const res = await ky.post(url, {
         headers: {
             Authorization: `Bearer ${token}`,
             Accept: 'application/vnd.github+json',
-            'Content-Type': 'application/json',
             'X-GitHub-Api-Version': '2022-11-28',
         },
-        body: JSON.stringify({
+        json: {
             title,
             body,
             head: branch,
             base: 'develop',
-        }),
+        },
     });
     if (!res.ok) {
         const err = await res.text();

package/dist/commands/build-flows.js

@@ -57,7 +57,7 @@ const FlowConfigSchema = z.object({
     steps: z.array(FlowStepSchema).min(1),
     trigger: z.object({
         type: z.literal('event'),
-        eventId: z.string().includes('.'),
+        eventId: z.string().refine(val => val.includes('.'), { message: 'eventId must be namespaced (e.g. domain.event)' }),
         semverRange: z.string().min(1),
     }).optional(),
 });

package/dist/commands/dev.d.ts

@@ -1,3 +1,5 @@
+import { spawn, type ChildProcess } from 'node:child_process';
+import type { FastifyInstance } from 'fastify';
 /**
  * Options for the dev command.
  */
@@ -6,10 +8,35 @@ export interface DevOptions {
     domainRoot: string;
     /** Port for the local HTTP server. Defaults to 3000. */
     port?: number;
+    /** Absolute path to the project root. Defaults to process.cwd(). */
+    projectRoot?: string;
+    /** Port for the Vite frontend dev server. Defaults to 3001. */
+    frontendPort?: number;
+    /** Override the spawn function (used for tests). Defaults to node:child_process.spawn. */
+    spawnFn?: typeof spawn;
 }
 /**
- * Execute the dev command: build the domain registry and start the local Fastify
- * HTTP server. Keeps the process running. Shuts down gracefully on SIGINT/SIGTERM.
- * @param options - DevOptions specifying domain root and optional port.
+ * Handle returned by startDev, exposing the live processes and a shutdown function.
+ */
+export interface DevHandle {
+    /** The Fastify API server instance. */
+    server: FastifyInstance;
+    /** The Vite child process, or null when no frontend/ directory was found. */
+    vite: ChildProcess | null;
+    /** Shut down both processes gracefully. Idempotent. */
+    shutdown: () => Promise<void>;
+}
+/**
+ * Start the dev servers (Fastify API + Vite frontend if present) and return a handle.
+ * This is the testable entry point — the signal-handling logic lives in runDev.
+ * @param options - DevOptions specifying domain root, ports, and project root.
+ * @returns A DevHandle with the running server, vite child (or null), and shutdown.
+ */
+export declare function startDev(options: DevOptions): Promise<DevHandle>;
+/**
+ * Execute the dev command: build the domain registry, start the local Fastify
+ * HTTP server, and (if frontend/ exists) start a Vite dev server alongside it.
+ * Keeps the process running. Shuts down both children gracefully on SIGINT/SIGTERM.
+ * @param options - DevOptions specifying domain root, ports, and project root.
  */
 export declare function runDev(options: DevOptions): Promise<void>;

package/dist/commands/dev.js

@@ -1,15 +1,21 @@
-import { resolve } from 'node:path';
+import { resolve, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { spawn } from 'node:child_process';
 import { buildRegistry } from '../builder/build-registry.js';
 import { createApiServer } from '../server/api-server.js';
 import { cliLogger } from '../utils/logger.js';
 /**
- * Execute the dev command: build the domain registry and start the local Fastify
- * HTTP server. Keeps the process running. Shuts down gracefully on SIGINT/SIGTERM.
- * @param options - DevOptions specifying domain root and optional port.
+ * Start the dev servers (Fastify API + Vite frontend if present) and return a handle.
+ * This is the testable entry point — the signal-handling logic lives in runDev.
+ * @param options - DevOptions specifying domain root, ports, and project root.
+ * @returns A DevHandle with the running server, vite child (or null), and shutdown.
  */
-export async function runDev(options) {
+export async function startDev(options) {
+    const projectRoot = options.projectRoot ?? process.cwd();
     const domainRoot = resolve(options.domainRoot);
     const port = options.port ?? 3000;
+    const frontendPort = options.frontendPort ?? 3001;
+    const spawnFn = options.spawnFn ?? spawn;
     cliLogger.info({ domainRoot }, 'Building registry for dev server');
     const { registry, warnings } = await buildRegistry(domainRoot);
     for (const w of warnings) {
@@ -17,11 +23,46 @@ export async function runDev(options) {
     }
     cliLogger.info({ domain: registry.domain.id, apis: registry.apis.length, port }, 'Starting local dev server');
     const server = await createApiServer({ port, registry, domainRoot });
-    async function shutdown() {
-        cliLogger.info('Shutting down dev server');
-        await server.close();
-        process.exit(0);
+    // Spawn Vite if frontend/ exists; skip with warning otherwise.
+    const frontendDir = join(projectRoot, 'frontend');
+    let vite = null;
+    if (existsSync(frontendDir)) {
+        cliLogger.info({ frontendDir, port: frontendPort }, 'Starting Vite frontend dev server');
+        vite = spawnFn('npx', ['vite', '--port', String(frontendPort), '--strictPort'], {
+            cwd: frontendDir,
+            stdio: 'inherit',
+        });
+        vite.on('error', (err) => {
+            cliLogger.warn({ err: err.message }, 'Vite dev server failed to start');
+        });
     }
-    process.on('SIGINT', () => { void shutdown(); });
-    process.on('SIGTERM', () => { void shutdown(); });
+    else {
+        cliLogger.warn({ frontendDir }, 'No frontend/ directory found — skipping Vite dev server');
+    }
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        cliLogger.info('Shutting down dev servers');
+        if (vite && !vite.killed) {
+            vite.kill('SIGTERM');
+        }
+        await server.close();
+    };
+    return { server, vite, shutdown };
+}
+/**
+ * Execute the dev command: build the domain registry, start the local Fastify
+ * HTTP server, and (if frontend/ exists) start a Vite dev server alongside it.
+ * Keeps the process running. Shuts down both children gracefully on SIGINT/SIGTERM.
+ * @param options - DevOptions specifying domain root, ports, and project root.
+ */
+export async function runDev(options) {
+    const handle = await startDev(options);
+    const onSignal = () => {
+        void handle.shutdown().then(() => process.exit(0));
+    };
+    process.on('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
 }

package/dist/commands/doctor.d.ts

@@ -1,3 +1,9 @@
+/**
+ * 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 declare const DOCTOR_FIX_FLAG = "--fix";
 /**
  * Options for the doctor command.
  * Doctor is ALWAYS strict — any FAIL causes exit code 1.
@@ -7,6 +13,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;
 }
 /**
  * A single structural check result.