ace-git-github 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0e706c505528940d27bbfeb97b2cc408293f4082c4ed8bbbf5735e2db9470db1
+  data.tar.gz: a6e07ea07d307f870f015736c5f2d6039f4e7b480ff1824241540e0f21cb9eac
+SHA512:
+  metadata.gz: 5c9f2355511d607ef3910972145dab113234012e6935d11e491735775a6a25c83f23c7efb798779b7324ae0f7f6bea5dd07686b1c8651c45da33103ceb284d9f
+  data.tar.gz: 37235ad5c2af2931d4cdf7e76177c82b572f047e0463bb7ae9a8594b52ae038f4a704bec4a6c3c4093e0f9c7b8b9bacaeb74a6a7b514eb377cb6ffe970d4674b

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to ace-git-github will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-21
+
+### Added
+
+- Initial GitHub provider package implementing the forge-neutral ace-git provider contract.
+- Owns all `gh` CLI invocation, output parsing, and authentication verification
+  (moved out of the ace-git core as part of foundation chunk F0, task 8wk.t.l1e).
+- Normalized evidence translation for pull requests, issues, checks, and repository
+  metadata, with the shared classified failure taxonomy (no silent fallbacks).
+- Shared provider-contract parity suite coverage against scripted fakes.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michal Czyz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,22 @@
+# ace-git-github
+
+GitHub provider for the forge-neutral [`ace-git`](../ace-git) core.
+
+This package owns **all** GitHub-specific behavior for ACE:
+
+- `gh` CLI invocation (with timeout handling and structured output)
+- `gh` output parsing and normalization
+- `gh` authentication verification
+- GitHub-specific identifier formats (including `github.com` PR URLs)
+
+It implements the provider contract defined by the core
+(`Ace::Git::Providers::Base`) and registers itself under the `:github`
+provider type, so consumers resolve it through
+`Ace::Git::Providers.for(server)` and read normalized evidence types
+(`Ace::Git::ProviderPullRequest`, `Ace::Git::ProviderIssue`,
+`Ace::Git::ProviderCheck`, `Ace::Git::ProviderRepository`).
+
+Failures are classified with the shared taxonomy
+(`ProviderCliMissingError`, `ProviderAuthenticationError`,
+`ProviderUnreachableError`, `ProviderMalformedOutputError`,
+`ProviderObjectNotFoundError`). There is no silent fallback.

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.warning = false
+  t.verbose = false
+end
+
+task default: :test

data/lib/ace/git/github/cli_executor.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "open3"
+require "timeout"
+
+module Ace
+  module Git
+    module Github
+      # Executes the GitHub CLI (`gh`) with timeout and structured output.
+      #
+      # Owns every `gh` subprocess invocation for ACE: presence probes, auth
+      # probes, and arbitrary `gh` subcommands. Failures are classified with
+      # the shared provider taxonomy. A test runner may be injected instead of
+      # spawning real processes (see Providers::Base).
+      module CliExecutor
+        DEFAULT_TIMEOUT = 30
+        DEFAULT_SIMPLE_TIMEOUT = 10
+        BINARY = "gh"
+
+        class << self
+          # Execute a `gh` subcommand with timeout and structured output.
+          #
+          # @param subcommand [String] gh subcommand path (e.g. "pr")
+          # @param args [Array<String>] remaining arguments
+          # @param timeout [Integer, nil] seconds before the call times out
+          # @param runner [Proc, nil] injectable command runner for tests;
+          #   receives kwargs (args:, timeout:, env:), returns result hash
+          # @return [Hash] {success:, stdout:, stderr:, exit_code:}
+          # @raise [Ace::Git::ProviderCliMissingError] when `gh` is missing
+          # @raise [Ace::Git::ProviderUnreachableError] when the call times out
+          def execute(subcommand, args = [], timeout: nil, runner: nil)
+            timeout_seconds = timeout || Ace::Git.network_timeout || DEFAULT_TIMEOUT
+            result = run_command([BINARY, subcommand] + args, timeout_seconds, runner)
+            if result == :timeout
+              raise Ace::Git::ProviderUnreachableError,
+                "gh command timed out after #{timeout_seconds} seconds: #{([subcommand] + args).join(" ")}"
+            end
+
+            result
+          end
+
+          # Probe whether the `gh` binary is installed and runnable.
+          #
+          # @param runner [Proc, nil] injectable command runner for tests
+          # @return [Boolean]
+          def installed?(runner: nil)
+            result = execute_simple(["--version"], runner: runner)
+            result != :timeout && result[:success]
+          rescue Ace::Git::ProviderCliMissingError
+            false
+          end
+
+          # Probe whether `gh` is authenticated for the current host.
+          #
+          # @param runner [Proc, nil] injectable command runner for tests
+          # @return [Boolean]
+          def authenticated?(runner: nil)
+            result = execute_simple(["auth", "status"], runner: runner)
+            result != :timeout && result[:success]
+          rescue Ace::Git::ProviderCliMissingError
+            false
+          end
+
+          # @raise [Ace::Git::ProviderCliMissingError] when `gh` is missing
+          def check_installed!(runner: nil)
+            return true if installed?(runner: runner)
+
+            raise Ace::Git::ProviderCliMissingError,
+              "GitHub CLI (gh) is not installed or not runnable; install the GitHub CLI and retry"
+          end
+
+          # @raise [Ace::Git::ProviderAuthenticationError] when unauthenticated
+          def check_authenticated!(runner: nil)
+            return true if authenticated?(runner: runner)
+
+            raise Ace::Git::ProviderAuthenticationError,
+              "GitHub CLI (gh) is not authenticated; run: gh auth login"
+          end
+
+          # Run a full argument vector against `gh`.
+          #
+          # @return [Hash] result hash, or :timeout sentinel on timeout
+          def run_command(command, timeout_seconds, runner = nil)
+            if runner
+              call_runner(runner, command, timeout_seconds)
+            else
+              spawn_with_timeout(command, timeout_seconds)
+            end
+          end
+
+          def execute_simple(args, timeout: nil, runner: nil)
+            timeout_seconds = timeout || Ace::Git.network_timeout || DEFAULT_SIMPLE_TIMEOUT
+            run_command([BINARY] + args, timeout_seconds, runner)
+          end
+
+          def call_runner(runner, command, timeout_seconds)
+            runner.call(args: command, timeout: timeout_seconds, env: {"LC_ALL" => "C"})
+          rescue StandardError => e
+            {success: false, stdout: "", stderr: e.message, exit_code: 1}
+          end
+
+          def spawn_with_timeout(command, timeout_seconds)
+            stdout_str, stderr_str, status = Timeout.timeout(timeout_seconds) do
+              Open3.capture3({"LC_ALL" => "C"}, *command)
+            end
+
+            {
+              success: status.success?,
+              stdout: stdout_str,
+              stderr: stderr_str,
+              exit_code: status.exitstatus
+            }
+          rescue Timeout::Error
+            :timeout
+          rescue Errno::ENOENT
+            raise Ace::Git::ProviderCliMissingError,
+              "GitHub CLI (gh) is not installed or not runnable; install the GitHub CLI and retry"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/github/issue_sync.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Ace
+  module Git
+    module Github
+      # Synchronize ACE task linkage metadata to GitHub issues.
+      class IssueSync
+        class OwnershipConflict < StandardError; end
+
+        STICKY_MARKER = "<!-- ace-task:tracked -->"
+        TRACKED_LABEL = "ace:tracked"
+        TERMINAL_STATUSES = %w[done completed shipped closed cancelled skipped archived].freeze
+
+        def self.sync_task(task_id:, task_title:, task_status:, task_path:, issue_ids:, reason:, previous: nil,
+          current_issue_ids: nil)
+          current_ids = if current_issue_ids.nil?
+            Array(issue_ids).map(&:to_i).uniq
+          else
+            Array(current_issue_ids).map(&:to_i).uniq
+          end
+
+          issue_ids.each do |issue_id|
+            sync_issue(
+              issue_id: issue_id.to_i,
+              task_id: task_id,
+              task_title: task_title,
+              task_status: task_status,
+              task_path: task_path,
+              reason: reason,
+              previous: previous,
+              currently_linked: current_ids.include?(issue_id.to_i)
+            )
+          end
+
+          {success: true, synced: issue_ids.length, issues: issue_ids}
+        end
+
+        def self.sync_issue(issue_id:, task_id:, task_title:, task_status:, task_path:, reason:, previous:,
+          currently_linked:)
+          issue = fetch_issue(issue_id)
+          sticky = find_sticky_comment(issue["comments"] || [])
+
+          lines = tracked_lines(sticky&.dig("body"))
+          validate_link!(issue_id: issue_id, task_id: task_id, previous_task_id: previous&.[](:id), lines: lines) if currently_linked
+          lines = remove_previous_line(lines, previous)
+          lines = upsert_line(lines, task_id: task_id, task_title: task_title, task_path: task_path) if currently_linked
+          if lines.empty?
+            cleanup_tracking_artifacts(issue_id: issue_id, sticky: sticky, labels: issue["labels"] || [])
+            return {success: true, issue: issue_id, reason: reason}
+          end
+
+          body = render_body(lines)
+
+          if sticky
+            update_comment(issue_id: issue_id, comment: sticky, body: body)
+          else
+            create_comment(issue_id: issue_id, body: body)
+          end
+
+          ensure_label(issue_id, issue["labels"] || [])
+          if currently_linked
+            sync_lifecycle(
+              issue_id: issue_id,
+              issue_state: issue["state"],
+              task_status: task_status
+            )
+          end
+
+          {success: true, issue: issue_id, reason: reason}
+        end
+
+        def self.cleanup_tracking_artifacts(issue_id:, sticky:, labels:)
+          delete_comment(issue_id: issue_id, comment: sticky) if sticky
+          remove_label(issue_id, labels)
+        end
+
+        def self.fetch_issue(issue_id)
+          result = CliExecutor.execute("issue", ["view", issue_id.to_s, "--json", "state,comments,labels"])
+          raise "Failed to fetch issue #{issue_id}: #{result[:stderr]}" unless result[:success]
+
+          JSON.parse(result[:stdout])
+        rescue JSON::ParserError => e
+          raise "Failed to parse issue #{issue_id} response: #{e.message}"
+        end
+
+        def self.find_sticky_comment(comments)
+          comments.find { |comment| comment["body"].to_s.include?(STICKY_MARKER) }
+        end
+
+        def self.tracked_lines(body)
+          body.to_s.lines.map(&:rstrip).select { |line| line.start_with?("Tracked in ace-task: ") }
+        end
+
+        def self.remove_previous_line(lines, previous)
+          return lines unless previous.is_a?(Hash)
+
+          previous_id = previous[:id] || previous["id"]
+          return lines unless previous_id
+
+          lines.reject { |line| extract_task_id(line) == previous_id.to_s }
+        end
+
+        def self.upsert_line(lines, task_id:, task_title:, task_path:)
+          filtered = lines.reject { |line| extract_task_id(line) == task_id.to_s }
+          filtered << tracked_line(task_id: task_id, task_title: task_title, task_path: task_path)
+          filtered.uniq.sort
+        end
+
+        def self.tracked_line(task_id:, task_title:, task_path:)
+          "Tracked in ace-task: [#{task_id}](#{task_url(task_path)})"
+        end
+
+        def self.extract_task_id(line)
+          match = line.match(/\[([^\]]+)\]\(/)
+          match ? match[1] : nil
+        end
+
+        def self.render_body(lines)
+          ([STICKY_MARKER] + lines).join("\n")
+        end
+
+        def self.create_comment(issue_id:, body:)
+          CliExecutor.execute("issue", ["comment", issue_id.to_s, "--body", body]).tap do |result|
+            raise "Failed to create sticky comment for issue #{issue_id}: #{result[:stderr]}" unless result[:success]
+          end
+        end
+
+        def self.update_comment(issue_id:, comment:, body:)
+          comment_id = comment_api_id(comment)
+          CliExecutor.execute("api", [
+            "repos/{owner}/{repo}/issues/comments/#{comment_id}",
+            "--method", "PATCH",
+            "--field", "body=#{body}"
+          ]).tap do |result|
+            raise "Failed to update sticky comment for issue #{issue_id}: #{result[:stderr]}" unless result[:success]
+          end
+        end
+
+        def self.delete_comment(issue_id:, comment:)
+          comment_id = comment_api_id(comment)
+          CliExecutor.execute("api", [
+            "repos/{owner}/{repo}/issues/comments/#{comment_id}",
+            "--method", "DELETE"
+          ]).tap do |result|
+            raise "Failed to delete sticky comment for issue #{issue_id}: #{result[:stderr]}" unless result[:success]
+          end
+        end
+
+        def self.comment_api_id(comment)
+          database_id = comment["databaseId"] || comment[:databaseId]
+          return database_id.to_s if database_id.to_s.match?(/\A\d+\z/)
+
+          url = comment["url"] || comment[:url]
+          return Regexp.last_match(1) if url.to_s.match(/issuecomment-(\d+)/)
+
+          (comment["id"] || comment[:id]).to_s
+        end
+
+        def self.ensure_label(issue_id, labels)
+          return if labels.any? { |label| label["name"] == TRACKED_LABEL }
+
+          result = CliExecutor.execute("issue", ["edit", issue_id.to_s, "--add-label", TRACKED_LABEL])
+          raise "Failed to add #{TRACKED_LABEL} label to issue #{issue_id}: #{result[:stderr]}" unless result[:success]
+        end
+
+        def self.remove_label(issue_id, labels)
+          return unless labels.any? { |label| label["name"] == TRACKED_LABEL }
+
+          result = CliExecutor.execute("issue", ["edit", issue_id.to_s, "--remove-label", TRACKED_LABEL])
+          raise "Failed to remove #{TRACKED_LABEL} label from issue #{issue_id}: #{result[:stderr]}" unless result[:success]
+        end
+
+        def self.validate_link!(issue_id:, task_id:, previous_task_id: nil, lines: nil)
+          issue = fetch_issue(issue_id)
+          sticky = find_sticky_comment(issue["comments"] || [])
+          lines ||= tracked_lines(sticky&.dig("body"))
+          owners = lines.map { |line| extract_task_id(line) }.compact.uniq
+          return true if owners.empty?
+          return true if owners == [task_id.to_s]
+          return true if previous_task_id && owners == [previous_task_id.to_s]
+
+          raise OwnershipConflict, "GitHub issue ##{issue_id} is already owned by task #{owners.first}"
+        end
+
+        def self.sync_lifecycle(issue_id:, issue_state:, task_status:)
+          terminal = TERMINAL_STATUSES.include?(task_status.to_s.downcase)
+          issue_open = issue_state.to_s.upcase == "OPEN"
+
+          if terminal && issue_open
+            close_result = CliExecutor.execute("issue", ["close", issue_id.to_s])
+            raise "Failed to close issue #{issue_id}: #{close_result[:stderr]}" unless close_result[:success]
+          elsif !terminal && !issue_open
+            reopen_result = CliExecutor.execute("issue", ["reopen", issue_id.to_s])
+            raise "Failed to reopen issue #{issue_id}: #{reopen_result[:stderr]}" unless reopen_result[:success]
+          end
+        end
+
+        def self.task_url(task_path)
+          return task_path.to_s if task_path.to_s.empty?
+
+          repo_root = repo_root_path
+          relative = if repo_root && task_path.start_with?(repo_root + "/")
+            task_path.delete_prefix(repo_root + "/")
+          else
+            task_path.to_s
+          end
+
+          repo_slug = github_repo_slug
+          return relative unless repo_slug
+
+          "https://github.com/#{repo_slug}/blob/HEAD/#{relative}"
+        end
+
+        def self.repo_root_path
+          stdout, _stderr, status = Open3.capture3("git", "rev-parse", "--show-toplevel")
+          return nil unless status.success?
+
+          stdout.strip
+        rescue
+          nil
+        end
+
+        def self.github_repo_slug
+          stdout, _stderr, status = Open3.capture3("git", "remote", "get-url", "origin")
+          return nil unless status.success?
+
+          url = stdout.strip
+          return Regexp.last_match(1) if url.match(%r{github\.com[:/](.+?)(?:\.git)?$})
+
+          nil
+        rescue
+          nil
+        end
+
+        private_class_method :sync_issue, :fetch_issue, :find_sticky_comment, :tracked_lines, :remove_previous_line,
+          :upsert_line, :tracked_line, :extract_task_id, :render_body, :create_comment, :update_comment, :delete_comment,
+          :comment_api_id, :ensure_label, :remove_label, :cleanup_tracking_artifacts, :sync_lifecycle, :task_url, :repo_root_path,
+          :github_repo_slug
+      end
+
+    end
+  end
+end

data/lib/ace/git/github/pr_fetcher.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Git
+    module Github
+      # Fetch pull request data via the GitHub CLI (`gh`).
+      #
+      # Owns all `gh pr` invocation and output parsing for ACE. Failures are
+      # classified with the shared provider taxonomy; there is no fallback to
+      # any other transport.
+      module PrFetcher
+        # Error message patterns from the `gh` CLI
+        PR_NOT_FOUND_PATTERN = /not found|Could not resolve/i
+        AUTH_ERROR_PATTERN = /authentication|Unauthorized|not logged in|auth login/i
+
+        # Valid characters for PR identifiers (owner/repo#number format)
+        VALID_IDENTIFIER_PATTERN = /\A[\w\/.\-#@:]+\z/
+
+        # Fields to fetch for PR metadata
+        PR_FIELDS = %w[
+          number
+          state
+          isDraft
+          title
+          author
+          headRefName
+          baseRefName
+          url
+          isCrossRepository
+          headRepositoryOwner
+          headRefOid
+          mergeCommit
+        ].freeze
+
+        LIST_FIELDS = "number,title,state,mergedAt,author,headRefName,isDraft,baseRefName,url,headRefOid,mergeCommit"
+
+        class << self
+          # @return [Boolean] true when the `gh` binary is installed
+          def installed?(runner: nil)
+            CliExecutor.installed?(runner: runner)
+          end
+
+          # @return [Boolean] true when the `gh` CLI is authenticated
+          def authenticated?(runner: nil)
+            CliExecutor.authenticated?(runner: runner)
+          end
+
+          # Fetch PR diff content.
+          #
+          # @param identifier [String] PR identifier (number, URL, or owner/repo#number)
+          # @param timeout [Integer] Timeout in seconds
+          # @param runner [Proc, nil] injectable command runner for tests
+          # @return [Hash] Result with :success, :diff, :identifier, :source
+          def fetch_diff(identifier, timeout: Ace::Git.network_timeout, runner: nil)
+            parsed = PrIdentifier.parse(identifier)
+            raise ArgumentError, "Invalid PR identifier: #{identifier}" if parsed.nil?
+
+            validate_identifier_characters(parsed.gh_format)
+
+            result = CliExecutor.execute("pr", ["diff", parsed.gh_format], timeout: timeout, runner: runner)
+
+            if result[:success]
+              {
+                success: true,
+                diff: result[:stdout],
+                identifier: parsed.gh_format,
+                source: build_source_label(parsed)
+              }
+            else
+              handle_error(result[:stderr], parsed.gh_format)
+            end
+          end
+
+          # Fetch PR metadata (state, draft status, title, etc.).
+          #
+          # @param identifier [String] PR identifier
+          # @param timeout [Integer] Timeout in seconds
+          # @param runner [Proc, nil] injectable command runner for tests
+          # @return [Hash] Result with :success, :metadata, :identifier, :parsed
+          def fetch_metadata(identifier, timeout: Ace::Git.network_timeout, runner: nil)
+            parsed = PrIdentifier.parse(identifier)
+            raise ArgumentError, "Invalid PR identifier: #{identifier}" if parsed.nil?
+
+            validate_identifier_characters(parsed.gh_format)
+
+            result = CliExecutor.execute(
+              "pr", ["view", parsed.gh_format, "--json", PR_FIELDS.join(",")],
+              timeout: timeout, runner: runner
+            )
+
+            if result[:success]
+              metadata = JSON.parse(result[:stdout])
+              {
+                success: true,
+                metadata: metadata,
+                identifier: parsed.gh_format,
+                parsed: {number: parsed.number, repo: parsed.repo}
+              }
+            else
+              handle_error(result[:stderr], parsed.gh_format)
+            end
+          rescue JSON::ParserError => e
+            raise Ace::Git::ProviderMalformedOutputError, "Failed to parse PR metadata: #{e.message}"
+          end
+
+          # Fetch both diff and metadata.
+          #
+          # @param identifier [String] PR identifier
+          # @param timeout [Integer] Timeout in seconds
+          # @param runner [Proc, nil] injectable command runner for tests
+          # @return [Hash] Result with :success, :diff, :metadata, :identifier, :source
+          def fetch_pr(identifier, timeout: Ace::Git.network_timeout, runner: nil)
+            diff_result = fetch_diff(identifier, timeout: timeout, runner: runner)
+            return diff_result unless diff_result[:success]
+
+            metadata_result = fetch_metadata(identifier, timeout: timeout, runner: runner)
+            return metadata_result unless metadata_result[:success]
+
+            {
+              success: true,
+              diff: diff_result[:diff],
+              metadata: metadata_result[:metadata],
+              identifier: diff_result[:identifier],
+              source: diff_result[:source]
+            }
+          end
+
+          # Find PR number for the current branch.
+          #
+          # @param timeout [Integer] Timeout in seconds
+          # @param runner [Proc, nil] injectable command runner for tests
+          # @return [String, nil] PR number or nil
+          def find_pr_for_branch(timeout: Ace::Git.network_timeout, runner: nil)
+            result = CliExecutor.execute("pr", ["view", "--json", "number"], timeout: timeout, runner: runner)
+
+            return nil unless result[:success]
+
+            JSON.parse(result[:stdout])["number"]&.to_s
+          rescue JSON::ParserError
+            nil
+          end
+
+          # Fetch recently merged PRs.
+          #
+          # @param limit [Integer] Maximum number of PRs to return
+          # @param timeout [Integer] Timeout in seconds
+          # @param runner [Proc, nil] injectable command runner for tests
+          # @return [Hash] Result with :success, :prs array, or :error
+          def fetch_recently_merged(limit: Ace::Git.merged_prs_limit, timeout: Ace::Git.network_timeout, runner: nil)
+            result = CliExecutor.execute(
+              "pr", ["list", "--state", "merged", "--limit", limit.to_s, "--json", "number,title,mergedAt,author"],
+              timeout: timeout, runner: runner
+            )
+
+            list_result(result, parse_error_prefix: "Failed to parse merged PRs")
+          end
+
+          # Fetch open PRs.
+          #
+          # @param exclude_branch [String, nil] Branch name to exclude from results
+          # @param limit [Integer] Maximum number of PRs to return
+          # @param timeout [Integer] Timeout in seconds
+          # @param runner [Proc, nil] injectable command runner for tests
+          # @return [Hash] Result with :success, :prs array, or :error
+          def fetch_open_prs(exclude_branch: nil, limit: Ace::Git.open_prs_limit, timeout: Ace::Git.network_timeout, runner: nil)
+            result = CliExecutor.execute(
+              "pr", ["list", "--state", "open", "--limit", limit.to_s, "--json", "number,title,author,headRefName"],
+              timeout: timeout, runner: runner
+            )
+
+            parsed = list_result(result, parse_error_prefix: "Failed to parse open PRs")
+            return parsed unless parsed[:success] && exclude_branch
+
+            parsed.merge(prs: parsed[:prs].reject { |pr| pr["headRefName"] == exclude_branch })
+          end
+
+          # Fetch all recent PRs in a single call (open, merged, closed).
+          #
+          # @param limit [Integer] Maximum PRs to fetch
+          # @param timeout [Integer] Timeout in seconds
+          # @param runner [Proc, nil] injectable command runner for tests
+          # @return [Hash] Result with :success, :prs array, or :error
+          def fetch_all_prs(limit: 15, timeout: Ace::Git.network_timeout, runner: nil)
+            result = CliExecutor.execute(
+              "pr", ["list", "--state", "all", "--limit", limit.to_s, "--json", LIST_FIELDS],
+              timeout: timeout, runner: runner
+            )
+
+            list_result(result, parse_error_prefix: "Failed to parse PR list")
+          end
+
+          private
+
+          def list_result(result, parse_error_prefix:)
+            if result[:success]
+              begin
+                {success: true, prs: JSON.parse(result[:stdout])}
+              rescue JSON::ParserError => e
+                raise Ace::Git::ProviderMalformedOutputError, "#{parse_error_prefix}: #{e.message}"
+              end
+            else
+              {success: false, error: result[:stderr], prs: []}
+            end
+          end
+
+          def build_source_label(parsed)
+            if parsed.repo
+              "pr:#{parsed.repo}##{parsed.number}"
+            else
+              "pr:#{parsed.number}"
+            end
+          end
+
+          # Validate identifier characters to prevent shell metacharacter injection
+          def validate_identifier_characters(identifier)
+            return if identifier.nil? || identifier.empty?
+
+            unless identifier.match?(VALID_IDENTIFIER_PATTERN)
+              raise ArgumentError, "Invalid identifier characters: #{identifier}"
+            end
+          end
+
+          def handle_error(error_message, identifier)
+            error_str = error_message.to_s
+
+            if error_str.match?(PR_NOT_FOUND_PATTERN)
+              raise Ace::Git::ProviderObjectNotFoundError, "PR not found: #{identifier}"
+            elsif error_str.match?(AUTH_ERROR_PATTERN)
+              raise Ace::Git::ProviderAuthenticationError, "Not authenticated with GitHub. Run: gh auth login"
+            else
+              {
+                success: false,
+                error: "gh pr command failed: #{error_str}"
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/github/pr_identifier.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Ace
+  module Git
+    module Github
+      # Parse GitHub pull request identifiers into structured form.
+      #
+      # Supports the GitHub-specific formats:
+      # - Simple number: "123"
+      # - Qualified reference: "owner/repo#456"
+      # - GitHub URL: "https://github.com/owner/repo/pull/789"
+      module PrIdentifier
+        # Parsed PR identifier result. `gh_format` is the form accepted by
+        # `gh pr` commands.
+        ParseResult = Data.define(:number, :repo, :gh_format)
+
+        # Maximum length for PR identifier to bound regex work
+        MAX_IDENTIFIER_LENGTH = 256
+
+        def self.parse(input)
+          return nil if input.nil?
+
+          input_str = input.to_s.strip
+          return nil if input_str.empty?
+
+          if input_str.length > MAX_IDENTIFIER_LENGTH
+            raise ArgumentError, "PR identifier too long (max #{MAX_IDENTIFIER_LENGTH} characters)"
+          end
+
+          case input_str
+          when /\A(\d+)\z/
+            number = ::Regexp.last_match(1)
+            raise ArgumentError, "Invalid PR identifier format: #{input_str}" if number.to_i.zero?
+
+            canonical_number = number.to_i.to_s
+            ParseResult.new(number: canonical_number, repo: nil, gh_format: canonical_number)
+          when /\A(?<repo>[a-zA-Z0-9_\-.]+\/[a-zA-Z0-9_\-.]+)#(?<number>\d+)\z/
+            match = ::Regexp.last_match
+            ParseResult.new(number: match[:number], repo: match[:repo], gh_format: "#{match[:repo]}##{match[:number]}")
+          when %r{\Ahttps://github\.com/(?<repo>[^/]+/[^/]+)/pull/(?<number>\d+)}
+            match = ::Regexp.last_match
+            ParseResult.new(number: match[:number], repo: match[:repo], gh_format: "#{match[:repo]}##{match[:number]}")
+          else
+            raise ArgumentError, "Invalid PR identifier format: #{input_str}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/github/provider.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Git
+    module Github
+      # GitHub provider implementation of the shared provider contract.
+      #
+      # Owns GitHub terminology and translates `gh` responses into the
+      # normalized evidence types defined by the ace-git core. Every failure is
+      # classified with the shared taxonomy; nothing falls back silently.
+      class Provider < Ace::Git::Providers::Base
+        STATE_MAP = {
+          "OPEN" => :open,
+          "MERGED" => :merged,
+          "CLOSED" => :closed
+        }.freeze
+
+        # `gh` check bucket vocabulary mapped onto neutral conclusions
+        BUCKET_MAP = {
+          "pass" => :success,
+          "fail" => :failure,
+          "pending" => :pending,
+          "skipping" => :skipped
+        }.freeze
+
+        PR_FIELDS = "number,state,isDraft,title,author,headRefName,baseRefName,url,headRefOid,mergeCommit,mergedAt"
+        LIST_FIELDS = PrFetcher::LIST_FIELDS
+        REPO_FIELDS = "nameWithOwner,defaultBranchRef,url"
+        ISSUE_FIELDS = "number,title,state,author,url"
+
+        class << self
+          # Human-facing provider type name used in failure messages.
+          def display_name
+            "GitHub"
+          end
+        end
+
+        # @return [Boolean] true when the `gh` binary is installed
+        def available?
+          PrFetcher.installed?(runner: runner)
+        end
+
+        # @raise [Ace::Git::ProviderCliMissingError] when `gh` is missing
+        def check_available!
+          CliExecutor.check_installed!(runner: runner)
+        end
+
+        # @return [Boolean] true when `gh` is authenticated
+        def authenticated?
+          PrFetcher.authenticated?(runner: runner)
+        end
+
+        # @raise [Ace::Git::ProviderAuthenticationError] when unauthenticated
+        def check_authenticated!
+          CliExecutor.check_authenticated!(runner: runner)
+        end
+
+        # @return [ProviderPullRequest] normalized pull request evidence
+        # @raise [ProviderObjectNotFoundError] when the PR does not exist
+        # @raise [ProviderMalformedOutputError] when `gh` returns invalid JSON
+        # @raise [ProviderUnreachableError] when the endpoint is unreachable
+        def pull_request(number:)
+          data = gh_json(["pr", "view", number.to_s, "--json", PR_FIELDS])
+          normalize_pr(data, server.name)
+        end
+
+        # @return [ProviderPullRequest, nil] evidence for the branch's PR
+        def pull_request_for_branch(branch:)
+          candidates = recent_pull_requests(limit: 30)
+          branch_prs = candidates.select { |pr| pr.head_ref == branch }
+          return nil if branch_prs.empty?
+
+          branch_prs.min_by { |pr| STATE_ORDER.fetch(pr.state, 3) }
+        end
+
+        # @return [String] unified diff text for the pull request
+        def pull_request_diff(number:)
+          result = PrFetcher.fetch_diff(number.to_s, timeout: timeout, runner: runner)
+          result[:diff]
+        end
+
+        # @return [Array<ProviderPullRequest>] recent PRs, newest first
+        def recent_pull_requests(limit:)
+          result = PrFetcher.fetch_all_prs(limit: limit, timeout: timeout, runner: runner)
+          result[:prs]
+            .map { |pr| normalize_pr(pr, server.name) }
+            .sort_by { |pr| -pr.number.to_i }
+        end
+
+        # @return [ProviderIssue] normalized issue evidence
+        def issue(number:)
+          output = gh_json(["issue", "view", number.to_s, "--json", ISSUE_FIELDS])
+          normalize_issue(output)
+        end
+
+        # @return [Array<ProviderCheck>] normalized check evidence for a ref
+        def checks(ref:)
+          output = gh_json(["pr", "checks", ref.to_s, "--json", "name,state,bucket"])
+          output.map do |check|
+            bucket = check["bucket"].to_s.downcase
+            Ace::Git::ProviderCheck.new(
+              server_name: server.name,
+              name: check["name"].to_s,
+              state: check["state"].to_s.downcase.to_sym,
+              conclusion: BUCKET_MAP.fetch(bucket, bucket.empty? ? nil : bucket.to_sym),
+              url: nil
+            )
+          end
+        end
+
+        # @return [ProviderRepository] normalized repository evidence
+        def repository
+          output = gh_json(["repo", "view", "--json", REPO_FIELDS])
+          Ace::Git::ProviderRepository.new(
+            server_name: server.name,
+            full_name: output["nameWithOwner"],
+            default_branch: output.dig("defaultBranchRef", "name"),
+            url: output["url"]
+          )
+        end
+
+        private
+
+        STATE_ORDER = {open: 0, merged: 1, closed: 2}.freeze
+
+        # Run a `gh` command expecting JSON output; classify all failures.
+        def gh_json(args)
+          result = CliExecutor.execute(args.first, args[1..] || [], timeout: timeout, runner: runner)
+          unless result[:success]
+            classify_failure(result[:stderr], context: args.join(" "))
+          end
+
+          begin
+            JSON.parse(result[:stdout])
+          rescue JSON::ParserError => e
+            raise Ace::Git::ProviderMalformedOutputError,
+              "Malformed JSON from gh (#{args.join(" ")}): #{e.message}"
+          end
+        end
+
+        def normalize_pr(data, server_name)
+          Ace::Git::ProviderPullRequest.new(
+            server_name: server_name,
+            number: data["number"],
+            title: data["title"],
+            state: STATE_MAP.fetch(data["state"].to_s.upcase, data["state"].to_s.downcase.to_sym),
+            head_ref: data["headRefName"],
+            base_ref: data["baseRefName"],
+            head_sha: data["headRefOid"],
+            author: normalize_author(data["author"]),
+            url: data["url"],
+            draft: data["isDraft"],
+            merged_at: merged_at_of(data)
+          )
+        end
+
+        def merged_at_of(data)
+          data["mergedAt"]
+        end
+
+        def normalize_author(author)
+          return author["login"] if author.is_a?(Hash)
+
+          author
+        end
+
+        def normalize_issue(data)
+          Ace::Git::ProviderIssue.new(
+            server_name: server.name,
+            number: data["number"],
+            title: data["title"],
+            state: data["state"].to_s.upcase == "OPEN" ? :open : :closed,
+            author: normalize_author(data["author"]),
+            url: data["url"],
+            labels: nil
+          )
+        end
+
+        def classify_failure(stderr, context:)
+          message = stderr.to_s
+          if message.match?(PrFetcher::PR_NOT_FOUND_PATTERN)
+            raise Ace::Git::ProviderObjectNotFoundError, "Object not found: #{context}: #{message}"
+          elsif message.match?(PrFetcher::AUTH_ERROR_PATTERN)
+            raise Ace::Git::ProviderAuthenticationError, "Not authenticated with GitHub: #{message}"
+          else
+            raise Ace::Git::ProviderUnreachableError, "GitHub request failed (#{context}): #{message}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/github/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Ace
+  module Git
+    module Github
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/ace/git/github.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "ace/git"
+
+require_relative "github/version"
+require_relative "github/cli_executor"
+require_relative "github/pr_identifier"
+require_relative "github/pr_fetcher"
+require_relative "github/issue_sync"
+require_relative "github/provider"
+
+module Ace
+  module Git
+    # GitHub provider package for the forge-neutral ace-git core.
+    #
+    # Owns all GitHub-specific behavior: `gh` CLI invocation, output parsing,
+    # authentication verification, and GitHub terminology. Implements the
+    # shared provider contract exposed by the core and registers itself in the
+    # core provider registry.
+    module Github
+      PROVIDER_TYPE = :github
+    end
+  end
+end
+
+Ace::Git::Providers.register(Ace::Git::Github::PROVIDER_TYPE, Ace::Git::Github::Provider)

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: ace-git-github
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Michal Czyz
+bindir: exe
+cert_chain: []
+date: 2026-09-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ace-git
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.24'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.24'
+description: 'Implements the shared ace-git provider contract for GitHub: all `gh`
+  CLI invocation, output parsing, authentication verification, and classified failure
+  handling live behind one normalized evidence boundary.'
+email:
+- mc@cs3b.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/ace/git/github.rb
+- lib/ace/git/github/cli_executor.rb
+- lib/ace/git/github/issue_sync.rb
+- lib/ace/git/github/pr_fetcher.rb
+- lib/ace/git/github/pr_identifier.rb
+- lib/ace/git/github/provider.rb
+- lib/ace/git/github/version.rb
+homepage: https://forgejo.tail6c0887.ts.net/cs3b/ace
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://forgejo.tail6c0887.ts.net/cs3b/ace
+  source_code_uri: https://forgejo.tail6c0887.ts.net/cs3b/ace/src/branch/main/ace-git-github
+  changelog_uri: https://forgejo.tail6c0887.ts.net/cs3b/ace/src/branch/main/ace-git-github/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: GitHub provider for the forge-neutral ace-git core
+test_files: []