ace-git-forgejo 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8a35836d33fbf6fc14e52f4c27ef396244d1f809bc919ceca6ac0202db5e583
-  data.tar.gz: 548b2f7734d7f98ef2594e9630ddeb499ae9ead7f8c4297498ebe8726217c4a2
+  metadata.gz: e7388b7c2b27b633234131dca7f190a344c7e1f323e23e2e01b532ed3a16407a
+  data.tar.gz: 3960cdfc787b85500050589ac27b1a8bceb8d3e5cd594eb37db2448d7e314426
 SHA512:
-  metadata.gz: c19a8e1f44853f9c173e51118a42f1de9fd6ab04d77c01371c68f16d867f654b938f4cf5b252d8f7d4300c4bdcca826c53ed7dafddc6e616051fab8292aa457d
-  data.tar.gz: b312fbb4a37d5e871e55148f40e90951ebc2692c474d87e0052adb6beb0647fb24347b3599b914c7a4c7a93f9ca4726f201bd67301f4ba84ded528db979168da
+  metadata.gz: 77a634e5f5f9de6c004a2585e57379104062f11e6eee34532edb390c8200aeaba6d3fc3433ec21ccc6e6ee1a1a3aca22b47b99e83890982e9f8d4ef7400bd045
+  data.tar.gz: c13861e169c6bb26db7bde14c400186677f01c70c185bec7d07a374b6fdcde08717b27ef7233900da128072587af39393af5dc0584603085d0c8293eeba9aff1

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-03
+
+### Added
+- Forgejo issue tracking through the shared provider contract with selected-server authority checks and parsed issue evidence.
+
+### Fixed
+- Missing tracking labels are created on demand before attachment, forbidden organization-label listings fall back to repository labels, and fj credentials are found in the real macOS bundle directories (forgejo-cli.forgejo-cli, legacy Cyborus.forgejo-cli).
+
+## [0.4.0] - 2026-10-02
+
+### Added
+- Repository-bound Forgejo PR comment and review retrieval and comment create/update through the shared provider contract.
+- Correlation-based reconciliation after uncertain posts and explicit unsupported thread resolution.
+
 ## [0.3.0] - 2026-09-29
 
 ### Added

data/lib/ace/git/forgejo/http_client.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+require_relative "repository_binding"
+
+module Ace
+  module Git
+    module Forgejo
+      # Authenticated, repository-bound JSON transport for Forgejo API
+      # capabilities whose fj v0.6 output omits stable object IDs.
+      class HttpClient
+        def initialize(server:, timeout:, runner: nil)
+          @target = RepositoryBinding::Target.resolve(server.url)
+          @timeout = timeout
+          @runner = runner
+        end
+
+        def paginate(suffix)
+          page = 1
+          entries = []
+          seen_pages = {}
+          loop do
+            separator = suffix.include?("?") ? "&" : "?"
+            batch = request(:get, "#{suffix}#{separator}page=#{page}&limit=50")
+            unless batch.is_a?(Array)
+              raise Ace::Git::ProviderMalformedOutputError, "Forgejo #{suffix} did not return a list"
+            end
+            entries.concat(batch)
+            # A server may cap pages below the requested limit, so a short
+            # page is not proof of the end; stop only on an empty page and
+            # guard against servers repeating the same page forever.
+            break if batch.empty?
+            digest = Digest::SHA256.hexdigest(batch.to_s)
+            raise Ace::Git::ProviderMalformedOutputError,
+              "Forgejo #{suffix} pagination repeated page #{page}" if seen_pages[digest]
+
+            seen_pages[digest] = true
+            page += 1
+          end
+          entries
+        end
+
+        def request(method, suffix, body: nil)
+          RepositoryBinding.reject_selected_host_redirect!(@target.host_url)
+          path = "/api/v1/repos/#{@target.repo}/#{suffix}"
+          if @runner
+            result = @runner.call(args: ["forgejo-http", method.to_s.upcase, "#{@target.host_url}#{path}", body],
+              timeout: @timeout, env: {})
+            status = result[:status] || (result[:success] ? 200 : 503)
+            payload = result[:stdout].to_s
+          else
+            uri = URI.parse("#{@target.host_url}#{path}")
+            klass = {get: Net::HTTP::Get, post: Net::HTTP::Post, patch: Net::HTTP::Patch}.fetch(method)
+            req = klass.new(uri)
+            req["Authorization"] = "token #{access_token!}"
+            req["Accept"] = "application/json"
+            req["Content-Type"] = "application/json" if body
+            req.body = JSON.generate(body) if body
+            response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+              open_timeout: @timeout, read_timeout: @timeout) { |http| http.request(req) }
+            status = response.code.to_i
+            payload = response.body.to_s
+          end
+          classify_status!(status, method, path)
+          return nil if payload.empty?
+
+          JSON.parse(payload)
+        rescue JSON::ParserError => e
+          raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo response: #{e.message}"
+        rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, IOError, SocketError, OpenSSL::SSL::SSLError, SystemCallError => e
+          error = (method == :get) ? Ace::Git::ProviderUnreachableError : Ace::Git::ProviderUnknownOutcomeError
+          raise error, "Forgejo #{method} #{path} outcome unknown: #{e.class}"
+        end
+
+        private
+
+        def access_token!
+          path = RepositoryBinding.default_keys_path
+          data = path && JSON.parse(File.read(path))
+          # fj stores credentials under the bare host (or host:port)
+          # authority, never the scheme-prefixed URL.
+          login = data.is_a?(Hash) && data.fetch("hosts", {})[@target.authority]
+          token = login.is_a?(Hash) && login["token"]
+          return token if token.is_a?(String) && !token.empty?
+
+          raise Ace::Git::ProviderAuthenticationError,
+            "No fj token for selected host #{@target.authority}; authenticate with fj first"
+        rescue Errno::ENOENT, Errno::EACCES, JSON::ParserError
+          raise Ace::Git::ProviderAuthenticationError,
+            "Cannot read fj authentication for selected host #{@target.authority}"
+        end
+
+        def classify_status!(status, method, path)
+          return if (200..299).cover?(status.to_i)
+
+          error = case status.to_i
+          when 401, 403 then Ace::Git::ProviderAuthenticationError
+          when 404 then Ace::Git::ProviderObjectNotFoundError
+          when 409, 422 then Ace::Git::ProviderIdentityMismatchError
+          else (method == :get) ? Ace::Git::ProviderUnreachableError : Ace::Git::ProviderUnknownOutcomeError
+          end
+          raise error, "Forgejo #{method} #{path} returned HTTP #{status}"
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/forgejo/issue_api.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+require_relative "repository_binding"
+require "ace/git/atoms/server_url"
+
+module Ace
+  module Git
+    module Forgejo
+      # Structured issue operations unavailable through fj's output contract.
+      # Uses the same exact selected host and the token from fj's keys file.
+      class IssueApi
+        def initialize(server:, timeout:, runner: nil)
+          # Clone URLs may be SSH-style; the HTTP issue client always talks
+          # to the verified HTTPS web endpoint derived from that identity.
+          @target = RepositoryBinding::Target.resolve(Ace::Git::Atoms::ServerUrl.web_base(server.url))
+          @timeout = timeout
+          @runner = runner
+        end
+
+        def issue(number)
+          request(:get, "issues/#{number}")
+        end
+
+        def comments(number)
+          paginate("issues/#{number}/comments")
+        end
+
+        def create_comment(number, body)
+          request(:post, "issues/#{number}/comments", body: {body: body})
+        end
+
+        def update_comment(comment_id, body)
+          request(:patch, "issues/comments/#{comment_id}", body: {body: body})
+        end
+
+        def delete_comment(comment_id)
+          request(:delete, "issues/comments/#{comment_id}")
+        end
+
+        def add_label(number, label_id)
+          request(:post, "issues/#{number}/labels", body: {labels: [label_id]})
+        end
+
+        def remove_label(number, label_id)
+          request(:delete, "issues/#{number}/labels/#{label_id}")
+        end
+
+        def repository_labels(wanted: nil)
+          labels = paginate("labels")
+          # Repository labels satisfy the common case; the organization label
+          # listing is an extra request that can fail (403 org scope) and must
+          # not block linking when the wanted label is already available.
+          return labels if wanted && labels.any? { |entry| entry["name"] == wanted }
+
+          owner = @target.repo.split("/", 2).first
+          begin
+            labels + paginate("/api/v1/orgs/#{owner}/labels")
+          rescue Ace::Git::ProviderObjectNotFoundError, Ace::Git::ProviderAuthenticationError
+            # Organization labels are an optional supplement: 404 means no org
+            # scope exists and 401/403 mean the token cannot read it. Both
+            # leave the repository labels authoritative; errors from the
+            # repository-label request above still propagate.
+            labels
+          end
+        end
+
+        def create_repo_label(name:, color:)
+          request(:post, "labels", body: {name: name, color: color})
+        end
+
+        def set_state(number, state)
+          request(:patch, "issues/#{number}", body: {state: state.to_s})
+        end
+
+        private
+
+        def paginate(suffix)
+          page = 1
+          entries = []
+          seen = []
+          loop do
+            batch = request(:get, "#{suffix}?page=#{page}&limit=50")
+            unless batch.is_a?(Array)
+              raise Ace::Git::ProviderMalformedOutputError, "Forgejo #{suffix} did not return a list"
+            end
+            before = entries.length
+            # Stop when a page adds no new items (unique ids): instances
+            # may cap pages below the requested limit, so a short page alone
+            # does not prove the end of the collection.
+            fresh = batch.reject { |item| seen.include?(item["id"]) }
+            entries.concat(fresh)
+            fresh.each { |item| seen << item["id"] }
+            break if fresh.empty?
+
+            page += 1
+          end
+          entries
+        end
+
+        def request(method, suffix, body: nil)
+          RepositoryBinding.reject_selected_host_redirect!(@target.host_url)
+          path = suffix.start_with?("/api/v1/") ? suffix : "/api/v1/repos/#{@target.repo}/#{suffix}"
+          if @runner
+            result = @runner.call(args: ["forgejo-http", method.to_s.upcase, "#{@target.host_url}#{path}", body],
+              timeout: @timeout, env: {})
+            status = result[:status] || (result[:success] ? 200 : 503)
+            payload = result[:stdout].to_s
+          else
+            uri = URI.parse("#{@target.host_url}#{path}")
+            token = access_token!
+            klass = {get: Net::HTTP::Get, post: Net::HTTP::Post, patch: Net::HTTP::Patch,
+                     delete: Net::HTTP::Delete}.fetch(method)
+            req = klass.new(uri)
+            req["Authorization"] = "token #{token}"
+            req["Accept"] = "application/json"
+            req["Content-Type"] = "application/json" if body
+            req.body = JSON.generate(body) if body
+            response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+              open_timeout: @timeout, read_timeout: @timeout) { |http| http.request(req) }
+            status = response.code.to_i
+            payload = response.body.to_s
+          end
+          classify_status!(status, method, path)
+          return nil if payload.empty?
+
+          JSON.parse(payload)
+        rescue JSON::ParserError => e
+          raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo issue response: #{e.message}"
+        rescue Net::OpenTimeout, Net::ReadTimeout, IOError, SocketError, SystemCallError,
+               OpenSSL::SSL::SSLError => e
+          error = method == :get ? Ace::Git::ProviderUnreachableError : Ace::Git::ProviderUnknownOutcomeError
+          raise error, "Forgejo issue #{method} #{path} outcome unknown: #{e.class}"
+        end
+
+        def access_token!
+          path = RepositoryBinding.default_keys_path
+          data = path && JSON.parse(File.read(path))
+          login = data.is_a?(Hash) && data.fetch("hosts", {})[@target.authority]
+          token = login.is_a?(Hash) && login["token"]
+          return token if token.is_a?(String) && !token.empty?
+
+          raise Ace::Git::ProviderAuthenticationError,
+            "No fj token for selected host #{@target.host_url}; authenticate with fj first"
+        rescue Errno::ENOENT, Errno::EACCES, JSON::ParserError
+          raise Ace::Git::ProviderAuthenticationError,
+            "Cannot read fj authentication for selected host #{@target.host_url}"
+        end
+
+        def classify_status!(status, method, path)
+          return if (200..299).cover?(status.to_i)
+
+          error = case status.to_i
+          when 401, 403 then Ace::Git::ProviderAuthenticationError
+          when 404 then Ace::Git::ProviderObjectNotFoundError
+          # A conflict on a mutation does not prove ownership was rejected
+          # before the write: earlier requests in the same sync may already
+          # have committed (e.g. the tracking comment). Uncertainty keeps the
+          # local recovery identity instead of deleting the task.
+          when 409, 422 then method == :get ? Ace::Git::ProviderIdentityMismatchError : Ace::Git::ProviderUnknownOutcomeError
+          else method == :get ? Ace::Git::ProviderUnreachableError : Ace::Git::ProviderUnknownOutcomeError
+          end
+          raise error, "Forgejo issue #{method} #{path} returned HTTP #{status}"
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/forgejo/parsers.rb

@@ -116,18 +116,54 @@ module Ace
         #
         # @return [Array<Hash>] {name:, state:, sha:}
         def self.parse_actions_tasks(text)
-          text.to_s.lines.map { |line| clean(line) }.filter_map do |line|
+          tasks = []
+          declared_count = nil
+          text.to_s.lines.map { |line| clean(line) }.reject(&:empty?).each do |line|
+            # `fj` emits exactly one leading "<n> tasks" count header
+          # before task lines; require it (including 0 tasks).
+            if (header = line.match(/\A(\d+) tasks?\z/i))
+              raise Ace::Git::ProviderMalformedOutputError,
+                "Duplicate `fj actions tasks` count header" if declared_count
+              declared_count = header[1].to_i
+              next
+            end
+            raise Ace::Git::ProviderMalformedOutputError,
+              "Missing `fj actions tasks` count header" unless declared_count
+
             match = line.match(
-              /\A#(?<task>\d+)\s+\((?<sha>[0-9a-f]+)\)\s+(?<state>\w+)\s+(?<name>.+?)\s+[\dhms.]+\s+\((?:push|pull_request|schedule)\)/
+              /\A#(?<task>\d+)\s+\((?<sha>[0-9a-f]+)\)\s+(?<state>\w+)\s+(?<name>.+?)\s+[\dhms.]+\s+\((?<event>[^)]+)\)/
             )
-            next nil unless match
-
-            {
+            # Any other nonempty line that cannot be parsed must not silently
+            # shrink check evidence; fail closed instead. The SHA may be
+            # abbreviated; the provider binds it to the reviewed head by
+            # prefix, so anything shorter than Git's conventional minimum
+            # abbreviation cannot establish commit identity and is rejected.
+            raise Ace::Git::ProviderMalformedOutputError,
+              "Unrecognized `fj actions tasks` output line: #{line[0, 80]}" unless match
+            unless match[:sha].length.between?(7, 40)
+              raise Ace::Git::ProviderMalformedOutputError,
+                "Unbindable `fj actions tasks` SHA (need 7-40 hex chars): #{match[:sha]}"
+            end
+
+            tasks << {
               name: match[:name],
               state: match[:state].downcase.to_sym,
               sha: match[:sha]
             }
           end
+          # Empty or whitespace-only output never reaches the in-loop header
+          # check; the contract requires the count header even for zero tasks,
+          # so fail closed instead of returning an empty task list.
+          raise Ace::Git::ProviderMalformedOutputError,
+            "Missing `fj actions tasks` count header" unless declared_count
+          # A declared count that disagrees with the parsed rows means
+          # truncated output; fail closed instead of accepting partial
+          # check evidence.
+          if declared_count != tasks.length
+            raise Ace::Git::ProviderMalformedOutputError,
+              "Incomplete `fj actions tasks` output: declared #{declared_count}, parsed #{tasks.length}"
+          end
+          tasks
         end
 
         # Parse `fj repo view` output.

data/lib/ace/git/forgejo/provider.rb

@@ -4,6 +4,7 @@ require "json"
 require "uri"
 require_relative "cli_executor"
 require_relative "parsers"
+require_relative "issue_api"
 
 module Ace
   module Git
@@ -20,6 +21,9 @@ module Ace
       # `fj` failures are never hidden behind ad-hoc curl calls or silent
       # fallbacks.
       class Provider < Ace::Git::Providers::Base
+        # Fill color for repo labels created on demand by issue linking.
+        TRACKED_LABEL_COLOR = "0e8a16"
+
         class << self
           def display_name
             "Forgejo"
@@ -109,11 +113,94 @@ module Ace
           )
         end
 
+        def issue_tracking(number:)
+          data = issue_api.issue(request_number!(number))
+          unless data.is_a?(Hash) && data["number"].to_i == number.to_i &&
+              data["html_url"].to_s == issue_url(number.to_i)
+            raise Ace::Git::ProviderIdentityMismatchError, "Issue ##{number} is not in #{server.url}"
+          end
+          evidence = Ace::Git::ProviderIssue.new(
+            server_name: server.name, number: data["number"], title: data["title"],
+            state: normalize_state(data["state"]),
+            author: data.dig("user", "login"), url: data["html_url"],
+            labels: Array(data["labels"]).map { |label| label["name"] }
+          )
+          {issue: evidence,
+           comments: Array(issue_api.comments(number)).map { |c| {id: c.fetch("id"), body: c["body"].to_s} },
+           labels: evidence.labels}
+        end
+
+        # Unrecognized or missing state is malformed evidence: mapping it to
+        # :closed would let sync close an issue without valid state proof.
+        def normalize_state(value)
+          case value.to_s
+          when "open" then :open
+          when "closed" then :closed
+          else raise Ace::Git::ProviderMalformedOutputError, "Unknown issue state #{value.inspect}"
+          end
+        end
+
+        def create_issue_comment(number:, body:)
+          issue_api.create_comment(request_number!(number), body)
+        end
+
+        def update_issue_comment(number:, comment_id:, body:)
+          assert_issue_comment_owned!(number, comment_id)
+          issue_api.update_comment(Integer(comment_id), body)
+        end
+
+        def delete_issue_comment(number:, comment_id:)
+          assert_issue_comment_owned!(number, comment_id)
+          issue_api.delete_comment(Integer(comment_id))
+        end
+
+        def add_issue_label(number:, label:)
+          issue_api.add_label(request_number!(number), ensure_repo_label_id(label))
+        end
+
+        def remove_issue_label(number:, label:)
+          match = Array(issue_api.repository_labels(wanted: label)).find { |entry| entry["name"] == label }
+          return unless match
+
+          issue_api.remove_label(request_number!(number), match.fetch("id"))
+        end
+
+        # Fresh repositories lack the tracking label; creating it on demand
+        # keeps issue linking from committing a tracking comment it could
+        # never label. A concurrent creator surfaces as an uncertain mutation
+        # outcome, which only means re-list and attach what appeared.
+        def ensure_repo_label_id(label)
+          match = Array(issue_api.repository_labels(wanted: label)).find { |entry| entry["name"] == label }
+          return match["id"] if match && match["id"].to_i.positive?
+
+          begin
+            issue_api.create_repo_label(name: label, color: TRACKED_LABEL_COLOR)
+          rescue Ace::Git::ProviderUnknownOutcomeError
+            nil
+          end
+          match = Array(issue_api.repository_labels(wanted: label)).find { |entry| entry["name"] == label }
+          unless match && match["id"].to_i.positive?
+            raise Ace::Git::ProviderObjectNotFoundError,
+              "Forgejo label #{label.inspect} could not be created or found on #{server.url}"
+          end
+          match["id"]
+        end
+
+        def set_issue_state(number:, state:)
+          raise ArgumentError, "Invalid issue state #{state.inspect}" unless %i[open closed].include?(state)
+
+          issue_api.set_state(request_number!(number), state)
+        end
+
         # @return [Array<ProviderCheck>] normalized check evidence for a ref
         def checks(ref:)
           tasks = fj(:actions_tasks)
           Parsers.parse_actions_tasks(tasks)
-            .select { |task| task[:sha].start_with?(ref.to_s) || ref.to_s.start_with?(task[:sha]) }
+            # Exact-head evidence binds each task to the reviewed head by SHA
+            # prefix: a full or abbreviated SHA that prefixes the reviewed
+            # head identifies that commit, and anything else is another
+            # head's task. No matching evidence is silently dropped.
+            .select { |task| ref.to_s.downcase.start_with?(task[:sha].downcase) }
             .map do |task|
               Ace::Git::ProviderCheck.new(
                 server_name: server.name,
@@ -123,6 +210,13 @@ module Ace
                 url: nil
               )
             end
+        rescue Ace::Git::ProviderObjectNotFoundError
+          # A repository with Actions disabled serves no tasks endpoint. The
+          # review flows resolve the repository binding and the PR before
+          # collecting checks, so a not-found here means CI is unavailable,
+          # not a missing repository; empty check evidence keeps the review
+          # collectable. Parse and transport failures still fail closed.
+          []
         end
 
         # @return [ProviderRepository] normalized repository evidence
@@ -142,6 +236,201 @@ module Ace
           )
         end
 
+        # The fj CLI surface omits the PR body; the repository-bound API
+        # supplies it for review evidence. Malformed payloads fail closed.
+        def pull_request_body(number:)
+          number = request_number!(number)
+          data = review_http.request(:get, "pulls/#{number}")
+          unless data.is_a?(Hash) && data["number"] == number && data.key?("body") &&
+                    (data["body"].nil? || data["body"].is_a?(String))
+            raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo PR body evidence"
+          end
+          data["body"]
+        end
+
+        def pull_request_review_evidence(number:, expected_head:)
+          number = request_number!(number)
+          verify_expected_head!(pull_request(number: number), expected_head)
+          comments = review_http.paginate("issues/#{number}/comments").map do |entry|
+            review_comment(entry, number, expected_head)
+          end
+          reviews = review_http.paginate("pulls/#{number}/reviews").map do |entry|
+            review_entry(entry, number, expected_head)
+          end
+          # Review comments live under each review, not at the PR level.
+          inline = reviews.flat_map do |review|
+            # The per-review endpoint returns the complete list (no
+            # pagination); a repeated nonempty page would trip the loop
+            # guard, so fetch once and require an array.
+            entries = review_http.request(:get, "pulls/#{number}/reviews/#{review.id}/comments")
+            unless entries.is_a?(Array)
+              raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo review comment evidence"
+            end
+            entries.map { |entry| review_comment(entry, number, expected_head) }
+          end
+          verify_expected_head!(pull_request(number: number), expected_head)
+          Ace::Git::ProviderReviewEvidence.new(
+            server_name: server.name, repository_url: server.url,
+            pr_number: number, head_sha: expected_head,
+            comments: comments + inline, reviews: reviews
+          )
+        end
+
+        def pull_request_review_details(number:)
+          number = request_number!(number)
+          data = review_http.request(:get, "pulls/#{number}")
+          files = review_http.paginate("pulls/#{number}/files").map do |entry|
+            entry.is_a?(Hash) && entry["filename"]
+          end
+          unless data.is_a?(Hash) && data["base"].is_a?(Hash) && data["number"] == number &&
+              data.dig("base", "sha").to_s.match?(/\A[0-9a-f]{40}\z/) &&
+              data["changed_files"].is_a?(Integer) && data["changed_files"] == files.length &&
+              files.all? { |path| path.is_a?(String) && !path.empty? }
+            raise Ace::Git::ProviderMalformedOutputError, "Malformed or incomplete Forgejo PR file evidence"
+          end
+          Ace::Git::ProviderReviewDetails.new(
+            server_name: server.name, repository_url: server.url, pr_number: number,
+            base_sha: data.dig("base", "sha"), files: files
+          )
+        end
+
+        def pull_request_checks(number:, head_sha:)
+          verify_expected_head!(pull_request(number: number), head_sha)
+          checks(ref: head_sha)
+        end
+
+        def repository_file(path:, ref:)
+          require "base64"
+          # %20, not form encoding: "+" in a path segment is a literal plus.
+          # Explicit unreserved-character allowlist: percent-encode
+          # everything else (DEFAULT_PARSER leaves ? and + ambiguous).
+          escaped = path.split("/").map { |part|
+            part.gsub(/[^A-Za-z0-9._~!$&'()*+,;=@:-]/) { |c| c.bytes.map { |b| format("%%%02X", b) }.join }
+          }.join("/")
+          data = review_http.request(:get, "contents/#{escaped}?ref=#{ref}")
+          unless data.is_a?(Hash) && data["encoding"] == "base64" && data["content"].is_a?(String)
+            raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo repository file evidence"
+          end
+          Base64.strict_decode64(data["content"].delete("\n"))
+        rescue ArgumentError => e
+          raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo repository file content: #{e.message}"
+        end
+
+        def create_pull_request_comment(number:, expected_head:, body:, correlation:)
+          number = request_number!(number)
+          pr = verify_expected_head!(pull_request(number: number), expected_head)
+          require_open_pr!(pr)
+          marker = comment_marker(correlation)
+          with_session_lock(correlation) do
+          existing = matching_review_comments(number, marker, expected_head)
+          if existing.length > 1
+            raise Ace::Git::ProviderConflictingMatchesError,
+              "Multiple comments match review session #{correlation} on PR ##{number}"
+          end
+          if existing.one?
+            # A repeat reconciles only the exact session comment; a marker
+            # match with different content is a conflict, never our post.
+            sent = "#{body}\n\n#{marker}"
+            if existing.first.body == sent
+              verify_post_mutation_head!(number, expected_head, correlation)
+              return review_mutation(number, expected_head, existing.first, :existing)
+            end
+
+            raise Ace::Git::ProviderConflictingMatchesError,
+              "Review session #{correlation} comment exists on PR ##{number} with different content"
+          end
+          second = verify_expected_head!(pull_request(number: number), expected_head)
+          require_open_pr!(second)
+          begin
+            review_http.request(:post, "issues/#{number}/comments", body: {body: "#{body}\n\n#{marker}"})
+          rescue Ace::Git::ProviderMalformedOutputError => e
+            raise Ace::Git::ProviderUnknownOutcomeError,
+              "PR comment sent but response unreadable for #{server.name}/#{number}, head #{expected_head}, session #{correlation}: #{e.message}; reconcile before repeating"
+          rescue Ace::Git::ProviderUnknownOutcomeError => e
+            raise Ace::Git::ProviderUnknownOutcomeError,
+              "PR comment outcome unknown for #{server.name}/#{number}, head #{expected_head}, " \
+              "session #{correlation}: #{e.message}; reconcile before repeating"
+          end
+          begin
+          matches = matching_review_comments(number, marker, expected_head)
+          rescue Ace::Git::ProviderMalformedOutputError, Ace::Git::ProviderAuthenticationError, Ace::Git::ProviderObjectNotFoundError, Ace::Git::ProviderUnreachableError => e
+            raise Ace::Git::ProviderUnknownOutcomeError,
+              "PR comment sent but reconciliation read failed for session #{correlation}: #{e.message}; reconcile before repeating"
+          end
+          unless matches.one? && matches.first.body == "#{body}\n\n#{marker}"
+            raise Ace::Git::ProviderUnknownOutcomeError,
+              "PR comment sent but reconciliation found #{matches.length} exact-content match(es) for session #{correlation}"
+          end
+          verify_post_mutation_head!(number, expected_head, correlation)
+          review_mutation(number, expected_head, matches.first, :created)
+          end
+        end
+
+        def update_pull_request_comment(number:, expected_head:, comment_id:, body:)
+          number = request_number!(number)
+          comment_id = Integer(comment_id)
+          verify_expected_head!(pull_request(number: number), expected_head)
+          issue_matches = review_http.paginate("issues/#{number}/comments").select { |entry| entry["id"] == comment_id }
+          # Inline ids live under individual reviews; locate them there
+          # so an unsupported edit is classified explicitly instead of
+          # being misread as not-belonging to this PR.
+          inline_found = issue_matches.empty? && review_comment_ids(number).include?(comment_id)
+          if inline_found
+            raise Ace::Git::ProviderUnsupportedCapabilityError,
+              "Editing inline review comments is unsupported by the observed fj v0.6.0 surface (comment #{comment_id})"
+          end
+          matches = issue_matches
+          update_route = "issues/comments/#{comment_id}"
+          unless matches.one?
+            raise Ace::Git::ProviderIdentityMismatchError,
+              "Comment #{comment_id} does not belong to selected PR ##{number}"
+          end
+          comment = review_comment(matches.first, number, expected_head)
+          if comment.body == body
+            verify_post_mutation_head!(number, expected_head, "comment #{comment_id}")
+            return review_mutation(number, expected_head, comment, :existing)
+          end
+
+          verify_expected_head!(pull_request(number: number), expected_head)
+          begin
+            review_http.request(:patch, update_route, body: {body: body})
+          rescue Ace::Git::ProviderMalformedOutputError => e
+            raise Ace::Git::ProviderUnknownOutcomeError,
+              "Comment update sent but response unreadable for #{server.name}/#{number}, comment #{comment_id}: #{e.message}; reconcile before repeating"
+          rescue Ace::Git::ProviderUnknownOutcomeError => e
+            raise Ace::Git::ProviderUnknownOutcomeError,
+              "Comment update outcome unknown for #{server.name}/#{number}, " \
+              "head #{expected_head}, comment #{comment_id}: #{e.message}"
+          end
+          begin
+            # Fetch individually and validate the Forgejo issue identity.
+            begin
+              updated = review_http.request(:get, update_route)
+            rescue Ace::Git::ProviderMalformedOutputError, Ace::Git::ProviderAuthenticationError, Ace::Git::ProviderObjectNotFoundError, Ace::Git::ProviderUnreachableError => e
+              raise Ace::Git::ProviderUnknownOutcomeError,
+                "Comment update sent but verification read failed for comment #{comment_id}: #{e.message}; reconcile before repeating"
+            end
+            unless updated.is_a?(Hash) && updated["issue_url"].to_s.end_with?("/#{number}")
+              raise Ace::Git::ProviderUnknownOutcomeError,
+                "Comment update sent but edited comment #{comment_id} does not verify against PR ##{number}; reconcile before repeating"
+            end
+          rescue Ace::Git::ProviderUnreachableError => e
+            raise Ace::Git::ProviderUnknownOutcomeError,
+              "Comment update sent but verification read failed for comment #{comment_id}: #{e.message}; reconcile before repeating"
+          end
+          unless updated && updated["id"] == comment_id && updated["body"] == body
+            raise Ace::Git::ProviderUnknownOutcomeError,
+              "Comment update sent but exact PR comment #{comment_id} could not be verified"
+          end
+          verify_post_mutation_head!(number, expected_head, "comment #{comment_id}")
+          review_mutation(number, expected_head, review_comment(updated, number, expected_head), :updated)
+        end
+
+        def resolve_pull_request_thread(number:, expected_head:, thread_id:)
+          raise Ace::Git::ProviderUnsupportedCapabilityError,
+            "Forgejo does not expose an observed repository-bound review thread resolution capability"
+        end
+
         # ---- PR lifecycle mutations ----
 
         # @return [Array<ProviderPullRequest>] open PRs matching the exact
@@ -233,6 +522,135 @@ module Ace
 
         private
 
+        def require_open_pr!(pr)
+          return if pr.state == :open
+
+          raise Ace::Git::ProviderUnsupportedCapabilityError,
+            "Cannot post review comment to PR ##{pr.number} in #{pr.state} state"
+        end
+
+        def review_http
+          @review_http ||= HttpClient.new(server: server, timeout: timeout, runner: runner)
+        end
+
+  # A mutation receipt may only bind the expected head; if the PR head
+  # moved during the mutation the outcome stays uncertain.
+  def verify_post_mutation_head!(number, expected_head, correlation)
+    current = begin
+      pull_request(number: number)
+    rescue Ace::Git::ProviderMalformedOutputError, Ace::Git::ProviderAuthenticationError, Ace::Git::ProviderObjectNotFoundError, Ace::Git::ProviderUnreachableError => e
+      raise Ace::Git::ProviderUnknownOutcomeError,
+        "Head verification read failed after mutation for #{server.name}: #{e.message}; reconcile before repeating"
+    end
+    return if current.head_sha == expected_head
+
+    raise Ace::Git::ProviderUnknownOutcomeError,
+      "PR head moved during mutation for #{server.name}/##{number} " \
+      "(#{expected_head} -> #{current.head_sha}), session #{correlation}: reconcile before repeating"
+  end
+
+        # Serialize the read/post/reconcile sequence per session so two
+      # concurrent callers cannot both observe "no marker" and post.
+        def with_session_lock(correlation)
+          require "tmpdir"
+          lock_path = File.join(Dir.tmpdir, "ace-review-session-#{correlation}.lock")
+          File.open(lock_path, File::CREAT | File::RDWR, 0600) do |lock|
+            lock.flock(File::LOCK_EX)
+            yield
+          end
+        end
+
+        def comment_marker(correlation)
+          unless correlation.to_s.match?(/\A[a-zA-Z0-9._:-]+\z/)
+            raise Ace::Git::ConfigError, "Invalid review session correlation"
+          end
+          "<!-- ace-review-session:#{correlation} -->"
+        end
+
+        def matching_review_comments(number, marker, expected_head)
+          review_http.paginate("issues/#{number}/comments").filter_map do |entry|
+            unless entry.is_a?(Hash) && entry["body"].is_a?(String)
+              raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo PR comment collection"
+            end
+            next unless entry["body"].include?(marker)
+
+            review_comment(entry, number, expected_head)
+          end
+        end
+
+        def review_comment(entry, number, head)
+          user = entry.is_a?(Hash) ? entry["user"] : nil
+          unless entry.is_a?(Hash) && entry["id"].is_a?(Integer) && entry["id"].positive? && entry["body"].is_a?(String) &&
+              user.is_a?(Hash) && user["login"].is_a?(String)
+            raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo PR comment evidence"
+          end
+          Ace::Git::ProviderReviewComment.new(
+            server_name: server.name, repository_url: server.url, pr_number: number,
+            id: entry["id"], author: user["login"], body: entry["body"],
+            url: entry["html_url"], path: entry["path"],
+            # Forgejo supplies position/original_position rather than
+            # line; the positive side position is the normalized line.
+            line: entry["line"] || [entry["position"], entry["original_position"]].compact.reject { |v| !v.is_a?(Integer) || v <= 0 }.first,
+            head_sha: entry["commit_id"], resolved: entry.key?("resolver") ? !entry["resolver"].nil? : nil,
+            thread_id: nil
+          )
+        end
+
+        # Collect inline (review) comment ids by walking each review.
+        def review_comment_ids(number)
+          review_http.paginate("pulls/#{number}/reviews").flat_map do |review|
+            entries = review_http.request(:get, "pulls/#{number}/reviews/#{review["id"]}/comments")
+            unless entries.is_a?(Array)
+              raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo review comment evidence"
+            end
+            entries.filter_map { |entry| entry["id"] if entry.is_a?(Hash) && entry["id"].is_a?(Integer) }
+          end
+        end
+
+        def review_entry(entry, number, head)
+          unless entry.is_a?(Hash)
+            raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo PR review evidence"
+          end
+          user, team = entry["user"], entry["team"]
+          unless user.nil? || user.is_a?(Hash)
+            raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo PR review evidence: user must be an object"
+          end
+          unless team.nil? || team.is_a?(Hash)
+            raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo PR review evidence: team must be an object"
+          end
+          reviewer = user&.[]("login") || team&.[]("name")
+          unless entry["id"].is_a?(Integer) && entry["id"].positive? && reviewer.is_a?(String) &&
+              entry["state"].is_a?(String) && !entry["state"].empty?
+            raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo PR review evidence"
+          end
+          Ace::Git::ProviderReview.new(
+            server_name: server.name, repository_url: server.url, pr_number: number,
+            id: entry["id"], author: reviewer, body: entry["body"],
+            # Forgejo reports REQUEST_CHANGES; consumers count only the
+            # canonical CHANGES_REQUESTED spelling.
+            state: (entry["state"] == "REQUEST_CHANGES") ? "CHANGES_REQUESTED" : entry["state"],
+            url: entry["html_url"], head_sha: entry["commit_id"]
+          )
+        end
+
+        def review_mutation(number, head, comment, idempotency)
+          Ace::Git::ProviderReviewMutation.new(
+            server_name: server.name, repository_url: server.url, pr_number: number,
+            head_sha: head, comment: comment, idempotency: idempotency
+          )
+        end
+
+        def assert_issue_comment_owned!(number, comment_id)
+          return if issue_tracking(number: number)[:comments].any? { |comment| comment[:id].to_i == comment_id.to_i }
+
+          raise Ace::Git::ProviderIdentityMismatchError,
+            "Comment #{comment_id} is not on selected issue ##{number} in #{server.url}"
+        end
+
+        def issue_api
+          @issue_api ||= IssueApi.new(server: server, timeout: timeout, runner: runner)
+        end
+
         # Validated selected repository identity. Built once; malformed
         # selections fail as configuration errors before any subprocess.
         def repository_target
@@ -384,6 +802,7 @@ module Ace
             server_name: server.name,
             number: parsed[:number],
             title: parsed[:title],
+            body: parsed[:body],
             state: parsed[:state],
             head_ref: parsed[:head_ref],
             base_ref: parsed[:base_ref],
@@ -423,6 +842,7 @@ module Ace
             server_name: server.name,
             number: entry[:number],
             title: entry[:title],
+            body: nil,
             state: nil,
             head_ref: nil,
             base_ref: nil,
@@ -478,13 +898,16 @@ module Ace
         end
 
         def pr_url(number)
-          base = repository_target.url.to_s.chomp("/")
+          # A configured URL may end in .git (clone form); the web URL
+          # must be built from the repository page base instead.
+          base = repository_target.url.to_s.chomp("/").sub(/\.git\z/i, "")
           "#{base}/pulls/#{number}"
         end
 
         def issue_url(number)
-          base = repository_target.url.to_s.chomp("/")
-          "#{base}/issues/#{number}"
+          # Identity evidence comes from the web endpoint, not the clone URL
+          # (which may be SSH-style and is not a parseable web URL).
+          "#{Ace::Git::Atoms::ServerUrl.web_base(server.url)}/issues/#{number}"
         end
       end
     end

data/lib/ace/git/forgejo/repository_binding.rb

@@ -175,8 +175,10 @@ module Ace
             nil
           end
 
-          # Observed forgejo-cli v0.6.0 keys-file locations (data_dir of the
-          # `directories` crate, plus the legacy Cyborus org path).
+          # Observed forgejo-cli keys-file locations (data_dir of the
+          # `directories` crate, plus the legacy Cyborus org path). On macOS
+          # the real CLI uses bundle-dir names: forgejo-cli.forgejo-cli
+          # (current) and Cyborus.forgejo-cli (legacy).
           def default_keys_path
             candidates = []
             xdg = ENV["XDG_DATA_HOME"]
@@ -185,7 +187,10 @@ module Ace
             if home
               candidates << File.join(home, ".local", "share", "forgejo-cli", "keys.json")
               candidates << File.join(home, "Library", "Application Support", "forgejo-cli", "keys.json")
+              # macOS app-support uses reverse-DNS bundle directories.
+              candidates << File.join(home, "Library", "Application Support", "forgejo-cli.forgejo-cli", "keys.json")
               candidates << File.join(home, ".local", "share", "Cyborus", "forgejo-cli", "keys.json")
+              candidates << File.join(home, "Library", "Application Support", "Cyborus.forgejo-cli", "keys.json")
               candidates << File.join(home, "Library", "Application Support", "Cyborus", "forgejo-cli", "keys.json")
             end
             candidates.find { |path| File.exist?(path) }

data/lib/ace/git/forgejo/version.rb

@@ -3,7 +3,7 @@
 module Ace
   module Git
     module Forgejo
-      VERSION = "0.3.0"
+      VERSION = "0.5.0"
     end
   end
 end

data/lib/ace/git/forgejo.rb

@@ -7,6 +7,7 @@ require_relative "forgejo/repository_binding"
 require_relative "forgejo/cli_executor"
 require_relative "forgejo/pr_identifier"
 require_relative "forgejo/parsers"
+require_relative "forgejo/http_client"
 require_relative "forgejo/provider"
 
 module Ace

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-git-forgejo
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-01 00:00:00.000000000 Z
+date: 2026-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-git
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.24'
+        version: '0.26'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.24'
+        version: '0.26'
 description: 'Implements the shared ace-git provider contract for Forgejo: all `fj`
   CLI invocation, output parsing, authentication verification, and classified failure
   handling live behind one normalized evidence boundary. Ad-hoc curl fallbacks are
@@ -39,6 +39,8 @@ files:
 - Rakefile
 - lib/ace/git/forgejo.rb
 - lib/ace/git/forgejo/cli_executor.rb
+- lib/ace/git/forgejo/http_client.rb
+- lib/ace/git/forgejo/issue_api.rb
 - lib/ace/git/forgejo/parsers.rb
 - lib/ace/git/forgejo/pr_identifier.rb
 - lib/ace/git/forgejo/provider.rb