ace-git 0.23.0 → 0.24.0

data/lib/ace/git/organisms/repo_status_loader.rb

@@ -4,12 +4,17 @@ module Ace
   module Git
     module Organisms
       # Orchestrates loading complete repository status
-      # Combines branch info, task pattern detection, and PR metadata
+      # Combines branch info, task pattern detection, and PR evidence
+      #
+      # PR enrichment is provider-optional: it resolves the default forge
+      # server and its registered provider via the core contract. With no
+      # server configured, no provider registered, or a classified provider
+      # failure, status stays purely local and the PR sections are skipped.
       class RepoStatusLoader
         class << self
           # Load complete repository status
           # @param options [Hash] Options for status loading
-          # @option options [Boolean] :include_pr Whether to fetch PR metadata (default: true)
+          # @option options [Boolean] :include_pr Whether to fetch PR evidence (default: true)
           # @option options [Boolean] :include_pr_activity Whether to fetch PR activity (default: true)
           # @option options [Boolean] :include_commits Whether to fetch recent commits (default: true)
           # @option options [Integer] :commits_limit Number of recent commits to fetch (default: 3)
@@ -53,28 +58,18 @@ module Ace
               recent_commits = fetch_recent_commits(limit: commits_limit)
             end
 
-            # Fetch PR data (metadata and activity) - parallelized for performance
+            # Fetch PR evidence (metadata and activity) via the provider contract
             pr_metadata = nil
             pr_activity = nil
             if !branch_info[:detached]
-              if include_pr && include_pr_activity
-                # Both requested: use parallel fetch for ~50% speedup
-                pr_data = fetch_pr_data_parallel(
-                  current_branch: branch_info[:name],
-                  timeout: timeout
-                )
-                pr_metadata = pr_data[:pr_metadata]
-                pr_activity = pr_data[:pr_activity]
-              elsif include_pr
-                # Only PR metadata requested
-                pr_metadata = fetch_pr_metadata(timeout: timeout)
-              elsif include_pr_activity
-                # Only activity requested
-                pr_activity = fetch_pr_activity(
-                  current_branch: branch_info[:name],
-                  timeout: timeout
-                )
-              end
+              pr_sections = fetch_pr_sections(
+                current_branch: branch_info[:name],
+                include_metadata: include_pr,
+                include_activity: include_pr_activity,
+                timeout: timeout
+              )
+              pr_metadata = pr_sections[:pr_metadata]
+              pr_activity = pr_sections[:pr_activity]
             end
 
             # Build and return status
@@ -100,13 +95,8 @@ module Ace
             # Get basic status (skip PR activity since we're fetching a specific PR)
             status = load(include_pr: false, include_pr_activity: false)
 
-            # Fetch specific PR metadata
-            begin
-              result = Molecules::PrMetadataFetcher.fetch_metadata(pr_identifier, timeout: timeout)
-              pr_metadata = result[:success] ? result[:metadata] : nil
-            rescue Ace::Git::Error
-              pr_metadata = nil
-            end
+            # Fetch specific PR evidence
+            pr_metadata = resolve_pr_metadata(pr_identifier, timeout: timeout)
 
             # Return status with PR data
             Models::RepoStatus.from_data(
@@ -131,6 +121,60 @@ module Ace
 
           private
 
+          # Resolve a specific PR via the provider contract
+          # @return [ProviderPullRequest, nil] PR evidence or nil
+          def resolve_pr_metadata(pr_identifier, timeout:)
+            provider = active_provider(timeout: timeout)
+            return nil unless provider
+
+            provider.pull_request(number: pr_identifier)
+          rescue Ace::Git::Error
+            # Classified provider failure: keep status local, skip PR evidence
+            nil
+          end
+
+          # Fetch PR evidence sections via the provider contract
+          # @return [Hash] {:pr_metadata => ProviderPullRequest, :pr_activity => Hash}
+          def fetch_pr_sections(current_branch:, include_metadata:, include_activity:, timeout:)
+            provider = active_provider(timeout: timeout)
+            return {pr_metadata: nil, pr_activity: nil} unless provider
+
+            metadata = include_metadata ? provider.pull_request_for_branch(branch: current_branch) : nil
+            activity = include_activity ? fetch_activity(provider, current_branch: current_branch) : nil
+
+            {pr_metadata: metadata, pr_activity: activity}
+          rescue Ace::Git::Error
+            # Classified provider failure: keep status local, skip PR evidence
+            {pr_metadata: nil, pr_activity: nil}
+          end
+
+          # Build merged/open activity lists from recent PR evidence
+          def fetch_activity(provider, current_branch:)
+            prs = provider.recent_pull_requests(limit: 30)
+            merged = prs
+              .select { |pr| pr.state == :merged }
+              .first(Ace::Git.merged_prs_limit)
+            open_prs = prs
+              .select { |pr| pr.state == :open && pr.head_ref != current_branch }
+              .first(Ace::Git.open_prs_limit)
+
+            return nil if merged.empty? && open_prs.empty?
+
+            {merged: merged, open: open_prs}
+          end
+
+          # Resolve the default server's registered provider, or nil.
+          # Resolution failures are classified; enrichment is optional, so any
+          # of them simply skips the PR sections.
+          def active_provider(timeout:)
+            server = ServerRegistry.resolve_default
+            return nil unless server
+
+            Providers.for(server, timeout: timeout)
+          rescue Ace::Git::Error
+            nil
+          end
+
           # Fetch git status in short branch format
           # @return [String, nil] Git status output or nil
           def fetch_git_status
@@ -149,114 +193,6 @@ module Ace
           rescue
             nil
           end
-
-          # Fetch PR metadata for current branch
-          # @param timeout [Integer] Timeout in seconds
-          # @return [Hash, nil] PR metadata or nil
-          def fetch_pr_metadata(timeout:)
-            # First try to find PR for current branch
-            pr_number = Molecules::PrMetadataFetcher.find_pr_for_branch(timeout: timeout)
-            return nil unless pr_number
-
-            # Then fetch full metadata
-            result = Molecules::PrMetadataFetcher.fetch_metadata(pr_number, timeout: timeout)
-            result[:success] ? result[:metadata] : nil
-          rescue Ace::Git::GhNotInstalledError, Ace::Git::GhAuthenticationError
-            # gh not available, skip PR metadata
-            nil
-          rescue Ace::Git::PrNotFoundError
-            # No PR for this branch
-            nil
-          rescue Ace::Git::TimeoutError
-            # Timeout, skip PR metadata
-            nil
-          rescue
-            # Any other error, skip PR metadata
-            nil
-          end
-
-          # Fetch PR activity (recently merged and open PRs)
-          # @param current_branch [String] Current branch name to exclude from open PRs
-          # @param timeout [Integer] Timeout in seconds
-          # @return [Hash, nil] PR activity with :merged and :open arrays (symbol keys), or nil
-          #   Each PR in the arrays has string keys from JSON parsing: "number", "title", etc.
-          def fetch_pr_activity(current_branch:, timeout:)
-            merged_result = Molecules::PrMetadataFetcher.fetch_recently_merged(
-              limit: Ace::Git.merged_prs_limit,
-              timeout: timeout
-            )
-            open_result = Molecules::PrMetadataFetcher.fetch_open_prs(
-              exclude_branch: current_branch,
-              timeout: timeout
-            )
-
-            # Return nil if both failed
-            return nil unless merged_result[:success] || open_result[:success]
-
-            # Use symbol keys for outer hash, string keys for PR data (from JSON)
-            # This is documented behavior - consumers should access via pr_activity[:merged]
-            # and individual PRs via pr["number"], pr["title"], etc.
-            {
-              merged: merged_result[:success] ? merged_result[:prs] : [],
-              open: open_result[:success] ? open_result[:prs] : []
-            }
-          rescue
-            # Any error, skip PR activity
-            nil
-          end
-
-          # Fetch PR metadata and activity in a single API call for optimal performance
-          # Uses gh pr list --state all to get all PRs, then filters locally
-          # @param current_branch [String] Current branch name to match/exclude
-          # @param timeout [Integer] Timeout in seconds
-          # @return [Hash] Result with :pr_metadata and :pr_activity keys
-          def fetch_pr_data_parallel(current_branch:, timeout:)
-            # Single API call gets all recent PRs
-            result = Molecules::PrMetadataFetcher.fetch_all_prs(
-              limit: 15,  # Enough for current + merged + open
-              timeout: timeout
-            )
-
-            return {pr_metadata: nil, pr_activity: nil} unless result[:success]
-
-            prs = result[:prs]
-
-            # Find current PR (matching branch, prefer OPEN > MERGED > CLOSED)
-            branch_prs = prs.select { |pr| pr["headRefName"] == current_branch }
-            current_pr = branch_prs.min_by { |pr|
-              case pr["state"]
-              when "OPEN" then 0
-              when "MERGED" then 1
-              when "CLOSED" then 2
-              else 3
-              end
-            }
-
-            # Get merged PRs (sorted by mergedAt descending, limited)
-            merged_prs = prs
-              .select { |pr| pr["state"] == "MERGED" }
-              .sort_by { |pr| pr["mergedAt"] || "" }
-              .reverse
-              .take(Ace::Git.merged_prs_limit)
-
-            # Get open PRs (exclude current branch, limited)
-            open_prs = prs
-              .select { |pr| pr["state"] == "OPEN" && pr["headRefName"] != current_branch }
-              .take(Ace::Git.open_prs_limit)
-
-            # Build activity hash (nil if no activity to show)
-            pr_activity = nil
-            if merged_prs.any? || open_prs.any?
-              pr_activity = {merged: merged_prs, open: open_prs}
-            end
-
-            {
-              pr_metadata: current_pr,
-              pr_activity: pr_activity
-            }
-          rescue
-            {pr_metadata: nil, pr_activity: nil}
-          end
         end
       end
     end

data/lib/ace/git/providers/base.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Ace
+  module Git
+    module Providers
+      # Abstract provider contract implemented by provider packages.
+      #
+      # The core defines the interface and the normalized evidence types;
+      # implementations own all provider CLI invocation, output parsing, and
+      # authentication verification. The core itself never executes a provider
+      # CLI and never parses provider output.
+      #
+      # Subclasses receive the resolved server identity and may accept two
+      # optional constructor keywords (see {Providers.for}):
+      # - timeout: operation timeout in seconds
+      # - runner: injectable command runner for tests; a callable receiving
+      #   keyword arguments (args:, timeout:, env:) and returning a Hash with
+      #   :stdout, :stderr, :exit_code
+      class Base
+        attr_reader :server, :timeout
+
+        # @param server [ResolvedServer] resolved server identity
+        # @param timeout [Integer, nil] operation timeout (default: config)
+        # @param runner [Proc, nil] injectable command runner for tests
+        def initialize(server:, timeout: nil, runner: nil)
+          @server = server
+          @timeout = timeout || Ace::Git.network_timeout
+          @runner = runner
+        end
+
+        # @return [Boolean] true when the provider CLI binary is installed
+        def available?
+          raise NotImplementedError, "Providers must implement #{self.class}#available?"
+        end
+
+        # @raise [ProviderCliMissingError] when the provider CLI is missing
+        def check_available!
+          raise NotImplementedError, "Providers must implement #{self.class}#check_available!"
+        end
+
+        # @return [Boolean] true when the provider CLI is authenticated
+        def authenticated?
+          raise NotImplementedError, "Providers must implement #{self.class}#authenticated?"
+        end
+
+        # @raise [ProviderAuthenticationError] when unauthenticated
+        def check_authenticated!
+          raise NotImplementedError, "Providers must implement #{self.class}#check_authenticated!"
+        end
+
+        # Fetch one pull request.
+        #
+        # @param number [Integer, String] pull request number
+        # @return [ProviderPullRequest] normalized pull request evidence
+        def pull_request(number:)
+          raise NotImplementedError, "Providers must implement #{self.class}#pull_request"
+        end
+
+        # Find the pull request associated with a branch.
+        #
+        # @param branch [String] branch name
+        # @return [ProviderPullRequest, nil] evidence, or nil when no pull
+        #   request is associated with the branch
+        def pull_request_for_branch(branch:)
+          raise NotImplementedError, "Providers must implement #{self.class}#pull_request_for_branch"
+        end
+
+        # Fetch the full diff of one pull request.
+        #
+        # @param number [Integer, String] pull request number
+        # @return [String] unified diff text
+        def pull_request_diff(number:)
+          raise NotImplementedError, "Providers must implement #{self.class}#pull_request_diff"
+        end
+
+        # List recent pull requests across states (newest first).
+        #
+        # @param limit [Integer] maximum number of pull requests
+        # @return [Array<ProviderPullRequest>] normalized pull requests
+        def recent_pull_requests(limit:)
+          raise NotImplementedError, "Providers must implement #{self.class}#recent_pull_requests"
+        end
+
+        # Fetch one issue.
+        #
+        # @param number [Integer, String] issue number
+        # @return [ProviderIssue] normalized issue evidence
+        def issue(number:)
+          raise NotImplementedError, "Providers must implement #{self.class}#issue"
+        end
+
+        # Fetch check/CI status evidence for a reference.
+        #
+        # @param ref [String] commit sha or branch name
+        # @return [Array<ProviderCheck>] normalized check evidence
+        def checks(ref:)
+          raise NotImplementedError, "Providers must implement #{self.class}#checks"
+        end
+
+        # Fetch repository metadata for the resolved server.
+        #
+        # @return [ProviderRepository] normalized repository evidence
+        def repository
+          raise NotImplementedError, "Providers must implement #{self.class}#repository"
+        end
+
+        private
+
+        # Command runner: injected fake or nil (implementations use their own
+        # executor when nil).
+        attr_reader :runner
+      end
+    end
+  end
+end

data/lib/ace/git/providers/evidence.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Ace
+  module Git
+    # Normalized evidence types produced by every provider implementation.
+    #
+    # Provider packages translate their CLI responses into exactly these
+    # shapes, so consumers can stay forge-neutral. All fields except the
+    # identifying ones may be nil when a provider cannot supply them.
+    #
+    # Pull request state values: :open, :merged, :closed. Issue state values:
+    # :open, :closed.
+    ProviderPullRequest = Data.define(
+      :server_name, :number, :title, :state, :head_ref, :base_ref,
+      :head_sha, :author, :url, :draft, :merged_at
+    )
+
+    ProviderIssue = Data.define(:server_name, :number, :title, :state, :author, :url, :labels)
+
+    # Normalized check/CI evidence for one check run.
+    ProviderCheck = Data.define(:server_name, :name, :state, :conclusion, :url)
+
+    # Normalized repository evidence.
+    ProviderRepository = Data.define(:server_name, :full_name, :default_branch, :url)
+  end
+end

data/lib/ace/git/providers.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "providers/base"
+require_relative "providers/evidence"
+
+module Ace
+  module Git
+    # Registry of provider implementations owned by provider packages.
+    #
+    # The core never executes provider CLIs. Provider packages register their
+    # contract implementation here when loaded; downstream consumers then
+    # obtain a provider via {Providers.for}.
+    #
+    # @example Registering (inside a provider package)
+    #   Ace::Git::Providers.register(:acme, Ace::Git::Acme::Provider)
+    #
+    # @example Resolving (in consumers)
+    #   server = Ace::Git::ServerRegistry.resolve_default
+    #   provider = Ace::Git::Providers.for(server)
+    #   pr = provider.pull_request(number: 25)
+    module Providers
+      @registry = {}
+      @mutex = Mutex.new
+
+      class << self
+        # Register a provider implementation for a provider type.
+        #
+        # @param type [Symbol, String] provider type (e.g. :acme)
+        # @param provider_class [Class] class implementing Providers::Base;
+        #   must respond to .new
+        # @raise [ArgumentError] when type or provider_class is invalid
+        def register(type, provider_class)
+          key = normalize_type(type)
+          unless provider_class.respond_to?(:new)
+            raise ArgumentError, "Provider for #{key.inspect} must be a class (got #{provider_class.inspect})"
+          end
+
+          @mutex.synchronize { @registry[key] = provider_class }
+          provider_class
+        end
+
+        # Build the provider implementation for a resolved server.
+        #
+        # @param server [ResolvedServer] exactly-resolved server identity
+        # @param timeout [Integer, nil] provider operation timeout in seconds
+        # @param runner [Proc, nil] optional command runner injection for tests;
+        #   see Providers::Base
+        # @return [Providers::Base] provider instance bound to the server
+        # @raise [UnknownProviderError] when no provider is registered for the
+        #   server's provider type
+        def for(server, timeout: nil, runner: nil)
+          key = normalize_type(server.provider)
+          provider_class = @mutex.synchronize { @registry[key] }
+          unless provider_class
+            raise UnknownProviderError,
+              "No provider registered for type #{key.inspect} (server '#{server.name}'); " \
+              "install and require the provider package that owns #{key.inspect}"
+          end
+
+          provider_class.new(server: server, timeout: timeout, runner: runner)
+        end
+
+        # @param type [Symbol, String] provider type
+        # @return [Boolean] true when a provider is registered for the type
+        def registered?(type)
+          key = normalize_type(type)
+          @mutex.synchronize { @registry.key?(key) }
+        end
+
+        # @return [Array<Symbol>] registered provider types, sorted
+        def types
+          @mutex.synchronize { @registry.keys.sort }
+        end
+
+        # Clear all registrations (test seam).
+        def reset!
+          @mutex.synchronize { @registry.clear }
+        end
+
+        private
+
+        def normalize_type(type)
+          normalized = type.to_s.strip.downcase
+          raise ArgumentError, "Provider type must be a non-empty symbol or string" if normalized.empty?
+
+          normalized.to_sym
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/resolved_server.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Ace
+  module Git
+    # An exactly-resolved forge server identity.
+    #
+    # Produced by ServerRegistry (by explicit name, by default resolution, or by
+    # remote URL matching). Carries the configured server name, the provider
+    # type that owns its behavior, and the configured base URL.
+    #
+    # @example
+    #   ResolvedServer.new(name: "forge-lab", provider: :acme, url: "https://forge.example.com")
+    ResolvedServer = Data.define(:name, :provider, :url) do
+      # @return [Hash] Plain hash representation
+      def to_h
+        {name: name, provider: provider, url: url}
+      end
+    end
+  end
+end

data/lib/ace/git/server_registry.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative "atoms/command_executor"
+require_relative "atoms/server_url"
+require_relative "errors"
+require_relative "resolved_server"
+
+module Ace
+  module Git
+    # Resolves forge server identity from configuration, deterministically.
+    #
+    # Configuration lives under the `git.servers` key (see
+    # `.ace-defaults/git/config.yml`). Each entry is a uniquely named server:
+    #
+    # ```yaml
+    # servers:
+    #   - name: forge-lab
+    #     provider: acme
+    #     url: https://forge.example.com/owner/repo
+    #     default: true
+    #   - name: forge-mirror
+    #     provider: other
+    #     url: https://other.example.com/owner/repo
+    # ```
+    #
+    # At most one server may be marked `default: true`. Resolution never falls
+    # back silently: every failure raises a classified error from the failure
+    # taxonomy.
+    class ServerRegistry
+      # Internal configured entry: resolved identity plus its default flag.
+      Entry = Data.define(:server, :default)
+
+      class << self
+        # All configured servers, in configuration order.
+        #
+        # @return [Array<ResolvedServer>]
+        # @raise [DuplicateServerNameError] when two servers share a name
+        # @raise [ConfigError] when an entry is malformed
+        def servers
+          entries.map(&:server)
+        end
+
+        # Resolve a server by its explicit, configured name.
+        #
+        # @param name [String, Symbol] configured server name
+        # @return [ResolvedServer]
+        # @raise [UnknownServerNameError] when no server has that name
+        def resolve(name)
+          wanted = name.to_s
+          entries.map(&:server).find { |server| server.name == wanted } ||
+            raise(UnknownServerNameError, "No server named '#{wanted}' is configured " \
+              "(configured: #{servers.map(&:name).join(", ")}); add it to git.servers")
+        end
+
+        # Resolve the explicitly configured default server.
+        #
+        # @return [ResolvedServer]
+        # @raise [NoDefaultServerConfiguredError] when zero servers are default
+        # @raise [MultipleDefaultServersError] when more than one is default
+        def resolve_default
+          defaults = entries.select(&:default)
+          if defaults.empty?
+            raise NoDefaultServerConfiguredError,
+              "No default server configured; mark exactly one entry in git.servers with default: true"
+          end
+          if defaults.size > 1
+            raise MultipleDefaultServersError,
+              "Multiple servers marked as default: #{defaults.map { |e| e.server.name }.join(", ")}; " \
+              "keep exactly one"
+          end
+
+          defaults.first.server
+        end
+
+        # Resolve server identity from a git remote URL, matching configured
+        # servers deterministically (no hostname assumptions).
+        #
+        # @param remote_name [String, nil] git remote name (default: configured
+        #   `remote`, then "origin")
+        # @return [ResolvedServer] the single matching configured server
+        # @raise [AmbiguousRemoteError] when the remote matches no configured
+        #   server, or more than one
+        def resolve_remote(remote_name = nil)
+          remote_name ||= Ace::Git.config["remote"] || "origin"
+          remote_url = read_remote_url(remote_name)
+          matches = entries.map(&:server).select { |server| Atoms::ServerUrl.match?(server.url, remote_url) }
+
+          if matches.empty?
+            raise AmbiguousRemoteError,
+              "Remote '#{remote_name}' (#{remote_url || "missing"}) matches no configured server " \
+              "(configured: #{servers.map(&:name).join(", ")})"
+          end
+          if matches.size > 1
+            raise AmbiguousRemoteError,
+              "Remote '#{remote_name}' (#{remote_url}) matches multiple configured servers: " \
+              "#{matches.map(&:name).join(", ")}; make server URLs distinct"
+          end
+
+          matches.first
+        end
+
+        private
+
+        # Validated configured entries, in configuration order.
+        def entries
+          raw = Ace::Git.config["servers"]
+          return [] if raw.nil?
+
+          raise ConfigError, "servers config must be a list" unless raw.is_a?(Array)
+
+          list = raw.map { |entry| build_entry(entry) }
+          assert_unique_names!(list)
+          list
+        end
+
+        # Read a remote URL with local git only (no network, no forge CLI).
+        def read_remote_url(remote_name)
+          result = Atoms::CommandExecutor.execute("git", "remote", "get-url", remote_name.to_s)
+          result[:success] ? result[:output].to_s.strip : nil
+        end
+
+        # Build one internal entry from a config entry, validating structure.
+        def build_entry(entry)
+          unless entry.is_a?(Hash)
+            raise ConfigError, "Each git.servers entry must be a mapping with name, provider, url"
+          end
+
+          normalized = entry.transform_keys(&:to_s)
+          %w[name provider url].each do |key|
+            next unless normalized[key].nil? || normalized[key].to_s.empty?
+
+            raise ConfigError, "git.servers entry is missing '#{key}': #{entry.inspect}"
+          end
+
+          Entry.new(
+            server: ResolvedServer.new(
+              name: normalized["name"].to_s,
+              provider: normalized["provider"].to_s.to_sym,
+              url: normalized["url"].to_s
+            ),
+            default: normalized["default"] == true || normalized["default"].to_s == "true"
+          )
+        end
+
+        def assert_unique_names!(list)
+          names = list.map { |entry| entry.server.name }
+          duplicates = names.tally.select { |_name, count| count > 1 }.keys
+          return if duplicates.empty?
+
+          raise DuplicateServerNameError,
+            "Duplicate server names in git.servers: #{duplicates.join(", ")}; server names must be unique"
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Git
-    VERSION = "0.23.0"
+    VERSION = "0.24.0"
   end
 end