gemkeeper 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88d9b763777c56c907c9c945fb35f7a782b6be529d7af8f38b5d14a899cda825
-  data.tar.gz: 201987b7a1d4307548b8d7f020fb25a2e7ecf274f85e37f5156a26065fde8fa4
+  metadata.gz: eb3f426b4f46c874ec2f771bf5358fecbc16b5bf89c2aa4f98b156f5b2a6f5f3
+  data.tar.gz: 18f4c1ddff554048708f75c9c0fdee83aa2376302510f16bb27c8a7c6c74bd9b
 SHA512:
-  metadata.gz: 79924f19d7da544373cdd0d213e818a1b4fc1411651bdc1819d331fb16a9361200e20a2de52b4319ebac064bf64bc14503abae89d8463e2d522e04d9f840c4d1
-  data.tar.gz: 3e175013111f44149a4c3273fb21fa1fe1785763713fd14eb698e33dcd9b898933a5e6a485d76c5fe0e23ef1f3ed5a4d8f92aff5fea85793e94dda4b1a7e3b9a
+  metadata.gz: ad2ac96a3426d7d6f5102b5ee53fb0db42f965937c6a19a9cff0105d51adc5ad9ff64ef7270de37c64f327184dd2a5e2984ba27b8d80f7c55451a23fe5a52e7a
+  data.tar.gz: 663465d415e7a30f0d74b092344b169968ab798cfad747673fdfa5f0371d61eb8ff974cfb9500c00b969390c77786286c38fc476754cdabba3119c604828c9ac

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [0.8.1] - 2026-05-29
+
+### Changed
+
+- Updated gemspec description to reflect the current compact index server architecture; removes the stale "Gem in a Box" reference.
+- Declared `rack` as an explicit gemspec dependency; it was previously relied on transitively via `rackup`.
+- Removed stale dev dependencies (`builder`, `irb`, `ostruct`) from the Gemfile.
+
 ## [0.8.0] - 2026-05-29
 
 ### Changed
@@ -186,7 +194,8 @@
 
 - Initial release
 
-[Unreleased]: https://github.com/danhorst/gemkeeper/compare/v0.8.0...HEAD
+[Unreleased]: https://github.com/danhorst/gemkeeper/compare/v0.8.1...HEAD
+[0.8.1]: https://github.com/danhorst/gemkeeper/compare/0.8.0...0.8.1
 [0.8.0]: https://github.com/danhorst/gemkeeper/compare/0.7.2...0.8.0
 [0.7.2]: https://github.com/danhorst/gemkeeper/compare/0.7.1...0.7.2
 [0.7.1]: https://github.com/danhorst/gemkeeper/compare/0.7.0...0.7.1

data/lib/gemkeeper/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Gemkeeper
-  VERSION = "0.8.0"
+  VERSION = "0.8.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gemkeeper
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Dan Brubaker Horst
@@ -80,6 +80,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: rackup
   requirement: !ruby/object:Gem::Requirement
@@ -94,8 +108,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-description: An opinionated wrapper around Gem in a Box to manage private gems in
-  a development environment.
+description: A utility for building and hosting private gems locally and proxying
+  to RubyGems for the rest.
 email:
 - dan.brubaker.horst@gmail.com
 executables:
@@ -154,19 +168,6 @@ files:
 - lib/gemkeeper/version.rb
 - mise.toml
 - sig/gemkeeper.rbs
-- specs/20260518-154733-gemkeeper-contractor-support/implementation-summary.md
-- specs/20260518-154733-gemkeeper-contractor-support/spec.md
-- specs/20260529-091429-replace-geminabox-compact-proxy/critique-consolidated-v-1.md
-- specs/20260529-091429-replace-geminabox-compact-proxy/critique-v-1-claude.md
-- specs/20260529-091429-replace-geminabox-compact-proxy/critique-v-1-codex.md
-- specs/20260529-091429-replace-geminabox-compact-proxy/critique-v-1-copilot.md
-- specs/20260529-091429-replace-geminabox-compact-proxy/spec.md
-- specs/20260529-131354-sync-serve-cache-contract/critique-consolidated-v-1.md
-- specs/20260529-131354-sync-serve-cache-contract/critique-v-1-claude.md
-- specs/20260529-131354-sync-serve-cache-contract/critique-v-1-codex.md
-- specs/20260529-131354-sync-serve-cache-contract/critique-v-1-copilot.md
-- specs/20260529-131354-sync-serve-cache-contract/implementation-summary.md
-- specs/20260529-131354-sync-serve-cache-contract/spec.md
 homepage: https://github.com/danhorst/gemkeeper
 licenses:
 - MIT

data/specs/20260518-154733-gemkeeper-contractor-support/implementation-summary.md

@@ -1,75 +0,0 @@
-# Implementation Summary: 20260518-154733-gemkeeper-contractor-support
-
-**Status:** Completed
-**Date:** 2026-05-18
-
-## Overview
-
-Implemented contractor support for gemkeeper: a `setup` command that generates config from a
-Gemfile.lock + org manifest, lockfile-aware sync with idempotency and partial failure handling,
-localhost-only server binding, ref injection protection, and a contractor setup sequence in the README.
-
-Also fixed a pre-existing test failure (`test_checkout_version_with_tag`) caused by
-`tag.gpgSign = true` in global git config silently breaking tag creation in test helpers.
-
-## Files Created
-
-- `lib/gemkeeper/lockfile_parser.rb` — walks directories for Gemfile.lock, parses GEM section
-- `lib/gemkeeper/manifest_reader.rb` — loads `~/.config/gemkeeper/manifest.yml`
-- `lib/gemkeeper/cli/commands/setup.rb` — `gemkeeper setup` command (FR-1.1, FR-1.2)
-- `test/gemkeeper/test_lockfile_parser.rb` — unit tests for LockfileParser
-- `test/gemkeeper/test_manifest_reader.rb` — unit tests for ManifestReader
-- `test/integration/test_setup_integration.rb` — integration tests for setup command
-- `test/fixtures/sample.lock` — fixture Gemfile.lock with GEM and GIT sections
-- `test/fixtures/sample_manifest.yml` — fixture manifest with 3 internal gems
-
-## Files Modified
-
-- `lib/gemkeeper/errors.rb` — added `ManifestNotFoundError`
-- `lib/gemkeeper/configuration.rb` — `from_lockfile?` predicate, version validation (AR-4.1)
-- `lib/gemkeeper/git_repository.rb` — `validate_ref!` (AR-3.2), `checkout_resolved_version` (FR-2.1)
-- `lib/gemkeeper/server_manager.rb` — `--host 127.0.0.1` in both cmd builders (AR-3.1); extracted `build_start_cmd` / `build_foreground_cmd` helpers
-- `lib/gemkeeper/cli/commands/sync.rb` — `from_lockfile` resolution, idempotency skip, partial failure collection, auth error detection (FR-2.1–2.4)
-- `lib/gemkeeper/cli.rb` — require setup command
-- `lib/gemkeeper.rb` — require lockfile_parser, manifest_reader
-- `test/gemkeeper/test_configuration.rb` — tests for `from_lockfile?`, validation
-- `test/gemkeeper/test_git_repository.rb` — tests for ref validation
-- `test/gemkeeper/test_server_manager.rb` — tests for `--host 127.0.0.1`
-- `test/integration/test_cli_integration.rb` — tests for skip-cached, from_lockfile error, partial failure
-- `test/integration/test_git_repository_integration.rb` — fixed `tag.gpgSign`/`commit.gpgSign` in helpers
-- `README.md` — Contractor Setup section (FR-4.1), HTTPS URL examples (FR-4.2)
-
-## Test Results
-
-```
-89 runs, 207 assertions, 0 failures, 0 errors, 0 skips
-bundle exec rubocop: no offenses detected
-```
-
-Baseline before implementation: 57 runs (1 pre-existing error fixed before starting).
-
-## Spec Adherence
-
-| Requirement | Status | Implementation | Test |
-|-------------|--------|---------------|------|
-| FR-1.1 setup command | Done | `cli/commands/setup.rb` | `test_setup_integration.rb` (7 tests) |
-| FR-1.2 bundle config output | Done | `setup.rb:print_bundler_instructions` | `test_setup_prints_bundle_config_instruction` |
-| FR-2.1 from_lockfile resolution | Done | `sync.rb:resolve_version`, `git_repository.rb:checkout_resolved_version` | `test_sync_from_lockfile_no_lockfile_exits_nonzero` |
-| FR-2.2 skip cached versions | Done | `sync.rb:cached?` | `test_sync_skips_already_cached_gem` |
-| FR-2.3 partial failure handling | Done | `sync.rb:run_sync` + `report_failures` | `test_sync_partial_failure_continues_and_exits_nonzero` |
-| FR-2.4 git auth error handling | Done | `sync.rb:auth_error?` + `auth_failure_error` | Covered via partial failure path; no standalone auth-mock test |
-| FR-3.1 localhost-only binding | Done | `server_manager.rb:build_start_cmd/build_foreground_cmd` | `test_start_server_command_binds_to_localhost` |
-| FR-4.1 contractor setup sequence | Done | `README.md` Contractor Setup section | Documentation |
-| FR-4.2 HTTPS URL examples | Done | `README.md` Configuration Options | Documentation |
-| AR-3.1 --host 127.0.0.1 in rackup | Done | Both cmd builders in `server_manager.rb` | `test_start_server_*_binds_to_localhost` |
-| AR-3.2 ref validation | Done | `git_repository.rb:validate_ref!` | `test_checkout_version_rejects_unsafe_ref/spaces` |
-| AR-4.1 from_lockfile schema | Done | `configuration.rb:GemDefinition` | `test_from_lockfile_version_recognized`, `test_invalid_version_raises_error` |
-| AR-4.2 no Geminabox patching | Done | Geminabox used as-is; no monkey-patching | — |
-| AR-4.3 Bundler mirror approach | Done | `setup.rb` prints mirror cmd; README documents it | `test_setup_prints_bundle_config_instruction` |
-
-## Deviations from Spec
-
-**FR-2.4 standalone test:** The auth error message format (containing "authentication" and the docs URL)
-is exercised through the partial failure path in integration tests rather than a dedicated mock.
-A real git auth error would propagate through the same code path.
-The behavior is implemented correctly; the gap is test isolation, not coverage.

data/specs/20260518-154733-gemkeeper-contractor-support/spec.md

@@ -1,287 +0,0 @@
-# Spec 20260518-154733: Gemkeeper Contractor Support
-
-## Overview
-Contractors need to install internal Ruby gems that are normally served from a private gem
-server they cannot reach without VPN.
-This spec defines the features needed to make gemkeeper a reliable, self-service solution for
-this use case: a project setup command, lockfile-aware sync, correct server binding, and
-accurate documentation of the full setup sequence.
-The companion CLI tool that delivers the gem manifest is specified separately.
-
-## Goals
-- Let a contractor configure gemkeeper for a specific project without knowing the internal
-  gem inventory
-- Make `gemkeeper sync` idempotent against a `Gemfile.lock` with no redundant builds
-- Document the end-to-end contractor setup sequence in the gemkeeper README
-- Harden the server and sync commands against the most common failure modes
-
----
-
-## Feature 1: Project Setup Command
-
-**Who & why:** A contractor has just installed gemkeeper and has a `Gemfile.lock` in front
-of them.
-They should not need to know the names of internal gems, their GitHub URLs, or how to
-construct a `gemkeeper.yml` by hand.
-`gemkeeper setup` reads the lockfile, cross-references the org gem manifest, and
-produces a ready-to-use config.
-
-### Functional Requirements
-
-#### FR-1.1: Setup Command
-`gemkeeper setup <path-to-gemfile-lock>` reads the `GEM` section of the lockfile,
-cross-references the manifest at `~/.config/gemkeeper/manifest.yml` (override:
-`--manifest <path>`), and writes a `gemkeeper.yml` in the current directory.
-
-Each matched gem entry uses `version: "from_lockfile"` so subsequent sync calls read the
-current lockfile version rather than requiring setup to be re-run on every lockfile change.
-
-**Behavior when `gemkeeper.yml` already exists:** the command merges — it adds or updates
-only entries for gems found in the manifest, leaving all other keys (port, repos_path,
-gems_path, unrelated gem entries) untouched.
-Pass `--force` to overwrite the file entirely.
-
-**Error cases:**
-- Manifest not found at default or `--manifest` path → fail with message directing the user
-  to install the org's gem manifest
-- Gem appears in lockfile with a name matching an internal pattern but absent from manifest →
-  warn and skip, do not fail
-
-**Verify:** Running `gemkeeper setup /path/to/Gemfile.lock` in a directory with no prior
-config produces a `gemkeeper.yml` listing only the internal gems the lockfile references, each
-with `version: "from_lockfile"`.
-
-#### FR-1.2: Bundler Configuration Output
-After setup completes, the command prints the `bundle config` command the developer
-must run to redirect their project's internal gem source to the local Geminabox.
-If the manifest includes a `source_url` field, that URL is used as the mirror key.
-Otherwise, the command prints a generic placeholder the developer must fill in.
-Example output:
-```
-To point Bundler at your local Geminabox, run:
-  bundle config set --local mirror.<private-gem-source-url> http://localhost:9292
-```
-The port in the command matches the configured port in `gemkeeper.yml` (default: 9292).
-`git:` source declarations in the Gemfile are unaffected and require no mirror config.
-
-**Verify:** After running the printed command, `bundle install` resolves internal gems from
-the local Geminabox and public gems from rubygems.org without modifying any tracked file.
-
----
-
-## Feature 2: Lockfile-Aware Sync
-
-**Who & why:** With `version: "from_lockfile"` in the config, sync must read the lockfile,
-resolve the correct git checkout ref, skip versions already cached, and handle partial
-failures gracefully.
-A sync that rebuilds everything on every run, or that fails entirely on one bad gem, is not
-usable in practice.
-
-### Functional Requirements
-
-#### FR-2.1: `from_lockfile` Version Resolution
-When a gem entry specifies `version: "from_lockfile"`, `gemkeeper sync`:
-1. Walks up from the current directory to find the nearest `Gemfile.lock`
-2. Reads the gem's locked version from the `GEM` section
-3. Attempts to check out git tag `v{version}`, then `{version}`, in that order
-4. Fails with a named error if neither tag exists in the repo (naming the gem and version)
-
-If no `Gemfile.lock` is found in the directory walk, sync fails with a message naming the
-gem and the search path traversed.
-
-`version: "latest"` and explicit version tags continue to work as before.
-
-**Verify:** `gemkeeper sync` for a gem with `version: "from_lockfile"` checks out the git tag
-corresponding to the version pinned in the nearest `Gemfile.lock`.
-When no lockfile is found, the command exits non-zero with a descriptive message.
-
-#### FR-2.2: Skip Already-Cached Versions
-Before cloning, fetching, building, or uploading, `gemkeeper sync` checks whether the `.gem`
-file for the resolved version is already present in the Geminabox cache at
-`File.join(gems_path, "gems", "#{name}-#{version}.gem")`.
-If present, the gem is skipped entirely — no clone, no build, no upload.
-Re-running sync with no lockfile change is a no-op.
-
-**Verify:** First sync builds and uploads gem X at version 1.2.3.
-Second sync with no lockfile change produces no git, build, or upload activity.
-Updating the lockfile to version 1.3.0 causes sync to build and upload only that version.
-
-#### FR-2.3: Partial Failure Handling
-If one gem's clone, build, or upload fails, sync continues with the remaining gems.
-At the end of the run, sync reports all failures (gem name + error message) and exits
-non-zero if any gem failed.
-A fully successful sync exits zero.
-**Verify:** A sync with one gem that fails to build still attempts all other configured gems
-and exits non-zero with a summary of the failure.
-
-#### FR-2.4: Git Authentication Failure Handling
-When `git clone` or `git fetch` returns an authentication error, sync exits non-zero with a
-message that includes the failed repo URL and a pointer to GitHub credential setup
-documentation (`https://docs.github.com/en/authentication`).
-The raw git error may be included but the failure type must be identified specifically.
-Clone URLs must not use the embedded-token format (`https://token@github.com/...`); the
-README must warn against this pattern.
-**Verify:** Running sync against a repo with no configured GitHub credentials produces a
-message containing "authentication" and the docs URL.
-
----
-
-## Feature 3: Server and Security Hardening
-
-**Who & why:** Geminabox runs without authentication.
-Binding to `0.0.0.0` would expose an unauthenticated gem push endpoint to LAN peers, allowing
-a malicious gem to be silently installed by `bundle install`.
-Ref validation prevents argument injection from crafted manifest entries.
-
-### Functional Requirements
-
-#### FR-3.1: Localhost-Only Server Binding
-`gemkeeper server start` (and `server start --foreground`) must bind Geminabox to `127.0.0.1`
-only.
-**Verify:** After `gemkeeper server start`, `lsof -i :9292` shows the process bound to
-`127.0.0.1`, not `0.0.0.0`.
-
-### Architectural Requirements
-
-#### AR-3.1: `--host 127.0.0.1` Passed to Rackup
-The `start_server` and `start_server_foreground` methods in `ServerManager` must pass
-`"--host", "127.0.0.1"` in the rackup command array.
-This applies to both daemonized and foreground start.
-
-#### AR-3.2: Manifest Ref Validation
-Before passing any manifest-derived or lockfile-derived value to `git checkout`, gemkeeper
-validates the value against `/\A[a-zA-Z0-9._\-]+\z/`.
-Values that do not match are rejected with an error naming the offending entry.
-The existing `run_git` method uses `Open3.capture3(*cmd)` array form and is already safe from
-shell injection; this validation prevents argument injection (e.g., `--upload-pack=...`).
-
----
-
-## Feature 4: Documentation
-
-**Who & why:** A contractor following the gemkeeper README must be able to complete setup
-independently.
-The current README does not document the contractor workflow or the full sequence
-of commands needed to get `bundle install` working.
-
-### Functional Requirements
-
-#### FR-4.1: Contractor Setup Sequence
-The gemkeeper README must document the full setup sequence as a numbered checklist:
-1. Install gemkeeper (`gem install gemkeeper`)
-2. Install the org's gem manifest (mechanism provided by the org)
-3. Run `gemkeeper setup <path/to/Gemfile.lock>` in the project directory
-4. Run `gemkeeper sync` to build and cache internal gems
-5. Start the local server (`gemkeeper server start`)
-6. Configure Bundler with the command printed by step 3
-
-The checklist must note that GitHub credentials must be configured before step 4 (link to
-`https://docs.github.com/en/authentication`).
-
-**Verify:** A new contractor with no prior gemkeeper knowledge can follow the checklist and
-reach a passing `bundle install` without assistance.
-
-#### FR-4.2: HTTPS Git URL Documentation
-Config examples and the README must document HTTPS GitHub URLs
-(`https://github.com/org/repo`) as the recommended format for contractors who have not
-configured SSH keys.
-SSH URLs (`git@github.com:org/repo.git`) must be noted as an alternative.
-**Verify:** The README config examples use HTTPS URLs.
-
----
-
-## Architectural Requirements (Cross-Cutting)
-
-#### AR-4.1: `from_lockfile` Schema in Configuration
-`from_lockfile` is a new reserved string in `Configuration::GemDefinition`, validated
-alongside `"latest"`.
-The existing `latest?` predicate is joined by a `from_lockfile?` predicate.
-`gemkeeper.yml` validation rejects any `version` value that is not `"latest"`,
-`"from_lockfile"`, or a string matching `/\A[a-zA-Z0-9._\-]+\z/`.
-
-#### AR-4.2: No Geminabox Patching
-All sync logic, idempotency tracking, and version resolution lives in gemkeeper code.
-Geminabox is used as a Rack dependency without modification.
-`rubygems_proxy = true` is already set in the generated `config.ru` and requires no change.
-
-#### AR-4.3: Bundler Mirror over Source Block
-`gemkeeper setup` prints a `bundle config set --local mirror.X Y` instruction rather than
-suggesting a Gemfile source block, because the mirror approach requires no change to the
-committed `Gemfile` or `Gemfile.lock`.
-
----
-
-## Integration Points
-
-- gemkeeper setup → `~/.config/gemkeeper/manifest.yml` (written by the org's manifest installer)
-- gemkeeper sync → GitHub (HTTPS or SSH clone; no private gem server required)
-- gemkeeper server → Geminabox (Rack app, localhost only)
-- gemkeeper → Bundler (mirror config, local scope, printed by setup)
-
-## Related Specs
-
-The companion CLI tool that delivers `~/.config/gemkeeper/manifest.yml` is out of scope for this repo.
-
-## Constraints
-- Geminabox is used as a dependency, not modified
-- Ruby >= 3.1.0 (existing gemspec requirement)
-
-## Out of Scope
-- Automating manifest updates on gem release
-- Centrally hosted gem mirror
-- Windows support
-- Gems declared via `git:` source blocks (these already resolve via GitHub; no caching needed)
-- CI/CD pipeline support (contractors and local dev only for this spec)
-
----
-
-## Spec Completeness Checklist
-
-- [x] **Scope & acceptance criteria** — FR-1.1 through FR-4.2 have Verify: lines; Out of
-  Scope names exclusions; `git:` source blocks explicitly excluded
-- [x] **Testing strategy** — new commands (setup, FR-1.1; manifest-aware sync, FR-2.1–2.4)
-  follow the pattern in `test/` with unit tests per class and integration tests for CLI
-  commands; manifest loading tested with fixture YAML; lockfile parsing tested with fixture
-  lockfiles covering `GEM` and `GIT` sections; FR-3.1 server binding tested via `lsof` in
-  integration test; ref validation (AR-3.2) tested with crafted inputs
-- [x] **Existing patterns** — spec extends `Configuration::GemDefinition` (AR-4.1),
-  `GemBuilder`/`GemUploader`/`GitRepository` (sync FRs), `ServerManager` (FR-3.1);
-  `run_git` array form confirmed safe from shell injection
-- [x] **Dependencies** — no new runtime gems required; `bundler` gem used for lockfile
-  parsing if not already available (it is, as a development dependency); no other additions
-- [x] **Architecture & interfaces** — `from_lockfile` schema defined in AR-4.1; lockfile
-  search and version-to-tag mapping defined in FR-2.1; idempotency check path defined in
-  FR-2.2; server binding defined in AR-3.1; manifest interface defined in Integration Points
-- [x] **Error handling & failure modes** — FR-2.1 covers missing lockfile and missing tag;
-  FR-2.3 covers partial sync failure; FR-2.4 covers git auth failure; FR-1.1 covers missing
-  manifest; AR-3.2 covers invalid refs; known limitation: disk-present ≠ upload-confirmed
-  (see Assumptions & Risks #3)
-- [x] **Security review** — `run_git` uses `Open3.capture3(*cmd)` array form (safe); AR-3.2
-  adds ref validation; AR-3.1 binds to localhost; FR-2.4 prohibits embedded-token URLs;
-  no credentials stored by gemkeeper
-- [x] **Performance impact** — idempotency check (FR-2.2) skips entire clone/build/upload
-  pipeline when version is cached; Geminabox proxies public gems via `rubygems_proxy = true`;
-  no production system impact
-- [N/A] **Rollout & migration** — additive; existing `gemkeeper.yml` files without
-  `from_lockfile` continue to work; server binding change is transparent to users
-- [x] **Assumptions & risks** — see below
-
-### Assumptions & Risks
-
-1. **Assumption:** All contractors have HTTPS GitHub access to the internal gem repos listed
-   in the manifest.
-   The contractor setup checklist (FR-4.1) must state this as a prerequisite.
-
-2. **Assumption:** Internal gem `gemspec` files can be evaluated locally without proprietary
-   build tooling.
-   If a gem requires a non-standard build step, `gemkeeper sync` will fail.
-   Mitigation: verify `gemkeeper sync` succeeds for each gem before adding it to the manifest.
-
-3. **Known limitation:** The idempotency check (FR-2.2) confirms a `.gem` file exists on
-   disk, not that it was successfully uploaded to the running Geminabox instance.
-   A build whose upload failed will be silently skipped on re-run.
-   Mitigation: `gemkeeper list` can be used to verify what the running server holds.
-
-4. **Risk:** Gems containing native extensions produce platform-specific `.gem` files.
-   A gem cache is not portable across machines with different CPU architectures.
-   Each developer must run `gemkeeper sync` on their own machine.

data/specs/20260529-091429-replace-geminabox-compact-proxy/critique-consolidated-v-1.md

@@ -1,168 +0,0 @@
-# Spec 20260529-091429: Consolidated Critique (v1)
-
-## Overview
-
-**Critiques received from:** Claude, Copilot, Codex
-**Critiques missing:** None
-
-## Executive Summary
-
-All three critics reached the same verdict: the direction and architecture are sound, but the spec is not implementation-ready.
-The blocking issues cluster around three areas: the `/versions` merge algorithm is underspecified in ways Bundler will exercise directly; ETag/digest header generation for merged responses is absent; and security input validation is incorrectly dismissed.
-There are also several codebase assumptions that don't match reality (GemUploader response codes, `rubygems-generate_index` dependency, `list_gems` dead method).
-The fixes are additive — the spec doesn't need restructuring, just more precision in the places listed below.
-
----
-
-## Blocking Issues (must resolve before implementation)
-
-### B-1. `/versions` merge algorithm is underspecified
-
-All three critics flagged this.
-The spec says private gems "take precedence" when a name appears in both, but doesn't define the algorithm.
-
-The problems:
-
-1. **Collision semantics** — does "private takes precedence" mean: replace the entire public entry (suppressing all public versions), replace only matching version entries, or append a private-wins line and rely on Bundler's last-entry behavior? If public versions remain visible, a developer pulling `rails 7.1.0` from the private gem (a fork) will still see public rails versions and Bundler may resolve the wrong one (dependency confusion).
-
-2. **Byte stability** — Bundler caches the byte offset of the last `/versions` line it fetched and issues `Range: bytes=N-` on subsequent requests. If the merge interleaves private gems by insertion date, any new private gem shifts offsets of everything after it, corrupting Bundler's incremental update. The spec must define a stable layout: e.g., upstream public block verbatim first, private gem entries appended at the end.
-
-3. **`VersionsFile` API** — `CompactIndex.versions(versions_file, extra_gems)` takes a `CompactIndex::VersionsFile` object backed by a cached file, not a raw upstream response string. The spec must describe how the upstream body is persisted to disk and surfaced as a `VersionsFile`.
-
-**Recommendation:**
-- Cache the raw upstream `/versions` response verbatim to `cache_dir/rubygems_cache/versions`.
-- Construct a `VersionsFile` from that cached file.
-- Pass private gems as `extra_gems` so they are appended after the public block — this preserves byte stability for the public block.
-- "Precedence" means private gem entries replace the matching public name in `extra_gems` merge (public versions for colliding names are suppressed).
-
-### B-2. ETag and `Repr-Digest` for merged responses must be computed from the merged body
-
-The spec requires these headers (FR-1.3) but does not say how to derive them for merged responses.
-All three critics noted this independently.
-
-Forwarding the upstream `ETag` or `Repr-Digest` header from RubyGems.org is wrong — the merged body differs from the upstream body, so Bundler's SHA256 verification will fail and it will retry unconditionally.
-
-**Recommendation:** For all endpoints serving merged or locally-generated content (`/versions`, `/info/:gemname` for private gems, `/names`), compute `ETag` and `Repr-Digest: sha-256=<base64>` from the final response body. Do not forward upstream headers unchanged.
-Pick SHA256 for ETag (avoids a second hash pass; consistent with `Repr-Digest`).
-
-### B-3. `info_checksum` has a circular dependency
-
-Copilot and Claude both identified this.
-`CompactIndex::GemVersion#info_checksum` is the SHA256 of the `/info/:gemname` response body.
-To populate it in `/versions`, the server must generate the `/info` body first, hash it, and embed the hash.
-An implementer who builds the versions index before the info bodies will produce invalid checksums, causing Bundler to re-fetch unconditionally.
-
-**Recommendation:** Add an AR stating: info bodies for all private gems are generated first; their SHA256 checksums are computed and stored in memory; then the `/versions` index is built referencing those checksums. Checksums are recomputed after each successful upload.
-
-Also note: Codex flagged that `CompactIndex::GemVersion` may use `number` rather than `version` as the field name in 0.15.x. Verify the actual field names against the installed gem before implementation.
-
-### B-4. `/names` scope is undefined
-
-Copilot and Codex both flagged this.
-RubyGems.org `/names` is ~2.7 MB / ~175,000 entries.
-FR-1.1 says `/names` returns "all gem names (local and proxied)" but doesn't say whether the server fetches, caches, and merges the upstream `/names` file or scopes to a smaller subset.
-
-These produce different behavior:
-- Full public namespace: correct, but expensive.
-- Local-only + cached: bundle install fails on any public gem not already in the info cache.
-
-**Recommendation:** Treat `/names` consistently with `/versions` — fetch and cache the upstream `/names` file; merge with local private gem names; apply the same ETag/cache TTL rules as `/info/:gemname`.
-
----
-
-## Significant Gaps
-
-### G-1. Path traversal in `/gems/:filename.gem`
-
-All three critics raised this.
-The spec's security checklist marks this N/A because the server binds to 127.0.0.1.
-Localhost binding does not prevent path traversal — any local process can issue a crafted request.
-A filename like `../../gemkeeper.pid` resolves outside `gems_path/gems/`.
-The same `gemname` parameter is used to construct `https://rubygems.org/info/:gemname`, creating an SSRF vector if unvalidated.
-
-**Recommendation:** Add a validation constraint: `:gemname` and `:filename` URL parameters are validated against `/\A[a-zA-Z0-9._-]+\z/` before any filesystem or upstream URL construction. Return 400 otherwise. Additionally, assert the resolved file path is under `gems_path/gems/` before serving.
-
-### G-2. "Valid gem" definition in FR-1.2 is ambiguous
-
-All three critics flagged this.
-Three interpretations exist: (1) correct `.gem` extension; (2) parseable tar archive containing `metadata.gz`; (3) `metadata.gz` can be loaded as a Ruby gemspec without errors.
-Option 3 is dangerous — loading a gemspec can execute arbitrary Ruby.
-
-**Recommendation:** Specify option 2: validate that the file is a tar archive containing `metadata.gz` and `data.tar.gz`. Parse gemspec metadata from `metadata.gz` using `Gem::Package.new(path).spec` inside a rescue block. If parsing raises, return 422. Do not `load` or `eval` gemspec content.
-
-### G-3. Upload atomicity and `gems_path/gems/` creation
-
-Codex and Claude raised this.
-FR-1.2 does not require `mkdir_p gems_path/gems/` (the subdirectory may not exist on first run), atomic temp-file writes (concurrent uploads of different gems can interleave file writes), or cleanup of temp files after failed validation.
-
-**Recommendation:** Add to FR-1.2: create `gems_path/gems/` if absent before writing; write to a temp file in the same directory first, then `File.rename` to the target path (atomic on POSIX); delete temp file on validation failure.
-
-### G-4. Thread safety for in-memory gem index
-
-Copilot and Codex raised this.
-Puma uses a thread pool. A `GET /info/:gemname` concurrent with an upload rebuilding the in-memory index produces a data race.
-
-**Recommendation:** Add an AR: the in-memory gem index is replaced atomically via a single instance variable assignment after each full rebuild (copy-on-write pattern). Index reads do not acquire a lock; the rebuild completes into a new object before swapping.
-
-### G-5. Upstream 404 vs outage distinction in FR-3.4
-
-Codex and Copilot raised this.
-FR-3.4 says return 404 with `"Upstream unavailable and no local cache"`.
-But if RubyGems.org returns a genuine 404 (the gem does not exist), the spec's response body is misleading.
-The two cases — "upstream reachable, gem not found" and "upstream unreachable" — should produce different responses.
-
-**Recommendation:** Distinguish: upstream reachable + 404 → return 404 with no body; upstream unreachable (connection error, timeout) + no cache → return 503; upstream unreachable + cache exists → serve from cache with appropriate headers.
-
-### G-6. `GemUploader#list_gems` becomes a dead method
-
-Copilot raised this.
-`GemUploader#list_gems` calls `GET /api/v1/gems.json`, a Geminabox-specific endpoint the new server will not implement.
-The method is not called in production code (list reads the filesystem), but it is a public method that silently breaks after migration.
-
-**Recommendation:** Either add `GET /api/v1/gems.json` to the Out of Scope list and note that `list_gems` becomes a broken dead method (acceptable since it is unused), or have the server return a 404 for that path and add a note in the spec that the method should be removed or stubbed.
-
-### G-7. `rubygems-generate_index` dependency not addressed
-
-Copilot and Codex both noted that `gemkeeper.gemspec` and `Gemfile` declare `rubygems-generate_index ~> 1.0`, which exists to support Geminabox's legacy Marshal index generation.
-The spec swaps `geminabox` for `compact_index` but is silent on this.
-
-**Recommendation:** Add `rubygems-generate_index` to the list of dependencies removed in the Integration Points table.
-
----
-
-## Additional Requirements to Add
-
-| # | Source | Requirement |
-| - | ------ | ----------- |
-| AR-new-1 | All | Info bodies computed before versions index; checksums embedded in versions from pre-computed hashes |
-| AR-new-2 | All | ETag is SHA256 of merged response body for all locally-generated or merged endpoints |
-| AR-new-3 | All | `:gemname` and `:filename` URL params validated to `/\A[a-zA-Z0-9._-]+\z/` before filesystem or upstream URL use |
-| AR-new-4 | Copilot/Codex | Puma's thread count should be set to 1 (or the index swap made atomic) — specify which |
-| FR-new-1 | All | `/names` fetches, caches, and merges upstream `/names` with local gem names under the same TTL rules as `/info` |
-
----
-
-## Ambiguities to Resolve
-
-1. **ETag algorithm** — spec says "MD5 or SHA256"; pick SHA256 (consistent with `Repr-Digest`, avoids two passes).
-2. **GemUploader response codes** — spec says 201/409; actual `GemUploader#handle_response` also accepts 200 and 302 as success. Align the spec with the real code.
-3. **`/versions` cache storage** — spec is ambiguous about whether the cache stores the raw upstream body (re-merged on request) or the merged result (invalidated on upload). Specify: cache raw upstream body; re-merge with private gems in memory on request; memoize the merged result until next upload or upstream ETag change.
-4. **`CompactIndex::GemVersion` field names** — verify `number` vs `version` against the installed 0.15.x gem before referencing them in the spec.
-5. **AGENTS.md vs CLAUDE.md** — Codex noted the Integration Points table references `CLAUDE.md`, but the actual project instruction file may be `AGENTS.md`. Verify and correct.
-
----
-
-## Summary of Required Changes
-
-1. **(Blocking)** Specify the `/versions` merge algorithm: upstream verbatim block first, private gems appended via `extra_gems`, collision = suppress public entry, byte-stable layout.
-2. **(Blocking)** Specify ETag and `Repr-Digest` computation from merged body for all generated/merged endpoints.
-3. **(Blocking)** Specify `info_checksum` generation order: info bodies first, checksums embedded into versions index.
-4. **(Blocking)** Define `/names` scope: fetched, cached, merged like `/versions`.
-5. Add input validation constraint for `:gemname` and `:filename` path parameters.
-6. Clarify "valid gem" validation as tar-parseable + gemspec extractable (no eval).
-7. Add upload atomicity requirements: `mkdir_p`, temp-file write, rename.
-8. Add thread safety AR: atomic index swap after rebuild.
-9. Distinguish upstream 404 vs outage in FR-3.4 (404 vs 503).
-10. Note `list_gems` dead method and `rubygems-generate_index` removal in Integration Points.
-11. Correct GemUploader response code list (200/201/302 accepted, not just 201).
-12. Resolve ETag algorithm ambiguity (SHA256 only).