Add Homebrew formula update script and release docs

Author: henrygarner

docs/releasing.md

@@ -0,0 +1,54 @@
+# Releasing
+
+Pushing a `v*` tag triggers the release workflow, which builds and publishes all artifacts: Rust binaries, VSIX, npm tarballs, LSP and tree-sitter outputs. Everything ships from a single tag.
+
+Not every artifact needs manual follow-up. The Homebrew formula is the only piece that requires a separate update after CI finishes.
+
+## What goes where
+
+| Artifact | Destination | Needs manual step? |
+|---|---|---|
+| Rust CLI binaries (4 platforms) | GitHub release | No (CI publishes) |
+| VSIX | GitHub release | No (CI publishes) |
+| npm tarballs (allium-cli, allium-lsp, tree-sitter) | GitHub release | No (CI publishes) |
+| Homebrew formula | homebrew-allium tap | Yes |
+
+## Steps
+
+1. **Bump versions** with `scripts/version-bump.sh`:
+
+   ```bash
+   ./scripts/version-bump.sh 1.0.0
+   ```
+
+2. **Commit, tag and push:**
+
+   ```bash
+   git add -A && git commit -m "v1.0.0"
+   git tag v1.0.0
+   git push origin main --tags
+   ```
+
+3. **Wait for CI** to build and attach release artifacts.
+
+4. **Update the Homebrew tap:**
+
+   ```bash
+   ./scripts/update-homebrew-formula.sh 1.0.0
+   ```
+
+   This downloads the four platform tarballs, computes SHA256 checksums and rewrites the formula. Pass `--dry-run` to preview without modifying the file.
+
+5. **Push the tap repo:**
+
+   ```bash
+   cd ~/Code/homebrew-allium
+   git add -A && git commit -m "allium 1.0.0"
+   git push
+   ```
+
+## When to release
+
+All core-tier packages share a major.minor version (see `VERSIONING.md`). Right now, every release cuts a single tag and publishes everything. This means a tree-sitter bugfix produces new Rust binaries even if nothing changed in the Rust crates, and vice versa.
+
+This is fine while the project is small. If the coupling becomes a problem, the natural split is separate tags per artifact group (e.g. `cli-v1.0.1`, `vscode-v0.3.0`), each triggering only its own CI job. That would also let the Homebrew update script run automatically as a post-release workflow step rather than requiring a manual invocation.

scripts/update-homebrew-formula.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Update the Homebrew formula with checksums from a GitHub release.
+#
+# Usage:
+#   ./scripts/update-homebrew-formula.sh [--dry-run] <version> [tap-path]
+#
+# Examples:
+#   ./scripts/update-homebrew-formula.sh 1.0.0
+#   ./scripts/update-homebrew-formula.sh --dry-run 0.1.4
+#   ./scripts/update-homebrew-formula.sh 1.0.0 ~/Code/homebrew-allium
+
+REPO="juxt/allium-tools"
+TARGETS=(
+  aarch64-apple-darwin
+  x86_64-apple-darwin
+  aarch64-unknown-linux-gnu
+  x86_64-unknown-linux-gnu
+)
+
+DRY_RUN=false
+VERSION=""
+TAP_PATH=""
+
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=true ;;
+    -*) echo "Unknown flag: $arg" >&2; exit 1 ;;
+    *)
+      if [[ -z "$VERSION" ]]; then
+        VERSION="$arg"
+      else
+        TAP_PATH="$arg"
+      fi
+      ;;
+  esac
+done
+
+if [[ -z "$VERSION" ]]; then
+  echo "Usage: update-homebrew-formula.sh [--dry-run] <version> [tap-path]" >&2
+  exit 1
+fi
+
+if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+  echo "Error: version must be in semver format (e.g. 1.0.0)" >&2
+  exit 1
+fi
+
+# Default tap path: sibling directory to this repo
+if [[ -z "$TAP_PATH" ]]; then
+  TAP_PATH="$(cd "$(dirname "$0")/../.." && pwd)/homebrew-allium"
+fi
+
+FORMULA="$TAP_PATH/Formula/allium.rb"
+
+if [[ ! -f "$FORMULA" ]]; then
+  echo "Error: formula not found at $FORMULA" >&2
+  exit 1
+fi
+
+echo "Fetching checksums for v$VERSION..."
+
+declare -A CHECKSUMS
+for target in "${TARGETS[@]}"; do
+  url="https://github.com/$REPO/releases/download/v$VERSION/allium-$target.tar.gz"
+  echo "  $target"
+  sha=$(curl -fsSL "$url" | shasum -a 256 | awk '{print $1}')
+  CHECKSUMS[$target]="$sha"
+done
+
+echo ""
+echo "Checksums:"
+for target in "${TARGETS[@]}"; do
+  echo "  $target: ${CHECKSUMS[$target]}"
+done
+echo ""
+
+if $DRY_RUN; then
+  echo "(dry run — formula not modified)"
+  exit 0
+fi
+
+# Update version
+sed -i '' "s/^  version \".*\"/  version \"$VERSION\"/" "$FORMULA"
+
+# Update checksums using the placeholder/previous values
+for target in "${TARGETS[@]}"; do
+  # Convert target to the placeholder name: hyphens to underscores, uppercase
+  placeholder=$(echo "$target" | tr '-' '_' | tr '[:lower:]' '[:upper:]')
+  sha="${CHECKSUMS[$target]}"
+  # Replace either a placeholder or a previous 64-char hex hash on the line following the matching URL
+  sed -i '' "/allium-${target}\.tar\.gz/{ n; s/sha256 \"[^\"]*\"/sha256 \"${sha}\"/; }" "$FORMULA"
+done
+
+echo "Updated $FORMULA to v$VERSION"