docs: recommend bun for global installs#681
Conversation
Bun blocks untrusted postinstall scripts by default, giving users visibility into what runs during installation. This is particularly relevant for globally installed CLI tools like OpenSpec, which includes a postinstall script for shell completions that npm runs silently. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
📝 WalkthroughWalkthroughDocumentation reorganized to promote bun package manager installation instructions. The bun installation block was repositioned before npm with a new "recommended" subsection emphasizing security and postinstall behavior. Removed duplicate bun instructions previously located at the end of the Package Managers section. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
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. Comment |
Greptile OverviewGreptile SummaryReordered package manager installation options to recommend bun over npm, with an explanation of bun's security benefits for global installs. The change accurately describes how bun blocks untrusted postinstall scripts by default (requiring explicit
Confidence Score: 5/5
Important Files Changed
Sequence DiagramsequenceDiagram
participant User
participant npm
participant bun
participant postinstall.js
participant Shell
Note over User,Shell: npm install flow
User->>npm: npm install -g @fission-ai/openspec
npm->>postinstall.js: Execute automatically (silent)
postinstall.js->>Shell: Auto-install completions
postinstall.js-->>npm: Complete
npm-->>User: Installation complete
Note over User,Shell: bun install flow
User->>bun: bun add -g @fission-ai/openspec
bun->>bun: Block untrusted postinstall
bun-->>User: Prompt: untrusted script detected
User->>bun: bun pm trust @fission-ai/openspec
bun->>postinstall.js: Execute after user approval
postinstall.js->>Shell: Auto-install completions
postinstall.js-->>bun: Complete
bun-->>User: Installation complete
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@docs/installation.md`:
- Around line 9-16: Update the "### bun (recommended)" section to clarify Bun's
default allowlist behavior: note that Bun blocks lifecycle scripts by default
but ships with a default allowlist of popular npm packages (so some common
packages may run postinstall unless explicitly distrusted), that the allowlist
applies only to npm registry packages (packages installed from git:, file:, or
link: sources must be explicitly trusted), and add guidance to use the existing
commands shown (bun pm trust <pkg>) to trust packages and bun install
--ignore-scripts to override/disable all script execution.
🧹 Nitpick comments (2)
docs/installation.md (2)
5-5: Consider adding a Bun version prerequisite.The Prerequisites section specifies a Node.js version requirement, but doesn't mention a minimum Bun version. Since Bun is now the recommended installation method, consider documenting a minimum version requirement to ensure users have access to the security features mentioned.
📝 Proposed addition to prerequisites
## Prerequisites - **Node.js 20.19.0 or higher** — Check your version: `node --version` +- **Bun 1.x or higher** (if using bun) — Check your version: `bun --version`
15-15: Consider mentioning potential compatibility trade-offs.While the security benefits are clearly stated, users might benefit from knowing about any potential compatibility or stability considerations when choosing Bun over npm. For example, does Bun have full compatibility with all npm packages? Are there any known edge cases?
This would help users make an informed decision, especially for production environments where stability is critical.
| ### bun (recommended) | ||
|
|
||
| ```bash | ||
| bun add -g @fission-ai/openspec@latest | ||
| ``` | ||
|
|
||
| > **Why bun?** Bun blocks untrusted postinstall scripts by default, giving you visibility into what runs during installation. For example, OpenSpec includes a postinstall script that auto-installs shell completions — npm runs it silently, while bun surfaces it so you can review and opt in via `bun pm trust`. For packages you install globally, this default-deny behavior is a meaningful supply chain security improvement. | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Bun postinstall scripts default behavior security bun pm trust
💡 Result:
- Default behavior: Bun runs your project’s
{pre|post}installand{pre|post}preparescripts, but does not run lifecycle scripts (e.g.,postinstall) from installed dependencies by default because they can execute arbitrary shell commands (security risk). [1][2] - How to allow (trust) dependency scripts: Add packages to
trustedDependenciesin your app’spackage.json; Bun will then run lifecycle scripts only for those explicitly trusted packages. [1][2] bun pm trust:bun pm trust <pkg>is the convenience command that adds<pkg>totrustedDependenciesfor you. [3]- Built-in allowlist: Bun also ships with a default allowlist of popular npm packages with lifecycle scripts (described as “top 500” on the lifecycle docs); this default applies only to packages installed from npm, not
file:,link:,git:, orgithub:sources (those must be explicitly trusted to prevent spoofing). [1][3] - Disable all scripts: Use
bun install --ignore-scripts. [1]
Sources:
[1] Bun docs – Lifecycle scripts: https://bun.com/docs/pm/lifecycle
[2] Bun docs – bun install: https://bun.com/docs/pm/cli/install
[3] Bun guide – Add a trusted dependency (bun pm trust): https://bun.com/guides/install/trusted
Clarify the default behavior for popular packages—Bun includes an allowlist.
The security claims are accurate, but the documentation may mislead readers about how strict the defaults actually are. Bun blocks lifecycle scripts from dependencies by default, but it ships with a default allowlist of approximately 500 popular npm packages, whose scripts will run unless explicitly distrusted. The bun pm trust <pkg> command is verified to work as described, allowing users to add new packages to trustedDependencies.
For completeness, consider clarifying that:
- This allowlist applies only to packages from npm; packages from
git:,file:, orlink:sources must be explicitly trusted - Popular packages (e.g., common build tools) may already run their postinstall scripts by default
- Users can override all script execution with
bun install --ignore-scripts
🤖 Prompt for AI Agents
In `@docs/installation.md` around lines 9 - 16, Update the "### bun (recommended)"
section to clarify Bun's default allowlist behavior: note that Bun blocks
lifecycle scripts by default but ships with a default allowlist of popular npm
packages (so some common packages may run postinstall unless explicitly
distrusted), that the allowlist applies only to npm registry packages (packages
installed from git:, file:, or link: sources must be explicitly trusted), and
add guidance to use the existing commands shown (bun pm trust <pkg>) to trust
packages and bun install --ignore-scripts to override/disable all script
execution.
1 participant
Bun blocks untrusted postinstall scripts by default. OpenSpec's
postinstallauto-installs shell completions — npm runs it silently, bun surfaces it for review. For globally installed CLIs, that matters.Moves bun to the top of the install options in
docs/installation.mdwith a short note explaining why.🤖 Generated with Claude Code
Summary by CodeRabbit