ace-git 0.23.1 → 0.25.0

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

@@ -0,0 +1,96 @@
+# 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,
+      :head_repository_url, :base_repository_url, :merge_commit_sha
+    )
+
+    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)
+
+    # Exact pull request source/base identity used for idempotent create
+    # reconciliation, expected-head proof, and cleanup consent binding.
+    #
+    # `head_sha` is the exact head commit the identity was captured at; every
+    # mutation decision that depends on head state must compare against it.
+    ProviderPullRequestIdentity = Data.define(
+      :head_repository_url, :head_ref, :base_repository_url, :base_ref, :head_sha
+    ) do
+      # @return [Hash] plain, JSON-serializable representation
+      def to_h
+        {
+          head_repository_url: head_repository_url,
+          head_ref: head_ref,
+          base_repository_url: base_repository_url,
+          base_ref: base_ref,
+          head_sha: head_sha
+        }
+      end
+    end
+
+    # Normalized result of one provider lifecycle mutation (create, update,
+    # ready, merge). Receipts are immutable evidence: the operation performed,
+    # the pull request state observed afterwards, and — for creates only —
+    # whether the request created a new PR or reconciled to an existing one
+    # (`:created` / `:existing`; nil for non-create operations).
+    ProviderMutationReceipt = Data.define(:server_name, :operation, :pull_request, :idempotency) do
+      # @return [Hash] plain, JSON-serializable representation
+      def to_h
+        {
+          server_name: server_name,
+          operation: operation,
+          idempotency: idempotency,
+          pull_request: pull_request&.to_h
+        }
+      end
+    end
+
+    # Cleanup proof status vocabulary. Only :merged is confirmed remote merge
+    # proof; every other status retains the candidate. Provider transport
+    # failures (:offline, :authentication_error, :malformed) are distinct from
+    # object states and never relabel a failed lookup as merged.
+    CLEANUP_PROOF_STATUSES = %i[
+      no_pr open closed_unmerged merged offline authentication_error malformed
+    ].freeze
+
+    # Normalized provider proof about the pull request behind a cleanup
+    # candidate (worktree, local ref, or remote ref). `status` is one of
+    # {CLEANUP_PROOF_STATUSES}; pr/head fields are nil unless a PR was found.
+    ProviderCleanupProof = Data.define(
+      :server_name, :status, :pr_number, :pr_url, :head_sha, :merge_commit_sha
+    ) do
+      # @return [Boolean] true only for confirmed remote merge proof
+      def merged?
+        status == :merged
+      end
+
+      # @return [Hash] plain, JSON-serializable representation
+      def to_h
+        {
+          server_name: server_name,
+          status: status,
+          pr_number: pr_number,
+          pr_url: pr_url,
+          head_sha: head_sha,
+          merge_commit_sha: merge_commit_sha
+        }
+      end
+    end
+  end
+end

data/lib/ace/git/providers.rb

@@ -0,0 +1,121 @@
+# 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.
+        #
+        # Provider packages register themselves when required. On a miss, the
+        # provider libraries listed in the `git.providers` configuration are
+        # required once (mono-repo default: both shipped provider gems) and
+        # the registry is re-checked; a still-missing provider is a classified
+        # failure, never a fallback.
+        #
+        # @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
+            require_configured_providers
+            provider_class = @mutex.synchronize { @registry[key] }
+          end
+          unless provider_class
+            raise UnknownProviderError,
+              "No provider registered for type #{key.inspect} (server '#{server.name}'); " \
+              "install the provider package that owns #{key.inspect} and list it in git.providers"
+          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 do
+            @registry.clear
+            @required_configured = {}
+          end
+        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
+
+        # Require the provider libraries configured under `git.providers`
+        # (e.g. "github" -> ace/git/github). Load failures are ignored here;
+        # a missing provider surfaces as UnknownProviderError at resolution.
+        def require_configured_providers
+          @required_configured ||= {}
+          Array(Ace::Git.config["providers"]).each do |name|
+            library = name.to_s.strip.downcase
+            next if library.empty? || @required_configured[library]
+
+            require "ace/git/#{library}"
+            @required_configured[library] = true
+          rescue LoadError
+            @required_configured[library] = true
+          end
+        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,202 @@
+# 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
+
+        # Resolve exactly one server for an operation from CLI-style selection.
+        #
+        # @param server_name [String, Symbol, nil] explicit configured server name
+        # @param use_default [Boolean] resolve the configured default server
+        # @param remote_name [String, nil] remote used when nothing is selected
+        # @return [ResolvedServer]
+        # @raise [ConfigError] when explicit selection and default conflict
+        # @raise [UnknownServerNameError, NoDefaultServerConfiguredError,
+        #   MultipleDefaultServersError, AmbiguousRemoteError] per resolution
+        def resolve_for(server_name: nil, use_default: false, remote_name: nil)
+          if server_name && use_default
+            raise ConfigError,
+              "Server selection is ambiguous: an explicit server ('#{server_name}') and " \
+              "the default-server request are mutually exclusive"
+          end
+
+          if server_name
+            resolve(server_name)
+          elsif use_default
+            resolve_default
+          else
+            resolve_remote(remote_name)
+          end
+        end
+
+        # Configured servers whose URL matches the repository URL exactly.
+        #
+        # @param repository_url [String] repository URL in any supported shape
+        # @return [Array<ResolvedServer>] matching servers (may be empty)
+        def matching_servers(repository_url)
+          entries.map(&:server).select { |server| Atoms::ServerUrl.match?(server.url, repository_url) }
+        end
+
+        # Configured servers whose repository path equals `owner/repo`
+        # (any host). Never assumes a forge hostname.
+        #
+        # @param owner_repo [String] "owner/repo"
+        # @return [Array<ResolvedServer>] matching servers (may be empty)
+        def servers_for_owner_repo(owner_repo)
+          wanted = owner_repo.to_s.downcase
+          entries.map(&:server).select do |server|
+            path = Atoms::ServerUrl.normalize(server.url).to_s.split("/", 2)[1]
+            path == wanted
+          end
+        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.1"
+    VERSION = "0.25.0"
   end
 end

data/lib/ace/git.rb

@@ -2,6 +2,7 @@
 
 require "ace/support/config"
 require_relative "git/version"
+require_relative "git/errors"
 
 module Ace
   module Git
@@ -12,14 +13,9 @@ module Ace
     # - 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 GhNotInstalledError < Error; end
-    class GhAuthenticationError < Error; end
-    class PrNotFoundError < Error; end
-    class TimeoutError < Error; end
+    # All custom exceptions inherit from Ace::Git::Error for consistent catching;
+    # they are defined in git/errors.rb (local git failures plus the forge server
+    # resolution and provider interaction taxonomy).
 
     # Mutex for thread-safe config initialization
     @config_mutex = Mutex.new
@@ -124,7 +120,7 @@ module Ace
       normalized = normalize_keys(git_section)
 
       # Copy top-level settings
-      %w[default_branch remote verbose timeout network_timeout].each do |key|
+      %w[default_branch remote verbose timeout network_timeout servers providers].each do |key|
         config[key] = normalized[key] if normalized.key?(key)
       end
 
@@ -170,7 +166,7 @@ module Ace
       config["timeout"] || 30
     end
 
-    # Timeout for network operations (gh CLI, remote operations)
+    # Timeout for network operations (provider CLIs, remote operations)
     # @return [Integer] Timeout in seconds (default: 60)
     def self.network_timeout
       config["network_timeout"] || 60
@@ -198,6 +194,9 @@ end
 
 # Require ATOM architecture components
 require_relative "git/atoms/command_executor"
+require_relative "git/atoms/server_url"
+require_relative "git/atoms/pr_reference"
+require_relative "git/atoms/pr_identifier"
 require_relative "git/atoms/pattern_filter"
 require_relative "git/atoms/diff_parser"
 require_relative "git/atoms/diff_numstat_parser"
@@ -205,7 +204,6 @@ require_relative "git/atoms/file_grouper"
 require_relative "git/atoms/grouped_stats_formatter"
 require_relative "git/atoms/date_resolver"
 require_relative "git/atoms/task_pattern_extractor"
-require_relative "git/atoms/pr_identifier_parser"
 require_relative "git/atoms/repository_state_detector"
 require_relative "git/atoms/repository_checker"
 require_relative "git/atoms/git_scope_filter"
@@ -218,14 +216,17 @@ require_relative "git/molecules/diff_generator"
 require_relative "git/molecules/config_loader"
 require_relative "git/molecules/diff_filter"
 require_relative "git/molecules/branch_reader"
-require_relative "git/molecules/pr_metadata_fetcher"
 require_relative "git/molecules/recent_commits_fetcher"
 require_relative "git/molecules/git_status_fetcher"
-require_relative "git/molecules/gh_cli_executor"
-require_relative "git/molecules/github_issue_sync"
 
 require_relative "git/organisms/diff_orchestrator"
 require_relative "git/organisms/repo_status_loader"
+require_relative "git/organisms/pull_request_lifecycle"
+require_relative "git/resolved_server"
+require_relative "git/server_registry"
+require_relative "git/providers/base"
+require_relative "git/providers/evidence"
+require_relative "git/providers"
 
 require_relative "git/models/diff_result"
 require_relative "git/models/diff_config"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-git
 version: !ruby/object:Gem::Version
-  version: 0.23.1
+  version: 0.25.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-05 00:00:00.000000000 Z
+date: 2026-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-config
@@ -94,8 +94,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '13.0'
 description: ace-git gives developers and coding agents focused git context commands
-  and guided workflows for rebases, pull requests, and commit reorganization, with
-  smart diff output and Git 2.23+ guardrails.
+  and guided workflows for rebases and commit reorganization, with smart diff output,
+  a forge server registry, and a provider contract backed by pluggable provider gems.
 email:
 - mc@cs3b.com
 executables:
@@ -149,9 +149,11 @@ files:
 - lib/ace/git/atoms/grouped_stats_formatter.rb
 - lib/ace/git/atoms/lock_error_detector.rb
 - lib/ace/git/atoms/pattern_filter.rb
-- lib/ace/git/atoms/pr_identifier_parser.rb
+- lib/ace/git/atoms/pr_identifier.rb
+- lib/ace/git/atoms/pr_reference.rb
 - lib/ace/git/atoms/repository_checker.rb
 - lib/ace/git/atoms/repository_state_detector.rb
+- lib/ace/git/atoms/server_url.rb
 - lib/ace/git/atoms/stale_lock_cleaner.rb
 - lib/ace/git/atoms/status_formatter.rb
 - lib/ace/git/atoms/task_pattern_extractor.rb
@@ -161,6 +163,7 @@ files:
 - lib/ace/git/cli/commands/diff.rb
 - lib/ace/git/cli/commands/pr.rb
 - lib/ace/git/cli/commands/status.rb
+- lib/ace/git/errors.rb
 - lib/ace/git/models/diff_config.rb
 - lib/ace/git/models/diff_result.rb
 - lib/ace/git/models/repo_status.rb
@@ -168,22 +171,25 @@ files:
 - lib/ace/git/molecules/config_loader.rb
 - lib/ace/git/molecules/diff_filter.rb
 - lib/ace/git/molecules/diff_generator.rb
-- lib/ace/git/molecules/gh_cli_executor.rb
 - lib/ace/git/molecules/git_status_fetcher.rb
-- lib/ace/git/molecules/github_issue_sync.rb
-- lib/ace/git/molecules/pr_metadata_fetcher.rb
 - lib/ace/git/molecules/recent_commits_fetcher.rb
 - lib/ace/git/organisms/diff_orchestrator.rb
+- lib/ace/git/organisms/pull_request_lifecycle.rb
 - lib/ace/git/organisms/repo_status_loader.rb
+- lib/ace/git/providers.rb
+- lib/ace/git/providers/base.rb
+- lib/ace/git/providers/evidence.rb
+- lib/ace/git/resolved_server.rb
+- lib/ace/git/server_registry.rb
 - lib/ace/git/version.rb
-homepage: https://github.com/cs3b/ace/tree/main/ace-git
+homepage: https://forgejo.tail6c0887.ts.net/cs3b/ace
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/cs3b/ace/tree/main/ace-git
-  source_code_uri: https://github.com/cs3b/ace/tree/main/ace-git/
-  changelog_uri: https://github.com/cs3b/ace/blob/main/ace-git/CHANGELOG.md
+  homepage_uri: https://forgejo.tail6c0887.ts.net/cs3b/ace
+  source_code_uri: https://forgejo.tail6c0887.ts.net/cs3b/ace/src/branch/main/ace-git
+  changelog_uri: https://forgejo.tail6c0887.ts.net/cs3b/ace/src/branch/main/ace-git/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -200,5 +206,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Git workflows and context commands for developers and AI agents
+summary: Forge-neutral Git workflows and context commands for developers and AI agents
 test_files: []