gem-contribute 0.1.0 → 0.3.0

data/lib/gem_contribute/cli/scan.rb

@@ -21,9 +21,10 @@ module GemContribute
       # 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
+      def initialize(stdout: $stdout, stderr: $stderr, output: nil,
+                     resolver: Resolver.new,
+                     adapter: HostAdapters::GitHubAdapter.new)
+        @output = output || Output::Standard.new(out: stdout, err: stderr)
         @resolver = resolver
         @adapter = adapter
       end
@@ -33,20 +34,21 @@ module GemContribute
       def run(argv)
         path = argv.first || "Gemfile.lock"
         gems = LockfileParser.parse(path)
-        @stdout.puts "Scanning #{path} (#{gems.size} gems)..."
+        @output.progress("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)
+        RateLimitFooter.print(adapter: @adapter, output: @output)
         0
       rescue LockfileNotFound => e
-        @stderr.puts "gem-contribute: #{e.message}"
+        @output.error("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."
+        @output.error("gem-contribute: network unreachable (#{e.class}: #{e.message})")
+        @output.error("Re-run when you have connectivity, or use cached data with --refresh disabled.")
         1
       end
 
@@ -60,12 +62,13 @@ module GemContribute
 
       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?
+        @output.info("\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)
+        claim_index = IssueAnnouncer.fetch_claim_index(@adapter)
+        print_ranked(ranked, claim_index)
       end
 
       def tally_hosts(projects)
@@ -80,7 +83,7 @@ module GemContribute
           label = host == :unknown ? "unknown source" : "on #{host}"
           parts << "#{count} #{label}"
         end
-        @stdout.puts parts.join(" · ")
+        @output.info(parts.join(" · "))
       end
 
       def rank_by_issue_count(projects)
@@ -99,17 +102,19 @@ module GemContribute
         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}"
+        @output.warn("  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):"
+      def print_ranked(ranked, claim_index)
+        @output.info("")
+        @output.info("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)
+          claimed = claim_index["#{project.owner}/#{project.repo}"] || []
+          suffix = claimed.empty? ? "" : "  · #{claimed.size} claimed"
+          @output.info(format("  %-#{col_name}s  %3d  %s%s", project.gem_name, count, location, suffix))
         end
       end
     end

data/lib/gem_contribute/cli/submit.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "open3"
-require "uri"
 
 module GemContribute
   module CLI
@@ -13,21 +12,23 @@ module GemContribute
     #   - 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.
+    # The PR itself is NOT opened via API. We push, then open the host's
+    # compare/MR 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. The host-specific
+    # URL is built by the adapter (ADR-0011).
     class Submit
+      include PlatformTools
+
       BRANCH_REGEX = %r{\Agem-contribute/issue-(\d+)\z}
 
-      def initialize(stdout: $stdout, stderr: $stderr,
-                     git: Git.new,
+      def initialize(stdout: $stdout, stderr: $stderr, output: nil,
+                     git: GemContribute::Git.new,
                      adapter_factory: ->(token:) { HostAdapters::GitHubAdapter.new(token: token) },
                      store: TokenStore.new,
                      browser_opener: nil,
                      working_dir: Dir.pwd)
-        @stdout = stdout
-        @stderr = stderr
+        @output = output || Output::Standard.new(out: stdout, err: stderr)
         @git = git
         @adapter_factory = adapter_factory
         @store = store
@@ -47,19 +48,30 @@ module GemContribute
         # 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
+        execute(branch, issue_number, origin, upstream)
       rescue AdapterError => e
-        @stderr.puts "submit failed: #{e.message}"
+        @output.error("submit failed: #{e.message}")
         1
       end
 
       private
 
+      def execute(branch, issue_number, origin, upstream)
+        adapter = @adapter_factory.call(token: @store.token_for("github.com"))
+        upstream_project = project_for(upstream)
+        title = fetch_issue_title(adapter, upstream_project, issue_number)
+        push_branch(branch)
+        url = adapter.pull_request_url(
+          upstream_project,
+          head_owner: origin[:owner],
+          head_branch: branch,
+          title: pr_title(issue_number, title),
+          body: pr_body(issue_number)
+        )
+        open_and_print(url)
+        0
+      end
+
       def current_branch
         # symbolic-ref works even on a fresh branch with no commits;
         # rev-parse --abbrev-ref doesn't.
@@ -73,82 +85,66 @@ module GemContribute
         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."
+        @output.error("submit: branch #{branch.inspect} doesn't match #{BRANCH_REGEX.source}.")
+        @output.error("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
+        return missing_remote_error(name) if !status.success? && required
+        return nil unless status.success?
 
         owner_repo_from_url(out.strip)
       end
 
+      def missing_remote_error(name)
+        @output.error("submit: no `#{name}` remote configured. Are you inside a git clone?")
+        nil
+      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}"
+          @output.error("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)
+      def project_for(owner_repo)
+        Project.new(
+          gem_name: owner_repo[:repo], host: "github.com",
+          owner: owner_repo[:owner], repo: owner_repo[:repo], metadata: {}
+        )
+      end
+
+      def fetch_issue_title(adapter, upstream_project, number)
+        adapter.issue(upstream_project, number).fetch("title", nil)
       rescue AdapterError => e
-        @stderr.puts "submit: couldn't fetch issue title (#{e.message}). Continuing without it."
+        @output.warn("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)
+      def pr_title(issue_number, title)
+        title ? "Fix ##{issue_number}: #{title}" : "Fix ##{issue_number}"
       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)}"
+      def pr_body(issue_number)
+        "Closes ##{issue_number}.\n\n_Opened via `gem-contribute submit`._"
       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}"
+      def push_branch(branch)
+        @output.progress("Pushing #{branch} to origin...") do
+          @git.push(@working_dir, "origin", branch)
+        end
       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
+      def open_and_print(url)
+        opened = @browser_opener.call(url)
+        @output.info(opened ? "Opened browser to:" : "Open this URL to file the PR:")
+        @output.info("  #{url}")
       end
     end
   end

data/lib/gem_contribute/cli/workflow.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+
+module GemContribute
+  module CLI
+    # Shared scaffolding for action-style CLI verbs (Fix, Fork, future
+    # Abandon). Each verb owns its own `parse_argv`, `execute`, and
+    # `print_usage_error`; this module captures the common pieces around
+    # them: the missing-clone_root error, the auth-token check (as a
+    # Result-returning service per ADR-0012), and the project resolver.
+    #
+    # Including classes are expected to hold:
+    #   @output, @resolver, @store, @adapter_factory, @clone_root
+    module Workflow
+      include Dry::Monads[:result]
+
+      private
+
+      def missing_clone_root
+        @output.error("clone_root is not configured. Run `gem-contribute init` first.")
+        1
+      end
+
+      # Per ADR-0012: returns Success(adapter) | Failure(:unauthenticated).
+      # Callers pattern-match — no nil + stderr side effect, no exceptions.
+      def build_adapter
+        token = @store.token_for("github.com")
+        return Failure(:unauthenticated) if token.nil?
+
+        Success(@adapter_factory.call(token: token))
+      end
+
+      # Resolves a CLI target to a `github.com` Project, or prints an
+      # error and returns nil. With `allow_owner_repo: true` the slash
+      # form (`owner/repo`) bypasses RubyGems and constructs the Project
+      # directly — useful for verbs that don't require a published gem.
+      def resolve_target(target, verb:, allow_owner_repo: false)
+        if allow_owner_repo && target.include?("/")
+          owner, repo = target.split("/", 2)
+          return GemContribute::Project.new(
+            gem_name: repo, host: "github.com",
+            owner: owner, repo: repo, metadata: {}
+          )
+        end
+
+        return GemContribute::SELF_PROJECT if target == GemContribute::SELF_PROJECT.gem_name
+
+        gem = LockedGem.new(name: target, version: "*",
+                            source_type: :rubygems, source_uri: "https://rubygems.org/")
+        project = @resolver.resolve(gem)
+
+        if project.host != "github.com"
+          @output.error("Cannot run `#{verb}`: #{target} resolves to #{project.host} " \
+                        "(only github.com is supported at v0.1)")
+          return nil
+        end
+
+        project
+      end
+    end
+  end
+end

data/lib/gem_contribute/cli.rb

@@ -4,17 +4,11 @@ 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:
+        init                     One-time interactive setup (sets clone_root).
         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).
@@ -24,8 +18,13 @@ module GemContribute
         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.
+        fork <gem|owner/repo>    Fork (and clone) any GitHub repo. Pass a gem name
+                                 to look it up on RubyGems, or `owner/repo` for any
+                                 GitHub project (e.g. `rubyevents/rubyevents`).
+                                 Lands on the default branch.
+                                 Flags: -e (editor), -a (AI tool).
         fix <gem>/<issue#>       Fork the gem's repo, clone the fork, branch from main.
-                                 (alias: fork-clone-branch)
+                                 Flags: -e (editor), -a (AI tool), --no-comment.
         submit                   Push the current branch and open a pre-filled
                                  PR compare page in the browser. Run from inside
                                  a clone created by `fix`.
@@ -58,17 +57,15 @@ module GemContribute
     end
 
     COMMANDS = {
+      "init" => ->(o, e) { Init.new(stdout: o, stderr: e) },
       "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) },
+      "fork" => ->(o, e) { Fork.new(stdout: o, stderr: e, clone_root: GemContribute::Config.new.clone_root) },
       "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)
+        config = GemContribute::Config.new
+        Fix.new(stdout: o, stderr: e, clone_root: config.clone_root, config: config)
       },
       "submit" => ->(o, e) { Submit.new(stdout: o, stderr: e) }
     }.freeze

data/lib/gem_contribute/config.rb

@@ -8,9 +8,7 @@ module GemContribute
   # 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
+    KNOWN_KEYS = %w[clone_root editor ai_tool comment_on_fix].freeze
 
     def initialize(path: self.class.default_path)
       @path = path
@@ -19,7 +17,26 @@ module GemContribute
 
     def clone_root
       raw = @data["clone_root"]
-      raw ? File.expand_path(raw) : DEFAULT_CLONE_ROOT
+      raw ? File.expand_path(raw) : nil
+    end
+
+    def editor
+      @data["editor"]
+    end
+
+    def ai_tool
+      @data["ai_tool"]
+    end
+
+    # Returns whether `fix` should post a "working on this" comment.
+    # Pass a repo (`"owner/repo"`) to check the per-repo override; without
+    # a repo, returns the global default. Default is true when unset.
+    def comment_on_fix?(repo = nil)
+      overrides = @data["comment_on_fix_overrides"]
+      return truthy?(overrides[repo]) if repo && overrides.is_a?(Hash) && overrides.key?(repo)
+
+      raw = @data["comment_on_fix"]
+      raw.nil? || truthy?(raw)
     end
 
     def set(key, value)
@@ -41,6 +58,13 @@ module GemContribute
 
     private
 
+    def truthy?(value)
+      case value
+      when true, false then value
+      else value.to_s.downcase != "false"
+      end
+    end
+
     def load_file
       return {} unless File.exist?(@path)
 

data/lib/gem_contribute/git.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module GemContribute
+  # Thin wrapper around the `git` CLI so callers can substitute a fake in
+  # tests without shelling out. Uses Open3 with arg-list invocation (no shell)
+  # so there's 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 branch_exists?(path, branch)
+      _out, _err, status = Open3.capture3("git", "-C", path,
+                                          "rev-parse", "--verify", "--quiet",
+                                          "refs/heads/#{branch}")
+      status.success?
+    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

data/lib/gem_contribute/host_adapter.rb

@@ -3,24 +3,51 @@
 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.
+  # rest of the app — Operations, CLI verbs, TUI — doesn't have to special-case
+  # anything beyond looking up the right adapter for a project's host.
+  #
+  # See ADR-0011: HostAdapter owns the host-API verbs (fork, comment,
+  # pull_request_url) plus the host-specific URL templating (clone_url,
+  # repo_url). Higher layers compose those primitives; they don't construct
+  # host URLs themselves.
   #
   # Public-API methods (no auth needed):
   #   issues(project, labels:)
+  #   issue(project, number)
+  #   issue_comments(project, number)
   #   community_profile(project)
   #   file_contents(project, path)
+  #   search_issues(query)
+  #   clone_url(owner, repo)
+  #   repo_url(owner, repo)
   #
   # Auth-required methods (raise AuthRequired without a cached token):
-  #   fork(project)
-  #   already_forked?(project)
+  #   fork(project)            — idempotent, blocks until the fork is reachable
+  #   comment(project, issue:, body:)
+  #   pull_request_url(upstream, head_owner:, head_branch:, title:, body:)
+  #   viewer_login
   #
   # See ADR-0001 for the JIT auth contract.
   class HostAdapter
+    # Result of a successful `fork(project)`.
+    # - clone_url:  HTTPS URL suitable for `git clone`.
+    # - fork_url:   human-readable web URL of the fork (used in summaries).
+    # - viewer:     the authenticated user's login (and the fork's owner).
+    # - reused:     true if the fork already existed; false if just created.
+    ForkResult = Data.define(:clone_url, :fork_url, :viewer, :reused)
+
     def issues(_project, labels: nil)
       raise NotImplementedError
     end
 
+    def issue(_project, _number)
+      raise NotImplementedError
+    end
+
+    def issue_comments(_project, _number)
+      raise NotImplementedError
+    end
+
     def community_profile(_project)
       raise NotImplementedError
     end
@@ -29,11 +56,31 @@ module GemContribute
       raise NotImplementedError
     end
 
+    def search_issues(_query)
+      raise NotImplementedError
+    end
+
     def fork(_project)
       raise NotImplementedError
     end
 
-    def already_forked?(_project)
+    def comment(_project, issue:, body:)
+      raise NotImplementedError
+    end
+
+    def pull_request_url(_upstream, head_owner:, head_branch:, title:, body:)
+      raise NotImplementedError
+    end
+
+    def viewer_login
+      raise NotImplementedError
+    end
+
+    def clone_url(_owner, _repo)
+      raise NotImplementedError
+    end
+
+    def repo_url(_owner, _repo)
       raise NotImplementedError
     end
   end