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

package/hooks/api-workflow-check.py

@@ -29,6 +29,8 @@ REQUIRED_PHASES = [
     ("interview", "User interview"),
     ("tdd_red", "TDD Red phase (failing tests written)"),
     ("tdd_green", "TDD Green phase (tests passing)"),
+    ("verify", "Verification phase (re-checked against docs)"),
+    ("documentation", "Documentation updates (manifest/research cached)"),
 ]
 
 # Phases that SHOULD be complete (warning but don't block)

package/hooks/enforce-deep-research.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit
+Purpose: Block writing if deep research not completed WITH USER APPROVAL
+
+Phase 4 requires:
+  1. PROPOSE searches based on interview answers
+  2. Show checkbox list to user
+  3. USE AskUserQuestion: "Approve? [Y] / Add more? ____"
+  4. Execute only approved searches
+  5. Loop back if user wants additions
+
+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)
+
+    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", {})
+
+    # Only enforce after interview is complete
+    if interview.get("status") != "complete":
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    status = research_deep.get("status", "not_started")
+
+    # If deep research was not needed (no proposed searches), allow
+    proposed = research_deep.get("proposed_searches", [])
+    if not proposed and status == "not_started":
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    if status != "complete":
+        user_question_asked = research_deep.get("user_question_asked", False)
+        user_approved = research_deep.get("user_approved", False)
+        proposals_shown = research_deep.get("proposals_shown", False)
+        approved_searches = research_deep.get("approved_searches", [])
+        executed_searches = research_deep.get("executed_searches", [])
+        skipped_searches = research_deep.get("skipped_searches", [])
+
+        # Calculate pending
+        pending = [s for s in approved_searches if s not in executed_searches and s not in skipped_searches]
+
+        missing = []
+        if not proposals_shown:
+            missing.append("Proposed searches 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 search list")
+        if pending:
+            missing.append(f"Approved searches not executed ({len(pending)} pending)")
+
+        print(json.dumps({
+            "permissionDecision": "deny",
+            "reason": f"""❌ BLOCKED: Deep research (Phase 4) not complete.
+
+Status: {status}
+Proposed searches: {len(proposed)}
+User shown proposals: {proposals_shown}
+User question asked: {user_question_asked}
+User approved: {user_approved}
+Approved: {len(approved_searches)}
+Executed: {len(executed_searches)}
+Skipped: {len(skipped_searches)}
+Pending: {len(pending)}
+
+MISSING:
+{chr(10).join(f"  • {m}" for m in missing)}
+
+═══════════════════════════════════════════════════════════
+⚠️  GET USER APPROVAL FOR DEEP RESEARCH
+═══════════════════════════════════════════════════════════
+
+REQUIRED STEPS:
+
+1. Based on interview, PROPOSE targeted searches:
+   ┌───────────────────────────────────────────────────────┐
+   │ PROPOSED DEEP RESEARCH                                │
+   │                                                       │
+   │ Based on your interview answers, I want to research:  │
+   │                                                       │
+   │ [x] Error response format (for error handling)        │
+   │ [x] Rate limiting behavior (caching selected)         │
+   │ [ ] Webhook support (not selected in interview)       │
+   │ [x] Authentication edge cases                         │
+   │                                                       │
+   │ Approve these searches? [Y]                           │
+   │ Add more: ____                                        │
+   │ Skip and proceed: [n]                                 │
+   └───────────────────────────────────────────────────────┘
+
+2. USE AskUserQuestion:
+   question: "Approve these deep research searches?"
+   options: [
+     {{"value": "approve", "label": "Yes, run these searches"}},
+     {{"value": "add", "label": "Add more - I also need [topic]"}},
+     {{"value": "skip", "label": "Skip deep research, proceed to schema"}}
+   ]
+
+3. If user says "add":
+   • Ask what additional topics they need
+   • Add to proposed_searches
+   • LOOP BACK and show updated list
+
+4. If user says "approve":
+   • Execute each approved search
+   • Record results in executed_searches
+
+5. If user says "skip":
+   • Record all as skipped_searches with reason
+   • Proceed to schema
+
+6. After all searches complete (or skipped):
+   • Set research_deep.user_approved = true
+   • Set research_deep.user_question_asked = true
+   • Set research_deep.proposals_shown = true
+   • Set research_deep.status = "complete"
+
+WHY: Research is ADAPTIVE based on interview, not shotgun."""
+        }))
+        sys.exit(0)
+
+    # Complete
+    executed = research_deep.get("executed_searches", [])
+    skipped = research_deep.get("skipped_searches", [])
+    print(json.dumps({
+        "permissionDecision": "allow",
+        "message": f"""✅ Deep research complete.
+Executed: {len(executed)} searches
+Skipped: {len(skipped)} (with reasons)
+User approved the search plan."""
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/enforce-disambiguation.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit
+Purpose: Block writing API code if disambiguation phase not complete WITH USER CONFIRMATION
+
+Phase 0 requires:
+  1. Search 3-5 variations of the term
+  2. Present options to user via AskUserQuestion
+  3. User selects which interpretation
+  4. Loop back if still ambiguous
+
+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"
+
+# Minimum search variations required
+MIN_SEARCH_VARIATIONS = 2
+
+
+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)
+
+    # 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": "deny",
+            "reason": """❌ API workflow not started.
+
+Run /api-create [endpoint-name] to begin the interview-driven workflow.
+
+Phase 0 (Disambiguation) is required before any implementation."""
+        }))
+        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", {})
+    status = disambiguation.get("status", "not_started")
+
+    if status != "complete":
+        search_variations = disambiguation.get("search_variations", [])
+        user_question_asked = disambiguation.get("user_question_asked", False)
+        user_selected = disambiguation.get("user_selected", None)
+
+        # Check what's missing
+        missing = []
+        if len(search_variations) < MIN_SEARCH_VARIATIONS:
+            missing.append(f"Search variations ({len(search_variations)}/{MIN_SEARCH_VARIATIONS})")
+        if not user_question_asked:
+            missing.append("User question (AskUserQuestion not used)")
+        if not user_selected:
+            missing.append("User selection (no choice recorded)")
+
+        print(json.dumps({
+            "permissionDecision": "deny",
+            "reason": f"""❌ BLOCKED: Disambiguation phase (Phase 0) not complete.
+
+Status: {status}
+Search variations: {len(search_variations)}
+User question asked: {user_question_asked}
+User selection: {user_selected or "None"}
+
+MISSING:
+{chr(10).join(f"  • {m}" for m in missing)}
+
+═══════════════════════════════════════════════════════════
+⚠️  COMPLETE DISAMBIGUATION WITH USER CONFIRMATION
+═══════════════════════════════════════════════════════════
+
+REQUIRED STEPS:
+
+1. Search 2-3 variations:
+   • WebSearch: "{endpoint}"
+   • WebSearch: "{endpoint} API"
+   • WebSearch: "{endpoint} SDK npm package"
+
+2. USE AskUserQuestion with options:
+   ┌───────────────────────────────────────────────────────┐
+   │ I found multiple things matching "{endpoint}":        │
+   │                                                       │
+   │ [A] The official REST API                             │
+   │ [B] The npm/SDK wrapper package                       │
+   │ [C] Both (API + SDK)                                  │
+   │ [D] Something else: ____                              │
+   │                                                       │
+   │ Which should this endpoint use?                       │
+   └───────────────────────────────────────────────────────┘
+
+3. Record user's choice in state:
+   disambiguation.user_selected = "A" (or user's choice)
+   disambiguation.user_question_asked = true
+   disambiguation.status = "complete"
+
+4. LOOP BACK if user is still unsure - search more variations
+
+WHY: Different interpretations = different implementations."""
+        }))
+        sys.exit(0)
+
+    # Complete - inject context
+    selected = disambiguation.get("user_selected", "")
+    print(json.dumps({
+        "permissionDecision": "allow",
+        "message": f"""✅ Disambiguation complete.
+User selected: {selected}
+Proceeding with this interpretation."""
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/enforce-documentation.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit (and Stop)
+Purpose: Block completion until documentation confirmed WITH USER REVIEW
+
+Phase 11 (Documentation) requires:
+  1. Update api-tests-manifest.json
+  2. Cache research to .claude/research/
+  3. Update OpenAPI spec if applicable
+  4. SHOW documentation checklist to user
+  5. USE AskUserQuestion: "Documentation complete? [Y/n]"
+  6. Only allow completion 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 documentation files or when trying to mark workflow complete
+    is_manifest = "api-tests-manifest.json" in file_path
+    is_openapi = "openapi" in file_path.lower() and file_path.endswith((".json", ".yaml", ".yml"))
+    is_readme = file_path.endswith("README.md") and "/api/" in file_path
+
+    # Also check for state file updates (marking complete)
+    is_state_update = "api-dev-state.json" in file_path
+
+    if not is_manifest and not is_openapi and not is_readme and not is_state_update:
+        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", {})
+    tdd_refactor = phases.get("tdd_refactor", {})
+    documentation = phases.get("documentation", {})
+
+    # Only enforce after refactor is complete
+    if tdd_refactor.get("status") != "complete":
+        # Allow documentation updates during development
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    status = documentation.get("status", "not_started")
+
+    if status != "complete":
+        user_question_asked = documentation.get("user_question_asked", False)
+        user_confirmed = documentation.get("user_confirmed", False)
+        checklist_shown = documentation.get("checklist_shown", False)
+        manifest_updated = documentation.get("manifest_updated", False)
+        research_cached = documentation.get("research_cached", False)
+        openapi_updated = documentation.get("openapi_updated", False)
+
+        missing = []
+        if not manifest_updated:
+            missing.append("api-tests-manifest.json not updated")
+        if not research_cached:
+            missing.append("Research not cached to .claude/research/")
+        if not checklist_shown:
+            missing.append("Documentation checklist not shown to user")
+        if not user_question_asked:
+            missing.append("User confirmation question (AskUserQuestion not used)")
+        if not user_confirmed:
+            missing.append("User hasn't confirmed documentation complete")
+
+        print(json.dumps({
+            "permissionDecision": "deny",
+            "reason": f"""❌ BLOCKED: Documentation (Phase 11) not complete.
+
+Status: {status}
+Manifest updated: {manifest_updated}
+Research cached: {research_cached}
+OpenAPI updated: {openapi_updated}
+Checklist shown: {checklist_shown}
+User question asked: {user_question_asked}
+User confirmed: {user_confirmed}
+
+MISSING:
+{chr(10).join(f"  • {m}" for m in missing)}
+
+═══════════════════════════════════════════════════════════
+⚠️  GET USER CONFIRMATION FOR DOCUMENTATION
+═══════════════════════════════════════════════════════════
+
+REQUIRED STEPS:
+
+1. Update api-tests-manifest.json with:
+   • Endpoint path, method, description
+   • Request/response schemas
+   • Test coverage info
+   • Code examples
+   • Testing notes
+
+2. Cache research to .claude/research/{endpoint}/:
+   • sources.json - URLs and summaries
+   • interview.json - User decisions
+   • schema.json - Final Zod schemas
+
+3. Update OpenAPI spec (if applicable):
+   • Add endpoint definition
+   • Document parameters
+   • Document responses
+
+4. SHOW documentation checklist to user:
+   ┌───────────────────────────────────────────────────────┐
+   │ DOCUMENTATION CHECKLIST                               │
+   │                                                       │
+   │ ✓ api-tests-manifest.json                            │
+   │   • Added {endpoint} entry                           │
+   │   • 8 test scenarios documented                       │
+   │   • Code examples included                            │
+   │                                                       │
+   │ ✓ Research Cache                                      │
+   │   • .claude/research/{endpoint}/sources.json         │
+   │   • .claude/research/{endpoint}/interview.json       │
+   │                                                       │
+   │ {'✓' if openapi_updated else '⏭'} OpenAPI Spec                                       │
+   │   • {'Updated' if openapi_updated else 'Skipped (internal API)'}                                       │
+   │                                                       │
+   │ All documentation complete? [Y]                       │
+   │ Need to add something? [n] ____                       │
+   └───────────────────────────────────────────────────────┘
+
+5. USE AskUserQuestion:
+   question: "Documentation checklist complete?"
+   options: [
+     {{"value": "confirm", "label": "Yes, all documentation is done"}},
+     {{"value": "add", "label": "No, I need to add [what]"}},
+     {{"value": "skip", "label": "Skip docs for now (not recommended)"}}
+   ]
+
+6. If user says "add":
+   • Ask what documentation is missing
+   • Update the relevant files
+   • LOOP BACK and show updated checklist
+
+7. If user says "confirm":
+   • Set documentation.user_confirmed = true
+   • Set documentation.user_question_asked = true
+   • Set documentation.checklist_shown = true
+   • Set documentation.manifest_updated = true
+   • Set documentation.research_cached = true
+   • Set documentation.status = "complete"
+   • Mark entire workflow as complete!
+
+WHY: Documentation ensures next developer (or future Claude) has context."""
+        }))
+        sys.exit(0)
+
+    # Documentation complete
+    print(json.dumps({
+        "permissionDecision": "allow",
+        "message": f"""✅ Documentation complete for {endpoint}.
+Manifest updated: {manifest_updated}
+Research cached: {research_cached}
+OpenAPI updated: {openapi_updated}
+User confirmed documentation is complete."""
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()