@hustle-together/api-dev-tools 2.0.7 → 3.1.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-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()

package/hooks/enforce-research.py

@@ -1,10 +1,13 @@
 #!/usr/bin/env python3
 """
 Hook: PreToolUse for Write/Edit
-Purpose: Block writing API code if research phase not complete
+Purpose: Block writing API code if research phase not complete WITH USER CHECKPOINT
 
-This hook runs BEFORE Claude can write or edit files in /api/ directories.
-It checks the api-dev-state.json file to ensure research was completed first.
+Phase 2 requires:
+  1. Execute 2-3 initial searches (Context7, WebSearch)
+  2. Present summary TABLE to user
+  3. USE AskUserQuestion: "Proceed? [Y] / Search more? [n]"
+  4. Loop back if user wants more research
 
 Returns:
   - {"permissionDecision": "allow"} - Let the tool run
@@ -14,97 +17,141 @@ 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"
 
+# Minimum sources required
+MIN_SOURCES = 2
+
 
 def main():
-    # Read hook input from stdin (Claude Code passes tool info as JSON)
     try:
         input_data = json.load(sys.stdin)
     except json.JSONDecodeError:
-        # If we can't parse input, allow (fail open for safety)
         print(json.dumps({"permissionDecision": "allow"}))
         sys.exit(0)
 
-    tool_name = input_data.get("tool_name", "")
     tool_input = input_data.get("tool_input", {})
-
-    # Get the file path being written/edited
     file_path = tool_input.get("file_path", "")
 
     # Only enforce for API route files
-    # Check for both /api/ and /api-test/ patterns
     if "/api/" not in file_path and "/api-test/" not in file_path:
-        # Not an API file, allow without checking
         print(json.dumps({"permissionDecision": "allow"}))
         sys.exit(0)
 
-    # Also skip for test files - tests should be written before research completes
-    # (TDD Red phase)
+    # Skip test files - TDD Red allows tests before research complete
     if ".test." in file_path or "/__tests__/" in file_path:
         print(json.dumps({"permissionDecision": "allow"}))
         sys.exit(0)
 
-    # Skip for documentation/config files
     if file_path.endswith(".md") or file_path.endswith(".json"):
         print(json.dumps({"permissionDecision": "allow"}))
         sys.exit(0)
 
-    # Check if state file exists
     if not STATE_FILE.exists():
         print(json.dumps({
             "permissionDecision": "deny",
             "reason": """❌ API development state not initialized.
 
-Before writing API implementation code, you must:
-  1. Run /api-create [endpoint-name] to start the workflow
-  OR
-  2. Run /api-research [library-name] to research dependencies
-
-This ensures you're working with current documentation, not outdated training data."""
+Run /api-create [endpoint-name] to start the workflow."""
         }))
         sys.exit(0)
 
-    # Load and check state
     try:
         state = json.loads(STATE_FILE.read_text())
     except json.JSONDecodeError:
-        # Corrupted state file, allow but warn
         print(json.dumps({"permissionDecision": "allow"}))
         sys.exit(0)
 
-    # Check research phase status
+    endpoint = state.get("endpoint", "unknown")
     phases = state.get("phases", {})
     research = phases.get("research_initial", {})
-    research_status = research.get("status", "not_started")
+    status = research.get("status", "not_started")
+
+    if status != "complete":
+        sources = research.get("sources", [])
+        user_question_asked = research.get("user_question_asked", False)
+        user_approved = research.get("user_approved", False)
+        summary_shown = research.get("summary_shown", False)
+
+        missing = []
+        if len(sources) < MIN_SOURCES:
+            missing.append(f"Sources ({len(sources)}/{MIN_SOURCES} minimum)")
+        if not summary_shown:
+            missing.append("Research summary table not shown to user")
+        if not user_question_asked:
+            missing.append("User checkpoint (AskUserQuestion not used)")
+        if not user_approved:
+            missing.append("User approval to proceed")
 
-    if research_status != "complete":
-        sources_count = len(research.get("sources", []))
         print(json.dumps({
             "permissionDecision": "deny",
-            "reason": f"""❌ Cannot write API implementation code yet.
-
-RESEARCH PHASE INCOMPLETE
-Current status: {research_status}
-Sources consulted: {sources_count}
-
-REQUIRED ACTIONS:
-  1. Complete research phase first
-  2. Run: /api-research [library-name]
-  3. Ensure Context7 or WebSearch has been used
-
-WHY THIS MATTERS:
-  - Implementation must match CURRENT API documentation
-  - Training data may be outdated
-  - All parameters must be discovered before coding
-
-Once research is complete, you can proceed with implementation."""
+            "reason": f"""❌ BLOCKED: Initial research (Phase 2) not complete.
+
+Status: {status}
+Sources consulted: {len(sources)}
+Summary shown: {summary_shown}
+User question asked: {user_question_asked}
+User approved: {user_approved}
+
+MISSING:
+{chr(10).join(f"  • {m}" for m in missing)}
+
+═══════════════════════════════════════════════════════════
+⚠️  COMPLETE RESEARCH WITH USER CHECKPOINT
+═══════════════════════════════════════════════════════════
+
+REQUIRED STEPS:
+
+1. Execute 2-3 initial searches:
+   • Context7: "{endpoint}"
+   • WebSearch: "{endpoint} official documentation"
+   • WebSearch: "site:[official-domain] {endpoint} API reference"
+
+2. Present summary TABLE to user:
+   ┌───────────────────────────────────────────────────────┐
+   │ RESEARCH SUMMARY                                      │
+   │                                                       │
+   │ │ Source         │ Found                              │
+   │ ├────────────────┼────────────────────────────────────│
+   │ │ Official docs  │ ✓ [URL]                            │
+   │ │ API Reference  │ ✓ REST v2                          │
+   │ │ Auth method    │ ✓ Bearer token                     │
+   │ │ NPM package    │ ? Not found                        │
+   │                                                       │
+   │ Proceed? [Y] / Search more? [n] ____                  │
+   └───────────────────────────────────────────────────────┘
+
+3. USE AskUserQuestion:
+   question: "Research summary above. Proceed or search more?"
+   options: [
+     {{"value": "proceed", "label": "Proceed to interview"}},
+     {{"value": "more", "label": "Search more - I need [topic]"}},
+     {{"value": "specific", "label": "Search for something specific"}}
+   ]
+
+4. If user says "more" or "specific":
+   • Ask what they want to research
+   • Execute additional searches
+   • LOOP BACK and show updated summary
+
+5. If user says "proceed":
+   • Set research_initial.user_approved = true
+   • Set research_initial.user_question_asked = true
+   • Set research_initial.summary_shown = true
+   • Set research_initial.status = "complete"
+
+WHY: Implementation must match CURRENT API documentation."""
         }))
         sys.exit(0)
 
-    # Research complete, allow writing
-    print(json.dumps({"permissionDecision": "allow"}))
+    # Research complete - inject context
+    sources = research.get("sources", [])
+    print(json.dumps({
+        "permissionDecision": "allow",
+        "message": f"""✅ Initial research complete.
+Sources: {len(sources)}
+User approved proceeding to interview."""
+    }))
     sys.exit(0)