gemkeeper 0.1.0 → 0.2.1

data/lib/gemkeeper/configuration.rb

@@ -24,7 +24,7 @@ module Gemkeeper
     end
 
     def self.config_search_paths
-      CONFIG_PATHS.map { |p| p.is_a?(Proc) ? p.call : p }
+      CONFIG_PATHS.map(&:call)
     end
 
     def initialize(config_path = nil)
@@ -51,6 +51,13 @@ module Gemkeeper
 
     private
 
+    def validate_port!
+      return if @port.is_a?(Integer) && (1..65_535).cover?(@port)
+
+      raise InvalidConfigError,
+            "port must be an integer between 1 and 65535, got #{@port.inspect}"
+    end
+
     def find_config_file
       self.class.config_search_paths.find { |path| File.exist?(path) }
     end
@@ -67,30 +74,48 @@ module Gemkeeper
 
     def apply_config
       @port = @config.fetch(:port, DEFAULT_PORT)
+      validate_port!
       @repos_path = File.expand_path(@config.fetch(:repos_path, "./cache/repos"))
       @gems_path = File.expand_path(@config.fetch(:gems_path, "./cache/gems"))
       @pid_file = File.expand_path(@config.fetch(:pid_file, "./cache/gemkeeper.pid"))
-      @gems = (@config[:gems] || []).map { |g| GemDefinition.new(g) }
+      @gems = (@config[:gems] || []).map { |gem_config| GemDefinition.new(gem_config) }
 
       FileUtils.mkdir_p(@repos_path)
       FileUtils.mkdir_p(@gems_path)
     end
 
     class GemDefinition
+      VALID_VERSION_PATTERN = /\A[a-zA-Z0-9._-]+\z/
+      RESERVED_VERSIONS = %w[latest from_lockfile].freeze
+
       attr_reader :repo, :version, :name
 
       def initialize(config)
         @repo = config[:repo] or raise InvalidConfigError, "Gem definition missing 'repo'"
         @version = config[:version] || "latest"
         @name = config[:name] || extract_name_from_repo
+        validate_version!
       end
 
       def latest?
         @version == "latest"
       end
 
+      def from_lockfile?
+        @version == "from_lockfile"
+      end
+
       private
 
+      def validate_version!
+        return if RESERVED_VERSIONS.include?(@version)
+        return if @version.match?(VALID_VERSION_PATTERN)
+
+        raise InvalidConfigError,
+              "Invalid version #{@version.inspect} for gem #{@name.inspect} — " \
+              "must be \"latest\", \"from_lockfile\", or a tag string matching [a-zA-Z0-9._-]"
+      end
+
       def extract_name_from_repo
         File.basename(@repo, ".git").sub(/^ruby-/, "")
       end

data/lib/gemkeeper/errors.rb

@@ -6,6 +6,7 @@ module Gemkeeper
   class ConfigurationError < Error; end
   class ConfigFileNotFoundError < ConfigurationError; end
   class InvalidConfigError < ConfigurationError; end
+  class ManifestNotFoundError < ConfigurationError; end
 
   class GitError < Error; end
   class CloneError < GitError; end

data/lib/gemkeeper/git_repository.rb

@@ -20,11 +20,13 @@ module Gemkeeper
       end
     end
 
+    SAFE_REF_PATTERN = /\A[a-zA-Z0-9._-]+\z/
+
     def checkout_version(version)
       if version == "latest"
         checkout_trunk
       else
-        checkout_ref(version)
+        checkout_tag(version)
       end
     end
 
@@ -33,15 +35,9 @@ module Gemkeeper
       return nil unless gemspec_path
 
       content = File.read(gemspec_path)
-      version_patterns = [
-        /\.version\s*=\s*["']([^"']+)["']/,
-        /VERSION\s*=\s*["']([^"']+)["']/
-      ]
-
-      version_patterns.each do |pattern|
-        return Regexp.last_match(1) if content =~ pattern
-      end
-      nil
+      extract_version_from_content(content) ||
+        version_from_requires(content, File.dirname(gemspec_path)) ||
+        version_from_version_files
     end
 
     def find_gemspec
@@ -72,11 +68,56 @@ module Gemkeeper
       end
     end
 
-    def checkout_ref(ref)
+    def validate_ref!(ref)
+      return if ref.match?(SAFE_REF_PATTERN)
+
+      raise GitError, "Unsafe ref rejected: #{ref.inspect} — must match [a-zA-Z0-9._-]"
+    end
+
+    def extract_version_from_content(content)
+      [
+        /\.version\s*=\s*["']([^"']+)["']/,
+        /\bVERSION\s*=\s*["']([^"']+)["']/
+      ].each do |pattern|
+        m = content.match(pattern)
+        return m[1] if m
+      end
+      nil
+    end
+
+    def version_from_requires(content, base_dir)
+      content.scan(/require_relative\s+["']([^"']+)["']/).each do |match|
+        base = match[0].delete_suffix(".rb")
+        path = File.expand_path("#{base}.rb", base_dir)
+        next unless File.exist?(path)
+
+        version = extract_version_from_content(File.read(path))
+        return version if version
+      end
+      nil
+    end
+
+    def version_from_version_files
+      Dir.glob(File.join(@local_path, "lib", "**", "version.rb")).each do |path|
+        version = extract_version_from_content(File.read(path))
+        return version if version
+      end
+      nil
+    end
+
+    def checkout_tag(version)
+      bare = version.delete_prefix("v")
+      validate_ref!(bare)
       Dir.chdir(@local_path) do
         run_git("fetch", "--all", "--tags")
-        run_git("checkout", ref)
+        begin
+          run_git("checkout", "v#{bare}")
+        rescue GitError
+          run_git("checkout", bare)
+        end
       end
+    rescue GitError
+      raise GitError, "Could not find tag v#{bare} or #{bare} in #{@repo_url}"
     end
 
     def detect_trunk_branch
@@ -84,13 +125,11 @@ module Gemkeeper
         stdout, = run_git("branch", "-r")
         remotes = stdout.lines.map(&:strip)
 
-        if remotes.any? { |r| r =~ %r{origin/main$} }
-          "main"
-        elsif remotes.any? { |r| r =~ %r{origin/master$} }
-          "master"
-        else
-          raise GitError, "Cannot detect trunk branch (no main or master found)"
+        %w[main master].each do |branch|
+          return branch if remotes.any? { |remote| remote.end_with?("origin/#{branch}") }
         end
+
+        raise GitError, "Cannot detect trunk branch (no main or master found)"
       end
     end
 

data/lib/gemkeeper/lockfile_parser.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Gemkeeper
+  class LockfileParser
+    LOCKFILE_NAME = "Gemfile.lock"
+
+    def self.find(start_dir = Dir.pwd)
+      dir = File.expand_path(start_dir)
+      loop do
+        candidate = File.join(dir, LOCKFILE_NAME)
+        return candidate if File.exist?(candidate)
+
+        parent = File.dirname(dir)
+        break if parent == dir
+
+        dir = parent
+      end
+      nil
+    end
+
+    def self.parse(lockfile_path)
+      new(lockfile_path).gem_versions
+    end
+
+    def initialize(lockfile_path)
+      @lockfile_path = lockfile_path
+    end
+
+    def gem_versions
+      content = File.read(@lockfile_path)
+      extract_gem_section(content)
+    end
+
+    private
+
+    def extract_gem_section(content)
+      versions = {}
+      in_gem_specs = false
+
+      content.each_line do |line|
+        if line.strip == "GEM"
+          in_gem_specs = true
+          next
+        end
+
+        # A new top-level section (no leading spaces) ends the GEM block
+        in_gem_specs = false if in_gem_specs && line =~ /\A[A-Z]/ && line.strip != "GEM"
+
+        next unless in_gem_specs
+
+        # Spec lines look like: "    gem_name (version)" — exactly 4 spaces, no deeper indent
+        versions[Regexp.last_match(1)] = Regexp.last_match(2) if line.chomp =~ /\A    ([a-zA-Z0-9_-]+) \(([^)]+)\)\z/
+      end
+
+      versions
+    end
+  end
+end

data/lib/gemkeeper/manifest_reader.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Gemkeeper
+  class ManifestReader
+    DEFAULT_PATH = File.expand_path("~/.config/gemkeeper/manifest.yml")
+
+    attr_reader :gems, :source_url
+
+    def self.load(path = DEFAULT_PATH)
+      new(path)
+    end
+
+    def initialize(path)
+      @path = path
+      raise ManifestNotFoundError, manifest_not_found_message unless File.exist?(@path)
+
+      parse_manifest
+    end
+
+    def gem_names
+      @gems.map { |gem_entry| gem_entry[:name] }
+    end
+
+    def find_by_name(name)
+      @gems.find { |gem_entry| gem_entry[:name] == name }
+    end
+
+    private
+
+    def parse_manifest
+      data = YAML.safe_load_file(@path, permitted_classes: [], symbolize_names: true) || {}
+      @source_url = data[:source_url]&.to_s
+      @gems = (data[:gems] || []).map do |entry|
+        { name: entry[:name].to_s, repo: entry[:repo].to_s }
+      end
+    end
+
+    def manifest_not_found_message
+      "Manifest not found at #{@path}. " \
+        "Install your org's gem manifest, then re-run setup."
+    end
+  end
+end

data/lib/gemkeeper/output.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Gemkeeper
+  module Output
+    COLORS = {
+      green: "\e[32m",
+      yellow: "\e[33m",
+      red: "\e[31m",
+      dim: "\e[2m",
+      reset: "\e[0m"
+    }.freeze
+
+    module_function
+
+    def colorize(text, color)
+      return text unless $stdout.tty?
+
+      "#{COLORS[color]}#{text}#{COLORS[:reset]}"
+    end
+
+    def step(msg)    = puts colorize("  #{msg}", :dim)
+    def success(msg) = puts colorize(msg, :green)
+    def skip(msg)    = puts colorize(msg, :yellow)
+    def failure(msg) = warn colorize(msg, :red)
+  end
+end

data/lib/gemkeeper/server_manager.rb

@@ -12,15 +12,13 @@ module Gemkeeper
     end
 
     def start
-      raise ServerAlreadyRunningError, "Server is already running (PID: #{read_pid})" if running?
-
+      ensure_not_running!
       generate_config_ru
       start_server
     end
 
     def start_foreground
-      raise ServerAlreadyRunningError, "Server is already running (PID: #{read_pid})" if running?
-
+      ensure_not_running!
       generate_config_ru
       start_server_foreground
     end
@@ -30,21 +28,10 @@ module Gemkeeper
 
       pid = read_pid
       Process.kill("TERM", pid)
-
-      # Wait for process to stop
-      10.times do
-        break unless process_alive?(pid)
-
-        sleep 0.5
-      end
-
-      # Force kill if still running
-      Process.kill("KILL", pid) if process_alive?(pid)
-
+      wait_for_process_exit(pid)
       cleanup_pid_file
       true
     rescue Errno::ESRCH
-      # Process already dead
       cleanup_pid_file
       true
     end
@@ -68,9 +55,14 @@ module Gemkeeper
 
     private
 
+    def ensure_not_running!
+      raise ServerAlreadyRunningError, "Server is already running (PID: #{read_pid})" if running?
+    end
+
     def generate_config_ru
+      gems_path = config.gems_path
       FileUtils.mkdir_p(config.cache_dir)
-      FileUtils.mkdir_p(config.gems_path)
+      FileUtils.mkdir_p(gems_path)
 
       content = <<~RUBY
         # frozen_string_literal: true
@@ -79,7 +71,7 @@ module Gemkeeper
         require "rubygems/indexer"
         require "geminabox"
 
-        Geminabox.data = #{config.gems_path.inspect}
+        Geminabox.data = #{gems_path.inspect}
         Geminabox.rubygems_proxy = true
 
         run Geminabox::Server
@@ -88,15 +80,20 @@ module Gemkeeper
       File.write(config.config_ru_path, content)
     end
 
+    def build_rackup_cmd(*extra)
+      ["rackup", config.config_ru_path, "--host", "127.0.0.1", "-p", config.port.to_s, "-s", "puma", *extra]
+    end
+
+    def build_start_cmd
+      build_rackup_cmd("-D", "-P", config.pid_file)
+    end
+
+    def build_foreground_cmd
+      build_rackup_cmd
+    end
+
     def start_server
-      cmd = [
-        "rackup",
-        config.config_ru_path,
-        "-p", config.port.to_s,
-        "-D",
-        "-P", config.pid_file,
-        "-s", "puma"
-      ]
+      cmd = build_start_cmd
 
       Dir.chdir(config.cache_dir) do
         _stdout, stderr, status = Open3.capture3(*cmd)
@@ -109,41 +106,45 @@ module Gemkeeper
     end
 
     def start_server_foreground
-      cmd = [
-        "rackup",
-        config.config_ru_path,
-        "-p", config.port.to_s,
-        "-s", "puma"
-      ]
-
       Dir.chdir(config.cache_dir) do
-        system(*cmd)
+        system(*build_foreground_cmd)
+      end
+    end
+
+    def wait_for_process_exit(pid)
+      10.times do
+        return unless process_alive?(pid)
+
+        sleep 0.5
       end
+      Process.kill("KILL", pid) if process_alive?(pid)
     end
 
     def wait_for_server(timeout: 10)
       require "net/http"
 
-      deadline = Time.now + timeout
       uri = URI(config.geminabox_url)
+      (timeout / 0.5).ceil.times do
+        return true if server_responding?(uri)
 
-      while Time.now < deadline
-        begin
-          response = Net::HTTP.get_response(uri)
-          return true if response.is_a?(Net::HTTPSuccess) || response.is_a?(Net::HTTPRedirection)
-        rescue Errno::ECONNREFUSED, Errno::ECONNRESET, SocketError
-          # Server not ready yet
-        end
         sleep 0.5
       end
 
       raise ServerError, "Server failed to start within #{timeout} seconds"
     end
 
+    def server_responding?(uri)
+      response = Net::HTTP.get_response(uri)
+      response.is_a?(Net::HTTPSuccess) || response.is_a?(Net::HTTPRedirection)
+    rescue Errno::ECONNREFUSED, Errno::ECONNRESET, SocketError
+      false
+    end
+
     def read_pid
-      return nil unless File.exist?(config.pid_file)
+      pid_file = config.pid_file
+      return nil unless File.exist?(pid_file)
 
-      pid = File.read(config.pid_file).strip.to_i
+      pid = File.read(pid_file).strip.to_i
       pid.positive? ? pid : nil
     end
 

data/lib/gemkeeper/version.rb

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

data/lib/gemkeeper.rb

@@ -2,7 +2,10 @@
 
 require_relative "gemkeeper/version"
 require_relative "gemkeeper/errors"
+require_relative "gemkeeper/output"
 require_relative "gemkeeper/configuration"
+require_relative "gemkeeper/lockfile_parser"
+require_relative "gemkeeper/manifest_reader"
 require_relative "gemkeeper/git_repository"
 require_relative "gemkeeper/gem_builder"
 require_relative "gemkeeper/gem_uploader"

data/mise.toml

@@ -0,0 +1,6 @@
+[env]
+_.file = ".env"
+_.path = [
+  "bin",
+  "exe",
+]

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

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