ruby-test-ide 0.1.0

data/lib/ruby_test_ide/server.rb

@@ -0,0 +1,724 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# RubyTestIDE proof-of-concept server.
+#
+# Zero-gem HTTP server (plain TCPServer) that powers a browser IDE with
+# *runtime* Ruby intelligence: every completion/hover/run request spawns a
+# short-lived worker (lib/runner.rb) that actually evaluates the buffer in a
+# sandbox binding and reflects on the live objects — the same trick irb uses.
+#
+#   ruby server.rb [port]      # default port 3000, then open http://localhost:3000
+#
+# Endpoints (all JSON):
+#   POST /api/complete     {code, line, column}          -> {items:[...], receiver, prefix, receiver_class}
+#   POST /api/hover        {code, line, column, word, wordStartColumn} -> {kind, signature, doc, ...}
+#   POST /api/diagnostics  {code}                        -> {diagnostics:[{line, message}]}
+#   POST /api/run          {code}                        -> {stdout, line_states, final_locals, error}
+#   GET  /health           -> ok
+
+require 'socket'
+require 'json'
+require 'stringio'
+require 'uri'
+
+module RubyTestIDE
+  ROOT = __dir__
+  RUNNER = File.join(ROOT, 'runner.rb')
+  RUNNER_TIMEOUT = 4 # seconds of wall clock before the worker is killed
+  # The project directory being edited. The `ruby-test-ide` executable sets
+  # the env var to --workspace (default: the directory it was launched from).
+  WORKSPACE = File.expand_path(ENV['RUBY_TEST_IDE_WORKSPACE'] || Dir.pwd)
+
+  # The server executes arbitrary code from any request it accepts, so every
+  # route except /health and /vendor/* (static library assets, no user data)
+  # requires this token — set by the `ruby-test-ide` executable, which
+  # generates a random one per launch unless --token/--no-auth override it.
+  AUTH_DISABLED = ENV['RUBY_TEST_IDE_NO_AUTH'] == '1'
+  TOKEN = ENV['RUBY_TEST_IDE_TOKEN'].to_s
+
+  # Constant-time compare — cheap insurance on localhost, real insurance if
+  # this ever ends up reachable from elsewhere (e.g. --workspace over a VPN).
+  def self.token_matches?(candidate)
+    return true if AUTH_DISABLED
+    return false if candidate.nil? || TOKEN.empty?
+
+    a = candidate.to_s.b
+    b = TOKEN.b
+    return false unless a.bytesize == b.bytesize
+
+    result = 0
+    a.bytes.each_with_index { |byte, i| result |= byte ^ b.getbyte(i) }
+    result.zero?
+  end
+  WORKSPACE_IGNORE = %r{(\A|/)(\.git|node_modules|tmp|\.bundle|\.ruby-ide)(/|\z)}
+  # The sidebar is a Ruby IDE, not a general file browser: showing every
+  # file (Gemfile.lock, README, dotfiles) invited opening a non-Ruby file,
+  # which the editor still force-parsed as Ruby and reported bogus syntax
+  # errors on. Extensionless Ruby files are named explicitly.
+  RUBY_FILENAMES = %w[Gemfile Rakefile].freeze
+  TEST_GLOBS = ['test/**/*_test.rb', 'test/**/test_*.rb', 'spec/**/*_spec.rb'].freeze
+  LEARN_TIMEOUT = 60 # whole learn commands get a bigger budget than single evals
+  OBSERVATIONS = File.join(WORKSPACE, '.ruby-ide', 'observations.json')
+  OBSERVER = File.join(ROOT, 'observer.rb')
+  CONFIG_FILE = File.join(WORKSPACE, '.ruby_ide.yaml')
+
+  def self.discover_tests
+    TEST_GLOBS.flat_map { |g| Dir.glob(File.join(WORKSPACE, g)) }.uniq.sort
+  end
+
+  # .ruby_ide.yaml in the workspace root, e.g.
+  #   learn:                       # any commands that execute your code
+  #     - bundle exec rspec
+  #     - bundle exec rake test
+  #     - ruby scripts/exercise.rb
+  #   timeout: 120                 # optional, seconds per command
+  def self.load_config
+    return {} unless File.file?(CONFIG_FILE)
+
+    require 'yaml'
+    config = YAML.safe_load(File.read(CONFIG_FILE))
+    config.is_a?(Hash) ? config : {}
+  rescue StandardError => e
+    { 'config_error' => "#{File.basename(CONFIG_FILE)}: #{e.message}" }
+  end
+
+  # No config? Guess: run each minitest file / the spec dir, under bundler
+  # when the workspace has a Gemfile.
+  def self.default_learn_commands
+    prefix = File.file?(File.join(WORKSPACE, 'Gemfile')) ? 'bundle exec ' : ''
+    tests = discover_tests
+    specs, minitests = tests.partition { |f| f.end_with?('_spec.rb') }
+    commands = minitests.map { |f| "#{prefix}ruby #{f.delete_prefix("#{WORKSPACE}/")}" }
+    commands << "#{prefix}rspec" unless specs.empty?
+    commands
+  end
+
+  # Run one learn command with the observer preloaded into every ruby
+  # process it starts. Output is captured; the process group is killed on
+  # timeout, exactly like eval workers.
+  def self.run_learn_command(cmd, obs_dir, timeout)
+    out_r, out_w = IO.pipe
+    env = {
+      'RUBYOPT' => [ENV['RUBYOPT'], "-r#{OBSERVER}"].compact.reject(&:empty?).join(' '),
+      'RUBY_IDE_OBS_DIR' => obs_dir,
+      'RUBY_IDE_OBS_ROOT' => WORKSPACE,
+    }
+    pid = spawn(env, cmd.to_s, chdir: WORKSPACE,
+                in: File::NULL, out: out_w, err: out_w, pgroup: true)
+    out_w.close
+    out_thread = Thread.new { out_r.read }
+    status, killed = wait_or_kill(pid, timeout)
+    output = out_thread.value
+    out_r.close
+    { 'command' => cmd, 'exit' => status&.exitstatus, 'ok' => !killed && status&.success? == true,
+      'timeout' => killed || nil, 'output' => output.to_s[-4000..] || output.to_s }.compact
+  rescue StandardError => e
+    { 'command' => cmd, 'ok' => false, 'output' => "#{e.class}: #{e.message}" }
+  end
+
+  def self.wait_or_kill(pid, timeout)
+    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+    loop do
+      _, status = Process.waitpid2(pid, Process::WNOHANG)
+      return [status, false] if status
+
+      if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+        begin
+          Process.kill('-KILL', pid)
+        rescue StandardError
+          nil
+        end
+        _, status = Process.waitpid2(pid)
+        return [status, true]
+      end
+      sleep 0.01
+    end
+  end
+
+  # Merge the per-process observation dumps into one map (a suite may spawn
+  # several ruby processes; each writes its own file).
+  def self.merge_observations(files)
+    merged = {}
+    files.each do |f|
+      JSON.parse(File.read(f)).each do |key, entry|
+        if (existing = merged[key])
+          existing['calls'] += entry['calls'].to_i
+          entry['args'].each do |name, classes|
+            (existing['args'][name] ||= {}).merge!(classes) { |_, mine, _| mine }
+          end
+          existing['returns'].merge!(entry['returns']) { |_, mine, _| mine }
+        else
+          merged[key] = entry
+        end
+      end
+    rescue StandardError
+      next
+    end
+    merged
+  end
+
+  # Files the editor lists / opens / saves all live under WORKSPACE.
+  # Every relative path from the browser is resolved and fenced here.
+  def self.workspace_path(rel)
+    raise ArgumentError, 'path required' if rel.to_s.empty?
+
+    abs = File.expand_path(rel.to_s, WORKSPACE)
+    raise ArgumentError, 'path escapes workspace' unless abs == WORKSPACE || abs.start_with?("#{WORKSPACE}/")
+
+    abs
+  end
+
+  # NB: no Dir.chdir here — the cwd is process-wide and this server is
+  # multi-threaded, so relative globbing would race between requests.
+  def self.workspace_files
+    Dir.glob(File.join(WORKSPACE, '**', '*'))
+       .select { |f| File.file?(f) }
+       .map { |f| f.delete_prefix("#{WORKSPACE}/") }
+       .reject { |f| f.match?(WORKSPACE_IGNORE) }
+       .select { |f| f.end_with?('.rb') || RUBY_FILENAMES.include?(File.basename(f)) }
+       .sort
+       .map { |f| { 'path' => f, 'size' => File.size(File.join(WORKSPACE, f)) } }
+  end
+
+  def self.seed_workspace
+    require 'fileutils'
+    FileUtils.mkdir_p(WORKSPACE)
+    return unless Dir.empty?(WORKSPACE)
+
+    FileUtils.mkdir_p(File.join(WORKSPACE, 'lib'))
+    File.write(File.join(WORKSPACE, 'main.rb'), <<~RUBY)
+      # Files here are real: open them from the sidebar, edit, save with Cmd+S.
+      # require_relative works — and so does reflection ACROSS files:
+      # type  greeter.  below and methods from lib/greeter.rb appear.
+
+      require_relative 'lib/greeter'
+
+      greeter = Greeter.new('Sam')
+      message = greeter.greet
+      puts message
+    RUBY
+    File.write(File.join(WORKSPACE, 'lib', 'greeter.rb'), <<~RUBY)
+      # Edit this class, save, and completions in main.rb update on the
+      # next keystroke — the runtime is the single source of truth.
+      class Greeter
+        attr_reader :name
+
+        def initialize(name)
+          @name = name
+        end
+
+        def greet(punctuation = '!')
+          "Hello, \#{name}\#{punctuation}"
+        end
+      end
+    RUBY
+  end
+
+  # ------------------------------------------------------------------ workers
+
+  # Spawn lib/runner.rb, hand it one JSON request on stdin, read the JSON
+  # reply from fd 3 (so user code writing to stdout can't corrupt it), and
+  # kill the whole process group if it blows the time budget.
+  def self.run_worker(payload, timeout: RUNNER_TIMEOUT)
+    stdin_r, stdin_w = IO.pipe
+    out_r, out_w = IO.pipe
+    result_r, result_w = IO.pipe
+    pid = spawn(RbConfig.ruby, '--disable-gems', RUNNER,
+                in: stdin_r, out: out_w, err: out_w, 3 => result_w,
+                pgroup: true, rlimit_cpu: timeout * 2)
+    stdin_r.close
+    out_w.close
+    result_w.close
+    stdin_w.write(JSON.generate(payload))
+    stdin_w.close
+
+    out_thread = Thread.new { out_r.read }
+    result_thread = Thread.new { result_r.read }
+
+    _status, killed = wait_or_kill(pid, timeout)
+
+    user_output = out_thread.value
+    raw = result_thread.value
+    out_r.close
+    result_r.close
+
+    if killed
+      return { 'error' => "evaluation timed out after #{timeout}s (infinite loop?)",
+               'timeout' => true, 'stdout' => user_output }
+    end
+
+    response = begin
+      JSON.parse(raw)
+    rescue StandardError
+      { 'error' => "runner crashed: #{user_output.to_s[0, 500]}" }
+    end
+    response['stdout'] = user_output[0, 20_000] unless user_output.to_s.empty?
+    response
+  end
+
+  # ----------------------------------------------------- cursor text analysis
+
+  # Split "everything on the line before the cursor" into [receiver, prefix]:
+  #   "t.st"            -> ["t",        "st"]
+  #   "x = 'foo'.up"    -> ["'foo'",    "up"]
+  #   "arr[0].e"        -> ["arr[0]",   "e"]
+  #   "t.strip.rev"     -> ["t.strip",  "rev"]
+  #   "pu"              -> [nil,        "pu"]
+  def self.split_target(text)
+    i = text.length
+    j = i
+    j -= 1 while j.positive? && text[j - 1].match?(/[A-Za-z0-9_]/)
+    prefix = text[j...i]
+
+    if j.positive? && text[j - 1] == '.' && !(j > 1 && text[j - 2] == '.')
+      recv_end = j - 1
+      recv_start = receiver_start(text, recv_end)
+      return [nil, prefix] if recv_start >= recv_end
+
+      [text[recv_start...recv_end], prefix]
+    else
+      # pull sigils (@, @@, $) into the prefix for ivar/gvar completion
+      j -= 1 while j.positive? && text[j - 1].match?(/[@$]/)
+      [nil, text[j...i]]
+    end
+  end
+
+  # Scan backwards from the trailing '.' to find where the receiver
+  # expression starts, honouring balanced brackets and string literals.
+  def self.receiver_start(text, pos)
+    i = pos
+    while i.positive?
+      c = text[i - 1]
+      case c
+      when /[A-Za-z0-9_?!@$]/
+        i -= 1
+      when ')', ']', '}'
+        open = matching_open(text, i - 1)
+        return i unless open
+
+        i = open
+      when '"', "'"
+        k = i - 2
+        k -= 1 while k >= 0 && !(text[k] == c && (k.zero? || text[k - 1] != '\\'))
+        return i if k.negative?
+
+        i = k
+      when '.'
+        return i if i >= 2 && text[i - 2] == '.' # don't cross a range operator
+
+        i -= 1
+      when ':'
+        i -= 1
+      else
+        return i
+      end
+    end
+    0
+  end
+
+  def self.matching_open(text, close_idx)
+    pairs = { ')' => '(', ']' => '[', '}' => '{' }
+    close = text[close_idx]
+    open = pairs[close]
+    depth = 0
+    close_idx.downto(0) do |k|
+      depth += 1 if text[k] == close
+      depth -= 1 if text[k] == open
+      return k if depth.zero?
+    end
+    nil
+  end
+
+  # --------------------------------------------------------------- diagnostics
+
+  # Compile (never execute) the buffer to catch syntax errors — on 3.2,
+  # AbstractSyntaxTree.parse omits line numbers. Two message formats exist:
+  #   <= 3.3 (parse.y): "(buffer):3: syntax error, unexpected end-of-input"
+  #   >= 3.4 (prism):   "(buffer):3: syntax errors found" followed by a
+  #                     source listing with "> 3 | puts 1" markers and
+  #                     "    |       ^ expected an `end` ..." caret lines
+  def self.syntax_diagnostics(code)
+    stderr = $stderr
+    $stderr = StringIO.new
+    RubyVM::InstructionSequence.compile(code, '(buffer)')
+    []
+  rescue SyntaxError => e
+    parse_syntax_error(e.message)
+  ensure
+    $stderr = stderr
+  end
+
+  def self.parse_syntax_error(message)
+    diagnostics = []
+    current_line = nil
+    message.split("\n").each do |line|
+      if (m = line.match(/\A>\s*(\d+)\s*\|/)) # prism: marked source line
+        current_line = m[1].to_i
+      elsif current_line && (m = line.match(/\A\s*\|\s*\^+\s*(.+)/)) # prism: caret detail
+        diagnostics << { 'line' => current_line, 'message' => m[1],
+                         'severity' => 'error', 'source' => 'syntax' }
+      elsif (m = line.match(/\A\(buffer\):(\d+):\s*(.+)/)) # parse.y, or prism header
+        diagnostics << { 'line' => m[1].to_i, 'message' => m[2],
+                         'severity' => 'error', 'source' => 'syntax' }
+      end
+    end
+    # prefer prism's detailed caret messages over its generic header line
+    detailed = diagnostics.reject { |d| d['message'].start_with?('syntax error') && diagnostics.size > 1 }
+    detailed.empty? ? diagnostics : detailed
+  end
+
+  # ---------------------------------------------------------------- ri lookup
+
+  # Documentation comes from the installed ri database (same data `ri
+  # String#strip` uses). Method docs are fetched in-process via
+  # RDoc::RI::Driver (~0.15ms warm vs ~290ms for shelling out to `ri`);
+  # class docs and any driver failure fall back to the `ri` CLI. Memoised.
+  #
+  # If lookups return nothing, generate the core docs once:
+  #   cd ~/.rvm/src/ruby-3.2.2 && rdoc --all --ri \
+  #     --op ~/.rvm/rubies/ruby-3.2.2/share/ri/3.2.0/system .
+  class DocStore
+    def initialize
+      @cache = {}
+      @mutex = Mutex.new
+      @driver = :unloaded
+    end
+
+    def lookup(*names)
+      names.compact.uniq.each do |name|
+        doc = @mutex.synchronize { @cache[name] }
+        unless @mutex.synchronize { @cache.key?(name) }
+          doc = fetch(name)
+          @mutex.synchronize { @cache[name] = doc }
+        end
+        return doc if doc && !doc.empty?
+      end
+      nil
+    end
+
+    private
+
+    def fetch(name)
+      doc = name.match?(/[#.]/) ? driver_fetch(name) : nil
+      doc || shell_fetch(name)
+    end
+
+    def driver_fetch(name)
+      d = driver
+      return nil unless d
+
+      out = RDoc::Markup::Document.new
+      @mutex.synchronize { d.add_method(out, name.sub('.', '::')) }
+      text = out.accept(RDoc::Markup::ToMarkdown.new)
+      text && !text.strip.empty? ? text.strip[0, 4000] : nil
+    rescue StandardError
+      nil # NotFoundError or store hiccup — fall through to `ri` CLI
+    end
+
+    def driver
+      @mutex.synchronize do
+        if @driver == :unloaded
+          @driver = begin
+            require 'rdoc'
+            RDoc::RI::Driver.new(RDoc::RI::Driver.default_options)
+          rescue StandardError, LoadError
+            nil
+          end
+        end
+        @driver
+      end
+    end
+
+    def shell_fetch(name)
+      out = IO.popen(['ri', '-T', '--format=markdown', name], err: File::NULL, &:read)
+      return nil unless $?.success?
+
+      out = out.strip
+      out.empty? ? nil : out[0, 4000]
+    rescue StandardError
+      nil
+    end
+  end
+
+  DOCS = DocStore.new
+
+  # -------------------------------------------------------------------- http
+
+  class Server
+    PUBLIC = File.join(ROOT, 'public')
+    VENDOR = File.join(PUBLIC, 'vendor')
+    STATIC_CONTENT_TYPES = {
+      '.js' => 'text/javascript; charset=utf-8',
+      '.css' => 'text/css; charset=utf-8',
+      '.ttf' => 'font/ttf',
+    }.freeze
+
+    def initialize(port)
+      @port = port
+    end
+
+    def start
+      server = TCPServer.new('127.0.0.1', @port)
+      url = "http://localhost:#{@port}/"
+      url += "?token=#{RubyTestIDE::TOKEN}" unless RubyTestIDE::AUTH_DISABLED
+      puts "RubyTestIDE listening on #{url} (ruby #{RUBY_VERSION})"
+      # This line is the only way to learn the token when stdout is
+      # redirected to a file — puts alone can sit in a buffer indefinitely
+      # on a long-running server that never exits on its own.
+      $stdout.flush
+      if RubyTestIDE::AUTH_DISABLED
+        warn 'WARNING: started with --no-auth — anyone who can reach this port can execute code as you.'
+      end
+      loop do
+        client = server.accept
+        Thread.new(client) do |sock|
+          handle_client(sock)
+        rescue StandardError => e
+          warn "client error: #{e.class}: #{e.message}"
+        ensure
+          begin
+            sock.close
+          rescue StandardError
+            nil
+          end
+        end
+      end
+    end
+
+    def handle_client(sock)
+      request_line = sock.gets
+      return unless request_line
+
+      verb, path, = request_line.split
+      headers = {}
+      while (line = sock.gets) && line != "\r\n"
+        k, v = line.split(': ', 2)
+        headers[k.to_s.downcase] = v.to_s.strip
+      end
+      body = headers['content-length'] ? sock.read(headers['content-length'].to_i) : ''
+
+      status, ctype, payload, cache = route(verb, path, body, headers)
+      sock.write("HTTP/1.1 #{status}\r\n" \
+                 "Content-Type: #{ctype}\r\n" \
+                 "Content-Length: #{payload.bytesize}\r\n" \
+                 "Cache-Control: #{cache || 'no-store'}\r\n" \
+                 "Connection: close\r\n\r\n")
+      sock.write(payload)
+    end
+
+    def route(verb, full_path, body, headers)
+      path, query = full_path.to_s.split('?', 2)
+      params = query ? URI.decode_www_form(query).to_h : {}
+
+      # /health (used by process supervisors / readiness probes) and
+      # /vendor/* (the vendored Monaco library — no user data) never need
+      # the token. Everything else does: this server evaluates arbitrary
+      # code and reads/writes the workspace on request.
+      case [verb, path]
+      in ['GET', '/health']
+        return ['200 OK', 'application/json', '{"ok":true}']
+      in ['GET', %r{\A/vendor/}]
+        return serve_static(path)
+      else
+        # falls through to the auth-gated routes below
+      end
+
+      token = headers['x-ruby-test-ide-token'] || params['token']
+      return unauthorized(html: path == '/' || path == '/index.html') unless RubyTestIDE.token_matches?(token)
+
+      case [verb, path]
+      in ['GET', '/'] | ['GET', '/index.html']
+        # Cache-bust vendored assets with the gem version: serve_static sets
+        # a 1-year immutable cache, so a stale browser cache across a gem
+        # upgrade would otherwise serve last version's Monaco forever. The
+        # token is only embedded here because we've just verified it above —
+        # the client then sends it back as a header on every /api/* call.
+        html = File.read(File.join(PUBLIC, 'index.html'))
+                   .gsub('__RTI_VERSION__', RubyTestIDE::VERSION)
+                   .gsub('__RTI_TOKEN__', RubyTestIDE::TOKEN)
+        ['200 OK', 'text/html; charset=utf-8', html]
+      in ['GET', '/api/files']        then json { { 'files' => RubyTestIDE.workspace_files } }
+      in ['GET', '/api/file']         then json { api_read_file(params) }
+      in ['POST', '/api/file']        then json { api_save_file(parse(body)) }
+      in ['POST', '/api/complete']    then json { api_complete(parse(body)) }
+      in ['POST', '/api/hover']       then json { api_hover(parse(body)) }
+      in ['POST', '/api/diagnostics'] then json { api_diagnostics(parse(body)) }
+      in ['POST', '/api/run']         then json { api_run(parse(body)) }
+      in ['POST', '/api/learn']       then json { api_learn }
+      else
+        ['404 Not Found', 'text/plain', 'not found']
+      end
+    rescue Errno::ENOENT
+      ['404 Not Found', 'text/plain', 'not found']
+    end
+
+    def unauthorized(html:)
+      if html
+        ['401 Unauthorized', 'text/plain; charset=utf-8',
+         "401 Unauthorized\n\n" \
+         "Missing or invalid token. Open the URL printed in the terminal " \
+         "where you ran ruby-test-ide (it includes ?token=...).\n"]
+      else
+        ['401 Unauthorized', 'application/json; charset=utf-8',
+         JSON.generate('error' => 'unauthorized: missing or invalid token')]
+      end
+    end
+
+    def parse(body)
+      JSON.parse(body.to_s)
+    rescue StandardError
+      {}
+    end
+
+    # Serves vendored front-end assets (Monaco) so the IDE works with no
+    # internet access beyond the initial `gem install`. Content is fixed at
+    # gem-build time and keyed by RubyTestIDE::VERSION in the URL the
+    # browser requests, so it's safe to cache indefinitely.
+    def serve_static(path)
+      rel = path.delete_prefix('/vendor/')
+      abs = File.expand_path(File.join(VENDOR, rel))
+      return ['404 Not Found', 'text/plain', 'not found'] unless abs.start_with?("#{VENDOR}/") && File.file?(abs)
+
+      ctype = STATIC_CONTENT_TYPES[File.extname(abs)] || 'application/octet-stream'
+      ['200 OK', ctype, File.binread(abs), 'public, max-age=31536000, immutable']
+    end
+
+    def json
+      payload = yield
+      ['200 OK', 'application/json; charset=utf-8', JSON.generate(payload)]
+    rescue StandardError => e
+      ['500 Internal Server Error', 'application/json',
+       JSON.generate('error' => "#{e.class}: #{e.message}")]
+    end
+
+    # ---- endpoints
+
+    def api_read_file(params)
+      abs = RubyTestIDE.workspace_path(params['path'])
+      raise Errno::ENOENT, params['path'] unless File.file?(abs)
+
+      { 'path' => params['path'], 'content' => File.read(abs) }
+    end
+
+    def api_save_file(req)
+      abs = RubyTestIDE.workspace_path(req['path'])
+      require 'fileutils'
+      FileUtils.mkdir_p(File.dirname(abs))
+      File.write(abs, req['content'].to_s)
+      { 'ok' => true, 'path' => req['path'], 'size' => File.size(abs) }
+    end
+
+    # The file's real location, so the worker can chdir there and make
+    # require_relative resolve against the workspace.
+    def file_context(req)
+      abs = RubyTestIDE.workspace_path(req['path'])
+      { 'path' => abs, 'dir' => File.dirname(abs), 'root' => WORKSPACE }
+    rescue ArgumentError
+      {}
+    end
+
+    def api_complete(req)
+      code = req['code'].to_s
+      lines = code.split("\n", -1)
+      line = req['line'].to_i          # 1-based (monaco convention)
+      column = req['column'].to_i      # 1-based
+      before = (lines[line - 1] || '')[0, [column - 1, 0].max]
+      receiver, prefix = RubyTestIDE.split_target(before.to_s)
+      code_before = lines[0, line - 1].join("\n")
+
+      result = RubyTestIDE.run_worker(
+        { 'op' => 'complete', 'code_before' => code_before,
+          'receiver' => receiver, 'prefix' => prefix }.merge(file_context(req)),
+        timeout: RUNNER_TIMEOUT
+      )
+      result.merge('receiver' => receiver, 'prefix' => prefix)
+    end
+
+    def api_hover(req)
+      code = req['code'].to_s
+      lines = code.split("\n", -1)
+      line = req['line'].to_i
+      word = req['word'].to_s
+      word_start = req['wordStartColumn'].to_i
+      before_word = (lines[line - 1] || '')[0, [word_start - 1, 0].max].to_s
+
+      receiver = nil
+      if before_word.end_with?('.') && !before_word.end_with?('..')
+        start = RubyTestIDE.receiver_start(before_word, before_word.length - 1)
+        receiver = before_word[start...-1]
+        receiver = nil if receiver.to_s.strip.empty?
+      end
+      # For hover, context = everything up to and including the previous line,
+      # plus the current line itself when it parses on its own.
+      code_before = lines[0, line - 1].join("\n")
+
+      result = RubyTestIDE.run_worker(
+        { 'op' => 'hover', 'code_before' => code_before,
+          'receiver' => receiver, 'name' => word }.merge(file_context(req)),
+        timeout: RUNNER_TIMEOUT
+      )
+
+      if (src = result['source']) && src.start_with?("#{WORKSPACE}/")
+        result['source_rel'] = src.delete_prefix("#{WORKSPACE}/")
+      end
+      if result['kind'] == 'method'
+        result['doc'] = DOCS.lookup(
+          "#{result['owner']}##{word}",
+          "#{result['receiver_class']}##{word}",
+          "#{result['owner']}.#{word}"
+        )
+      elsif %w[variable constant class].include?(result['kind'])
+        result['doc'] = DOCS.lookup(result['kind'] == 'class' ? result['name'] : result['class'])
+      end
+      result
+    end
+
+    def api_diagnostics(req)
+      { 'diagnostics' => RubyTestIDE.syntax_diagnostics(req['code'].to_s) }
+    end
+
+    def api_run(req)
+      RubyTestIDE.run_worker({ 'op' => 'run', 'code' => req['code'].to_s }.merge(file_context(req)),
+                         timeout: RUNNER_TIMEOUT)
+    end
+
+    # Run the configured learn commands (any test framework or script) with
+    # the observer preloaded, then persist the merged type observations —
+    # completion/hover consult these when live eval can't help.
+    def api_learn
+      config = RubyTestIDE.load_config
+      return { 'error' => config['config_error'] } if config['config_error']
+
+      commands = Array(config['learn'] || RubyTestIDE.default_learn_commands).map(&:to_s)
+      if commands.empty?
+        return { 'error' => 'nothing to run: add learn: commands to ' \
+                            '.ruby_ide.yaml or create test/**/*_test.rb / spec files' }
+      end
+      timeout = (config['timeout'] || LEARN_TIMEOUT).to_i.clamp(1, 600)
+
+      require 'tmpdir'
+      require 'fileutils'
+      merged = nil
+      results = nil
+      Dir.mktmpdir('ruby-ide-obs') do |obs_dir|
+        results = commands.map { |cmd| RubyTestIDE.run_learn_command(cmd, obs_dir, timeout) }
+        merged = RubyTestIDE.merge_observations(Dir.glob(File.join(obs_dir, 'obs-*.json')))
+      end
+      unless merged.empty?
+        FileUtils.mkdir_p(File.dirname(OBSERVATIONS))
+        File.write(OBSERVATIONS, JSON.generate(merged))
+      end
+      { 'commands' => results,
+        'passed' => results.all? { |r| r['ok'] },
+        'methods_observed' => merged.size }
+    end
+  end
+end
+
+module RubyTestIDE
+  def self.start(port: 3000)
+    seed_workspace
+    Server.new(port).start
+  end
+end