Create Homebrew tap/formula for macOS installation (bypasses Gatekeeper)

[julio75012]

Problem

macOS Gatekeeper quarantines downloaded binaries with com.apple.quarantine extended attribute, showing "developer cannot be verified" warnings. Users must run xattr -d com.apple.quarantine manually or go through System Settings.

Solution: Homebrew Formula

Homebrew automatically removes the quarantine attribute during installation via brew install. This provides the best macOS UX and is the standard distribution method for CLI developer tools.

Implementation Plan

Option A: Homebrew Core (Long-term)

Submit to homebrew/core after repository meets notability requirements (30+ forks, 75+ watchers).

Option B: Custom Tap (Immediate - RECOMMENDED)

Create thunderbyte-labs/homebrew-tap repository and host formula there.

Formula structure (thin-wrap.rb):

class ThinWrap < Formula
desc "Thin cross-platform terminal-based chat application for LLM APIs"
homepage "https://github.com/thunderbyte-labs/thin-wrap"
version "0.1"

if Hardware::CPU.intel?
url "https://github.com/thunderbyte-labs/thin-wrap/releases/download/v0.1/thin-wrap-Darwin-x86_64.zip"
sha256 "PLACEHOLDER_SHA256_INTEL"
else
url "https://github.com/thunderbyte-labs/thin-wrap/releases/download/v0.1/thin-wrap-Darwin-arm64.zip"
sha256 "PLACEHOLDER_SHA256_ARM64"
end

def install
bin.install "thin-wrap"
prefix.install "config.json" if File.exist?("config.json")
end

def caveats
<<~EOS
Configuration files are stored in ~/.config/thin-wrap/ (XDG standard)
To get started: thin-wrap --help
EOS
end

test do
system "#{bin}/thin-wrap", "--version"
end
end

Repository Structure for Tap

thunderbyte-labs/homebrew-tap/
├── README.md
├── Formula/
│ └── thin-wrap.rb
└── .github/workflows/ (optional auto-update)

Acceptance Criteria

• Create thunderbyte-labs/homebrew-tap repository
• Add thin-wrap.rb formula with Intel & ARM64 support
• Add GitHub Action to auto-update formula SHA256 on new releases (optional)
• Update main repo README with: brew install thunderbyte-labs/tap/thin-wrap
• Update macOS installation docs to list Homebrew as primary method, manual install as fallback

Benefits

1. No Gatekeeper warnings - Homebrew handles quarantine removal
2. Automatic updates - brew upgrade thin-wrap
3. Standard UX - macOS developers expect brew install
4. PATH handled automatically - Homebrew links to /opt/homebrew/bin or /usr/local/bin

References

• Homebrew Tap Documentation: https://docs.brew.sh/Taps
• How to Create and Maintain a Tap: https://docs.brew.sh/How-to-Create-and-Maintain-a-Tap
• Formula Cookbook: https://docs.brew.sh/Formula-Cookbook

Priority: Medium-High
Effort: ~2 hours initial setup, 5 minutes per release thereafter

Labels: enhancement, macOS, packaging, good-first-issue