docs(install): document Bun install and improve missing-binary error

[AxDSan]

Summary

Installing @gitlawb/zero with Bun silently skips the wrapper's postinstall, so the native binary is never fetched and the first run fails with:

[zero] No native binary found next to the npm wrapper. Reinstall the zero
package or run `go run ./cmd/zero-release build` from the repository.

That message only helps someone with a source checkout — a Bun user who just ran bun add is left stuck. This PR makes Bun a documented install path and makes the error actionable for everyone.

Why this happens

Bun is "default-secure" and does not run lifecycle scripts of installed dependencies by default — only the installing project's own scripts. @gitlawb/zero isn't on Bun's built-in trustedDependencies list, so the postinstall in scripts/postinstall.mjs (which downloads the platform binary from GitHub Releases) is skipped with no warning. npm/yarn run it, so the documented npm install -g @gitlawb/zero flow works; only Bun users hit this.

Refs: bun.sh/docs/cli/install, bun.sh/docs/pm/lifecycle

Changes

• README.md — new ### Bun subsection under Install with the two working install paths.
• docs/INSTALL.md — new ## Bun section with the same, plus a link to Bun's lifecycle docs.
• bin/zero.js — rewrote the missing-binary error to:
  • keep the existing No native binary found next to the npm wrapper lead line (so the Go wrapper test at internal/npmwrapper/npmwrapper_test.go:259 still passes),
  • tell the user to run scripts/postinstall.mjs manually (concrete fix that works for any package manager), and
  • when launched under Bun (process.versions.bun / bun in execPath), append a Bun-specific note pointing at trustedDependencies.
  • The source-build fallback now points at go run ./cmd/zero rather than go run ./cmd/zero-release build (the latter only makes sense inside a release checkout).

Verification

• node --check bin/zero.js ✓
• Previewed the error under node (generic path) and under bun (Bun-specific hint appears) ✓
• go test ./internal/npmwrapper/ ./internal/release/ ✓ (all pass, including TestNodeWrapperReportsMissingNativeBinary)

ok  github.com/Gitlawb/zero/internal/npmwrapper  0.544s
ok  github.com/Gitlawb/zero/internal/release     0.024s

Notes / possible follow-ups

• A more permanent fix would be to ship the binary via per-platform optionalDependencies packages (esbuild/sharp style), which removes the reliance on a postinstall entirely and works under Bun without trustedDependencies. That's a bigger change and out of scope here; this PR is the minimal docs + error-message fix.
• Happy to trim/adjust wording if you'd prefer a shorter README note.

Summary by CodeRabbit

• Documentation

  • Added Bun-specific installation guidance, including how to handle packages that skip lifecycle scripts by default.
  • Documented two setup options: run the post-install step manually or allow it via trusted dependencies.
  • Expanded install docs with notes for global installs and related lifecycle behavior.

• Bug Fixes

  • Improved the missing-native-binary error message with clearer, step-by-step recovery instructions.
  • Added clearer guidance for Bun users and a fallback path for rebuilding from source.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c6cf1783-e7fd-487c-ad98-536e05060c57

📥 Commits

Reviewing files that changed from the base of the PR and between 952788f and 66ba93e.

📒 Files selected for processing (3)

• README.md
• bin/zero.js
• docs/INSTALL.md

---

Walkthrough

This PR adds Bun-specific remediation guidance for the missing native binary scenario. bin/zero.js now detects Bun installs and prints expanded instructions referencing postinstall.mjs and trustedDependencies; README.md and docs/INSTALL.md document the same Bun installation workflow.

Changes

Bun Install Remediation

Layer / File(s)	Summary
CLI error message with Bun detection bin/zero.js	Computes scripts/postinstall.mjs path, detects Bun via process.execPath/process.versions.bun, and prints an expanded multi-paragraph remediation message before process.exit(1).
Bun installation docs README.md, docs/INSTALL.md	New "Bun" sections explain that Bun skips lifecycle scripts by default, requiring manual postinstall.mjs execution or trustedDependencies configuration to auto-run postinstall.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• Gitlawb/zero#71: Complements the bin/zero.js native-binary remediation flow this PR expands with Bun-specific guidance.
• Gitlawb/zero#88: Also touches the bin/zero.js missing-binary check/entrypoint flow this PR extends.

Suggested reviewers: gnanam1990

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the two main changes: Bun install documentation and improved missing-binary error messaging.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[kevincodex1]

thank you for this

[AxDSan]

thank you for this

Thank you for Zero and everything else! ✨ keep shipping big!

• AJ