anvil-dev-framework 0.1.6

package/global/tools/ralph-loop.sh

@@ -0,0 +1,359 @@
+#!/bin/bash
+# =============================================================================
+# ralph-loop.sh - Ralph Wiggum Execution Loop (ANV-163)
+# =============================================================================
+#
+# External loop that runs Claude Code in print mode, feeding PROMPT.md each
+# iteration. The ralph_stop.sh hook handles continuation/exit decisions.
+#
+# Usage:
+#   ./ralph-loop.sh [options]
+#
+# Options:
+#   --prompt FILE         Path to prompt file (default: PROMPT.md)
+#   --max-iterations N    Override max iterations (default: env or 50)
+#   --completion TEXT     Override completion promise (default: env or COMPLETE)
+#   --dry-run             Show what would run without executing
+#   --verbose             Enable verbose output
+#
+# Environment Variables:
+#   RALPH_MAX_ITERATIONS      Max iterations (default: 50)
+#   RALPH_COMPLETION_PROMISE  Completion text (default: COMPLETE)
+#   RALPH_STATE_FILE          State file path (default: .claude/ralph-state.json)
+#   RALPH_ENABLE_LOGGING      Enable logging (default: false)
+#
+# Exit Codes:
+#   0  - Task completed successfully (promise detected)
+#   1  - Error or circuit breaker triggered
+#   2  - Manual interruption (Ctrl+C)
+#
+# Dependencies:
+#   - Claude Code CLI (@anthropic/claude-code)
+#   - jq (for state management)
+#
+# =============================================================================
+
+set -euo pipefail
+
+# =============================================================================
+# Configuration
+# =============================================================================
+
+PROMPT_FILE="PROMPT.md"  # Default, may be overridden by --prompt
+MAX_ITERATIONS="${RALPH_MAX_ITERATIONS:-50}"
+COMPLETION_PROMISE="${RALPH_COMPLETION_PROMISE:-COMPLETE}"
+STATE_FILE="${RALPH_STATE_FILE:-.claude/ralph-state.json}"
+ENABLE_LOGGING="${RALPH_ENABLE_LOGGING:-false}"
+LOG_FILE=".claude/logs/ralph-loop.log"
+
+DRY_RUN=false
+VERBOSE=false
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --prompt)
+            PROMPT_FILE="$2"
+            shift 2
+            ;;
+        --max-iterations)
+            MAX_ITERATIONS="$2"
+            shift 2
+            ;;
+        --completion)
+            COMPLETION_PROMISE="$2"
+            shift 2
+            ;;
+        --dry-run)
+            DRY_RUN=true
+            shift
+            ;;
+        --verbose)
+            VERBOSE=true
+            shift
+            ;;
+        --help|-h)
+            head -50 "$0" | grep -E "^#" | sed 's/^# //' | sed 's/^#//'
+            exit 0
+            ;;
+        *)
+            # First positional arg is prompt file
+            if [[ ! "$1" =~ ^-- ]]; then
+                PROMPT_FILE="$1"
+            fi
+            shift
+            ;;
+    esac
+done
+
+# Export for child processes (hooks)
+export RALPH_MAX_ITERATIONS="$MAX_ITERATIONS"
+export RALPH_COMPLETION_PROMISE="$COMPLETION_PROMISE"
+export RALPH_STATE_FILE="$STATE_FILE"
+export RALPH_ENABLE_LOGGING="$ENABLE_LOGGING"
+
+# =============================================================================
+# Utilities
+# =============================================================================
+
+log() {
+    local level="$1"
+    local message="$2"
+    local timestamp
+    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+    if [[ "$ENABLE_LOGGING" == "true" ]]; then
+        mkdir -p "$(dirname "$LOG_FILE")"
+        echo "[$timestamp] [$level] $message" >> "$LOG_FILE"
+    fi
+
+    if [[ "$VERBOSE" == "true" ]] || [[ "$level" == "ERROR" ]]; then
+        case "$level" in
+            ERROR)  echo "❌ Ralph Loop: $message" >&2 ;;
+            WARN)   echo "⚠️  Ralph Loop: $message" >&2 ;;
+            INFO)   echo "🔄 Ralph Loop: $message" ;;
+            OK)     echo "✅ Ralph Loop: $message" ;;
+        esac
+    fi
+}
+
+check_dependencies() {
+    local missing=()
+
+    if ! command -v npx &> /dev/null; then
+        missing+=("npx (Node.js)")
+    fi
+
+    if ! command -v jq &> /dev/null; then
+        missing+=("jq")
+    fi
+
+    if [[ ${#missing[@]} -gt 0 ]]; then
+        log "ERROR" "Missing dependencies: ${missing[*]}"
+        echo "Install missing dependencies:" >&2
+        echo "  - npx: Install Node.js (https://nodejs.org)" >&2
+        echo "  - jq: apt install jq (Linux) or brew install jq (macOS)" >&2
+        exit 1
+    fi
+}
+
+check_prompt_file() {
+    if [[ ! -f "$PROMPT_FILE" ]]; then
+        log "ERROR" "Prompt file not found: $PROMPT_FILE"
+        if [[ "$DRY_RUN" == "true" ]]; then
+            echo "⚠️  Prompt file not found: $PROMPT_FILE (dry-run mode, continuing)" >&2
+        else
+            echo "Create the prompt file first:" >&2
+            echo "  1. Run /ralph start to set up files" >&2
+            echo "  2. Or create $PROMPT_FILE manually" >&2
+            exit 1
+        fi
+    fi
+}
+
+# =============================================================================
+# State Management
+# =============================================================================
+
+init_state() {
+    if [[ ! -f "$STATE_FILE" ]]; then
+        mkdir -p "$(dirname "$STATE_FILE")"
+        local timestamp
+        timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+        cat > "$STATE_FILE" << EOF
+{
+  "task_name": "ralph-task",
+  "objective": "Complete the task defined in PROMPT.md",
+  "iteration": 0,
+  "started_at": "$timestamp",
+  "status": "running",
+  "no_change_count": 0,
+  "last_diff_hash": "",
+  "error_hashes": []
+}
+EOF
+        log "INFO" "Initialized state file: $STATE_FILE"
+    fi
+}
+
+read_state() {
+    local key="$1"
+    local default="${2:-}"
+    jq -r ".$key // \"$default\"" "$STATE_FILE" 2>/dev/null || echo "$default"
+}
+
+get_iteration() {
+    read_state "iteration" "0"
+}
+
+get_status() {
+    read_state "status" "unknown"
+}
+
+# =============================================================================
+# Signal Handling
+# =============================================================================
+
+cleanup() {
+    log "WARN" "Interrupted! Cleaning up..."
+
+    # Update state to reflect interruption
+    if [[ -f "$STATE_FILE" ]]; then
+        jq '.status = "interrupted"' "$STATE_FILE" > tmp.$$ && mv tmp.$$ "$STATE_FILE"
+    fi
+
+    echo ""
+    echo "╔══════════════════════════════════════════════════════════════╗"
+    echo "║                    RALPH LOOP INTERRUPTED                     ║"
+    echo "╠══════════════════════════════════════════════════════════════╣"
+    echo "║ The loop was interrupted by user (Ctrl+C).                   ║"
+    echo "║                                                              ║"
+    echo "║ Current iteration: $(printf '%-3s' "$(get_iteration)")"                                   "║"
+    echo "║ State file: $STATE_FILE"
+    echo "║                                                              ║"
+    echo "║ To resume:  ./ralph-loop.sh                                  ║"
+    echo "║ To stop:    rm $STATE_FILE                                   ║"
+    echo "╚══════════════════════════════════════════════════════════════╝"
+
+    exit 2
+}
+
+trap cleanup SIGINT SIGTERM
+
+# =============================================================================
+# Main Loop
+# =============================================================================
+
+run_iteration() {
+    local iteration="$1"
+
+    log "INFO" "Starting iteration $iteration"
+
+    if [[ "$DRY_RUN" == "true" ]]; then
+        echo "[DRY RUN] Would execute: cat $PROMPT_FILE | npx --yes @anthropic-ai/claude-code --print"
+        return 0
+    fi
+
+    # Run Claude Code with the prompt
+    # The --print flag runs in non-interactive mode
+    # Exit code from Claude Code is handled by the stop hook
+    local exit_code=0
+    cat "$PROMPT_FILE" | npx --yes @anthropic-ai/claude-code --print || exit_code=$?
+
+    return $exit_code
+}
+
+main() {
+    echo "╔══════════════════════════════════════════════════════════════╗"
+    echo "║                    RALPH WIGGUM LOOP                         ║"
+    echo "╠══════════════════════════════════════════════════════════════╣"
+    echo "║ Starting autonomous execution loop.                          ║"
+    echo "║                                                              ║"
+    echo "║ Prompt file:      $PROMPT_FILE"
+    echo "║ Max iterations:   $MAX_ITERATIONS"
+    echo "║ Completion text:  $COMPLETION_PROMISE"
+    echo "║                                                              ║"
+    echo "║ Press Ctrl+C to interrupt safely.                            ║"
+    echo "╚══════════════════════════════════════════════════════════════╝"
+    echo ""
+
+    check_dependencies
+    check_prompt_file
+    init_state
+
+    local iteration=0
+    local start_iteration
+    start_iteration=$(get_iteration)
+
+    if [[ $start_iteration -gt 0 ]]; then
+        iteration=$start_iteration
+        log "INFO" "Resuming from iteration $iteration"
+    fi
+
+    while true; do
+        iteration=$((iteration + 1))
+
+        # Check max iterations before running
+        if [[ $iteration -gt $MAX_ITERATIONS ]]; then
+            log "WARN" "Maximum iterations ($MAX_ITERATIONS) reached"
+            echo ""
+            echo "══════════════════════════════════════════════════════════════"
+            echo " RALPH LOOP STOPPED: Maximum iterations reached"
+            echo "══════════════════════════════════════════════════════════════"
+            exit 1
+        fi
+
+        echo ""
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        echo " ITERATION $iteration of $MAX_ITERATIONS"
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        echo ""
+
+        # Run the iteration
+        local result=0
+        run_iteration "$iteration" || result=$?
+
+        # Check status after iteration
+        local status
+        status=$(get_status)
+
+        case "$status" in
+            "completed")
+                log "OK" "Task completed successfully!"
+                echo ""
+                echo "╔══════════════════════════════════════════════════════════════╗"
+                echo "║                    TASK COMPLETE                             ║"
+                echo "╠══════════════════════════════════════════════════════════════╣"
+                echo "║ The completion promise was detected.                         ║"
+                echo "║ Total iterations: $iteration"
+                echo "╚══════════════════════════════════════════════════════════════╝"
+                exit 0
+                ;;
+            "fatal_error")
+                log "ERROR" "Fatal error detected - stopping"
+                echo ""
+                echo "╔══════════════════════════════════════════════════════════════╗"
+                echo "║                    FATAL ERROR                               ║"
+                echo "╠══════════════════════════════════════════════════════════════╣"
+                echo "║ Claude reported a fatal/unrecoverable error.                 ║"
+                echo "║ Check progress.txt for details.                              ║"
+                echo "╚══════════════════════════════════════════════════════════════╝"
+                exit 1
+                ;;
+            "circuit_breaker")
+                log "ERROR" "Circuit breaker triggered - stopping"
+                echo ""
+                echo "╔══════════════════════════════════════════════════════════════╗"
+                echo "║                    CIRCUIT BREAKER                           ║"
+                echo "╠══════════════════════════════════════════════════════════════╣"
+                echo "║ Loop appears stuck (no changes across multiple iterations).  ║"
+                echo "║ Review progress.txt and fix_plan.md for issues.              ║"
+                echo "╚══════════════════════════════════════════════════════════════╝"
+                exit 1
+                ;;
+            "max_iterations")
+                log "WARN" "Maximum iterations reached"
+                exit 1
+                ;;
+            "stopped")
+                log "INFO" "Manually stopped"
+                exit 0
+                ;;
+            *)
+                # Status is "running" or unknown - continue loop
+                if [[ $result -ne 0 ]]; then
+                    log "INFO" "Iteration $iteration complete, continuing..."
+                fi
+                ;;
+        esac
+
+        # Small delay between iterations for rate limiting
+        sleep 1
+    done
+}
+
+# =============================================================================
+# Entry Point
+# =============================================================================
+
+main "$@"

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "anvil-dev-framework",
+  "version": "0.1.6",
+  "description": "AI-powered development framework for Claude Code - multi-agent coordination, specifications, and quality gates",
+  "author": "Alexander Cahiz",
+  "license": "MIT",
+  "homepage": "https://github.com/alexandercahiz/anvil-dev-framework",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexandercahiz/anvil-dev-framework.git"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "development",
+    "framework",
+    "multi-agent",
+    "specifications",
+    "quality-gates"
+  ],
+  "bin": {
+    "anvil": "./scripts/anvil"
+  },
+  "files": [
+    "scripts/",
+    "global/",
+    "docs/",
+    "VERSION",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js || true"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "bun": ">=1.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "preferGlobal": true
+}