coatepec 0.4.0

data/lib/coatepec/spec/result.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Coatepec
+  module Spec
+    # Turns a finished RSpec child process's exit status, captured
+    # stdout/stderr (each capped at MAX_OUTPUT_BYTES), and RSpec's own JSON
+    # formatter output into the flat result hash rails_spec_run returns.
+    module Result
+      MAX_OUTPUT_BYTES = 256 * 1024
+
+      module_function
+
+      def build(pid:, status:, out_r:, err_r:, json_path:)
+        stdout_result = read_bounded(out_r)
+        stderr_result = read_bounded(err_r)
+        summary = read_summary(json_path)
+
+        base(pid, status, stdout_result, stderr_result).merge(
+          summary: summary && summary_fields(summary),
+          examples: (summary&.fetch("examples", []) || []).first(500).map { |e| example_fields(e) }
+        )
+      end
+
+      # rubocop:disable Metrics/MethodLength -- one flat hash literal mapping
+      # Process::Status/captured-output fields to the result payload's own
+      # field names; splitting it would scatter that 1:1 mapping across
+      # methods for no readability gain.
+      def base(pid, status, stdout_result, stderr_result)
+        {
+          status: status.exited? && status.exitstatus.zero? ? "passed" : "failed",
+          exit_code: status.exitstatus,
+          child_pid: pid,
+          signaled: status.signaled?,
+          termsig: status.termsig,
+          stopsig: status.stopsig,
+          coredump: status.respond_to?(:coredump?) ? status.coredump? : false,
+          stdout: stdout_result[:text],
+          stdout_truncated: stdout_result[:truncated],
+          stderr: stderr_result[:text],
+          stderr_truncated: stderr_result[:truncated]
+        }
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      def read_summary(json_path)
+        return nil unless File.exist?(json_path) && !File.empty?(json_path)
+
+        JSON.parse(File.read(json_path))
+      end
+
+      def summary_fields(summary)
+        {
+          example_count: summary.dig("summary", "example_count"),
+          failure_count: summary.dig("summary", "failure_count"),
+          duration: summary.dig("summary", "duration")
+        }
+      end
+
+      def example_fields(example)
+        {
+          id: example["id"],
+          description: example["full_description"],
+          status: example["status"],
+          file_path: example["file_path"],
+          line_number: example["line_number"]
+        }
+      end
+
+      def read_bounded(io)
+        data = io.read.to_s
+        truncated = data.bytesize > MAX_OUTPUT_BYTES
+        data = data.byteslice(-MAX_OUTPUT_BYTES, MAX_OUTPUT_BYTES) if truncated
+        { text: data, truncated: truncated }
+      end
+    end
+  end
+end

data/lib/coatepec/spec/runner.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module Spec
+    # Validates a `rails_spec_run` request's paths, builds the RSpec CLI
+    # args, and delegates to the platform-appropriate process strategy
+    # (fork on Linux, spawn on macOS, or a guarded fork on macOS when the
+    # project opts in via .coatepec.yml).
+    class Runner
+      DEFAULT_TIMEOUT = 120
+
+      def initialize(project_root, rails_runtime: nil)
+        @project_root = project_root
+        @project = Project.new(project_root)
+        @path_policy = PathPolicy.new(@project)
+        @rails_runtime = rails_runtime
+      end
+
+      def run(paths:, example: nil, seed: nil, fail_fast: false, timeout_seconds: DEFAULT_TIMEOUT)
+        require_rspec!
+        selectors = @path_policy.validate!(paths)
+        args = build_args(selectors, example, seed, fail_fast)
+
+        strategy_class.new(@project_root, project: @project, rails_runtime: @rails_runtime).run(args, timeout_seconds)
+      end
+
+      private
+
+      def strategy_class
+        case RbConfig::CONFIG["host_os"]
+        when /linux/ then ForkStrategy
+        # The macos_fork config key governs this whole branch, BSD included --
+        # the name tracks the documented macOS incident, not the platform set.
+        when /darwin|bsd/ then macos_strategy_class
+        else raise Coatepec::Error.new(:unsupported_platform, "Coatepec supports macOS and Linux only")
+        end
+      end
+
+      # Reading @project.config here means an invalid .coatepec.yml only
+      # raises :invalid_config on macOS -- the Linux branch never touches it.
+      # Accepted asymmetry: the file exists to configure this branch.
+      def macos_strategy_class
+        @project.config.macos_fork? ? GuardedForkStrategy : SpawnStrategy
+      end
+
+      def require_rspec!
+        require "rspec/core"
+      rescue LoadError
+        raise Coatepec::Error.new(:unsupported_test_framework, "rspec-rails must be in the application's test group")
+      end
+
+      def build_args(selectors, example, seed, fail_fast)
+        args = selectors.dup
+        args += ["-e", example] if example
+        args += ["--seed", seed.to_s] if seed
+        args << "--fail-fast" if fail_fast
+
+        args
+      end
+    end
+  end
+end

data/lib/coatepec/spec/spawn_strategy.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module Spec
+    # Runs RSpec in a freshly `Process.spawn`ed `bundle exec rspec` (macOS
+    # and any platform without a working fork): slower per run since Rails
+    # boots from scratch, but avoids fork-safety pitfalls.
+    class SpawnStrategy < ProcessStrategy
+      private
+
+      def start(full_args, out_w, err_w)
+        Process.spawn(
+          { "RAILS_ENV" => "test" }, "bundle", "exec", "rspec", *full_args,
+          chdir: @project_root, out: out_w, err: err_w, pgroup: true
+        )
+      end
+    end
+  end
+end

data/lib/coatepec/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Coatepec
+  VERSION = "0.4.0"
+end

data/lib/coatepec/worker/change_detector.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module Worker
+    # Fingerprints Gemfile/Gemfile.lock and boot-relevant files (mtime +
+    # size) so WorkerManager can decide whether a bundle change requires the
+    # whole sidecar to restart, or a boot-file change just the worker.
+    class ChangeDetector
+      BUNDLE_FILES = %w[Gemfile Gemfile.lock].freeze
+      BOOT_FILES = %w[config/boot.rb config/application.rb config/environment.rb config/environments/test.rb].freeze
+
+      def initialize(project_root)
+        @project_root = project_root
+      end
+
+      def snapshot
+        { bundle: fingerprint(BUNDLE_FILES), boot: fingerprint(BOOT_FILES + initializer_files) }
+      end
+
+      def restart_reason(previous_snapshot)
+        current = snapshot
+        return :sidecar_restart_required if current[:bundle] != previous_snapshot[:bundle]
+        return :worker_restart_required if current[:boot] != previous_snapshot[:boot]
+
+        nil
+      end
+
+      private
+
+      def initializer_files
+        Dir.glob(File.join(@project_root, "config/initializers/**/*.rb"))
+           .sort
+           .map { |f| f.delete_prefix("#{@project_root}/") }
+      end
+
+      def fingerprint(relative_paths)
+        relative_paths.each_with_object({}) do |relative_path, acc|
+          full_path = File.join(@project_root, relative_path)
+          acc[relative_path] = File.exist?(full_path) ? [File.mtime(full_path).to_f, File.size(full_path)] : nil
+        end
+      end
+    end
+  end
+end

data/lib/coatepec/worker/client.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "bundler"
+
+module Coatepec
+  module Worker
+    # The parent-process handle to a spawned test worker: owns its pipes,
+    # sends NDJSON requests with a response timeout, and detects when the
+    # worker has died.
+    class Client
+      class DisconnectedError < StandardError; end
+
+      def self.spawn(project_root)
+        new(project_root).tap(&:start)
+      end
+
+      def initialize(project_root)
+        @project_root = project_root
+        @next_id = 0
+      end
+
+      def start
+        to_worker_r, @to_worker_write = IO.pipe
+        @from_worker_read, from_worker_w = IO.pipe
+
+        @pid = spawn_worker(to_worker_r, from_worker_w)
+        to_worker_r.close
+        from_worker_w.close
+        @protocol = Protocol.new(input: @from_worker_read, output: @to_worker_write)
+      end
+
+      def alive?
+        return false unless @pid
+
+        Process.kill(0, @pid)
+        true
+      rescue Errno::ESRCH
+        false
+      end
+
+      def request(command, args, timeout: 30)
+        raise DisconnectedError, "Worker is not running" unless alive?
+
+        id = (@next_id += 1)
+        @protocol.write(id: id, command: command, args: args)
+        message = read_response(id, timeout)
+
+        message[:ok] ? message[:data] : raise_worker_error(message[:error])
+      end
+
+      def stop
+        return unless @pid
+
+        Process.kill("TERM", @pid)
+        Process.wait(@pid)
+      rescue Errno::ESRCH, Errno::ECHILD
+        nil
+      ensure
+        [@to_worker_write, @from_worker_read].each { |io| io && !io.closed? && io.close }
+        @pid = nil
+      end
+
+      private
+
+      def spawn_worker(to_worker_r, from_worker_w)
+        worker_exe = File.expand_path("../../../exe/coatepec-worker", __dir__)
+        lib_path = File.expand_path("../..", __dir__)
+        # If this process is itself running under a Bundler context (e.g. the
+        # host app's own deployment-mode bundle), Bundler.setup has already
+        # narrowed GEM_PATH/RUBYOPT to that bundle's install location. Without
+        # stripping that, the worker -- which needs the target app's own
+        # separately-installed gems -- inherits a GEM_PATH that can't see them
+        # and fails with a spurious Bundler::GemNotFound. with_unbundled_env
+        # also resets RUBYLIB to its pre-Bundler snapshot, so it must be set
+        # explicitly here rather than relying on the caller's environment.
+        Bundler.with_unbundled_env do
+          Process.spawn(
+            { "BUNDLE_GEMFILE" => File.join(@project_root, "Gemfile"), "RUBYLIB" => lib_path },
+            RbConfig.ruby, worker_exe, @project_root,
+            in: to_worker_r, out: from_worker_w, err: :err, chdir: @project_root
+          )
+        end
+      end
+
+      def read_response(id, timeout)
+        ready = IO.select([@from_worker_read], nil, nil, timeout)
+        raise DisconnectedError, "Worker timed out responding" unless ready
+
+        message = @protocol.read
+        raise DisconnectedError, "Worker closed the connection" if message.nil?
+        raise DisconnectedError, "Unexpected response id #{message[:id]} for request #{id}" unless message[:id] == id
+
+        message
+      end
+
+      def raise_worker_error(error)
+        raise Coatepec::Error.new(error[:code].to_sym, error[:message], details: error[:details] || {})
+      end
+    end
+  end
+end

data/lib/coatepec/worker/rails_runtime.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Coatepec
+  module Worker
+    # Boots the fixture/target Rails app under RAILS_ENV=test exactly once
+    # per worker process and reports its identity (pid, boot_id, versions,
+    # lifecycle state) for rails_runtime_status.
+    class RailsRuntime
+      attr_reader :pid, :boot_id, :boot_duration_ms, :ruby_version, :rails_version, :post_boot_thread_count
+
+      def initialize(project_root)
+        @project_root = project_root
+        @booted = false
+      end
+
+      def booted?
+        @booted
+      end
+
+      def boot!
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        ENV["RAILS_ENV"] = "test"
+        force_reloading!
+        require File.join(@project_root, "config/environment")
+        record_boot!(started_at)
+      rescue Coatepec::Error
+        raise
+      rescue StandardError, LoadError => e
+        raise Coatepec::Error.new(:worker_failure, "Rails failed to boot: #{e.message}")
+      end
+
+      def status
+        {
+          pid: pid,
+          boot_id: boot_id,
+          ruby_version: ruby_version,
+          rails_version: rails_version,
+          boot_duration_ms: boot_duration_ms,
+          environment: "test",
+          coatepec_version: Coatepec::VERSION,
+          lifecycle_state: booted? ? "ready" : "not_started"
+        }
+      end
+
+      # Loaded gem names for GuardedForkStrategy's denylist check. RailsRuntime
+      # itself has no notion of macOS or forking -- it only exposes the raw
+      # fact of what's loaded.
+      def loaded_gem_names
+        Gem.loaded_specs.keys.map(&:to_s)
+      end
+
+      private
+
+      # Rails' test environment disables reloading by default, and Zeitwerk
+      # refuses to enable reloading on a loader that's already had #setup
+      # called on it -- which happens automatically, deep inside
+      # Rails.application.initialize!, before any of our own code can run.
+      # The only window to influence this is before the target app's own
+      # config/environment.rb executes: intercept the config setter itself,
+      # so whatever the app's test.rb assigns, reloading still ends up on.
+      #
+      # `require "bundler/setup"` here (before `require "rails"`) is
+      # necessary, not optional: without it, `require "rails"` resolves
+      # whatever Rails version RubyGems activates by default -- not
+      # necessarily the one pinned by the target app's own Gemfile.lock --
+      # and once the wrong version's gems are activated process-wide, the
+      # target app's own later `require "bundler/setup"` (in its
+      # config/boot.rb) raises a Gem::LoadError version conflict instead of
+      # silently no-oping. BUNDLE_GEMFILE is already set to the target app's
+      # Gemfile by the caller (Worker::Client's spawn env) before this
+      # process starts, so this activates the correct version and the app's
+      # own later Bundler.setup call is simply a no-op.
+      def force_reloading!
+        require "bundler/setup"
+        require "rails"
+        return if Rails::Application::Configuration.method_defined?(:coatepec_forces_reloading?)
+
+        Rails::Application::Configuration.prepend(reload_forcing_module)
+        Rails::Application::Configuration.prepend(file_watcher_forcing_module)
+      end
+
+      # `enable_reloading=` is overridden as the modern, documented setter.
+      # `cache_classes=` is also overridden because Rails' own
+      # `enable_reloading=` is implemented as `self.cache_classes = !value`
+      # (see railties' application/configuration.rb) with `cache_classes`
+      # remaining a plain attr_accessor underneath -- so a target app's
+      # config/environments/test.rb using the legacy `config.cache_classes =
+      # true` form would otherwise write that flag directly, bypassing the
+      # `enable_reloading=` override entirely and silently leaving reloading
+      # off.
+      def reload_forcing_module
+        Module.new do
+          def coatepec_forces_reloading? = true
+
+          def enable_reloading=(_value)
+            super(true)
+          end
+
+          def cache_classes=(_value)
+            super(false)
+          end
+        end
+      end
+
+      # Consequence of the override above, and prepended alongside it: with
+      # reloading on, Rails' own finisher now instantiates
+      # `config.file_watcher` -- something that never happened in this process
+      # while the test env kept reloading off. The default
+      # `ActiveSupport::FileUpdateChecker` polls on the calling thread and is
+      # fork-safe, but a target app configuring
+      # `ActiveSupport::EventedFileUpdateChecker` would instead spawn `listen`
+      # background threads *during boot* in the warm worker. On macOS those
+      # are exactly the ObjC-initializing threads GuardedForkStrategy exists
+      # to keep out of a fork -- and because they'd start before
+      # #post_boot_thread_count is sampled, they'd be baked into the guard's
+      # own baseline and sail through its thread-count check unnoticed. So the
+      # watcher is pinned to the polling implementation regardless of what the
+      # app asks for.
+      def file_watcher_forcing_module
+        Module.new do
+          def file_watcher=(_value)
+            super(::ActiveSupport::FileUpdateChecker)
+          end
+        end
+      end
+
+      def record_boot!(started_at)
+        @pid = Process.pid
+        @boot_id = SecureRandom.hex(8)
+        @ruby_version = RUBY_VERSION
+        @rails_version = Rails.version
+        @boot_duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
+        @post_boot_thread_count = Thread.list.count
+        @booted = true
+      end
+    end
+  end
+end

data/lib/coatepec/worker/server.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module Worker
+    # The test worker's message loop: reads NDJSON requests from its parent
+    # over Protocol, lazily boots Rails on first use, dispatches `status`/
+    # `spec_run`, and writes back structured ok/error responses.
+    class Server
+      def initialize(project_root, input:, protocol_output:)
+        @protocol = Protocol.new(input: input, output: protocol_output)
+        @runtime = RailsRuntime.new(project_root)
+        @project_root = project_root
+      end
+
+      def run
+        loop do
+          message = @protocol.read
+          break if message.nil?
+
+          handle(message)
+        end
+      end
+
+      private
+
+      def handle(message)
+        @runtime.boot! unless @runtime.booted?
+
+        data = dispatch(message[:command], message[:args] || {})
+        @protocol.write(id: message[:id], ok: true, data: data)
+      rescue Coatepec::Error => e
+        @protocol.write(id: message[:id], ok: false, error: { code: e.code, message: e.message, details: e.details })
+      rescue StandardError => e
+        @protocol.write(id: message[:id], ok: false, error: { code: :internal_error, message: e.message, details: {} })
+      end
+
+      def dispatch(command, args)
+        Rails.application.reloader.wrap { execute_command(command, args) }
+      end
+
+      def execute_command(command, args)
+        case command
+        when "status" then @runtime.status
+        when "spec_run" then handle_spec_run(args)
+        when "routes" then handle_routes(args)
+        when "model" then handle_model(args)
+        else
+          raise Coatepec::Error.new(:internal_error, "Unknown command #{command}")
+        end
+      end
+
+      def handle_spec_run(args)
+        Spec::Runner.new(@project_root, rails_runtime: @runtime).run(**args.transform_keys(&:to_sym))
+      end
+
+      def handle_routes(args)
+        Introspection::Routes.new(**args.transform_keys(&:to_sym)).call
+      end
+
+      def handle_model(args)
+        Introspection::Model.new(args.transform_keys(&:to_sym)[:name]).call
+      end
+    end
+  end
+end

data/lib/coatepec/worker_manager.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Coatepec
+  # Owns the single warm Worker::Client for a project: lazily starts it,
+  # restarts it when ChangeDetector flags a boot-file change, escalates a
+  # Gemfile change to :sidecar_restart_required, and retries a request once
+  # if the worker had died since the last dispatch.
+  class WorkerManager
+    def initialize(project)
+      @project = project
+      @change_detector = Worker::ChangeDetector.new(project.root)
+      @client = nil
+      @snapshot = nil
+      @lock = Monitor.new
+    end
+
+    def status
+      dispatch("status", {}, timeout: 30)
+    end
+
+    def run_spec(paths:, example:, seed:, fail_fast:, timeout_seconds:)
+      dispatch(
+        "spec_run",
+        { paths: paths, example: example, seed: seed, fail_fast: fail_fast, timeout_seconds: timeout_seconds },
+        timeout: timeout_seconds + 10
+      )
+    end
+
+    def routes(query: nil, limit: 50, offset: 0)
+      dispatch("routes", { query: query, limit: limit, offset: offset }, timeout: 30)
+    end
+
+    def model(name:)
+      dispatch("model", { name: name }, timeout: 30)
+    end
+
+    def stop
+      @lock.synchronize { @client&.stop }
+    end
+
+    private
+
+    def dispatch(command, args, timeout:, retried: false)
+      @lock.synchronize do
+        # The restart check must run against the *pre-existing* snapshot, before
+        # ensure_worker! can re-baseline it by booting a fresh worker: a dead
+        # worker plus a changed Gemfile must still surface
+        # :sidecar_restart_required rather than silently adopting the new bundle.
+        # There is nothing to compare against on the very first dispatch.
+        check_for_restart! if @snapshot
+        ensure_worker!
+        perform(command, args, timeout: timeout, retried: retried)
+      end
+    end
+
+    def perform(command, args, timeout:, retried:)
+      @client.request(command, args, timeout: timeout)
+    rescue Worker::Client::DisconnectedError
+      raise Coatepec::Error.new(:worker_disconnected, "Worker disconnected") if retried
+
+      restart_worker!
+      dispatch(command, args, timeout: timeout, retried: true)
+    end
+
+    def check_for_restart!
+      reason = @change_detector.restart_reason(@snapshot)
+      case reason
+      when :sidecar_restart_required
+        raise Coatepec::Error.new(:sidecar_restart_required, "Gemfile changed; restart Coatepec")
+      when :worker_restart_required
+        restart_worker!
+      end
+    end
+
+    def ensure_worker!
+      restart_worker! unless @client&.alive?
+    end
+
+    def restart_worker!
+      @client&.stop
+      @client = Worker::Client.spawn(@project.root)
+      @snapshot = @change_detector.snapshot
+    end
+  end
+end

data/lib/coatepec.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "coatepec/version"
+require_relative "coatepec/errors"
+require_relative "coatepec/project_config"
+require_relative "coatepec/project"
+require_relative "coatepec/spec/path_policy"
+require_relative "coatepec/protocol"
+require_relative "coatepec/worker/change_detector"
+require_relative "coatepec/worker/client"
+require_relative "coatepec/worker/rails_runtime"
+require_relative "coatepec/introspection/routes"
+require_relative "coatepec/introspection/safe_options"
+require_relative "coatepec/introspection/model"
+require_relative "coatepec/spec/result"
+require_relative "coatepec/spec/process_strategy"
+require_relative "coatepec/spec/fork_strategy"
+require_relative "coatepec/spec/spawn_strategy"
+require_relative "coatepec/spec/guarded_fork_strategy"
+require_relative "coatepec/spec/runner"
+require_relative "coatepec/worker/server"
+require_relative "coatepec/worker_manager"
+
+# Coatepec is a local stdio MCP sidecar that keeps an isolated Rails test
+# worker warm so coding agents can run targeted RSpec examples quickly,
+# without exposing a general Rails console.
+module Coatepec
+end

data/sig/coatepec.rbs

@@ -0,0 +1,4 @@
+module Coatepec
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end