@hustle-together/api-dev-tools 3.10.1 → 3.11.1

package/.claude/hooks/enforce-tdd-red.py

@@ -0,0 +1,250 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit
+Purpose: Block writing implementation if test matrix not approved WITH USER CONFIRMATION
+
+Phase 8 (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", [])
+    phase_exit_confirmed = tdd_red.get("phase_exit_confirmed", False)
+
+    # Check if TDD Red phase is complete
+    if tdd_red_status != "complete" or not phase_exit_confirmed:
+        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")
+        if not phase_exit_confirmed:
+            missing.append("Phase exit confirmation (user must explicitly approve to proceed)")
+
+        print(json.dumps({
+            "permissionDecision": "deny",
+            "reason": f"""❌ BLOCKED: TDD Red phase (Phase 8) 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}
+Phase exit confirmed: {phase_exit_confirmed}
+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/.claude/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 10 (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 8 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 10) 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 3
+   • 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 8 (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/.claude/hooks/periodic-reground.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""
+Hook: PostToolUse (for periodic re-grounding)
+Purpose: Inject context reminders every N turns to prevent context dilution
+
+This hook tracks turn count and periodically injects a summary of:
+  - Current endpoint and phase
+  - Key decisions from interview
+  - Research cache status
+  - Important file locations
+
+The goal is to keep Claude grounded during long sessions where
+the original CLAUDE.md context may get diluted.
+
+Configuration:
+  - REGROUND_INTERVAL: Number of turns between re-grounding (default: 7)
+
+Returns:
+  - {"continue": true} with optional additionalContext on reground turns
+"""
+import json
+import sys
+import os
+from datetime import datetime
+from pathlib import Path
+
+# Configuration
+REGROUND_INTERVAL = 7  # Re-ground every N turns
+
+# State file is in .claude/ directory (sibling to hooks/)
+STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+
+
+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)
+
+    # Check if state file exists
+    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)
+
+    # Increment turn count
+    turn_count = state.get("turn_count", 0) + 1
+    state["turn_count"] = turn_count
+    state["last_turn_timestamp"] = datetime.now().isoformat()
+
+    # Check if we should re-ground
+    should_reground = turn_count % REGROUND_INTERVAL == 0
+
+    if should_reground and state.get("endpoint"):
+        # Build re-grounding context
+        context_parts = []
+        context_parts.append(f"## Re-Grounding Reminder (Turn {turn_count})")
+        context_parts.append("")
+
+        endpoint = state.get("endpoint", "unknown")
+        context_parts.append(f"**Active Endpoint:** {endpoint}")
+
+        # Get current phase
+        phases = state.get("phases", {})
+        phase_order = [
+            "disambiguation", "scope", "research_initial", "interview",
+            "research_deep", "schema_creation", "environment_check",
+            "tdd_red", "tdd_green", "verify", "tdd_refactor", "documentation"
+        ]
+
+        current_phase = None
+        completed_phases = []
+        for phase_name in phase_order:
+            phase = phases.get(phase_name, {})
+            status = phase.get("status", "not_started")
+            if status == "complete":
+                completed_phases.append(phase_name)
+            elif status == "in_progress" and not current_phase:
+                current_phase = phase_name
+
+        if not current_phase:
+            # Find first not_started phase
+            for phase_name in phase_order:
+                phase = phases.get(phase_name, {})
+                if phase.get("status", "not_started") == "not_started":
+                    current_phase = phase_name
+                    break
+
+        context_parts.append(f"**Current Phase:** {current_phase or 'documentation'}")
+        context_parts.append(f"**Completed:** {', '.join(completed_phases) if completed_phases else 'None'}")
+
+        # Key decisions summary
+        interview = phases.get("interview", {})
+        decisions = interview.get("decisions", {})
+        if decisions:
+            context_parts.append("")
+            context_parts.append("**Key Decisions:**")
+            for key, value in list(decisions.items())[:5]:  # Limit to 5 key decisions
+                response = value.get("value", value.get("response", "N/A"))
+                if response:
+                    context_parts.append(f"  - {key}: {str(response)[:50]}")
+
+        # Research freshness warning
+        research_index = state.get("research_index", {})
+        if endpoint in research_index:
+            entry = research_index[endpoint]
+            days_old = entry.get("days_old", 0)
+            if days_old > 7:
+                context_parts.append("")
+                context_parts.append(f"**WARNING:** Research is {days_old} days old. Consider re-researching.")
+
+        # File reminders
+        context_parts.append("")
+        context_parts.append("**Key Files:** .claude/api-dev-state.json, .claude/research/")
+
+        # Add to reground history
+        reground_history = state.setdefault("reground_history", [])
+        reground_history.append({
+            "turn": turn_count,
+            "timestamp": datetime.now().isoformat(),
+            "phase": current_phase
+        })
+        # Keep only last 10 reground events
+        state["reground_history"] = reground_history[-10:]
+
+        # Save state
+        STATE_FILE.write_text(json.dumps(state, indent=2))
+
+        # Output with context injection
+        output = {
+            "continue": True,
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": "\n".join(context_parts)
+            }
+        }
+        print(json.dumps(output))
+    else:
+        # Just update turn count and continue
+        STATE_FILE.write_text(json.dumps(state, indent=2))
+        print(json.dumps({"continue": True}))
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()