wralph 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b57c8d8dca1cee5599eb0948a7eb9cbab5032bd33c9eb6aa879fbf7ec3b590b3
+  data.tar.gz: b04697444291bd7749c80a26a3f2cc29710f8fa9ef2d76a89c9334450ece3c52
+SHA512:
+  metadata.gz: 727b377643d3159fa5832d0c67c08b207e11bd806648e652913f80b4b38412c929c6c028bfd92c55037ab59f4c56c919421ff7cced18733512ee29d568dab083
+  data.tar.gz: 6e12faa9ada5ac909b82e29f5850820cbd5c98407789632d6392a1fbe5eb1fd3cbafe5c6803fbd63f91851d0166af80a5b86f657b319df41679413a690551c4c

data/README.md

@@ -0,0 +1,275 @@
+# WRALPH - Workflow Ralph
+
+**WRALPH** (short for **Workflow Ralph**) is an implementation of the "Ralph Wiggum" technique of using AI agents to iteratively develop code until complete.
+
+## Overview
+
+This toolset provides a streamlined workflow for fixing bugs, implementing features, or making code changes by combining AI-powered code generation with human oversight. The process flows from issue repository pull → plan generation → execution → CI iteration → human review.
+
+## What Makes WRALPH Distinct
+
+What sets WRALPH apart from other autonomous development tools is its explicit use of **non-AI components** to facilitate the workflow and allow multiple instances running (even on the same repository) without interference:
+
+- **Issue Repository**: Plans are generated from structured issue repositories (default: GitHub issues), providing clear requirements and context
+- **Git Worktrees**: Each issue gets its own isolated worktree, ensuring clean separation and preventing conflicts
+- **Remote CI Evaluation**: Results are evaluated using remote CI (default: CircleCI), which allows multiple instances of WRALPH to run in parallel without interfering with each other
+
+The remote CI feature is particularly powerful—it enables you to run multiple instances of WRALPH simultaneously, each working on different issues, without the processes stepping on each other. This parallel execution capability makes WRALPH highly scalable for teams working on multiple issues concurrently.
+
+## Workflow
+
+```mermaid
+flowchart TD
+    Start[Create GitHub Issue] --> Init[wralph init]
+    Init --> Plan[wralph plan ISSUE_NUMBER]
+    Plan --> PlanGen[AI Generates Plan]
+    PlanGen --> Review{Human Reviews Plan}
+    Review -->|Needs Changes| PlanGen
+    Review -->|Approved| Execute[Execute Plan]
+    Execute --> Code[AI Makes Code Changes]
+    Code --> PR[Create Pull Request]
+    PR --> CI[Monitor CI Build]
+    CI --> CheckCI{CI Passes?}
+    CheckCI -->|No| Fix[AI Analyzes Failures]
+    Fix --> Push[Push Fixes]
+    Push --> CI
+    CheckCI -->|Yes| HumanReview{Human Reviews PR}
+    HumanReview -->|Changes Requested| Feedback[wralph feedback ISSUE_NUMBER]
+    Feedback --> Changes[AI Makes Changes]
+    Changes --> CI
+    HumanReview -->|Approved| Cleanup[wralph remove ISSUE_NUMBER]
+    Cleanup --> Done[Complete]
+```
+
+## Prerequisites
+
+Before using these scripts, ensure you have the following tools installed:
+
+- **[Ruby](https://www.ruby-lang.org/)** `>= 3.0` - Ruby interpreter (use rbenv, rvm, or Homebrew to install)
+- **[GitHub CLI](https://cli.github.com/)** (`gh`) - Must be authenticated (`gh auth login`)
+- **[Claude Code CLI](https://code.claude.com/)** (`claude`) - For AI-powered code generation
+- **[jq](https://stedolan.github.io/jq/)** - JSON processor (install via `brew install jq` on macOS)
+- **[curl](https://curl.se/)** - HTTP client (usually pre-installed)
+- **[worktrunk](https://github.com/max-sixty/worktrunk)** (`wt`) - Git worktree management tool
+
+## Configuration
+
+After running `wralph init`, you'll have a `.wralph` directory with configuration files:
+
+### Secrets (`secrets.yaml`)
+
+Add your CI API token to `.wralph/secrets.yaml`:
+
+```yaml
+ci_api_token: your_token_here
+```
+
+This file is automatically git-ignored for security.
+
+### Adapter Configuration (`config.yaml`)
+
+The `.wralph/config.yaml` file allows you to configure which adapters to use:
+
+```yaml
+# Objective repository adapter (where issues/objectives are stored)
+objective_repository:
+  source: github_issues  # or "custom" with class_name
+
+# CI/CD adapter (for build monitoring)
+ci:
+  source: circle_ci  # or "custom" with class_name
+```
+
+**Custom Adapters**: You can create custom adapters by:
+1. Setting `source: custom` in the config
+2. Specifying a `class_name` (e.g., `MyCustomAdapter`)
+3. Creating a file `.wralph/my_custom_adapter.rb` with your class implementation
+
+See the config file comments for more details on creating custom adapters.
+
+## Installation
+
+If you're installing WRALPH (once it's distributed via Homebrew):
+
+```bash
+brew install wralph  # When available
+```
+
+For development:
+
+1. Ensure you have Ruby 3.0 or higher installed
+2. Clone this repository
+3. Install dependencies: `bundle install`
+
+## Usage
+
+### 1. Initialize WRALPH
+
+```bash
+wralph init
+```
+
+This creates the `.wralph` directory structure needed for plans and configuration.
+
+### 2. Create and Plan an Issue
+
+```bash
+wralph plan 123
+```
+
+This command:
+- Fetches GitHub issue #123
+- Uses Claude Code to generate a detailed plan saved to `.wralph/plans/plan_123.md`
+- Prompts you to review and approve the plan
+- Automatically proceeds to execution once approved
+
+The plan includes:
+- Analysis of the issue
+- Approach to solving it
+- Test cases to verify the solution
+- Implementation steps
+- Potential risks or considerations
+- Questions for clarification (if needed)
+
+After plan approval, `wralph plan` automatically:
+- Creates a git worktree for branch `issue-123`
+- Uses Claude Code to implement the plan
+- Commits changes (including the plan file) with a descriptive message
+- Pushes the branch and creates a pull request
+- Monitors CI build status for the PR (default: CircleCI)
+- If CI fails: extracts failure details, uses Claude Code to fix issues, pushes fixes, and iterates (up to 10 retries)
+- If CI passes: exits successfully
+
+**Note:** The AI is instructed not to run tests locally, but instead to push a PR and rely on CI.
+
+Failure details are saved to `tmp/issue-{NUMBER}_failure_details_{ITERATION}.txt` for reference.
+
+### 3. Handle PR Review Feedback
+
+When reviewers request changes on a PR:
+
+```bash
+wralph feedback 123
+```
+
+This command:
+- Switches to the worktree for branch `issue-123`
+- Prompts you to enter feedback (multi-line input, press Enter 3 times to submit)
+- Uses Claude Code to analyze the feedback and make changes
+- Pushes the changes and monitors CI again (with automatic retries if CI fails)
+
+### 4. Clean Up (Optional)
+
+To delete a branch and its worktree after completion:
+
+```bash
+wralph remove 123
+```
+
+This removes:
+- Local branch `issue-123`
+- Remote branch `issue-123`
+- Associated worktree
+
+## Commands Overview
+
+| Command | Purpose |
+|---------|---------|
+| `wralph init` | Initialize WRALPH in the current repository |
+| `wralph plan <issue_number>` | Generate plan and execute it (creates PR, monitors CI) |
+| `wralph feedback <issue_number>` | Handle PR review feedback and iterate |
+| `wralph remove <issue_number>` | Clean up branches and worktrees |
+
+## Directory Structure
+
+The tool creates and manages the following:
+
+```
+.
+├── .wralph/                      # WRALPH configuration directory (created by `wralph init`)
+│   ├── config.yaml               # Adapter configuration (objective_repository, ci)
+│   ├── secrets.yaml              # API tokens and secrets (git-ignored)
+│   └── plans/                    # Generated plans
+│       └── plan_123.md           # Example plan file
+├── tmp/                          # CI failure details (created automatically)
+│   └── issue-123_failure_details_1_1.txt
+└── [worktree directories]        # Managed by worktrunk
+```
+
+## Key Features
+
+- **Worktree Isolation**: Each issue gets its own git worktree via worktrunk, keeping your main working directory clean
+- **Automatic CI Integration**: Monitors CI builds (configurable adapter), extracts failure details, and iteratively fixes issues
+- **Configurable Adapters**: Support for custom objective repositories and CI adapters via configuration
+- **Human Oversight**: Plans require approval before execution, and PRs can be reviewed before merging
+- **Failure Recovery**: Automatically retries up to 10 times to fix CI failures
+- **Branch Management**: Automatic branch creation, PR creation, and cleanup utilities
+- **Plan Persistence**: All plans are saved for reference and context during iterations
+
+## Workflow Tips
+
+1. **Initialize First**: Always run `wralph init` before using other commands
+2. **Start Clean**: Ensure you don't have uncommitted changes before running `wralph plan` (or commit/stash them first)
+3. **Review Plans Carefully**: The plan review step is your opportunity to catch issues before code changes
+4. **Monitor Output**: Commands provide colored output (ℹ info, ✓ success, ⚠ warning, ✗ error) to track progress
+5. **PR Linking**: PRs automatically reference the GitHub issue (e.g., "Fixes #123") for proper linking
+6. **CI Timeout**: CI monitoring waits up to 1 hour for builds to complete
+7. **Max Retries**: If CI fails more than 10 times, the command exits and requires manual intervention
+
+## Example Session
+
+```bash
+# 1. Initialize WRALPH in your repository
+wralph init
+
+# 2. Create a GitHub issue describing the bug/feature
+
+# 3. Generate and execute plan:
+wralph plan 456
+
+# Review the generated plan at .wralph/plans/plan_456.md
+# Answer any questions Claude asked, then approve
+
+# 4. Command automatically:
+#    - Executes the plan
+#    - Creates PR #789
+#    - Monitors CI
+#    - Fixes failures if needed
+
+# 5. Review the PR on GitHub
+
+# 6. If changes are needed:
+wralph feedback 456
+# Enter your feedback, press Enter 3 times
+
+# 7. After merging, clean up:
+wralph remove 456
+```
+
+## Error Handling
+
+The tool includes error handling for common scenarios:
+- WRALPH not initialized (must run `wralph init` first)
+- Missing GitHub authentication
+- Uncommitted changes (with warning)
+- Duplicate branches (must delete first)
+- Missing plan files
+- CI timeout or max retries exceeded
+- Missing required tools
+
+All errors provide clear messages about what went wrong and how to resolve the issue.
+
+## Development
+
+### Requirements
+
+- Ruby 3.0 or higher (specified in `.ruby-version` and `Gemfile`)
+- Development dependencies installed via `bundle install`
+
+### Running Tests
+
+```bash
+bundle exec rspec
+```
+
+Tests are located in the `spec/` directory and are excluded from distribution packages.

data/bin/wralph

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Add lib directory to load path
+lib_dir = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
+
+require 'wralph'
+
+# Parse arguments
+case ARGV[0]
+when 'init'
+  Wralph::Run::Init.run
+when 'plan'
+  if ARGV[1].nil?
+    puts "Usage: wralph plan <github_issue_number>"
+    exit 1
+  end
+  Wralph::Run::Plan.run(ARGV[1])
+when 'execute'
+  if ARGV[1].nil?
+    puts "Usage: wralph execute <github_issue_number>"
+    exit 1
+  end
+  Wralph::Run::ExecutePlan.run(ARGV[1])
+when 'feedback'
+  if ARGV[1].nil?
+    puts "Usage: wralph feedback <github_issue_number>"
+    exit 1
+  end
+  Wralph::Run::Feedback.run(ARGV[1])
+when 'remove'
+  if ARGV[1].nil?
+    puts "Usage: wralph remove <github_issue_number>"
+    exit 1
+  end
+  Wralph::Run::Remove.run(ARGV[1])
+when '--version', '-v'
+  puts "wralph #{Wralph::VERSION}"
+else
+  if ARGV.empty? || ARGV[0] == '--help' || ARGV[0] == '-h'
+    puts "Usage: wralph <command> [options]"
+    puts ""
+    puts "Commands:"
+    puts "  init                    Initialize WRALPH in the current repository"
+    puts "  plan <issue_number>     Generate and execute plan for GitHub issue"
+    puts "  execute <issue_number>  Execute an existing plan for GitHub issue"
+    puts "  feedback <issue_number> Handle PR review feedback"
+    puts "  remove <issue_number>   Remove branch, worktree, and remote branch for issue"
+    puts ""
+    puts "Options:"
+    puts "  --version, -v           Show version"
+    puts "  --help, -h              Show this help message"
+    exit 0
+  else
+    puts "Unknown command: #{ARGV[0]}"
+    puts "Run 'wralph --help' for usage information"
+    exit 1
+  end
+end

data/lib/wralph/adapters/agents/claude_code.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+require_relative '../../interfaces/shell'
+
+module Wralph
+  module Adapters
+    module Agents
+      module ClaudeCode
+        def self.run(instructions)
+          claude_output, = Interfaces::Shell.run_command(
+            "claude -p #{Shellwords.shellescape(instructions)} --dangerously-skip-permissions", raise_on_error: false
+          )
+          claude_output
+        end
+      end
+    end
+  end
+end

data/lib/wralph/adapters/agents.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Wralph
+  module Adapters
+    module Agents
+      require_relative 'agents/claude_code'
+    end
+  end
+end

data/lib/wralph/adapters/cis/circle_ci.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+require_relative '../../interfaces/shell'
+require_relative '../../interfaces/print'
+
+module Wralph
+  module Adapters
+    module Cis
+      module CircleCi
+        def self.http_get(url, api_token: nil)
+          uri = URI(url)
+          req = Net::HTTP::Get.new(uri)
+          req['Circle-Token'] = api_token if api_token
+          res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
+          [res.body, res.is_a?(Net::HTTPSuccess)]
+        end
+
+        # Get CircleCI build status for a PR
+        def self.build_status(pr_number, repo_owner, repo_name, api_token, verbose: true)
+          unless api_token
+            Interfaces::Print.error 'ci_api_token is not set in .wralph/secrets.yaml'
+            return nil
+          end
+
+          # Get the branch name from the PR
+          branch_name, = Interfaces::Shell.run_command("gh pr view #{pr_number} --json headRefName -q .headRefName")
+          branch_name = branch_name.strip
+          Interfaces::Print.info "Checking CircleCI build for branch: #{branch_name}" if verbose && $stderr.respond_to?(:puts)
+
+          # Get the pipeline for this branch
+          project_slug = "gh/#{repo_owner}/#{repo_name}"
+          pipeline_url = "https://circleci.com/api/v2/project/#{project_slug}/pipeline?branch=#{branch_name}"
+
+          stdout, success = http_get(pipeline_url, api_token: api_token)
+          unless success
+            Interfaces::Print.warning "No CircleCI pipeline found for branch #{branch_name}" if verbose
+            return 'not_found'
+          end
+
+          begin
+            pipeline_data = JSON.parse(stdout)
+            pipeline_item = pipeline_data['items']&.first
+            return 'not_found' unless pipeline_item
+
+            pipeline_id = pipeline_item['id']
+            pipeline_state = pipeline_item['state']
+
+            Interfaces::Print.info "Pipeline ID: #{pipeline_id}, State: #{pipeline_state}" if verbose
+
+            return 'running' if %w[running pending].include?(pipeline_state)
+
+            # Get workflow details to check if it succeeded
+            workflow_url = "https://circleci.com/api/v2/pipeline/#{pipeline_id}/workflow"
+            stdout, success = http_get(workflow_url, api_token: api_token)
+            unless success
+              Interfaces::Print.warning "No workflow found for pipeline #{pipeline_id}" if verbose
+              return 'unknown'
+            end
+
+            workflow_data = JSON.parse(stdout)
+            workflow_item = workflow_data['items']&.first
+            unless workflow_item
+              Interfaces::Print.warning "No workflow found for pipeline #{pipeline_id}" if verbose
+              return 'unknown'
+            end
+
+            workflow_status = workflow_item['status']&.strip
+            Interfaces::Print.info "Workflow status: #{workflow_status}" if verbose
+
+            workflow_status
+          rescue JSON::ParserError => e
+            Interfaces::Print.warning "Failed to parse JSON response: #{e.message}" if verbose
+            'unknown'
+          end
+        end
+
+        # Wait for CircleCI build to complete
+        def self.wait_for_build(pr_number, repo_owner, repo_name, api_token)
+          max_wait_time = 3600 # 1 hour max wait
+          wait_interval = 30   # Check every 30 seconds
+          elapsed = 0
+
+          Interfaces::Print.info 'Waiting for CircleCI build to complete...'
+
+          last_status = nil
+          while elapsed < max_wait_time
+            # Get status quietly first to check if it changed
+            status = build_status(pr_number, repo_owner, repo_name, api_token, verbose: false)
+
+            # If status hasn't changed since last check, just print a dot
+            if last_status && last_status == status
+              print '.'
+              sleep wait_interval
+              elapsed += wait_interval
+              next
+            end
+
+            # Status changed (or first check) - get verbose output with pipeline/workflow details
+            status = build_status(pr_number, repo_owner, repo_name, api_token, verbose: true)
+
+            case status
+            when 'success'
+              Interfaces::Print.success 'CircleCI build passed!'
+              return true
+            when 'failed', 'error', 'canceled', 'unauthorized'
+              Interfaces::Print.warning "CircleCI build failed with status: #{status}"
+              return false
+            when 'running', 'on_hold'
+              Interfaces::Print.info "Build still running... (elapsed: #{elapsed}s)"
+            when 'not_found'
+              Interfaces::Print.warning 'Build not found yet, waiting...'
+            else
+              Interfaces::Print.warning "Unknown build status: #{status}, waiting..."
+            end
+            sleep wait_interval
+            elapsed += wait_interval
+            last_status = status
+          end
+
+          Interfaces::Print.error 'Timeout waiting for CircleCI build to complete'
+          exit 1
+        end
+
+        # Get CircleCI build failures
+        def self.build_failures(pr_number, repo_owner, repo_name, api_token)
+          return 'ci_api_token is not set in .wralph/secrets.yaml' unless api_token
+
+          # 1. Get branch name from PR
+          branch_name, = Interfaces::Shell.run_command("gh pr view #{pr_number} --json headRefName -q .headRefName")
+          branch_name = branch_name.strip
+
+          # 2. Get the latest pipeline for that branch
+          project_slug = "gh/#{repo_owner}/#{repo_name}"
+          pipeline_url = "https://circleci.com/api/v2/project/#{project_slug}/pipeline?branch=#{branch_name}"
+          stdout, success = http_get(pipeline_url, api_token: api_token)
+          return 'Could not fetch pipeline' unless success
+
+          pipeline_id = JSON.parse(stdout)['items']&.first&.[]('id')
+          return 'No pipeline found' unless pipeline_id
+
+          # 3. Get the workflow ID
+          workflow_url = "https://circleci.com/api/v2/pipeline/#{pipeline_id}/workflow"
+          stdout, = http_get(workflow_url, api_token: api_token)
+          workflow_id = JSON.parse(stdout)['items']&.first&.[]('id')
+          return 'No workflow found' unless workflow_id
+
+          # 4. Get jobs and filter for failures
+          jobs_url = "https://circleci.com/api/v2/workflow/#{workflow_id}/job"
+          stdout, = http_get(jobs_url, api_token: api_token)
+          jobs_data = JSON.parse(stdout)
+
+          failed_jobs = jobs_data['items']&.select { |j| %w[failed error].include?(j['status']) }
+          return "All jobs passed for branch #{branch_name}." if failed_jobs.nil? || failed_jobs.empty?
+
+          # 5. For each failed job, reach into v1.1 API to get the logs
+          failed_jobs.map do |job|
+            job_num = job['job_number']
+            job_name = job['name']
+
+            # We use v1.1 because v2 does not provide step-level output URLs
+            v1_api_url = "https://circleci.com/api/v1.1/project/github/#{repo_owner}/#{repo_name}/#{job_num}"
+            v1_stdout, v1_success = http_get(v1_api_url, api_token: api_token)
+
+            log_content = "Job: #{job_name} (##{job_num}) failed."
+
+            if v1_success
+              job_details = JSON.parse(v1_stdout)
+              # Find the step that actually failed
+              failed_step = job_details['steps']&.find { |s| s['actions'].to_a.any? { |a| a['failed'] } }
+
+              if failed_step
+                action = failed_step['actions'].find { |a| a['failed'] }
+                output_url = action&.[]('output_url')
+
+                if output_url
+                  # The output_url provides a JSON array of log lines
+                  raw_log_json, = http_get(output_url)
+                  begin
+                    logs = JSON.parse(raw_log_json)
+                    # Join the last 30 lines of the log for context
+                    tail_logs = logs.map { |l| l['message'] }.last(30).join("\n")
+                    log_content += "\nFAILED STEP: #{failed_step['name']}\n\nLOG TAIL:\n#{tail_logs}"
+                  rescue StandardError
+                    log_content += "\n(Could not parse raw log output)"
+                  end
+                end
+              end
+            end
+
+            log_content
+          end.join("\n\n#{'=' * 40}\n\n")
+        end
+      end
+    end
+  end
+end

data/lib/wralph/adapters/cis.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Wralph
+  module Adapters
+    module Cis
+      require_relative 'cis/circle_ci'
+    end
+  end
+end

data/lib/wralph/adapters/objective_repositories/github_issues.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'shellwords'
+require_relative '../../interfaces/shell'
+require_relative '../../interfaces/repo'
+
+module Wralph
+  module Adapters
+    module ObjectiveRepositories
+      module GithubIssues
+        def self.download!(identifier)
+          # Ensure objectives directory exists
+          objectives_dir = File.join(Interfaces::Repo.wralph_dir, 'objectives')
+          FileUtils.mkdir_p(objectives_dir)
+
+          # Get the local file path
+          file_path = local_file_path(identifier)
+
+          # Fetch GitHub issue content
+          issue_content, stderr, success = Interfaces::Shell.run_command("gh issue view #{Shellwords.shellescape(identifier)}")
+          raise "Failed to download GitHub issue ##{identifier}: #{stderr}" unless success
+
+          # Write the issue content to the file (overwrites if exists)
+          File.write(file_path, issue_content)
+
+          file_path
+        end
+
+        def self.local_file_path(identifier)
+          objectives_dir = File.join(Interfaces::Repo.wralph_dir, 'objectives')
+          File.join(objectives_dir, "#{identifier}.md")
+        end
+      end
+    end
+  end
+end

data/lib/wralph/adapters/objective_repositories.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Wralph
+  module Adapters
+    module ObjectiveRepositories
+      require_relative 'objective_repositories/github_issues'
+    end
+  end
+end