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

package/.claude/hooks/run-visual-qa.py

@@ -0,0 +1,338 @@
+#!/usr/bin/env python3
+"""
+Visual QA Hook (Ralph Wiggum Loop Pattern)
+
+Runs visual analysis with AI (Haiku) and LOOPS until all issues are fixed.
+This ensures visual quality before proceeding to next phase.
+
+Hook Type: PostToolUse (triggers after Storybook/visual tests)
+
+Ralph Wiggum Pattern:
+    1. Run visual tests / capture screenshots
+    2. Analyze with AI (Haiku subagent)
+    3. If issues found → inject context for agent to fix
+    4. Agent fixes CSS/layout
+    5. Re-run visual tests → hook triggers again
+    6. Re-analyze with Haiku
+    7. Loop until clean OR max iterations
+    8. Emit <promise>VISUAL_CLEAN</promise>
+
+Environment Variables:
+    VISUAL_QA_ENABLED: Set to 'true' to enable (default: true)
+    VISUAL_QA_MAX_ITERATIONS: Max QA cycles (default: 5)
+
+Version: 1.0.0
+"""
+import os
+import sys
+import json
+from pathlib import Path
+from datetime import datetime
+
+# State file for tracking visual QA loops
+VISUAL_STATE_FILE = ".claude/visual-qa-state.json"
+MAX_ITERATIONS = int(os.environ.get("VISUAL_QA_MAX_ITERATIONS", "5"))
+
+
+def load_visual_state() -> dict:
+    """Load visual QA loop state."""
+    state_file = Path.cwd() / VISUAL_STATE_FILE
+    if state_file.exists():
+        try:
+            return json.loads(state_file.read_text())
+        except (json.JSONDecodeError, IOError):
+            pass
+    return {
+        "iteration": 0,
+        "issues_found": [],
+        "components_checked": [],
+        "viewports_passed": [],
+        "status": "pending",
+        "started_at": None,
+        "last_check_at": None
+    }
+
+
+def save_visual_state(state: dict):
+    """Save visual QA loop state."""
+    state_file = Path.cwd() / VISUAL_STATE_FILE
+    state_file.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        state_file.write_text(json.dumps(state, indent=2))
+    except IOError:
+        pass
+
+
+def clear_visual_state():
+    """Clear visual state after successful completion."""
+    state_file = Path.cwd() / VISUAL_STATE_FILE
+    if state_file.exists():
+        try:
+            state_file.unlink()
+        except IOError:
+            pass
+
+
+def load_workflow_state() -> dict:
+    """Load current workflow state."""
+    state_file = Path.cwd() / ".claude" / "api-dev-state.json"
+    if state_file.exists():
+        try:
+            return json.loads(state_file.read_text())
+        except (json.JSONDecodeError, IOError):
+            pass
+
+    # Also check hustle-build state
+    hustle_state = Path.cwd() / ".claude" / "hustle-build-state.json"
+    if hustle_state.exists():
+        try:
+            return json.loads(hustle_state.read_text())
+        except (json.JSONDecodeError, IOError):
+            pass
+
+    return {}
+
+
+def update_workflow_state(issues_count: int, iteration: int):
+    """Update workflow state with visual QA results."""
+    state_file = Path.cwd() / ".claude" / "api-dev-state.json"
+    state = load_workflow_state()
+
+    if "phases" not in state:
+        state["phases"] = {}
+
+    state["phases"]["visual_qa"] = {
+        "status": "in_progress" if issues_count > 0 else "complete",
+        "iteration": iteration,
+        "issues_found": issues_count,
+        "checked_at": datetime.now().isoformat()
+    }
+
+    try:
+        state_file.write_text(json.dumps(state, indent=2))
+    except IOError:
+        pass
+
+
+def should_run_visual_qa(hook_input: dict) -> bool:
+    """Determine if visual QA should run based on hook context."""
+    # Check if visual QA is enabled
+    if os.environ.get("VISUAL_QA_ENABLED", "true").lower() == "false":
+        return False
+
+    tool_name = hook_input.get("tool_name", "")
+    tool_input = hook_input.get("tool_input", {})
+
+    # Run after Storybook tests
+    if tool_name == "Bash":
+        command = tool_input.get("command", "")
+        tool_result = hook_input.get("tool_result", {})
+        stdout = tool_result.get("stdout", "")
+
+        # Check if visual/storybook tests ran
+        visual_triggers = [
+            "storybook",
+            "test-storybook",
+            "chromatic",
+            "playwright test --project=visual",
+            "visual",
+            "screenshot"
+        ]
+
+        if any(trigger in command.lower() for trigger in visual_triggers):
+            return True
+
+    # Run after Task with visual-analyzer
+    if tool_name == "Task":
+        subagent_type = tool_input.get("subagent_type", "")
+        if subagent_type == "visual-analyzer":
+            return True
+
+    return False
+
+
+def parse_visual_issues(hook_input: dict) -> list:
+    """Parse visual issues from tool output."""
+    issues = []
+
+    tool_result = hook_input.get("tool_result", {})
+    stdout = tool_result.get("stdout", "")
+    message = tool_result.get("message", "")
+
+    output = stdout + "\n" + message
+
+    # Look for common issue patterns
+    issue_keywords = [
+        "touch target",
+        "contrast",
+        "overflow",
+        "clipping",
+        "alignment",
+        "spacing",
+        "typography",
+        "safe area",
+        "layout issue",
+        "responsive",
+        "accessibility",
+        "wcag"
+    ]
+
+    lines = output.split("\n")
+    for line in lines:
+        line_lower = line.lower()
+        if any(keyword in line_lower for keyword in issue_keywords):
+            if "issue" in line_lower or "warning" in line_lower or "error" in line_lower or "fail" in line_lower:
+                issues.append(line.strip())
+
+    # Also look for severity markers
+    for line in lines:
+        if "⚠️" in line or "❌" in line or "warning" in line.lower():
+            if line.strip() and line.strip() not in issues:
+                issues.append(line.strip())
+
+    return issues[:10]  # Limit to 10 issues
+
+
+def format_issues_for_context(issues: list, iteration: int) -> str:
+    """Format issues as context for the agent to fix."""
+    if not issues:
+        return ""
+
+    lines = [
+        "",
+        "=" * 60,
+        "VISUAL QA ISSUES TO FIX (Ralph Wiggum Loop)",
+        "=" * 60,
+        "",
+        f"Iteration {iteration}/{MAX_ITERATIONS}",
+        "",
+        "The following visual issues were found by AI analysis.",
+        "Please fix ALL issues, then re-run visual tests.",
+        "The QA will re-run automatically.",
+        "",
+        "ISSUES:",
+    ]
+
+    for i, issue in enumerate(issues, 1):
+        lines.append(f"  {i}. {issue}")
+
+    lines.extend([
+        "",
+        "Common fixes:",
+        "  - Touch targets: Add min-h-[44px] min-w-[44px]",
+        "  - Contrast: Check text color against background",
+        "  - Safe areas: Use safe-area-inset-* CSS",
+        "  - Overflow: Add overflow-hidden or adjust sizing",
+        "",
+        "After fixing, run: /test-visual",
+        "=" * 60,
+        ""
+    ])
+
+    return "\n".join(lines)
+
+
+def main():
+    """Main hook entry point with Ralph Wiggum loop pattern."""
+    # Read hook input
+    try:
+        hook_input = json.loads(sys.stdin.read())
+    except json.JSONDecodeError:
+        hook_input = {}
+
+    # Check if we should run
+    if not should_run_visual_qa(hook_input):
+        print(json.dumps({"continue": True}))
+        return
+
+    # Load current visual QA state
+    visual_state = load_visual_state()
+
+    # Increment iteration
+    visual_state["iteration"] += 1
+    iteration = visual_state["iteration"]
+
+    # Check max iterations
+    if iteration > MAX_ITERATIONS:
+        output = f"""
+================================================================================
+VISUAL QA - MAX ITERATIONS REACHED ({MAX_ITERATIONS})
+================================================================================
+Proceeding with remaining warnings. Consider reviewing manually.
+
+<promise>VISUAL_CLEAN</promise>
+"""
+        print(json.dumps({
+            "continue": True,
+            "message": output
+        }))
+        clear_visual_state()
+        return
+
+    # Track timing
+    if iteration == 1:
+        visual_state["started_at"] = datetime.now().isoformat()
+    visual_state["last_check_at"] = datetime.now().isoformat()
+
+    # Parse issues from the visual test output
+    issues = parse_visual_issues(hook_input)
+    issue_count = len(issues)
+
+    update_workflow_state(issue_count, iteration)
+
+    if issue_count == 0:
+        # All clean! Emit promise and proceed
+        visual_state["status"] = "complete"
+        save_visual_state(visual_state)
+
+        output = f"""
+================================================================================
+VISUAL QA LOOP COMPLETE (Iteration {iteration}/{MAX_ITERATIONS})
+================================================================================
+All visual checks passed!
+- Layout: ✅
+- Typography: ✅
+- Touch Targets: ✅
+- Safe Areas: ✅
+- Brand Consistency: ✅
+
+Proceeding to next phase.
+
+<promise>VISUAL_CLEAN</promise>
+"""
+        print(json.dumps({
+            "continue": True,
+            "message": output
+        }))
+        clear_visual_state()
+        return
+
+    # Issues found - save state and provide context for fixes
+    visual_state["status"] = "needs_fixing"
+    visual_state["issues_found"] = issues
+    save_visual_state(visual_state)
+
+    # Format issues as context
+    issues_context = format_issues_for_context(issues, iteration)
+
+    output = f"""
+================================================================================
+VISUAL QA LOOP - ITERATION {iteration}/{MAX_ITERATIONS}
+================================================================================
+{issue_count} visual issue(s) found. Fix them and re-run visual tests.
+{issues_context}
+"""
+
+    # Block workflow - agent needs to fix issues
+    print(json.dumps({
+        "continue": False,  # Block until fixed
+        "message": output,
+        "issues_count": issue_count,
+        "iteration": iteration,
+        "action_required": True,
+        "next_action": "Fix the visual issues above, then run /test-visual"
+    }))
+
+
+if __name__ == "__main__":
+    main()

package/.claude/hooks/session-logger.py

@@ -0,0 +1,323 @@
+#!/usr/bin/env python3
+"""
+Hook: Stop
+Purpose: Save session to .claude/api-sessions/ for later review
+
+This hook runs when a Claude Code session ends (Stop event).
+It saves the session data for the completed workflow including:
+  - State snapshot at completion
+  - Files created during the workflow
+  - Summary of phases completed
+  - Research sources used
+  - Interview decisions made
+
+Added in v3.6.7 for session logging support.
+
+Returns:
+  - JSON with session save info
+"""
+import json
+import sys
+import os
+from datetime import datetime
+from pathlib import Path
+import shutil
+
+# Import shared utilities for NTFY
+try:
+    from hook_utils import send_ntfy_notification
+    HAS_NTFY = True
+except ImportError:
+    HAS_NTFY = False
+
+STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+SESSIONS_DIR = Path(__file__).parent.parent / "api-sessions"
+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 get_completed_phases(endpoint_data):
+    """Get list of completed phases."""
+    completed = []
+    phases = endpoint_data.get("phases", {})
+
+    phase_order = [
+        "disambiguation", "scope", "research_initial", "interview",
+        "research_deep", "schema_creation", "environment_check",
+        "tdd_red", "tdd_green", "verify", "tdd_refactor", "documentation", "completion"
+    ]
+
+    for phase_name in phase_order:
+        phase = phases.get(phase_name, {})
+        if phase.get("status") == "complete":
+            completed.append(phase_name)
+
+    return completed
+
+
+def get_files_created(endpoint_data):
+    """Get list of files created during this workflow."""
+    files = []
+
+    # From completion phase
+    completion = endpoint_data.get("phases", {}).get("completion", {})
+    files.extend(completion.get("files_created", []))
+
+    # From schema phase
+    schema = endpoint_data.get("phases", {}).get("schema_creation", {})
+    if schema.get("schema_file"):
+        files.append(schema.get("schema_file"))
+
+    # From TDD phases
+    tdd_red = endpoint_data.get("phases", {}).get("tdd_red", {})
+    if tdd_red.get("test_file"):
+        files.append(tdd_red.get("test_file"))
+
+    tdd_green = endpoint_data.get("phases", {}).get("tdd_green", {})
+    if tdd_green.get("implementation_file"):
+        files.append(tdd_green.get("implementation_file"))
+
+    return list(set(files))  # Deduplicate
+
+
+def generate_summary(endpoint, endpoint_data, state):
+    """Generate a markdown summary of the session."""
+    completed = get_completed_phases(endpoint_data)
+    files = get_files_created(endpoint_data)
+    decisions = endpoint_data.get("phases", {}).get("interview", {}).get("decisions", {})
+
+    lines = [
+        f"# Session Summary: {endpoint}",
+        "",
+        f"*Generated: {datetime.now().isoformat()}*",
+        "",
+        "## Overview",
+        "",
+        f"- **Endpoint:** {endpoint}",
+        f"- **Library:** {endpoint_data.get('library', 'N/A')}",
+        f"- **Started:** {endpoint_data.get('started_at', 'N/A')}",
+        f"- **Completed Phases:** {len(completed)}/13",
+        f"- **Status:** {endpoint_data.get('status', 'unknown')}",
+        "",
+        "## Phases Completed",
+        ""
+    ]
+
+    for i, phase in enumerate(completed, 1):
+        lines.append(f"{i}. {phase.replace('_', ' ').title()}")
+
+    lines.extend([
+        "",
+        "## Files Created",
+        ""
+    ])
+
+    for f in files:
+        lines.append(f"- `{f}`")
+
+    if decisions:
+        lines.extend([
+            "",
+            "## Interview Decisions",
+            ""
+        ])
+        for key, value in decisions.items():
+            response = value.get("response", value.get("value", "N/A"))
+            lines.append(f"- **{key}:** {response}")
+
+    lines.extend([
+        "",
+        "## Research Sources",
+        ""
+    ])
+
+    # Check for research cache
+    research_path = RESEARCH_DIR / endpoint / "sources.json"
+    if research_path.exists():
+        try:
+            sources = json.loads(research_path.read_text())
+            for src in sources.get("sources", [])[:10]:  # Limit to 10
+                url = src.get("url", src.get("query", ""))
+                if url:
+                    lines.append(f"- {url}")
+        except (json.JSONDecodeError, IOError):
+            lines.append("- (sources.json not readable)")
+    else:
+        lines.append("- (no sources.json found)")
+
+    lines.extend([
+        "",
+        "---",
+        "",
+        f"*Session saved to: .claude/api-sessions/{endpoint}_{{timestamp}}/*"
+    ])
+
+    return "\n".join(lines)
+
+
+def save_session(endpoint, endpoint_data, state):
+    """Save session to .claude/api-sessions/."""
+    # Create timestamp
+    timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
+    session_dir = SESSIONS_DIR / f"{endpoint}_{timestamp}"
+    session_dir.mkdir(parents=True, exist_ok=True)
+
+    # 1. Save state snapshot
+    state_snapshot = {
+        "saved_at": datetime.now().isoformat(),
+        "endpoint": endpoint,
+        "endpoint_data": endpoint_data,
+        "turn_count": state.get("turn_count", 0),
+        "research_queries": state.get("research_queries", [])
+    }
+    (session_dir / "state-snapshot.json").write_text(json.dumps(state_snapshot, indent=2))
+
+    # 2. Save files list
+    files = get_files_created(endpoint_data)
+    (session_dir / "files-created.txt").write_text("\n".join(files))
+
+    # 3. Generate and save summary
+    summary = generate_summary(endpoint, endpoint_data, state)
+    (session_dir / "summary.md").write_text(summary)
+
+    # 4. Copy research cache if exists
+    research_src = RESEARCH_DIR / endpoint
+    if research_src.exists():
+        research_dst = session_dir / "research-cache"
+        research_dst.mkdir(exist_ok=True)
+        for f in research_src.iterdir():
+            if f.is_file():
+                shutil.copy2(f, research_dst / f.name)
+
+    # 5. Update sessions index
+    update_sessions_index(endpoint, timestamp, endpoint_data)
+
+    return session_dir
+
+
+def update_sessions_index(endpoint, timestamp, endpoint_data):
+    """Update the sessions index file."""
+    index_file = SESSIONS_DIR / "index.json"
+
+    if index_file.exists():
+        try:
+            index = json.loads(index_file.read_text())
+        except json.JSONDecodeError:
+            index = {"version": "3.6.7", "sessions": []}
+    else:
+        index = {"version": "3.6.7", "sessions": []}
+
+    # Add this session
+    completed = get_completed_phases(endpoint_data)
+    index["sessions"].append({
+        "endpoint": endpoint,
+        "timestamp": timestamp,
+        "folder": f"{endpoint}_{timestamp}",
+        "status": endpoint_data.get("status", "unknown"),
+        "phases_completed": len(completed),
+        "created_at": datetime.now().isoformat()
+    })
+
+    index_file.write_text(json.dumps(index, indent=2))
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        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:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Only save if there's meaningful progress
+    completed = get_completed_phases(endpoint_data)
+    if len(completed) < 2:
+        # Not enough progress to save
+        print(json.dumps({
+            "hookSpecificOutput": {
+                "sessionSaved": False,
+                "reason": "Not enough progress to save (need at least 2 completed phases)"
+            }
+        }))
+        sys.exit(0)
+
+    # Save the session
+    try:
+        session_dir = save_session(endpoint, endpoint_data, state)
+
+        # Send NTFY notification on session end
+        if HAS_NTFY:
+            status = endpoint_data.get("status", "unknown")
+            if status == "complete":
+                send_ntfy_notification(
+                    title=f"✅ Session Complete: {endpoint}",
+                    message=f"Completed {len(completed)}/13 phases. Session saved.",
+                    priority="default",
+                    tags=["white_check_mark", "robot"]
+                )
+            else:
+                send_ntfy_notification(
+                    title=f"📋 Session Ended: {endpoint}",
+                    message=f"Completed {len(completed)}/13 phases. Status: {status}",
+                    priority="low",
+                    tags=["clipboard", "robot"]
+                )
+
+        output = {
+            "hookSpecificOutput": {
+                "sessionSaved": True,
+                "endpoint": endpoint,
+                "sessionDir": str(session_dir),
+                "phasesCompleted": len(completed),
+                "notificationSent": HAS_NTFY
+            }
+        }
+
+        print(json.dumps(output))
+        sys.exit(0)
+
+    except Exception as e:
+        output = {
+            "hookSpecificOutput": {
+                "sessionSaved": False,
+                "error": str(e)
+            }
+        }
+        print(json.dumps(output))
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()