yellowjacket/packaging/homebrew/README.md

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

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.

Upgrading from 1.x needs a reinstall, once

Releases became automatic and restarted at 0.0.1 (plan 017), which is lower than the 1.3.0 this tap last published. Homebrew compares versions and has no equivalent of pacman's epoch, so brew upgrade sees a downgrade and offers nothing at all — silently, which is indistinguishable from the tap having gone stale.

brew uninstall yellowjacket && brew install shadow-puppet/yellowjacket/yellowjacket

Nothing is stored inside the Cellar, so this costs a rebuild and no data. It is a one-time step: 0.0.2 onwards upgrade normally.

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: under Wails v3 the bundling is a separate step from the build. wails3 task build produces a bare yellowjacket binary in bin/ on both platforms; on macOS the formula runs wails3 task package instead, which wraps that binary in a yellowjacket.app (installed under the Cellar with an exec shim in bin).
• Linuxbrew: building on Linux additionally needs the system WebKitGTK/GTK stack (webkitgtk-6.0, gtk4, alsa-lib) — OS packages, not Homebrew deps. v2's webkit2gtk-4.1/gtk3 is now only the -tags gtk3 escape hatch. 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.