Stop future releases from denying Homebrew and npm.

Why:
The tag-driven release notes still said the release was not a Homebrew
formula or npm package, and the workflow never attached the npm tarball.
The spec-only front-door suite also fetched live GitHub, so agent verify
could fail on rate limits or a stale tap.

Changed:
release.yml packages and attaches simbroker-<version>.tgz and rewrites
the release notes. The live tap compare moves to
scripts/sync_homebrew_tap.sh --check-remote. Front-door tests stay
offline and pin the new release.yml contract.

Verification:
npm run agent:verify -- --profile spec-only --paths .github/workflows/release.yml,docs/test/front-door.test.mjs,scripts/sync_homebrew_tap.sh,spec/build-and-test.md,CHANGELOG.md --session-dir task-sessions/20260819-homebrew-p2-review
node --test docs/test/front-door.test.mjs

Affected:
.github/workflows/release.yml
docs/test/front-door.test.mjs
scripts/sync_homebrew_tap.sh
spec/build-and-test.md
CHANGELOG.md

Refs:
#12
spec/build-and-test.md

Session:
task-sessions/20260819-homebrew-p2-review

Author: VladimirBrejcha

.github/workflows/release.yml

@@ -1,6 +1,6 @@
-# Publish the Alpha CLI tarball when a version tag is pushed.
-# After merge, create the matching tag (example: v0.1.0-alpha.1).
-# This workflow does not build or attach the macOS app.
+# Publish the Alpha CLI tarball and the packable npm CLI when a version
+# tag is pushed. After merge, create the matching tag (example:
+# v0.1.0-alpha.1). This workflow does not build or attach the macOS app.
 name: Release CLI
 
 on:
@@ -13,7 +13,7 @@ permissions:
 
 jobs:
   release:
-    name: attach CLI tarball
+    name: attach CLI and npm packages
     runs-on: ubuntu-latest
     timeout-minutes: 30
     steps:
@@ -38,8 +38,10 @@ jobs:
           npm run test:client
           npm run test:harness-adoption
 
-      - name: Package CLI tarball
-        run: npm run package:cli
+      - name: Package CLI tarball and npm CLI
+        run: |
+          npm run package:cli
+          npm run package:npm
 
       - name: Create GitHub Release
         env:
@@ -48,13 +50,15 @@ jobs:
           version="$(node -p "require('./package.json').version")"
           asset="artifacts/cli/simulator-broker-${version}-cli.tar.gz"
           checksum="${asset}.sha256"
+          npm_asset="artifacts/npm/simbroker-${version}.tgz"
           prerelease_args=()
           if [[ "$version" == *alpha* || "$version" == *beta* || "$version" == *rc* ]]; then
             prerelease_args+=(--prerelease)
           fi
           gh release create "${GITHUB_REF_NAME}" \
             --title "Simulator Broker ${GITHUB_REF_NAME}" \
-            --notes "Alpha CLI tarball. Extract it and run \`./bin/simbroker --help\`. Node.js 20 or newer is required. macOS and Xcode are still required to create and run iOS Simulators. This release is not a Homebrew formula, notarized app, or npm package. See CHANGELOG.md." \
+            --notes "Alpha CLI. Install with \`brew install fiveonecode/simulator-broker/simbroker\` or \`npm install -g\` the attached \`simbroker-${version}.tgz\`. Node.js 20 or newer is required. macOS and Xcode are still required to create and run iOS Simulators. A signed, notarized operator app is not attached. See CHANGELOG.md." \
             "${prerelease_args[@]}" \
             "$asset" \
-            "$checksum"
+            "$checksum" \
+            "$npm_asset"

CHANGELOG.md

@@ -17,7 +17,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   from the signed, notarized GitHub Release zip `Simulator-Broker-<version>.zip`
   when that zip is attached.
 - Packable npm CLI `packages/simbroker` (`npm run package:npm`) with a `bin`
-  field. The repo-root package stays private.
+  field. The repo-root package stays private. Tag-driven
+  `.github/workflows/release.yml` attaches that tarball and no longer
+  claims the release is not a Homebrew formula or npm package.
 
 ## [0.1.0-alpha.1] - 2026-08-18
 

docs/test/front-door.test.mjs

@@ -174,9 +174,16 @@ test("release workflow packages the CLI tarball on version tags", () => {
 
   assert.ok(release.includes("tags:"));
   assert.ok(release.includes("npm run package:cli"));
+  assert.ok(release.includes("npm run package:npm"));
+  assert.ok(release.includes("artifacts/npm/simbroker-${version}.tgz"));
   assert.ok(release.includes("gh release create"));
   assert.ok(release.includes("--prerelease"));
   assert.equal(release.includes("test:app"), false);
+  assert.equal(
+    release.replace(/\s+/g, " ").includes("This release is not a Homebrew formula, notarized app, or npm package."),
+    false,
+    "future release notes must not deny Homebrew and npm",
+  );
 });
 
 test("issue forms cover install failure, bug, and feature and state Alpha limits", () => {
@@ -238,11 +245,12 @@ test("status and contributing point strangers at issue forms, not later-sequence
   assert.ok(readme.includes("issues/new/choose"));
 });
 
-test("Homebrew one-liner is documented against the homebrew-simulator-broker tap", async () => {
+test("Homebrew one-liner is documented against the homebrew-simulator-broker tap", () => {
   const readme = readRepoFile("README.md");
   const gettingStarted = readRepoFile("docs/getting-started.md");
   const structure = readRepoFile("spec/project-structure.md");
   const changelog = readRepoFile("CHANGELOG.md");
+  const syncScript = readRepoFile("scripts/sync_homebrew_tap.sh");
 
   for (const body of [readme, gettingStarted, structure, changelog]) {
     assert.ok(
@@ -255,22 +263,10 @@ test("Homebrew one-liner is documented against the homebrew-simulator-broker tap
     );
   }
 
-  const repoResponse = await fetch("https://api.github.com/repos/fiveonecode/homebrew-simulator-broker", {
-    headers: { "User-Agent": "simulator-broker-front-door-test" },
-  });
-  assert.equal(
-    repoResponse.status,
-    200,
-    "fiveonecode/homebrew-simulator-broker must exist for the brew one-liner",
-  );
-  const formulaResponse = await fetch(
-    "https://raw.githubusercontent.com/fiveonecode/homebrew-simulator-broker/main/Formula/simbroker.rb",
-    { headers: { "User-Agent": "simulator-broker-front-door-test" } },
-  );
-  assert.equal(formulaResponse.status, 200, "tap must publish Formula/simbroker.rb on main");
-  const formula = await formulaResponse.text();
-  assert.ok(formula.includes("class Simbroker"));
-  assert.ok(formula.includes("simulator-broker-0.1.0-alpha.1-cli.tar.gz"));
+  assert.ok(syncScript.includes("--check-remote"));
+  assert.ok(syncScript.includes("cmp -s"));
+  assert.ok(syncScript.includes("--max-time"));
+  assert.ok(syncScript.includes("Formula/simbroker.rb"));
 });
 
 test("sync_homebrew_tap.sh copies Formula and Casks into a tap checkout", () => {

scripts/sync_homebrew_tap.sh

@@ -6,24 +6,34 @@ repo_root="$(cd "$(dirname "$0")/.." && pwd)"
 usage() {
   cat <<'EOF'
 Usage: bash scripts/sync_homebrew_tap.sh --tap-dir <path>
+       bash scripts/sync_homebrew_tap.sh --check-remote
 
 Copy Formula/ and Casks/ from this checkout into a clone of
 fiveonecode/homebrew-simulator-broker. Refuses to delete tap files when
 this tree has no Formula/simbroker.rb.
 
+--check-remote compares this checkout's Formula/simbroker.rb to the
+published tap formula. It is optional and is not part of spec-only.
+
 Options:
   --tap-dir <path>  Existing checkout of fiveonecode/homebrew-simulator-broker
+  --check-remote    Compare local Formula/simbroker.rb to the live tap
   -h, --help        Show this help text.
 EOF
 }
 
 tap_dir=""
+check_remote=0
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --tap-dir)
       tap_dir="$2"
       shift 2
       ;;
+    --check-remote)
+      check_remote=1
+      shift
+      ;;
     -h|--help)
       usage
       exit 0
@@ -36,6 +46,30 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
+if [[ "$check_remote" -eq 1 ]]; then
+  if [[ ! -f "$repo_root/Formula/simbroker.rb" ]]; then
+    echo "This tree has no Formula/simbroker.rb." >&2
+    exit 1
+  fi
+  remote_url="https://raw.githubusercontent.com/fiveonecode/homebrew-simulator-broker/main/Formula/simbroker.rb"
+  remote_tmp="$(mktemp "${TMPDIR:-/tmp}/simbroker-tap-formula.XXXXXX")"
+  cleanup_remote() {
+    rm -f "$remote_tmp"
+  }
+  trap cleanup_remote EXIT
+  if ! curl --fail --silent --show-error --max-time 15 -A "simulator-broker-sync-homebrew-tap" \
+    -o "$remote_tmp" "$remote_url"; then
+    echo "Could not fetch live tap formula from $remote_url" >&2
+    exit 1
+  fi
+  if ! cmp -s "$repo_root/Formula/simbroker.rb" "$remote_tmp"; then
+    echo "Live tap Formula/simbroker.rb does not match this checkout. Run scripts/sync_homebrew_tap.sh --tap-dir <tap> and push the tap." >&2
+    exit 1
+  fi
+  echo "Live tap formula matches this checkout."
+  exit 0
+fi
+
 if [[ -z "$tap_dir" ]]; then
   usage >&2
   exit 1

spec/build-and-test.md

@@ -41,7 +41,8 @@ A first extracted implementation slice now exists:
   `brew install fiveonecode/simulator-broker/simbroker` clones
   `fiveonecode/homebrew-simulator-broker`. `scripts/sync_homebrew_tap.sh`
   copies `Formula/` and `Casks/` into a tap checkout only when
-  `Formula/simbroker.rb` exists
+  `Formula/simbroker.rb` exists. `--check-remote` compares this tree to
+  the published tap formula and is not part of `spec-only`
 - `scripts/package_npm.sh` (`npm run package:npm`) packs `packages/simbroker`
   with a `bin` field; the repo-root package stays `private`
 - `Casks/simulator-broker.rb` installs `Simulator Broker.app` from
@@ -53,8 +54,9 @@ A first extracted implementation slice now exists:
   app snapshot must inject the fixture `simctl` adapter. The default
   public-surface scan reads index blobs only for dirty or missing worktree
   files so a clean checkout does not spawn one `git cat-file` per file.
-- tagged versions such as `v0.1.0-alpha.1` attach the CLI tarball to a GitHub
-  Release through `.github/workflows/release.yml`
+- tagged versions such as `v0.1.0-alpha.1` attach the CLI tarball and the
+  packable `simbroker-<version>.tgz` to a GitHub Release through
+  `.github/workflows/release.yml`
 - local-debug portable bundle support through a zip bundle plus package-smoke verification of the bundled install path and installed-app launch proof
 - a separate Release distribution packaging path that requires operator-supplied signing inputs, runs `codesign` plus `spctl`, optionally notarizes with `notarytool`, and writes a readiness summary JSON
 - executable `agent-harness/` changes now route through the implementation