rubyn-code 0.4.0 → 0.5.1

data/lib/rubyn_code/mcp/tool_bridge.rb

@@ -51,7 +51,7 @@ module RubynCode
           klass
         end
 
-        def create_tool_class(tool_name, description, parameters, mcp_client, remote_name) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- dynamic class creation requires setting many constants
+        def create_tool_class(tool_name, description, parameters, mcp_client, remote_name) # rubocop:disable Metrics/MethodLength -- dynamic class creation requires setting many constants
           bridge = self
 
           Class.new(Tools::Base) do

data/lib/rubyn_code/megaplan/ci_recovery.rb

@@ -0,0 +1,104 @@
+  # frozen_string_literal: true
+
+module RubynCode
+  module Megaplan
+    # Drives one CI recovery attempt on a Rubyn-opened PR.
+    #
+    # Receives the failure context the extension's CiWatcher packaged
+    # (trimmed log + phase docs + branch + attempt counts) and asks the
+    # agent to push a fix commit. Returns a `recovery_outcome` shape:
+    #
+    #   { kind: 'fixed' | 'no_fix' | 'errored', commit_sha?, summary? }
+    #
+    # 'fixed' means the agent identified and committed a fix on the
+    # branch. 'no_fix' means the agent looked but couldn't see an
+    # obvious correctness fix in the log (escalate to the human).
+    # 'errored' means the agent loop itself crashed.
+    class CiRecovery
+      class RecoveryError < RubynCode::Error; end
+
+      SYSTEM_PROMPT = <<~PROMPT.freeze
+        You are Rubyn doing CI auto-recovery on a megaplan PR.
+
+        Read the failing job log, identify the root cause, push a fix
+        commit to the existing branch. Keep the diff minimal and focused
+        — this is not a refactoring opportunity.
+
+        If you can't identify a concrete fix from the log, output exactly:
+
+          NO_FIX_IDENTIFIED: <one-sentence reason>
+
+        Do not invent fixes. Do not "try something" just to try. A clean
+        escalation to the human beats a wrong commit any day.
+      PROMPT
+
+      def initialize(agent_invoker: nil)
+        @agent_invoker = agent_invoker || method(:default_agent_invoker)
+      end
+
+      # @param context [Hash] the recovery_ci payload from the extension
+      # @return [Hash] recovery_outcome { kind, commit_sha?, summary? }
+      def recover(context)
+        validate!(context)
+        prompt = build_prompt(context)
+        result = @agent_invoker.call(prompt, context)
+        interpret(result, context)
+      rescue StandardError => e
+        { 'kind' => 'errored', 'summary' => e.message }
+      end
+
+      private
+
+      def validate!(context)
+        raise ArgumentError, 'context required' unless context.is_a?(Hash)
+
+        %w[plan_id phase_number branch pr_number trimmed_log attempt_number max_attempts].each do |key|
+          raise ArgumentError, "missing #{key}" if context[key].nil?
+        end
+      end
+
+      def build_prompt(context)
+        phase = context['phase'] || {}
+        <<~PROMPT
+          Auto-recovery attempt #{context['attempt_number']} of #{context['max_attempts']}.
+
+          **PR:** ##{context['pr_number']}
+          **Branch:** `#{context['branch']}`
+          **Failing check:** #{context['failing_check_name'] || 'unknown'}
+          **Commit SHA:** #{context['commit_sha']}
+
+          **Phase #{context['phase_number']} — #{phase['name']}**
+          #{phase['summary']}
+
+          **Trimmed log:**
+          ```
+          #{context['trimmed_log']}
+          ```
+
+          Fix the failure on the branch above. If you can't identify a fix,
+          respond with `NO_FIX_IDENTIFIED: <reason>` instead.
+        PROMPT
+      end
+
+      def interpret(result, context)
+        text = result.is_a?(Hash) ? (result[:text] || result['text'] || '') : result.to_s
+        if text =~ /\bNO_FIX_IDENTIFIED:\s*(.+)$/
+          { 'kind' => 'no_fix', 'summary' => Regexp.last_match(1).strip }
+        else
+          {
+            'kind' => 'fixed',
+            'summary' => 'Agent recovery attempt completed.',
+            'commit_sha' => context['commit_sha']
+          }
+        end
+      end
+
+      def default_agent_invoker(prompt, _context)
+        # Stub for now — real wiring happens in RecoverCiHandler which has
+        # an Agent::Loop on hand. The handler injects its own invoker via
+        # the constructor.
+        raise RecoveryError, 'No agent invoker configured.'
+      end
+    end
+  end
+end

data/lib/rubyn_code/megaplan/interview_session.rb

@@ -0,0 +1,245 @@
+  # frozen_string_literal: true
+
+require 'json'
+require 'securerandom'
+
+# Eager-load so LLM::TextBlock / LLM::ToolUseBlock constants resolve at
+# class definition time — we reference them directly in `assistant_turn_blocks`
+# before any MessageBuilder call has had a chance to trigger autoload.
+require_relative '../llm/message_builder'
+
+module RubynCode
+  module Megaplan
+    # Drives a multi-turn LLM conversation that gathers enough context to
+    # produce a megaplan. The model has a small whitelist of READ-ONLY
+    # tools (read_file, grep, glob, git_status, git_diff, git_log) so it
+    # can inspect the codebase before asking sharper questions — but it
+    # cannot edit, run shell mutations, or call any side-effecting tool.
+    #
+    # Each interview turn ends in one of two JSON shapes:
+    #
+    #   { "question": { "text": "...", "options": ["a", "b"] | null } }
+    #   { "plan": { "slug": ..., "feature": ..., "phases": [...] } }
+    #
+    # Validation of the plan payload is delegated to PlanProposer's
+    # existing rules so both /megaplan paths stay consistent.
+    class InterviewSession
+      class InvalidAnswerError < RubynCode::Error; end
+      class MalformedResponseError < RubynCode::Error; end
+
+      Question = Data.define(:id, :text, :options) do
+        def open? = options.nil? || options.empty?
+      end
+
+      # The megaplan skill lives in the gem's shared skill catalog
+      # (skills/megaplan/megaplan.md) so it's also reachable as
+      # `/skill megaplan` from the REPL and the chat. We load the file
+      # body directly (skipping the YAML frontmatter) for the system
+      # prompt.
+      SKILL_PATH = File.expand_path('../../../skills/megaplan/megaplan.md', __dir__)
+
+      def self.load_skill_body
+        raw = File.read(SKILL_PATH)
+        raw.sub(/\A---\s*\n.+?\n---\s*\n/m, '')
+      end
+
+      # Whitelist of read-only tools the interviewer may call. Picked from
+      # the existing Tools::Registry by name. Anything that writes, runs
+      # shell mutations, or spawns sub-agents is intentionally excluded.
+      INTERVIEW_TOOLS = %w[
+        read_file
+        glob
+        grep
+        git_status
+        git_diff
+        git_log
+      ].freeze
+
+      # Safety cap on the interview's per-turn tool loop. A well-behaved
+      # interviewer should read at most a handful of files before asking
+      # its next question; this stops a runaway model from stalling the
+      # session indefinitely. Per-turn, not per-session.
+      MAX_TOOL_TURNS = 10
+
+      # Strict output contract bolted on top of the megaplan skill body.
+      # The skill teaches *what* a megaplan is and *how* to interview; this
+      # contract teaches the LLM the wire format the gem expects on every
+      # turn AND that its tool palette is read-only.
+      JSON_OUTPUT_CONTRACT = <<~CONTRACT.freeze
+        # Output contract (overrides any other formatting instinct)
+
+        You are an interviewer, not a coding agent. You have a READ-ONLY
+        tool palette: `read_file`, `glob`, `grep`, `git_status`, `git_diff`,
+        `git_log`. Use them sparingly — only when looking at the code would
+        let you ask a SHARPER question (e.g. confirming a column already
+        exists before asking about it). You must NOT edit, write, run
+        shell mutations, or call any other tool. There are no other tools
+        available.
+
+        After any tool use, your next message must be a single JSON object
+        — no markdown fences, no prose before or after — in one of these
+        two shapes:
+
+          { "question": { "text": "<one focused question>", "options": ["a", "b", "c"] | null } }
+
+          { "plan": { "slug": "<kebab-case>", "feature": "<short description>",
+                      "phases": [{ "number": 1, "slug": "<kebab>", "name": "<name>",
+                                   "summary": "<one sentence>",
+                                   "requirements_md": "<markdown>",
+                                   "design_md": "<markdown>",
+                                   "tasks_md": "<markdown>" }, ...] } }
+
+        Interview rules:
+          - Ask one question at a time. Never bundle multiple.
+          - Prefer numbered options (3-5 choices) when there's an obvious option set.
+          - Use null `options` only for genuinely open questions (end-state, constraints prose).
+          - Walk the megaplan-skill agenda (goal → constraints → assets → ordering
+            → external deps → destructive ops → tests → done-per-phase). Skip
+            topics already obvious from context — including anything you've
+            confirmed via a read-only tool.
+          - Stop interviewing when you're 95% sure of the shape; emit the plan.
+
+        Plan rules:
+          - 1 to 12 phases. Each phase is a vertical slice that ships independently.
+          - Trunk works at every phase boundary.
+          - tasks_md uses `[ ]` checkboxes; requirements_md uses EARS-style SHALL
+            statements when phrasing acceptance criteria.
+
+        When you emit your final answer for a turn (a question or a plan),
+        produce ONLY the JSON object. No prefatory text. No trailing
+        commentary. Never produce free-form coding-agent output.
+      CONTRACT
+
+      DEFAULT_INTERVIEW_PROMPT = "#{load_skill_body}\n\n#{JSON_OUTPUT_CONTRACT}".freeze
+
+      attr_reader :session_id
+
+      def initialize(llm_client: nil, system_prompt: nil, workspace_path: nil, executor: nil)
+        @llm_client = llm_client || LLM::Client.new
+        @system_prompt = system_prompt || DEFAULT_INTERVIEW_PROMPT
+        @session_id = SecureRandom.uuid
+        @history = []
+        @last_question = nil
+        @workspace_path = workspace_path || Dir.pwd
+        @executor = executor || Tools::Executor.new(project_root: @workspace_path)
+      end
+
+      # Returns a Question to ask the user, or a Hash (validated plan payload)
+      # if the LLM jumped straight to the plan.
+      def start
+        ask_llm('Begin the interview. Ask your first question.')
+      end
+
+      # @param question_id [String] echoes back the question's id (anti-race)
+      # @param answer_text [String] the user's answer
+      # @return [Question, Hash] the next question OR the final plan payload
+      def answer(question_id, answer_text)
+        raise InvalidAnswerError, 'no question awaiting answer' unless @last_question
+        raise InvalidAnswerError, 'wrong question id' unless @last_question.id == question_id
+
+        @history << { role: 'user', content: answer_text.to_s }
+        ask_llm(answer_text.to_s)
+      end
+
+      private
+
+      def ask_llm(prompt)
+        @history << { role: 'user', content: prompt } if @history.empty? || @history.last[:content] != prompt
+
+        MAX_TOOL_TURNS.times do
+          response = @llm_client.chat(
+            messages: @history,
+            system: @system_prompt,
+            tools: interview_tool_definitions
+          )
+
+          tool_calls = response.respond_to?(:tool_calls) ? response.tool_calls : []
+          if tool_calls.any?
+            @history << assistant_turn_blocks(response)
+            @history << tool_results_turn(tool_calls)
+            next
+          end
+
+          text = extract_text(response)
+          @history << { role: 'assistant', content: text }
+          return parse_outcome(text)
+        end
+
+        raise MalformedResponseError,
+              "Interview tool loop exceeded #{MAX_TOOL_TURNS} turns without producing a question or plan"
+      end
+
+      def interview_tool_definitions
+        @executor.tool_definitions.select do |defn|
+          INTERVIEW_TOOLS.include?(defn[:name].to_s)
+        end
+      end
+
+      def assistant_turn_blocks(response)
+        blocks = response.content.filter_map do |block|
+          case block
+          when LLM::TextBlock
+            { type: 'text', text: block.text }
+          when LLM::ToolUseBlock
+            { type: 'tool_use', id: block.id, name: block.name, input: block.input }
+          end
+        end
+        { role: 'assistant', content: blocks }
+      end
+
+      def tool_results_turn(tool_calls)
+        content = tool_calls.map do |call|
+          result = if INTERVIEW_TOOLS.include?(call.name.to_s)
+                     @executor.execute(call.name, stringify_keys(call.input))
+                   else
+                     "Tool '#{call.name}' is not available in interview mode (read-only palette: #{INTERVIEW_TOOLS.join(', ')})."
+                   end
+          { type: 'tool_result', tool_use_id: call.id, content: result.to_s }
+        end
+        { role: 'user', content: content }
+      end
+
+      def stringify_keys(input)
+        return input unless input.is_a?(Hash)
+
+        input.each_with_object({}) { |(k, v), out| out[k.to_s] = v }
+      end
+
+      # Mirrors PlanProposer#extract_text so both /megaplan paths handle
+      # LLM::Response Data objects, Hash legacy shapes, and raw Strings.
+      def extract_text(response)
+        return response.text if response.respond_to?(:text) && !response.is_a?(String)
+        return response[:text] || response['text'] if response.is_a?(Hash)
+
+        response.to_s
+      end
+
+      def parse_outcome(text)
+        cleaned = text.to_s.strip
+                      .sub(/\A```(?:json)?\s*\n?/, '')
+                      .sub(/\n?```\s*\z/, '')
+        payload = JSON.parse(cleaned)
+        if payload.is_a?(Hash) && payload['question']
+          q = build_question(payload['question'])
+          @last_question = q
+          q
+        elsif payload.is_a?(Hash) && payload['plan']
+          plan = payload['plan']
+          PlanProposer.new.validate!(plan)
+          @last_question = nil
+          plan
+        else
+          raise MalformedResponseError, 'LLM response is neither a question nor a plan'
+        end
+      rescue JSON::ParserError => e
+        raise MalformedResponseError, "LLM response is not valid JSON: #{e.message}"
+      end
+
+      def build_question(payload)
+        options = payload['options']
+        options = nil if options.is_a?(Array) && options.empty?
+        Question.new(id: SecureRandom.uuid, text: payload['text'].to_s, options: options)
+      end
+    end
+  end
+end

data/lib/rubyn_code/megaplan/plan_proposer.rb

@@ -0,0 +1,153 @@
+  # frozen_string_literal: true
+
+require 'json'
+require 'securerandom'
+
+module RubynCode
+  module Megaplan
+    # Proposes a multi-phase megaplan for a feature description.
+    #
+    # Asks the LLM to produce a JSON payload that matches the extension's
+    # `plan_proposal` shape — one folder per phase, three documents per
+    # phase, vertical-slice ordering. The handler validates the response
+    # and returns it to the IDE.
+    #
+    # The LLM call is the slow part (~5-30s); callers should run this
+    # off the main JSON-RPC thread.
+    class PlanProposer
+      class InvalidProposalError < RubynCode::Error; end
+
+      MAX_PHASES = 12
+      DEFAULT_SYSTEM_PROMPT = <<~PROMPT.freeze
+        You are a senior Ruby/Rails architect breaking a feature request into a megaplan.
+
+        A megaplan is a multi-phase development plan where each phase is a
+        VERTICAL SLICE that can ship independently. Trunk works at every phase
+        boundary. No "scaffolding first, behavior later" — every phase delivers
+        a thin, end-to-end working increment.
+
+        Output a single JSON object with this exact shape:
+
+        {
+          "slug": "kebab-case-feature-slug",
+          "feature": "Short feature description",
+          "phases": [
+            {
+              "number": 1,
+              "slug": "kebab-case-phase-slug",
+              "name": "Human-readable phase name",
+              "summary": "One-sentence summary of what this phase ships",
+              "requirements_md": "# Phase 1 — <name>: Requirements\\n\\n...",
+              "design_md":       "# Phase 1 — <name>: Design\\n\\n...",
+              "tasks_md":        "# Phase 1 — <name>: Tasks\\n\\n## [ ] 1. ...\\n\\n- [ ] 1.1 ..."
+            }
+          ]
+        }
+
+        Constraints:
+          - 1 to 12 phases. Smaller, sharper phases beat fewer mega-phases.
+          - Each phase must be a vertical slice.
+          - tasks_md is a checklist with `[ ]` boxes (megaplan convention).
+          - Every phase needs requirements_md, design_md, tasks_md.
+          - Return ONLY the JSON. No markdown fences. No commentary.
+      PROMPT
+
+      def initialize(llm_client: nil, system_prompt: nil, max_phases: MAX_PHASES)
+        @llm_client = llm_client || LLM::Client.new
+        @system_prompt = system_prompt || DEFAULT_SYSTEM_PROMPT
+        @max_phases = max_phases
+      end
+
+      # @param feature [String] the user's feature description
+      # @return [Hash] payload with `slug`, `feature`, `phases`
+      # @raise [InvalidProposalError] if the LLM response can't be parsed
+      def propose(feature)
+        raise ArgumentError, 'feature is required' if feature.nil? || feature.strip.empty?
+
+        response = @llm_client.chat(
+          messages: [{ role: 'user', content: feature_prompt(feature) }],
+          system: @system_prompt
+        )
+
+        text = extract_text(response)
+        payload = parse_payload(text)
+        validate!(payload, feature)
+        normalize(payload, feature)
+      end
+
+      # Validate a parsed plan_proposal Hash. Public so the interview path
+      # (which produces the same shape via a different LLM workflow) can
+      # reuse the rule set without reaching into a private method.
+      def validate!(payload, _feature = nil)
+        raise InvalidProposalError, 'payload is not an object' unless payload.is_a?(Hash)
+
+        phases = payload['phases']
+        raise InvalidProposalError, 'phases must be an array' unless phases.is_a?(Array)
+        raise InvalidProposalError, 'phases is empty' if phases.empty?
+        raise InvalidProposalError, "too many phases (max #{@max_phases})" if phases.size > @max_phases
+
+        phases.each_with_index do |phase, idx|
+          %w[name summary requirements_md design_md tasks_md].each do |key|
+            next unless phase[key].nil? || phase[key].to_s.strip.empty?
+
+            raise InvalidProposalError, "phase #{idx + 1} missing #{key}"
+          end
+        end
+      end
+
+      private
+
+      # LLM::Client#chat returns a `LLM::Response` Data object whose `.text`
+      # joins all text blocks. Tests and older callers may pass a String or
+      # a Hash — handle all three so the proposer doesn't crash with
+      # `#<data ...>` ending up as parser input.
+      def extract_text(response)
+        return response.text if response.respond_to?(:text) && !response.is_a?(String)
+        return response[:text] || response['text'] if response.is_a?(Hash)
+
+        response.to_s
+      end
+
+      def feature_prompt(feature)
+        "Plan this feature as a megaplan:\n\n#{feature.strip}"
+      end
+
+      def parse_payload(text)
+        # The LLM can leak fences despite the prompt — strip a leading/trailing
+        # ``` block if present.
+        cleaned = text.to_s.strip
+        cleaned = cleaned.sub(/\A```(?:json)?\s*\n?/, '').sub(/\n?```\s*\z/, '')
+        JSON.parse(cleaned)
+      rescue JSON::ParserError => e
+        raise InvalidProposalError, "LLM response is not valid JSON: #{e.message}"
+      end
+
+      def normalize(payload, feature)
+        slug = payload['slug'].to_s.strip
+        slug = slugify(feature) if slug.empty?
+        phases = payload['phases'].each_with_index.map do |phase, idx|
+          {
+            'number' => phase['number'] || idx + 1,
+            'slug' => (phase['slug'].to_s.strip.empty? ? slugify(phase['name']) : phase['slug']),
+            'name' => phase['name'],
+            'summary' => phase['summary'],
+            'requirements_md' => phase['requirements_md'],
+            'design_md' => phase['design_md'],
+            'tasks_md' => phase['tasks_md']
+          }
+        end
+        {
+          'slug' => slug,
+          'feature' => payload['feature'] || feature,
+          'phases' => phases
+        }
+      end
+
+      def slugify(text)
+        cleaned = text.to_s.downcase.gsub(/[^a-z0-9]+/, '-').gsub(/^-+|-+$/, '')
+        cleaned = cleaned[0, 80]
+        cleaned.empty? ? 'feature' : cleaned
+      end
+    end
+  end
+end

data/lib/rubyn_code/observability/usage_reporter.rb

@@ -80,7 +80,8 @@ module RubynCode
         }
       end
 
-      def build_session_summary_lines(session_id, turns, totals) # rubocop:disable Metrics/AbcSize -- assembles multi-field summary
+      # -- assembles multi-field summary
+      def build_session_summary_lines(session_id, turns, totals)
         avg_cost = turns.positive? ? totals[:cost] / turns : 0.0
         [
           header('Session Summary'),
@@ -104,7 +105,8 @@ module RubynCode
         ).to_a
       end
 
-      def build_daily_summary_lines(today, rows) # rubocop:disable Metrics/AbcSize -- assembles multi-field daily summary
+      # -- assembles multi-field daily summary
+      def build_daily_summary_lines(today, rows)
         total_input  = rows.sum { |r| fetch_int(r, 'input_tokens') }
         total_output = rows.sum { |r| fetch_int(r, 'output_tokens') }
         total_cost   = rows.sum { |r| fetch_float(r, 'cost_usd') }

data/lib/rubyn_code/output/diff_renderer.rb

@@ -97,7 +97,8 @@ module RubynCode
         table
       end
 
-      def fill_lcs_row(table, row, old_lines, new_lines, col_count) # rubocop:disable Metrics/AbcSize -- LCS algorithm step
+      # -- LCS algorithm step
+      def fill_lcs_row(table, row, old_lines, new_lines, col_count)
         (1..col_count).each do |col|
           table[row][col] = if old_lines[row - 1] == new_lines[col - 1]
                               table[row - 1][col - 1] + 1
@@ -121,7 +122,7 @@ module RubynCode
         result
       end
 
-      def backtrack_step(result, table, old_lines, new_lines, old_idx, new_idx) # rubocop:disable Metrics/AbcSize, Metrics/ParameterLists -- LCS backtrack step requires all state
+      def backtrack_step(result, table, old_lines, new_lines, old_idx, new_idx) # rubocop:disable Metrics/ParameterLists -- LCS backtrack step requires all state
         if lines_match?(old_lines, new_lines, old_idx, new_idx)
           result.unshift([:equal, old_idx - 1, new_idx - 1])
           [old_idx - 1, new_idx - 1]

data/lib/rubyn_code/self_test.rb

@@ -53,7 +53,8 @@ module RubynCode
       record('File read (version.rb)', content.include?('VERSION ='))
     end
 
-    def check_file_write_edit_cleanup # rubocop:disable Metrics/AbcSize -- sequential file ops
+    # -- sequential file ops
+    def check_file_write_edit_cleanup
       tmp = File.join(project_root, '.rubyn-code/self_test_tmp.rb')
       FileUtils.mkdir_p(File.dirname(tmp))