gemkeeper 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45860b370cd7f5370ab01069c44b9547208b64b0de895e1e2e1f625d87873fec
-  data.tar.gz: 1989d795d04f3d368e5e26c419b6e8d10c59a2ae814a2d9cb28c1083d5cbf081
+  metadata.gz: 97154d493b89cc264c9de34cd0c15f3712d2e23a9757ec9fc749c436dee126d5
+  data.tar.gz: 4dba3a688a98ea40994b5979f5ef16df68ecad0cbc6fb5a8f2581abab40b0537
 SHA512:
-  metadata.gz: 9e9ef5c779e1b6928562fbb39277f605aede5f46dc3d2d6937951b926a5fc296f2d530ffb5417548ab6155586e15a2e4eba990ad369fd7a2ec983999fb070bd5
-  data.tar.gz: b83947d19960c2439d7abcb49b4aa64113c1d5333bb133ab63cf6ce71d81d62ca403145c752545c1f58e02ebfcfc6f14ff92eba03903192e1b6d321136a0fe97
+  metadata.gz: 4531fa55ac8d2f512ba602bee71752299b22e0243313ed1c3489bf6d5b9723f8d94d7a23da77a2fa2de8cd9587fac243f34fb899c3c11d43d5c6a77a05d99818
+  data.tar.gz: 85e9e466db67728d70ca25be6fec81a98717325021e5a8e38257e1b4d51fde54c91e9486e2284f0a81cd68f6bc74a9ba87d319e3c994e8567574e1de86c17c4d

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 ## [Unreleased]
 
+## [0.2.1] - 2026-05-19
+
+### Fixed
+
+- RuboCop offenses in sync command and executable (numeric predicate style, `delete_prefix`, parentheses, cyclomatic complexity).
+
+## [0.2.0] - 2026-05-19
+
+### Fixed
+
+- `version: latest` now caches by the resolved gemspec version rather than the string "latest" — re-running `sync` is a no-op if the tip hasn't changed.
+- Explicit versions accept both `v`-prefixed (`v1.2.3`) and bare semver (`1.2.3`) tag formats; the cache key is normalized to bare semver in both cases.
+- `gemkeeper --help` and `gemkeeper server --help` now exit 0.
+- Port validation raises a clear error at config load time rather than failing mid-command.
+- Running the `gemkeeper` executable directly (without `bundle exec`) no longer raises a load error.
+
+### Changed
+
+- Sync output uses ANSI colors (TTY only) to distinguish progress steps, skips, and failures.
+- `sync` prints a summary line on completion: `Sync complete: 2 synced, 1 skipped (3 total)`.
+- Version reading for `version: latest` follows `require_relative` in the gemspec and falls back to globbing `lib/**/version.rb`, covering the common pattern where the version lives in a separate constant file.
+
 ## [0.1.0] - 2026-01-29
 
 - Initial release
+
+[Unreleased]: https://github.com/danhorst/gemkeeper/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/danhorst/gemkeeper/compare/0.2.0...0.2.1
+[0.2.0]: https://github.com/danhorst/gemkeeper/compare/0.1.0...0.2.0

data/README.md

@@ -1,19 +1,256 @@
-# Gemkeeper
+![Gemkeeper](./img/gemkeeper.jpeg)
 
-An opinionated wrapper around [Gem in a Box][1] for local, sandboxed Ruby development.
+This project is an opinionated wrapper around [Gem in a Box][1] for managing private gem dependencies in an offline development environment.
 
-## Usage
+## Installation
 
-This project can be run directly on your machine or in a Docker container.
-For a local service, you'll need to install [Ruby][2], ideally with a [version manager][3].
+### Via RubyGems
 
-## Colophon
+```bash
+gem install gemkeeper
+```
 
-This project has been augmented with [Claude Code][4].
-The instructions for all agents are all in `AGENTS.md`.
-There is a utility script (`bin/agent-setup`) that takes care of symlinking `AGENTS.md` to `CLAUDE.md`.
+### Via Homebrew (MacOS)
+
+```bash
+brew tap danhorst/tap
+brew install danhorst/tap/gemkeeper
+```
+
+Forumla: [`danhorst/homebrew-tap`][2]
+
+## Workstation Setup
+
+If you cannot reach your organization's private gem server, follow these steps to use gemkeeper as a local proxy.
+
+**Prerequisites:** You must have HTTPS access to the internal gem repositories on GitHub.
+Configure GitHub credentials before step 4 — see [GitHub authentication docs][3].
+
+1. Install gemkeeper:
+
+```bash
+gem install gemkeeper
+```
+
+2. Install your org's gem manifest:
+
+Your organization should provide a command or file that writes `~/.config/gemkeeper/manifest.yml`.
+This manifest lists the internal gems and their GitHub URLs, and may include the private gem source URL used in step 6.
+
+3. Generate a `gemkeeper.yml` for your project:
+
+```bash
+gemkeeper setup path/to/Gemfile.lock
+```
+
+This reads the lockfile, cross-references the manifest, and writes a `gemkeeper.yml` in the current directory.
+It also prints the `bundle config` command you will need in step 6.
+
+4. Build and cache the internal gems:
+
+```bash
+gemkeeper sync
+```
+
+5. Start the local gem server:
+
+```bash
+gemkeeper server start
+```
+
+6. Point Bundler at the local server using the command printed by step 3:
+
+```bash
+bundle config set --local mirror.<your-private-gem-source-url> http://localhost:9292
+```
+
+Replace `<your-private-gem-source-url>` with the gem source URL declared in your `Gemfile` (the one that requires VPN or private credentials).
+The mirror approach redirects gem resolution to your local Geminabox without modifying the committed `Gemfile` or `Gemfile.lock`.
+Public gems are proxied from RubyGems.org automatically.
+
+## Quick Start
+
+1. Create a configuration file at `~/.config/gemkeeper/config.yml`:
+
+```yaml
+port: 9292
+gems:
+  - repo: https://github.com/company/internal-gem
+    version: latest
+```
+
+2. Start the server:
+
+```bash
+gemkeeper server start
+```
+
+3. Configure your Rails app to use the local gem server:
+
+```ruby
+# Gemfile
+source "http://localhost:9292" do
+  gem "internal-gem"
+end
+```
+
+4. Sync your gems:
+
+```bash
+gemkeeper sync
+```
+
+## Configuration
+
+Gemkeeper looks for configuration files in these locations (in order):
+
+1. `./gemkeeper.yml` (current directory)
+2. `~/.config/gemkeeper/config.yml`
+3. `~/.gemkeeper.yml`
+4. `/usr/local/etc/gemkeeper.yml` (Homebrew on Intel)
+5. `/opt/homebrew/etc/gemkeeper.yml` (Homebrew on Apple Silicon)
+
+### Configuration Options
+
+```yaml
+# Port for the Geminabox server (default: 9292)
+port: 9292
+
+# Where to clone gem repositories (default: ./cache/repos)
+repos_path: ./cache/repos
+
+# Where to store built gems (default: ./cache/gems)
+gems_path: ./cache/gems
+
+# PID file location (default: ./cache/gemkeeper.pid)
+pid_file: ./cache/gemkeeper.pid
+
+# List of gems to manage
+gems:
+  # HTTPS is recommended — works without SSH key setup (alternative: git@github.com:company/gem-one.git)
+  - repo: https://github.com/company/gem-one
+    version: latest    # Use the latest commit on main/master; cached by resolved gemspec version
+
+  - repo: https://github.com/company/gem-two
+    version: v1.2.3    # Use a specific tag; both v-prefixed and bare semver accepted
+
+  - repo: https://github.com/company/gem-two
+    version: from_lockfile    # Read version from the nearest Gemfile.lock
+
+  - repo: https://github.com/company/ruby-gem-three
+    name: gem-three    # Override the gem name (strips "ruby-" prefix by default)
+```
+
+## CLI Commands
+
+### Server Management
+
+```bash
+# Start the server (daemonized)
+gemkeeper server start
+
+# Start in foreground (for services/debugging)
+gemkeeper server start --foreground
+gemkeeper server start -f
+
+# Start on a specific port
+gemkeeper server start --port 8080
+
+# Stop the server
+gemkeeper server stop
+
+# Check server status
+gemkeeper server status
+```
+
+### Project Setup
+
+```bash
+# Generate gemkeeper.yml from a Gemfile.lock and org manifest
+gemkeeper setup path/to/Gemfile.lock
+
+# Use a custom manifest path
+gemkeeper setup path/to/Gemfile.lock --manifest ~/.config/myorg/manifest.yml
+
+# Overwrite existing gemkeeper.yml entirely
+gemkeeper setup path/to/Gemfile.lock --force
+```
+
+### Gem Synchronization
+
+```bash
+# Sync all configured gems
+gemkeeper sync
+
+# Sync a specific gem
+gemkeeper sync internal-gem
+```
+
+### Other Commands
+
+```bash
+# List cached gems
+gemkeeper list
+
+# Show version
+gemkeeper version
+```
+
+### Global Options
+
+All commands support:
+
+```bash
+--config PATH    # Use a specific config file
+```
+
+## Running as a Service
+
+### Homebrew Services (macOS)
+
+If installed via Homebrew:
+
+```bash
+# Start and enable at login
+brew services start gemkeeper
+
+# Stop the service
+brew services stop gemkeeper
+
+# Check status
+brew services info gemkeeper
+```
+
+### Manual Background Mode
+
+```bash
+# Start daemonized
+gemkeeper server start
+
+# Check if running
+gemkeeper server status
+
+# Stop
+gemkeeper server stop
+```
+
+## How It Works
+
+1. **Clone/Pull**: Gemkeeper clones (or pulls) gem repositories to a local cache.
+2. **Build**: Builds `.gem` files from the source at the specified version/tag.
+3. **Upload**: Uploads built gems to a local Geminabox server.
+4. **Proxy**: Geminabox proxies public gems from RubyGems.org, so you only need one gem source.
+
+This lets you use a combination of public and private gems from a single gem source.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test    # Run tests
+bundle exec rubocop      # Run linter
+```
 
 [1]: https://github.com/geminabox/geminabox
-[2]: https://www.ruby-lang.org/en/
-[3]: https://www.ruby-lang.org/en/documentation/installation/#managers
-[4]: https://claude.com/product/claude-code
+[2]: https://github.com/danhorst/homebrew-tap
+[3]: https://docs.github.com/en/authentication

data/exe/gemkeeper

@@ -1,7 +1,13 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
 require "gemkeeper"
 require "gemkeeper/cli"
 
-Dry::CLI.new(Gemkeeper::CLI).call
+begin
+  Dry::CLI.new(Gemkeeper::CLI).call
+rescue SystemExit => e
+  exit(ARGV.include?("--help") || ARGV.include?("-h") ? 0 : e.status)
+end

data/lib/gemkeeper/cli/commands/setup.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Gemkeeper
+  module CLI
+    module Commands
+      class Setup < Dry::CLI::Command
+        desc "Generate gemkeeper.yml from a Gemfile.lock and org manifest"
+
+        argument :lockfile_path, type: :string, required: true,
+                                 desc: "Path to the project's Gemfile.lock"
+        option :manifest, type: :string,
+                          desc: "Path to gem manifest (default: ~/.config/gemkeeper/manifest.yml)"
+        option :config, type: :string, desc: "Path to write gemkeeper.yml (default: ./gemkeeper.yml)"
+        option :force, type: :boolean, default: false,
+                       desc: "Overwrite existing gemkeeper.yml entirely"
+
+        def call(lockfile_path:, **options)
+          manifest_path = options[:manifest] || ManifestReader::DEFAULT_PATH
+          output_path = options[:config] || File.join(Dir.pwd, Configuration::DEFAULT_CONFIG_FILENAME)
+
+          manifest = ManifestReader.load(manifest_path)
+          lockfile_versions = LockfileParser.parse(lockfile_path)
+
+          matched = match_gems(manifest, lockfile_versions)
+
+          write_config(matched, output_path, force: options[:force])
+          print_bundler_instructions(output_path, manifest)
+        rescue ManifestNotFoundError => e
+          warn "Error: #{e.message}"
+          exit 1
+        end
+
+        private
+
+        def match_gems(manifest, lockfile_versions)
+          matched = manifest.gems.filter_map do |gem_entry|
+            name = gem_entry[:name]
+            { name: name, repo: gem_entry[:repo] } if lockfile_versions.key?(name)
+          end
+
+          warn_unmatched_internals(manifest, lockfile_versions)
+          matched
+        end
+
+        def warn_unmatched_internals(manifest, lockfile_versions)
+          lockfile_versions.each_key do |gem_name|
+            next if manifest.find_by_name(gem_name)
+
+            gem_prefix = gem_name.split("-").first
+            next unless manifest.gem_names.any? { |manifest_name| manifest_name.split("-").first == gem_prefix }
+
+            warn "Warning: #{gem_name} matches an internal name pattern but is not in the manifest — skipping"
+          end
+        end
+
+        def write_config(matched_gems, output_path, force:)
+          existing = load_existing_config(output_path) unless force
+          existing ||= {}
+
+          gem_entries = matched_gems.map do |gem_entry|
+            { "repo" => gem_entry[:repo], "version" => "from_lockfile" }
+          end
+
+          config = if force || existing.empty?
+                     build_fresh_config(gem_entries)
+                   else
+                     merge_config(existing, gem_entries, matched_gems)
+                   end
+
+          File.write(output_path, config.to_yaml)
+          puts "Wrote #{output_path}"
+        end
+
+        def load_existing_config(path)
+          return nil unless File.exist?(path)
+
+          YAML.safe_load_file(path, permitted_classes: [], symbolize_names: false) || {}
+        end
+
+        def build_fresh_config(gem_entries)
+          {
+            "port" => Configuration::DEFAULT_PORT,
+            "repos_path" => "./cache/repos",
+            "gems_path" => "./cache/gems",
+            "gems" => gem_entries
+          }
+        end
+
+        def merge_config(existing, _new_gem_entries, matched_gems)
+          existing_gems = existing["gems"] || []
+          matched_names = matched_gems.map { |gem_entry| gem_entry[:name] }
+
+          # Build a lookup for new entries by repo
+          new_by_name = matched_gems.to_h do |gem_entry|
+            entry_name = gem_entry[:name]
+            [entry_name, { "repo" => gem_entry[:repo], "version" => "from_lockfile" }]
+          end
+
+          # Update existing entries for matched gems, keep others untouched
+          updated = existing_gems.map do |entry|
+            repo = entry["repo"].to_s
+            name = File.basename(repo, ".git").sub(/^ruby-/, "")
+            if matched_names.include?(name)
+              new_by_name.delete(name).merge(entry.except("version")).merge("version" => "from_lockfile")
+            else
+              entry
+            end
+          end
+
+          # Append any matched gems not already in the config
+          updated += new_by_name.values
+
+          existing.merge("gems" => updated)
+        end
+
+        def print_bundler_instructions(config_path, manifest)
+          config = load_existing_config(config_path) || {}
+          port = config.fetch("port", Configuration::DEFAULT_PORT)
+          local_url = "http://localhost:#{port}"
+          source_url = manifest.source_url
+          puts ""
+          puts "To point Bundler at your local Geminabox, run:"
+          if source_url
+            puts "  bundle config set --local mirror.#{source_url} #{local_url}"
+          else
+            puts "  bundle config set --local mirror.<your-private-gem-source-url> #{local_url}"
+            puts "  (Replace <your-private-gem-source-url> with the gem source URL from your Gemfile)"
+          end
+        end
+      end
+    end
+
+    register "setup", Commands::Setup
+  end
+end

data/lib/gemkeeper/cli/commands/sync.rb

@@ -11,73 +11,148 @@ module Gemkeeper
 
         def call(gem_name: nil, **options)
           config = Configuration.load(options[:config])
+          gems_to_sync = select_gems(config, gem_name)
+          uploader = GemUploader.new(config.geminabox_url)
+          counts, failures = run_sync(gems_to_sync, config, uploader)
+          report_results(counts, failures, gems_to_sync.size)
+        end
+
+        private
 
-          if config.gems.empty?
+        def select_gems(config, gem_name)
+          all_gems = config.gems
+          if all_gems.empty?
             warn "No gems configured. Add gems to your gemkeeper.yml file."
             exit 1
           end
 
-          gems_to_sync = if gem_name
-                           config.gems.select { |g| g.name == gem_name }
-                         else
-                           config.gems
-                         end
+          gems = gem_name ? all_gems.select { |gem| gem.name == gem_name } : all_gems
 
-          if gems_to_sync.empty?
+          if gems.empty?
             warn "No matching gem found: #{gem_name}"
             exit 1
           end
 
-          uploader = GemUploader.new(config.geminabox_url)
+          gems
+        end
 
+        def run_sync(gems_to_sync, config, uploader)
+          counts = { synced: 0, skipped: 0 }
+          failures = []
           gems_to_sync.each do |gem_def|
-            sync_gem(gem_def, config, uploader)
+            result = sync_gem(gem_def, config, uploader)
+            counts[result] += 1
+          rescue Error => e
+            failures << { name: gem_def.name, message: e.message }
           end
-        rescue Error => e
-          warn "Error: #{e.message}"
-          exit 1
+          [counts, failures]
         end
 
-        private
+        def report_results(counts, failures, total)
+          parts = []
+          parts << Output.colorize("#{counts[:synced]} synced", :green) if counts[:synced].positive?
+          parts << Output.colorize("#{counts[:skipped]} skipped", :yellow) if counts[:skipped].positive?
+          parts << Output.colorize("#{failures.size} failed", :red) if failures.any?
+          puts "\nSync complete: #{parts.join(", ")} (#{total} total)"
+
+          return if failures.empty?
+
+          warn "\nSync completed with #{failures.size} failure(s):"
+          failures.each { |f| warn "  #{f[:name]}: #{f[:message]}" }
+          exit 1
+        end
 
         def sync_gem(gem_def, config, uploader)
-          puts "Syncing #{gem_def.name}..."
+          name = gem_def.name
+          repo_url = gem_def.repo
+          gems_path = config.gems_path
+          version = resolve_version(gem_def)
 
-          # Clone or pull the repository
-          local_path = File.join(config.repos_path, gem_def.name)
-          repo = GitRepository.new(gem_def.repo, local_path)
+          return :skipped if !gem_def.latest? && cached?(name, version, gems_path)
 
-          puts "  Fetching from #{gem_def.repo}..."
-          repo.clone_or_pull
+          puts "Syncing #{name} @ #{version}..."
+
+          local_path = File.join(config.repos_path, name)
+          repo = GitRepository.new(repo_url, local_path)
+
+          Output.step("Fetching from #{repo_url}...")
+          fetch_repo(repo, repo_url)
+
+          checkout_gem_version(repo, version)
 
-          # Checkout the specified version
-          puts "  Checking out #{gem_def.version}..."
-          repo.checkout_version(gem_def.version)
+          if gem_def.latest?
+            version = repo.current_version or
+              raise BuildError, "Could not read version from gemspec in #{repo_url}"
+            return :skipped if cached?(name, version, gems_path)
+          end
 
-          # Build the gem
-          puts "  Building gem..."
-          builder = GemBuilder.new(local_path)
-          gem_path = builder.build
+          Output.step("Building gem...")
+          gem_path = GemBuilder.new(local_path, config.gems_path).build
 
-          # Upload to Geminabox
-          puts "  Uploading to Geminabox..."
+          Output.step("Uploading to Geminabox...")
           result = uploader.upload(gem_path)
+          Output.step(result[:message])
+          Output.success("  Done!")
+          :synced
+        end
+
+        def resolve_version(gem_def)
+          return gem_def.version unless gem_def.from_lockfile?
+
+          name = gem_def.name
+          lockfile_path = LockfileParser.find
+          unless lockfile_path
+            raise GitError,
+                  "version: from_lockfile for #{name} — no Gemfile.lock found in " \
+                  "#{Dir.pwd} or any parent directory"
+          end
+
+          versions = LockfileParser.parse(lockfile_path)
+          version = versions[name]
+          raise GitError, "#{name} not found in #{lockfile_path}" unless version
 
-          puts "  #{result[:message]}"
+          version
+        end
 
-          # Clean up the built gem file
-          FileUtils.rm_f(gem_path)
+        def cached?(name, version, gems_path)
+          bare_version = version.delete_prefix("v")
+          gem_file = File.join(gems_path, "gems", "#{name}-#{bare_version}.gem")
+          if File.exist?(gem_file)
+            Output.skip("Skipping #{name} @ #{bare_version} (already cached)")
+            true
+          else
+            false
+          end
+        end
 
-          puts "  Done!"
+        def fetch_repo(repo, repo_url)
+          repo.clone_or_pull
         rescue GitError => e
-          warn "  Git error: #{e.message}"
-          raise
-        rescue BuildError => e
-          warn "  Build error: #{e.message}"
-          raise
-        rescue UploadError => e
-          warn "  Upload error: #{e.message}"
-          raise
+          raise auth_error?(e) ? auth_failure_error(repo_url, e) : e
+        end
+
+        def checkout_gem_version(repo, version)
+          Output.step("Checking out #{version}...")
+          repo.checkout_version(version)
+        end
+
+        def auth_error?(error)
+          auth_patterns = [
+            /authentication failed/i,
+            /could not read from remote repository/i,
+            /permission denied \(publickey\)/i,
+            /repository not found/i,
+            /fatal: credential/i
+          ]
+          auth_patterns.any? { |pat| error.message.match?(pat) }
+        end
+
+        def auth_failure_error(repo_url, original_error)
+          GitError.new(
+            "Git authentication failed for #{repo_url}.\n" \
+            "#{original_error.message}\n" \
+            "Configure GitHub credentials: https://docs.github.com/en/authentication"
+          )
         end
       end
     end

data/lib/gemkeeper/cli.rb

@@ -13,6 +13,7 @@ module Gemkeeper
 end
 
 require_relative "cli/commands/version"
+require_relative "cli/commands/setup"
 require_relative "cli/commands/sync"
 require_relative "cli/commands/list"
 require_relative "cli/commands/server/start"