ace-git-forgejo 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd545a2d89b063b16fe426301be445f5fd96e9831c90f4f3cbc8bcdf5a6cd535
-  data.tar.gz: a0d960a767bb9c94286d1f3cf0f0d2faa90bff6e1d27e798acd4559c4944f987
+  metadata.gz: 7f71ec19c2631e884747c20ba07ad19b595fff3ad52c4505571d3f91da61f2ff
+  data.tar.gz: ca8d1ff36047ef554da1fa8b23285b7fb01d486b35bde3321b03d199ba92ffb0
 SHA512:
-  metadata.gz: 61487148163544e819c66ad42c63be3de3d350b641162650d49094f78186673820dbf47a4ae9fa29ccddacc333eebddeb6f884c5e8259496a780a62f101c7ce1
-  data.tar.gz: 1c3d7f3985b77e4cb0104b7be71c22245c63fdacc4fd4f3148931fbee5d57f335565edaf4dcf7fdd5b8c1aab95246494293909eea61ff15ad227406522c3f175
+  metadata.gz: 6cddccbd90c235fe84a052c58dfe3030a6c3b826527da34681d4316579c46e798bc1ca212ee438f5020be3d47ac77d51fc99729ca2805d1f7c3e3f0c0046b30a
+  data.tar.gz: 621fa2ebff13f4e344dba8500ad40b2e41604a97c39282979424d9eaf942c32c2f266be1f3aaa74037f1244924dd73518067f74d19a93162d0378f3781dcc487

data/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-28
+
+### Added
+- PR lifecycle mutations matching the shared provider contract: exact-match
+  lookup via `fj pr search`, idempotent create reconciliation, head-verified
+  title/body updates.
+- Fork provenance: the `fj pr view` head-repository segment is parsed and
+  returned in normalized PR evidence.
+
+### Changed
+- `pr ready` and `pr merge` are classified unsupported capabilities: `fj`
+  offers no draft-to-ready command and cannot enforce an expected-head merge
+  precondition atomically, so both refuse instead of racing.
+- PR view parser captures the fork repository prefix of the `From` segment.
+
+### Added
+- PR lifecycle mutations matching the shared provider contract: exact-match
+  lookup via `fj pr search`, idempotent create reconciliation, head-verified
+  title/body updates.
+- Fork provenance: the `fj pr view` head-repository segment is parsed and
+  returned in normalized PR evidence.
+
+### Changed
+- `pr ready` and `pr merge` are classified unsupported capabilities: `fj`
+  offers no draft-to-ready command and cannot enforce an expected-head merge
+  precondition atomically, so both refuse instead of racing.
+- PR view parser captures the fork repository prefix of the `From` segment.
+
+## [0.1.1] - 2026-09-28
+
+
 ### Fixed
 
 - Parse real `fj` v0.6.0 minimal-style output: strip Unicode bidi isolate/pop-directional marks (U+2066–U+2069, U+202A–U+202E, U+200E/U+200F, soft hyphen) that `[[:cntrl:]]` does not cover. Real `fj` output wraps dynamic fields (titles, numbers, URLs) in U+2068/U+2069, which made `parse_pr_view` return `nil` and leaked marks into repo-URL evidence.

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

@@ -29,7 +29,11 @@ module Ace
         #   By lab-builder - Merged - +252 -8
         #   From `owner/repo:head-branch` into `main`
         #
-        # @return [Hash, nil] {number:, title:, author:, state:, head_ref:, base_ref:}
+        # The `From` segment carries an optional `owner/repo:` prefix before
+        # the head branch; it is present only for fork (cross-repository)
+        # pull requests.
+        #
+        # @return [Hash, nil] {number:, title:, author:, state:, head_ref:, base_ref:, head_repository:}
         def self.parse_pr_view(text)
           lines = text.to_s.lines.map { |line| clean(line) }.reject(&:empty?)
           return nil if lines.empty?
@@ -44,7 +48,8 @@ module Ace
             author: nil,
             state: nil,
             head_ref: nil,
-            base_ref: nil
+            base_ref: nil,
+            head_repository: nil
           }
 
           byline = lines[1].to_s
@@ -54,9 +59,12 @@ module Ace
           end
 
           refs = lines.find { |line| line.start_with?("From ") }
-          if (match = refs.to_s.match(/\AFrom\s+`(?:[^`:]+:)?(?<head>[^`]+)`\s+into\s+`(?<base>[^`]+)`\z/))
+          if (match = refs.to_s.match(
+            /\AFrom\s+`(?:(?<repo>[^`:]+):)?(?<head>[^`]+)`\s+into\s+`(?<base>[^`]+)`\z/
+          ))
             info[:head_ref] = match[:head]
             info[:base_ref] = match[:base]
+            info[:head_repository] = match[:repo]
           end
 
           info

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

@@ -46,13 +46,7 @@ module Ace
         # @raise [ProviderMalformedOutputError] when `fj` output is unexpected
         # @raise [ProviderUnreachableError] when the endpoint is unreachable
         def pull_request(number:)
-          view = fj(["--style", "minimal", "pr", "view", number.to_s])
-          parsed = Parsers.parse_pr_view(view) ||
-            raise(Ace::Git::ProviderMalformedOutputError,
-              "Unrecognized `fj pr view #{number}` output; update the Forgejo provider parser")
-
-          parsed[:head_sha] = head_sha_of(number)
-          normalize_pr(parsed)
+          fetch_pr(number)
         end
 
         # @return [ProviderPullRequest, nil] evidence for the branch's PR
@@ -137,6 +131,95 @@ module Ace
           )
         end
 
+        # ---- PR lifecycle mutations ----
+
+        # @return [Array<ProviderPullRequest>] open PRs matching the exact
+        #   base/head identity, with head SHA provenance
+        def find_open_pull_requests(head_repository_url:, head_ref:, base_repository_url:, base_ref:)
+          require_base_on_server!(base_repository_url)
+          listing = fj(["--style", "minimal", "pr", "search", "--state", "open"])
+          Parsers.parse_search(listing).filter_map do |entry|
+            parsed = view_pr(entry[:number])
+            next unless parsed && parsed[:state] == :open
+            next unless parsed[:head_ref] == head_ref && parsed[:base_ref] == base_ref
+            next unless Ace::Git::Atoms::ServerUrl.match?(head_repository_url_of(parsed), head_repository_url)
+
+            with_head_sha(parsed)
+          end
+        end
+
+        # Create a PR via `fj pr create`, reconciling to an exact open match
+        # first and proving the resulting head against `expected_head`.
+        # `fj` cannot create draft PRs; the receipt reports the provider's
+        # real draft state.
+        #
+        # @return [ProviderMutationReceipt] idempotency :created/:existing
+        def create_pull_request(head_ref:, head_repository_url:, base_ref:, expected_head:, title:, body: nil, draft: true)
+          # `fj pr create` operates on the checkout's repository and cannot
+          # encode an explicit fork head; refusing before any command (even
+          # lookups) beats creating the wrong PR.
+          unless Ace::Git::Atoms::ServerUrl.match?(head_repository_url, server.url)
+            raise Ace::Git::ProviderUnsupportedCapabilityError,
+              "Forgejo CLI (fj) pr create cannot target head repository " \
+              "#{head_repository_url} (resolved server repository: #{server.url}); " \
+              "run from the fork checkout or use the forge web UI"
+          end
+
+          matches = find_open_pull_requests(
+            head_repository_url: head_repository_url, head_ref: head_ref,
+            base_repository_url: server.url, base_ref: base_ref
+          )
+          if matches.size > 1
+            raise Ace::Git::ProviderConflictingMatchesError,
+              "Multiple open pull requests match #{head_repository_url}@#{head_ref} -> " \
+              "#{base_ref}: #{matches.map(&:number).join(", ")}; resolve the conflict first"
+          end
+          if matches.size == 1
+            return receipt(:create, verify_expected_head!(matches.first, expected_head), :existing)
+          end
+
+          args = ["pr", "create", title, "--head", head_ref, "--base", base_ref]
+          args += ["--body", body] if body
+          send_mutation(args, ambiguous: true, identity: identity_text(head_repository_url, head_ref, base_ref))
+
+          created = reconcile_created(
+            head_repository_url: head_repository_url, head_ref: head_ref,
+            base_ref: base_ref, expected_head: expected_head
+          )
+          receipt(:create, created, :created)
+        end
+
+        # `fj pr edit` takes one field subcommand per invocation (title|body),
+        # so multi-field updates are separate commands with final evidence
+        # fetched only after every field update succeeded.
+        #
+        # @return [ProviderMutationReceipt] operation :update
+        def update_pull_request(number:, expected_head:, title: nil, body: nil)
+          verify_expected_head!(fetch_pr(number), expected_head)
+          send_mutation(["pr", "edit", number.to_s, "title", title], ambiguous: false) if title
+          send_mutation(["pr", "edit", number.to_s, "body", body], ambiguous: false) if body
+          receipt(:update, fetch_pr(number), nil)
+        end
+
+        # `fj` offers no draft-to-ready command; classified as an unsupported
+        # capability instead of guessing at provider behavior.
+        def ready_pull_request(number:, expected_head:)
+          raise Ace::Git::ProviderUnsupportedCapabilityError,
+            "Forgejo CLI (fj) cannot mark a draft pull request ready; use the forge web UI"
+        end
+
+        # `fj pr merge` cannot enforce an expected-head precondition
+        # atomically, so merging is refused rather than racing a stale head.
+        def merge_pull_request(number:, expected_head:, method:)
+          unless %i[squash merge rebase].include?(method)
+            raise ArgumentError, "Invalid merge method #{method.inspect}"
+          end
+
+          raise Ace::Git::ProviderUnsupportedCapabilityError,
+            "Forgejo CLI (fj) pr merge cannot enforce expected-head (#{expected_head}) " \
+            "atomically; refusing unsafe merge"
+        end
+
         private
 
         # Run one `fj` command, classifying every failure with the taxonomy.
@@ -144,15 +227,95 @@ module Ace
           result = CliExecutor.execute(args, timeout: timeout, runner: runner)
           return result[:stdout] if result[:success]
 
-          message = result[:stderr].to_s
+          classify_failure(result[:stderr], context: args.join(" "))
+        end
+
+        # Send one mutating `fj` command. When `ambiguous` is true (create),
+        # any transport-level failure becomes an unknown outcome: the request
+        # may have mutated the forge, so callers must reconcile by exact
+        # identity instead of retrying blindly.
+        def send_mutation(args, ambiguous:, identity: nil)
+          result = CliExecutor.execute(args, timeout: timeout, runner: runner)
+          return result if result[:success]
+
+          classify_failure(result[:stderr], context: args.join(" "))
+        rescue Ace::Git::ProviderUnreachableError => e
+          raise e unless ambiguous
+
+          raise Ace::Git::ProviderUnknownOutcomeError,
+            "PR create outcome unknown after transport failure (#{e.message}); " \
+            "reconcile by exact identity before repeating: #{identity}"
+        end
+
+        def classify_failure(message, context:)
+          message = message.to_s
           case message
           when /not found|does not exist|no pull request|no issue/i
-            raise Ace::Git::ProviderObjectNotFoundError, "Object not found (#{args.join(" ")}): #{message}"
+            raise Ace::Git::ProviderObjectNotFoundError, "Object not found (#{context}): #{message}"
           when /access denied|unauthorized|token/i
             raise Ace::Git::ProviderAuthenticationError, "Not authenticated with Forgejo: #{message}"
           else
-            raise Ace::Git::ProviderUnreachableError, "Forgejo request failed (#{args.join(" ")}): #{message}"
+            raise Ace::Git::ProviderUnreachableError, "Forgejo request failed (#{context}): #{message}"
+          end
+        end
+
+        # Fetch one PR as normalized evidence with exact head SHA.
+        def fetch_pr(number)
+          with_head_sha(view_pr(number))
+        end
+
+        # Complete a parsed PR view with its exact head SHA evidence.
+        def with_head_sha(parsed)
+          parsed[:head_sha] = head_sha_of(parsed[:number])
+          normalize_pr(parsed)
+        end
+
+        # View one PR and parse its stable minimal-style output.
+        def view_pr(number)
+          view = fj(["--style", "minimal", "pr", "view", number.to_s])
+          Parsers.parse_pr_view(view) ||
+            raise(Ace::Git::ProviderMalformedOutputError,
+              "Unrecognized `fj pr view #{number}` output; update the Forgejo provider parser")
+        end
+
+        # Re-fetch and verify the PR created by an accepted create request.
+        def reconcile_created(head_repository_url:, head_ref:, base_ref:, expected_head:)
+          matches = find_open_pull_requests(
+            head_repository_url: head_repository_url, head_ref: head_ref,
+            base_repository_url: server.url, base_ref: base_ref
+          )
+          if matches.empty?
+            raise Ace::Git::ProviderUnknownOutcomeError,
+              "PR create accepted but no open pull request matches " \
+              "#{head_repository_url}@#{head_ref} -> #{server.url}@#{base_ref}; " \
+              "reconcile by exact identity before repeating"
           end
+          if matches.size > 1
+            raise Ace::Git::ProviderConflictingMatchesError,
+              "Multiple open pull requests match #{head_repository_url}@#{head_ref} -> " \
+              "#{base_ref}: #{matches.map(&:number).join(", ")}; resolve the conflict first"
+          end
+
+          verify_expected_head!(matches.first, expected_head)
+        end
+
+        def require_base_on_server!(base_repository_url)
+          return if Ace::Git::Atoms::ServerUrl.match?(base_repository_url, server.url)
+
+          raise Ace::Git::ProviderUnsupportedCapabilityError,
+            "Forgejo provider operates on the resolved server repository (#{server.url}); " \
+            "refusing base repository #{base_repository_url}"
+        end
+
+        def identity_text(head_repository_url, head_ref, base_ref)
+          "#{head_repository_url}@#{head_ref} -> #{server.url}@#{base_ref}"
+        end
+
+        def receipt(operation, pull_request, idempotency)
+          Ace::Git::ProviderMutationReceipt.new(
+            server_name: server.name, operation: operation,
+            pull_request: pull_request, idempotency: idempotency
+          )
         end
 
         def head_sha_of(number)
@@ -172,10 +335,30 @@ module Ace
             author: parsed[:author],
             url: pr_url(parsed[:number]),
             draft: nil,
-            merged_at: nil
+            merged_at: nil,
+            head_repository_url: head_repository_url_of(parsed),
+            base_repository_url: server.url,
+            merge_commit_sha: nil
           )
         end
 
+        # Source repository URL for the PR head: forks are reported by the
+        # `From `owner/repo:branch`` segment and live on the same host as the
+        # base repository; canonical PRs use the configured repository.
+        def head_repository_url_of(parsed)
+          repo = parsed[:head_repository]
+          return server.url if repo.nil? || repo.empty?
+
+          "#{server_host_root}/#{repo}"
+        end
+
+        def server_host_root
+          @server_host_root ||= begin
+            uri = URI.parse(server.url.to_s)
+            "#{uri.scheme || "https"}://#{uri.host}#{":#{uri.port}" if uri.port && uri.port != uri.default_port}"
+          end
+        end
+
         def normalize_search_entry(entry)
           Ace::Git::ProviderPullRequest.new(
             server_name: server.name,
@@ -188,7 +371,10 @@ module Ace
             author: entry[:author],
             url: pr_url(entry[:number]),
             draft: nil,
-            merged_at: nil
+            merged_at: nil,
+            head_repository_url: nil,
+            base_repository_url: nil,
+            merge_commit_sha: nil
           )
         end
 

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

@@ -3,7 +3,7 @@
 module Ace
   module Git
     module Forgejo
-      VERSION = "0.1.0"
+      VERSION = "0.2.0"
     end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-git-forgejo
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-23 00:00:00.000000000 Z
+date: 2026-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-git