@nclamvn/vibecode-cli 1.0.1 → 1.2.0

package/bin/vibecode.js

@@ -79,6 +79,9 @@ program
   .option('-c, --complete', 'Mark build as complete')
   .option('-e, --evidence', 'Capture evidence snapshot')
   .option('-a, --auto', 'Auto-build with Claude Code (--dangerously-skip-permissions)')
+  .option('-i, --iterate', 'Iterative build: build-test-fix loop until tests pass')
+  .option('-m, --max <n>', 'Max iterations for --iterate mode', parseInt)
+  .option('--strict', 'Strict mode: exit with error if tests fail after max iterations')
   .option('--provider <name>', 'Provider to use: claude-code', 'claude-code')
   .action(buildCommand);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nclamvn/vibecode-cli",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Build software with discipline - AI coding with guardrails",
   "main": "src/index.js",
   "type": "module",

package/src/commands/build.js

@@ -20,7 +20,7 @@ import { getCurrentState, transitionTo } from '../core/state-machine.js';
 import { getSpecHash } from '../core/contract.js';
 import { STATES } from '../config/constants.js';
 import { getBuildReportTemplate } from '../config/templates.js';
-import { ensureDir, pathExists, appendToFile, readMarkdown } from '../utils/files.js';
+import { ensureDir, pathExists, appendToFile, readMarkdown, writeJson } from '../utils/files.js';
 import { printBox, printError, printSuccess, printWarning, printNextStep } from '../ui/output.js';
 import {
   spawnClaudeCode,
@@ -28,6 +28,19 @@ import {
   buildPromptWithContext,
   getProviderInfo
 } from '../providers/index.js';
+// Phase D: Iterative Build
+import { runTests, formatTestResults } from '../core/test-runner.js';
+import { analyzeErrors, formatErrors, createErrorSummary } from '../core/error-analyzer.js';
+import { generateFixPrompt, areErrorsFixable, estimateFixComplexity } from '../core/fix-generator.js';
+import {
+  createIterationState,
+  recordIteration,
+  canContinue,
+  finalizeIterationState,
+  saveIterationState,
+  formatIterationSummary,
+  logIteration
+} from '../core/iteration.js';
 
 const execAsync = promisify(exec);
 
@@ -46,7 +59,10 @@ export async function buildCommand(options = {}) {
     const specHash = await getSpecHash();
 
     // Handle different build modes
-    if (options.auto) {
+    if (options.iterate) {
+      // Phase D: Iterative Build
+      await handleIterativeBuild(currentState, projectName, sessionId, sessionPath, specHash, options);
+    } else if (options.auto) {
       await handleAutoBuild(currentState, projectName, sessionId, sessionPath, specHash, options);
     } else if (options.start) {
       await handleBuildStart(currentState, projectName, sessionId, sessionPath, specHash);
@@ -216,6 +232,320 @@ ${evidence.screenshots > 0 ? `  ✅ ${evidence.screenshots} screenshots` : '
   }
 }
 
+/**
+ * Handle --iterate mode: Build-Test-Fix loop
+ * "Build until tests pass or max iterations reached"
+ */
+async function handleIterativeBuild(currentState, projectName, sessionId, sessionPath, specHash, options) {
+  const maxIterations = options.max || 3;
+  const strictMode = options.strict || false;
+
+  // Check state - must be PLAN_CREATED or BUILD_IN_PROGRESS or REVIEW_FAILED
+  const validStates = [STATES.PLAN_CREATED, STATES.BUILD_IN_PROGRESS, STATES.REVIEW_FAILED];
+  if (!validStates.includes(currentState)) {
+    printError(`Cannot iterate in state: ${currentState}`);
+    console.log('Run `vibecode plan` first to create execution plan.');
+    process.exit(1);
+  }
+
+  // Check if Claude Code is available
+  const available = await isClaudeCodeAvailable();
+  if (!available) {
+    printError('Claude Code CLI not found.');
+    console.log(chalk.gray('Install with: npm install -g @anthropic-ai/claude-code'));
+    process.exit(1);
+  }
+
+  // Check coder_pack.md exists
+  if (!await sessionFileExists('coder_pack.md')) {
+    printError('coder_pack.md not found. Run `vibecode plan` first.');
+    process.exit(1);
+  }
+
+  // Setup directories
+  const evidencePath = path.join(sessionPath, 'evidence');
+  await ensureDir(evidencePath);
+  await ensureDir(path.join(evidencePath, 'screenshots'));
+  const iterationDir = path.join(sessionPath, 'iterations');
+  await ensureDir(iterationDir);
+  const logPath = path.join(evidencePath, 'build.log');
+
+  // Initialize iteration state
+  let iterationState = createIterationState(sessionId, maxIterations);
+
+  // Save initial state
+  const stateData = await loadState();
+  const startTime = new Date().toISOString();
+  stateData.build_started = startTime;
+  stateData.build_provider = 'claude-code';
+  stateData.build_mode = 'iterate';
+  stateData.max_iterations = maxIterations;
+  await saveState(stateData);
+
+  // Transition to BUILD_IN_PROGRESS if not already
+  if (currentState !== STATES.BUILD_IN_PROGRESS) {
+    await transitionTo(STATES.BUILD_IN_PROGRESS, 'iterative_build_started');
+  }
+
+  // Load coder pack
+  const originalCoderPack = await readSessionFile('coder_pack.md');
+
+  // Log start
+  await appendToFile(logPath, `\n${'='.repeat(60)}\n`);
+  await appendToFile(logPath, `ITERATIVE BUILD STARTED: ${startTime}\n`);
+  await appendToFile(logPath, `Max Iterations: ${maxIterations}\n`);
+  await appendToFile(logPath, `Strict Mode: ${strictMode}\n`);
+  await appendToFile(logPath, `${'='.repeat(60)}\n\n`);
+
+  // Show starting message
+  const providerInfo = getProviderInfo();
+
+  const content = `🔄 ITERATIVE BUILD
+
+Project: ${projectName}
+Session: ${sessionId}
+Spec Hash: ${specHash}
+
+Provider: ${providerInfo.name}
+Max Iterations: ${maxIterations}
+Strict Mode: ${strictMode ? 'Yes' : 'No'}
+
+Starting build-test-fix loop...`;
+
+  console.log();
+  printBox(content, { borderColor: 'magenta' });
+  console.log();
+
+  // Build-Test-Fix Loop
+  let currentPrompt = await buildPromptWithContext(originalCoderPack, process.cwd());
+  let loopResult = { success: false, reason: '' };
+
+  while (true) {
+    const iteration = iterationState.currentIteration + 1;
+    const iterationStart = Date.now();
+
+    console.log(chalk.cyan(`\n${'─'.repeat(60)}`));
+    console.log(chalk.cyan(`│ ITERATION ${iteration}/${maxIterations}`));
+    console.log(chalk.cyan(`${'─'.repeat(60)}\n`));
+
+    await logIteration(logPath, iteration, 'Starting iteration');
+
+    // Step 1: Run Claude Code
+    console.log(chalk.yellow('▶ Running Claude Code...'));
+    console.log();
+
+    try {
+      const buildResult = await spawnClaudeCode(currentPrompt, {
+        cwd: process.cwd(),
+        logPath: logPath
+      });
+
+      console.log();
+      await logIteration(logPath, iteration, `Claude Code exited with code: ${buildResult.code}`);
+
+      // Capture evidence for this iteration
+      await captureGitDiff(evidencePath);
+      const iterEvidencePath = path.join(iterationDir, `iteration-${iteration}-diff.txt`);
+      try {
+        const { stdout } = await execAsync('git diff HEAD', { maxBuffer: 10 * 1024 * 1024 });
+        if (stdout.trim()) {
+          const fs = await import('fs-extra');
+          await fs.default.writeFile(iterEvidencePath, stdout, 'utf-8');
+        }
+      } catch (e) { /* ignore */ }
+
+      // Step 2: Run Tests
+      console.log(chalk.yellow('▶ Running tests...'));
+      const spinner = ora('Testing...').start();
+
+      const testResult = await runTests(process.cwd());
+      const iterationDuration = Date.now() - iterationStart;
+
+      if (testResult.passed) {
+        spinner.succeed('All tests passed!');
+
+        // Record successful iteration
+        iterationState = recordIteration(iterationState, {
+          passed: true,
+          errorCount: 0,
+          errorTypes: [],
+          affectedFiles: [],
+          duration: iterationDuration,
+          action: 'build'
+        });
+
+        // Finalize as success
+        iterationState = finalizeIterationState(iterationState, 'success');
+        await saveIterationState(sessionPath, iterationState);
+
+        loopResult = { success: true, reason: 'All tests passed' };
+        break;
+
+      } else {
+        spinner.fail(`Tests failed: ${testResult.summary.failed}/${testResult.summary.total}`);
+
+        // Step 3: Analyze Errors
+        const analyzedErrors = analyzeErrors(testResult);
+        const summary = createErrorSummary(analyzedErrors);
+
+        console.log();
+        console.log(formatErrors(analyzedErrors));
+
+        await logIteration(logPath, iteration, `Found ${analyzedErrors.length} errors`);
+
+        // Save error analysis for this iteration
+        await writeJson(path.join(iterationDir, `iteration-${iteration}-errors.json`), {
+          iteration,
+          timestamp: new Date().toISOString(),
+          summary,
+          errors: analyzedErrors
+        });
+
+        // Record failed iteration
+        iterationState = recordIteration(iterationState, {
+          passed: false,
+          errorCount: analyzedErrors.length,
+          errorTypes: [...new Set(analyzedErrors.map(e => e.type))],
+          affectedFiles: [...new Set(analyzedErrors.filter(e => e.file).map(e => e.file))],
+          duration: iterationDuration,
+          action: 'build'
+        });
+
+        // Check if errors are fixable
+        const fixableCheck = areErrorsFixable(analyzedErrors);
+        if (!fixableCheck.fixable) {
+          console.log(chalk.red(`\n⚠️  ${fixableCheck.reason}`));
+          await logIteration(logPath, iteration, `Errors not fixable: ${fixableCheck.reason}`);
+
+          iterationState = finalizeIterationState(iterationState, 'unfixable');
+          await saveIterationState(sessionPath, iterationState);
+
+          loopResult = { success: false, reason: fixableCheck.reason };
+          break;
+        }
+
+        // Check if we can continue
+        const continueCheck = canContinue(iterationState);
+        if (!continueCheck.canContinue) {
+          console.log(chalk.yellow(`\n⚠️  ${continueCheck.reason}`));
+          await logIteration(logPath, iteration, continueCheck.reason);
+
+          iterationState = finalizeIterationState(iterationState, 'max_reached');
+          await saveIterationState(sessionPath, iterationState);
+
+          loopResult = { success: false, reason: continueCheck.reason };
+          break;
+        }
+
+        // Step 4: Generate Fix Prompt
+        const complexity = estimateFixComplexity(analyzedErrors);
+        console.log(chalk.gray(`\nFix complexity: ${complexity}`));
+        console.log(chalk.yellow(`\n▶ Generating fix prompt for iteration ${iteration + 1}...`));
+
+        currentPrompt = generateFixPrompt(analyzedErrors, originalCoderPack, iteration + 1);
+
+        // Save fix prompt for evidence
+        await writeSessionFile(`iterations/fix-prompt-${iteration + 1}.md`, currentPrompt);
+
+        await logIteration(logPath, iteration, 'Generated fix prompt for next iteration');
+      }
+
+    } catch (error) {
+      console.log(chalk.red(`\n❌ Build error: ${error.message}`));
+      await logIteration(logPath, iteration, `Error: ${error.message}`);
+
+      iterationState = finalizeIterationState(iterationState, 'error');
+      await saveIterationState(sessionPath, iterationState);
+
+      loopResult = { success: false, reason: error.message };
+      break;
+    }
+  }
+
+  // Final Summary
+  const endTime = new Date().toISOString();
+  await appendToFile(logPath, `\n${'='.repeat(60)}\n`);
+  await appendToFile(logPath, `ITERATIVE BUILD COMPLETED: ${endTime}\n`);
+  await appendToFile(logPath, `Result: ${loopResult.success ? 'SUCCESS' : 'FAILED'}\n`);
+  await appendToFile(logPath, `Iterations: ${iterationState.currentIteration}\n`);
+  await appendToFile(logPath, `${'='.repeat(60)}\n`);
+
+  // Save final iteration state
+  await saveIterationState(sessionPath, iterationState);
+
+  // Check evidence
+  const evidence = await checkEvidence(evidencePath);
+
+  // Generate build report
+  const reportContent = getBuildReportTemplate(
+    projectName,
+    sessionId,
+    specHash,
+    startTime,
+    endTime,
+    evidence
+  );
+  await writeSessionFile('build_report.md', reportContent);
+
+  // Update state
+  stateData.build_completed = endTime;
+  stateData.iterations = iterationState.currentIteration;
+  stateData.iteration_result = loopResult.success ? 'success' : 'failed';
+  await saveState(stateData);
+
+  console.log();
+  console.log(chalk.cyan('─'.repeat(60)));
+  console.log();
+
+  if (loopResult.success) {
+    await transitionTo(STATES.BUILD_DONE, 'iterative_build_success');
+
+    const duration = Math.round((new Date(endTime) - new Date(startTime)) / 1000 / 60);
+
+    const successContent = `✅ ITERATIVE BUILD SUCCESS
+
+Project: ${projectName}
+Iterations: ${iterationState.currentIteration}/${maxIterations}
+Duration: ${duration} minutes
+Result: All tests passed!
+
+Evidence:
+${evidence.hasDiff ? '  ✅ changes.diff' : '  ⬜ changes.diff'}
+${evidence.hasLog ? '  ✅ build.log' : '  ⬜ build.log'}
+  ✅ ${iterationState.currentIteration} iteration records`;
+
+    printBox(successContent, { borderColor: 'green' });
+    printNextStep('Run `vibecode review` to validate your build');
+
+  } else {
+    // Still transition to BUILD_DONE but with failure note
+    await transitionTo(STATES.BUILD_DONE, 'iterative_build_completed_with_errors');
+
+    const failContent = `⚠️  ITERATIVE BUILD INCOMPLETE
+
+Project: ${projectName}
+Iterations: ${iterationState.currentIteration}/${maxIterations}
+Result: ${loopResult.reason}
+
+Evidence saved in:
+  ${iterationDir}/
+
+Check iteration logs for details.`;
+
+    printBox(failContent, { borderColor: 'yellow' });
+
+    if (strictMode) {
+      printError('Strict mode: Build failed with errors');
+      process.exit(1);
+    } else {
+      console.log(chalk.gray('\nYou can:'));
+      console.log(chalk.gray('  • Run `vibecode build --iterate` to try again'));
+      console.log(chalk.gray('  • Run `vibecode review` to review current state'));
+      console.log(chalk.gray('  • Fix errors manually and run `vibecode build --complete`'));
+    }
+  }
+}
+
 async function handleBuildStart(currentState, projectName, sessionId, sessionPath, specHash) {
   const spinner = ora('Starting build...').start();
 

package/src/config/constants.js

@@ -3,7 +3,7 @@
 // Spec Hash: 0fe43335f5a325e3279a079ce616c052
 // ═══════════════════════════════════════════════════════════════════════════════
 
-export const VERSION = '2.0.0';
+export const VERSION = '1.0.1';
 export const SPEC_HASH = '0fe43335f5a325e3279a079ce616c052';
 
 // ─────────────────────────────────────────────────────────────────────────────

package/src/core/error-analyzer.js

@@ -0,0 +1,237 @@
+// ═══════════════════════════════════════════════════════════════════════════════
+// VIBECODE CLI - Error Analyzer
+// Intelligent error analysis for iterative builds
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Analyze test results and extract actionable errors
+ * @param {TestResults} testResult - Results from test runner
+ * @returns {AnalyzedError[]}
+ */
+export function analyzeErrors(testResult) {
+  const errors = [];
+
+  for (const test of testResult.tests) {
+    if (!test.passed) {
+      const testErrors = test.errors || [];
+
+      for (const error of testErrors) {
+        errors.push({
+          source: test.name,
+          type: categorizeError(error),
+          file: error.file || null,
+          line: error.line || null,
+          column: error.column || null,
+          message: error.message,
+          suggestion: generateSuggestion(error),
+          priority: calculatePriority(error),
+          raw: error.raw
+        });
+      }
+
+      // If no specific errors but test failed, add generic error
+      if (testErrors.length === 0) {
+        errors.push({
+          source: test.name,
+          type: 'unknown',
+          message: test.error || `${test.name} failed`,
+          suggestion: `Check ${test.name} output for details`,
+          priority: 'medium',
+          raw: test.output
+        });
+      }
+    }
+  }
+
+  // Sort by priority
+  return errors.sort((a, b) => {
+    const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+    return (priorityOrder[a.priority] || 2) - (priorityOrder[b.priority] || 2);
+  });
+}
+
+/**
+ * Categorize error type
+ */
+function categorizeError(error) {
+  const message = (error.message || '').toLowerCase();
+  const raw = (error.raw || '').toLowerCase();
+  const combined = message + ' ' + raw;
+
+  if (combined.includes('syntaxerror') || combined.includes('unexpected token')) {
+    return 'syntax';
+  }
+  if (combined.includes('typeerror') || combined.includes('type error') || combined.includes('is not a function')) {
+    return 'type';
+  }
+  if (combined.includes('referenceerror') || combined.includes('is not defined')) {
+    return 'reference';
+  }
+  if (combined.includes('import') || combined.includes('require') || combined.includes('module not found')) {
+    return 'import';
+  }
+  if (combined.includes('eslint') || combined.includes('lint')) {
+    return 'lint';
+  }
+  if (combined.includes('test') || combined.includes('expect') || combined.includes('assert')) {
+    return 'test';
+  }
+  if (combined.includes('typescript') || combined.includes('ts(')) {
+    return 'typescript';
+  }
+  if (combined.includes('build') || combined.includes('compile')) {
+    return 'build';
+  }
+
+  return 'unknown';
+}
+
+/**
+ * Generate fix suggestion based on error type
+ */
+function generateSuggestion(error) {
+  const type = categorizeError(error);
+  const message = error.message || '';
+
+  switch (type) {
+    case 'syntax':
+      return 'Check for missing brackets, semicolons, or typos near the error location';
+
+    case 'type':
+      if (message.includes('undefined')) {
+        return 'Check if the variable/property is properly initialized';
+      }
+      if (message.includes('is not a function')) {
+        return 'Verify the function exists and is properly imported';
+      }
+      return 'Check type compatibility and ensure proper type handling';
+
+    case 'reference':
+      return 'Ensure the variable/function is defined or imported before use';
+
+    case 'import':
+      if (message.includes('module not found')) {
+        return 'Install missing package with npm install or fix import path';
+      }
+      return 'Check import path and ensure the module exports correctly';
+
+    case 'lint':
+      return 'Fix the linting issue as specified in the error message';
+
+    case 'test':
+      return 'Update the implementation to match expected behavior, or fix the test assertion';
+
+    case 'typescript':
+      return 'Fix type errors by adding proper types or type guards';
+
+    case 'build':
+      return 'Check build configuration and dependencies';
+
+    default:
+      return 'Review the error message and fix accordingly';
+  }
+}
+
+/**
+ * Calculate error priority
+ */
+function calculatePriority(error) {
+  const type = categorizeError(error);
+
+  // Critical - blocks everything
+  if (type === 'syntax' || type === 'import') {
+    return 'critical';
+  }
+
+  // High - likely causes cascading failures
+  if (type === 'reference' || type === 'type') {
+    return 'high';
+  }
+
+  // Medium - should be fixed
+  if (type === 'typescript' || type === 'build' || type === 'test') {
+    return 'medium';
+  }
+
+  // Low - nice to fix
+  if (type === 'lint') {
+    return 'low';
+  }
+
+  return 'medium';
+}
+
+/**
+ * Group errors by file for better organization
+ */
+export function groupErrorsByFile(errors) {
+  const grouped = {};
+
+  for (const error of errors) {
+    const file = error.file || 'unknown';
+    if (!grouped[file]) {
+      grouped[file] = [];
+    }
+    grouped[file].push(error);
+  }
+
+  return grouped;
+}
+
+/**
+ * Get unique files with errors
+ */
+export function getAffectedFiles(errors) {
+  const files = new Set();
+  for (const error of errors) {
+    if (error.file) {
+      files.add(error.file);
+    }
+  }
+  return Array.from(files);
+}
+
+/**
+ * Format errors for display
+ */
+export function formatErrors(errors) {
+  const lines = [];
+
+  lines.push(`Found ${errors.length} error(s):`);
+  lines.push('');
+
+  const grouped = groupErrorsByFile(errors);
+
+  for (const [file, fileErrors] of Object.entries(grouped)) {
+    lines.push(`📄 ${file}`);
+    for (const error of fileErrors) {
+      const loc = error.line ? `:${error.line}` : '';
+      const priority = error.priority === 'critical' ? '🔴' :
+                       error.priority === 'high' ? '🟠' :
+                       error.priority === 'medium' ? '🟡' : '🟢';
+      lines.push(`   ${priority} ${error.type}: ${error.message?.substring(0, 60) || 'Unknown error'}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Create a summary of errors for logging
+ */
+export function createErrorSummary(errors) {
+  const byType = {};
+  const byPriority = { critical: 0, high: 0, medium: 0, low: 0 };
+
+  for (const error of errors) {
+    byType[error.type] = (byType[error.type] || 0) + 1;
+    byPriority[error.priority] = (byPriority[error.priority] || 0) + 1;
+  }
+
+  return {
+    total: errors.length,
+    byType,
+    byPriority,
+    files: getAffectedFiles(errors)
+  };
+}

package/src/core/fix-generator.js

@@ -0,0 +1,195 @@
+// ═══════════════════════════════════════════════════════════════════════════════
+// VIBECODE CLI - Fix Generator
+// Generate fix prompts for iterative builds
+// ═══════════════════════════════════════════════════════════════════════════════
+
+import { formatErrors, createErrorSummary } from './error-analyzer.js';
+
+/**
+ * Generate a fix prompt based on errors from previous iteration
+ * @param {AnalyzedError[]} errors - Analyzed errors from test runner
+ * @param {string} originalPack - Original coder pack content
+ * @param {number} iteration - Current iteration number
+ * @returns {string} - Fix prompt for Claude Code
+ */
+export function generateFixPrompt(errors, originalPack, iteration = 1) {
+  const summary = createErrorSummary(errors);
+
+  const sections = [
+    '# 🔧 FIX REQUIRED - Iteration ' + iteration,
+    '',
+    `The previous build had **${errors.length} error(s)**. Please fix them.`,
+    '',
+    '---',
+    '',
+    '## 📋 Error Summary',
+    '',
+    `- **Total Errors:** ${summary.total}`,
+    `- **Critical:** ${summary.byPriority.critical}`,
+    `- **High:** ${summary.byPriority.high}`,
+    `- **Medium:** ${summary.byPriority.medium}`,
+    `- **Low:** ${summary.byPriority.low}`,
+    '',
+    `**Affected Files:** ${summary.files.length > 0 ? summary.files.join(', ') : 'Unknown'}`,
+    '',
+    '---',
+    '',
+    '## 🚨 Errors to Fix',
+    '',
+  ];
+
+  // Add detailed errors grouped by priority
+  const byPriority = groupByPriority(errors);
+
+  for (const [priority, priorityErrors] of Object.entries(byPriority)) {
+    if (priorityErrors.length === 0) continue;
+
+    const emoji = priority === 'critical' ? '🔴' :
+                  priority === 'high' ? '🟠' :
+                  priority === 'medium' ? '🟡' : '🟢';
+
+    sections.push(`### ${emoji} ${priority.toUpperCase()} Priority`);
+    sections.push('');
+
+    for (const error of priorityErrors) {
+      const location = error.file
+        ? `\`${error.file}${error.line ? ':' + error.line : ''}\``
+        : 'Unknown location';
+
+      sections.push(`**${error.type}** at ${location}`);
+      sections.push(`- Message: ${error.message}`);
+      sections.push(`- Suggestion: ${error.suggestion}`);
+      if (error.raw && error.raw !== error.message) {
+        sections.push(`- Raw output: \`${truncate(error.raw, 200)}\``);
+      }
+      sections.push('');
+    }
+  }
+
+  sections.push('---');
+  sections.push('');
+  sections.push('## 📝 Original Task Reference');
+  sections.push('');
+  sections.push('<details>');
+  sections.push('<summary>Click to expand original task</summary>');
+  sections.push('');
+  sections.push(originalPack);
+  sections.push('');
+  sections.push('</details>');
+  sections.push('');
+  sections.push('---');
+  sections.push('');
+  sections.push('## ⚡ Fix Instructions');
+  sections.push('');
+  sections.push('1. **Fix ONLY the errors listed above** - Do not refactor or change working code');
+  sections.push('2. **Start with CRITICAL errors** - They likely cause cascading failures');
+  sections.push('3. **Run tests after each fix** - Verify the error is resolved');
+  sections.push('4. **Keep changes minimal** - Focus on the specific issue');
+  sections.push('');
+  sections.push('When all errors are fixed, the build will be validated again.');
+  sections.push('');
+
+  return sections.join('\n');
+}
+
+/**
+ * Generate a minimal fix prompt for single error
+ */
+export function generateSingleFixPrompt(error) {
+  const location = error.file
+    ? `${error.file}${error.line ? ':' + error.line : ''}`
+    : 'unknown location';
+
+  return `# Fix Required
+
+**Error Type:** ${error.type}
+**Location:** ${location}
+**Message:** ${error.message}
+
+**Suggestion:** ${error.suggestion}
+
+Please fix this specific error. Keep the change minimal and focused.`;
+}
+
+/**
+ * Generate iteration context for logging
+ */
+export function generateIterationContext(iteration, errors, duration) {
+  return {
+    iteration,
+    timestamp: new Date().toISOString(),
+    errorCount: errors.length,
+    errorTypes: [...new Set(errors.map(e => e.type))],
+    affectedFiles: [...new Set(errors.filter(e => e.file).map(e => e.file))],
+    duration
+  };
+}
+
+/**
+ * Group errors by priority
+ */
+function groupByPriority(errors) {
+  const grouped = {
+    critical: [],
+    high: [],
+    medium: [],
+    low: []
+  };
+
+  for (const error of errors) {
+    const priority = error.priority || 'medium';
+    if (grouped[priority]) {
+      grouped[priority].push(error);
+    } else {
+      grouped.medium.push(error);
+    }
+  }
+
+  return grouped;
+}
+
+/**
+ * Truncate string with ellipsis
+ */
+function truncate(str, maxLen) {
+  if (!str) return '';
+  if (str.length <= maxLen) return str;
+  return str.substring(0, maxLen - 3) + '...';
+}
+
+/**
+ * Check if errors are fixable (not system/config errors)
+ */
+export function areErrorsFixable(errors) {
+  // If all errors are unknown type with no file info, might be config issue
+  const unknownWithoutFile = errors.filter(e => e.type === 'unknown' && !e.file);
+
+  if (unknownWithoutFile.length === errors.length) {
+    return {
+      fixable: false,
+      reason: 'All errors are unstructured with no file information. This may indicate a configuration or environment issue.'
+    };
+  }
+
+  return { fixable: true };
+}
+
+/**
+ * Estimate fix complexity
+ */
+export function estimateFixComplexity(errors) {
+  let score = 0;
+
+  for (const error of errors) {
+    switch (error.priority) {
+      case 'critical': score += 3; break;
+      case 'high': score += 2; break;
+      case 'medium': score += 1; break;
+      case 'low': score += 0.5; break;
+    }
+  }
+
+  if (score <= 3) return 'simple';
+  if (score <= 8) return 'moderate';
+  return 'complex';
+}

package/src/core/iteration.js

@@ -0,0 +1,226 @@
+// ═══════════════════════════════════════════════════════════════════════════════
+// VIBECODE CLI - Iteration Tracker
+// Manage and track build-test-fix iterations
+// ═══════════════════════════════════════════════════════════════════════════════
+
+import path from 'path';
+import { ensureDir, writeJson, readJson, pathExists, appendToFile } from '../utils/files.js';
+
+/**
+ * @typedef {Object} IterationRecord
+ * @property {number} iteration - Iteration number
+ * @property {string} timestamp - ISO timestamp
+ * @property {boolean} passed - Whether tests passed
+ * @property {number} errorCount - Number of errors
+ * @property {string[]} errorTypes - Types of errors found
+ * @property {string[]} affectedFiles - Files with errors
+ * @property {number} duration - Duration in ms
+ * @property {string} action - What action was taken (build/fix)
+ */
+
+/**
+ * @typedef {Object} IterationState
+ * @property {string} sessionId - Session identifier
+ * @property {string} startTime - When iteration started
+ * @property {number} currentIteration - Current iteration number
+ * @property {number} maxIterations - Max allowed iterations
+ * @property {IterationRecord[]} history - History of iterations
+ * @property {boolean} completed - Whether iteration loop completed
+ * @property {string} result - Final result (success/max_reached/error)
+ */
+
+/**
+ * Create new iteration state
+ * @param {string} sessionId - Session identifier
+ * @param {number} maxIterations - Maximum iterations allowed
+ * @returns {IterationState}
+ */
+export function createIterationState(sessionId, maxIterations = 3) {
+  return {
+    sessionId,
+    startTime: new Date().toISOString(),
+    currentIteration: 0,
+    maxIterations,
+    history: [],
+    completed: false,
+    result: null
+  };
+}
+
+/**
+ * Record an iteration result
+ * @param {IterationState} state - Current iteration state
+ * @param {Object} result - Iteration result
+ * @returns {IterationState} - Updated state
+ */
+export function recordIteration(state, result) {
+  const record = {
+    iteration: state.currentIteration + 1,
+    timestamp: new Date().toISOString(),
+    passed: result.passed,
+    errorCount: result.errorCount || 0,
+    errorTypes: result.errorTypes || [],
+    affectedFiles: result.affectedFiles || [],
+    duration: result.duration || 0,
+    action: result.action || 'build'
+  };
+
+  return {
+    ...state,
+    currentIteration: state.currentIteration + 1,
+    history: [...state.history, record]
+  };
+}
+
+/**
+ * Check if can continue iterating
+ * @param {IterationState} state - Current state
+ * @returns {{canContinue: boolean, reason: string}}
+ */
+export function canContinue(state) {
+  if (state.completed) {
+    return { canContinue: false, reason: 'Iteration already completed' };
+  }
+
+  if (state.currentIteration >= state.maxIterations) {
+    return { canContinue: false, reason: `Max iterations (${state.maxIterations}) reached` };
+  }
+
+  // Check if last iteration passed
+  const lastRecord = state.history[state.history.length - 1];
+  if (lastRecord && lastRecord.passed) {
+    return { canContinue: false, reason: 'Tests passed - no more iterations needed' };
+  }
+
+  // Check for stuck loop (same errors repeated 3 times)
+  if (state.history.length >= 3) {
+    const last3 = state.history.slice(-3);
+    const errorCounts = last3.map(r => r.errorCount);
+    if (errorCounts.every(c => c === errorCounts[0]) && errorCounts[0] > 0) {
+      return { canContinue: false, reason: 'Stuck in loop - same error count for 3 iterations' };
+    }
+  }
+
+  return { canContinue: true, reason: '' };
+}
+
+/**
+ * Finalize iteration state
+ * @param {IterationState} state - Current state
+ * @param {string} result - Result type (success/max_reached/error/stuck)
+ * @returns {IterationState}
+ */
+export function finalizeIterationState(state, result) {
+  return {
+    ...state,
+    completed: true,
+    result,
+    endTime: new Date().toISOString(),
+    totalDuration: state.history.reduce((sum, r) => sum + r.duration, 0)
+  };
+}
+
+/**
+ * Save iteration state to session directory
+ * @param {string} sessionDir - Session directory path
+ * @param {IterationState} state - Iteration state
+ */
+export async function saveIterationState(sessionDir, state) {
+  const iterationDir = path.join(sessionDir, 'iterations');
+  await ensureDir(iterationDir);
+
+  const stateFile = path.join(iterationDir, 'state.json');
+  await writeJson(stateFile, state, { spaces: 2 });
+
+  // Also write individual iteration files for evidence
+  for (const record of state.history) {
+    const recordFile = path.join(iterationDir, `iteration-${record.iteration}.json`);
+    if (!await pathExists(recordFile)) {
+      await writeJson(recordFile, record, { spaces: 2 });
+    }
+  }
+}
+
+/**
+ * Load iteration state from session directory
+ * @param {string} sessionDir - Session directory path
+ * @returns {Promise<IterationState|null>}
+ */
+export async function loadIterationState(sessionDir) {
+  const stateFile = path.join(sessionDir, 'iterations', 'state.json');
+  if (await pathExists(stateFile)) {
+    return await readJson(stateFile);
+  }
+  return null;
+}
+
+/**
+ * Format iteration summary for display
+ * @param {IterationState} state - Iteration state
+ * @returns {string}
+ */
+export function formatIterationSummary(state) {
+  const lines = [];
+
+  lines.push(`Iteration Summary (${state.sessionId})`);
+  lines.push('═'.repeat(50));
+  lines.push(`Total Iterations: ${state.currentIteration}/${state.maxIterations}`);
+  lines.push(`Result: ${state.result || 'In Progress'}`);
+  lines.push('');
+
+  if (state.history.length > 0) {
+    lines.push('History:');
+    for (const record of state.history) {
+      const status = record.passed ? '✅' : '❌';
+      const errors = record.errorCount > 0 ? ` (${record.errorCount} errors)` : '';
+      lines.push(`  ${record.iteration}. ${status} ${record.action}${errors} - ${formatDuration(record.duration)}`);
+    }
+  }
+
+  if (state.totalDuration) {
+    lines.push('');
+    lines.push(`Total Duration: ${formatDuration(state.totalDuration)}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format duration in human readable format
+ */
+function formatDuration(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${Math.floor(ms / 60000)}m ${Math.round((ms % 60000) / 1000)}s`;
+}
+
+/**
+ * Write iteration log entry
+ */
+export async function logIteration(logPath, iteration, message) {
+  const timestamp = new Date().toISOString();
+  const entry = `[${timestamp}] [Iteration ${iteration}] ${message}\n`;
+  await appendToFile(logPath, entry);
+}
+
+/**
+ * Get progress percentage
+ */
+export function getProgressPercent(state) {
+  if (state.completed && state.result === 'success') {
+    return 100;
+  }
+  return Math.round((state.currentIteration / state.maxIterations) * 100);
+}
+
+/**
+ * Check if errors are improving (decreasing)
+ */
+export function isImproving(state) {
+  if (state.history.length < 2) return true;
+
+  const last = state.history[state.history.length - 1];
+  const prev = state.history[state.history.length - 2];
+
+  return last.errorCount < prev.errorCount;
+}

package/src/core/test-runner.js

@@ -0,0 +1,248 @@
+// ═══════════════════════════════════════════════════════════════════════════════
+// VIBECODE CLI - Test Runner
+// Automated test execution for iterative builds
+// ═══════════════════════════════════════════════════════════════════════════════
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import path from 'path';
+import { pathExists, readJson } from '../utils/files.js';
+
+const execAsync = promisify(exec);
+
+/**
+ * Run all available tests for a project
+ * @param {string} projectPath - Path to the project
+ * @returns {Promise<TestResults>}
+ */
+export async function runTests(projectPath) {
+  const results = {
+    passed: true,
+    tests: [],
+    errors: [],
+    summary: {
+      total: 0,
+      passed: 0,
+      failed: 0
+    },
+    duration: 0
+  };
+
+  const startTime = Date.now();
+
+  // 1. Check if package.json exists
+  const packageJsonPath = path.join(projectPath, 'package.json');
+  const hasPackageJson = await pathExists(packageJsonPath);
+
+  if (hasPackageJson) {
+    const pkg = await readJson(packageJsonPath);
+
+    // 2. Run npm test (if script exists)
+    if (pkg.scripts?.test && !pkg.scripts.test.includes('no test specified')) {
+      const npmTest = await runCommand('npm test', projectPath, 'npm test');
+      results.tests.push(npmTest);
+    }
+
+    // 3. Run npm run lint (if script exists)
+    if (pkg.scripts?.lint) {
+      const npmLint = await runCommand('npm run lint', projectPath, 'npm lint');
+      results.tests.push(npmLint);
+    }
+
+    // 4. Run npm run build (if script exists) - check for build errors
+    if (pkg.scripts?.build) {
+      const npmBuild = await runCommand('npm run build', projectPath, 'npm build');
+      results.tests.push(npmBuild);
+    }
+
+    // 5. Run TypeScript check if tsconfig exists
+    const tsconfigPath = path.join(projectPath, 'tsconfig.json');
+    if (await pathExists(tsconfigPath)) {
+      const tscCheck = await runCommand('npx tsc --noEmit', projectPath, 'typescript');
+      results.tests.push(tscCheck);
+    }
+  }
+
+  // 6. Check for syntax errors in JS files
+  const syntaxCheck = await checkJsSyntax(projectPath);
+  if (syntaxCheck.ran) {
+    results.tests.push(syntaxCheck);
+  }
+
+  // 7. Aggregate results
+  results.summary.total = results.tests.length;
+  results.summary.passed = results.tests.filter(t => t.passed).length;
+  results.summary.failed = results.tests.filter(t => !t.passed).length;
+  results.passed = results.tests.length === 0 || results.tests.every(t => t.passed);
+  results.errors = results.tests.filter(t => !t.passed).flatMap(t => t.errors || []);
+  results.duration = Date.now() - startTime;
+
+  return results;
+}
+
+/**
+ * Run a single command and capture results
+ */
+async function runCommand(command, cwd, name) {
+  const result = {
+    name,
+    command,
+    passed: false,
+    ran: true,
+    output: '',
+    errors: [],
+    duration: 0
+  };
+
+  const startTime = Date.now();
+
+  try {
+    const { stdout, stderr } = await execAsync(command, {
+      cwd,
+      timeout: 120000, // 2 minute timeout
+      maxBuffer: 10 * 1024 * 1024
+    });
+
+    result.passed = true;
+    result.output = stdout + stderr;
+    result.duration = Date.now() - startTime;
+
+  } catch (error) {
+    result.passed = false;
+    result.output = error.stdout || '';
+    result.error = error.stderr || error.message;
+    result.exitCode = error.code;
+    result.duration = Date.now() - startTime;
+
+    // Parse errors from output
+    result.errors = parseErrors(error.stderr || error.stdout || error.message, name);
+  }
+
+  return result;
+}
+
+/**
+ * Check JavaScript syntax errors
+ */
+async function checkJsSyntax(projectPath) {
+  const result = {
+    name: 'syntax-check',
+    passed: true,
+    ran: false,
+    errors: []
+  };
+
+  try {
+    // Find JS/TS files (limited to src/ to avoid node_modules)
+    const { stdout } = await execAsync(
+      'find src -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" 2>/dev/null | head -20',
+      { cwd: projectPath }
+    );
+
+    const files = stdout.trim().split('\n').filter(f => f);
+    if (files.length === 0) return result;
+
+    result.ran = true;
+
+    // Check each file for syntax errors using node --check
+    for (const file of files) {
+      if (file.endsWith('.ts') || file.endsWith('.tsx')) continue; // Skip TS files
+
+      try {
+        await execAsync(`node --check "${file}"`, { cwd: projectPath });
+      } catch (error) {
+        result.passed = false;
+        result.errors.push({
+          file,
+          message: error.message,
+          type: 'syntax'
+        });
+      }
+    }
+  } catch (error) {
+    // find command failed, skip syntax check
+  }
+
+  return result;
+}
+
+/**
+ * Parse error messages into structured format
+ */
+function parseErrors(errorOutput, source) {
+  const errors = [];
+  const lines = errorOutput.split('\n');
+
+  for (const line of lines) {
+    // Match common error patterns
+    // Pattern: file.js:10:5: error message
+    const fileLineMatch = line.match(/([^\s:]+):(\d+):(\d+)?:?\s*(.+)/);
+    if (fileLineMatch) {
+      errors.push({
+        source,
+        file: fileLineMatch[1],
+        line: parseInt(fileLineMatch[2]),
+        column: fileLineMatch[3] ? parseInt(fileLineMatch[3]) : null,
+        message: fileLineMatch[4].trim(),
+        raw: line
+      });
+      continue;
+    }
+
+    // Pattern: Error: message
+    const errorMatch = line.match(/^(Error|TypeError|SyntaxError|ReferenceError):\s*(.+)/);
+    if (errorMatch) {
+      errors.push({
+        source,
+        type: errorMatch[1],
+        message: errorMatch[2].trim(),
+        raw: line
+      });
+      continue;
+    }
+
+    // Pattern: ✖ or ✗ or FAIL
+    if (line.includes('✖') || line.includes('✗') || line.includes('FAIL')) {
+      errors.push({
+        source,
+        message: line.trim(),
+        raw: line
+      });
+    }
+  }
+
+  // If no structured errors found, add the whole output
+  if (errors.length === 0 && errorOutput.trim()) {
+    errors.push({
+      source,
+      message: errorOutput.substring(0, 500),
+      raw: errorOutput
+    });
+  }
+
+  return errors;
+}
+
+/**
+ * Format test results for display
+ */
+export function formatTestResults(results) {
+  const lines = [];
+
+  lines.push(`Tests: ${results.summary.passed}/${results.summary.total} passed`);
+  lines.push(`Duration: ${(results.duration / 1000).toFixed(1)}s`);
+
+  if (!results.passed) {
+    lines.push('');
+    lines.push('Failed tests:');
+    for (const test of results.tests.filter(t => !t.passed)) {
+      lines.push(`  ❌ ${test.name}`);
+      for (const error of test.errors || []) {
+        const loc = error.file ? `${error.file}:${error.line || '?'}` : '';
+        lines.push(`     ${loc} ${error.message?.substring(0, 80) || ''}`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}