gem-contribute 0.1.0

data/lib/gem_contribute/cli/submit.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "open3"
+require "uri"
+
+module GemContribute
+  module CLI
+    # `gem-contribute submit` — push the current branch to the user's fork and
+    # open a pre-filled PR compare page in the browser.
+    #
+    # Run from inside a clone created by `gem-contribute fix`. Reads:
+    #   - origin remote   → fork owner/repo (where the branch is pushed)
+    #   - upstream remote → canonical owner/repo (where the PR is filed)
+    #   - current branch  → must match `gem-contribute/issue-<N>`
+    #
+    # The PR itself is NOT opened via API. We push, then open GitHub's compare
+    # page in the browser with title and body pre-filled. This mirrors the
+    # `auth login` UX (browser handles the human step) and means the user
+    # always reviews the PR text before submitting.
+    class Submit
+      BRANCH_REGEX = %r{\Agem-contribute/issue-(\d+)\z}
+
+      def initialize(stdout: $stdout, stderr: $stderr,
+                     git: Git.new,
+                     adapter_factory: ->(token:) { HostAdapters::GitHubAdapter.new(token: token) },
+                     store: TokenStore.new,
+                     browser_opener: nil,
+                     working_dir: Dir.pwd)
+        @stdout = stdout
+        @stderr = stderr
+        @git = git
+        @adapter_factory = adapter_factory
+        @store = store
+        @browser_opener = browser_opener || method(:default_browser_opener)
+        @working_dir = working_dir
+      end
+
+      def run(_argv)
+        branch = current_branch
+        issue_number = parse_issue_number(branch)
+        return 1 if issue_number.nil?
+
+        origin = parse_remote("origin", required: true)
+        return 1 if origin.nil?
+
+        # When the user owns the upstream (e.g. self-dogfooding) there's no
+        # separate fork and no `upstream` remote — fall back to origin and
+        # build a same-repo PR.
+        upstream = parse_remote("upstream", required: false) || origin
+
+        title = fetch_issue_title(upstream, issue_number)
+        push_branch(branch)
+        url = compare_url(upstream, origin, branch, issue_number, title)
+        open_and_print(url)
+        0
+      rescue AdapterError => e
+        @stderr.puts "submit failed: #{e.message}"
+        1
+      end
+
+      private
+
+      def current_branch
+        # symbolic-ref works even on a fresh branch with no commits;
+        # rev-parse --abbrev-ref doesn't.
+        out, _err, status = Open3.capture3("git", "-C", @working_dir, "symbolic-ref", "--short", "HEAD")
+        raise AdapterError, "not inside a git repository (or HEAD is detached)" unless status.success?
+
+        out.strip
+      end
+
+      def parse_issue_number(branch)
+        match = BRANCH_REGEX.match(branch)
+        return match[1].to_i if match
+
+        @stderr.puts "submit: branch #{branch.inspect} doesn't match #{BRANCH_REGEX.source}."
+        @stderr.puts "Run `gem-contribute fix <gem>/<issue#>` first to set up the branch."
+        nil
+      end
+
+      def parse_remote(name, required:)
+        out, _err, status = Open3.capture3("git", "-C", @working_dir, "remote", "get-url", name)
+        unless status.success?
+          if required
+            @stderr.puts "submit: no `#{name}` remote configured. " \
+                         "Are you inside a git clone?"
+          end
+          return nil
+        end
+
+        owner_repo_from_url(out.strip)
+      end
+
+      # Accepts both https://github.com/owner/repo(.git) and git@github.com:owner/repo.git
+      def owner_repo_from_url(url)
+        if (m = url.match(%r{github\.com[:/]([^/]+)/([^/]+?)(?:\.git)?\z}))
+          { owner: m[1], repo: m[2] }
+        else
+          @stderr.puts "submit: can't parse GitHub owner/repo from #{url.inspect}"
+          nil
+        end
+      end
+
+      def fetch_issue_title(upstream, number)
+        token = @store.token_for("github.com")
+        adapter = @adapter_factory.call(token: token)
+        adapter.issue(upstream[:owner], upstream[:repo], number).fetch("title", nil)
+      rescue AdapterError => e
+        @stderr.puts "submit: couldn't fetch issue title (#{e.message}). Continuing without it."
+        nil
+      end
+
+      def push_branch(branch)
+        @stdout.puts "Pushing #{branch} to origin..."
+        @git.push(@working_dir, "origin", branch)
+      end
+
+      def compare_url(upstream, origin, branch, issue_number, title)
+        # GitHub compare URL forms:
+        #   Cross-fork:  /<upstream>/compare/<fork-owner>:<branch>
+        #   Same-repo:   /<upstream>/compare/<branch>
+        # We omit the explicit base so GitHub auto-resolves to default.
+        # `expand=1` opens the PR creation form pre-filled.
+        same_repo = origin[:owner] == upstream[:owner] && origin[:repo] == upstream[:repo]
+        head = same_repo ? branch : "#{origin[:owner]}:#{branch}"
+        full_title = title ? "Fix ##{issue_number}: #{title}" : "Fix ##{issue_number}"
+        params = {
+          "expand" => "1",
+          "title" => full_title,
+          "body" => "Closes ##{issue_number}.\n\n_Opened via `gem-contribute submit`._"
+        }
+
+        "https://github.com/#{upstream[:owner]}/#{upstream[:repo]}/compare/#{head}?" \
+          "#{URI.encode_www_form(params)}"
+      end
+
+      def open_and_print(url)
+        opened = @browser_opener.call(url)
+        @stdout.puts opened ? "Opened browser to:" : "Open this URL to file the PR:"
+        @stdout.puts "  #{url}"
+      end
+
+      def default_browser_opener(uri)
+        cmd = case RbConfig::CONFIG["host_os"]
+              when /darwin/             then "open"
+              when /linux/              then "xdg-open"
+              when /mswin|mingw|cygwin/ then "start"
+              end
+        cmd && Kernel.system(cmd, uri)
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/gem_contribute/cli.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module GemContribute
+  module CLI
+    autoload :Scan, "gem_contribute/cli/scan"
+    autoload :Auth, "gem_contribute/cli/auth"
+    autoload :Config, "gem_contribute/cli/config"
+    autoload :Issues, "gem_contribute/cli/issues"
+    autoload :ForkCloneBranch, "gem_contribute/cli/fork_clone_branch"
+    autoload :Git, "gem_contribute/cli/fork_clone_branch"
+    autoload :Submit, "gem_contribute/cli/submit"
+    USAGE = <<~USAGE
+      Usage: gem-contribute <command> [options]
+
+      Commands:
+        scan [path]              Summarize the contributable surface of a Gemfile.lock.
+                                 Path defaults to ./Gemfile.lock.
+        issues <gem|all>         List open "good first issue" issues for a gem (or all gems).
+        config set <key> <val>   Persist a configuration value.
+        config get <key>         Print a configuration value.
+        config list              Print all configuration values.
+        auth login               Authenticate with GitHub via OAuth device flow.
+        auth status              Show whether you're authenticated.
+        auth logout              Remove the cached token for github.com.
+        fix <gem>/<issue#>       Fork the gem's repo, clone the fork, branch from main.
+                                 (alias: fork-clone-branch)
+        submit                   Push the current branch and open a pre-filled
+                                 PR compare page in the browser. Run from inside
+                                 a clone created by `fix`.
+
+      Global options:
+        --refresh                Invalidate caches before running.
+        -h, --help               Show this help.
+        --version                Print the version and exit.
+    USAGE
+
+    module_function
+
+    # Entry point for exe/gem-contribute. Returns an integer exit status so the
+    # caller can `exit GemContribute::CLI.run(ARGV)`.
+    def run(argv, stdout: $stdout, stderr: $stderr)
+      argv = argv.dup
+      handle_global_flags!(argv, stdout: stdout)
+      dispatch(argv.shift, argv, stdout: stdout, stderr: stderr)
+    end
+
+    def dispatch(command, argv, stdout:, stderr:)
+      builder = COMMANDS[command]
+      if builder.nil?
+        return print_help(stdout) if [nil, "help", "-h", "--help"].include?(command)
+
+        return unknown_command(command, stderr)
+      end
+
+      builder.call(stdout, stderr).run(argv)
+    end
+
+    COMMANDS = {
+      "scan" => ->(o, e) { Scan.new(stdout: o, stderr: e, adapter: github_adapter) },
+      "issues" => ->(o, e) { Issues.new(stdout: o, stderr: e, adapter: github_adapter) },
+      "config" => ->(o, e) { Config.new(stdout: o, stderr: e) },
+      "auth" => ->(o, e) { Auth.new(stdout: o, stderr: e) },
+      "fix" => lambda { |o, e|
+        ForkCloneBranch.new(stdout: o, stderr: e,
+                            clone_root: GemContribute::Config.new.clone_root)
+      },
+      "fork-clone-branch" => lambda { |o, e|
+        ForkCloneBranch.new(stdout: o, stderr: e,
+                            clone_root: GemContribute::Config.new.clone_root)
+      },
+      "submit" => ->(o, e) { Submit.new(stdout: o, stderr: e) }
+    }.freeze
+
+    def print_help(stdout)
+      stdout.puts USAGE
+      0
+    end
+
+    def unknown_command(command, stderr)
+      stderr.puts "gem-contribute: unknown command #{command.inspect}"
+      stderr.puts USAGE
+      2
+    end
+
+    def github_adapter
+      token = TokenStore.new.token_for("github.com")
+      HostAdapters::GitHubAdapter.new(token: token)
+    end
+
+    def handle_global_flags!(argv, stdout:)
+      if argv.include?("--version")
+        stdout.puts "gem-contribute #{GemContribute::VERSION}"
+        exit 0
+      end
+
+      return unless argv.delete("--refresh")
+
+      Cache.new.clear!
+      stdout.puts "Cache cleared at #{Cache.default_root}"
+    end
+  end
+end

data/lib/gem_contribute/config.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+
+module GemContribute
+  # Reads and writes ~/.config/gem-contribute/config.yml.
+  # Honors XDG_CONFIG_HOME so tests stay hermetic and unusual layouts work.
+  # Missing or corrupt files are treated as an empty config (no crash).
+  class Config
+    DEFAULT_CLONE_ROOT = File.expand_path("~/code/oss")
+
+    KNOWN_KEYS = %w[clone_root].freeze
+
+    def initialize(path: self.class.default_path)
+      @path = path
+      @data = load_file
+    end
+
+    def clone_root
+      raw = @data["clone_root"]
+      raw ? File.expand_path(raw) : DEFAULT_CLONE_ROOT
+    end
+
+    def set(key, value)
+      raise ArgumentError, "unknown config key #{key.inspect}. Known keys: #{KNOWN_KEYS.join(", ")}" \
+        unless KNOWN_KEYS.include?(key)
+
+      @data[key] = value
+      write_file
+    end
+
+    def to_h
+      @data.dup
+    end
+
+    def self.default_path
+      base = ENV.fetch("XDG_CONFIG_HOME", File.expand_path("~/.config"))
+      File.join(base, "gem-contribute", "config.yml")
+    end
+
+    private
+
+    def load_file
+      return {} unless File.exist?(@path)
+
+      parsed = YAML.safe_load(File.read(@path, encoding: "UTF-8"))
+      parsed.is_a?(Hash) ? parsed : {}
+    rescue Psych::Exception, Errno::EACCES
+      {}
+    end
+
+    def write_file
+      FileUtils.mkdir_p(File.dirname(@path))
+      tmp = "#{@path}.tmp"
+      File.write(tmp, YAML.dump(@data), encoding: "UTF-8")
+      File.rename(tmp, @path)
+    end
+  end
+end

data/lib/gem_contribute/errors.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module GemContribute
+  class Error < StandardError; end
+
+  class LockfileNotFound < Error; end
+
+  class LockfileParseError < Error; end
+
+  class ResolveError < Error
+    attr_reader :gem_name
+
+    def initialize(gem_name, message)
+      @gem_name = gem_name
+      super("#{gem_name}: #{message}")
+    end
+  end
+
+  class AdapterError < Error; end
+
+  # Raised by host adapters when an authenticated call is attempted without a
+  # cached token for that host. The TUI catches this and triggers device flow;
+  # CLI callers print a "run auth login" hint. See ADR-0001.
+  class AuthRequired < Error
+    attr_reader :host
+
+    def initialize(host)
+      @host = host
+      super("authentication required for #{host}")
+    end
+  end
+end

data/lib/gem_contribute/host_adapter.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module GemContribute
+  # Abstract host adapter. Concrete implementations (GitHubAdapter, future
+  # GitLabAdapter, future CodebergAdapter) conform to this interface so the
+  # TUI doesn't have to special-case anything beyond looking up the right
+  # adapter for a project's host.
+  #
+  # Public-API methods (no auth needed):
+  #   issues(project, labels:)
+  #   community_profile(project)
+  #   file_contents(project, path)
+  #
+  # Auth-required methods (raise AuthRequired without a cached token):
+  #   fork(project)
+  #   already_forked?(project)
+  #
+  # See ADR-0001 for the JIT auth contract.
+  class HostAdapter
+    def issues(_project, labels: nil)
+      raise NotImplementedError
+    end
+
+    def community_profile(_project)
+      raise NotImplementedError
+    end
+
+    def file_contents(_project, _path)
+      raise NotImplementedError
+    end
+
+    def fork(_project)
+      raise NotImplementedError
+    end
+
+    def already_forked?(_project)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/gem_contribute/host_adapters/github_adapter.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module GemContribute
+  module HostAdapters
+    # GitHub adapter. v0.1 implements the unauthenticated read methods
+    # (issues, community_profile, file_contents). The auth-required methods
+    # raise AuthRequired so the calling layer (CLI in Stage 2, TUI in Stage 3)
+    # can trigger device flow. See ADR-0001 and ADR-0004.
+    #
+    # `token` is optional and reserved for Stage 2; when present it's sent as
+    # `Authorization: Bearer …` to lift the rate limit and unlock fork/etc.
+    class GitHubAdapter < HostAdapter
+      API_BASE = "https://api.github.com"
+      ACCEPT = "application/vnd.github+json"
+      API_VERSION = "2022-11-28"
+      MAX_REDIRECTS = 3
+
+      RateLimit = Data.define(:limit, :remaining, :reset_at)
+
+      attr_reader :rate_limit
+
+      def initialize(cache: Cache.new, http: Net::HTTP, token: nil)
+        super()
+        @cache = cache
+        @http = http
+        @token = token
+        @rate_limit = nil
+      end
+
+      # @return [Hash] a single issue's full payload (uncached — submit only).
+      def issue(owner, repo, number)
+        ensure_known_host!(Project.new(gem_name: repo, host: "github.com",
+                                       owner: owner, repo: repo, metadata: {}))
+        get_json("/repos/#{owner}/#{repo}/issues/#{number}")
+      end
+
+      # @return [Array<Hash>] open issues filtered to the given labels (if any)
+      def issues(project, labels: nil)
+        ensure_known_host!(project)
+
+        cache_key = issue_cache_key(project, labels)
+        cached = @cache.fetch("issues", cache_key)
+        return cached if cached
+
+        params = { state: "open", per_page: 50 }
+        params[:labels] = Array(labels).join(",") if labels && !Array(labels).empty?
+        body = get_json("/repos/#{project.owner}/#{project.repo}/issues", params)
+
+        # GitHub's /issues endpoint mixes pull requests in. PRs have a
+        # `pull_request` key; filter those out so callers see issues only.
+        only_issues = body.reject { |i| i.key?("pull_request") }
+        @cache.write("issues", cache_key, only_issues)
+      end
+
+      def community_profile(project)
+        ensure_known_host!(project)
+        cache_key = "#{project.owner}/#{project.repo}"
+        cached = @cache.fetch("repos", cache_key)
+        return cached if cached
+
+        body = get_json("/repos/#{project.owner}/#{project.repo}/community/profile")
+        @cache.write("repos", cache_key, body)
+      end
+
+      def file_contents(project, path)
+        ensure_known_host!(project)
+        cache_key = "#{project.owner}/#{project.repo}:#{path}"
+        cached = @cache.fetch("files", cache_key)
+        return cached if cached
+
+        body = get_json("/repos/#{project.owner}/#{project.repo}/contents/#{path}")
+        @cache.write("files", cache_key, body)
+      end
+
+      # POST /repos/:owner/:repo/forks. Returns the fork's parsed body
+      # (clone_url, owner.login, name, etc.). GitHub responds 202 (accepted)
+      # immediately even if the fork is still propagating; callers that need
+      # to clone right after may want to poll readiness — see
+      # `fork_ready?` below.
+      def fork(project)
+        raise AuthRequired, "github.com" unless @token
+
+        ensure_known_host!(project)
+        post_json("/repos/#{project.owner}/#{project.repo}/forks")
+      end
+
+      # GET /repos/:viewer/:repo. True iff the viewer already owns a fork of
+      # the upstream repo at the same name.
+      def already_forked?(project)
+        raise AuthRequired, "github.com" unless @token
+
+        ensure_known_host!(project)
+        viewer = viewer_login
+        get_json("/repos/#{viewer}/#{project.repo}")
+        true
+      rescue AdapterError => e
+        return false if e.message.include?("404")
+
+        raise
+      end
+
+      # GET /user. Used by `auth status` and `already_forked?`. Returns the
+      # authenticated user's login string (e.g. "cdhagmann").
+      def viewer_login
+        raise AuthRequired, "github.com" unless @token
+
+        body = get_json("/user")
+        body.fetch("login")
+      end
+
+      # GET /repos/:viewer/:repo, returning true once GitHub has finished
+      # provisioning the fork. The fork endpoint returns 202 immediately;
+      # the resource may 404 for a few seconds before becoming live.
+      def fork_ready?(viewer, repo_name)
+        raise AuthRequired, "github.com" unless @token
+
+        get_json("/repos/#{viewer}/#{repo_name}")
+        true
+      rescue AdapterError => e
+        return false if e.message.include?("404")
+
+        raise
+      end
+
+      private
+
+      def issue_cache_key(project, labels)
+        label_segment = Array(labels).sort.join(",")
+        "#{project.owner}/#{project.repo}?labels=#{label_segment}"
+      end
+
+      def ensure_known_host!(project)
+        return if project.host == "github.com"
+
+        raise AdapterError, "GitHubAdapter cannot serve project on host #{project.host.inspect}"
+      end
+
+      def get_json(path, params = {})
+        response = http_get(path, params)
+        record_rate_limit(response)
+        decode_response(response, path)
+      end
+
+      def post_json(path, body = nil)
+        response = http_post(path, body)
+        record_rate_limit(response)
+        decode_response(response, path)
+      end
+
+      def http_get(path, params, redirects_remaining: MAX_REDIRECTS)
+        url = URI("#{API_BASE}#{path}")
+        url.query = URI.encode_www_form(params) unless params.empty?
+        response = @http.start(url.host, url.port, use_ssl: true) do |conn|
+          conn.get(url.request_uri, request_headers)
+        end
+
+        if response.is_a?(Net::HTTPMovedPermanently) && redirects_remaining.positive?
+          new_path = URI(response["Location"]).path
+          return http_get(new_path, params, redirects_remaining: redirects_remaining - 1)
+        end
+
+        response
+      end
+
+      def http_post(path, body)
+        url = URI("#{API_BASE}#{path}")
+        @http.start(url.host, url.port, use_ssl: true) do |conn|
+          request = Net::HTTP::Post.new(url.request_uri, request_headers.merge("Content-Type" => "application/json"))
+          request.body = JSON.dump(body) if body
+          conn.request(request)
+        end
+      end
+
+      def decode_response(response, path)
+        case response
+        when Net::HTTPNoContent then nil
+        when Net::HTTPSuccess then JSON.parse(response.body)
+        when Net::HTTPUnauthorized, Net::HTTPForbidden
+          raise AuthRequired, "github.com" if @token.nil?
+
+          raise AdapterError, "GitHub returned #{response.code}: #{response.body}"
+        else
+          raise AdapterError, "GitHub returned #{response.code} for #{path}"
+        end
+      end
+
+      def request_headers
+        headers = {
+          "Accept" => ACCEPT,
+          "User-Agent" => "gem-contribute/#{GemContribute::VERSION}",
+          "X-GitHub-Api-Version" => API_VERSION
+        }
+        headers["Authorization"] = "Bearer #{@token}" if @token
+        headers
+      end
+
+      def record_rate_limit(response)
+        limit = response["X-RateLimit-Limit"]
+        remaining = response["X-RateLimit-Remaining"]
+        reset = response["X-RateLimit-Reset"]
+        return if [limit, remaining, reset].any?(&:nil?)
+
+        @rate_limit = RateLimit.new(
+          limit: limit.to_i,
+          remaining: remaining.to_i,
+          reset_at: Time.at(reset.to_i)
+        )
+      end
+    end
+  end
+end

data/lib/gem_contribute/locked_gem.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module GemContribute
+  # A single dependency parsed from Gemfile.lock.
+  #
+  # The design doc calls this "a Gem"; the in-code name is LockedGem to avoid
+  # shadowing Ruby's stdlib ::Gem inside the GemContribute namespace.
+  # See ADR-0009.
+  #
+  # `source_type` is one of:
+  #   :rubygems  — published to a RubyGems-compatible index
+  #   :git       — `gem 'foo', git: '…'`
+  #   :path      — `gem 'foo', path: '…'`
+  #   :bundler   — Bundler itself (only present in lockfiles via DEPENDENCIES)
+  LockedGem = Data.define(:name, :version, :source_type, :source_uri) do
+    def rubygems?
+      source_type == :rubygems
+    end
+
+    def resolvable?
+      # We can only ask the RubyGems API about things we got from RubyGems.
+      # See ADR-0003 for what we do with the answer.
+      rubygems?
+    end
+  end
+end

data/lib/gem_contribute/lockfile_parser.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "bundler"
+
+module GemContribute
+  # Wraps Bundler::LockfileParser. See ADR-0002.
+  #
+  # Input: a path to a Gemfile.lock.
+  # Output: an Array of LockedGem.
+  module LockfileParser
+    module_function
+
+    # @param path [String, Pathname] path to a Gemfile.lock
+    # @return [Array<LockedGem>]
+    def parse(path)
+      contents = read_lockfile(path)
+      parser = Bundler::LockfileParser.new(contents)
+
+      parser.specs.map { |spec| build_locked_gem(spec) }
+    rescue Bundler::LockfileError => e
+      raise LockfileParseError, "could not parse #{path}: #{e.message}"
+    end
+
+    def read_lockfile(path)
+      File.read(path)
+    rescue Errno::ENOENT
+      raise LockfileNotFound, "no Gemfile.lock at #{path}"
+    end
+
+    def build_locked_gem(spec)
+      LockedGem.new(
+        name: spec.name,
+        version: spec.version.to_s,
+        source_type: classify_source(spec.source),
+        source_uri: source_uri(spec.source)
+      )
+    end
+
+    def classify_source(source)
+      case source
+      when Bundler::Source::Rubygems then :rubygems
+      when Bundler::Source::Git then :git
+      when Bundler::Source::Path then :path
+      else :unknown
+      end
+    end
+
+    def source_uri(source)
+      case source
+      when Bundler::Source::Rubygems
+        # Bundler::Source::Rubygems can have multiple remotes; pick the first.
+        # In practice this is rubygems.org for almost every gem.
+        source.remotes.first&.to_s
+      when Bundler::Source::Git
+        source.uri
+      when Bundler::Source::Path
+        source.path.to_s
+      end
+    end
+  end
+end