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

package/.claude/hooks/verify-after-green.py

@@ -0,0 +1,282 @@
+#!/usr/bin/env python3
+"""
+Hook: PostToolUse (after test runs)
+Purpose: Trigger Phase 10 (Verify) + Manifest Generation after tests pass
+
+This hook detects when tests pass (TDD Green phase complete) and:
+  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:
+  - 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
+
+Returns:
+  - {"continue": true} with additionalContext prompting verification
+"""
+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():
+    # Read hook input from stdin
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+    tool_output = input_data.get("tool_output", {})
+
+    # Only trigger on Bash commands
+    if tool_name != "Bash":
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if this is a test command
+    command = tool_input.get("command", "")
+    is_test_command = any(test_keyword in command.lower() for test_keyword in [
+        "pnpm test", "npm test", "vitest", "jest", "pytest", "test:run"
+    ])
+
+    if not is_test_command:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if tests passed (exit code 0 or output indicates success)
+    output_text = ""
+    if isinstance(tool_output, str):
+        output_text = tool_output
+    elif isinstance(tool_output, dict):
+        output_text = tool_output.get("output", tool_output.get("stdout", ""))
+
+    # Look for success indicators
+    tests_passed = any(indicator in output_text.lower() for indicator in [
+        "tests passed", "all tests passed", "test suites passed",
+        "✓", "passed", "0 failed", "pass"
+    ]) and not any(fail in output_text.lower() for fail in [
+        "failed", "error", "fail"
+    ])
+
+    if not tests_passed:
+        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}))
+        sys.exit(0)
+
+    try:
+        state = json.loads(STATE_FILE.read_text())
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    phases = state.get("phases", {})
+    tdd_green = phases.get("tdd_green", {})
+    verify = phases.get("verify", {})
+
+    # Check if we're in TDD Green phase
+    if tdd_green.get("status") != "in_progress":
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if verify phase already done
+    if verify.get("status") == "complete":
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Mark TDD Green as complete
+    tdd_green["status"] = "complete"
+    tdd_green["all_tests_passing"] = True
+    tdd_green["completed_at"] = datetime.now().isoformat()
+
+    # Start verify phase
+    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))
+
+    # Build verification prompt
+    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 10: Implementation Verification Required")
+    context_parts.append("")
+    context_parts.append("Tests are passing. Before proceeding, you MUST verify your implementation:")
+    context_parts.append("")
+    context_parts.append("**Required Actions:**")
+    context_parts.append("1. Re-read the original API documentation (use Context7 or WebSearch)")
+    context_parts.append("2. Compare EVERY documented parameter/feature to your implementation")
+    context_parts.append("3. Report any discrepancies in this format:")
+    context_parts.append("")
+    context_parts.append("```")
+    context_parts.append("| Feature          | In Docs | Implemented | Status          |")
+    context_parts.append("|------------------|---------|-------------|-----------------|")
+    context_parts.append("| param_name       | Yes     | Yes         | Match           |")
+    context_parts.append("| missing_param    | Yes     | No          | MISSING         |")
+    context_parts.append("| extra_param      | No      | Yes         | EXTRA (OK)      |")
+    context_parts.append("```")
+    context_parts.append("")
+    context_parts.append("**After comparison, ask the user:**")
+    context_parts.append("- Fix gaps? [Y] - Loop back to Red phase")
+    context_parts.append("- Skip (intentional omissions)? [n] - Document and proceed")
+    context_parts.append("")
+    context_parts.append("DO NOT proceed to Refactor until verification is complete.")
+
+    output = {
+        "continue": True,
+        "hookSpecificOutput": {
+            "hookEventName": "PostToolUse",
+            "additionalContext": "\n".join(context_parts)
+        }
+    }
+
+    print(json.dumps(output))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.claude/hooks/verify-implementation.py

@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit (runs AFTER enforce-research and enforce-interview)
+Purpose: Verify implementation matches interview requirements
+
+This hook addresses these gaps:
+1. AI uses exact user terminology when researching (not paraphrasing)
+2. All changed files are tracked and verified
+3. Test files use same patterns as production code
+
+Returns:
+  - {"permissionDecision": "allow"} - Let the tool run
+  - {"permissionDecision": "deny", "reason": "..."} - Block with explanation
+"""
+import json
+import sys
+import re
+from pathlib import Path
+
+# State file is in .claude/ directory (sibling to hooks/)
+STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+
+
+def extract_key_terms(text: str) -> list[str]:
+    """Extract likely important terms from interview answers.
+
+    These are terms that should appear in research and implementation:
+    - Proper nouns (capitalized multi-word phrases)
+    - Technical terms (SDK names, API names, etc.)
+    - Specific patterns (e.g., "via X", "using X", "with X")
+    """
+    terms = []
+
+    # Look for "via X", "using X", "with X" patterns
+    via_patterns = re.findall(r'(?:via|using|with|through)\s+([A-Z][A-Za-z0-9\s]+?)(?:[,.\n]|$)', text)
+    terms.extend(via_patterns)
+
+    # Look for capitalized phrases (likely proper nouns/product names)
+    # e.g., "Vercel AI Gateway", "OpenAI API"
+    proper_nouns = re.findall(r'[A-Z][a-z]+(?:\s+[A-Z][a-z]+)+', text)
+    terms.extend(proper_nouns)
+
+    # Clean up and dedupe
+    terms = [t.strip() for t in terms if len(t.strip()) > 3]
+    return list(set(terms))
+
+
+def check_research_used_exact_terms(state: dict) -> list[str]:
+    """Verify research sources used the exact terms from interview.
+
+    Gap 1 Fix: When user provides a term, use THAT EXACT TERM to search.
+    """
+    issues = []
+
+    interview = state.get("phases", {}).get("interview", {})
+    research = state.get("phases", {}).get("research_initial", {})
+    deep_research = state.get("phases", {}).get("research_deep", {})
+
+    questions = interview.get("questions", [])
+    if isinstance(questions, list) and len(questions) > 0:
+        # Extract key terms from all interview answers
+        all_text = " ".join(str(q) for q in questions)
+        key_terms = extract_key_terms(all_text)
+
+        # Check if these terms appear in research sources
+        research_sources = research.get("sources", []) + deep_research.get("sources", [])
+        research_text = " ".join(str(s) for s in research_sources).lower()
+
+        missing_terms = []
+        for term in key_terms:
+            # Check if term or close variant appears in research
+            term_lower = term.lower()
+            if term_lower not in research_text:
+                # Check for partial matches (e.g., "AI Gateway" in "Vercel AI Gateway")
+                words = term_lower.split()
+                if not any(all(w in research_text for w in words) for _ in [1]):
+                    missing_terms.append(term)
+
+        if missing_terms:
+            issues.append(
+                f"⚠️ Gap 1 Warning: User-specified terms not found in research:\n"
+                f"   Terms from interview: {missing_terms}\n"
+                f"   These EXACT terms should have been searched."
+            )
+
+    return issues
+
+
+def check_files_tracked(state: dict, file_path: str) -> list[str]:
+    """Verify we're tracking all files being modified.
+
+    Gap 2 Fix: Track files as they're modified, not after claiming completion.
+    """
+    issues = []
+
+    files_created = state.get("files_created", [])
+    files_modified = state.get("files_modified", [])
+    all_tracked = files_created + files_modified
+
+    # Normalize paths for comparison
+    normalized_path = file_path.replace("\\", "/")
+
+    # Check if this file is a test file
+    is_test = ".test." in file_path or "/__tests__/" in file_path or ".spec." in file_path
+
+    # For non-test files in api/ or lib/, they should be tracked
+    is_trackable = ("/api/" in file_path or "/lib/" in file_path) and file_path.endswith(".ts")
+
+    if is_trackable and not is_test:
+        # Check if any tracked file matches this one
+        found = False
+        for tracked in all_tracked:
+            if normalized_path.endswith(tracked) or tracked in normalized_path:
+                found = True
+                break
+
+        # Don't block, but log that this file should be tracked
+        if not found:
+            state.setdefault("files_modified", []).append(normalized_path.split("/src/")[-1] if "/src/" in normalized_path else normalized_path)
+            STATE_FILE.write_text(json.dumps(state, indent=2))
+
+    return issues
+
+
+def check_test_production_alignment(state: dict, file_path: str, content: str = "") -> list[str]:
+    """Verify test files use same patterns as production code.
+
+    Gap 5 Fix: Test files must use the same patterns as production code.
+    """
+    issues = []
+
+    is_test = ".test." in file_path or "/__tests__/" in file_path or ".spec." in file_path
+
+    if not is_test:
+        return issues
+
+    # Check interview for key configuration patterns
+    interview = state.get("phases", {}).get("interview", {})
+    questions = interview.get("questions", [])
+    all_text = " ".join(str(q) for q in questions)
+
+    # Look for environment variable patterns mentioned in interview
+    env_patterns = re.findall(r'[A-Z_]+_(?:KEY|API_KEY|TOKEN|SECRET)', all_text)
+
+    if env_patterns and content:
+        # If interview mentions specific env vars, test should check those
+        for pattern in env_patterns:
+            if pattern in content:
+                # Good - test is checking the right env var
+                pass
+
+        # Look for mismatches - e.g., checking OPENAI_API_KEY when we said "single gateway key"
+        if "gateway" in all_text.lower() or "single key" in all_text.lower():
+            # Interview mentioned gateway/single key - tests shouldn't check individual provider keys
+            old_patterns = ["OPENAI_API_KEY", "ANTHROPIC_API_KEY", "GOOGLE_API_KEY", "PERPLEXITY_API_KEY"]
+            found_old = [p for p in old_patterns if p in content]
+
+            if found_old and "AI_GATEWAY" not in content:
+                issues.append(
+                    f"⚠️ Gap 5 Warning: Test may be checking wrong environment variables.\n"
+                    f"   Interview mentioned: gateway/single key pattern\n"
+                    f"   Test checks: {found_old}\n"
+                    f"   Consider: Should test check AI_GATEWAY_API_KEY instead?"
+                )
+
+    return issues
+
+
+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", "")
+    new_content = tool_input.get("content", "") or tool_input.get("new_string", "")
+
+    # Only check for API/schema/lib files
+    is_api_file = "/api/" in file_path and file_path.endswith(".ts")
+    is_lib_file = "/lib/" in file_path and file_path.endswith(".ts")
+
+    if not is_api_file and not is_lib_file:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Load state
+    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)
+
+    # Run verification checks
+    all_issues = []
+
+    # Check 1: Research used exact terms from interview
+    all_issues.extend(check_research_used_exact_terms(state))
+
+    # Check 2: Track this file
+    all_issues.extend(check_files_tracked(state, file_path))
+
+    # Check 5: Test/production alignment
+    all_issues.extend(check_test_production_alignment(state, file_path, new_content))
+
+    # If there are issues, warn but don't block (these are warnings)
+    # The user can review these in the state file
+    if all_issues:
+        # Store warnings in state for later review
+        state.setdefault("verification_warnings", []).extend(all_issues)
+        STATE_FILE.write_text(json.dumps(state, indent=2))
+
+    # Allow the operation - these are warnings, not blockers
+    print(json.dumps({"permissionDecision": "allow"}))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.claude/research/index.json

@@ -0,0 +1,6 @@
+{
+  "version": "3.0.0",
+  "description": "Research cache index with freshness tracking",
+  "freshness_threshold_days": 7,
+  "apis": {}
+}

package/.claude/settings.json

@@ -0,0 +1,93 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "WebFetch",
+      "mcp__context7",
+      "mcp__context7__resolve-library-id",
+      "mcp__context7__get-library-docs",
+      "mcp__github",
+      "Bash(claude mcp:*)",
+      "Bash(pnpm test:*)",
+      "Bash(npm test:*)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-startup.py"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-external-research.py"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-research.py"
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-interview.py"
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/verify-implementation.py"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "WebSearch|WebFetch|mcp__context7.*|AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/track-tool-use.py"
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/periodic-reground.py"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/verify-after-green.py"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/api-workflow-check.py"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(cat:*)",
+      "Bash(npm whoami:*)",
+      "Bash(npm version:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)"
+    ]
+  }
+}