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

package/.claude/hooks/enforce-freshness.py

@@ -1,184 +0,0 @@
-#!/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

@@ -1,186 +0,0 @@
-#!/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

@@ -1,155 +0,0 @@
-#!/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()

package/.claude/hooks/enforce-questions-sourced.py

@@ -1,146 +0,0 @@
-#!/usr/bin/env python3
-"""
-Hook: PreToolUse for AskUserQuestion
-Purpose: Validate interview questions come from research, not templates
-
-This hook ensures that questions asked during the interview phase are
-generated from actual research findings, not generic template questions.
-
-Added in v3.6.7 for question quality enforcement.
-
-Returns:
-  - {"permissionDecision": "allow"} - Question is properly sourced
-  - {"permissionDecision": "allow", "message": "..."} - Allow with reminder
-"""
-import json
-import sys
-from pathlib import Path
-
-STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
-
-
-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
-
-    endpoint = state.get("endpoint")
-    if endpoint:
-        return endpoint, state
-
-    return None, None
-
-
-def get_research_keywords(state, endpoint_data):
-    """Extract keywords from research that should appear in questions."""
-    keywords = set()
-
-    # From research queries
-    for query in state.get("research_queries", []):
-        q = query.get("query", "")
-        # Extract meaningful words (length > 3)
-        words = [w.lower() for w in q.split() if len(w) > 3]
-        keywords.update(words)
-
-    # From initial research sources
-    initial = endpoint_data.get("phases", {}).get("research_initial", {})
-    for src in initial.get("sources", []):
-        if isinstance(src, dict):
-            summary = src.get("summary", "")
-            words = [w.lower() for w in summary.split() if len(w) > 3]
-            keywords.update(words)
-
-    # From deep research sources
-    deep = endpoint_data.get("phases", {}).get("research_deep", {})
-    for src in deep.get("sources", []):
-        if isinstance(src, dict):
-            summary = src.get("summary", "")
-            words = [w.lower() for w in summary.split() if len(w) > 3]
-            keywords.update(words)
-
-    return keywords
-
-
-def main():
-    try:
-        input_data = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        print(json.dumps({"permissionDecision": "allow"}))
-        sys.exit(0)
-
-    tool_name = input_data.get("tool_name", "")
-    tool_input = input_data.get("tool_input", {})
-
-    if tool_name != "AskUserQuestion":
-        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, endpoint_data = get_active_endpoint(state)
-    if not endpoint or not endpoint_data:
-        print(json.dumps({"permissionDecision": "allow"}))
-        sys.exit(0)
-
-    # Only enforce during interview phase
-    interview = endpoint_data.get("phases", {}).get("interview", {})
-    if interview.get("status") != "in_progress":
-        print(json.dumps({"permissionDecision": "allow"}))
-        sys.exit(0)
-
-    # Check if research has been done
-    initial = endpoint_data.get("phases", {}).get("research_initial", {})
-    if initial.get("status") != "complete":
-        # Allow question but remind to do research first
-        print(json.dumps({
-            "permissionDecision": "allow",
-            "message": "REMINDER: Initial research (Phase 3) should be complete before interview. Questions should be generated FROM research findings."
-        }))
-        sys.exit(0)
-
-    # Get the question being asked
-    question = tool_input.get("question", "")
-
-    # Get research keywords
-    keywords = get_research_keywords(state, endpoint_data)
-
-    # Check if question contains any research-derived terms
-    question_lower = question.lower()
-    found_keywords = [k for k in keywords if k in question_lower]
-
-    if not found_keywords and len(keywords) > 5:
-        # No research keywords found - this might be a generic question
-        print(json.dumps({
-            "permissionDecision": "allow",
-            "message": f"""NOTE: This question doesn't appear to reference terms discovered in research.
-
-Research-derived terms include: {', '.join(list(keywords)[:10])}...
-
-BEST PRACTICE: Interview questions should be generated FROM research findings.
-Example: "I discovered the API supports [feature]. Do you want to implement this?"
-
-Proceeding anyway, but consider revising the question."""
-        }))
-        sys.exit(0)
-
-    # Question looks good
-    print(json.dumps({
-        "permissionDecision": "allow",
-        "message": f"Question references research terms: {', '.join(found_keywords[:5])}"
-    }))
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()