chore: prep for homebrew-core submission

[leggetter]

Summary

Preparation work to enable submitting hookdeck to homebrew-core, which lets users brew install hookdeck without the brew trust step that becomes mandatory when Homebrew 5.2.0 ships (~4–8 weeks). Tracked in #295; parent context in #294.

Three logical commits:

• chore(release): disable CGO for darwin builds in mac.yml — Removes the vestigial CGO_ENABLED=1 flag from the darwin amd64 GoReleaser build. The codebase has no actual CGO usage (no import "C", no #cgo directives); the flag was cargo-culted from the very first release config in 2021 (4d423da) and never revisited. All other builds (darwin arm64, all linux, all windows, all npm builds since commit fd2338b in Feb 2026) already use CGO_ENABLED=0. Resulting binary is statically linked and consistent across the build matrix. Locally smoke-tested: build succeeds, version-string injection intact.

• docs: regenerate REFERENCE.md for connection pause/unpause command — Drive-by fix for stale auto-generated docs. The gateway connection pause/unpause commands accept an ID or name (added in CLI: connection pause/unpause should accept connection name or ID #276), but REFERENCE.md still documented the older ID-only argument. Regenerated from cobra metadata via go run ./tools/generate-reference.

• feat(completion): output completion script to stdout — Changes hookdeck completion --shell <shell> to write the completion script to stdout instead of writing a file to the current directory and printing multi-step setup instructions. This brings the command in line with every other major Cobra-based CLI (gh, goreleaser, kubectl, helm, terraform) and unblocks the idiomatic generate_completions_from_executable helper in the homebrew-core formula. Also simplifies scripts/completions.sh significantly.

⚠️ Behavior change in hookdeck completion

Before	After
Writes hookdeck-completion.bash / .zsh to cwd	Writes the script to stdout
Prints multi-step OS-specific install instructions	Help text (--help) documents the redirection pattern

Anyone scripting against the old file-writing behavior is affected. The next release notes (drafted by the hookdeck-cli-release skill) should call this out — it should pick up automatically from the conventional commit but worth verifying when cutting.

Canonical new usage:

source <(hookdeck completion --shell bash)
source <(hookdeck completion --shell zsh)

Sequencing — what happens after this merges

1. Cut next stable release (next vX.Y.Z). Automatically rolls in v2.1.2-beta.1's auth-recovery work (already in main via squash-merge bc3e7cb of fix(cli): auth recovery for stale keys and clearer 401 UX #286) plus this branch's changes.
2. Update the drafted homebrew-core formula (currently at /opt/homebrew/Library/Taps/homebrew/homebrew-core/Formula/h/hookdeck.rb locally) with the new release's url + sha256 + version.
3. Fork Homebrew/homebrew-core, push the formula branch, open PR titled hookdeck X.Y.Z (new formula).

The formula already passes brew audit --strict --new --online hookdeck clean.

Test plan

• CI: Homebrew Build and Installation Tests workflow passes (validates GoReleaser config still produces a valid Homebrew formula end-to-end)
• CI: existing test suites pass
• Manual: go build && ./hookdeck completion --shell bash | head shows the bash completion script on stdout (no file written, no instructions printed)
• Manual: source <(./hookdeck completion --shell bash) enables completions in the current bash session
• Manual: source <(./hookdeck completion --shell zsh) enables completions in the current zsh session
• Manual: bash ./scripts/completions.sh produces completions/hookdeck.bash and completions/_hookdeck correctly
• Manual (release-time only): after cutting a release and updating the formula version/SHA256, brew install --build-from-source ./Formula/h/hookdeck.rb in the local homebrew-core checkout succeeds

🤖 Generated with Claude Code

[leggetter]

Manual test results — all pass

Ran against fresh build of HEAD (3d369ce).

Test 1: bash completion to stdout

$ ./hookdeck completion --shell bash | head -5
# bash completion for hookdeck                             -*- shell-script -*-

__hookdeck_debug()
{
    if [[ -n ${BASH_COMP_DEBUG_FILE:-} ]]; then

• ✅ Completion script on stdout
• ✅ No hookdeck-completion.bash file created in cwd
• ✅ Stderr empty (no instruction blob)

Test 2: bash sourcing

$ bash -c 'source <(./hookdeck completion --shell bash) && complete -p hookdeck'
complete -o default -F __start_hookdeck hookdeck

• ✅ Sources without errors
• ✅ __start_hookdeck function registered
• ✅ complete -F __start_hookdeck hookdeck properly wired

Test 3: zsh sourcing

$ zsh -c 'autoload -Uz compinit && compinit -u && source <(./hookdeck completion --shell zsh) && echo OK'
OK

• ✅ Sources cleanly with compinit initialized
• ✅ _hookdeck function registered

Note: bare source <(...) without compinit shows command not found: compdef — this is expected zsh behavior since compdef is part of the completion system that compinit installs. Real users have this in .zshrc.

Test 4: scripts/completions.sh

$ bash ./scripts/completions.sh
Generating bash completion...
Generating zsh completion...
✅ Completions generated successfully in completions/
-rw-r--r--@ 1 leggetter staff 7.6K _hookdeck
-rw-r--r--@ 1 leggetter staff 196K hookdeck.bash

• ✅ Produces completions/hookdeck.bash (GoReleaser-expected name)
• ✅ Produces completions/_hookdeck (GoReleaser-expected name)
• ✅ Both pass syntax validation (bash -n / zsh -n)

CI status

All 12 jobs pass, including the critical test-homebrew-build workflow that exercises the GoReleaser → Homebrew formula pipeline end-to-end. Acceptance, unit, build (mac/linux/windows), npm, and homebrew-build all green.

Outstanding

The brew install --build-from-source test from Phase 2 of #295 remains blocked until we cut a release containing this change — v2.1.1 still has the old completion behavior. That'll be validated after release and before opening the homebrew-core PR.

[github-actions]

Addressed review feedback. New commit(s) pushed; verification passed.