ace-git-worktree 0.23.0 → 0.24.1

data/lib/ace/git/worktree/molecules/cleanup_pr_resolver.rb

@@ -2,117 +2,226 @@
 
 require "json"
 require "open3"
-require "ace/git/github"
-require "ace/git/github/pr_fetcher"
+require "ace/git"
 
 module Ace
   module Git
     module Worktree
       module Molecules
-        # Resolves PR evidence for candidate branches to prove safe squash-merge cleanup.
+        # Resolves PR evidence for candidate branches through the registered
+        # forge provider to prove safe merge cleanup.
+        #
+        # Only confirmed remote merge evidence (:merged) can prove removal;
+        # object states (:no_pr, :open, :closed_unmerged) and transport
+        # failures (:offline, :authentication_error, :malformed) always
+        # retain the candidate. Merge proof additionally requires the
+        # evidence's provenance (server, repository, branch, base) to agree
+        # with the resolved selection; incomplete or conflicting provenance
+        # retains. Local ancestry proof is handled by the reporter before
+        # this resolver is consulted.
         class CleanupPrResolver
-          def initialize(target:, target_sha:, offline: false)
+          # @param target [String] base ref the PR must have targeted
+          # @param target_sha [String] commit SHA of the target
+          # @param offline [Boolean] skip provider evidence entirely
+          # @param server_name [String, nil] explicit server selection
+          # @param use_default [Boolean] resolve the configured default server
+          # @param remote_name [String, nil] remote used for fallback resolution
+          # @param timeout [Integer, nil] provider timeout
+          # @param runner [Proc, nil] injectable provider runner (tests)
+          def initialize(target:, target_sha:, offline: false, server_name: nil, use_default: false,
+            remote_name: nil, timeout: nil, runner: nil)
             @target = target
             @target_sha = target_sha
             @offline = offline
-            
-            # Cache gh availability to avoid repeated checks
-            @gh_available = Ace::Git::Github::PrFetcher.installed? &&
-                            Ace::Git::Github::PrFetcher.authenticated?
+            @selection = {server_name: server_name, use_default: use_default, remote_name: remote_name}
+            @timeout = timeout
+            @runner = runner
           end
 
-          # Classify a candidate branch with GitHub PR evidence.
+          # @return [Ace::Git::ResolvedServer, nil] the server resolved for
+          #   provider evidence; nil when unresolvable (local proof only)
+          def resolved_server
+            resolve_provider
+            @resolved_server
+          end
+
+          # Classify a candidate branch with provider PR evidence.
           #
-          # @param branch [String] The branch name (e.g. "feature")
-          # @param candidate_sha [String] The commit SHA of the candidate
-          # @return [Hash] Proof classification result
+          # @param branch [String] the branch name (e.g. "feature")
+          # @param candidate_sha [String] the commit SHA of the candidate
+          # @return [Hash] proof classification; :status is one of
+          #   Ace::Git::CLEANUP_PROOF_STATUSES
           def classify(branch, candidate_sha)
-            return offline_result unless @gh_available && !@offline
-
-            prs = fetch_merged_prs_for_branch(branch)
-            return unproven_result if prs.nil? || prs.empty?
-
-            # Find a PR that targets the configured base and is actually reachable
-            valid_pr = prs.find do |pr|
-              pr["baseRefName"] == @target && 
-              pr["state"] == "MERGED" && 
-              pr["mergeCommit"] && 
-              pr["mergeCommit"]["oid"] &&
-              ancestor?(pr["mergeCommit"]["oid"], @target_sha)
-            end
+            return unproven_result(:no_pr, "provider_disabled") if @offline
+
+            evidence = fetch_merged_evidence(branch)
+            return failure_result(evidence) if evidence.is_a?(Hash) # transport failure marker
 
-            return ambiguous_result(prs) if prs.length > 1 && !valid_pr
-            return unproven_result unless valid_pr
+            return unproven_result(:no_pr) unless evidence
+            return unproven_result(:open) if evidence.state == :open
+            return unproven_result(:closed_unmerged) if evidence.state == :closed
+            return unproven_result(:merged, "state_unavailable") unless evidence.state == :merged
 
-            merge_commit_sha = valid_pr["mergeCommit"]["oid"]
-            pr_head_sha = valid_pr["headRefOid"]
+            problem = provenance_problem(evidence, branch)
+            return unproven_result(:merged, problem) if problem
+            return unproven_result(:merged, "merge_commit_unavailable") unless evidence.merge_commit_sha
+            return unproven_result(:merged, "merge_commit_unreachable") unless ancestor?(evidence.merge_commit_sha, @target_sha)
+
+            merge_commit_sha = evidence.merge_commit_sha
+            pr_head_sha = evidence.head_sha
 
             if candidate_sha == pr_head_sha
-              {
-                proof: "exact_merged_pr_head",
-                pr: valid_pr["number"],
-                candidate_head: candidate_sha,
-                merged_head: pr_head_sha,
-                merge_commit: merge_commit_sha,
-                target_reachable: true,
-                path_type_mode_match: true,
-                provider_status: "available",
-                action: "remove"
-              }
+              proof_result(evidence, "exact_merged_pr_head", candidate_sha, pr_head_sha, merge_commit_sha)
             elsif patch_equivalent?(candidate_sha, merge_commit_sha)
-              {
-                proof: "stable_patch_equivalence",
-                pr: valid_pr["number"],
-                candidate_head: candidate_sha,
-                merged_head: pr_head_sha,
-                merge_commit: merge_commit_sha,
-                target_reachable: true,
-                path_type_mode_match: true,
-                provider_status: "available",
-                action: "remove"
-              }
+              proof_result(evidence, "stable_patch_equivalence", candidate_sha, pr_head_sha, merge_commit_sha)
             else
               {
-                proof: "none",
-                pr: valid_pr["number"],
+                status: :merged,
+                proof: nil,
+                pr: evidence.number,
+                pr_url: evidence.url,
                 candidate_head: candidate_sha,
                 merged_head: pr_head_sha,
                 merge_commit: merge_commit_sha,
                 target_reachable: true,
-                path_type_mode_match: false,
                 provider_status: "available",
                 action: "retain",
                 retention_reason: "patch_mismatch"
               }
             end
-          rescue Ace::Git::ProviderCliMissingError, Ace::Git::ProviderAuthenticationError, Ace::Git::TimeoutError
-            # Provider failure degradation
-            offline_result("unavailable")
           end
 
           private
 
-          def fetch_merged_prs_for_branch(branch)
-            # Use `gh pr list --head <branch> --state merged` to find the exact PR
-            cmd = [
-              "gh", "pr", "list", "--state", "merged", "--head", branch,
-              "--json", "number,state,headRefOid,mergeCommit,baseRefName"
-            ]
-            
-            # Using Open3 directly to avoid circular dependencies if we don't want to augment ace-git too heavily for just this
-            # but we can rely on LC_ALL=C for safety.
-            env = {"LC_ALL" => "C"}
-            out, err, status = Open3.capture3(env, *cmd)
-            
-            return nil unless status.success?
-            
-            JSON.parse(out)
-          rescue JSON::ParserError, Errno::ENOENT
+          # Fetch the merged PR evidence for a branch, or a failure marker
+          # hash {:failure_status => ...} on classified transport failures.
+          def fetch_merged_evidence(branch)
+            provider = resolve_provider
+            return {failure_status: :offline} unless provider
+
+            provider.pull_request_for_branch(branch: branch)
+          rescue Ace::Git::ProviderAuthenticationError
+            {failure_status: :authentication_error}
+          rescue Ace::Git::ProviderMalformedOutputError
+            {failure_status: :malformed}
+          rescue Ace::Git::Error
+            {failure_status: :offline}
+          end
+
+          # Resolve the provider lazily, once per resolver. Unresolvable
+          # server selection (no config, ambiguous remote, missing provider)
+          # means no provider evidence is available.
+          def resolve_provider
+            return @provider if defined?(@provider)
+
+            @provider = begin
+              server = Ace::Git::ServerRegistry.resolve_for(**@selection)
+              @resolved_server = server
+              Ace::Git::Providers.for(server, timeout: @timeout, runner: @runner)
+            rescue Ace::Git::Error
+              @resolved_server = nil
+              nil
+            end
+          end
+
+          # Merge proof may only remove a candidate whose evidence provably
+          # belongs to the resolved server and the candidate's branch/base.
+          # PR and branch identities are not globally unique: incomplete
+          # provenance cannot be verified and conflicting provenance means
+          # the evidence was routed from another repository — both retain.
+          # @return [String, nil] retention reason, or nil when provenance agrees
+          def provenance_problem(evidence, branch)
+            server = resolved_server
+            unless server && evidence.server_name && evidence.base_repository_url &&
+                evidence.head_ref && evidence.base_ref
+              return "provenance_incomplete"
+            end
+
+            return "provenance_conflict" unless evidence.server_name == server.name
+            return "provenance_conflict" unless Ace::Git::Atoms::ServerUrl.match?(evidence.base_repository_url, server.url)
+            return "provenance_conflict" unless evidence.head_ref == branch
+            return "provenance_conflict" unless evidence.base_ref == target_branch
+
             nil
           end
 
+          # The branch the PR must have targeted. Targets arrive as bare
+          # branch names, remote-tracking refs ("origin/main",
+          # "refs/remotes/origin/main"), or local refs ("refs/heads/main");
+          # all of those forms name the same branch the PR base reports. A
+          # path segment only counts as a remote prefix when it names a
+          # configured git remote, so slashed branch names stay strict.
+          def target_branch
+            ref = @target.to_s
+            ref = ref.sub(%r{\Arefs/remotes/([^/]+)/}) do
+              git_remotes.include?(Regexp.last_match(1)) ? "" : Regexp.last_match(0)
+            end
+            ref = ref.sub(%r{\Arefs/heads/}, "")
+            if ref.include?("/")
+              prefix, rest = ref.split("/", 2)
+              ref = rest if git_remotes.include?(prefix)
+            end
+            ref
+          end
+
+          def git_remotes
+            out, _status = Open3.capture2("git", "remote")
+            out.to_s.lines.map(&:strip).reject(&:empty?)
+          rescue StandardError
+            []
+          end
+
+          def proof_result(evidence, proof, candidate_sha, pr_head_sha, merge_commit_sha)
+            {
+              status: :merged,
+              proof: proof,
+              pr: evidence.number,
+              pr_url: evidence.url,
+              candidate_head: candidate_sha,
+              merged_head: pr_head_sha,
+              merge_commit: merge_commit_sha,
+              target_reachable: true,
+              provider_status: "available",
+              action: "remove",
+              retention_reason: nil
+            }
+          end
+
+          def unproven_result(status, reason = "ancestry_unproven")
+            {
+              status: status,
+              proof: nil,
+              pr: nil,
+              pr_url: nil,
+              candidate_head: nil,
+              merged_head: nil,
+              merge_commit: nil,
+              target_reachable: "unknown",
+              provider_status: "available",
+              action: "retain",
+              retention_reason: reason
+            }
+          end
+
+          def failure_result(marker)
+            status = marker[:failure_status]
+            {
+              status: status,
+              proof: nil,
+              pr: nil,
+              pr_url: nil,
+              candidate_head: nil,
+              merged_head: nil,
+              merge_commit: nil,
+              target_reachable: "unknown",
+              provider_status: status.to_s,
+              action: "retain",
+              retention_reason: "provider_evidence_unavailable"
+            }
+          end
+
           def ancestor?(candidate, target)
-            out, status = Open3.capture2("git", "merge-base", "--is-ancestor", candidate, target)
+            _out, status = Open3.capture2("git", "merge-base", "--is-ancestor", candidate, target)
             status.success?
           end
 
@@ -122,7 +231,7 @@ module Ace
             base, status = Open3.capture2("git", "merge-base", candidate_sha, @target_sha)
             return false unless status.success?
             base = base.strip
-            
+
             # Candidate inventory: path, type, mode changes
             cand_inv = tree_diff_inventory(base, candidate_sha)
             return false unless cand_inv
@@ -136,9 +245,8 @@ module Ace
           end
 
           def tree_diff_inventory(tree_a, tree_b)
-            # git diff-tree -r --name-status or raw mode
-            # using raw mode to get exact mode and type
-            # :100644 100644 e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 0000000000000000000000000000000000000000 M  file
+            # git diff-tree -r raw mode carries exact mode and type information
+            # :100644 100644 e69de29... 000000... M  file
             out, status = Open3.capture2("git", "diff-tree", "-r", "--no-commit-id", tree_a, tree_b)
             return nil unless status.success?
 
@@ -146,66 +254,19 @@ module Ace
             out.each_line do |line|
               # Format: :src_mode dst_mode src_sha dst_sha status\tpath
               parts = line.strip.split("\t", 2)
+              next if parts.length < 2
+
               meta = parts[0].split(" ")
               path = parts[1]
-              
-              dst_mode = meta[1]
-              dst_sha = meta[3]
-              status_char = meta[4]
-              
+
               inventory[path] = {
-                mode: dst_mode,
-                sha: dst_sha,
-                status: status_char[0] # handle R100 etc by taking first char
+                mode: meta[1],
+                sha: meta[3],
+                status: meta[4][0] # handle R100 etc by taking first char
               }
             end
-            
-            inventory
-          end
-
-          def offline_result(status = "offline")
-            {
-              proof: "none",
-              pr: nil,
-              candidate_head: nil,
-              merged_head: nil,
-              merge_commit: nil,
-              target_reachable: "unknown",
-              path_type_mode_match: "unknown",
-              provider_status: status,
-              action: "retain",
-              retention_reason: "ancestry_unproven"
-            }
-          end
-
-          def unproven_result
-            {
-              proof: "none",
-              pr: nil,
-              candidate_head: nil,
-              merged_head: nil,
-              merge_commit: nil,
-              target_reachable: "unknown",
-              path_type_mode_match: "unknown",
-              provider_status: "available",
-              action: "retain",
-              retention_reason: "ancestry_unproven"
-            }
-          end
 
-          def ambiguous_result(prs)
-            {
-              proof: "none",
-              pr: nil,
-              candidate_head: nil,
-              merged_head: nil,
-              merge_commit: nil,
-              target_reachable: "unknown",
-              path_type_mode_match: "unknown",
-              provider_status: "ambiguous",
-              action: "retain",
-              retention_reason: "ambiguous_prs"
-            }
+            inventory
           end
         end
       end

data/lib/ace/git/worktree/molecules/cleanup_reporter.rb

@@ -19,12 +19,22 @@ module Ace
           SCHEMA_VERSION = "1.0"
 
           # @param target [String] Target ref (e.g. "main", "origin/main")
-          # @param remote [String] Remote name (e.g. "origin")
+          # @param remote [String] Remote name (e.g. "origin"); identifies the
+          #   local Git remote, never the forge
           # @param offline [Boolean] Skip remote refresh
-          def initialize(target:, remote: "origin", offline: false)
+          # @param server_name [String, nil] explicit forge server selection
+          # @param use_default [Boolean] resolve the configured default server
+          # @param remote_name [String, nil] remote used for fallback resolution
+          # @param timeout [Integer, nil] provider timeout
+          # @param runner [Proc, nil] injectable provider runner (tests)
+          def initialize(target:, remote: "origin", offline: false, server_name: nil, use_default: false,
+            remote_name: nil, timeout: nil, runner: nil)
             @target = target
             @remote = remote
             @offline = offline
+            @selection = {server_name: server_name, use_default: use_default, remote_name: remote_name}
+            @timeout = timeout
+            @runner = runner
           end
 
           # Build complete cleanup report.
@@ -46,7 +56,11 @@ module Ace
             local_refs = inventory_local_refs
             remote_refs = inventory_remote_refs
 
-            pr_resolver = CleanupPrResolver.new(target: @target, target_sha: target_sha, offline: @offline)
+            pr_resolver = CleanupPrResolver.new(
+              target: @target, target_sha: target_sha, offline: @offline,
+              server_name: @selection[:server_name], use_default: @selection[:use_default],
+              remote_name: @selection[:remote_name], timeout: @timeout, runner: @runner
+            )
 
             # Classify each item
             classify_worktrees(worktrees, target_sha, pr_resolver)
@@ -56,8 +70,12 @@ module Ace
             # Build ordered action plan
             actions = build_action_plan(worktrees, local_refs, remote_refs)
 
-            # Compute canonical digest
-            plan_digest = compute_plan_digest(worktrees, local_refs, remote_refs, actions, target_sha)
+            # The resolved server identity binds provider proof to the plan;
+            # changed server configuration invalidates approval.
+            server = server_identity_hash(pr_resolver)
+
+            # Compute canonical digest (server/PR/head evidence included)
+            plan_digest = compute_plan_digest(worktrees, local_refs, remote_refs, actions, target_sha, server)
 
             {
               success: true,
@@ -65,6 +83,7 @@ module Ace
               repository: common_dir,
               target: {ref: @target, sha: target_sha},
               remote: {name: @remote, sha: remote_sha},
+              server: server,
               refresh: @offline ? {status: "offline"} : (refresh_result || {status: "skipped"}),
               worktrees: worktrees,
               local_refs: local_refs,
@@ -286,7 +305,7 @@ module Ace
                 wt[:ancestry] = "ancestor"
                 wt[:action] = "remove"
               else
-                # Try GitHub PR evidence
+                # Try provider PR evidence
                 proof_result = pr_resolver.classify(wt[:branch], wt[:sha])
                 if proof_result[:action] == "remove"
                   wt[:ancestry] = proof_result[:proof]
@@ -311,7 +330,7 @@ module Ace
                 ref[:ancestry] = "ancestor"
                 ref[:action] = "remove"
               else
-                # Try GitHub PR evidence
+                # Try provider PR evidence
                 # Only local refs and remote-tracking refs have meaningful branch names for PR lookup
                 branch_name = kind == "remote" ? ref[:short_name] : ref[:name]
                 proof_result = pr_resolver.classify(branch_name, ref[:sha])
@@ -378,17 +397,36 @@ module Ace
 
           # --- Canonical digest ---
 
-          def compute_plan_digest(worktrees, local_refs, remote_refs, actions, target_sha)
+          # Resolved server identity for the report/digest; nil when no
+          # provider was resolvable (local ancestry proof only).
+          def server_identity_hash(pr_resolver)
+            server = pr_resolver.resolved_server
+            return nil unless server
+
+            {name: server.name, provider: server.provider.to_s, url: server.url}
+          end
+
+          def compute_plan_digest(worktrees, local_refs, remote_refs, actions, target_sha, server)
             canonical = {
+              schema_version: SCHEMA_VERSION,
               target_sha: target_sha,
-              worktrees: worktrees.sort_by { |wt| wt[:path] }.map { |wt| [wt[:path], wt[:sha], wt[:action]] },
-              local_refs: local_refs.sort_by { |r| r[:name] }.map { |r| [r[:name], r[:sha], r[:action]] },
-              remote_refs: remote_refs.sort_by { |r| r[:name] }.map { |r| [r[:name], r[:sha], r[:action]] },
+              server: server,
+              worktrees: worktrees.sort_by { |wt| wt[:path] }.map { |wt| proof_tuple(wt[:path], wt) },
+              local_refs: local_refs.sort_by { |r| r[:name] }.map { |r| proof_tuple(r[:name], r) },
+              remote_refs: remote_refs.sort_by { |r| r[:name] }.map { |r| proof_tuple(r[:name], r) },
               actions: actions.map { |a| [a[:type], a[:target], a[:sha]] }
             }
 
             Digest::SHA256.hexdigest(JSON.generate(canonical))
           end
+
+          # One canonical entry per item: identity, decision, and the full
+          # provider proof that justified it.
+          def proof_tuple(identity, item)
+            proof = item[:pr_proof]
+            [identity, item[:sha], item[:action], item[:ancestry],
+             proof ? [proof[:status], proof[:pr], proof[:merged_head], proof[:merge_commit]] : nil]
+          end
         end
       end
     end

data/lib/ace/git/worktree/molecules/pull_request_checkout_preparer.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "ace/git"
+
+module Ace
+  module Git
+    module Worktree
+      module Molecules
+        # Fetches the exact source repository/ref declared by PR evidence and
+        # proves the fetched commit before any worktree is created.
+        #
+        # Canonical-repository and fork source URLs are equally valid: the
+        # fetch goes through a matching local remote when one exists, and by
+        # explicit URL otherwise (no remote ref is created for URL fetches).
+        class PullRequestCheckoutPreparer
+          DEFAULT_TIMEOUT = 60
+
+          # @param timeout [Integer] git command timeout in seconds
+          def initialize(timeout: DEFAULT_TIMEOUT)
+            @timeout = timeout
+          end
+
+          # Fetch the declared source ref and verify its SHA against the
+          # evidence head.
+          #
+          # @param evidence [Ace::Git::ProviderPullRequest] normalized PR evidence
+          # @return [Hash] {success:, local_ref:, sha:, remote_tracking:, error:}
+          #   `local_ref` is the exact verified commit SHA (immutable), safe
+          #   for `git worktree add` even if later fetches move FETCH_HEAD.
+          def prepare(evidence)
+            head_url = evidence.head_repository_url
+            head_ref = evidence.head_ref
+            return error_result("PR evidence is missing the source repository URL") if head_url.nil? || head_url.empty?
+            return error_result("PR evidence is missing the source branch") if head_ref.nil? || head_ref.empty?
+            return error_result("PR evidence is missing the exact head SHA") unless evidence.head_sha
+
+            local_remote = matching_local_remote(head_url)
+            fetch_source = local_remote || head_url
+            fetch_desc = "#{head_url}@#{head_ref}"
+
+            fetch_result = Ace::Git::Worktree::Atoms::GitCommand.execute(
+              "fetch", fetch_source, head_ref, timeout: @timeout
+            )
+            return error_result("Failed to fetch #{fetch_desc}: #{fetch_result[:error]}") unless fetch_result[:success]
+
+            sha = resolve_fetch_head
+            return error_result("Cannot resolve fetched commit for #{fetch_desc}") unless sha
+
+            if sha != evidence.head_sha
+              return error_result(
+                "Fetched head #{sha} does not match PR evidence head #{evidence.head_sha} " \
+                "(#{head_url}@#{head_ref}); the PR head moved since the evidence was captured"
+              )
+            end
+
+            {
+              success: true,
+              # The immutable verified SHA, not FETCH_HEAD: a later fetch must
+              # never be able to change what the worktree is created from.
+              local_ref: sha,
+              sha: sha,
+              remote_tracking: local_remote ? "#{local_remote}/#{head_ref}" : nil,
+              error: nil
+            }
+          end
+
+          private
+
+          # Find a configured local git remote whose URL matches the evidence
+          # source repository; nil means fetch by explicit URL instead.
+          def matching_local_remote(head_url)
+            result = Ace::Git::Worktree::Atoms::GitCommand.execute("remote", "-v", timeout: 5)
+            return nil unless result[:success]
+
+            remotes = {}
+            result[:output].to_s.each_line do |line|
+              name, url, = line.strip.split(/\s+/)
+              remotes[name] = url if url
+            end
+
+            remotes.find do |_name, url|
+              Ace::Git::Atoms::ServerUrl.match?(url, head_url)
+            end&.first
+          end
+
+          def resolve_fetch_head
+            result = Ace::Git::Worktree::Atoms::GitCommand.execute(
+              "rev-parse", "--verify", "FETCH_HEAD^{commit}", timeout: 10
+            )
+            result[:success] ? result[:output].to_s.strip : nil
+          end
+
+          def error_result(message)
+            {success: false, local_ref: nil, sha: nil, remote_tracking: nil, error: message}
+          end
+        end
+      end
+    end
+  end
+end