ace-git-github 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 582b5aa0bbe2430f79b22897711fdebfa1e6b1b9f95bc18bed86bf65c1e9827f
-  data.tar.gz: a494f8d740771123e5d82ea5ab2b10872c38f0434f6e7311a892715025904402
+  metadata.gz: 998ca300a7c6610ff632dac2a6051fe84daa68a4e8daac13181e10fd86223798
+  data.tar.gz: 8cc1cf649582eed6600fc53bb0d70ac8bdc73226c02072400f8cf6c5de450d4a
 SHA512:
-  metadata.gz: 554e3438466bb91e22fe03addcdaed22a3678aeab24c00a874a75c36b00fe6814ad06e6b7613075c38864145d4dd29466692ac739f88b1e58998f3feacd19d17
-  data.tar.gz: 98b94104aac8d09ca7a319b2c3ef201fb4a44bac5b90e02facbfae5eb477bd74bdb33cfcb64b2cdc6c6d86dfad00fd5783b4567a159bf2952be22ebffe0f5ac0
+  metadata.gz: 5f8d10b98f72f43767031476e9a980658462834374ec26af019a7d7b753c5bb3d5e78257b2a6ee7261856069c72db234993541223b4f14c52ac84e83ba9a28f0
+  data.tar.gz: d1399752f36d349a36fa0bbb21406d62c820806ad78ff62eefe3ec0423b0bfc28f75964ac389f45e99b7ed599c148b8c638152ecf0bef8e51d77b596ea5a0ec8

data/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-28
+
+### Added
+- PR lifecycle mutations with atomic provider-side expected-head enforcement:
+  exact-match lookup (`find_open_pull_requests`), idempotent draft-create
+  reconciliation, expected-head merge via the gh match-head-commit flag,
+  head-verified update/ready.
+- Cross-repository PR provenance: head repository URL resolved from gh
+  evidence and returned in normalized PR evidence.
+- Classified lifecycle failures (conflicting matches, expected-head conflict,
+  unknown create outcome with reconciliation identity).
+
+### Changed
+- `gh pr view`/`list` JSON field sets extended with head-repository fields.
+
+
+### Added
+- PR lifecycle mutations with atomic provider-side expected-head enforcement:
+  exact-match lookup (`find_open_pull_requests`), idempotent draft-create
+  reconciliation, expected-head merge via the gh match-head-commit flag,
+  head-verified update/ready.
+- Cross-repository PR provenance: head repository URL resolved from gh
+  evidence and returned in normalized PR evidence.
+- Classified lifecycle failures (conflicting matches, expected-head conflict,
+  unknown create outcome with reconciliation identity).
+
+### Changed
+- `gh pr view`/`list` JSON field sets extended with head-repository fields.
+
+
+## [0.1.2] - 2026-09-26
+
+### Added
+- `IssueSync.available?` probe: true when the `gh` CLI is installed and authenticated, letting callers treat GitHub sync as best-effort.
+
 ## [0.1.1] - 2026-09-24
 
 ### Fixed

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

@@ -14,6 +14,12 @@ module Ace
         TRACKED_LABEL = "ace:tracked"
         TERMINAL_STATUSES = %w[done completed shipped closed cancelled skipped archived].freeze
 
+        # True when GitHub sync can run: the gh CLI is installed and authenticated.
+        # GitHub sync is best-effort; callers skip it silently when this is false.
+        def self.available?
+          CliExecutor.authenticated?
+        end
+
         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?

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

@@ -53,13 +53,15 @@ module Ace
           # @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)
+          def fetch_diff(identifier, timeout: Ace::Git.network_timeout, runner: nil, repo: 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.cli_target_args], timeout: timeout, runner: runner)
+            args = ["diff", *parsed.cli_target_args]
+            args += ["--repo", repo] if repo
+            result = CliExecutor.execute("pr", args, timeout: timeout, runner: runner)
 
             if result[:success]
               {
@@ -182,9 +184,11 @@ module Ace
           # @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)
+          def fetch_all_prs(limit: 15, timeout: Ace::Git.network_timeout, runner: nil, repo: nil)
+            args = ["list", "--state", "all", "--limit", limit.to_s, "--json", LIST_FIELDS]
+            args += ["--repo", repo] if repo
             result = CliExecutor.execute(
-              "pr", ["list", "--state", "all", "--limit", limit.to_s, "--json", LIST_FIELDS],
+              "pr", args,
               timeout: timeout, runner: runner
             )
 

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "uri"
 
 module Ace
   module Git
@@ -25,11 +26,14 @@ module Ace
           "skipping" => :skipped
         }.freeze
 
-        PR_FIELDS = "number,state,isDraft,title,author,headRefName,baseRefName,url,headRefOid,mergeCommit,mergedAt"
+        PR_FIELDS = "number,state,isDraft,title,author,headRefName,baseRefName,url,headRefOid,mergeCommit,mergedAt,headRepositoryOwner,headRepository"
         LIST_FIELDS = PrFetcher::LIST_FIELDS
         REPO_FIELDS = "nameWithOwner,defaultBranchRef,url"
         ISSUE_FIELDS = "number,title,state,author,url"
 
+        # Fields needed to match pull requests by exact base/head identity.
+        LIFECYCLE_LIST_FIELDS = "number,title,state,isDraft,author,headRefName,baseRefName,url,headRefOid,headRepositoryOwner,headRepository"
+
         class << self
           # Human-facing provider type name used in failure messages.
           def display_name
@@ -66,6 +70,13 @@ module Ace
           normalize_pr(data, server.name)
         end
 
+        # @return [String] HOST/OWNER/REPO for the resolved server; appended
+        #   to every data/mutation command so a `--server` selection can never
+        #   be silently retargeted to the checkout's repository.
+        def repo_target
+          @repo_target ||= Ace::Git::Atoms::ServerUrl.normalize(server.url)
+        end
+
         # @return [ProviderPullRequest, nil] evidence for the branch's PR
         def pull_request_for_branch(branch:)
           candidates = recent_pull_requests(limit: 30)
@@ -77,13 +88,13 @@ module Ace
 
         # @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 = PrFetcher.fetch_diff(number.to_s, timeout: timeout, runner: runner, repo: repo_target)
           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 = PrFetcher.fetch_all_prs(limit: limit, timeout: timeout, runner: runner, repo: repo_target)
           result[:prs]
             .map { |pr| normalize_pr(pr, server.name) }
             .sort_by { |pr| -pr.number.to_i }
@@ -112,7 +123,8 @@ module Ace
 
         # @return [ProviderRepository] normalized repository evidence
         def repository
-          output = gh_json(["repo", "view", "--json", REPO_FIELDS])
+          # `gh repo view` rejects `--repo`; the repository is positional.
+          output = gh_json(["repo", "view", repo_target, "--json", REPO_FIELDS], bind_repo: false)
           Ace::Git::ProviderRepository.new(
             server_name: server.name,
             full_name: output["nameWithOwner"],
@@ -121,13 +133,156 @@ module Ace
           )
         end
 
+        # ---- PR lifecycle mutations ----
+
+        # @return [Array<ProviderPullRequest>] open PRs matching the exact
+        #   base/head identity (head repository URL/ref plus base URL/ref)
+        def find_open_pull_requests(head_repository_url:, head_ref:, base_repository_url:, base_ref:)
+          require_base_on_server!(base_repository_url)
+          data = gh_json(["pr", "list", "--state", "open", "--limit", "200", "--json", LIFECYCLE_LIST_FIELDS])
+          data.filter_map { |entry| normalize_pr(entry, server.name) }
+            .select do |pr|
+              pr.head_ref == head_ref &&
+                pr.base_ref == base_ref &&
+                Ace::Git::Atoms::ServerUrl.match?(pr.head_repository_url, head_repository_url)
+            end
+        end
+
+        # Create a PR, reconciling to an exact open match first; proves the
+        # created/reconciled head against `expected_head`.
+        #
+        # @return [ProviderMutationReceipt] idempotency :created/:existing
+        def create_pull_request(head_ref:, head_repository_url:, base_ref:, expected_head:, title:, body: nil, draft: true)
+          matches = find_open_pull_requests(
+            head_repository_url: head_repository_url, head_ref: head_ref,
+            base_repository_url: server.url, base_ref: base_ref
+          )
+          if matches.size > 1
+            raise Ace::Git::ProviderConflictingMatchesError,
+              "Multiple open pull requests match #{head_repository_url}@#{head_ref} -> " \
+              "#{base_ref}: #{matches.map(&:number).join(", ")}; resolve the conflict first"
+          end
+          if matches.size == 1
+            existing = matches.first
+            return receipt(:create, verify_head!(existing, expected_head), :existing)
+          end
+
+          args = ["pr", "create", "--head", gh_head_arg(head_ref, head_repository_url), "--base", base_ref, "--title", title]
+          args += ["--body", body] if body
+          args << "--draft" if draft
+
+          result = send_mutation(args, ambiguous: true, identity: identity_text(head_repository_url, head_ref, base_ref))
+          number = result[:stdout].to_s.strip[%r{/pull/(\d+)\z}, 1]
+          unless number
+            raise Ace::Git::ProviderMalformedOutputError,
+              "gh pr create did not return a pull request URL: #{result[:stdout].to_s.strip}"
+          end
+
+          created = verify_head!(pull_request(number: number), expected_head)
+          receipt(:create, created, :created)
+        end
+
+        # @return [ProviderMutationReceipt] operation :update
+        def update_pull_request(number:, expected_head:, title: nil, body: nil)
+          verify_head!(pull_request(number: number), expected_head)
+          args = ["pr", "edit", number.to_s]
+          args += ["--title", title] if title
+          args += ["--body", body] if body
+          send_mutation(args, ambiguous: false)
+          receipt(:update, pull_request(number: number), nil)
+        end
+
+        # @return [ProviderMutationReceipt] operation :ready
+        def ready_pull_request(number:, expected_head:)
+          verify_head!(pull_request(number: number), expected_head)
+          send_mutation(["pr", "ready", number.to_s], ambiguous: false)
+          receipt(:ready, pull_request(number: number), nil)
+        end
+
+        # Merge with atomic provider-side expected-head enforcement via
+        # `gh pr merge --match-head-commit`.
+        #
+        # @return [ProviderMutationReceipt] operation :merge
+        def merge_pull_request(number:, expected_head:, method:)
+          unless %i[squash merge rebase].include?(method)
+            raise ArgumentError, "Invalid merge method #{method.inspect}"
+          end
+
+          send_mutation(
+            ["pr", "merge", number.to_s, "--#{method}", "--match-head-commit", expected_head],
+            ambiguous: false
+          )
+          receipt(:merge, pull_request(number: number), nil)
+        end
+
         private
 
         STATE_ORDER = {open: 0, merged: 1, closed: 2}.freeze
 
+        # Send one mutating `gh` command. When `ambiguous` is true (create),
+        # any transport-level failure is reported as an unknown outcome: the
+        # request may have mutated the forge, so callers must reconcile by
+        # exact identity instead of retrying blindly.
+        def send_mutation(args, ambiguous:, identity: nil)
+          result = CliExecutor.execute(args.first, (args[1..] || []) + ["--repo", repo_target], timeout: timeout, runner: runner)
+          return result if result[:success]
+
+          classify_failure(result[:stderr], context: args.join(" "))
+          result
+        rescue Ace::Git::ProviderUnreachableError => e
+          raise e unless ambiguous
+
+          raise Ace::Git::ProviderUnknownOutcomeError,
+            "PR create outcome unknown after transport failure (#{e.message}); " \
+            "reconcile by exact identity before repeating: #{identity}"
+        end
+
+        # Exact base/head identity text for reconciliation contexts.
+        def identity_text(head_repository_url, head_ref, base_ref)
+          "#{head_repository_url}@#{head_ref} -> #{server.url}@#{base_ref}"
+        end
+
+        # Refuse when the live head differs from the caller's expected head
+        # (shared guard from Providers::Base).
+        def verify_head!(pr, expected_head)
+          verify_expected_head!(pr, expected_head)
+        end
+
+        # `gh` head selector: "user:branch" for fork sources, plain ref for
+        # the base repository. The owner comes from the declared URL only.
+        def gh_head_arg(head_ref, head_repository_url)
+          return head_ref if head_repository_url.nil? ||
+            Ace::Git::Atoms::ServerUrl.match?(head_repository_url, server.url)
+
+          path = Ace::Git::Atoms::ServerUrl.normalize(head_repository_url).split("/", 2)[1]
+          owner = path.to_s.split("/").first
+          raise ArgumentError, "Cannot derive fork owner from #{head_repository_url}" if owner.nil? || owner.empty?
+
+          "#{owner}:#{head_ref}"
+        end
+
+        def require_base_on_server!(base_repository_url)
+          return if Ace::Git::Atoms::ServerUrl.match?(base_repository_url, server.url)
+
+          raise Ace::Git::ProviderUnsupportedCapabilityError,
+            "GitHub provider operates on the resolved server repository (#{server.url}); " \
+            "refusing base repository #{base_repository_url}"
+        end
+
+        def receipt(operation, pull_request, idempotency)
+          Ace::Git::ProviderMutationReceipt.new(
+            server_name: server.name, operation: operation,
+            pull_request: pull_request, idempotency: idempotency
+          )
+        end
+
         # 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)
+        # Every command is bound to the resolved server repository via
+        # `--repo`, except commands that take the repository positionally.
+        def gh_json(args, bind_repo: true)
+          argv = args[1..] || []
+          argv += ["--repo", repo_target] if bind_repo
+          result = CliExecutor.execute(args.first, argv, timeout: timeout, runner: runner)
           unless result[:success]
             classify_failure(result[:stderr], context: args.join(" "))
           end
@@ -152,10 +307,31 @@ module Ace
             author: normalize_author(data["author"]),
             url: data["url"],
             draft: data["isDraft"],
-            merged_at: merged_at_of(data)
+            merged_at: merged_at_of(data),
+            head_repository_url: head_repository_url_of(data),
+            base_repository_url: server.url,
+            merge_commit_sha: data.dig("mergeCommit", "oid")
           )
         end
 
+        # Source repository URL for the PR head: the fork's owner/name against
+        # the server host for cross-repository PRs, the configured repository
+        # otherwise. Never inferred beyond what `gh` reported.
+        def head_repository_url_of(data)
+          owner = data.dig("headRepositoryOwner", "login")
+          name = data.dig("headRepository", "name")
+          return server.url if owner.nil? || name.nil?
+
+          "#{server_host_root}/#{owner}/#{name}"
+        end
+
+        def server_host_root
+          @server_host_root ||= begin
+            uri = URI.parse(server.url.to_s)
+            "#{uri.scheme || "https"}://#{uri.host}#{":#{uri.port}" if uri.port && uri.port != uri.default_port}"
+          end
+        end
+
         def merged_at_of(data)
           data["mergedAt"]
         end
@@ -184,6 +360,9 @@ module Ace
             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}"
+          elsif message.match?(/match[- ]head[- ]commit|head commit/i)
+            raise Ace::Git::ProviderExpectedHeadConflictError,
+              "GitHub refused the merge: pull request head does not match --match-head-commit (#{context}): #{message}"
           else
             raise Ace::Git::ProviderUnreachableError, "GitHub request failed (#{context}): #{message}"
           end

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

@@ -3,7 +3,7 @@
 module Ace
   module Git
     module Github
-      VERSION = "0.1.1"
+      VERSION = "0.2.0"
     end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-git-github
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-24 00:00:00.000000000 Z
+date: 2026-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-git