ai-spec-dev 0.31.0 → 0.35.0

package/cli/commands/dashboard.ts

@@ -0,0 +1,62 @@
+import { Command } from "commander";
+import * as path from "path";
+import * as fs from "fs-extra";
+import chalk from "chalk";
+import { execSync } from "child_process";
+import { loadRunLogs } from "../../core/run-trend";
+import { generateDashboard } from "../../core/dashboard-generator";
+
+export function registerDashboard(program: Command): void {
+  program
+    .command("dashboard")
+    .description("Generate an HTML Harness Dashboard from run logs")
+    .option("--output <path>", "Output file path (default: .ai-spec/dashboard.html)")
+    .option("--open", "Auto-open the dashboard in the default browser after generation")
+    .option("--last <n>", "Limit to the last N runs (default: all)", "0")
+    .action(async (opts) => {
+      const currentDir = process.cwd();
+
+      // ── Load run logs ────────────────────────────────────────────────────────
+      let logs = await loadRunLogs(currentDir);
+      if (logs.length === 0) {
+        console.log(chalk.yellow("\n  No run logs found. Run `ai-spec create` at least once first.\n"));
+        return;
+      }
+
+      const last = parseInt(opts.last, 10);
+      if (last > 0) logs = logs.slice(0, last);
+
+      // ── Generate HTML ────────────────────────────────────────────────────────
+      const html = generateDashboard(logs);
+
+      // ── Write file ───────────────────────────────────────────────────────────
+      const outputPath = opts.output
+        ? path.resolve(opts.output)
+        : path.join(currentDir, ".ai-spec", "dashboard.html");
+
+      await fs.ensureDir(path.dirname(outputPath));
+      await fs.writeFile(outputPath, html, "utf-8");
+      const relPath = path.relative(currentDir, outputPath);
+
+      console.log(chalk.green(`\n  ✔ Dashboard generated: ${relPath}`));
+      console.log(chalk.gray(`  Runs analyzed : ${logs.length}`));
+      console.log(chalk.gray(`  Size          : ${Math.round(html.length / 1024)}KB`));
+      console.log(chalk.blue(`\n  Open in browser:`));
+      console.log(chalk.gray(`    open ${relPath}\n`));
+
+      // ── Auto-open ────────────────────────────────────────────────────────────
+      if (opts.open) {
+        try {
+          const cmd =
+            process.platform === "darwin"
+              ? `open "${outputPath}"`
+              : process.platform === "win32"
+              ? `start "" "${outputPath}"`
+              : `xdg-open "${outputPath}"`;
+          execSync(cmd);
+        } catch {
+          // Non-fatal — file was already written
+        }
+      }
+    });
+}

package/cli/commands/export.ts

@@ -0,0 +1,66 @@
+import { Command } from "commander";
+import * as path from "path";
+import * as fs from "fs-extra";
+import chalk from "chalk";
+import { SpecDSL } from "../../core/dsl-types";
+import { exportOpenApi } from "../../core/openapi-exporter";
+import { findLatestDslFile } from "../../core/mock-server-generator";
+
+export function registerExport(program: Command): void {
+  program
+    .command("export")
+    .description("Export the latest DSL to OpenAPI 3.1.0 (YAML or JSON)")
+    .option("--openapi", "Export as OpenAPI 3.1.0 (default behaviour)")
+    .option("--format <fmt>", "Output format: yaml | json (default: yaml)", "yaml")
+    .option("--output <path>", "Output file path (default: openapi.yaml)")
+    .option("--server <url>", "API server URL in the OpenAPI document (default: http://localhost:3000)")
+    .option("--dsl <path>", "Path to a specific .dsl.json file (auto-detected if omitted)")
+    .action(async (opts) => {
+      const currentDir = process.cwd();
+
+      // ── Find DSL ────────────────────────────────────────────────────────────
+      let dslPath: string | null = opts.dsl ?? null;
+      if (!dslPath) {
+        dslPath = await findLatestDslFile(currentDir);
+        if (!dslPath) {
+          console.error(chalk.red("  No .dsl.json file found. Run `ai-spec create` first or use --dsl <path>."));
+          process.exit(1);
+        }
+        console.log(chalk.gray(`  Using DSL: ${path.relative(currentDir, dslPath)}`));
+      }
+
+      let dsl: SpecDSL;
+      try {
+        dsl = await fs.readJson(dslPath);
+      } catch (err) {
+        console.error(chalk.red(`  Failed to read DSL: ${(err as Error).message}`));
+        process.exit(1);
+      }
+
+      // ── Export ──────────────────────────────────────────────────────────────
+      console.log(chalk.blue("\n─── ai-spec export ─────────────────────────────"));
+
+      const format = (opts.format === "json" ? "json" : "yaml") as "yaml" | "json";
+      const serverUrl = opts.server || "http://localhost:3000";
+
+      try {
+        const outputPath = await exportOpenApi(dsl, currentDir, {
+          format,
+          serverUrl,
+          outputPath: opts.output,
+        });
+        const rel = path.relative(currentDir, outputPath);
+        console.log(chalk.green(`  ✔ OpenAPI ${format.toUpperCase()} exported: ${rel}`));
+        console.log(chalk.gray(`  Feature  : ${dsl.feature.title}`));
+        console.log(chalk.gray(`  Endpoints: ${dsl.endpoints.length}`));
+        console.log(chalk.gray(`  Models   : ${dsl.models.length}`));
+        console.log(chalk.gray(`  Server   : ${serverUrl}`));
+        console.log(chalk.blue("\n  Next steps:"));
+        console.log(chalk.gray(`  • Import ${rel} into Postman / Insomnia / Swagger UI`));
+        console.log(chalk.gray(`  • Use openapi-generator to generate client SDKs`));
+      } catch (err) {
+        console.error(chalk.red(`  Export failed: ${(err as Error).message}`));
+        process.exit(1);
+      }
+    });
+}

package/cli/commands/init.ts

@@ -0,0 +1,190 @@
+import { Command } from "commander";
+import * as path from "path";
+import * as fs from "fs-extra";
+import chalk from "chalk";
+import { createProvider, DEFAULT_MODELS, SUPPORTED_PROVIDERS } from "../../core/spec-generator";
+import { ContextLoader } from "../../core/context-loader";
+import { ConstitutionGenerator, CONSTITUTION_FILE } from "../../core/constitution-generator";
+import { ConstitutionConsolidator } from "../../core/constitution-consolidator";
+import {
+  loadGlobalConstitution,
+  saveGlobalConstitution,
+  GLOBAL_CONSTITUTION_FILE,
+} from "../../core/global-constitution";
+import {
+  globalConstitutionSystemPrompt,
+  buildGlobalConstitutionPrompt,
+} from "../../prompts/global-constitution.prompt";
+import { loadConfig, resolveApiKey } from "../utils";
+import { loadIndex, ProjectEntry } from "../../core/project-index";
+
+export function registerInit(program: Command): void {
+  program
+    .command("init")
+    .description(`Analyze codebase and generate Project Constitution (${CONSTITUTION_FILE})`)
+    .option(
+      "--provider <name>",
+      `AI provider (${SUPPORTED_PROVIDERS.join("|")})`,
+      undefined
+    )
+    .option("--model <name>", "Model name")
+    .option("-k, --key <apiKey>", "API key")
+    .option("--force", "Overwrite existing constitution")
+    .option(
+      "--global",
+      `Generate a Global Constitution (~/${GLOBAL_CONSTITUTION_FILE}) instead of a project-level one`
+    )
+    .option("--consolidate", "Consolidate §9 accumulated lessons into §1–§8 core rules (prune & rebase)")
+    .option("--dry-run", "Preview consolidation result without writing (use with --consolidate)")
+    .action(async (opts) => {
+      const currentDir = process.cwd();
+      const config = await loadConfig(currentDir);
+
+      const providerName = opts.provider || config.provider || "gemini";
+      const modelName = opts.model || config.model || DEFAULT_MODELS[providerName];
+      const apiKey = await resolveApiKey(providerName, opts.key);
+      const provider = createProvider(providerName, apiKey, modelName);
+
+      // ── Consolidate mode ───────────────────────────────────────────────────
+      if (opts.consolidate) {
+        const consolidator = new ConstitutionConsolidator(provider);
+        try {
+          const result = await consolidator.consolidate(currentDir, {
+            dryRun: opts.dryRun,
+            auto: opts.auto,
+          });
+          if (result.written) {
+            console.log(chalk.blue("\n  Summary:"));
+            console.log(chalk.gray(`  Lines : ${result.before.totalLines} → ${result.after.totalLines} (${result.before.totalLines - result.after.totalLines > 0 ? "-" : "+"}${Math.abs(result.before.totalLines - result.after.totalLines)})`));
+            console.log(chalk.gray(`  §9    : ${result.before.lessonCount} → ${result.after.lessonCount} lessons remaining`));
+            if (result.backupPath) {
+              console.log(chalk.gray(`  Backup: ${path.basename(result.backupPath)}`));
+            }
+          }
+        } catch (err) {
+          console.error(chalk.red(`  ✘ Consolidation failed: ${(err as Error).message}`));
+          process.exit(1);
+        }
+        return;
+      }
+
+      // ── Global constitution mode ───────────────────────────────────────────
+      if (opts.global) {
+        const existing = await loadGlobalConstitution([currentDir]);
+        if (existing && !opts.force) {
+          console.log(chalk.yellow(`\n  Global constitution already exists at: ${existing.source}`));
+          console.log(chalk.gray("  Use --force to overwrite it."));
+          return;
+        }
+
+        console.log(chalk.blue("\n─── Generating Global Constitution ──────────────"));
+        console.log(chalk.gray(`  Provider: ${providerName}/${modelName}`));
+
+        // ── Build per-project summaries ────────────────────────────────────
+        const projectSummaries: Array<{ name: string; summary: string }> = [];
+        const index = await loadIndex(currentDir);
+
+        if (index && index.projects.length > 0) {
+          const active = index.projects.filter((p: ProjectEntry) => !p.missing);
+          console.log(chalk.gray(`  Found project index: ${active.length} project(s) — reading constitutions...`));
+
+          for (const entry of active) {
+            const absPath = path.join(currentDir, entry.path);
+            const lines: string[] = [
+              `Type: ${entry.type} (${entry.role})`,
+              `Tech stack: ${entry.techStack.join(", ") || "unknown"}`,
+            ];
+
+            // Include §1–§6 of project constitution if available (skip §9 lessons)
+            if (entry.hasConstitution) {
+              try {
+                const constitutionPath = path.join(absPath, CONSTITUTION_FILE);
+                const raw = await fs.readFile(constitutionPath, "utf-8");
+                // Take up to first 2000 chars (covers §1–§6 without §9 noise)
+                const excerpt = raw.slice(0, 2000);
+                lines.push("", "Constitution excerpt:", excerpt);
+              } catch { /* skip if unreadable */ }
+            }
+
+            projectSummaries.push({ name: entry.name, summary: lines.join("\n") });
+          }
+        } else {
+          // No index — fall back to scanning just the current directory
+          console.log(chalk.yellow("  No project index found. Run `ai-spec scan` first for better results."));
+          console.log(chalk.gray("  Falling back: scanning current directory only..."));
+          const loader = new ContextLoader(currentDir);
+          const ctx = await loader.loadProjectContext();
+          projectSummaries.push({
+            name: path.basename(currentDir),
+            summary: [
+              `Tech stack: ${ctx.techStack.join(", ") || "unknown"}`,
+              `Dependencies: ${ctx.dependencies.slice(0, 20).join(", ")}`,
+            ].join("\n"),
+          });
+        }
+
+        console.log(chalk.gray(`  Generating from ${projectSummaries.length} project(s)...`));
+        const prompt = buildGlobalConstitutionPrompt(projectSummaries);
+        let globalConstitution: string;
+        try {
+          globalConstitution = await provider.generate(prompt, globalConstitutionSystemPrompt);
+        } catch (err) {
+          console.error(chalk.red("  ✘ Failed to generate global constitution:"), err);
+          process.exit(1);
+        }
+
+        const saved = await saveGlobalConstitution(globalConstitution, currentDir);
+        console.log(chalk.green(`\n  ✔ Global constitution saved: ${saved}`));
+        console.log(chalk.gray("  This will be automatically merged into all project constitutions in this workspace."));
+        console.log(chalk.gray("  Project-level rules always override global rules.\n"));
+        console.log(chalk.bold("  Preview:"));
+        console.log(chalk.gray(globalConstitution.split("\n").slice(0, 12).join("\n")));
+        if (globalConstitution.split("\n").length > 12) {
+          console.log(chalk.gray(`  ... (${globalConstitution.split("\n").length} lines total)`));
+        }
+        return;
+      }
+
+      // ── Project constitution mode (default) ───────────────────────────────
+      const constitutionPath = path.join(currentDir, CONSTITUTION_FILE);
+
+      if (!opts.force && (await fs.pathExists(constitutionPath))) {
+        console.log(chalk.yellow(`\n  ${CONSTITUTION_FILE} already exists.`));
+        console.log(chalk.gray("  Use --force to overwrite it."));
+        console.log(chalk.gray(`  Or edit it directly: ${constitutionPath}`));
+        return;
+      }
+
+      console.log(chalk.blue("\n─── Generating Project Constitution ─────────────"));
+      console.log(chalk.gray(`  Provider: ${providerName}/${modelName}`));
+      console.log(chalk.gray("  Analyzing codebase..."));
+
+      const generator = new ConstitutionGenerator(provider);
+
+      let constitution: string;
+      try {
+        constitution = await generator.generate(currentDir);
+      } catch (err) {
+        console.error(chalk.red("  ✘ Failed to generate constitution:"), err);
+        process.exit(1);
+      }
+
+      const saved = await generator.saveConstitution(currentDir, constitution);
+
+      const globalResult = await loadGlobalConstitution([path.dirname(currentDir)]);
+      if (globalResult) {
+        console.log(chalk.cyan(`\n  ℹ Global constitution detected: ${globalResult.source}`));
+        console.log(chalk.gray("    It will be merged with this project constitution at runtime."));
+        console.log(chalk.gray("    Project rules take priority over global rules."));
+      }
+
+      console.log(chalk.green(`\n  ✔ Constitution saved: ${saved}`));
+      console.log(chalk.gray("  This file will be automatically used in all future `ai-spec create` runs."));
+      console.log(chalk.gray("  Edit it to add custom rules or red lines for your project.\n"));
+      console.log(chalk.bold("  Preview:"));
+      console.log(chalk.gray(constitution.split("\n").slice(0, 15).join("\n")));
+      if (constitution.split("\n").length > 15) {
+        console.log(chalk.gray(`  ... (${constitution.split("\n").length} lines total)`));
+      }
+    });
+}

package/cli/commands/learn.ts

@@ -0,0 +1,30 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { input } from "@inquirer/prompts";
+import { appendDirectLesson } from "../../core/knowledge-memory";
+
+export function registerLearn(program: Command): void {
+  program
+    .command("learn")
+    .description("Append a lesson or engineering decision directly to constitution §9")
+    .argument("[lesson]", "The lesson or decision to record (prompted if omitted)")
+    .action(async (lesson: string | undefined) => {
+      const currentDir = process.cwd();
+
+      if (!lesson) {
+        lesson = await input({
+          message: "What lesson or engineering decision should be recorded?",
+          validate: (v) => v.trim().length > 0 || "Please enter a lesson",
+        });
+      }
+
+      const result = await appendDirectLesson(currentDir, lesson.trim());
+
+      if (result.appended) {
+        console.log(chalk.green(`\n  ✔ Lesson appended to constitution §9`));
+        console.log(chalk.gray(`  File: .ai-spec-constitution.md`));
+      } else {
+        console.log(chalk.yellow(`\n  ⚠ Not appended: ${result.reason}`));
+      }
+    });
+}

package/cli/commands/logs.ts

@@ -0,0 +1,106 @@
+import { Command } from "commander";
+import * as path from "path";
+import * as fs from "fs-extra";
+import chalk from "chalk";
+import { loadRunLogs } from "../../core/run-trend";
+
+export function registerLogs(program: Command): void {
+  program
+    .command("logs")
+    .description("List recent run logs with stage timing")
+    .argument("[runId]", "Show detailed stage breakdown for a specific run ID")
+    .option("--last <n>", "Number of runs to list (default: 10)", "10")
+    .action(async (runId: string | undefined, opts: { last: string }) => {
+      const currentDir = process.cwd();
+      const logDir = path.join(currentDir, ".ai-spec-logs");
+
+      if (!(await fs.pathExists(logDir))) {
+        console.log(chalk.yellow("\n  No run logs found (.ai-spec-logs/ does not exist).\n"));
+        return;
+      }
+
+      if (runId) {
+        // ── Detail view for a single run ──────────────────────────────────────
+        const logPath = path.join(logDir, `${runId}.json`);
+        if (!(await fs.pathExists(logPath))) {
+          console.log(chalk.red(`\n  Run not found: ${runId}\n`));
+          return;
+        }
+        const log = await fs.readJson(logPath);
+
+        console.log(chalk.cyan(`\n─── Run: ${log.runId} ─────────────────────────────────`));
+        console.log(chalk.gray(`  Started : ${log.startedAt}`));
+        if (log.endedAt) console.log(chalk.gray(`  Ended   : ${log.endedAt}`));
+        if (log.totalDurationMs !== undefined)
+          console.log(chalk.gray(`  Duration: ${(log.totalDurationMs / 1000).toFixed(1)}s`));
+        if (log.provider) console.log(chalk.gray(`  Provider: ${log.provider} / ${log.model ?? "?"}`));
+        if (log.promptHash) console.log(chalk.gray(`  Prompt  : ${log.promptHash}`));
+        if (log.harnessScore !== undefined)
+          console.log(chalk.white(`  Score   : ${log.harnessScore}/10`));
+        if (log.filesWritten?.length)
+          console.log(chalk.gray(`  Files   : ${log.filesWritten.length} written`));
+        if (log.errors?.length)
+          console.log(chalk.yellow(`  Errors  : ${log.errors.length}`));
+
+        if (log.entries?.length) {
+          console.log(chalk.bold("\n  Stages:\n"));
+          const doneEvents = (log.entries as Array<{ event: string; data?: Record<string, unknown>; ts: string }>)
+            .filter((e) => e.event.endsWith(":done") || e.event.endsWith(":failed"));
+
+          for (const entry of doneEvents) {
+            const isOk  = entry.event.endsWith(":done");
+            const stage = entry.event.replace(/:done$|:failed$/, "");
+            const dur   = entry.data?.durationMs
+              ? chalk.gray(` ${(Number(entry.data.durationMs) / 1000).toFixed(1)}s`)
+              : "";
+            const mark  = isOk ? chalk.green("✔") : chalk.red("✘");
+            console.log(`    ${mark}  ${stage.padEnd(20)}${dur}`);
+          }
+        }
+        console.log(chalk.cyan("─".repeat(52)));
+        return;
+      }
+
+      // ── List view ─────────────────────────────────────────────────────────────
+      const logs = await loadRunLogs(currentDir);
+      const last  = parseInt(opts.last, 10) || 10;
+      const shown = logs.slice(0, last);
+
+      if (shown.length === 0) {
+        console.log(chalk.yellow("\n  No run logs found.\n"));
+        return;
+      }
+
+      console.log(chalk.cyan("\n─── Run Logs ────────────────────────────────────────────────"));
+      console.log(chalk.gray(
+        "\n  " +
+        "Run ID                  ".padEnd(26) +
+        "Date      " +
+        "Score ".padStart(6) +
+        "  Files  Dur\n"
+      ));
+
+      for (const log of shown) {
+        const date  = log.startedAt.slice(0, 10);
+        const score = log.harnessScore !== undefined
+          ? (log.harnessScore >= 8 ? chalk.green : log.harnessScore >= 6 ? chalk.yellow : chalk.red)(
+              log.harnessScore.toFixed(1).padStart(5)
+            )
+          : chalk.gray("    —");
+        const files = String(log.filesWritten?.length ?? 0).padStart(5);
+        const dur   = log.totalDurationMs !== undefined
+          ? chalk.gray((log.totalDurationMs / 1000).toFixed(0) + "s")
+          : chalk.gray("—");
+        const errMark = (log.errors?.length ?? 0) > 0
+          ? chalk.yellow(` ⚠${log.errors.length}`)
+          : "";
+
+        console.log(`  ${chalk.white(log.runId.padEnd(25))} ${chalk.gray(date)} ${score}  ${chalk.gray(files)}  ${dur}${errMark}`);
+      }
+
+      console.log(chalk.gray(`\n  Showing ${shown.length} of ${logs.length} run(s)  ·  logs: .ai-spec-logs/`));
+      console.log(chalk.cyan("─".repeat(63)));
+      console.log(chalk.gray(`  Tip: ai-spec logs <runId>   to see stage breakdown`));
+      console.log(chalk.gray(`       ai-spec trend          to see score trend by prompt version\n`));
+    });
+}

package/cli/commands/mock.ts

@@ -0,0 +1,175 @@
+import { Command } from "commander";
+import * as path from "path";
+import * as fs from "fs-extra";
+import chalk from "chalk";
+import {
+  WorkspaceLoader,
+  WORKSPACE_CONFIG_FILE,
+} from "../../core/workspace-loader";
+import { SpecDSL } from "../../core/dsl-types";
+import {
+  generateMockAssets,
+  findLatestDslFile,
+  applyMockProxy,
+  restoreMockProxy,
+  startMockServerBackground,
+  saveMockServerPid,
+} from "../../core/mock-server-generator";
+
+export function registerMock(program: Command): void {
+  program
+    .command("mock")
+    .description("Generate a standalone mock server + proxy config from the latest DSL")
+    .option("--port <n>", "Mock server port (default: 3001)", "3001")
+    .option("--msw", "Also generate MSW (Mock Service Worker) handlers at src/mocks/")
+    .option("--proxy", "Also generate frontend proxy config snippet")
+    .option("--dsl <path>", "Path to a specific .dsl.json file (auto-detected if omitted)")
+    .option("--workspace", "Generate mock assets for all backend repos in the workspace")
+    .option("--serve", "Start mock server in background + patch frontend proxy (use with --frontend)")
+    .option("--frontend <path>", "Path to frontend project for proxy patching (used with --serve/--restore)")
+    .option("--restore", "Undo proxy changes and stop mock server (requires --frontend or auto-detects)")
+    .action(async (opts) => {
+      const currentDir = process.cwd();
+      const port = parseInt(opts.port, 10) || 3001;
+
+      console.log(chalk.blue("\n─── ai-spec mock ───────────────────────────────"));
+
+      // ── Restore mode ────────────────────────────────────────────────────────
+      if (opts.restore) {
+        const frontendDir = opts.frontend ? path.resolve(opts.frontend) : currentDir;
+        const r = await restoreMockProxy(frontendDir);
+        if (r.restored) {
+          console.log(chalk.green("  ✔ Proxy restored and mock server stopped."));
+        } else {
+          console.log(chalk.yellow(`  ${r.note ?? "Nothing to restore."}`));
+        }
+        return;
+      }
+
+      // ── Workspace mode ──────────────────────────────────────────────────────
+      if (opts.workspace) {
+        const workspaceLoader = new WorkspaceLoader(currentDir);
+        const workspaceConfig = await workspaceLoader.load();
+        if (!workspaceConfig) {
+          console.error(chalk.red(`  No ${WORKSPACE_CONFIG_FILE} found. Run \`ai-spec workspace init\` first.`));
+          process.exit(1);
+        }
+
+        const backendRepos = workspaceConfig.repos.filter((r) => r.role === "backend");
+        if (backendRepos.length === 0) {
+          console.log(chalk.yellow("  No backend repos found in workspace."));
+          return;
+        }
+
+        for (const repo of backendRepos) {
+          const repoAbsPath = workspaceLoader.resolveAbsPath(repo);
+          console.log(chalk.cyan(`\n  Repo: ${repo.name} (${repoAbsPath})`));
+
+          const dslFile = await findLatestDslFile(repoAbsPath);
+          if (!dslFile) {
+            console.log(chalk.yellow(`    No DSL file found — skipping.`));
+            continue;
+          }
+
+          const dsl: SpecDSL = await fs.readJson(dslFile);
+          const result = await generateMockAssets(dsl, repoAbsPath, {
+            port,
+            msw: opts.msw,
+            proxy: opts.proxy,
+          });
+
+          for (const f of result.files) {
+            console.log(chalk.green(`    ✔ ${f.path}`));
+            console.log(chalk.gray(`      ${f.description}`));
+          }
+        }
+        return;
+      }
+
+      // ── Single-repo mode ────────────────────────────────────────────────────
+      let dslPath: string | null = opts.dsl ?? null;
+
+      if (!dslPath) {
+        dslPath = await findLatestDslFile(currentDir);
+        if (!dslPath) {
+          console.error(
+            chalk.red(
+              "  No .dsl.json file found in .ai-spec/. Run `ai-spec create` first or use --dsl <path>."
+            )
+          );
+          process.exit(1);
+        }
+        console.log(chalk.gray(`  Using DSL: ${path.relative(currentDir, dslPath)}`));
+      }
+
+      let dsl: SpecDSL;
+      try {
+        dsl = await fs.readJson(dslPath);
+      } catch (err) {
+        console.error(chalk.red(`  Failed to read DSL file: ${(err as Error).message}`));
+        process.exit(1);
+      }
+
+      const result = await generateMockAssets(dsl, currentDir, {
+        port,
+        msw: opts.msw,
+        proxy: opts.proxy,
+      });
+
+      console.log(chalk.green(`\n  ✔ Mock assets generated (${result.files.length} file(s)):`));
+      for (const f of result.files) {
+        console.log(chalk.green(`    ${f.path}`));
+        console.log(chalk.gray(`      ${f.description}`));
+      }
+
+      // ── Serve mode: start mock server + patch frontend proxy ────────────────
+      if (opts.serve) {
+        const serverJsPath = path.join(currentDir, "mock", "server.js");
+        if (!(await fs.pathExists(serverJsPath))) {
+          console.error(chalk.red("  mock/server.js not found — generation may have failed."));
+          process.exit(1);
+        }
+
+        const pid = startMockServerBackground(serverJsPath, port);
+        console.log(chalk.green(`\n  ✔ Mock server started (PID ${pid}) → http://localhost:${port}`));
+
+        if (opts.frontend) {
+          const frontendDir = path.resolve(opts.frontend);
+          const proxyResult = await applyMockProxy(frontendDir, port, dsl.endpoints);
+          await saveMockServerPid(frontendDir, pid);
+
+          if (proxyResult.applied) {
+            console.log(chalk.green(`  ✔ Frontend proxy patched (${proxyResult.framework})`));
+            console.log(chalk.bold.cyan(`\n  Ready! Open a new terminal and run:`));
+            console.log(chalk.white(`    cd ${frontendDir}`));
+            console.log(chalk.white(`    ${proxyResult.devCommand}`));
+            console.log(chalk.gray(`\n  When done: ai-spec mock --restore --frontend ${frontendDir}`));
+          } else {
+            console.log(chalk.yellow(`  ⚠ Auto-patch not available for ${proxyResult.framework}.`));
+            if (proxyResult.note) console.log(chalk.gray(`    ${proxyResult.note}`));
+          }
+        } else {
+          console.log(chalk.gray(`  Tip: use --frontend <path> to also auto-patch your frontend proxy config.`));
+          console.log(chalk.gray(`  Mock server: http://localhost:${port}`));
+        }
+        return;
+      }
+
+      console.log(chalk.blue("\n─── Quick start ────────────────────────────────"));
+      console.log(chalk.white(`  1. Install express (if not already):`));
+      console.log(chalk.gray(`       npm install --save-dev express`));
+      console.log(chalk.white(`  2. Start mock server:`));
+      console.log(chalk.gray(`       node mock/server.js`));
+      console.log(chalk.gray(`       # or: ai-spec mock --serve --frontend <path-to-frontend>`));
+      console.log(chalk.white(`  3. Configure your frontend to proxy API calls to:`));
+      console.log(chalk.gray(`       http://localhost:${port}`));
+      if (opts.proxy) {
+        console.log(chalk.gray(`     (See the generated proxy config file for framework-specific instructions)`));
+      }
+      if (opts.msw) {
+        console.log(chalk.white(`  4. MSW: import and start the worker in your app entry:`));
+        console.log(chalk.gray(`       import { worker } from './mocks/browser';`));
+        console.log(chalk.gray(`       if (process.env.NODE_ENV === 'development') worker.start();`));
+      }
+    });
+}