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

package/hooks/enforce-documentation.py

@@ -3,7 +3,7 @@
 Hook: PreToolUse for Write/Edit (and Stop)
 Purpose: Block completion until documentation confirmed WITH USER REVIEW
 
-Phase 21 (Documentation) requires:
+Phase 12 (Documentation) requires:
   1. Update api-tests-manifest.json
   2. Cache research to .claude/research/
   3. Update OpenAPI spec if applicable
@@ -14,12 +14,50 @@ Phase 21 (Documentation) requires:
 Returns:
   - {"permissionDecision": "allow"} - Let the tool run
   - {"permissionDecision": "deny", "reason": "..."} - Block with explanation
+
+Updated in v3.6.7:
+  - Support multi-API state structure
+  - Don't block on missing cache files (cache-research.py creates them)
+  - Check actual file existence, not just state flags
 """
 import json
 import sys
 from pathlib import Path
 
 STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+RESEARCH_DIR = Path(__file__).parent.parent / "research"
+
+
+def get_active_endpoint(state):
+    """Get active endpoint - supports both old and new state formats."""
+    # New format (v3.6.7+): endpoints object with active_endpoint pointer
+    if "endpoints" in state and "active_endpoint" in state:
+        active = state.get("active_endpoint")
+        if active and active in state["endpoints"]:
+            return active, state["endpoints"][active]
+        return None, None
+
+    # Old format: single endpoint field
+    endpoint = state.get("endpoint")
+    if endpoint:
+        return endpoint, state
+
+    return None, None
+
+
+def check_research_cache_exists(endpoint):
+    """Check if research cache files actually exist."""
+    cache_dir = RESEARCH_DIR / endpoint
+    if not cache_dir.exists():
+        return False, []
+
+    expected_files = ["sources.json", "interview.json", "schema.json"]
+    existing = []
+    for f in expected_files:
+        if (cache_dir / f).exists():
+            existing.append(f)
+
+    return len(existing) >= 2, existing  # At least 2 of 3 files should exist
 
 
 def main():
@@ -54,8 +92,13 @@ def main():
         print(json.dumps({"permissionDecision": "allow"}))
         sys.exit(0)
 
-    endpoint = state.get("endpoint", "unknown")
-    phases = state.get("phases", {})
+    # Get active endpoint (supports both old and new formats)
+    endpoint, endpoint_data = get_active_endpoint(state)
+    if not endpoint or not endpoint_data:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    phases = endpoint_data.get("phases", {})
     tdd_refactor = phases.get("tdd_refactor", {})
     documentation = phases.get("documentation", {})
 
@@ -74,14 +117,19 @@ def main():
         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)
 
+        # v3.6.7: Check actual file existence for research cache
+        # (cache-research.py PostToolUse hook creates these files automatically)
+        cache_exists, cache_files = check_research_cache_exists(endpoint)
+        research_cached = cache_exists or documentation.get("research_cached", 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/")
+            # Don't block - cache-research.py will create files when docs are written
+            missing.append(f"Research cache pending (will be created automatically)")
         if not checklist_shown:
             missing.append("Documentation checklist not shown to user")
         if not user_question_asked:
@@ -93,7 +141,7 @@ def main():
 
         print(json.dumps({
             "permissionDecision": "deny",
-            "reason": f"""❌ BLOCKED: Documentation (Phase 21) not complete.
+            "reason": f"""❌ BLOCKED: Documentation (Phase 12) not complete.
 
 Status: {status}
 Manifest updated: {manifest_updated}
@@ -176,12 +224,16 @@ WHY: Documentation ensures next developer (or future Claude) has context."""
         }))
         sys.exit(0)
 
-    # Documentation complete
+    # Documentation complete - check actual file existence for status
+    cache_exists, cache_files = check_research_cache_exists(endpoint)
+    manifest_updated = documentation.get("manifest_updated", False)
+    openapi_updated = documentation.get("openapi_updated", False)
+
     print(json.dumps({
         "permissionDecision": "allow",
         "message": f"""✅ Documentation complete for {endpoint}.
 Manifest updated: {manifest_updated}
-Research cached: {research_cached}
+Research cached: {cache_exists} ({', '.join(cache_files) if cache_files else 'no files'})
 OpenAPI updated: {openapi_updated}
 User confirmed documentation is complete."""
     }))

package/hooks/enforce-freshness.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse (Write|Edit)
+Purpose: Enforce research freshness for the active endpoint
+
+This hook blocks Write/Edit operations if:
+  1. There is an active endpoint in api-dev-state.json
+  2. Research exists for that endpoint
+  3. Research is older than 7 days (configurable)
+
+The user can:
+  - Run /hustle-api-research to refresh the research
+  - Set "enforce_freshness": false in the endpoint config to disable
+  - Research is only enforced for the ACTIVE endpoint
+
+Exit Codes:
+  - 0: Continue (no active endpoint, research is fresh, or enforcement disabled)
+  - 2: Block with message (research is stale, requires re-research)
+
+Added in v3.7.0:
+  - User requested enforcement (not just warning) for stale research
+  - Only enforces for the active endpoint being worked on
+"""
+import json
+import sys
+import os
+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"
+RESEARCH_INDEX = Path(__file__).parent.parent / "research" / "index.json"
+
+# Default freshness threshold (days)
+FRESHNESS_THRESHOLD_DAYS = 7
+
+
+def get_active_endpoint(state):
+    """Get active endpoint - supports both old and new state formats."""
+    if "endpoints" in state and "active_endpoint" in state:
+        active = state.get("active_endpoint")
+        if active and active in state["endpoints"]:
+            return active, state["endpoints"][active]
+        return None, None
+
+    # Old format
+    endpoint = state.get("endpoint")
+    if endpoint:
+        return endpoint, state
+
+    return None, None
+
+
+def load_research_index():
+    """Load research index from .claude/research/index.json file."""
+    if not RESEARCH_INDEX.exists():
+        return {}
+    try:
+        index = json.loads(RESEARCH_INDEX.read_text())
+        return index.get("apis", {})
+    except (json.JSONDecodeError, IOError):
+        return {}
+
+
+def calculate_days_old(timestamp_str):
+    """Calculate how many days old a timestamp is."""
+    if not timestamp_str:
+        return 0
+    try:
+        last_updated = datetime.fromisoformat(timestamp_str.replace('Z', '+00:00'))
+        now = datetime.now(last_updated.tzinfo) if last_updated.tzinfo else datetime.now()
+        return (now - last_updated).days
+    except (ValueError, TypeError):
+        return 0
+
+
+def is_api_related_file(file_path):
+    """Check if the file being written is API-related."""
+    if not file_path:
+        return False
+
+    file_path = file_path.lower()
+
+    # Files that indicate API development
+    api_indicators = [
+        '/api/',
+        '/route.ts',
+        '/route.js',
+        '.api.test.',
+        '/schemas/',
+        'api-tests-manifest',
+        '/v2/'
+    ]
+
+    return any(indicator in file_path for indicator in api_indicators)
+
+
+def main():
+    # Read hook input from stdin
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        input_data = {}
+
+    # Get the file being written (if applicable)
+    tool_input = input_data.get("toolInput", {})
+    file_path = tool_input.get("file_path", "")
+
+    # Only enforce for API-related files
+    if not is_api_related_file(file_path):
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if state file exists
+    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)
+
+    # Get active endpoint
+    endpoint, endpoint_data = get_active_endpoint(state)
+    if not endpoint or not endpoint_data:
+        # No active endpoint - allow
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if freshness enforcement is disabled for this endpoint
+    if endpoint_data.get("enforce_freshness") is False:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check research freshness
+    research_index = load_research_index()
+
+    if endpoint not in research_index:
+        # No research indexed yet - allow but note this is caught by enforce-research.py
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    entry = research_index[endpoint]
+    last_updated = entry.get("last_updated", "")
+    days_old = calculate_days_old(last_updated)
+
+    # Get custom threshold if set
+    threshold = endpoint_data.get("freshness_threshold_days", FRESHNESS_THRESHOLD_DAYS)
+
+    if days_old > threshold:
+        # Research is stale - block and require re-research
+        output = {
+            "decision": "block",
+            "reason": f"""🔄 STALE RESEARCH DETECTED
+
+Research for '{endpoint}' is {days_old} days old (threshold: {threshold} days).
+
+**Action Required:**
+Run `/hustle-api-research {endpoint}` to refresh the research before continuing.
+
+**Why This Matters:**
+- API documentation may have changed
+- New parameters or features may be available
+- Breaking changes may have been introduced
+- Your implementation may not match current docs
+
+**To Skip (Not Recommended):**
+Set `"enforce_freshness": false` in api-dev-state.json for this endpoint.
+
+Last researched: {last_updated or 'Unknown'}
+Research location: .claude/research/{endpoint}/CURRENT.md"""
+        }
+        print(json.dumps(output))
+        sys.exit(2)  # Exit code 2 = block with message
+
+    # Research is fresh - continue
+    print(json.dumps({"continue": True}))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/enforce-page-components.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""
+Hook: enforce-page-components.py
+Trigger: PreToolUse (Write|Edit)
+Purpose: Check that components from registry are considered before creating new ones
+
+For ui-create-page workflow, ensures Phase 5 (PAGE ANALYSIS) is complete and
+encourages reuse of existing components from the registry.
+"""
+
+import json
+import sys
+import os
+import re
+
+def load_state():
+    """Load the api-dev-state.json file"""
+    state_paths = [
+        ".claude/api-dev-state.json",
+        os.path.join(os.environ.get("CLAUDE_PROJECT_DIR", ""), ".claude/api-dev-state.json")
+    ]
+
+    for path in state_paths:
+        if os.path.exists(path):
+            with open(path, 'r') as f:
+                return json.load(f)
+    return None
+
+def load_registry():
+    """Load the registry.json file"""
+    registry_paths = [
+        ".claude/registry.json",
+        os.path.join(os.environ.get("CLAUDE_PROJECT_DIR", ""), ".claude/registry.json")
+    ]
+
+    for path in registry_paths:
+        if os.path.exists(path):
+            with open(path, 'r') as f:
+                return json.load(f)
+    return {}
+
+def is_page_workflow(state):
+    """Check if current workflow is ui-create-page"""
+    workflow = state.get("workflow", "")
+    return workflow == "ui-create-page"
+
+def get_active_element(state):
+    """Get the active element being worked on"""
+    active = state.get("active_element", "")
+    if not active:
+        active = state.get("endpoint", "")
+    return active
+
+def is_creating_new_component(file_path):
+    """Check if the file path suggests creating a new standalone component"""
+    if not file_path:
+        return False
+
+    # Patterns that suggest a new standalone component (not page-specific)
+    standalone_patterns = [
+        r"src/components/[A-Z]",
+        r"components/ui/",
+        r"components/shared/",
+    ]
+
+    return any(re.search(pattern, file_path) for pattern in standalone_patterns)
+
+def is_page_specific_component(file_path, element_name):
+    """Check if the file is a page-specific component (allowed)"""
+    if not file_path or not element_name:
+        return False
+
+    # Page-specific components in _components folder are allowed
+    patterns = [
+        f"src/app/{element_name}/_components/",
+        f"app/{element_name}/_components/",
+    ]
+
+    return any(pattern in file_path for pattern in patterns)
+
+def check_page_analysis_phase(state, element_name):
+    """Check if page analysis phase is complete"""
+    elements = state.get("elements", {})
+    element = elements.get(element_name, {})
+    phases = element.get("phases", {})
+
+    page_analysis = phases.get("page_analysis", {})
+    return page_analysis.get("status") == "complete"
+
+def get_available_components(registry):
+    """Get list of available components from registry"""
+    components = registry.get("components", {})
+    return list(components.keys())
+
+def main():
+    try:
+        # Read tool input from stdin
+        input_data = json.loads(sys.stdin.read())
+        tool_name = input_data.get("tool_name", "")
+        tool_input = input_data.get("tool_input", {})
+
+        # Only check Write tool
+        if tool_name != "Write":
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        file_path = tool_input.get("file_path", "")
+
+        # Load state
+        state = load_state()
+        if not state:
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        # Only apply to ui-create-page workflow
+        if not is_page_workflow(state):
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        element_name = get_active_element(state)
+        if not element_name:
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        # Allow page-specific components (in _components folder)
+        if is_page_specific_component(file_path, element_name):
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        # Check if creating a new standalone component
+        if is_creating_new_component(file_path):
+            # Check if page analysis phase is complete
+            if not check_page_analysis_phase(state, element_name):
+                # Load registry to show available components
+                registry = load_registry()
+                available = get_available_components(registry)
+
+                component_list = "\n".join([f"  - {c}" for c in available[:10]])
+                if len(available) > 10:
+                    component_list += f"\n  ... and {len(available) - 10} more"
+
+                print(json.dumps({
+                    "decision": "block",
+                    "reason": f"""
+PAGE ANALYSIS REQUIRED (Phase 5)
+
+You are creating a new standalone component, but Page Analysis phase is not complete.
+
+Before creating new components:
+1. Check the registry for existing components
+2. Decide which existing components to reuse
+3. Update state: phases.page_analysis.status = "complete"
+
+Available Components in Registry:
+{component_list if available else "  (No components registered yet)"}
+
+If you need a NEW component, consider:
+- Using /ui-create to properly create and document it
+- Or create a page-specific component in src/app/{element_name}/_components/
+"""
+                }))
+                return
+
+            # Even if phase is complete, notify about registry
+            registry = load_registry()
+            available = get_available_components(registry)
+
+            if available:
+                print(json.dumps({
+                    "decision": "allow",
+                    "message": f"Note: {len(available)} components available in registry. Consider reusing existing components."
+                }))
+                return
+
+        # Allow everything else
+        print(json.dumps({"decision": "allow"}))
+
+    except Exception as e:
+        # On error, allow to avoid blocking workflow
+        print(json.dumps({
+            "decision": "allow",
+            "error": str(e)
+        }))
+
+if __name__ == "__main__":
+    main()

package/hooks/enforce-page-data-schema.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""
+Hook: enforce-page-data-schema.py
+Trigger: PreToolUse (Write|Edit)
+Purpose: Validate that API response types are defined before page implementation
+
+For ui-create-page workflow, ensures Phase 6 (DATA SCHEMA) is complete before
+allowing page implementation in Phase 9.
+"""
+
+import json
+import sys
+import os
+import re
+
+def load_state():
+    """Load the api-dev-state.json file"""
+    state_paths = [
+        ".claude/api-dev-state.json",
+        os.path.join(os.environ.get("CLAUDE_PROJECT_DIR", ""), ".claude/api-dev-state.json")
+    ]
+
+    for path in state_paths:
+        if os.path.exists(path):
+            with open(path, 'r') as f:
+                return json.load(f)
+    return None
+
+def is_page_workflow(state):
+    """Check if current workflow is ui-create-page"""
+    workflow = state.get("workflow", "")
+    return workflow == "ui-create-page"
+
+def get_active_element(state):
+    """Get the active element being worked on"""
+    active = state.get("active_element", "")
+    if not active:
+        # Fall back to endpoint for older state files
+        active = state.get("endpoint", "")
+    return active
+
+def is_page_file(file_path, element_name):
+    """Check if the file being written is a page implementation file"""
+    if not file_path or not element_name:
+        return False
+
+    patterns = [
+        f"src/app/{element_name}/page.tsx",
+        f"src/app/{element_name}/layout.tsx",
+        f"src/app/{element_name}/_components/",
+        f"app/{element_name}/page.tsx",
+    ]
+
+    return any(pattern in file_path for pattern in patterns)
+
+def is_types_file(file_path, element_name):
+    """Check if the file being written is the types/schema file"""
+    if not file_path or not element_name:
+        return False
+
+    patterns = [
+        f"src/app/{element_name}/_types/",
+        f"src/app/{element_name}/types.ts",
+        f"src/lib/schemas/{element_name}",
+    ]
+
+    return any(pattern in file_path for pattern in patterns)
+
+def is_test_file(file_path):
+    """Check if file is a test file"""
+    return "__tests__" in file_path or ".test." in file_path or ".spec." in file_path
+
+def check_data_schema_phase(state, element_name):
+    """Check if data schema phase is complete"""
+    elements = state.get("elements", {})
+    element = elements.get(element_name, {})
+    phases = element.get("phases", {})
+
+    # Check data_schema phase
+    data_schema = phases.get("data_schema", {})
+    return data_schema.get("status") == "complete"
+
+def main():
+    try:
+        # Read tool input from stdin
+        input_data = json.loads(sys.stdin.read())
+        tool_name = input_data.get("tool_name", "")
+        tool_input = input_data.get("tool_input", {})
+
+        # Only check Write and Edit tools
+        if tool_name not in ["Write", "Edit"]:
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        file_path = tool_input.get("file_path", "")
+
+        # Load state
+        state = load_state()
+        if not state:
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        # Only apply to ui-create-page workflow
+        if not is_page_workflow(state):
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        element_name = get_active_element(state)
+        if not element_name:
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        # Allow writing types/schema files (Phase 6)
+        if is_types_file(file_path, element_name):
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        # Allow writing test files (Phase 8)
+        if is_test_file(file_path):
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        # Check if writing page implementation file
+        if is_page_file(file_path, element_name):
+            # Verify data schema phase is complete
+            if not check_data_schema_phase(state, element_name):
+                print(json.dumps({
+                    "decision": "block",
+                    "reason": f"""
+DATA SCHEMA REQUIRED (Phase 6)
+
+You are trying to implement page code, but the data schema phase is not complete.
+
+Before writing page implementation:
+1. Define TypeScript interfaces for API responses
+2. Create types in src/app/{element_name}/_types/index.ts
+3. Update state: phases.data_schema.status = "complete"
+
+Page implementation requires knowing the data structure first.
+"""
+                }))
+                return
+
+        # Allow everything else
+        print(json.dumps({"decision": "allow"}))
+
+    except Exception as e:
+        # On error, allow to avoid blocking workflow
+        print(json.dumps({
+            "decision": "allow",
+            "error": str(e)
+        }))
+
+if __name__ == "__main__":
+    main()