Fix stale Bundler plugin registration after v5 (#1295)

[Mikola Lysenko (mikolalysenko)]

LLM Description written by Claude Code:claude-opus-5-5

Fixes #1295

Summary

After a team migrates to v5 as documented, every other checkout that ran bundle install under v4 (teammates' machines, persistent CI runners) still has Bundler's plugin registration for socket-patch, pointing at the deleted .socket/bundler-plugin/. On Bundler 2.3–2.5 every bundle install then fails with a LoadError that doesn't mention socket-patch. 2.6+ prints a warning on every run.

This PR:

• Detects it. scan (gem ecosystem selected, project mode) and apply (gem patches in scope, project mode) read $BUNDLE_APP_CONFIG/plugin/index (default .bundle/plugin/index). If it registers socket-patch at a path that no longer exists, they report a gem_bundler_plugin_stale run warning. The detail names the path, the index file and the one-line fix (bundle plugin uninstall socket-patch, or delete .bundle/plugin/). Under --json it goes in warnings[]; otherwise it prints one Warning: line on stderr, and apply suppresses it under --silent. A registration whose directory still exists is a working v4 setup and is not reported.
• Documents the per-checkout step in docs/migrating-to-v5.md, in CLI_CONTRACT.md (the "Agent mode in CI" section, which never mentioned it before), and in the retired-setup usage error.

Root cause

v4's setup --remove cleared .bundle/plugin/index (#210). v5 removed setup (#279), and .bundle/ is never committed, so nothing removes the registration in the checkouts that weren't the migrator's.

Evidence

• Reproduced locally with Bundler 4.0.18 / Ruby 3.3.6. After bundle install with a v4-style plugin "socket-patch", path: ".socket/bundler-plugin" block, the index reads plugin_paths:\n socket-patch: "<abs>/.socket/bundler-plugin". After removing the block and the directory, every bundle install prints "The following plugin paths don't exist…". bundle plugin uninstall socket-patch empties the index and clears the warning. The unit-test fixture uses that exact index text.
• Red → green: cargo test -p socket-patch-cli --all-features --test apply -- gem_stale_bundler_plugin
  • without the scan/apply wiring: scan_json_warns_about_stale_plugin_registration FAILED and apply_warns_about_stale_plugin_registration FAILED; scan_json_is_quiet_while_the_plugin_dir_exists passed
  • with the fix: all 3 pass, and the existing in_process_gem_config_warning tests still pass
• cargo test -p socket-patch-core --lib: the 3 new tests (registered_plugin_path_reads_bundlers_index, stale_plugin_registration_is_reported, stale_plugin_registration_follows_bundle_app_config) pass. Full lib run: 6094 passed. The 4 failures are pre-existing permission tests (copy_tree, vlt_heal, pypi_poetry, pypi_requirements) that can't fail as intended because the sandbox runs as uid 0, which bypasses read-only permissions. They're unrelated to this diff.
• cargo test -p socket-patch-cli --all-features --lib: 915 passed. --test cli_parse_main setup_subcommand_is_removed passes; it now also asserts that the error names bundle plugin uninstall socket-patch.
• cargo clippy --workspace --all-features -- -D warnings is clean, and rustfmt is clean on every touched file.
• A full cargo test --workspace does not fit in this sandbox's disk allowance (ENOSPC while linking the test binaries), so CI runs the full matrix.

Per-issue checklist

• v5 Bundler plugin cleanup leaves .bundle/plugin registered in every other checkout, so bundle install crashes with LoadError on Bundler 2.3–2.5 #1295, detection: gem_stale_bundler_plugin::{scan_json_warns_about_stale_plugin_registration, apply_warns_about_stale_plugin_registration, scan_json_is_quiet_while_the_plugin_dir_exists}, plus the core unit tests
• v5 Bundler plugin cleanup leaves .bundle/plugin registered in every other checkout, so bundle install crashes with LoadError on Bundler 2.3–2.5 #1295, docs and setup error: cli_parse_main::setup_subcommand_is_removed

Notes

• Wrappers (npm/, pypi/, gem/) carry no Bundler plugin cleanup text, so they need no changes.
• No CHANGELOG.md changes, per AGENTS.md.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NBZNtzNwEeuo5izMsyMaGm

---

Generated by Claude Code

---

Note

Low Risk
Read-only detection and user-facing warnings plus documentation; no change to patch application or Bundler integration beyond surfacing remediation guidance.

Overview
Addresses #1295: after v5 removes the Bundler plugin files, other checkouts can still have a machine-local socket-patch entry in .bundle/plugin/index (v4's setup --remove used to clear this). Bundler then breaks or warns on every bundle install.

Detection adds stale_plugin_registration_warning in the Ruby crawler: it reads the Bundler app config plugin index (honoring BUNDLE_APP_CONFIG), parses the registered socket-patch path, and only warns when that directory is missing. scan (gem, project mode) and apply (gem in scope, project mode) surface code gem_bundler_plugin_stale via JSON warnings[] or a single stderr Warning: (apply respects --silent). Working v4 installs with the plugin dir still present stay quiet.

Docs and UX expand v5 migration guidance and the retired setup error to require bundle plugin uninstall socket-patch (or deleting .bundle/plugin/) on every checkout that ran v4 bundle install. Integration and unit tests cover scan/apply JSON and stderr behavior plus index parsing.

^{Reviewed by Cursor Bugbot for commit 687e9fc. Configure here.}

[Mikola Lysenko (mikolalysenko)]

BugBot review

---

Generated by Claude Code

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 687e9fc. Configure here.}

[Mikola Lysenko (mikolalysenko)]

ci-ok is red on 687e9fc2 only because the CI run was cancelled manually ("The run was canceled by Mikola Lysenko (@mikolalysenko)"). It was part of a queue-wide cancel that hit about 20 runs. No test failed. Every check that finished before the cancel passed, including clippy, unit tests and the non-Gradle e2e jobs. The cancelled jobs were the Gradle e2e matrix and coverage-merge, and this PR changes no Gradle code.

I haven't re-run CI because that would undo the queue purge. Re-run the CI workflow when the queue has room. Bugbot found nothing on this head.

---

Generated by Claude Code