@hustle-together/api-dev-tools 3.12.3 → 3.12.16

package/.claude/hooks/enforce-dry-run.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""
+Enforce Dry-Run Mode Hook
+
+This hook blocks Write and Edit operations when --dry-run mode is active.
+It allows the workflow to run completely (research, interviews, schema generation)
+but prevents any files from being written.
+
+Hook Type: PreToolUse (matcher: Write, Edit)
+
+Use Cases:
+- Preview what a workflow will create before committing
+- Test autonomous mode without modifying files
+- Validate workflow logic without side effects
+
+v4.5.0: Initial implementation
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+# Import shared utilities
+try:
+    from hook_utils import (
+        check_dry_run_mode,
+        log_workflow_event,
+        load_state
+    )
+    UTILS_AVAILABLE = True
+except ImportError:
+    UTILS_AVAILABLE = False
+
+
+def get_file_path_from_env():
+    """Extract file path from tool input environment variable."""
+    tool_input = os.environ.get("CLAUDE_TOOL_INPUT", "{}")
+    try:
+        data = json.loads(tool_input)
+        return data.get("file_path", "unknown")
+    except json.JSONDecodeError:
+        return "unknown"
+
+
+def main():
+    """Main hook entry point."""
+    tool_name = os.environ.get("CLAUDE_TOOL_NAME", "")
+
+    # Only enforce for Write and Edit tools
+    if tool_name not in ["Write", "Edit"]:
+        print(json.dumps({"continue": True}))
+        return
+
+    # Check if dry-run mode is active
+    dry_run_active = False
+
+    if UTILS_AVAILABLE:
+        try:
+            dry_run_active = check_dry_run_mode()
+        except Exception:
+            pass
+    else:
+        # Fallback: check state file directly
+        try:
+            project_dir = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+            state_file = Path(project_dir) / ".claude" / "api-dev-state.json"
+            if state_file.exists():
+                state = json.loads(state_file.read_text())
+                dry_run_active = state.get("dry_run_mode", False) or state.get("flags", {}).get("dry_run", False)
+        except Exception:
+            pass
+
+    if not dry_run_active:
+        # Normal mode - allow the operation
+        print(json.dumps({"continue": True}))
+        return
+
+    # Dry-run mode active - block the write
+    file_path = get_file_path_from_env()
+
+    # Log the blocked operation
+    if UTILS_AVAILABLE:
+        try:
+            log_workflow_event("dry_run_block", {
+                "tool": tool_name,
+                "file_path": file_path,
+                "action": "blocked"
+            })
+        except Exception:
+            pass
+
+    # Return blocking result with informative message
+    result = {
+        "continue": False,
+        "reason": f"""## 🔒 Dry-Run Mode Active
+
+**Tool:** {tool_name}
+**Would write to:** `{file_path}`
+
+In dry-run mode, no files are modified. The workflow continues to show
+what WOULD be created, but Write and Edit operations are blocked.
+
+### To Execute For Real:
+1. Run the same command without `--dry-run`
+2. Or disable dry-run: Update state with `dry_run_mode: false`
+
+### Preview Summary:
+This operation would {_get_operation_description(tool_name, file_path)}
+
+---
+_Dry-run preview - no files were modified_
+"""
+    }
+    print(json.dumps(result))
+
+
+def _get_operation_description(tool_name, file_path):
+    """Generate a human-readable description of the blocked operation."""
+    path = Path(file_path)
+
+    if tool_name == "Write":
+        if not path.exists() if file_path != "unknown" else True:
+            return f"create a new file at `{file_path}`"
+        return f"overwrite the file at `{file_path}`"
+
+    if tool_name == "Edit":
+        return f"modify the file at `{file_path}`"
+
+    return f"perform a {tool_name} operation on `{file_path}`"
+
+
+if __name__ == "__main__":
+    main()

package/.claude/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/.claude/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/.claude/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()