ai-spec-dev 0.38.0 → 0.42.0

package/cli/utils.ts

@@ -20,6 +20,8 @@ export interface AiSpecConfig {
   minHarnessScore?: number;
   /** Maximum error-feedback cycles before giving up (default: 2, TDD default: 3). */
   maxErrorCycles?: number;
+  /** §9 lesson count threshold for auto-consolidation (default: 12). */
+  autoConsolidateThreshold?: number;
 }
 
 export const CONFIG_FILE = ".ai-spec.json";

package/core/cli-ui.ts

@@ -0,0 +1,136 @@
+import chalk from "chalk";
+
+// ─── Spinner ──────────────────────────────────────────────────────────────────
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+export interface Spinner {
+  /** Update the text shown after the spinner. */
+  update(text: string): void;
+  /** Stop the spinner and show a final message. */
+  stop(finalText?: string): void;
+  /** Stop with a success (✔) mark. */
+  succeed(text: string): void;
+  /** Stop with a failure (✘) mark. */
+  fail(text: string): void;
+}
+
+/**
+ * Start a CLI spinner that renders on a single line.
+ * Works in any TTY; silently degrades to static text in non-TTY (CI).
+ */
+export function startSpinner(text: string): Spinner {
+  const isTTY = process.stderr.isTTY;
+  let frame = 0;
+  let currentText = text;
+  let stopped = false;
+
+  function render() {
+    if (stopped) return;
+    const symbol = chalk.cyan(SPINNER_FRAMES[frame % SPINNER_FRAMES.length]);
+    if (isTTY) {
+      process.stderr.write(`\r  ${symbol} ${currentText}${" ".repeat(10)}`);
+    }
+    frame++;
+  }
+
+  // Print initial line for non-TTY
+  if (!isTTY) {
+    process.stderr.write(`  … ${currentText}\n`);
+  }
+
+  const timer = setInterval(render, 80);
+  render();
+
+  return {
+    update(newText: string) {
+      currentText = newText;
+    },
+    stop(finalText?: string) {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      if (isTTY) {
+        process.stderr.write(`\r${" ".repeat(currentText.length + 20)}\r`);
+      }
+      if (finalText) {
+        process.stderr.write(`  ${finalText}\n`);
+      }
+    },
+    succeed(successText: string) {
+      this.stop(chalk.green(`✔ ${successText}`));
+    },
+    fail(failText: string) {
+      this.stop(chalk.red(`✘ ${failText}`));
+    },
+  };
+}
+
+// ─── Retry Countdown ──────────────────────────────────────────────────────────
+
+/**
+ * Show an animated countdown during retry wait.
+ * Displays error details + a live seconds countdown.
+ */
+export async function retryCountdown(opts: {
+  attempt: number;
+  maxAttempts: number;
+  waitMs: number;
+  errorMessage: string;
+  label: string;
+}): Promise<void> {
+  const { attempt, maxAttempts, waitMs, errorMessage, label } = opts;
+  const isTTY = process.stderr.isTTY;
+
+  // Error box
+  const shortErr = errorMessage.length > 120
+    ? errorMessage.slice(0, 117) + "..."
+    : errorMessage;
+
+  process.stderr.write("\n");
+  process.stderr.write(chalk.yellow(`  ┌─ Retry ${attempt}/${maxAttempts} `) + chalk.gray(`[${label}]`) + chalk.yellow(` ${"─".repeat(Math.max(1, 40 - label.length))}\n`));
+  process.stderr.write(chalk.yellow(`  │ `) + chalk.white(shortErr) + "\n");
+  process.stderr.write(chalk.yellow(`  │ `) + chalk.gray(`Waiting before retry...`) + "\n");
+
+  // Animated countdown
+  const totalSeconds = Math.ceil(waitMs / 1000);
+  for (let s = totalSeconds; s > 0; s--) {
+    const bar = chalk.green("█".repeat(totalSeconds - s)) + chalk.gray("░".repeat(s));
+    const line = chalk.yellow(`  │ `) + `${bar} ${chalk.bold.white(`${s}s`)}`;
+    if (isTTY) {
+      process.stderr.write(`\r${line}${" ".repeat(10)}`);
+    }
+    await new Promise<void>((r) => setTimeout(r, 1000));
+  }
+
+  if (isTTY) {
+    process.stderr.write(`\r${" ".repeat(70)}\r`);
+  }
+  process.stderr.write(chalk.yellow(`  └─ `) + chalk.cyan(`Retrying now...`) + "\n\n");
+}
+
+// ─── Stage Progress ───────────────────────────────────────────────────────────
+
+const STAGE_ICONS: Record<string, string> = {
+  context_load: "📂",
+  design_dialogue: "💬",
+  spec_gen: "📝",
+  spec_refine: "✏️ ",
+  spec_assess: "📊",
+  dsl_extract: "🔗",
+  dsl_gap_feedback: "🔍",
+  codegen: "⚙️ ",
+  test_gen: "🧪",
+  error_feedback: "🔧",
+  review: "🔎",
+  self_eval: "📈",
+};
+
+/**
+ * Start a pipeline stage with a spinner.
+ * Returns a handle to succeed/fail/update the stage display.
+ */
+export function startStage(stageKey: string, label: string): Spinner {
+  const icon = STAGE_ICONS[stageKey] ?? "▸";
+  return startSpinner(`${icon}  ${label}`);
+}

package/core/code-generator.ts

@@ -10,242 +10,26 @@ import { loadDslForSpec, buildDslContextSection } from "./dsl-extractor";
 import { loadFrontendContext, buildFrontendContextSection } from "./frontend-context-loader";
 import { getActiveSnapshot } from "./run-snapshot";
 import { getActiveLogger } from "./run-logger";
-
-// ─── Shared Config Helper ───────────────────────────────────────────────────
-
-function buildSharedConfigSection(context?: ProjectContext): string {
-  if (!context?.sharedConfigFiles || context.sharedConfigFiles.length === 0) return "";
-
-  const lines: string[] = [
-    "\n=== Existing Shared Config Files (study these to learn project conventions) ===",
-    "These are real files from the project. Use them as ground truth for naming, structure, and registration patterns.",
-    "Modify them in-place when adding new entries. Do NOT create parallel files for the same purpose.\n",
-  ];
-
-  for (const f of context.sharedConfigFiles) {
-    lines.push(`--- File: ${f.path}  [${f.category}] ---`);
-    lines.push(f.preview);
-    lines.push("");
-  }
-  return lines.join("\n") + "\n";
-}
-
-function buildInstalledPackagesSection(context?: ProjectContext): string {
-  if (!context?.dependencies || context.dependencies.length === 0) return "";
-  return `\n=== Installed Packages (ONLY use packages from this list — NEVER import anything not listed here) ===\n${context.dependencies.join(", ")}\n`;
-}
-
-/**
- * Extract a behavioral contract summary from a generated file.
- *
- * Captures:
- * - export interface / type / enum — full multi-line blocks (the actual TS contracts)
- * - export function / const / class — opening signature line
- * - Throw statements — error codes & validation constraints
- *
- * Multi-line blocks (interface, type alias with {}) are captured in full so
- * downstream tasks see complete method signatures and field shapes, not just
- * a single-line "export interface Foo {" that conveys nothing.
- *
- * Falls back to first 3000 chars for CommonJS files with no explicit exports.
- */
-export function extractBehavioralContract(content: string): string {
-  const lines = content.split("\n");
-  const contractLines: string[] = [];
-  const throwLines: string[] = [];
-  let i = 0;
-
-  while (i < lines.length) {
-    const line = lines[i];
-    const trimmed = line.trim();
-
-    // ── Multi-line block exports: interface / type X = { / class / enum ──────
-    // Capture the full block so downstream tasks see the complete contract.
-    if (/^export\s+(interface|type|class|abstract\s+class|enum)\s/.test(trimmed)) {
-      contractLines.push(line.trimEnd());
-      if (trimmed.includes("{")) {
-        let depth =
-          (trimmed.match(/\{/g) ?? []).length -
-          (trimmed.match(/\}/g) ?? []).length;
-        i++;
-        while (i < lines.length && depth > 0) {
-          const inner = lines[i];
-          contractLines.push(inner.trimEnd());
-          depth += (inner.match(/\{/g) ?? []).length;
-          depth -= (inner.match(/\}/g) ?? []).length;
-          i++;
-        }
-      } else {
-        i++;
-      }
-      continue;
-    }
-
-    // ── export const X = defineStore(...) — capture full block ───────────────
-    // Pinia stores wrap all actions inside defineStore(). Without the full block
-    // the consumer only sees "export const useTaskStore = defineStore(" and has
-    // to guess every action name — the primary source of fetchTasks→fetchTaskList
-    // hallucinations. Capture the complete defineStore(...) call so the return
-    // object (public API) is visible.
-    if (/^export\s+const\s+\w+\s*=\s*(defineStore|createStore|createSlice)\s*\(/.test(trimmed)) {
-      contractLines.push(line.trimEnd());
-      let depth = (trimmed.match(/\(/g) ?? []).length - (trimmed.match(/\)/g) ?? []).length;
-      i++;
-      while (i < lines.length && depth > 0) {
-        const inner = lines[i];
-        contractLines.push(inner.trimEnd());
-        depth += (inner.match(/\(/g) ?? []).length;
-        depth -= (inner.match(/\)/g) ?? []).length;
-        i++;
-      }
-      continue;
-    }
-
-    // ── return { ... } — composable/store public API surface ─────────────────
-    // In Pinia composition-API stores and Vue composables the return object is
-    // the definitive list of exposed names. Capture it so consumers see the
-    // exact exported identifiers (e.g. "fetchTasks" not "fetchTaskList").
-    if (/^return\s*\{/.test(trimmed)) {
-      contractLines.push("// public API (return object):");
-      contractLines.push(line.trimEnd());
-      let depth = (trimmed.match(/\{/g) ?? []).length - (trimmed.match(/\}/g) ?? []).length;
-      i++;
-      while (i < lines.length && depth > 0) {
-        const inner = lines[i];
-        contractLines.push(inner.trimEnd());
-        depth += (inner.match(/\{/g) ?? []).length;
-        depth -= (inner.match(/\}/g) ?? []).length;
-        i++;
-      }
-      continue;
-    }
-
-    // ── export default function/class — capture full block ───────────────────
-    // Needed for React components (export default function Foo()) and Vue
-    // composables (export default class Foo {}). Without full-block capture the
-    // consumer only sees the opening line and can't know the return shape.
-    if (/^export\s+default\s+(async\s+)?(function|class)\b/.test(trimmed)) {
-      contractLines.push(line.trimEnd());
-      if (trimmed.includes("{")) {
-        let depth =
-          (trimmed.match(/\{/g) ?? []).length -
-          (trimmed.match(/\}/g) ?? []).length;
-        i++;
-        while (i < lines.length && depth > 0) {
-          const inner = lines[i];
-          contractLines.push(inner.trimEnd());
-          depth += (inner.match(/\{/g) ?? []).length;
-          depth -= (inner.match(/\}/g) ?? []).length;
-          i++;
-        }
-      } else {
-        i++;
-      }
-      continue;
-    }
-
-    // ── Single-line export declarations (functions, consts, re-exports) ───────
-    if (/^export\s/.test(trimmed)) {
-      contractLines.push(line.trimEnd());
-    }
-
-    // ── Throw patterns — validation constraints and named error codes ─────────
-    if (
-      /throw\s+(new\s+)?\w*[Ee]rror\b|throw\s+create[A-Z]\w*|@throws/.test(line) &&
-      throwLines.length < 20
-    ) {
-      throwLines.push("  // " + trimmed);
-    }
-
-    i++;
-  }
-
-  if (contractLines.length === 0 && throwLines.length === 0) {
-    return content.slice(0, 3000);
-  }
-
-  const parts: string[] = [...contractLines];
-  if (throwLines.length > 0) {
-    parts.push("", "// Error contracts (throws / validation):", ...throwLines);
-  }
-  return parts.join("\n");
-}
-
-/**
- * Build a context section from files already written in this generation run.
- * Injected before generating files that may import from those paths (e.g., route files
- * importing from API files generated in an earlier task).
- */
-function buildGeneratedFilesSection(cache: Map<string, string>): string {
-  if (cache.size === 0) return "";
-  const lines = [
-    "\n=== Files Already Generated in This Run — USE EXACT EXPORTS (do not rename or invent alternatives) ===",
-    "// CRITICAL: function/action names and file paths below are ground truth. Copy them EXACTLY.",
-    "// Do NOT add suffixes (List, Data, All, Info) or change casing.",
-    "// For '// exists:' entries: use the EXACT filename shown — do NOT substitute index.vue or other defaults.",
-  ];
-  for (const [filePath, content] of cache) {
-    // View/page components: only show the path as a name sentinel.
-    // The router needs to know the exact filename (e.g. TaskManagement.vue, NOT index.vue).
-    const isViewFile = /src[\\/](views?|pages?)[\\/]/i.test(filePath);
-    if (isViewFile) {
-      lines.push(`\n// exists: ${filePath}`);
-      continue;
-    }
-    lines.push(`\n--- ${filePath} ---`);
-    // Store and composable files: pass full content — the entire file IS the contract
-    const isStoreOrComposable = /src[\\/](stores?|composables?)[\\/]/i.test(filePath);
-    lines.push(isStoreOrComposable ? content : extractBehavioralContract(content));
-  }
-  return lines.join("\n") + "\n";
-}
+import {
+  buildSharedConfigSection,
+  buildInstalledPackagesSection,
+  buildGeneratedFilesSection,
+  extractBehavioralContract,
+  stripCodeFences,
+  parseJsonArray,
+  isRtkAvailable,
+  FileAction,
+} from "./codegen/helpers";
+import { topoSortLayerTasks, printTaskProgress, LAYER_ICONS } from "./codegen/topo-sort";
+import { estimateTokens, getDefaultBudget } from "./token-budget";
+import { startSpinner } from "./cli-ui";
+
+// Re-export public symbols for backward compatibility
+export { extractBehavioralContract } from "./codegen/helpers";
+export { printTaskProgress } from "./codegen/topo-sort";
 
 export type CodeGenMode = "claude-code" | "api" | "plan";
 
-// ─── RTK Helper ────────────────────────────────────────────────────────────────
-// RTK (Rust Token Killer) saves tokens by filtering verbose CLI output.
-// When available, prefix 'claude' with 'rtk' for token savings.
-
-function isRtkAvailable(): boolean {
-  try {
-    execSync("rtk --version", { stdio: "ignore" });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-interface FileAction {
-  file: string;
-  action: "create" | "modify";
-  description: string;
-}
-
-// ─── Helpers ───────────────────────────────────────────────────────────────────
-
-function stripCodeFences(output: string): string {
-  // Remove ```lang ... ``` wrapping if present
-  const fenced = output.match(/^```(?:\w+)?\n([\s\S]*?)```\s*$/m);
-  if (fenced) return fenced[1].trim();
-  const lines = output.split("\n");
-  if (lines[0].startsWith("```")) lines.shift();
-  if (lines[lines.length - 1].trim() === "```") lines.pop();
-  return lines.join("\n").trim();
-}
-
-function parseJsonArray(text: string): FileAction[] {
-  // Try a JSON code fence first
-  const fenced = text.match(/```(?:json)?\n(\[[\s\S]*?\])\n```/);
-  const raw = fenced ? fenced[1] : text.match(/\[[\s\S]*?\]/)?.[0] ?? "";
-  try {
-    const parsed = JSON.parse(raw);
-    if (Array.isArray(parsed)) return parsed as FileAction[];
-  } catch {
-    // fall through
-  }
-  return [];
-}
-
 // ─── CodeGenerator ────────────────────────────────────────────────────────────
 
 export interface CodeGenOptions {
@@ -301,7 +85,7 @@ export class CodeGenerator {
 
   private isClaudeCLIAvailable(): boolean {
     try {
-      execSync("claude --version", { stdio: "ignore" });
+      execSync("claude --version", { stdio: "ignore", timeout: 10_000 });
       return true;
     } catch {
       return false;
@@ -457,7 +241,7 @@ export class CodeGenerator {
     }
 
     const spec = await fs.readFile(specFilePath, "utf-8");
-    const constitutionSection = context?.constitution
+    let constitutionSection = context?.constitution
       ? `\n=== Project Constitution (MUST follow) ===\n${context.constitution}\n`
       : "";
     const contextSummary = context
@@ -484,6 +268,27 @@ export class CodeGenerator {
       console.log(chalk.gray(`  Frontend context: ${fctx.framework} / ${fctx.httpClient} | hooks:${fctx.hookFiles.length} stores:${fctx.storeFiles.length}`));
     }
 
+    // Token budget check — warn if context sections are large
+    const allContextText = spec + constitutionSection + dslSection + frontendSection + installedPackagesSection + sharedConfigSection;
+    const estimatedTokenCount = estimateTokens(allContextText);
+    const budget = getDefaultBudget(this.provider.providerName);
+    if (estimatedTokenCount > budget * 0.7) {
+      console.log(
+        chalk.yellow(
+          `  ⚠ Context size: ~${Math.round(estimatedTokenCount / 1000)}K tokens (budget: ${Math.round(budget / 1000)}K for ${this.provider.providerName})`
+        )
+      );
+      // Trim constitution §9 if it's the largest contributor
+      if (constitutionSection.length > 4000) {
+        const s9Start = constitutionSection.indexOf("## 9.");
+        if (s9Start > 0) {
+          constitutionSection = constitutionSection.slice(0, s9Start) +
+            "## 9. 积累教训 (Accumulated Lessons)\n[Trimmed for context budget — run `ai-spec init --consolidate` to prune]\n";
+          console.log(chalk.gray("    → §9 trimmed from constitution to save tokens."));
+        }
+      }
+    }
+
     // Use tasks if available for finer-grained generation with resume support
     const tasks = await loadTasksForSpec(specFilePath);
     if (tasks && tasks.length > 0) {
@@ -724,16 +529,19 @@ Output ONLY a valid JSON array:
 
       for (const batch of taskBatches) {
         const batchIsParallel = batch.length > 1;
-        // Wrap each task in .catch() so a single unexpected failure (disk full,
-        // provider timeout, mkdir error) degrades gracefully instead of rejecting
-        // the entire Promise.all and aborting all sibling tasks in the batch.
-        const batchResultPromises = batch.map((task) =>
-          executeTask(task, batchIsParallel).catch((err): TaskResult => {
-            console.log(chalk.yellow(`  ⚠ ${task.id} threw unexpectedly: ${(err as Error).message}`));
-            return { task, files: [], createdFiles: [], success: 0, total: 0, impliesRegistration: false };
-          })
-        );
-        const batchResults = await Promise.all(batchResultPromises);
+        const batchResultPromises = batch.map((task) => executeTask(task, batchIsParallel));
+        const settled = await Promise.allSettled(batchResultPromises);
+        const batchResults: TaskResult[] = [];
+        for (let i = 0; i < settled.length; i++) {
+          const outcome = settled[i];
+          if (outcome.status === "fulfilled") {
+            batchResults.push(outcome.value);
+          } else {
+            const task = batch[i];
+            console.log(chalk.yellow(`  ⚠ ${task.id} threw unexpectedly: ${outcome.reason?.message ?? outcome.reason}`));
+            batchResults.push({ task, files: [], createdFiles: [], success: 0, total: 0, impliesRegistration: false });
+          }
+        }
         layerResults.push(...batchResults);
         // Update cache after each batch so the next batch sees the exports.
         await updateCacheFromBatch(batchResults);
@@ -847,6 +655,7 @@ ${constitutionSection}
 === ${existingContent ? "Existing content (modify and return the complete file)" : "Create this file from scratch"} ===
 ${existingContent || "Output only the complete file content."}`;
 
+      const fileSpinner = startSpinner(`${prefix}Generating ${chalk.bold(item.file)}...`);
       try {
         const raw = await this.provider.generate(codePrompt, systemPrompt);
         const fileContent = stripCodeFences(raw);
@@ -854,11 +663,11 @@ ${existingContent || "Output only the complete file content."}`;
         await fs.ensureDir(path.dirname(fullPath));
         await fs.writeFile(fullPath, fileContent, "utf-8");
         getActiveLogger()?.fileWritten(item.file);
-        console.log(`${prefix}${existingContent ? chalk.yellow("~") : chalk.green("+")} ${chalk.bold(item.file)} ${chalk.green("✔")}`);
+        fileSpinner.succeed(`${existingContent ? chalk.yellow("~") : chalk.green("+")} ${chalk.bold(item.file)}`);
         successCount++;
         writtenFiles.push(item.file);
       } catch (err) {
-        console.log(`${prefix}${chalk.red("✘")} ${chalk.bold(item.file)} — ${chalk.red((err as Error).message)}`);
+        fileSpinner.fail(`${chalk.bold(item.file)} — ${(err as Error).message}`);
       }
     }
 
@@ -893,99 +702,3 @@ ${spec}`,
     console.log(chalk.cyan("\n") + plan);
   }
 }
-
-// ─── Topological Batch Sort ────────────────────────────────────────────────────
-
-/**
- * Partition tasks within a layer into ordered batches that respect the
- * `dependencies` field.  Tasks in the same batch have no intra-layer
- * dependencies on each other and can run in parallel.  Tasks in later batches
- * wait for earlier batches to complete.
- *
- * Only intra-layer dependencies (i.e. deps whose IDs also appear in `tasks`)
- * are considered — cross-layer ordering is already handled by LAYER_ORDER.
- *
- * Returns at least one batch.  On circular-dependency detection the remaining
- * tasks are dumped into a final batch so execution always completes.
- */
-function topoSortLayerTasks(tasks: SpecTask[]): SpecTask[][] {
-  if (tasks.length <= 1) return [tasks];
-
-  const idSet = new Set(tasks.map((t) => t.id));
-  const taskById = new Map(tasks.map((t) => [t.id, t]));
-  const inDegree = new Map<string, number>();
-  const dependents = new Map<string, string[]>(); // dep → tasks that depend on it
-
-  for (const task of tasks) {
-    inDegree.set(task.id, 0);
-    dependents.set(task.id, []);
-  }
-
-  for (const task of tasks) {
-    const intraDeps = task.dependencies.filter((dep) => idSet.has(dep));
-    inDegree.set(task.id, intraDeps.length);
-    for (const dep of intraDeps) {
-      dependents.get(dep)!.push(task.id);
-    }
-  }
-
-  const batches: SpecTask[][] = [];
-  const remaining = new Set(tasks.map((t) => t.id));
-
-  while (remaining.size > 0) {
-    const batch = [...remaining]
-      .filter((id) => inDegree.get(id) === 0)
-      .map((id) => taskById.get(id)!);
-
-    if (batch.length === 0) {
-      // Circular dependency — run all remaining tasks in parallel to avoid deadlock
-      batches.push([...remaining].map((id) => taskById.get(id)!));
-      break;
-    }
-
-    batches.push(batch);
-    for (const task of batch) {
-      remaining.delete(task.id);
-      for (const dependent of dependents.get(task.id)!) {
-        inDegree.set(dependent, inDegree.get(dependent)! - 1);
-      }
-    }
-  }
-
-  return batches;
-}
-
-// ─── Progress Bar Helper ───────────────────────────────────────────────────────
-
-const LAYER_ICONS: Record<string, string> = {
-  data: "💾",
-  infra: "⚙️ ",
-  service: "🔧",
-  api: "🌐",
-  view: "🖥️ ",
-  route: "🗺️ ",
-  test: "🧪",
-};
-
-export function printTaskProgress(
-  completed: number,
-  total: number,
-  task: SpecTask,
-  mode: "run" | "skip"
-): void {
-  const pct = total > 0 ? Math.round((completed / total) * 100) : 0;
-  const barWidth = 20;
-  const filled = Math.round((pct / 100) * barWidth);
-  const bar = chalk.green("█".repeat(filled)) + chalk.gray("░".repeat(barWidth - filled));
-  const icon = LAYER_ICONS[task.layer] ?? "  ";
-
-  if (mode === "skip") {
-    console.log(
-      chalk.gray(`\n  [${bar}] ${pct}% ✓ ${task.id} ${icon} ${task.title} — already done`)
-    );
-  } else {
-    console.log(
-      chalk.bold(`\n  [${bar}] ${pct}% → ${task.id} ${icon} ${task.title}`)
-    );
-  }
-}