gem-contribute 0.1.0

data/lib/gem_contribute/cli/auth.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module GemContribute
+  module CLI
+    # `gem-contribute auth <subcommand>` — Stage 2 entry point for OAuth.
+    #
+    # Subcommands:
+    #   login   — start device flow, poll for completion, persist the token
+    #   status  — show whether a token is cached for github.com (and try to
+    #             validate it by hitting /user)
+    #   logout  — drop the cached token for github.com
+    class Auth
+      USAGE = <<~USAGE
+        Usage: gem-contribute auth <subcommand>
+
+        Subcommands:
+          login    Authenticate with GitHub via OAuth device flow.
+          status   Show whether you're authenticated.
+          logout   Remove the cached token for github.com.
+      USAGE
+
+      DEFAULT_HOST = "github.com"
+
+      def initialize(stdout: $stdout, stderr: $stderr, store: TokenStore.new,
+                     sleeper: ->(s) { Kernel.sleep(s) },
+                     browser_opener: nil, clipper: nil)
+        @stdout = stdout
+        @stderr = stderr
+        @store = store
+        @sleeper = sleeper
+        @browser_opener = browser_opener || method(:default_browser_opener)
+        @clipper = clipper || method(:default_clipper)
+      end
+
+      def run(argv)
+        case argv.shift
+        when "login"  then login
+        when "status" then status
+        when "logout" then logout
+        when nil, "help", "-h", "--help"
+          @stdout.puts USAGE
+          0
+        else
+          @stderr.puts "gem-contribute: unknown auth subcommand"
+          @stderr.puts USAGE
+          2
+        end
+      end
+
+      private
+
+      def login
+        device_code = GemContribute::Auth.request_device_code(GemContribute::Auth::CLIENT_ID)
+        prompt_user(device_code)
+        result = poll_loop(device_code)
+        persist_or_report(result)
+      rescue GemContribute::Auth::AuthError => e
+        @stderr.puts "auth login failed: #{e.message}"
+        1
+      end
+
+      def prompt_user(device_code)
+        copied = @clipper.call(device_code.user_code)
+        code_suffix = copied ? " (copied to clipboard)" : ""
+        @stdout.puts "Your one-time code#{code_suffix}: #{device_code.user_code}"
+
+        opened = @browser_opener.call(device_code.verification_uri)
+        url_prefix = opened ? "Browser opened to" : "Visit"
+        @stdout.puts "#{url_prefix}: #{device_code.verification_uri}"
+
+        @stdout.puts "Waiting for you to authorize..."
+      end
+
+      def poll_loop(device_code)
+        loop do
+          if device_code.expired?
+            return GemContribute::Auth::Result.new(status: :expired, token: nil, scope: nil, error_message: nil)
+          end
+
+          @sleeper.call(device_code.interval)
+          result = GemContribute::Auth.poll(device_code, GemContribute::Auth::CLIENT_ID)
+
+          case result.status
+          when :pending then next
+          when :slow_down then device_code = device_code.with_interval(device_code.interval + 5)
+          else return result
+          end
+        end
+      end
+
+      def persist_or_report(result)
+        case result.status
+        when :ok
+          @store.store(DEFAULT_HOST, access_token: result.token, scope: result.scope)
+          @stdout.puts "Authenticated. Token saved to #{TokenStore.default_path} (mode 0600)."
+          0
+        when :expired
+          @stderr.puts "Device code expired. Run `gem-contribute auth login` again."
+          1
+        when :denied
+          @stderr.puts "Authorization denied."
+          1
+        else
+          @stderr.puts "auth login failed: #{result.error_message}"
+          1
+        end
+      end
+
+      def status
+        entry = @store.entry_for(DEFAULT_HOST)
+        if entry.nil?
+          @stdout.puts "Not authenticated. Run `gem-contribute auth login`."
+          return 1
+        end
+
+        verify_and_print(entry)
+      end
+
+      def verify_and_print(entry)
+        adapter = HostAdapters::GitHubAdapter.new(token: entry["access_token"])
+        login_name = adapter.viewer_login
+        @stdout.puts "Authenticated as @#{login_name} on #{DEFAULT_HOST} (scope: #{entry["scope"] || "unknown"})"
+        0
+      rescue GemContribute::AuthRequired, GemContribute::AdapterError => e
+        @stderr.puts "Token cached for #{DEFAULT_HOST} but verification failed: #{e.message}"
+        @stderr.puts "Run `gem-contribute auth login` to refresh."
+        1
+      end
+
+      def logout
+        if @store.delete(DEFAULT_HOST)
+          @stdout.puts "Logged out of #{DEFAULT_HOST}."
+        else
+          @stdout.puts "No cached token for #{DEFAULT_HOST}."
+        end
+        0
+      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
+
+      def default_clipper(text)
+        case RbConfig::CONFIG["host_os"]
+        when /darwin/
+          IO.popen("pbcopy", "w") { |p| p.write(text) }
+          true
+        when /linux/
+          IO.popen(["xclip", "-selection", "clipboard"], "w") { |p| p.write(text) }
+          true
+        end
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/gem_contribute/cli/config.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module GemContribute
+  module CLI
+    # `gem-contribute config <subcommand>`
+    #
+    # Subcommands:
+    #   set <key> <value>   Write a value to ~/.config/gem-contribute/config.yml
+    #   get <key>           Print the current value of a key
+    #   list                Print all configured values
+    class Config
+      USAGE = <<~USAGE
+        Usage: gem-contribute config <subcommand>
+
+        Subcommands:
+          set <key> <value>    Set a configuration value.
+          get <key>            Print the current value of a key.
+          list                 Print all configured values.
+
+        Keys:
+          clone_root           Directory where forks are cloned (default: ~/code/oss).
+                               Example: gem-contribute config set clone_root ~/Projects/oss
+      USAGE
+
+      def initialize(stdout: $stdout, stderr: $stderr, config: GemContribute::Config.new)
+        @stdout = stdout
+        @stderr = stderr
+        @config = config
+      end
+
+      def run(argv)
+        case argv.shift
+        when "set"  then set(argv)
+        when "get"  then get(argv)
+        when "list" then list
+        when nil, "help", "-h", "--help"
+          @stdout.puts USAGE
+          0
+        else
+          @stderr.puts "gem-contribute: unknown config subcommand"
+          @stderr.puts USAGE
+          2
+        end
+      end
+
+      private
+
+      def set(argv)
+        key = argv.shift
+        value = argv.shift
+        if key.nil? || value.nil?
+          @stderr.puts "Usage: gem-contribute config set <key> <value>"
+          return 2
+        end
+
+        @config.set(key, value)
+        @stdout.puts "#{key} = #{value}"
+        0
+      rescue ArgumentError => e
+        @stderr.puts e.message
+        1
+      end
+
+      def get(argv)
+        key = argv.shift
+        if key.nil?
+          @stderr.puts "Usage: gem-contribute config get <key>"
+          return 2
+        end
+
+        unless GemContribute::Config::KNOWN_KEYS.include?(key)
+          @stderr.puts "unknown config key #{key.inspect}"
+          return 1
+        end
+
+        @stdout.puts @config.to_h.fetch(key, "(not set — default applies)")
+        0
+      end
+
+      def list
+        @stdout.puts "Configuration (#{GemContribute::Config.default_path}):"
+        @stdout.puts "  clone_root = #{@config.clone_root}"
+        0
+      end
+    end
+  end
+end

data/lib/gem_contribute/cli/fork_clone_branch.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module GemContribute
+  module CLI
+    # `gem-contribute fork-clone-branch <gem>/<issue#>`
+    #
+    # Performs the full sequence the TUI's `f` keybinding will trigger in
+    # Stage 3:
+    #
+    #   1. Resolve <gem> via the RubyGems Resolver (no lockfile required;
+    #      the lockfile is for discovery via `scan`, not gating here).
+    #   2. Read the cached GitHub token; raise AuthRequired with a clear
+    #      `auth login` hint if missing.
+    #   3. Look up the viewer's login.
+    #   4. If they don't already have a fork, fork the upstream repo.
+    #   5. Poll until the fork is reachable (forks return 202 immediately
+    #      but the resource may 404 for a few seconds).
+    #   6. `git clone` the fork to `<clone_root>/<owner>/<repo>`.
+    #   7. `git checkout -b gem-contribute/issue-<N>` from the default branch.
+    #   8. Print the local path on stdout.
+    #
+    # The shell-outs use Open3 with explicit args (not strings) to avoid any
+    # shell-injection surface.
+    class ForkCloneBranch
+      DEFAULT_CLONE_ROOT = File.expand_path("~/code/oss")
+      BRANCH_PREFIX = "gem-contribute/issue-"
+      FORK_READINESS_RETRIES = 12 # 12 × 5s = 60s ceiling
+      FORK_READINESS_INTERVAL = 5
+
+      def initialize(stdout: $stdout,
+                     stderr: $stderr,
+                     resolver: Resolver.new,
+                     store: TokenStore.new,
+                     adapter_factory: ->(token:) { HostAdapters::GitHubAdapter.new(token: token) },
+                     git: Git.new,
+                     clone_root: DEFAULT_CLONE_ROOT,
+                     sleeper: ->(s) { Kernel.sleep(s) })
+        @stdout = stdout
+        @stderr = stderr
+        @resolver = resolver
+        @store = store
+        @adapter_factory = adapter_factory
+        @git = git
+        @clone_root = clone_root
+        @sleeper = sleeper
+      end
+
+      def run(argv)
+        target = argv.shift
+        return print_usage_error if target.nil? || !target.include?("/")
+
+        gem_name, issue = target.split("/", 2)
+        adapter = build_adapter
+        return 1 if adapter.nil?
+
+        project = resolve_or_fail(gem_name)
+        return 1 if project.nil?
+
+        execute(adapter, project, issue)
+      rescue AuthRequired
+        @stderr.puts "Not authenticated. Run `gem-contribute auth login` first."
+        1
+      rescue AdapterError => e
+        @stderr.puts "fork-clone-branch failed: #{e.message}"
+        1
+      end
+
+      private
+
+      def print_usage_error
+        @stderr.puts "Usage: gem-contribute fork-clone-branch <gem>/<issue#>"
+        2
+      end
+
+      def build_adapter
+        token = @store.token_for("github.com")
+        if token.nil?
+          @stderr.puts "Not authenticated. Run `gem-contribute auth login` first."
+          return nil
+        end
+        @adapter_factory.call(token: token)
+      end
+
+      def resolve_or_fail(gem_name)
+        return GemContribute::SELF_PROJECT if gem_name == GemContribute::SELF_PROJECT.gem_name
+
+        gem = LockedGem.new(name: gem_name, version: "*", source_type: :rubygems, source_uri: "https://rubygems.org/")
+        project = @resolver.resolve(gem)
+
+        if project.host != "github.com"
+          @stderr.puts "Cannot fork-clone-branch: #{gem_name} resolves to #{project.host} " \
+                       "(only github.com is supported at v0.1)"
+          return nil
+        end
+
+        project
+      end
+
+      def execute(adapter, project, issue)
+        viewer = adapter.viewer_login
+        clone_url = ensure_fork(adapter, project, viewer)
+        local_path = clone_into_root(project, clone_url)
+        branch_name = "#{BRANCH_PREFIX}#{issue}"
+        @git.checkout_branch(local_path, branch_name)
+        # `submit` needs to know the canonical project to point the PR at.
+        # Naming it `upstream` follows the standard fork workflow convention.
+        @git.add_remote(local_path, "upstream",
+                        "https://github.com/#{project.owner}/#{project.repo}.git")
+
+        @stdout.puts "Forked, cloned, and branched."
+        @stdout.puts "  path:   #{local_path}"
+        @stdout.puts "  branch: #{branch_name}"
+        @stdout.puts "  upstream: https://github.com/#{project.owner}/#{project.repo}"
+        @stdout.puts "  fork:     https://github.com/#{viewer}/#{project.repo}"
+        @stdout.puts
+        @stdout.puts "Next: cd #{local_path} && make your changes, then `gem-contribute submit`."
+        0
+      end
+
+      def ensure_fork(adapter, project, viewer)
+        if adapter.already_forked?(project)
+          @stdout.puts "You already have a fork at #{viewer}/#{project.repo}. Skipping fork."
+          return "https://github.com/#{viewer}/#{project.repo}.git"
+        end
+
+        @stdout.puts "Forking #{project.owner}/#{project.repo} → #{viewer}/#{project.repo}..."
+        body = adapter.fork(project)
+        wait_until_ready(adapter, viewer, project.repo)
+        body.fetch("clone_url")
+      end
+
+      def wait_until_ready(adapter, viewer, name)
+        ready = FORK_READINESS_RETRIES.times.any? do |i|
+          break true if adapter.fork_ready?(viewer, name)
+
+          @sleeper.call(FORK_READINESS_INTERVAL) unless i == FORK_READINESS_RETRIES - 1
+          false
+        end
+        return if ready
+
+        raise AdapterError, "fork not reachable after #{FORK_READINESS_RETRIES * FORK_READINESS_INTERVAL}s"
+      end
+
+      def clone_into_root(project, clone_url)
+        target = File.join(@clone_root, project.owner, project.repo)
+        if File.directory?(File.join(target, ".git"))
+          @stdout.puts "Reusing existing clone at #{target}."
+          return target
+        end
+
+        FileUtils.mkdir_p(File.dirname(target))
+        @stdout.puts "Cloning into #{target}..."
+        @git.clone(clone_url, target)
+        target
+      end
+    end
+
+    # Thin wrapper around git so the spec can swap in a fake without shelling
+    # out. The real implementation uses Open3 with arg-list invocation — no
+    # shell, so no injection surface.
+    class Git
+      def clone(url, target)
+        run!(["git", "clone", url, target])
+      end
+
+      def checkout_branch(path, branch)
+        run!(["git", "-C", path, "checkout", "-b", branch])
+      end
+
+      def add_remote(path, name, url)
+        # Idempotent: if the remote already exists (e.g. reusing a clone)
+        # we silently succeed rather than fail the whole flow.
+        return if remote_exists?(path, name)
+
+        run!(["git", "-C", path, "remote", "add", name, url])
+      end
+
+      def push(path, remote, branch)
+        run!(["git", "-C", path, "push", "-u", remote, branch])
+      end
+
+      def remote_exists?(path, name)
+        out, _err, status = Open3.capture3("git", "-C", path, "remote")
+        status.success? && out.split("\n").include?(name)
+      end
+
+      def run!(argv)
+        _stdout, stderr_str, status = Open3.capture3(*argv)
+        return if status.success?
+
+        raise GemContribute::AdapterError, "git #{argv[1..].join(" ")} failed: #{stderr_str.strip}"
+      end
+    end
+  end
+end

data/lib/gem_contribute/cli/issues.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module GemContribute
+  module CLI
+    # `gem-contribute issues <gem|all>` — list open "good first issue" issues.
+    #
+    # With a gem name: lists issues for that gem.
+    # With "all":     iterates every github.com gem in Gemfile.lock.
+    #
+    # Issue numbers appear prominently so they can be passed directly to
+    # `fork-clone-branch <gem>/<issue#>`.
+    class Issues
+      DEFAULT_LABEL = "good first issue"
+
+      def initialize(stdout: $stdout, stderr: $stderr,
+                     resolver: Resolver.new,
+                     adapter: HostAdapters::GitHubAdapter.new,
+                     lockfile_path: "Gemfile.lock")
+        @stdout = stdout
+        @stderr = stderr
+        @resolver = resolver
+        @adapter = adapter
+        @lockfile_path = lockfile_path
+      end
+
+      def run(argv)
+        target = argv.shift
+        return print_usage if target.nil?
+
+        if target == "all"
+          run_all
+        else
+          project = resolve_or_fail(target)
+          return 1 if project.nil?
+
+          list_issues(project)
+        end
+      rescue AdapterError => e
+        @stderr.puts "gem-contribute: #{e.message}"
+        1
+      end
+
+      private
+
+      def print_usage
+        @stderr.puts "Usage: gem-contribute issues <gem|all>"
+        2
+      end
+
+      def run_all
+        gems = LockfileParser.parse(@lockfile_path)
+        projects = gems.filter_map do |gem|
+          project = @resolver.resolve(gem)
+          project if project.host == "github.com"
+        end
+
+        @stdout.puts "Scanning #{projects.size} github.com gems from #{@lockfile_path}...\n\n"
+
+        any = false
+        projects.each do |project|
+          issues = fetch_issues(project)
+          next if issues.empty?
+
+          any = true
+          print_project_issues(project, issues)
+        end
+
+        @stdout.puts "(no good first issues found across #{projects.size} gems)" unless any
+        0
+      rescue LockfileNotFound => e
+        @stderr.puts "gem-contribute: #{e.message}"
+        1
+      end
+
+      def fetch_issues(project)
+        @adapter.issues(project, labels: [DEFAULT_LABEL])
+      rescue AdapterError => e
+        @stderr.puts "  warning: #{project.gem_name}: #{e.message}"
+        []
+      end
+
+      def resolve_or_fail(gem_name)
+        # gem-contribute isn't on RubyGems yet; short-circuit to the canonical
+        # self-project so the tool's own issues are reachable today.
+        return GemContribute::SELF_PROJECT if gem_name == GemContribute::SELF_PROJECT.gem_name
+
+        gem = LockedGem.new(name: gem_name, version: "*",
+                            source_type: :rubygems, source_uri: "https://rubygems.org/")
+        project = @resolver.resolve(gem)
+
+        if project.host != "github.com"
+          @stderr.puts "#{gem_name}: resolves to #{project.host} (only github.com is supported)"
+          return nil
+        end
+
+        project
+      end
+
+      def list_issues(project)
+        issues = @adapter.issues(project, labels: [DEFAULT_LABEL])
+        print_project_issues(project, issues)
+        @stdout.puts "To contribute: gem-contribute fix #{project.gem_name}/<issue#>"
+        0
+      end
+
+      def print_project_issues(project, issues)
+        repo_url = "https://github.com/#{project.owner}/#{project.repo}"
+        @stdout.puts "#{project.gem_name} — #{issues.size} open \"#{DEFAULT_LABEL}\" issues (#{repo_url})"
+
+        if issues.empty?
+          @stdout.puts "  (none — browse #{repo_url}/issues directly)"
+        else
+          @stdout.puts
+          issues.each do |issue|
+            @stdout.puts "  ##{issue["number"]}  #{issue["title"]}"
+            @stdout.puts "        #{issue["html_url"]}"
+            @stdout.puts
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gem_contribute/cli/scan.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module GemContribute
+  module CLI
+    # `gem-contribute scan [path]` — Stage 1's command.
+    #
+    # Reads a Gemfile.lock, resolves each rubygems-sourced gem, hits the
+    # GitHub adapter for `good first issue`-tagged issue counts on every
+    # github.com project, and prints:
+    #
+    #   <N> gems · <N> on github.com · <N> on <other> · <N> unknown source
+    #
+    #   Top contributable projects (by open `good first issue` count):
+    #     <gem-name>  <count>  <github.com/owner/repo>
+    #     ...
+    class Scan
+      # GitHub's `labels=foo,bar` query is an AND, not an OR, so passing the
+      # full set of beginner-friendly variants returns almost nothing. Stage 1
+      # uses the canonical `good first issue` label only — the "render labels
+      # verbatim" promise in ADR-0005 belongs to display, not to server-side
+      # filtering. Future stages can call once per label and dedupe.
+      DEFAULT_LABEL = "good first issue"
+
+      def initialize(stdout: $stdout, stderr: $stderr, resolver: Resolver.new, adapter: HostAdapters::GitHubAdapter.new)
+        @stdout = stdout
+        @stderr = stderr
+        @resolver = resolver
+        @adapter = adapter
+      end
+
+      # @param argv [Array<String>] passed-in args (no leading "scan")
+      # @return [Integer] exit status
+      def run(argv)
+        path = argv.first || "Gemfile.lock"
+        gems = LockfileParser.parse(path)
+        @stdout.puts "Scanning #{path} (#{gems.size} gems)..."
+
+        projects = gems.map { |gem| @resolver.resolve(gem) }
+        # Summary tally reflects only the lockfile contents — the
+        # self-injection is intentionally additive, not part of the count.
+        print_summary(tally_hosts(projects), gems.size)
+        scan_github_projects(projects)
+        0
+      rescue LockfileNotFound => e
+        @stderr.puts "gem-contribute: #{e.message}"
+        1
+      rescue Errno::ECONNREFUSED, SocketError => e
+        @stderr.puts "gem-contribute: network unreachable (#{e.class}: #{e.message})"
+        @stderr.puts "Re-run when you have connectivity, or use cached data with --refresh disabled."
+        1
+      end
+
+      private
+
+      def inject_self(github_projects)
+        return github_projects if github_projects.any? { |p| p.gem_name == GemContribute::SELF_PROJECT.gem_name }
+
+        github_projects + [GemContribute::SELF_PROJECT]
+      end
+
+      def scan_github_projects(projects)
+        github_from_lockfile = projects.select { |p| p.host == "github.com" }
+        @stdout.puts "\nNo github.com projects in this lockfile." if github_from_lockfile.empty?
+
+        ranked = rank_by_issue_count(inject_self(github_from_lockfile))
+        return if ranked.empty?
+
+        print_ranked(ranked)
+      end
+
+      def tally_hosts(projects)
+        counts = Hash.new(0)
+        projects.each { |p| counts[p.host] += 1 }
+        counts
+      end
+
+      def print_summary(host_counts, total)
+        parts = ["#{total} gems"]
+        host_counts.each do |host, count|
+          label = host == :unknown ? "unknown source" : "on #{host}"
+          parts << "#{count} #{label}"
+        end
+        @stdout.puts parts.join(" · ")
+      end
+
+      def rank_by_issue_count(projects)
+        # We hit the API anonymously here. With a 60/hr unauthenticated rate
+        # limit, scanning a 50-gem lockfile is the dominant pressure on this
+        # CLI. The 7-day RubyGems and 5-min issues caches absorb most repeats.
+        results = projects.map do |project|
+          count = issue_count(project)
+          [project, count]
+        end.compact
+
+        results.reject { |_, count| count.zero? }.sort_by { |_, count| -count }
+      end
+
+      def issue_count(project)
+        issues = @adapter.issues(project, labels: [DEFAULT_LABEL])
+        issues.size
+      rescue AdapterError, AuthRequired => e
+        @stderr.puts "  warning: #{project.gem_name} (#{project.host}/#{project.owner}/#{project.repo}): #{e.message}"
+        0
+      end
+
+      def print_ranked(ranked)
+        @stdout.puts
+        @stdout.puts "Top contributable projects (by open `good first issue` count):"
+        col_name = ranked.map { |p, _| p.gem_name.length }.max
+        ranked.each do |project, count|
+          location = "#{project.host}/#{project.owner}/#{project.repo}"
+          @stdout.printf("  %-#{col_name}s  %3d  %s\n", project.gem_name, count, location)
+        end
+      end
+    end
+  end
+end