build(packaging): add Homebrew tap formula and release sync

Build-from-source formula for macOS/Linuxbrew, mirroring the Arch PKGBUILD. A Gitea workflow recomputes the tarball checksum on each version tag and syncs the formula into the homebrew-yellowjacket tap repo, so releases need no manual formula edits. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-24 15:01:33 -04:00
parent a181a98ce3
commit d3fc2b9237
3 changed files with 227 additions and 0 deletions
@@ -0,0 +1,76 @@
+# YellowJacket Homebrew formula
+
+The formula builds YellowJacket from source on macOS and Linuxbrew, mirroring
+the Arch `PKGBUILD`: the Wails toolchain resolves from `go.mod`'s tool
+directives and drives the frontend build itself, so the only build inputs are
+Go, Node, and pnpm.
+
+```
+packaging/homebrew/
+└── Formula/
+    └── yellowjacket.rb   ← canonical source; CI syncs it to the tap repo
+```
+
+## Installing
+
+```bash
+brew install shadow-puppet/yellowjacket/yellowjacket
+```
+
+`shadow-puppet/yellowjacket` is Homebrew shorthand for the tap repo
+`github.com/Shadow-Puppet/homebrew-yellowjacket`. Brew auto-taps it, so there's
+no separate `brew tap` step. To build the tip of `main` instead of the latest
+release, add `--HEAD`.
+
+## How publishing works
+
+This directory holds the **canonical** formula. The tap users install from lives
+in a **separate** repo — `homebrew-yellowjacket` — because Homebrew only
+discovers formulae from a repo whose name starts with `homebrew-`, with the
+formula at a top-level `Formula/`. Keeping it separate is also why nothing has
+to live in this repo's root.
+
+On every version tag (`v*`), `.gitea/workflows/homebrew-formula.yml`:
+
+1. downloads the GitHub release tarball for that tag,
+2. computes its `sha256`,
+3. rewrites the `version` and `sha256` lines in the formula, and
+4. commits the result to `homebrew-yellowjacket`'s `Formula/yellowjacket.rb`.
+
+So a normal release needs **no manual formula edits** — tag, and the tap updates
+itself. (This is the Homebrew equivalent of the Arch package's publish workflow.)
+
+### About the `sha256`
+
+Homebrew re-downloads the source tarball on each install and refuses to build
+unless its checksum matches `sha256` — integrity/tamper detection. The committed
+value here is a `REPLACE_WITH_...` placeholder on purpose; the real checksum is
+computed and injected by CI at release time, so it never has to be maintained by
+hand. (The Arch `PKGBUILD` sidesteps this with `SKIP` because it clones over git
+rather than downloading a tarball.)
+
+## One-time setup
+
+1. **Create the tap repo:** `Shadow-Puppet/homebrew-yellowjacket` on GitHub,
+   with a `main` branch. It can start empty — the first tagged release seeds
+   `Formula/yellowjacket.rb`.
+2. **Add a CI secret:** `HOMEBREW_TAP_TOKEN` — a GitHub token with write access
+   to that repo (a fine-grained PAT scoped to `homebrew-yellowjacket`, Contents:
+   read/write, is enough).
+
+That's it. The source repo must be public (or the tap private with an
+authenticated `brew install`) for brew to fetch the release tarball.
+
+## Notes
+
+- **License**: declared as `license :cannot_represent` (custom license). Replace
+  with the correct SPDX identifier once the license is finalized.
+- **macOS vs Linux**: `wails build` produces a `YellowJacket.app` bundle on
+  macOS (installed under the Cellar with an `exec` shim in `bin`) and a bare
+  `yellowjacket` binary on Linux (installed to `bin`).
+- **Linuxbrew**: building on Linux additionally needs the system WebKitGTK/GTK
+  stack (`webkit2gtk-4.1`, `gtk3`, `alsa-lib`) — OS packages, not Homebrew deps.
+  macOS needs only the Xcode Command Line Tools.
+- **Cask alternative**: if you later ship prebuilt macOS `.dmg`/`.zip` artifacts,
+  a Homebrew *cask* pointing at those installs faster than this source build.
+  This formula is the source-build path.