coatepec 0.4.1 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0db2635670e0fdfe695b2ba6b7fa8ffb6d1aa0400adf39eaee7bfc567e1c810
-  data.tar.gz: a236a2a6a096632f35d1442fad90656f3606389593b05baec61ad0c9dcbdf7ea
+  metadata.gz: 161aafede82c7279701f75a51cc7976a6ef7bbbadff7bc22a7bc04dc050e1780
+  data.tar.gz: 2b867df0d495bb573e1e00ad9a94f9aca800fa7045bbf6965fb0825acfc2683f
 SHA512:
-  metadata.gz: 7cff582a4b6aa94543265820d79f28769e1a5f5cca3b121f68ce8493d6a08c6f472628e6a81ff15f69f75d9b1f547233010957264fadd86cb554c86d54796b74
-  data.tar.gz: 79e09341a8ae0780da47ec7ab12953fea0cb8eb912f18582e6c21c27f99161b1d1cd1f6881c4f8029c4611deab6df3b8193bd56a902bcc651a50e408b06f421e
+  metadata.gz: d93777d12dac89c55450377259fc7d206bd6ef077766395f1397045372a58a7203bf986bbb9a525fc89b8510159a7fd9d0c3a057c321219edd95d6f23caa7acf
+  data.tar.gz: 3e580288a7c4ef9b0e707909967c28293ce8bc8b749e8c11d03903faef69ef80587c4a8307e13e769633d521b6245a05f806859d124a40346a9a0120b56e3e9b

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 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`
+  gem -- it's a development dependency, since Coatepec is meant to be
+  installed once outside any Rails app's own bundle and pointed at the app
+  via `--root`, not added to the app's `Gemfile` (`Worker::Client` resolves
+  the worker's `RUBYLIB` from Coatepec's own installation regardless).
+  Anyone whose MCP config currently launches Coatepec with `bundle exec
+  coatepec` from inside a target app's bundle will hit a `LoadError` on
+  upgrade once that bundle no longer pulls in `mcp` transitively.
+
+  **Migration:** `gem install mcp` alongside `coatepec`, and change your MCP
+  client config to invoke `coatepec` directly rather than `bundle exec
+  coatepec` (drop the `coatepec` line from the target app's `Gemfile` too,
+  if present -- see the README Quickstart for the corrected install story).
+
 ## 0.4.1
 
 - Fix `exe/coatepec-worker` booting against a target app whose locally

data/README.md

@@ -6,26 +6,31 @@ console.
 
 ## Quickstart
 
-```ruby
-# Gemfile
-group :development, :test do
-  gem "coatepec", require: false
-end
-```
+Coatepec is installed once, outside of any Rails app's own bundle, and
+points at the app via `--root`:
 
 ```bash
-bundle install
-bundle exec coatepec --version
+gem install coatepec mcp
+coatepec --version
 ```
 
-Configure your MCP client to run `bundle exec coatepec --root /absolute/path/to/app`
-from the Rails application's own bundle.
+Do not add `coatepec` to the target app's `Gemfile`. `Worker::Client#spawn_worker`
+resolves both the worker executable and its `RUBYLIB` from Coatepec's own
+installation, not from the app's bundle -- so the worker gets Coatepec's
+`lib` regardless of what the app's Gemfile says. Adding it there is not just
+redundant, it's a version-skew hazard: Bundler would activate whatever
+version is in the app's lockfile while Coatepec itself keeps running the
+version on `RUBYLIB`, and a drift between the two surfaces as a confusing
+"already activated" failure. The only thing Coatepec needs from the target
+app is `railties`, which is definitionally present in any Rails app you'd
+point it at. Host app footprint is zero: no Gemfile line, no lockfile
+change, no dependency resolution.
 
 With the [Claude Code CLI](https://docs.claude.com/en/docs/claude-code),
 from the Rails app's own root:
 
 ```bash
-claude mcp add coatepec --scope project -- bundle exec coatepec --root .
+claude mcp add coatepec --scope project -- coatepec --root .
 ```
 
 That writes a project-scoped `.mcp.json` you can commit so the whole team
@@ -36,8 +41,8 @@ same thing looks like:
 {
   "mcpServers": {
     "coatepec": {
-      "command": "bundle",
-      "args": ["exec", "coatepec", "--root", "."]
+      "command": "coatepec",
+      "args": ["--root", "."]
     }
   }
 }
@@ -93,6 +98,29 @@ includes an `execution_mode` field (`fork`, `spawn_fallback`, or
 call; `spawn_after_crash` results also carry the crashed fork's own stderr
 under `crashed_fork_stderr` so the crash can be diagnosed.
 
+`macos_fork: true` also effectively requires
+`OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` in Coatepec's own environment.
+Without it, a forked child that touches an Objective-C-initialized class
+aborts -- Coatepec retries via spawn, so it degrades silently to the slow
+path (no crash, no error surfaced) rather than failing loudly, and you
+simply never get the speedup. Set it on the MCP server process itself:
+
+```json
+{
+  "mcpServers": {
+    "coatepec": {
+      "command": "coatepec",
+      "args": ["--root", "."],
+      "env": { "OBJC_DISABLE_INITIALIZE_FORK_SAFETY": "YES" }
+    }
+  }
+}
+```
+
+Be aware this flag disables a real safety check in Apple's Objective-C
+runtime; it's a reasonable trade for a local dev/test sidecar, but it's not
+a no-op.
+
 ## Tools
 
 | Tool | Input | Notes |
@@ -102,6 +130,31 @@ under `crashed_fork_stderr` so the crash can be diagnosed.
 | `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
@@ -115,6 +168,16 @@ worker). For most apps this is invisible, but if you ever see behavior differ
 between Coatepec and your own `bundle exec rspec`, this is the first thing to
 suspect.
 
+### Restarts
+
+If any tool call fails with `sidecar_restart_required`, the target app's
+`Gemfile`/`Gemfile.lock` changed since Coatepec's own parent process (the
+"sidecar") started -- not just the warm test worker, which Coatepec restarts
+on its own. This is expected any time you switch branches, pull, or rebase
+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.
+
 ## 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.rb

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
 
-require "mcp"
+begin
+  require "mcp"
+rescue LoadError
+  raise LoadError, "The \"mcp\" gem is required to run Coatepec but is not installed. " \
+    "Install it alongside Coatepec: `gem install coatepec mcp`."
+end
+
 require "coatepec"
 require_relative "mcp/response"
 require_relative "mcp/tools"

data/lib/coatepec/version.rb

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

data/lib/coatepec/worker_manager.rb

@@ -68,7 +68,10 @@ module Coatepec
       reason = @change_detector.restart_reason(@snapshot)
       case reason
       when :sidecar_restart_required
-        raise Coatepec::Error.new(:sidecar_restart_required, "Gemfile changed; restart Coatepec")
+        raise Coatepec::Error.new(
+          :sidecar_restart_required,
+          "Gemfile changed; restart your MCP client to restart Coatepec and pick up the change"
+        )
       when :worker_restart_required
         restart_worker!
       end

metadata

@@ -1,28 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: coatepec
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.1
 platform: ruby
 authors:
 - Enrique Mogollan
 bindir: exe
 cert_chain: []
-date: 2026-08-03 00:00:00.000000000 Z
+date: 2026-08-07 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: mcp
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
@@ -43,6 +29,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 description: 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.