@hustle-together/api-dev-tools 3.6.4 → 3.9.2

package/hooks/enforce-brand-guide.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit
+Purpose: Inject brand guide content during UI implementation
+
+This hook runs before writing component/page files. When use_brand_guide=true
+in the state, it logs the brand guide summary to remind Claude to apply
+consistent branding.
+
+Version: 3.9.0
+
+Returns:
+  - {"continue": true} - Always continues
+  - May include "notify" with brand guide summary
+"""
+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"
+BRAND_GUIDE_FILE = Path(__file__).parent.parent / "BRAND_GUIDE.md"
+
+
+def extract_brand_summary(content):
+    """Extract key brand values from brand guide markdown."""
+    summary = []
+
+    lines = content.split("\n")
+    current_section = ""
+
+    for line in lines:
+        line = line.strip()
+
+        # Track section
+        if line.startswith("## "):
+            current_section = line[3:].lower()
+            continue
+
+        # Extract key values
+        if line.startswith("- **") and ":" in line:
+            # Parse "- **Key:** Value" format
+            try:
+                key_part = line.split(":**")[0].replace("- **", "")
+                value_part = line.split(":**")[1].strip()
+
+                # Only include primary brand values
+                if current_section == "colors" and key_part in ["Primary", "Accent", "Background"]:
+                    summary.append(f"{key_part}: {value_part}")
+                elif current_section == "typography" and key_part in ["Headings", "Body"]:
+                    summary.append(f"{key_part}: {value_part}")
+                elif current_section == "component styling" and key_part in ["Border Radius", "Focus Ring"]:
+                    summary.append(f"{key_part}: {value_part}")
+            except IndexError:
+                continue
+
+    return summary
+
+
+def main():
+    # Read hook input from stdin
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+
+    # Only check Write/Edit operations
+    if tool_name not in ["Write", "Edit"]:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if targeting component or page files
+    file_path = tool_input.get("file_path", "")
+    is_component = "/components/" in file_path and file_path.endswith(".tsx")
+    is_page = "/app/" in file_path and "page.tsx" in file_path
+
+    if not is_component and not is_page:
+        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)
+
+    # Load state
+    try:
+        state = json.loads(STATE_FILE.read_text())
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    workflow = state.get("workflow", "")
+
+    # Only apply for UI workflows
+    if workflow not in ["ui-create-component", "ui-create-page"]:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if brand guide is enabled
+    ui_config = state.get("ui_config", {})
+    use_brand_guide = ui_config.get("use_brand_guide", False)
+
+    if not use_brand_guide:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if brand guide file exists
+    if not BRAND_GUIDE_FILE.exists():
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Extract brand summary
+    brand_content = BRAND_GUIDE_FILE.read_text()
+    summary = extract_brand_summary(brand_content)
+
+    if summary:
+        notify_msg = "Applying brand guide: " + " | ".join(summary[:5])
+        print(json.dumps({"continue": True, "notify": notify_msg}))
+    else:
+        print(json.dumps({"continue": True}))
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

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-questions-sourced.py

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