Bun Dev

Bun Dev

Rule-first Bun guidance plus a shared audit/remediation engine.

Use bun-dev for operating-model decisions, rule lookup, release sync, and platform routing. Use bun-audit when the task is specifically about scanning a repo, planning safe fixes, applying deterministic remediations, or validating changes against Bun policy.

Start with rules/_index.md for discovery, then route by the Priority Table below.

Navigation (How To Use This Skill)

1. If changing package manager/runtime, open P1 rules first: pm-*, runtime-*, vercel-*.
2. If working in a monorepo, open: scripts-bun-run-parallel-sequential, scripts-bun-filter-and-workspaces.
3. If deploying to Vercel, open: vercel-bun-runtime-enable, vercel-bun-runtime-limitations.
4. For repo-wide enforcement, use the shared CLI: bun-platform audit, plan-fixes, apply-safe-fixes, validate.
5. For “what changed recently?” (Bun v1.3.10), refresh references and open: references/ref-bun-release-notes-bun-v1.3.10.md.

Quick Start (Audit -> Fix -> Verify)

Audit (report-only):

bun ~/.agents/skills/bun-dev/scripts/bun-platform.ts audit --root . --format text

Plan safe fixes:

bun ~/.agents/skills/bun-dev/scripts/bun-platform.ts plan-fixes --root .

Apply safe fixes:

bun ~/.agents/skills/bun-dev/scripts/bun-platform.ts apply-safe-fixes --root .

Validate after remediation:

bun ~/.agents/skills/bun-dev/scripts/bun-platform.ts validate --root . --fail-on warn

Priority Table (Route To The Right Rules)

Quick Reference (Start Here)

1) Package Manager + Lockfiles (CRITICAL)

• pm-bun-add-remove-update
• pm-no-mixed-lockfiles
• pm-commit-bun-lockb
• pm-bun-install-ci-frozen-lockfile
• pm-package-manager-field
• pm-bunx-vs-npx

2) Runtime Selection (CRITICAL)

• runtime-bun-vs-node-choose
• runtime-bun-run-bun-flag
• runtime-ts-direct-execution
• runtime-watch-and-hot-reload
• runtime-env-files

3) Vercel Bun Runtime (CRITICAL)

• vercel-bun-install-detection
• vercel-bun-runtime-enable
• vercel-bun-runtime-limitations
• vercel-nextjs-bun-runtime-scripts
• vercel-bun-function-fetch-handler

4) Scripts + Monorepos (HIGH)

• scripts-bun-run-parallel-sequential
• scripts-bun-filter-and-workspaces
• scripts-no-npm-in-bun-repos

5) TypeScript (HIGH)

• tsconfig-bun-recommended
• tsconfig-bun-types
• tsconfig-module-resolution-bundler

6) Testing + Build (MEDIUM)

• test-bun-test-runner
• test-bun-retry
• test-mocking-and-spying
• build-bun-build-bundler
• build-compile-executables
• build-bun-compile-browser

7) Performance (MEDIUM)

• perf-prefer-bun-native-apis
• perf-avoid-node-fs-promises-hot-paths

8) Migration + Troubleshooting (LOW/MED)

• migrate-node-to-bun-checklist
• troubleshooting-esm-cjs-and-exports
• troubleshooting-types-bun

References (Vendor Docs Snapshots)

Start with references/index.md.

Shared Platform Commands

• audit: report Bun findings in text, md, or json
• list-rules: print all rule ids
• explain <rule-id>: print the matching rule file
• plan-fixes: print deterministic safe fix candidates
• apply-safe-fixes: apply safe file rewrites only
• validate: rerun the audit and fail on a severity threshold
• benchmark: emit audit/fix-planning timings
• release-sync: refresh Bun/Vercel references and rebuild rule indexes

Platform state:

• .bun-platform/cache.sqlite: shared scan cache
• .bun-platform/rollbacks/: safe-fix rollback artifacts
• references/release-sync-report.json: local generated release intelligence summary (ignored; not committed)

Config file:

• bun-platform.config.json
  • disabledRules
  • severityOverrides
  • adapters
  • includePaths
  • excludeDirs
  • baseline
  • maxFiles
  • maxBytes
  • validationCommands
  • manageGitignore
• Example template: assets/templates/bun-platform.config.example.json

Reference Map

Refresh reference snapshots:

bun ~/.agents/skills/bun-dev/scripts/bun-platform.ts release-sync

Automation

Shared CLI:

bun ~/.agents/skills/bun-dev/scripts/bun-platform.ts audit --root .

Compatibility wrapper:

bun ~/.agents/skills/bun-dev/scripts/bun-audit.ts audit --root .

Skill integrity check (rule ids, indexes, flat references):

bun ~/.agents/skills/bun-dev/scripts/check-skill-integrity.ts