rubik 0.1.0

data/lib/rubik/lsp/manager.rb

@@ -0,0 +1,366 @@
+# frozen_string_literal: true
+
+require "monitor"
+require_relative "client"
+require_relative "../runtime/discovery"
+require_relative "../runtime/diagnostic_engine"
+
+module Rubik
+  module LSP
+    class Manager
+      EXTENSION_MAP = {
+        ".go" => "go",
+        ".rs" => "rust",
+        ".zig" => "zig",
+        ".c" => "c",
+        ".h" => "c",
+        ".cpp" => "c",
+        ".hpp" => "c",
+        ".py" => "python",
+        ".rb" => "ruby",
+        ".ts" => "typescript",
+        ".tsx" => "typescript",
+        ".js" => "javascript",
+        ".jsx" => "javascript",
+        ".sh" => "bash",
+        ".bash" => "bash",
+        ".cr" => "crystal",
+        ".gleam" => "gleam",
+        ".vue" => "vue"
+      }.freeze
+
+      MAX_CONSECUTIVE_CRASHES = 3
+      CIRCUIT_COOLDOWN_SECONDS = 300
+
+      attr_reader :config, :root_dir, :clients, :crash_stats
+      attr_accessor :runtime_manager, :context
+
+      def initialize(config:, root_dir: Dir.pwd, runtime_manager: nil, context: nil)
+        @config = config
+        @root_dir = File.expand_path(root_dir)
+        @runtime_manager = runtime_manager
+        @context = context || runtime_manager&.context
+        @clients = {}
+        @crash_stats = {}
+        @monitor = Monitor.new
+      end
+
+      def enabled?
+        @config.fetch("lsp.enabled", false) == true
+      end
+
+      def auto_diagnostics?
+        @config.fetch("lsp.auto_diagnostics", true) == true
+      end
+
+      def detect_language(file_path)
+        ext = File.extname(file_path).downcase
+        EXTENSION_MAP[ext]
+      end
+
+      def circuit_open?(lang)
+        @monitor.synchronize do
+          stat = @crash_stats[lang.to_s.downcase]
+          return false unless stat && stat[:circuit_open]
+
+          if stat[:last_crash_at] && (Time.now - stat[:last_crash_at] > CIRCUIT_COOLDOWN_SECONDS)
+            stat[:circuit_open] = false
+            stat[:count] = 0
+            false
+          else
+            true
+          end
+        end
+      end
+
+      def record_crash(lang)
+        @monitor.synchronize do
+          lang_str = lang.to_s.downcase
+          stat = (@crash_stats[lang_str] ||= { count: 0, last_crash_at: nil, circuit_open: false })
+          stat[:count] += 1
+          stat[:last_crash_at] = Time.now
+          stat[:circuit_open] = true if stat[:count] >= MAX_CONSECUTIVE_CRASHES
+        end
+      end
+
+      def reset_circuit!(lang)
+        @monitor.synchronize do
+          lang_str = lang.to_s.downcase
+          @crash_stats.delete(lang_str)
+        end
+      end
+
+      def ensure_healthy!(language_or_client)
+        return nil unless enabled?
+
+        client = language_or_client.is_a?(Client) ? language_or_client : client_for(language_or_client)
+        return nil unless client
+
+        if client.running && client.respond_to?(:alive?) && !client.alive?
+          lang = client.language
+          record_crash(lang)
+          @monitor.synchronize do
+            begin
+              client.stop
+            rescue
+              nil
+            end
+            @clients.delete(lang)
+          end
+          start_client(lang) unless circuit_open?(lang)
+          client = @clients[lang]
+        elsif !client.running && @config.fetch("lsp.auto_start", true) && client.available? && !circuit_open?(client.language)
+          start_client(client.language)
+          client = @clients[client.language]
+        end
+
+        client
+      end
+
+      def client_for(language_or_file)
+        lang = if language_or_file.to_s.include?(".")
+                 detect_language(language_or_file)
+               else
+                 language_or_file.to_s.downcase
+               end
+
+        return nil unless lang
+
+        @monitor.synchronize do
+          if @clients.key?(lang)
+            client = @clients[lang]
+            if client.running && client.respond_to?(:alive?) && !client.alive?
+              record_crash(lang)
+              begin
+                client.stop
+              rescue
+                nil
+              end
+              @clients.delete(lang)
+              nil # Will trigger recreate / start below
+            else
+              client
+            end
+          elsif enabled?
+            configured_cmd = @config.fetch("lsp.servers.#{lang}") || Client::SERVERS[lang]
+            client = Client.new(lang, root_dir: @root_dir, server_cmd: configured_cmd)
+            unless client.available?
+              probed_cmd = Runtime::Discovery.probe_lsp(lang, root_dir: @root_dir, custom_cmd: configured_cmd)
+              client = Client.new(lang, root_dir: @root_dir, server_cmd: probed_cmd) if probed_cmd
+            end
+
+            if client.available? && @config.fetch("lsp.auto_start", true) && !circuit_open?(lang)
+              if client.start
+                reset_circuit!(lang)
+                effective_ctx = @context || @runtime_manager&.context
+                if effective_ctx
+                  effective_ctx.provide("lsp:#{lang}", client)
+                  effective_ctx.register_disposable { client.stop if client.running }
+                end
+              else
+                record_crash(lang)
+                begin
+                  client.stop
+                rescue StandardError
+                  nil
+                end
+              end
+            end
+            @clients[lang] = client
+          end
+        end
+      end
+
+      def start_client(lang)
+        lang_str = lang.to_s.downcase
+        @monitor.synchronize do
+          configured_cmd = @config.fetch("lsp.servers.#{lang_str}") || Client::SERVERS[lang_str]
+          client = @clients[lang_str] || Client.new(lang_str, root_dir: @root_dir, server_cmd: configured_cmd)
+
+          # 1. Fallback probing if configured command binary is not available
+          unless client.available?
+            probed_cmd = Runtime::Discovery.probe_lsp(lang_str, root_dir: @root_dir, custom_cmd: configured_cmd)
+            client = Client.new(lang_str, root_dir: @root_dir, server_cmd: probed_cmd) if probed_cmd && probed_cmd != client.server_cmd
+          end
+
+          unless client.available?
+            failure = Runtime::DiagnosticEngine.diagnose(
+              cmd: client.server_cmd,
+              exit_code: 127,
+              stderr: "Server binary '#{client.server_cmd}' not found in PATH"
+            )
+            return {
+              ok: false,
+              error: "Server binary '#{client.server_cmd}' not found",
+              diagnostic: failure,
+              suggestion: failure.suggestion
+            }
+          end
+
+          if client.running
+            { ok: true, message: "LSP server for '#{lang_str}' is already running (PID: #{client.instance_variable_get(:@wait_thr)&.pid})" }
+          else
+            res = client.start
+            @clients[lang_str] = client
+            if res
+              reset_circuit!(lang_str)
+              effective_ctx = @context || @runtime_manager&.context
+              if effective_ctx
+                effective_ctx.provide("lsp:#{lang_str}", client)
+                effective_ctx.register_disposable { client.stop if client.running }
+              end
+              { ok: true, message: "Started LSP server for '#{lang_str}' (#{client.server_cmd})" }
+            else
+              record_crash(lang_str)
+              begin
+                client.stop
+              rescue StandardError
+                nil
+              end
+              failure = Runtime::DiagnosticEngine.diagnose(
+                cmd: client.server_cmd,
+                exit_code: 1,
+                stderr: "Failed to initialize LSP server handshake for '#{lang_str}'"
+              )
+              {
+                ok: false,
+                error: "Failed to initialize LSP server for '#{lang_str}'",
+                diagnostic: failure,
+                suggestion: failure.suggestion
+              }
+            end
+          end
+        end
+      end
+
+      def stop_client(lang)
+        lang_str = lang.to_s.downcase
+        @monitor.synchronize do
+          client = @clients[lang_str]
+          return { ok: false, error: "No active client for '#{lang_str}'" } unless client
+
+          client.stop
+          @clients.delete(lang_str)
+          { ok: true, message: "Stopped LSP server for '#{lang_str}'" }
+        end
+      end
+
+      def stop_all
+        @monitor.synchronize do
+          @clients.each_value(&:stop)
+          @clients.clear
+        end
+      end
+
+      def sync_buffer_file(file_path, content)
+        return false unless enabled?
+
+        client = client_for(file_path)
+        return false unless client&.running
+
+        # Try did_change, or did_open if not yet opened
+        if client.document_open?(file_path)
+          client.did_change(file_path, content)
+        else
+          client.did_open(file_path, content)
+        end
+      end
+
+      def sync_buffer_file_if_needed(file_path, buffer_manager)
+        return false unless enabled? && buffer_manager
+
+        if file_path.nil? || file_path.to_s.strip.empty?
+          if buffer_manager.respond_to?(:dirty_files)
+            buffer_manager.dirty_files.each_key do |f|
+              content = buffer_manager.read(f)
+              sync_buffer_file(f, content) if content
+            end
+          end
+          return true
+        end
+
+        path_str = file_path.to_s.strip
+        needs_sync = begin
+          if buffer_manager.respond_to?(:dirty?)
+            buffer_manager.method(:dirty?).arity.zero? ? buffer_manager.dirty? : buffer_manager.dirty?(path_str)
+          else
+            false
+          end
+        rescue ArgumentError
+          buffer_manager.dirty?
+        end
+
+        return unless needs_sync
+
+        content = buffer_manager.read(path_str)
+        sync_buffer_file(path_str, content) if content
+      end
+
+      def diagnostics_for(file_path)
+        client = client_for(file_path)
+        return [] unless client&.running
+
+        client.diagnostics_for(file_path)
+      end
+
+      def all_diagnostics
+        result = {}
+        @monitor.synchronize do
+          @clients.each_value do |client|
+            next unless client.running
+
+            result.merge!(client.all_diagnostics)
+          end
+        end
+        result
+      end
+
+      def hover(file_path, line, character)
+        client = client_for(file_path)
+        return { ok: false, error: "LSP not active for '#{file_path}'" } unless client&.running
+
+        client.hover(file_path, line, character)
+      end
+
+      def definition(file_path, line, character)
+        client = client_for(file_path)
+        return { ok: false, error: "LSP not active for '#{file_path}'" } unless client&.running
+
+        client.definition(file_path, line, character)
+      end
+
+      def references(file_path, line, character)
+        client = client_for(file_path)
+        return { ok: false, error: "LSP not active for '#{file_path}'" } unless client&.running
+
+        client.references(file_path, line, character)
+      end
+
+      def status_summary
+        client_statuses = {}
+        @monitor.synchronize do
+          Client::SERVERS.each do |lang, def_cmd|
+            cmd = @config.fetch("lsp.servers.#{lang}") || def_cmd
+            active_c = @clients[lang]
+            avail = active_c ? active_c.available? : Runtime::Discovery.binary_available?(cmd)
+            probed = avail ? cmd : Runtime::Discovery.probe_lsp(lang, root_dir: @root_dir)
+
+            client_statuses[lang] = {
+              server_cmd: cmd,
+              probed_cmd: probed,
+              available: avail || !probed.nil?,
+              running: active_c&.running || false,
+              diagnostics_count: active_c ? active_c.all_diagnostics.values.flatten.size : 0
+            }
+          end
+        end
+
+        {
+          enabled: enabled?,
+          auto_diagnostics: auto_diagnostics?,
+          servers: client_statuses
+        }
+      end
+    end
+  end
+end

data/lib/rubik/lsp.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "lsp/client"
+require_relative "lsp/manager"
+
+module Rubik
+  module LSP
+  end
+end

data/lib/rubik/mcp/boot_lifecycle.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Rubik
+  module MCP
+    # Boot state-machine vocabulary for Rubik::MCP::Manager (included there).
+    # Storage stays on the host: @statuses, @boot_marks, @clients and @monitor
+    # are Manager ivars these paths touch on `self`, always under that
+    # monitor (Ruby Monitor is re-entrant, so callers already holding it
+    # compose freely). Thread-safety fence (mcp-async-boot G5): none of these
+    # paths block on threads or I/O — the boot-thread join stays outside the
+    # monitor.
+    #
+    # Precedent: orchestrator/subagent/lifecycle.rb — a pure state machine
+    # deserves its own page, not headroom to grow back.
+    module BootLifecycle
+      # Raised by transition_server! on an edge outside TRANSITIONS. The
+      # table is derived from the actual write sites, so this firing means a
+      # new writer skipped the guarded seam (fail-loud tripwire).
+      class StateError < StandardError; end
+
+      STATES = [:disabled, :connecting, :active, :failed].freeze
+
+      # Every legal from->to edge, derived from the write sites:
+      #   disabled   <- add_server (auto_start false / disabled config),
+      #                 disable_server (user teardown wins from ANY state),
+      #                 re-add over a failed/connecting slot
+      #   connecting <- boot phase-0 claim over :disabled, :failed (re-boot),
+      #                 or :active-with-dead-client (already_active misses)
+      #   active     <- apply success (boot path from :connecting; enable
+      #                 path from :disabled/:failed), user enable during a
+      #                 boot (:connecting)
+      #   failed     <- apply rollback, enable connect failure (from
+      #                 :disabled, :failed retry, :active dead-client,
+      #                 :connecting), boot's epoch-guarded connect-failure
+      #                 flip and D6 ensure sweep
+      # The table is fully connected — that IS the invariant: user decisions
+      # are legal from any state; boot writes are legal only from an
+      # epoch-owned :connecting. Server absence (remove_server) is not a
+      # state, it is record deletion (clear_server_record!).
+      TRANSITIONS = {
+        disabled: [:connecting, :active, :failed],
+        connecting: [:active, :failed, :disabled],
+        active: [:disabled, :connecting, :failed],
+        failed: [:connecting, :active, :disabled]
+      }.transform_values(&:freeze).freeze
+
+      # The only mutation path for @statuses. epoch: nil is the USER actor —
+      # the decision wins from any state (D5). Passing epoch: makes it the
+      # BOOT actor: it owns the slot only while the slot is still :connecting
+      # under ITS epoch; anything else (user disable/enable/remove, a newer
+      # boot's fresh mark) wins, and the call is a silent no-op returning
+      # nil. Idempotent on same-state (returns the current state); raises
+      # StateError on an edge outside TRANSITIONS. Epoch gate and flip are
+      # applied in the SAME monitor hold — never split this into a predicate
+      # read followed by an unguarded write.
+      def transition_server!(name, to, epoch: nil)
+        name = name.to_s
+        @monitor.synchronize do
+          current = @statuses[name] || :disabled
+          target = to.to_sym
+          return current if current == target
+
+          return nil if epoch && (current != :connecting || !@boot_marks[name].equal?(epoch))
+
+          raise StateError, "illegal MCP boot transition '#{name}': #{current} -> #{target}" unless TRANSITIONS.fetch(current, []).include?(target)
+
+          @statuses[name] = target
+          # Boot-mark debt: a mark only matters while :connecting. Leaving
+          # the state retires it, so marks never outlive their epoch
+          # (zero-restart — claim/apply and claim/remove cycles keep
+          # @boot_marks flat instead of growing forever).
+          @boot_marks.delete(name) unless target == :connecting
+          target
+        end
+      end
+
+      # Phase-0 claim: returns true when a live :active server already owns
+      # the slot (boot must not touch it); otherwise flips the slot to
+      # :connecting and tags it with this boot's epoch — atomically under one
+      # monitor hold (D5). A re-claim over a stale :connecting mark (wedged
+      # older boot) takes the slot over with the new epoch.
+      def claim_boot_slot!(name, epoch)
+        name = name.to_s
+        @monitor.synchronize do
+          already_active = @statuses[name] == :active && @clients[name]&.running?
+          unless already_active
+            transition_server!(name, :connecting) # re-entrant: same hold
+            @boot_marks[name] = epoch
+          end
+          already_active
+        end
+      end
+
+      # remove_server's record deletion: status and (possibly dead) boot mark
+      # retire together — deletion must not leave a mark for a slot that no
+      # longer exists.
+      def clear_server_record!(name)
+        name = name.to_s
+        @monitor.synchronize do
+          @statuses.delete(name)
+          @boot_marks.delete(name)
+        end
+      end
+
+      # Stop-debt rule, structural (was prose in perform_load_from_config
+      # plus the [:failed, true].include? arithmetic): an applied or
+      # failed-apply slot stopped its own client (context drain / rollback);
+      # skipped and never-ran slots still owe a stop in the ensure.
+      def self.owes_stop?(outcome)
+        !outcome.equal?(:applied) && !outcome.equal?(:failed)
+      end
+    end
+  end
+end

data/lib/rubik/mcp/client.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "transport/stdio"
+require_relative "../version"
+
+module Rubik
+  module MCP
+    class ToolResult
+      attr_reader :content, :is_error, :text
+
+      def initialize(content: [], is_error: false, text: "")
+        @content = content
+        @is_error = is_error
+        @text = text
+      end
+
+      def error?
+        @is_error
+      end
+
+      def to_s
+        @text
+      end
+
+      def [](key)
+        case key.to_s
+        when "content" then @content
+        when "isError" then @is_error
+        when "text" then @text
+        end
+      end
+
+      def key?(key)
+        ["content", "isError", "text"].include?(key.to_s)
+      end
+
+      def to_h
+        { "content" => @content, "isError" => @is_error, "text" => @text }
+      end
+    end
+
+    class Client
+      DEFAULT_PROTOCOL_VERSION = "2024-11-05"
+      # Connect handshake (initialize + tools/list) and tools/call round-trip
+      # defaults. The user-facing mirrors live in config/defaults.rb as
+      # mcp.timeout / mcp.call_timeout (MCP::Manager resolves and passes them
+      # down); these constants are the last link of that fallback chain.
+      DEFAULT_TIMEOUT = 10
+      DEFAULT_CALL_TIMEOUT = 30
+
+      attr_reader :name, :transport, :server_info, :server_capabilities, :protocol_version, :initialized
+
+      def initialize(command, args: [], env: {}, name: "unnamed", root_dir: Dir.pwd, transport: nil, guard: nil,
+                     call_timeout: nil)
+        @name = name.to_s
+        @transport = transport || Transport::Stdio.new(command, args: args, env: env, root_dir: root_dir, guard: guard)
+        # Session-wide tools/call timeout; nil (absent or not a positive
+        # number) keeps the per-call DEFAULT_CALL_TIMEOUT fallback.
+        @default_call_timeout = positive_number?(call_timeout) ? call_timeout : nil
+        @server_info = {}
+        @server_capabilities = {}
+        @protocol_version = nil
+        @initialized = false
+      end
+
+      def start!(timeout: DEFAULT_TIMEOUT)
+        return self if @initialized && running?
+
+        @transport.open
+
+        init_params = {
+          "protocolVersion" => DEFAULT_PROTOCOL_VERSION,
+          "capabilities" => {},
+          "clientInfo" => {
+            "name" => "Rubik",
+            "version" => defined?(Rubik::VERSION) ? Rubik::VERSION : "1.0.0"
+          }
+        }
+
+        result = @transport.send_request("initialize", init_params, timeout: timeout)
+        if result.is_a?(Hash)
+          @protocol_version = result["protocolVersion"]
+          @server_info = result["serverInfo"] || {}
+          @server_capabilities = result["capabilities"] || {}
+        end
+
+        @transport.send_notification("notifications/initialized", {})
+        @initialized = true
+        self
+      end
+      alias start start!
+
+      def list_tools(timeout: DEFAULT_TIMEOUT)
+        ensure_running!
+        res = @transport.send_request("tools/list", {}, timeout: timeout)
+        if res.is_a?(Hash) && res.key?("tools")
+          Array(res["tools"]).compact
+        elsif res.is_a?(Array)
+          res.compact
+        else
+          []
+        end
+      end
+
+      def call_tool(tool_name, arguments = {}, timeout: nil)
+        ensure_running!
+        params = {
+          "name" => tool_name.to_s,
+          "arguments" => arguments || {}
+        }
+        res = @transport.send_request("tools/call", params, timeout: resolve_call_timeout(timeout))
+
+        is_error = res.is_a?(Hash) ? (res["isError"] == true) : false
+        content = if res.is_a?(Hash) && res["content"].is_a?(Array)
+                    res["content"]
+                  elsif res.is_a?(Array)
+                    res
+                  else
+                    [{ "type" => "text", "text" => res.to_s }]
+                  end
+
+        text = content.select { |c| c.is_a?(Hash) && (c["type"] == "text" || c[:type] == "text") }
+                      .map { |c| (c["text"] || c[:text]).to_s }
+                      .join("\n")
+
+        text = res.to_s if text.empty? && !res.nil?
+
+        ToolResult.new(content: content, is_error: is_error, text: text)
+      end
+
+      def ping(timeout: 5)
+        ensure_running!
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @transport.send_request("ping", {}, timeout: timeout)
+        ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0).round(2)
+      end
+
+      def stop
+        @initialized = false
+        @transport.close
+      end
+      alias close stop
+      alias dispose stop
+
+      def running?
+        @transport&.running? || false
+      end
+
+      private
+
+      def ensure_running!
+        raise ConnectionError, "MCP client '#{@name}' is not running" unless running?
+      end
+
+      # Per-call override first, then the session-wide constructor value,
+      # then the constant — so an explicit timeout argument always wins.
+      def resolve_call_timeout(timeout)
+        return timeout if positive_number?(timeout)
+
+        @default_call_timeout || DEFAULT_CALL_TIMEOUT
+      end
+
+      def positive_number?(value)
+        value.is_a?(Numeric) && value.positive?
+      end
+    end
+  end
+end

data/lib/rubik/mcp/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Rubik
+  module MCP
+    class Error < StandardError; end
+    class ConnectionError < Error; end
+    class TimeoutError < Error; end
+    class ProtocolError < Error; end
+    class ToolExecutionError < Error; end
+  end
+end