anvil-dev-framework 0.1.6

package/global/hooks/parse_transcript.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""
+parse_transcript.py - Lightweight bash wrapper for transcript parsing
+
+Returns JSON output suitable for consumption by bash scripts (statusline.sh).
+Designed for minimal latency with caching.
+
+Usage:
+    # Get current todo for statusline
+    python3 parse_transcript.py todo /path/to/transcript.jsonl
+
+    # Get tool activity for HUD
+    python3 parse_transcript.py tools /path/to/transcript.jsonl
+
+    # Get both as combined JSON
+    python3 parse_transcript.py all /path/to/transcript.jsonl
+
+Output (todo):
+    {"content": "Writing auth tests", "completed": 3, "total": 7}
+    or empty {} if no todos
+
+Output (tools):
+    {"running": [{"name": "Edit", "target": "..."}], "completed": {"Edit": 4, "Read": 2}}
+"""
+
+import json
+import os
+import sys
+
+# Add lib directory to path
+lib_dir = os.path.join(os.path.dirname(os.path.dirname(__file__)), "lib")
+sys.path.insert(0, lib_dir)
+
+from transcript_parser import TranscriptParser  # noqa: E402
+
+
+def format_todo_output(parser: TranscriptParser, transcript_path: str) -> dict:
+    """Format todo state for statusline consumption."""
+    todos = parser.get_todos(transcript_path)
+
+    if not todos.in_progress and todos.total == 0:
+        return {}
+
+    result = {
+        "total": todos.total,
+        "completed": todos.completed,
+        "pending": todos.pending,
+    }
+
+    if todos.in_progress:
+        result["content"] = todos.in_progress.content
+        result["activeForm"] = todos.in_progress.active_form or todos.in_progress.content
+
+    return result
+
+
+def format_tools_output(parser: TranscriptParser, transcript_path: str) -> dict:
+    """Format tool activity for HUD consumption."""
+    activity = parser.parse(transcript_path)
+
+    result = {
+        "running": [],
+        "completed": {},
+        "errors": activity.error_count,
+    }
+
+    for tool in activity.running:
+        result["running"].append({
+            "name": tool.name,
+            "target": tool.target,
+            "started_at": tool.started_at,
+        })
+
+    result["completed"] = dict(activity.get_top_completed(limit=6))
+
+    return result
+
+
+def main():
+    if len(sys.argv) < 3:
+        print(json.dumps({"error": "Usage: parse_transcript.py <todo|tools|all> <path>"}))
+        sys.exit(1)
+
+    command = sys.argv[1]
+    transcript_path = sys.argv[2]
+
+    # Validate path
+    if not os.path.exists(transcript_path):
+        print(json.dumps({}))
+        sys.exit(0)
+
+    parser = TranscriptParser(cache_ttl=1.0)
+
+    try:
+        if command == "todo":
+            result = format_todo_output(parser, transcript_path)
+        elif command == "tools":
+            result = format_tools_output(parser, transcript_path)
+        elif command == "all":
+            result = {
+                "todo": format_todo_output(parser, transcript_path),
+                "tools": format_tools_output(parser, transcript_path),
+            }
+        else:
+            result = {"error": f"Unknown command: {command}"}
+
+        print(json.dumps(result))
+
+    except Exception as e:
+        # Graceful degradation - return empty on any error
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/global/hooks/post_merge_cleanup.sh

@@ -0,0 +1,132 @@
+#!/bin/bash
+# =============================================================================
+# post_merge_cleanup.sh - Post-Merge Cleanup Suggestions (ANV-242)
+# =============================================================================
+#
+# Suggests cleanup for related branches and stashes after a PR is merged.
+# This script is called after gh pr merge to help maintain repository hygiene.
+#
+# Usage:
+#   ./post_merge_cleanup.sh [branch_name]
+#   Called automatically via PostToolUse hook after gh pr merge
+#
+# Arguments:
+#   branch_name - The branch that was merged (optional, detected from git if not provided)
+#
+# Output:
+#   Cleanup suggestions for related artifacts (non-blocking)
+#
+# Exit Codes:
+#   0 - Always (suggestions are non-blocking)
+#
+
+set -euo pipefail
+
+# =============================================================================
+# Configuration
+# =============================================================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# =============================================================================
+# Functions
+# =============================================================================
+
+# Extract issue references from text (e.g., ANV-123)
+extract_issue_refs() {
+    local text="$1"
+    echo "$text" | grep -oE 'ANV-[0-9]+' | sort -u || true
+}
+
+# Check if a local branch exists
+branch_exists() {
+    local branch="$1"
+    git show-ref --verify --quiet "refs/heads/$branch" 2>/dev/null
+}
+
+# Get stashes related to an issue reference
+get_related_stashes() {
+    local issue_ref="$1"
+    git stash list 2>/dev/null | grep -i "$issue_ref" || true
+}
+
+# Get the most recently merged branch from reflog
+get_recently_merged_branch() {
+    # Look for recent merge commits in reflog
+    local merge_info
+    merge_info=$(git reflog --pretty=format:"%gs" -n 20 | grep -m1 "merge" || true)
+
+    if [[ -n "$merge_info" ]]; then
+        # Extract branch name from merge message
+        echo "$merge_info" | sed -n 's/.*merge \([^ ]*\).*/\1/p' | head -1
+    fi
+}
+
+# =============================================================================
+# Main
+# =============================================================================
+
+main() {
+    local merged_branch="${1:-}"
+
+    # If no branch provided, try to detect from recent merge
+    if [[ -z "$merged_branch" ]]; then
+        merged_branch=$(get_recently_merged_branch)
+    fi
+
+    if [[ -z "$merged_branch" ]]; then
+        # No merged branch detected, exit silently
+        exit 0
+    fi
+
+    # Extract issue references from branch name
+    local issue_refs
+    issue_refs=$(extract_issue_refs "$merged_branch")
+
+    if [[ -z "$issue_refs" ]]; then
+        # No issue references found, exit silently
+        exit 0
+    fi
+
+    # Check for cleanup opportunities
+    local has_suggestions=false
+    local suggestions=""
+
+    # Check if local branch still exists
+    if branch_exists "$merged_branch"; then
+        has_suggestions=true
+        suggestions+="
+- **Local branch**: \`$merged_branch\` still exists
+  Delete with: \`git branch -D $merged_branch\`"
+    fi
+
+    # Check for related stashes
+    for issue_ref in $issue_refs; do
+        local related_stashes
+        related_stashes=$(get_related_stashes "$issue_ref")
+
+        if [[ -n "$related_stashes" ]]; then
+            has_suggestions=true
+            local stash_count
+            stash_count=$(echo "$related_stashes" | wc -l | tr -d ' ')
+            suggestions+="
+- **Stashes**: $stash_count stash(es) reference $issue_ref
+  Review with: \`git stash list | grep -i $issue_ref\`"
+        fi
+    done
+
+    # Output suggestions if any
+    if [[ "$has_suggestions" == true ]]; then
+        echo ""
+        echo "## Cleanup Suggestions for $merged_branch"
+        echo ""
+        echo "The following artifacts may be obsolete after this merge:"
+        echo "$suggestions"
+        echo ""
+        echo "Run \`/cleanup\` to address these issues."
+        echo ""
+    fi
+}
+
+# Run main with all arguments
+main "$@"

package/global/hooks/post_tool_format.sh

@@ -0,0 +1,215 @@
+#!/bin/bash
+# =============================================================================
+# post_tool_format.sh - PostToolUse Formatting Hook (ANV-143)
+# =============================================================================
+#
+# Automatically formats code files after every Edit or Write operation.
+# This catches the "last 10%" of formatting issues that Claude often misses.
+#
+# Usage: Called automatically by Claude Code on PostToolUse events
+#
+# Environment Variables:
+#   CLAUDE_FILE_PATH    - Path to the file that was edited/written
+#   ANVIL_FORMAT_LOG    - Set to "true" to enable logging
+#   ANVIL_FORMAT_TIMEOUT - Timeout in seconds (default: 5)
+#
+# Exit Codes:
+#   0 - Always (formatting should never block operations)
+#
+
+# =============================================================================
+# Configuration
+# =============================================================================
+
+FILE_PATH="${CLAUDE_FILE_PATH:-}"
+ENABLE_LOGGING="${ANVIL_FORMAT_LOG:-false}"
+TIMEOUT_SECONDS="${ANVIL_FORMAT_TIMEOUT:-5}"
+LOG_FILE=".claude/logs/format.log"
+
+# Start timing
+START_TIME=$(date +%s%N 2>/dev/null || date +%s)
+
+# =============================================================================
+# Logging
+# =============================================================================
+
+log_event() {
+    local message="$1"
+    if [[ "$ENABLE_LOGGING" == "true" ]]; then
+        local timestamp
+        timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+        mkdir -p "$(dirname "$LOG_FILE")"
+        echo "[$timestamp] $message" >> "$LOG_FILE"
+    fi
+}
+
+log_timing() {
+    if [[ "$ENABLE_LOGGING" == "true" ]]; then
+        local end_time
+        end_time=$(date +%s%N 2>/dev/null || date +%s)
+        local duration_ms
+        if [[ ${#START_TIME} -gt 10 ]]; then
+            # Nanoseconds available
+            duration_ms=$(( (end_time - START_TIME) / 1000000 ))
+        else
+            # Fallback to seconds
+            duration_ms=$(( (end_time - START_TIME) * 1000 ))
+        fi
+        log_event "Formatting completed in ${duration_ms}ms"
+    fi
+}
+
+# =============================================================================
+# Path Validation
+# =============================================================================
+
+# Skip if no file path provided
+if [[ -z "$FILE_PATH" ]]; then
+    exit 0
+fi
+
+# Skip non-existent files
+if [[ ! -f "$FILE_PATH" ]]; then
+    exit 0
+fi
+
+# Skip binary and excluded paths
+is_excluded() {
+    case "$FILE_PATH" in
+        # Package managers
+        */node_modules/*|*/vendor/*|*/.venv/*|*/venv/*)
+            return 0
+            ;;
+        # Version control
+        */.git/*|*/.svn/*|*/.hg/*)
+            return 0
+            ;;
+        # Build outputs
+        */dist/*|*/build/*|*/out/*|*/.next/*|*/__pycache__/*)
+            return 0
+            ;;
+        # Lock files
+        */package-lock.json|*/yarn.lock|*/pnpm-lock.yaml|*/Cargo.lock|*/poetry.lock)
+            return 0
+            ;;
+        # Binary files
+        *.png|*.jpg|*.jpeg|*.gif|*.ico|*.svg|*.webp)
+            return 0
+            ;;
+        *.woff|*.woff2|*.ttf|*.eot|*.otf)
+            return 0
+            ;;
+        *.pdf|*.zip|*.tar|*.gz|*.bz2)
+            return 0
+            ;;
+        # Generated files
+        *.min.js|*.min.css|*.bundle.js|*.map)
+            return 0
+            ;;
+        *)
+            return 1
+            ;;
+    esac
+}
+
+if is_excluded; then
+    exit 0
+fi
+
+log_event "Formatting: $FILE_PATH"
+
+# =============================================================================
+# Formatter Execution with Timeout
+# =============================================================================
+
+run_formatter() {
+    local formatter_cmd="$1"
+
+    # Use timeout if available
+    if command -v timeout &> /dev/null; then
+        timeout "${TIMEOUT_SECONDS}s" bash -c "$formatter_cmd" 2>/dev/null || true
+    else
+        # macOS fallback: use perl for timeout
+        perl -e 'alarm shift; exec @ARGV' "$TIMEOUT_SECONDS" bash -c "$formatter_cmd" 2>/dev/null || true
+    fi
+}
+
+# =============================================================================
+# Format Based on File Type
+# =============================================================================
+
+case "$FILE_PATH" in
+    # TypeScript/JavaScript/Web files (Prettier)
+    *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs)
+        if command -v npx &> /dev/null; then
+            run_formatter "npx prettier --write '$FILE_PATH'"
+            log_event "Formatted with prettier (JS/TS)"
+        fi
+        ;;
+
+    *.json|*.md|*.css|*.scss|*.less|*.html|*.vue|*.svelte)
+        if command -v npx &> /dev/null; then
+            run_formatter "npx prettier --write '$FILE_PATH'"
+            log_event "Formatted with prettier (web)"
+        fi
+        ;;
+
+    # Python (black or ruff)
+    *.py)
+        if command -v black &> /dev/null; then
+            run_formatter "black --quiet '$FILE_PATH'"
+            log_event "Formatted with black"
+        elif command -v ruff &> /dev/null; then
+            run_formatter "ruff format --quiet '$FILE_PATH'"
+            log_event "Formatted with ruff"
+        fi
+        ;;
+
+    # Go (gofmt)
+    *.go)
+        if command -v gofmt &> /dev/null; then
+            run_formatter "gofmt -w '$FILE_PATH'"
+            log_event "Formatted with gofmt"
+        fi
+        ;;
+
+    # Shell scripts (shfmt)
+    *.sh|*.bash)
+        if command -v shfmt &> /dev/null; then
+            run_formatter "shfmt -w '$FILE_PATH'"
+            log_event "Formatted with shfmt"
+        fi
+        ;;
+
+    # Rust (rustfmt)
+    *.rs)
+        if command -v rustfmt &> /dev/null; then
+            run_formatter "rustfmt --quiet '$FILE_PATH'"
+            log_event "Formatted with rustfmt"
+        fi
+        ;;
+
+    # YAML (prettier or yamlfmt)
+    *.yaml|*.yml)
+        if command -v npx &> /dev/null; then
+            run_formatter "npx prettier --write '$FILE_PATH'"
+            log_event "Formatted with prettier (yaml)"
+        fi
+        ;;
+
+    # TOML (taplo)
+    *.toml)
+        if command -v taplo &> /dev/null; then
+            run_formatter "taplo format '$FILE_PATH'"
+            log_event "Formatted with taplo"
+        fi
+        ;;
+
+    *)
+        # Unknown file type - skip silently
+        log_event "Skipped: unknown file type"
+        ;;
+esac
+
+log_timing
+exit 0

package/global/hooks/ralph_context_monitor.py

@@ -0,0 +1,240 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = []
+# ///
+"""
+ralph_context_monitor.py - CCS Context Monitor for Ralph Mode (ANV-199)
+
+Monitors context percentage during Ralph autonomous execution and triggers
+checkpoints when thresholds are exceeded.
+
+Called as a PostToolUse hook during Ralph sessions. Reads context data from
+stdin (JSON from Claude Code) and checks against CCS thresholds.
+
+Thresholds:
+- L1 (70-84%): Warning only, no checkpoint
+- L2 (85-94%): Trigger checkpoint, allow current edit to complete
+- L3 (95%+): Emergency checkpoint, signal immediate stop
+
+Output signals (parsed by Claude Code):
+- CCS_WARNING|L1|<percent>|<message>
+- CCS_CHECKPOINT_TRIGGERED|L2|<percent>|<handoff_file>
+- CCS_EMERGENCY_STOP|L3|<percent>|<handoff_file>
+"""
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+# Add global lib to path for ralph_state
+_global_lib = Path(__file__).parent.parent / "lib"
+if _global_lib.exists():
+    sys.path.insert(0, str(_global_lib))
+
+# CCS Thresholds
+THRESHOLD_L1 = 70
+THRESHOLD_L2 = 85
+THRESHOLD_L3 = 95
+
+# State file location
+DEFAULT_STATE_FILE = ".claude/ralph-state.json"
+
+
+def is_ralph_active() -> bool:
+    """Check if Ralph mode is active by looking for state file."""
+    return Path(DEFAULT_STATE_FILE).exists()
+
+
+def load_ralph_state() -> dict:
+    """Load Ralph state from JSON file."""
+    try:
+        with open(DEFAULT_STATE_FILE) as f:
+            return json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError):
+        return {}
+
+
+def save_ralph_state(state: dict) -> None:
+    """Save Ralph state to JSON file."""
+    Path(DEFAULT_STATE_FILE).parent.mkdir(parents=True, exist_ok=True)
+    with open(DEFAULT_STATE_FILE, "w") as f:
+        json.dump(state, f, indent=2)
+
+
+def get_context_percent(input_data: dict) -> int:
+    """Extract context percentage from Claude Code JSON data.
+
+    Claude Code provides context window info in the input:
+    {
+        "context_window": {
+            "current_usage": {
+                "input_tokens": N,
+                "output_tokens": N,
+                "cache_read_input_tokens": N,
+                "cache_creation_input_tokens": N
+            },
+            "context_window_size": 200000
+        }
+    }
+    """
+    context_window = input_data.get("context_window", {})
+    current_usage = context_window.get("current_usage", {})
+    context_limit = context_window.get("context_window_size", 200000)
+
+    if context_limit == 0:
+        return 0
+
+    # Context usage = input + cache write (what counts toward limit)
+    tokens_input = current_usage.get("input_tokens", 0)
+    tokens_cache_write = current_usage.get("cache_creation_input_tokens", 0)
+    context_usage = tokens_input + tokens_cache_write
+
+    return int((context_usage / context_limit) * 100)
+
+
+def get_level(percent: int) -> str:
+    """Determine CCS level from percentage."""
+    if percent >= THRESHOLD_L3:
+        return "L3"
+    elif percent >= THRESHOLD_L2:
+        return "L2"
+    elif percent >= THRESHOLD_L1:
+        return "L1"
+    return "L0"
+
+
+def generate_handoff_filename() -> str:
+    """Generate timestamped handoff filename."""
+    timestamp = datetime.now().strftime("%Y-%m-%d-%H%M")
+    return f".claude/handoffs/{timestamp}-checkpoint.md"
+
+
+def trigger_checkpoint(level: str, percent: int, state: dict) -> str:
+    """Trigger a CCS checkpoint within Ralph iteration.
+
+    Updates state and returns the handoff file path.
+    """
+    timestamp = datetime.now(timezone.utc).isoformat()
+    handoff_file = generate_handoff_filename()
+
+    # Get current todo item if available
+    todo_items = state.get("todo_items", [])
+    current_item = todo_items[0] if todo_items else ""
+
+    # Initialize or update context_checkpoint
+    state["context_checkpoint"] = {
+        "active": True,
+        "level": level,
+        "percent_at_checkpoint": percent,
+        "timestamp": timestamp,
+        "handoff_file": handoff_file,
+        "resume_summary": "",  # Filled by handoff generation
+        "files_in_progress": [],
+        "current_todo_item": current_item,
+        "progress_on_item": "checkpoint triggered"
+    }
+
+    # Add to context history
+    if "context_history" not in state:
+        state["context_history"] = []
+
+    state["context_history"].append({
+        "iteration": state.get("iteration", 0),
+        "peak_percent": percent,
+        "checkpoint": True,
+        "level": level,
+        "timestamp": timestamp
+    })
+
+    save_ralph_state(state)
+    return handoff_file
+
+
+def update_context_history(percent: int, state: dict) -> None:
+    """Update context history without triggering checkpoint."""
+    if "context_history" not in state:
+        state["context_history"] = []
+
+    iteration = state.get("iteration", 0)
+
+    # Check if we already have an entry for this iteration
+    if state["context_history"]:
+        last_entry = state["context_history"][-1]
+        if last_entry.get("iteration") == iteration:
+            # Update peak if higher
+            if percent > last_entry.get("peak_percent", 0):
+                last_entry["peak_percent"] = percent
+            return
+
+    # Add new entry for this iteration (non-checkpoint)
+    state["context_history"].append({
+        "iteration": iteration,
+        "peak_percent": percent,
+        "checkpoint": False
+    })
+
+
+def main():
+    """Main entry point for the hook."""
+    # Skip if not in Ralph mode
+    if not is_ralph_active():
+        sys.exit(0)
+
+    try:
+        # Read JSON from stdin (same format as statusline)
+        input_data = json.load(sys.stdin)
+
+        # Get context percentage
+        percent = get_context_percent(input_data)
+
+        # Load current Ralph state
+        state = load_ralph_state()
+
+        # Check if checkpoint already active (avoid re-triggering)
+        checkpoint = state.get("context_checkpoint", {})
+        if checkpoint.get("active", False):
+            # Already in checkpoint mode, don't re-trigger
+            sys.exit(0)
+
+        # Determine level
+        level = get_level(percent)
+
+        # Handle based on level
+        if level == "L3":
+            # Emergency: trigger checkpoint and signal immediate stop
+            handoff_file = trigger_checkpoint("L3", percent, state)
+            print(f"CCS_EMERGENCY_STOP|L3|{percent}|{handoff_file}")
+            sys.exit(1)  # Signal emergency stop
+
+        elif level == "L2":
+            # Critical: trigger checkpoint, allow current edit to complete
+            handoff_file = trigger_checkpoint("L2", percent, state)
+            print(f"CCS_CHECKPOINT_TRIGGERED|L2|{percent}|{handoff_file}")
+            # Don't exit - let current operation complete
+
+        elif level == "L1":
+            # Warning: just log, no checkpoint
+            update_context_history(percent, state)
+            save_ralph_state(state)
+            print(f"CCS_WARNING|L1|{percent}|Context at {percent}%, approaching threshold")
+
+        else:
+            # L0: Normal operation, track history
+            update_context_history(percent, state)
+            save_ralph_state(state)
+
+    except json.JSONDecodeError:
+        # Invalid JSON input, skip silently
+        pass
+    except Exception:
+        # Don't crash Ralph on monitor errors
+        pass
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()