@hustle-together/api-dev-tools 1.3.0 → 1.7.0

package/hooks/api-workflow-check.py

@@ -6,33 +6,104 @@ Purpose: Check if all required phases are complete before allowing stop
 This hook runs when Claude tries to stop/end the conversation.
 It checks api-dev-state.json to ensure critical workflow phases completed.
 
+Gap Fixes Applied:
+- Gap 2: Shows files_created vs files_modified to verify all claimed changes
+- Gap 3: Warns if there are verification_warnings that weren't addressed
+- Gap 4: Requires explicit verification that implementation matches interview
+
 Returns:
   - {"decision": "approve"} - Allow stopping
   - {"decision": "block", "reason": "..."} - Prevent stopping with explanation
 """
 import json
 import sys
+import subprocess
 from pathlib import Path
 
 # State file is in .claude/ directory (sibling to hooks/)
 STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
 
 # Phases that MUST be complete before stopping
-# These are the critical phases - others are optional
 REQUIRED_PHASES = [
     ("research_initial", "Initial research (Context7/WebSearch)"),
+    ("interview", "User interview"),
     ("tdd_red", "TDD Red phase (failing tests written)"),
     ("tdd_green", "TDD Green phase (tests passing)"),
 ]
 
 # Phases that SHOULD be complete (warning but don't block)
 RECOMMENDED_PHASES = [
-    ("interview", "User interview"),
     ("schema_creation", "Schema creation"),
+    ("tdd_refactor", "TDD Refactor phase"),
     ("documentation", "Documentation updates"),
 ]
 
 
+def get_git_modified_files() -> list[str]:
+    """Get list of modified files from git.
+
+    Gap 2 Fix: Verify which files actually changed.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--name-only", "HEAD"],
+            capture_output=True,
+            text=True,
+            cwd=STATE_FILE.parent.parent  # Project root
+        )
+        if result.returncode == 0:
+            return [f.strip() for f in result.stdout.strip().split("\n") if f.strip()]
+    except Exception:
+        pass
+    return []
+
+
+def check_verification_warnings(state: dict) -> list[str]:
+    """Check for unaddressed verification warnings.
+
+    Gap 3 Fix: Don't accept "skipped" or warnings without explanation.
+    """
+    warnings = state.get("verification_warnings", [])
+    if warnings:
+        return [
+            "⚠️ Unaddressed verification warnings:",
+            *[f"  - {w}" for w in warnings[-5:]],  # Show last 5
+            "",
+            "Please review and address these warnings before completing."
+        ]
+    return []
+
+
+def check_interview_implementation_match(state: dict) -> list[str]:
+    """Verify implementation matches interview requirements.
+
+    Gap 4 Fix: Define specific "done" criteria based on interview.
+    """
+    issues = []
+
+    interview = state.get("phases", {}).get("interview", {})
+    questions = interview.get("questions", [])
+
+    # Extract key requirements from interview
+    all_text = " ".join(str(q) for q in questions)
+
+    # Check files_created includes expected patterns
+    files_created = state.get("files_created", [])
+
+    # Look for route files if interview mentioned endpoints
+    if "endpoint" in all_text.lower() or "/api/" in all_text.lower():
+        route_files = [f for f in files_created if "route.ts" in f]
+        if not route_files:
+            issues.append("⚠️ Interview mentioned endpoints but no route.ts files were created")
+
+    # Look for test files
+    test_files = [f for f in files_created if ".test." in f or "__tests__" in f]
+    if not test_files:
+        issues.append("⚠️ No test files tracked in files_created")
+
+    return issues
+
+
 def main():
     # If no state file, we're not in an API workflow - allow stop
     if not STATE_FILE.exists():
@@ -56,6 +127,9 @@ def main():
         print(json.dumps({"decision": "approve"}))
         sys.exit(0)
 
+    # Collect all issues
+    all_issues = []
+
     # Check required phases
     incomplete_required = []
     for phase_key, phase_name in REQUIRED_PHASES:
@@ -64,6 +138,10 @@ def main():
         if status != "complete":
             incomplete_required.append(f"  - {phase_name} ({status})")
 
+    if incomplete_required:
+        all_issues.append("❌ REQUIRED phases incomplete:")
+        all_issues.extend(incomplete_required)
+
     # Check recommended phases
     incomplete_recommended = []
     for phase_key, phase_name in RECOMMENDED_PHASES:
@@ -72,42 +150,73 @@ def main():
         if status != "complete":
             incomplete_recommended.append(f"  - {phase_name} ({status})")
 
+    # Gap 2: Check git diff vs tracked files
+    git_files = get_git_modified_files()
+    tracked_files = state.get("files_created", []) + state.get("files_modified", [])
+
+    if git_files and tracked_files:
+        # Find files in git but not tracked
+        untracked_changes = []
+        for gf in git_files:
+            if not any(gf.endswith(tf) or tf in gf for tf in tracked_files):
+                if gf.endswith(".ts") and ("/api/" in gf or "/lib/" in gf):
+                    untracked_changes.append(gf)
+
+        if untracked_changes:
+            all_issues.append("\n⚠️ Gap 2: Files changed but not tracked:")
+            all_issues.extend([f"  - {f}" for f in untracked_changes[:5]])
+
+    # Gap 3: Check for unaddressed warnings
+    warning_issues = check_verification_warnings(state)
+    if warning_issues:
+        all_issues.append("\n" + "\n".join(warning_issues))
+
+    # Gap 4: Check interview-implementation match
+    match_issues = check_interview_implementation_match(state)
+    if match_issues:
+        all_issues.append("\n⚠️ Gap 4: Implementation verification:")
+        all_issues.extend([f"  {i}" for i in match_issues])
+
     # Block if required phases incomplete
     if incomplete_required:
-        reason_parts = ["❌ API workflow has REQUIRED phases incomplete:\n"]
-        reason_parts.extend(incomplete_required)
-
-        if incomplete_recommended:
-            reason_parts.append("\n\n⚠️ Also recommended but not complete:")
-            reason_parts.extend(incomplete_recommended)
-
-        reason_parts.append("\n\nTo continue:")
-        reason_parts.append("  1. Complete required phases above")
-        reason_parts.append("  2. Use /api-status to see detailed progress")
-        reason_parts.append("  3. Or manually mark phases complete in .claude/api-dev-state.json")
+        all_issues.append("\n\nTo continue:")
+        all_issues.append("  1. Complete required phases above")
+        all_issues.append("  2. Use /api-status to see detailed progress")
+        all_issues.append("  3. Run `git diff --name-only` to verify changes")
 
         print(json.dumps({
             "decision": "block",
-            "reason": "\n".join(reason_parts)
+            "reason": "\n".join(all_issues)
         }))
         sys.exit(0)
 
-    # Warn about recommended phases but allow
-    if incomplete_recommended:
-        # Allow but the reason will be shown to user
-        print(json.dumps({
-            "decision": "approve",
-            "message": f"""⚠️ API workflow completing with optional phases pending:
-{chr(10).join(incomplete_recommended)}
+    # Build completion message
+    message_parts = ["✅ API workflow completing"]
 
-Consider running /api-status to review what was skipped."""
-        }))
-        sys.exit(0)
+    if incomplete_recommended:
+        message_parts.append("\n⚠️ Optional phases skipped:")
+        message_parts.extend(incomplete_recommended)
+
+    # Show summary of tracked files
+    files_created = state.get("files_created", [])
+    if files_created:
+        message_parts.append(f"\n📁 Files created: {len(files_created)}")
+        for f in files_created[:5]:
+            message_parts.append(f"  - {f}")
+        if len(files_created) > 5:
+            message_parts.append(f"  ... and {len(files_created) - 5} more")
+
+    # Show any remaining warnings
+    if warning_issues or match_issues:
+        message_parts.append("\n⚠️ Review suggested:")
+        if warning_issues:
+            message_parts.extend(warning_issues[:3])
+        if match_issues:
+            message_parts.extend(match_issues[:3])
 
-    # All phases complete
     print(json.dumps({
         "decision": "approve",
-        "message": "✅ API workflow completed successfully!"
+        "message": "\n".join(message_parts)
     }))
     sys.exit(0)
 

package/hooks/enforce-external-research.py

@@ -0,0 +1,318 @@
+#!/usr/bin/env python3
+"""
+Hook: UserPromptSubmit
+Purpose: Enforce research before answering external API/SDK questions
+
+This hook runs BEFORE Claude processes the user's prompt. It detects
+questions about external APIs, SDKs, or services and injects context
+requiring Claude to research first before answering.
+
+Philosophy: "When in doubt, research. Training data is ALWAYS potentially outdated."
+
+Returns:
+  - Prints context to stdout (injected into conversation)
+  - Exit 0 to allow the prompt to proceed
+"""
+import json
+import sys
+import re
+from pathlib import Path
+from datetime import datetime
+
+# State file is in .claude/ directory (sibling to hooks/)
+STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+
+# ============================================================================
+# PATTERN-BASED DETECTION
+# ============================================================================
+
+# Patterns that indicate external service/API mentions
+EXTERNAL_SERVICE_PATTERNS = [
+    # Package names
+    r"@[\w-]+/[\w-]+",                    # @scope/package
+    r"\b[\w-]+-(?:sdk|api|js|ts|py)\b",   # something-sdk, something-api, something-js
+
+    # API/SDK keywords
+    r"\b(?:api|sdk|library|package|module|framework)\b",
+
+    # Technical implementation terms
+    r"\b(?:endpoint|route|webhook|oauth|auth|token)\b",
+
+    # Version references
+    r"\bv?\d+\.\d+(?:\.\d+)?\b",           # version numbers like v1.2.3, 2.0
+
+    # Import/require patterns
+    r"(?:import|require|from)\s+['\"][\w@/-]+['\"]",
+]
+
+# Patterns that indicate asking about features/capabilities
+CAPABILITY_QUESTION_PATTERNS = [
+    # "What does X support/have/do"
+    r"what\s+(?:does|can|are|is)\s+\w+",
+    r"what\s+\w+\s+(?:support|have|provide|offer)",
+
+    # "Does X support/have"
+    r"(?:does|can|will)\s+\w+\s+(?:support|have|handle|do|work)",
+
+    # "How to/do" questions
+    r"how\s+(?:to|do|does|can|should)\s+",
+
+    # Lists and availability
+    r"(?:list|show)\s+(?:of|all|available)",
+    r"which\s+\w+\s+(?:are|is)\s+(?:available|supported)",
+    r"all\s+(?:available|supported)\s+\w+",
+
+    # Examples and implementation
+    r"example\s+(?:of|for|using|with)",
+    r"how\s+to\s+(?:use|implement|integrate|connect|setup|configure)",
+]
+
+# Common external service/company names (partial list - patterns catch the rest)
+KNOWN_SERVICES = [
+    # AI/ML
+    "openai", "anthropic", "google", "gemini", "gpt", "claude", "llama",
+    "groq", "perplexity", "mistral", "cohere", "huggingface", "replicate",
+
+    # Cloud/Infrastructure
+    "aws", "azure", "gcp", "vercel", "netlify", "cloudflare", "supabase",
+    "firebase", "mongodb", "postgres", "redis", "elasticsearch",
+
+    # APIs/Services
+    "stripe", "twilio", "sendgrid", "mailchimp", "slack", "discord",
+    "github", "gitlab", "bitbucket", "jira", "notion", "airtable",
+    "shopify", "salesforce", "hubspot", "zendesk",
+
+    # Data/Analytics
+    "segment", "mixpanel", "amplitude", "datadog", "sentry", "grafana",
+
+    # Media/Content
+    "cloudinary", "imgix", "mux", "brandfetch", "unsplash", "pexels",
+
+    # Auth
+    "auth0", "okta", "clerk", "nextauth", "passport",
+
+    # Payments
+    "paypal", "square", "braintree", "adyen",
+]
+
+# ============================================================================
+# DETECTION LOGIC
+# ============================================================================
+
+def detect_external_api_question(prompt: str) -> dict:
+    """
+    Detect if the prompt is asking about external APIs/SDKs.
+
+    Returns:
+        {
+            "detected": bool,
+            "terms": list of detected terms,
+            "patterns_matched": list of pattern types matched,
+            "confidence": "high" | "medium" | "low"
+        }
+    """
+    prompt_lower = prompt.lower()
+    detected_terms = []
+    patterns_matched = []
+
+    # Check for known services
+    for service in KNOWN_SERVICES:
+        if service in prompt_lower:
+            detected_terms.append(service)
+            patterns_matched.append("known_service")
+
+    # Check external service patterns
+    for pattern in EXTERNAL_SERVICE_PATTERNS:
+        matches = re.findall(pattern, prompt_lower, re.IGNORECASE)
+        if matches:
+            detected_terms.extend(matches)
+            patterns_matched.append("external_service_pattern")
+
+    # Check capability question patterns
+    for pattern in CAPABILITY_QUESTION_PATTERNS:
+        if re.search(pattern, prompt_lower, re.IGNORECASE):
+            patterns_matched.append("capability_question")
+            break
+
+    # Deduplicate
+    detected_terms = list(set(detected_terms))
+    patterns_matched = list(set(patterns_matched))
+
+    # Determine confidence
+    if "known_service" in patterns_matched and "capability_question" in patterns_matched:
+        confidence = "high"
+    elif "known_service" in patterns_matched or len(detected_terms) >= 2:
+        confidence = "medium"
+    elif patterns_matched:
+        confidence = "low"
+    else:
+        confidence = "none"
+
+    return {
+        "detected": confidence in ["high", "medium"],
+        "terms": detected_terms[:10],  # Limit to 10 terms
+        "patterns_matched": patterns_matched,
+        "confidence": confidence,
+    }
+
+
+def check_active_workflow() -> bool:
+    """Check if there's an active API development workflow."""
+    if not STATE_FILE.exists():
+        return False
+
+    try:
+        state = json.loads(STATE_FILE.read_text())
+        phases = state.get("phases", {})
+
+        # Check if any phase is in progress
+        for phase_key, phase_data in phases.items():
+            if isinstance(phase_data, dict):
+                status = phase_data.get("status", "")
+                if status in ["in_progress", "pending"]:
+                    return True
+
+        return False
+    except (json.JSONDecodeError, Exception):
+        return False
+
+
+def check_already_researched(terms: list) -> list:
+    """Check which terms have already been researched."""
+    if not STATE_FILE.exists():
+        return []
+
+    try:
+        state = json.loads(STATE_FILE.read_text())
+        research_queries = state.get("research_queries", [])
+
+        # Also check sources in phases
+        phases = state.get("phases", {})
+        all_sources = []
+        for phase_data in phases.values():
+            if isinstance(phase_data, dict):
+                sources = phase_data.get("sources", [])
+                all_sources.extend(sources)
+
+        # Combine all research text
+        all_research_text = " ".join(str(s) for s in all_sources)
+        all_research_text += " ".join(
+            str(q.get("query", "")) + " " + str(q.get("term", ""))
+            for q in research_queries
+            if isinstance(q, dict)
+        )
+        all_research_text = all_research_text.lower()
+
+        # Find which terms were already researched
+        already_researched = []
+        for term in terms:
+            if term.lower() in all_research_text:
+                already_researched.append(term)
+
+        return already_researched
+    except (json.JSONDecodeError, Exception):
+        return []
+
+
+def log_detection(prompt: str, detection: dict) -> None:
+    """Log this detection for debugging/auditing."""
+    if not STATE_FILE.exists():
+        return
+
+    try:
+        state = json.loads(STATE_FILE.read_text())
+
+        if "prompt_detections" not in state:
+            state["prompt_detections"] = []
+
+        state["prompt_detections"].append({
+            "timestamp": datetime.now().isoformat(),
+            "prompt_preview": prompt[:100] + "..." if len(prompt) > 100 else prompt,
+            "detection": detection,
+        })
+
+        # Keep only last 20 detections
+        state["prompt_detections"] = state["prompt_detections"][-20:]
+
+        STATE_FILE.write_text(json.dumps(state, indent=2))
+    except Exception:
+        pass  # Don't fail the hook on logging errors
+
+
+# ============================================================================
+# MAIN
+# ============================================================================
+
+def main():
+    # Read hook input from stdin
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        # If we can't parse input, allow without injection
+        sys.exit(0)
+
+    prompt = input_data.get("prompt", "")
+
+    if not prompt:
+        sys.exit(0)
+
+    # Check if in active workflow mode (stricter enforcement)
+    active_workflow = check_active_workflow()
+
+    # Detect external API questions
+    detection = detect_external_api_question(prompt)
+
+    # Log for debugging
+    if detection["detected"] or active_workflow:
+        log_detection(prompt, detection)
+
+    # Determine if we should inject research requirement
+    should_inject = False
+    inject_reason = ""
+
+    if active_workflow:
+        # In active workflow, ALWAYS inject for technical questions
+        if detection["confidence"] in ["high", "medium", "low"]:
+            should_inject = True
+            inject_reason = "active_workflow"
+    elif detection["detected"]:
+        # Check if already researched
+        already_researched = check_already_researched(detection["terms"])
+        unresearched_terms = [t for t in detection["terms"] if t not in already_researched]
+
+        if unresearched_terms:
+            should_inject = True
+            inject_reason = "unresearched_terms"
+            detection["unresearched"] = unresearched_terms
+
+    # Inject context if needed
+    if should_inject:
+        terms_str = ", ".join(detection.get("unresearched", detection["terms"])[:5])
+
+        injection = f"""
+<user-prompt-submit-hook>
+EXTERNAL API/SDK DETECTED: {terms_str}
+Confidence: {detection["confidence"]}
+{"Mode: Active API Development Workflow" if active_workflow else ""}
+
+MANDATORY RESEARCH REQUIREMENT:
+Before answering this question, you MUST:
+
+1. Use Context7 (mcp__context7__resolve-library-id + get-library-docs) to look up current documentation
+2. Use WebSearch to find official documentation and recent updates
+3. NEVER answer from training data alone - it may be outdated
+
+Training data can be months or years old. APIs change constantly.
+Research first. Then answer with verified, current information.
+
+After researching, cite your sources in your response.
+</user-prompt-submit-hook>
+"""
+        print(injection)
+
+    # Always allow the prompt to proceed
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()