ace-git-forgejo 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7388b7c2b27b633234131dca7f190a344c7e1f323e23e2e01b532ed3a16407a
-  data.tar.gz: 3960cdfc787b85500050589ac27b1a8bceb8d3e5cd594eb37db2448d7e314426
+  metadata.gz: b31bdebd863b7bee391783037e9aef4dab2a1ac4bede0b2b897e8442ac297b7f
+  data.tar.gz: db3a546c09effeda3781370316a691cb893af860cb0212ef982320a521ab9cc0
 SHA512:
-  metadata.gz: 77a634e5f5f9de6c004a2585e57379104062f11e6eee34532edb390c8200aeaba6d3fc3433ec21ccc6e6ee1a1a3aca22b47b99e83890982e9f8d4ef7400bd045
-  data.tar.gz: c13861e169c6bb26db7bde14c400186677f01c70c185bec7d07a374b6fdcde08717b27ef7233900da128072587af39393af5dc0584603085d0c8293eeba9aff1
+  metadata.gz: b4323793a3d0b8b0f217bf7acca41d31d89dc9316b14c51509352edc903760d6811e7412497d1189bf9339cd774154ac6fbc70b506d4c0587a017a3bc8dce2f9
+  data.tar.gz: e501d7e7d7ddf48e3194eb6a110c29df8984ba5f873295c0d6bbbbaa621987dcd814f50ede1fb594eb7f18c605dd1b8bc98edb2ca95a3cb6837db8f7a829d305

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-10-04
+
+### Fixed
+- Prove Forgejo's source repository selector before PR creation and bind accepted receipts to source/base repository IDs, refs, SHA and draft state. Incomplete accepted responses and failed verification remain unknown outcomes without replay.
+
+## [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.
+- The unused `expected_head` plumbing on the review-comment reconciliation helpers (internal refactor; no behavior change).
+
 ## [0.5.0] - 2026-10-03
 
 ### Added
@@ -75,19 +94,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,48 @@ 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.
+
+Create preflight verifies the repository that Forgejo's `owner:branch` selector resolves, including direct forks and a fork's parent. Sharing an owner, branch or SHA does not establish source identity. An accepted create returns a receipt only when the response and authoritative read agree with the requested repository IDs, refs, SHA and draft state. A failed or contradictory verification stays `unknown_outcome`; reconcile by reading the exact identity before authorizing another mutation.

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,99 @@ 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/")
+
+          return "/api/v1/repos/#{@target.repo}" if suffix.to_s.empty?
+
+          "/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))