ace-git-worktree 0.19.0

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

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require_relative "../atoms/task_id_extractor"
+require_relative "../atoms/git_command"
+require_relative "task_fetcher"
+
+module Ace
+  module Git
+    module Worktree
+      module Molecules
+        # Parent task resolver molecule
+        #
+        # Determines the target branch for a task's PR by resolving the parent task's
+        # worktree branch. This enables subtasks to target their orchestrator branch
+        # instead of defaulting to main.
+        #
+        # @example Resolve target branch for a subtask
+        #   resolver = ParentTaskResolver.new
+        #   target = resolver.resolve_target_branch(subtask_data)
+        #   target # => "202-rename-support-gems" or "main"
+        class ParentTaskResolver
+          # Default fallback target branch when no parent is found
+          DEFAULT_TARGET = "main"
+
+          # Regex pattern for extracting task number from full task ID
+          # Pattern: v.0.9.0+task.202.01 -> captures "202.01"
+          TASK_ID_PATTERN = /task\.(\d+(?:\.\d+)?)\z/
+
+          # SHA pattern for detecting detached HEAD state
+          # Git returns 7-40 hex characters for SHAs (7 for short, 40 for full)
+          SHA_PATTERN = /\A[0-9a-f]{7,40}\z/i
+
+          # Initialize a new ParentTaskResolver
+          #
+          # @param project_root [String] Project root directory
+          # @param task_fetcher [TaskFetcher] Optional TaskFetcher instance (for testing)
+          def initialize(project_root: Dir.pwd, task_fetcher: nil)
+            @project_root = project_root
+            @task_fetcher = task_fetcher || TaskFetcher.new
+          end
+
+          # Resolve target branch for a task
+          #
+          # @param task_data [Hash] Task data hash from ace-task
+          # @return [String] Parent's worktree branch or DEFAULT_TARGET
+          #
+          # @example Subtask with parent
+          #   resolve_target_branch(subtask_data) # => "202-orchestrator-branch"
+          #
+          # @example Orchestrator task (no parent)
+          #   resolve_target_branch(orchestrator_data) # => "main"
+          def resolve_target_branch(task_data)
+            return DEFAULT_TARGET unless task_data
+
+            # Extract parent task ID from task ID
+            parent_id = extract_parent_id(task_data[:id])
+            unless parent_id
+              # Non-subtask: use current branch (e.g., feature branch) instead of defaulting to main
+              return current_branch_fallback || DEFAULT_TARGET
+            end
+
+            # Load parent task data
+            parent_task = load_parent_task(parent_id)
+            return DEFAULT_TARGET unless parent_task
+
+            # Extract parent's worktree branch
+            extract_parent_branch(parent_task)
+          rescue
+            # Silently fall back to default - debugging info available via --verbose flag on CLI
+            DEFAULT_TARGET
+          end
+
+          # Load parent task data
+          #
+          # @param parent_id [String] Parent task ID (e.g., "202")
+          # @return [Hash, nil] Parent task data or nil
+          def load_parent_task(parent_id)
+            return nil unless parent_id
+
+            @task_fetcher.fetch(parent_id)
+          end
+
+          # Extract parent's worktree branch from task data
+          #
+          # Implements a 3-level fallback priority chain for determining the target branch:
+          #
+          # Priority 1: Parent worktree branch
+          #   - If parent task has worktree metadata with a branch, use that branch
+          #   - This enables subtasks to target their orchestrator's feature branch
+          #
+          # Priority 2: Current branch fallback
+          #   - If parent has no worktree metadata, use the current branch
+          #   - Skipped if in detached HEAD state (SHA detected)
+          #   - Allows creating subtask worktrees from the parent's context
+          #
+          # Priority 3: DEFAULT_TARGET ("main")
+          #   - Final fallback when no branch context is available
+          #   - Ensures a valid target branch is always returned
+          #
+          # @param parent_data [Hash] Parent task data hash
+          # @return [String] Parent's worktree branch, current branch, or DEFAULT_TARGET
+          #
+          # @example Parent with worktree metadata
+          #   extract_parent_branch({ worktree: { branch: "202-feature" } })
+          #   # => "202-feature"
+          #
+          # @example Parent without worktree (uses current branch)
+          #   # When current branch is "develop"
+          #   extract_parent_branch({ id: "task.202" })
+          #   # => "develop"
+          #
+          # @example Detached HEAD state (falls back to main)
+          #   # When in detached HEAD state
+          #   extract_parent_branch({ id: "task.202" })
+          #   # => "main"
+          def extract_parent_branch(parent_data)
+            # Try parent worktree branch first
+            if parent_data
+              worktree_data = parent_data[:worktree] || parent_data["worktree"]
+              if worktree_data.is_a?(Hash)
+                branch = worktree_data[:branch] || worktree_data["branch"]
+                return branch if branch
+              end
+            end
+
+            # Fallback: current branch (if valid) or default
+            current_branch_fallback || DEFAULT_TARGET
+          end
+
+          private
+
+          # Extract parent task ID from task ID
+          #
+          # @param task_id [String] Full task ID (e.g., "v.0.9.0+task.202.01")
+          # @return [String, nil] Parent task ID (e.g., "202") or nil
+          #
+          # @example Subtask
+          #   extract_parent_id("v.0.9.0+task.202.01") # => "202"
+          #
+          # @example Orchestrator task
+          #   extract_parent_id("v.0.9.0+task.202") # => nil
+          def extract_parent_id(task_id)
+            return nil unless task_id
+
+            # Extract task number from full ID using TASK_ID_PATTERN
+            # Pattern: v.0.9.0+task.202.01 -> 202.01
+            match = task_id.match(TASK_ID_PATTERN)
+            return nil unless match
+
+            task_number = match[1]
+
+            # Check if this is a subtask (contains dot)
+            return nil unless task_number.include?(".")
+
+            # Extract parent number: 202.01 -> 202
+            task_number.split(".").first
+          end
+
+          # Get current branch as fallback for target branch
+          #
+          # Returns the current branch name if available and not a detached HEAD.
+          # Used when parent task has no worktree metadata.
+          #
+          # @return [String, nil] Current branch name or nil if detached/error
+          def current_branch_fallback
+            branch = Atoms::GitCommand.current_branch
+            return nil if branch.nil? || branch.empty?
+            return nil if branch == "HEAD"
+
+            # If branch looks like a SHA, verify it's not actually a branch name
+            # This handles edge case of hex-only branch names like "deadbeef"
+            if branch.match?(SHA_PATTERN)
+              # Check if refs/heads/<name> exists - if so, it's a real branch
+              return nil unless Atoms::GitCommand.ref_exists?("refs/heads/#{branch}")
+            end
+
+            branch
+          rescue => e
+            warn "[DEBUG] current_branch_fallback failed: #{e.message}" if ENV["DEBUG"]
+            nil
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,253 @@
+# 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