gemvault 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7de6dc35280e873a80b18d4619ef13b789525cc2e071417acbd80fe65d040ada
+  data.tar.gz: 8520005cc49b5eead43706f03c622063b330c5e391ab3d8966c6e69b4482d267
+SHA512:
+  metadata.gz: 34f5e6485abe04eaed2f39b10bf7394b89d7e7f0b3f3bd8b51b60aeeed43e140ef1b4c43e20ed0f73d6f8f60f81dcdd98eb818af67d17297db655bd239535d03
+  data.tar.gz: 52dc205f6c9f989a52881d14ebb828ab0cd8733bfad990db472307393ca62cac444ee539070f95efac91e447e4fce319730d83cb058ad697e44867a2a3876f62

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,181 @@
+# ===========================================================================
+# RuboCop Configuration
+#
+# Base: Stock RuboCop defaults
+# AI guardrails: rubocop-claude plugin (all Claude/ cops + stricter metrics)
+# Performance: rubocop-performance (with chain-hostile cops disabled)
+#
+# Philosophy: idiomatic Ruby, pipeline-style chaining, strict for AI agents,
+# readable for humans.
+# ===========================================================================
+
+plugins:
+  - rubocop-claude
+  - rubocop-rspec
+  - rubocop-performance
+  - rubocop-rake
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 4.0
+  Exclude:
+    - bin/*
+    - vendor/**/*
+    - lib/core_ext/**/*
+    - rakelib/project.rb
+    - rakelib/project_version.rb
+    - rakelib/version_tag.rb
+    - rakelib/github_release.rb
+    - rakelib/strict_shell.rb
+
+# ===========================================================================
+# Overrides from stock — personal style preferences
+# ===========================================================================
+
+# Double quotes everywhere. One less decision to make.
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+# Frozen string literal is transitional cruft. Ruby 3.4 has chilled strings,
+# full default freeze is coming in a future Ruby.
+Style/FrozenStringLiteralComment:
+  EnforcedStyle: never
+
+# Pipeline style. Chaining multi-line blocks is the whole point.
+Style/MultilineBlockChain:
+  Enabled: false
+
+# Block delimiters are a taste call. Pipeline code uses braces for chaining,
+# do/end for side effects. No cop captures this nuance.
+Style/BlockDelimiters:
+  Enabled: false
+
+# Write arrays like arrays.
+Style/WordArray:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: false
+
+# Argument indentation: consistent 2-space indent, not aligned to first arg.
+Layout/FirstArgumentIndentation:
+  EnforcedStyle: consistent
+
+# Dot-aligned chaining. Dots form a visual column.
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: aligned
+
+# ===========================================================================
+# Overrides from rubocop-claude — loosen where pipeline style conflicts
+# ===========================================================================
+
+Claude/NoOverlyDefensiveCode:
+  MaxSafeNavigationChain: 2
+
+Style/SafeNavigation:
+  MaxChainLength: 2
+
+# Allow `return a, b` for tuple-style returns.
+Style/RedundantReturn:
+  AllowMultipleReturnValues: true
+
+# ===========================================================================
+# Overrides from rubocop-performance — disable chain-hostile cops
+# ===========================================================================
+
+Performance/ChainArrayAllocation:
+  Enabled: false
+
+Performance/MapMethodChain:
+  Enabled: false
+
+# ===========================================================================
+# Additional tightening — not set by stock or rubocop-claude
+# ===========================================================================
+
+# Short blocks push toward small chained steps instead of fat lambdas.
+Metrics/BlockLength:
+  Max: 8
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+    - method_call
+  AllowedMethods:
+    - command
+    - describe
+    - context
+    - shared_examples
+    - shared_examples_for
+    - shared_context
+  Exclude:
+    - "gemvault.gemspec"
+    - "rakelib/**/*"
+
+# Gemspec and rake files use patterns that trigger Claude cops legitimately.
+Claude/NoFancyUnicode:
+  Exclude:
+    - "gemvault.gemspec"
+
+Claude/MysteryRegex:
+  Exclude:
+    - "rakelib/**/*"
+
+# Shared test contexts legitimately define many helpers.
+RSpec/MultipleMemoizedHelpers:
+  Max: 10
+
+# Anonymous forwarding (*, **, &) breaks TruffleRuby, JRuby, and
+# Ruby < 3.2. Named args are explicit and portable.
+Style/ArgumentsForwarding:
+  Enabled: false
+
+# Explicit begin/rescue/end is clearer than implicit method-body rescue.
+Style/RedundantBegin:
+  Enabled: false
+
+# Compact class names are fine for small files and tests.
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+# Classes get rdoc.
+Style/Documentation:
+  Enabled: true
+  Exclude:
+    - "spec/**/*"
+
+# Trailing commas in multiline literals and arguments.
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: comma
+
+# ===========================================================================
+# RSpec — rubocop-rspec overrides
+# ===========================================================================
+
+# Not every describe block wraps a class.
+RSpec/DescribeClass:
+  Enabled: false
+
+# Subject placement is a readability call, not a rule.
+RSpec/LeadingSubject:
+  Enabled: false
+
+# Block style for expect { }.to change { } reads like a sentence.
+RSpec/ExpectChange:
+  EnforcedStyle: block
+
+RSpec/NamedSubject:
+  Enabled: false
+
+# have_file_content matcher accepts a filename string in expect()
+RSpec/ExpectActual:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+4.0.1

data/ASSESSMENT.md

@@ -0,0 +1,88 @@
+# Gemvault: Gem Server Without a Server
+
+## The Pitch
+
+Every gem workflow that normally requires running server infrastructure — Geminabox, Gemstash, a private rubygems.org instance — gemvault does with a single SQLite file.
+
+No daemon. No port. No config. No uptime concerns. Just a `.gemv` file you can commit, sync, email, or drop on a USB stick.
+
+## What You Get Today
+
+Three integration layers, all working and tested (122 tests, 0 failures):
+
+```bash
+# CLI — manage the vault
+gemvault new myvault
+gemvault add myvault.gemv rails-7.1.0.gem sidekiq-7.2.0.gem
+gemvault list myvault.gemv
+gemvault remove myvault.gemv sidekiq
+gemvault extract myvault.gemv rails -o vendor/
+
+# Bundler — use in a Gemfile like any source
+source "myvault.gemv", type: :vault do
+  gem "rails"
+  gem "sidekiq"
+end
+
+# RubyGems — gem install, no server needed
+gem install --source myvault.gemv rails
+```
+
+All three participate in real dependency resolution. Platform gems, prereleases, version constraints, lockfiles — it all works.
+
+## Scorecard
+
+| Capability | Status | Notes |
+|-----------|--------|-------|
+| Store multiple gems in one file | Done | SQLite with ACID guarantees |
+| `bundle install` from vault | Done | Full Bundler plugin (source type `:vault`) |
+| `gem install --source` from vault | Done | RubyGems plugin, standard install pipeline |
+| Dependency resolution | Done | Both Bundler and RubyGems resolvers |
+| Platform gems (x86_64, arm64, etc.) | Done | Stored, filtered, resolved correctly |
+| Prerelease versions | Done | Filtered by `:released`/`:prerelease`/`:latest` |
+| Lockfile generation | Done | Round-trips cleanly |
+| Mixed sources (vault + rubygems.org) | Done | Vault gems + public gems coexist |
+| Add/remove/list/extract via CLI | Done | 5 commands, all tested |
+| Inspectable with standard tools | Done | It's SQLite — `sqlite3 vault.gemv ".tables"` |
+
+## What You Don't Need Anymore
+
+| Before (server) | Now (gemvault) |
+|-----------------|----------------|
+| Run Geminabox on a VM | Drop a `.gemv` file in your repo |
+| Configure Gemstash with Redis | `gemvault new private.gemv` |
+| Maintain uptime for CI to pull gems | File is right there on disk |
+| Set up auth tokens for private gems | Access = having the file |
+| Mirror rubygems.org for air-gapped deploys | `gemvault add` the gems you need |
+
+## Where It Shines
+
+**Air-gapped / offline deploys.** Bundle all your private gems into a `.gemv`, copy it to the isolated network, `bundle install` or `gem install` with no internet.
+
+**CI dependency vendoring.** Commit the `.gemv` alongside your lockfile. CI never hits rubygems.org for your private gems. No gem server to maintain, no tokens to rotate.
+
+**Distributing private gems.** Instead of publishing to a private server, `gemvault add` and hand someone the file. They `gem install --source` and they're done.
+
+**Portable gem snapshots.** Capture a known-good set of gems as a single file. Reproducible installs anywhere, forever, with no network dependency.
+
+## Remaining Gaps
+
+These are real but don't undermine the core proposition:
+
+1. **No update-in-place** — Must `remove` + `add` to replace a version. Could add `--force` flag.
+2. **Specs re-extracted on each open** — No cached spec column in SQLite yet. Works fine but adds latency for large vaults.
+3. **No `gemvault info`** — No quick way to inspect vault metadata (schema version, created date, total size).
+4. **No encryption** — Planned but not implemented. The file is readable SQLite.
+5. **Plugin setup friction** — Bundler requires a `plugin` line pointing at the local path until the gem is published to rubygems.org. RubyGems needs `RUBYLIB` set during development.
+
+## Test Coverage
+
+```
+122 runs, 0 failures, 0 errors, 0 skips
+
+test/vault_test.rb           — 33 unit tests (Vault CRUD, GemEntry, Vault.open)
+test/vault_source_test.rb    — 17 unit tests (Bundler source plugin)
+test/cli_test.rb             — 32 CLI tests
+test/integration_test.rb     — 12 end-to-end Bundler tests
+test/rubygems_plugin_test.rb — 28 RubyGems plugin tests (incl. gem install e2e)
+```

data/CLAUDE.md

@@ -0,0 +1,76 @@
+# CLAUDE.md — Gemvault
+
+## Project Overview
+
+Multi-gem portable archives backed by SQLite. A single `.gemv` file contains multiple `.gem` files.
+
+Two gems, one repo:
+
+- **`gemvault`** — the real gem. All code, CLI, RubyGems plugin. Published to rubygems.org.
+- **`bundler-source-vault`** — thin shim in `shim/`. Depends on `gemvault`, has a `plugins.rb` that registers the Bundler source. Published to rubygems.org so Bundler's `type: :vault` auto-discovery works. Users never interact with this name directly.
+
+### User experience
+
+```ruby
+# Gemfile — once both gems are published to rubygems.org, no plugin line needed:
+source "myvault.gemv", type: :vault do
+  gem "foo"
+end
+
+# Until then, point Bundler at the local source:
+plugin "bundler-source-vault", path: "/path/to/gemvault"
+```
+
+Bundler auto-infers `bundler-source-vault` → installs it → pulls in `gemvault` as dependency → `plugins.rb` registers the vault source.
+
+Also works as a RubyGems plugin:
+
+```bash
+gem install --source myvault.gemv foo
+gem install --source file:///path/to/myvault.gemv foo
+```
+
+## Architecture
+
+- `gemvault.gemspec` — main gem spec (name: `gemvault`)
+- `lib/gemvault/vault.rb` — Core vault class (SQLite CRUD for gem blobs + specs)
+- `lib/gemvault/cli.rb` — CLI dispatcher (new/add/list/remove/extract)
+- `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)
+- `lib/rubygems/resolver/vault_set.rb` — `Gem::Resolver::VaultSet` for dependency resolution
+- `exe/gemvault` — CLI executable
+- `shim/bundler-source-vault.gemspec` — thin shim gemspec depending on `gemvault`
+- `shim/plugins.rb` — Bundler plugin registration + `Gem::Specification.dirs` workaround
+- `plugins.rb` — development-only redirect to `shim/plugins.rb` (not shipped in gems)
+
+## Key Design Decisions
+
+- SQLite storage — random access, ACID, single file, inspectable with `sqlite3` CLI
+- Specs extracted from gem blobs at runtime (no separate spec storage)
+- Vault opened/closed per operation in the source plugin (no persistent connection)
+- `fetch_gemspec_files` checks installed state — Bundler computes `full_gem_path` as `dirname(loaded_from)`, so `loaded_from` must point inside the gem directory
+- `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
+
+## Testing
+
+```bash
+bundle exec rake test    # 122 tests, 289 assertions
+```
+
+- `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)
+
+Integration tests use a manually-written Bundler plugin index to avoid rubygems.org resolution during testing.
+
+## Dependencies
+
+- `sqlite3` (~> 2.0) — runtime
+- `bundler` (>= 2.0) — runtime
+- `command_kit` (~> 0.6) — runtime (CLI)
+- `minitest`, `rake` — development

data/Dockerfile.test

@@ -0,0 +1,11 @@
+FROM docker.io/library/ruby:4.0.1-slim
+
+COPY . /tmp/build/
+
+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

data/LICENSE

@@ -0,0 +1,21 @@
+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.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 David Gillis
+
+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.

data/MACROPLAN.md

@@ -0,0 +1,63 @@
+# Gemvault Implementation Plan
+
+## Context
+
+Bundler supports `path:`, `git:`, and remote sources but not `.gem` files directly. The `bundler-source-package` plugin proves single `.gem` file support works. Gemvault extends this to **multi-gem portable archives** — a single `.gemv` file containing multiple gems, backed by SQLite. Commit it, send it over Slack, reference it in your Gemfile. Like a `.jar` directory but for Ruby.
+
+```ruby
+# CLI
+gemvault new randomgems                          # creates randomgems.gemv
+gemvault add randomgems.gemv foo.gem bar.gem     # add gems
+gemvault list randomgems.gemv                    # list contents
+
+# Gemfile
+source "randomgems.gemv", type: :vault do
+  gem "foo"
+  gem "bar"
+end
+```
+
+## Phase Dependency Graph
+
+```
+Phase 1 (Vault lib + tests)
+  └──> Phase 2 (Source plugin + tests)    [needs Vault]
+           └──> Phase 3 (Integration tests)  [needs Source]
+                    └──> Phase 4 (CLI)  [thin wrapper, last]
+                              └──> Phase 5 (Encryption)  [future]
+```
+
+## SQLite Schema
+
+```sql
+CREATE TABLE metadata (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+CREATE TABLE gems (
+  name TEXT NOT NULL,
+  version TEXT NOT NULL,
+  platform TEXT NOT NULL DEFAULT 'ruby',
+  spec TEXT NOT NULL,
+  data BLOB NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (name, version, platform)
+);
+```
+
+## Status
+
+- Phase 0: Complete (project scaffolding)
+- Phase 1: Complete (core Vault library — 27 unit tests)
+- Phase 2: Complete (Bundler source plugin — 15 unit tests)
+- Phase 3: Complete (integration tests — 11 end-to-end tests)
+- Phase 4: Complete (CLI tool with CommandKit auto-loaded subcommands — 27 CLI tests)
+- Phase 5: Future (encryption)
+
+Post-phase refinements:
+- Schema: dropped `spec` column, specs derived from gem blobs at runtime
+- Tests: idiomatic Minitest assertions, Pathname throughout
+- CLI: refactored from hand-rolled dispatcher to CommandKit::Commands::AutoLoad
+
+Total: 84 tests, 215 assertions

data/README.md

@@ -0,0 +1,74 @@
+# Gemvault
+
+A gem server in a file. No HTTP. No infrastructure.
+
+A `.gemv` file is a SQLite database that contains Ruby gems. Commit it to your repo, drop it on S3, email it, put it on a USB drive — Bundler and RubyGems read from it directly. Private gems without running a server.
+
+## Installation
+
+```bash
+gem install gemvault
+```
+
+## Usage
+
+### Bundler
+
+```ruby
+# Gemfile
+source "https://rubygems.org"
+
+source "vendor/private.gemv", type: :vault do
+  gem "my_private_gem"
+end
+```
+
+```bash
+bundle install
+```
+
+Bundler auto-discovers the `bundler-source-vault` plugin, installs it, and resolves gems from the vault alongside rubygems.org. No extra configuration.
+
+### RubyGems CLI
+
+```bash
+gem install --source myvault.gemv my_private_gem
+gem install --source file:///path/to/myvault.gemv my_private_gem
+```
+
+### Creating and managing vaults
+
+```bash
+gemvault new myvault                          # creates myvault.gemv
+gemvault add myvault.gemv foo.gem bar.gem     # add .gem files
+gemvault list myvault.gemv                    # list contents
+gemvault remove myvault.gemv foo 1.0.0        # remove a gem
+gemvault extract myvault.gemv foo -o vendor/  # extract .gem file to disk
+```
+
+## How It Works
+
+A `.gemv` file is a SQLite database containing gem metadata and raw `.gem` blobs. You can inspect it directly:
+
+```bash
+sqlite3 myvault.gemv "SELECT name, version, platform FROM gems"
+```
+
+When Bundler sees `type: :vault` in your Gemfile, it auto-installs the `bundler-source-vault` plugin from rubygems.org. The plugin implements the `Bundler::Plugin::API::Source` interface — it reads gemspecs from the vault, participates in dependency resolution, then extracts and installs gems from the vault's blob storage.
+
+The RubyGems plugin works similarly: `gem install --source vault.gemv` loads specs and extracts gems on demand.
+
+## Development
+
+```bash
+git clone https://github.com/gillisd/gemvault
+cd gemvault
+bin/setup
+bundle exec rake test         # unit tests
+bundle exec rake spec         # specs + container integration tests
+bundle exec rake              # all of the above + rubocop
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,39 @@
+require "bundler/gem_tasks"
+
+require "minitest/test_task"
+
+Minitest::TestTask.create do |t|
+  t.test_globs = ["test/*_test.rb"]
+end
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new
+
+require "gempilot/version_task"
+Gempilot::VersionTask.new
+
+CACHED_IMAGE = "gemvault-test:latest".freeze
+
+namespace :spec do
+  desc "Build cached container image with gemvault pre-installed"
+  task :build do
+    sh "podman", "build",
+       "--network=host",
+       "-t", CACHED_IMAGE,
+       "-f", "Dockerfile.test",
+       "."
+  end
+end
+
+namespace :shim do
+  desc "Build the bundler-source-vault shim gem"
+  task :build do
+    Dir.chdir("shim") { sh "gem build bundler-source-vault.gemspec" }
+  end
+end
+
+task default: [:test, :spec, :rubocop]