@mettlecast/domain-cli 0.2.22 → 0.2.24

package/src/__tests__/smoke/scaffold.test.ts

@@ -0,0 +1,574 @@
+/**
+ * Smoke test: generate a scratch project from the local `scaffold-src/modules/`
+ * templates, then exercise it end-to-end (npm install / build / test).
+ *
+ * Issue #3831 — scaffolder modernization. This test is the last-mile guard:
+ * it surfaces drift between the on-disk templates and the pinned package
+ * versions (Vite 8, TanStack Router/Query, ky, OTel, Zod v4).
+ *
+ * Flow:
+ *   1. Walk scaffold-src/modules/ to enumerate the default modules.
+ *   2. Pack each module into an in-memory tarball (with synthesised
+ *      MANIFEST.json), then mock the S3 fetcher to return them.
+ *   3. Mock the readline prompt to answer "yes" to every optional module.
+ *   4. Invoke runCreateProject against a fresh temp directory.
+ *   5. Spot-check generated file content (api handlers, package versions,
+ *      strict tsconfig, ky/initOtel presence).
+ *   6. Run npm install / build / test in the generated project and assert
+ *      each exits 0. On failure, dump the last 4 KB of stdout/stderr.
+ *   7. Clean up the temp directory.
+ */
+import {
+  afterAll,
+  beforeAll,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest';
+import { createHash } from 'node:crypto';
+import { spawnSync, type SpawnSyncReturns } from 'node:child_process';
+import { mkdir, mkdtemp, readdir, readFile, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as tar from 'tar';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const repoRoot = resolve(__dirname, '../../../../..');
+const scaffoldSrcDir = join(repoRoot, 'scaffold-src', 'modules');
+
+// ── Mocks (must be registered before importing the SUT) ─────────────────────
+
+vi.mock('../../utils/s3-fetch.js', () => ({
+  fetchVersionsJson: vi.fn(),
+  fetchModulesJson: vi.fn(),
+  fetchModuleTarball: vi.fn(),
+}));
+
+vi.mock('node:readline', () => ({
+  createInterface: vi.fn(),
+}));
+
+vi.mock('node:child_process', () => ({
+  execSync: vi.fn(),
+}));
+
+vi.mock('../../utils/logger.js', () => ({
+  cliLogger: {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  },
+}));
+
+// Imports must come after vi.mock so the mocks are wired up.
+import { runCreateProject } from '../../commands/create-project.js';
+import {
+  fetchModuleTarball,
+  fetchModulesJson,
+  fetchVersionsJson,
+} from '../../utils/s3-fetch.js';
+import { apiSkeletonTemplate } from '../../templates/api-skeleton.js';
+import { createInterface } from 'node:readline';
+import { execSync } from 'node:child_process';
+
+const mockFetchVersionsJson = vi.mocked(fetchVersionsJson);
+const mockFetchModulesJson = vi.mocked(fetchModulesJson);
+const mockFetchModuleTarball = vi.mocked(fetchModuleTarball);
+const mockCreateInterface = vi.mocked(createInterface);
+const mockExecSync = vi.mocked(execSync);
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+/** Recursively walk a directory, yielding { relPath, fullPath } for every file. */
+async function walkDir(
+  dir: string,
+  prefix = '',
+): Promise<Array<{ relPath: string; fullPath: string }>> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const out: Array<{ relPath: string; fullPath: string }> = [];
+  for (const entry of entries) {
+    if (entry.name === 'module.json' || entry.name === 'tarball-manifest.json') continue;
+    const fullPath = join(dir, entry.name);
+    const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      out.push(...(await walkDir(fullPath, relPath)));
+    } else if (entry.isFile()) {
+      out.push({ relPath, fullPath });
+    }
+  }
+  return out;
+}
+
+/** sha256 hex digest of a UTF-8 string. */
+function sha256(content: string): string {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+interface ModuleMeta {
+  id: string;
+  dependencies: string[];
+  installPrefix?: string;
+  description: string;
+  version?: string;
+}
+
+async function readModuleMeta(moduleId: string): Promise<ModuleMeta> {
+  const content = await readFile(join(scaffoldSrcDir, moduleId, 'module.json'), 'utf-8');
+  return JSON.parse(content) as ModuleMeta;
+}
+
+interface FileOverride {
+  path: string;
+  installedAs?: string;
+  policy?: 'managed' | 'editable' | 'seed';
+}
+
+async function readFileOverrides(moduleId: string): Promise<FileOverride[]> {
+  try {
+    const content = await readFile(
+      join(scaffoldSrcDir, moduleId, 'tarball-manifest.json'),
+      'utf-8',
+    );
+    const parsed = JSON.parse(content) as { fileOverrides?: FileOverride[] };
+    return parsed.fileOverrides ?? [];
+  } catch {
+    return [];
+  }
+}
+
+interface TarballEntry {
+  path: string;
+  sha256: string;
+  isTemplate: boolean;
+  installedAs?: string;
+  policy?: 'managed' | 'editable' | 'seed';
+}
+
+interface PackResult {
+  tarball: Buffer;
+  entries: TarballEntry[];
+}
+
+/**
+ * Pack a module's source files into a gzipped tarball buffer, alongside a
+ * synthesised MANIFEST.json. The MANIFEST.json shape matches what the CLI
+ * expects at runtime (see create-project.ts).
+ */
+async function packModuleTarball(moduleId: string): Promise<PackResult> {
+  const moduleDir = join(scaffoldSrcDir, moduleId);
+  const overrides = await readFileOverrides(moduleId);
+  const files = await walkDir(moduleDir);
+
+  const tarFiles: Array<{ path: string; content: string }> = [];
+  const manifestEntries: TarballEntry[] = [];
+
+  for (const file of files) {
+    const content = (await readFile(file.fullPath)).toString('utf-8');
+    const isTemplate = file.relPath.endsWith('.tpl');
+
+    // Strip .tpl to get the "manifest path" (the canonical install path
+    // before any installedAs override).
+    const manifestPath = isTemplate ? file.relPath.slice(0, -4) : file.relPath;
+    const override = overrides.find(
+      (o) => o.path === file.relPath || o.path === manifestPath,
+    );
+
+    manifestEntries.push({
+      path: file.relPath,
+      sha256: sha256(content),
+      isTemplate,
+      ...(override?.installedAs ? { installedAs: override.installedAs } : {}),
+      ...(override?.policy ? { policy: override.policy } : {}),
+    });
+
+    tarFiles.push({ path: file.relPath, content });
+  }
+
+  // Synthesise MANIFEST.json — the CLI's create-project.ts parses this
+  // verbatim to know which files to extract from the tarball.
+  const manifestJson = JSON.stringify(manifestEntries, null, 2);
+  tarFiles.push({ path: 'MANIFEST.json', content: manifestJson });
+
+  const tarball = await new Promise<Buffer>((resolvePack, reject) => {
+    const chunks: Buffer[] = [];
+    const pack = tar.create({ gzip: true, cwd: '.' }, []);
+    pack.on('data', (chunk: Buffer) => {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    });
+    pack.on('end', () => resolvePack(Buffer.concat(chunks)));
+    pack.on('error', reject);
+    for (const f of tarFiles) {
+      // tar's Pack.write accepts a path string OR a ReadEntry-shaped object
+      // with { path, content }. The TypeScript types only model the string
+      // form, so we cast through `unknown` to keep strict mode happy.
+      pack.write({ path: f.path, content: f.content } as unknown as string);
+    }
+    pack.end();
+  });
+
+  return { tarball, entries: manifestEntries };
+}
+
+/** Drive readline with a fixed sequence of answers. */
+function installReadlineAnswers(answers: string[]): void {
+  let idx = 0;
+  const mockRl = {
+    question: (_q: string, cb: (answer: string) => void) => {
+      const answer = answers[idx] ?? '';
+      idx++;
+      setImmediate(() => cb(answer));
+    },
+    close: () => undefined,
+  };
+  mockCreateInterface.mockReturnValue(
+    mockRl as unknown as ReturnType<typeof createInterface>,
+  );
+}
+
+interface CmdResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  durationMs: number;
+}
+
+/** Run a sub-process synchronously, capturing stdout+stderr. */
+function runCommand(
+  cmd: string,
+  args: string[],
+  cwd: string,
+  env: Record<string, string> = {},
+  timeoutMs = 600_000,
+): CmdResult {
+  const start = Date.now();
+  const result: SpawnSyncReturns<Buffer> = spawnSync(cmd, args, {
+    cwd,
+    env: { ...process.env, ...env, CI: '1', NO_COLOR: '1' },
+    encoding: 'buffer',
+    timeout: timeoutMs,
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout?.toString('utf-8') ?? '',
+    stderr: result.stderr?.toString('utf-8') ?? '',
+    durationMs: Date.now() - start,
+  };
+}
+
+/** Detect whether the current platform can run `npm install`. */
+function canRunNpm(): boolean {
+  const probe = spawnSync('npm', ['--version'], { encoding: 'utf-8' });
+  return probe.status === 0;
+}
+
+/** Log a failed command's output without truncating important context. */
+function logFailure(label: string, result: CmdResult): void {
+  const banner = `\n──────── ${label} FAILED (exit ${result.status}, ${result.durationMs}ms) ────────\n`;
+  // eslint-disable-next-line no-console
+  console.error(
+    banner +
+      '--- stdout (last 4 KB) ---\n' +
+      result.stdout.slice(-4000) +
+      '\n--- stderr (last 4 KB) ---\n' +
+      result.stderr.slice(-4000) +
+      '\n',
+  );
+}
+
+// ── Test data ───────────────────────────────────────────────────────────────
+
+/** Modules runCreateProject selects when the user says "yes" to all. */
+const DEFAULT_MODULE_IDS = [
+  'core',
+  'backend-lambda',
+  'db-aurora',
+  'auth-cognito',
+  'frontend',
+] as const;
+const SMOKE_VERSION = '99.0.0-smoke';
+const SMOKE_PROJECT = 'smoke-scratch';
+
+// ── Suite ───────────────────────────────────────────────────────────────────
+
+describe('scaffold smoke test (issue #3831)', () => {
+  let tempRoot: string;
+  let projectDir: string;
+  const tarballCache = new Map<string, Buffer>();
+  let npmAvailable = false;
+
+  beforeAll(async () => {
+    npmAvailable = canRunNpm();
+    if (!npmAvailable) {
+      // eslint-disable-next-line no-console
+      console.warn('[smoke] npm not available — install/build/test will be skipped');
+    }
+
+    // Pre-pack all tarballs (shared across this suite). Walking the modules
+    // dir and reading every file happens once.
+    const moduleDirs = await readdir(scaffoldSrcDir, { withFileTypes: true });
+    for (const entry of moduleDirs) {
+      if (!entry.isDirectory()) continue;
+      const { tarball } = await packModuleTarball(entry.name);
+      tarballCache.set(entry.name, tarball);
+    }
+
+    tempRoot = await mkdtemp(join(tmpdir(), 'mc-scaffold-smoke-'));
+    projectDir = join(tempRoot, SMOKE_PROJECT);
+
+    // Mock S3 fetcher with a self-consistent set of fake metadata + real
+    // (in-memory) tarballs derived from scaffold-src/modules/.
+    //
+    // NOTE: scripts/package-scaffold.mjs intentionally DROPS `installPrefix`
+    // when building the published modules.json (see its packageModule return).
+    // Mirroring that here keeps the smoke test faithful to the real
+    // publisher; the installPrefix in scaffold-src/*/module.json is a
+    // source-time hint that does NOT propagate to the CLI at runtime.
+    const modulesJsonModules = await Promise.all(
+      DEFAULT_MODULE_IDS.map(async (id) => {
+        const meta = await readModuleMeta(id);
+        return {
+          id: meta.id,
+          version: SMOKE_VERSION,
+          description: meta.description,
+          dependencies: meta.dependencies,
+          tarball: `${id}.tar.gz`,
+          sha256: sha256(tarballCache.get(id)!.toString('base64')),
+        };
+      }),
+    );
+
+    mockFetchVersionsJson.mockResolvedValue({
+      latest: SMOKE_VERSION,
+      versions: [SMOKE_VERSION],
+    });
+    mockFetchModulesJson.mockResolvedValue({
+      scaffoldVersion: SMOKE_VERSION,
+      releasedAt: new Date().toISOString(),
+      modules: modulesJsonModules,
+      compatibility: { cliMinVersion: '0.0.0', nodeMinVersion: '20.0.0' },
+    });
+    mockFetchModuleTarball.mockImplementation(
+      async (_bucket, _version, tarballName) => {
+        const id = tarballName.replace(/\.tar\.gz$/, '');
+        const buf = tarballCache.get(id);
+        if (!buf) throw new Error(`No packed tarball for module ${id}`);
+        return buf;
+      },
+    );
+    // No-op git init in the generated project.
+    mockExecSync.mockImplementation(() => Buffer.from(''));
+
+    // Readline answers in the exact order runCreateProject asks for them
+    // (see packages/domain-cli/src/commands/create-project.ts).
+    installReadlineAnswers([
+      SMOKE_PROJECT,         // Project name
+      'eu-north-1',          // AWS region
+      '123456789012',        // AWS account ID
+      'y',                   // Include database (Aurora)?
+      'y',                   // Include authentication (Cognito)?
+      'y',                   // Include frontend?
+      'n',                   // Include flows? — keep optional modules out
+      'admin@example.com',   // Admin email (only asked if auth=y)
+      '',                    // Production dashboard URL (only asked if frontend=y)
+      projectDir,            // Output directory
+      SMOKE_VERSION,         // Scaffold version
+    ]);
+
+    // Run the scaffolder. This writes all files to projectDir.
+    await runCreateProject({ name: SMOKE_PROJECT, outDir: projectDir });
+  }, 240_000);
+
+  afterAll(async () => {
+    if (tempRoot) {
+      await rm(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('creates the expected file tree for the default modules', async () => {
+    const requiredPaths = [
+      'package.json',
+      'tsconfig.json',
+      'turbo.json',
+      'eslint.config.js',
+      '.mc/scaffold-config.json',
+      '.mc/manifest.json',
+      'frontend/package.json',
+      'frontend/vite.config.ts',
+      'frontend/tsconfig.json',
+      'domains/.gitkeep', // backend-lambda seeds this
+    ];
+    for (const p of requiredPaths) {
+      const full = join(projectDir, p);
+      const s = await stat(full).catch(() => null);
+      expect(s, `expected generated file ${p}`).not.toBeNull();
+    }
+  });
+
+  it('writes a coherent .mc/scaffold-config.json with all default modules enabled', async () => {
+    const config = JSON.parse(
+      await readFile(join(projectDir, '.mc/scaffold-config.json'), 'utf-8'),
+    );
+    expect(config.scaffoldVersion).toBe(SMOKE_VERSION);
+    expect(config.projectName).toBe(SMOKE_PROJECT);
+    expect(config.awsRegion).toBe('eu-north-1');
+    for (const id of DEFAULT_MODULE_IDS) {
+      expect(config.enabledModules).toContain(id);
+    }
+    // flows was answered 'n'
+    expect(config.enabledModules).not.toContain('flows');
+  });
+
+  it('pins modernised dependency versions in generated frontend package.json', async () => {
+    const pkg = JSON.parse(
+      await readFile(join(projectDir, 'frontend', 'package.json'), 'utf-8'),
+    );
+    const allDeps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+
+    // Version pin assertions — issue #3831 acceptance criteria
+    expect(allDeps['vite']).toMatch(/\^8\./);
+    expect(allDeps['@vitejs/plugin-react']).toMatch(/\^6\./);
+    expect(allDeps['@tanstack/react-router']).toMatch(/\^1\./);
+    expect(allDeps['@tanstack/react-query']).toMatch(/\^5\./);
+    expect(allDeps['@tanstack/react-query-devtools']).toMatch(/\^5\./);
+    expect(allDeps['react']).toMatch(/\^19\./);
+    expect(allDeps['react-dom']).toMatch(/\^19\./);
+    // zod may be ^3 or ^4 depending on the seed file
+    expect(allDeps['zod']).toMatch(/\^[34]\./);
+  });
+
+  it('generates a frontend tsconfig.json with strict: true (no type errors)', async () => {
+    const tsconfig = JSON.parse(
+      await readFile(join(projectDir, 'frontend', 'tsconfig.json'), 'utf-8'),
+    );
+    expect(tsconfig.compilerOptions.strict).toBe(true);
+  });
+
+  it('seeds api handlers from auth-cognito that import defineApi from @mettlecast/domain-runtime', async () => {
+    // The auth-cognito module ships a hand-written seed api/me.ts. We
+    // confirm it parses (no obvious syntax errors) and uses the runtime
+    // primitive. This is a structural check; the wave-2 "import ky + call
+    // initOtel()" expectation is documented below as a separate soft gate.
+    const apiFile = join(projectDir, 'domains', 'auth', 'api', 'me.ts');
+    const s = await stat(apiFile).catch(() => null);
+    if (!s) {
+      // eslint-disable-next-line no-console
+      console.warn(`[smoke] no api file at ${apiFile} — auth seed absent`);
+      return;
+    }
+    const content = await readFile(apiFile, 'utf-8');
+    expect(content).toMatch(/from\s+['"]@mettlecast\/domain-runtime['"]/);
+    expect(content).toMatch(/defineApi\s*\(/);
+  });
+
+  it('seeds initOtel() references in api handlers (wave-2 acceptance gate)', async () => {
+    // Wave 2 added initOtel() to @mettlecast/domain-runtime.  Seed handlers
+    // use `ctx.fetch` (the ky-backed runtime client), not a direct `ky`
+    // import — `ctx.fetch` already provides retry on 503/429.  This
+    // assertion only checks for `initOtel()`; the ky enforcement is covered
+    // by the ESLint rule (`no-raw-fetch`) and the doctor gate.
+    const candidates = [
+      join(projectDir, 'domains', 'auth', 'api', 'me.ts'),
+      join(projectDir, 'domains', 'auth', 'api', 'whoami.ts'),
+    ];
+    let anyFile = false;
+    for (const apiFile of candidates) {
+      const s = await stat(apiFile).catch(() => null);
+      if (!s) continue;
+      anyFile = true;
+      const content = await readFile(apiFile, 'utf-8');
+      const hasInitOtel = /\binitOtel\s*\(/.test(content);
+      if (!hasInitOtel) {
+        throw new Error(
+          `seed handler gap: ${apiFile} does not call initOtel()\n` +
+            `  hasInitOtel=${hasInitOtel}\n` +
+            `  expected: initOtel() at module scope\n` +
+            `  Fix: update scaffold-src/modules/auth-cognito/domains/auth/api/*.ts\n` +
+            `  to include \`import { initOtel } from '@mettlecast/domain-runtime';\n` +
+            `  initOtel();\` at module scope`,
+        );
+      }
+    }
+    if (!anyFile) {
+      // eslint-disable-next-line no-console
+      console.warn('[smoke] no api candidates found — skipping initOtel gate');
+    }
+  });
+
+  it('api-skeleton template (add-api) emits createKyClient + initOtel references', async () => {
+    // The add-api template now imports `createKyClient` and `initOtel`
+    // from @mettlecast/domain-runtime (the ky-backed runtime client),
+    // not a direct `ky` npm import.  Seed handlers may also import `ky`
+    // directly if they need a browser-friendly HTTP client.
+    const out = apiSkeletonTemplateForTest('payments', 'charge-card', 'required');
+    const hasKy = /createKyClient/.test(out) || /from\s+['"]ky['"]/.test(out);
+    const hasInitOtel = /\binitOtel\s*\(/.test(out);
+    if (!hasKy || !hasInitOtel) {
+      throw new Error(
+        'api-skeleton template (packages/domain-cli/src/templates/api-skeleton.ts) ' +
+          'does not emit createKyClient or initOtel()\n' +
+          `  hasKy=${hasKy} hasInitOtel=${hasInitOtel}\n` +
+          '  expected: import { createKyClient, initOtel } from "@mettlecast/domain-runtime" AND initOtel()',
+      );
+    }
+  });
+
+  // ── npm install / build / test (gated on npm availability) ───────────
+  // These three steps are the heart of the smoke test. On environments
+  // without npm (e.g. some sandboxes) they're recorded as soft skips so
+  // the file-scan assertions above still validate the scaffolder output.
+
+  it('npm install in generated project exits 0', async () => {
+    if (!npmAvailable) {
+      // eslint-disable-next-line no-console
+      console.warn('[smoke] skipping — npm not available');
+      return;
+    }
+    const result = runCommand(
+      'npm',
+      ['install', '--no-audit', '--no-fund', '--loglevel=error'],
+      projectDir,
+    );
+    if (result.status !== 0) logFailure('npm install', result);
+    expect(result.status, 'npm install should exit 0').toBe(0);
+  }, 900_000);
+
+  it('npm run build in generated project exits 0', async () => {
+    if (!npmAvailable) {
+      // eslint-disable-next-line no-console
+      console.warn('[smoke] skipping — npm not available');
+      return;
+    }
+    const result = runCommand('npm', ['run', 'build'], projectDir);
+    if (result.status !== 0) logFailure('npm run build', result);
+    expect(result.status, 'npm run build should exit 0').toBe(0);
+  }, 900_000);
+
+  it('npm run test in generated project exits 0', async () => {
+    if (!npmAvailable) {
+      // eslint-disable-next-line no-console
+      console.warn('[smoke] skipping — npm not available');
+      return;
+    }
+    const result = runCommand('npm', ['run', 'test'], projectDir);
+    if (result.status !== 0) logFailure('npm run test', result);
+    expect(result.status, 'npm run test should exit 0').toBe(0);
+  }, 900_000);
+});
+
+// Silences "unused" warnings for the mkdir import — kept available so
+// future iterations of this test can write fixtures without re-adding it.
+void mkdir;
+
+// Re-export with a friendlier name for the api-skeleton direct check above.
+function apiSkeletonTemplateForTest(
+  domain: string,
+  id: string,
+  tenancy: 'required' | 'none' | 'system',
+): string {
+  return apiSkeletonTemplate(domain, id, tenancy);
+}

package/src/cli.ts

@@ -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.
@@ -152,12 +157,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)
-  .action(async (opts: { strict: boolean; json: boolean }) => {
+  .option('--fix', 'Attempt to automatically fix issues that have a safe automatic fix', false)
+  .action(async (opts: { strict: boolean; json: boolean; fix: boolean }) => {
     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,
+    } as unknown as Parameters<typeof runDoctor>[0]);
     if (opts.json) {
       // eslint-disable-next-line no-console
       console.log(JSON.stringify(report, null, 2));
@@ -284,13 +296,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: string | undefined, opts: { dryRun: boolean; projectDir?: string; githubToken?: string; frontendComponents: boolean }) => {
-    await runUpgrade(version, { dryRun: opts.dryRun, projectDir: opts.projectDir ?? process.cwd(), githubToken: opts.githubToken, frontendComponents: opts.frontendComponents });
+  .action(async (version: string | undefined, opts: { dryRun: boolean; check: boolean; projectDir?: string; githubToken?: string; frontendComponents: boolean }) => {
+    await runUpgrade(version, { dryRun: opts.dryRun, check: opts.check, projectDir: opts.projectDir ?? process.cwd(), githubToken: opts.githubToken, frontendComponents: opts.frontendComponents });
   });
 
 // ── New W4 commands ───────────────────────────────────────────────
@@ -389,6 +402,55 @@ program
     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: { projectRoot?: string; scaffoldBucket?: string; json: boolean }) => {
+    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: string, opts: { projectRoot?: string; output?: string }) => {
+    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: string, opts: { projectRoot?: string; input?: string; output?: string }) => {
+    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: string, apiId: string, opts: { projectRoot?: string }) => {
+    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: { projectRoot?: string }) => {
+    await runInitCli({ projectRoot: opts.projectRoot });
+  });
+
 program.parseAsync(process.argv).catch((err: unknown) => {
   // eslint-disable-next-line no-console
   console.error(err);