beads/scripts/ci
CI Bot e988fd002d feat(httpapi): OpenAPI v0 spec, types-only codegen, and the drift gates (bd-ilb)
Lands the bd serve wire contract and the machinery that keeps it honest. No
runtime behavior: nothing routes, nothing serves, and no CLI surface changes.

internal/httpapi/spec/openapi.v0.yaml is hand-written and is the source of
truth; internal/httpapi/apigen is generated from it with oapi-codegen
types-only (no server stubs, no router), via a go.mod tool directive so
contributors need no extra install.

The decisions this slice fixes, because they are one-way doors:

- No second wire struct. Issue, IssueWithCounts, IssueDetails and
  IssueWithDependencyMetadata are pinned to the canonical Go types with
  x-go-type, so the generator emits type aliases and the CLI's --json, the
  JSONL interchange and the HTTP bodies all marshal one struct. A hand-written
  Go-to-Go mapping layer would recreate the drift disease this epic exists to
  cure. Guarded by a two-way JSON-tag bijection test, not a round-trip fixture:
  a new omitempty field absent from a fixture round-trips cleanly in both
  directions and proves nothing.
- limit=0 means unlimited, matching the CLI exactly, with defaults 50 (list)
  and 100 (ready) documented as the shared constants. The only exception --
  refusal under --allow-non-loopback -- is in the limit description.
- ready returns IssueWithCounts, not bare Issue.
- Unknown query parameters are rejected with 400 invalid_argument naming the
  parameter in a machine-readable extension member: with types-only codegen the
  decoders are hand-written, and Go's silent-ignore default would WIDEN a
  filtered result set under version skew.
- /v0/beads/issues forces (created_at DESC, id ASC) on every request, and the
  spec documents the deliberate divergence from bd list's priority ordering.
- One RFC 9457 problem+json envelope everywhere, with a frozen code vocabulary
  mapped from the sentinels via errors.Is. 5xx bodies carry a static per-code
  detail; the real error goes only to the log, because driver and dial errors
  routinely embed the DSN.
- Only the status codes the six operations need are documented. Every
  documented status+code pair is permanent wire surface.

Two traps found while building this, both now guarded:

- oapi-codegen v2.6.0 silently drops x-go-type from a component that also
  carries allOf. An allOf-composed IssueWithCounts generated
  "type IssueWithCounts = types.Issue" -- the ready endpoint would have shipped
  with the count fields gone. The pinned schemas therefore repeat their
  property lists, and internal/httpapi/pinning.go turns a regression into a
  build failure.
- context.DeadlineExceeded satisfies net.Error, so a tripped request deadline
  would have mapped to 503 db_unavailable instead of a generic 500.

make api-check is the three-part gate (regenerate, diff-or-fail, spec tests)
and runs from scripts/ci/pr-policy.sh, i.e. in a required PR job -- the Main
workflow is perpetually concurrency-cancelled, so a gate living only there
would be unenforced.

The go.mod diff is the tool directive and its closure. The protocol corpus is
untouched.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-07-31 08:37:34 +00:00
..
go-list-test-names Add PR CI wrapper command surface (#4211) 2026-05-29 18:52:53 -07:00
lib Add PR CI wrapper command surface (#4211) 2026-05-29 18:52:53 -07:00
detect-package-gates.sh docs: go all-in on Mintlify — delete the Docusaurus site and its machinery 2026-07-12 10:37:17 -07:00
gen_proxied_shard_manifest.py test(proxied): split the six heaviest suites so shards balance under the timeout 2026-07-20 15:55:17 -07:00
go-test-shard-names.sh Add PR CI wrapper command surface (#4211) 2026-05-29 18:52:53 -07:00
go-test-shard-packages.sh Add PR CI wrapper command surface (#4211) 2026-05-29 18:52:53 -07:00
package-mcp.sh Add PR CI wrapper command surface (#4211) 2026-05-29 18:52:53 -07:00
package-npm.sh Add PR CI wrapper command surface (#4211) 2026-05-29 18:52:53 -07:00
pr-core.sh Add PR CI wrapper command surface (#4211) 2026-05-29 18:52:53 -07:00
pr-lint.sh ci(lint): cross-lint Windows-tagged Go, fix fmt-check exit status, pin golangci-lint (core of #5075) (#5083) 2026-07-26 12:41:18 -07:00
pr-policy.sh feat(httpapi): OpenAPI v0 spec, types-only codegen, and the drift gates (bd-ilb) 2026-07-31 08:37:34 +00:00