ace-git-forgejo 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f652620ca5f68a59c0809d789d57b13fbcebda51a12d93863f24359bd316ad2b
-  data.tar.gz: 843e555799aac783ae018d8676314a6f3681f4836854a085a0c2d2232b10183c
+  metadata.gz: c8a35836d33fbf6fc14e52f4c27ef396244d1f809bc919ceca6ac0202db5e583
+  data.tar.gz: 548b2f7734d7f98ef2594e9630ddeb499ae9ead7f8c4297498ebe8726217c4a2
 SHA512:
-  metadata.gz: 58efabf1f68159415d2f0908cdb11f5a0bd15e32e3e299ada2049d12af79b0794d8090ca26098f0f6dedfc5b6f8da800a9071bfdac7afacb58038f44faeb5287
-  data.tar.gz: 6ac53befa67d15633f0fc19c4d431a65d8357cdd96051b16295a927c5de09f434a1b667bfdfe2aa0148429d2205db5651a12569511171df07c78bfe19eeabfab
+  metadata.gz: c19a8e1f44853f9c173e51118a42f1de9fd6ab04d77c01371c68f16d867f654b938f4cf5b252d8f7d4300c4bdcca826c53ed7dafddc6e616051fab8292aa457d
+  data.tar.gz: b312fbb4a37d5e871e55148f40e90951ebc2692c474d87e0052adb6beb0647fb24347b3599b914c7a4c7a93f9ca4726f201bd67301f4ba84ded528db979168da

data/CHANGELOG.md

@@ -5,8 +5,78 @@ All notable changes to ace-git-forgejo will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.3.0] - 2026-09-29
+
+### Added
+- Selected-repository binding for every `fj` repository command: the
+  resolved server's host/owner/repository is validated once (malformed
+  selections raise `ConfigError` before any subprocess) and stamped onto
+  every call via `-H` plus qualified `owner/repo#N` ids or `-r owner/repo`,
+  so a named server selection can never be silently retargeted by cwd,
+  remotes, default login, or another checkout.
+- Capability table grounded in observed forgejo-cli v0.6.0 help/output
+  (upstream release binary, plus real-server read-only probes); operations
+  without an observed argv form and installed versions outside the observed
+  set refuse with `ProviderUnsupportedCapabilityError` before launch.
+- Returned-identity validation: PR/issue numbers and repository view
+  full-name/URL must agree with the selection or evidence fails closed
+  with `ProviderIdentityMismatchError`.
+
+### Changed
+- All `fj` subprocess launches now go through a two-path executor boundary:
+  an allowlisted control path (`fj version`, `fj auth list`) and the
+  repository boundary. Authentication compares `fj auth list` lines exactly
+  against the selected authority (substring hosts no longer count) and
+  scans both output streams (observed v0.6.0 prints "No logins." on stderr
+  with exit 0).
+- Unauthenticated-API failures are classified as authentication errors
+  (observed Lab text "Only signed in user is allowed to call APIs.").
+- `merge_commit_sha` stays empty: observed fj v0.6.0 exposes no
+  authoritative merge-commit field for a selected PR, so cleanup evidence
+  never claims one.
+
+### Fixed
+- Selected-host fidelity: `-H` now carries the selected `scheme://authority`
+  (fj assumes HTTPS for a bare host, so an http authority was silently
+  upgraded), non-http(s) server schemes are rejected as configuration
+  errors before any subprocess, and the provider refuses to launch
+  repository commands when the readable fj keys file aliases the selected
+  host to a different endpoint (read-only check; absent/unreadable keys
+  file is allowed, never modified).
+
+## [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/README.md

@@ -5,8 +5,20 @@ Forgejo provider for the forge-neutral [`ace-git`](../ace-git) core.
 This package owns **all** Forgejo-specific behavior for ACE:
 
 - `fj` CLI invocation (with timeout handling and structured output)
-- `fj` minimal-style output parsing and normalization
-- `fj` authentication verification (`fj auth list` per configured server host)
+- **Selected-repository binding**: every repository-scoped `fj` call is
+  bound to the resolved server's exact host/owner/repository — `-H` plus
+  qualified `owner/repo#N` object ids or `-r owner/repo` — never cwd,
+  remotes, a default login, or user `fj` configuration. Malformed server
+  URLs fail as `ConfigError` before any subprocess; operations whose argv
+  form was never observed on a real `fj` refuse with
+  `ProviderUnsupportedCapabilityError` before launch, and the installed
+  `fj` version must be one of the observed versions (`v0.6.0`) to inherit
+  the capability table.
+- `fj` minimal-style output parsing and normalization, with returned
+  identity validated against the selection (misrouted evidence raises
+  `ProviderIdentityMismatchError` instead of being relabelled)
+- `fj` authentication verification (`fj auth list`, compared exactly
+  against the selected host authority)
 - Forgejo-specific identifier formats (including `/pulls/N` web URLs)
 
 It implements the provider contract defined by the core
@@ -21,3 +33,24 @@ Failures are classified with the shared taxonomy
 `ProviderUnreachableError`, `ProviderMalformedOutputError`,
 `ProviderObjectNotFoundError`). Ad-hoc curl fallbacks are strictly
 forbidden; there is no silent fallback of any kind.
+
+## Supported operations (observed on forgejo-cli v0.6.0)
+
+PR view/diff/head-commits, PR search (all/open, client-side newest-first
+window — `fj` has no `--limit`), PR create (same-repository head only),
+PR edit title/body, issue view, actions tasks, repository view, version
+and `auth list` probes. `fj` v0.6.0 exposes no draft-to-ready command, no
+atomic expected-head merge, and no authoritative merge-commit field, so
+`ready_pull_request`/`merge_pull_request` refuse as unsupported
+capabilities and `merge_commit_sha` stays empty — worktree cleanup
+conservatively retains Forgejo checkouts until `fj` exposes that field.
+The capability evidence and its provenance live in the
+`8wr.t.uj0` task folder (`evidence/fj-capabilities.md`).
+
+Endpoint fidelity: `-H` carries the selected `scheme://authority` (fj
+otherwise assumes HTTPS), and because fj v0.6.0 silently applies its
+keys-file `aliases` map to `-H`, the provider read-only checks the
+observed keys-file locations and refuses a repository command when an
+alias redirects the selected host — never modifying user fj
+configuration; an absent or unreadable keys file is allowed.
+

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

@@ -2,59 +2,129 @@
 
 require "open3"
 require "timeout"
+require_relative "parsers"
+require_relative "repository_binding"
 
 module Ace
   module Git
     module Forgejo
       # Executes the Forgejo CLI (`fj`) with timeout and structured output.
       #
-      # Owns every `fj` subprocess invocation for ACE. A test runner may be
-      # injected instead of spawning real processes (see Providers::Base).
+      # Owns every `fj` subprocess invocation for ACE. Two launch paths exist:
+      #
+      # - {execute_control}: allowlisted login/version probes (`fj version`,
+      #   `fj auth list`) that are host- or installation-scoped.
+      # - {execute_repository}: repository-scoped commands, which require the
+      #   validated selected {RepositoryBinding::Target} and a named operation
+      #   with an observed argv form. The executor stamps `-H <authority>`
+      #   from the target and refuses unobserved operations before launch —
+      #   repository selection never comes from cwd, remotes, a default
+      #   login, or user `fj` configuration.
+      #
+      # A test runner may be injected instead of spawning real processes
+      # (see Providers::Base).
       module CliExecutor
         DEFAULT_TIMEOUT = 30
         BINARY = "fj"
 
+        # Host/installation-scoped probes; never repository targeting.
+        CONTROL_ARGS = {
+          version: ["version"],
+          auth_list: ["auth", "list"]
+        }.freeze
+
         class << self
-          # Execute an `fj` command with timeout and structured output.
+          # Execute an allowlisted control command with timeout.
           #
-          # @param args [Array<String>] full argument vector after the binary
-          # @param timeout [Integer, nil] seconds before the call times out
-          # @param runner [Proc, nil] injectable command runner for tests
+          # @param command [Symbol] key in {CONTROL_ARGS}
           # @return [Hash] {success:, stdout:, stderr:, exit_code:}
           # @raise [Ace::Git::ProviderCliMissingError] when `fj` is missing
           # @raise [Ace::Git::ProviderUnreachableError] when the call times out
-          def execute(args, timeout: nil, runner: nil)
-            timeout_seconds = timeout || Ace::Git.network_timeout || DEFAULT_TIMEOUT
-            result = run_command([BINARY] + args, timeout_seconds, runner)
-            if result == :timeout
-              raise Ace::Git::ProviderUnreachableError,
-                "fj command timed out after #{timeout_seconds} seconds: #{args.join(" ")}"
+          # @raise [ArgumentError] when the command is not allowlisted
+          def execute_control(command, timeout: nil, runner: nil)
+            args = CONTROL_ARGS.fetch(command) do
+              raise ArgumentError, "Unknown fj control command #{command.inspect}"
             end
+            execute(args, timeout: timeout, runner: runner)
+          end
 
-            result
+          # Execute one repository-scoped operation bound to the selected
+          # target. The operation must have an observed argv form; the host
+          # flag is stamped here so no caller can omit selection.
+          #
+          # @param target [RepositoryBinding::Target] validated selected repository
+          # @param operation [Symbol] repository operation (RepositoryBinding::FORMS)
+          # @param arguments [Array<Object>] per-operation arguments
+          # @return [Hash] {success:, stdout:, stderr:, exit_code:}
+          # @raise [Ace::Git::ConfigError] when the target is missing/invalid
+          # @raise [Ace::Git::ProviderUnsupportedCapabilityError] when the
+          #   operation has no observed form
+          # @raise [Ace::Git::ProviderCliMissingError] when `fj` is missing
+          # @raise [Ace::Git::ProviderUnreachableError] when the call times out
+          def execute_repository(target:, operation:, arguments: [], timeout: nil, runner: nil)
+            unless target.is_a?(RepositoryBinding::Target)
+              raise Ace::Git::ConfigError,
+                "Repository commands require a validated selected Forgejo target"
+            end
+
+            argv = RepositoryBinding.argv_for(operation, target, arguments)
+            # `-H` carries the full selected URL: fj otherwise assumes HTTPS,
+            # which would drop a configured http authority (observed v0.6.0).
+            execute(["-H", target.host_url] + argv, timeout: timeout, runner: runner)
           end
 
           # Probe whether the `fj` binary is installed and runnable.
           # `fj` has no `--version` flag (it rejects it with "unexpected
           # argument"); the supported presence probe is `fj version`.
           def installed?(runner: nil)
-            result = execute(["version"], runner: runner)
-            result != :timeout && result[:success]
+            result = execute_control(:version, runner: runner)
+            result[:success]
           rescue Ace::Git::ProviderCliMissingError
             false
           end
 
-          # Probe whether the resolved server host has a configured `fj` login.
-          # `fj auth list` exits nonzero when no instance is configured and
-          # prints one host per line otherwise.
-          def authenticated?(host, runner: nil)
-            result = execute(["auth", "list"], runner: runner)
-            return false unless result[:success]
+          # @return [String, nil] installed forgejo-cli version (e.g. "v0.6.0"),
+          #   or nil when `fj version` output is unparseable
+          # @raise [Ace::Git::ProviderCliMissingError] when `fj` is missing
+          #   or the version probe fails
+          def installed_version(runner: nil)
+            result = execute_control(:version, runner: runner)
+            unless result[:success]
+              raise Ace::Git::ProviderCliMissingError,
+                "Forgejo CLI (fj) is not installed or not runnable; install the Forgejo CLI and retry"
+            end
 
-            hosts = result[:stdout].to_s.lines.map(&:strip).reject(&:empty?)
-            return hosts.any? unless host
+            match = result[:stdout].to_s.match(/\bfj\s+(v?\d+\.\d+\.\d+)\b/)
+            match && match[1].sub(/\Av?/, "v")
+          end
 
-            hosts.any? { |line| line.include?(host.to_s) }
+          # @raise [Ace::Git::ProviderUnsupportedCapabilityError] when the
+          #   installed version was never observed; it must not inherit the
+          #   capability table of an observed version
+          def check_version_supported!(runner: nil)
+            version = installed_version(runner: runner)
+            return version if RepositoryBinding::OBSERVED_VERSIONS.include?(version)
+
+            raise Ace::Git::ProviderUnsupportedCapabilityError,
+              "Installed forgejo-cli version #{version || "of unknown version"} was never " \
+              "observed; observed versions: #{RepositoryBinding::OBSERVED_VERSIONS.join(", ")}. " \
+              "Observe its real surface before repository operations are allowed " \
+              "(see the ace-git-forgejo repository binding evidence)"
+          end
+
+          # Probe whether the resolved server authority has a configured `fj`
+          # login. `fj auth list` prints "No logins." (stderr, exit 0) when no
+          # instance is configured; configured hosts are listed one per line.
+          # Comparison is exact against the selected authority — never a
+          # substring of an unrelated line.
+          def authenticated?(authority, runner: nil)
+            result = execute_control(:auth_list, runner: runner)
+            return false unless result[:success]
+
+            lines = "#{result[:stdout]}\n#{result[:stderr]}".lines
+            lines.map { |line| Parsers.clean(line) }.any? do |line|
+              !line.empty? && line.casecmp(authority.to_s)&.zero?
+            end
           rescue Ace::Git::ProviderCliMissingError
             false
           end
@@ -68,18 +138,31 @@ module Ace
           end
 
           # @raise [Ace::Git::ProviderAuthenticationError] when unauthenticated
-          def check_authenticated!(host: nil, runner: nil)
-            return true if authenticated?(host, runner: runner)
+          def check_authenticated!(authority:, runner: nil)
+            return true if authenticated?(authority, runner: runner)
 
             raise Ace::Git::ProviderAuthenticationError,
-              "Forgejo CLI (fj) has no usable login for #{host || "the target host"}; " \
+              "Forgejo CLI (fj) has no usable login for #{authority || "the target host"}; " \
               "check fj auth list"
           end
 
           # Run a full argument vector against `fj`.
           #
-          # @return [Hash] result hash, or :timeout sentinel on timeout
-          def run_command(command, timeout_seconds, runner = nil)
+          # @return [Hash] result hash
+          def execute(args, timeout: nil, runner: nil)
+            timeout_seconds = timeout || Ace::Git.network_timeout || DEFAULT_TIMEOUT
+            result = run_command([BINARY] + args, timeout_seconds, runner)
+            if result == :timeout
+              raise Ace::Git::ProviderUnreachableError,
+                "fj command timed out after #{timeout_seconds} seconds: #{args.join(" ")}"
+            end
+
+            result
+          end
+
+          private
+
+          def run_command(command, timeout_seconds, runner)
             if runner
               call_runner(runner, command, timeout_seconds)
             else
@@ -87,8 +170,6 @@ module Ace
             end
           end
 
-          private
-
           def call_runner(runner, command, timeout_seconds)
             runner.call(args: command, timeout: timeout_seconds, env: {"LC_ALL" => "C"})
           rescue StandardError => e

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

@@ -11,9 +11,14 @@ module Ace
       # Forgejo provider implementation of the shared provider contract.
       #
       # Owns Forgejo terminology and translates `fj` responses into the
-      # normalized evidence types defined by the ace-git core. Every failure is
-      # classified with the shared taxonomy; `fj` failures are never hidden
-      # behind ad-hoc curl calls or silent fallbacks.
+      # normalized evidence types defined by the ace-git core. Every
+      # repository-scoped call is bound to the selected server's exact
+      # host/owner/repository through the {CliExecutor} repository boundary:
+      # the selected identity is mandatory, unobserved operations refuse
+      # before launch, and returned evidence is checked for conflicting
+      # identity. Every failure is classified with the shared taxonomy;
+      # `fj` failures are never hidden behind ad-hoc curl calls or silent
+      # fallbacks.
       class Provider < Ace::Git::Providers::Base
         class << self
           def display_name
@@ -31,14 +36,15 @@ module Ace
           CliExecutor.check_installed!(runner: runner)
         end
 
-        # @return [Boolean] true when the server host has a configured `fj` login
+        # @return [Boolean] true when the selected server's host has a
+        #   configured `fj` login
         def authenticated?
-          CliExecutor.authenticated?(server_host, runner: runner)
+          CliExecutor.authenticated?(repository_target.authority, runner: runner)
         end
 
         # @raise [Ace::Git::ProviderAuthenticationError] when unauthenticated
         def check_authenticated!
-          CliExecutor.check_authenticated!(host: server_host, runner: runner)
+          CliExecutor.check_authenticated!(authority: repository_target.authority, runner: runner)
         end
 
         # @return [ProviderPullRequest] normalized pull request evidence
@@ -46,24 +52,18 @@ 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
         def pull_request_for_branch(branch:)
-          # `fj pr search` has no --limit flag; fetch all and order newest-first.
-          listing = fj(["--style", "minimal", "pr", "search", "--state", "all"])
+          # `fj pr search` has no --limit flag (observed v0.6.0); fetch all
+          # and order newest-first.
+          listing = fj(:pr_search, "all")
           entries = Parsers.parse_search(listing).sort_by { |entry| -entry[:number] }
 
           entries.each do |entry|
-            view = fj(["--style", "minimal", "pr", "view", entry[:number].to_s])
-            parsed = Parsers.parse_pr_view(view)
+            parsed = view_pr(entry[:number])
             next unless parsed && parsed[:head_ref] == branch
 
             parsed[:head_sha] = head_sha_of(entry[:number])
@@ -75,7 +75,7 @@ module Ace
 
         # @return [String] unified diff text for the pull request
         def pull_request_diff(number:)
-          fj(["pr", "view", number.to_s, "diff"])
+          fj(:pr_diff, request_number!(number))
         end
 
         # `fj pr search` has no --limit flag; cap client-side after sorting
@@ -83,7 +83,7 @@ module Ace
         #
         # @return [Array<ProviderPullRequest>] recent PRs, newest first
         def recent_pull_requests(limit:)
-          listing = fj(["--style", "minimal", "pr", "search", "--state", "all"])
+          listing = fj(:pr_search, "all")
           Parsers.parse_search(listing)
             .map { |entry| normalize_search_entry(entry) }
             .sort_by { |pr| -pr.number }
@@ -92,10 +92,11 @@ module Ace
 
         # @return [ProviderIssue] normalized issue evidence
         def issue(number:)
-          view = fj(["--style", "minimal", "issue", "view", number.to_s])
+          view = fj(:issue_view, request_number!(number))
           parsed = Parsers.parse_issue_view(view) ||
             raise(Ace::Git::ProviderMalformedOutputError,
               "Unrecognized `fj issue view #{number}` output; update the Forgejo provider parser")
+          verify_returned_number!(parsed, number, "issue")
 
           Ace::Git::ProviderIssue.new(
             server_name: server.name,
@@ -110,7 +111,7 @@ module Ace
 
         # @return [Array<ProviderCheck>] normalized check evidence for a ref
         def checks(ref:)
-          tasks = fj(["--style", "minimal", "actions", "tasks"])
+          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]) }
             .map do |task|
@@ -125,38 +126,256 @@ module Ace
         end
 
         # @return [ProviderRepository] normalized repository evidence
+        # @raise [ProviderIdentityMismatchError] when the CLI reports a
+        #   repository other than the selected one
         def repository
-          view = fj(["--style", "minimal", "repo", "view"])
+          target = repository_target
+          view = fj(:repo_view)
           parsed = Parsers.parse_repo_view(view)
+          verify_returned_repository!(parsed, target)
 
           Ace::Git::ProviderRepository.new(
             server_name: server.name,
             full_name: parsed[:full_name],
             default_branch: nil,
-            url: parsed[:url]
+            url: parsed[:url] || target.url
+          )
+        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(:pr_search, "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 encode an explicit fork head; 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 -r` binds the base repository, but no observed form
+          # encodes a cross-repository 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
+
+          send_mutation(:pr_create, title, head_ref, base_ref, body,
+            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)
+          number = request_number!(number)
+          verify_expected_head!(fetch_pr(number), expected_head)
+          send_mutation(:pr_edit_title, number, title, ambiguous: false) if title
+          send_mutation(:pr_edit_body, number, 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.
-        def fj(args)
-          result = CliExecutor.execute(args, timeout: timeout, runner: runner)
+        # Validated selected repository identity. Built once; malformed
+        # selections fail as configuration errors before any subprocess.
+        def repository_target
+          @repository_target ||= RepositoryBinding::Target.resolve(server.url)
+        end
+
+        # Refuse before any repository subprocess when the installed fj was
+        # never observed; a different version must not inherit capabilities.
+        def ensure_observed_version!
+          return if @version_checked
+
+          CliExecutor.check_version_supported!(runner: runner)
+          @version_checked = true
+        end
+
+        # Run one repository-scoped `fj` command bound to the selected
+        # target, classifying every failure with the taxonomy.
+        def fj(operation, *arguments)
+          result = execute_repository(operation, arguments)
           return result[:stdout] if result[:success]
 
-          message = result[:stderr].to_s
+          classify_failure(result[:stderr], context: operation_context(operation, arguments))
+        end
+
+        # Send one mutating repository operation. 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(operation, *arguments, ambiguous:, identity: nil)
+          result = execute_repository(operation, arguments)
+          return result if result[:success]
+
+          classify_failure(result[:stderr], context: operation_context(operation, arguments))
+        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 execute_repository(operation, arguments)
+          target = repository_target
+          ensure_observed_version!
+          ensure_not_redirecting!(target)
+          CliExecutor.execute_repository(
+            target: target, operation: operation,
+            arguments: arguments, timeout: timeout, runner: runner
+          )
+        end
+
+        # Refuse before any subprocess when the readable fj configuration
+        # aliases the selected host to a different endpoint: `-H` cannot
+        # prevent that redirect, and returned-identity checks cannot see it.
+        def ensure_not_redirecting!(target)
+          return if @redirect_checked
+
+          RepositoryBinding.reject_selected_host_redirect!(target.host_url)
+          @redirect_checked = true
+        end
+
+        def operation_context(operation, arguments)
+          "#{operation} #{arguments.compact.join(" ")}".strip
+        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}"
-          when /access denied|unauthorized|token/i
+            raise Ace::Git::ProviderObjectNotFoundError, "Object not found (#{context}): #{message}"
+          when /access denied|unauthorized|token|only signed in|not logged in|log ?in required/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. The
+        # qualified `owner/repo#N` reference binds the read to the selected
+        # repository; a returned number that disagrees with the request is a
+        # routed mismatch and fails closed.
+        def view_pr(number)
+          view = fj(:pr_view, number)
+          parsed = Parsers.parse_pr_view(view) ||
+            raise(Ace::Git::ProviderMalformedOutputError,
+              "Unrecognized `fj pr view #{number}` output; update the Forgejo provider parser")
+          verify_returned_number!(parsed, number, "pull request")
+          parsed
+        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)
-          commits = fj(["--style", "minimal", "pr", "view", number.to_s, "commits"])
+          commits = fj(:pr_commits, number)
           Parsers.parse_head_sha(commits)
         end
 
@@ -172,10 +391,33 @@ 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: repository_target.url,
+            # fj v0.6.0 exposes no authoritative merge-commit field for a
+            # selected PR (observed; see the task capability evidence), so
+            # merge evidence stays empty and cleanup retains the checkout.
+            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 repository_target.url if repo.nil? || repo.empty?
+
+          "#{server_host_root}/#{repo}"
+        end
+
+        def server_host_root
+          @server_host_root ||= begin
+            uri = URI.parse(repository_target.url)
+            "#{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,26 +430,60 @@ 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: repository_target.url,
+            merge_commit_sha: nil
           )
         end
 
-        def server_host
-          @server_host ||= begin
-            uri = URI.parse(server.url.to_s)
-            uri.host
-          rescue URI::Error
-            nil
+        # Reject non-numeric or non-positive PR/issue numbers as
+        # configuration failures before any subprocess.
+        def request_number!(number)
+          text = number.to_s
+          unless /\A\d+\z/.match?(text) && text.to_i.positive?
+            raise Ace::Git::ConfigError,
+              "Pull request and issue numbers must be positive integers, got #{number.inspect}"
+          end
+
+          text.to_i
+        end
+
+        # PR and issue numbers are not globally unique: evidence whose
+        # number disagrees with the selected reference was not routed to the
+        # selected repository and must never be relabelled.
+        def verify_returned_number!(parsed, requested, kind)
+          return if parsed[:number] == requested.to_i
+
+          raise Ace::Git::ProviderIdentityMismatchError,
+            "Forgejo returned #{kind} ##{parsed[:number]} for selected #{kind} " \
+            "##{requested} on #{repository_target.repo}; refusing misrouted evidence"
+        end
+
+        # `fj repo view` was bound to the selected owner/repository, so
+        # returned identity fields must agree with the selection.
+        def verify_returned_repository!(parsed, target)
+          full_name = parsed[:full_name].to_s.sub(%r{\.git\z}i, "")
+          unless !full_name.empty? && full_name.casecmp(target.repo).zero?
+            raise Ace::Git::ProviderIdentityMismatchError,
+              "Forgejo repo view returned #{full_name.inspect} for selected repository " \
+              "#{target.repo}; refusing misrouted evidence"
           end
+          return if parsed[:url].nil? || parsed[:url].empty? ||
+            Ace::Git::Atoms::ServerUrl.match?(parsed[:url], target.url)
+
+          raise Ace::Git::ProviderIdentityMismatchError,
+            "Forgejo repo view returned URL #{parsed[:url].inspect} for selected repository " \
+            "#{target.url}; refusing misrouted evidence"
         end
 
         def pr_url(number)
-          base = server.url.to_s.chomp("/")
+          base = repository_target.url.to_s.chomp("/")
           "#{base}/pulls/#{number}"
         end
 
         def issue_url(number)
-          base = server.url.to_s.chomp("/")
+          base = repository_target.url.to_s.chomp("/")
           "#{base}/issues/#{number}"
         end
       end

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

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Ace
+  module Git
+    module Forgejo
+      # Selected-server identity binding for `fj` repository commands.
+      #
+      # Forgejo CLI v0.6.0 exposes two explicit-target mechanisms and no
+      # others (see the task evidence file): `-H HOST` plus either
+      # `-r OWNER/REPO` (search, create, issue/actions repo selection) or a
+      # qualified `OWNER/REPO#N` object id (view/edit/status family). A
+      # repository command may only launch through {RepositoryBinding.argv_for},
+      # which exists for operations whose argv form was observed on a real
+      # binary; everything else refuses before any subprocess.
+      module RepositoryBinding
+        # forgejo-cli versions whose help/output this table was observed on.
+        # A different installed version must not inherit these capabilities;
+        # the executor refuses it until the table is re-observed and extended.
+        OBSERVED_VERSIONS = ["v0.6.0"].freeze
+
+        # The validated selected repository. Built once from the resolved
+        # server URL; malformed selections fail with ConfigError before any
+        # subprocess launch.
+        class Target
+          attr_reader :host, :authority, :host_url, :repo, :url
+
+          SUPPORTED_SCHEMES = ["http", "https"].freeze
+
+          # @param server_url [String] resolved server URL (https://host/owner/repo)
+          # @raise [Ace::Git::ConfigError] when host, scheme, or owner/repository is missing
+          def self.resolve(server_url)
+            uri = URI.parse(server_url.to_s)
+            raise_config_error!(server_url, "missing host") if uri.host.nil? || uri.host.empty?
+            unless SUPPORTED_SCHEMES.include?(uri.scheme.to_s.downcase)
+              raise_config_error!(server_url, "scheme must be http or https")
+            end
+
+            authority = if uri.port && uri.port != uri.default_port
+              "#{uri.host}:#{uri.port}"
+            else
+              uri.host
+            end
+            path = uri.path.to_s.sub(%r{/+\z}, "").sub(/\.git\z/i, "")
+            segments = path.split("/").reject(&:empty?)
+            unless segments.length == 2
+              raise_config_error!(server_url, "path must be exactly owner/repository")
+            end
+
+            repo = "#{segments[0]}/#{segments[1]}"
+            # `fj -H` accepts a full URL and otherwise assumes HTTPS (observed
+            # v0.6.0); passing scheme + authority preserves the configured
+            # endpoint exactly.
+            host_url = "#{uri.scheme.downcase}://#{authority}"
+            new(
+              host: uri.host, authority: authority, host_url: host_url,
+              repo: repo, url: "#{host_url}/#{repo}"
+            )
+          rescue URI::Error
+            raise_config_error!(server_url, "unparseable URL")
+          end
+
+          def self.raise_config_error!(server_url, reason)
+            raise Ace::Git::ConfigError,
+              "Selected Forgejo server URL #{server_url.inspect} is unusable (#{reason}); " \
+              "configure the server as scheme://host/owner/repository"
+          end
+
+          def initialize(host:, authority:, host_url:, repo:, url:)
+            @host = host
+            @authority = authority
+            @host_url = host_url
+            @repo = repo
+            @url = url
+          end
+          private_class_method :new
+
+          # Qualified object id form accepted by `fj pr/issue view|edit` (v0.6.0).
+          def qualified_ref(number)
+            "#{repo}##{number}"
+          end
+        end
+
+        # Capability table: repository operations with an argv form observed
+        # on real forgejo-cli v0.6.0 (task evidence file). Forms receive the
+        # validated Target plus the provider's per-call arguments and return
+        # the argv after the binary name; the executor stamps `-H host`.
+        FORMS = {
+          pr_view: ->(target, number) do
+            ["--style", "minimal", "pr", "view", target.qualified_ref(number)]
+          end,
+          pr_commits: ->(target, number) do
+            ["--style", "minimal", "pr", "view", target.qualified_ref(number), "commits"]
+          end,
+          pr_diff: ->(target, number) do
+            ["pr", "view", target.qualified_ref(number), "diff"]
+          end,
+          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,
+          actions_tasks: ->(target) do
+            ["--style", "minimal", "actions", "tasks", "-r", target.repo]
+          end,
+          repo_view: ->(target) do
+            ["--style", "minimal", "repo", "view", target.repo]
+          end
+        }.freeze
+
+        class << self
+          # Resolve one repository operation to its explicitly bound argv.
+          #
+          # @param operation [Symbol] key in {FORMS}
+          # @param target [Target] validated selected repository
+          # @param arguments [Array] per-operation arguments
+          # @raise [Ace::Git::ProviderUnsupportedCapabilityError] when the
+          #   operation has no observed form
+          def argv_for(operation, target, arguments)
+            form = FORMS.fetch(operation) do
+              raise Ace::Git::ProviderUnsupportedCapabilityError,
+                "forgejo-cli #{OBSERVED_VERSIONS.join("/")} exposes no repository-bound " \
+                "argv form for #{operation.inspect}; refusing to run it against #{target.repo}"
+            end
+            form.call(target, *arguments)
+          end
+
+          # Refuse to launch repository commands when the readable fj keys
+          # file contains an alias that redirects the selected host. fj
+          # v0.6.0 applies its `aliases` map to `-H` values (observed: an
+          # alias silently rewrites the endpoint), and no CLI command prints
+          # aliases, so ACE verifies the one configuration file it must
+          # agree with — read-only, never modified. An absent or unreadable
+          # keys file (other fj versions, moved storage) cannot be verified
+          # and is allowed; misdirected runtime requests still classify
+          # through the shared taxonomy.
+          #
+          # @param host_url [String] selected scheme://authority
+          # @param config_path [String, nil] explicit keys-file path (tests)
+          # @raise [Ace::Git::ConfigError] on a conflicting redirect
+          def reject_selected_host_redirect!(host_url, config_path: nil)
+            path = config_path || default_keys_path
+            return unless path && File.exist?(path)
+
+            data = JSON.parse(File.read(path))
+            aliases = data.is_a?(Hash) ? data["aliases"] : nil
+            return unless aliases.is_a?(Hash)
+
+            selected = strip_scheme(host_url)
+            redirect = aliases[selected] || aliases[host_url.to_s]
+            return if redirect.nil? || redirect.to_s.empty?
+
+            redirect_authority = strip_scheme(redirect)
+            return if redirect_authority.casecmp(selected).zero?
+
+            raise Ace::Git::ConfigError,
+              "fj configuration redirects selected host #{selected} to #{redirect} " \
+              "(#{path}); remove or fix the conflicting fj alias — ACE will not " \
+              "operate on a redirected endpoint"
+          rescue JSON::ParserError, IOError, SystemCallError
+            nil
+          end
+
+          # Observed forgejo-cli v0.6.0 keys-file locations (data_dir of the
+          # `directories` crate, plus the legacy Cyborus org path).
+          def default_keys_path
+            candidates = []
+            xdg = ENV["XDG_DATA_HOME"]
+            candidates << File.join(xdg, "forgejo-cli", "keys.json") if xdg && !xdg.empty?
+            home = Dir.home rescue nil
+            if home
+              candidates << File.join(home, ".local", "share", "forgejo-cli", "keys.json")
+              candidates << File.join(home, "Library", "Application Support", "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")
+            end
+            candidates.find { |path| File.exist?(path) }
+          end
+
+          private
+
+          def strip_scheme(url)
+            url.to_s.sub(%r{\A[a-z][a-z0-9+.\-]*://}i, "").chomp("/")
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/ace/git/forgejo.rb

@@ -3,6 +3,7 @@
 require "ace/git"
 
 require_relative "forgejo/version"
+require_relative "forgejo/repository_binding"
 require_relative "forgejo/cli_executor"
 require_relative "forgejo/pr_identifier"
 require_relative "forgejo/parsers"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-git-forgejo
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-28 00:00:00.000000000 Z
+date: 2026-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-git
@@ -42,6 +42,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/repository_binding.rb
 - lib/ace/git/forgejo/version.rb
 homepage: https://forgejo.tail6c0887.ts.net/cs3b/ace
 licenses: