gemvault 0.2.4 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f95c7549060cbc79cadfe917e554bdaf894a1826351ab1935fe90e29197dcf82
-  data.tar.gz: 46247a46388af9ea35772c647456a80bbd68b7e96f98d0b3c2b456982b320ac5
+  metadata.gz: 4447e59a767dbc08bd6c0964964fefaf00bb1f2768421f7ce1fc6247f9e8f2c4
+  data.tar.gz: b017dc605efee9f1a576b1fc362b2cf51ebab25e48b424c2be7e50d9cb5f1e3f
 SHA512:
-  metadata.gz: eadddf04aad0f8307523984ddf26ee790e1b78a24480eeba13ba35f778521140e833d7ebfc307daf5edbb8ab666290feb05829fa92a787d1b5134568a911faa9
-  data.tar.gz: cd9dad01cfe52dc4f2d828ae5908a6bd40b2077adcdd45e7059901b7712762fc99fc407ee33d5fea3f80a46c912e7f3c1453c7596306073d1de68e6707908565
+  metadata.gz: 5c993d8b4fd00d8c35ed6de9645653400882565860f44449e7adbbcd53730ad7ca161e4cae10e7e817f512c3b63e2101e2ceb58496ebebe97eadd32eceefc46a
+  data.tar.gz: 39bfbb4959725d6ad92401dfd3d6841ea72c94021031bdf7680bdde9f2563bd721b51329db7cd76eaf0ef01a32dbfb0a9a788e7795befc50cdc6396f8c2db595

data/CHANGELOG.md

@@ -24,6 +24,15 @@ 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).
 - `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,7 @@ 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 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`).
 
 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

@@ -1017,3 +1017,73 @@ Description: /workspace/.bundle/plugin/gems/bundler-source-vault-0.2.2/gemvault_
 + /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
 Status: open
+
+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.
+Status: open

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

@@ -1,27 +1,56 @@
 require_relative "../command"
+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.
       #
-      # 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.
+      # Re-running bundle install afterwards triggers Bundler to reinstall
+      # the plugin against whatever the current Gemfile declares. Run this
+      # from the project directory.
       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"
+
+        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
+          begin
+            remove_ghost_specifications
+          rescue SystemCallError => e
+            print_error("#{e.message} #{PERMISSION_HINT}")
+            exit(1)
+          end
           system("bundle", "plugin", "uninstall", "bundler-source-vault", exception: true)
           exec("bundle", "install")
         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
       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.5".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.5
 platform: ruby
 authors:
 - David Gillis
@@ -74,6 +74,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