ace-git 0.23.1 → 0.25.0

data/lib/ace/git/cli/commands/pr.rb

@@ -7,110 +7,185 @@ module Ace
   module Git
     module CLI
       module Commands
-        # ace-support-cli command for showing PR information
-        class Pr < Ace::Support::Cli::Command
-          include Ace::Support::Cli::Base
-
-          desc "Show PR information"
-
-          argument :number, required: false, desc: "PR number (auto-detected if not provided)"
-
-          option :format, type: :string, aliases: ["f"], default: "markdown",
-            desc: "Output format: markdown, json"
-          option :with_diff, type: :boolean, default: false,
-            desc: "Include PR diff in output"
+        # Forge-neutral pull request lifecycle commands.
+        #
+        # Every subcommand accepts `--server NAME` / `--default-server`
+        # (mutually exclusive; remote resolution when neither is given) and
+        # `--format json`. Success output carries the resolved server,
+        # provider, and exact PR identity; failures exit nonzero with the
+        # classified provider error and never claim success.
+        module Pr
+          # Shared plumbing for all pr subcommands.
+          class BaseCommand < Ace::Support::Cli::Command
+            include Ace::Support::Cli::Base
+
+            option :server, type: :string, desc: "Explicit configured forge server name"
+            option :default_server, type: :boolean, desc: "Use the configured default forge server"
+            option :remote, type: :string, desc: "Git remote used for server resolution when nothing is selected"
+            option :format, type: :string, default: "text", desc: "Output format: text, json"
+
+            private
+
+            def lifecycle(options)
+              Organisms::PullRequestLifecycle.new(
+                server_name: options[:server],
+                use_default: options[:default_server] == true,
+                remote_name: options[:remote]
+              )
+            end
 
-          # Standard options
-          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
-          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
-          option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+            def render_evidence(options, header: nil, **fields)
+              if options[:format] == "json"
+                puts JSON.pretty_generate(fields)
+              else
+                puts header if header
+                fields.each do |label, value|
+                  next if value.nil?
 
-          def call(number: nil, **options)
-            # Check if gh is installed
-            unless Molecules::PrMetadataFetcher.gh_installed?
-              raise Ace::Support::Cli::Error.new("GitHub CLI (gh) not installed. Install with: brew install gh")
+                  puts "#{label.to_s.tr("_", "-")}: #{format_value(value)}"
+                end
+              end
             end
 
-            # Determine PR identifier
-            identifier = if number
-              number.to_s
-            else
-              # Try to find PR for current branch
-              found = Molecules::PrMetadataFetcher.find_pr_for_branch
-              unless found
-                raise Ace::Support::Cli::Error.new("No PR found for current branch. Specify a PR number.")
+            def format_value(value)
+              case value
+              when Hash
+                value.compact.map { |key, nested| "#{key}=#{nested}" }.join(" ")
+              else
+                value.to_s
               end
-              found
             end
 
-            # Fetch PR data
-            result = if options[:with_diff]
-              Molecules::PrMetadataFetcher.fetch_pr(identifier)
-            else
-              Molecules::PrMetadataFetcher.fetch_metadata(identifier)
+            def emit_receipt(options, operation, receipt)
+              pr = receipt.pull_request
+              render_evidence(
+                options,
+                header: "#{operation} PR ##{pr.number} on #{receipt.server_name}",
+                server: receipt.server_name,
+                operation: receipt.operation,
+                idempotency: receipt.idempotency,
+                number: pr.number,
+                url: pr.url,
+                title: pr.title,
+                state: pr.state,
+                draft: pr.draft,
+                head: pr.head_sha,
+                head_ref: pr.head_ref,
+                head_repository: pr.head_repository_url,
+                base_ref: pr.base_ref,
+                base_repository: pr.base_repository_url
+              )
             end
+          end
 
-            unless result[:success]
-              raise Ace::Support::Cli::Error.new(result[:error])
+          # `ace-git pr show ID`
+          class Show < BaseCommand
+            desc "Show normalized pull request evidence"
+
+            argument :identifier, required: true, desc: "PR number, owner/repo#number, or URL"
+
+            def call(identifier:, **options)
+              pr = lifecycle(options).show(identifier)
+              render_evidence(
+                options,
+                header: "PR ##{pr.number} on #{pr.server_name}",
+                server: pr.server_name,
+                number: pr.number,
+                url: pr.url,
+                title: pr.title,
+                state: pr.state,
+                draft: pr.draft,
+                head: pr.head_sha,
+                head_ref: pr.head_ref,
+                head_repository: pr.head_repository_url,
+                base_ref: pr.base_ref,
+                base_repository: pr.base_repository_url,
+                merge_commit: pr.merge_commit_sha
+              )
+            rescue Ace::Git::Error, ArgumentError => e
+              raise Ace::Support::Cli::Error.new(e.message)
             end
+          end
 
-            # Output based on format
-            case options[:format]
-            when "json"
-              output_data = {metadata: result[:metadata]}
-              output_data[:diff] = result[:diff] if options[:with_diff]
-              puts JSON.pretty_generate(output_data)
-            else
-              output_markdown(result[:metadata], result[:diff], options)
+          # `ace-git pr create --head REF --head-repo URL --base REF --expected-head SHA --title TEXT [--body-file PATH] [--draft]`
+          class Create < BaseCommand
+            desc "Create (or reconcile to) a pull request; drafts are the default"
+
+            option :head, type: :string, required: true, desc: "Source branch/ref"
+            option :head_repo, type: :string, desc: "Source repository URL (fork); defaults to the base repository"
+            option :base, type: :string, required: true, desc: "Base branch/ref"
+            option :expected_head, type: :string, required: true, desc: "Exact SHA the pushed source ref must resolve to"
+            option :title, type: :string, required: true, desc: "Pull request title"
+            option :body_file, type: :string, desc: "Path to the pull request body text"
+            option :draft, type: :boolean, default: true, desc: "Create as draft when the provider supports it"
+
+            def call(head:, base:, expected_head:, title:, **options)
+              receipt = lifecycle(options).create(
+                head_ref: head,
+                head_repository_url: options[:head_repo],
+                base_ref: base,
+                expected_head: expected_head,
+                title: title,
+                body_file: options[:body_file],
+                draft: options[:draft] != false
+              )
+              emit_receipt(options, "created", receipt)
+            rescue Ace::Git::Error, ArgumentError => e
+              raise Ace::Support::Cli::Error.new(e.message)
             end
-          rescue Ace::Git::Error => e
-            raise Ace::Support::Cli::Error.new(e.message)
-          rescue ArgumentError => e
-            raise Ace::Support::Cli::Error.new(e.message)
           end
 
-          private
-
-          def output_markdown(metadata, diff, options)
-            lines = []
-
-            # Header line: # PR #82: Title... [OPEN]
-            header = "# PR ##{metadata["number"]}"
-            header += ": #{metadata["title"]}" if metadata["title"]
-            header += " [#{metadata["state"]}]" if metadata["state"]
-            lines << header
-
-            # Branch line: Branch: source → target | Draft: No
-            branch_parts = []
-            if metadata["headRefName"] && metadata["baseRefName"]
-              branch_parts << "Branch: #{metadata["headRefName"]} → #{metadata["baseRefName"]}"
-            elsif metadata["headRefName"]
-              branch_parts << "Branch: #{metadata["headRefName"]}"
-            elsif metadata["baseRefName"]
-              branch_parts << "Target: #{metadata["baseRefName"]}"
+          # `ace-git pr update ID --expected-head SHA [--title TEXT] [--body-file PATH]`
+          class Update < BaseCommand
+            desc "Update pull request title/body after head verification"
+
+            argument :identifier, required: true, desc: "PR number, owner/repo#number, or URL"
+            option :expected_head, type: :string, required: true, desc: "Exact SHA the PR head must still be"
+            option :title, type: :string, desc: "New title"
+            option :body_file, type: :string, desc: "Path to the new body text"
+
+            def call(identifier:, expected_head:, **options)
+              receipt = lifecycle(options).update(
+                identifier,
+                expected_head: expected_head,
+                title: options[:title],
+                body_file: options[:body_file]
+              )
+              emit_receipt(options, "updated", receipt)
+            rescue Ace::Git::Error, ArgumentError => e
+              raise Ace::Support::Cli::Error.new(e.message)
             end
-            branch_parts << "Draft: #{metadata["isDraft"] ? "Yes" : "No"}" if metadata.key?("isDraft")
-            lines << branch_parts.join(" | ") unless branch_parts.empty?
+          end
 
-            # Author line
-            if metadata["author"]
-              author = metadata["author"].is_a?(Hash) ? metadata["author"]["login"] : metadata["author"]
-              lines << "Author: #{author}"
-            end
+          # `ace-git pr ready ID --expected-head SHA`
+          class Ready < BaseCommand
+            desc "Mark a draft pull request ready for review"
 
-            # URL line
-            lines << "URL: #{metadata["url"]}" if metadata["url"]
+            argument :identifier, required: true, desc: "PR number, owner/repo#number, or URL"
+            option :expected_head, type: :string, required: true, desc: "Exact SHA the PR head must still be"
 
-            if options[:with_diff] && diff
-              lines << ""
-              lines << "## Diff"
-              lines << ""
-              lines << "```diff"
-              lines << diff
-              lines << "```"
+            def call(identifier:, expected_head:, **options)
+              receipt = lifecycle(options).ready(identifier, expected_head: expected_head)
+              emit_receipt(options, "readied", receipt)
+            rescue Ace::Git::Error, ArgumentError => e
+              raise Ace::Support::Cli::Error.new(e.message)
             end
+          end
 
-            puts lines.join("\n")
+          # `ace-git pr merge ID --expected-head SHA --method squash|merge|rebase`
+          class Merge < BaseCommand
+            desc "Merge with provider-side expected-head enforcement; no default method"
+
+            argument :identifier, required: true, desc: "PR number, owner/repo#number, or URL"
+            option :expected_head, type: :string, required: true, desc: "Exact SHA enforced by the provider"
+            option :method, type: :string, required: true, desc: "Merge method: squash, merge, rebase"
+
+            def call(identifier:, expected_head:, method:, **options)
+              receipt = lifecycle(options).merge(identifier, expected_head: expected_head, method: method)
+              emit_receipt(options, "merged", receipt)
+            rescue Ace::Git::Error, ArgumentError => e
+              raise Ace::Support::Cli::Error.new(e.message)
+            end
           end
         end
       end

data/lib/ace/git/cli/commands/status.rb

@@ -59,24 +59,34 @@ module Ace
             # Include diff if requested
             if options[:with_diff] && status.has_pr?
               begin
-                diff_result = Molecules::PrMetadataFetcher.fetch_diff(
-                  status.pr_metadata["number"].to_s
-                )
-                if diff_result[:success]
+                provider = active_provider
+                diff = provider&.pull_request_diff(number: status.pr_metadata.number.to_s)
+                if diff
                   puts ""
                   puts "## PR Diff"
                   puts ""
                   puts "```diff"
-                  puts diff_result[:diff]
+                  puts diff
                   puts "```"
                 end
               rescue Ace::Git::Error
-                # Silently skip diff if it fails
+                # Classified provider failure: skip the diff section
               end
             end
           rescue Ace::Git::Error => e
             raise Ace::Support::Cli::Error.new(e.message)
           end
+
+          private
+
+          # Resolve the default server's registered provider for optional
+          # enrichment; nil when no server or provider is configured.
+          def active_provider
+            server = Ace::Git::ServerRegistry.resolve_default
+            Ace::Git::Providers.for(server)
+          rescue Ace::Git::Error
+            nil
+          end
         end
       end
     end

data/lib/ace/git/cli.rb

@@ -52,19 +52,24 @@ module Ace
         ["diff", "Show filtered git diff output"],
         ["status", "Show repository status and PR context"],
         ["branch", "Show current branch information"],
-        ["pr", "Show pull request information"]
+        ["pr", "Forge-neutral pull request lifecycle: show, create, update, ready, merge"]
       ].freeze
 
       HELP_EXAMPLES = [
         "ace-git diff --since 7d           # Changes from last week",
         "ace-git diff -p 'lib/**' -f summary  # Filtered summary",
-        "ace-git status --no-pr            # Quick status, skip network"
+        "ace-git status --no-pr            # Quick status, skip network",
+        "ace-git pr show 25 --format json  # Normalized PR evidence"
       ].freeze
 
       register "diff", Commands::Diff.new
       register "status", Commands::Status.new
       register "branch", Commands::Branch.new
-      register "pr", Commands::Pr.new
+      register "pr show", Commands::Pr::Show.new
+      register "pr create", Commands::Pr::Create.new
+      register "pr update", Commands::Pr::Update.new
+      register "pr ready", Commands::Pr::Ready.new
+      register "pr merge", Commands::Pr::Merge.new
 
       version_cmd = Ace::Support::Cli::VersionCommand.build(
         gem_name: "ace-git",

data/lib/ace/git/errors.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Ace
+  module Git
+    # Error handling pattern:
+    # - Atoms: Pure functions, raise exceptions for invalid inputs
+    # - Molecules: May return error hashes for "expected" errors (e.g., not in git repo)
+    #   or raise exceptions for unexpected failures
+    # - Organisms: Orchestrate molecules, propagate or wrap exceptions
+    # - Commands: Catch exceptions and return exit codes (0=success, 1=error)
+    #
+    # All custom exceptions inherit from Ace::Git::Error for consistent catching.
+    class Error < StandardError; end
+    class GitError < Error; end
+    class ConfigError < Error; end
+    class TimeoutError < Error; end
+
+    # ---- Forge server resolution failures ----
+
+    # Default requested but no default server is configured.
+    class NoDefaultServerConfiguredError < Error; end
+
+    # More than one server is marked as default in configuration.
+    class MultipleDefaultServersError < Error; end
+
+    # Multiple servers are configured with the same identifier.
+    class DuplicateServerNameError < Error; end
+
+    # A server references a provider type that no provider package registered.
+    class UnknownProviderError < Error; end
+
+    # The requested server name is not present in configuration.
+    class UnknownServerNameError < Error; end
+
+    # A remote URL matches multiple configured servers, or none, so the server
+    # identity cannot be determined without caller input.
+    class AmbiguousRemoteError < Error; end
+
+    # ---- Provider interaction failures ----
+
+    # The provider CLI binary is not installed in PATH.
+    class ProviderCliMissingError < Error; end
+
+    # The provider CLI is unauthenticated or its credential lease expired.
+    class ProviderAuthenticationError < Error; end
+
+    # The remote forge endpoint is offline or unreachable.
+    class ProviderUnreachableError < Error; end
+
+    # The provider CLI returned invalid JSON or an unexpected schema.
+    class ProviderMalformedOutputError < Error; end
+
+    # The requested pull request, issue, branch, or commit does not exist.
+    class ProviderObjectNotFoundError < Error; end
+
+    # ---- PR lifecycle mutation failures ----
+
+    # A supplied PR URL or repository identity does not match the resolved
+    # server (or the explicit selection contradicts the identifier). Detected
+    # before any mutation.
+    class ProviderIdentityMismatchError < Error; end
+
+    # More than one open pull request exactly matches the requested
+    # base/head identity, so no single object can be selected.
+    class ProviderConflictingMatchesError < Error; end
+
+    # The pull request head changed relative to the expected head SHA the
+    # caller supplied. The operation did not proceed (or the provider refused
+    # it atomically).
+    class ProviderExpectedHeadConflictError < Error; end
+
+    # The provider CLI cannot enforce a required precondition atomically
+    # (e.g. expected-head merge) or does not offer the requested operation.
+    # Never worked around with a check-then-act fallback.
+    class ProviderUnsupportedCapabilityError < Error; end
+
+    # A mutation request was sent but its outcome is unknown (e.g. transport
+    # failure after the send). Contains the exact base/head identity needed to
+    # reconcile by lookup; never retried automatically.
+    class ProviderUnknownOutcomeError < Error; end
+  end
+end

data/lib/ace/git/models/diff_config.rb

@@ -91,7 +91,7 @@ module Ace
           elsif exclude_renames?
             flags << "--diff-filter=ACDMTUXB"
           elsif exclude_moves?
-            # Moves appear as rename with 100% similarity, disable high-similarity renames
+            # Moves appear as renames with total similarity; disable such exact renames
             flags << "-M0" # Disable rename detection (moves are renames at 100% similarity)
           end
           flags
@@ -164,7 +164,7 @@ module Ace
           hash.each_key do |key|
             key_str = key.to_s
             next if KNOWN_KEYS.include?(key_str)
-            # Skip nested sections that may be passed through
+            # Skip nested sections that may be propagated
             next if %w[diff rebase pr squash default_branch remote verbose].include?(key_str)
 
             warn "[ace-git] Unknown config key '#{key_str}' in DiffConfig - did you mean one of: #{KNOWN_KEYS.join(", ")}?"

data/lib/ace/git/models/repo_status.rb

@@ -68,7 +68,7 @@ module Ace
         # Check if has associated PR
         # @return [Boolean] True if PR metadata present
         def has_pr?
-          !pr_metadata.nil? && !pr_metadata.empty?
+          !pr_metadata.nil?
         end
 
         # Check if has detected task pattern

data/lib/ace/git/molecules/branch_reader.rb

@@ -35,17 +35,14 @@ module Ace
           # @param executor [Module] Command executor
           # @return [Hash] { ahead: Integer, behind: Integer }
           def tracking_status(executor: Atoms::CommandExecutor)
-            result = executor.execute("git", "rev-list", "--left-right", "--count", "@{upstream}...HEAD")
+            ahead = count_commits("@{upstream}..HEAD", executor: executor)
+            behind = count_commits("HEAD..@{upstream}", executor: executor)
 
-            unless result[:success]
+            if ahead.nil? || behind.nil?
               return {ahead: 0, behind: 0, error: "No tracking branch or not in git repo"}
             end
 
-            parts = result[:output].strip.split(/\s+/)
-            {
-              ahead: parts[1].to_i,
-              behind: parts[0].to_i
-            }
+            {ahead: ahead, behind: behind}
           end
 
           # Get full branch information
@@ -85,6 +82,15 @@ module Ace
               "#{behind} behind"
             end
           end
+
+          # Count commits in a rev-list range; nil when the range is invalid
+          # (e.g. no upstream configured)
+          def count_commits(range, executor: Atoms::CommandExecutor)
+            result = executor.execute("git", "rev-list", "--count", range)
+            return nil unless result[:success]
+
+            result[:output].strip.to_i
+          end
         end
       end
     end

data/lib/ace/git/molecules/config_loader.rb

@@ -13,7 +13,7 @@ module Ace
         class << self
           # Load configuration using ace-config cascade with deep merge
           # Priority: instance_config merged over global config (which is already defaults + user)
-          # @param instance_config [Hash] Instance-level configuration (highest priority)
+          # @param instance_config [Hash] Instance-level configuration (top priority)
           # @return [Models::DiffConfig] Merged configuration
           def load(instance_config = {})
             # Get global config from ace-git (already merged defaults + user per ADR-022)