woods 1.0.0

data/lib/woods/console/adapters/job_adapter.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Woods
+  module Console
+    module Adapters
+      # Base class for job backend adapters.
+      #
+      # Subclasses implement `self.available?` and a private `prefix` method.
+      # The prefix is used to build bridge tool names (e.g., "sidekiq_queue_stats").
+      #
+      # @example
+      #   class MyAdapter < JobAdapter
+      #     def self.available? = !!defined?(::MyQueue)
+      #     private
+      #     def prefix = 'my_queue'
+      #   end
+      #
+      class JobAdapter
+        # Get queue statistics (sizes, latencies).
+        #
+        # @return [Hash] Bridge request
+        def queue_stats
+          { tool: "#{prefix}_queue_stats", params: {} }
+        end
+
+        # List recent job failures.
+        #
+        # @param limit [Integer] Max failures (default: 10, max: 100)
+        # @return [Hash] Bridge request
+        def recent_failures(limit: 10)
+          limit = [limit, 100].min
+          { tool: "#{prefix}_recent_failures", params: { limit: limit } }
+        end
+
+        # Find a job by its ID.
+        #
+        # @param id [Object] Job ID
+        # @return [Hash] Bridge request
+        def find_job(id:)
+          { tool: "#{prefix}_find_job", params: { id: id } }
+        end
+
+        # List scheduled jobs.
+        #
+        # @param limit [Integer] Max jobs (default: 20, max: 100)
+        # @return [Hash] Bridge request
+        def scheduled_jobs(limit: 20)
+          limit = [limit, 100].min
+          { tool: "#{prefix}_scheduled_jobs", params: { limit: limit } }
+        end
+
+        # Retry a failed job.
+        #
+        # @param id [Object] Job ID
+        # @return [Hash] Bridge request
+        def retry_job(id:)
+          { tool: "#{prefix}_retry_job", params: { id: id } }
+        end
+
+        private
+
+        def prefix
+          raise NotImplementedError, "#{self.class}#prefix must be implemented"
+        end
+      end
+    end
+  end
+end

data/lib/woods/console/adapters/sidekiq_adapter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'job_adapter'
+
+module Woods
+  module Console
+    module Adapters
+      # Job backend adapter for Sidekiq.
+      #
+      # Builds bridge requests for Sidekiq queue stats, failure listing,
+      # job lookup, scheduled jobs, and retry operations.
+      #
+      # @example
+      #   adapter = SidekiqAdapter.new
+      #   adapter.queue_stats  # => { tool: 'sidekiq_queue_stats', params: {} }
+      #
+      class SidekiqAdapter < JobAdapter
+        # Check if Sidekiq is available in the current environment.
+        #
+        # @return [Boolean]
+        def self.available?
+          !!defined?(::Sidekiq)
+        end
+
+        private
+
+        def prefix
+          'sidekiq'
+        end
+      end
+    end
+  end
+end

data/lib/woods/console/adapters/solid_queue_adapter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'job_adapter'
+
+module Woods
+  module Console
+    module Adapters
+      # Job backend adapter for Solid Queue.
+      #
+      # Builds bridge requests for Solid Queue job stats, failure listing,
+      # job lookup, scheduled jobs, and retry operations.
+      #
+      # @example
+      #   adapter = SolidQueueAdapter.new
+      #   adapter.queue_stats  # => { tool: 'solid_queue_queue_stats', params: {} }
+      #
+      class SolidQueueAdapter < JobAdapter
+        # Check if Solid Queue is available in the current environment.
+        #
+        # @return [Boolean]
+        def self.available?
+          !!defined?(::SolidQueue)
+        end
+
+        private
+
+        def prefix
+          'solid_queue'
+        end
+      end
+    end
+  end
+end

data/lib/woods/console/audit_logger.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+
+module Woods
+  module Console
+    # Logs all Tier 4 tool invocations to a JSONL file.
+    #
+    # Each line is a JSON object with: tool name, params, timestamp,
+    # confirmation status, and result summary.
+    #
+    # @example
+    #   logger = AuditLogger.new(path: 'log/console_audit.jsonl')
+    #   logger.log(tool: 'console_eval', params: { code: '1+1' },
+    #              confirmed: true, result_summary: '2')
+    #   logger.entries # => [{ "tool" => "console_eval", ... }]
+    #
+    class AuditLogger
+      # @param path [String] Path to the JSONL audit log file
+      def initialize(path:)
+        @path = path
+      end
+
+      # Write an audit entry.
+      #
+      # @param tool [String] Tool name
+      # @param params [Hash] Tool parameters
+      # @param confirmed [Boolean] Whether confirmation was granted
+      # @param result_summary [String] Brief result description
+      # @return [void]
+      def log(tool:, params:, confirmed:, result_summary:)
+        ensure_directory!
+
+        entry = {
+          tool: tool,
+          params: params,
+          confirmed: confirmed,
+          result_summary: result_summary,
+          timestamp: Time.now.utc.iso8601
+        }
+
+        File.open(@path, 'a') { |f| f.puts(JSON.generate(entry)) }
+      end
+
+      # Read all audit entries.
+      #
+      # @return [Array<Hash>] Parsed JSONL entries
+      def entries
+        return [] unless File.exist?(@path)
+
+        File.readlines(@path).filter_map do |line|
+          JSON.parse(line.strip) unless line.strip.empty?
+        end
+      end
+
+      # Number of audit entries.
+      #
+      # @return [Integer]
+      def size
+        entries.size
+      end
+
+      private
+
+      # Ensure the parent directory of the log file exists.
+      #
+      # @return [void]
+      def ensure_directory!
+        dir = File.dirname(@path)
+        FileUtils.mkdir_p(dir)
+      end
+    end
+  end
+end

data/lib/woods/console/bridge.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'model_validator'
+require_relative 'safe_context'
+
+module Woods
+  module Console
+    # JSON-lines protocol bridge between MCP server and Rails environment.
+    #
+    # Reads JSON-lines requests from an input IO, validates model/column names,
+    # dispatches to tool handlers, and writes JSON-lines responses to an output IO.
+    #
+    # Protocol:
+    #   Request:  {"id":"req_1","tool":"count","params":{"model":"Order","scope":{"status":"pending"}}}
+    #   Response: {"id":"req_1","ok":true,"result":{"count":1847},"timing_ms":12.3}
+    #   Error:    {"id":"req_1","ok":false,"error":"Model not found","error_type":"validation"}
+    #
+    # @example
+    #   bridge = Bridge.new(input: $stdin, output: $stdout,
+    #                       model_validator: validator, safe_context: ctx)
+    #   bridge.run
+    #
+    class Bridge
+      SUPPORTED_TOOLS = %w[count sample find pluck aggregate association_count schema recent status].freeze
+      # Alias used by EmbeddedExecutor to avoid duplicating the list.
+      TIER1_TOOLS = SUPPORTED_TOOLS
+      TOOL_HANDLERS = SUPPORTED_TOOLS.to_h { |t| [t, :"handle_#{t}"] }.freeze
+
+      # @param input [IO] Input stream (reads JSON-lines)
+      # @param output [IO] Output stream (writes JSON-lines)
+      # @param model_validator [ModelValidator] Validates model/column names
+      # @param safe_context [SafeContext] Wraps execution in safe transaction
+      def initialize(input:, output:, model_validator:, safe_context:)
+        @input = input
+        @output = output
+        @model_validator = model_validator
+        @safe_context = safe_context
+      end
+
+      # Read loop — processes requests until input is closed.
+      #
+      # @return [void]
+      def run
+        @input.each_line do |line|
+          line = line.strip
+          next if line.empty?
+
+          request = parse_request(line)
+          next unless request
+
+          response = handle_request(request)
+          write_response(response)
+        end
+      end
+
+      # Process a single request hash and return a response hash.
+      #
+      # @param request [Hash] Parsed request with "id", "tool", "params"
+      # @return [Hash] Response with "id", "ok", and "result" or "error"
+      def handle_request(request)
+        id = request['id']
+        tool = request['tool']
+        params = request['params'] || {}
+
+        return error_response(id, "Unknown tool: #{tool}", 'unknown_tool') unless SUPPORTED_TOOLS.include?(tool)
+
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = dispatch(tool, params)
+        elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(1)
+
+        { 'id' => id, 'ok' => true, 'result' => result, 'timing_ms' => elapsed }
+      rescue ValidationError => e
+        error_response(id, e.message, 'validation')
+      rescue StandardError => e
+        error_response(id, e.message, 'execution')
+      end
+
+      private
+
+      # Parse a JSON line into a request hash.
+      #
+      # @param line [String] Raw JSON line
+      # @return [Hash, nil] Parsed request or nil on parse error
+      def parse_request(line)
+        JSON.parse(line)
+      rescue JSON::ParserError => e
+        write_response(error_response(nil, "Invalid JSON: #{e.message}", 'parse'))
+        nil
+      end
+
+      # Dispatch a tool request to the appropriate handler.
+      #
+      # @param tool [String] Tool name
+      # @param params [Hash] Tool parameters
+      # @return [Hash] Tool result
+      def dispatch(tool, params)
+        case tool
+        when 'status'
+          handle_status
+        when 'schema'
+          handle_schema(params)
+        else
+          validate_model_param(params)
+          handler = TOOL_HANDLERS.fetch(tool) { raise ValidationError, "Unknown tool: #{tool}" }
+          send(handler, params)
+        end
+      end
+
+      # Validate that the model parameter is present and known.
+      def validate_model_param(params)
+        model = params['model']
+        raise ValidationError, 'Missing required parameter: model' unless model
+
+        @model_validator.validate_model!(model)
+      end
+
+      # Stub handlers below return empty/zero data by design.
+      # This Bridge class is a protocol scaffold — real execution happens
+      # in EmbeddedExecutor (in-process) or a live Rails bridge process.
+      # The stubs satisfy the protocol contract for testing and offline use.
+
+      def handle_count(_params)
+        { 'count' => 0 }
+      end
+
+      def handle_sample(_params)
+        { 'records' => [] }
+      end
+
+      def handle_find(_params)
+        { 'record' => nil }
+      end
+
+      def handle_pluck(params)
+        @model_validator.validate_columns!(params['model'], params['columns']) if params['columns']
+        { 'values' => [] }
+      end
+
+      def handle_aggregate(params)
+        @model_validator.validate_column!(params['model'], params['column']) if params['column']
+        { 'value' => nil }
+      end
+
+      def handle_association_count(_params)
+        { 'count' => 0 }
+      end
+
+      def handle_schema(params)
+        model = params['model']
+        raise ValidationError, 'Missing required parameter: model' unless model
+
+        @model_validator.validate_model!(model)
+        { 'columns' => @model_validator.columns_for(model), 'indexes' => [] }
+      end
+
+      def handle_recent(_params)
+        { 'records' => [] }
+      end
+
+      def handle_status
+        { 'status' => 'ok', 'models' => @model_validator.model_names }
+      end
+
+      # Build an error response hash.
+      def error_response(id, message, error_type)
+        { 'id' => id, 'ok' => false, 'error' => message, 'error_type' => error_type }
+      end
+
+      # Write a JSON-line response to the output stream.
+      def write_response(response)
+        @output.puts(JSON.generate(response))
+        @output.flush
+      end
+    end
+  end
+end

data/lib/woods/console/confirmation.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# @see Woods
+module Woods
+  class Error < StandardError; end unless defined?(Woods::Error)
+
+  module Console
+    class ConfirmationDeniedError < Woods::Error; end
+
+    # Human-in-the-loop confirmation protocol for Tier 4 tools.
+    #
+    # Supports three modes:
+    # - `:auto_approve` — Always approve (for testing/trusted environments)
+    # - `:auto_deny` — Always deny (for locked-down environments)
+    # - `:callback` — Delegates to a callable that returns true/false
+    #
+    # Tracks confirmation history for audit purposes.
+    #
+    # @example Auto-approve mode
+    #   confirmation = Confirmation.new(mode: :auto_approve)
+    #   confirmation.request_confirmation(tool: 'eval', description: '1+1', params: {})
+    #   # => true
+    #
+    # @example Callback mode
+    #   confirmation = Confirmation.new(mode: :callback, callback: ->(req) { req[:tool] != 'eval' })
+    #   confirmation.request_confirmation(tool: 'sql', description: 'SELECT 1', params: {})
+    #   # => true
+    #
+    class Confirmation
+      VALID_MODES = %i[auto_approve auto_deny callback].freeze
+
+      # @return [Array<Hash>] History of confirmation requests and outcomes
+      attr_reader :history
+
+      # @param mode [Symbol] One of :auto_approve, :auto_deny, :callback
+      # @param callback [Proc, nil] Required when mode is :callback
+      # @raise [ArgumentError] if mode is invalid or callback is missing for callback mode
+      def initialize(mode:, callback: nil)
+        unless VALID_MODES.include?(mode)
+          raise ArgumentError, "Invalid mode: #{mode}. Must be one of: #{VALID_MODES.join(', ')}"
+        end
+
+        raise ArgumentError, 'Callback required for callback mode' if mode == :callback && callback.nil?
+
+        @mode = mode
+        @callback = callback
+        @history = []
+      end
+
+      # Request confirmation for a Tier 4 operation.
+      #
+      # @param tool [String] Tool name
+      # @param description [String] Human-readable description of the action
+      # @param params [Hash] Tool parameters
+      # @return [true] if confirmed
+      # @raise [ConfirmationDeniedError] if denied
+      def request_confirmation(tool:, description:, params:) # rubocop:disable Naming/PredicateMethod
+        approved = evaluate(tool: tool, description: description, params: params)
+
+        @history << {
+          tool: tool,
+          description: description,
+          params: params,
+          approved: approved,
+          timestamp: Time.now.utc.iso8601
+        }
+
+        raise ConfirmationDeniedError, "Confirmation denied for #{tool}: #{description}" unless approved
+
+        true
+      end
+
+      private
+
+      # Evaluate the confirmation based on the current mode.
+      #
+      # @return [Boolean]
+      def evaluate(tool:, description:, params:)
+        case @mode
+        when :auto_approve
+          true
+        when :auto_deny
+          false
+        when :callback
+          @callback.call({ tool: tool, description: description, params: params })
+        end
+      end
+    end
+  end
+end

data/lib/woods/console/connection_manager.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+require 'shellwords'
+
+# @see Woods
+module Woods
+  class Error < StandardError; end unless defined?(Woods::Error)
+
+  module Console
+    class ConnectionError < Woods::Error; end
+
+    # Manages the bridge process connection via Docker exec, direct spawn, or SSH.
+    #
+    # Spawns and manages the bridge process, sends JSON-lines requests,
+    # receives responses. Implements heartbeat (30s) and reconnect with
+    # exponential backoff (max 5 retries).
+    #
+    # @example
+    #   manager = ConnectionManager.new(config: {
+    #     'mode' => 'direct',
+    #     'command' => 'bundle exec rails runner bridge.rb'
+    #   })
+    #   manager.connect!
+    #   response = manager.send_request({ 'id' => 'r1', 'tool' => 'status', 'params' => {} })
+    #   manager.disconnect!
+    #
+    class ConnectionManager
+      MAX_RETRIES = 5
+      HEARTBEAT_INTERVAL = 30
+
+      # @param config [Hash] Connection configuration
+      # @option config [String] 'mode' Connection mode: 'docker', 'direct', or 'ssh'
+      # @option config [String] 'command' Command to run the bridge
+      # @option config [String] 'container' Docker container name (docker mode)
+      # @option config [String] 'directory' Working directory (direct mode)
+      # @option config [String] 'host' SSH host (ssh mode)
+      # @option config [String] 'user' SSH user (ssh mode)
+      def initialize(config:)
+        @config = config
+        @mode = config['mode'] || 'direct'
+        @command = config['command'] || 'bundle exec rails runner lib/woods/console/bridge.rb'
+        @stdin = nil
+        @stdout = nil
+        @wait_thread = nil
+        @retries = 0
+        @last_heartbeat = nil
+      end
+
+      # Spawn the bridge process.
+      #
+      # @return [void]
+      # @raise [ConnectionError] if the process cannot be started
+      def connect!
+        cmd = build_command
+        if @mode == 'direct' && @config['directory']
+          Dir.chdir(@config['directory']) do
+            @stdin, @stdout, @wait_thread = Open3.popen2(*cmd)
+          end
+        else
+          @stdin, @stdout, @wait_thread = Open3.popen2(*cmd)
+        end
+        @last_heartbeat = Time.now
+        @retries = 0
+      rescue StandardError => e
+        raise ConnectionError, "Failed to connect (#{@mode}): #{e.message}"
+      end
+
+      # Terminate the bridge process.
+      #
+      # @return [void]
+      def disconnect!
+        @stdin&.close
+        @stdout&.close
+        @wait_thread&.value
+        @stdin = nil
+        @stdout = nil
+        @wait_thread = nil
+      end
+
+      # Send a request to the bridge and read the response.
+      #
+      # @param request [Hash] JSON-serializable request hash
+      # @return [Hash] Parsed response hash
+      # @raise [ConnectionError] if communication fails after retries
+      def send_request(request)
+        ensure_connected!
+        @stdin.puts(JSON.generate(request))
+        @stdin.flush
+        line = @stdout.gets
+        raise ConnectionError, 'Bridge process closed unexpectedly' unless line
+
+        @last_heartbeat = Time.now
+        JSON.parse(line)
+      rescue IOError, Errno::EPIPE, Errno::ECONNRESET => e
+        reconnect_or_raise!(e)
+        retry
+      end
+
+      # Check if the bridge process is alive.
+      #
+      # @return [Boolean]
+      def alive?
+        return false unless @wait_thread
+
+        @wait_thread.alive?
+      end
+
+      # Check if a heartbeat is needed (30s since last communication).
+      #
+      # @return [Boolean]
+      def heartbeat_needed?
+        return false unless @last_heartbeat
+
+        (Time.now - @last_heartbeat) >= HEARTBEAT_INTERVAL
+      end
+
+      private
+
+      # Build the shell command based on connection mode.
+      #
+      # @return [Array<String>]
+      def build_command
+        case @mode
+        when 'docker' then build_docker_command
+        when 'ssh'    then build_ssh_command
+        when 'direct' then build_direct_command
+        else raise ConnectionError, "Unknown connection mode: #{@mode}"
+        end
+      end
+
+      def build_docker_command
+        container = @config['container'] || raise(ConnectionError, 'Docker mode requires container name')
+        ['docker', 'exec', '-i', container] + @command.shellsplit
+      end
+
+      def build_ssh_command
+        host = @config['host'] || raise(ConnectionError, 'SSH mode requires host')
+        user = @config['user']
+        target = user ? "#{user}@#{host}" : host
+        ['ssh', target] + @command.shellsplit
+      end
+
+      def build_direct_command
+        @command.shellsplit
+      end
+
+      # Ensure the connection is active.
+      def ensure_connected!
+        return if alive?
+
+        connect!
+      end
+
+      # Attempt reconnection with exponential backoff.
+      #
+      # @param error [StandardError] The original error
+      # @raise [ConnectionError] if max retries exceeded
+      def reconnect_or_raise!(error)
+        @retries += 1
+        if @retries > MAX_RETRIES
+          raise ConnectionError,
+                "Connection failed after #{MAX_RETRIES} retries: #{error.message}"
+        end
+
+        sleep((2**(@retries - 1)) * 0.1)
+        disconnect!
+        connect!
+      end
+    end
+  end
+end