@hustle-together/api-dev-tools 2.0.7 → 3.1.0

package/hooks/enforce-schema.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit
+Purpose: Block writing implementation if schema not reviewed WITH USER CONFIRMATION
+
+Phase 5 requires:
+  1. Create Zod schemas based on interview + research
+  2. SHOW schema to user in formatted display
+  3. USE AskUserQuestion: "Schema matches interview? [Y/n]"
+  4. Loop back if user wants changes
+  5. Only proceed when user confirms
+
+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 and schema files
+    is_api_file = "/api/" in file_path and file_path.endswith(".ts")
+    is_schema_file = "/schemas/" in file_path and file_path.endswith(".ts")
+
+    if not is_api_file and not is_schema_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", {})
+    interview = phases.get("interview", {})
+    research_deep = phases.get("research_deep", {})
+    schema_creation = phases.get("schema_creation", {})
+
+    # Only enforce after interview is complete
+    if interview.get("status") != "complete":
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Only enforce after deep research is complete (or not needed)
+    deep_status = research_deep.get("status", "not_started")
+    proposed = research_deep.get("proposed_searches", [])
+    if proposed and deep_status != "complete":
+        # Let enforce-deep-research.py handle this
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    status = schema_creation.get("status", "not_started")
+
+    if status != "complete":
+        user_question_asked = schema_creation.get("user_question_asked", False)
+        user_confirmed = schema_creation.get("user_confirmed", False)
+        schema_shown = schema_creation.get("schema_shown", False)
+        schema_file = schema_creation.get("schema_file", None)
+        fields_count = schema_creation.get("fields_count", 0)
+
+        missing = []
+        if not schema_shown:
+            missing.append("Schema not shown to user")
+        if not user_question_asked:
+            missing.append("User review question (AskUserQuestion not used)")
+        if not user_confirmed:
+            missing.append("User hasn't confirmed schema matches interview")
+
+        print(json.dumps({
+            "permissionDecision": "deny",
+            "reason": f"""❌ BLOCKED: Schema creation (Phase 5) not complete.
+
+Status: {status}
+Schema shown: {schema_shown}
+User question asked: {user_question_asked}
+User confirmed: {user_confirmed}
+Schema file: {schema_file or "Not created yet"}
+Fields: {fields_count}
+
+MISSING:
+{chr(10).join(f"  • {m}" for m in missing)}
+
+═══════════════════════════════════════════════════════════
+⚠️  GET USER CONFIRMATION FOR SCHEMA
+═══════════════════════════════════════════════════════════
+
+REQUIRED STEPS:
+
+1. Create Zod schemas based on:
+   • Interview answers (error handling, caching, etc.)
+   • Research findings (API parameters, response format)
+
+2. SHOW formatted schema to user:
+   ┌───────────────────────────────────────────────────────┐
+   │ SCHEMA REVIEW                                         │
+   │                                                       │
+   │ Request Schema:                                       │
+   │   domain: z.string()        ← From interview: domain │
+   │   mode: z.enum(["full", "logo"]) ← Your choice: full │
+   │   includeColors: z.boolean().default(true)           │
+   │                                                       │
+   │ Response Schema:                                      │
+   │   success: z.boolean()                               │
+   │   data: BrandDataSchema                              │
+   │   cached: z.boolean()       ← From interview: 24h   │
+   │   error: ErrorSchema.optional()                      │
+   │                                                       │
+   │ Based on YOUR interview answers:                      │
+   │   ✓ Error handling: Return objects                   │
+   │   ✓ Caching: 24h (long)                              │
+   │   ✓ Mode: Full brand kit                             │
+   │                                                       │
+   │ Does this match your requirements? [Y/n]             │
+   └───────────────────────────────────────────────────────┘
+
+3. USE AskUserQuestion:
+   question: "Does this schema match your interview answers?"
+   options: [
+     {{"value": "confirm", "label": "Yes, schema looks correct"}},
+     {{"value": "modify", "label": "No, I need changes - [describe]"}},
+     {{"value": "restart", "label": "Let's redo the interview"}}
+   ]
+
+4. If user says "modify":
+   • Ask what changes they need
+   • Update schema accordingly
+   • LOOP BACK and show updated schema
+
+5. If user says "restart":
+   • Reset interview phase
+   • Go back to Phase 3
+
+6. If user says "confirm":
+   • Set schema_creation.user_confirmed = true
+   • Set schema_creation.user_question_asked = true
+   • Set schema_creation.schema_shown = true
+   • Set schema_creation.status = "complete"
+
+WHY: Schema is the CONTRACT. User must approve before implementation."""
+        }))
+        sys.exit(0)
+
+    # Schema complete
+    schema_file = schema_creation.get("schema_file", "")
+    fields_count = schema_creation.get("fields_count", 0)
+    print(json.dumps({
+        "permissionDecision": "allow",
+        "message": f"""✅ Schema creation complete.
+Schema file: {schema_file}
+Fields: {fields_count}
+User confirmed schema matches interview requirements."""
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/enforce-scope.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit
+Purpose: Block writing API code if scope not confirmed BY USER
+
+Phase 1 requires:
+  1. Present scope understanding to user
+  2. USE AskUserQuestion: "Is this correct? [Y/n]"
+  3. Record any modifications user requests
+  4. Loop back if user wants changes
+
+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
+    if "/api/" not in file_path:
+        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)
+
+    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")
+    if not endpoint:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    phases = state.get("phases", {})
+    disambiguation = phases.get("disambiguation", {})
+    scope = phases.get("scope", {})
+
+    # Check disambiguation is complete first
+    if disambiguation.get("status") != "complete":
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    status = scope.get("status", "not_started")
+    user_confirmed = scope.get("user_confirmed", False)
+    user_question_asked = scope.get("user_question_asked", False)
+
+    if status != "complete" or not user_confirmed:
+        endpoint_path = scope.get("endpoint_path", f"/api/v2/{endpoint}")
+        modifications = scope.get("modifications", [])
+
+        missing = []
+        if not user_question_asked:
+            missing.append("User question (AskUserQuestion not used)")
+        if not user_confirmed:
+            missing.append("User confirmation (user hasn't said 'yes')")
+
+        print(json.dumps({
+            "permissionDecision": "deny",
+            "reason": f"""❌ BLOCKED: Scope confirmation (Phase 1) not complete.
+
+Status: {status}
+User question asked: {user_question_asked}
+User confirmed: {user_confirmed}
+Proposed path: {endpoint_path}
+Modifications: {len(modifications)}
+
+MISSING:
+{chr(10).join(f"  • {m}" for m in missing)}
+
+═══════════════════════════════════════════════════════════
+⚠️  GET USER CONFIRMATION OF SCOPE
+═══════════════════════════════════════════════════════════
+
+REQUIRED STEPS:
+
+1. Present your understanding:
+   ┌───────────────────────────────────────────────────────┐
+   │ SCOPE CONFIRMATION                                    │
+   │                                                       │
+   │ I understand you want: {endpoint_path}                │
+   │ Purpose: [describe inferred purpose]                  │
+   │ External API: [service name if any]                   │
+   │                                                       │
+   │ Is this correct? [Y/n]                                │
+   │ Any modifications needed? ____                        │
+   └───────────────────────────────────────────────────────┘
+
+2. USE AskUserQuestion:
+   question: "Is this scope correct? Any modifications?"
+   options: [
+     {{"value": "yes", "label": "Yes, proceed"}},
+     {{"value": "modify", "label": "I have modifications"}},
+     {{"value": "no", "label": "No, let me clarify"}}
+   ]
+
+3. If user says "modify" or "no":
+   • Ask for their modifications
+   • Record them in scope.modifications
+   • LOOP BACK and confirm again
+
+4. If user says "yes":
+   • Set scope.user_confirmed = true
+   • Set scope.user_question_asked = true
+   • Set scope.status = "complete"
+
+WHY: Prevents building the wrong thing."""
+        }))
+        sys.exit(0)
+
+    # Scope confirmed - inject context
+    endpoint_path = scope.get("endpoint_path", f"/api/v2/{endpoint}")
+    modifications = scope.get("modifications", [])
+
+    context = [f"✅ Scope confirmed: {endpoint_path}"]
+    if modifications:
+        context.append("User modifications:")
+        for mod in modifications[:3]:
+            context.append(f"  • {mod}")
+
+    print(json.dumps({
+        "permissionDecision": "allow",
+        "message": "\n".join(context)
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/enforce-tdd-red.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit
+Purpose: Block writing implementation if test matrix not approved WITH USER CONFIRMATION
+
+Phase 7 (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", [])
+
+    # Check if TDD Red phase is complete
+    if tdd_red_status != "complete":
+        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")
+
+        print(json.dumps({
+            "permissionDecision": "deny",
+            "reason": f"""❌ BLOCKED: TDD Red phase (Phase 7) 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}
+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()