ralphblaster-agent 1.2.0

package/src/ralph/ralph.sh

@@ -0,0 +1,239 @@
+#!/bin/bash
+# Ralph Wiggum - Long-running AI agent loop
+# Usage: ./ralph.sh [max_iterations]
+
+set -e
+
+MAX_ITERATIONS=${1:-10}
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PRD_FILE="$SCRIPT_DIR/prd.json"
+PROGRESS_FILE="$SCRIPT_DIR/progress.txt"
+ARCHIVE_DIR="$SCRIPT_DIR/archive"
+LAST_BRANCH_FILE="$SCRIPT_DIR/.last-branch"
+
+# Worktree configuration - auto-detect git repository
+# Navigate up from instance directory to find git root
+CURRENT_DIR="$SCRIPT_DIR"
+while [ "$CURRENT_DIR" != "/" ]; do
+  if [ -d "$CURRENT_DIR/.git" ] || git -C "$CURRENT_DIR" rev-parse --git-dir >/dev/null 2>&1; then
+    MAIN_REPO_PATH="$(cd "$CURRENT_DIR" && git rev-parse --show-toplevel)"
+    break
+  fi
+  CURRENT_DIR="$(dirname "$CURRENT_DIR")"
+done
+
+if [ -z "$MAIN_REPO_PATH" ]; then
+  echo "Error: Could not find git repository. Ralph instances must be within a git repository."
+  exit 1
+fi
+
+# Derive worktree parent directory (sibling to repo)
+REPO_NAME="$(basename "$MAIN_REPO_PATH")"
+REPO_PARENT="$(dirname "$MAIN_REPO_PATH")"
+WORKTREE_PARENT="$REPO_PARENT/${REPO_NAME}-worktrees"
+WORKTREE_PATH_FILE="$SCRIPT_DIR/.worktree-path"
+
+# Setup worktree for the branch specified in prd.json
+setup_worktree() {
+  local branch_name="$1"
+
+  if [ -z "$branch_name" ]; then
+    echo "Error: No branch name provided to setup_worktree"
+    return 1
+  fi
+
+  # If RALPH_WORKTREE_PATH is set and valid, use it
+  if [ -n "$RALPH_WORKTREE_PATH" ] && [ -d "$RALPH_WORKTREE_PATH" ]; then
+    if git -C "$RALPH_WORKTREE_PATH" rev-parse --git-dir >/dev/null 2>&1; then
+      echo "✓ Using provided worktree: $RALPH_WORKTREE_PATH"
+      echo "$RALPH_WORKTREE_PATH" > "$WORKTREE_PATH_FILE"
+      export RALPH_WORKTREE_PATH
+      return 0
+    fi
+  fi
+
+  # Fall back to calculating worktree path (existing logic)
+  # Derive worktree path (strip ralph/ prefix if present)
+  local worktree_name=$(echo "$branch_name" | sed 's|^ralph/||')
+  local worktree_path="$WORKTREE_PARENT/$worktree_name"
+
+  # Create parent directory if it doesn't exist
+  mkdir -p "$WORKTREE_PARENT"
+
+  # Check if worktree already exists
+  if [ -d "$worktree_path" ]; then
+    # Verify it's a valid git worktree
+    if git -C "$worktree_path" rev-parse --git-dir >/dev/null 2>&1; then
+      echo "✓ Using existing worktree: $worktree_path"
+      echo "$worktree_path" > "$WORKTREE_PATH_FILE"
+      return 0
+    else
+      echo "⚠ Invalid worktree found, removing: $worktree_path"
+      rm -rf "$worktree_path"
+    fi
+  fi
+
+  # Create new worktree
+  echo "Creating worktree for branch: $branch_name"
+  cd "$MAIN_REPO_PATH"
+
+  # Check if branch exists
+  if git show-ref --verify --quiet "refs/heads/$branch_name"; then
+    # Branch exists, checkout to worktree
+    git worktree add "$worktree_path" "$branch_name"
+  else
+    # Branch doesn't exist, create from main
+    git worktree add "$worktree_path" -b "$branch_name" main
+  fi
+
+  if [ $? -eq 0 ]; then
+    echo "✓ Worktree created: $worktree_path"
+    echo "$worktree_path" > "$WORKTREE_PATH_FILE"
+    return 0
+  else
+    echo "✗ Failed to create worktree"
+    return 1
+  fi
+}
+
+# Archive previous run if branch changed
+if [ -f "$PRD_FILE" ] && [ -f "$LAST_BRANCH_FILE" ]; then
+  CURRENT_BRANCH=$(jq -r '.branchName // empty' "$PRD_FILE" 2>/dev/null || echo "")
+  LAST_BRANCH=$(cat "$LAST_BRANCH_FILE" 2>/dev/null || echo "")
+  
+  if [ -n "$CURRENT_BRANCH" ] && [ -n "$LAST_BRANCH" ] && [ "$CURRENT_BRANCH" != "$LAST_BRANCH" ]; then
+    # Archive the previous run
+    DATE=$(date +%Y-%m-%d)
+    # Strip "ralph/" prefix from branch name for folder
+    FOLDER_NAME=$(echo "$LAST_BRANCH" | sed 's|^ralph/||')
+    ARCHIVE_FOLDER="$ARCHIVE_DIR/$DATE-$FOLDER_NAME"
+    
+    echo "Archiving previous run: $LAST_BRANCH"
+    mkdir -p "$ARCHIVE_FOLDER"
+    [ -f "$PRD_FILE" ] && cp "$PRD_FILE" "$ARCHIVE_FOLDER/"
+    [ -f "$PROGRESS_FILE" ] && cp "$PROGRESS_FILE" "$ARCHIVE_FOLDER/"
+    echo "   Archived to: $ARCHIVE_FOLDER"
+    
+    # Reset progress file for new run
+    echo "# Ralph Progress Log" > "$PROGRESS_FILE"
+    echo "Started: $(date)" >> "$PROGRESS_FILE"
+    echo "---" >> "$PROGRESS_FILE"
+  fi
+fi
+
+# Track current branch
+if [ -f "$PRD_FILE" ]; then
+  CURRENT_BRANCH=$(jq -r '.branchName // empty' "$PRD_FILE" 2>/dev/null || echo "")
+  if [ -n "$CURRENT_BRANCH" ]; then
+    echo "$CURRENT_BRANCH" > "$LAST_BRANCH_FILE"
+  fi
+fi
+
+# Initialize progress file if it doesn't exist
+if [ ! -f "$PROGRESS_FILE" ]; then
+  echo "# Ralph Progress Log" > "$PROGRESS_FILE"
+  echo "Started: $(date)" >> "$PROGRESS_FILE"
+  echo "---" >> "$PROGRESS_FILE"
+fi
+
+# Setup worktree before starting iterations
+if [ -f "$PRD_FILE" ]; then
+  BRANCH_NAME=$(jq -r '.branchName // empty' "$PRD_FILE" 2>/dev/null || echo "")
+  if [ -n "$BRANCH_NAME" ]; then
+    setup_worktree "$BRANCH_NAME"
+    if [ $? -ne 0 ]; then
+      echo "Failed to setup worktree"
+      exit 1
+    fi
+  else
+    echo "Error: No branchName found in prd.json"
+    exit 1
+  fi
+else
+  echo "Error: prd.json not found at $PRD_FILE"
+  exit 1
+fi
+
+# Export environment variables for Claude
+WORKTREE_PATH=$(cat "$WORKTREE_PATH_FILE" 2>/dev/null || echo "")
+if [ -z "$WORKTREE_PATH" ]; then
+  echo "Error: Worktree path not found"
+  exit 1
+fi
+
+export RALPH_WORKTREE_PATH="$WORKTREE_PATH"
+export RALPH_INSTANCE_DIR="$SCRIPT_DIR"
+export RALPH_MAIN_REPO="$MAIN_REPO_PATH"
+
+echo "Starting Ralph - Max iterations: $MAX_ITERATIONS"
+echo "Worktree: $RALPH_WORKTREE_PATH"
+echo "Instance: $RALPH_INSTANCE_DIR"
+
+for i in $(seq 1 $MAX_ITERATIONS); do
+  echo ""
+  echo "═══════════════════════════════════════════════════════"
+  echo "  Ralph Iteration $i of $MAX_ITERATIONS"
+  echo "═══════════════════════════════════════════════════════"
+  echo "Started: $(date '+%H:%M:%S')"
+  echo ""
+  echo "💬 Executing Claude..."
+  echo ""
+
+  # Start tailing progress file in background to show real-time updates
+  if [ -f "$PROGRESS_FILE" ]; then
+    # Get current line count to show only new additions
+    PROGRESS_LINES_BEFORE=$(wc -l < "$PROGRESS_FILE" 2>/dev/null || echo "0")
+    tail -f "$PROGRESS_FILE" &
+    TAIL_PID=$!
+  fi
+
+  # Run claude with the ralph prompt from the instance directory
+  # Use --continue for iterations after the first to maintain context
+  # Use stdbuf to unbuffer output for real-time visibility
+  if [ "$i" -eq 1 ]; then
+    OUTPUT=$(cd "$SCRIPT_DIR" && cat prompt.md | stdbuf -oL -eL claude --dangerously-skip-permissions 2>&1 | tee /dev/stderr) || true
+  else
+    OUTPUT=$(cd "$SCRIPT_DIR" && cat prompt.md | stdbuf -oL -eL claude --dangerously-skip-permissions --continue 2>&1 | tee /dev/stderr) || true
+  fi
+
+  # Stop tailing progress file
+  if [ -n "$TAIL_PID" ]; then
+    kill $TAIL_PID 2>/dev/null || true
+    wait $TAIL_PID 2>/dev/null || true
+  fi
+
+  # Check for completion signal
+  if echo "$OUTPUT" | grep -q "<promise>COMPLETE</promise>"; then
+    echo ""
+    echo "✅ Ralph completed all tasks!"
+    echo "Completed at iteration $i of $MAX_ITERATIONS ($(date '+%H:%M:%S'))"
+    exit 0
+  fi
+
+  echo ""
+  echo "✓ Iteration $i complete at $(date '+%H:%M:%S')"
+
+  # Show progress summary from this iteration
+  if [ -f "$PROGRESS_FILE" ]; then
+    PROGRESS_LINES_AFTER=$(wc -l < "$PROGRESS_FILE" 2>/dev/null || echo "0")
+    NEW_LINES=$((PROGRESS_LINES_AFTER - PROGRESS_LINES_BEFORE))
+    if [ "$NEW_LINES" -gt 0 ]; then
+      echo ""
+      echo "📝 Progress update ($NEW_LINES new lines in $PROGRESS_FILE):"
+      echo "---"
+      tail -n "$NEW_LINES" "$PROGRESS_FILE" | head -20
+      if [ "$NEW_LINES" -gt 20 ]; then
+        echo "... (showing last 20 of $NEW_LINES new lines)"
+      fi
+      echo "---"
+    fi
+  fi
+
+  echo "Continuing in 2 seconds..."
+  sleep 2
+done
+
+echo ""
+echo "Ralph reached max iterations ($MAX_ITERATIONS) without completing all tasks."
+echo "Check $PROGRESS_FILE for status."
+exit 1

package/src/ralph-instance-manager.js

@@ -0,0 +1,171 @@
+const fs = require('fs').promises;
+const path = require('path');
+const { exec } = require('child_process');
+const { promisify } = require('util');
+
+const execAsync = promisify(exec);
+
+/**
+ * Manages Ralph agent instances within git worktrees
+ * Creates instance directories, converts PRDs, and manages progress tracking
+ */
+class RalphInstanceManager {
+  /**
+   * Creates a Ralph instance directory with all required files
+   * @param {string} worktreePath - Path to the git worktree
+   * @param {string} prompt - The PRD or feature description in markdown
+   * @param {string} jobId - Unique job identifier
+   * @returns {Promise<string>} Path to the created instance directory
+   */
+  async createInstance(worktreePath, prompt, jobId) {
+    // Create instance directory inside the worktree
+    const instancePath = path.join(worktreePath, 'ralph-instance');
+    await fs.mkdir(instancePath, { recursive: true });
+
+    // Copy bundled ralph.sh and prompt.md to instance
+    const bundledRalphDir = path.join(__dirname, 'ralph');
+    const ralphShPath = path.join(bundledRalphDir, 'ralph.sh');
+    const promptMdPath = path.join(bundledRalphDir, 'prompt.md');
+
+    await fs.copyFile(ralphShPath, path.join(instancePath, 'ralph.sh'));
+    await fs.copyFile(promptMdPath, path.join(instancePath, 'prompt.md'));
+
+    // Make ralph.sh executable
+    await fs.chmod(path.join(instancePath, 'ralph.sh'), 0o755);
+
+    // Convert prompt to prd.json
+    await this.convertPrdToJson(instancePath, prompt);
+
+    // Initialize progress.txt
+    const progressContent = `# Ralph Progress Log - Job ${jobId}
+Started: ${new Date().toISOString()}
+---
+
+`;
+    await fs.writeFile(path.join(instancePath, 'progress.txt'), progressContent);
+
+    return instancePath;
+  }
+
+  /**
+   * Converts markdown PRD to prd.json using Claude /ralph skill
+   * @param {string} instancePath - Path to the Ralph instance directory
+   * @param {string} prompt - The PRD markdown content
+   * @returns {Promise<void>}
+   */
+  async convertPrdToJson(instancePath, prompt) {
+    // Write the prompt to a temporary file
+    const promptFilePath = path.join(instancePath, 'input-prd.md');
+    await fs.writeFile(promptFilePath, prompt);
+
+    try {
+      // Run claude /ralph to convert the PRD
+      const { stdout, stderr } = await execAsync(
+        `claude /ralph < "${promptFilePath}"`,
+        {
+          cwd: instancePath,
+          env: {
+            ...process.env,
+            // Ensure Claude CLI can access the instance directory
+            PWD: instancePath
+          },
+          maxBuffer: 10 * 1024 * 1024 // 10MB buffer for large outputs
+        }
+      );
+
+      // Verify prd.json was created
+      const prdJsonPath = path.join(instancePath, 'prd.json');
+      try {
+        await fs.access(prdJsonPath);
+
+        // Validate prd.json structure
+        const prdContent = await fs.readFile(prdJsonPath, 'utf8');
+        const prd = JSON.parse(prdContent);
+
+        if (!prd.branchName || !prd.userStories) {
+          throw new Error('Invalid prd.json structure: missing branchName or userStories');
+        }
+      } catch (error) {
+        throw new Error(`prd.json validation failed: ${error.message}\nStdout: ${stdout}\nStderr: ${stderr}`);
+      }
+
+      // Clean up temporary prompt file
+      await fs.unlink(promptFilePath).catch(() => {});
+    } catch (error) {
+      throw new Error(`Failed to convert PRD to JSON: ${error.message}`);
+    }
+  }
+
+  /**
+   * Returns environment variables required for ralph.sh execution
+   * @param {string} worktreePath - Path to the git worktree
+   * @param {string} instancePath - Path to the Ralph instance directory
+   * @param {string} mainRepoPath - Path to the main repository
+   * @returns {Object} Environment variables object
+   */
+  getEnvVars(worktreePath, instancePath, mainRepoPath) {
+    return {
+      ...process.env,
+      RALPH_WORKTREE_PATH: worktreePath,
+      RALPH_INSTANCE_DIR: instancePath,
+      RALPH_MAIN_REPO: mainRepoPath
+    };
+  }
+
+  /**
+   * Reads and parses the progress summary from progress.txt
+   * @param {string} instancePath - Path to the Ralph instance directory
+   * @returns {Promise<string>} Summary of progress
+   */
+  async readProgressSummary(instancePath) {
+    const progressPath = path.join(instancePath, 'progress.txt');
+
+    try {
+      const content = await fs.readFile(progressPath, 'utf8');
+
+      // Extract meaningful summary from progress file
+      const lines = content.split('\n');
+      const summaryLines = [];
+
+      for (const line of lines) {
+        // Skip header and empty lines
+        if (line.startsWith('#') || line.startsWith('Started:') || line === '---' || !line.trim()) {
+          continue;
+        }
+
+        summaryLines.push(line);
+      }
+
+      return summaryLines.join('\n').trim() || 'No progress recorded yet';
+    } catch (error) {
+      return `Failed to read progress: ${error.message}`;
+    }
+  }
+
+  /**
+   * Checks if Ralph has completed successfully by looking for completion signal
+   * @param {string} output - The output from ralph.sh execution
+   * @returns {boolean} True if completion signal found
+   */
+  hasCompletionSignal(output) {
+    return output.includes('<promise>COMPLETE</promise>');
+  }
+
+  /**
+   * Extracts the branch name from prd.json
+   * @param {string} instancePath - Path to the Ralph instance directory
+   * @returns {Promise<string|null>} Branch name or null if not found
+   */
+  async getBranchName(instancePath) {
+    try {
+      const prdJsonPath = path.join(instancePath, 'prd.json');
+      const content = await fs.readFile(prdJsonPath, 'utf8');
+      const prd = JSON.parse(content);
+      return prd.branchName || null;
+    } catch (error) {
+      return null;
+    }
+  }
+}
+
+module.exports = RalphInstanceManager;

package/src/worktree-manager.js

@@ -0,0 +1,170 @@
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs').promises;
+const logger = require('./logger');
+
+/**
+ * WorktreeManager - Manages git worktrees for parallel job execution
+ *
+ * Each job gets an isolated worktree in .ralph-worktrees/job-{id}/
+ * with a unique branch: ralph/ticket-{task_id}/job-{job_id}
+ */
+class WorktreeManager {
+  /**
+   * Create a new worktree for a job
+   * @param {Object} job - The job object with id, task, and project
+   * @returns {Promise<string>} - The absolute path to the worktree
+   */
+  async createWorktree(job) {
+    const worktreePath = this.getWorktreePath(job)
+    const branchName = this.getBranchName(job)
+    const systemPath = job.project.system_path
+
+    logger.info(`Creating worktree for job ${job.id}`, {
+      worktreePath,
+      branchName,
+      systemPath
+    })
+
+    try {
+      // Verify git is available
+      await this.execGit(systemPath, ['--version'], 5000)
+
+      // Check if worktree already exists (from a previous failed run)
+      try {
+        await fs.access(worktreePath)
+        logger.warn(`Worktree already exists at ${worktreePath}, removing stale worktree`)
+        await this.removeWorktree(job)
+      } catch (err) {
+        // Worktree doesn't exist, which is expected
+      }
+
+      // Create the worktree with a new branch
+      // -b creates a new branch, --detach would checkout without branch
+      await this.execGit(
+        systemPath,
+        ['worktree', 'add', '-b', branchName, worktreePath, 'HEAD'],
+        30000
+      )
+
+      logger.info(`Created worktree: ${worktreePath}`)
+      return worktreePath
+    } catch (error) {
+      logger.error(`Failed to create worktree for job ${job.id}`, {
+        error: error.message,
+        worktreePath,
+        branchName
+      })
+      throw new Error(`Failed to create worktree: ${error.message}`)
+    }
+  }
+
+  /**
+   * Remove a worktree after job completion
+   * @param {Object} job - The job object
+   */
+  async removeWorktree(job) {
+    const worktreePath = this.getWorktreePath(job)
+    const branchName = this.getBranchName(job)
+    const systemPath = job.project.system_path
+
+    logger.info(`Removing worktree for job ${job.id}`, {
+      worktreePath,
+      branchName
+    })
+
+    try {
+      // Remove the worktree (--force removes even if dirty)
+      await this.execGit(
+        systemPath,
+        ['worktree', 'remove', worktreePath, '--force'],
+        30000
+      )
+
+      logger.info(`Removed worktree: ${worktreePath}`)
+    } catch (error) {
+      // Log error but don't throw - cleanup is best-effort
+      logger.error(`Failed to remove worktree for job ${job.id}`, {
+        error: error.message,
+        worktreePath
+      })
+    }
+
+    // Note: We intentionally don't delete the branch here
+    // The branch remains in the repo for history/inspection
+  }
+
+  /**
+   * Get the absolute path where the worktree should be created
+   * @param {Object} job - The job object
+   * @returns {string} - Absolute path to worktree
+   */
+  getWorktreePath(job) {
+    const systemPath = job.project.system_path
+    return path.join(systemPath, '.ralph-worktrees', `job-${job.id}`)
+  }
+
+  /**
+   * Get the branch name for this job
+   * @param {Object} job - The job object
+   * @returns {string} - Branch name in format ralph/ticket-{task_id}/job-{job_id}
+   */
+  getBranchName(job) {
+    return `ralph/ticket-${job.task_id}/job-${job.id}`
+  }
+
+  /**
+   * Execute a git command safely
+   * @param {string} cwd - Working directory
+   * @param {string[]} args - Git command arguments
+   * @param {number} timeout - Timeout in milliseconds (default: 30s)
+   * @returns {Promise<{stdout: string, stderr: string}>}
+   */
+  async execGit(cwd, args, timeout = 30000) {
+    return new Promise((resolve, reject) => {
+      const process = spawn('git', args, {
+        cwd,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        shell: false // Security: Don't use shell to prevent injection
+      })
+
+      let stdout = ''
+      let stderr = ''
+      let timedOut = false
+
+      const timer = setTimeout(() => {
+        timedOut = true
+        process.kill('SIGTERM')
+        reject(new Error(`Git command timed out after ${timeout}ms`))
+      }, timeout)
+
+      process.stdout.on('data', (data) => {
+        stdout += data.toString()
+      })
+
+      process.stderr.on('data', (data) => {
+        stderr += data.toString()
+      })
+
+      process.on('error', (err) => {
+        clearTimeout(timer)
+        if (!timedOut) {
+          reject(new Error(`Failed to execute git: ${err.message}`))
+        }
+      })
+
+      process.on('close', (code) => {
+        clearTimeout(timer)
+        if (timedOut) return // Already rejected
+
+        if (code === 0) {
+          resolve({ stdout, stderr })
+        } else {
+          reject(new Error(`Git command failed (exit code ${code}): ${stderr || stdout}`))
+        }
+      })
+    })
+  }
+}
+
+module.exports = WorktreeManager;