gem-contribute 0.1.0 → 0.3.0

data/lib/gem_contribute/cli/fix.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "dry/initializer"
+require "dry/monads"
+
+module GemContribute
+  module CLI
+    # `gem-contribute fix <gem>/<issue#> [-e] [-a] [--no-comment]`
+    #
+    # The issue-tied path: run `Operations::FixPipeline` (Fork → Clone →
+    # Branch → Announce), then optionally open the user's editor or AI
+    # tool. The verb is a thin Result-pattern-matching shell around the
+    # pipeline (per ADR-0012).
+    class Fix
+      extend Dry::Initializer
+      include Workflow
+      include Dry::Monads[:result]
+
+      DEFAULT_CLONE_ROOT = File.expand_path("~/code/oss")
+
+      option :stdout, default: -> { $stdout }
+      option :stderr, default: -> { $stderr }
+      option :output, default: -> { Output::Standard.new(out: stdout, err: stderr) }
+      option :resolver, default: -> { Resolver.new }
+      option :store, default: -> { TokenStore.new }
+      option :adapter_factory,
+             default: -> { ->(token:) { HostAdapters::GitHubAdapter.new(token: token) } }
+      option :git, default: -> { GemContribute::Git.new }
+      option :clone_root, default: -> { DEFAULT_CLONE_ROOT }
+      option :post_clone_hooks, default: -> { PostCloneHooks.new(output: output) }
+      option :config, default: -> { GemContribute::Config.new }
+      option :pipeline, default: -> { Operations::FixPipeline.new(git: git) }
+
+      def run(argv)
+        return missing_clone_root if @clone_root.nil?
+
+        target, flags = parse_argv(argv)
+        return print_usage_error if target.nil? || !target.include?("/")
+
+        gem_name, issue = target.split("/", 2)
+
+        case build_adapter
+        in Success(adapter)
+          project = resolve_target(gem_name, verb: "fix")
+          return 1 if project.nil?
+
+          execute(adapter, project, issue, flags)
+        in Failure(:unauthenticated)
+          @output.error("Not authenticated. Run `gem-contribute auth login` first.")
+          1
+        end
+      end
+
+      private
+
+      def parse_argv(argv)
+        flags = { editor: false, ai_tool: false, no_comment: false }
+        positional = []
+        argv.each do |arg|
+          case arg
+          when "-e", "--editor" then flags[:editor] = true
+          when "-a", "--ai"     then flags[:ai_tool] = true
+          when "--no-comment"   then flags[:no_comment] = true
+          else positional << arg
+          end
+        end
+        [positional.first, flags]
+      end
+
+      def print_usage_error
+        @output.error("Usage: gem-contribute fix <gem>/<issue#> [-e] [-a]")
+        2
+      end
+
+      def execute(adapter, project, issue, flags)
+        allow_announce = !flags[:no_comment] &&
+                         @config.comment_on_fix?("#{project.owner}/#{project.repo}")
+
+        result = @output.progress("Forking #{project.owner}/#{project.repo}...") do
+          @pipeline.call(adapter: adapter, project: project, issue: issue,
+                         root: @clone_root, allow_announce: allow_announce)
+        end
+
+        case result
+        in Success(fork: fork_data, clone: clone_data, branch: branch_data, announce: announce_data)
+          print_summary(clone_data.path, branch_data.name, fork_data)
+          print_announce_outcome(announce_data, issue)
+          @post_clone_hooks.call(clone_data.path, editor: flags[:editor], ai_tool: flags[:ai_tool])
+          0
+        in Failure(:unauthenticated)
+          @output.error("Not authenticated. Run `gem-contribute auth login` first.")
+          1
+        in Failure(:adapter_error, message)
+          @output.error("fix failed: #{message}")
+          1
+        end
+      end
+
+      def print_summary(local_path, branch_name, fork_info)
+        @output.info("Forked, cloned, and branched.")
+        @output.info("  path:   #{local_path}")
+        @output.info("  branch: #{branch_name}")
+        @output.info("  upstream: #{fork_info.upstream_url}")
+        @output.info("  fork:     #{fork_info.fork_url}")
+        @output.info("")
+        @output.info("Next: cd #{local_path} && make your changes, then `gem-contribute submit`.")
+      end
+
+      def print_announce_outcome(announce_result, issue)
+        case announce_result
+        in Success(:posted)
+          @output.info("Posted 'working on this' comment to issue ##{issue}.")
+        in Success(:skipped)
+          # no output for skipped — quiet success
+        in Failure(:announce_failed, message)
+          @output.warn("Note: couldn't post 'working on this' comment to issue ##{issue}: " \
+                       "#{message}. Continuing.")
+        end
+      end
+    end
+  end
+end

data/lib/gem_contribute/cli/fork.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "dry/initializer"
+require "dry/monads"
+
+module GemContribute
+  module CLI
+    # `gem-contribute fork <gem|owner/repo> [-e] [-a]`. Resolve the target,
+    # bootstrap a fork+clone via `Operations::Fork` + `Operations::Clone`,
+    # print a summary, run post-clone hooks. The CLI verb is a thin
+    # composition; the host-API ceremony lives in the adapter and the
+    # filesystem policy lives in Operations (ADR-0011). Operations are
+    # output-free per ADR-0012; this verb does the printing.
+    class Fork
+      extend Dry::Initializer
+      include Workflow
+      include Dry::Monads[:result]
+
+      DEFAULT_CLONE_ROOT = File.expand_path("~/code/oss")
+
+      option :stdout, default: -> { $stdout }
+      option :stderr, default: -> { $stderr }
+      option :output, default: -> { Output::Standard.new(out: stdout, err: stderr) }
+      option :resolver, default: -> { Resolver.new }
+      option :store, default: -> { TokenStore.new }
+      option :adapter_factory,
+             default: -> { ->(token:) { HostAdapters::GitHubAdapter.new(token: token) } }
+      option :git, default: -> { GemContribute::Git.new }
+      option :clone_root, default: -> { DEFAULT_CLONE_ROOT }
+      option :post_clone_hooks, default: -> { PostCloneHooks.new(output: output) }
+      option :fork_op, default: -> { Operations::Fork.new }
+      option :clone_op, default: -> { Operations::Clone.new(git: git) }
+
+      def run(argv)
+        return missing_clone_root if @clone_root.nil?
+
+        target, flags = parse_argv(argv)
+        return print_usage_error if target.nil?
+
+        case build_adapter
+        in Success(adapter)
+          project = resolve_target(target, verb: "fork", allow_owner_repo: true)
+          return 1 if project.nil?
+
+          execute(adapter, project, flags)
+        in Failure(:unauthenticated)
+          @output.error("Not authenticated. Run `gem-contribute auth login` first.")
+          1
+        end
+      end
+
+      # The bootstrap primitive Fix shares: fork (or reuse) → clone (or
+      # reuse) → upstream remote. Returns `Success([local_path, fork_info])`
+      # on the happy path; `Failure(reason)` propagated from Operations
+      # otherwise.
+      def bootstrap(adapter, project)
+        @output.progress("Forking #{project.owner}/#{project.repo}...")
+        fork_result = @fork_op.call(adapter: adapter, project: project)
+        return fork_result if fork_result.failure?
+
+        fork_info = fork_result.value!
+        @output.info(fork_status_line(fork_info, project))
+
+        clone_result = @clone_op.call(adapter: adapter, project: project,
+                                      fork_clone_url: fork_info.clone_url, root: @clone_root)
+        return clone_result if clone_result.failure?
+
+        clone_info = clone_result.value!
+        @output.info(clone_status_line(clone_info))
+
+        Success([clone_info.path, fork_info])
+      end
+
+      private
+
+      def parse_argv(argv)
+        flags = { editor: false, ai_tool: false }
+        positional = []
+        argv.each do |arg|
+          case arg
+          when "-e", "--editor" then flags[:editor] = true
+          when "-a", "--ai"     then flags[:ai_tool] = true
+          else positional << arg
+          end
+        end
+        [positional.first, flags]
+      end
+
+      def print_usage_error
+        @output.error("Usage: gem-contribute fork <gem|owner/repo> [-e] [-a]")
+        2
+      end
+
+      def execute(adapter, project, flags)
+        case bootstrap(adapter, project)
+        in Success(local_path, fork_info)
+          print_summary(local_path, project, fork_info, flags)
+          @post_clone_hooks.call(local_path, editor: flags[:editor], ai_tool: flags[:ai_tool])
+          0
+        in Failure(:unauthenticated)
+          @output.error("Not authenticated. Run `gem-contribute auth login` first.")
+          1
+        in Failure(:adapter_error, message)
+          @output.error("fork failed: #{message}")
+          1
+        end
+      end
+
+      def fork_status_line(info, project)
+        if info.reused
+          "  Reusing existing fork at #{info.viewer}/#{project.repo}."
+        else
+          "  Forked → #{info.viewer}/#{project.repo}."
+        end
+      end
+
+      def clone_status_line(info)
+        if info.reused
+          "Reusing existing clone at #{info.path}."
+        else
+          "Cloned into #{info.path}."
+        end
+      end
+
+      def print_summary(local_path, project, fork_info, flags)
+        @output.info("Forked and cloned. You're on the default branch.")
+        @output.info("  path:     #{local_path}")
+        @output.info("  upstream: #{fork_info.upstream_url}")
+        @output.info("  fork:     #{fork_info.fork_url}")
+        @output.info("")
+        @output.info(next_hint(local_path, project, flags))
+      end
+
+      def next_hint(local_path, project, flags)
+        fix_command = "`gem-contribute fix #{project.gem_name}/<issue#>`"
+        if flags[:editor] || flags[:ai_tool]
+          "Next: pick an issue and run #{fix_command} to branch off the default."
+        else
+          "Next: cd #{local_path} && $EDITOR . " \
+            "When you pick an issue, #{fix_command} branches off the default."
+        end
+      end
+    end
+  end
+end

data/lib/gem_contribute/cli/init.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "tty-prompt"
+
+module GemContribute
+  module CLI
+    # `gem-contribute init` — interactive one-time setup. Writes the user's
+    # `clone_root` to ~/.config/gem-contribute/config.yml and, if no GitHub
+    # token is cached, offers to run `auth login`.
+    #
+    # Without init, `fix` errors with a hint to run init. The point is to
+    # avoid creating directories or assuming auth without explicit consent.
+    #
+    # Prompt input/output goes through `TTY::Prompt` (per ADR-0012 Phase 2,
+    # commit #31). The injected `prompt:` keyword lets tests pass a
+    # `TTY::Prompt.new(input:, output:)` with StringIO streams.
+    class Init
+      USAGE = <<~USAGE
+        Usage: gem-contribute init
+
+        Interactively set the directory where forks are cloned (clone_root),
+        then offer to authenticate with GitHub if you haven't already.
+        Re-run any time to change.
+      USAGE
+
+      DEFAULT_SUGGESTION = "~/code/oss"
+      AUTH_HOST = "github.com"
+
+      def initialize(stdout: $stdout, stderr: $stderr, output: nil,
+                     config: GemContribute::Config.new,
+                     store: GemContribute::TokenStore.new,
+                     auth: nil,
+                     prompt: nil)
+        @output = output || Output::Standard.new(out: stdout, err: stderr)
+        @config = config
+        @store = store
+        @auth = auth || GemContribute::CLI::Auth.new(output: @output, store: store)
+        @prompt = prompt || TTY::Prompt.new
+      end
+
+      def run(argv)
+        return print_usage if %w[help -h --help].include?(argv.first)
+
+        prompt_clone_root
+        maybe_authenticate
+        0
+      end
+
+      private
+
+      def prompt_clone_root
+        current = @config.to_h["clone_root"]
+        default = current || DEFAULT_SUGGESTION
+        chosen = @prompt.ask("Where should I clone repos?", default: default)
+        @config.set("clone_root", chosen)
+        @output.info("Clone root set to #{File.expand_path(chosen)}")
+      end
+
+      def maybe_authenticate
+        if @store.token_for(AUTH_HOST)
+          @output.info("GitHub: already authenticated.")
+          return
+        end
+
+        if @prompt.yes?("Authenticate with GitHub now?", default: true)
+          @auth.run(["login"])
+        else
+          @output.info("Skipping auth. Run `gem-contribute auth login` when you're ready.")
+        end
+      end
+
+      def print_usage
+        @output.info(USAGE)
+        0
+      end
+    end
+  end
+end

data/lib/gem_contribute/cli/issue_announcer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module GemContribute
+  module CLI
+    # CLI-side helpers for the "I'm working on this" claim machinery.
+    #
+    # The actual posting (and gating) lives in `Operations::Announce`
+    # (output-free, Result-returning) — see ADR-0012. What remains here
+    # is the index-fetching used by `scan` and `issues` to flag claimed
+    # issues in their output. Both halves share `Operations::Announce::WORKING_MARKER`.
+    module IssueAnnouncer
+      MARKER = Operations::Announce::WORKING_MARKER
+
+      module_function
+
+      # Builds a lookup hash of {"owner/repo" => Set<issue_number>} from
+      # GitHub's issue search for our marker. Used by `scan` and `issues`
+      # to flag claimed issues. One search call per process (the adapter
+      # caches the result for the issues TTL). Degrades to an empty hash
+      # if the search fails (anonymous rate limits, network, etc.).
+      def fetch_claim_index(adapter)
+        items = adapter.search_issues("\"#{MARKER}\" is:issue is:open")
+        items.each_with_object(Hash.new { |h, k| h[k] = [] }) do |item, index|
+          parsed = parse_issue_url(item["html_url"])
+          next unless parsed
+
+          owner, repo, number = parsed
+          index["#{owner}/#{repo}"] << number
+        end
+      rescue GemContribute::AdapterError, GemContribute::AuthRequired
+        {}
+      end
+
+      def parse_issue_url(url)
+        match = url.to_s.match(%r{github\.com/([^/]+)/([^/]+)/issues/(\d+)})
+        return nil unless match
+
+        [match[1], match[2], match[3].to_i]
+      end
+    end
+  end
+end

data/lib/gem_contribute/cli/issues.rb

@@ -8,16 +8,17 @@ module GemContribute
     # 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#>`.
+    # `fix <gem>/<issue#>`.
     class Issues
+      include Workflow
+
       DEFAULT_LABEL = "good first issue"
 
-      def initialize(stdout: $stdout, stderr: $stderr,
+      def initialize(stdout: $stdout, stderr: $stderr, output: nil,
                      resolver: Resolver.new,
                      adapter: HostAdapters::GitHubAdapter.new,
                      lockfile_path: "Gemfile.lock")
-        @stdout = stdout
-        @stderr = stderr
+        @output = output || Output::Standard.new(out: stdout, err: stderr)
         @resolver = resolver
         @adapter = adapter
         @lockfile_path = lockfile_path
@@ -27,26 +28,29 @@ module GemContribute
         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
+        @claim_index = IssueAnnouncer.fetch_claim_index(@adapter)
+        status = target == "all" ? run_all : run_single(target)
+        RateLimitFooter.print(adapter: @adapter, output: @output)
+        status
       rescue AdapterError => e
-        @stderr.puts "gem-contribute: #{e.message}"
+        @output.error("gem-contribute: #{e.message}")
         1
       end
 
       private
 
       def print_usage
-        @stderr.puts "Usage: gem-contribute issues <gem|all>"
+        @output.error("Usage: gem-contribute issues <gem|all>")
         2
       end
 
+      def run_single(target)
+        project = resolve_target(target, verb: "issues")
+        return 1 if project.nil?
+
+        list_issues(project)
+      end
+
       def run_all
         gems = LockfileParser.parse(@lockfile_path)
         projects = gems.filter_map do |gem|
@@ -54,7 +58,7 @@ module GemContribute
           project if project.host == "github.com"
         end
 
-        @stdout.puts "Scanning #{projects.size} github.com gems from #{@lockfile_path}...\n\n"
+        @output.info("Scanning #{projects.size} github.com gems from #{@lockfile_path}...\n")
 
         any = false
         projects.each do |project|
@@ -65,57 +69,46 @@ module GemContribute
           print_project_issues(project, issues)
         end
 
-        @stdout.puts "(no good first issues found across #{projects.size} gems)" unless any
+        @output.info("(no good first issues found across #{projects.size} gems)") unless any
         0
       rescue LockfileNotFound => e
-        @stderr.puts "gem-contribute: #{e.message}"
+        @output.error("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}"
+        @output.warn("  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#>"
+        @output.info("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})"
+        @output.info("#{project.gem_name} — #{issues.size} open \"#{DEFAULT_LABEL}\" issues (#{repo_url})")
 
         if issues.empty?
-          @stdout.puts "  (none — browse #{repo_url}/issues directly)"
+          @output.info("  (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
+          @output.info("")
+          print_issue_list(project, issues)
+        end
+      end
+
+      def print_issue_list(project, issues)
+        claimed = @claim_index["#{project.owner}/#{project.repo}"] || []
+        issues.each do |issue|
+          label = claimed.include?(issue["number"]) ? "[claimed] " : ""
+          @output.info("  ##{issue["number"]}  #{label}#{issue["title"]}")
+          @output.info("        #{issue["html_url"]}")
+          @output.info("")
         end
       end
     end

data/lib/gem_contribute/cli/platform_tools.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module GemContribute
+  module CLI
+    module PlatformTools
+      private
+
+      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)
+        cmd = case RbConfig::CONFIG["host_os"]
+              when /darwin/ then "pbcopy"
+              when /linux/  then ["xclip", "-selection", "clipboard"]
+              end
+        return false unless cmd
+
+        IO.popen(cmd, "w") { |p| p.write(text) }
+        true
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/gem_contribute/cli/post_clone_hooks.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module GemContribute
+  module CLI
+    # Optional post-clone hooks invoked by `fix` when the user passes
+    # `-e` (open editor) and/or `-a` (launch AI tool). Extracted so the
+    # `fix` state machine stays focused on the fork/clone/branch
+    # sequence.
+    class PostCloneHooks
+      def initialize(stdout: $stdout, stderr: $stderr, output: nil,
+                     config: GemContribute::Config.new,
+                     editor_runner: ->(cmd, path) { Kernel.system("#{cmd} #{path.shellescape}") },
+                     ai_runner: ->(cmd, path) { Kernel.system(cmd, chdir: path) })
+        @output = output || Output::Standard.new(out: stdout, err: stderr)
+        @config = config
+        @editor_runner = editor_runner
+        @ai_runner = ai_runner
+      end
+
+      def call(local_path, editor:, ai_tool:)
+        open_editor(local_path) if editor
+        launch_ai(local_path)   if ai_tool
+      end
+
+      private
+
+      def open_editor(local_path)
+        editor = @config.editor || ENV.fetch("EDITOR", nil)
+        if editor.nil? || editor.empty?
+          @output.warn("-e: no editor configured. " \
+                       "Set with `gem-contribute config set editor <cmd>` or set $EDITOR.")
+          return
+        end
+        @editor_runner.call(editor, local_path)
+      end
+
+      def launch_ai(local_path)
+        ai_tool = @config.ai_tool
+        if ai_tool.nil? || ai_tool.empty?
+          @output.warn("-a: no ai_tool configured. " \
+                       "Set with `gem-contribute config set ai_tool \"<cmd>\"`.")
+          return
+        end
+        @ai_runner.call(ai_tool, local_path)
+      end
+    end
+  end
+end

data/lib/gem_contribute/cli/rate_limit_footer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module GemContribute
+  module CLI
+    # Prints a one-line GitHub rate-limit footer after `scan` or `issues`
+    # finishes its main output, when the adapter has rate-limit data.
+    #
+    # Format: "GitHub rate limit: 4,587 / 5,000 remaining · resets at 14:32 UTC"
+    #
+    # When `adapter.rate_limit` is nil (e.g. every call was served from cache),
+    # nothing is printed — see #4 acceptance criteria.
+    module RateLimitFooter
+      module_function
+
+      # @param adapter [GemContribute::HostAdapters::GitHubAdapter]
+      # @param output [GemContribute::Output::Standard, GemContribute::Output::Null]
+      # @param stdout [IO] backward-compat for callers that haven't migrated to `output:`
+      def print(adapter:, output: nil, stdout: $stdout)
+        output ||= Output::Standard.new(out: stdout)
+        rate_limit = adapter.respond_to?(:rate_limit) ? adapter.rate_limit : nil
+        return if rate_limit.nil?
+
+        remaining = format_with_separators(rate_limit.remaining)
+        limit = format_with_separators(rate_limit.limit)
+        reset = rate_limit.reset_at.utc.strftime("%H:%M")
+        output.info("GitHub rate limit: #{remaining} / #{limit} remaining · resets at #{reset} UTC")
+      end
+
+      def format_with_separators(integer)
+        integer.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+      end
+    end
+  end
+end