ai-spec-dev 0.42.0 → 0.55.0

package/cli/utils.ts

@@ -1,37 +1,120 @@
 import * as path from "path";
 import * as fs from "fs-extra";
+import * as os from "os";
 import chalk from "chalk";
 import { input, select } from "@inquirer/prompts";
 import { CodeGenMode } from "../core/code-generator";
-import { ENV_KEY_MAP } from "../core/spec-generator";
+import { ENV_KEY_MAP, PROVIDER_CATALOG } from "../core/spec-generator";
 import { getSavedKey, saveKey, KEY_STORE_FILE } from "../core/key-store";
 
 // ─── Config ───────────────────────────────────────────────────────────────────
 
-export interface AiSpecConfig {
+/** User-level preferences (stored in ~/.ai-spec-config.json) */
+export interface AiSpecGlobalConfig {
   provider?: string;
   model?: string;
   codegen?: CodeGenMode;
   codegenProvider?: string;
   codegenModel?: string;
+}
+
+/** Full merged config (global + project-level overrides) */
+export interface AiSpecConfig extends AiSpecGlobalConfig {
   /** Minimum overall spec score (1-10) required to pass Approval Gate. 0 = disabled (default). */
   minSpecScore?: number;
   /** Minimum harness score (1-10) required for pipeline success. 0 = disabled (default). */
   minHarnessScore?: number;
   /** Maximum error-feedback cycles before giving up (default: 2, TDD default: 3). */
   maxErrorCycles?: number;
+  /**
+   * Maximum number of tasks that can run concurrently within a codegen batch
+   * (api mode only). Prevents rate-limit errors when a layer has many independent
+   * tasks. Default: 3.
+   */
+  maxCodegenConcurrency?: number;
+  /**
+   * When true (default), past hallucination patterns from
+   * `.ai-spec-fix-history.json` are injected into codegen prompts.
+   * Set to false to disable automatic learning from fix history.
+   */
+  injectFixHistory?: boolean;
+  /**
+   * Number of times a hallucination pattern must repeat in fix-history before
+   * `ai-spec fix-history --promote` offers it as a constitution §9 lesson.
+   * Default: 5.
+   */
+  fixHistoryPromotionThreshold?: number;
+  /**
+   * Maximum number of past hallucination patterns injected into a single
+   * codegen prompt. Prevents prompt bloat. Default: 10.
+   */
+  fixHistoryInjectMax?: number;
   /** §9 lesson count threshold for auto-consolidation (default: 12). */
   autoConsolidateThreshold?: number;
+
+  // ── Directory & file overrides ─────────────────────────────────────────────
+  /** Run log directory (default: ".ai-spec-logs") */
+  logDir?: string;
+  /** VCR recording directory (default: ".ai-spec-vcr") */
+  vcrDir?: string;
+  /** File backup directory (default: ".ai-spec-backup") */
+  backupDir?: string;
+  /** Review history file (default: ".ai-spec-reviews.json") */
+  reviewHistoryFile?: string;
+
+  // ── URL overrides ──────────────────────────────────────────────────────────
+  /** Default server URL for OpenAPI export (default: "http://localhost:3000") */
+  openApiServerUrl?: string;
+
+  // ── Numeric limits ─────────────────────────────────────────────────────────
+  /** Max chars captured from build/test/lint command output (default: 30000) */
+  maxCommandOutputChars?: number;
+  /** Max chars of source file sent to AI for auto-fix (default: 60000) */
+  maxFixFileChars?: number;
+  /** Max DSL extraction retries (default: 2) */
+  dslMaxRetries?: number;
+  /** Max constitution chars in codegen prompt (default: 4000) */
+  maxConstitutionChars?: number;
+  /** Per-provider token budget overrides (e.g. { "gemini": 900000, "claude": 180000 }) */
+  providerTokenBudgets?: Record<string, number>;
 }
 
 export const CONFIG_FILE = ".ai-spec.json";
+export const GLOBAL_CONFIG_FILE = path.join(os.homedir(), ".ai-spec-config.json");
+
+/** Load global user-level config from ~/.ai-spec-config.json */
+export async function loadGlobalConfig(): Promise<AiSpecGlobalConfig> {
+  try {
+    if (await fs.pathExists(GLOBAL_CONFIG_FILE)) {
+      return await fs.readJson(GLOBAL_CONFIG_FILE);
+    }
+  } catch { /* ignore */ }
+  return {};
+}
 
+/** Save global user-level config to ~/.ai-spec-config.json */
+export async function saveGlobalConfig(config: AiSpecGlobalConfig): Promise<void> {
+  await fs.ensureFile(GLOBAL_CONFIG_FILE);
+  await fs.writeJson(GLOBAL_CONFIG_FILE, config, { spaces: 2 });
+}
+
+/**
+ * Load merged config: global (baseline) + project-level (override).
+ * Provider/model from global, project-specific settings from local .ai-spec.json.
+ */
 export async function loadConfig(dir: string): Promise<AiSpecConfig> {
+  const globalConfig = await loadGlobalConfig();
+
+  let localConfig: AiSpecConfig = {};
   const p = path.join(dir, CONFIG_FILE);
   if (await fs.pathExists(p)) {
-    return fs.readJson(p);
+    try {
+      localConfig = await fs.readJson(p);
+    } catch { /* ignore */ }
   }
-  return {};
+
+  // Local overrides global
+  return { ...globalConfig, ...localConfig };
 }
 
 // ─── API Key Resolution ───────────────────────────────────────────────────────
@@ -45,6 +128,14 @@ export async function resolveApiKey(
   const envVar = ENV_KEY_MAP[providerName];
   if (envVar && process.env[envVar]) return process.env[envVar]!;
 
+  // Check fallback env vars (e.g. MiMo reads ANTHROPIC_AUTH_TOKEN from token-plan)
+  const meta = PROVIDER_CATALOG[providerName];
+  if (meta?.fallbackEnvKeys) {
+    for (const key of meta.fallbackEnvKeys) {
+      if (process.env[key]) return process.env[key]!;
+    }
+  }
+
   const savedKey = await getSavedKey(providerName);
   if (savedKey) {
     const masked = savedKey.slice(0, 6) + "..." + savedKey.slice(-4);

package/core/code-generator.ts

@@ -23,6 +23,7 @@ import {
 import { topoSortLayerTasks, printTaskProgress, LAYER_ICONS } from "./codegen/topo-sort";
 import { estimateTokens, getDefaultBudget } from "./token-budget";
 import { startSpinner } from "./cli-ui";
+import { loadFixHistory, buildHallucinationAvoidanceSection } from "./fix-history";
 
 // Re-export public symbols for backward compatibility
 export { extractBehavioralContract } from "./codegen/helpers";
@@ -41,6 +42,20 @@ export interface CodeGenOptions {
   dslFilePath?: string;
   /** Repo language type — selects the appropriate codegen system prompt */
   repoType?: string;
+  /**
+   * Maximum number of tasks that can run concurrently within a single batch
+   * (api mode only). A batch larger than this value is split into sequential
+   * sub-chunks, each running maxConcurrency tasks in parallel. Default: 3.
+   */
+  maxConcurrency?: number;
+  /**
+   * When true, prior hallucination patterns from `.ai-spec-fix-history.json`
+   * are injected into the codegen prompt as a "DO NOT REPEAT" section.
+   * Default: true when the ledger exists.
+   */
+  injectFixHistory?: boolean;
+  /** Max number of past hallucination patterns to inject. Default: 10 */
+  fixHistoryInjectMax?: number;
 }
 
 export class CodeGenerator {
@@ -268,8 +283,27 @@ export class CodeGenerator {
       console.log(chalk.gray(`  Frontend context: ${fctx.framework} / ${fctx.httpClient} | hooks:${fctx.hookFiles.length} stores:${fctx.storeFiles.length}`));
     }
 
+    // Inject past hallucination patterns so the AI learns from this project's fix history.
+    // Opt out via CodeGenOptions.injectFixHistory = false.
+    let fixHistorySection = "";
+    if (options.injectFixHistory !== false) {
+      try {
+        const history = await loadFixHistory(workingDir);
+        const section = buildHallucinationAvoidanceSection(history, {
+          maxItems: options.fixHistoryInjectMax ?? 10,
+        });
+        if (section) {
+          fixHistorySection = `\n${section}\n`;
+          const patternCount = (section.match(/❌ Do NOT/g) ?? []).length;
+          console.log(chalk.cyan(`  ✓ Injected ${patternCount} prior hallucination pattern(s) from fix-history`));
+        }
+      } catch {
+        // Non-fatal: if the ledger is broken, just skip injection
+      }
+    }
+
     // Token budget check — warn if context sections are large
-    const allContextText = spec + constitutionSection + dslSection + frontendSection + installedPackagesSection + sharedConfigSection;
+    const allContextText = spec + constitutionSection + dslSection + frontendSection + installedPackagesSection + sharedConfigSection + fixHistorySection;
     const estimatedTokenCount = estimateTokens(allContextText);
     const budget = getDefaultBudget(this.provider.providerName);
     if (estimatedTokenCount > budget * 0.7) {
@@ -292,7 +326,7 @@ export class CodeGenerator {
     // Use tasks if available for finer-grained generation with resume support
     const tasks = await loadTasksForSpec(specFilePath);
     if (tasks && tasks.length > 0) {
-      return this.runApiModeWithTasks(spec, tasks, specFilePath, workingDir, constitutionSection + dslSection + installedPackagesSection, frontendSection, sharedConfigSection, options, systemPrompt, context);
+      return this.runApiModeWithTasks(spec, tasks, specFilePath, workingDir, constitutionSection + dslSection + installedPackagesSection + fixHistorySection, frontendSection, sharedConfigSection, options, systemPrompt, context);
     }
 
     // Fallback: plan-then-generate
@@ -306,7 +340,7 @@ IMPORTANT: Check the "Frontend Project Context" section below. Extend existing h
 
 === Feature Spec ===
 ${spec}
-${constitutionSection}${dslSection}${frontendSection}${installedPackagesSection}${sharedConfigSection}
+${constitutionSection}${dslSection}${frontendSection}${installedPackagesSection}${sharedConfigSection}${fixHistorySection}
 === Project Context ===
 ${contextSummary}
 
@@ -336,7 +370,7 @@ Output ONLY a valid JSON array:
       console.log(`  ${icon} ${item.file}: ${chalk.gray(item.description)}`);
     });
 
-    const { files } = await this.generateFiles(filePlan, spec, workingDir, constitutionSection + dslSection + frontendSection + installedPackagesSection, systemPrompt);
+    const { files } = await this.generateFiles(filePlan, spec, workingDir, constitutionSection + dslSection + frontendSection + installedPackagesSection + fixHistorySection, systemPrompt);
     return files;
   }
 
@@ -524,24 +558,39 @@ Output ONLY a valid JSON array:
 
       // Partition tasks into topological batches (respects dependencies field).
       // Each batch runs in parallel; batches run sequentially.
+      // Additionally, each batch is chunked by maxConcurrency to prevent
+      // rate-limit errors when a batch contains many independent tasks.
       const taskBatches = topoSortLayerTasks(layerTasks);
       const layerResults: TaskResult[] = [];
+      const maxConcurrency = Math.max(1, options.maxConcurrency ?? 3);
 
       for (const batch of taskBatches) {
         const batchIsParallel = batch.length > 1;
-        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 });
+
+        // Split batch into chunks of at most `maxConcurrency` tasks.
+        // Each chunk runs in parallel; chunks run sequentially within the batch.
+        for (let chunkStart = 0; chunkStart < batch.length; chunkStart += maxConcurrency) {
+          const chunk = batch.slice(chunkStart, chunkStart + maxConcurrency);
+          if (batchIsParallel && batch.length > maxConcurrency) {
+            const chunkIdx = Math.floor(chunkStart / maxConcurrency) + 1;
+            const totalChunks = Math.ceil(batch.length / maxConcurrency);
+            console.log(chalk.gray(`    ↳ chunk ${chunkIdx}/${totalChunks} (${chunk.length} tasks, concurrency cap: ${maxConcurrency})`));
+          }
+          const chunkResultPromises = chunk.map((task) => executeTask(task, batchIsParallel));
+          const settled = await Promise.allSettled(chunkResultPromises);
+          for (let i = 0; i < settled.length; i++) {
+            const outcome = settled[i];
+            if (outcome.status === "fulfilled") {
+              batchResults.push(outcome.value);
+            } else {
+              const task = chunk[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);

package/core/config-defaults.ts

@@ -0,0 +1,44 @@
+/**
+ * config-defaults.ts — Centralized default values for all configurable constants.
+ *
+ * Modules import their defaults from here instead of defining local magic numbers.
+ * The pipeline can override any value via AiSpecConfig at runtime.
+ */
+
+// ─── Directory & File Names ─────────────────────────────────────────────────
+
+export const DEFAULT_LOG_DIR = ".ai-spec-logs";
+export const DEFAULT_VCR_DIR = ".ai-spec-vcr";
+export const DEFAULT_BACKUP_DIR = ".ai-spec-backup";
+export const DEFAULT_REVIEW_HISTORY_FILE = ".ai-spec-reviews.json";
+
+// ─── URLs ───────────────────────────────────────────────────────────────────
+
+export const DEFAULT_OPENAPI_SERVER_URL = "http://localhost:3000";
+
+// ─── Numeric Limits ─────────────────────────────────────────────────────────
+
+/** Max chars captured from build/test/lint command output before parsing. */
+export const DEFAULT_MAX_COMMAND_OUTPUT_CHARS = 30_000;
+
+/** Max chars of an existing file sent to the AI for auto-fix. */
+export const DEFAULT_MAX_FIX_FILE_CHARS = 60_000;
+
+/** Max DSL extraction retries on parse failure. */
+export const DEFAULT_DSL_MAX_RETRIES = 2;
+
+/** Max constitution chars in codegen prompts (trimmed if exceeded). */
+export const DEFAULT_MAX_CONSTITUTION_CHARS = 4_000;
+
+/** Max chars of file content sent per file in review (reviewFiles mode). */
+export const DEFAULT_MAX_REVIEW_FILE_CHARS = 3_000;
+
+// ─── Token Budgets ──────────────────────────────────────────────────────────
+
+export const DEFAULT_TOKEN_BUDGETS: Record<string, number> = {
+  gemini: 900_000,
+  claude: 180_000,
+  openai: 120_000,
+  deepseek: 60_000,
+  default: 100_000,
+};

package/core/constitution-generator.ts

@@ -4,6 +4,7 @@ import * as path from "path";
 import { AIProvider } from "./spec-generator";
 import { ContextLoader, ProjectContext } from "./context-loader";
 import { constitutionSystemPrompt } from "../prompts/constitution.prompt";
+import { DEFAULT_MAX_CONSTITUTION_CHARS } from "./config-defaults";
 
 export const CONSTITUTION_FILE = ".ai-spec-constitution.md";
 
@@ -41,7 +42,7 @@ function buildConstitutionPrompt(context: ProjectContext, projectRoot: string):
   }
 
   if (context.schema) {
-    parts.push(`=== Prisma Schema ===\n${context.schema.slice(0, 4000)}\n`);
+    parts.push(`=== Prisma Schema ===\n${context.schema.slice(0, DEFAULT_MAX_CONSTITUTION_CHARS)}\n`);
   }
 
   if (context.errorPatterns) {