ai-spec-dev 0.17.0 → 0.25.0

package/cli/index.ts

@@ -38,7 +38,7 @@ import { DslExtractor } from "../core/dsl-extractor";
 import { TestGenerator } from "../core/test-generator";
 import { runErrorFeedback } from "../core/error-feedback";
 import { assessSpec, printSpecAssessment } from "../core/spec-assessor";
-import { accumulateReviewKnowledge } from "../core/knowledge-memory";
+import { accumulateReviewKnowledge, appendDirectLesson } from "../core/knowledge-memory";
 import {
   WorkspaceLoader,
   WorkspaceConfig,
@@ -62,7 +62,14 @@ import { buildFrontendApiContract, buildContractContextSection } from "../core/c
 import { loadFrontendContext, buildFrontendContextSection } from "../core/frontend-context-loader";
 import { buildFrontendSpecPrompt, frontendSpecSystemPrompt } from "../prompts/frontend-spec.prompt";
 import { SpecDSL } from "../core/dsl-types";
-import { generateMockAssets, findLatestDslFile } from "../core/mock-server-generator";
+import {
+  generateMockAssets,
+  findLatestDslFile,
+  applyMockProxy,
+  restoreMockProxy,
+  startMockServerBackground,
+  saveMockServerPid,
+} from "../core/mock-server-generator";
 import { SpecUpdater } from "../core/spec-updater";
 import { exportOpenApi } from "../core/openapi-exporter";
 
@@ -74,6 +81,8 @@ interface AiSpecConfig {
   codegen?: CodeGenMode;
   codegenProvider?: string;
   codegenModel?: string;
+  /** Minimum overall spec score (1-10) required to pass Approval Gate. 0 = disabled (default). */
+  minSpecScore?: number;
 }
 
 const CONFIG_FILE = ".ai-spec.json";
@@ -86,22 +95,6 @@ async function loadConfig(dir: string): Promise<AiSpecConfig> {
   return {};
 }
 
-// ─── Constitution Length Warning ──────────────────────────────────────────────
-
-const CONSTITUTION_WARN_CHARS = 6000;
-
-function warnIfConstitutionLong(context: { constitution?: string }): void {
-  if (!context.constitution) return;
-  const len = context.constitution.length;
-  if (len > CONSTITUTION_WARN_CHARS) {
-    console.log(
-      chalk.yellow(
-        `    ⚠ Constitution is long (${len.toLocaleString()} chars). Consider running: ai-spec init --consolidate`
-      )
-    );
-  }
-}
-
 // ─── API Key Resolution ────────────────────────────────────────────────────────
 
 async function resolveApiKey(
@@ -205,6 +198,8 @@ program
   .option("--skip-error-feedback", "Skip error feedback loop (test/lint auto-fix)")
   .option("--tdd", "TDD mode: generate failing tests first, then generate implementation to pass them")
   .option("--skip-assessment", "Skip spec quality pre-assessment before the Approval Gate")
+  .option("--force", "Bypass the spec quality score gate even if score is below minSpecScore")
+  .option("--serve", "After workspace pipeline completes, auto-start mock server + patch frontend proxy")
   .action(async (idea: string | undefined, opts) => {
     const currentDir = process.cwd();
     const config = await loadConfig(currentDir);
@@ -224,7 +219,49 @@ program
     if (workspaceConfig) {
       console.log(chalk.cyan(`\n[Workspace] Detected workspace: ${workspaceConfig.name}`));
       console.log(chalk.gray(`  Repos: ${workspaceConfig.repos.map((r) => r.name).join(", ")}`));
-      await runMultiRepoPipeline(idea!, workspaceConfig, opts, currentDir, config);
+      const pipelineResults = await runMultiRepoPipeline(idea!, workspaceConfig, opts, currentDir, config);
+
+      // ── Auto-serve: start mock server + patch frontend proxy ──────────────
+      if (opts.serve) {
+        console.log(chalk.blue("\n─── Auto-serve: starting mock server ───────────"));
+        const backendResult = pipelineResults.find((r) => r.role === "backend" && r.status === "success" && r.dsl);
+        const frontendResult = pipelineResults.find((r) => (r.role === "frontend" || r.role === "mobile") && r.status === "success");
+
+        if (!backendResult) {
+          console.log(chalk.yellow("  No successful backend with DSL found — skipping auto-serve."));
+        } else {
+          const mockPort = 3001;
+          // Generate mock assets in backend repo
+          const mockResult = await generateMockAssets(backendResult.dsl!, backendResult.repoAbsPath, { port: mockPort });
+          const serverJsPath = path.join(backendResult.repoAbsPath, "mock", "server.js");
+          console.log(chalk.green(`  ✔ Mock assets generated (${mockResult.files.length} file(s))`));
+
+          // Start mock server
+          const pid = startMockServerBackground(serverJsPath, mockPort);
+          console.log(chalk.green(`  ✔ Mock server started (PID ${pid}) → http://localhost:${mockPort}`));
+
+          // Patch frontend proxy
+          if (frontendResult) {
+            const proxyResult = await applyMockProxy(frontendResult.repoAbsPath, mockPort, backendResult.dsl!.endpoints);
+            await saveMockServerPid(frontendResult.repoAbsPath, pid);
+            if (proxyResult.applied) {
+              console.log(chalk.green(`  ✔ Frontend proxy patched (${proxyResult.framework})`));
+              console.log(chalk.bold.cyan(`\n  Ready! Run your frontend dev server:`));
+              console.log(chalk.white(`    cd ${frontendResult.repoAbsPath}`));
+              console.log(chalk.white(`    ${proxyResult.devCommand}`));
+              console.log(chalk.gray(`\n  When done, restore: ai-spec mock --restore --frontend ${frontendResult.repoAbsPath}`));
+            } else {
+              console.log(chalk.yellow(`  ⚠ Auto-patch not available for ${proxyResult.framework}.`));
+              if (proxyResult.note) console.log(chalk.gray(`    ${proxyResult.note}`));
+              console.log(chalk.gray(`    Mock server: http://localhost:${mockPort}`));
+            }
+          } else {
+            console.log(chalk.gray(`  No frontend repo found — mock server is running at http://localhost:${mockPort}`));
+            console.log(chalk.gray(`  Configure your frontend proxy manually to point to http://localhost:${mockPort}`));
+          }
+        }
+      }
+
       return;
     }
 
@@ -263,13 +300,15 @@ program
     const { type: detectedRepoType } = await detectRepoType(currentDir);
     console.log(chalk.gray(`  Tech stack  : ${context.techStack.join(", ") || "unknown"} [${detectedRepoType}]`));
     console.log(chalk.gray(`  Dependencies: ${context.dependencies.length} packages`));
-    warnIfConstitutionLong(context);
     console.log(chalk.gray(`  API files   : ${context.apiStructure.length} files`));
     if (context.schema) {
       console.log(chalk.gray(`  Prisma schema: found`));
     }
     if (context.constitution) {
       console.log(chalk.green(`  Constitution : found (.ai-spec-constitution.md)`));
+      if (context.constitution.length > 6000) {
+        console.log(chalk.yellow(`  ⚠ Constitution is long (${context.constitution.length.toLocaleString()} chars). Consider running: ai-spec init --consolidate`));
+      }
     } else {
       // Auto-run init: generate constitution before proceeding
       console.log(chalk.yellow("  Constitution : not found — auto-generating..."));
@@ -331,13 +370,35 @@ program
     const featureSlug = slugify(idea!);
 
     // ── Step 3.4: Spec Quality Pre-Assessment ────────────────────────────────
-    // Advisory only — never blocks the flow. Skipped in --auto mode and with --skip-assessment.
-    if (!opts.auto && !opts.skipAssessment) {
-      console.log(chalk.blue("\n[3.4/6] Spec quality assessment..."));
+    // Skipped in --skip-assessment mode.
+    // In --auto mode: skipped UNLESS minSpecScore is configured — the hard gate
+    // must still enforce even in CI/auto runs (only the interactive display is skipped).
+    const minScore = config.minSpecScore ?? 0;
+    const shouldRunAssessment = !opts.skipAssessment && (!opts.auto || minScore > 0);
+
+    if (shouldRunAssessment) {
+      if (!opts.auto) {
+        console.log(chalk.blue("\n[3.4/6] Spec quality assessment..."));
+      }
       const assessment = await assessSpec(specProvider, finalSpec, context.constitution ?? undefined);
       if (assessment) {
-        printSpecAssessment(assessment);
-      } else {
+        if (!opts.auto) printSpecAssessment(assessment);
+
+        if (minScore > 0 && assessment.overallScore < minScore) {
+          if (opts.force) {
+            console.log(chalk.yellow(`\n  ⚠ Score gate: ${assessment.overallScore}/10 < minimum ${minScore}/10 — bypassed with --force.`));
+          } else {
+            console.log(chalk.red(`\n  ✘ Spec quality gate failed: overallScore ${assessment.overallScore}/10 < minimum ${minScore}/10`));
+            if (!opts.auto) {
+              console.log(chalk.gray(`  Address the issues above and re-run, or use --force to bypass.`));
+            } else {
+              console.log(chalk.gray(`  Auto mode: gate enforced. Fix the spec or lower minSpecScore, or use --force to bypass.`));
+            }
+            console.log(chalk.gray(`  Gate threshold set in .ai-spec.json → "minSpecScore": ${minScore}`));
+            process.exit(1);
+          }
+        }
+      } else if (!opts.auto) {
         console.log(chalk.gray("  (Assessment skipped — AI call failed or timed out)"));
       }
     }
@@ -792,6 +853,7 @@ program
   )
   .option("--codegen-provider <name>", "Default provider for code generation")
   .option("--codegen-model <name>", "Default model for code generation")
+  .option("--min-spec-score <score>", "Minimum overall spec score (1-10) to pass Approval Gate (0 = disabled)")
   .option("--show", "Print current configuration")
   .option("--reset", "Reset configuration to empty")
   .option("--clear-keys", "Delete all saved API keys from ~/.ai-spec-keys.json")
@@ -853,6 +915,14 @@ program
     if (opts.codegen) updated.codegen = opts.codegen as CodeGenMode;
     if (opts.codegenProvider) updated.codegenProvider = opts.codegenProvider;
     if (opts.codegenModel) updated.codegenModel = opts.codegenModel;
+    if (opts.minSpecScore !== undefined) {
+      const score = parseInt(opts.minSpecScore, 10);
+      if (isNaN(score) || score < 0 || score > 10) {
+        console.error(chalk.red("  --min-spec-score must be a number between 0 and 10"));
+        process.exit(1);
+      }
+      updated.minSpecScore = score;
+    }
 
     await fs.writeJson(configPath, updated, { spaces: 2 });
     console.log(chalk.green(`✔ Config saved to ${configPath}`));
@@ -1055,7 +1125,9 @@ async function runSingleRepoPipelineInWorkspace(opts: {
 
   console.log(chalk.gray(`    Tech stack: ${context.techStack.join(", ") || "unknown"} [${detectedRepoType}]`));
   console.log(chalk.gray(`    Dependencies: ${context.dependencies.length} packages`));
-  warnIfConstitutionLong(context);
+  if (context.constitution && context.constitution.length > 6000) {
+    console.log(chalk.yellow(`    ⚠ Constitution is long (${context.constitution.length.toLocaleString()} chars). Consider running: ai-spec init --consolidate`));
+  }
 
   if (!context.constitution) {
     console.log(chalk.yellow(`    Constitution: not found — auto-generating...`));
@@ -1194,13 +1266,22 @@ async function runSingleRepoPipelineInWorkspace(opts: {
 /**
  * Multi-repo pipeline: decompose → order repos → run each repo in order → bridge contracts.
  */
+type MultiRepoResult = {
+  repoName: string;
+  status: "success" | "failed" | "skipped";
+  specFile: string | null;
+  dsl: SpecDSL | null;
+  repoAbsPath: string;
+  role: string;
+};
+
 async function runMultiRepoPipeline(
   idea: string,
   workspace: WorkspaceConfig,
   opts: Record<string, unknown>,
   currentDir: string,
   config: AiSpecConfig
-): Promise<void> {
+): Promise<MultiRepoResult[]> {
   // ── Resolve providers ──────────────────────────────────────────────────────
   const specProviderName = (opts.provider as string) || config.provider || "gemini";
   const specModelName = (opts.model as string) || config.model || DEFAULT_MODELS[specProviderName];
@@ -1239,7 +1320,6 @@ async function runMultiRepoPipeline(
     try {
       const loader = new ContextLoader(repoAbsPath);
       const ctx = await loader.loadProjectContext();
-      warnIfConstitutionLong(ctx);
       contexts.set(repo.name, ctx);
 
       // Load frontend context for frontend/mobile repos
@@ -1334,19 +1414,14 @@ async function runMultiRepoPipeline(
   // ── Step 5: Run each repo's pipeline ──────────────────────────────────────
   console.log(chalk.blue(`\n[W4] Running pipeline for ${sortedRepoRequirements.length} repo(s)...`));
 
-  const results: Array<{
-    repoName: string;
-    status: "success" | "failed" | "skipped";
-    specFile: string | null;
-    dsl: SpecDSL | null;
-  }> = [];
+  const results: MultiRepoResult[] = [];
 
   for (const repoReq of sortedRepoRequirements) {
     // Find repo config in workspace
     const repoConfig = workspace.repos.find((r) => r.name === repoReq.repoName);
     if (!repoConfig) {
       console.log(chalk.yellow(`  Skipping ${repoReq.repoName} — not found in workspace config.`));
-      results.push({ repoName: repoReq.repoName, status: "skipped", specFile: null, dsl: null });
+      results.push({ repoName: repoReq.repoName, status: "skipped", specFile: null, dsl: null, repoAbsPath: "", role: repoReq.role });
       continue;
     }
 
@@ -1413,11 +1488,11 @@ async function runMultiRepoPipeline(
         console.log(chalk.green(`    Contract stored for downstream repos.`));
       }
 
-      results.push({ repoName: repoReq.repoName, status: "success", specFile, dsl });
+      results.push({ repoName: repoReq.repoName, status: "success", specFile, dsl, repoAbsPath, role: repoReq.role });
       console.log(chalk.green(`  ✔ ${repoReq.repoName} complete`));
     } catch (err) {
       console.error(chalk.red(`  ✘ ${repoReq.repoName} failed: ${(err as Error).message}`));
-      results.push({ repoName: repoReq.repoName, status: "failed", specFile: null, dsl: null });
+      results.push({ repoName: repoReq.repoName, status: "failed", specFile: null, dsl: null, repoAbsPath, role: repoReq.role });
       // Continue — don't abort other repos
     }
   }
@@ -1432,6 +1507,8 @@ async function runMultiRepoPipeline(
     const specInfo = r.specFile ? chalk.gray(` → ${r.specFile}`) : "";
     console.log(`  ${icon} ${r.repoName} (${r.status})${specInfo}`);
   }
+
+  return results;
 }
 
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -1703,7 +1780,9 @@ program
     console.log(chalk.gray("  Loading project context..."));
     const loader = new ContextLoader(currentDir);
     const context = await loader.loadProjectContext();
-    warnIfConstitutionLong(context);
+    if (context.constitution && context.constitution.length > 6000) {
+      console.log(chalk.yellow(`  ⚠ Constitution is long (${context.constitution.length.toLocaleString()} chars). Consider running: ai-spec init --consolidate`));
+    }
 
     // ── Detect repo type ──────────────────────────────────────────────────────
     const { detectRepoType: _detectRepoType } = await import("../core/workspace-loader");
@@ -1866,16 +1945,28 @@ program
   .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("--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);
@@ -1952,11 +2043,47 @@ program
       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);
+      }
+
+      // Start mock server in background
+      const pid = startMockServerBackground(serverJsPath, port);
+      console.log(chalk.green(`\n  ✔ Mock server started (PID ${pid}) → http://localhost:${port}`));
+
+      // Apply frontend proxy patch
+      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) {
@@ -1969,6 +2096,37 @@ program
     }
   });
 
+// ═══════════════════════════════════════════════════════════════════════════════
+// Command: learn  —  zero-friction knowledge injection into constitution §9
+// ═══════════════════════════════════════════════════════════════════════════════
+
+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) {
+      const { default: inquirerInput } = await import("@inquirer/prompts").then(
+        (m) => ({ default: m.input })
+      );
+      lesson = await inquirerInput({
+        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}`));
+    }
+  });
+
 // Show welcome screen when invoked with no arguments
 if (process.argv.length <= 2) {
   (async () => {