feat: Add Homebrew channel and install-aware updates - #196
Merged
Conversation
Users previously needed a Node.js runtime to run the CLI, and every release shipped transpiled JS through a single npm package. Compiling with Bun produces one self-contained binary per platform, so the CLI runs with no runtime prerequisite and distributes directly through GitHub Releases. A compiled binary cannot discover package assets on disk at runtime, so integrations, bundled skills, and the Agent SDK executable move to generated manifests: the first two are embedded statically, while the Agent SDK is downloaded on first agent use and verified against a sha256 pinned at build time. Every release binary is smoke tested on native hardware for all five targets (including the new `workos internal verify-assets` command) before the draft release publishes, so a broken binary can never become `latest`. npm remains a secondary channel: a thin launcher package plus one platform package per binary (the esbuild pattern) preserves `npm install -g workos` and `npx workos`. BREAKING CHANGE: The npm package no longer exports a library API — `main`/`exports` are gone and it only provides the `workos` binary. Development now requires Bun >= 1.3.0 instead of Node >= 22.11.
The Bun standalone binaries only covered glibc Linux, so the CLI could not run on Alpine and other musl systems, and Windows ARM users were left running the x64 build under emulation. Runtime musl detection mirrors the napi-rs loaders so the npm launcher and the Agent SDK download both resolve the same target the binary was compiled for, and musl artifacts are smoke tested in real Alpine containers because no glibc host can prove they run.
A partial npm publish failure left the release permanently half-published: re-running the job hit npm's cannot-publish-over- existing-version error on the first already-live package and aborted before reaching the unpublished ones, including the launcher. Guarding each publish with `npm view` makes re-runs converge, so the job comment's "re-run just this job" recovery actually works.
On Alpine, `bun install` (postinstall runs generate) pinned the glibc Agent SDK package while the runtime's musl detection demanded the musl one, so every dev agent use threw a target mismatch. The keyring-binding check in build.ts assumed glibc the same way. Both scripts now mirror the runtime's isMuslRuntime() when WORKOS_BUILD_TARGET is unset; explicit targets are unchanged.
The first-run download (~100MB from the npm registry) had no abort signal, so a stalled connection hung `workos install` forever mid-progress, and any transient network error failed the run outright. A stall timer that resets on each received chunk catches both connect hangs and mid-stream stalls without penalizing slow links, and a single retry absorbs transient failures. Checksum mismatches stay hard failures and are never retried.
After the first install the cached executable is only revalidated by file size, so silent size-preserving corruption (disk fault, antivirus quarantine/restore) passed unnoticed until runtime. `internal verify-assets` is the diagnostic a user with a corrupted cache gets pointed at, so it now re-hashes the executable against the pinned manifest digest and fails with a distinct error code and a delete-the-cache remedy.
The concurrent-extraction recovery in materializeFile (accept a winner's byte-identical copy, re-throw on divergence) had no coverage; only the happy path was exercised. A mocked renameSync that plants the winner's file before failing forces both branches and proves no temp files are orphaned either way.
Nothing in src/ imports it, so it reads as removable — but ink's devtools.js statically imports it and `bun build --compile` cannot prove the DEV-gated branch dead, so removing the dep fails the compile. `--external` compiles but crashes the binary on every command. Documenting the measured ~742 KiB cost and the failed alternatives keeps a well-meaning cleanup from breaking the build.
Conflicts and semantic resolutions against #192: - src/lib/validation/validator.ts: kept this branch's static JSON rule imports (required for the compiled binary) alongside main's new detectPort import; main's port-detection call sites auto-merged. - src/bin.ts: took main's $0 default handler (JSON command tree via buildCommandTree, else parser.showHelp()) — it supersedes this branch's one-line scriptName fix because the parser already carries .scriptName('workos'). - src/bin-default-command.integration.spec.ts (new on main): converted the subprocess spawn from `node --import tsx` to `bun --preload`, matching bin-command-telemetry.integration.spec.ts — tsx is no longer a dependency on this branch. - 12 new tests from #192 asserted the `npx workos@latest` hint form when npm-exec variables are present; this branch always emits the standalone `workos` form, so those tests now assert the hints are invariant to npm env, matching recovery-hints.spec.ts.
The only npm-channel check was running the launcher script directly with NODE_PATH, which bypasses everything that can actually break for users: registry fetch, optionalDependencies platform selection, npx cache and bin linking, and the launcher's no-binary error path. A manual dress rehearsal against a local registry surfaced real gaps the shortcut can't see (npm nests global deps inside the package; a brew-installed `workos` shadows bare `npx workos` unless the prefix and PATH are isolated). Codifying it makes `npx workos` a gated guarantee: every PR runs it, and the release pipeline runs it after generating the real packages — so a packaging regression fails before anything touches npmjs.org. The registry has no uplinks, proving the install is self-contained.
The smoke gates proved the binary starts (--version, --help, verify-assets) but nothing executed real subcommands and asserted the non-TTY contract that agents and CI pipelines script against: exit codes (0 success, 1 error, 4 auth required), structured JSON errors on stderr, and JSON output. Seven of the eight platform binaries never ran a user-facing command before shipping. command-smoke.sh is POSIX sh so the same checks run inside the --network none debian container on PRs, inside the Alpine containers for musl, under Git Bash on the Windows runners, and directly on the mac/linux legs — every release binary now executes the contract on native hardware before the draft release publishes. It sandboxes HOME/USERPROFILE and uses --insecure-storage so host auth state can never leak in, keeping the exit-4 assertion deterministic.
The smoke gates covered offline behavior only — no shipped binary ever executed a command that talks to the WorkOS API before release. With a dedicated staging-environment key the contract smoke now also runs an authenticated section: organization list plus a create → get → delete round-trip, exercising key resolution, real HTTP, and JSON output on the write path. The key is withheld from the offline checks so the exit-4 assertion stays deterministic, a cleanup trap deletes the round-trip org even when a mid-flight check fails, and the CI step skips itself when the WORKOS_SMOKE_API_KEY secret is absent — fork PRs receive no secrets, so this cannot fail there.
…ng API URL The authenticated section discarded stderr, so a CI failure showed exit codes with no cause. The CLI's structured errors are key-free by design (keys are masked in all output), so printing them is safe and turns a blind failure into a diagnosis. WORKOS_SMOKE_API_URL lets the smoke key target a non-default API host, guarded so an unset secret cannot inject an empty WORKOS_API_URL.
A keyring or file blob missing the required token fields — left by a partial write or an older schema — was returned as-is by getCredentials(). Consumers assume accessToken/expiresAt/userId exist, so `new Date(undefined).toISOString()` threw on every authenticated command AND on auth status, bricking the CLI until the entry was deleted by hand. Found on a real machine while smoke testing this branch: the entry held only the staging sub-object. The bug predates the Bun migration (main has the same code), but the binary upgrade makes stale keyring entries a mainstream path, so validate required fields at both read sites and degrade to "not logged in — run workos auth login", which also overwrites the bad entry on the next login. Malformed file blobs are no longer migrated into the keyring either.
When the version gate refused an install (Next.js < 15.3, React Router < 6), the integration returned an empty summary, which the runAgent wrapper mapped to success:true — so agents and CI scripting `workos install --json` saw "Successfully installed WorkOS AuthKit!" with exit 0 while nothing was installed. Found by running the compiled binary against the bundled Next.js 14 fixture. Gates now throw InstallDeclinedError, which rides the machine's existing error path: exit 1, a structured stderr error and NDJSON error/complete events carrying unsupported_framework_version, while the human flow keeps its friendly guidance (adapters recognize the decline code and skip the generic failure styling and AI-service message rewrites).
The typescript-strict fixture pinned Next.js ^14.2.0 while the installer's own version gate requires >= 15.3.0, so the bundled fixture could never exercise the agent path — every eval or manual run against it hit the gate instead. Next 15 pairs with React 19, whose types drop the global JSX namespace, so the annotations move to ReactElement. Verified with tsc --noEmit and next build.
The recent malformed-credentials fix made getCredentials() return null for a blob missing required token fields, but hasCredentials() still reported true from a bare file/entry probe. A caller that gated on hasCredentials() alone would treat a malformed blob as logged-in and then hit the very null the fix was meant to prevent. Validating at both read sites keeps the two functions from ever disagreeing, without triggering getCredentials()'s keyring migration as a side effect of a boolean check.
Three robustness gaps surfaced while reviewing the first-run download path: - The stale-cache reap deleted every sibling version dir unconditionally, so an upgrade run could remove the executable out from under a concurrently running other-version CLI. A 24h staleness guard (matching the skills reaper) leaves fresh dirs alone. - gunzip ran unbounded before the sha256 gate, so a compromised or corrupt registry response could expand a gzip bomb in memory before verification had a chance to reject it. Capping output at the pinned executable size plus headroom bounds it. - A retry restarted the byte count at zero, which froze the progress readout until it re-passed the previous peak. An onRetry hook resets the throttle and tells the user it is retrying.
The update notice always pointed at the generic GitHub download link, so the suggested action rarely matched how the CLI was actually installed. It now infers the channel from the running binary's path and prints the matching command — brew upgrade, npm install -g, or the download link. Homebrew joins npm as a supported channel: each stable release regenerates the tap formula from the same published binaries and pushes it to workos/homebrew-tap, keeping brew in lockstep with releases instead of the hand-maintained, now-stale formula.
Greptile SummaryThis PR adds Homebrew distribution and install-aware update notices. The main changes are:
Confidence Score: 5/5This looks safe to merge.
Important Files Changed
Reviews (4): Last reviewed commit: "ci: Split the Bun CI workflow into lint ..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
The npm launcher's binary sits at …\node_modules\@workos\cli-win32-x64 \bin\workos.exe on Windows, whose backslashes never matched the /node_modules/ marker — so Windows npm users were told to re-download from GitHub Releases instead of running npm install -g. Normalize separators before matching.
The SDK Automation Bot is already installed on workos/homebrew-tap with contents write, so mint a tap-scoped installation token from it instead of provisioning a dedicated PAT — one fewer secret to manage, and it matches how the SDK repos already publish.
Resolves conflicts from the #195 squash-merge (Bun standalone) and the #200 consent-gated setup / flat output rework: - release.yml: keep the publish-homebrew job on top of main's release flow - install.ts / bin.ts: take main's maybeRunSetupAfter flow; drop the superseded autoInstallSkills + maybeOfferMcpInstall wiring - clack -> ui module rename applied across integrations and specs - version-check.ts: keep install-aware upgradeNotice() over the static URL - install.spec.ts: drop a duplicated describe block referencing clack - bun.lock: regenerated against the merged package.json Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
PR #195 dropped id-token: write from the caller while adding a publish-npm job that requests it in the called release.yml — a called workflow cannot request permissions the caller does not hold, so every Release Please run on main dies at startup before any job runs. Also pass secrets: inherit on the call: called workflows receive no secrets by default, and publish-homebrew needs SDK_BOT_PRIVATE_KEY to push the formula to workos/homebrew-tap. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Lint (oxlint, format check, typecheck) fails fast and independently of the test workflow (vitest, manifest freshness, standalone build, and the four smoke tests), so a style failure no longer hides a test result and the two run in parallel. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
gjtorikian
added a commit
that referenced
this pull request
Jul 26, 2026
* docs: add Homebrew install instructions to the README The Homebrew channel shipped in #196 and the tap formula is live, but the README's Installation section only covered GitHub Releases and npm. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: point Windows readers at the npm install option --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
detectInstallMethod()infers homebrew / npm / downloaded-binary from the running binary'sprocess.execPathand prints the matching upgrade command (brew upgrade workos,npm install -g workos@latest, or the GitHub download link) instead of the one-size-fits-all link that rarely matched how the CLI was actually installed.publish-homebrewjob regenerates the tap formula from the same published binaries and pushes it toworkos/homebrew-tapon every stable release, sobrew install workos/tap/workosandbrew upgrade workostrack releases instead of the hand-maintained, now-stale formula.scripts/gen-homebrew-formula.tscomputes each platform's sha256 from the release artifacts, rejects prereleases, and emits an audit-cleandesc. Stable-only is enforced twice: the job is gatedif: !contains(tag, '-')and the generator throws on prerelease versions.install-method.spec.tscovers detection and upgrade strings across mac/Linuxbrew/npm/download paths;version-check.spec.tspins the notice via a mock so the assertion no longer depends on the test runner's own execPath.