ace-git-worktree 0.23.0 → 0.24.0

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

@@ -103,20 +103,27 @@ module Ace
             end
           end
 
-          # Create a worktree for a Pull Request
+          # Create a worktree for a Pull Request from an already-verified
+          # source ref (see PullRequestCheckoutPreparer).
           #
-          # @param pr_data [Hash] PR data hash from PrFetcher
+          # @param pr_data [Hash] normalized PR data: :number, :title,
+          #   :head_branch, :base_branch
           # @param config [WorktreeConfig] Worktree configuration
           # @param git_root [String, nil] Git repository root (auto-detected if nil)
+          # @param source_ref [String, nil] verified local ref (e.g. FETCH_HEAD)
+          #   the PR head was proven against; required
+          # @param remote_tracking [String, nil] "remote/branch" tracking ref
+          #   when the source is reachable via a configured local remote
           # @return [Hash] Result with :success, :worktree_path, :branch, :error
           #
           # @example
           #   pr_data = { number: 26, title: "Add feature", head_branch: "feature/auth", base_branch: "main" }
-          #   result = creator.create_for_pr(pr_data, config)
-          #   # => { success: true, worktree_path: "/project/.ace-wt/pr-26", branch: "pr-26", tracking: "origin/feature/auth" }
-          def create_for_pr(pr_data, config, git_root: nil)
+          #   result = creator.create_for_pr(pr_data, config, source_ref: "FETCH_HEAD")
+          #   # => { success: true, worktree_path: ".../ace-pr-26", branch: "pr-26-add-feature", tracking: nil }
+          def create_for_pr(pr_data, config, git_root: nil, source_ref: nil, remote_tracking: nil)
             return error_result("PR data is required") unless pr_data
             return error_result("Configuration is required") unless config
+            return error_result("Verified source ref is required for PR checkout") if source_ref.nil? || source_ref.empty?
 
             begin
               # Determine git repository root
@@ -125,7 +132,6 @@ module Ace
 
               # Get PR-specific configuration (fallback to defaults)
               pr_config = config.pr_config || {}
-              remote_name = pr_config[:remote_name] || "origin"
               directory_format = pr_config[:directory_format] || "ace-pr-{number}"
               branch_format = pr_config[:branch_format] || "pr-{number}-{slug}"
 
@@ -140,27 +146,28 @@ module Ace
               validation = validate_worktree_path(worktree_path, git_root)
               return error_result(validation[:error]) unless validation[:valid]
 
-              # Fetch the remote branch
-              head_branch = pr_data[:head_branch]
-              fetch_result = fetch_remote_branch(remote_name, head_branch, git_root)
-              return error_result(fetch_result[:error]) unless fetch_result[:success]
-
-              # Create worktree with remote tracking
-              result = create_worktree_with_tracking(
-                worktree_path,
-                local_branch_name,
-                "#{remote_name}/#{head_branch}",
-                git_root,
-                configure_push: config.configure_push_for_mismatch?
-              )
+              # Create the worktree from the proven source ref
+              result = create_worktree(worktree_path, local_branch_name, git_root, start_point: source_ref)
               return result unless result[:success]
 
+              # Configure push behavior when tracking a differently-named branch
+              if remote_tracking && local_branch_name != extract_remote_branch_name(remote_tracking)
+                configure_push_for_worktree(worktree_path, local_branch_name, remote_tracking)
+              end
+
+              # Bind the reported tracking ref as the branch's real upstream so
+              # `@{upstream}` resolves; advisory when the tracking ref is not a
+              # local remote-tracking ref (fork URL fetches).
+              upstream = remote_tracking ? set_and_verify_upstream(local_branch_name, remote_tracking) : nil
+
               # Success - return worktree information
               {
                 success: true,
                 worktree_path: worktree_path,
                 branch: local_branch_name,
-                tracking: "#{remote_name}/#{head_branch}",
+                tracking: remote_tracking,
+                upstream: upstream,
+                warnings: remote_tracking && !upstream ? ["Could not set upstream to #{remote_tracking}"] : nil,
                 directory_name: directory_name,
                 pr_number: pr_data[:number],
                 pr_title: pr_data[:title],
@@ -764,6 +771,31 @@ module Ace
             }
           end
 
+          # Set and verify upstream for a PR worktree branch.
+          #
+          # @param local_branch [String] the worktree's local branch
+          # @param remote_tracking [String] e.g. "origin/feature"
+          # @return [String, nil] the verified upstream, or nil when it could
+          #   not be established (advisory)
+          def set_and_verify_upstream(local_branch, remote_tracking)
+            require_relative "../atoms/git_command"
+
+            exists = Atoms::GitCommand.execute(
+              "show-ref", "--verify", "--quiet", "refs/remotes/#{remote_tracking}", timeout: 5
+            )
+            return nil unless exists[:success]
+
+            result = Atoms::GitCommand.execute(
+              "branch", "--set-upstream-to=#{remote_tracking}", local_branch, timeout: 10
+            )
+            return nil unless result[:success]
+
+            verify = Atoms::GitCommand.execute(
+              "rev-parse", "--abbrev-ref", "#{local_branch}@{upstream}", timeout: 5
+            )
+            verify[:success] && verify[:output].to_s.strip == remote_tracking ? remote_tracking : nil
+          end
+
           # Format PR name using template
           #
           # @param template [String] Template string with {variables}

data/lib/ace/git/worktree/organisms/task_worktree_orchestrator.rb

@@ -31,7 +31,6 @@ module Ace
             @task_committer = Molecules::TaskCommitter.new(project_root: project_root)
             @task_pusher = Molecules::TaskPusher.new
             @worktree_creator = Molecules::WorktreeCreator.new
-            @pr_creator = Molecules::PrCreator.new
             @parent_task_resolver = Molecules::ParentTaskResolver.new(project_root: project_root)
           end
 
@@ -861,14 +860,14 @@ module Ace
             result[:success] && result[:output]&.include?(branch)
           end
 
-          # Create draft PR for task
+          # Create draft PR for task through the forge-neutral provider contract.
           #
-          # Creates a draft PR targeting the source branch (start_point) from which
-          # the worktree branch was created.
+          # The exact pushed head SHA is proven to the provider (expected_head);
+          # PR identity is never inferred from branch names alone.
           #
           # @param task_data [Hash] Task data hash from ace-task
           # @param worktree_result [Hash] Worktree creation result with :branch, :start_point
-          # @param options [Hash] Options (may include :source for base branch override)
+          # @param options [Hash] Options (may include :source, :server, :default_server)
           # @return [Hash] Result with :success, :pr_number, :pr_url, :existing, :error
           def create_pr_for_task(task_data, worktree_result, options)
             branch = worktree_result[:branch]
@@ -880,14 +879,49 @@ module Ace
             # Resolve base branch - handle SHA vs branch name
             base = resolve_pr_base(start_point, options)
 
-            # Create draft PR
-            @pr_creator.create_draft(
+            push_remote = options[:push_remote] || @config.push_remote || "origin"
+            creator = Molecules::PullRequestCreator.new(
+              server_name: options[:server],
+              use_default: options[:default_server] == true,
+              remote_name: push_remote
+            )
+            creator.create_draft(
               branch: branch,
               base: base,
-              title: title
+              title: title,
+              expected_head: pushed_branch_sha(branch, worktree_result[:worktree_path]),
+              head_repository_url: remote_url(push_remote)
             )
           end
 
+          # Exact SHA of the pushed worktree branch, proven locally before any
+          # provider call.
+          #
+          # @param branch [String] worktree branch name
+          # @param worktree_path [String, nil] worktree directory to resolve in
+          # @return [String] branch head SHA
+          def pushed_branch_sha(branch, worktree_path)
+            result = if worktree_path && Dir.exist?(worktree_path)
+              Dir.chdir(worktree_path) do
+                Atoms::GitCommand.execute("rev-parse", "--verify", "#{branch}^{commit}", timeout: 10)
+              end
+            else
+              Atoms::GitCommand.execute("rev-parse", "--verify", "#{branch}^{commit}", timeout: 10)
+            end
+            return result[:output].to_s.strip if result[:success]
+
+            raise Ace::Git::Error, "Cannot prove pushed head SHA for branch '#{branch}': #{result[:error]}"
+          end
+
+          # Local URL of a configured git remote (no network).
+          #
+          # @param remote [String] remote name
+          # @return [String, nil] remote URL
+          def remote_url(remote)
+            result = Atoms::GitCommand.execute("remote", "get-url", remote, timeout: 10)
+            result[:success] ? result[:output].to_s.strip : nil
+          end
+
           # Resolve PR base branch from start_point
           #
           # If start_point is a commit SHA (not a branch name), creates a branch
@@ -948,7 +982,7 @@ module Ace
           # Add started_at timestamp to task file IN WORKTREE
           #
           # This creates an initial commit in the worktree branch, enabling PR creation
-          # (GitHub requires at least one commit difference between branches for a PR).
+          # (Forges require at least one commit difference between branches for a PR).
           #
           # @param task_data [Hash] Task data hash from ace-task
           # @param worktree_result [Hash] Worktree creation result with :worktree_path

data/lib/ace/git/worktree/organisms/worktree_manager.rb

@@ -121,25 +121,31 @@ module Ace
             end
           end
 
-          # Create a worktree for a Pull Request
+          # Create a worktree for a Pull Request from normalized evidence.
           #
-          # @param pr_number [Integer] PR number
-          # @param pr_data [Hash] PR data from Ace::Git::Github::PrFetcher
+          # @param evidence [Ace::Git::ProviderPullRequest] normalized PR
+          #   evidence with exact source/base provenance
+          # @param checkout [Hash, nil] verified checkout from
+          #   PullRequestCheckoutPreparer ({local_ref:, remote_tracking:});
+          #   nil is valid only for dry runs
           # @param options [Hash] Options for creation
           # @return [Hash] Creation result
           #
           # @example
           #   manager = WorktreeManager.new
-          #   pr_data = { number: 26, title: "Add feature", head_branch: "feature/auth" }
-          #   result = manager.create_pr(26, pr_data)
-          def create_pr(pr_number, pr_data, options = {})
-            return error_result("PR number is required") if pr_number.nil?
-            return error_result("PR data is required") if pr_data.nil?
+          #   checkout = preparer.prepare(evidence)
+          #   result = manager.create_pr(evidence, checkout)
+          def create_pr(evidence, checkout, options = {})
+            return error_result("PR evidence is required") if evidence.nil?
+
+            pr_number = evidence.number
+            pr_data = normalized_pr_data(evidence)
+            local_branch = preview_pr_branch(pr_data)
 
             # Check if worktree already exists for this PR's branch
-            head_branch = pr_data[:head_branch]
             existing = @worktree_lister.find_by_branch("pr-#{pr_number}") ||
-              @worktree_lister.find_by_branch(head_branch)
+              @worktree_lister.find_by_branch(local_branch) ||
+              @worktree_lister.find_by_branch(evidence.head_ref)
 
             if existing && !options[:force]
               return error_result("Worktree already exists at: #{existing.path}")
@@ -150,11 +156,15 @@ module Ace
               return dry_run_pr_creation(pr_number, pr_data, options)
             end
 
+            return error_result("Verified checkout is required for PR worktree creation") unless checkout
+
             # Create the worktree
             result = @worktree_creator.create_for_pr(
               pr_data,
               @config,
-              git_root: @project_root
+              git_root: @project_root,
+              source_ref: checkout[:local_ref],
+              remote_tracking: checkout[:remote_tracking]
             )
 
             if result[:success]
@@ -554,6 +564,40 @@ module Ace
 
           # Create error result
           #
+          # Convert normalized PR evidence into the internal pr_data naming
+          # format used by configuration templates.
+          #
+          # @param evidence [Ace::Git::ProviderPullRequest]
+          # @return [Hash] {number:, title:, head_branch:, base_branch:}
+          def normalized_pr_data(evidence)
+            {
+              number: evidence.number,
+              title: evidence.title,
+              head_branch: evidence.head_ref,
+              base_branch: evidence.base_ref
+            }
+          end
+
+          # Preview the configured local branch name for a PR worktree.
+          #
+          # @param pr_data [Hash] normalized PR data
+          # @return [String] formatted branch name
+          def preview_pr_branch(pr_data)
+            pr_config = @config.pr_config || {}
+            branch_format = pr_config[:branch_format] || "pr-{number}-{slug}"
+            require_relative "../atoms/slug_generator"
+
+            result = branch_format.dup
+            result.gsub!("{number}", pr_data[:number].to_s)
+            if pr_data[:title]
+              slug = Atoms::SlugGenerator.from_title(pr_data[:title])
+              result.gsub!("{slug}", slug)
+              result.gsub!("{title_slug}", slug)
+            end
+            result.gsub!("{base_branch}", pr_data[:base_branch].to_s) if pr_data[:base_branch]
+            result
+          end
+
           # Dry run PR worktree creation
           #
           # @param pr_number [Integer] PR number

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

@@ -3,7 +3,7 @@
 module Ace
   module Git
     module Worktree
-      VERSION = "0.23.0"
+      VERSION = "0.24.0"
     end
   end
 end

data/lib/ace/git/worktree.rb

@@ -190,7 +190,9 @@ module Ace
 
       require_relative "worktree/molecules/config_loader"
       require_relative "worktree/molecules/task_fetcher"
-      require_relative "worktree/molecules/pr_creator"
+      require_relative "worktree/molecules/pull_request_creator"
+      require_relative "worktree/molecules/pull_request_evidence_resolver"
+      require_relative "worktree/molecules/pull_request_checkout_preparer"
       require_relative "worktree/molecules/task_committer"
       require_relative "worktree/molecules/task_pusher"
       require_relative "worktree/molecules/task_status_updater"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-git-worktree
 version: !ruby/object:Gem::Version
-  version: 0.23.0
+  version: 0.24.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-27 00:00:00.000000000 Z
+date: 2026-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
@@ -65,20 +65,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.24'
-- !ruby/object:Gem::Dependency
-  name: ace-git-github
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.1.1
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.1.1
 - !ruby/object:Gem::Dependency
   name: ace-task
   requirement: !ruby/object:Gem::Requirement
@@ -205,7 +191,9 @@ files:
 - lib/ace/git/worktree/molecules/current_task_linker.rb
 - lib/ace/git/worktree/molecules/hook_executor.rb
 - lib/ace/git/worktree/molecules/parent_task_resolver.rb
-- lib/ace/git/worktree/molecules/pr_creator.rb
+- lib/ace/git/worktree/molecules/pull_request_checkout_preparer.rb
+- lib/ace/git/worktree/molecules/pull_request_creator.rb
+- lib/ace/git/worktree/molecules/pull_request_evidence_resolver.rb
 - lib/ace/git/worktree/molecules/task_committer.rb
 - lib/ace/git/worktree/molecules/task_fetcher.rb
 - lib/ace/git/worktree/molecules/task_pusher.rb

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

@@ -1,253 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-require "open3"
-
-module Ace
-  module Git
-    module Worktree
-      module Molecules
-        # PR creator molecule
-        #
-        # Creates draft pull requests on GitHub using the gh CLI.
-        # Provides a simple interface for creating PRs with graceful degradation
-        # when gh CLI is unavailable or not authenticated.
-        #
-        # @example Create a draft PR
-        #   creator = PrCreator.new
-        #   result = creator.create_draft(
-        #     branch: "125-upstream-setup",
-        #     base: "main",
-        #     title: "125 - upstream-setup-and-pr-creation"
-        #   )
-        #   result[:pr_number] # => 456
-        #   result[:pr_url] # => "https://github.com/owner/repo/pull/456"
-        #
-        # @example Handle unavailable gh CLI
-        #   creator = PrCreator.new
-        #   unless creator.gh_available?
-        #     puts "gh CLI not available"
-        #   end
-        class PrCreator
-          # Error raised when gh CLI is not available
-          class GhNotAvailableError < StandardError; end
-
-          # Error raised when gh CLI is not authenticated
-          class GhNotAuthenticatedError < StandardError; end
-
-          # Error raised on network/timeout issues
-          class NetworkError < StandardError; end
-
-          # Error raised when PR already exists
-          class PrAlreadyExistsError < StandardError; end
-
-          # Initialize a new PrCreator
-          #
-          # @param timeout [Integer] Timeout in seconds (default: 30)
-          def initialize(timeout: 30)
-            @timeout = timeout
-          end
-
-          # Create a draft pull request
-          #
-          # @param branch [String] Head branch for the PR
-          # @param base [String] Base branch to merge into
-          # @param title [String] PR title
-          # @param body [String, nil] PR body/description
-          # @return [Hash] Result hash with :success, :pr_number, :pr_url, :error
-          #
-          # @example
-          #   result = creator.create_draft(branch: "feature", base: "main", title: "Add feature")
-          #   result[:success] # => true
-          #   result[:pr_number] # => 123
-          #   result[:pr_url] # => "https://github.com/owner/repo/pull/123"
-          def create_draft(branch:, base:, title:, body: nil)
-            # Check gh availability and authentication
-            unless gh_available?
-              return error_result("gh CLI is not installed")
-            end
-
-            unless gh_authenticated?
-              return error_result("gh CLI is not authenticated. Run: gh auth login")
-            end
-
-            # Check if PR already exists for this branch
-            existing_pr = find_existing_pr(branch: branch)
-            if existing_pr
-              return {
-                success: true,
-                pr_number: existing_pr[:number],
-                pr_url: existing_pr[:url],
-                existing: true,
-                message: "PR already exists for branch"
-              }
-            end
-
-            # Build gh command
-            cmd = ["gh", "pr", "create", "--draft", "--head", branch, "--base", base, "--title", title]
-            cmd += ["--body", body || title]
-
-            # Execute command
-            stdout, stderr, status = execute_with_timeout(cmd, @timeout)
-
-            if status.success?
-              # Parse PR URL from output
-              pr_url = stdout.strip
-              pr_number = extract_pr_number(pr_url)
-
-              {
-                success: true,
-                pr_number: pr_number,
-                pr_url: pr_url,
-                existing: false,
-                error: nil
-              }
-            else
-              handle_creation_error(stderr)
-            end
-          rescue => e
-            error_result("Unexpected error: #{e.message}")
-          end
-
-          # Check if gh CLI is available (cached)
-          #
-          # @return [Boolean] true if gh is installed and accessible
-          def gh_available?
-            return @gh_available unless @gh_available.nil?
-
-            @gh_available = system("which gh > /dev/null 2>&1")
-          end
-
-          # Check if gh CLI is authenticated (cached)
-          #
-          # @return [Boolean] true if gh is authenticated
-          def gh_authenticated?
-            return @gh_authenticated unless @gh_authenticated.nil?
-
-            _, _stderr, status = Open3.capture3("gh", "auth", "status")
-            @gh_authenticated = status.success?
-          rescue
-            @gh_authenticated = false
-          end
-
-          # Find an existing PR for a branch
-          #
-          # @param branch [String] Branch name to search for
-          # @return [Hash, nil] PR info hash or nil if not found
-          #
-          # @example
-          #   pr = creator.find_existing_pr(branch: "feature-branch")
-          #   pr[:number] # => 123
-          #   pr[:url] # => "https://github.com/owner/repo/pull/123"
-          def find_existing_pr(branch:)
-            return nil unless gh_available?
-
-            # Search for open PRs with this head branch
-            cmd = [
-              "gh", "pr", "list",
-              "--head", branch,
-              "--state", "open",
-              "--json", "number,url",
-              "--limit", "1"
-            ]
-
-            stdout, _stderr, status = execute_with_timeout(cmd, @timeout)
-            return nil unless status.success?
-
-            prs = JSON.parse(stdout)
-            return nil if prs.empty?
-
-            pr = prs.first
-            {
-              number: pr["number"],
-              url: pr["url"]
-            }
-          rescue JSON::ParserError
-            nil
-          rescue
-            nil
-          end
-
-          # Get helpful error message when gh CLI is unavailable
-          #
-          # @return [String] User-friendly error message with installation guidance
-          def gh_not_available_message
-            <<~MESSAGE
-              gh CLI is required for PR creation but is not installed.
-
-              Install gh CLI:
-              - macOS: brew install gh
-              - Linux: See https://github.com/cli/cli#installation
-              - Windows: See https://github.com/cli/cli#installation
-
-              After installation, authenticate with: gh auth login
-            MESSAGE
-          end
-
-          private
-
-          # Execute command with timeout
-          #
-          # @param cmd [Array<String>] Command and arguments
-          # @param timeout [Integer] Timeout in seconds
-          # @return [Array<String, String, Process::Status>] stdout, stderr, status
-          def execute_with_timeout(cmd, timeout)
-            require "timeout"
-
-            Timeout.timeout(timeout) do
-              Open3.capture3(*cmd)
-            end
-          rescue Timeout::Error
-            raise NetworkError, "Request timed out after #{timeout} seconds"
-          end
-
-          # Extract PR number from URL
-          #
-          # @param url [String] PR URL
-          # @return [Integer, nil] PR number or nil if not parseable
-          def extract_pr_number(url)
-            return nil unless url
-
-            match = url.match(%r{/pull/(\d+)})
-            match ? match[1].to_i : nil
-          end
-
-          # Handle PR creation error
-          #
-          # @param stderr [String] Error output from gh
-          # @return [Hash] Error result hash
-          def handle_creation_error(stderr)
-            error_msg = stderr.downcase
-
-            if error_msg.include?("already exists") || error_msg.include?("pull request already exists")
-              error_result("A PR already exists for this branch")
-            elsif error_msg.include?("authentication") || error_msg.include?("not logged in")
-              error_result("GitHub CLI not authenticated. Run: gh auth login")
-            elsif error_msg.include?("network") || error_msg.include?("connection")
-              error_result("Network error. Check your connection and try again.")
-            elsif error_msg.include?("repository not found") || error_msg.include?("not a git repository")
-              error_result("Not in a git repository or repository not found on GitHub")
-            elsif error_msg.include?("branch") && error_msg.include?("not found")
-              error_result("Branch not found on remote. Push the branch first.")
-            else
-              error_result("GitHub CLI error: #{stderr.strip}")
-            end
-          end
-
-          # Create an error result hash
-          #
-          # @param message [String] Error message
-          # @return [Hash] Error result
-          def error_result(message)
-            {
-              success: false,
-              pr_number: nil,
-              pr_url: nil,
-              error: message
-            }
-          end
-        end
-      end
-    end
-  end
-end