ace-git 0.26.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b306e7eeb68db0b211dead9498aabdeba48ca866b13a3710a886193232d310a
-  data.tar.gz: db3448da7471947520a0aa68f70c56283f3539412456b221809ab7cd0349f976
+  metadata.gz: 8f05486971c36b968a3eeeb42f4bfdeda24b0a3d672732dd5ff532ab4a7db034
+  data.tar.gz: 21fe708e731585aba811f719acc8705b906b2c2e11cf249f9d5279223890ea69
 SHA512:
-  metadata.gz: 0af17d14185c802e2a72f1f93c99054ea31d77ff86e3e2fd62adc2f30a99d3384dbc1f1f64de41ede47175f19ba334843ed553e775770839c41b3fc6a8232372
-  data.tar.gz: 6a5229b535fe9a4c586d1fd2e332daf90b57b0f91a899727cc677e3750aff38d55eb58f010ba1363e3956227b5f0f51879128f1bf18effac22f47236afbb53f1
+  metadata.gz: a4439500ea545b8c557af9e6b436852b14bebec56f4e44b4f36c72c005851d72d29256cef3a70fcff6de50900bc2e101d5f55ef93a7b48c850b69c200157ddca
+  data.tar.gz: 705d2d95b952af1c2bd44a8da79b1173210b00313744c3dbd554b9d22d76983534b5db3552655a8fd797584accc4c774b205bb5710cb8e8b0fd61ddddf0fc80e

data/CHANGELOG.md

@@ -7,13 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.27.0] - 2026-10-03
+
+### Added
+- Forge-neutral issue tracking contract with named-server selection, normalized issue evidence, and classified provider failures.
+
+### Fixed
+- Scheme-less server URLs with numeric ports (forge.example:8443/owner/repo) keep the port in the derived web endpoint instead of parsing it as an scp-style repo path.
+
 ## [0.26.0] - 2026-10-02
 
 ### Added
 - Normalized PR comment and review evidence, comment mutation receipts, and guarded review snapshots with exact repository and head identity.
 - Recheck PR heads around collection and before review comments or thread mutations; classify unsupported capabilities and uncertain post outcomes.
 
-
 ## [0.25.0] - 2026-09-28
 
 ### Added

data/docs/usage.md

@@ -282,10 +282,14 @@ the provider contract (`Ace::Git::Providers::Base`), and normalized evidence typ
 provider packages own all forge CLI behavior:
 
 - **ace-git-github** - GitHub behavior via the `gh` CLI (PR lookups, diffs, issue
-  synchronization). Registers under the `github` provider type.
+  tracking operations). Registers under the `github` provider type.
 - **ace-git-forgejo** - Forgejo behavior via the `fj` CLI. Registers under the
   `forgejo` provider type.
 
+Both providers implement the same issue-tracking contract (issue lookup, comment
+create/update/delete, label add/remove, state transitions) so task issue
+synchronization stays forge-neutral; `ace-task` owns the sync orchestration.
+
 Configure servers in `.ace/git.yml` (or project config) under `git.servers`, then
 resolve them by name, by default, or from a git remote URL. Every failure path is
 classified (missing CLI, unauthenticated, unreachable, malformed output, object

data/lib/ace/git/atoms/server_url.rb

@@ -38,6 +38,46 @@ module Ace
           text.chomp("/").downcase
         end
 
+        # Derive the HTTP(S) web endpoint for a configured server URL.
+        # HTTPS/HTTP URLs keep their scheme and authority; SSH-style URLs
+        # (scp-style "git@host:path", "ssh://") map to https web endpoints.
+        #
+        # @param url [String] configured server URL
+        # @return [String] web base without trailing slash or .git suffix
+        def self.web_base(url)
+          text = url.to_s.strip
+          scheme = text[/\A(https?):\/\//i, 1]&.downcase
+          rest = text.sub(/\A[a-z][a-z0-9+.\-]*:\/\//i, "").sub(/\A[^\/\s]+@/, "")
+          if scheme
+            authority, _, path = rest.partition("/")
+          elsif text.match?(/\Assh:\/\//i)
+            # ssh:// URLs separate the authority (with optional port) by slash.
+            rest = text.sub(/\Assh:\/\//i, "").sub(/\A[^\/\s]+@/, "")
+            authority, _, path = rest.partition("/")
+            authority = authority.split(":").first.to_s
+            scheme = "https"
+          else
+            host_part, sep, remainder = rest.partition(":")
+            if sep == ":" && remainder.match?(%r{\A\d+/})
+              # A numeric segment before the slash is an SSH-style port, not
+              # an scp repo path: keep it in the web authority.
+              authority = "#{host_part}:#{remainder.split("/", 2).first}"
+              path = remainder.split("/", 2).last
+            elsif sep == ":" && !remainder.start_with?("/")
+              # scp-style "git@host:path"; ssh ports ride the colon and are
+              # dropped from the web endpoint.
+              authority = host_part.split(":").first.to_s
+              path = remainder.sub(%r{\A\d+/}, "")
+            else
+              # Scheme-less "host/owner/repo" splits on the first slash.
+              authority, _, path = rest.partition("/")
+            end
+            scheme = "https"
+          end
+          path = path.sub(%r{/+\z}, "").sub(/\.git\z/i, "")
+          "#{scheme}://#{authority}/#{path}"
+        end
+
         # Compare a configured server URL against a remote URL for identity.
         #
         # @param server_url [String] configured server base URL

data/lib/ace/git/errors.rb

@@ -78,5 +78,10 @@ module Ace
     # failure after the send). Contains the exact base/head identity needed to
     # reconcile by lookup; never retried automatically.
     class ProviderUnknownOutcomeError < Error; end
+
+    # Reconciliation reads all completed and the tracked marker never
+    # appeared: authoritative absence of a prior create. The only outcome
+    # that may authorize a fresh create POST.
+    class ProviderReconcileAbsenceError < ProviderUnknownOutcomeError; end
   end
 end

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

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+module Ace
+  module Git
+    module Organisms
+      # One ACE task owns at most one exact remote issue. The provider handles
+      # transport; this service owns only the marker, label, and task lifecycle.
+      class IssueTracking
+        STICKY_MARKER = "<!-- ace-task:tracked -->"
+        RECONCILE_READ_ATTEMPTS = 3
+        RECONCILE_READ_INTERVAL_SECONDS = 1
+        CREATE_RECONCILE_READ_ATTEMPTS = 5
+        CREATE_RECONCILE_READ_INTERVAL_SECONDS = 2
+        TRACKED_LABEL = "ace:tracked"
+        TERMINAL_STATUSES = %w[done cancelled skipped].freeze
+
+        def initialize(provider:)
+          @provider = provider
+        end
+
+        def validate_link!(number:, task_id: nil, previous_task_id: nil)
+          snapshot = fetch(number)
+          owners = owned_task_ids(snapshot)
+          if sticky_comment(snapshot) && owners.empty?
+            raise ProviderMalformedOutputError, "Issue ##{number} has an ACE marker without a task owner"
+          end
+          accepted = [task_id, previous_task_id].compact.map(&:to_s).uniq
+          return snapshot if owners.empty? || (!accepted.empty? && owners.all? { |owner| accepted.include?(owner) })
+
+          raise ProviderIdentityMismatchError,
+            "Issue ##{number} is already owned by ACE task #{owners.join(', ')}"
+        end
+
+        def sync(number:, task_id:, task_link:, task_status:, previous_task_id: nil,
+          create_pending: false, before_create: nil, comment_only: false)
+          # Reparenting/promotion changes the local ID; the remote marker may
+          # still name the previous ID, or may already carry the new one when
+          # a prior sync failed partway. Both count as this task's ownership.
+          snapshot = validate_link!(number: number, task_id: task_id, previous_task_id: previous_task_id)
+          sticky = sticky_comment(snapshot)
+          desired_line = "Tracked in ace-task: [#{task_id}](#{task_link})"
+          desired_body = compose_tracking_body(sticky&.dig(:body), desired_line)
+          if sticky.nil?
+            if create_pending
+              # A prior create ended with an unknown outcome: this replay must
+              # reconcile (bounded extended reads), never issue a second POST.
+              resolved = CREATE_RECONCILE_READ_ATTEMPTS.times.any? do |attempt|
+                snapshot = fetch(number)
+                found = sticky_comment(snapshot)
+                break true if found&.[](:body) == desired_body
+
+                if found
+                  # The marker that just appeared may belong to another task
+                  # or be malformed; validate ownership before overwriting
+                  # anything (same guard as validate_link!).
+                  owners = owned_task_ids(snapshot)
+                  accepted = [task_id, previous_task_id].compact.map(&:to_s).uniq
+                  if (found && owners.empty?) || !owners.all? { |owner| accepted.include?(owner) }
+                    raise ProviderIdentityMismatchError,
+                      "Issue ##{number} is already owned by ACE task #{owners.join(', ')}"
+                  end
+                  desired_line = "Tracked in ace-task: [#{task_id}](#{task_link})"
+                  reconciled_body = compose_tracking_body(found[:body], desired_line)
+                  desired_body = reconciled_body
+                  mutate_and_reconcile(number, desired_body: reconciled_body) do
+                    @provider.update_issue_comment(number: number, comment_id: found[:id], body: reconciled_body)
+                  end
+                  break true
+                end
+                sleep(create_reconcile_interval(attempt))
+                false
+              end
+              raise ProviderReconcileAbsenceError,
+                "Prior tracking comment create for issue ##{number} is still unresolved" unless resolved
+            else
+              mutate_and_reconcile(number, desired_body: desired_body) do
+                # Persist the uncertain-create guard before the only
+                # non-idempotent call, so a stop after the POST leaves a
+                # durable reconcile record instead of a duplicate on replay.
+                before_create&.call
+                @provider.create_issue_comment(number: number, body: desired_body)
+              end
+            end
+          elsif sticky[:body] != desired_body
+            mutate_and_reconcile(number, desired_body: desired_body) do
+              @provider.update_issue_comment(number: number, comment_id: sticky[:id], body: desired_body)
+            end
+          end
+          verified = nil
+          unless comment_only
+            begin
+              snapshot = fetch(number)
+              unless snapshot[:labels].include?(TRACKED_LABEL)
+                mutate_and_reconcile(number, label: TRACKED_LABEL) do
+                  @provider.add_issue_label(number: number, label: TRACKED_LABEL)
+                end
+              end
+              desired_state = TERMINAL_STATUSES.include?(task_status.to_s) ? :closed : :open
+              snapshot = fetch(number)
+              unless snapshot[:issue].state == desired_state
+                mutate_and_reconcile(number, state: desired_state) do
+                  @provider.set_issue_state(number: number, state: desired_state)
+                end
+              end
+            rescue ProviderAuthenticationError, ProviderObjectNotFoundError => e
+              # The non-idempotent comment POST already committed, so a later
+              # definitive-looking failure cannot prove the create failed.
+              # Replay must reconcile the committed marker, never re-POST.
+              raise ProviderUnknownOutcomeError,
+                "post-create step failed after the tracking comment committed: #{e.class}: #{e.message}"
+            end
+            verified = fetch(number)
+            unless sticky_comment(verified)&.[](:body) == desired_body &&
+                verified[:labels].include?(TRACKED_LABEL) && verified[:issue].state == desired_state
+              raise ProviderMalformedOutputError, "Issue ##{number} did not reflect ACE tracking updates"
+            end
+          else
+            verified = fetch(number)
+            unless sticky_comment(verified)&.[](:body) == desired_body
+              raise ProviderMalformedOutputError, "Issue ##{number} did not reflect ACE tracking updates"
+            end
+          end
+          verified
+        end
+
+        # Clear only the task's marker/comment and ACE label. Issue state is
+        # intentionally untouched, even when it was changed by prior sync.
+        def clear(number:, task_id:, previous_task_id: nil)
+          snapshot = fetch(number)
+          owners = owned_task_ids(snapshot)
+          sticky = sticky_comment(snapshot)
+          if sticky && owners.empty?
+            raise ProviderMalformedOutputError, "Issue ##{number} has an ACE marker without a task owner"
+          end
+          accepted = [task_id, previous_task_id].compact.map(&:to_s).uniq
+          unless owners.empty? || (!accepted.empty? && owners.all? { |owner| accepted.include?(owner) })
+            raise ProviderIdentityMismatchError, "Issue ##{number} is owned by another ACE task"
+          end
+          if sticky
+            # Strip inline markers concatenated onto note lines (historical
+            # layout) so the rebuilt body verifies marker-free.
+            preserved = sticky[:body].to_s.lines
+              .reject { |line| line.chomp == STICKY_MARKER || line.start_with?("Tracked in ace-task: ") }
+              .map { |line| line.gsub(STICKY_MARKER, "") }
+            mutate_and_reconcile(number, absent_comment: true) do
+              if preserved.empty?
+                @provider.delete_issue_comment(number: number, comment_id: sticky[:id])
+              else
+                @provider.update_issue_comment(number: number, comment_id: sticky[:id], body: preserved.join)
+              end
+            end
+          end
+          snapshot = fetch(number)
+          if snapshot[:labels].include?(TRACKED_LABEL)
+            mutate_and_reconcile(number, absent_label: TRACKED_LABEL) do
+              @provider.remove_issue_label(number: number, label: TRACKED_LABEL)
+            end
+          end
+          verified = fetch(number)
+          if sticky_comment(verified) || verified[:labels].include?(TRACKED_LABEL)
+            raise ProviderMalformedOutputError, "Issue ##{number} still contains ACE tracking artifacts"
+          end
+          verified
+        end
+
+        private
+
+        # Unrelated lines are preserved verbatim (including trailing
+        # whitespace); only ACE-owned lines are ever added or removed. A
+        # marker concatenated onto a note line (historical layout) is
+        # stripped in place so clear can rebuild the body cleanly.
+        def compose_tracking_body(existing_body, desired_line)
+          preserved = existing_body.to_s.lines
+            .reject { |line| line.chomp == STICKY_MARKER || line.start_with?("Tracked in ace-task: ") }
+            .map { |line| line.gsub(STICKY_MARKER, "") }
+          prefix = preserved.join
+          prefix += "\n" unless prefix.empty? || prefix.end_with?("\n")
+          "#{prefix}#{STICKY_MARKER}\n#{desired_line}"
+        end
+
+        def create_reconcile_interval(attempt)
+          CREATE_RECONCILE_READ_INTERVAL_SECONDS * (attempt + 1)
+        end
+
+        def fetch(number)
+          snapshot = @provider.issue_tracking(number: number)
+          unless snapshot.is_a?(Hash) && snapshot[:issue]&.number.to_i == number.to_i &&
+              snapshot[:comments].is_a?(Array) && snapshot[:labels].is_a?(Array)
+            raise ProviderMalformedOutputError, "Incomplete issue tracking evidence for ##{number}"
+          end
+          # Pagination across capped pages can repeat comments; dedupe by id
+          # so duplicate pages never read as multiple ACE tracking comments.
+          seen_ids = []
+          snapshot = snapshot.merge(
+            comments: snapshot[:comments].reject do |comment|
+              if seen_ids.include?(comment[:id])
+                true
+              else
+                seen_ids << comment[:id]
+                false
+              end
+            end
+          )
+          snapshot
+        end
+
+        def sticky_comment(snapshot)
+          matches = snapshot[:comments].select { |comment| comment[:body].to_s.include?(STICKY_MARKER) }
+          if matches.length > 1
+            raise ProviderIdentityMismatchError, "Multiple ACE tracking comments on issue ##{snapshot[:issue].number}"
+          end
+          matches.first
+        end
+
+        def owned_task_ids(snapshot)
+          sticky = sticky_comment(snapshot)
+          return [] unless sticky
+
+          sticky[:body].to_s.lines.filter_map do |line|
+            line[/\ATracked in ace-task: \[([^\]]+)\]\(/, 1]
+          end.uniq
+        end
+
+        def mutate_and_reconcile(number, desired_body: nil, label: nil, state: nil,
+          absent_comment: false, absent_label: nil)
+          yield
+        rescue ProviderUnknownOutcomeError
+          begin
+            @reconcile_resolved = reconcile_outcome(number, desired_body: desired_body, label: label, state: state,
+              absent_comment: absent_comment, absent_label: absent_label)
+          rescue ProviderUnknownOutcomeError
+            raise
+          rescue StandardError => e
+            # The mutation outcome is still unknown when reconciliation reads
+            # fail (a 401/404 on a read says nothing about the write); keep
+            # the uncertainty so replay reconciles instead of duplicating.
+            raise ProviderUnknownOutcomeError,
+              "Mutation outcome unresolved; reconciliation read failed: #{e.class}"
+          end
+          raise unless @reconcile_resolved
+        end
+
+        def reconcile_outcome(number, desired_body: nil, label: nil, state: nil,
+          absent_comment: false, absent_label: nil)
+          resolved = RECONCILE_READ_ATTEMPTS.times.any? do |attempt|
+            snapshot = fetch(number)
+            outcome = if desired_body
+              sticky_comment(snapshot)&.[](:body) == desired_body
+            elsif label
+              snapshot[:labels].include?(label)
+            elsif state
+              snapshot[:issue].state == state
+            elsif absent_comment
+              sticky_comment(snapshot).nil?
+            elsif absent_label
+              !snapshot[:labels].include?(absent_label)
+            end
+            break outcome if outcome
+
+            # The forge may still be committing the write; an immediate read
+            # can miss it and a replay would then duplicate the mutation.
+            sleep(RECONCILE_READ_INTERVAL_SECONDS * (attempt + 1)) if desired_body
+            outcome
+          end
+          resolved
+        end
+      end
+    end
+  end
+end

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

@@ -89,6 +89,37 @@ module Ace
           raise NotImplementedError, "Providers must implement #{self.class}#issue"
         end
 
+        # Read the exact issue and its comments/labels for task tracking.
+        # Returns {issue: ProviderIssue, comments: [{id:, body:}], labels: [String]}.
+        # Every mutation below is scoped to this provider's resolved server.
+        def issue_tracking(number:)
+          raise NotImplementedError, "Providers must implement #{self.class}#issue_tracking"
+        end
+
+        def create_issue_comment(number:, body:)
+          raise NotImplementedError, "Providers must implement #{self.class}#create_issue_comment"
+        end
+
+        def update_issue_comment(number:, comment_id:, body:)
+          raise NotImplementedError, "Providers must implement #{self.class}#update_issue_comment"
+        end
+
+        def delete_issue_comment(number:, comment_id:)
+          raise NotImplementedError, "Providers must implement #{self.class}#delete_issue_comment"
+        end
+
+        def add_issue_label(number:, label:)
+          raise NotImplementedError, "Providers must implement #{self.class}#add_issue_label"
+        end
+
+        def remove_issue_label(number:, label:)
+          raise NotImplementedError, "Providers must implement #{self.class}#remove_issue_label"
+        end
+
+        def set_issue_state(number:, state:)
+          raise NotImplementedError, "Providers must implement #{self.class}#set_issue_state"
+        end
+
         # Fetch check/CI status evidence for a reference.
         #
         # @param ref [String] commit sha or branch name

data/lib/ace/git/server_registry.rb

@@ -129,7 +129,20 @@ module Ace
         # @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) }
+          supplied = repository_url.to_s
+          supplied_scheme = supplied[/\A([a-z][a-z0-9+.\-]*):\/\//i, 1]&.downcase
+          entries.map(&:server).select do |server|
+            # Compare the derived web endpoint so SSH clone URLs (including
+            # custom SSH ports) match their HTTPS issue URLs.
+            next false unless Atoms::ServerUrl.match?(Atoms::ServerUrl.web_base(server.url), supplied)
+            next true if supplied_scheme.nil?
+
+            # An explicit issue-URL scheme must not downgrade to a server
+            # serving the same host/path over a weaker scheme. SSH-configured
+            # clones serve their web endpoint over HTTPS.
+            server_scheme = Atoms::ServerUrl.web_base(server.url)[/\A(https?):\/\//i, 1]&.downcase
+            server_scheme == supplied_scheme
+          end
         end
 
         # Configured servers whose repository path equals `owner/repo`

data/lib/ace/git/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Git
-    VERSION = "0.26.0"
+    VERSION = "0.27.0"
   end
 end

data/lib/ace/git.rb

@@ -222,6 +222,7 @@ require_relative "git/molecules/git_status_fetcher"
 require_relative "git/organisms/diff_orchestrator"
 require_relative "git/organisms/repo_status_loader"
 require_relative "git/organisms/pull_request_lifecycle"
+require_relative "git/organisms/issue_tracking"
 require_relative "git/resolved_server"
 require_relative "git/server_registry"
 require_relative "git/providers/base"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-git
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.27.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-02 00:00:00.000000000 Z
+date: 2026-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-config
@@ -174,6 +174,7 @@ files:
 - lib/ace/git/molecules/git_status_fetcher.rb
 - lib/ace/git/molecules/recent_commits_fetcher.rb
 - lib/ace/git/organisms/diff_orchestrator.rb
+- lib/ace/git/organisms/issue_tracking.rb
 - lib/ace/git/organisms/pull_request_lifecycle.rb
 - lib/ace/git/organisms/repo_status_loader.rb
 - lib/ace/git/providers.rb