coatepec 0.5.0 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7cbcec579a7904ef50c8d8227036bbb0dd45f05bd664ffa2fceb2d210f5171be
-  data.tar.gz: 672092f99f2bfab2de7ad832572e6f16b5aeea8613860f0456fc81f7abaf25f4
+  metadata.gz: be24375e5f36c63e0511dc268bacecd57a54a33a94f5d44540925927c49f6655
+  data.tar.gz: 0e80f68351e4e814e9e4486f7e02d8d3f70512edaa7e9806c6baa3091111e779
 SHA512:
-  metadata.gz: f065ef0f83fbf5796d8e333326d9cf852a7322de12a12f77ece713df6cf00d29f167ea3ca2001830cb70e1e770a4533e3b111956390da1d0968c682cdeb8335a
-  data.tar.gz: 62d2d70afe6f5554c4e40fd83572384161f1819b228e65baa5c3a9c048716632e47c126356810e0c5aeb1e2ca1e9a79ed30fe0d10e97e773d6f1b6527a373d38
+  metadata.gz: 297b7eb82d12ece3991893ed1052650648d37fb86b438356257e67e90f69260297b5c3f4b390a2ce25860e2e06a8487dc1597bb39219c3f13ac550901cc92e94
+  data.tar.gz: dbe1f843c872f42c20d7df9ee4226af83200b9c9457bb2a9b3aba185d22b7c5c8878fa3237a57dc4dfb4526c499e4c75cb1cb5c3135262aa24dd71fc4ea8805b

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.5.2
+
+- Fix `WorkerManager` getting permanently stuck treating a dead worker as
+  alive: `Worker::Client#alive?` used `Process.kill(0, pid)`, which returns
+  true for an unreaped zombie, and the one existing auto-restart-and-retry
+  path only caught `Worker::Client::DisconnectedError`, not a raw
+  `Errno::EPIPE`/`SystemCallError` from writing to a dead worker's pipe.
+  Every call after a worker died this way failed identically, forever --
+  since stdio MCP servers have no lighter reconnect in Claude Code, this
+  previously required a full session restart to recover from.
+- Add `rails_runtime_restart`: unconditionally tears down and respawns the
+  test worker, for whatever the automatic detection above doesn't catch.
+- Fix RSpec's own "(files took N seconds to load)" reporting growing
+  across every `rails_spec_run` call made through the same warm,
+  forked-per-run worker -- it was measuring time since the worker first
+  booted, not time this run's files took to load, because `rspec-core`
+  freezes that timestamp once per process and Coatepec never reset it on
+  reuse.
+
+## 0.5.1
+
+- Fix `rails_model` crashing outright for a model with a `has_one`/
+  `has_many :through` association that goes through a polymorphic
+  `belongs_to` (e.g. `has_one :x, through: :notable, source: :y` where
+  `belongs_to :notable, polymorphic: true`). `foreign_key` on that
+  reflection needs a single fixed class to resolve, which a polymorphic
+  association can't provide, and that was previously an unrescued
+  `ArgumentError` that took down the whole response. That specific case now
+  reports `foreign_key: nil`/`class_name: nil` for the affected association,
+  the same way an already-handled plain polymorphic `belongs_to` does.
+- Add a general safety net around each association's metadata: if a single
+  association still fails for some other, not-yet-anticipated
+  `ActiveRecord` reflection quirk, only that association's entry degrades
+  (gaining an `error` field describing what went wrong) instead of the
+  entire `rails_model` call crashing for the whole model.
+
 ## 0.5.0
 
 - **Breaking:** `mcp` is no longer a runtime dependency of the `coatepec`

data/README.md

@@ -127,9 +127,35 @@ a no-op.
 |---|---|---|
 | `rails_spec_run` | `paths: string[1..100]`, `example?`, `seed?`, `fail_fast?`, `timeout_seconds?` (1..900, default 120) | Isolated per run; output capped at 256 KiB per stream |
 | `rails_runtime_status` | `{}` | Reports Ruby/Rails versions, worker PID, boot_id, lifecycle state |
+| `rails_runtime_restart` | `{}` | Unconditionally respawns the worker, discarding its warm boot |
 | `rails_routes` | `query?`, `limit?` (1..200, default 50), `offset?` | Case-insensitive filter across name/verb/path/controller/action |
 | `rails_model` | `name` (constant path, e.g. `Widget` or `Admin::Widget`) | ActiveRecord models only; columns, associations, validators, enums -- no row data |
 
+### Example queries
+
+`rails_routes`:
+
+- "What are all the routes in this app?" -- `rails_routes()`
+- "What's the URL for widgets?" -- `rails_routes(query: "widget")`. `query` is a
+  case-insensitive substring match across name, verb, path, controller, *and*
+  action -- not just the path -- so a resource name alone typically returns
+  every route for that resource (index/create/new/...); narrow further with
+  something like `query: "new_widget"` to hit one route by name.
+- "Which routes accept POST?" -- `rails_routes(query: "POST")`, the same
+  substring match applied to the verb column.
+
+`rails_model`:
+
+- "What columns does Widget have, and which are nullable?" --
+  `rails_model(name: "Widget")` -- see `columns[].null`, `columns[].sql_type`,
+  `columns[].default`.
+- "What validations and associations does Widget enforce?" -- same call --
+  see `validators` and `associations`.
+- "What happens if I ask about a non-model class, like a controller?" --
+  `rails_model(name: "ApplicationController")` raises `not_active_record_model`
+  rather than introspecting it (a nonexistent constant raises `model_not_found`
+  instead) -- the tool only ever reflects on `ActiveRecord::Base` descendants.
+
 The warm test worker forces Rails' reload-checking on for its own boot,
 regardless of the target app's own `test.rb` setting (which disables it by
 default) -- so editing a model file takes effect on the next tool call
@@ -153,6 +179,13 @@ across a commit that touches the Gemfile, since the sidecar is managed by
 your MCP client rather than by Coatepec itself: restart your MCP client (or
 however it manages the Coatepec process) to pick up the change.
 
+A dead *worker* (as opposed to a dead sidecar) recovers on its own: the
+next tool call detects it and transparently boots a fresh one before
+retrying, whether the worker exited outright or a request to it failed
+with a broken pipe. If you want a fresh worker without waiting for a
+failure -- or one keeps recurring -- call `rails_runtime_restart` directly;
+it always respawns, even if the current worker looks healthy.
+
 ## Security boundary
 
 No eval, console, SQL/record access, shell, Rake, or file-write tool. Spec

data/lib/coatepec/introspection/model.rb

@@ -93,7 +93,32 @@ module Coatepec
       end
 
       def associations_for(klass)
-        klass.reflect_on_all_associations.first(MAX_ITEMS).map { |assoc| build_association_data(assoc) }
+        klass.reflect_on_all_associations.first(MAX_ITEMS).map { |assoc| safe_association_data(assoc) }
+      end
+
+      # build_association_data's own field-level rescues (association_class_name,
+      # association_foreign_key) cover every failure mode seen in practice so
+      # far, but ActiveRecord's reflection internals are large enough that
+      # betting the whole rails_model call on having anticipated all of them
+      # is optimistic -- a has_one/has_many :through a polymorphic belongs_to
+      # is exactly the kind of case that wasn't anticipated until it crashed
+      # this method outright (see association_foreign_key). This is the
+      # boundary of last resort: one association's introspection failing
+      # degrades just that entry instead of the whole model. It deliberately
+      # does not rescue StandardError -- a NoMethodError here is a genuine
+      # Coatepec bug (e.g. a typo), and letting that crash loudly beats
+      # silently reporting it as "this association is fine, no data".
+      def safe_association_data(assoc)
+        build_association_data(assoc)
+      rescue NameError, ArgumentError, ::ActiveRecord::ActiveRecordError => e
+        degraded_association_data(assoc, e)
+      end
+
+      def degraded_association_data(assoc, error)
+        {
+          name: assoc.name.to_s, macro: assoc.macro.to_s, class_name: nil, foreign_key: nil, through: nil,
+          polymorphic: nil, error: "#{error.class}: #{error.message}"
+        }
       end
 
       def build_association_data(assoc)
@@ -101,7 +126,7 @@ module Coatepec
           name: assoc.name.to_s,
           macro: assoc.macro.to_s,
           class_name: association_class_name(assoc),
-          foreign_key: assoc.foreign_key.to_s,
+          foreign_key: association_foreign_key(assoc),
           through: assoc.through_reflection&.name&.to_s,
           polymorphic: assoc.polymorphic? || false
         }
@@ -120,6 +145,20 @@ module Coatepec
         nil
       end
 
+      # A has_one/has_many :through reflection whose `through:` target is
+      # itself a polymorphic belongs_to has no single fixed class either --
+      # ThroughReflection#foreign_key needs through_reflection.klass to find
+      # the source reflection, and .klass on a polymorphic reflection always
+      # raises ArgumentError (see association_class_name above). A dangling
+      # class_name on the reflection itself still raises NameError the same
+      # way. Report foreign_key: nil rather than letting either crash the
+      # call.
+      def association_foreign_key(assoc)
+        assoc.foreign_key.to_s
+      rescue NameError, ArgumentError
+        nil
+      end
+
       def validators_for(klass)
         klass.validators.first(MAX_ITEMS).map do |validator|
           {

data/lib/coatepec/mcp/tools.rb

@@ -69,6 +69,31 @@ module Coatepec
       end
     end
 
+    # The `rails_runtime_restart` MCP tool: unconditionally tears down and
+    # respawns the test worker, discarding its warm Rails boot. A manual
+    # escape hatch alongside WorkerManager's own automatic dead-worker
+    # detection, for whatever failure mode that detection doesn't catch.
+    class RuntimeRestartTool < ::MCP::Tool
+      tool_name "rails_runtime_restart"
+      description "Tear down and respawn the Coatepec test worker, discarding its warm Rails boot " \
+                  "(use if rails_spec_run/rails_runtime_status keep failing and a fresh worker is needed)"
+      annotations(read_only_hint: false, destructive_hint: true, idempotent_hint: false, 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].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 })
+        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

data/lib/coatepec/mcp.rb

@@ -12,15 +12,15 @@ 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.
+  # Wires the `rails_spec_run`, `rails_runtime_status`, `rails_runtime_restart`,
+  # `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],
+        tools: [SpecRunTool, RuntimeStatusTool, RuntimeRestartTool, RoutesTool, ModelTool],
         server_context: { worker_manager: worker_manager, project_root: project.root }
       )
     end

data/lib/coatepec/spec/fork_strategy.rb

@@ -14,6 +14,15 @@ module Coatepec
           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)
           $stdout.flush

data/lib/coatepec/version.rb

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

data/lib/coatepec/worker/client.rb

@@ -32,9 +32,20 @@ module Coatepec
       def alive?
         return false unless @pid
 
+        # A dead-but-unreaped worker (crash, the OS reclaiming a long-idle
+        # process, anything) is a zombie: Process.kill(0, pid) below would still
+        # succeed against it, since it still holds a process-table entry. Reap it
+        # here so staleness is detected instead of reported as "alive" forever --
+        # nothing else calls Process.wait on this pid except #stop, which only
+        # WorkerManager#restart_worker! reaches, and only once #alive? itself
+        # already says false.
+        _pid, status = Process.waitpid2(@pid, Process::WNOHANG)
+        @pid = nil if status
+        return false unless @pid
+
         Process.kill(0, @pid)
         true
-      rescue Errno::ESRCH
+      rescue Errno::ESRCH, Errno::ECHILD
         false
       end
 

data/lib/coatepec/worker_manager.rb

@@ -40,6 +40,27 @@ module Coatepec
       @lock.synchronize { @client&.stop }
     end
 
+    # Unconditionally tears down and respawns the worker, bypassing the usual
+    # "only restart if #ensure_worker! thinks it's needed" check. Manual escape
+    # hatch for rails_runtime_restart, independent of whatever #perform's
+    # rescue below already recovers from automatically.
+    #
+    # Still honors the sidecar-restart invariant: if the Gemfile changed since
+    # boot, a worker-only respawn would silently adopt the new bundle in the
+    # worker while the parent MCP process stays on the old one, so that case
+    # raises :sidecar_restart_required instead of restarting. The check runs
+    # against the *pre-existing* snapshot, before restart_worker! re-baselines
+    # it -- same ordering #dispatch uses. Nothing to compare against on the
+    # very first call.
+    def restart!
+      @lock.synchronize do
+        raise_sidecar_restart_required! if sidecar_restart_required?
+
+        restart_worker!
+        status
+      end
+    end
+
     private
 
     def dispatch(command, args, timeout:, retried: false)
@@ -57,26 +78,33 @@ module Coatepec
 
     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
+    rescue Worker::Client::DisconnectedError, SystemCallError, IOError => e
+      raise Coatepec::Error.new(:worker_disconnected, "Worker disconnected: #{e.message}") if retried
 
       restart_worker!
       dispatch(command, args, timeout: timeout, retried: true)
     end
 
     def check_for_restart!
-      reason = @change_detector.restart_reason(@snapshot)
-      case reason
+      case @change_detector.restart_reason(@snapshot)
       when :sidecar_restart_required
-        raise Coatepec::Error.new(
-          :sidecar_restart_required,
-          "Gemfile changed; restart your MCP client to restart Coatepec and pick up the change"
-        )
+        raise_sidecar_restart_required!
       when :worker_restart_required
         restart_worker!
       end
     end
 
+    def sidecar_restart_required?
+      @snapshot && @change_detector.restart_reason(@snapshot) == :sidecar_restart_required
+    end
+
+    def raise_sidecar_restart_required!
+      raise Coatepec::Error.new(
+        :sidecar_restart_required,
+        "Gemfile changed; restart your MCP client to restart Coatepec and pick up the change"
+      )
+    end
+
     def ensure_worker!
       restart_worker! unless @client&.alive?
     end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: coatepec
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.2
 platform: ruby
 authors:
 - Enrique Mogollan
 bindir: exe
 cert_chain: []
-date: 2026-08-05 00:00:00.000000000 Z
+date: 2026-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties