@hustle-together/api-dev-tools 2.0.7 → 3.1.0

package/hooks/verify-after-green.py

@@ -0,0 +1,282 @@
+#!/usr/bin/env python3
+"""
+Hook: PostToolUse (after test runs)
+Purpose: Trigger Phase 9 (Verify) + Manifest Generation after tests pass
+
+This hook detects when tests pass (TDD Green phase complete) and:
+  1. Runs the programmatic manifest generation scripts
+  2. Reminds Claude to re-research the original documentation
+  3. Compares implemented features to documented features
+  4. Requires user confirmation before proceeding
+
+The goal is to:
+  - Automatically generate api-tests-manifest.json from test files (programmatic, not LLM)
+  - Catch cases where Claude implemented from memory instead of from researched docs
+
+Triggers on: Bash commands containing "test" that exit successfully
+
+Returns:
+  - {"continue": true} with additionalContext prompting verification
+"""
+import json
+import sys
+import os
+import subprocess
+from datetime import datetime
+from pathlib import Path
+
+# State file is in .claude/ directory (sibling to hooks/)
+STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+# Scripts locations (try in order):
+# 1. Installed in project: scripts/api-dev-tools/
+# 2. In node_modules (if running from package)
+# 3. Package root (development)
+PROJECT_ROOT = Path(__file__).parent.parent.parent
+SCRIPTS_LOCATIONS = [
+    PROJECT_ROOT / "scripts" / "api-dev-tools",  # CLI-installed location
+    PROJECT_ROOT / "node_modules" / "@hustle-together" / "api-dev-tools" / "scripts",
+    Path(__file__).parent.parent.parent / "scripts",  # Development fallback
+]
+
+
+def run_manifest_scripts() -> dict:
+    """
+    Run the programmatic manifest generation scripts.
+
+    These scripts are 100% deterministic - they parse source files,
+    extract parameters from Zod schemas, and generate the manifest.
+    NO LLM involvement.
+
+    Returns dict with results of each script.
+    """
+    results = {
+        "manifest_generated": False,
+        "parameters_extracted": False,
+        "results_collected": False,
+        "errors": []
+    }
+
+    # Find the scripts directory (try multiple locations)
+    scripts_dir = None
+    for loc in SCRIPTS_LOCATIONS:
+        if loc.exists():
+            scripts_dir = loc
+            break
+
+    if scripts_dir is None:
+        results["errors"].append("Scripts directory not found in any expected location")
+        return results
+
+    project_root = PROJECT_ROOT
+
+    # Run generate-test-manifest.ts
+    manifest_script = scripts_dir / "generate-test-manifest.ts"
+    if manifest_script.exists():
+        try:
+            subprocess.run(
+                ["npx", "tsx", str(manifest_script), str(project_root)],
+                cwd=str(project_root),
+                capture_output=True,
+                text=True,
+                timeout=60
+            )
+            results["manifest_generated"] = True
+        except subprocess.TimeoutExpired:
+            results["errors"].append("Manifest generation timed out")
+        except Exception as e:
+            results["errors"].append(f"Manifest generation failed: {e}")
+
+    # Run extract-parameters.ts
+    params_script = scripts_dir / "extract-parameters.ts"
+    if params_script.exists():
+        try:
+            subprocess.run(
+                ["npx", "tsx", str(params_script), str(project_root)],
+                cwd=str(project_root),
+                capture_output=True,
+                text=True,
+                timeout=60
+            )
+            results["parameters_extracted"] = True
+        except subprocess.TimeoutExpired:
+            results["errors"].append("Parameter extraction timed out")
+        except Exception as e:
+            results["errors"].append(f"Parameter extraction failed: {e}")
+
+    # Run collect-test-results.ts (optional - only if tests were just run)
+    results_script = scripts_dir / "collect-test-results.ts"
+    if results_script.exists():
+        try:
+            subprocess.run(
+                ["npx", "tsx", str(results_script), str(project_root)],
+                cwd=str(project_root),
+                capture_output=True,
+                text=True,
+                timeout=120  # Test collection can take longer
+            )
+            results["results_collected"] = True
+        except subprocess.TimeoutExpired:
+            results["errors"].append("Test results collection timed out")
+        except Exception as e:
+            results["errors"].append(f"Test results collection failed: {e}")
+
+    return results
+
+
+def main():
+    # Read hook input from stdin
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+    tool_output = input_data.get("tool_output", {})
+
+    # Only trigger on Bash commands
+    if tool_name != "Bash":
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if this is a test command
+    command = tool_input.get("command", "")
+    is_test_command = any(test_keyword in command.lower() for test_keyword in [
+        "pnpm test", "npm test", "vitest", "jest", "pytest", "test:run"
+    ])
+
+    if not is_test_command:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if tests passed (exit code 0 or output indicates success)
+    output_text = ""
+    if isinstance(tool_output, str):
+        output_text = tool_output
+    elif isinstance(tool_output, dict):
+        output_text = tool_output.get("output", tool_output.get("stdout", ""))
+
+    # Look for success indicators
+    tests_passed = any(indicator in output_text.lower() for indicator in [
+        "tests passed", "all tests passed", "test suites passed",
+        "✓", "passed", "0 failed", "pass"
+    ]) and not any(fail in output_text.lower() for fail in [
+        "failed", "error", "fail"
+    ])
+
+    if not tests_passed:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Tests passed - run manifest generation scripts
+    manifest_output = run_manifest_scripts()
+
+    # Tests passed - check state file
+    if not STATE_FILE.exists():
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    try:
+        state = json.loads(STATE_FILE.read_text())
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    phases = state.get("phases", {})
+    tdd_green = phases.get("tdd_green", {})
+    verify = phases.get("verify", {})
+
+    # Check if we're in TDD Green phase
+    if tdd_green.get("status") != "in_progress":
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if verify phase already done
+    if verify.get("status") == "complete":
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Mark TDD Green as complete
+    tdd_green["status"] = "complete"
+    tdd_green["all_tests_passing"] = True
+    tdd_green["completed_at"] = datetime.now().isoformat()
+
+    # Start verify phase
+    verify["status"] = "in_progress"
+    verify["started_at"] = datetime.now().isoformat()
+
+    # Update manifest_generation section in state
+    if "manifest_generation" not in state:
+        state["manifest_generation"] = {}
+
+    state["manifest_generation"]["last_run"] = datetime.now().isoformat()
+    state["manifest_generation"]["manifest_generated"] = manifest_output.get("manifest_generated", False)
+    state["manifest_generation"]["parameters_extracted"] = manifest_output.get("parameters_extracted", False)
+    state["manifest_generation"]["test_results_collected"] = manifest_output.get("results_collected", False)
+
+    # Save state
+    STATE_FILE.write_text(json.dumps(state, indent=2))
+
+    # Build verification prompt
+    endpoint = state.get("endpoint", "the endpoint")
+
+    context_parts = []
+
+    # Report manifest generation results
+    if manifest_output.get("manifest_generated"):
+        context_parts.append("## ✅ Manifest Generation Complete")
+        context_parts.append("")
+        context_parts.append("Programmatically generated from test files (no LLM):")
+        if manifest_output.get("manifest_generated"):
+            context_parts.append("  - ✓ api-tests-manifest.json")
+        if manifest_output.get("parameters_extracted"):
+            context_parts.append("  - ✓ parameter-matrix.json")
+        if manifest_output.get("results_collected"):
+            context_parts.append("  - ✓ test-results.json")
+        if manifest_output.get("errors"):
+            context_parts.append("")
+            context_parts.append("⚠️ Some scripts had issues:")
+            for err in manifest_output["errors"]:
+                context_parts.append(f"  - {err}")
+        context_parts.append("")
+        context_parts.append("---")
+        context_parts.append("")
+
+    context_parts.append("## Phase 9: Implementation Verification Required")
+    context_parts.append("")
+    context_parts.append("Tests are passing. Before proceeding, you MUST verify your implementation:")
+    context_parts.append("")
+    context_parts.append("**Required Actions:**")
+    context_parts.append("1. Re-read the original API documentation (use Context7 or WebSearch)")
+    context_parts.append("2. Compare EVERY documented parameter/feature to your implementation")
+    context_parts.append("3. Report any discrepancies in this format:")
+    context_parts.append("")
+    context_parts.append("```")
+    context_parts.append("| Feature          | In Docs | Implemented | Status          |")
+    context_parts.append("|------------------|---------|-------------|-----------------|")
+    context_parts.append("| param_name       | Yes     | Yes         | Match           |")
+    context_parts.append("| missing_param    | Yes     | No          | MISSING         |")
+    context_parts.append("| extra_param      | No      | Yes         | EXTRA (OK)      |")
+    context_parts.append("```")
+    context_parts.append("")
+    context_parts.append("**After comparison, ask the user:**")
+    context_parts.append("- Fix gaps? [Y] - Loop back to Red phase")
+    context_parts.append("- Skip (intentional omissions)? [n] - Document and proceed")
+    context_parts.append("")
+    context_parts.append("DO NOT proceed to Refactor until verification is complete.")
+
+    output = {
+        "continue": True,
+        "hookSpecificOutput": {
+            "hookEventName": "PostToolUse",
+            "additionalContext": "\n".join(context_parts)
+        }
+    }
+
+    print(json.dumps(output))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hustle-together/api-dev-tools",
-  "version": "2.0.7",
-  "description": "Interview-driven API development workflow for Claude Code - Automates research, testing, and documentation",
+  "version": "3.1.0",
+  "description": "Interview-driven, research-first API development workflow with continuous verification loops for Claude Code",
   "main": "bin/cli.js",
   "bin": {
     "api-dev-tools": "./bin/cli.js"
@@ -10,6 +10,7 @@
     "bin/",
     "commands/",
     "hooks/",
+    "scripts/",
     "templates/",
     "demo/",
     "README.md",

package/scripts/collect-test-results.ts

@@ -0,0 +1,404 @@
+#!/usr/bin/env npx tsx
+/**
+ * Collect Test Results Script
+ *
+ * Runs Vitest and collects results programmatically.
+ * Updates the manifest with actual pass/fail status.
+ *
+ * IMPORTANT: This is 100% programmatic - NO LLM involvement.
+ * Tests are executed and results are collected automatically.
+ *
+ * @generated by @hustle-together/api-dev-tools v3.0
+ */
+
+import { execSync, spawn } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+
+// ============================================
+// Types
+// ============================================
+
+interface TestResult {
+  name: string;
+  file: string;
+  status: 'passed' | 'failed' | 'skipped';
+  duration: number;
+  error?: string;
+}
+
+interface TestSuiteResult {
+  file: string;
+  tests: TestResult[];
+  passed: number;
+  failed: number;
+  skipped: number;
+  duration: number;
+}
+
+interface CollectedResults {
+  version: string;
+  collectedAt: string;
+  suites: TestSuiteResult[];
+  summary: {
+    totalSuites: number;
+    totalTests: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    duration: number;
+    success: boolean;
+  };
+}
+
+// ============================================
+// Vitest Output Parser
+// ============================================
+
+function parseVitestJson(jsonOutput: string): CollectedResults {
+  try {
+    const data = JSON.parse(jsonOutput);
+
+    const suites: TestSuiteResult[] = [];
+    let totalPassed = 0;
+    let totalFailed = 0;
+    let totalSkipped = 0;
+    let totalDuration = 0;
+
+    // Parse Vitest JSON reporter output
+    if (data.testResults) {
+      for (const fileResult of data.testResults) {
+        const suite: TestSuiteResult = {
+          file: fileResult.name || fileResult.filepath,
+          tests: [],
+          passed: 0,
+          failed: 0,
+          skipped: 0,
+          duration: fileResult.duration || 0
+        };
+
+        if (fileResult.assertionResults) {
+          for (const test of fileResult.assertionResults) {
+            const result: TestResult = {
+              name: test.title || test.fullName,
+              file: suite.file,
+              status: test.status === 'passed' ? 'passed' :
+                      test.status === 'failed' ? 'failed' : 'skipped',
+              duration: test.duration || 0
+            };
+
+            if (test.failureMessages && test.failureMessages.length > 0) {
+              result.error = test.failureMessages.join('\n');
+            }
+
+            suite.tests.push(result);
+
+            if (result.status === 'passed') suite.passed++;
+            else if (result.status === 'failed') suite.failed++;
+            else suite.skipped++;
+          }
+        }
+
+        totalPassed += suite.passed;
+        totalFailed += suite.failed;
+        totalSkipped += suite.skipped;
+        totalDuration += suite.duration;
+
+        suites.push(suite);
+      }
+    }
+
+    return {
+      version: '3.0.0',
+      collectedAt: new Date().toISOString(),
+      suites,
+      summary: {
+        totalSuites: suites.length,
+        totalTests: totalPassed + totalFailed + totalSkipped,
+        passed: totalPassed,
+        failed: totalFailed,
+        skipped: totalSkipped,
+        duration: totalDuration,
+        success: totalFailed === 0
+      }
+    };
+  } catch (error) {
+    throw new Error(`Failed to parse Vitest JSON output: ${error}`);
+  }
+}
+
+// ============================================
+// Console Output Parser (Fallback)
+// ============================================
+
+function parseVitestConsole(output: string): CollectedResults {
+  const suites: TestSuiteResult[] = [];
+  let currentSuite: TestSuiteResult | null = null;
+
+  const lines = output.split('\n');
+
+  for (const line of lines) {
+    // Match file header: ✓ src/path/file.test.ts (5 tests) 123ms
+    const fileMatch = line.match(/[✓✗◯]\s+([^\s]+\.(?:test|spec)\.tsx?)\s+\((\d+)\s+tests?\)/);
+    if (fileMatch) {
+      if (currentSuite) {
+        suites.push(currentSuite);
+      }
+
+      const durationMatch = line.match(/(\d+)ms$/);
+
+      currentSuite = {
+        file: fileMatch[1],
+        tests: [],
+        passed: 0,
+        failed: 0,
+        skipped: 0,
+        duration: durationMatch ? parseInt(durationMatch[1]) : 0
+      };
+      continue;
+    }
+
+    // Match test result: ✓ should do something (5ms)
+    const testMatch = line.match(/^\s*([✓✗◯⊘])\s+(.+?)(?:\s+\((\d+)ms\))?$/);
+    if (testMatch && currentSuite) {
+      const [, icon, name, duration] = testMatch;
+
+      const status: 'passed' | 'failed' | 'skipped' =
+        icon === '✓' ? 'passed' :
+        icon === '✗' ? 'failed' : 'skipped';
+
+      currentSuite.tests.push({
+        name,
+        file: currentSuite.file,
+        status,
+        duration: duration ? parseInt(duration) : 0
+      });
+
+      if (status === 'passed') currentSuite.passed++;
+      else if (status === 'failed') currentSuite.failed++;
+      else currentSuite.skipped++;
+    }
+  }
+
+  if (currentSuite) {
+    suites.push(currentSuite);
+  }
+
+  // Calculate summary
+  const summary = suites.reduce((acc, suite) => ({
+    totalSuites: acc.totalSuites + 1,
+    totalTests: acc.totalTests + suite.tests.length,
+    passed: acc.passed + suite.passed,
+    failed: acc.failed + suite.failed,
+    skipped: acc.skipped + suite.skipped,
+    duration: acc.duration + suite.duration,
+    success: acc.success && suite.failed === 0
+  }), {
+    totalSuites: 0,
+    totalTests: 0,
+    passed: 0,
+    failed: 0,
+    skipped: 0,
+    duration: 0,
+    success: true
+  });
+
+  return {
+    version: '3.0.0',
+    collectedAt: new Date().toISOString(),
+    suites,
+    summary
+  };
+}
+
+// ============================================
+// Test Runner
+// ============================================
+
+function runVitest(baseDir: string, filter?: string): CollectedResults {
+  console.log('🧪 Running Vitest...');
+
+  const vitestArgs = ['vitest', 'run', '--reporter=json'];
+  if (filter) {
+    vitestArgs.push(filter);
+  }
+
+  try {
+    // Try running with JSON reporter
+    const result = execSync(`npx ${vitestArgs.join(' ')}`, {
+      cwd: baseDir,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      maxBuffer: 50 * 1024 * 1024 // 50MB buffer
+    });
+
+    return parseVitestJson(result);
+  } catch (error: unknown) {
+    // Vitest may exit with non-zero on test failures
+    // Try to parse the output anyway
+    const execError = error as { stdout?: string; stderr?: string };
+    if (execError.stdout) {
+      try {
+        return parseVitestJson(execError.stdout);
+      } catch {
+        // Fall back to console parsing
+        return parseVitestConsole(execError.stdout);
+      }
+    }
+
+    // Try fallback: run without JSON reporter
+    console.log('   ⚠️  JSON reporter failed, trying console output...');
+
+    try {
+      const consoleResult = execSync(`npx vitest run ${filter || ''}`, {
+        cwd: baseDir,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+
+      return parseVitestConsole(consoleResult);
+    } catch (fallbackError: unknown) {
+      const fbError = fallbackError as { stdout?: string };
+      if (fbError.stdout) {
+        return parseVitestConsole(fbError.stdout);
+      }
+      throw error;
+    }
+  }
+}
+
+// ============================================
+// Manifest Updater
+// ============================================
+
+function updateManifest(manifestPath: string, results: CollectedResults): void {
+  if (!fs.existsSync(manifestPath)) {
+    console.log('   ⚠️  Manifest not found, skipping update');
+    return;
+  }
+
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+
+  // Create a map of test results by file
+  const resultsByFile = new Map<string, TestSuiteResult>();
+  for (const suite of results.suites) {
+    const basename = path.basename(suite.file);
+    resultsByFile.set(basename, suite);
+  }
+
+  // Update each endpoint's test status
+  if (manifest.endpoints) {
+    for (const endpoint of manifest.endpoints) {
+      const testBasename = path.basename(endpoint.testFile || '');
+      const suiteResult = resultsByFile.get(testBasename);
+
+      if (suiteResult) {
+        endpoint.testResults = {
+          passed: suiteResult.passed,
+          failed: suiteResult.failed,
+          skipped: suiteResult.skipped,
+          duration: suiteResult.duration,
+          lastRun: results.collectedAt
+        };
+      }
+    }
+  }
+
+  // Update summary
+  manifest.lastTestRun = {
+    ...results.summary,
+    timestamp: results.collectedAt
+  };
+
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+  console.log(`   ✅ Updated manifest with test results`);
+}
+
+// ============================================
+// CLI Entry Point
+// ============================================
+
+function main() {
+  const args = process.argv.slice(2);
+  const baseDir = args[0] || process.cwd();
+  const filter = args[1] || undefined;
+  const outputPath = args[2] || path.join(baseDir, 'src', 'app', 'api-test', 'test-results.json');
+  const manifestPath = path.join(baseDir, 'src', 'app', 'api-test', 'api-tests-manifest.json');
+
+  console.log('═══════════════════════════════════════════════════════════════');
+  console.log('  🧪 Test Results Collector');
+  console.log('  @hustle-together/api-dev-tools v3.0');
+  console.log('═══════════════════════════════════════════════════════════════');
+  console.log(`\n📁 Base directory: ${baseDir}`);
+  if (filter) {
+    console.log(`🔍 Filter: ${filter}`);
+  }
+  console.log(`📄 Output file: ${outputPath}\n`);
+
+  try {
+    const results = runVitest(baseDir, filter);
+
+    // Ensure output directory exists
+    const outputDir = path.dirname(outputPath);
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    }
+
+    // Write results
+    fs.writeFileSync(outputPath, JSON.stringify(results, null, 2));
+
+    // Update manifest with results
+    updateManifest(manifestPath, results);
+
+    console.log('\n═══════════════════════════════════════════════════════════════');
+    if (results.summary.success) {
+      console.log('  ✅ All tests passed!');
+    } else {
+      console.log('  ❌ Some tests failed');
+    }
+    console.log('═══════════════════════════════════════════════════════════════');
+
+    console.log(`\n📊 Summary:`);
+    console.log(`   • Suites: ${results.summary.totalSuites}`);
+    console.log(`   • Tests: ${results.summary.totalTests}`);
+    console.log(`   • Passed: ${results.summary.passed} ✓`);
+    if (results.summary.failed > 0) {
+      console.log(`   • Failed: ${results.summary.failed} ✗`);
+    }
+    if (results.summary.skipped > 0) {
+      console.log(`   • Skipped: ${results.summary.skipped} ⊘`);
+    }
+    console.log(`   • Duration: ${results.summary.duration}ms`);
+
+    // List failed tests
+    const failedTests = results.suites.flatMap(suite =>
+      suite.tests.filter(t => t.status === 'failed').map(t => ({
+        file: suite.file,
+        name: t.name,
+        error: t.error
+      }))
+    );
+
+    if (failedTests.length > 0) {
+      console.log(`\n❌ Failed tests:`);
+      for (const test of failedTests) {
+        console.log(`   • ${test.file}: ${test.name}`);
+        if (test.error) {
+          console.log(`     ${test.error.split('\n')[0]}`);
+        }
+      }
+    }
+
+    console.log(`\n📄 Results: ${outputPath}`);
+    console.log(`📄 Manifest: ${manifestPath}\n`);
+
+    // Exit with appropriate code
+    process.exit(results.summary.success ? 0 : 1);
+
+  } catch (error) {
+    console.error('\n❌ Failed to collect test results:', error);
+    process.exit(1);
+  }
+}
+
+main();