Skip to content

docs: recommend bun for global installs #681

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
0xRaduan wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: recommend bun for global installs #681

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 8 additions & 6 deletions docs/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,14 @@

## Package Managers

### 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.

Comment on lines +9 to +16
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🌐 Web query:

Bun postinstall scripts default behavior security bun pm trust

💡 Result:

  • Default behavior: Bun runs your project’s {pre|post}install and {pre|post}prepare scripts, 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 trustedDependencies in your app’s package.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> to trustedDependencies for 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:, or github: 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:, or link: 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.

### npm

```bash
Expand All @@ -24,12 +32,6 @@ pnpm add -g @fission-ai/openspec@latest
yarn global add @fission-ai/openspec@latest
```

### bun

```bash
bun add -g @fission-ai/openspec@latest
```

## Nix

Run OpenSpec directly without installation:
Expand Down
Loading