@hustle-together/api-dev-tools 3.0.0 → 3.2.0

package/hooks/enforce-tdd-red.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit
+Purpose: Block writing implementation if test matrix not approved WITH USER CONFIRMATION
+
+Phase 7 (TDD Red) requires:
+  1. Propose test matrix based on interview + schema
+  2. SHOW test plan to user (scenarios, edge cases, coverage)
+  3. USE AskUserQuestion: "Test plan looks good? [Y/n]"
+  4. Loop back if user wants more tests
+  5. Only allow route.ts after user approves test matrix
+
+Returns:
+  - {"permissionDecision": "allow"} - Let the tool run
+  - {"permissionDecision": "deny", "reason": "..."} - Block with explanation
+"""
+import json
+import sys
+from pathlib import Path
+
+# State file is in .claude/ directory (sibling to hooks/)
+STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+
+
+def find_test_file(route_path: str) -> tuple[bool, str]:
+    """Check if a test file exists for the given route file."""
+    route_file = Path(route_path)
+
+    # Common test file patterns
+    # route.ts -> route.test.ts, __tests__/route.test.ts, route.spec.ts
+    possible_tests = [
+        route_file.with_suffix(".test.ts"),
+        route_file.with_suffix(".test.tsx"),
+        route_file.with_suffix(".spec.ts"),
+        route_file.parent / "__tests__" / f"{route_file.stem}.test.ts",
+        route_file.parent / "__tests__" / f"{route_file.stem}.test.tsx",
+        route_file.parent.parent / "__tests__" / f"{route_file.parent.name}.test.ts",
+    ]
+
+    for test_path in possible_tests:
+        if test_path.exists():
+            return True, str(test_path)
+
+    return False, str(possible_tests[0])  # Return expected path
+
+
+def main():
+    # Read hook input from stdin
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    tool_input = input_data.get("tool_input", {})
+    file_path = tool_input.get("file_path", "")
+
+    # Only enforce for route.ts files in /api/ directories
+    if not file_path.endswith("route.ts") or "/api/" not in file_path:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Allow if this IS a test file (shouldn't match but safety check)
+    if ".test." in file_path or "/__tests__/" in file_path or ".spec." in file_path:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Check if state file exists
+    if not STATE_FILE.exists():
+        # Even without state, enforce TDD
+        test_exists, expected_path = find_test_file(file_path)
+        if not test_exists:
+            print(json.dumps({
+                "permissionDecision": "deny",
+                "reason": f"""❌ TDD VIOLATION: No test file found!
+
+You're trying to write: {file_path}
+
+But the test file doesn't exist: {expected_path}
+
+═══════════════════════════════════════════════════════════
+⚠️  WRITE TESTS FIRST (TDD Red Phase)
+═══════════════════════════════════════════════════════════
+
+TDD requires:
+  1. Write a FAILING test first
+  2. THEN write implementation to make it pass
+
+Create the test file first:
+  {expected_path}
+
+Example test structure:
+  import {{ describe, it, expect }} from 'vitest';
+
+  describe('POST /api/...', () => {{
+    it('should return 200 with valid input', async () => {{
+      // Test implementation
+    }});
+
+    it('should return 400 with invalid input', async () => {{
+      // Test validation
+    }});
+  }});"""
+            }))
+            sys.exit(0)
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Load state
+    try:
+        state = json.loads(STATE_FILE.read_text())
+    except json.JSONDecodeError:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    phases = state.get("phases", {})
+    tdd_red = phases.get("tdd_red", {})
+    tdd_red_status = tdd_red.get("status", "not_started")
+    test_count = tdd_red.get("test_count", 0)
+
+    # Get user checkpoint fields
+    user_question_asked = tdd_red.get("user_question_asked", False)
+    user_approved = tdd_red.get("user_approved", False)
+    matrix_shown = tdd_red.get("matrix_shown", False)
+    test_scenarios = tdd_red.get("test_scenarios", [])
+
+    # Check if TDD Red phase is complete
+    if tdd_red_status != "complete":
+        test_exists, expected_path = find_test_file(file_path)
+
+        # Check what's missing for user checkpoint
+        missing = []
+        if not test_exists:
+            missing.append("Test file not created yet")
+        if not matrix_shown:
+            missing.append("Test matrix not shown to user")
+        if not user_question_asked:
+            missing.append("User approval question (AskUserQuestion not used)")
+        if not user_approved:
+            missing.append("User hasn't approved the test plan")
+
+        print(json.dumps({
+            "permissionDecision": "deny",
+            "reason": f"""❌ BLOCKED: TDD Red phase (Phase 7) not complete.
+
+Current status: {tdd_red_status}
+Test count: {test_count}
+Test file exists: {test_exists}
+Matrix shown: {matrix_shown}
+User question asked: {user_question_asked}
+User approved: {user_approved}
+Scenarios: {len(test_scenarios)}
+
+MISSING:
+{chr(10).join(f"  • {m}" for m in missing)}
+
+═══════════════════════════════════════════════════════════
+⚠️  GET USER APPROVAL FOR TEST MATRIX
+═══════════════════════════════════════════════════════════
+
+REQUIRED STEPS:
+
+1. PROPOSE test matrix based on interview + schema:
+   ┌───────────────────────────────────────────────────────┐
+   │ TEST MATRIX                                           │
+   │                                                       │
+   │ Based on your interview, I'll test:                   │
+   │                                                       │
+   │ ✅ Success Scenarios:                                 │
+   │    • GET with valid domain → 200 + brand data        │
+   │    • POST with full payload → 200 + created          │
+   │                                                       │
+   │ ✅ Error Scenarios (your choice: return objects):    │
+   │    • Invalid domain → 400 + error object             │
+   │    • Missing API key → 401 + error object            │
+   │    • Not found → 404 + error object                  │
+   │                                                       │
+   │ ✅ Edge Cases:                                        │
+   │    • Rate limit exceeded → 429 + retry-after         │
+   │    • Cache hit → 200 + cached: true                  │
+   │    • Empty response → 200 + empty data               │
+   │                                                       │
+   │ Total: 8 test scenarios                               │
+   │                                                       │
+   │ Test plan looks good? [Y]                             │
+   │ Add more tests? [n] ____                              │
+   └───────────────────────────────────────────────────────┘
+
+2. USE AskUserQuestion:
+   question: "This test plan cover your requirements?"
+   options: [
+     {{"value": "approve", "label": "Yes, write these tests"}},
+     {{"value": "add", "label": "Add more - I also need [scenario]"}},
+     {{"value": "modify", "label": "Change a scenario - [which one]"}}
+   ]
+
+3. If user says "add" or "modify":
+   • Update test_scenarios list
+   • LOOP BACK and show updated matrix
+
+4. If user says "approve":
+   • Create test file: {expected_path}
+   • Write all approved test scenarios
+   • Run tests to confirm they FAIL (red)
+   • Set tdd_red.user_approved = true
+   • Set tdd_red.user_question_asked = true
+   • Set tdd_red.matrix_shown = true
+   • Set tdd_red.test_count = N
+   • Set tdd_red.status = "complete"
+
+Based on interview decisions:
+{_format_interview_hints(phases.get("interview", {}))}
+
+WHY: User approves what gets tested BEFORE implementation."""
+        }))
+        sys.exit(0)
+
+    # TDD Red complete - allow implementation
+    print(json.dumps({
+        "permissionDecision": "allow",
+        "message": f"""✅ TDD Red phase complete.
+{test_count} tests written and failing.
+User approved {len(test_scenarios)} test scenarios.
+Proceeding to Green phase - make them pass!"""
+    }))
+    sys.exit(0)
+
+
+def _format_interview_hints(interview: dict) -> str:
+    """Format interview decisions as test hints."""
+    decisions = interview.get("decisions", {})
+    if not decisions:
+        return "  (no interview decisions recorded)"
+
+    hints = []
+    for key, data in list(decisions.items())[:5]:
+        value = data.get("value", data.get("response", ""))
+        if value:
+            short_value = str(value)[:50] + "..." if len(str(value)) > 50 else str(value)
+            hints.append(f"  • {key}: {short_value}")
+
+    return "\n".join(hints) if hints else "  (no interview decisions recorded)"
+
+
+if __name__ == "__main__":
+    main()

package/hooks/enforce-verify.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit
+Purpose: Block refactoring until verification complete WITH USER GAP DECISION
+
+Phase 9 (Verify) requires:
+  1. Re-read original documentation (after tests pass)
+  2. Compare implementation to docs - find gaps
+  3. SHOW gap analysis to user
+  4. USE AskUserQuestion: "Fix gaps? [Y] / Skip? [n]"
+  5. Loop back to Phase 7 if user wants fixes
+  6. Only proceed to refactor when user decides
+
+Returns:
+  - {"permissionDecision": "allow"} - Let the tool run
+  - {"permissionDecision": "deny", "reason": "..."} - Block with explanation
+"""
+import json
+import sys
+from pathlib import Path
+
+STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    tool_input = input_data.get("tool_input", {})
+    file_path = tool_input.get("file_path", "")
+
+    # Only enforce for API route files
+    is_api_file = "/api/" in file_path and file_path.endswith(".ts")
+
+    if not is_api_file:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Skip test files
+    if ".test." in file_path or "/__tests__/" in file_path or ".spec." in file_path:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Skip documentation/config files
+    if file_path.endswith(".md") or file_path.endswith(".json"):
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    if not STATE_FILE.exists():
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    try:
+        state = json.loads(STATE_FILE.read_text())
+    except json.JSONDecodeError:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    endpoint = state.get("endpoint", "unknown")
+    phases = state.get("phases", {})
+    tdd_green = phases.get("tdd_green", {})
+    verify = phases.get("verify", {})
+
+    # Only enforce after TDD Green is complete
+    if tdd_green.get("status") != "complete":
+        # Let earlier hooks handle this
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    status = verify.get("status", "not_started")
+
+    if status != "complete":
+        user_question_asked = verify.get("user_question_asked", False)
+        user_decided = verify.get("user_decided", False)
+        gap_analysis_shown = verify.get("gap_analysis_shown", False)
+        re_research_done = verify.get("re_research_done", False)
+        gaps_found = verify.get("gaps_found", 0)
+        gaps_fixed = verify.get("gaps_fixed", 0)
+        gaps_skipped = verify.get("gaps_skipped", 0)
+        user_decision = verify.get("user_decision", None)
+
+        missing = []
+        if not re_research_done:
+            missing.append("Re-research original docs not done")
+        if not gap_analysis_shown:
+            missing.append("Gap analysis not shown to user")
+        if not user_question_asked:
+            missing.append("User gap decision question (AskUserQuestion not used)")
+        if not user_decided:
+            missing.append("User hasn't decided on gaps")
+
+        print(json.dumps({
+            "permissionDecision": "deny",
+            "reason": f"""❌ BLOCKED: Verification (Phase 9) not complete.
+
+Status: {status}
+Re-research done: {re_research_done}
+Gap analysis shown: {gap_analysis_shown}
+User question asked: {user_question_asked}
+User decided: {user_decided}
+User decision: {user_decision or "None yet"}
+Gaps found: {gaps_found}
+Gaps fixed: {gaps_fixed}
+Gaps skipped: {gaps_skipped}
+
+MISSING:
+{chr(10).join(f"  • {m}" for m in missing)}
+
+═══════════════════════════════════════════════════════════
+⚠️  GET USER DECISION ON IMPLEMENTATION GAPS
+═══════════════════════════════════════════════════════════
+
+REQUIRED STEPS:
+
+1. Re-read the ORIGINAL API documentation:
+   • Use Context7 or WebSearch with SAME queries from Phase 2
+   • Compare EVERY documented feature to your implementation
+   • Don't rely on memory - actually re-read the docs
+
+2. Create and SHOW gap analysis table:
+   ┌───────────────────────────────────────────────────────┐
+   │ VERIFICATION RESULTS                                  │
+   │                                                       │
+   │ │ Feature         │ In Docs │ Implemented │ Status   │
+   │ ├─────────────────┼─────────┼─────────────┼──────────│
+   │ │ domain param    │ Yes     │ Yes         │ ✓ Match  │
+   │ │ format option   │ Yes     │ Yes         │ ✓ Match  │
+   │ │ include_fonts   │ Yes     │ No          │ ❌ GAP   │
+   │ │ webhook_url     │ No      │ Yes         │ ⚠ Extra │
+   │                                                       │
+   │ Found 1 gap in implementation.                        │
+   │                                                       │
+   │ Fix the gap? [Y] - Loop back to add missing feature  │
+   │ Skip? [n] - Document as intentional omission          │
+   └───────────────────────────────────────────────────────┘
+
+3. USE AskUserQuestion:
+   question: "I found {gaps_found} gap(s). How should I proceed?"
+   options: [
+     {{"value": "fix", "label": "Fix gaps - loop back to Red phase"}},
+     {{"value": "skip", "label": "Skip - these are intentional omissions"}},
+     {{"value": "partial", "label": "Fix some, skip others - [specify]"}}
+   ]
+
+4. If user says "fix":
+   • Loop back to Phase 7 (TDD Red)
+   • Write new tests for missing features
+   • Implement and verify again
+   • REPEAT until no gaps or user says skip
+
+5. If user says "skip":
+   • Document each skipped gap with reason
+   • Set verify.gaps_skipped = count
+   • Proceed to refactor
+
+6. After user decides:
+   • Set verify.user_decided = true
+   • Set verify.user_question_asked = true
+   • Set verify.gap_analysis_shown = true
+   • Set verify.re_research_done = true
+   • Set verify.user_decision = "fix" or "skip" or "partial"
+   • Set verify.status = "complete"
+
+WHY: Catch memory-based implementation errors BEFORE refactoring."""
+        }))
+        sys.exit(0)
+
+    # Verify complete
+    user_decision = verify.get("user_decision", "unknown")
+    print(json.dumps({
+        "permissionDecision": "allow",
+        "message": f"""✅ Verification complete.
+User decision: {user_decision}
+Gaps found: {gaps_found}
+Gaps fixed: {gaps_fixed}
+Gaps skipped (intentional): {gaps_skipped}
+Proceeding to refactor phase."""
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/verify-after-green.py

@@ -1,15 +1,17 @@
 #!/usr/bin/env python3
 """
 Hook: PostToolUse (after test runs)
-Purpose: Trigger Phase 9 (Verify) after tests pass - force re-research
+Purpose: Trigger Phase 9 (Verify) + Manifest Generation after tests pass
 
 This hook detects when tests pass (TDD Green phase complete) and:
-  1. Reminds Claude to re-research the original documentation
-  2. Compares implemented features to documented features
-  3. Requires user confirmation before proceeding
+  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 catch cases where Claude implemented from memory
-instead of from the researched documentation.
+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
 
@@ -19,11 +21,106 @@ Returns:
 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():
@@ -72,6 +169,9 @@ def main():
         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}))
@@ -106,6 +206,15 @@ def main():
     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))
 
@@ -113,6 +222,27 @@ def main():
     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:")

package/package.json

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