ace-git-forgejo 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1e1e605a8808db94b0b68ad90d445149f8fce01df65f7ddad401f59a0fce255
-  data.tar.gz: 312685879a60d54363626b6f7dc98d2954b0575120aeb0dde0e128826252fba6
+  metadata.gz: cf55e32720105f61ee776ab2e828cc52eff70422d40169c3ec473faa8918852e
+  data.tar.gz: d53c30cfdd65d9efd401846871c8572a48442c68d280a0615e7d9b04c8792b45
 SHA512:
-  metadata.gz: 85a2d43f44c7d07d7c60c236f9a5c81c350233fca510c4a6503181f42ab2052a50e31094380e1a2ac752a55bb3ecdaf6923376a439197c459c1a71a66ed21364
-  data.tar.gz: ddfee8db45e1545dfb7592e77396255a71d90e083c455a1507ee412da71482fee2a499c098c47ed59cbcc0b6abe46952cea8faa5b151d97b2521106c5e2f6bc8
+  metadata.gz: c3d888812cbbec6e223ddfca72514bbee53f3281374825b4147c4f1ebc3fd415528f4fc5c08eafadb6cfed35df6acac4220955f629e15b90dc593d91ceee963c
+  data.tar.gz: 9dd8b2e6fed777a0c038b111e448c536c0a960c7a7ff53e6d0d9ca1e200bd083e591cb35bf6d7943ec552e206b006021a7314b9bb615e93a9df1a34e179c1f98

data/CHANGELOG.md

@@ -7,13 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-04
+
+### Added
+- Complete PR delivery lifecycle over the repository-bound Forgejo API v1: create with canonical and same-server fork heads and exact draft state, mark-ready, and merge with the server-enforced `head_commit_id` expected-head precondition (minimum supported server: Forgejo 8.0 — first line enforcing the merge precondition and reporting the API draft field — probed before mutations).
+- Authoritative pull request reads from the API: exact head provenance, draft state, and merge-commit evidence replace the fj view/commits pair for PR identity.
+- Duplicate-create races reconcile to the exact open match; already-merged refusals are reusable only with authoritative merged evidence at the expected source SHA.
+
+### Changed
+- PR reads, lifecycle matching, and updates ride the Faraday HTTP transport (ADR-010) with retries limited to safe GETs and no redirect following; lifecycle mutations are gated on a documented server capability floor and fail closed without it.
+
+### Removed
+- The fj-era refusals for fork creation, draft-to-ready, and expected-head merging; the conservative `fj pr merge`/`pr edit` paths are replaced by the API lifecycle.
+
+## [0.5.0] - 2026-10-03
+
+### Added
+- Forgejo issue tracking through the shared provider contract with selected-server authority checks and parsed issue evidence.
+
+### Fixed
+- Missing tracking labels are created on demand before attachment, forbidden organization-label listings fall back to repository labels, and fj credentials are found in the real macOS bundle directories (forgejo-cli.forgejo-cli, legacy Cyborus.forgejo-cli).
+
 ## [0.4.0] - 2026-10-02
 
 ### Added
 - Repository-bound Forgejo PR comment and review retrieval and comment create/update through the shared provider contract.
 - Correlation-based reconciliation after uncertain posts and explicit unsupported thread resolution.
 
-
 ## [0.3.0] - 2026-09-29
 
 ### Added
@@ -68,19 +88,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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
 
 

data/README.md

@@ -36,16 +36,15 @@ 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`).
+Through `fj` (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`), issue view, actions tasks, repository view, version and
+`auth list` probes. Through the repository-bound API v1: authoritative PR
+reads, PR create (canonical and same-server fork heads, exact draft
+state), edit, ready transitions, and expected-head-guarded merges — see
+the delivery lifecycle section below. The per-surface capability evidence
+and its provenance live in the `8wr.t.uj0` (`evidence/fj-capabilities.md`)
+and `8x2.t.z78` (`capability-evidence-2026-10-04.md`) task folders.
 
 Endpoint fidelity: `-H` carries the selected `scheme://authority` (fj
 otherwise assumes HTTPS), and because fj v0.6.0 silently applies its
@@ -54,3 +53,46 @@ 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.
 
+## PR delivery lifecycle (Forgejo API v1)
+
+The delivery lifecycle — create (canonical and same-server fork sources,
+exact draft state), mark-ready, and merge with a server-enforced
+expected-head precondition — rides the repository-bound Forgejo REST API
+v1 through the same selected host and `fj` token as the review transport.
+The `fj` v0.6 CLI cannot encode a fork head, an explicit draft state, a
+ready transition, or an atomic merge precondition, so those operations do
+not approximate it with check-then-act sequencing.
+
+Minimum supported server: **Forgejo 8.0** (the first line that both
+enforces the documented `MergePullRequestOption.head_commit_id` merge
+precondition server-side and reports the API `draft` field; the provider
+probes `/api/v1/version` and refuses lifecycle mutations below the
+floor). Official capability evidence lives in the
+`8x2.t.z78` task folder (`capability-evidence-2026-10-04.md`).
+
+Forgejo-specific conventions the provider translates:
+
+- **Drafts**: the create/edit API forms have no writable draft field —
+  a draft is a WIP-prefixed title (server defaults `WIP:`, `[WIP]`;
+  compared case-insensitively). The server reports the computed boolean
+  in the API `draft` response field, which this provider treats as the
+  only draft truth on reads. Create with
+  `draft: true` prefixes the title `WIP: `; `draft: false` refuses a
+  WIP-prefixed title instead of silently publishing it as a draft. Ready
+  strips one leading prefix and proves the resulting `draft: false` by
+  read-back. A draft whose title carries no known prefix refuses before
+  the mutation (the server likely uses configured prefixes).
+- **Merge** sends the full expected SHA in `head_commit_id`; Forgejo
+  re-resolves the head ref inside the merge and refuses with 409 when it
+  moved. The provider classifies that as
+  `ProviderExpectedHeadConflictError` and never pre-reads as a substitute
+  guard. A 409 that reads back as already merged at the expected source
+  SHA, with a merge commit, is reusable authoritative evidence.
+- **Reconciliation**: a transport failure on any mutation raises
+  `ProviderUnknownOutcomeError` carrying the exact identity; nothing is
+  retried automatically. A duplicate-create 409 reconciles to the exact
+  open match; mutation outcomes are proven by authoritative read-backs
+  (head unchanged, requested state, merged evidence).
+
+Identical lifecycle assertions run against every provider through the
+shared `Ace::TestSupport::PullRequestLifecycleContract` parity suite.

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

@@ -2,9 +2,9 @@
 
 require "digest"
 require "json"
-require "net/http"
+require "faraday"
+require "faraday/retry"
 require "openssl"
-require "uri"
 require_relative "repository_binding"
 
 module Ace
@@ -12,6 +12,13 @@ module Ace
     module Forgejo
       # Authenticated, repository-bound JSON transport for Forgejo API
       # capabilities whose fj v0.6 output omits stable object IDs.
+      #
+      # Live traffic uses Faraday (ADR-010): no redirect middleware is
+      # installed (a redirect must never carry credentials or a write to
+      # another host; the configured endpoint is verified up front by
+      # {RepositoryBinding.reject_selected_host_redirect!}), and retries are
+      # limited to the safe GET verb — a mutation is sent at most once per
+      # call, so a lost response stays an unknown outcome.
       class HttpClient
         def initialize(server:, timeout:, runner: nil)
           @target = RepositoryBinding::Target.resolve(server.url)
@@ -44,40 +51,97 @@ module Ace
           entries
         end
 
+        # Send one request and classify every non-success status with the
+        # shared taxonomy.
+        #
+        # @return [Object, nil] parsed JSON body (nil when empty)
         def request(method, suffix, body: nil)
+          status, payload = exchange(method, suffix, body: body)
+          classify_status!(status, method, exchange_path(suffix))
+          payload
+        end
+
+        # Send one request and return the raw HTTP outcome so endpoint-aware
+        # callers can classify statuses the generic map cannot distinguish
+        # (e.g. a 409 that may mean "already exists" on create or "head out
+        # of date" on merge). Transport failures still classify by method:
+        # reads are unreachable, mutations are unknown outcomes.
+        #
+        # @return [Array(Integer, Object, nil)] status, parsed JSON body
+        #   (nil when empty), and the server-supplied error message for
+        #   non-success statuses (sanitized, truncated)
+        def exchange(method, suffix, body: nil)
           RepositoryBinding.reject_selected_host_redirect!(@target.host_url)
-          path = "/api/v1/repos/#{@target.repo}/#{suffix}"
+          path = exchange_path(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
+            response = connection(method).send(method, path) do |req|
+              req.headers["Content-Type"] = "application/json" if body
+              req.body = JSON.generate(body) if body
+            end
+            status = response.status
             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
+          [status, parse_payload(payload), server_error_message(payload)]
+        rescue Faraday::TimeoutError, Faraday::ConnectionFailed, 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
 
+        # Suffixes already carrying the API root are used verbatim (the
+        # server-level /api/v1/version probe); everything else is
+        # repository-scoped to the selected owner/repo.
+        def exchange_path(suffix)
+          return suffix if suffix.to_s.start_with?("/api/v1/")
+
+          "/api/v1/repos/#{@target.repo}/#{suffix}"
+        end
+
+        # A non-JSON body is an absent payload, not a parse failure: the
+        # status carries the outcome, and every consumer validates the shape
+        # of what it reads, so malformed evidence still fails closed.
+        def parse_payload(payload)
+          return nil if payload.nil? || payload.empty?
+
+          JSON.parse(payload)
+        rescue JSON::ParserError
+          nil
+        end
+
+        # The forge's own explanation for a failed status, sanitized: only
+        # the JSON `message` string survives, truncated, so tokens and raw
+        # response bodies never reach an error message.
+        def server_error_message(payload)
+          parsed = parse_payload(payload)
+          return nil unless parsed.is_a?(Hash) && parsed["message"].is_a?(String)
+
+          message = parsed["message"].strip
+          message.empty? ? nil : message[0, 300]
+        end
+
+        # Connection per HTTP method: the retry middleware is installed only
+        # for the safe verb so a mutation can never be silently re-sent.
+        def connection(method)
+          @connections = {} unless @connections.is_a?(Hash)
+          @connections[method] ||= Faraday.new(url: @target.host_url) do |faraday|
+            faraday.options.timeout = @timeout
+            faraday.options.open_timeout = @timeout
+            faraday.headers["Accept"] = "application/json"
+            faraday.headers["Authorization"] = "token #{access_token!}"
+            if method == :get
+              faraday.request :retry, max: 2, methods: [:get], retry_if: ->(_env, _result) { false }
+            end
+            faraday.adapter Faraday.default_adapter
+          end
+        end
+
         def access_token!
           path = RepositoryBinding.default_keys_path
           data = path && JSON.parse(File.read(path))

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

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

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

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