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

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)
 
 

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()