chore: promote homebrew-core as primary macOS install path (#299)

* chore(release): stop publishing stable hookdeck formula to third-party tap

The stable `hookdeck` formula now lives in homebrew-core (merged 2026-06-04)
and is auto-bumped by Homebrew's BrewTestBot. The third-party
`hookdeck/homebrew-hookdeck` tap continues to host only `hookdeck-beta`
(homebrew-core does not accept pre-releases).

The brews block now uses a fixed `hookdeck-beta` name with `skip_upload`
gated to pre-release tags, so stable releases will no longer overwrite the
tap's `hookdeck.rb`. A follow-up PR on the tap repo removes the stale
stable formula files and adds `tap_migrations.json` to redirect existing
tap users to homebrew-core.

Refs #297

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(readme): promote homebrew-core as the primary macOS install path

`hookdeck` is now in homebrew-core, so the default macOS install is
`brew install hookdeck` (no tap, no trust step). The third-party tap is
demoted to "for beta releases only" with a note about the upcoming
`HOMEBREW_REQUIRE_TAP_TRUST` default flip.

Replaces the stale Troubleshooting entry (cask-migration leftover from
an abandoned cask plan) with three relevant entries: tap → homebrew-core
migration, hookdeck/hookdeck-beta link conflicts, and beta tap-trust.

Refs #297

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ci(test-homebrew-build): validate hookdeck-beta.rb instead of hookdeck.rb

The GoReleaser brews block now produces `hookdeck-beta.rb` only (the stable
`hookdeck` formula lives in homebrew-core). The test-homebrew-build CI was
still validating `dist/homebrew/Formula/hookdeck.rb`, which no longer exists.

Updates:
- `test-scripts/test-homebrew-build.sh`: validate_formula now reads
  `hookdeck-beta.rb`; the install-test path (gated by `--install` flag,
  workflow_dispatch only) targets the `hookdeck-beta` formula name.
- `.github/workflows/test-homebrew-build.yml`: upload artifact path
  updated to `hookdeck-beta.rb`.

Verified locally: `./test-scripts/test-homebrew-build.sh` exits 0.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ci(test-homebrew-build): drop stale "deprecation warnings" reporting

The validation script's header and success summary still claimed to verify
that the formula contains deprecation warnings — a leftover from when the
tap's `hookdeck.rb` carried a "being deprecated in favor of cask" notice.
That notice was removed from the tap formula a while back, and there has
been no actual `grep` check for deprecation warnings in this script. Drops
the two stale lines.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: leggetter

.github/workflows/test-homebrew-build.yml

@@ -53,5 +53,5 @@ jobs:
         with:
           name: homebrew-files
           path: |
-            dist/homebrew/Formula/hookdeck.rb
+            dist/homebrew/Formula/hookdeck-beta.rb
           retention-days: 7

.goreleaser/mac.yml

@@ -47,7 +47,12 @@ archives:
       - README*
       - CHANGELOG*
 brews:
-  - name: "{{ if .Prerelease }}hookdeck-beta{{ else }}hookdeck{{ end }}"
+  # Stable releases are published to homebrew-core via Homebrew's autobump
+  # (BrewTestBot opens version-bump PRs after each tagged release). The
+  # third-party tap publishes only the beta channel — homebrew-core does
+  # not accept pre-releases, so the `hookdeck-beta` formula lives here.
+  - name: hookdeck-beta
+    skip_upload: "{{ if not .Prerelease }}true{{ end }}"
     ids:
       - hookdeck
     repository:
@@ -56,21 +61,20 @@ brews:
     directory: Formula
     homepage: https://hookdeck.com
     description: Receive events (e.g. webhooks) on your localhost with event history, replay, and team collaboration
-    
+
     install: |
       bin.install "hookdeck"
-      
+
       # Install completions from pre-generated files
       bash_completion.install "completions/hookdeck.bash" => "hookdeck"
       zsh_completion.install "completions/_hookdeck"
-    
+
     caveats: |
-      ❤ Thanks for installing the Hookdeck CLI!
-      {{ if .Prerelease }}
+      ❤ Thanks for installing the Hookdeck CLI beta!
+
       ⚠️  You are using a BETA version. Report issues at:
         https://github.com/hookdeck/hookdeck-cli/issues
-      {{ end }}
-      
+
       If this is your first time using the CLI, run:
         hookdeck login
 

README.md

@@ -75,18 +75,27 @@ npm install hookdeck-cli@beta -g
 
 ### macOS
 
-Hookdeck CLI is available on macOS via [Homebrew](https://brew.sh/):
+Hookdeck CLI is available on macOS via [Homebrew](https://brew.sh/) in [homebrew-core](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/h/hookdeck.rb):
 
 ```sh
-brew install hookdeck/hookdeck/hookdeck
+brew install hookdeck
 ```
 
-To install a beta (pre-release) version:
+New stable versions are picked up automatically by Homebrew's autobump after each release — `brew upgrade` will pull them in.
+
+To install a beta (pre-release) version from our tap:
 
 ```sh
 brew install hookdeck/hookdeck/hookdeck-beta
 ```
 
+> [!NOTE]
+> When [`HOMEBREW_REQUIRE_TAP_TRUST`](https://docs.brew.sh/Taps) becomes the default in Homebrew 5.2.0 / 6.0.0, installing the beta formula from a third-party tap will require an explicit trust step:
+> ```sh
+> brew trust --formula hookdeck/hookdeck/hookdeck-beta
+> ```
+> The stable `hookdeck` formula lives in homebrew-core and is not affected.
+
 ### Windows
 
 Hookdeck CLI is available on Windows via the [Scoop](https://scoop.sh/) package manager:
@@ -1218,22 +1227,41 @@ There are also some hidden flags that are mainly used for development and debugg
 
 ## Troubleshooting
 
-### Homebrew: Binary Already Exists Error
+### Homebrew: migrating from the third-party tap to homebrew-core
+
+The stable `hookdeck` formula now lives in [homebrew-core](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/h/hookdeck.rb). The third-party `hookdeck/hookdeck` tap publishes only the beta formula.
 
-If you previously installed Hookdeck via the Homebrew formula and are upgrading to the cask version, you may see:
+If you installed via the tap, the move is automatic: `brew update && brew upgrade` will pull the next stable version from homebrew-core. No action needed.
 
+If you want to switch immediately:
+
+```sh
+brew update
+brew upgrade hookdeck
 ```
-Warning: It seems there is already a Binary at '/opt/homebrew/bin/hookdeck'
-from formula hookdeck; skipping link.
+
+### Homebrew: `hookdeck` and `hookdeck-beta` conflict on link
+
+Both formulae install a binary called `hookdeck`, so only one can be linked at a time. Switching between them requires `--overwrite`:
+
+```sh
+# Switch from beta to stable
+brew link --overwrite hookdeck
+
+# Switch from stable to beta
+brew link --overwrite hookdeck-beta
 ```
 
-To resolve this, uninstall the old formula version first, then install the cask:
+### Homebrew: beta install asks for a `brew trust` step
+
+Once [`HOMEBREW_REQUIRE_TAP_TRUST`](https://docs.brew.sh/Taps) becomes the default in Homebrew 5.2.0 / 6.0.0, installing the beta from the third-party tap requires:
 
 ```sh
-brew uninstall hookdeck
-brew install --cask hookdeck/hookdeck/hookdeck
+brew trust --formula hookdeck/hookdeck/hookdeck-beta
 ```
 
+The stable formula lives in homebrew-core and is unaffected.
+
 
 ## Developing
 
@@ -1433,7 +1461,7 @@ The GitHub Actions workflow will automatically:
 - Create a stable GitHub release
 - Publish to NPM with the `latest` tag
 - Update package managers:
-  - Homebrew: `hookdeck` formula
+  - Homebrew: stable formula in [homebrew-core](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/h/hookdeck.rb) is auto-bumped by Homebrew's BrewTestBot (no action from us; runs every ~3 hours after the tag is published). The `hookdeck-beta` formula in our third-party tap is updated only on pre-release tags.
   - Scoop: `hookdeck` package
   - Docker: Updates both the version tag and `latest`
 

test-scripts/test-homebrew-build.sh

@@ -8,7 +8,6 @@
 # It validates that:
 #   - GoReleaser snapshot build completes successfully
 #   - Homebrew formula file is generated
-#   - Formula contains deprecation warning
 #   - Formula references completion files correctly
 #   - Completion files are bundled in the tarball
 # NOTE: Cask validation is currently commented out - focusing on formula only
@@ -170,9 +169,11 @@ run_goreleaser_build() {
 
 # Validate Homebrew formula file
 validate_formula() {
-    echo_section "Validating Formula (dist/homebrew/Formula/hookdeck.rb)"
-    
-    local formula_file="dist/homebrew/Formula/hookdeck.rb"
+    echo_section "Validating Formula (dist/homebrew/Formula/hookdeck-beta.rb)"
+
+    # Stable releases of `hookdeck` now go to homebrew-core; the third-party
+    # tap publishes only `hookdeck-beta` on pre-release tags.
+    local formula_file="dist/homebrew/Formula/hookdeck-beta.rb"
 
     if [ ! -f "$formula_file" ]; then
         echo_error "Formula file not found at $formula_file"
@@ -298,7 +299,7 @@ setup_local_tap() {
 
     # Patch formula to use local file:// URLs for testing
     echo_info "Patching formula to use local file URLs for testing..."
-    local formula_file="$LOCAL_TAP_PATH/Formula/hookdeck.rb"
+    local formula_file="$LOCAL_TAP_PATH/Formula/hookdeck-beta.rb"
     local current_dir="$(pwd)"
 
     # Replace GitHub URLs with local file:// URLs
@@ -320,8 +321,8 @@ setup_local_tap() {
 test_formula_installation() {
     echo_section "Testing Formula Installation"
 
-    local tap_name="hookdeck-test/hookdeck-test/hookdeck"
-    
+    local tap_name="hookdeck-test/hookdeck-test/hookdeck-beta"
+
     echo_info "Installing formula: brew install $tap_name"
     if brew install "$tap_name"; then
         echo_success "Formula installed successfully"
@@ -526,7 +527,6 @@ main() {
         echo_info "What was validated:"
         echo "  ✓ GoReleaser configuration generates correct Homebrew formula"
         echo "  ✓ Completion files are bundled in archives"
-        echo "  ✓ Formula has deprecation warnings"
         echo "  ✓ Formula has proper completion directives"
         # echo "  ✓ Cask has proper completion directives"  # Commented out - not testing cask