gemvault 0.2.4 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f95c7549060cbc79cadfe917e554bdaf894a1826351ab1935fe90e29197dcf82
-  data.tar.gz: 46247a46388af9ea35772c647456a80bbd68b7e96f98d0b3c2b456982b320ac5
+  metadata.gz: 6c8bf335258cabfbfbe016fe547e1302da87c37060d1523cae394e941bd493dd
+  data.tar.gz: f4a027c561cb8edf619f777989654d657bae70d741106ba8730b540b38de7f2f
 SHA512:
-  metadata.gz: eadddf04aad0f8307523984ddf26ee790e1b78a24480eeba13ba35f778521140e833d7ebfc307daf5edbb8ab666290feb05829fa92a787d1b5134568a911faa9
-  data.tar.gz: cd9dad01cfe52dc4f2d828ae5908a6bd40b2077adcdd45e7059901b7712762fc99fc407ee33d5fea3f80a46c912e7f3c1453c7596306073d1de68e6707908565
+  metadata.gz: 9f3691b960faaa2d6ab493d18363091691ce3ac106a23d8859a052e946fd6aaa78178282da8269823e07c21cf52cb5ba5e9e262c51767aea19d805b620ee6287
+  data.tar.gz: 99feeb31a5af138c4da80b61b3fe3853cd545044954b895e202d57a5f7c2817b3cb59701f752140efbce75c839120f4b6bcf0a5871a806a94cc80cc6d12670ed

data/CHANGELOG.md

@@ -24,6 +24,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   is shared with the RubyGems source via `Gemvault::VaultPath` (issue #9).
 
 ### Fixed
+- `gemvault doctor` now repairs ghost installations: a
+  `specifications/<gem>-<version>.gemspec` left behind after its gem directory
+  was removed (interrupted uninstall, hand-cleaned gem home), even when the
+  record itself is truncated or unreadable. Such a ghost of
+  `bundler-source-vault` makes every `bundle install` fail with
+  `Bundler::Plugin::MalformattedPlugin (plugins.rb was not found in the
+  plugin.)` — Bundler reinstalls the gem correctly but validates the ghost's
+  dead path — and nothing project-local can recover, because the wreck lives
+  in the ambient gem home (issue #23).
+- `gemvault doctor` now works in a project whose Gemfile is inline
+  (`bundler/inline`). Such a script keeps its plugin index in
+  `<project>/.bundle/plugin`, a root bundler only consults mid-script, so
+  doctor's uninstall silently repaired nothing and the `bundle install` that
+  followed dumped bundler's entire usage screen. Doctor now reaches the
+  project's index the way `bundler/inline` does and, with no Gemfile to
+  reinstall from, says so and exits 0 — the inline gemfile reinstalls the
+  plugin the next time the script runs (issue #14). Run outside any project,
+  doctor no longer claims to have cleared a project index it never touched.
+- `gemvault doctor` no longer strands a machine without the plugin. Its
+  closing `bundle install` does more than reinstall the plugin, and when that
+  extra work failed (a Ruby version pin, an unresolvable gem) the already-run
+  uninstall had cleared the plugin index for nothing — strictly worse than
+  the wreck doctor was asked to repair. The index is now snapshotted before
+  the uninstall and restored when the reinstall never happened, `bundle
+  install` runs as a child rather than replacing the process, and every
+  failure is one line on stderr and exit 1 instead of a backtrace
+  (issues #27, #24).
+- The shim no longer spams `already initialized constant` warnings when
+  bundler evaluates two installed copies of it in one process — an upgrade
+  resolving a newer bundler-source-vault while the plugin index still names
+  the old one. The first copy wins, matching the guard plugins.rb already
+  applies to the vault source class (issue #26).
 - `bundle plugin install bundler-source-vault` no longer dies with
   `LoadError: cannot load such file -- bundler/plugin/vault_source`. The shim's
   `plugins.rb` now derives the gem root from its own installed location (local

data/CLAUDE.md

@@ -60,6 +60,7 @@ gem install --source file:///path/to/myvault.gemv foo
 - `gemvault.gemspec` — main gem spec (name: `gemvault`)
 - `lib/gemvault/vault.rb` — Vault facade choosing a backend by file format (Tarvault current, legacy Dbvault read-only)
 - `lib/gemvault/cli.rb` — CLI dispatcher (new/add/list/remove/extract)
+- `lib/gemvault/ghost_specification.rb` — installation records whose gem directory is gone; swept by `gemvault doctor` (issue #23)
 - `lib/bundler/plugin/vault_source.rb` — Bundler `Plugin::API::Source` implementation
 - `lib/rubygems_plugin.rb` — RubyGems plugin: monkey-patches for `--source myvault.gemv` support
 - `lib/rubygems/source/vault.rb` — `Gem::Source::Vault` class (spec loading, download, `file://` URI handling, verbose logging)
@@ -115,9 +116,9 @@ bundle exec rake spec:teardown   # remove it
 Integration specs serve the tree's own gems from a local gem index (`GemIndex`)
 to avoid rubygems.org resolution during testing.
 
-Rubycritic scores `lib/`, `test/` and `shim/` but not `spec/`: flog taxes each
-block-nesting level, so idiomatic describe/context nesting reads as complexity.
-rubocop-rspec owns spec style.
+Rubycritic scores `lib/`, `spec/support/`, `test/` and `shim/` but not spec
+example files: flog taxes each block-nesting level, so idiomatic
+describe/context nesting reads as complexity. rubocop-rspec owns spec style.
 
 ### Container fidelity — do not undo these
 

data/README.md

@@ -70,9 +70,20 @@ When Bundler sees `type: :vault` in your Gemfile, it auto-installs the `bundler-
 
 The RubyGems plugin works similarly: `gem install --source vault.gemv` loads specs and extracts gems on demand.
 
-## Recovering from a broken bundler plugin path: `gemvault doctor`
+## Recovering from broken bundler plugin state: `gemvault doctor`
 
-If you installed `bundler-source-vault` from a local path (e.g. `plugin "bundler-source-vault", path: "/path/to/gemvault"` in a Gemfile), bundler records that absolute path in its plugin index. Moving, renaming, or deleting the source directory afterwards invalidates the stored path, and the next `bundle install` prints:
+Two kinds of wreckage make every `bundle install` fail, and `gemvault doctor` repairs both.
+
+**A ghost installation.** If a gem home holds a `specifications/bundler-source-vault-<version>.gemspec` whose `gems/` directory is gone (an interrupted `gem uninstall`, a hand-cleaned gem home), bundler trusts the leftover record and every install dies with:
+
+```
+Installing bundler-source-vault 0.2.4
+Failed to install plugin `bundler-source-vault`, due to Bundler::Plugin::MalformattedPlugin (plugins.rb was not found in the plugin.)
+```
+
+Deleting `.bundle` or the lockfile cannot help — the wreck lives in the machine's gem home, not the project. `doctor` finds such records across your gem roots, removes them (reporting each), and reinstalls the plugin.
+
+**A broken plugin path.** If you installed `bundler-source-vault` from a local path (e.g. `plugin "bundler-source-vault", path: "/path/to/gemvault"` in a Gemfile), bundler records that absolute path in its plugin index. Moving, renaming, or deleting the source directory afterwards invalidates the stored path, and the next `bundle install` prints:
 
 ```
 The following plugin paths don't exist: /path/to/gemvault/shim/.
@@ -87,7 +98,11 @@ To recover, update the Gemfile to point at the new path and run:
 gemvault doctor
 ```
 
-`doctor` clears the broken entry from bundler's plugin index (`bundle plugin uninstall bundler-source-vault`) and then re-runs `bundle install`, which reinstalls the plugin against whatever the current Gemfile declares. Run it from your project directory.
+`doctor` removes any ghost installation records, clears the broken entry from bundler's plugin index (`bundle plugin uninstall bundler-source-vault`) and then, when a Gemfile exists, re-runs `bundle install`, which reinstalls the plugin against whatever the current Gemfile declares. Run it from your project directory. If a ghost record sits in a root-owned gem home, doctor says so on one line — re-run it with permissions for that gem home (e.g. `sudo gemvault doctor`).
+
+A project whose Gemfile is inline (`require "bundler/inline"`) works too. Such a script keeps its plugin index in `<project>/.bundle/plugin`, a root bundler only consults while the script runs; doctor reaches it the same way the script did. With no Gemfile on disk there is nothing to reinstall from, so doctor clears the entry, says so, and exits 0 — the inline gemfile reinstalls the plugin the next time the script runs. Run outside any project, doctor works against bundler's global index and points you back at the project directory for the reinstall.
+
+The repair is transactional. `bundle install` does more than reinstall the plugin, and that extra work can fail on its own — a Ruby version pin, an unresolvable gem. When it does, doctor says so in one line and exits 1; and if the failure struck before the plugin was reinstalled, doctor puts the plugin index back the way it found it. A failed run never leaves the machine with less than it started with — fix the install error and re-run.
 
 The published `bundler-source-vault` gem installed from rubygems.org is immune to this: it lives in a bundler-managed directory that does not move.
 

data/issues.rec

@@ -750,7 +750,42 @@ Id: 14
 Updated: Wed, 29 Jul 2026 16:41:11 -0400
 Name: gemvault doctor fails when bundler/inline is used
 Description: Loudly fails with 2 errors, one of which is "can't find gemfile"
-Status: open
++
++ RESOLUTION: both errors reproduced in podman, and doctor turned out to be
++ broken twice over rather than once.
++
++ (1) "Plugin bundler-source-vault is not installed". bundler/inline sets
++ BUNDLE_GEMFILE to a bare "Gemfile" for the life of the script (bundler
++ inline.rb:53), so Bundler.root is the script's working directory and the plugin
++ index is written to <project>/.bundle/plugin. A later `gemvault doctor` sets no
++ such variable and finds no Gemfile on disk, so Bundler::Plugin.root --
++ local_root only when SharedHelpers.in_bundle?, global_root otherwise
++ (plugin.rb:162) -- falls back to ~/.bundle/plugin. The uninstall therefore
++ looked in the wrong root and repaired nothing, silently.
++
++ (2) "Could not locate Gemfile". doctor then exec'd `bundle install`, which with
++ no Gemfile prints its entire usage screen and exits 10 -- reading as gemvault
++ itself failing, after the repair it was asked for had already not happened.
++
++ doctor now runs the uninstall with BUNDLE_GEMFILE="Gemfile" when the project
++ owns a plugin root Bundler would ignore, which is bundler/inline's own trick and
++ needs no file to exist; verified against the real thing (plain uninstall says
++ "not installed", the same command with BUNDLE_GEMFILE set says "Uninstalled
++ plugin bundler-source-vault" and empties the index). When no Gemfile exists it
++ skips the reinstall and says so, exiting 0, because clearing the entry is the
++ repair and only the reinstall is unavailable -- an inline gemfile reinstalls the
++ plugin the next time the script runs.
++
++ Gemvault::BundlerGemfile mirrors SharedHelpers#find_gemfile and
++ Gemvault::BundlerPluginRoot mirrors Plugin.root, both reimplemented rather than
++ delegated because bundler is deliberately not a dependency and doctor runs
++ outside any Bundler process. Replicated first by
++ spec/integration/cli/commands/doctor_inline_spec.rb -- all 8 examples failed
++ against the old code -- with unit cover in spec/gemvault/bundler_gemfile_spec.rb,
++ spec/gemvault/bundler_plugin_root_spec.rb and the extended doctor_spec.rb. The
++ inline support now runs its script from the project directory, as a real user
++ does; that is what puts the plugin root where the report describes.
+Status: closed
 
 Id: 15
 Updated: Wed, 29 Jul 2026 17:39:23 -0400
@@ -783,7 +818,11 @@ Id: 16
 Updated: Wed, 29 Jul 2026 18:25:48 -0400
 Name: Add jruby-ci workflow
 Description: It should be already set up on the jruby-support branch. It just needs to be picked from it. DO NOT use the other code in that - it is very outdated
-Status: open
++
++ RESOLUTION: shipped in commit 635ba41 ("ci: add JRuby test job") -- the jruby
++ job in .github/workflows/ci.yml runs the minitest suite on jruby-10.1.0.0 and
++ is green on CI.
+Status: closed
 
 Id: 17
 Updated: Thu, 30 Jul 2026 00:07:42 +0000
@@ -972,7 +1011,15 @@ Description: [dev@rstore]/workspace% bundle install
 + 	from /usr/local/bin/bundle:25:in '<main>'
 + 
 + Though I will add that gemvault doctor followed by bundle install fixed the issue
-Status: open
++
++ RESOLUTION: the broken-plugin-path wreck, recovered exactly as reported --
++ gemvault doctor then bundle install. The plugin index entry pointed into a
++ reinstalled rbenv ruby's gem home; bundler does not revalidate stored plugin
++ paths, skips loading the plugin, and crashes in SourceList#add_plugin_source,
++ upstream behavior README documents under "A broken plugin path". doctor is
++ the repair. Hinting at doctor from the failure site was considered and
++ declined: the crash happens in bundler frames before any gemvault code loads.
+Status: closed
 
 Id: 21
 Updated: Fri, 31 Jul 2026 13:54:09 -0400
@@ -1011,9 +1058,168 @@ Description: bundler-cache: true on the ruby/setup-ruby action will not work cor
 +         run: | # confine gems to vendor/bundle so the cache never shadows vendor/vendored.gemv
 +           bundle config set --local path vendor/bundle
 +           bundle install --jobs 4 --retry 3
+Status: open
+
+Id: 26
 Updated: Mon, 10 Aug 2026 10:14:51 -0400
 Name: Gemvault spams warnings on bundle install
 Description: /workspace/.bundle/plugin/gems/bundler-source-vault-0.2.2/gemvault_load_path.rb:31: warning: already initialized constant BundlerSourceVault::GemvaultLoadPath::GEM
 + /workspace/.bundle/plugin/gems/bundler-source-vault-0.2.2/gemvault_load_path.rb:32: warning: already initialized constant BundlerSourceVault::GemvaultLoadPath::SHIM
 + /workspace/.bundle/plugin/gems/bundler-source-vault-0.2.2/gemvault_load_path.rb:33: warning: already initialized constant BundlerSourceVault::GemvaultLoadPath::VAULT_SOURCE
++
++ RESOLUTION: bundler can evaluate two installed copies of the shim in one
++ process -- an upgrade resolving a newer bundler-source-vault while the index
++ still names the old one, the dual-version plugin root the failure report
++ also recorded as issue #29 -- and require_relative cannot deduplicate
++ across paths, so the second copy reopened GemvaultLoadPath and warned on
++ every constant. gemvault_load_path.rb now returns before redefining
++ anything when the module is already loaded, first copy winning as
++ plugins.rb already arranges for Bundler::Plugin::VaultSource. Replicated by
++ spec/shim_reload_spec.rb (two copies loaded in one process, red against the
++ old shim), with the plain-install path guarded in
++ spec/integration/bundle_install_spec.rb.
+Status: closed
+
+Id: 23
+Updated: Mon, 10 Aug 2026 17:40:28 -0400
+Name: URGENT bundler plugin completely broken
+Description: ❯
++ ❯ bundle install
++ Fetching gem metadata from https://rubygems.org/.......
++ Resolving dependencies...
++ Installing bundler-source-vault 0.2.4
++ Failed to install plugin `bundler-source-vault`, due to Bundler::Plugin::MalformattedPlugin (plugins.rb was not found in the plugin.)
++ 
++ RESOLUTION: the machine, not the gem. bundler-source-vault-0.2.4 as published
++ contains plugins.rb (verified against rubygems.org; identical to 0.2.2 but for
++ versions). The trigger is a ghost installation in an ambient gem root:
++ specifications/bundler-source-vault-0.2.4.gemspec still present after
++ gems/bundler-source-vault-0.2.4/ was removed (interrupted uninstall or
++ hand-cleaned gem home). Bundler's Gemfile-driven plugin install then walks
++ into an upstream bug: resolution materializes the plugin as the installed
++ stub; rubygems.org's compact index carries created_at, and the cooldown
++ backfill (Source::Rubygems#backfill_created_at) attaches the remote to that
++ stub; download() therefore swaps the freshly fetched package spec into the
++ stub, and the installed? check inside install() memoizes that spec's
++ full_gem_path while its loaded_from is still nil -- the Gem.dir fallback,
++ i.e. the ghost's ambient path. Gem::Installer then extracts the gem
++ correctly into .bundle/plugin, but the poisoned memo survives, install()
++ copies it back onto the stub, and validate_plugin! checks plugins.rb against
++ the dead ambient directory instead of the copy it just installed. Hence the
++ report's shape -- "Installing bundler-source-vault 0.2.4" every run, then
++ MalformattedPlugin -- and hence its permanence: rm -rf .bundle, deleting the
++ lockfile and gemvault doctor all rebuilt project state while the wreck sat
++ in the ambient gem home. Present in bundler 4.0.17, 4.0.18 and master;
++ worth filing at rubygems/rubygems.
++ 
++ gemvault doctor now repairs the wreck: Gemvault::GhostSpecification finds
++ specifications whose gem directory is gone across Gem.path for the two gems
++ this project ships, and doctor removes them (reporting each) before its
++ existing uninstall-and-reinstall; a removal it cannot perform is one line on
++ stderr and exit 1. Replicated first by spec/integration/ghost_plugin_spec.rb
++ (real container, real ghost, real exit code): bundle install fails with
++ exactly the reported message, and the doctor context recovers to a complete
++ bundle. Unit cover in spec/gemvault/ghost_specification_spec.rb and
++ spec/gemvault/cli/commands/doctor_spec.rb.
++ 
++ The integration suite could not have caught this: GemIndex served only the
++ legacy marshal index, and only a compact index that carries created_at sends
++ Bundler down the stub-with-remote path. GemIndex now serves the compact
++ index too (versions and info/NAME with checksum and created_at, rendered by
++ GemIndexFiles), matching what rubygems.org sends, with the marshal files
++ kept for `gem install --source`.
++ 
++ Review hardening: detection evaluates no Ruby. The gem directory's name is
++ the record's file name minus .gemspec by RubyGems' install convention, so a
++ missing payload is recognized from the filesystem alone; scoping to the
++ asked gem reads the record's "# stub:" header when readable and falls back
++ to the filename. That sweeps truncated or unreadable records -- wreckage in
++ their own right, and Bundler's stub path needs only the header line, so a
++ truncated record can keep triggering this bug -- instead of silently
++ skipping them, and an unreadable neighboring record no longer aborts the
++ scan. Deliberately out of scope: a gem directory that exists but lost part
++ of its payload (same MalformattedPlugin symptom via a shorter path).
++ Telling that wreck apart from a healthy install would mean trusting the
++ record's file list, and a false positive there deletes a working
++ installation's record; a report of that wreck reopens this.
+Status: closed
+
+Id: 24
+Updated: Mon, 10 Aug 2026 23:16:35 +0000
+Name: doctor prints a backtrace when the plugin uninstall step fails
+Description: gemvault doctor's `bundle plugin uninstall` step runs with exception: true; a nonzero exit raises RuntimeError and a missing bundle raises Errno::ENOENT, and both escape Command#run to command_kit's ExceptionHandler, which prints error.full_message -- a full backtrace -- violating the one-line-and-exit-1 convention issue #15 established. Adjacent to issue #14 (doctor failing under bundler/inline). The ghost-specification sweep added for issue #23 reports its own failures as one line; the uninstall step should match.
++
++ RESOLUTION: fixed alongside issue #27's transactional rework. The uninstall
++ step no longer runs with exception: true; a failing or missing bundle is one
++ line on stderr ("doctor: bundle plugin uninstall bundler-source-vault
++ failed") and exit 1, matching the convention issues #15 and #23 established,
++ and the snapshotted index is left untouched.
+Status: closed
+
+Id: 25
+Updated: Tue, 11 Aug 2026 20:05:27 -0400
+Name: Project with Gemfile + locked json version + gemvault throws error
+Description: Project with Gemfile + locked json version + gemvault throws "bundler: failed to load command: rails (/private/tmp/local/flipmine/flipmine/vendor/ruby/4.0.0/bin/rails)
++ /Users/davidgillis/.rbenv/versions/4.0.1/lib/ruby/gems/4.0.0/gems/bundler-4.0.18/lib/bundler/runtime.rb:328:in 'Bundler::Runtime#check_for_activated_spec!': You have already activated json 2.21.2, but your Gemfile requires json 2.19.7. Prepending `bundle exec` to your command may solve this. (Gem::LoadError)"
++ 
++ I believe this error to be coming from gemvault's dependency on JSON. It is clear that dependencies are cursed in this project, whether its the added load time for reinstalling them on every `bundle install`, or errors like this one. Rather than rely on JSON, I think it would be better to just marshal our own manifest, or use some other serialization tool if any that rubygems already provides.
+Status: open
+
+Id: 27
+Updated: Wed, 12 Aug 2026 16:05:55 +0000
+Name: gemvault doctor can leave the machine with no plugin at all
+Description: Reported from a container where bundle install could not succeed
++ (ruby version pin mismatch): doctor removed ghost records, uninstalled the
++ plugin, emptied .bundle/plugin/index, then exec'd bundle install -- which
++ failed, leaving no plugin installed. Strictly worse than the broken-path
++ state doctor was invoked to repair, and recoverable only by knowing to run
++ `bundle plugin install bundler-source-vault` by hand. doctor repairs by
++ mutation with no dry-run, no report of findings before acting, and no
++ rollback when the reinstall it hands off to fails. Suggested in the report:
++ report-then-fix (--dry-run, or report by default and repair under --fix);
++ reinstall the plugin directly with `bundle plugin install` and verify the
++ index rather than exec'ing into `bundle install`, so a failed dependency
++ install cannot take the plugin down with it; or restore the previous index
++ when the step after the uninstall fails.
++
++ RESOLUTION: the uninstall-reinstall pair is now transactional. doctor
++ snapshots the plugin index bundler will consult (Gemvault::BundlerPluginIndex
++ over BundlerPluginRoot#consulted) before clearing it, runs `bundle install`
++ as a child instead of exec'ing into it, and on failure checks whether the
++ plugin came back: reinstalled means the repair stands and the one-line error
++ says only the bundle is unfinished; not reinstalled means the snapshot is
++ restored, so the machine is left as found and re-running doctor once the
++ install error is fixed recovers fully. Replicated first by
++ spec/integration/cli/commands/doctor_reinstall_failure_spec.rb -- doctor run
++ against a Gemfile still naming a renamed plugin path, an un-installable
++ bundle in the reporter's shape -- which fails against the old code and
++ proves the restored index heals on the next run. Unit cover in
++ spec/gemvault/bundler_plugin_index_spec.rb and the reworked doctor_spec.rb.
+Status: closed
+
+Id: 28
+Updated: Wed, 12 Aug 2026 16:05:55 +0000
+Name: plugins.rb dies with a bare LoadError when gemvault is installed nowhere
+Description: A plugin root holding only the shim -- the normal state wherever
++ `gem install gemvault` has run, since Bundler skips installing a plugin
++ dependency already present -- stops loading when the tree lands on a machine
++ with no gemvault in any gem root: GemvaultLoadPath.entries returns [] and
++ `require "bundler/plugin/vault_source"` raises a bare LoadError with no hint.
++ Observed after a macOS working tree was copied into a Linux container (the
++ shim alone in .bundle/plugin, gemvault absent from every gem root on the
++ box); also reachable by `gem uninstall gemvault` on a single machine. The
++ ambient-root search cannot cover gemvault being truly absent. Suggested:
++ fail with an explicit "gemvault not found in any gem root" message naming
++ the remedy (gem install gemvault, or bundle plugin uninstall + install to
++ get a self-contained root), or vendor gemvault into the shim.
+Status: open
+
+Id: 29
+Updated: Wed, 12 Aug 2026 16:05:55 +0000
+Name: Stale plugin versions are never reaped from the plugin root
+Description: bundler-source-vault-0.2.4 survived in the plugin root's gems/,
++ specifications/ and cache/ across the 0.2.5 upgrade and an explicit `bundle
++ plugin uninstall`; only 0.2.5 was ever referenced by the index. Possibly
++ Bundler's doing rather than the plugin's, but doctor is well placed to sweep
++ plugin-root versions the index no longer references.
 Status: open

data/lib/gemvault/bundler_gemfile.rb

@@ -0,0 +1,63 @@
+require "pathname"
+
+module Gemvault
+  ##
+  # The Gemfile Bundler would load from a directory.
+  #
+  # Mirrors Bundler::SharedHelpers#find_gemfile: <tt>BUNDLE_GEMFILE</tt> wins
+  # when set and non-empty, otherwise the search walks up looking for
+  # <tt>gems.rb</tt> then <tt>Gemfile</tt> in each directory. Reimplemented
+  # rather than delegated because bundler is deliberately not a gemvault
+  # dependency (see gemvault.gemspec) and +gemvault doctor+ runs as a plain
+  # CLI, outside any Bundler process.
+  #
+  # One difference is deliberate. Bundler returns <tt>BUNDLE_GEMFILE</tt>
+  # whatever it points at, existing or not -- bundler/inline relies on that,
+  # setting it to a bare "Gemfile" purely to make Bundler treat the working
+  # directory as the app root. The question here is whether +bundle install+
+  # could work, so a value that does not name a file is ignored and the
+  # walk-up search decides instead.
+  class BundlerGemfile
+    # Checked in this order within each directory, as Bundler checks them.
+    NAMES = ["gems.rb", "Gemfile"].freeze
+
+    def initialize(dir: Dir.pwd, env: ENV)
+      @dir = Pathname(dir)
+      @env = env
+    end
+
+    # :call-seq:
+    #   path -> Pathname or nil
+    #
+    # The Gemfile Bundler would load, or +nil+ when there is none.
+    def path
+      return @path if defined?(@path)
+
+      @path = from_env || search_up
+    end
+
+    # Whether Bundler would find a Gemfile at all.
+    def exist?
+      !path.nil?
+    end
+
+    private
+
+    def from_env
+      given = @env["BUNDLE_GEMFILE"].to_s
+      return nil if given.empty?
+
+      candidate = Pathname(given).expand_path(@dir)
+      candidate.file? ? candidate : nil
+    end
+
+    def search_up
+      @dir.expand_path.ascend do |dir|
+        found = NAMES.map { |name| dir / name }.find(&:file?)
+        return found if found
+      end
+
+      nil
+    end
+  end
+end

data/lib/gemvault/bundler_plugin_index.rb

@@ -0,0 +1,58 @@
+require "pathname"
+
+module Gemvault
+  ##
+  # Bundler's plugin index file inside a plugin root.
+  #
+  # The uninstall step of +gemvault doctor+ clears entries from this file, and
+  # the reinstall that follows can fail for reasons unrelated to the plugin.
+  # Snapshot and restore make that pair transactional: a repair that cannot
+  # finish puts the index back instead of leaving the machine with no plugin
+  # registered at all (issue #27).
+  #
+  # The plugin_paths section is scanned textually rather than parsed as YAML:
+  # loading a YAML library into doctor's process invites the same
+  # stdlib-activation conflicts as issue #25, and bundler's own emitter writes
+  # one two-space-indented "name: path" line per plugin.
+  class BundlerPluginIndex
+    def initialize(root)
+      @root = Pathname(root)
+    end
+
+    def file
+      @root / "index"
+    end
+
+    # Whether plugin_paths currently lists +plugin+.
+    def registered?(plugin)
+      plugin_paths.any? { |line| line.match?(/\A\s{2}#{Regexp.escape(plugin)}:/) }
+    end
+
+    # :call-seq:
+    #   snapshot -> String or nil
+    #
+    # The index content as it stands, +nil+ when no index exists.
+    def snapshot
+      file.file? ? file.read : nil
+    end
+
+    # Puts the index back the way +snapshot+ recorded it; restoring +nil+
+    # removes an index that did not exist at snapshot time.
+    def restore(snapshot)
+      return file.write(snapshot) if snapshot
+
+      file.delete if file.exist?
+    end
+
+    private
+
+    def plugin_paths
+      return [] unless file.file?
+
+      file.readlines
+          .drop_while { |line| !line.start_with?("plugin_paths:") }
+          .drop(1)
+          .take_while { |line| line.start_with?(" ") }
+    end
+  end
+end

data/lib/gemvault/bundler_plugin_root.rb

@@ -0,0 +1,59 @@
+require "pathname"
+require_relative "bundler_gemfile"
+
+module Gemvault
+  ##
+  # Where Bundler keeps plugin data for a directory.
+  #
+  # Bundler::Plugin.root answers the project-local <tt>.bundle/plugin</tt> when
+  # <tt>SharedHelpers.in_bundle?</tt> holds, and the global
+  # <tt>~/.bundle/plugin</tt> when it does not. Since +in_bundle?+ is just
+  # "was a Gemfile found", a project can own a plugin root that Bundler
+  # declines to look in.
+  class BundlerPluginRoot
+    LOCAL_DIR = ".bundle/plugin".freeze
+
+    def initialize(dir: Dir.pwd, gemfile: BundlerGemfile.new(dir: dir), env: ENV)
+      @dir = Pathname(dir)
+      @gemfile = gemfile
+      @env = env
+    end
+
+    # The project's own plugin root, whether or not Bundler would consult it.
+    def local
+      @dir.expand_path / LOCAL_DIR
+    end
+
+    # Where Bundler keeps plugins for a user outside any project, mirroring
+    # Bundler's user_bundle_path lookup for plugins: <tt>BUNDLE_USER_PLUGIN</tt>
+    # names the root directly, <tt>BUNDLE_USER_HOME</tt> relocates
+    # <tt>.bundle</tt>, and the home directory is the default.
+    def global
+      named = @env["BUNDLE_USER_PLUGIN"]
+      return Pathname(named) if named
+
+      Pathname(@env["BUNDLE_USER_HOME"] || File.join(Dir.home, ".bundle")) / "plugin"
+    end
+
+    # The plugin root Bundler will consult here: beside the Gemfile when one
+    # was found, the project's own root when doctor points Bundler at it (see
+    # #unreachable?), the global root otherwise.
+    def consulted
+      return @gemfile.path.dirname / LOCAL_DIR if @gemfile.exist?
+      return local if unreachable?
+
+      global
+    end
+
+    # Whether this project has a plugin root that Bundler currently ignores.
+    #
+    # bundler/inline installs plugins into <tt><cwd>/.bundle/plugin</tt>, having
+    # set <tt>BUNDLE_GEMFILE</tt> to a bare "Gemfile" for the duration of the
+    # script. A later command in that same directory sets no such variable and
+    # finds no Gemfile on disk, so Bundler falls back to the global root and
+    # reports the plugin as not installed -- while the entry sits here.
+    def unreachable?
+      !@gemfile.exist? && local.directory?
+    end
+  end
+end

data/lib/gemvault/cli/commands/doctor.rb

@@ -1,26 +1,143 @@
 require_relative "../command"
+require_relative "../../bundler_gemfile"
+require_relative "../../bundler_plugin_index"
+require_relative "../../bundler_plugin_root"
+require_relative "../../ghost_specification"
 
 module Gemvault
   class CLI
     module Commands
-      # Recovers from a bundler plugin index entry whose stored path no
-      # longer exists. Bundler records absolute paths in .bundle/plugin/index
-      # for path-installed plugins. Moving or renaming the source directory
+      # Recovers from wrecked bundler plugin state. Two wrecks are repaired:
+      #
+      # A bundler plugin index entry whose stored path no longer exists.
+      # Bundler records absolute paths in .bundle/plugin/index for
+      # path-installed plugins. Moving or renaming the source directory
       # leaves an invalid path behind -- Bundler::Plugin.load_plugin warns
       # "The following plugin paths don't exist: ..." and silently returns,
       # leaving @sources[<type>] nil. The next `source X, type: :vault`
       # crashes inside Bundler::SourceList#add_plugin_source with
-      # NoMethodError on nil.
+      # NoMethodError on nil. Uninstalling clears the broken entry.
+      #
+      # A ghost specification: an installation record whose gem directory is
+      # gone (see Gemvault::GhostSpecification). Bundler's plugin installer
+      # trusts the record and validates plugins.rb against the missing
+      # directory instead of the copy it just installed, so every
+      # `bundle install` fails with MalformattedPlugin (issue #23). Removing
+      # the record lets the reinstall see the machine as it is.
+      #
+      # Re-running bundle install afterwards triggers Bundler to reinstall
+      # the plugin against whatever the current Gemfile declares. Run this
+      # from the project directory.
       #
-      # Uninstalling clears the broken entry; re-running bundle install
-      # triggers Bundler to reinstall the plugin against whatever the
-      # current Gemfile declares. Run this from the project directory.
+      # A project whose Gemfile is inline has no Gemfile to reinstall from, and
+      # keeps its plugins in a root Bundler will not consult unless told to.
+      # Both are handled below.
+      #
+      # The repair is transactional. `bundle install` does more than reinstall
+      # the plugin, and that extra work can fail on its own; the index the
+      # uninstall clears is snapshotted first and put back when the reinstall
+      # never happened, so a failed run leaves the machine as found rather
+      # than with no plugin at all (issue #27). Every failure is one line on
+      # stderr and exit 1 (issue #24).
       class Doctor < Command
-        description "Clear a broken bundler-source-vault plugin index entry and reinstall it"
+        description "Repair broken bundler-source-vault plugin state and reinstall the plugin"
+
+        PLUGIN = "bundler-source-vault".freeze
+
+        OWNED_GEMS = %w[gemvault bundler-source-vault].freeze
+
+        PERMISSION_HINT = "(re-run with permissions for that gem home, e.g. sudo gemvault doctor)".freeze
 
         def run
-          system("bundle", "plugin", "uninstall", "bundler-source-vault", exception: true)
-          exec("bundle", "install")
+          begin
+            remove_ghost_specifications
+          rescue SystemCallError => e
+            print_error("#{e.message} #{PERMISSION_HINT}")
+            exit(1)
+          end
+          saved = index.snapshot
+          uninstall_plugin
+          reinstall_or_explain(saved)
+        end
+
+        private
+
+        def remove_ghost_specifications
+          OWNED_GEMS.flat_map { |name| GhostSpecification.of(name) }.each do |ghost|
+            ghost.delete
+            puts "Removed ghost specification #{ghost}"
+          end
+        end
+
+        def gemfile
+          @gemfile ||= BundlerGemfile.new
+        end
+
+        def plugin_root
+          @plugin_root ||= BundlerPluginRoot.new(gemfile: gemfile)
+        end
+
+        def index
+          @index ||= BundlerPluginIndex.new(plugin_root.consulted)
+        end
+
+        # bundler/inline's own trick: a non-empty BUNDLE_GEMFILE is the whole of
+        # what Bundler::Plugin.root consults to prefer a project's plugin
+        # directory over the global one, so setting it reaches the entry that
+        # needs clearing. The file it names never has to exist.
+        def uninstall_env
+          return {} unless plugin_root.unreachable?
+
+          { "BUNDLE_GEMFILE" => "Gemfile" }
+        end
+
+        def uninstall_plugin
+          return if system(uninstall_env, "bundle", "plugin", "uninstall", PLUGIN)
+
+          print_error("bundle plugin uninstall #{PLUGIN} failed")
+          exit(1)
+        end
+
+        # `bundle install` with no Gemfile prints its entire usage screen and
+        # exits 10, which reads as gemvault itself failing. By this point the
+        # repair has already happened; only the reinstall is unavailable.
+        def reinstall_or_explain(saved)
+          return reinstall(saved) if gemfile.exist?
+          return explain_inline_repair if plugin_root.unreachable?
+
+          puts "No Gemfile here to reinstall from -- re-run gemvault doctor from the"
+          puts "project directory to reinstall the plugin."
+        end
+
+        def reinstall(saved)
+          return if system("bundle", "install")
+          return exit_partially_repaired if index.registered?(PLUGIN)
+
+          exit_restoring(saved)
+        end
+
+        # The plugin came back before the install died, so the repair stands;
+        # only the rest of the bundle is unfinished.
+        def exit_partially_repaired
+          print_error("bundle install failed; the #{PLUGIN} plugin itself was reinstalled " \
+                      "-- fix the install error and re-run bundle install")
+          exit(1)
+        end
+
+        def exit_restoring(saved)
+          index.restore(saved)
+          print_error("bundle install failed before reinstalling #{PLUGIN}; restored the " \
+                      "previous plugin index -- fix the install error and re-run gemvault doctor")
+          exit(1)
+        end
+
+        # The local path is named only when it was the uninstall's target --
+        # otherwise bundler worked against its global root, and naming this
+        # project's path would misreport what happened.
+        def explain_inline_repair
+          puts "Cleared the #{PLUGIN} plugin index at #{plugin_root.local}."
+          puts "No Gemfile here to reinstall from -- an inline gemfile installs the plugin"
+          puts "again the next time the script runs."
         end
       end
     end

data/lib/gemvault/ghost_specification.rb

@@ -0,0 +1,87 @@
+require "pathname"
+
+module Gemvault
+  ##
+  # A gem installation record -- <tt>specifications/<full name>.gemspec</tt> --
+  # whose <tt>gems/<full name></tt> directory is gone: the wreckage of an
+  # interrupted uninstall or a hand-cleaned gem home.
+  #
+  # RubyGems still lists such a gem as installed, and Bundler's Gemfile-driven
+  # plugin installer trusts that record: it materializes the plugin against the
+  # ambient gem roots, reinstalls the missing gem into the plugin root, but
+  # then validates <tt>plugins.rb</tt> against the ghost's dead directory
+  # instead of the copy it just extracted. Every <tt>bundle install</tt> after
+  # that dies with <tt>MalformattedPlugin (plugins.rb was not found in the
+  # plugin.)</tt> -- issue #23. Removing the ghost record lets the next install
+  # see the machine as it really is.
+  #
+  # Detection never evaluates the record. The gem directory's name is the
+  # record's file name minus <tt>.gemspec</tt> by RubyGems' own install
+  # convention, so a missing payload is recognized from the filesystem alone --
+  # which lets a truncated or unreadable record, wreckage in its own right, be
+  # swept rather than silently skipped. Scoping to the asked gem reads the
+  # record's "# stub:" header when it is readable and falls back to the
+  # filename when it is not.
+  #
+  # Deliberately out of scope: a gem directory that exists but has lost part of
+  # its payload. Telling that wreck apart from a healthy install would mean
+  # trusting the record's file list, and a false positive here deletes a
+  # working installation's record.
+  class GhostSpecification
+    # All ghost specifications of +name+ across +roots+ (gem homes as listed
+    # on Gem.path, the same view Bundler's plugin installer resolves against).
+    def self.of(name, roots: Gem.path)
+      roots.flat_map { |root| in_root(Pathname(root), name) }
+    end
+
+    def self.in_root(root, name)
+      root.join("specifications").glob("#{name}-*.gemspec")
+          .select { |file| of_gem?(file, name) }
+          .reject { |file| root.join("gems", file.basename(".gemspec").to_s).directory? }
+          .map { |file| new(file) }
+    end
+    private_class_method :in_root
+
+    def self.of_gem?(file, name)
+      stub_name = stub_header_name(file)
+      return stub_name == name unless stub_name.nil?
+
+      version_shaped?(file.basename(".gemspec").to_s.delete_prefix("#{name}-"))
+    end
+    private_class_method :of_gem?
+
+    # Installed records open with an optional encoding magic comment followed
+    # by "# stub: <name> <version> <platform> <require paths>".
+    def self.stub_header_name(file)
+      file.open("r") do |io|
+        2.times do
+          line = io.gets or break
+          name = line[/\A# stub: (\S+) /, 1] and return name
+        end
+      end
+      nil
+    rescue SystemCallError
+      nil
+    end
+    private_class_method :stub_header_name
+
+    # A version starts with a digit and a gem-name segment rarely does; with
+    # no stub header left to say so, that is the best remaining evidence, and
+    # it is only ever weighed for a record whose payload is already missing.
+    def self.version_shaped?(remainder) = remainder.match?(/\A\d/)
+    private_class_method :version_shaped?
+
+    attr_reader :file
+
+    def initialize(file)
+      @file = file
+    end
+    private_class_method :new
+
+    def to_s = file.to_s
+
+    def delete
+      File.delete(file)
+    end
+  end
+end

data/lib/gemvault/version.rb

@@ -1,3 +1,3 @@
 module Gemvault
-  VERSION = "0.2.4".freeze
+  VERSION = "0.2.6".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gemvault
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.6
 platform: ruby
 authors:
 - David Gillis
@@ -56,6 +56,9 @@ files:
 - lib/bundler/plugin/vaulted_gem.rb
 - lib/gemvault.rb
 - lib/gemvault/archive_entry.rb
+- lib/gemvault/bundler_gemfile.rb
+- lib/gemvault/bundler_plugin_index.rb
+- lib/gemvault/bundler_plugin_root.rb
 - lib/gemvault/cli.rb
 - lib/gemvault/cli/command.rb
 - lib/gemvault/cli/commands/add.rb
@@ -74,6 +77,7 @@ files:
 - lib/gemvault/gem_reference/any_version.rb
 - lib/gemvault/gem_reference/parser.rb
 - lib/gemvault/gem_reference/specific_version.rb
+- lib/gemvault/ghost_specification.rb
 - lib/gemvault/manifest.rb
 - lib/gemvault/tarball.rb
 - lib/gemvault/tarvault.rb