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

package/hooks/api-workflow-check.py

@@ -49,6 +49,127 @@ RECOMMENDED_PHASES = [
     ("documentation", "Documentation updates"),
 ]
 
+# Combine workflow specific phases
+COMBINE_REQUIRED_PHASES = [
+    ("selection", "API selection (2+ APIs required)"),
+    ("scope", "Scope confirmation"),
+    ("research_initial", "Initial research"),
+    ("interview", "User interview"),
+    ("research_deep", "Deep research"),
+    ("schema_creation", "Combined schema creation"),
+    ("environment_check", "Environment check"),
+    ("tdd_red", "TDD Red phase"),
+    ("tdd_green", "TDD Green phase"),
+    ("verify", "Verification phase"),
+    ("documentation", "Documentation updates"),
+]
+
+# UI workflow specific phases
+UI_REQUIRED_PHASES = [
+    ("disambiguation", "Component/Page type disambiguation"),
+    ("scope", "Scope confirmation"),
+    ("design_research", "Design research"),
+    ("interview", "User interview"),
+    ("tdd_red", "TDD Red phase"),
+    ("tdd_green", "TDD Green phase"),
+    ("verify", "Verification phase (4-step)"),
+    ("documentation", "Documentation updates"),
+]
+
+
+def get_workflow_type(state):
+    """Detect the workflow type from state."""
+    workflow = state.get("workflow", "")
+    if workflow:
+        return workflow
+
+    # Infer from state structure
+    if state.get("combine_config"):
+        return "combine-api"
+    if state.get("ui_config"):
+        mode = state.get("ui_config", {}).get("mode", "")
+        return f"ui-create-{mode}" if mode else "ui-create-component"
+
+    return "api-create"
+
+
+def get_required_phases_for_workflow(workflow_type):
+    """Get the required phases list for a given workflow type."""
+    if workflow_type == "combine-api":
+        return COMBINE_REQUIRED_PHASES
+    elif workflow_type.startswith("ui-create"):
+        return UI_REQUIRED_PHASES
+    else:
+        return REQUIRED_PHASES
+
+
+def validate_combine_workflow(state):
+    """Validate combine-specific requirements.
+
+    Returns list of issues if validation fails, empty list if OK.
+    """
+    issues = []
+
+    combine_config = state.get("combine_config", {})
+    if not combine_config:
+        issues.append("❌ Combine config not found in state")
+        return issues
+
+    # Check that at least 2 APIs are selected
+    source_elements = combine_config.get("source_elements", [])
+    if len(source_elements) < 2:
+        issues.append(f"❌ Combine requires 2+ APIs, found {len(source_elements)}")
+        issues.append("   Select more APIs in Phase 1 (SELECTION)")
+
+    # Verify all source APIs exist in registry
+    try:
+        registry_path = STATE_FILE.parent / "registry.json"
+        if registry_path.exists():
+            registry = json.loads(registry_path.read_text())
+            apis = registry.get("apis", {})
+
+            for elem in source_elements:
+                elem_name = elem.get("name", "") if isinstance(elem, dict) else str(elem)
+                if elem_name and elem_name not in apis:
+                    issues.append(f"⚠️ Source API '{elem_name}' not found in registry")
+                    issues.append(f"   Run /api-create {elem_name} first")
+    except Exception:
+        pass
+
+    # Check flow type is defined
+    flow_type = combine_config.get("flow_type", "")
+    if not flow_type:
+        issues.append("⚠️ Flow type not defined (sequential/parallel/conditional)")
+
+    return issues
+
+
+def validate_ui_workflow(state):
+    """Validate UI-specific requirements.
+
+    Returns list of issues if validation fails, empty list if OK.
+    """
+    issues = []
+
+    ui_config = state.get("ui_config", {})
+    if not ui_config:
+        # Try to get from active element
+        active = state.get("active_element", "")
+        if active:
+            elements = state.get("elements", {})
+            element = elements.get(active, {})
+            ui_config = element.get("ui_config", {})
+
+    if not ui_config:
+        issues.append("⚠️ UI config not found in state")
+        return issues
+
+    # Check brand guide was applied
+    if not ui_config.get("use_brand_guide"):
+        issues.append("⚠️ Brand guide not applied - design may not match project standards")
+
+    return issues
+
 
 def get_active_endpoint(state):
     """Get active endpoint - supports both old and new state formats."""
@@ -58,11 +179,23 @@ def get_active_endpoint(state):
             return active, state["endpoints"][active]
         return None, None
 
+    # Support for elements (UI workflow)
+    if "elements" in state and "active_element" in state:
+        active = state.get("active_element")
+        if active and active in state["elements"]:
+            return active, state["elements"][active]
+        return None, None
+
     # Old format: single endpoint
     endpoint = state.get("endpoint")
     if endpoint:
         return endpoint, state
 
+    # Try active_element without elements dict
+    active = state.get("active_element")
+    if active:
+        return active, state
+
     return None, None
 
 
@@ -465,6 +598,9 @@ def main():
         print(json.dumps({"decision": "approve"}))
         sys.exit(0)
 
+    # Detect workflow type
+    workflow_type = get_workflow_type(state)
+
     # Get active endpoint (multi-API support)
     endpoint, endpoint_data = get_active_endpoint(state)
 
@@ -476,7 +612,12 @@ def main():
 
     # Check if workflow was even started
     research = phases.get("research_initial", {})
-    if research.get("status") == "not_started":
+    design_research = phases.get("design_research", {})  # For UI workflows
+    selection = phases.get("selection", {})  # For combine workflows
+
+    if (research.get("status") == "not_started" and
+        design_research.get("status") == "not_started" and
+        selection.get("status") == "not_started"):
         # Workflow not started, allow stop
         print(json.dumps({"decision": "approve"}))
         sys.exit(0)
@@ -484,9 +625,26 @@ def main():
     # Collect all issues
     all_issues = []
 
+    # Workflow-specific validation
+    if workflow_type == "combine-api":
+        combine_issues = validate_combine_workflow(state)
+        if combine_issues:
+            all_issues.append("❌ COMBINE WORKFLOW VALIDATION FAILED:")
+            all_issues.extend(combine_issues)
+            all_issues.append("")
+
+    elif workflow_type.startswith("ui-create"):
+        ui_issues = validate_ui_workflow(state)
+        if ui_issues:
+            all_issues.extend(ui_issues)
+            all_issues.append("")
+
+    # Get the correct required phases for this workflow
+    required_phases = get_required_phases_for_workflow(workflow_type)
+
     # Check required phases
     incomplete_required = []
-    for phase_key, phase_name in REQUIRED_PHASES:
+    for phase_key, phase_name in required_phases:
         phase = phases.get(phase_key, {})
         status = phase.get("status", "not_started")
         if status != "complete":

package/hooks/check-api-routes.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""
+Hook: check-api-routes.py
+Trigger: PreToolUse (Write|Edit)
+Purpose: Verify required API routes exist before page implementation
+
+For ui-create-page workflow, ensures Phase 7 (ENVIRONMENT) has verified
+that required API routes are available.
+"""
+
+import json
+import sys
+import os
+import glob
+
+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:
+        active = state.get("endpoint", "")
+    return active
+
+def is_page_implementation(file_path, element_name):
+    """Check if the file is a page implementation file"""
+    if not file_path or not element_name:
+        return False
+
+    patterns = [
+        f"src/app/{element_name}/page.tsx",
+        f"app/{element_name}/page.tsx",
+    ]
+
+    return any(pattern in file_path for pattern in patterns)
+
+def check_environment_phase(state, element_name):
+    """Check if environment phase is complete"""
+    elements = state.get("elements", {})
+    element = elements.get(element_name, {})
+    phases = element.get("phases", {})
+
+    environment = phases.get("environment_check", {})
+    return environment.get("status") == "complete"
+
+def get_required_api_routes(state, element_name):
+    """Get list of required API routes from interview decisions"""
+    elements = state.get("elements", {})
+    element = elements.get(element_name, {})
+    ui_config = element.get("ui_config", {})
+
+    # Check if data sources were defined
+    data_sources = ui_config.get("data_sources", [])
+    return data_sources
+
+def find_existing_api_routes():
+    """Find all existing API routes in the project"""
+    routes = []
+
+    # Check src/app/api paths
+    api_patterns = [
+        "src/app/api/**/*.ts",
+        "src/app/api/**/*.tsx",
+        "app/api/**/*.ts",
+        "app/api/**/*.tsx",
+    ]
+
+    for pattern in api_patterns:
+        for file_path in glob.glob(pattern, recursive=True):
+            if "route.ts" in file_path or "route.tsx" in file_path:
+                # Extract route name from path
+                route = file_path.replace("src/app/api/", "/api/")
+                route = route.replace("app/api/", "/api/")
+                route = route.replace("/route.ts", "")
+                route = route.replace("/route.tsx", "")
+                routes.append(route)
+
+    return routes
+
+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
+
+        # Check if writing main page file
+        if is_page_implementation(file_path, element_name):
+            # Verify environment phase is complete
+            if not check_environment_phase(state, element_name):
+                # Find existing API routes for reference
+                existing_routes = find_existing_api_routes()
+                routes_list = "\n".join([f"  - {r}" for r in existing_routes[:15]])
+                if len(existing_routes) > 15:
+                    routes_list += f"\n  ... and {len(existing_routes) - 15} more"
+
+                print(json.dumps({
+                    "decision": "block",
+                    "reason": f"""
+ENVIRONMENT CHECK REQUIRED (Phase 7)
+
+You are implementing the main page, but the Environment phase is not complete.
+
+Before implementing page.tsx:
+1. Verify required API routes exist
+2. Check authentication configuration
+3. Verify required packages are installed
+4. Update state: phases.environment_check.status = "complete"
+
+Existing API Routes Found:
+{routes_list if existing_routes else "  (No API routes found)"}
+
+If you need new API routes, use /api-create to create them 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/hooks/enforce-a11y-audit.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""
+Hook: PostToolUse for Write/Edit
+Purpose: Trigger accessibility audit after UI component/page implementation
+
+This hook runs after Phase 9 (TDD GREEN) for UI workflows. It notifies Claude
+to run axe-core audit on Storybook stories or pages to verify WCAG compliance.
+
+Version: 3.10.0
+
+Returns:
+  - {"continue": true} - Always continues
+  - May include "notify" with accessibility check reminder
+  - May include "additionalContext" with accessibility guidelines
+"""
+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"
+
+# WCAG 2.1 Level AA Quick Reference
+WCAG_AA_CHECKLIST = [
+    "Color contrast: 4.5:1 for normal text, 3:1 for large text",
+    "Focus visible: All interactive elements show focus state",
+    "Keyboard nav: All functionality accessible via keyboard",
+    "Labels: All form inputs have associated labels",
+    "Alt text: All images have meaningful alt text",
+    "Headings: Proper heading hierarchy (h1-h6)",
+    "Touch targets: Min 44x44px for touch targets",
+    "Error messages: Clear error identification and suggestions",
+]
+
+
+def get_workflow_type(state):
+    """Detect the workflow type from state."""
+    workflow = state.get("workflow", "")
+    if workflow:
+        return workflow
+
+    if state.get("ui_config"):
+        mode = state.get("ui_config", {}).get("mode", "")
+        return f"ui-create-{mode}" if mode else "ui-create-component"
+
+    return "api-create"
+
+
+def get_active_element(state):
+    """Get active element name and data."""
+    if "elements" in state and "active_element" in state:
+        active = state.get("active_element")
+        if active and active in state["elements"]:
+            return active, state["elements"][active]
+        return None, None
+
+    active = state.get("active_element")
+    if active:
+        return active, state
+
+    return None, None
+
+
+def is_verify_phase(phases):
+    """Check if we're in or just completed the verify phase."""
+    verify = phases.get("verify", {})
+    tdd_green = phases.get("tdd_green", {})
+
+    # After green, before or during verify
+    return (
+        tdd_green.get("status") == "complete" and
+        verify.get("status") in ["not_started", "in_progress"]
+    )
+
+
+def get_accessibility_level(state, element_data):
+    """Get the accessibility level requirement."""
+    ui_config = state.get("ui_config", {})
+    if not ui_config and element_data:
+        ui_config = element_data.get("ui_config", {})
+
+    return ui_config.get("accessibility_level", "AA")
+
+
+def generate_a11y_commands(element_name, workflow_type):
+    """Generate accessibility testing commands."""
+    commands = []
+
+    if "component" in workflow_type:
+        commands.extend([
+            f"# Storybook accessibility check",
+            f"pnpm storybook --ci",
+            f"# Then run axe in browser or:",
+            f"pnpm dlx @storybook/test-runner --url http://localhost:6006",
+            f"",
+            f"# Or manual axe-core check:",
+            f"pnpm dlx @axe-core/cli http://localhost:6006/?path=/story/{element_name.lower()}--default"
+        ])
+    else:
+        commands.extend([
+            f"# Page accessibility check",
+            f"pnpm dev",
+            f"# Then in another terminal:",
+            f"pnpm dlx @axe-core/cli http://localhost:3000/{element_name}",
+            f"",
+            f"# Or use Playwright accessibility tests:",
+            f"pnpm test:e2e --grep 'accessibility'"
+        ])
+
+    return "\n".join(commands)
+
+
+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", "")
+
+    # Only process Write/Edit operations
+    if tool_name not in ["Write", "Edit"]:
+        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_type = get_workflow_type(state)
+
+    # Only apply for UI workflows
+    if not workflow_type.startswith("ui-create"):
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Get active element
+    element_name, element_data = get_active_element(state)
+    if not element_name or not element_data:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    phases = element_data.get("phases", {}) if element_data else state.get("phases", {})
+
+    # Check if we should trigger a11y audit (after TDD Green)
+    if not is_verify_phase(phases):
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Get accessibility level
+    a11y_level = get_accessibility_level(state, element_data)
+
+    # Generate audit commands
+    commands = generate_a11y_commands(element_name, workflow_type)
+
+    # Build accessibility context
+    checklist = "\n".join([f"  - {item}" for item in WCAG_AA_CHECKLIST])
+
+    context = f"""
+## Accessibility Audit Required (WCAG 2.1 {a11y_level})
+
+The TDD Green phase is complete. Before marking verify as complete, run an accessibility audit.
+
+### Quick Commands
+```bash
+{commands}
+```
+
+### WCAG 2.1 {a11y_level} Checklist
+{checklist}
+
+### 4-Step Verification for UI
+1. **Responsive**: Test at 320px, 768px, 1024px, 1440px
+2. **Data Binding**: Verify all data sources load correctly
+3. **Tests**: All unit/e2e tests pass
+4. **Accessibility**: Run axe-core, fix any violations
+
+If violations are found, fix them before completing the verify phase.
+"""
+
+    output = {
+        "continue": True,
+        "notify": f"Accessibility audit required for {element_name} (WCAG 2.1 {a11y_level})",
+        "additionalContext": context
+    }
+
+    print(json.dumps(output))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()