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

package/.claude/hooks/test-orchestrator-reground.py

@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""
+Test Orchestrator Re-grounding Hook
+
+Runs every 5 turns during test orchestration to:
+1. Re-inject testing goals and current progress
+2. Send NTFY notification with status update
+3. Prevent context dilution during long test sessions
+
+Hook Type: PostToolUse
+Trigger: Every 5 turns
+NTFY Topic: test_api_devtools_alerts
+
+Version: 1.0.0
+"""
+
+import json
+import os
+import sys
+import subprocess
+from datetime import datetime
+from pathlib import Path
+
+# Configuration
+REGROUND_INTERVAL = 5  # Re-ground every 5 turns
+NTFY_TOPIC = "test_api_devtools_alerts"
+STATE_FILE = Path(__file__).parent.parent / "test-orchestrator-state.json"
+
+
+def send_ntfy(message, title="Test Orchestrator", priority=3, tags=None):
+    """Send NTFY notification."""
+    try:
+        headers = [
+            f"Title: {title}",
+            f"Priority: {priority}",
+        ]
+        if tags:
+            headers.append(f"Tags: {','.join(tags)}")
+
+        header_args = []
+        for h in headers:
+            header_args.extend(["-H", h])
+
+        subprocess.run(
+            ["curl", "-s"] + header_args + ["-d", message, f"https://ntfy.sh/{NTFY_TOPIC}"],
+            capture_output=True,
+            timeout=10
+        )
+    except Exception as e:
+        # Don't fail if notification fails
+        print(f"NTFY failed: {e}", file=sys.stderr)
+
+
+def load_test_state():
+    """Load test orchestrator state."""
+    if not STATE_FILE.exists():
+        return {
+            "turn_count": 0,
+            "started_at": datetime.now().isoformat(),
+            "commands_tested": {},
+            "current_command": None,
+            "current_phase": None,
+            "total_retries": 0,
+            "reground_history": []
+        }
+
+    try:
+        return json.loads(STATE_FILE.read_text())
+    except Exception:
+        return {
+            "turn_count": 0,
+            "started_at": datetime.now().isoformat(),
+            "commands_tested": {},
+            "current_command": None,
+            "current_phase": None,
+            "total_retries": 0,
+            "reground_history": []
+        }
+
+
+def save_test_state(state):
+    """Save test orchestrator state."""
+    STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    STATE_FILE.write_text(json.dumps(state, indent=2))
+
+
+def format_progress_summary(state):
+    """Format a progress summary for re-grounding."""
+    commands = state.get("commands_tested", {})
+
+    summary_lines = []
+    summary_lines.append("## Test Orchestrator Progress")
+    summary_lines.append("")
+
+    # Overall stats
+    turn = state.get("turn_count", 0)
+    started = state.get("started_at", "unknown")
+    summary_lines.append(f"**Turn:** {turn}")
+    summary_lines.append(f"**Started:** {started}")
+    summary_lines.append(f"**Total Retries:** {state.get('total_retries', 0)}")
+    summary_lines.append("")
+
+    # Command progress
+    summary_lines.append("**Command Progress:**")
+    all_commands = [
+        "/api-create",
+        "/hustle-ui-create",
+        "/hustle-ui-create-page",
+        "/hustle-combine",
+        "/hustle-build"
+    ]
+
+    for cmd in all_commands:
+        cmd_state = commands.get(cmd, {})
+        status = cmd_state.get("status", "NOT STARTED")
+
+        icon = {
+            "PASSED": "✅",
+            "FAILED": "❌",
+            "IN PROGRESS": "🔄",
+            "NOT STARTED": "⏳"
+        }.get(status, "❓")
+
+        phases = cmd_state.get("phases_complete", 0)
+        retries = cmd_state.get("retries", 0)
+
+        if status == "PASSED":
+            summary_lines.append(f"- {icon} {cmd}: PASSED ({phases}/14 phases)")
+        elif status == "FAILED":
+            summary_lines.append(f"- {icon} {cmd}: FAILED at phase {phases}/14 (retry {retries}/∞)")
+        elif status == "IN PROGRESS":
+            summary_lines.append(f"- {icon} {cmd}: IN PROGRESS (phase {phases}/14)")
+        else:
+            summary_lines.append(f"- {icon} {cmd}: NOT STARTED")
+
+    summary_lines.append("")
+
+    # Current task
+    current_cmd = state.get("current_command")
+    current_phase = state.get("current_phase")
+    if current_cmd:
+        summary_lines.append(f"**Current Task:** {current_cmd} - Phase {current_phase}")
+    else:
+        summary_lines.append("**Current Task:** Initializing test harness")
+
+    summary_lines.append("")
+    summary_lines.append("## Primary Goal")
+    summary_lines.append("")
+    summary_lines.append("Test ALL 5 commands until they work perfectly:")
+    summary_lines.append("1. Run each command in isolated test directory")
+    summary_lines.append("2. Auto-answer questions via pending-answer.json")
+    summary_lines.append("3. Verify ALL 14 phases complete")
+    summary_lines.append("4. Verify ALL hooks fire correctly")
+    summary_lines.append("5. If tests fail: research, fix code, rebuild, retry")
+    summary_lines.append("6. NEVER STOP until all 5 commands pass")
+    summary_lines.append("")
+    summary_lines.append("## Key Resources")
+    summary_lines.append("")
+    summary_lines.append("- Test directory: ~/test-api-dev-tools-auto/")
+    summary_lines.append("- .env file: Copy from /Users/alfonso/Documents/GitHub/api-dev-tools/.env.example")
+    summary_lines.append("- WORKFLOW_CHECKLIST.md: Track results")
+    summary_lines.append("- NTFY topic: test_api_devtools_alerts")
+    summary_lines.append("")
+    summary_lines.append("## Failure Strategy")
+    summary_lines.append("")
+    summary_lines.append("If stuck after 5 retries:")
+    summary_lines.append("1. Use WebSearch to research the error")
+    summary_lines.append("2. Find similar issues and solutions")
+    summary_lines.append("3. Try new approaches")
+    summary_lines.append("4. Use git commits as savepoints")
+    summary_lines.append("5. NEVER give up - keep iterating")
+
+    return "\n".join(summary_lines)
+
+
+def main():
+    # Load state
+    state = load_test_state()
+
+    # Increment turn count
+    turn_count = state.get("turn_count", 0) + 1
+    state["turn_count"] = turn_count
+    state["last_turn_timestamp"] = datetime.now().isoformat()
+
+    # Check if we should re-ground
+    should_reground = turn_count % REGROUND_INTERVAL == 0
+
+    if should_reground:
+        # Generate progress summary
+        summary = format_progress_summary(state)
+
+        # Send NTFY notification
+        commands = state.get("commands_tested", {})
+        passed = sum(1 for c in commands.values() if c.get("status") == "PASSED")
+        in_progress = sum(1 for c in commands.values() if c.get("status") == "IN PROGRESS")
+        failed = sum(1 for c in commands.values() if c.get("status") == "FAILED")
+
+        ntfy_msg = f"""Turn {turn_count} Update:
+✅ Passed: {passed}/5
+🔄 In Progress: {in_progress}/5
+❌ Failed: {failed}/5
+
+Current: {state.get('current_command', 'Initializing')}
+Retries: {state.get('total_retries', 0)}
+"""
+
+        send_ntfy(
+            ntfy_msg,
+            title=f"🔄 Turn {turn_count} - Test Orchestrator",
+            priority=3,
+            tags=["robot", "test"]
+        )
+
+        # Add to reground history
+        reground_history = state.setdefault("reground_history", [])
+        reground_history.append({
+            "turn": turn_count,
+            "timestamp": datetime.now().isoformat(),
+            "current_command": state.get("current_command"),
+            "current_phase": state.get("current_phase"),
+            "passed": passed,
+            "failed": failed
+        })
+        # Keep only last 20 reground events
+        state["reground_history"] = reground_history[-20:]
+
+        # Save state
+        save_test_state(state)
+
+        # Output with context injection
+        output = {
+            "continue": True,
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": summary
+            }
+        }
+        print(json.dumps(output))
+    else:
+        # Just update turn count
+        save_test_state(state)
+        print(json.dumps({"continue": True}))
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.claude/hooks/track-scope-coverage.py

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+"""
+Hook: PostToolUse for AskUserQuestion
+Purpose: Track implemented vs deferred features for scope coverage
+
+This hook tracks which features discovered during research are:
+  - Implemented (user chose to include)
+  - Deferred (user chose to skip for later)
+  - Discovered (found in docs but not yet decided)
+
+Added in v3.6.7 for feature scope tracking.
+
+Returns:
+  - JSON with scope coverage update info
+"""
+import json
+import sys
+from datetime import datetime
+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_feature_from_question(question, options):
+    """Try to extract a feature name from the question."""
+    # Look for common patterns
+    patterns = [
+        "implement",
+        "include",
+        "support",
+        "enable",
+        "add"
+    ]
+
+    question_lower = question.lower()
+    for pattern in patterns:
+        if pattern in question_lower:
+            # Extract the words after the pattern
+            idx = question_lower.find(pattern)
+            after = question_lower[idx:].split("?")[0]
+            # Clean up
+            words = after.split()[1:4]  # Get 1-3 words after pattern
+            if words:
+                return " ".join(words).strip(",.?")
+
+    return None
+
+
+def is_feature_decision(question, answer, options):
+    """Determine if this was a feature implementation decision."""
+    question_lower = question.lower()
+
+    # Keywords suggesting feature decision
+    feature_keywords = [
+        "implement", "include", "support", "enable", "add",
+        "feature", "functionality", "capability"
+    ]
+
+    has_keyword = any(k in question_lower for k in feature_keywords)
+
+    # Check if answer indicates yes/no/defer decision
+    answer_lower = str(answer).lower() if answer else ""
+    is_decision = any(word in answer_lower for word in [
+        "yes", "no", "skip", "defer", "later", "include", "exclude",
+        "implement", "confirm", "reject"
+    ])
+
+    return has_keyword and is_decision
+
+
+def categorize_decision(answer):
+    """Categorize the decision as implement/defer/skip."""
+    answer_lower = str(answer).lower() if answer else ""
+
+    if any(word in answer_lower for word in ["yes", "include", "implement", "confirm"]):
+        return "implement"
+    elif any(word in answer_lower for word in ["defer", "later", "phase 2", "future"]):
+        return "defer"
+    elif any(word in answer_lower for word in ["no", "skip", "exclude", "reject"]):
+        return "skip"
+
+    return "unknown"
+
+
+def main():
+    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", {})
+    tool_result = input_data.get("tool_result", {})
+
+    if tool_name != "AskUserQuestion":
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    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)
+
+    endpoint, endpoint_data = get_active_endpoint(state)
+    if not endpoint or not endpoint_data:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Get question and answer
+    question = tool_input.get("question", "")
+    options = tool_input.get("options", [])
+
+    # Get user's answer from result
+    answer = None
+    if isinstance(tool_result, dict):
+        answer = tool_result.get("answer", tool_result.get("value", ""))
+    elif isinstance(tool_result, str):
+        answer = tool_result
+
+    # Check if this is a feature decision
+    if not is_feature_decision(question, answer, options):
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Extract feature name
+    feature = extract_feature_from_question(question, options)
+    if not feature:
+        feature = f"feature_{datetime.now().strftime('%H%M%S')}"
+
+    # Categorize decision
+    category = categorize_decision(answer)
+
+    # Ensure scope object exists
+    if "endpoints" in state:
+        if "scope" not in state["endpoints"][endpoint]:
+            state["endpoints"][endpoint]["scope"] = {
+                "discovered_features": [],
+                "implemented_features": [],
+                "deferred_features": [],
+                "coverage_percent": 0
+            }
+        scope = state["endpoints"][endpoint]["scope"]
+    else:
+        if "scope" not in state:
+            state["scope"] = {
+                "discovered_features": [],
+                "implemented_features": [],
+                "deferred_features": [],
+                "coverage_percent": 0
+            }
+        scope = state["scope"]
+
+    # Add to discovered if not already there
+    feature_entry = {
+        "name": feature,
+        "discovered_at": datetime.now().isoformat(),
+        "question": question[:100],
+        "decision": category
+    }
+
+    if feature not in [f.get("name") if isinstance(f, dict) else f for f in scope["discovered_features"]]:
+        scope["discovered_features"].append(feature_entry)
+
+    # Add to appropriate category
+    if category == "implement":
+        if feature not in scope["implemented_features"]:
+            scope["implemented_features"].append(feature)
+    elif category == "defer":
+        defer_entry = {
+            "name": feature,
+            "reason": f"User chose to defer: {str(answer)[:50]}",
+            "deferred_at": datetime.now().isoformat()
+        }
+        if feature not in [f.get("name") if isinstance(f, dict) else f for f in scope["deferred_features"]]:
+            scope["deferred_features"].append(defer_entry)
+
+    # Calculate coverage
+    total = len(scope["discovered_features"])
+    implemented = len(scope["implemented_features"])
+    if total > 0:
+        scope["coverage_percent"] = round((implemented / total) * 100, 1)
+
+    # Save state
+    STATE_FILE.write_text(json.dumps(state, indent=2))
+
+    output = {
+        "hookSpecificOutput": {
+            "featureTracked": feature,
+            "decision": category,
+            "coveragePercent": scope["coverage_percent"]
+        }
+    }
+
+    print(json.dumps(output))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.claude/hooks/track-token-usage.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""
+Hook: PostToolUse
+Purpose: Track token usage per phase and display after phase completion
+
+Logs token usage to state file and outputs summary after each phase.
+Integrates with ccusage if available.
+
+Version: 3.10.0
+"""
+import json
+import sys
+import subprocess
+from pathlib import Path
+from datetime import datetime
+
+
+def get_token_usage() -> dict:
+    """Get current token usage from ccusage."""
+    try:
+        result = subprocess.run(
+            ["ccusage", "--json"],
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+        if result.returncode == 0:
+            return json.loads(result.stdout)
+    except (subprocess.TimeoutExpired, FileNotFoundError, json.JSONDecodeError):
+        pass
+    return {}
+
+
+def main():
+    # Read hook input from stdin
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+
+    # Only trigger on Write/Edit to state file
+    if tool_name not in ["Write", "Edit"]:
+        sys.exit(0)
+
+    file_path = tool_input.get("file_path", "")
+    if "api-dev-state.json" not in file_path:
+        sys.exit(0)
+
+    # Get current token usage
+    usage = get_token_usage()
+    if not usage:
+        sys.exit(0)
+
+    # Read state file
+    cwd = Path.cwd()
+    state_file = cwd / ".claude" / "api-dev-state.json"
+
+    if not state_file.exists():
+        sys.exit(0)
+
+    try:
+        state = json.loads(state_file.read_text())
+    except (json.JSONDecodeError, IOError):
+        sys.exit(0)
+
+    # Check for phase completion and log usage
+    phases = state.get("phases", {})
+    current_phase = None
+
+    for phase_key, phase_data in phases.items():
+        if isinstance(phase_data, dict):
+            status = phase_data.get("status", "")
+            if status == "complete":
+                current_phase = phase_key
+
+    if current_phase:
+        # Initialize token tracking in state if needed
+        if "token_usage" not in state:
+            state["token_usage"] = {
+                "by_phase": {},
+                "total_at_start": usage.get("total_tokens", 0),
+                "started_at": datetime.now().isoformat()
+            }
+
+        # Record phase completion tokens
+        state["token_usage"]["by_phase"][current_phase] = {
+            "total_tokens": usage.get("total_tokens", 0),
+            "total_cost": usage.get("total_cost", 0),
+            "timestamp": datetime.now().isoformat()
+        }
+
+        # Calculate phase delta if we have previous data
+        by_phase = state["token_usage"]["by_phase"]
+        phase_keys = list(by_phase.keys())
+
+        if len(phase_keys) >= 2:
+            prev_phase = phase_keys[-2]
+            prev_tokens = by_phase[prev_phase].get("total_tokens", 0)
+            current_tokens = usage.get("total_tokens", 0)
+            delta = current_tokens - prev_tokens
+
+            # Output phase token summary
+            print(f"\n📊 Phase '{current_phase}' Token Usage:", file=sys.stderr)
+            print(f"   Phase tokens: {delta:,}", file=sys.stderr)
+            print(f"   Total tokens: {current_tokens:,}", file=sys.stderr)
+            print(f"   Total cost: ${usage.get('total_cost', 0):.2f}", file=sys.stderr)
+
+        # Update state file with token tracking
+        try:
+            state_file.write_text(json.dumps(state, indent=2))
+        except IOError:
+            pass
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()