chore(release): prep v1.0.1 homebrew tap flow

smorin · smorin · commit dd4dc167e1cf · 2026-02-16T13:27:28.000-08:00
diff --git a/.github/workflows/homebrew-tap-pr.yml b/.github/workflows/homebrew-tap-pr.yml
@@ -0,0 +1,101 @@
+name: Homebrew Tap PR
+
+on:
+  release:
+    types:
+      - published
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing release tag to sync to tap (e.g. v1.0.0)"
+        required: true
+        type: string
+
+concurrency:
+  group: homebrew-tap-${{ github.workflow }}-${{ github.event_name }}-${{ github.event.release.tag_name || inputs.tag || github.run_id }}
+  cancel-in-progress: false
+
+jobs:
+  update-tap:
+    name: Update homebrew tap formula
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    env:
+      ENVGEN_HINTS: "0"
+      HOMEBREW_TAP_REPO: smorinlabs/homebrew-tap
+      TAP_REPO_DIR: ${{ github.workspace }}/homebrew-tap
+      HOMEBREW_SOURCE_JSON: ${{ github.workspace }}/.homebrew/source.json
+    steps:
+      - name: Resolve tag
+        id: tag
+        shell: bash
+        run: |
+          if [[ "${{ github.event_name }}" == "release" ]]; then
+            TAG="${{ github.event.release.tag_name }}"
+          else
+            TAG="${{ inputs.tag }}"
+          fi
+
+          if [[ -z "$TAG" ]]; then
+            echo "ERROR: missing release tag"
+            exit 1
+          fi
+
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout envgen
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
+          ref: ${{ steps.tag.outputs.tag }}
+
+      - name: Validate tag matches Cargo.toml version
+        id: version
+        shell: bash
+        run: |
+          VERSION="$(python3 scripts/release/validate_tag.py --tag "${{ steps.tag.outputs.tag }}")"
+          echo "Validated tag ${{ steps.tag.outputs.tag }} for Cargo.toml version $VERSION"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Resolve source tarball metadata
+        run: |
+          make homebrew-source \
+            TAG="${{ steps.tag.outputs.tag }}" \
+            HOMEBREW_SOURCE_JSON="$HOMEBREW_SOURCE_JSON"
+
+      - name: Checkout tap repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          repository: smorinlabs/homebrew-tap
+          token: ${{ secrets.HOMEBREW_TAP_GITHUB_TOKEN }}
+          path: homebrew-tap
+          fetch-depth: 0
+
+      - name: Configure git author
+        working-directory: ${{ env.TAP_REPO_DIR }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Sync formula
+        run: |
+          make homebrew-sync-formula \
+            TAG="${{ steps.tag.outputs.tag }}" \
+            TAP_REPO_DIR="$TAP_REPO_DIR" \
+            HOMEBREW_SOURCE_JSON="$HOMEBREW_SOURCE_JSON"
+
+      - name: Verify formula
+        run: |
+          make homebrew-verify-formula \
+            TAG="${{ steps.tag.outputs.tag }}" \
+            TAP_REPO_DIR="$TAP_REPO_DIR"
+
+      - name: Open or update tap PR
+        env:
+          GH_TOKEN: ${{ secrets.HOMEBREW_TAP_GITHUB_TOKEN }}
+        run: |
+          make homebrew-open-tap-pr \
+            TAG="${{ steps.tag.outputs.tag }}" \
+            TAP_REPO_DIR="$TAP_REPO_DIR" \
+            HOMEBREW_TAP_REPO="$HOMEBREW_TAP_REPO"
diff --git a/.gitignore b/.gitignore
@@ -6,6 +6,7 @@ __pycache__/
 .uv-cache
 .uv-tools
 .bin
+.homebrew
 .DS_Store
 .env.local
 .env.dev
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -19,6 +19,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+## [1.0.1] - 2026-02-16
+
+### Added
+
+### Changed
+
+- Added a separate `homebrew-tap` release flow: `make homebrew-*` targets, `scripts/homebrew/tap_release.py`, and an automated tap PR workflow.
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
 ## [1.0.0] - 2026-02-16
 
 ### Added
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "envgen"
-version = "1.0.0"
+version = "1.0.1"
 edition = "2021"
 description = "Generate and validate .env files from one spec - self-documenting config, consistent across environments, secrets stay out of git."
 readme = "README.md"
diff --git a/Makefile b/Makefile
@@ -20,6 +20,13 @@ YAML_FIXTURES := $(shell find tests/fixtures -type f \( -name '*.yaml' -o -name
 SCHEMA_ARTIFACT_VERSION := $(shell tr -d '\r\n' < SCHEMA_VERSION)
 SCHEMA_FILE := schemas/envgen.schema.v$(SCHEMA_ARTIFACT_VERSION).json
 VERSION_BUMP_SCRIPT := scripts/version_bump.py
+HOMEBREW_TAP_SCRIPT := scripts/homebrew/tap_release.py
+HOMEBREW_SOURCE_REPO ?= smorinlabs/envgen
+HOMEBREW_TAP_REPO ?= smorinlabs/homebrew-tap
+HOMEBREW_TAP_REPO_DIR ?= /Users/stevemorin/c/homebrew-tap
+HOMEBREW_TAP_FORMULA ?= Formula/envgen.rb
+HOMEBREW_SOURCE_JSON ?= $(CURDIR)/.homebrew/source-$(TAG).json
+TAP_REPO_DIR ?= $(HOMEBREW_TAP_REPO_DIR)
 
 # ─── Build & Test ────────────────────────────────────────────────
 
@@ -351,6 +358,97 @@ tag-schema: ## Create local schema tag schema-vA.B.C (SCHEMA_VERSION can overrid
 push-tag-schema: ## Push schema tag schema-vA.B.C to origin (SCHEMA_VERSION can override file-derived value)
 	SCHEMA_VERSION="$(SCHEMA_VERSION)" python3 $(VERSION_BUMP_SCRIPT) push-tag-schema $(if $(DRY_RUN),--dry-run,)
 
+# ─── Homebrew Tap Release ───────────────────────────────────────
+
+.PHONY: homebrew-status
+homebrew-status: ## Show Homebrew release/tap status for TAG=vX.Y.Z
+	@if [ -z "$(TAG)" ]; then \
+		echo "ERROR: TAG is required (example: make homebrew-status TAG=v1.0.0)"; \
+		exit 1; \
+	fi
+	python3 $(HOMEBREW_TAP_SCRIPT) status \
+		--tag "$(TAG)" \
+		--source-repo "$(HOMEBREW_SOURCE_REPO)" \
+		--source-json "$(HOMEBREW_SOURCE_JSON)" \
+		--tap-repo "$(HOMEBREW_TAP_REPO)" \
+		--tap-repo-dir "$(HOMEBREW_TAP_REPO_DIR)" \
+		--formula-path "$(HOMEBREW_TAP_FORMULA)"
+
+.PHONY: homebrew-source
+homebrew-source: ## Download and hash source tarball for TAG=vX.Y.Z
+	@if [ -z "$(TAG)" ]; then \
+		echo "ERROR: TAG is required (example: make homebrew-source TAG=v1.0.0)"; \
+		exit 1; \
+	fi
+	python3 $(HOMEBREW_TAP_SCRIPT) resolve-source \
+		--tag "$(TAG)" \
+		--source-repo "$(HOMEBREW_SOURCE_REPO)" \
+		--out-json "$(HOMEBREW_SOURCE_JSON)"
+
+.PHONY: homebrew-sync-formula
+homebrew-sync-formula: ## Sync tap formula from source metadata (TAG=vX.Y.Z TAP_REPO_DIR=/path/to/homebrew-tap)
+	@if [ -z "$(TAG)" ]; then \
+		echo "ERROR: TAG is required (example: make homebrew-sync-formula TAG=v1.0.0 TAP_REPO_DIR=/path/to/homebrew-tap)"; \
+		exit 1; \
+	fi
+	@if [ -z "$(TAP_REPO_DIR)" ]; then \
+		echo "ERROR: TAP_REPO_DIR is required"; \
+		exit 1; \
+	fi
+	python3 $(HOMEBREW_TAP_SCRIPT) sync-formula \
+		--tag "$(TAG)" \
+		--formula-path "$(TAP_REPO_DIR)/$(HOMEBREW_TAP_FORMULA)" \
+		--source-json "$(HOMEBREW_SOURCE_JSON)" \
+		$(if $(DRY_RUN),--dry-run,)
+
+.PHONY: homebrew-verify-formula
+homebrew-verify-formula: ## Run brew style/audit/install/test on tap formula (TAG=vX.Y.Z TAP_REPO_DIR=/path/to/homebrew-tap)
+	@if [ -z "$(TAG)" ]; then \
+		echo "ERROR: TAG is required (example: make homebrew-verify-formula TAG=v1.0.0 TAP_REPO_DIR=/path/to/homebrew-tap)"; \
+		exit 1; \
+	fi
+	@if [ -z "$(TAP_REPO_DIR)" ]; then \
+		echo "ERROR: TAP_REPO_DIR is required"; \
+		exit 1; \
+	fi
+	python3 $(HOMEBREW_TAP_SCRIPT) verify-formula \
+		--tag "$(TAG)" \
+		--tap-repo-dir "$(TAP_REPO_DIR)" \
+		--tap-repo "$(HOMEBREW_TAP_REPO)" \
+		--formula-path "$(HOMEBREW_TAP_FORMULA)"
+
+.PHONY: homebrew-open-tap-pr
+homebrew-open-tap-pr: ## Open/update tap PR for TAG=vX.Y.Z (requires GH auth; TAP_REPO_DIR=/path/to/homebrew-tap)
+	@if [ -z "$(TAG)" ]; then \
+		echo "ERROR: TAG is required (example: make homebrew-open-tap-pr TAG=v1.0.0 TAP_REPO_DIR=/path/to/homebrew-tap)"; \
+		exit 1; \
+	fi
+	@if [ -z "$(TAP_REPO_DIR)" ]; then \
+		echo "ERROR: TAP_REPO_DIR is required"; \
+		exit 1; \
+	fi
+	python3 $(HOMEBREW_TAP_SCRIPT) open-pr \
+		--tag "$(TAG)" \
+		--tap-repo "$(HOMEBREW_TAP_REPO)" \
+		--tap-repo-dir "$(TAP_REPO_DIR)" \
+		--formula-path "$(HOMEBREW_TAP_FORMULA)" \
+		$(if $(DRY_RUN),--dry-run,)
+
+.PHONY: homebrew-release-tap
+homebrew-release-tap: ## End-to-end tap release flow (TAG=vX.Y.Z TAP_REPO_DIR=/path/to/homebrew-tap)
+	@if [ -z "$(TAG)" ]; then \
+		echo "ERROR: TAG is required (example: make homebrew-release-tap TAG=v1.0.0 TAP_REPO_DIR=/path/to/homebrew-tap)"; \
+		exit 1; \
+	fi
+	@if [ -z "$(TAP_REPO_DIR)" ]; then \
+		echo "ERROR: TAP_REPO_DIR is required"; \
+		exit 1; \
+	fi
+	$(MAKE) homebrew-source TAG="$(TAG)" HOMEBREW_SOURCE_JSON="$(HOMEBREW_SOURCE_JSON)" HOMEBREW_SOURCE_REPO="$(HOMEBREW_SOURCE_REPO)"
+	$(MAKE) homebrew-sync-formula TAG="$(TAG)" TAP_REPO_DIR="$(TAP_REPO_DIR)" HOMEBREW_SOURCE_JSON="$(HOMEBREW_SOURCE_JSON)" HOMEBREW_TAP_FORMULA="$(HOMEBREW_TAP_FORMULA)" $(if $(DRY_RUN),DRY_RUN=$(DRY_RUN),)
+	$(MAKE) homebrew-verify-formula TAG="$(TAG)" TAP_REPO_DIR="$(TAP_REPO_DIR)" HOMEBREW_TAP_FORMULA="$(HOMEBREW_TAP_FORMULA)"
+	$(MAKE) homebrew-open-tap-pr TAG="$(TAG)" TAP_REPO_DIR="$(TAP_REPO_DIR)" HOMEBREW_TAP_REPO="$(HOMEBREW_TAP_REPO)" HOMEBREW_TAP_FORMULA="$(HOMEBREW_TAP_FORMULA)" $(if $(DRY_RUN),DRY_RUN=$(DRY_RUN),)
+
 # ─── Commit Message ──────────────────────────────────────────────
 
 CLAUDE ?= claude
diff --git a/README.md b/README.md
@@ -77,12 +77,16 @@ Variables to resolve:
 
 ## Install
 
-### Homebrew (homebrew-core)
+### Homebrew (personal tap)
 
 ```bash
+brew tap smorinlabs/tap
 brew install envgen
 ```
 
+This project currently ships through the `smorinlabs/tap` formula stream. `homebrew-core`
+support is a future track and is intentionally non-blocking for releases.
+
 ### Cargo
 
 ```bash
diff --git a/RELEASING.md b/RELEASING.md
@@ -1,6 +1,6 @@
 # Releasing `envgen`
 
-This repo has two independent release streams:
+This repo has three independent release streams:
 
 - Crate release stream:
   - Version source: `Cargo.toml` (`[package].version`)
@@ -13,6 +13,42 @@ This repo has two independent release streams:
   - Changelog: `SCHEMA_CHANGELOG.md`
   - Tags: `schema-vA.B.C`
   - Automation: no publish workflow is triggered by schema tags
+- Homebrew tap sync stream:
+  - Source tag: crate tag `vX.Y.Z` from `smorinlabs/envgen`
+  - Formula host repo: `smorinlabs/homebrew-tap`
+  - Formula path: `Formula/envgen.rb`
+  - Automation: `.github/workflows/homebrew-tap-pr.yml` (opens/updates PR in tap repo)
+
+## Homebrew repo ownership
+
+- `smorinlabs/envgen` owns:
+  - release tag (`vX.Y.Z`) creation
+  - source tarball URL + SHA256 resolution
+  - automation code (`scripts/homebrew/tap_release.py`, `make homebrew-*`)
+  - workflow that opens/updates tap PRs (`.github/workflows/homebrew-tap-pr.yml`)
+- `smorinlabs/homebrew-tap` owns:
+  - formula files (`Formula/*.rb`)
+  - PR review/merge policy for tap updates
+  - optional tap-native CI
+- `Homebrew/homebrew-core` is future/optional:
+  - no required release gate for `envgen`
+  - existing `release.yml` `homebrew-core` job remains non-blocking until formula exists upstream
+
+## GitHub source tarball contract (for Homebrew formulas)
+
+For release tag `vX.Y.Z`, the formula source URL is:
+
+- `https://github.com/smorinlabs/envgen/archive/refs/tags/vX.Y.Z.tar.gz`
+
+Behavior:
+
+- GitHub serves this as a redirect (`302`) to codeload, then `200` when the tag exists.
+- This archive is generated from the git tag; it is not uploaded by release assets.
+- Formula `sha256` must be computed from this tarball content.
+
+Current verified example:
+
+- `v1.0.0` (published `2026-02-16T20:11:01Z`) resolves successfully via the URL above.
 
 ## One-time setup (crates.io trusted publishing)
 
@@ -55,6 +91,12 @@ This mapping must match the publish job in `.github/workflows/release.yml` exact
 - `make push-tag-crate`
 - `make tag-schema`
 - `make push-tag-schema`
+- `make homebrew-status TAG=vX.Y.Z`
+- `make homebrew-source TAG=vX.Y.Z`
+- `make homebrew-sync-formula TAG=vX.Y.Z TAP_REPO_DIR=/path/to/homebrew-tap`
+- `make homebrew-verify-formula TAG=vX.Y.Z TAP_REPO_DIR=/path/to/homebrew-tap`
+- `make homebrew-open-tap-pr TAG=vX.Y.Z TAP_REPO_DIR=/path/to/homebrew-tap`
+- `make homebrew-release-tap TAG=vX.Y.Z TAP_REPO_DIR=/path/to/homebrew-tap`
 
 ## Guided hints
 
@@ -77,6 +119,10 @@ Commands with guided next-step output include:
 - `make check-schema`
 - `make tag-schema`
 - `make push-tag-schema`
+- `make homebrew-source`
+- `make homebrew-sync-formula`
+- `make homebrew-verify-formula`
+- `make homebrew-open-tap-pr`
 
 Example (crate flow):
 
@@ -230,6 +276,23 @@ The release workflow at `.github/workflows/release.yml` runs when:
 
 Pushing `schema-v*.*.*` tags does not trigger crates.io publish.
 
+## Homebrew tap sync flow (example)
+
+1. Ensure a crate release tag exists in `smorinlabs/envgen`:
+   - e.g. `v1.0.0`
+2. Prepare source metadata:
+   - `make homebrew-source TAG=v1.0.0`
+3. Sync formula in tap clone:
+   - `make homebrew-sync-formula TAG=v1.0.0 TAP_REPO_DIR=/Users/stevemorin/c/homebrew-tap`
+4. Verify formula:
+   - `make homebrew-verify-formula TAG=v1.0.0 TAP_REPO_DIR=/Users/stevemorin/c/homebrew-tap`
+5. Open/update tap PR:
+   - `make homebrew-open-tap-pr TAG=v1.0.0 TAP_REPO_DIR=/Users/stevemorin/c/homebrew-tap`
+
+Automation equivalent:
+
+- `.github/workflows/homebrew-tap-pr.yml` runs on `release.published` and can be retried with `workflow_dispatch`.
+
 ## Failure modes
 
 - Missing release section for tagging:
@@ -265,5 +328,6 @@ For migration safety, token-based publish remains available through
 ## Notes
 
 - This setup assumes you use "Squash and merge" and "Default to PR title for squash merge commits" in GitHub settings so your main-branch commits stay Conventional.
+- Tap PR automation requires `HOMEBREW_TAP_GITHUB_TOKEN` secret with write access to `smorinlabs/homebrew-tap`.
 - homebrew-core bump PRs require the `HOMEBREW_GITHUB_API_TOKEN` secret (a GitHub token able to open PRs against `Homebrew/homebrew-core`).
 - The homebrew-core automation will no-op until the `envgen` formula exists in `Homebrew/homebrew-core`.
diff --git a/docs/adr/0013-separate-homebrew-tap-release-flow.md b/docs/adr/0013-separate-homebrew-tap-release-flow.md
diff --git a/scripts/homebrew/tap_release.py b/scripts/homebrew/tap_release.py
