gemvault 0.2.0 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c643dd2d86d0a918dbecb5a8f20026746a0e60670eaa5590009fe35e6f9b9b0
-  data.tar.gz: fa0f695ae5d5d9ab9686caa479cc89c2c6954fc8c53bfdd02841cf12578622bd
+  metadata.gz: fc64d612838fd7c22293d18622272cf495d92374f0b23aeb55eb900678081ec8
+  data.tar.gz: 29dae30a7efc5c9d38b829859682e8c3d0db49e340b4e1a28f139940045938ad
 SHA512:
-  metadata.gz: d16d9d84c05c143a2372eaee7bd55b162aca32019a4709227f689ce47a4c725bd4d2d8a64b9b788f32d107ec37ae8c61b73178d547e60613a221bd55d48aff53
-  data.tar.gz: 21b8fbd66feeea5146546632f5636a194c698c2ab6aa1d51ae0d9544b021dc15f32d4c1171a98e92c67fe62b56cfe2f57dab5138fef2c8dc6a4bb5d194b1952d
+  metadata.gz: 305c089e3b58804bbf70f89e3c11f94300fc2e6204dec50fab4fb63346da163fe735f639ee89a7fceea83caa53b17f2a69c3f898e97e4b0585ace415f0ade178
+  data.tar.gz: 15bcb0df46245246f279fcb4a08bfa1c351d68f09e432ac547df92e56120800bc5decc1ae5f8351a49990b0f5001a23437a78161af66491f1dd71a2162915bb0

data/.rubocop.yml

@@ -21,6 +21,7 @@ AllCops:
   Exclude:
     - bin/*
     - vendor/**/*
+    - references/**/*
     - lib/core_ext/**/*
     - rakelib/project.rb
     - rakelib/project_version.rb

data/.rubycritic.yml

@@ -0,0 +1,15 @@
+path: "tmp/rubycritic" # Set path where report will be saved (tmp/rubycritic by default)
+coverage_path: "tmp/coverage" # Set path where SimpleCov coverage will be saved (./coverage by default)
+threshold_score: 0 # default is 0
+deduplicate_symlinks: false # default is false
+suppress_ratings: false # default is false
+no_browser: true # default is false
+formats: # Available values are: html, json, console, lint. Default value is html.
+  - console
+  - json
+minimum_score: 95 # default is 0
+paths: # Files to analyse. Churn calculation is scoped to these files when using Git SCM.
+  - "lib/"
+  - "spec/"
+  - "test/"
+  - "shim/"

data/CHANGELOG.md

@@ -36,6 +36,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Vault gems whose versions carry a non-numeric suffix (e.g. `0.2.1.patch1`)
   install from a vault with `gem install --pre`, matching RubyGems' prerelease
   semantics (issue #6).
+- Repeated `bundle install` no longer fails with `cannot load such file --
+  bundler/plugin/vault_source` on machines that have gemvault installed
+  system-wide. Bundler skips installing a plugin dependency already present on
+  the ambient GEM_PATH, so the plugin root holds only the shim; once the app
+  bundle is populated Bundler restricts GEM_PATH to it and the ambient copy
+  falls out of scope. The shim now locates gemvault's `lib` across every root
+  that can hold it — `Gem.default_path` above all, which is what RubyGems knows
+  about its own gem roots and therefore covers rubies from rbenv, asdf, chruby,
+  Homebrew and distros, none of which export `GEM_HOME` or `GEM_PATH` — and
+  loads it via `$LOAD_PATH` rather than gem activation (issue #13).
+- The vault source registers correctly when Bundler evaluates the plugin more
+  than once in a process; gemvault is resolved and required only on the first
+  evaluation, so `Gemvault::GemEntry` can no longer be defined twice from two
+  different gem roots (issue #13).
+- `gemvault new` no longer raises `cannot load such file -- json` on a stock
+  distro ruby. json backs the tarball vault's manifest, so every current-format
+  vault needs it; it is a default gem upstream but a separate package on
+  distros, where `dnf install ruby` leaves it absent. It is now a declared
+  runtime dependency.
+- Reading a vault through the Bundler source no longer raises `cannot load such
+  file -- json` either. Loading gemvault off `$LOAD_PATH` skips activation, and
+  therefore skips its dependencies, so the declared dependency alone did not
+  reach the plugin path. The shim now resolves gemvault's declared runtime
+  dependencies the same way it resolves gemvault and puts their require paths —
+  extension directories included — on `$LOAD_PATH`. A dependency it cannot find
+  is skipped rather than fatal, which is what activation could not do.
+- `bundle install` no longer fails with `Could not find 'command_kit' (~> 0.6)`
+  when gemvault is installed into the plugin root without its dependencies.
+  Loading the vault source no longer activates the gemvault gem, which would
+  demand the full runtime dependency set; `vault_source.rb` reaches the rest of
+  gemvault through `require_relative` alone (issue #13).
 
 ### Changed
 - `sqlite3` is no longer a runtime dependency. Gemvault runs dependency-free on

data/CLAUDE.md

@@ -9,15 +9,16 @@ Do NOT modify `.rubocop.yml` or use inline `# rubocop:disable` tags without expl
 1. Specs always come first. Every plan should start with the skeleton of the BDD specs being added, changed or removed. Skeleton means the empty RSpec language, without implementation.
 2. Specs should never have comments. Any urge to put a comment in a spec means that comment should probably be its own spec
 3. DO NOT edit .rubocop.yml or add inline rubocop exemptions without explicit permission
-4. DO NOT run any git command that will rewrite history without explicit permission
-5. PREFER method & class extraction over comments
-6. Making new files, classes, modules, and methods IS NOT overengineering
-7. BEFORE writing code, identify which domain concept owns the behavior. Each class and module should have a single responsibility. If the new behavior doesn't fit an existing class's responsibility, create a new one — don't expand the scope of what's already there.
-8. DO NOT name classes with suffixes like "-er" or "-or" unless using a canonical pattern name (e.g., Parser, Router, Controller)
-9. ALWAYS write specs first. The workflow is: identify the domain concept (rule 5), write specs describing its behavior, then implement. No implementation without a failing spec.
-10. Integration specs are the first line of defense for CLI-tool bugs. For any bug reported from using the CLI tool (not the gemvault lib / Ruby API), the FIRST spec you write is an integration spec that reproduces the user's exact invocation — real subprocess, real vault, real exit code. Stub-heavy unit specs are complementary, not sufficient: they prove internal logic produces the expected value assuming surrounding wiring works, but a user's bug report is evidence the wiring didn't work.
-11. If an integration spec is not catching a reported CLI-tool bug, one of two things is true, and the fix starts by diagnosing which: (a) existing integration specs are not specific enough — extend them to cover the exact scenario before touching production code; or (b) the scenario is not spec'd at all, which means the work is not a bug fix but a new feature — write integration specs for the contract first (per rule 1), then implement.
-12. NEVER write to /tmp. Use /workspace/tmp
+4. DO NOT edit .rubycritic.yml or add inline rubycritic exemptions without explicit permission
+5. DO NOT run any git command that will rewrite history without explicit permission
+6. PREFER method & class extraction over comments
+7. Making new files, classes, modules, and methods IS NOT overengineering
+8. BEFORE writing code, identify which domain concept owns the behavior. Each class and module should have a single responsibility. If the new behavior doesn't fit an existing class's responsibility, create a new one — don't expand the scope of what's already there.
+9. DO NOT name classes with suffixes like "-er" or "-or" unless using a canonical pattern name (e.g., Parser, Router, Controller)
+10. ALWAYS write specs first. The workflow is: identify the domain concept (rule 5), write specs describing its behavior, then implement. No implementation without a failing spec.
+11. Integration specs are the first line of defense for CLI-tool bugs. For any bug reported from using the CLI tool (not the gemvault lib / Ruby API), the FIRST spec you write is an integration spec that reproduces the user's exact invocation — real subprocess, real vault, real exit code. Stub-heavy unit specs are complementary, not sufficient: they prove internal logic produces the expected value assuming surrounding wiring works, but a user's bug report is evidence the wiring didn't work.
+12. If an integration spec is not catching a reported CLI-tool bug, one of two things is true, and the fix starts by diagnosing which: (a) existing integration specs are not specific enough — extend them to cover the exact scenario before touching production code; or (b) the scenario is not spec'd at all, which means the work is not a bug fix but a new feature — write integration specs for the contract first (per rule 1), then implement.
+13. NEVER write to /tmp. Use /workspace/tmp
 
 ## Additional rules
 
@@ -77,6 +78,15 @@ gem install --source file:///path/to/myvault.gemv foo
 - `bundler-source-vault` name exists because Bundler auto-infers plugin name from `type: :vault` → `bundler-source-vault`
 - `file://` URIs stripped to plain paths in `Gem::Source::Vault#initialize`
 - Verbose logging via `Gem::UserInteraction#verbose` for `--verbose` support
+- `shim/plugins.rb` loads gemvault by putting its `lib` on `$LOAD_PATH`, never by
+  activating the gem. Bundler skips installing a plugin dependency already
+  present on the ambient GEM_PATH, so the plugin root often lacks gemvault, and
+  by load time GEM_PATH is restricted to the plugin root and the app bundle. The
+  shim therefore searches every root that can hold gemvault, including the ones
+  Bundler masked (`Bundler.original_env` GEM_HOME/GEM_PATH). Activation is
+  avoided because it demands gemvault's full runtime dependency set (command_kit),
+  which Bundler skips for the same reason — `vault_source.rb` reaches the rest of
+  gemvault through `require_relative` alone and needs none of it.
 
 ## Testing
 
@@ -84,17 +94,72 @@ gem install --source file:///path/to/myvault.gemv foo
 bundle exec rake test
 ```
 
-- `test/vault_test.rb` — 33 unit tests for Vault class
-- `test/vault_source_test.rb` — 17 unit tests for Bundler source plugin
-- `test/integration_test.rb` — 12 end-to-end bundle install tests
-- `test/cli_test.rb` — 32 CLI tests
-- `test/rubygems_plugin_test.rb` — 28 tests (source, resolver, monkey-patches, gem install integration, file:// URI, verbose logging)
+Minitest covers the library; RSpec covers the CLI and the containerized
+integration suite. `rake` (the default task) runs `test`, `spec`, `rubocop` and `rubycritic`.
 
-Integration tests use a manually-written Bundler plugin index to avoid rubygems.org resolution during testing.
+```bash
+bundle exec rake test            # minitest only
+bundle exec rake spec:core       # rspec, no containers
+bundle exec rake spec:integration # rspec, containers (builds the image first)
+bundle exec rake spec:build      # rebuild the container image
+bundle exec rake spec:teardown   # remove it
+```
+
+- `test/vault_test.rb` — unit tests for Vault class
+- `test/vault_source_test.rb` — unit tests for Bundler source plugin
+- `test/cli_test.rb` — CLI tests
+- `test/rubygems_plugin_test.rb` — source, resolver, monkey-patches, gem install integration, file:// URI, verbose logging
+- `spec/integration/` — end-to-end specs, each run inside a podman container
+- `spec/support/` — script fragments the integration specs assemble into those containers
+
+Integration specs serve the tree's own gems from a local gem index (`GemIndex`)
+to avoid rubygems.org resolution during testing.
+
+### Container fidelity — do not undo these
+
+The container has to look like a machine a user actually has. The `ruby` base
+image does not, and every way it differs has already hidden a real defect. These
+five are load-bearing; reverting any of them silently makes the suite green
+against something other than the code under test:
+
+1. **`bundler-source-vault` is NOT installed system-wide in `Dockerfile.test`.**
+   An ambient copy satisfies Bundler's plugin resolution without ever populating
+   the plugin root. Specs resolve the shim from the local gem index (`GemIndex`)
+   so they exercise the tree's shim. `gemvault` IS installed system-wide on
+   purpose — that is a real user's machine and the trigger for issue #13.
+2. **`BUNDLE_APP_CONFIG` is not set in the container.** The `ruby` image sets it
+   to `/usr/local/bundle`, which moves `Bundler::Plugin.root` out of the project
+   so no spec ever touches a project-local `.bundle/plugin`. Fedora sets it
+   nowhere; do not add it, and do not adopt a base image that does.
+3. **`GEM_HOME` and `GEM_PATH` are not exported in the container, and nothing
+   pins them.** Gems land in RubyGems' own default dirs. The `ruby` image
+   exports `GEM_HOME`; rubies from rbenv, asdf, chruby, Homebrew and distros
+   export nothing. Anything that reads gem roots back out of the environment
+   finds them on the image and finds nothing on a user's machine — that is what
+   made the first fix for issue #13 pass its specs while still failing for the
+   reporter. Neither `Dockerfile.test` nor `ContainerHelper#podman_run` should
+   grow an `ENV`/`-e` for either variable.
+4. **Bundler is pinned to the version users run, not the image's default gem.**
+   The plugin machinery under test is Bundler's own, so a stale default silently
+   tests different code.
+5. **dnf runs with stock settings — weak dependencies included.** On a real
+   Fedora machine `dnf install ruby` pulls the unbundled default-gem RPMs
+   (`rubygem-json`, `rubygem-psych`, …) through the ruby package's Recommends.
+   `--setopt=install_weak_deps=False` builds a ruby no user has — one where
+   `require "json"` raises — and that faulty install once failed every CLI
+   scenario in the suite.
+
+Fidelity is a property of the image, not of a script fragment: integration specs
+run only commands a user would actually type.
+
+If a spec fails only after removing a system-installed gem or an exported
+variable, the spec was passing for the wrong reason — fix the spec, not the
+container.
 
 ## Dependencies
 
 - `bundler` — NOT a dependency; the plugin always runs inside an existing Bundler process, and declaring it breaks gem activation under `bundle exec`'s restricted GEM_PATH
 - `command_kit` (~> 0.6) — runtime (CLI)
+- `json` — NOT a dependency, though it backs the tarball vault's manifest. A default gem upstream; distros that unbundle it (Fedora's `rubygem-json`) still install it alongside ruby itself, and it stays requireable even under `bundle exec`'s restricted view. Declaring it would compile a native extension on every `gem install gemvault` for no gain.
 - `sqlite3` (~> 2.0) — NOT a runtime dependency; loaded lazily only to read a legacy SQLite (Dbvault) vault. Declared in the Gemfile for development/test.
-- `minitest`, `rake` — development
+- `minitest`, `rspec`, `rake` — development

data/Dockerfile.test

@@ -1,25 +1,64 @@
-FROM docker.io/library/ruby:4.0.1-slim
+# A dev machine, not a packaging convenience.
+#
+# The official ruby image is not shaped like anything a user runs: it redirects
+# gems to /usr/local/bundle, exports GEM_HOME and BUNDLE_APP_CONFIG to match,
+# and freezes bundler at whatever shipped. Each of those differences hid a real
+# defect, and patching them one at a time only moved the blind spot. A distro
+# ruby has none of them: gems land in RubyGems' own default dirs, nothing is
+# exported, and bundler is a regular gem rather than a default one -- which is
+# also the shape that broke `bundle exec` in issue #12.
+FROM docker.io/library/fedora:44
 
-COPY . /tmp/build/
+# Stock dnf settings, weak dependencies included: on a real Fedora machine
+# `dnf install ruby` pulls the unbundled default-gem RPMs (rubygem-json,
+# rubygem-psych, rubygem-rdoc, ...) through the ruby package's Recommends.
+# Passing --setopt=install_weak_deps=False builds a ruby no user has -- one
+# where `require "json"` raises -- and that faulty install once failed every
+# CLI scenario in the suite.
+RUN dnf \
+	install \
+	-y \
+	@standard \
+	@development-tools \
+	@ruby \
+	sqlite3 \
+	&& dnf clean all
 
-RUN cd /tmp/build \
-    && gem build gemvault.gemspec \
-    && gem install --no-document gemvault-*.gem \
-    && cd shim \
-    && gem build bundler-source-vault.gemspec \
-    && gem install --no-document bundler-source-vault-*.gem \
-    && rm -rf /tmp/build
+# Keep this in step with the `BUNDLED WITH` line the project's own lockfile
+# carries. The plugin machinery these specs exercise is Bundler's own, so a
+# stale version silently tests different code.
+RUN gem install --no-document bundler -v 4.0.17
 
 # sqlite3 is not a gemvault runtime dependency; install it here so the upgrade
 # integration test can read the committed legacy SQLite (Dbvault) fixture it
 # migrates.
 RUN gem install --no-document sqlite3
 
-# Gem files for integration specs that install the plugin from a local gem
-# index at spec runtime, kept for offline use: command_kit is gemvault's
-# runtime dependency; the bundler gem lets specs simulate distro rubies where
-# bundler is a regular (non-default) gem.
-RUN mkdir -p /opt/gems \
-    && cd /opt/gems \
-    && gem fetch command_kit -v 0.6.0 \
-    && gem fetch bundler -v "$(ruby -rbundler -e 'print Bundler::VERSION')"
+# The tree arrives as a bind mount at /src rather than a COPY: the build context
+# lives on a filesystem whose extended-attribute listing podman's copier cannot
+# read. `rake spec:build` supplies both the mount and SOURCE_DIGEST.
+#
+# A bind mount's contents are not part of podman's cache key, so without
+# SOURCE_DIGEST in the command line this layer is reused forever and the image
+# keeps whichever gemvault the tree held the first time it was built -- the
+# suite would then run green against code that is not under test. The digest
+# changes whenever the installed source does, which invalidates the layer. It is
+# last so that editing lib/ does not re-fetch the layers above.
+#
+# gemvault is installed system-wide because integration specs need the CLI to
+# build vault fixtures, and because that is what a real user's machine looks
+# like: `gem install gemvault` puts it on the ambient GEM_PATH. That ambient
+# copy is load-bearing for the plugin root specs -- Bundler skips installing a
+# plugin dependency that is already installed, so the plugin root only gets a
+# complete dependency set if gemvault puts it there itself.
+#
+# bundler-source-vault is deliberately NOT installed system-wide. An ambient
+# copy satisfies Bundler's plugin resolution without ever populating the plugin
+# root, which masks every plugin-root defect the integration specs exist to
+# catch. Specs install it from the local gem index built by GemIndex instead.
+ARG SOURCE_DIGEST=unset
+RUN test "$SOURCE_DIGEST" != unset \
+    && cd /src \
+    && gem build gemvault.gemspec -o /tmp/gemvault.gem \
+    && gem install --no-document /tmp/gemvault.gem \
+    && rm -f /tmp/gemvault.gem

data/Rakefile

@@ -24,31 +24,44 @@ RuboCop::RakeTask.new
 require "gempilot/version_task"
 Gempilot::VersionTask.new
 
-CACHED_IMAGE = "gemvault-test:latest".freeze
-
-def cached_image_exists?
-  system("podman", "image", "exists", CACHED_IMAGE, out: File::NULL, err: File::NULL)
+require "rubycritic/rake_task"
+require "yaml"
+
+# The task's default paths are FileList["."], passed straight to the CLI where
+# they override .rubycritic.yml's paths -- and "." drags in references/, whose
+# vendored checkouts flog cannot even read. Feed the yml's own list back in so
+# the config file stays the single source of truth.
+RubyCritic::RakeTask.new do |task|
+  task.paths = YAML.load_file(".rubycritic.yml").fetch("paths")
 end
 
-def build_cached_image
-  sh "podman", "build", "--network=host", "-t", CACHED_IMAGE, "-f", "Dockerfile.test", "."
+require "digest"
+require_relative "spec/support/container_helper"
+require_relative "spec/support/container_image"
+
+# What the image is built from. ContainerImage feeds this to podman as a build
+# arg, because the bind mount the Dockerfile reads is invisible to podman's
+# layer cache key.
+def image_source_digest
+  fingerprints = FileList["lib/**/*", "exe/*", "gemvault.gemspec"]
+                 .select { |path| File.file?(path) }.sort
+                 .map { |path| "#{path} #{Digest::SHA256.hexdigest(File.binread(path))}" }
+  Digest::SHA256.hexdigest(fingerprints.join("\n"))
 end
 
-def destroy_cached_image
-  strays = `podman ps -aq --filter ancestor=#{CACHED_IMAGE}`.split
-  sh "podman", "rm", "-f", *strays unless strays.empty?
-  sh "podman", "rmi", CACHED_IMAGE
+def cached_image
+  ContainerImage.new(name: ContainerHelper::CACHED_IMAGE, root: __dir__, digest: image_source_digest)
 end
 
 namespace :spec do
   desc "Build cached container image with gemvault pre-installed"
-  task(:build) { build_cached_image }
+  task(:build) { cached_image.build }
 
   desc "Build the cached image unless it already exists"
-  task(:setup) { build_cached_image unless cached_image_exists? }
+  task(:setup) { cached_image.ensure_built }
 
   desc "Remove test containers and the cached image"
-  task(:teardown) { destroy_cached_image if cached_image_exists? }
+  task(:teardown) { cached_image.destroy }
 end
 
 directory "pkg" do
@@ -72,4 +85,4 @@ Rake::Task[:build].enhance ["shim:build"]
 Rake::Task[:release].enhance ["shim:release"]
 Rake::Task[:clobber].enhance ["spec:teardown"]
 
-task default: [:test, :spec, :rubocop]
+task default: [:test, :spec, :rubocop, :rubycritic]

data/_claude/archives/issue-13-root-cause.md

@@ -0,0 +1,197 @@
+# Issue #13 — `cannot load such file -- bundler/plugin/vault_source`
+
+Line references are to the vendored RubyGems/Bundler checkout in
+`references/rubygems` (`bundler-v4.0.0-1207-gf912ac9b0b`).
+
+## Symptom
+
+```
+❯ bundle install
+Fetching gem metadata from https://rubygems.org/.......
+Resolving dependencies...
+Installing bundler-source-vault 0.2.0
+
+[!] There was an error parsing `Gemfile`: cannot load such file -- bundler/plugin/vault_source. Bundler cannot continue.
+
+ #  from /Users/davidgillis/repos/reversal-store/Gemfile:19
+ >  source "vendor/vendored.gemv", type: :vault do
+```
+
+Reported as permanent. `gemvault doctor`, `rm -rf .bundle/plugin`, `rm -f
+Gemfile.lock`, and the two combined all left it unchanged.
+
+## Reproduction
+
+The reporter's `.bundle` tarball showed a plugin root holding the shim and
+nothing else:
+
+```
+.bundle/plugin/cache/bundler-source-vault-0.2.0.gem
+.bundle/plugin/gems/bundler-source-vault-0.2.0/plugins.rb
+.bundle/plugin/specifications/bundler-source-vault-0.2.0.gemspec
+.bundle/plugin/index
+```
+
+No `gemvault` anywhere. Reproduced exactly with: gemvault installed on the
+ambient `GEM_PATH`, the shim not installed, a project-local `.bundle` with a
+configured bundle path, and `bundle install` run **twice**.
+
+## Root cause
+
+Three independent mechanisms compose. Each is fine alone.
+
+### 1. Bundler never puts gemvault in the plugin root
+
+`Source::Rubygems#install` (`lib/bundler/source/rubygems.rb:206`) short-circuits:
+
+```ruby
+if (spec.default_gem? && !cached_built_in_gem(...)) || (installed?(spec) && !options[:force])
+  print_using_message "Using #{version_message(spec, options[:previous_spec])}"
+  return nil
+end
+```
+
+`installed?` (`:484`) consults `installed_specs`. On any machine where
+`gem install gemvault` has run — that is, anyone who uses the CLI — the ambient
+copy satisfies it. Bundler prints "Using gemvault" and the plugin root receives
+the shim alone. Nothing is downloaded, so the plugin root's `cache/` has no
+gemvault either, which is exactly what the reporter's tarball showed.
+
+### 2. The ambient copy disappears precisely when it is needed
+
+`Plugin::Installer#install_all_sources` calls
+`Bundler.configure_gem_home_and_path(Plugin.root)`
+(`lib/bundler/plugin/installer.rb:100`), and `configure_gem_path`
+(`lib/bundler.rb:661`) does:
+
+```ruby
+unless use_system_gems?
+  Bundler::SharedHelpers.set_env "GEM_PATH", ""
+end
+```
+
+With a configured bundle path, `use_system_gems?` is false, so `GEM_PATH`
+becomes empty and `Gem.path` collapses to the bundle. The copy that made step 1
+"safe" is now out of scope.
+
+This is why the failure is **permanent and why it starts on the second run**.
+The first `bundle install` succeeds because the ambient gemvault is still
+visible. It populates the bundle path. From then on every `bundle install`
+narrows `GEM_PATH`, and every recovery step the reporter tried rebuilds the same
+incomplete plugin root.
+
+### 3. Locating gemvault is not sufficient — activation cannot survive here
+
+The obvious repair — find gemvault and load it — has a trap. Loading it via
+`$LOAD_PATH` skips activation, and therefore skips its dependencies. gemvault
+reads a vault manifest through `json` (`lib/gemvault/manifest.rb:1`), so the
+plugin dies later, at first vault read, instead of at load.
+
+Activating instead does not work, for two separate reasons:
+
+- **The path would be stripped one line before it is used.** `Runtime#setup`
+  (`lib/bundler/runtime.rb:12-38`) runs `clean_load_path` at line 16 and
+  `@definition.specs_for(groups)` at line 18 — and resolution is what asks the
+  vault source for specs. `clean_load_path`
+  (`lib/bundler/shared_helpers.rb:371-380`) rejects a `$LOAD_PATH` entry only
+  when `loaded_gem_paths.delete(p)` is truthy, and `loaded_gem_paths`
+  (`lib/bundler/rubygems_integration.rb:132-135`) is built from
+  `Gem.loaded_specs` — i.e. **activated gems**. Activating is what would put the
+  path on the chopping block. A directory pushed without activation is absent
+  from that list, so `delete` returns nil and the entry survives.
+
+- **`Gem::Specification` cannot see outside the bundle.** `stub_rubygems`
+  (`lib/bundler/rubygems_integration.rb:336-340`) sets
+  `Gem::Specification.all = specs` and reapplies it through `Gem.post_reset`, so
+  under `bundle exec` `find_by_name` cannot find a gem installed outside the
+  bundle, and `Gem::Specification.reset` will not restore it.
+
+## Why the test suite could not catch any of this
+
+The integration container was the official `ruby` image. It differs from a
+machine anyone develops on in four ways, and each one hid one layer:
+
+| Image behaviour | What it hid |
+|---|---|
+| `gemvault` **and** `bundler-source-vault` installed system-wide | `require "bundler/plugin/vault_source"` resolved from `/usr/local/bundle` no matter what the plugin root held |
+| `BUNDLE_APP_CONFIG=/usr/local/bundle` | `Bundler::Plugin.root` was never project-local, so no spec touched a real `.bundle/plugin` |
+| `GEM_HOME` exported | a first repair that read gem roots out of the environment appeared to work |
+| `json` present as a default gem | the undeclared dependency was invisible |
+
+The first repair for this issue reconstructed gem roots from
+`Bundler.original_env`, which is a snapshot of environment variables.
+`GEM_HOME`/`GEM_PATH` are only present there if something exported them —
+rbenv, asdf, chruby, Homebrew and distro rubies export neither. The reporter is
+on rbenv (`issues.rec`: `/Users/davidgillis/.rbenv/versions/4.0.1/`,
+`rbenv 1.3.2`), so that repair passed its specs in Docker and still failed on
+their machine.
+
+The suite now runs on `fedora:44` with a distro ruby: gems in RubyGems' own
+default dirs, nothing exported, bundler a regular gem. Moving to it immediately
+surfaced two further real defects — the undeclared `json` dependency, and the
+`json/ext/parser` extension path.
+
+## The fix
+
+`shim/gemvault_load_path.rb` locates gemvault and its declared runtime
+dependencies across every root that could hold them, and pushes their require
+paths onto `$LOAD_PATH`.
+
+- **`Gem.default_path` is the load-bearing root.** It is what RubyGems knows
+  about its own gem roots, independent of the narrowing in step 2, so it covers
+  rubies that export nothing. `Bundler.original_env` is still consulted, for the
+  rubies that do export a root outside those defaults, such as RVM.
+- **`$LOAD_PATH`, not activation**, for the reasons in step 3.
+- **Dependencies resolved by hand**, using `full_require_paths`
+  (`lib/rubygems/basic_specification.rb:172-183`), which appends `extension_dir`
+  when `have_extensions?` — without it `json/ext/parser` is unfindable, since
+  json's compiled half lives outside its gem directory.
+- **A dependency that cannot be found is skipped rather than fatal.** That is
+  the one thing activation could not do: it would abort on `command_kit`, which
+  only the CLI needs.
+- **`json` is now a declared runtime dependency**, so `gemvault new` works on a
+  stock distro ruby.
+
+## Does the suite actually protect this?
+
+Green is not evidence on its own — the whole reason this bug shipped is that a
+green suite was being satisfied by an ambient gem. So the two pieces of the fix
+were checked by mutation:
+
+| Mutation | Result |
+|---|---|
+| `Gem.default_path` dropped from the searched roots | 18 examples fail |
+| the shim's pinned gemvault requirement ignored, so the newest wins | both examples of the upgrade-residue scenario fail |
+
+Restoring each returns the suite to green.
+
+## Platforms verified
+
+| Platform | Status |
+|---|---|
+| CRuby 4.0.6, Fedora 44, aarch64 | Full suite, 265 examples |
+| JRuby 10.1.1.0 (the reporter runs 10.1.0.0) | Verified once by hand, **not covered by the suite**: vault create/add/list, `bundle install` twice against a vault source, `bundle exec require`. `json 2.21.1 (java)` installed as a platform gem and resolved, which is the case `full_require_paths` has to get right |
+| macOS `arm64-darwin-24` | **Not verified.** The reporter's own platform. Nothing here can run it |
+
+JRuby has no permanent coverage because JRuby caps its own heap from the cgroup
+and the development sandbox is small enough that the cap lands at 148 MB, where
+even a single `gem fetch` dies. The one successful hand-run above happened in a
+lucky memory window and did not reproduce. A JRuby image, rake task and spec
+were written and then reverted rather than shipped unverified: harness code
+nobody has watched pass is the same defect as a spec that cannot fail. On a
+machine with ordinary memory this is worth adding, and it is the highest-value
+gap left, since issue #13 was reported against JRuby as well as CRuby.
+
+## Coverage
+
+`spec/support/vault_sourced_gemfile_examples.rb` applies "a complete bundle" to
+a vault-sourced Gemfile and then re-applies it after each user action: deleting
+`Gemfile.lock`, deleting `.bundle`, deleting both, removing the vaulted gem,
+adding a gem from rubygems, adding the project's own gemspec (the reporter's
+Gemfile shape), adding another gem from the same vault, and adding one from a
+second vault. `spec/integration/vaulted_project_spec.rb` runs that whole
+group under four bundler configurations — stock, an install path chosen, that
+path undone, and the project's gems cached — and
+`spec/integration/no_ambient_gemvault_spec.rb` covers the machine that has no
+gemvault of its own, where the plugin root has to carry the whole dependency
+set.

data/docs/Rakefile.vault_example

@@ -0,0 +1,76 @@
+require "rake/clean"
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+require "open3"
+
+def gemvault_contains?(gemvault_file, gem)
+  response, status = Open3.capture2e("gemvault", "list", gemvault_file)
+  unless status.success?
+    warn "Failed to list gems in vault:"
+    warn response
+    exit 1
+  end
+  gems = response.lines(chomp: true)
+  gemname_and_version = Pathname(gem).basename.sub_ext("").to_s
+  gems.include?(gemname_and_version)
+end
+
+def in_root_dir(&)
+  chdir(Bundler.root, &)
+end
+
+def gemvault(*, **)
+  sh "gemvault", *, **
+end
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList["spec/**/*_spec.rb"]
+end
+
+RuboCop::RakeTask.new
+CLOBBER.include "dist"
+
+desc "Generate a new cop with a template"
+task :new_cop, [:cop] do |_task, args|
+  require "rubocop"
+
+  cop_name = args.fetch(:cop) do
+    warn "usage: bundle exec rake new_cop[Department/Name]"
+    exit!
+  end
+
+  generator = RuboCop::Cop::Generator.new(cop_name)
+  generator.write_source
+  generator.write_spec
+  generator.inject_require(root_file_path: "lib/rubocop/cop/kaizo_cops.rb")
+  generator.inject_config(config_file_path: "config/default.yml")
+
+  puts generator.todo
+end
+
+directory "dist" do
+  mkdir "dist"
+end
+
+file "dist/vault.gemv" => "dist" do
+  in_root_dir do
+    gemvault "new", "dist/vault.gemv"
+  end
+end
+
+ENV["gem_push"] = "0"
+namespace :release do
+  desc "release to a vault"
+  task vault: ["dist/vault.gemv", :build] do
+    FileList["pkg/*.gem"].each do |v|
+      in_root_dir do
+        gemvault "add", "dist/vault.gemv", v unless gemvault_contains? "dist/vault.gemv", v
+      end
+    end
+  end
+end
+
+Rake::Task[:release].enhance ["release:vault"]
+
+task default: [:spec, :rubocop]