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

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.1.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",