Skip to content

docs(adr): supersede 0004 with 0005 vendor-binaries implementation plan - #41

Merged
johnnyhuy merged 1 commit into
mainfrom
docs/adr-0005-vendor-binaries
Aug 18, 2026
Merged

docs(adr): supersede 0004 with 0005 vendor-binaries implementation plan#41
johnnyhuy merged 1 commit into
mainfrom
docs/adr-0005-vendor-binaries

Conversation

@johnnyhuy

Copy link
Copy Markdown
Contributor

Summary

ADR-0004 reserved the decision to bundle bw/op/sops/age but left sourcing, layout, signing, and resolution semantics as follow-ups. ADR-0005 replaces it with the concrete plan.

Changes

  • ADR-0004 → superseded. Frontmatter now points at 0005.
  • ADR-0005 (new). Implementation-ready plan covering what bundles vs. what ships as an npm dep, the resources/bin/<platform>-<arch>/ layout, the build-time fetch (pinned vendor-versions.json, sha256 verification), runtime resolution, lazy backend loading, macOS re-signing for Gatekeeper, and a diagnostics row per binary.
  • Resolution order deliberately reversed from 0004: env override → $PATH → bundled. Reasoning in the ADR: bw and op carry the user's auth state (BW_SESSION, biometric unlock, op service-account token), so the installed copy wins. sops/age are stateless so bundling wins on convenience — but uniform PATH-first is easier to reason about and the env override gives power users an escape hatch.

Consequences

  • +~50 MB macOS / +~35 MB Linux / +~30 MB Windows to app size. sops is the largest single contributor.
  • vendor-versions.json becomes a chore; bumps ride Hoist releases for v1.
  • macOS CI gains a DEVELOPER_ID_APPLICATION + notarisation dependency. Linux/Windows dev builds stay unsigned (no Gatekeeper).
  • People who read ADR-0004 in isolation will be surprised by the resolution-order flip. Mitigated by the frontmatter link.

Testing

  • This is docs only — no CI run.

Refs: ADR-0001 (backend abstraction), ADR-0004 (superseded stub).

ADR-0004 reserved the decision to bundle bw/op/sops/age but left sourcing,
layout, signing, and resolution semantics as follow-ups. ADR-0005 replaces it
with the concrete plan:

- what ships as extraResources vs. npm dep (and why)
- layout under resources/bin/<platform>-<arch>/
- build-time fetch from pinned vendor-versions.json with sha256 verification
- runtime resolution order: env override > \$PATH > bundled (opposite of
  0004 — deliberate, so the user's authenticated bw/op wins; sops/age are
  stateless so bundled is fine)
- lazy backend loading so vendor processes aren't spawned on launch
- macOS re-signing of unsigned sops/age with our Developer ID to clear
  Gatekeeper
- diagnostics row per vendor binary (version + resolved path)

Co-authored-by: opencode <noreply@opencode.ai>
@johnnyhuy
johnnyhuy enabled auto-merge (squash) August 18, 2026 12:42
@johnnyhuy
johnnyhuy merged commit ee13c1c into main Aug 18, 2026
7 checks passed
@johnnyhuy
johnnyhuy deleted the docs/adr-0005-vendor-binaries branch August 18, 2026 12:43
@github-actions github-actions Bot mentioned this pull request Aug 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant