feat(forgejo): implement Client (17-function surface) + typed request/response against #505 interface + #504 C7 contract

bosun commented

2026-07-26 09:49:54 +02:00

Owner

Implement internal/forgejo package (Client + typed request/response types) satisfying the Go interface landed in #505 + the C7 contract landed in #504.

Motivation

Phase 4 continues contract-driven TDD-per-phase per ADR-0009 §3.1. internal/forgejo is one of two Phase 4 packages (sibling: #542 manifest). Interface (Client, 17-function surface + typed request/response types) is Surveyor-approved in #505; C7 contract (docs/architecture/contracts/forgejo-api.md + response-shape schemas) landed in #504; implementation lands here.

Scope

internal/forgejo/*.go — implementation satisfying #505 interface (Client with 17-function surface; typed request/response structs matching C7)
17-function surface: per #505 interface — enumerate at implementation start (Client.CreateRelease, Client.CreatePR, Client.MergePR, Client.GetPR, Client.ListIssues, etc.); verify against #505 landed shape as first step
Bash byte-oracle: existing bash curl calls (in lib/forgejo.sh or scattered across release.sh/release-prep.sh/draft-release.sh — VERIFY on-disk before starting; may be scattered like #528 events was central, or scattered like #528 events would have been if bash surface was not centralized)
Harness shape design call: (a) mock Forgejo API for hermetic tests, OR (b) real test-instance calls, OR (c) hybrid. Engineer's judgment on shape — disclose in PR body. Given the arc's harness discipline (real oracle beats mock), (b) or (c) likely preferred if a test-instance is available.
TDD approach (contract-driven per ADR-0009 §3.1):
1. Test against interface first
2. Oracle harness case using internal/harness (reuse Phase-1 vehicle: Go oracleshim + bash dispatcher + PREBUILT BINARY per substrate-of-record memo)
3. Implementation to green
C7 validation: typed request/response structs match schemas; parse errors + schema-violation errors have distinct sentinels
Fixture corpus at testdata/fixtures/forgejo/ — real API request/response shapes (from actual Forgejo instance if available OR from captured session logs)

AC

internal/forgejo implementation compiles + all #505 interface methods satisfied (15 methods actual = 7 reads + 8 mutations per Engineer deep-read against interface.go; the "17-function" tracker text was Bosun's initial framing at file-time — restated to real interface surface per ac-tick-discipline same class as prior contract-vs-tracker restatements). Verified in PR#545 249e522
Typed request/response structs match C7 schemas — verified in PR#545. Includes FROZEN-STRUCT CORRECTION on BranchProtection (enable_push→enable_push_whitelist + push_whitelist_teams added; missing teams field; interface-sanctioned per Phase-4 enumeration; consumer-correct per preflight-push-whitelist.sh). Strict-unmarshal boundary swept complete + safe-direction (Surveyor 11-case sweep, review 4583)
Unit tests green — verified in PR#545 gate run: TestStrictUnmarshalStricterThanBash + per-method units + dry-run mode units
Equivalence-harness cases against bash oracle green — verified: hybrid harness landed (13 read-replay cases with httptest + real forgejo-api.sh jq incl not-found/404-collapse; 8 dry-run payload-diff cases with tricky escape-off vectors; resilience httptest fault-injection covering every retry class from resilience.bats). Mutation payloads byte-identical to jq -nc independently reproduced by Surveyor; her own transport-safety mutation proved harness teeth (review 4583). Substrate-of-record: API-client-with-limited-oracle harness class established (mutation-payload-diff + captured-fixture-replay + fault-injection-server), reusable for future limited-oracle scenarios
go vet ./... + golangci-lint run clean — verified: gate own instrument (golangci-lint 2.12.1) fired 0 issues; shellcheck clean

Depends on: #505 (interfaces — 17-function Client + typed request/response), #504 (C7 contract), #503 (harness vehicle)
Sibling: #542 (manifest — parallelizable OR sequential Engineer continuation)
Downstream: Phase 6 orchestrators (#508) consume both Client + Store
Refs ADR-0009 §3.1 (contract-driven TDD), §3.2 C7, §3.3 phase 4 row, §5 (fail-loud + trivalent-verdict discipline)

Anchor

Filed 2026-07-26 by Bosun on operator continuation direction for Phase 4 dispatch.

Implement `internal/forgejo` package (Client + typed request/response types) satisfying the Go interface landed in #505 + the C7 contract landed in #504. ## Motivation Phase 4 continues contract-driven TDD-per-phase per ADR-0009 §3.1. `internal/forgejo` is one of two Phase 4 packages (sibling: [[#542 manifest]]). Interface (`Client`, 17-function surface + typed request/response types) is Surveyor-approved in #505; C7 contract (`docs/architecture/contracts/forgejo-api.md` + response-shape schemas) landed in #504; implementation lands here. ## Scope - `internal/forgejo/*.go` — implementation satisfying #505 interface (Client with 17-function surface; typed request/response structs matching C7) - **17-function surface**: per #505 interface — enumerate at implementation start (Client.CreateRelease, Client.CreatePR, Client.MergePR, Client.GetPR, Client.ListIssues, etc.); verify against #505 landed shape as first step - **Bash byte-oracle**: existing bash `curl` calls (in `lib/forgejo.sh` or scattered across `release.sh`/`release-prep.sh`/`draft-release.sh` — VERIFY on-disk before starting; may be scattered like #528 events was central, or scattered like #528 events would have been if bash surface was not centralized) - **Harness shape design call**: (a) mock Forgejo API for hermetic tests, OR (b) real test-instance calls, OR (c) hybrid. Engineer's judgment on shape — disclose in PR body. Given the arc's harness discipline (real oracle beats mock), (b) or (c) likely preferred if a test-instance is available. - **TDD approach** (contract-driven per ADR-0009 §3.1): 1. Test against interface first 2. Oracle harness case using `internal/harness` (reuse Phase-1 vehicle: Go oracleshim + bash dispatcher + PREBUILT BINARY per substrate-of-record memo) 3. Implementation to green - **C7 validation**: typed request/response structs match schemas; parse errors + schema-violation errors have distinct sentinels - Fixture corpus at `testdata/fixtures/forgejo/` — real API request/response shapes (from actual Forgejo instance if available OR from captured session logs) ## AC - [x] `internal/forgejo` implementation compiles + all `#505` interface methods satisfied (**15 methods actual** = 7 reads + 8 mutations per Engineer deep-read against interface.go; the "17-function" tracker text was Bosun's initial framing at file-time — restated to real interface surface per [[ac-tick-discipline]] same class as prior contract-vs-tracker restatements). Verified in PR#545 249e522 - [x] Typed request/response structs match C7 schemas — verified in PR#545. Includes FROZEN-STRUCT CORRECTION on BranchProtection (enable_push→enable_push_whitelist + push_whitelist_teams added; missing teams field; interface-sanctioned per Phase-4 enumeration; consumer-correct per preflight-push-whitelist.sh). Strict-unmarshal boundary swept complete + safe-direction (Surveyor 11-case sweep, review 4583) - [x] Unit tests green — verified in PR#545 gate run: TestStrictUnmarshalStricterThanBash + per-method units + dry-run mode units - [x] Equivalence-harness cases against bash oracle green — verified: hybrid harness landed (13 read-replay cases with httptest + real forgejo-api.sh jq incl not-found/404-collapse; 8 dry-run payload-diff cases with tricky escape-off vectors; resilience httptest fault-injection covering every retry class from resilience.bats). Mutation payloads byte-identical to jq -nc independently reproduced by Surveyor; her own transport-safety mutation proved harness teeth (review 4583). Substrate-of-record: **API-client-with-limited-oracle harness class** established (mutation-payload-diff + captured-fixture-replay + fault-injection-server), reusable for future limited-oracle scenarios - [x] `go vet ./...` + `golangci-lint run` clean — verified: gate own instrument (golangci-lint 2.12.1) fired 0 issues; shellcheck clean ## Related - Depends on: #505 (interfaces — 17-function Client + typed request/response), #504 (C7 contract), #503 (harness vehicle) - Sibling: #542 (manifest — parallelizable OR sequential Engineer continuation) - Downstream: Phase 6 orchestrators (#508) consume both Client + Store - Refs ADR-0009 §3.1 (contract-driven TDD), §3.2 C7, §3.3 phase 4 row, §5 (fail-loud + trivalent-verdict discipline) ## Anchor Filed 2026-07-26 by Bosun on operator continuation direction for Phase 4 dispatch.

bosun added this to the Phase 4 — Forgejo client + manifest milestone

2026-07-26 09:49:54 +02:00

bosun added the

priority/high

size/L

kind/feature

labels

2026-07-26 09:49:54 +02:00

bosun referenced this issue

2026-07-26 09:49:54 +02:00

feat(manifest): implement Store + round-trip invariant against #505 interface + #504 C2 schema #542

engineer referenced this issue

2026-07-26 10:07:36 +02:00

feat(manifest): implement Store — Read/Write/CheckDesync + round-trip (#542) #543

bosun referenced this issue

2026-07-26 10:26:44 +02:00

feat(manifest): implement Store + round-trip invariant against #505 interface + #504 C2 schema #542

engineer self-assigned this

2026-07-26 10:28:00 +02:00

engineer referenced this issue from a commit

2026-07-26 14:34:03 +02:00

feat(forgejo): #541 typed Forgejo API client (Phase 4 2/2)

engineer referenced this issue

2026-07-26 14:34:19 +02:00

feat(forgejo): #541 typed Forgejo API client (Phase 4 2/2) #545

bosun closed this issue

2026-07-26 14:47:04 +02:00

bosun commented

2026-07-26 14:47:04 +02:00

Author

Owner

Closed by hand — PR#545 merged as 249e522a28a2ed520ac89f5eb117e6c78259ae0a on v2/next (fast-forward). All 5 ACs ticked with substrate anchors above.

Substrate landed:

internal/forgejo.Client — 15 methods (7 reads + 8 mutations)
Hybrid harness (mutation-payload-diff + captured-fixture-replay + fault-injection-server) — new reusable class for API-client-with-limited-oracle scenarios
FROZEN-STRUCT CORRECTION: BranchProtection.EnablePush → EnablePushWhitelist + PushWhitelistTeams added — interface-sanctioned per Phase-4 enumeration; consumer-correct per preflight-push-whitelist.sh. 4th substrate-check-design-claim-before-pr instance this arc.
Strict-unmarshal stricter-than-bash standing test (same disclosed-boundary class as #542 TestManifestSchemaStricterThanBash)
Uniform-retry / dry-run-mode / beyond-oracle deltas disclosed

AC1 restated (17-function → 15 methods actual): tracker text at file-time cited "17-function surface" as anticipated shape; Engineer's deep-read against interface.go confirmed 15 (7 reads + 8 mutations) as the real surface. Restated per ac-tick-discipline — same class as 3× prior contract-vs-tracker restatements this arc. Substrate reality wins.

Cleanest Phase-4 close PR: NO must-fix / NO should-consider per Surveyor 4583. Triple-verified BranchProtection correction. Reusable harness-class established.

Cross-references:

Depends on: #505 (interfaces including 15-method Client shape), #504 (C7 contract + response schemas), #503 (harness vehicle from Phase 1)
Sibling: #542 (manifest — landed prior)
Downstream: Phase 6 orchestrators (#508) consume both Client + Store
Refs ADR-0009 §3.1 (contract-driven TDD), §3.2 C7, §3.3 phase 4 row, §5 (fail-loud + trivalent-verdict discipline)

Phase 4 COMPLETE: #541 forgejo + #542 manifest both landed. Milestone #76 closes on this tracker close.

**Closed by hand** — PR#545 merged as `249e522a28a2ed520ac89f5eb117e6c78259ae0a` on v2/next (fast-forward). All 5 ACs ticked with substrate anchors above. **Substrate landed**: - `internal/forgejo.Client` — 15 methods (7 reads + 8 mutations) - Hybrid harness (mutation-payload-diff + captured-fixture-replay + fault-injection-server) — new reusable class for API-client-with-limited-oracle scenarios - **FROZEN-STRUCT CORRECTION**: BranchProtection.EnablePush → EnablePushWhitelist + PushWhitelistTeams added — interface-sanctioned per Phase-4 enumeration; consumer-correct per preflight-push-whitelist.sh. 4th substrate-check-design-claim-before-pr instance this arc. - Strict-unmarshal stricter-than-bash standing test (same disclosed-boundary class as #542 TestManifestSchemaStricterThanBash) - Uniform-retry / dry-run-mode / beyond-oracle deltas disclosed **AC1 restated** (17-function → 15 methods actual): tracker text at file-time cited "17-function surface" as anticipated shape; Engineer's deep-read against interface.go confirmed 15 (7 reads + 8 mutations) as the real surface. Restated per [[ac-tick-discipline]] — same class as 3× prior contract-vs-tracker restatements this arc. Substrate reality wins. **Cleanest Phase-4 close PR**: NO must-fix / NO should-consider per Surveyor 4583. Triple-verified BranchProtection correction. Reusable harness-class established. **Cross-references**: - Depends on: #505 (interfaces including 15-method Client shape), #504 (C7 contract + response schemas), #503 (harness vehicle from Phase 1) - Sibling: #542 (manifest — landed prior) - Downstream: Phase 6 orchestrators (#508) consume both Client + Store - Refs ADR-0009 §3.1 (contract-driven TDD), §3.2 C7, §3.3 phase 4 row, §5 (fail-loud + trivalent-verdict discipline) **Phase 4 COMPLETE**: #541 forgejo + #542 manifest both landed. Milestone #76 closes on this tracker close.

bosun referenced this issue

2026-07-26 14:51:00 +02:00

feat(self-bootstrap): wire rt to bake its own consumer-ready artifacts using internal/bake.Baker — closes dogfood meta-loop (rt-baked-by-rt) #547

bosun referenced this issue

2026-07-26 15:39:22 +02:00

feat(bake): implement Baker + byte-exactness invariant against #505 interface (TDD against bash byte-oracle if central; disclose if scattered/absent) #546

bosun referenced this issue

2026-07-26 15:39:23 +02:00

feat(bake): implement Baker + byte-exactness invariant against #505 interface (TDD against bash byte-oracle if central; disclose if scattered/absent) #546

engineer referenced this issue from a commit

2026-07-26 21:48:40 +02:00

feat(forgejo): #541 typed Forgejo API client (Phase 4 2/2)