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

package/hooks/detect-interruption.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""
+Hook: SessionStart
+Purpose: Detect and prompt for interrupted workflows
+
+This hook runs at session start and checks if there are any
+in-progress workflows that were interrupted. If found, it injects
+a prompt asking the user if they want to resume.
+
+Added in v3.6.7 for session continuation support.
+
+Returns:
+  - JSON with additionalContext about interrupted workflows
+"""
+import json
+import sys
+import os
+from datetime import datetime
+from pathlib import Path
+
+STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+
+
+def get_interrupted_workflows(state):
+    """Find all workflows that are in_progress but not active."""
+    interrupted = []
+
+    # New format (v3.6.7+): check endpoints object
+    if "endpoints" in state:
+        active = state.get("active_endpoint")
+        for endpoint_name, endpoint_data in state["endpoints"].items():
+            status = endpoint_data.get("status", "not_started")
+            if status == "in_progress" and endpoint_name != active:
+                # Find the current phase
+                phases = endpoint_data.get("phases", {})
+                current_phase = None
+                for phase_name, phase_data in phases.items():
+                    if phase_data.get("status") == "in_progress":
+                        current_phase = phase_name
+                        break
+
+                interrupted.append({
+                    "endpoint": endpoint_name,
+                    "status": status,
+                    "current_phase": current_phase,
+                    "started_at": endpoint_data.get("started_at"),
+                    "interrupted_at": endpoint_data.get("session", {}).get("interrupted_at"),
+                    "interrupted_phase": endpoint_data.get("session", {}).get("interrupted_phase")
+                })
+
+        # Also check if active endpoint is not fully started
+        if active and active in state["endpoints"]:
+            active_data = state["endpoints"][active]
+            session = active_data.get("session", {})
+            if session.get("interrupted_at"):
+                # Active endpoint was previously interrupted
+                interrupted.insert(0, {
+                    "endpoint": active,
+                    "status": active_data.get("status"),
+                    "current_phase": session.get("interrupted_phase"),
+                    "started_at": active_data.get("started_at"),
+                    "interrupted_at": session.get("interrupted_at"),
+                    "is_active": True
+                })
+
+    # Old format: single endpoint
+    elif state.get("endpoint"):
+        endpoint = state.get("endpoint")
+        phases = state.get("phases", {})
+
+        # Check if any phase is in_progress
+        for phase_name, phase_data in phases.items():
+            if phase_data.get("status") == "in_progress":
+                interrupted.append({
+                    "endpoint": endpoint,
+                    "status": "in_progress",
+                    "current_phase": phase_name,
+                    "started_at": state.get("created_at"),
+                    "is_legacy": True
+                })
+                break
+
+    return interrupted
+
+
+def format_interrupted_message(interrupted):
+    """Format a user-friendly message about interrupted workflows."""
+    if not interrupted:
+        return None
+
+    lines = [
+        "",
+        "=" * 60,
+        " INTERRUPTED WORKFLOW DETECTED",
+        "=" * 60,
+        ""
+    ]
+
+    for i, workflow in enumerate(interrupted, 1):
+        endpoint = workflow["endpoint"]
+        phase = workflow.get("current_phase", "unknown")
+        started = workflow.get("started_at", "unknown")
+        interrupted_at = workflow.get("interrupted_at", "")
+
+        lines.append(f"{i}. **{endpoint}**")
+        lines.append(f"   - Phase: {phase}")
+        lines.append(f"   - Started: {started}")
+        if interrupted_at:
+            lines.append(f"   - Interrupted: {interrupted_at}")
+        lines.append("")
+
+    lines.extend([
+        "To resume an interrupted workflow, use:",
+        "  /api-continue [endpoint-name]",
+        "",
+        "Or start a new workflow with:",
+        "  /api-create [new-endpoint-name]",
+        "",
+        "=" * 60
+    ])
+
+    return "\n".join(lines)
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        input_data = {}
+
+    # 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)
+
+    # Find interrupted workflows
+    interrupted = get_interrupted_workflows(state)
+
+    if not interrupted:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Format message
+    message = format_interrupted_message(interrupted)
+
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": message,
+            "interruptedWorkflows": interrupted
+        }
+    }
+
+    print(json.dumps(output))
+    sys.exit(0)
+
+
+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()

package/hooks/enforce-brand-guide.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit
+Purpose: Inject brand guide content and validate color compliance 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 and validates that only approved colors are used.
+
+Version: 3.10.0
+
+Returns:
+  - {"continue": true} - Always continues (notifies on violations)
+  - May include "notify" with brand guide summary or color violations
+"""
+import json
+import sys
+import re
+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_colors(content):
+    """Extract all brand colors from brand guide markdown.
+
+    Returns a set of allowed colors (hex values, CSS variables, Tailwind classes).
+    """
+    allowed_colors = set()
+
+    # Extract hex colors from brand guide
+    hex_pattern = r'#[0-9A-Fa-f]{3,8}'
+    for match in re.finditer(hex_pattern, content):
+        allowed_colors.add(match.group(0).upper())
+
+    # Extract CSS variable names
+    css_var_pattern = r'var\(--([a-zA-Z0-9-]+)\)'
+    for match in re.finditer(css_var_pattern, content):
+        allowed_colors.add(f"--{match.group(1)}")
+
+    # Extract Tailwind color classes mentioned in brand guide
+    tailwind_pattern = r'(?:bg|text|border|ring)-([a-zA-Z]+-[0-9]+|[a-zA-Z]+)'
+    for match in re.finditer(tailwind_pattern, content):
+        allowed_colors.add(match.group(0))
+
+    # Always allow these common values
+    allowed_colors.update([
+        'transparent', 'inherit', 'currentColor', 'current',
+        'white', 'black', 'bg-white', 'bg-black', 'text-white', 'text-black',
+        'bg-transparent', 'border-transparent',
+        # Common utility colors
+        'bg-background', 'text-foreground', 'border-border',
+        'bg-primary', 'text-primary', 'border-primary',
+        'bg-secondary', 'text-secondary', 'border-secondary',
+        'bg-accent', 'text-accent', 'border-accent',
+        'bg-muted', 'text-muted', 'border-muted',
+        'bg-destructive', 'text-destructive', 'border-destructive',
+    ])
+
+    return allowed_colors
+
+
+def extract_colors_from_code(code_content):
+    """Extract colors used in component code.
+
+    Returns a list of color usages found.
+    """
+    used_colors = []
+
+    # Find hex colors
+    hex_pattern = r'#[0-9A-Fa-f]{3,8}'
+    for match in re.finditer(hex_pattern, code_content):
+        used_colors.append(('hex', match.group(0).upper()))
+
+    # Find Tailwind color classes (excluding allowed dynamic patterns)
+    tailwind_pattern = r'(?:bg|text|border|ring|from|to|via)-([a-zA-Z]+-[0-9]+)'
+    for match in re.finditer(tailwind_pattern, code_content):
+        # Skip if it's a dynamic value like bg-[#xxx]
+        full_match = match.group(0)
+        if '[' not in full_match:
+            used_colors.append(('tailwind', full_match))
+
+    # Find inline style colors
+    style_pattern = r'(?:color|backgroundColor|borderColor):\s*["\']([^"\']+)["\']'
+    for match in re.finditer(style_pattern, code_content):
+        value = match.group(1)
+        if value.startswith('#'):
+            used_colors.append(('style', value.upper()))
+
+    return used_colors
+
+
+def validate_color_compliance(code_content, allowed_colors):
+    """Check if code uses only brand-approved colors.
+
+    Returns list of violations found.
+    """
+    violations = []
+    used_colors = extract_colors_from_code(code_content)
+
+    for color_type, color_value in used_colors:
+        # Check if color is allowed
+        is_allowed = False
+
+        if color_type == 'hex':
+            is_allowed = color_value in allowed_colors
+        elif color_type == 'tailwind':
+            is_allowed = color_value in allowed_colors or color_value.split('-')[0] in ['bg', 'text', 'border']
+        elif color_type == 'style':
+            is_allowed = color_value in allowed_colors
+
+        if not is_allowed:
+            # Check against all allowed colors more loosely
+            if color_value not in allowed_colors:
+                violations.append(f"{color_type}: {color_value}")
+
+    return violations
+
+
+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)
+
+    # For Edit operations, check color compliance
+    tool_input = input_data.get("tool_input", {})
+    if tool_name == "Edit":
+        new_content = tool_input.get("new_string", "")
+        if new_content:
+            allowed_colors = extract_brand_colors(brand_content)
+            violations = validate_color_compliance(new_content, allowed_colors)
+
+            if violations:
+                notify_msg = f"⚠️ Brand color check: {len(violations)} potential non-brand colors: " + ", ".join(violations[:3])
+                print(json.dumps({"continue": True, "notify": notify_msg}))
+                sys.exit(0)
+
+    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()