Publish and test a third-party Homebrew tap formula after v0.2.0

[plx]

Parent

#26

Context

There is no Homebrew distribution today. Homebrew/core is not a realistic immediate target: at the 2026-07-25 audit the repository had four stars and no forks, below Homebrew’s package-acceptance thresholds. A maintained third-party tap is the appropriate first step after the audited 0.2.0 release exists.

This ticket is post-release convenience work, not a v0.2 release blocker. Do not create a formula that tracks a branch, mutable URL, or unaudited pre-release commit.

Required outcome

1. Choose and document the tap repository/ownership/support model, including the recovery owner established by Establish maintainer continuity, crates.io ownership, 2FA, and recovery controls #71 where appropriate.
2. Add a formula named consistently with the crate/binary that downloads an immutable v0.2.0 source archive or release artifact over HTTPS and verifies its exact SHA-256.
3. If building from source, use Homebrew’s Rust build dependency, the packaged lockfile, and an offline/locked build pattern supported by Homebrew. Do not fetch arbitrary dependencies during an ostensibly reproducible build.
4. Install shell completions/manpages only if generated reproducibly by the release process; do not synthesize behavior-specific assets from the mutable repository tip.
5. Add a functional formula test do block that creates a temporary guide/tree and proves both a valid verification success and an invalid verification failure. A --version-only test is insufficient.
6. Add tap CI (brew audit, style, source/bottle build as applicable, install, functional test, uninstall) on supported macOS runners. Pin all non-Homebrew Actions to immutable SHAs and minimize permissions.
7. Document brew tap, install, upgrade, uninstall, troubleshooting, support boundaries, and the relationship between tap version and upstream release.
8. Define a repeatable update procedure or automation that opens a reviewed PR for each upstream release and updates URL/version/checksum together.

Tests and validation

• Run brew audit --strict --online where appropriate for a third-party tap and resolve actionable findings.
• Install from a clean tap checkout on supported macOS architectures available to CI; assert --version equals 0.2.0.
• Execute the functional formula test, plus explicit invalid-guide and recursive zero-guide checks with expected non-zero statuses.
• Uninstall and confirm no unmanaged files remain in the prefix expected by the formula.
• Verify the downloaded bytes’ SHA-256 against the upstream release manifest and provenance.
• Exercise one simulated version bump in a branch to prove update automation changes the immutable URL/checksum and that CI rejects a stale checksum.

Acceptance criteria

• The formula consumes only the already-published audited release using an immutable checksummed source.
• Tap CI builds/installs/tests/uninstalls on supported Homebrew platforms with least privilege.
• The formula test validates real tool behavior, not only version output.
• User documentation and the update/ownership process are complete.
• A stale or tampered source checksum causes a hard failure.

Dependencies

Blocked by #73, because the formula must point to the live audited v0.2.0 release. Coordinates with #71 for tap ownership/recovery.

Non-goal

Do not submit to Homebrew/core in this ticket. Reassess that separately only after the project satisfies Homebrew’s then-current acceptance and notability policies.