coatepec 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 503cdd08a244ae010df42c9698c214d4a1e916969bae0f96ddaa62dfed2c2157
-  data.tar.gz: 54672230e5e1905f78f53d5614be4dccbcf0b5a9392fd3d0caae22dcf7d8c719
+  metadata.gz: 7cbcec579a7904ef50c8d8227036bbb0dd45f05bd664ffa2fceb2d210f5171be
+  data.tar.gz: 672092f99f2bfab2de7ad832572e6f16b5aeea8613860f0456fc81f7abaf25f4
 SHA512:
-  metadata.gz: f33a3b662004ab4aaba6d80ade9176952c90730ebe44a009f4f3443db5888c56b7fd8094b87c17b7be8a29519f7f067c2c6efcdb796249a4da3bc81945b236af
-  data.tar.gz: 8bfe0dccc1861c8b8923a8e049898ad8ead99da9febc5b85274914dad61ac52f06c3d5726e14d05b097e425e9a6c98eba1e3bca3bc98a51b6ea1227fb4b96bf7
+  metadata.gz: f065ef0f83fbf5796d8e333326d9cf852a7322de12a12f77ece713df6cf00d29f167ea3ca2001830cb70e1e770a4533e3b111956390da1d0968c682cdeb8335a
+  data.tar.gz: 62d2d70afe6f5554c4e40fd83572384161f1819b228e65baa5c3a9c048716632e47c126356810e0c5aeb1e2ca1e9a79ed30fe0d10e97e773d6f1b6527a373d38

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 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
+  installed default-gem versions (e.g. `json`) differ from what its
+  `Gemfile.lock` pins: `require "bundler/setup"` now runs before
+  `require "coatepec"` itself, so Bundler can pin default gems before
+  Ruby auto-activates a newer locally installed version and locks it in
+  for the rest of the process. Previously this broke every coatepec call
+  against such an app with `already activated X, but your Gemfile
+  requires Y`.
+
 ## 0.4.0
 
 - Add `enums` to `rails_model`'s output, sourced from ActiveRecord's own

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 |
@@ -115,6 +143,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/exe/coatepec-worker

@@ -1,6 +1,20 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+# Must run before any other require, including "coatepec" itself. Ruby
+# auto-activates the newest installed version of a default gem (json,
+# among others) the moment anything requires it, and a gem version can't
+# be changed once activated -- so if that happens before Bundler pins
+# versions to what the target app's Gemfile.lock actually specifies,
+# Bundler.setup then fails with "already activated X, but your Gemfile
+# requires Y" for any default gem that happens to have a newer version
+# installed locally than what's locked. require "coatepec" below pulls in
+# "json" (via protocol.rb) as its very first transitive require, so it's
+# exactly the kind of require this has to run ahead of.
+# Worker::Client#spawn_worker already sets BUNDLE_GEMFILE to the target
+# app's Gemfile before this process starts.
+require "bundler/setup"
+
 require "coatepec"
 
 # Preserve a real handle to the OS stdout fd for the private NDJSON

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.0"
+  VERSION = "0.5.0"
 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.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Enrique Mogollan
 bindir: exe
 cert_chain: []
-date: 2026-08-02 00:00:00.000000000 Z
+date: 2026-08-05 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.