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

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

package/hooks/enforce-schema-from-interview.py

@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit on schema files
+Purpose: Validate schema fields match interview decisions
+
+This hook ensures that when writing Zod schema files, the fields
+match what the user selected during the interview phase.
+
+Added in v3.6.7 for schema-interview consistency enforcement.
+
+Returns:
+  - {"permissionDecision": "allow"} - Schema matches interview
+  - {"permissionDecision": "allow", "message": "..."} - Allow with warning
+  - {"permissionDecision": "deny", "reason": "..."} - Block with explanation
+"""
+import json
+import sys
+import re
+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 extract_schema_fields_from_content(content):
+    """Extract field names from Zod schema content."""
+    fields = set()
+
+    # Match Zod object field definitions
+    # Patterns like: fieldName: z.string(), fieldName: z.number().optional()
+    field_pattern = r'(\w+):\s*z\.\w+\('
+
+    for match in re.finditer(field_pattern, content):
+        field_name = match.group(1)
+        # Skip common non-field names
+        if field_name not in {'z', 'const', 'export', 'type', 'interface'}:
+            fields.add(field_name.lower())
+
+    return fields
+
+
+def extract_interview_approved_fields(endpoint_data):
+    """Extract field names that were approved during interview."""
+    approved_fields = set()
+
+    interview = endpoint_data.get("phases", {}).get("interview", {})
+    decisions = interview.get("decisions", {})
+    questions = interview.get("questions", [])
+
+    # Extract from decisions
+    for key, value in decisions.items():
+        # Decision keys often match field names
+        approved_fields.add(key.lower())
+
+        # Values might be lists of approved options
+        if isinstance(value, list):
+            for v in value:
+                if isinstance(v, str):
+                    approved_fields.add(v.lower())
+        elif isinstance(value, str):
+            approved_fields.add(value.lower())
+
+    # Extract from question text (look for parameters mentioned)
+    for q in questions:
+        if isinstance(q, dict):
+            q_text = q.get("question", "") + " " + q.get("answer", "")
+        else:
+            q_text = str(q)
+
+        # Look for parameter-like words
+        param_pattern = r'\b(param|field|property|attribute)[:=\s]+["\']?(\w+)["\']?'
+        for match in re.finditer(param_pattern, q_text, re.IGNORECASE):
+            approved_fields.add(match.group(2).lower())
+
+        # Also extract snake_case and camelCase words that look like fields
+        field_like = re.findall(r'\b([a-z][a-z0-9]*(?:_[a-z0-9]+)+)\b', q_text, re.IGNORECASE)
+        for f in field_like:
+            approved_fields.add(f.lower())
+
+        field_like = re.findall(r'\b([a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)+)\b', q_text)
+        for f in field_like:
+            # Convert camelCase to lowercase for comparison
+            approved_fields.add(f.lower())
+
+    # Extract from scope if available
+    scope = endpoint_data.get("scope", {})
+    for feature in scope.get("implemented_features", []):
+        if isinstance(feature, dict):
+            approved_fields.add(feature.get("name", "").lower())
+        else:
+            approved_fields.add(str(feature).lower())
+
+    return approved_fields
+
+
+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", {})
+
+    # Only check Write and Edit tools
+    if tool_name not in ["Write", "Edit"]:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Check if writing to a schema file
+    file_path = tool_input.get("file_path", "")
+
+    # Detect schema files by path patterns
+    is_schema_file = any([
+        "/schemas/" in file_path,
+        "schema.ts" in file_path.lower(),
+        "schemas.ts" in file_path.lower(),
+        ".schema.ts" in file_path.lower(),
+    ])
+
+    if not is_schema_file:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Load state
+    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)
+
+    # Check if interview phase is complete
+    interview = endpoint_data.get("phases", {}).get("interview", {})
+    if interview.get("status") != "complete":
+        # Interview not done yet - allow but warn
+        print(json.dumps({
+            "permissionDecision": "allow",
+            "message": "WARNING: Writing schema before interview is complete. Schema fields should be derived from interview decisions."
+        }))
+        sys.exit(0)
+
+    # Get schema content being written
+    if tool_name == "Write":
+        schema_content = tool_input.get("content", "")
+    else:  # Edit
+        new_string = tool_input.get("new_string", "")
+        schema_content = new_string
+
+    if not schema_content:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Extract fields from schema
+    schema_fields = extract_schema_fields_from_content(schema_content)
+
+    if not schema_fields:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Extract approved fields from interview
+    approved_fields = extract_interview_approved_fields(endpoint_data)
+
+    if not approved_fields:
+        # No interview data to compare against
+        print(json.dumps({
+            "permissionDecision": "allow",
+            "message": "NOTE: No interview decisions found to validate schema against."
+        }))
+        sys.exit(0)
+
+    # Find fields in schema that weren't discussed in interview
+    # Use fuzzy matching - if any part of field name matches approved
+    unmatched_fields = []
+    for field in schema_fields:
+        matched = False
+        for approved in approved_fields:
+            # Check if field contains or is contained by approved field
+            if field in approved or approved in field:
+                matched = True
+                break
+            # Check word overlap
+            field_words = set(re.split(r'[_\s]', field))
+            approved_words = set(re.split(r'[_\s]', approved))
+            if field_words & approved_words:
+                matched = True
+                break
+
+        if not matched:
+            unmatched_fields.append(field)
+
+    # Common fields that are always okay
+    common_fields = {'id', 'createdat', 'updatedat', 'error', 'message', 'success', 'data', 'status', 'result'}
+    unmatched_fields = [f for f in unmatched_fields if f not in common_fields]
+
+    if unmatched_fields:
+        # Found fields not in interview - warn but allow
+        print(json.dumps({
+            "permissionDecision": "allow",
+            "message": f"""SCHEMA VALIDATION NOTE:
+
+The following schema fields were not explicitly discussed in the interview:
+  {', '.join(unmatched_fields[:5])}{'...' if len(unmatched_fields) > 5 else ''}
+
+Interview-approved terms: {', '.join(list(approved_fields)[:10])}{'...' if len(approved_fields) > 10 else ''}
+
+This is allowed, but consider:
+1. Did research discover these fields?
+2. Should the user be asked about these?
+3. Are these derived from approved fields?
+
+Proceeding with schema write."""
+        }))
+        sys.exit(0)
+
+    # All fields match interview
+    print(json.dumps({
+        "permissionDecision": "allow",
+        "message": f"Schema fields validated against interview: {', '.join(list(schema_fields)[:5])}"
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/enforce-ui-disambiguation.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit
+Purpose: Block UI implementation until component/page type is clarified (Phase 1)
+
+This hook ensures that Phase 1 (Disambiguation) is complete before any
+component or page files are written. It checks that:
+- Component type (atom/molecule/organism) is specified for components
+- Page type (landing/dashboard/form/list) is specified for pages
+
+Version: 3.9.0
+
+Returns:
+  - {"continue": true} - If disambiguation is complete or not a UI workflow
+  - {"continue": false, "reason": "..."} - If disambiguation is incomplete
+"""
+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"
+
+
+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 enforce for UI workflows
+    if workflow not in ["ui-create-component", "ui-create-page"]:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Get UI config
+    ui_config = state.get("ui_config", {})
+
+    # Check disambiguation for components
+    if workflow == "ui-create-component":
+        component_type = ui_config.get("component_type", "")
+        if not component_type:
+            print(json.dumps({
+                "continue": False,
+                "reason": (
+                    "Phase 1 (Disambiguation) incomplete.\n\n"
+                    "Before creating this component, you must clarify:\n"
+                    "- Is this an Atom, Molecule, or Organism?\n\n"
+                    "Please complete the disambiguation phase first."
+                )
+            }))
+            sys.exit(0)
+
+    # Check disambiguation for pages
+    if workflow == "ui-create-page":
+        page_type = ui_config.get("page_type", "")
+        if not page_type:
+            print(json.dumps({
+                "continue": False,
+                "reason": (
+                    "Phase 1 (Disambiguation) incomplete.\n\n"
+                    "Before creating this page, you must clarify:\n"
+                    "- Is this a Landing, Dashboard, Form, or List page?\n\n"
+                    "Please complete the disambiguation phase first."
+                )
+            }))
+            sys.exit(0)
+
+    # Disambiguation complete
+    print(json.dumps({"continue": True}))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/enforce-ui-interview.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit
+Purpose: Inject UI interview decisions during component/page implementation
+
+This hook injects the user's interview answers (variants, accessibility level,
+component dependencies, etc.) when Claude writes implementation code.
+This ensures the implementation matches what the user specified.
+
+Version: 3.9.0
+
+Returns:
+  - {"continue": true} - Always continues
+  - May include "notify" with key decisions 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"
+
+
+def format_decisions(decisions):
+    """Format interview decisions for display."""
+    formatted = []
+
+    for key, value in decisions.items():
+        if isinstance(value, dict):
+            # Extract value from nested structure
+            display_value = value.get("value", value.get("response", str(value)))
+        else:
+            display_value = value
+
+        # Format for display
+        if isinstance(display_value, list):
+            display_value = ", ".join(str(v) for v in display_value)
+        elif isinstance(display_value, bool):
+            display_value = "Yes" if display_value else "No"
+
+        formatted.append(f"{key}: {display_value}")
+
+    return formatted
+
+
+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)
+
+    # Get interview decisions
+    # Try elements format first, then fall back to phases format
+    active_element = state.get("active_element", "")
+    elements = state.get("elements", {})
+
+    if active_element and active_element in elements:
+        phases = elements[active_element].get("phases", {})
+    else:
+        phases = state.get("phases", {})
+
+    interview = phases.get("interview", {})
+    decisions = interview.get("decisions", {})
+
+    if not decisions:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Format key decisions for notification
+    formatted = format_decisions(decisions)
+
+    # Limit to most important decisions
+    key_decisions = []
+    priority_keys = ["component_type", "page_type", "variants", "accessibility", "design_system", "data_fetching"]
+
+    for key in priority_keys:
+        for f in formatted:
+            if f.lower().startswith(key.replace("_", " ")):
+                key_decisions.append(f)
+                break
+
+    if key_decisions:
+        notify_msg = "Interview decisions: " + " | ".join(key_decisions[:4])
+        print(json.dumps({"continue": True, "notify": notify_msg}))
+    else:
+        print(json.dumps({"continue": True}))
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()