@mettlecast/domain-cli 0.2.21 → 0.2.23

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);

package/src/commands/add-api.ts

@@ -6,12 +6,34 @@
 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';
 
 /**
@@ -24,6 +46,7 @@ export const API_PATTERNS = [
   'idempotent-mutation',
   'webhook-receiver-style',
   'system-admin',
+  'streaming-list',
 ] as const;
 
 export type ApiPattern = (typeof API_PATTERNS)[number];
@@ -87,8 +110,11 @@ export async function runAddApi(opts: AddApiOptions): Promise<void> {
 
   // Resolve template content
   let apiContent: string;
+  let exampleBody: string = '{}';
   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 {
     apiContent = apiSkeletonTemplate(opts.domain, opts.id, opts.tenancy);
@@ -97,12 +123,12 @@ export async function runAddApi(opts: AddApiOptions): Promise<void> {
   // 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)
+    apiFixtureSkeleton(opts.domain, opts.id, exampleBody)
   );
 
   cliLogger.info({ domain: opts.domain, api: opts.id, method: opts.method ?? 'GET', pattern: opts.pattern ?? 'skeleton' }, 'API added');
@@ -123,22 +149,45 @@ function resolveApiPattern(
   domain: string,
   id: string,
   tenancy: string,
-): string {
+): { apiContent: string; exampleBody: string } {
   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);
-    case 'system-admin':
-      return systemAdminTemplate(domain, id, tenancy);
+      return {
+        apiContent: webhookReceiverStyleTemplate(domain, id, tenancy),
+        exampleBody: webhookReceiverStyleExampleBody,
+      };
+     case 'system-admin':
+      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/src/commands/add-fixture-factory.ts

@@ -0,0 +1,75 @@
+/**
+ * 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';
+
+export interface AddFixtureFactoryOptions {
+  domain: string;
+  apiId: string;
+  projectRoot?: string;
+}
+
+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: AddFixtureFactoryOptions): Promise<string> {
+  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: string, apiId: string, opts: { projectRoot?: string } = {}): Promise<void> {
+  const factoryFile = await runAddFixtureFactory({ domain, apiId, ...opts });
+  // eslint-disable-next-line no-console
+  console.log(`Fixture factory written to: ${factoryFile}`);
+}

package/src/commands/add-module.ts

@@ -3,6 +3,7 @@ import { mkdir } from 'node:fs/promises';
 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';
@@ -99,18 +100,16 @@ async function createGitHubPR(
   token: string
 ): Promise<{ prUrl: string; prNumber: number } | null> {
   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) {

package/src/commands/add-seed-page.ts

@@ -4,6 +4,7 @@ import { execSync } from 'node:child_process';
 import { createGunzip } from 'node:zlib';
 import { Readable } from 'node:stream';
 import { extract } from 'tar';
+import ky from 'ky';
 import { cliLogger } from '../utils/logger.js';
 import {
   fetchVersionsJson,
@@ -58,20 +59,18 @@ async function createGitHubPR(
   body: string
 ): Promise<{ url: string; number: number }> {
   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) {

package/src/commands/build-flows.ts

@@ -70,12 +70,12 @@ const FlowStepSchema = z.union([
 const FlowConfigSchema = z.object({
   id: z.string().regex(/^[a-z][a-z0-9-]*$/),
   owningDomain: z.string().regex(/^[a-z][a-z0-9-]*$/).optional(),
-  type: z.enum(['express', 'standard']).optional(),
+  type: z.enum(['express', 'standard'] as const).optional(),
   name: z.string().min(1),
   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/src/commands/dev.ts

@@ -1,4 +1,7 @@
-import { resolve } from 'node:path';
+import { resolve, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { spawn, type ChildProcess } from 'node:child_process';
+import type { FastifyInstance } from 'fastify';
 import { buildRegistry } from '../builder/build-registry.js';
 import { createApiServer } from '../server/api-server.js';
 import { cliLogger } from '../utils/logger.js';
@@ -11,16 +14,38 @@ 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 async function runDev(options: DevOptions): Promise<void> {
+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 async function startDev(options: DevOptions): Promise<DevHandle> {
+  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);
@@ -36,12 +61,54 @@ export async function runDev(options: DevOptions): Promise<void> {
 
   const server = await createApiServer({ port, registry, domainRoot });
 
-  async function shutdown(): Promise<void> {
-    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: ChildProcess | null = 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: Error) => {
+      cliLogger.warn({ err: err.message }, 'Vite dev server failed to start');
+    });
+  } else {
+    cliLogger.warn(
+      { frontendDir },
+      'No frontend/ directory found — skipping Vite dev server'
+    );
   }
 
-  process.on('SIGINT', () => { void shutdown(); });
-  process.on('SIGTERM', () => { void shutdown(); });
+  let shuttingDown = false;
+  const shutdown = async (): Promise<void> => {
+    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: DevOptions): Promise<void> {
+  const handle = await startDev(options);
+
+  const onSignal = (): void => {
+    void handle.shutdown().then(() => process.exit(0));
+  };
+  process.on('SIGINT', onSignal);
+  process.on('SIGTERM', onSignal);
 }