Merge pull request #12 from fiveonecode/release/homebrew-notarized-npm

Add Homebrew formula, cask, and packable simbroker npm CLI

Author: VladimirBrejcha

.agents/manifests/specs.yaml

@@ -15,7 +15,12 @@ globs:
   - examples/**/.simulator-broker/*.json
   - spec/**
   - references/**
+  - Casks/**
+  - Formula/**
+  - packages/simbroker/**
   - scripts/package_cli.sh
+  - scripts/package_npm.sh
+  - scripts/sync_homebrew_tap.sh
 owner: spec-steward
 required_skills:
   - harness-engineering
@@ -44,7 +49,12 @@ allowed_paths:
   - examples/**/.simulator-broker/*.json
   - spec/**
   - references/**
+  - Casks/**
+  - Formula/**
+  - packages/simbroker/**
   - scripts/package_cli.sh
+  - scripts/package_npm.sh
+  - scripts/sync_homebrew_tap.sh
 forbidden_paths: []
 required_evidence:
   - structured-git-commit

.agents/verify/spec-only.yaml

@@ -4,7 +4,7 @@ covers_scenarios: []
 covers_boundaries: []
 commands:
   - id: spec-diff-check
-    run: git diff --check -- WORKFLOW.md AGENTS.md CLAUDE.md README.md LICENSE SECURITY.md CONTRIBUTING.md CODE_OF_CONDUCT.md CHANGELOG.md docs spec .agents agent-harness package.json package-lock.json .gitignore .github .codex script scripts references app broker-core client && git diff --cached --check -- WORKFLOW.md AGENTS.md CLAUDE.md README.md LICENSE SECURITY.md CONTRIBUTING.md CODE_OF_CONDUCT.md CHANGELOG.md docs spec .agents agent-harness package.json package-lock.json .gitignore .github .codex script scripts references app broker-core client
+    run: git diff --check -- WORKFLOW.md AGENTS.md CLAUDE.md README.md LICENSE SECURITY.md CONTRIBUTING.md CODE_OF_CONDUCT.md CHANGELOG.md docs spec .agents agent-harness package.json package-lock.json .gitignore .github .codex script scripts references app broker-core client Formula Casks packages && git diff --cached --check -- WORKFLOW.md AGENTS.md CLAUDE.md README.md LICENSE SECURITY.md CONTRIBUTING.md CODE_OF_CONDUCT.md CHANGELOG.md docs spec .agents agent-harness package.json package-lock.json .gitignore .github .codex script scripts references app broker-core client Formula Casks packages
   - id: public-front-door-check
     run: node --test docs/test/*.test.mjs
   - id: instruction-parity-check

.github/ISSUE_TEMPLATE/feature.yml

@@ -7,8 +7,10 @@ body:
     attributes:
       value: |
         Simulator Broker is **Alpha**, **macOS-only**, and needs **Xcode**.
-        It is maintenance-only infrastructure. There is no Homebrew formula,
-        notarized app, or npm package yet.
+        It is maintenance-only infrastructure. The CLI installs through
+        Homebrew or the packable `simbroker` npm package. A signed,
+        notarized operator app zip is not attached to the current Alpha
+        release.
 
         Maintainers may decline requests that add a feature, commercialization,
         or UX roadmap.

.github/ISSUE_TEMPLATE/install-failure.yml

@@ -7,8 +7,11 @@ body:
     attributes:
       value: |
         Simulator Broker is **Alpha**, **macOS-only**, and needs **Xcode** to
-        create or run iOS Simulators. There is no Homebrew formula, notarized
-        app, or npm package yet.
+        create or run iOS Simulators. Install the CLI with
+        `brew install fiveonecode/simulator-broker/simbroker` or
+        `npm install -g` of the `simbroker-0.1.0-alpha.1.tgz` from GitHub
+        Releases. A signed, notarized operator app zip is not attached to
+        this Alpha release.
 
         Do not paste credentials, private home paths, customer data, or
         live lease files. Redact logs first. Security reports go through
@@ -19,6 +22,8 @@ body:
     attributes:
       label: What install path did you use?
       options:
+        - Homebrew (`brew install fiveonecode/simulator-broker/simbroker`)
+        - npm (`npm install -g` of `simbroker-0.1.0-alpha.1.tgz` from GitHub Releases)
         - CLI-only (`bash scripts/install_local.sh --cli-only`)
         - Contributor app + CLI (`npm run install:local`)
         - Alpha CLI tarball from GitHub Releases

.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

@@ -5,6 +5,22 @@ All notable changes to Simulator Broker are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- Homebrew formula `Formula/simbroker.rb` installs the Alpha CLI tarball
+  (`brew install fiveonecode/simulator-broker/simbroker`). Homebrew clones
+  [`fiveonecode/homebrew-simulator-broker`](https://github.com/fiveonecode/homebrew-simulator-broker)
+  for that tap name. `Formula/` and `Casks/` here stay the source of truth.
+- Homebrew cask `Casks/simulator-broker.rb` installs `Simulator Broker.app`
+  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. 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
 
 First tagged Alpha. The CLI, local `brokerd` service, and macOS operator app

Casks/simulator-broker.rb

@@ -0,0 +1,21 @@
+cask "simulator-broker" do
+  version "0.1.0-alpha.1"
+  sha256 :no_check
+
+  url "https://github.com/fiveonecode/simulator-broker/releases/download/v#{version}/Simulator-Broker-#{version}.zip"
+  name "Simulator Broker"
+  desc "macOS operator app for the local iOS Simulator control plane"
+  homepage "https://github.com/fiveonecode/simulator-broker"
+
+  depends_on macos: :ventura
+
+  app "Simulator Broker.app"
+
+  caveats <<~EOS
+    This cask installs Simulator Broker.app from the signed, notarized
+    GitHub Release zip Simulator-Broker-#{version}.zip. Produce that zip
+    with npm run package:distribution (Developer ID Application + notarytool),
+    using payload/app/Simulator Broker.app from the distribution bundle.
+    The current Alpha GitHub Release attaches the CLI tarball, not this zip.
+  EOS
+end

Formula/simbroker.rb

@@ -0,0 +1,22 @@
+class Simbroker < Formula
+  desc "Local iOS Simulator control plane CLI"
+  homepage "https://github.com/fiveonecode/simulator-broker"
+  url "https://github.com/fiveonecode/simulator-broker/releases/download/v0.1.0-alpha.1/simulator-broker-0.1.0-alpha.1-cli.tar.gz"
+  sha256 "699695bc65a5bcb25b9c9b5d01494fcc3f25a40dcc90b8b5bf1ec61ea87a8522"
+  license "MIT"
+
+  depends_on :macos
+  depends_on "node"
+
+  def install
+    libexec.install Dir["*"]
+    (bin/"simbroker").write <<~SH
+      #!/bin/bash
+      exec "#{formula_opt_bin("node")}/node" "#{libexec}/client/bin/simbroker.mjs" "$@"
+    SH
+  end
+
+  test do
+    assert_match "simbroker", shell_output("#{bin}/simbroker --help")
+  end
+end

README.md

@@ -4,8 +4,9 @@ A local control plane so humans, AI agents, and CI jobs can share iOS Simulators
 on one Mac without stealing devices from each other.
 
 > **Alpha.** macOS only. Xcode is required to create or run iOS Simulators.
-> Interfaces can change. There is no Homebrew formula, notarized app, or npm
-> package yet.
+> Interfaces can change. Install the CLI with Homebrew or the `simbroker`
+> npm package. A signed, notarized operator app is not attached to this
+> Alpha release yet.
 
 [![Node tests](https://github.com/fiveonecode/simulator-broker/actions/workflows/ci.yml/badge.svg)](https://github.com/fiveonecode/simulator-broker/actions/workflows/ci.yml)
 
@@ -27,29 +28,47 @@ If you only ever use one simulator by hand, you may not need this yet.
 
 ## Use it
 
-From a clone, with Node.js 20+ on `PATH`:
+One-line CLI install on macOS, with Node.js 20+ still required at runtime:
+
+```bash
+brew install fiveonecode/simulator-broker/simbroker
+simbroker --help
+```
+
+Homebrew clones
+[`fiveonecode/homebrew-simulator-broker`](https://github.com/fiveonecode/homebrew-simulator-broker)
+for that tap name. `Formula/` and `Casks/` in this repository stay the
+source of truth.
+
+```bash
+npm install -g https://github.com/fiveonecode/simulator-broker/releases/download/v0.1.0-alpha.1/simbroker-0.1.0-alpha.1.tgz
+simbroker --help
+```
+
+From a clone:
 
 ```bash
 bash scripts/install_local.sh --cli-only
 command -v simbroker
 simbroker --help
 ```
 
-That copies the CLI runtime only. It does not run XcodeGen or build the macOS
-app. If Homebrew is installed, `simbroker` lands in `$(brew --prefix)/bin`.
-Otherwise the installer writes `~/.local/bin/simbroker` and one guarded
-login-shell PATH line. Open a new terminal if this shell still cannot resolve
-`simbroker`. `source .../env.sh` remains a fallback.
+The clone installer copies the CLI runtime only. It does not run XcodeGen or
+build the macOS app. If Homebrew is installed, `simbroker` lands in
+`$(brew --prefix)/bin`. Otherwise the installer writes `~/.local/bin/simbroker`
+and one guarded login-shell PATH line. Open a new terminal if this shell still
+cannot resolve `simbroker`. `source .../env.sh` remains a fallback.
 
-To try a tagged build without cloning, download
-`simulator-broker-<version>-cli.tar.gz` from
-[Releases](https://github.com/fiveonecode/simulator-broker/releases), extract
-it, and run `./bin/simbroker --help`. Node.js 20+ is still required.
+The Homebrew cask `fiveonecode/simulator-broker/simulator-broker` installs
+`Simulator Broker.app` from the signed, notarized GitHub Release zip
+`Simulator-Broker-<version>.zip`. That zip is not attached to the current
+Alpha release. Produce it with `npm run package:distribution` after Developer
+ID signing and notarytool notarization.
 
 Xcode is still required to create and run iOS Simulators. Alpha CLI tarballs
 are attached to
 [GitHub Releases](https://github.com/fiveonecode/simulator-broker/releases).
-There is no Homebrew formula or npm package yet.
+Extract a tarball and run `./bin/simbroker --help`.
 
 `simbroker` help and `simbroker doctor` print human-readable text by default.
 Pass `--json` for machine-readable payloads.

SECURITY.md

@@ -4,8 +4,10 @@
 
 Security fixes are considered for the current `main` branch and for the latest
 tagged Alpha (`0.1.0-alpha.1`). Older Alpha tags are not supported. The
-published artifact is the CLI tarball on GitHub Releases, not a Homebrew
-formula, notarized app, or npm package.
+published CLI artifacts are the GitHub Release tarball, the Homebrew
+formula that installs that tarball, and the packable `simbroker` npm
+package. A signed, notarized operator app zip is not attached to this
+Alpha release.
 
 ## Reporting A Vulnerability