🧪 upgrade-sandbox

Try before you buy — for npm dependencies. Instant hardlink-based sandbox that tests dependency upgrades in complete isolation. No Docker. No VMs. Milliseconds to create.

Features · Quick Start · CLI · How It Works · vs Competitors

✨ Features

| Feature | What It Does | |:--------|:-------------| | ⚡ Instant Hardlink Sandbox | Creates an isolated copy of your project in milliseconds — not minutes. Zero disk overhead | | 🔒 Config File Protection | package.json and lockfiles are COPIED, not hardlinked — your host project is never mutated | | 🔍 Auto PM Detection | Detects npm, yarn, pnpm, or bun from lockfiles — uses the right install command automatically | | 📊 Telemetry Built-In | Measures install duration, test duration, and exit codes — perfect for benchmarking | | 🧹 Zero Cleanup | Sandbox directory is auto-deleted after the run. Nothing left behind | | 🛡️ Shell-Safe Installs | Package manager installs use execFile() (no shell) — no injection risk | | ⏱️ Timeout Support | --timeout kills hung installs or tests |

[!NOTE] New in 1.0: Bun support, PM-aware default test commands (yarn test / pnpm test / bun test), bun.lockb protection in sandbox.

🚀 Quick Start

npm install -g upgrade-sandbox

# Test if upgrading lodash breaks your project
upgrade-sandbox run [email protected]

# Custom test command
upgrade-sandbox run [email protected] --test-cmd="npm run build && npm test"

# With timeout
upgrade-sandbox run [email protected] --timeout=120000

📖 CLI Reference

upgrade-sandbox run <pkg>[@version] [options]

upgrade-sandbox run lodash@latest                       # Default: runs "npm test"
upgrade-sandbox run [email protected] --test-cmd="npm run ci" # Custom verification
upgrade-sandbox run next@canary --timeout=300000         # 5-minute timeout

| Flag | Description | Default | |:-----|:------------|:-------| | --test-cmd=<cmd> | Command to verify compatibility | <pm> test | | --timeout=<ms> | Timeout for install and test commands | none | | --sandbox-dir=<dir> | Custom sandbox path | .upgrade-sandbox |

The default test command adapts to your package manager: npm test, yarn test, pnpm test, or bun test.

Example Output

--- UPGRADE SANDBOX REPORT ---
Package Tested:    [email protected]
Package Manager:   npm
Install Duration:  4523ms
Test Duration:     12450ms
Test Status:       PASSED (Success)
------------------------------

🔧 How It Works

┌────────────────────────────────────────────────────────┐
│  1. DETECT                                             │
│  Scan lockfiles → identify npm / yarn / pnpm / bun     │
├────────────────────────────────────────────────────────┤
│  2. SANDBOX                                            │
│  Create .upgrade-sandbox/run-xxxx/                     │
│  Hardlink all source files (instant, zero disk)        │
│  COPY package.json + lockfiles (protects host project) │
│  Skip: node_modules, .git, dist                        │
├────────────────────────────────────────────────────────┤
│  3. INSTALL                                            │
│  Run <pm> add <pkg> inside sandbox via execFile()      │
│  → No shell — no injection risk                        │
├────────────────────────────────────────────────────────┤
│  4. TEST                                               │
│  Run --test-cmd inside sandbox                         │
│  → Capture stdout, stderr, exit code, duration         │
├────────────────────────────────────────────────────────┤
│  5. REPORT + CLEANUP                                   │
│  Print telemetry report                                │
│  → Delete sandbox directory entirely                   │
└────────────────────────────────────────────────────────┘

[!WARNING] Source files are hardlinked — editing them inside the sandbox affects the host. Package installers write new files by unlinking first, so installing packages will never alter your host node_modules or config files.

🆚 Why upgrade-sandbox?

| Tool | Isolation Method | Setup Speed | PM Auto-Detect | No External Deps | Telemetry | |:-----|:----------------|:-----------:|:--------------:|:----------------:|:---------:| | upgrade-sandbox | Hardlinks | < 1ms | ✅ npm/yarn/pnpm/bun | ✅ (Node only) | ✅ | | npm-package-tester | Docker | Minutes | ❌ | ❌ (needs Docker) | ❌ | | @jagreehal/sandbox-node | Docker / Native | Slow | ✅ | ❌ (needs Docker) | ❌ | | safe-npm-updater | Git branch | Seconds | ❌ | ✅ | ❌ | | @fendsh/cli | macOS VM | Seconds | ❌ | ❌ (macOS only) | ❌ |

The difference: 790K developers use npm-check-updates weekly to find upgrades — virtually none test them in isolation. upgrade-sandbox bridges that gap with the fastest possible sandbox: hardlinks. No Docker pull. No VM boot. No git branch dance. Just run it and know.

📄 License

MIT · codecrypt112