gem-contribute 0.1.0

data/lib/gem_contribute/project.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module GemContribute
+  # A gem resolved to a host repository.
+  #
+  # `host` is one of: "github.com", "gitlab.com", "codeberg.org", or :unknown.
+  # When :unknown, owner/repo are nil and `metadata` may carry whatever URI we
+  # found so the user can at least see it.
+  Project = Data.define(:gem_name, :host, :owner, :repo, :metadata) do
+    def known_host?
+      host.is_a?(String)
+    end
+
+    def url
+      return metadata[:source_url] if metadata && !known_host?
+      return nil unless owner && repo
+
+      "https://#{host}/#{owner}/#{repo}"
+    end
+  end
+end

data/lib/gem_contribute/resolver.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module GemContribute
+  # Resolves a LockedGem to a Project (host + owner + repo) by querying the
+  # RubyGems v1 API and walking the metadata URIs in preference order.
+  #
+  # Preference order (ADR-0003):
+  #   bug_tracker_uri  →  source_code_uri  →  homepage_uri
+  #
+  # Recognized hosts: github.com, gitlab.com, codeberg.org. Anything else
+  # (mailing-list bug tracker, internal bugzilla, etc.) is stored as the
+  # `:source_url` in metadata so the user can at least see it.
+  class Resolver
+    API_BASE = "https://rubygems.org/api/v1/gems"
+    KNOWN_HOSTS = %w[github.com gitlab.com codeberg.org].freeze
+
+    # Reasons a resolve might come back without a host coordinate. Surfaced as
+    # `metadata[:reason]` on the returned Project so the CLI/TUI can show the
+    # user *why* a gem wasn't actionable.
+    REASON_NON_RUBYGEMS_SOURCE = :non_rubygems_source
+    REASON_API_NOT_FOUND = :api_not_found
+    REASON_NO_USABLE_URI = :no_usable_uri
+    REASON_UNKNOWN_HOST = :unknown_host
+
+    def initialize(cache: Cache.new, http: Net::HTTP, clock: -> { Time.now.to_i })
+      @cache = cache
+      @http = http
+      @clock = clock
+    end
+
+    # @param gem [LockedGem]
+    # @return [Project]
+    def resolve(gem)
+      return unresolved(gem, REASON_NON_RUBYGEMS_SOURCE) unless gem.resolvable?
+
+      metadata = fetch_metadata(gem)
+      return unresolved(gem, REASON_API_NOT_FOUND) if metadata.nil?
+
+      uri = preferred_uri(metadata)
+      return unresolved(gem, REASON_NO_USABLE_URI) if uri.nil?
+
+      coords = parse_host_coordinates(uri)
+      return unresolved(gem, REASON_UNKNOWN_HOST, source_url: uri) if coords.nil?
+
+      Project.new(
+        gem_name: gem.name,
+        host: coords[:host],
+        owner: coords[:owner],
+        repo: coords[:repo],
+        metadata: { source_url: uri, picked_from: coords[:picked_from] }
+      )
+    end
+
+    private
+
+    def unresolved(gem, reason, **extras)
+      Project.new(
+        gem_name: gem.name,
+        host: :unknown,
+        owner: nil,
+        repo: nil,
+        metadata: { reason: reason, **extras }
+      )
+    end
+
+    def fetch_metadata(gem)
+      cached = @cache.fetch("gems", gem.name)
+      return cached if cached
+
+      response = http_get("#{API_BASE}/#{gem.name}.json")
+      case response
+      when Net::HTTPSuccess
+        @cache.write("gems", gem.name, JSON.parse(response.body))
+      when Net::HTTPNotFound
+        nil
+      else
+        raise ResolveError.new(gem.name, "RubyGems API returned #{response.code}")
+      end
+    end
+
+    def http_get(url)
+      uri = URI(url)
+      @http.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |conn|
+        conn.get(uri.request_uri, "Accept" => "application/json", "User-Agent" => user_agent)
+      end
+    end
+
+    def user_agent
+      "gem-contribute/#{GemContribute::VERSION}"
+    end
+
+    def preferred_uri(metadata)
+      # Order matters. ADR-0003.
+      candidates = [
+        ["bug_tracker_uri", metadata["bug_tracker_uri"]],
+        ["source_code_uri", metadata["source_code_uri"]],
+        ["homepage_uri", metadata["homepage_uri"]]
+      ]
+      candidates.each do |label, value|
+        next if value.nil? || value.empty?
+
+        @last_picked = label
+        return value
+      end
+      nil
+    end
+
+    def parse_host_coordinates(url)
+      uri = safe_uri(url)
+      return nil if uri.nil? || uri.host.nil? || uri.path.nil?
+
+      host = uri.host.sub(/\Awww\./, "")
+      return nil unless KNOWN_HOSTS.include?(host)
+
+      owner, repo = uri.path.delete_prefix("/").split("/", 3)
+      return nil if owner.to_s.empty? || repo.to_s.empty?
+
+      { host: host, owner: owner, repo: repo.sub(/\.git\z/, ""), picked_from: @last_picked }
+    end
+
+    def safe_uri(url)
+      URI.parse(url)
+    rescue URI::InvalidURIError
+      nil
+    end
+  end
+end

data/lib/gem_contribute/token_store.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module GemContribute
+  # Reads / writes ~/.config/gem-contribute/auth.json (mode 0600), keyed by
+  # host. The per-host structure means GitLab / Codeberg adapters drop in
+  # without rearranging storage. See ADR-0001 and ADR-0004.
+  #
+  # File schema:
+  #   {
+  #     "github.com": {
+  #       "access_token": "gho_...",
+  #       "scope": "public_repo",
+  #       "stored_at": 1730000000
+  #     }
+  #   }
+  #
+  # Honors XDG_CONFIG_HOME so tests stay hermetic and unusual layouts work.
+  class TokenStore
+    def initialize(path: TokenStore.default_path, clock: -> { Time.now.to_i })
+      @path = path
+      @clock = clock
+    end
+
+    # @return [String, nil] the cached access token for the host, or nil
+    def token_for(host)
+      data = read
+      data.dig(host, "access_token")
+    end
+
+    # @return [Hash, nil] {access_token, scope, stored_at} or nil
+    def entry_for(host)
+      read[host]
+    end
+
+    def store(host, access_token:, scope: nil)
+      data = read
+      data[host] = {
+        "access_token" => access_token,
+        "scope" => scope,
+        "stored_at" => @clock.call
+      }.compact
+      write(data)
+    end
+
+    def delete(host)
+      data = read
+      removed = data.delete(host)
+      write(data) if removed
+      removed
+    end
+
+    def hosts
+      read.keys
+    end
+
+    def self.default_path
+      base = ENV["XDG_CONFIG_HOME"] || File.expand_path("~/.config")
+      File.join(base, "gem-contribute", "auth.json")
+    end
+
+    private
+
+    def read
+      return {} unless File.file?(@path)
+
+      JSON.parse(File.read(@path, encoding: "UTF-8"))
+    rescue JSON::ParserError, Encoding::InvalidByteSequenceError
+      # Corrupt store: don't lose the user's data, but don't crash either.
+      # The token is recoverable by re-running `auth login`; the worst case
+      # is one extra device-flow round trip.
+      {}
+    end
+
+    def write(data)
+      FileUtils.mkdir_p(File.dirname(@path))
+      tmp = "#{@path}.tmp"
+      File.write(tmp, JSON.pretty_generate(data), encoding: "UTF-8")
+      File.chmod(0o600, tmp)
+      File.rename(tmp, @path)
+      File.chmod(0o600, @path)
+    end
+  end
+end

data/lib/gem_contribute/version.rb

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

data/lib/gem_contribute.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "gem_contribute/version"
+require_relative "gem_contribute/errors"
+
+module GemContribute
+  autoload :LockedGem, "gem_contribute/locked_gem"
+  autoload :Project, "gem_contribute/project"
+
+  # The canonical Project for gem-contribute itself. Used by the CLI to
+  # short-circuit resolution (gem-contribute isn't on RubyGems yet) and
+  # to auto-inject the tool into its own scan results.
+  SELF_PROJECT = Project.new(
+    gem_name: "gem-contribute",
+    host: "github.com",
+    owner: "cdhagmann",
+    repo: "gem-contribute",
+    metadata: { self_injected: true }
+  ).freeze
+  autoload :LockfileParser, "gem_contribute/lockfile_parser"
+  autoload :Cache, "gem_contribute/cache"
+  autoload :Resolver, "gem_contribute/resolver"
+  autoload :HostAdapter, "gem_contribute/host_adapter"
+  autoload :Auth, "gem_contribute/auth"
+  autoload :Config, "gem_contribute/config"
+  autoload :TokenStore, "gem_contribute/token_store"
+  autoload :CLI, "gem_contribute/cli"
+
+  module HostAdapters
+    autoload :GitHubAdapter, "gem_contribute/host_adapters/github_adapter"
+  end
+end

data/script/lint-kicked-tires.rb

@@ -0,0 +1,76 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Validates KICKED_THE_TIRES.yml against the schema documented in its header.
+# Used by the auto-merge workflow (.github/workflows/auto-merge-kicked-tires.yml)
+# and runnable locally:
+#
+#   ruby script/lint-kicked-tires.rb              # lint the canonical file
+#   ruby script/lint-kicked-tires.rb path.yml     # lint a specific file
+#
+# Exits 0 on success, 1 on any schema violation, with a clear message.
+
+require "yaml"
+require "date"
+
+PATH = ARGV[0] || "KICKED_THE_TIRES.yml"
+ALLOWED_KEYS = %w[handle date note location].freeze
+REQUIRED_KEYS = %w[handle date].freeze
+HANDLE_PATTERN = /\A[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,38}[a-zA-Z0-9])?\z/ # GitHub handle rules
+DATE_PATTERN = /\A\d{4}-\d{2}-\d{2}\z/
+MAX_BYTES = 100_000 # 100KB — guards against runaway PRs
+
+def fail!(msg)
+  warn "✗ #{msg}"
+  exit 1
+end
+
+fail! "file not found: #{PATH}" unless File.exist?(PATH)
+fail! "file is suspiciously large (#{File.size(PATH)} bytes)" if File.size(PATH) > MAX_BYTES
+
+begin
+  data = YAML.safe_load_file(PATH, permitted_classes: [Date])
+rescue Psych::SyntaxError => e
+  fail! "YAML syntax error: #{e.message}"
+end
+
+fail! "top-level must be an array" unless data.is_a?(Array)
+fail! "must have at least one entry" if data.empty?
+
+handles = []
+data.each_with_index do |entry, i|
+  num = i + 1
+  fail! "entry #{num}: must be a hash, got #{entry.class}" unless entry.is_a?(Hash)
+
+  keys = entry.keys.map(&:to_s)
+  unknown = keys - ALLOWED_KEYS
+  fail! "entry #{num}: unknown keys: #{unknown.inspect} (allowed: #{ALLOWED_KEYS.inspect})" \
+    unless unknown.empty?
+
+  missing = REQUIRED_KEYS - keys
+  fail! "entry #{num}: missing required keys: #{missing.inspect}" unless missing.empty?
+
+  handle = entry["handle"]
+  fail! "entry #{num}: handle must be a string" unless handle.is_a?(String)
+  fail! "entry #{num}: handle must not start with '@' (use just the username)" \
+    if handle.start_with?("@")
+  fail! "entry #{num}: handle #{handle.inspect} doesn't look like a GitHub username" \
+    unless handle.match?(HANDLE_PATTERN)
+
+  date = entry["date"]
+  date_ok = date.is_a?(Date) || (date.is_a?(String) && date.match?(DATE_PATTERN))
+  fail! "entry #{num}: date must be YYYY-MM-DD" unless date_ok
+
+  fail! "entry #{num}: note must be a string" if entry.key?("note") && !entry["note"].is_a?(String)
+
+  if entry.key?("location") && !entry["location"].is_a?(String)
+    fail! "entry #{num}: location must be a string (not a nested object)"
+  end
+
+  handles << handle
+end
+
+duplicates = handles.group_by(&:itself).select { |_, v| v.size > 1 }.keys
+fail! "duplicate handles: #{duplicates.inspect}" unless duplicates.empty?
+
+puts "✓ #{data.size} entries, all valid"

data/sig/gem_contribute.rbs

@@ -0,0 +1,3 @@
+module GemContribute
+  VERSION: String
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: gem-contribute
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chris Hagmann
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+description: |
+  gem-contribute reads a project's Gemfile.lock, resolves each gem's source
+  repository via the RubyGems API, surfaces open contributable issues from
+  those repositories, and offers a one-keystroke fork-clone-branch flow so a
+  developer can go from "I noticed an issue" to "I have a working branch" in
+  seconds. v0.1 supports GitHub-hosted gems with OAuth device-flow auth.
+email:
+- cdhagmann@gmail.com
+executables:
+- gem-contribute
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/ISSUE_TEMPLATE/workshop-issue.md"
+- ".github/workflows/auto-merge-kicked-tires.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- CONTRIBUTING.md
+- KICKED_THE_TIRES.yml
+- LICENSE
+- MAINTAINER.md
+- README.md
+- Rakefile
+- docs/_config.yml
+- docs/adr/0001-just-in-time-auth.md
+- docs/adr/0002-bundler-lockfile-parser.md
+- docs/adr/0003-issue-tracker-preference.md
+- docs/adr/0004-device-flow-auth.md
+- docs/adr/0005-render-labels-verbatim.md
+- docs/adr/0006-standalone-gem-not-plugin.md
+- docs/adr/0007-display-contributing-verbatim.md
+- docs/adr/0008-rooibos-tui-framework.md
+- docs/adr/0009-top-level-namespace.md
+- docs/adr/README.md
+- docs/claude-code-prompt.md
+- docs/design.md
+- docs/index.md
+- docs/prep-plan.md
+- docs/workshop.md
+- exe/gem-contribute
+- lib/gem_contribute.rb
+- lib/gem_contribute/auth.rb
+- lib/gem_contribute/cache.rb
+- lib/gem_contribute/cli.rb
+- lib/gem_contribute/cli/auth.rb
+- lib/gem_contribute/cli/config.rb
+- lib/gem_contribute/cli/fork_clone_branch.rb
+- lib/gem_contribute/cli/issues.rb
+- lib/gem_contribute/cli/scan.rb
+- lib/gem_contribute/cli/submit.rb
+- lib/gem_contribute/config.rb
+- lib/gem_contribute/errors.rb
+- lib/gem_contribute/host_adapter.rb
+- lib/gem_contribute/host_adapters/github_adapter.rb
+- lib/gem_contribute/locked_gem.rb
+- lib/gem_contribute/lockfile_parser.rb
+- lib/gem_contribute/project.rb
+- lib/gem_contribute/resolver.rb
+- lib/gem_contribute/token_store.rb
+- lib/gem_contribute/version.rb
+- script/lint-kicked-tires.rb
+- sig/gem_contribute.rbs
+homepage: https://cdhagmann.com/gem-contribute/
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/cdhagmann/gem-contribute
+  bug_tracker_uri: https://github.com/cdhagmann/gem-contribute/issues
+  changelog_uri: https://github.com/cdhagmann/gem-contribute/blob/main/CHANGELOG.md
+  documentation_uri: https://cdhagmann.com/gem-contribute/
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Find and contribute to the open-source Ruby gems your project depends on.
+test_files: []