ai-spec-dev 0.33.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/init.ts

@@ -16,6 +16,7 @@ import {
   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
@@ -78,16 +79,52 @@ export function registerInit(program: Command): void {
 
         console.log(chalk.blue("\n─── Generating Global Constitution ──────────────"));
         console.log(chalk.gray(`  Provider: ${providerName}/${modelName}`));
-        console.log(chalk.gray("  Scanning repos in workspace..."));
 
-        const loader = new ContextLoader(currentDir);
-        const ctx = await loader.loadProjectContext();
-        const summary = [
-          `Tech stack: ${ctx.techStack.join(", ") || "unknown"}`,
-          `Dependencies: ${ctx.dependencies.slice(0, 20).join(", ")}`,
-        ].join("\n");
+        // ── 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"),
+          });
+        }
 
-        const prompt = buildGlobalConstitutionPrompt([{ name: path.basename(currentDir), summary }]);
+        console.log(chalk.gray(`  Generating from ${projectSummaries.length} project(s)...`));
+        const prompt = buildGlobalConstitutionPrompt(projectSummaries);
         let globalConstitution: string;
         try {
           globalConstitution = await provider.generate(prompt, globalConstitutionSystemPrompt);

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();`));
+      }
+    });
+}

package/cli/commands/scan.ts

@@ -0,0 +1,99 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import * as path from "path";
+import { runScan, saveIndex, loadIndex, INDEX_FILE, ProjectEntry } from "../../core/project-index";
+
+const ROLE_COLOR: Record<string, (s: string) => string> = {
+  backend:  chalk.blue,
+  frontend: chalk.green,
+  mobile:   chalk.magenta,
+  shared:   chalk.gray,
+};
+
+function formatEntry(entry: ProjectEntry): string {
+  const roleColor = ROLE_COLOR[entry.role] ?? chalk.white;
+  const role = roleColor(entry.role.padEnd(8));
+  const type = chalk.gray(entry.type.padEnd(14));
+  const name = (entry.missing ? chalk.strikethrough.gray : chalk.white)(entry.path.padEnd(30));
+  const badges: string[] = [];
+  if (entry.hasConstitution) badges.push(chalk.cyan("§C"));
+  if (entry.hasWorkspace)    badges.push(chalk.yellow("W"));
+  if (entry.missing)         badges.push(chalk.red("missing"));
+  const stack = chalk.gray(entry.techStack.slice(0, 5).join(", "));
+  return `  ${name} ${role} ${type} ${badges.join(" ")}  ${stack}`;
+}
+
+export function registerScan(program: Command): void {
+  program
+    .command("scan")
+    .description("Discover and index all projects under the current directory")
+    .option("-d, --depth <n>", "Max directory depth to search", "2")
+    .option("--list", "Just print the current index without rescanning")
+    .action(async (opts) => {
+      const cwd = process.cwd();
+
+      // ── List mode ─────────────────────────────────────────────────────────
+      if (opts.list) {
+        const existing = await loadIndex(cwd);
+        if (!existing || existing.projects.length === 0) {
+          console.log(chalk.gray("No index found. Run: ai-spec scan"));
+          return;
+        }
+
+        console.log(chalk.cyan(`\n─── Project Index (${existing.projects.length} projects) ─────────────────────────────`));
+        console.log(chalk.gray(`  Last scanned : ${existing.lastScanned.slice(0, 19).replace("T", " ")}`));
+        console.log(chalk.gray(`  Root         : ${existing.scanRoot}\n`));
+
+        const active = existing.projects.filter((p) => !p.missing);
+        const missing = existing.projects.filter((p) => p.missing);
+
+        for (const entry of active) {
+          console.log(formatEntry(entry));
+        }
+        if (missing.length > 0) {
+          console.log(chalk.gray(`\n  (${missing.length} previously seen, now missing)`));
+          for (const entry of missing) {
+            console.log(formatEntry(entry));
+          }
+        }
+
+        console.log(chalk.cyan("\n─".repeat(52)));
+        console.log(chalk.gray("  §C = has constitution  W = workspace root"));
+        console.log(chalk.gray(`  Index file: ${INDEX_FILE}`));
+        return;
+      }
+
+      // ── Scan mode ─────────────────────────────────────────────────────────
+      const maxDepth = parseInt(opts.depth, 10);
+      console.log(chalk.blue(`\nScanning ${cwd} (depth: ${maxDepth})...`));
+
+      const { index, added, updated, unchanged, nowMissing } = await runScan(cwd, maxDepth);
+      await saveIndex(cwd, index);
+
+      const active = index.projects.filter((p) => !p.missing);
+
+      // ── Summary ───────────────────────────────────────────────────────────
+      console.log(chalk.cyan(`\n─── Scan Results ────────────────────────────────────`));
+      if (added.length > 0)       console.log(chalk.green(`  + ${added.length} new project(s) added`));
+      if (updated.length > 0)     console.log(chalk.yellow(`  ~ ${updated.length} project(s) updated`));
+      if (unchanged.length > 0)   console.log(chalk.gray(`  · ${unchanged.length} project(s) unchanged`));
+      if (nowMissing.length > 0)  console.log(chalk.red(`  ✘ ${nowMissing.length} project(s) no longer found (marked missing)`));
+
+      if (added.length === 0 && updated.length === 0 && nowMissing.length === 0) {
+        console.log(chalk.gray("  Nothing changed."));
+      }
+
+      // ── Full listing ──────────────────────────────────────────────────────
+      if (active.length > 0) {
+        console.log(chalk.cyan(`\n  Projects (${active.length}):`));
+        for (const entry of active) {
+          console.log(formatEntry(entry));
+        }
+      }
+
+      console.log(chalk.cyan("\n─".repeat(52)));
+      console.log(chalk.gray("  §C = has constitution  W = workspace root"));
+      console.log(chalk.gray(`  Index saved : ${path.relative(cwd, path.join(cwd, INDEX_FILE))}`));
+      console.log(chalk.gray(`  Next steps  : ai-spec scan --list | ai-spec init [--global]`));
+    });
+}

package/cli/commands/types.ts

@@ -0,0 +1,69 @@
+import { Command } from "commander";
+import * as path from "path";
+import * as fs from "fs-extra";
+import chalk from "chalk";
+import { findLatestDslFile } from "../../core/mock-server-generator";
+import { SpecDSL } from "../../core/dsl-types";
+import { saveTypescriptTypes, generateTypescriptTypes } from "../../core/types-generator";
+
+export function registerTypes(program: Command): void {
+  program
+    .command("types")
+    .description("Generate TypeScript types from the latest DSL (models + endpoint request types)")
+    .option("--dsl <path>", "Path to a specific .dsl.json file (auto-detected if omitted)")
+    .option("--output <path>", "Output file path (default: .ai-spec/<feature>.types.ts)")
+    .option("--stdout", "Print generated types to stdout instead of writing a file")
+    .option("--no-endpoint-types", "Skip endpoint request/response type generation")
+    .option("--no-endpoint-map", "Skip the API_ENDPOINTS constant map")
+    .action(async (opts) => {
+      const currentDir = process.cwd();
+
+      // ── Resolve 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);
+        }
+      }
+
+      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);
+      }
+
+      const genOpts = {
+        includeEndpointTypes: opts.endpointTypes !== false,
+        includeEndpointMap: opts.endpointMap !== false,
+        outputPath: opts.output,
+      };
+
+      // ── Stdout mode ──────────────────────────────────────────────────────────
+      if (opts.stdout) {
+        const content = generateTypescriptTypes(dsl, genOpts);
+        process.stdout.write(content);
+        return;
+      }
+
+      // ── File mode ────────────────────────────────────────────────────────────
+      const outputPath = await saveTypescriptTypes(dsl, currentDir, genOpts);
+      const relPath = path.relative(currentDir, outputPath);
+
+      console.log(chalk.green(`\n  ✔ TypeScript types generated: ${relPath}`));
+      console.log(chalk.gray(`  Feature  : ${dsl.feature.title}`));
+      console.log(chalk.gray(`  Models   : ${dsl.models.length}`));
+      console.log(chalk.gray(`  Endpoints: ${dsl.endpoints.length}`));
+      if (dsl.components?.length) {
+        console.log(chalk.gray(`  Components: ${dsl.components.length}`));
+      }
+      console.log(chalk.blue(`\n  Usage:`));
+      console.log(chalk.gray(`    import type { ${dsl.models.slice(0, 3).map((m) => m.name).join(", ")}${dsl.models.length > 3 ? ", ..." : ""} } from './${relPath}';`));
+      console.log(chalk.gray(`    import { API_ENDPOINTS } from './${relPath}';\n`));
+    });
+}

package/cli/commands/vcr.ts

@@ -0,0 +1,70 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { listVcrRecordings, loadVcrRecording } from "../../core/vcr";
+
+export function registerVcr(program: Command): void {
+  const vcr = program
+    .command("vcr")
+    .description("Manage VCR recordings for offline pipeline replay");
+
+  // ── ai-spec vcr list ──────────────────────────────────────────────────────
+  vcr
+    .command("list")
+    .description("List available VCR recordings in .ai-spec-vcr/")
+    .action(async () => {
+      const cwd = process.cwd();
+      const recordings = await listVcrRecordings(cwd);
+
+      if (recordings.length === 0) {
+        console.log(chalk.gray("No VCR recordings found."));
+        console.log(chalk.gray("Record a run with: ai-spec create --vcr-record <idea>"));
+        return;
+      }
+
+      console.log(chalk.cyan("\n─── VCR Recordings ─────────────────────────────"));
+      for (const r of recordings) {
+        console.log(
+          "  " + chalk.white(r.runId) +
+          chalk.gray(` · ${r.entryCount} AI calls · ${r.providers.join(", ")}`) +
+          chalk.gray(` · ${r.recordedAt.slice(0, 10)}`)
+        );
+      }
+      console.log(chalk.cyan("─".repeat(49)));
+      console.log(chalk.gray("\nInspect : ai-spec vcr show <runId>"));
+      console.log(chalk.gray("Replay  : ai-spec create --vcr-replay <runId> <idea>"));
+    });
+
+  // ── ai-spec vcr show <runId> ──────────────────────────────────────────────
+  vcr
+    .command("show <runId>")
+    .description("Show call-by-call details of a VCR recording")
+    .action(async (runId: string) => {
+      const cwd = process.cwd();
+      const recording = await loadVcrRecording(cwd, runId);
+
+      if (!recording) {
+        console.log(chalk.red(`Recording not found: ${runId}`));
+        console.log(chalk.gray(`Expected: .ai-spec-vcr/${runId}.json`));
+        process.exit(1);
+      }
+
+      console.log(chalk.cyan(`\n─── VCR: ${recording.runId} ──────────────────────────`));
+      console.log(chalk.gray(`  Recorded at : ${recording.recordedAt}`));
+      console.log(chalk.gray(`  Providers   : ${recording.providers.join(", ")}`));
+      console.log(chalk.gray(`  Total calls : ${recording.entryCount}`));
+      console.log(chalk.cyan("\n  Calls:"));
+
+      for (const entry of recording.entries) {
+        const idx = String(entry.index).padStart(2, "0");
+        const preview = entry.promptPreview.slice(0, 90).replace(/\s+/g, " ");
+        console.log(
+          chalk.gray(`    [${idx}]`) + " " +
+          chalk.white(`${entry.providerName}/${entry.modelName}`) +
+          chalk.gray(` ${entry.durationMs}ms hash:${entry.callHash}`)
+        );
+        console.log(chalk.gray(`         "${preview}..."`));
+      }
+
+      console.log(chalk.cyan("─".repeat(49)));
+    });
+}