coatepec 0.7.0 → 0.9.0

data/lib/coatepec/mcp/tools.rb

@@ -2,67 +2,83 @@
 
 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.
+    # The `rails_spec_run` MCP tool: runs targeted RSpec examples or Minitest
+    # tests (chosen from the selector paths) 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(
+      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 }
+          timeout_seconds: { type: "integer", minimum: 1, maximum: 900 },
+          include_passing: { type: "boolean" },
+          include_stdout: { type: "string", enum: %w[failures always never] }
         },
         required: ["paths"],
         additionalProperties: false
-      )
+      }.freeze
+
+      # Kept a constant so the vocabulary clause stays readable next to the rest of the description.
+      RSPEC_VOCABULARY =
+        "; results use RSpec vocabulary for both frameworks: a Minitest error is status failed and is " \
+        "counted in summary.failure_count (so it can exceed the failures number Minitest prints in " \
+        "stdout; summary.error_count says how many of those were errors) and a skip is pending" \
+        "; summary.assertion_count is Minitest's assertion total, null for RSpec, as is error_count"
+
+      tool_name "rails_spec_run"
+      description "Run targeted RSpec examples (spec/**/*_spec.rb) or Minitest tests (test/**/*_test.rb) " \
+                  "against a warm, isolated Rails test worker; the framework is chosen from the selector " \
+                  "paths; there is no separate Minitest tool#{RSPEC_VOCABULARY}" \
+                  "; returns only failed and pending examples unless include_passing is true" \
+                  "; failure blocks in stdout that repeat an earlier error are rolled up into one line" \
+                  "; stdout is returned only for failing runs unless include_stdout is \"always\" or \"never\"" \
+                  "; defaults for include_passing, include_stdout and timeout_seconds can be set project-wide " \
+                  "in .coatepec.yml"
+      annotations(read_only_hint: false, destructive_hint: true, idempotent_hint: false, open_world_hint: true)
+      input_schema(**INPUT_SCHEMA)
 
       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
+        def call(paths:, server_context:, example: nil, seed: nil, fail_fast: false, timeout_seconds: nil,
+                 include_passing: nil, include_stdout: nil)
           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))
+          inputs = Defaults.resolve(:spec_run, server_context[:project_root], timeout_seconds: timeout_seconds,
+                                                                              include_passing: include_passing,
+                                                                              include_stdout: include_stdout)
+          data = server_context[:worker_manager].run_spec(paths: paths, example: example, seed: seed,
+                                                          fail_fast: fail_fast, **inputs)
+          Response.ok(data: data, meta: Response.meta(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.
+    # The `rails_runtime_status` MCP tool: reports the test worker's
+    # Ruby/Rails versions, PID, boot_id, lifecycle state, the spec strategy
+    # and its fallback count, the project root and the effective tool
+    # defaults. 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)"
+      description "Report the Coatepec test worker's identity and boot status (boots the warm worker if it is " \
+                  "not up yet); includes project_root, spec_strategy (fork, guarded_fork or spawn), fallbacks " \
+                  "(how many guarded-fork runs fell back to spawn; null unless guarded_fork) and defaults (the " \
+                  "effective rails_spec_run and rails_routes defaults after .coatepec.yml)"
       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 })
+          root = server_context[:project_root]
+          data = server_context[:worker_manager].status.merge(
+            project_root: root,
+            defaults: { spec_run: Defaults.resolve(:spec_run, root), routes: Defaults.resolve(:routes, root) }
+          )
+          Response.ok(data: data, meta: Response.meta(started_at))
         rescue Coatepec::Error => e
           Response.error(e)
         end
@@ -84,27 +100,20 @@ module Coatepec
         def call(server_context:)
           started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           data = server_context[:worker_manager].restart!
-          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 })
+          Response.ok(data: data, meta: Response.meta(started_at))
         rescue Coatepec::Error => e
           Response.error(e)
         end
       end
     end
 
-    # The `rails_spec_flaky_check` MCP tool: runs targeted RSpec examples
-    # multiple times with independently random seeds and reports which
-    # examples' pass/fail status was inconsistent across rounds. Separate
-    # tool from rails_spec_run for the same reason rails_spec_profile is --
-    # see docs/superpowers/specs/2026-08-13-flaky-spec-detection-design.md.
+    # The `rails_spec_flaky_check` MCP tool: runs targeted RSpec examples or
+    # Minitest tests multiple times with independently random seeds and
+    # reports which tests' pass/fail status was inconsistent across rounds.
+    # Separate tool from rails_spec_run for the same reason rails_spec_profile
+    # is -- see docs/superpowers/specs/2026-08-13-flaky-spec-detection-design.md.
     class FlakyCheckTool < ::MCP::Tool
-      tool_name "rails_spec_flaky_check"
-      description "Run targeted RSpec examples multiple times with random seeds to detect order-dependent or " \
-                  "intermittent flakiness, reporting which examples' status was inconsistent across runs"
-      annotations(read_only_hint: false, destructive_hint: true, idempotent_hint: false, open_world_hint: true)
-      input_schema(
+      INPUT_SCHEMA = {
         properties: {
           paths: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 100 },
           example: { type: %w[string null] },
@@ -113,7 +122,14 @@ module Coatepec
         },
         required: ["paths"],
         additionalProperties: false
-      )
+      }.freeze
+
+      tool_name "rails_spec_flaky_check"
+      description "Run targeted RSpec examples or Minitest tests multiple times with random seeds to detect " \
+                  "order-dependent or intermittent flakiness, reporting which tests' status was inconsistent " \
+                  "across runs; the framework is chosen from the selector paths"
+      annotations(read_only_hint: false, destructive_hint: true, idempotent_hint: false, open_world_hint: true)
+      input_schema(**INPUT_SCHEMA)
 
       class << self
         def call(paths:, server_context:, example: nil, timeout_seconds: 120, runs: 5)
@@ -121,17 +137,10 @@ module Coatepec
           data = server_context[:worker_manager].check_flaky(
             paths: paths, example: example, timeout_seconds: timeout_seconds, runs: runs
           )
-          Response.ok(data: data, meta: meta_for(server_context, started_at))
+          Response.ok(data: data, meta: Response.meta(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
 
@@ -139,66 +148,71 @@ module Coatepec
     # Rails app's routes.
     class RoutesTool < ::MCP::Tool
       tool_name "rails_routes"
-      description "Return a bounded, filterable list of the Rails app's routes"
+      description "Return a bounded, filterable list of the Rails app's routes, application routes only by " \
+                  "default: mounted-engine routes (for example admin scaffolding) are withheld and the response's " \
+                  "engines_excluded says how many routes matching the query the engines filter held back " \
+                  "(application routes, under \"only\"); pass " \
+                  "engines: \"include\" to list both or \"only\" for engine routes alone. Engine routes are " \
+                  "expanded one level deep, carry the mount point in their path, and name their engine in the " \
+                  "engine field (null for an application route; query also matches that field); returns columns " \
+                  "(name, verb, path, controller, action, engine) and up to limit rows (default 100) in that " \
+                  "order, paths without the (.:format) suffix Rails appends, with next_offset -- the offset to " \
+                  "pass back for the next page, null on the last one" \
+                  "; the engines default can be set project-wide in .coatepec.yml"
       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 }
+          offset: { type: "integer", minimum: 0 },
+          engines: { type: "string", enum: %w[include exclude only] }
         },
         required: [],
         additionalProperties: false
       )
 
       class << self
-        def call(server_context:, query: nil, limit: 50, offset: 0)
+        def call(server_context:, query: nil, limit: 100, offset: 0, engines: nil)
           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))
+          inputs = Defaults.resolve(:routes, server_context[:project_root], engines: engines)
+          data = server_context[:worker_manager].routes(query: query, limit: limit, offset: offset, **inputs)
+          Response.ok(data: data, meta: Response.meta(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.
+    # The `rails_model` MCP tool: returns an ActiveRecord model's table
+    # metadata and list counts, plus any lists named in fields.
     class ModelTool < ::MCP::Tool
       tool_name "rails_model"
-      description "Return bounded ActiveRecord schema, associations, validators, and enums for a model, " \
-                  "without row data"
+      description "Return an ActiveRecord model's name, table, primary key, abstract_class and counts by default " \
+                  "(the size of its columns, associations, validators and enums lists, each capped at 200), without " \
+                  "row data; pass fields (any of columns, associations, validators, enums) to include those lists -- " \
+                  "an omitted or empty fields returns no lists, only counts; validators are de-duplicated by class, " \
+                  "attributes and options, so the list holds distinct validators and can be shorter than " \
+                  "klass.validators; an array-valued validator option longer than 20 entries keeps its first 20 with " \
+                  "<option>_count and <option>_truncated beside it"
       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*)*$' }
+          name: { type: "string", pattern: '^[A-Z]\w*(?:::[A-Z]\w*)*$' },
+          fields: { type: "array", items: { type: "string", enum: %w[columns associations validators enums] },
+                    uniqueItems: true }
         },
         required: ["name"],
         additionalProperties: false
       )
 
       class << self
-        def call(name:, server_context:)
+        def call(name:, server_context:, fields: nil)
           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))
+          data = server_context[:worker_manager].model(name: name, fields: fields)
+          Response.ok(data: data, meta: Response.meta(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
 
@@ -221,17 +235,10 @@ module Coatepec
         def call(name:, server_context:)
           started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           data = server_context[:worker_manager].controller(name: name)
-          Response.ok(data: data, meta: meta_for(server_context, started_at))
+          Response.ok(data: data, meta: Response.meta(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

data/lib/coatepec/mcp.rb

@@ -9,6 +9,7 @@ end
 
 require "coatepec"
 require_relative "mcp/response"
+require_relative "mcp/defaults"
 require_relative "mcp/tools"
 
 module Coatepec
@@ -20,8 +21,8 @@ module Coatepec
       ::MCP::Server.new(
         name: "coatepec",
         version: Coatepec::VERSION,
-        tools: [SpecRunTool, RuntimeStatusTool, RuntimeRestartTool, FlakyCheckTool, RoutesTool, ModelTool,
-                ControllerTool],
+        tools: [SpecRunTool, RuntimeStatusTool, RuntimeRestartTool, FlakyCheckTool,
+                RoutesTool, ModelTool, ControllerTool],
         server_context: { worker_manager: worker_manager, project_root: project.root }
       )
     end

data/lib/coatepec/project.rb

@@ -2,7 +2,8 @@
 
 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.
+  # Gemfile); knows where its own and pack/engine/gem spec and test
+  # directories live.
   class Project
     attr_reader :root
 
@@ -23,6 +24,15 @@ module Coatepec
       ].select { |path| File.directory?(path) }
     end
 
+    def test_root_candidates
+      [
+        File.join(root, "test"),
+        *Dir.glob(File.join(root, "packs/*/test")),
+        *Dir.glob(File.join(root, "engines/*/test")),
+        *Dir.glob(File.join(root, "gems/*/test"))
+      ].select { |path| File.directory?(path) }
+    end
+
     def config
       @config ||= ProjectConfig.new(root)
     end

data/lib/coatepec/project_config.rb

@@ -7,12 +7,28 @@ module Coatepec
   # project root. A missing file means every setting takes its default --
   # this file has never been required for Coatepec to work.
   class ProjectConfig
+    # Mirrors the MCP input schemas so a value the file accepts is one the tool accepts.
+    DEFAULT_KEYS = {
+      "spec_run" => {
+        "include_passing" => { boolean: true },
+        "include_stdout" => { enum: %w[failures always never] },
+        "timeout_seconds" => { range: 1..900 }
+      },
+      "routes" => { "engines" => { enum: %w[include exclude only] } }
+    }.freeze
+
     def initialize(root)
       @data = load(root)
+      @defaults = validate_defaults!(@data["defaults"] || {}) # a bare `defaults:` key means none
+    end
+
+    def defaults_for(tool)
+      @defaults.fetch(tool.to_s, {}).transform_keys(&:to_sym)
     end
 
+    # Forking is the macOS default since 0.9.0; `macos_fork: false` opts a project out.
     def macos_fork?
-      !!@data["macos_fork"]
+      @data.fetch("macos_fork", true) ? true : false
     end
 
     def macos_fork_unsafe_gems
@@ -21,6 +37,29 @@ module Coatepec
 
     private
 
+    def validate_defaults!(defaults)
+      invalid!("defaults must be a mapping of tool names") unless defaults.is_a?(Hash)
+      defaults.each do |tool, keys|
+        rules = DEFAULT_KEYS[tool.to_s] || invalid!("defaults.#{tool} is not a configurable tool")
+        invalid!("defaults.#{tool} must be a mapping") unless keys.is_a?(Hash)
+        keys.each { |key, value| validate_default!(tool, key, value, rules[key.to_s]) }
+      end
+      defaults
+    end
+
+    def validate_default!(tool, key, value, rule)
+      invalid!("defaults.#{tool}.#{key} is not a configurable input") unless rule
+      ok = if rule[:boolean] then [true, false].include?(value)
+           elsif rule[:enum] then rule[:enum].include?(value)
+           else value.is_a?(Integer) && rule[:range].cover?(value)
+           end
+      invalid!("defaults.#{tool}.#{key}: #{value.inspect} is not allowed") unless ok
+    end
+
+    def invalid!(message)
+      raise Coatepec::Error.new(:invalid_config, "Invalid .coatepec.yml: #{message}")
+    end
+
     def load(root)
       path = File.join(root, ".coatepec.yml")
       return {} unless File.exist?(path)

data/lib/coatepec/spec/failure_collapser.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module Spec
+    # Collapses failure blocks that repeat one error verbatim (a broken layout erroring every controller
+    # test, say) into the first block plus a roll-up line naming the other tests. Unrecognised text is kept.
+    module FailureCollapser
+      MINITEST_START = /\A(?:Error|Failure):\z/
+      MINITEST_ID = /\A(\S+#\S+?)(?: \[[^\]]*\])?:\z/
+      MINITEST_END = /\A\S*\brails test \S+:\d+\z/
+      RSPEC_START = /\A  \d+\) (.+)\z/
+      RSPEC_END = /\A(?:  \d+\) |Finished in |Failed examples:)/
+      # Backtrace frames and RSpec's "Failure/Error: <source line>" differ per test; the error text is what must match.
+      IGNORED = %r{\A\s+(?:# )?\S+:\d+(?::in .*)?\z|\A\s+Failure/Error: }
+
+      module_function
+
+      def call(text)
+        # read_bounded's tail byteslice can sever a multibyte character, and matching a regexp on that raises.
+        return text unless text.valid_encoding?
+
+        lines = text.lines
+        blocks = minitest_blocks(lines)
+        blocks = rspec_blocks(lines) if blocks.empty?
+        return text if blocks.size < 2
+
+        rewrite(lines, blocks)
+      end
+
+      # A block runs from the Error:/Failure: line through Rails' "bin/rails test path:LINE" rerun line.
+      def minitest_blocks(lines)
+        blocks = []
+        i = 0
+        while i < lines.size
+          id, stop = minitest_block_end(lines, i)
+          blocks << block(i, stop, id, lines[(i + 2)...stop]) if stop
+          i = (stop || i) + 1
+        end
+        blocks
+      end
+
+      def minitest_block_end(lines, index)
+        id = lines[index].chomp.match?(MINITEST_START) && lines[index + 1]&.chomp&.[](MINITEST_ID, 1)
+        return [nil, nil] unless id
+
+        [id, ((index + 2)...lines.size).find { |j| lines[j].chomp.match?(MINITEST_END) }]
+      end
+
+      # A block runs from "  N) description" (after the Failures: heading only) to the next such line or the summary.
+      def rspec_blocks(lines)
+        rspec_starts(lines).map do |i|
+          last = rspec_block_end(lines, i)
+          block(i, last, lines[i].chomp[RSPEC_START, 1], lines[(i + 1)..last])
+        end
+      end
+
+      # Only the numbered entries under the Failures: heading, never RSpec's Pending: section.
+      def rspec_starts(lines)
+        failures_at = lines.index { |line| line.chomp == "Failures:" }
+        return [] unless failures_at
+
+        ((failures_at + 1)...lines.size).select { |i| lines[i].chomp.match?(RSPEC_START) }
+      end
+
+      # Stops before the next failure or the summary, then backs over the blank lines in between.
+      def rspec_block_end(lines, start)
+        stop = ((start + 1)...lines.size).find { |j| lines[j].chomp.match?(RSPEC_END) } || lines.size
+        stop -= 1 while stop > start + 1 && lines[stop - 1].strip.empty?
+        stop - 1
+      end
+
+      def block(first, last, id, body)
+        key = body.map(&:chomp).reject { |line| line.strip.empty? || line.match?(IGNORED) }
+        { first: first, last: last, id: id, key: key }
+      end
+
+      def rewrite(lines, blocks)
+        skipped = {}
+        notes = {}
+        blocks.group_by { |b| b[:key] }.each_value do |kept, *dropped|
+          next if dropped.empty?
+
+          dropped.each { |b| skip_block(lines, b, skipped) }
+          notes[kept[:last]] = note_for(dropped)
+        end
+        render(lines, skipped, notes)
+      end
+
+      def render(lines, skipped, notes)
+        lines.each_with_index.reject { |_, j| skipped[j] }.map { |line, j| attach_note(line, notes[j]) }.join
+      end
+
+      # The blank line that separates the dropped block from the next one goes with it.
+      def skip_block(lines, dropped, skipped)
+        (dropped[:first]..dropped[:last]).each { |j| skipped[j] = true }
+        skipped[dropped[:last] + 1] = true if lines[dropped[:last] + 1]&.strip&.empty?
+      end
+
+      def note_for(dropped)
+        noun = dropped.size == 1 ? "test" : "tests"
+        "#{dropped.size} more #{noun} failed with this same error: #{dropped.map { |b| b[:id] }.join(", ")}"
+      end
+
+      def attach_note(line, note)
+        return line unless note
+
+        "#{line.chomp}\n#{note}\n"
+      end
+    end
+  end
+end

data/lib/coatepec/spec/flaky_checker.rb

@@ -44,9 +44,11 @@ module Coatepec
 
       def run_one_round(paths, example, timeout_seconds)
         seed = SecureRandom.random_number(65_536)
+        # Every round needs the full roster: a pass in one round is what makes a later failure flaky.
+        # stdout is never read from a round, so it is not captured into the result.
         result = @runner.run(
           paths: paths, example: example, seed: seed, fail_fast: false,
-          timeout_seconds: timeout_seconds
+          timeout_seconds: timeout_seconds, include_passing: true, include_stdout: "never"
         )
         { seed: seed, status: result[:status], examples: result[:examples] }
       end

data/lib/coatepec/spec/fork_strategy.rb

@@ -2,29 +2,22 @@
 
 module Coatepec
   module Spec
-    # Runs RSpec in a `Process.fork`ed child (Linux only): cheap and reuses
+    # Runs the test framework 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)
+      def execution_mode = "fork"
+
+      def start(full_args, out_w, err_w, json_path)
         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)
-          # RSpec freezes its own "load started at" timestamp once, at the moment
-          # rspec/core.rb is first required -- in this architecture, that's when
-          # the long-lived warm worker booted, not when THIS run started. Every
-          # forked child inherits that frozen timestamp via copy-on-write, so
-          # RSpec's own "(files took N seconds to load)" reporting would
-          # otherwise measure "time since the worker booted" and grow across
-          # every run for as long as the worker stays warm. Reset it fresh
-          # before each run.
-          RSpec.configuration.start_time = RSpec::Core::Time.now
 
-          status = RSpec::Core::Runner.run(full_args, $stderr, $stdout)
+          status = @adapter.run_in_process(full_args, json_path)
           $stdout.flush
           $stderr.flush
           Kernel.exit!(status)

data/lib/coatepec/spec/guarded_fork_strategy.rb

@@ -2,11 +2,12 @@
 
 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.
+    # The macOS fork strategy (the default since 0.9.0; macos_fork: false
+    # opts out): 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
@@ -36,13 +37,14 @@ module Coatepec
       # 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)
+      def initialize(project_root, adapter: nil, project: nil, rails_runtime: nil)
         super
-        @spawn_strategy = SpawnStrategy.new(project_root)
+        @spawn_strategy = SpawnStrategy.new(project_root, adapter: @adapter)
       end
 
-      def run(args, timeout_seconds)
-        return fallback_result(args, timeout_seconds, "spawn_fallback") unless guard_passes?
+      def run(args, timeout_seconds, include_passing: false, include_stdout: "failures")
+        result_options = { include_passing: include_passing, include_stdout: include_stdout }
+        return fallback_result(args, timeout_seconds, "spawn_fallback", result_options) unless guard_passes?
 
         started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         begin
@@ -51,22 +53,22 @@ module Coatepec
           # 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")
+          # the same mode. Forking on macOS must never surface an error that
+          # plain SpawnStrategy wouldn't have.
+          return fallback_result(args, timeout_seconds, "spawn_fallback", result_options)
         end
-        return result.merge(execution_mode: "fork") unless crashed?(result)
+        return result unless crashed?(result)
 
-        retry_after_crash(args, timeout_seconds, started_at, result)
+        retry_after_crash(args, timeout_seconds, started_at, result, result_options)
       end
 
       private
 
-      def retry_after_crash(args, timeout_seconds, started_at, crashed)
+      def retry_after_crash(args, timeout_seconds, started_at, crashed, result_options)
         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")
+        fallback_result(args, remaining, "spawn_after_crash", result_options)
           .merge(crashed_fork_stderr: crash_diagnostics(crashed))
       end
 
@@ -79,8 +81,8 @@ module Coatepec
         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)
+      def fallback_result(args, timeout_seconds, mode, result_options)
+        @spawn_strategy.run(args, timeout_seconds, **result_options).merge(execution_mode: mode)
       end
 
       def guard_passes?