gemvault 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c643dd2d86d0a918dbecb5a8f20026746a0e60670eaa5590009fe35e6f9b9b0
-  data.tar.gz: fa0f695ae5d5d9ab9686caa479cc89c2c6954fc8c53bfdd02841cf12578622bd
+  metadata.gz: 6a1d5d0c990e232ac54514f5837db4224d92b127175f370a3443c8d15d44099f
+  data.tar.gz: ab40029793c2dd05206b9812e27da8921eb7fc478164f71fa7485296d5455f15
 SHA512:
-  metadata.gz: d16d9d84c05c143a2372eaee7bd55b162aca32019a4709227f689ce47a4c725bd4d2d8a64b9b788f32d107ec37ae8c61b73178d547e60613a221bd55d48aff53
-  data.tar.gz: 21b8fbd66feeea5146546632f5636a194c698c2ab6aa1d51ae0d9544b021dc15f32d4c1171a98e92c67fe62b56cfe2f57dab5138fef2c8dc6a4bb5d194b1952d
+  metadata.gz: 916b9a114590c9eb5fa3a377d59e9639c33a28e948429b8bac18399473eba0dcacf6711a9808106e3f91348945d71ebd051c1f65fe05239f9804289f56fcf859
+  data.tar.gz: 9ea36ee67195ca7f7a8bafd7ebc8658e000b72bcbf72356e3a2266c2f8d2679e0d8f5212f0b977a36a36c95441152f2dabae8ada78c5831770c0cd3498c4253d

data/.rubocop.yml

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

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

@@ -77,6 +77,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 +93,66 @@ 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` and `rubocop`.
 
-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
+four 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.
+
+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` (~> 2.0) — runtime; backs the tarball vault's manifest. A default gem upstream, but distros package it separately, so it is declared. Because the shim loads gemvault off `$LOAD_PATH` without activating it, it has to put json's require paths on `$LOAD_PATH` itself — see `dependency_specs` and `entries` in `shim/gemvault_load_path.rb`.
 - `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,14 +1,26 @@
-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/
+# redhat-rpm-config carries the hardening specs Fedora's ruby-devel compiles
+# extensions against; without it every native gem fails in extconf. Any Fedora
+# machine that can build a gem has it.
+RUN dnf -y install --setopt=install_weak_deps=False \
+        ruby ruby-devel rubygem-bundler \
+        gcc make redhat-rpm-config sqlite-devel tar \
+    && 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
@@ -16,10 +28,43 @@ RUN cd /tmp/build \
 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.
+# index at spec runtime, kept for offline use: command_kit and json are
+# gemvault's runtime dependencies, and `bundle plugin install` resolves them
+# against the Gemfile's sources with GEM_PATH already narrowed to the plugin
+# root, so an ambient copy does not satisfy it -- every declared dependency has
+# to be servable from the index. The bundler gem lets specs reinstall bundler
+# in place.
 RUN mkdir -p /opt/gems \
     && cd /opt/gems \
     && gem fetch command_kit -v 0.6.0 \
+    && gem fetch json -v "~> 2.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,14 +24,29 @@ RuboCop::RakeTask.new
 require "gempilot/version_task"
 Gempilot::VersionTask.new
 
-CACHED_IMAGE = "gemvault-test:latest".freeze
+require "digest"
+require_relative "spec/support/container_helper"
+
+CACHED_IMAGE = ContainerHelper::CACHED_IMAGE
+
+# Dockerfile.test reads the tree through a bind mount, whose contents podman
+# does not fold into its layer cache key. Feeding this digest in as a build arg
+# is what makes `rake spec:build` notice that the source changed.
+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 cached_image_exists?
   system("podman", "image", "exists", CACHED_IMAGE, out: File::NULL, err: File::NULL)
 end
 
 def build_cached_image
-  sh "podman", "build", "--network=host", "-t", CACHED_IMAGE, "-f", "Dockerfile.test", "."
+  sh "podman", "build", "--network=host", "-v", "#{__dir__}:/src:ro,z",
+     "--build-arg", "SOURCE_DIGEST=#{image_source_digest}",
+     "-t", CACHED_IMAGE, "-f", "Dockerfile.test", "."
 end
 
 def destroy_cached_image

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]

data/issues.rec

@@ -57,9 +57,9 @@ Description: Installing bundler-source-vault 0.1.2
 + 	from /Users/davidgillis/.rbenv/versions/4.0.1/lib/ruby/site_ruby/4.0.0/rubygems.rb:304:in 'Gem.activate_and_load_bin_path'
 + 	from /Users/davidgillis/.rbenv/versions/4.0.1/bin/bundle:25:in '<main>'
 + /Users/davidgillis/.rbenv/versions/4.0.1/lib/ruby/gems/4.0.0/gems/bundler-4.0.8/lib/bundler/source_list.rb:59:in 'Bundler::SourceList#add_plugin_source': undefined method 'new' for nil (NoMethodError)
-+
++ 
 +       add_source_to_list Plugin.source(source).new(options), @plugin_sources
-+
++ 
 + RESOLUTION: replicated by spec/integration/bundle_install_spec.rb ("path-installed
 + bundler plugin's source directory has been renamed"): Bundler's plugin index pins
 + the absolute path, and `gemvault doctor` clears it and reinstalls. Installing the
@@ -86,7 +86,7 @@ Description: Steps to replicate:
 + ```
 + 
 + Where vendored.gemv is the name of the old file, and there is still an entry in Gemfile.lock
-+
++ 
 + RESOLUTION: fixed on the tarvault branch; replicated by
 + spec/integration/bundle_install_spec.rb ("when the .gemv file is renamed and the
 + Gemfile updated to match"), passing.
@@ -101,7 +101,7 @@ Description: This vault is in vendor/vendored_gems.gmv, relative to the Gemfile
 + ```
 + Installing acme 1.0.1 from vault vendored_gems.gemv
 + ```
-+
++ 
 + RESOLUTION: fixed on the tarvault branch; replicated by
 + spec/integration/bundle_install_spec.rb ("logs the relative path as written"),
 + passing.
@@ -122,7 +122,7 @@ Description: Anytime I run bundle install, I always see:
 + ```
 + 
 + This is unacceptable. these should only need to be installed once
-+
++ 
 + ANALYSIS: upstream Bundler behavior. Bundler::Plugin.gemfile_install runs on
 + every `bundle install`/`bundle update` (bundler cli/install.rb:41), re-resolves
 + the inferred plugin definition remotely, and Source::Rubygems#install checks
@@ -143,7 +143,7 @@ Description: Consider the following:
 + ```
 + 
 + Notice an absolute path was passed to --source, yet it tried to resolve locally
-+
++ 
 + RESOLUTION: fixed on the tarvault branch; replicated by
 + spec/integration/gem_install_spec.rb ("accepts a vault:// URI with an absolute
 + path" and the file:// variant), passing. URI stripping now lives in
@@ -158,7 +158,7 @@ Description: When adding a gem like 'ronin-db-0.2.1.patch1.gem', gemvault succes
 + gemvault add myvault.gemv ronin-db-0.2.1.patch1.gem # success
 + gem install --debug --verbose --clear-sources --source file://myvault.gemv ronin-db # failure
 + ```
-+
++ 
 + RESOLUTION: RubyGems semantics, not a vault bug. A version containing letters
 + (0.2.1.patch1) is a prerelease everywhere in RubyGems, and `gem install`
 + excludes prereleases unless --pre is passed; with --pre the install from a
@@ -171,7 +171,7 @@ Id: 7
 Updated: Sun, 19 Jul 2026 03:27:39 +0000
 Name: Gemvault pollutes project dir with plugin files in .bundle
 Description: Why is it not using the plugin that is already installed globally?
-+
++ 
 + ANALYSIS: two parts. (1) Global `bundle plugin install bundler-source-vault`
 + crashed outright (issue #10's bug also hit the global root); that is fixed and
 + covered by spec/integration/plugin_install_spec.rb ("when run outside any
@@ -192,7 +192,7 @@ Description: Consider the following:
 + ```
 + 
 + Notice an absolute path was passed to --source, yet it tried to resolve locally
-+
++ 
 + RESOLUTION: duplicate of #5; see its resolution.
 Status: closed
 
@@ -200,7 +200,7 @@ Id: 9
 Updated: Sun, 19 Jul 2026 03:27:39 +0000
 Name: Gemvault commands should also be able to accept a uri
 Description: e.g. gemvault list vault:///Users/davidgillis/repos/vault/rubylib/myvault.gemv
-+
++ 
 + RESOLUTION: implemented. Gemvault::VaultPath resolves vault:// and file://
 + locators (absolute and two-slash relative forms) and every CLI command that
 + opens a vault goes through it, as does the RubyGems source. Covered by
@@ -617,7 +617,7 @@ Description:
 + https://github.com/ruby/rubygems/search?q=cannot+load+such+file+--+bundler%2Fplugin%2Fvault_source&type=Issues
 + 
 + If there aren't any reports for this error yet, please fill in the new issue form located at https://github.com/ruby/rubygems/issues/new?labels=Bundler&template=bundler-related-issue.md. Make sure to copy and paste the full output of this command under the "What happened instead?" section.
-+
++ 
 + RESOLUTION: two root causes, both fixed. (1) `bundle plugin install` switches
 + GEM_HOME to the plugin root mid-process, and RubyGems' spec stub cache is
 + populated during resolution, before gemvault is installed there; the shim's
@@ -637,14 +637,14 @@ Id: 11
 Updated: Sun, 19 Jul 2026 03:56:57 +0000
 Name: CI tests aren't running
 Description: CI tests should be running on all platforms
-+
++ 
 + ANALYSIS: .github/workflows/ci.yml exists (unit tests, specs, rubocop on
 + push/PR to master). Two likely reasons it cannot go green: (1) `rake rubocop`
 + exits nonzero on the pre-existing Gemspec/RequiredRubyVersion offenses
 + (required_ruby_version ">= 3.4.8" vs TargetRubyVersion 4.0 in .rubocop.yml) --
 + pick one and align; (2) `rake spec` builds/uses a podman image, so the runner
 + needs podman available. Not replicable as a podman rspec spec (CI infra).
-+
++ 
 + RESOLUTION: three blockers fixed. (1) TargetRubyVersion aligned to 3.4.8, the
 + gemspec floor, clearing the Gemspec/RequiredRubyVersion offenses; whole
 + tracked tree is rubocop-clean. (2) The integration job invoked
@@ -663,14 +663,14 @@ Updated: Sun, 19 Jul 2026 03:27:39 +0000
 Name: bundle exec fails after successful bundle install with path vendor
 Description: Reported 2026-07-19 (reversal-store): bundle install succeeds, then
 + any `bundle exec` fails while parsing the Gemfile:
-+
++ 
 + ```
 + [!] There was an error parsing `Gemfile`: Could not find 'bundler' (>= 2.0)
 + among 101 total gem(s)
 + Checked in 'GEM_PATH=/workspace/vendor/ruby/4.0.0' at:
 + /workspace/.bundle/plugin/specifications/gemvault-0.1.5.gemspec
 + ```
-+
++ 
 + RESOLUTION: gemvault declared bundler as a runtime dependency. Under
 + `bundle exec` with path vendor, GEM_PATH is restricted to the app bundle, and
 + on rubies where bundler is a regular (non-default) gem its spec is invisible,
@@ -681,3 +681,79 @@ Description: Reported 2026-07-19 (reversal-store): bundle install succeeds, then
 + reinstalling bundler as a regular gem and deleting its default-gem spec stub;
 + also covers the system-installed (`gem install gemvault`) flow. Both passing.
 Status: closed
+
+Id: 13
+Updated: Sun, 26 Jul 2026 20:33:33 -0400
+Name: bundle install fails, nothing seems to fix it
+Description: bundle install does not complete successfully (ruby 4.0.1 &jruby 10.1.0.0). Tried doing all of these:
++ 1. gemvault doctor (below, completes successfully, but another bundle install fails)
++ 2. rm -rf .bundle/plugin && bundle install
++ 3. rm -f Gemfile.lock && bundle install
++ 4. 2 & 3 combined before bundle install
++ 
++ ```
++ jruby -S gemvault doctor
++ Uninstalled plugin bundler-source-vault
++ Fetching gem metadata from https://rubygems.org/.......
++ Resolving dependencies...
++ Installing bundler-source-vault 0.2.0
++ Installed plugin bundler-source-vault
++ Bundle complete! 15 Gemfile dependencies, 50 gems now installed.
++ Bundled gems are installed into `./vendor`
++ ❯ 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
++  #    gem 'jarpack', "~> 0.2.1"
++  #  -------------------------------------------
++ ```
++ 
++ RESOLUTION: the plugin root never held gemvault, and the shim's require had no
++ way to reach the copy that did exist. Bundler's Source::Rubygems#install
++ short-circuits on `installed?(spec) && !force`, so a plugin dependency already
++ present on the ambient GEM_PATH is never downloaded into the plugin root --
++ which is every machine where `gem install gemvault` has run. That stays hidden
++ until the app bundle is populated: from the second `bundle install` onward
++ Bundler restricts GEM_PATH to the bundle, the ambient gemvault falls out of
++ scope, and nothing is left to resolve. Hence the reported permanence: step 2-4
++ all rebuild the same incomplete plugin root. shim/plugins.rb now locates
++ gemvault's lib across every root that can hold it, including the ones Bundler
++ masked (Bundler.original_env GEM_HOME/GEM_PATH), and puts it on $LOAD_PATH
++ instead of relying on gem activation. Using $LOAD_PATH also fixes a second
++ failure found while reproducing this -- `Could not find 'command_kit' (~> 0.6)`
++ when gemvault does land in the plugin root -- because activation demands the
++ full runtime dependency set while vault_source.rb reaches the rest of gemvault
++ through require_relative alone.
++ 
++ The integration suite could not have caught this. Dockerfile.test installed
++ gemvault AND bundler-source-vault system-wide, so `require
++ "bundler/plugin/vault_source"` resolved from the ambient GEM_HOME no matter
++ what the plugin root contained, and the ruby base image's
++ BUNDLE_APP_CONFIG=/usr/local/bundle moved Bundler::Plugin.root out of the
++ project so no spec ever exercised a project-local .bundle/plugin. The shim is
++ no longer installed system-wide (specs resolve it from the local gem index),
++ BUNDLE_APP_CONFIG is unset in the container, and gemvault stays installed
++ system-wide on purpose because that is the trigger. Removing the mask turned 13
++ previously green specs red; all now pass against the tree's shim rather than an
++ ambient copy. Replicated by spec/integration/plugin_root_deps_spec.rb (repeated
++ bundle install, and bundle exec under a restricted GEM_PATH).
+Status: closed
+
+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
+
+Id: 15
+Updated: Wed, 29 Jul 2026 17:39:23 -0400
+Name: gemvault new fails on path/to/gemvault.gemv
+Description: I did it in /tmp, maybe that's why?
+Status: open

data/lib/gemvault/version.rb

@@ -1,3 +1,3 @@
 module Gemvault
-  VERSION = "0.2.0".freeze
+  VERSION = "0.2.2".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gemvault
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - David Gillis
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 description: Portable .gemv archives for bundling and distributing multiple gems as
   a single file, read directly by Bundler and RubyGems
 email:
@@ -36,18 +50,19 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
-- ASSESSMENT.md
 - CHANGELOG.md
 - CLAUDE.md
 - Dockerfile.test
-- LICENSE
 - LICENSE.txt
-- MACROPLAN.md
 - README.md
 - Rakefile
-- docs/superpowers/plans/2026-04-16-container-integration-tests.md
-- docs/tarvault-findings.md
-- docs/tarvault.md
+- _claude/archives/ASSESSMENT.md
+- _claude/archives/MACROPLAN.md
+- _claude/archives/issue-13-root-cause.md
+- _claude/archives/plans/2026-04-16-container-integration-tests.md
+- _claude/archives/tarvault-findings.md
+- _claude/archives/tarvault.md
+- docs/Rakefile.vault_example
 - exe/gemvault
 - issues.rec
 - lib/bundler/plugin/vault_source.rb
@@ -104,7 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Multi-gem portable archives — a gem server in a file
 test_files: []

data/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.