coatepec 0.4.0

data/lib/coatepec/mcp/tools.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module MCP
+    # The `rails_spec_run` MCP tool: runs targeted RSpec examples against
+    # the warm test worker and returns a structured pass/fail result.
+    class SpecRunTool < ::MCP::Tool
+      tool_name "rails_spec_run"
+      description "Run targeted RSpec examples against a warm, isolated Rails test worker"
+      annotations(read_only_hint: false, destructive_hint: true, idempotent_hint: false, open_world_hint: true)
+      input_schema(
+        properties: {
+          paths: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 100 },
+          example: { type: %w[string null] },
+          seed: { type: %w[integer null], minimum: 0, maximum: 65_535 },
+          fail_fast: { type: "boolean" },
+          timeout_seconds: { type: "integer", minimum: 1, maximum: 900 }
+        },
+        required: ["paths"],
+        additionalProperties: false
+      )
+
+      class << self
+        # rubocop:disable Metrics/ParameterLists -- mirrors the tool's own input_schema
+        # (paths/example/seed/fail_fast/timeout_seconds) plus the MCP-framework-injected
+        # server_context; splitting it would fight the ::MCP::Tool#call contract.
+        def call(paths:, server_context:, example: nil, seed: nil, fail_fast: false, timeout_seconds: 120)
+          # rubocop:enable Metrics/ParameterLists
+          started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          data = server_context[:worker_manager].run_spec(
+            paths: paths, example: example, seed: seed, fail_fast: fail_fast, timeout_seconds: timeout_seconds
+          )
+          Response.ok(data: data, meta: meta_for(server_context, started_at))
+        rescue Coatepec::Error => e
+          Response.error(e)
+        end
+
+        private
+
+        def meta_for(server_context, started_at)
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
+          { project_root: server_context[:project_root], environment: "test", duration_ms: duration_ms }
+        end
+      end
+    end
+
+    # The `rails_runtime_status` MCP tool: reports the test worker's Ruby/Rails
+    # versions, PID, boot_id, and lifecycle state. Worker::Server#handle boots
+    # the Rails runtime before dispatching any command, so the first call to
+    # this tool starts (and blocks on) a full Rails boot just like a spec run.
+    class RuntimeStatusTool < ::MCP::Tool
+      tool_name "rails_runtime_status"
+      description "Report the Coatepec test worker's identity and boot status " \
+                  "(boots the warm worker if it is not up yet)"
+      annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
+      input_schema(properties: {}, required: [], additionalProperties: false)
+
+      class << self
+        def call(server_context:)
+          started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          data = server_context[:worker_manager].status
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
+          Response.ok(data: data,
+                      meta: { project_root: server_context[:project_root], environment: "test",
+                              duration_ms: duration_ms })
+        rescue Coatepec::Error => e
+          Response.error(e)
+        end
+      end
+    end
+
+    # The `rails_routes` MCP tool: lists/filters/paginates the target
+    # Rails app's routes.
+    class RoutesTool < ::MCP::Tool
+      tool_name "rails_routes"
+      description "Return a bounded, filterable list of the Rails app's routes"
+      annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
+      input_schema(
+        properties: {
+          query: { type: %w[string null] },
+          limit: { type: "integer", minimum: 1, maximum: 200 },
+          offset: { type: "integer", minimum: 0 }
+        },
+        required: [],
+        additionalProperties: false
+      )
+
+      class << self
+        def call(server_context:, query: nil, limit: 50, offset: 0)
+          started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          data = server_context[:worker_manager].routes(query: query, limit: limit, offset: offset)
+          Response.ok(data: data, meta: meta_for(server_context, started_at))
+        rescue Coatepec::Error => e
+          Response.error(e)
+        end
+
+        private
+
+        def meta_for(server_context, started_at)
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
+          { project_root: server_context[:project_root], environment: "test", duration_ms: duration_ms }
+        end
+      end
+    end
+
+    # The `rails_model` MCP tool: returns an ActiveRecord model's schema,
+    # associations, validators, and enums.
+    class ModelTool < ::MCP::Tool
+      tool_name "rails_model"
+      description "Return bounded ActiveRecord schema, associations, validators, and enums for a model, " \
+                  "without row data"
+      annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
+      input_schema(
+        properties: {
+          name: { type: "string", pattern: '^[A-Z]\w*(?:::[A-Z]\w*)*$' }
+        },
+        required: ["name"],
+        additionalProperties: false
+      )
+
+      class << self
+        def call(name:, server_context:)
+          started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          data = server_context[:worker_manager].model(name: name)
+          Response.ok(data: data, meta: meta_for(server_context, started_at))
+        rescue Coatepec::Error => e
+          Response.error(e)
+        end
+
+        private
+
+        def meta_for(server_context, started_at)
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
+          { project_root: server_context[:project_root], environment: "test", duration_ms: duration_ms }
+        end
+      end
+    end
+  end
+end

data/lib/coatepec/mcp.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "mcp"
+require "coatepec"
+require_relative "mcp/response"
+require_relative "mcp/tools"
+
+module Coatepec
+  # Wires the `rails_spec_run`, `rails_runtime_status`, `rails_routes`, and
+  # `rails_model` tools into an `::MCP::Server` instance backed by the given
+  # project's worker manager.
+  module MCP
+    def self.build_server(project:, worker_manager:)
+      ::MCP::Server.new(
+        name: "coatepec",
+        version: Coatepec::VERSION,
+        tools: [SpecRunTool, RuntimeStatusTool, RoutesTool, ModelTool],
+        server_context: { worker_manager: worker_manager, project_root: project.root }
+      )
+    end
+  end
+end

data/lib/coatepec/project.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Coatepec
+  # A Rails application checkout rooted at an absolute path (must contain a
+  # Gemfile); knows where its own and pack/engine/gem spec directories live.
+  class Project
+    attr_reader :root
+
+    def initialize(root)
+      @root = File.expand_path(root)
+
+      return if File.exist?(File.join(@root, "Gemfile"))
+
+      raise Coatepec::Error.new(:project_not_found, "No Gemfile found at #{@root}")
+    end
+
+    def spec_root_candidates
+      [
+        File.join(root, "spec"),
+        *Dir.glob(File.join(root, "packs/*/spec")),
+        *Dir.glob(File.join(root, "engines/*/spec")),
+        *Dir.glob(File.join(root, "gems/*/spec"))
+      ].select { |path| File.directory?(path) }
+    end
+
+    def config
+      @config ||= ProjectConfig.new(root)
+    end
+  end
+end

data/lib/coatepec/project_config.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Coatepec
+  # Optional per-project settings loaded from `.coatepec.yml` at the
+  # project root. A missing file means every setting takes its default --
+  # this file has never been required for Coatepec to work.
+  class ProjectConfig
+    def initialize(root)
+      @data = load(root)
+    end
+
+    def macos_fork?
+      !!@data["macos_fork"]
+    end
+
+    def macos_fork_unsafe_gems
+      Array(@data["macos_fork_unsafe_gems"]).map(&:to_s)
+    end
+
+    private
+
+    def load(root)
+      path = File.join(root, ".coatepec.yml")
+      return {} unless File.exist?(path)
+
+      parse(File.read(path))
+    # Psych::Exception, not just SyntaxError: safe_load also raises
+    # AliasesNotEnabled (anchors/aliases) and DisallowedClass (e.g. an
+    # unquoted date), which are equally the user's config being wrong.
+    rescue Psych::Exception => e
+      raise Coatepec::Error.new(:invalid_config, "Invalid .coatepec.yml: #{e.message}")
+    end
+
+    def parse(text)
+      data = YAML.safe_load(text)
+      return {} if data.nil?
+      return data if data.is_a?(Hash)
+
+      raise Coatepec::Error.new(:invalid_config, ".coatepec.yml must be a YAML mapping")
+    end
+  end
+end

data/lib/coatepec/protocol.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Coatepec
+  # Reads and writes the newline-delimited JSON (NDJSON) messages exchanged
+  # with the test worker over its private stdio pipe.
+  class Protocol
+    class FramingError < StandardError; end
+
+    def initialize(input:, output:)
+      @input = input
+      @output = output
+    end
+
+    def write(message)
+      @output.puts(JSON.generate(message))
+      @output.flush
+    end
+
+    def read
+      line = @input.gets
+      return nil if line.nil?
+
+      JSON.parse(line, symbolize_names: true)
+    rescue JSON::ParserError => e
+      raise FramingError, "Malformed NDJSON message: #{e.message}"
+    end
+  end
+end

data/lib/coatepec/spec/fork_strategy.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module Spec
+    # Runs RSpec in a `Process.fork`ed child (Linux only): cheap and reuses
+    # the warm worker's loaded Rails boot, but isolated from the parent's
+    # ActiveRecord connections and global state.
+    class ForkStrategy < ProcessStrategy
+      private
+
+      def start(full_args, out_w, err_w)
+        Process.fork do
+          Process.setpgid(0, 0)
+          redirect_output(out_w, err_w)
+          # Forked children must not share the parent's live DB sockets.
+          ActiveRecord::Base.connection_handler.clear_all_connections! if defined?(ActiveRecord::Base)
+
+          status = RSpec::Core::Runner.run(full_args, $stderr, $stdout)
+          $stdout.flush
+          $stderr.flush
+          Kernel.exit!(status)
+        end
+      end
+
+      # rubocop:disable Style/GlobalStdStream -- exe/coatepec-worker aliases $stdout to
+      # $stderr so Rails boot output can't corrupt the NDJSON protocol on fd 1. That
+      # makes $stdout/$stderr the same object here, so only the STDOUT/STDERR
+      # constants can move the underlying fds -- and fd 1 must move off the
+      # protocol pipe.
+      def redirect_output(out_w, err_w)
+        STDOUT.reopen(out_w)
+        STDERR.reopen(err_w)
+        $stdout = STDOUT
+        $stderr = STDERR
+      end
+      # rubocop:enable Style/GlobalStdStream
+    end
+  end
+end

data/lib/coatepec/spec/guarded_fork_strategy.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module Spec
+    # Opt-in macOS fork strategy: attempts Process.fork like ForkStrategy
+    # (reusing the warm worker's boot), but only after two cheap guard
+    # checks pass, and transparently falls back to a fresh SpawnStrategy
+    # run -- for this call only -- when a guard fails or the forked child
+    # crashes. See docs/superpowers/specs/2026-07-31-macos-guarded-fork-design.md.
+    class GuardedForkStrategy < ForkStrategy
+      # Intentionally empty at ship time: the one documented crash this
+      # guards against didn't name a specific culprit gem, just "something
+      # ObjC-initializing on another thread." This is an extension point
+      # for real incidents (refine via a project's own .coatepec.yml
+      # macos_fork_unsafe_gems), not a researched-and-complete list.
+      BUILTIN_UNSAFE_GEMS = [].freeze
+
+      # Live thread count is allowed to exceed the post-boot baseline by
+      # this much before the guard treats it as "something is mid-init."
+      THREAD_COUNT_TOLERANCE = 1
+
+      CRASH_SIGNAL_NAMES = %w[ABRT SEGV BUS].freeze
+
+      # A crash retry shares one timeout budget with the fork attempt that
+      # preceded it: WorkerManager only gives the whole dispatch
+      # timeout_seconds + 10 before Client#read_response raises
+      # DisconnectedError and the warm worker is restarted from scratch --
+      # exactly the boot this feature exists to preserve. The floor keeps a
+      # nearly-exhausted budget from turning the retry into a guaranteed
+      # timeout kill; a few seconds is enough for a fast spec to still land.
+      MIN_RETRY_TIMEOUT_SECONDS = 5
+
+      # The crashed child's stderr carries the macOS crash report -- the only
+      # evidence that could ever populate BUILTIN_UNSAFE_GEMS from a real
+      # incident. Kept far below Result::MAX_OUTPUT_BYTES because it rides
+      # along with a whole second result inside MCP::Response's 1 MiB cap.
+      MAX_CRASH_STDERR_BYTES = 4 * 1024
+
+      def initialize(project_root, project: nil, rails_runtime: nil)
+        super
+        @spawn_strategy = SpawnStrategy.new(project_root)
+      end
+
+      def run(args, timeout_seconds)
+        return fallback_result(args, timeout_seconds, "spawn_fallback") unless guard_passes?
+
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        begin
+          result = super
+        rescue SystemCallError
+          # Process.fork itself failed (Errno::EAGAIN/ENOMEM under
+          # process-table pressure), so no child was ever produced -- from the
+          # caller's side that is indistinguishable from a failed guard, hence
+          # the same mode. Opting into macos_fork must never surface an error
+          # that plain SpawnStrategy wouldn't have.
+          return fallback_result(args, timeout_seconds, "spawn_fallback")
+        end
+        return result.merge(execution_mode: "fork") unless crashed?(result)
+
+        retry_after_crash(args, timeout_seconds, started_at, result)
+      end
+
+      private
+
+      def retry_after_crash(args, timeout_seconds, started_at, crashed)
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+        remaining = [timeout_seconds - elapsed, MIN_RETRY_TIMEOUT_SECONDS].max
+
+        fallback_result(args, remaining, "spawn_after_crash")
+          .merge(crashed_fork_stderr: crash_diagnostics(crashed))
+      end
+
+      # Keeps the tail, matching Result#read_bounded: a crash report's tail is
+      # where the signal and backtrace land.
+      def crash_diagnostics(result)
+        text = result[:stderr].to_s
+        return text unless text.bytesize > MAX_CRASH_STDERR_BYTES
+
+        text.byteslice(-MAX_CRASH_STDERR_BYTES, MAX_CRASH_STDERR_BYTES)
+      end
+
+      def fallback_result(args, timeout_seconds, mode)
+        @spawn_strategy.run(args, timeout_seconds).merge(execution_mode: mode)
+      end
+
+      def guard_passes?
+        thread_count_ok? && !unsafe_gems_loaded?
+      end
+
+      def thread_count_ok?
+        baseline = @rails_runtime&.post_boot_thread_count
+        return true unless baseline
+
+        Thread.list.count <= baseline + THREAD_COUNT_TOLERANCE
+      end
+
+      def unsafe_gems_loaded?
+        denylist = BUILTIN_UNSAFE_GEMS + configured_unsafe_gems
+        return false if denylist.empty?
+
+        loaded = @rails_runtime&.loaded_gem_names || []
+        !(denylist & loaded).empty?
+      end
+
+      def configured_unsafe_gems
+        @project&.config&.macos_fork_unsafe_gems || []
+      end
+
+      def crashed?(result)
+        return false unless result[:signaled]
+
+        CRASH_SIGNAL_NAMES.any? { |name| Signal.list[name] == result[:termsig] }
+      end
+    end
+  end
+end

data/lib/coatepec/spec/path_policy.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module Spec
+    # Validates rails_spec_run's `paths` selectors against the allowed spec
+    # roots before any RSpec process is started, rejecting absolute paths,
+    # `..` traversal, symlink escapes, non-`_spec.rb` files, and oversized
+    # selector lists.
+    class PathPolicy
+      MAX_SELECTORS = 100
+
+      def initialize(project)
+        @project = project
+      end
+
+      def validate!(selectors)
+        raise Coatepec::Error.new(:invalid_spec_path, "No spec paths given") if selectors.nil? || selectors.empty?
+        if selectors.size > MAX_SELECTORS
+          raise Coatepec::Error.new(:invalid_spec_path, "At most #{MAX_SELECTORS} spec paths are allowed")
+        end
+
+        selectors.map { |selector| validate_one(selector) }
+      end
+
+      private
+
+      def validate_one(selector)
+        path_part, line_part = selector.to_s.split(":", 2)
+        reject_shape!(selector, path_part)
+        reject_line_part!(selector, line_part) if line_part
+
+        real_path = resolve_real_path!(selector, path_part)
+        reject_escape!(selector, real_path)
+        reject_wrong_kind!(selector, real_path)
+
+        line_part ? "#{path_part}:#{line_part}" : path_part
+      end
+
+      def resolve_real_path!(selector, path_part)
+        full_path = File.expand_path(path_part, @project.root)
+        unless File.exist?(full_path)
+          raise Coatepec::Error.new(:invalid_spec_path,
+                                    "Spec path does not exist: #{selector}")
+        end
+
+        File.realpath(full_path)
+      rescue Coatepec::Error
+        raise
+      rescue ArgumentError, Errno::EACCES, Errno::ENOENT, Errno::ENOTDIR => e
+        raise Coatepec::Error.new(:invalid_spec_path, "Invalid spec path: #{selector} (#{e.class.name})")
+      end
+
+      def reject_shape!(selector, path_part)
+        raise Coatepec::Error.new(:invalid_spec_path, "Blank selector") if path_part.to_s.strip.empty?
+        if path_part.start_with?("/")
+          raise Coatepec::Error.new(:invalid_spec_path,
+                                    "Absolute paths are not allowed: #{selector}")
+        end
+        return unless path_part.split("/").include?("..")
+
+        raise Coatepec::Error.new(:invalid_spec_path, "Path traversal is not allowed: #{selector}")
+      end
+
+      def reject_line_part!(selector, line_part)
+        return if line_part =~ /\A\d+\z/
+
+        raise Coatepec::Error.new(:invalid_spec_path, "Line number must be digits only: #{selector}")
+      end
+
+      def reject_escape!(selector, real_path)
+        real_root = File.realpath(@project.root)
+        return if real_path == real_root || real_path.start_with?("#{real_root}/")
+
+        raise Coatepec::Error.new(:invalid_spec_path, "Spec path escapes the project root: #{selector}")
+      end
+
+      def reject_wrong_kind!(selector, real_path)
+        return if under_allowed_root?(real_path) && (File.directory?(real_path) || real_path.end_with?("_spec.rb"))
+
+        raise Coatepec::Error.new(:invalid_spec_path,
+                                  "Spec path is not an allowed spec root or _spec.rb file: #{selector}")
+      end
+
+      def under_allowed_root?(real_path)
+        @project.spec_root_candidates.any? do |candidate|
+          real_candidate = File.realpath(candidate)
+          real_path == real_candidate || real_path.start_with?("#{real_candidate}/")
+        end
+      end
+    end
+  end
+end

data/lib/coatepec/spec/process_strategy.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+module Coatepec
+  module Spec
+    # Shared child-process lifecycle for running an isolated RSpec run: spawns
+    # (via a subclass's #start), reaps with a timeout budget (TERM then KILL
+    # on overrun), and hands the captured output/JSON to Result. Subclasses
+    # (ForkStrategy, SpawnStrategy) only implement how the child is started.
+    class ProcessStrategy
+      def initialize(project_root, project: nil, rails_runtime: nil)
+        @project_root = project_root
+        @project = project
+        @rails_runtime = rails_runtime
+      end
+
+      def run(args, timeout_seconds)
+        out_r, out_w = IO.pipe
+        err_r, err_w = IO.pipe
+        json_path = Tempfile.create(["coatepec-rspec", ".json"], &:path)
+
+        pid = start_or_release(args, out_w, err_w, json_path, [out_r, err_r])
+        [out_w, err_w].each(&:close)
+
+        reap(pid, out_r, err_r, timeout_seconds, json_path)
+      end
+
+      private
+
+      # Subclasses start a process and return its pid; RSpec's own output
+      # must be wired to out_w/err_w.
+      def start(_full_args, _out_w, _err_w)
+        raise NotImplementedError, "#{self.class} must implement #start"
+      end
+
+      # A failed #start (Process.fork can raise Errno::EAGAIN/ENOMEM outright)
+      # leaves no child to reap, so the fds and tempfile #reap would have
+      # released have to be freed here. The original exception still reaches
+      # the caller -- only GuardedForkStrategy intercepts it to fall back.
+      def start_or_release(args, out_w, err_w, json_path, read_ends)
+        start(args + json_format_args(json_path), out_w, err_w)
+      rescue StandardError
+        ([out_w, err_w] + read_ends).each { |io| io.close unless io.closed? }
+        File.delete(json_path) if File.exist?(json_path)
+        raise
+      end
+
+      def json_format_args(json_path)
+        ["--format", "progress", "--format", "json", "--out", json_path]
+      end
+
+      def reap(pid, out_r, err_r, timeout_seconds, json_path)
+        status = wait_with_timeout(pid, timeout_seconds)
+        result = Result.build(pid: pid, status: status, out_r: out_r, err_r: err_r, json_path: json_path)
+        [out_r, err_r].each(&:close)
+        result
+      ensure
+        File.delete(json_path) if File.exist?(json_path)
+      end
+
+      def wait_with_timeout(pid, timeout_seconds)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_seconds
+        poll_until(pid, deadline) || terminate_and_wait(pid)
+      end
+
+      def poll_until(pid, deadline)
+        loop do
+          _pid, status = Process.waitpid2(pid, Process::WNOHANG)
+          return status if status
+          return nil if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+
+          sleep 0.05
+        end
+      end
+
+      def terminate_and_wait(pid)
+        status = terminate(pid)
+        return status if status
+
+        _pid, status = Process.waitpid2(pid)
+        status
+      rescue Errno::ECHILD
+        nil
+      end
+
+      # TERM, wait briefly, then KILL — this needs the multi-step escalation
+      # so a hung child gets a graceful chance before the hard kill. If the
+      # WNOHANG poll below reaps the child, that reap is the *only* wait
+      # this pid will ever satisfy — the status must be returned here
+      # rather than discarded, or the caller's follow-up waitpid2 raises
+      # Errno::ECHILD.
+      def terminate(pid)
+        Process.kill("TERM", -pid)
+        3.times do
+          sleep 0.2
+          _pid, status = Process.waitpid2(pid, Process::WNOHANG)
+          return status if status
+        end
+        Process.kill("KILL", -pid)
+        nil
+      rescue Errno::ESRCH
+        nil
+      end
+    end
+  end
+end