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

package/hooks/enforce-environment.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit
+Purpose: Block writing if environment not verified WITH USER READINESS CONFIRMATION
+
+Phase 6 requires:
+  1. Check required API keys based on endpoint/interview
+  2. Report found/missing keys to user
+  3. USE AskUserQuestion: "Ready for testing? [Y/n]"
+  4. Only proceed to TDD when user confirms readiness
+
+Returns:
+  - {"permissionDecision": "allow"} - Let the tool run
+  - {"permissionDecision": "deny", "reason": "..."} - Block with explanation
+"""
+import json
+import os
+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"
+
+# Common API key patterns to check
+COMMON_KEY_PATTERNS = {
+    "openai": ["OPENAI_API_KEY", "NEXT_PUBLIC_OPENAI_API_KEY"],
+    "anthropic": ["ANTHROPIC_API_KEY", "NEXT_PUBLIC_ANTHROPIC_API_KEY"],
+    "google": ["GOOGLE_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY"],
+    "brandfetch": ["BRANDFETCH_API_KEY"],
+    "firecrawl": ["FIRECRAWL_API_KEY"],
+    "brave": ["BRAVE_SEARCH_API_KEY"],
+    "perplexity": ["PERPLEXITY_API_KEY"],
+    "exa": ["EXA_API_KEY"],
+    "cartesia": ["CARTESIA_API_KEY"],
+    "elevenlabs": ["ELEVENLABS_API_KEY"],
+    "unsplash": ["UNSPLASH_ACCESS_KEY"],
+    "pexels": ["PEXELS_API_KEY"],
+    "supabase": ["SUPABASE_URL", "SUPABASE_ANON_KEY", "SUPABASE_SERVICE_ROLE_KEY"],
+}
+
+
+def check_env_keys(required_keys: list) -> tuple[list, list]:
+    """Check which keys exist and which are missing."""
+    found = []
+    missing = []
+
+    for key in required_keys:
+        if os.environ.get(key):
+            found.append(key)
+        else:
+            missing.append(key)
+
+    return found, missing
+
+
+def infer_required_keys(endpoint: str, external_services: list) -> list:
+    """Infer required API keys from endpoint name and external services."""
+    required = []
+
+    # Check endpoint name against common patterns
+    endpoint_lower = endpoint.lower()
+    for service, keys in COMMON_KEY_PATTERNS.items():
+        if service in endpoint_lower:
+            required.extend(keys)
+
+    # Check external services list
+    for service in external_services:
+        service_lower = service.lower()
+        for pattern, keys in COMMON_KEY_PATTERNS.items():
+            if pattern in service_lower:
+                required.extend(keys)
+
+    return list(set(required))  # Deduplicate
+
+
+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 API route files (not tests - tests should fail if keys missing)
+    is_api_file = "/api/" in file_path and file_path.endswith(".ts")
+    is_route_file = file_path.endswith("route.ts")
+
+    if not is_api_file or not is_route_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)
+
+    # Check if state file exists
+    if not STATE_FILE.exists():
+        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)
+
+    endpoint = state.get("endpoint")
+    if not endpoint:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    phases = state.get("phases", {})
+    schema_creation = phases.get("schema_creation", {})
+    environment_check = phases.get("environment_check", {})
+
+    # Only enforce after schema creation
+    if schema_creation.get("status") != "complete":
+        # Let earlier hooks handle this
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    env_status = environment_check.get("status", "not_started")
+    keys_required = environment_check.get("keys_required", [])
+    keys_found = environment_check.get("keys_found", [])
+    keys_missing = environment_check.get("keys_missing", [])
+    user_question_asked = environment_check.get("user_question_asked", False)
+    user_ready = environment_check.get("user_ready", False)
+    env_shown = environment_check.get("env_shown", False)
+
+    # Check if environment check is complete
+    if env_status != "complete":
+        # Infer required keys if not already set
+        if not keys_required:
+            interview = phases.get("interview", {})
+            decisions = interview.get("decisions", {})
+            external_services = decisions.get("external_services", {}).get("value", [])
+            if isinstance(external_services, str):
+                external_services = [external_services]
+            keys_required = infer_required_keys(endpoint, external_services)
+
+        # Check current environment
+        if keys_required:
+            found, missing = check_env_keys(keys_required)
+        else:
+            found, missing = [], []
+
+        # Check what's missing for user checkpoint
+        missing_steps = []
+        if not env_shown:
+            missing_steps.append("Environment status not shown to user")
+        if not user_question_asked:
+            missing_steps.append("User readiness question (AskUserQuestion not used)")
+        if not user_ready:
+            missing_steps.append("User hasn't confirmed readiness for TDD")
+
+        print(json.dumps({
+            "permissionDecision": "deny",
+            "reason": f"""❌ BLOCKED: Environment check (Phase 6) not complete.
+
+Current status: {env_status}
+Required keys: {len(keys_required)}
+Found: {len(found)}
+Missing: {len(missing)}
+User shown env: {env_shown}
+User question asked: {user_question_asked}
+User ready: {user_ready}
+
+MISSING:
+{chr(10).join(f"  • {m}" for m in missing_steps)}
+
+═══════════════════════════════════════════════════════════
+⚠️  GET USER READINESS CONFIRMATION
+═══════════════════════════════════════════════════════════
+
+REQUIRED STEPS:
+
+1. Check API keys and SHOW status to user:
+   ┌───────────────────────────────────────────────────────┐
+   │ ENVIRONMENT CHECK                                     │
+   │                                                       │
+   │ Required for {endpoint}:                              │
+   │                                                       │
+   │ API Keys:                                             │
+{chr(10).join(f"   │   {'✓' if k in found else '❌'} {k:<40} │" for k in keys_required) if keys_required else "   │   No API keys required                          │"}
+   │                                                       │
+   │ Testing Setup:                                        │
+   │   • Schema file ready                                 │
+   │   • Test patterns defined                             │
+   │   • Mock data prepared (if needed)                    │
+   │                                                       │
+   │ Ready to begin TDD? [Y]                               │
+   │ Need to fix something? [n]                            │
+   └───────────────────────────────────────────────────────┘
+
+2. USE AskUserQuestion:
+   question: "Environment looks ready. Start TDD?"
+   options: [
+     {{"value": "ready", "label": "Yes, ready to write tests"}},
+     {{"value": "fix_keys", "label": "No, need to set up API keys first"}},
+     {{"value": "fix_other", "label": "No, need to fix something else"}}
+   ]
+
+3. If user says "fix_keys" or "fix_other":
+   • Help them resolve the issue
+   • Re-check environment
+   • LOOP BACK and show updated status
+
+4. If user says "ready":
+   • Set environment_check.user_ready = true
+   • Set environment_check.user_question_asked = true
+   • Set environment_check.env_shown = true
+   • Set environment_check.keys_found = [list]
+   • Set environment_check.keys_missing = [list]
+   • Set environment_check.status = "complete"
+
+{'API KEY ISSUES:' if missing else ''}
+{chr(10).join(f"  ❌ {k}" for k in missing) if missing else ''}
+
+WHY: Verify environment before writing tests that depend on it."""
+        }))
+        sys.exit(0)
+
+    # Environment check complete
+    if keys_missing and not user_ready:
+        print(json.dumps({
+            "permissionDecision": "deny",
+            "reason": f"""❌ Missing keys noted but user hasn't confirmed readiness.
+Use AskUserQuestion to confirm user is ready to proceed with missing keys:
+{chr(10).join(f"  ⚠️ {k}" for k in keys_missing[:3])}"""
+        }))
+        sys.exit(0)
+
+    print(json.dumps({
+        "permissionDecision": "allow",
+        "message": f"""✅ Environment check complete.
+User confirmed ready for TDD.
+Keys found: {len(keys_found)}
+Keys missing (acknowledged): {len(keys_missing)}"""
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/enforce-interview.py

@@ -259,9 +259,72 @@ Reset the interview and ask with options based on research."""
             }))
             sys.exit(0)
 
-    # All checks passed - inject interview decisions as context reminder
+    # Check 6: FINAL USER CONFIRMATION - must confirm interview is complete
+    user_question_asked_final = interview.get("user_question_asked", False)
+    user_completed = interview.get("user_completed", False)
     decisions = interview.get("decisions", {})
 
+    if not user_completed or not user_question_asked_final:
+        decision_summary = _build_decision_summary(decisions)
+        missing = []
+        if not user_question_asked_final:
+            missing.append("Final confirmation question (AskUserQuestion not used)")
+        if not user_completed:
+            missing.append("User hasn't confirmed interview complete")
+
+        print(json.dumps({
+            "permissionDecision": "deny",
+            "reason": f"""❌ BLOCKED: Interview needs FINAL USER CONFIRMATION.
+
+Questions asked: {len(questions)}
+Structured questions: {actual_structured}
+User final confirmation: {user_completed}
+
+MISSING:
+{chr(10).join(f"  • {m}" for m in missing)}
+
+═══════════════════════════════════════════════════════════
+⚠️  GET USER CONFIRMATION BEFORE PROCEEDING
+═══════════════════════════════════════════════════════════
+
+REQUIRED STEPS:
+
+1. SHOW interview summary to user:
+   ┌───────────────────────────────────────────────────────┐
+   │ INTERVIEW COMPLETE                                    │
+   │                                                       │
+   │ Your decisions:                                       │
+{chr(10).join(f"   │   • {line:<49} │" for line in decision_summary.split(chr(10))[:8]) if decision_summary else "   │   (no decisions recorded yet)                      │"}
+   │                                                       │
+   │ These will guide the schema, tests, and implementation│
+   │                                                       │
+   │ All correct? [Y]                                      │
+   │ Change an answer? [n] ____                            │
+   └───────────────────────────────────────────────────────┘
+
+2. USE AskUserQuestion:
+   question: "Interview decisions correct? Ready to proceed?"
+   options: [
+     {{"value": "confirm", "label": "Yes, proceed to schema creation"}},
+     {{"value": "change", "label": "No, I want to change [which question]"}},
+     {{"value": "add", "label": "Add another question about [topic]"}}
+   ]
+
+3. If user says "change" or "add":
+   • Ask which question/topic
+   • Re-ask with AskUserQuestion
+   • Update decisions
+   • LOOP BACK and show updated summary
+
+4. If user says "confirm":
+   • Set interview.user_question_asked = true
+   • Set interview.user_completed = true
+   • Set interview.status = "complete"
+
+WHY: User must approve their decisions before they drive implementation."""
+        }))
+        sys.exit(0)
+
     if decisions:
         # Build a reminder of what the user decided
         decision_summary = _build_decision_summary(decisions)

package/hooks/enforce-refactor.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit
+Purpose: Block refactoring until verification phase is complete
+
+This hook ensures that after tests pass (Green phase), the implementation
+is verified against documentation before any refactoring begins.
+
+Phase 10 of the 12-phase workflow requires:
+  - TDD Green phase complete (tests passing)
+  - Verify phase complete (Phase 9)
+  - All gaps found have been fixed or documented as intentional omissions
+
+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"
+
+# Keywords that suggest refactoring intent
+REFACTOR_KEYWORDS = [
+    "refactor",
+    "cleanup",
+    "clean up",
+    "restructure",
+    "reorganize",
+    "optimize",
+    "simplify",
+    "extract",
+    "rename",
+    "move",
+]
+
+
+def is_refactoring_edit(tool_input: dict) -> bool:
+    """Detect if this edit appears to be a refactoring operation."""
+    # Check the content being written
+    new_string = tool_input.get("new_string", "")
+    old_string = tool_input.get("old_string", "")
+
+    # If both old and new exist and are similar length, might be refactoring
+    if old_string and new_string:
+        len_diff = abs(len(new_string) - len(old_string))
+        # Similar length suggests refactoring vs new features
+        if len_diff < len(old_string) * 0.3:  # Within 30% length
+            return True
+
+    return False
+
+
+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_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+    file_path = tool_input.get("file_path", "")
+
+    # Only check Edit operations on API files (Write is for new content)
+    if tool_name != "Edit":
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Only enforce for API route files
+    if "/api/" not in file_path or not file_path.endswith(".ts"):
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Skip test files - can refactor tests anytime
+    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():
+        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)
+
+    endpoint = state.get("endpoint")
+    if not endpoint:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    phases = state.get("phases", {})
+    tdd_green = phases.get("tdd_green", {})
+    verify = phases.get("verify", {})
+    tdd_refactor = phases.get("tdd_refactor", {})
+
+    # Only enforce after TDD Green is complete
+    if tdd_green.get("status") != "complete":
+        # Still in implementation phase, allow edits
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Check if this looks like a refactoring edit
+    if not is_refactoring_edit(tool_input):
+        # Doesn't look like refactoring, might be bug fix
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Check verify phase status
+    verify_status = verify.get("status", "not_started")
+    gaps_found = verify.get("gaps_found", 0)
+    gaps_fixed = verify.get("gaps_fixed", 0)
+    intentional_omissions = verify.get("intentional_omissions", [])
+
+    if verify_status != "complete":
+        print(json.dumps({
+            "permissionDecision": "deny",
+            "reason": f"""❌ BLOCKED: Verify phase (Phase 9) not complete.
+
+Current status: {verify_status}
+Gaps found: {gaps_found}
+Gaps fixed: {gaps_fixed}
+Intentional omissions: {len(intentional_omissions)}
+
+═══════════════════════════════════════════════════════════
+⚠️  VERIFY BEFORE REFACTORING
+═══════════════════════════════════════════════════════════
+
+Before refactoring, you must:
+
+1. Re-read the original documentation
+2. Compare implementation to docs feature-by-feature
+3. Fix any gaps OR document them as intentional omissions
+
+Current gaps not addressed:
+  • {gaps_found - gaps_fixed} gaps still need attention
+
+Once verify phase is complete:
+  • All gaps fixed OR documented as omissions
+  • Implementation matches documented behavior
+  • THEN you can safely refactor
+
+WHY THIS MATTERS:
+  - Refactoring should not change behavior
+  - Must verify behavior is CORRECT before preserving it
+  - Otherwise you cement bugs into clean code"""
+        }))
+        sys.exit(0)
+
+    # Verify complete - check if all gaps addressed
+    unaddressed_gaps = gaps_found - gaps_fixed - len(intentional_omissions)
+    if unaddressed_gaps > 0:
+        print(json.dumps({
+            "permissionDecision": "deny",
+            "reason": f"""❌ BLOCKED: {unaddressed_gaps} gaps not addressed.
+
+Gaps found: {gaps_found}
+Gaps fixed: {gaps_fixed}
+Intentional omissions: {len(intentional_omissions)}
+Unaddressed: {unaddressed_gaps}
+
+Fix the remaining gaps or mark them as intentional omissions
+before refactoring."""
+        }))
+        sys.exit(0)
+
+    # All clear for refactoring
+    refactor_status = tdd_refactor.get("status", "not_started")
+    print(json.dumps({
+        "permissionDecision": "allow",
+        "message": f"""✅ Verification complete. Safe to refactor.
+Refactor phase status: {refactor_status}
+Remember: Tests must still pass after refactoring!"""
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()