ace-git-forgejo 0.5.0 → 0.6.1

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

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Git
+    module Forgejo
+      # Repository-bound Forgejo API v1 operations for the PR delivery
+      # lifecycle (create, edit, ready, merge) plus the authoritative single
+      # pull request read.
+      #
+      # The fj v0.6 CLI cannot encode a fork head, an explicit draft state,
+      # a ready transition, or an atomic expected-head merge precondition;
+      # this molecule owns those endpoints on the same selected host and
+      # token transport as {HttpClient}. Every returned payload is validated
+      # against the documented Forgejo `PullRequest` schema before it may
+      # become provider evidence; contradictory or missing identity fields
+      # fail closed as malformed evidence.
+      #
+      # Mutations return a {MutationOutcome} for the statuses that carry
+      # endpoint-specific meaning (201/200 success, 405/409/422 refusal) so
+      # the provider can classify the forge's own semantics; authentication,
+      # absence, and transport failures raise the shared taxonomy directly.
+      class PullRequestApi
+        # Official capability evidence (see the task capability-evidence
+        # report): `head_commit_id` merge enforcement is documented from
+        # release branch v7.0, and the API `draft` field is only computed
+        # from the WIP title from v8.0 (`Draft: pr.IsWorkInProgress` and a
+        # non-omitempty bool; v7.0 leaves it unset). The lifecycle proves
+        # draft state, so the floor is the first line reporting both.
+        MINIMUM_SERVER_VERSION = Gem::Version.new("8.0.0")
+
+        # Outcome of one mutation send whose status the provider must
+        # interpret: the HTTP status, the sanitized server message (nil on
+        # success), and the parsed payload when the server returned one.
+        MutationOutcome = Data.define(:status, :message, :payload)
+
+        def initialize(server:, timeout:, runner: nil)
+          @http = HttpClient.new(server: server, timeout: timeout, runner: runner)
+        end
+
+        # Probe and validate the selected server's API version once per
+        # instance. Every lifecycle mutation gate goes through here and
+        # fails closed when the server cannot prove the documented
+        # capability floor. Transport and authentication failures classify
+        # as they would for any read; an unusable or too-old version
+        # reports is a capability refusal.
+        #
+        # @raise [Ace::Git::ProviderUnsupportedCapabilityError] when the
+        #   server version cannot be verified or is below the floor
+        def ensure_version_supported!
+          return if @version_supported
+
+          status, payload = @http.exchange(:get, "/api/v1/version")
+          version_text = payload.is_a?(Hash) ? payload["version"] : nil
+          unless status == 200 && version_text.is_a?(String) && !version_text.empty?
+            if [401, 403].include?(status.to_i)
+              raise Ace::Git::ProviderAuthenticationError,
+                "Forgejo server version probe returned HTTP #{status}; authenticate with fj first"
+            end
+            raise Ace::Git::ProviderUnsupportedCapabilityError,
+              "Forgejo server did not report a usable API version (HTTP #{status}); " \
+              "cannot prove the PR delivery capability floor " \
+              "#{MINIMUM_SERVER_VERSION} before mutating"
+          end
+
+          version = parse_version(version_text)
+          unless version >= MINIMUM_SERVER_VERSION
+            raise Ace::Git::ProviderUnsupportedCapabilityError,
+              "Forgejo server reports #{version}; PR delivery requires #{MINIMUM_SERVER_VERSION} " \
+              "(server-enforced expected-head merge is not documented below it)"
+          end
+          @version_supported = true
+        end
+
+        # @return [Hash] the raw validated pull request payload
+        # @raise [Ace::Git::ProviderObjectNotFoundError] when absent
+        # @raise [Ace::Git::ProviderMalformedOutputError] on schema violation
+        # @raise [Ace::Git::ProviderIdentityMismatchError] when the payload
+        #   reports another object number (misrouted evidence)
+        def pull_request(number)
+          status, payload = @http.exchange(:get, "pulls/#{number}")
+          case status
+          when 200 then validate_pr_payload!(payload, number)
+          when 404 then raise Ace::Git::ProviderObjectNotFoundError, "Forgejo pull request ##{number} not found"
+          when 401, 403
+            raise Ace::Git::ProviderAuthenticationError,
+              "Forgejo pull request ##{number} read failed with HTTP #{status}"
+          else
+            raise Ace::Git::ProviderUnreachableError,
+              "Forgejo pull request ##{number} read failed with HTTP #{status}"
+          end
+        end
+
+        # @return [Array<Hash>] validated payloads of all open pull requests
+        def open_pull_requests
+          @http.paginate("pulls?state=open").map { |payload| validate_pr_payload!(payload, payload["number"]) }
+        end
+
+        # Prove the repository selected by Forgejo's owner:branch resolver.
+        # Forgejo uses the selected repository for its own owner, otherwise
+        # a direct fork owned by that user (the supported Forgejo 8 resolver).
+        def create_repository_identity(owner:)
+          base = repository_identity!(@http.request(:get, ""))
+          return [base, base] if base.dig("owner", "login").casecmp?(owner)
+
+          forks = @http.paginate("forks").map { |entry| repository_identity!(entry) }
+          matches = forks.select { |entry| entry.dig("owner", "login").casecmp?(owner) }
+          if matches.length > 1
+            raise Ace::Git::ProviderConflictingMatchesError, "Forgejo fork selector is ambiguous for #{owner}"
+          end
+          head = matches.first
+          unless head
+            raise Ace::Git::ProviderIdentityMismatchError, "Forgejo cannot prove fork selector for #{owner}"
+          end
+          [base, head]
+        end
+
+        def creation_evidence(payload)
+          validate_pr_payload!(payload, payload.is_a?(Hash) ? payload["number"] : nil)
+        end
+
+        # Send the create mutation. The head argument must already be in the
+        # documented API form (plain branch, or "owner:branch" for a
+        # same-server fork).
+        #
+        # @return [MutationOutcome] 201 with the created payload, or a
+        #   refusal outcome (409 duplicate, 404/422 unprovable source)
+        def create_pull_request(head:, base:, title:, body: nil)
+          form = {"title" => title, "base" => base, "head" => head}
+          form["body"] = body if body
+          status, payload, message = @http.exchange(:post, "pulls", body: form)
+          classify_send!(status, "create pull request")
+          MutationOutcome.new(status: status, message: message, payload: payload)
+        end
+
+        # Edit title/body of one pull request (also the ready transition:
+        # Forgejo marks a draft ready by removing its WIP title prefix).
+        #
+        # @return [MutationOutcome] 200, or a refusal outcome
+        def edit_pull_request(number, title: nil, body: nil)
+          form = {}
+          form["title"] = title if title
+          form["body"] = body if body
+          status, payload, message = @http.exchange(:patch, "pulls/#{number}", body: form)
+          classify_send!(status, "edit pull request #{number}")
+          MutationOutcome.new(status: status, message: message, payload: payload)
+        end
+
+        # Send the server-enforced merge: Forgejo re-resolves the head ref
+        # at merge time and refuses with 409 when it does not equal
+        # `head_commit_id` (documented `MergePullRequestOption`).
+        #
+        # @param do_method [String] "squash", "merge", or "rebase"
+        # @return [MutationOutcome] 200, or a refusal outcome (405 disabled
+        #   style, 409 stale head / conflicts / already merged)
+        def merge_pull_request(number, do_method:, head_commit_id:)
+          form = {"Do" => do_method, "head_commit_id" => head_commit_id}
+          status, payload, message = @http.exchange(:post, "pulls/#{number}/merge", body: form)
+          classify_send!(status, "merge pull request #{number}")
+          MutationOutcome.new(status: status, message: message, payload: payload)
+        end
+
+        private
+
+        # Authentication, absence, and transport failures classify directly
+        # inside the transport; only statuses whose meaning is
+        # endpoint-specific reach the provider as an outcome.
+        def classify_send!(status, operation)
+          return if (200..299).cover?(status)
+          return if [404, 405, 409, 422].include?(status.to_i)
+
+          error = case status.to_i
+          when 401, 403 then Ace::Git::ProviderAuthenticationError
+          else Ace::Git::ProviderUnknownOutcomeError
+          end
+          raise error, "Forgejo #{operation} returned HTTP #{status}; reconcile before repeating"
+        end
+
+        def repository_identity!(payload)
+          unless payload.is_a?(Hash) && payload["id"].is_a?(Integer) && payload["id"].positive? &&
+              payload["full_name"].is_a?(String) && payload["full_name"].match?(%r{\A[^/:\s?#]+/[^/:\s?#]+\z}) &&
+              payload["owner"].is_a?(Hash) && payload.dig("owner", "id").is_a?(Integer) && payload.dig("owner", "id").positive? &&
+              payload.dig("owner", "login").is_a?(String) && !payload.dig("owner", "login").empty? &&
+              payload["full_name"].split("/").first.casecmp?(payload.dig("owner", "login"))
+            raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo repository selector evidence"
+          end
+          payload
+        end
+
+        def validate_pr_payload!(payload, requested_number)
+          unless payload.is_a?(Hash)
+            raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo pull request evidence"
+          end
+          head = payload["head"]
+          base = payload["base"]
+          unless payload["number"].is_a?(Integer) && payload["number"].positive? &&
+              %w[open closed].include?(payload["state"]) &&
+              [true, false].include?(payload["draft"]) &&
+              [true, false].include?(payload["merged"]) &&
+              head.is_a?(Hash) && head["ref"].is_a?(String) && !head["ref"].empty? &&
+              head["sha"].to_s.match?(/\A[0-9a-f]{40}\z/) &&
+              base.is_a?(Hash) && base["ref"].is_a?(String) && !base["ref"].empty?
+            raise Ace::Git::ProviderMalformedOutputError,
+              "Malformed Forgejo pull request payload (missing number/state/draft/head/base identity)"
+          end
+          unless payload["number"] == requested_number
+            raise Ace::Git::ProviderIdentityMismatchError,
+              "Forgejo returned pull request ##{payload["number"]} for selected ##{requested_number}; " \
+              "refusing misrouted evidence"
+          end
+          payload
+        end
+
+        # Server version strings look like "7.0.5+gitea-..." or "v12.0.1";
+        # only the leading numeric release is comparable.
+        def parse_version(text)
+          match = text.strip.sub(/\Av/i, "").match(/\A(\d+\.\d+\.\d+)/)
+          unless match
+            raise Ace::Git::ProviderUnsupportedCapabilityError,
+              "Forgejo server version #{text.inspect} is not a comparable release; " \
+              "cannot prove the PR delivery capability floor #{MINIMUM_SERVER_VERSION}"
+          end
+          Gem::Version.new(match[1])
+        end
+      end
+    end
+  end
+end

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

@@ -100,17 +100,6 @@ module Ace
           pr_search: ->(target, state) do
             ["--style", "minimal", "pr", "search", "--state", state, "-r", target.repo]
           end,
-          pr_create: ->(target, title, head_ref, base_ref, body) do
-            argv = ["pr", "create", title, "--head", head_ref, "--base", base_ref]
-            argv += ["--body", body] if body
-            argv + ["-r", target.repo]
-          end,
-          pr_edit_title: ->(target, number, title) do
-            ["pr", "edit", target.qualified_ref(number), "title", title]
-          end,
-          pr_edit_body: ->(target, number, body) do
-            ["pr", "edit", target.qualified_ref(number), "body", body]
-          end,
           issue_view: ->(target, number) do
             ["--style", "minimal", "issue", "view", target.qualified_ref(number)]
           end,

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

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

data/lib/ace/git/forgejo.rb

@@ -8,6 +8,7 @@ require_relative "forgejo/cli_executor"
 require_relative "forgejo/pr_identifier"
 require_relative "forgejo/parsers"
 require_relative "forgejo/http_client"
+require_relative "forgejo/pull_request_api"
 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.5.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-03 00:00:00.000000000 Z
+date: 2026-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-git
@@ -23,6 +23,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.26'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
 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
@@ -44,6 +72,7 @@ files:
 - lib/ace/git/forgejo/parsers.rb
 - lib/ace/git/forgejo/pr_identifier.rb
 - lib/ace/git/forgejo/provider.rb
+- lib/ace/git/forgejo/pull_request_api.rb
 - lib/ace/git/forgejo/repository_binding.rb
 - lib/ace/git/forgejo/version.rb
 homepage: https://forgejo.tail6c0887.ts.net/cs3b/ace