feat: add Homebrew formula and macOS binary releases

[sonupreetam]

Summary

Add a source-build Homebrew Formula and macOS binary releases for complyctl.

Changes:

• Add darwin/amd64 and darwin/arm64 to the GoReleaser build matrix
• Add a "Publish Homebrew formula" step to the release workflow that
  generates a source-build Formula and pushes it to complytime/homebrew-tap
• Mint a short-lived GitHub App token via actions/create-github-app-token
  for cross-repo push (uses existing APP_ID/PRIVATE_KEY secrets)
• Fix deprecated archives.format → formats (GoReleaser v2)
• Document Homebrew and go install as installation methods
• Include OpenSpec artifacts documenting the architectural decisions

After merge, users install with:

brew install complytime/tap/complyctl

The Formula builds from source on the user's machine (Homebrew auto-installs
Go). This avoids macOS Gatekeeper/signing entirely — no Apple Developer
certificate, no xattr workaround needed.

Related Issues

• Closes Publish complyctl on homebrew #713

Review Hints

• The key design decision (Formula vs Cask) is documented in
  openspec/changes/homebrew-formula-and-go-install/design.md — start there
  for context on why source-build was chosen over pre-built binary distribution.

• The release workflow's "Publish Homebrew formula" step uses a heredoc to
  template the Ruby Formula file. The YAML indentation is handled by the |
  block scalar (18 spaces stripped by YAML, leaving correct Ruby formatting).

Test results:

• goreleaser check passes clean (zero deprecation warnings)
• goreleaser release --snapshot --clean produces all 4 archives
  (darwin/amd64, darwin/arm64, linux/amd64, linux/arm64)
• darwin/arm64 binary runs locally (complyctl version reports correct metadata)
• complyctl completion {bash,zsh,fish} generates completions successfully
• CI passes on this PR
• First release after merge publishes formula to complytime/homebrew-tap

Important

Admin pre-merge checklist:

• Verify the GitHub App (APP_ID/PRIVATE_KEY) has Contents: write
  permission on the homebrew-tap repository
• If the App installation is scoped to specific repos (not all org repos),
  add homebrew-tap to the list

[sonupreetam]

The lint issues are not from this PR. https://github.com/complytime/complyctl/actions/runs/29576984198/job/87873581142?pr=742
PR #750 fixes the error.

[trevor-vaughan]

Hi @sonupreetam. I'm happy to do an LLM-driven review of this if you like and review the results but I have almost no experience in the Homebrew/Mac ecosystem so I'm not sure I'm the best reviewer for this. Let me know if you'd like me to proceed anyway and happy to do so!

[sonupreetam]

No worries @trevor-vaughan, added @marcusburghardt & @jpower432 as the primary reviewers.

[hbraswelrh]

Corroborates @yvonnedevlinrh's findings on unvalidated ${{ inputs.tag }} (HIGH) and missing CHANGELOG entries (HIGH). Adding one new finding on token handling.

This review was generated by /review-pr (AI-assisted).

[sonupreetam]

@hbraswelrh & @yvonnedevlinrh Thank you for your feedbacks, I have addressed them.
@marcusburghardt For awareness, I would need maintainers with admin privileges to check the admin pre-merge checklist for this PR apart from the reviews. Until then the PR shouldn't be merged.

[yvonnedevlinrh]

Verdict: APPROVE (with findings below)

Summary

Well-structured PR that adds macOS binary releases to GoReleaser, automated Homebrew Formula publishing via a GitHub App token, go install documentation, and a Homebrew smoke test. The OpenSpec artifacts are thorough and the design decisions (source-build Formula, custom workflow step, GitHub App token) are well-reasoned. CI is fully green (30 checks pass).

---

Findings

MEDIUM — make test-homebrew broken on macOS (missing timeout)

File: Makefile:83

The test-homebrew target uses GNU timeout which is not available on stock macOS (BSD toolchain). macOS is the primary target audience for this test — the target description even says "requires brew, macOS/Linux". Running make test-homebrew on a Mac produces:

make: timeout: No such file or directory
make: *** [test-homebrew] Error 1

Recommendation: Either detect gtimeout on macOS, use a portable timeout mechanism, or drop the wrapper entirely since the test script has its own cleanup trap:

# Option A: portable detection
TIMEOUT := $(shell command -v timeout 2>/dev/null || command -v gtimeout 2>/dev/null || echo "")
test-homebrew:
	@command -v brew >/dev/null 2>&1 || { echo "ERROR: brew not found."; exit 1; }
	$(if $(TIMEOUT),$(TIMEOUT) 300) ./tests/homebrew_test.sh

MEDIUM — Spec deviation: gitTreeState ldflag contradicts spec and design

Files: .github/workflows/release.yml:131, openspec/.../design.md:76-78, openspec/.../tasks.md:12

The design doc states: "It does NOT inject commit or gitTreeState because source tarballs have no .git directory." Task 2.3 says: "Verify Formula uses std_go_args(ldflags:) with version and buildDate only (no commit/gitTreeState)". Yet the actual Formula injects:

-X github.com/complytime/complyctl/internal/version.gitTreeState=clean

In internal/version/version.go:44-47, when gitTreeState != "", version output becomes 1.2.3+clean. This is misleading for source tarball builds where there is no git context to verify tree cleanliness.

Recommendation: Either remove the gitTreeState ldflag (aligning with spec), or update the spec/design documents to document why hardcoding "clean" is appropriate for source builds.

LOW — Unchecked task 4.3 in tasks.md

File: openspec/.../tasks.md:26

Task 4.3 "Confirm GitHub App has Contents:write on homebrew-tap (admin check)" is unchecked. Expected (admin-level prerequisite), but should be confirmed before the first release exercising this workflow.

[sonupreetam]

@yvonnedevlinrh Thank you, addressed your new feedbacks.

• Task 4.3 is an admin verification that can't be confirmed through code, it requires someone with org access to check the GitHub App's installation scope. It's intentionally left unchecked.

It's already called out in two places:
The PR description has an Admin pre-merge checklist with this item
docs/RELEASE_PROCESS.md lists it as a prerequisite under the Homebrew section we added.

[yvonnedevlinrh]

LGTM

[sonupreetam]

@hbraswelrh I would need a re-review on this PR.

[hbraswelrh]

@hbraswelrh I would need a re-review on this PR.

Will do. Thanks, Sonu!

[hbraswelrh]

PR Review: #742 — feat: add Homebrew formula and macOS binary releases

Well-structured PR. Design decisions documented in OpenSpec ADR. All CI passes.
No runtime code changes — CI/CD, docs, and testing only.

Findings: 1 HIGH (auth header leak risk), 1 MEDIUM (template fragility — informational).
Verdict: COMMENT — no blocking issues, but the HIGH finding merits evaluation before merge.

This review was generated by /review-pr (AI-assisted).

[sonupreetam]

Hi @gxmiranda, would you take a look at the pre-merge checklist before this merges?