ralph.rb 1.2.435535439

data/lib/ralph/output/status.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Output
+    class Status
+      include ::Ralph::Helpers
+
+      def self.call(options:)
+        new(options).call
+      end
+
+      def initialize(options)
+        @options = options
+      end
+
+      def call
+        state = Storage::State.load
+        history = Storage::History.load_history
+        context = Storage::Context.new
+        show_tasks = @options[:tasks_mode] || state&.tasks_mode
+
+        print_header
+        print_loop_status(state)
+        print_pending_context(context)
+        print_tasks if show_tasks
+        print_history(history)
+        print_footer
+      end
+
+      private
+
+        def print_header
+          puts <<~HEADER
+
+            ╔#{"=" * 66}╗
+            ║                    Ralph Wiggum Status                           ║
+            ╚#{"=" * 66}╝
+          HEADER
+        end
+
+        def print_loop_status(state)
+          if state&.active
+            print_active_loop(state)
+          else
+            puts "⏹️  No active loop"
+          end
+        end
+
+        def print_active_loop(state)
+          elapsed = now_ms - (Time.parse(state.started_at).to_f * 1000).to_i
+          elapsed_str = format_duration_long(elapsed)
+          puts "🔄 ACTIVE LOOP"
+          max_str = state.max_iterations > 0 ? " / #{state.max_iterations}" : " (unlimited)"
+          puts "   Iteration:    #{state.iteration}#{max_str}"
+          puts "   Started:      #{state.started_at}"
+          puts "   Elapsed:      #{elapsed_str}"
+          puts "   Promise:      #{state.completion_promise}"
+          agent_label =
+            if state.agent
+              cfg = Agents.resolve(state.agent)
+              cfg ? cfg.config_name : state.agent
+            else
+              "OpenCode"
+            end
+          puts "   Agent:        #{agent_label}"
+          puts "   Model:        #{state.model}" if state.model && !state.model.empty?
+          if state.tasks_mode
+            puts "   Tasks Mode:   ENABLED"
+            puts "   Task Promise: #{state.task_promise}"
+          end
+          prompt_preview = state.prompt[0, 60] + (state.prompt.length > 60 ? "..." : "")
+          puts "   Prompt:       #{prompt_preview}"
+        end
+
+        def print_pending_context(context)
+          return unless context.present?
+
+          puts "\n📝 PENDING CONTEXT (will be injected next iteration):"
+          puts "   #{context.content.split("\n").join("\n   ")}"
+        end
+
+        def print_tasks
+          tasks_storage = Storage::Tasks.new
+          if File.exist?(tasks_storage.path)
+            begin
+              tasks_content = File.read(tasks_storage.path)
+              tasks = Tasks.parse(tasks_content)
+              print_current_tasks(tasks)
+            rescue StandardError
+              puts "\n📋 CURRENT TASKS: (error reading tasks)"
+            end
+          else
+            puts "\n📋 CURRENT TASKS: (no tasks file found)"
+          end
+        end
+
+        def print_current_tasks(tasks)
+          if tasks.any?
+            puts "\n📋 CURRENT TASKS:"
+            tasks.each_with_index do |task, i|
+              icon = tasks.status_icon(task.status)
+              puts "   #{i + 1}. #{icon} #{task.text}"
+              task.subtasks.each do |subtask|
+                sub_icon = tasks.status_icon(subtask.status)
+                puts "      #{sub_icon} #{subtask.text}"
+              end
+            end
+            complete = tasks.count { |t| t.status == :complete }
+            in_progress = tasks.count { |t| t.status == :in_progress }
+            puts "\n   Progress: #{complete}/#{tasks.length} complete, #{in_progress} in progress"
+          else
+            puts "\n📋 CURRENT TASKS: (no tasks found)"
+          end
+        end
+
+        def print_history(history)
+          iterations = history["iterations"] || []
+          return unless iterations.any?
+
+          puts "\n📊 HISTORY (#{iterations.length} iterations)"
+          puts "   Total time:   #{format_duration_long(history["total_duration_ms"] || 0)}"
+
+          recent = iterations.last(5)
+          print_recent_iterations(recent)
+
+          si = history["struggle_indicators"] || {}
+          has_repeated = (si["repeated_errors"] || {}).values.any? { |c| c >= 2 }
+          if (si["no_progress_iterations"] || 0) >= 3 || (si["short_iterations"] || 0) >= 3 || has_repeated
+            print_struggle_warnings(si)
+          end
+        end
+
+        def print_recent_iterations(iterations)
+          puts "\n   Recent iterations:"
+          iterations.each do |iter|
+            tools = (iter["tools_used"] || {})
+                      .sort_by { |_, v| -v }
+                      .first(3)
+                      .map { |k, v| "#{k}:#{v}" }
+                      .join(" ")
+            status_icon =
+              if iter["completion_detected"]
+                "✅"
+              elsif iter["exit_code"] != 0
+                "❌"
+              else
+                "🔄"
+              end
+            puts "   #{status_icon} ##{iter["iteration"]}: #{format_duration_long(iter["duration_ms"])} | #{tools.empty? ? "no tools" : tools}"
+          end
+        end
+
+        def print_struggle_warnings(si)
+          puts "\n⚠️  STRUGGLE INDICATORS:"
+          if (si["no_progress_iterations"] || 0) >= 3
+            puts "   - No file changes in #{si["no_progress_iterations"]} iterations"
+          end
+          if (si["short_iterations"] || 0) >= 3
+            puts "   - #{si["short_iterations"]} very short iterations (< 30s)"
+          end
+          top_errors = (si["repeated_errors"] || {})
+                         .select { |_, count| count >= 2 }
+                         .sort_by { |_, count| -count }
+                         .first(3)
+          top_errors.each do |error, count|
+            puts "   - Same error #{count}x: \"#{error[0, 50]}...\""
+          end
+          puts "\n   💡 Consider using: ralph --add-context \"your hint here\""
+        end
+
+        def print_footer
+          puts ""
+        end
+    end
+  end
+end

data/lib/ralph/output/struggle_warning.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Output
+    class StruggleWarning
+      def self.call(loop_context)
+        puts "\n⚠️  Potential struggle detected:"
+        if loop_context.struggle_indicators[:no_progress_iterations] >= 3
+          puts "   - No file changes in #{loop_context.struggle_indicators[:no_progress_iterations]} iterations"
+        end
+        if loop_context.struggle_indicators[:short_iterations] >= 3
+          puts "   - #{loop_context.struggle_indicators[:short_iterations]} very short iterations"
+        end
+        puts "   💡 Tip: Use 'ralph --add-context \"hint\"' in another terminal to guide the agent"
+      end
+    end
+  end
+end

data/lib/ralph/output/task_completion.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Output
+    class TaskCompletion
+      def self.call(loop_context)
+        puts "\n🔄 Task completion detected: <promise>#{loop_context.config.task_promise}</promise>"
+        puts "   Moving to next task in iteration #{loop_context.state.iteration + 1}..."
+      end
+    end
+  end
+end

data/lib/ralph/output/tasks_file_created.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Output
+    class TasksFileCreated
+      def self.call(path:)
+        puts "📋 Created tasks file: #{path}"
+      end
+    end
+  end
+end

data/lib/ralph/prompt_template.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Ralph
+  class PromptTemplate
+    class Error < StandardError; end
+
+    attr_reader :user_prompt, :context, :tasks
+
+    def initialize(user_prompt, context: nil, tasks: nil)
+      @user_prompt = user_prompt
+      @context = context
+      @tasks = tasks
+    end
+
+    def to_s = @user_prompt
+    def empty? = @user_prompt.strip.empty?
+
+    def context_section
+      @_context_section ||=
+        if @context.present?
+          "
+            ## Additional Context (added by user mid-loop)
+
+            #{@context.content}
+
+            ---
+          "
+        else
+          ""
+        end
+    end
+
+    def task_mode_prompt(state)
+      tasks_section = build_tasks_section(state)
+      <<~PROMPT.strip
+        # Ralph Wiggum Loop - Iteration #{state.iteration}
+
+        You are in an iterative development loop working through a task list.
+        #{context_section}#{tasks_section}
+        ## Your Main Goal
+
+        #{@user_prompt}
+
+        ## Critical Rules
+
+        - Work on ONE task at a time from .ralph/ralph-tasks.md
+        - ONLY output <promise>#{state.task_promise}</promise> when the current task is complete and marked in ralph-tasks.md
+        - ONLY output <promise>#{state.completion_promise}</promise> when ALL tasks are truly done
+        - Do NOT lie or output false promises to exit the loop
+        - If stuck, try a different approach
+        - Check your work before claiming completion
+
+        ## Current Iteration: #{state.iteration}#{state.max_iterations > 0 ? " / #{state.max_iterations}" : " (unlimited)"} (min: #{state.min_iterations || 1})
+
+        Tasks Mode: ENABLED - Work on one task at a time from ralph-tasks.md
+
+        Now, work on the current task. Good luck!
+      PROMPT
+    end
+
+    def non_task_mode_prompt(state)
+      <<~PROMPT.strip
+        # Ralph Wiggum Loop - Iteration #{state.iteration}
+
+        You are in an iterative development loop. Work on the task below until you can genuinely complete it.
+        #{context_section}
+        ## Your Task
+
+        #{@user_prompt}
+
+        ## Instructions
+
+        1. Read the current state of files to understand what's been done
+        2. Track your progress and plan remaining work
+        3. Make progress on the task
+        4. Run tests/verification if applicable
+        5. When the task is GENUINELY COMPLETE, output:
+           <promise>#{state.completion_promise}</promise>
+
+        ## Critical Rules
+
+        - ONLY output <promise>#{state.completion_promise}</promise> when the task is truly done
+        - Do NOT lie or output false promises to exit the loop
+        - If stuck, try a different approach
+        - Check your work before claiming completion
+        - The loop will continue until you succeed
+
+        ## Current Iteration: #{state.iteration}#{state.max_iterations > 0 ? " / #{state.max_iterations}" : " (unlimited)"} (min: #{state.min_iterations || 1})
+
+        Now, work on the task. Good luck!
+      PROMPT
+    end
+
+    # Build the full iteration prompt sent to the LLM.
+    # +state+ is a Storage::State with iteration metadata.
+    # +_agent+ is the agent config (reserved for future use).
+    def build_iteration(state, _agent)
+      if state.tasks_mode
+        task_mode_prompt(state)
+      else
+        non_task_mode_prompt(state)
+      end
+    end
+
+    private
+
+      def build_tasks_section(state)
+        tasks_path = @tasks.path
+        unless File.exist?(tasks_path)
+          return <<~SECTION
+
+            ## TASKS MODE: Enabled (no tasks file found)
+
+            Create .ralph/ralph-tasks.md with your task list, or use `ralph --add-task "description"` to add tasks.
+          SECTION
+        end
+
+        begin
+           tasks_content = File.read(tasks_path)
+           tasks = Tasks.parse(tasks_content)
+           current_task = tasks.current
+           next_task = tasks.next
+
+           task_instructions =
+             if current_task
+               <<~INST
+                🔄 CURRENT TASK: "#{current_task.text}"
+                   Focus on completing this specific task.
+                   When done: Mark as [x] in .ralph/ralph-tasks.md and output <promise>#{state.task_promise}</promise>
+              INST
+             elsif next_task
+               <<~INST
+                📍 NEXT TASK: "#{next_task.text}"
+                   Mark as [/] in .ralph/ralph-tasks.md before starting.
+                   When done: Mark as [x] and output <promise>#{state.task_promise}</promise>
+              INST
+             elsif tasks.all_complete?
+               <<~INST
+                ✅ ALL TASKS COMPLETE!
+                   Output <promise>#{state.completion_promise}</promise> to finish.
+              INST
+             else
+               <<~INST
+                📋 No tasks found. Add tasks to .ralph/ralph-tasks.md or use `ralph --add-task`
+              INST
+             end
+
+           <<~SECTION
+
+            ## TASKS MODE: Working through task list
+
+            Current tasks from .ralph/ralph-tasks.md:
+            ```markdown
+            #{tasks_content.strip}
+            ```
+            #{task_instructions}
+            ### Task Workflow
+            1. Find any task marked [/] (in progress). If none, pick the first [ ] task.
+            2. Mark the task as [/] in ralph-tasks.md before starting.
+            3. Complete the task.
+            4. Mark as [x] when verified complete.
+            5. Output <promise>#{state.task_promise}</promise> to move to the next task.
+            6. Only output <promise>#{state.completion_promise}</promise> when ALL tasks are [x].
+
+            ---
+          SECTION
+         rescue StandardError
+           <<~SECTION
+
+            ## TASKS MODE: Error reading tasks file
+
+            Unable to read .ralph/ralph-tasks.md
+          SECTION
+        end
+      end
+
+      class << self
+        def inject(user_prompt, context:, tasks:)
+          new(user_prompt, context: context, tasks: tasks)
+        end
+      end
+  end
+end

data/lib/ralph/storage/context.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Ralph
+  module Storage
+    # Represents the persistent AI context file for conversational continuity.
+    #
+    # Always instantiate with Context.new — it represents the file on disk.
+    # Content is read lazily; the file is created on first write/append.
+    class Context
+      attr_reader :path
+
+      def initialize
+        FileUtils.mkdir_p(dir)
+      end
+
+      def self.dir
+        @dir ||= File.join(Dir.pwd, ".ralph")
+      end
+
+      def dir = self.class.dir
+
+      def path
+        @path ||= File.join(dir, "ralph-context.md")
+      end
+
+      def content
+        if File.exist?(path)
+          text = File.read(path).strip
+          text.empty? ? nil : text
+        end
+      rescue StandardError
+        nil
+      end
+
+      def present? = !content.nil?
+
+      def append(text)
+        if File.exist?(path)
+          write(File.read(path) + text)
+        else
+          write("# Ralph Loop Context\n#{text}")
+        end
+      end
+
+      def write(text)
+        File.write(path, text)
+      end
+
+      def clear
+        if File.exist?(path)
+          File.delete(path) 
+        end
+      end
+    end
+  end
+end

data/lib/ralph/storage/history.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Ralph
+  module Storage
+    # Manages iteration history and performance tracking.
+    #
+    # Stores everything as plain hashes. No structs, no ceremony.
+    # Each iteration is a hash appended to an array, persisted as JSON.
+    class History
+      include ::Ralph::Helpers
+
+      EMPTY_HISTORY = {
+        "iterations" => [],
+        "total_duration_ms" => 0,
+        "struggle_indicators" => {
+          "repeated_errors" => {},
+          "no_progress_iterations" => 0,
+          "short_iterations" => 0
+        }
+      }.freeze
+
+      attr_reader :history
+
+      def initialize
+        @history = self.class.empty_history
+        self.class.save_history(@history)
+      end
+
+      # Record a completed iteration.
+      def record(state_iteration:, iteration_start:, result:, struggle_indicators:)
+        entry = {
+          "iteration" => state_iteration,
+          "started_at" => Time.at(iteration_start / 1000.0).utc.iso8601,
+          "ended_at" => Time.now.utc.iso8601,
+          "duration_ms" => result.duration_ms,
+          "tools_used" => result.tool_counts,
+          "files_modified" => result.files_modified,
+          "exit_code" => result.exit_code,
+          "completion_detected" => result.completion_detected,
+          "errors" => result.errors
+        }
+
+        append(entry, result.duration_ms, struggle_indicators)
+      end
+
+      # Record an iteration that raised an exception before producing a result.
+      def record_error(state_iteration:, iteration_start:, error:)
+        iteration_duration = now_ms - iteration_start
+
+        entry = {
+          "iteration" => state_iteration,
+          "started_at" => Time.at(iteration_start / 1000.0).utc.iso8601,
+          "ended_at" => Time.now.utc.iso8601,
+          "duration_ms" => iteration_duration,
+          "tools_used" => {},
+          "files_modified" => [],
+          "exit_code" => -1,
+          "completion_detected" => false,
+          "errors" => [error.to_s[0, 200]]
+        }
+
+        append(entry, iteration_duration, nil)
+      end
+
+      def total_duration_ms
+        @history["total_duration_ms"]
+      end
+
+      # --- Class API (raw persistence) ---
+
+      class << self
+        def state_dir
+          File.join(Dir.pwd, ".ralph")
+        end
+
+        def history_path
+          File.join(state_dir, "ralph-history.json")
+        end
+
+        def empty_history
+          JSON.parse(JSON.generate(EMPTY_HISTORY))
+        end
+
+        def save_history(history)
+          FileUtils.mkdir_p(state_dir)
+          File.write(history_path, JSON.pretty_generate(history))
+        end
+
+        def load_history
+          return empty_history unless File.exist?(history_path)
+
+          JSON.parse(File.read(history_path))
+        rescue StandardError
+          empty_history
+        end
+
+        def clear_history
+          File.delete(history_path) if File.exist?(history_path)
+        rescue StandardError
+          # ignore
+        end
+      end
+
+      private
+
+      def append(entry, duration_ms, struggle_indicators)
+        @history["iterations"] << entry
+        @history["total_duration_ms"] += duration_ms
+        @history["struggle_indicators"] = struggle_indicators if struggle_indicators
+        self.class.save_history(@history)
+      end
+    end
+  end
+end