ace-git-forgejo 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f71ec19c2631e884747c20ba07ad19b595fff3ad52c4505571d3f91da61f2ff
-  data.tar.gz: ca8d1ff36047ef554da1fa8b23285b7fb01d486b35bde3321b03d199ba92ffb0
+  metadata.gz: e1e1e605a8808db94b0b68ad90d445149f8fce01df65f7ddad401f59a0fce255
+  data.tar.gz: 312685879a60d54363626b6f7dc98d2954b0575120aeb0dde0e128826252fba6
 SHA512:
-  metadata.gz: 6cddccbd90c235fe84a052c58dfe3030a6c3b826527da34681d4316579c46e798bc1ca212ee438f5020be3d47ac77d51fc99729ca2805d1f7c3e3f0c0046b30a
-  data.tar.gz: 621fa2ebff13f4e344dba8500ad40b2e41604a97c39282979424d9eaf942c32c2f266be1f3aaa74037f1244924dd73518067f74d19a93162d0378f3781dcc487
+  metadata.gz: 85a2d43f44c7d07d7c60c236f9a5c81c350233fca510c4a6503181f42ab2052a50e31094380e1a2ac752a55bb3ecdaf6923376a439197c459c1a71a66ed21364
+  data.tar.gz: ddfee8db45e1545dfb7592e77396255a71d90e083c455a1507ee412da71482fee2a499c098c47ed59cbcc0b6abe46952cea8faa5b151d97b2521106c5e2f6bc8

data/CHANGELOG.md

@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- 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

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/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/parsers.rb

@@ -116,18 +116,37 @@ 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 a leading "<n> tasks" count header before task lines.
+            if (header = line.match(/\A(\d+) tasks?\z/i))
+              declared_count = header[1].to_i
+              next
+            end
+
             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.
+            raise Ace::Git::ProviderMalformedOutputError,
+              "Unrecognized `fj actions tasks` output line: #{line[0, 80]}" unless match
 
-            {
+            tasks << {
               name: match[:name],
               state: match[:state].downcase.to_sym,
               sha: match[:sha]
             }
           end
+          # A declared count that disagrees with the parsed rows means
+          # truncated output; fail closed instead of accepting partial
+          # check evidence.
+          if declared_count && 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.