feat(release): add GoReleaser and Homebrew publishing automation (#19)

* feat(release): add GoReleaser and Homebrew publishing automation

This commit adds automated Homebrew publishing using GoReleaser. The workflow maintains the
existing GitHub Release process while automating binary builds and Homebrew formula publishing.

Changes:
- Add .goreleaser.yaml with Homebrew tap configuration and release mode set to 'keep-existing'
  to preserve manually created release notes
- Add .github/workflows/release.yml for automated releases triggered by version tags
- Update Makefile with release-test and release-clean targets
- Update CLAUDE.md with comprehensive release process documentation including PAT setup
- Update planning/use-goreleaser-for-brew-publish.md with implementation details

Workflow:
1. Create GitHub Release first using 'gh release create' with detailed notes
2. GoReleaser automatically adds binaries to the release
3. Homebrew formula is published to erraggy/homebrew-oastools

Prerequisites:
- HOMEBREW_TAP_TOKEN secret configured in repository (required for cross-repo publishing)
- Commit author email in .goreleaser.yaml matches verified GitHub email

* fix(release): add architecture specification to GoReleaser config

Address critical issue found in PR review: GoReleaser builds section was missing goarch
specification, which would cause it to build only for the host architecture.

Changes:
- Add goarch specification with amd64, arm64, and 386 support
- Add ignore rules to exclude unsupported combinations (darwin/386, windows/arm64)

This ensures cross-platform builds for:
- Linux: amd64, arm64, 386
- macOS: amd64, arm64
- Windows: amd64, 386

Resolves critical issue in PR #19

Author: erraggy

.github/workflows/release.yml

@@ -0,0 +1,33 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+  # This is required for GoReleaser to push to the homebrew-oastools tap
+
+jobs:
+  goreleaser:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: '1.24'
+
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@v6
+        with:
+          distribution: goreleaser
+          version: '~> v2'
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}

.goreleaser.yaml

@@ -0,0 +1,76 @@
+# This is an example .goreleaser.yml file with some sensible defaults.
+# Make sure to check the documentation at https://goreleaser.com
+
+# The lines below are called `modelines`. See `:help modeline`
+# Feel free to remove those if you don't want/need to use them.
+# yaml-language-server: $schema=https://goreleaser.com/static/schema.json
+# vim: set ts=2 sw=2 tw=0 fo=cnqoj
+
+version: 2
+
+before:
+  hooks:
+    # You may remove this if you don't use go modules.
+    - go mod tidy
+
+builds:
+  - main: ./cmd/oastools
+    binary: oastools
+    env:
+      - CGO_ENABLED=0
+    goos:
+      - linux
+      - windows
+      - darwin
+    goarch:
+      - amd64
+      - arm64
+      - "386"
+    ignore:
+      - goos: darwin
+        goarch: "386"
+      - goos: windows
+        goarch: arm64
+
+archives:
+  - formats: [tar.gz]
+    # this name template makes the OS and Arch compatible with the results of `uname`.
+    name_template: >-
+      {{ .ProjectName }}_
+      {{- title .Os }}_
+      {{- if eq .Arch "amd64" }}x86_64
+      {{- else if eq .Arch "386" }}i386
+      {{- else }}{{ .Arch }}{{ end }}
+      {{- if .Arm }}v{{ .Arm }}{{ end }}
+    # use zip for windows archives
+    format_overrides:
+      - goos: windows
+        formats: [zip]
+
+brews:
+  - name: oastools
+    repository:
+      owner: erraggy
+      name: homebrew-oastools
+    commit_author:
+      name: Robbie Coleman
+      email: robbie@robnrob.com
+    homepage: "https://github.com/erraggy/oastools"
+    description: "OpenAPI Specification (OAS) tools for validation, parsing, converting, and joining specs."
+    license: "MIT"
+
+changelog:
+  sort: asc
+  filters:
+    exclude:
+      - "^docs:"
+      - "^test:"
+
+release:
+  # Use existing release created by gh release create
+  # This allows you to write detailed release notes first
+  mode: keep-existing
+  # Disable draft mode - use the release as-is
+  draft: false
+  # Don't replace the release notes you created
+  replace_existing_draft: false

CLAUDE.md

@@ -483,7 +483,18 @@ func TestConverterConvert(t *testing.T) { ... }
 
 ### Creating a new release
 
+**Release Infrastructure:**
+
+This repository uses **GoReleaser** with **GitHub Actions** to automate binary builds and Homebrew publishing.
+The recommended workflow is:
+
+1. Create a GitHub Release with detailed notes using `gh release create`
+2. GoReleaser automatically triggers, adds binaries to your release, and publishes to Homebrew
+
+This approach maintains full control over release notes while automating the build and distribution process.
+
 **Prerequisites:**
+
 1. Ensure you are on the `main` branch
 2. Ensure your local `main` is up-to-date with `origin/main`
 3. Verify all tests pass: `make check`
@@ -506,14 +517,88 @@ The version tag follows the format `vMAJOR.MINOR.PATCH` (e.g., `v1.7.0`):
   - Use when: Removing/changing public APIs, incompatible changes
   - Note: Major version bumps require careful planning and are extremely rare
 
-**Release Process:**
+**GitHub Personal Access Token (PAT) Setup:**
+
+**REQUIRED:** The automated release workflow needs a Personal Access Token to push to the Homebrew tap repository.
+
+The default `GITHUB_TOKEN` provided by GitHub Actions only has permissions for the current repository and
+**cannot** push to the separate `homebrew-oastools` repository. You must create a PAT with `repo` scope.
+
+**For Automated Releases (GitHub Actions) - REQUIRED SETUP:**
+
+1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
+2. Click "Generate new token (classic)"
+3. Set a descriptive name (e.g., "GoReleaser - oastools Homebrew Publishing")
+4. Select scopes: **`repo`** (full control of private repositories)
+5. Click "Generate token" and **copy the token immediately** (you won't be able to see it again)
+6. Go to the oastools repository → Settings → Secrets and variables → Actions
+7. Click "New repository secret"
+8. Name: `HOMEBREW_TAP_TOKEN`
+9. Value: Paste the token you copied
+10. Click "Add secret"
+
+The `.github/workflows/release.yml` file is already configured to use `${{ secrets.HOMEBREW_TAP_TOKEN }}`.
+
+**Verify PAT Setup:**
+
+Before creating your first release, verify the PAT secret is configured:
+```bash
+gh secret list --repo erraggy/oastools
+```
+
+You should see `HOMEBREW_TAP_TOKEN` in the list.
+
+**For Local Releases:**
+
+If you prefer to run releases locally (not recommended), you'll need to use the same PAT:
+
+1. Create a PAT as described above (or use the same one)
+2. Export it in your shell:
+   ```bash
+   export GITHUB_TOKEN="ghp_your_token_here"
+   ```
+3. Use the `make release-test` target to test locally before running a real release
+
+**IMPORTANT:** Never commit the PAT to git. Keep it secure in GitHub Secrets or your local environment only.
+
+**Release Make Targets:**
+
+The following make targets are available to help with testing:
+
+```bash
+# Test the GoReleaser configuration locally (no publishing)
+make release-test
+
+# Clean up local release artifacts
+make release-clean
+```
+
+**Pre-Release Checklist:**
+
+Before creating your first release, ensure:
+- [ ] `HOMEBREW_TAP_TOKEN` secret is created and added to repository secrets
+- [ ] Secret verified with: `gh secret list --repo erraggy/oastools`
+- [ ] Local test successful: `make release-test`
+- [ ] Commit author email in `.goreleaser.yaml` matches a verified email in your GitHub account
+- [ ] All changes committed and pushed to `main`
+- [ ] All tests pass: `make check`
+
+**Release Process (Recommended Workflow):**
 
-1. **Determine the version number** based on the changes included (see rules above)
+This workflow creates the GitHub Release first with detailed notes, then GoReleaser adds binaries and publishes to Homebrew.
 
-2. **Create the release using `gh release create`:**
+1. **Determine the version number** based on the changes included (see SemVer rules above)
+
+2. **Test the release configuration locally** (optional but recommended):
    ```bash
-   gh release create v1.7.0 \
-     --title "v1.7.0 - Brief summary within 72 chars" \
+   make release-test
+   ```
+   This runs GoReleaser in snapshot mode to verify everything builds correctly without publishing.
+
+3. **Create the GitHub Release with detailed notes**:
+   ```bash
+   gh release create v1.7.1 \
+     --title "v1.7.1 - Brief summary within 72 chars" \
      --notes "$(cat <<'EOF'
    ## Summary
 
@@ -538,55 +623,70 @@ The version tag follows the format `vMAJOR.MINOR.PATCH` (e.g., `v1.7.0`):
 
    - #17 - PR title
    - #18 - PR title
-   EOF
-   )"
-   ```
-
-3. **Title format**: `vX.Y.Z - Brief summary` (keep within 72 characters total)
-   - Example: `v1.7.0 - Performance improvements and benchmark suite`
-
-4. **Body format**: Well-formatted markdown with:
-   - **Summary**: High-level overview of the release
-   - **What's New**: Bullet points of new features/improvements
-   - **Changes**: Notable changes or fixes
-   - **Technical Details**: Benchmarks, metrics, migration notes (if applicable)
-   - **Related PRs**: Links to merged pull requests
 
-**Example Release Command:**
+   ## Installation
 
-```bash
-gh release create v1.7.0 \
-  --title "v1.7.0 - Performance improvements and benchmark suite" \
-  --notes "$(cat <<'EOF'
-## Summary
-
-This release introduces comprehensive performance benchmarking infrastructure
-and delivers significant JSON marshaling performance improvements.
-
-## What's New
-
-- Comprehensive benchmark suite (60+ benchmarks across all packages)
-- JSON marshaler optimization (25-32% faster, 29-37% fewer allocations)
-- Performance improvement planning documentation
-
-## Performance Improvements
-
-- Info marshaling: 26% faster (2,323ns → 1,707ns)
-- Contact marshaling: 32% faster (2,336ns → 1,599ns)
-- Server marshaling: 25% faster (2,837ns → 2,160ns)
+   ### Homebrew
+   ```bash
+   brew tap erraggy/oastools
+   brew install oastools
+   ```
 
-## Related PRs
+   ### Binary Download
+   Download the appropriate binary for your platform from the assets below.
+   EOF
+   )"
+   ```
 
-- #17 - Phase 1: Benchmark infrastructure and baseline
-- #18 - Phase 2: JSON marshaler optimization
-EOF
-)"
-```
+   **Important:** The `gh release create` command automatically:
+   - Creates the version tag (e.g., `v1.7.1`)
+   - Creates the GitHub Release with your detailed notes
+   - Triggers the GitHub Actions workflow
+
+4. **Monitor the automated build**:
+   The GitHub Actions workflow will automatically:
+   - Build binaries for all platforms (Linux, macOS, Windows)
+   - Add binary archives to your GitHub Release
+   - Publish the Homebrew formula to `homebrew-oastools`
+
+   Monitor progress at:
+   - Workflow: https://github.com/erraggy/oastools/actions
+   - Release: https://github.com/erraggy/oastools/releases
+   - Homebrew tap: https://github.com/erraggy/homebrew-oastools
+
+5. **Verify the release**:
+   - Check that binaries were added to the GitHub Release
+   - Verify Homebrew formula was updated in `homebrew-oastools`
+   - Test Homebrew installation (optional):
+     ```bash
+     brew tap erraggy/oastools
+     brew install oastools
+     oastools --version
+     ```
 
 **After Release:**
+
 - Verify the release appears correctly on GitHub
-- The tag is automatically created by `gh release create`
-- GitHub Actions will run (if configured) to build/publish artifacts
+- Test Homebrew installation: `brew tap erraggy/oastools && brew install oastools`
+- Announce the release (if applicable)
+- Update project documentation if needed
+
+**Troubleshooting:**
+
+**Issue: GoReleaser can't push to homebrew-oastools**
+- Verify the `homebrew-oastools` repository exists and is public
+- Check that the GitHub token has `repo` scope
+- Ensure the commit author email in `.goreleaser.yaml` matches a verified email in your GitHub account
+
+**Issue: Build fails for certain platforms**
+- Review the GitHub Actions logs for specific error messages
+- Check if any dependencies require CGO (we've set `CGO_ENABLED=0`)
+- Test locally with `make release-test` to reproduce the issue
+
+**Issue: Homebrew formula doesn't work**
+- Verify the formula in `homebrew-oastools` repository
+- Test installation in a clean environment
+- Check binary architecture matches the user's system
 
 ## Go Module
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build test lint clean install tidy check help bench bench-parser bench-validator bench-converter bench-joiner bench-save bench-compare bench-baseline bench-clean
+.PHONY: build test lint clean install tidy check help bench bench-parser bench-validator bench-converter bench-joiner bench-save bench-compare bench-baseline bench-clean release-test release-clean
 
 # Build variables
 BINARY_NAME=oastools
@@ -55,6 +55,7 @@ vet:
 clean:
 	@echo "Cleaning..."
 	@rm -rf $(BUILD_DIR)
+	@rm -rf dist/
 	@rm -f coverage.txt coverage.html
 	@rm -f benchmark-*.txt
 
@@ -179,6 +180,28 @@ bench-clean:
 	@rm -f mem-profile-*.prof
 	@echo "Benchmark outputs cleaned (baseline preserved)"
 
+## release-test: Test GoReleaser configuration locally (creates dist/ without publishing)
+release-test:
+	@echo "Testing GoReleaser configuration (snapshot mode)..."
+	@if ! command -v goreleaser >/dev/null 2>&1; then \
+		echo "Error: goreleaser not installed. Install it with:"; \
+		echo "  brew install goreleaser"; \
+		exit 1; \
+	fi
+	@goreleaser release --snapshot --clean
+	@echo ""
+	@echo "Test successful! Check dist/ directory for generated artifacts."
+	@echo "To clean up: make release-clean"
+	@echo ""
+	@echo "To create a real release, use:"
+	@echo "  gh release create vX.Y.Z --title \"vX.Y.Z - Description\" --notes \"...\""
+
+## release-clean: Clean GoReleaser artifacts from local testing
+release-clean:
+	@echo "Cleaning release artifacts..."
+	@rm -rf dist/
+	@echo "Release artifacts cleaned"
+
 ## help: Show this help message
 help:
 	@echo "Usage: make [target]"