Dotfiles

Appearance

ADR 0007: Bun-First Vibe Core ​

Status: superseded Last reviewed: 2026-06-20 Superseded by: DECISIONS.md#retired-vibe-workflow Accepted: 2026-05-23

This ADR is a historical record. Bun is no longer a repo-owned Vibe Core runtime requirement for this dotfiles repo.

Context ​

Issue #46 asked whether Vibe Core should remain Python, move to Bun-first TypeScript, move to Node-first TypeScript, or take a staged hybrid path. Issue 55 proved the Bun runner spike on WSL/Linux. Follow-up validation covered the native Windows lane and the worker-result mutation executor path.

The accepted issue decision states: adopt Bun-first TypeScript for Vibe Core, keep Node compatibility where practical, keep the current Python runner only as a temporary migration shim until TypeScript behavioural parity is reached, and avoid maintaining a permanent two-language runtime unless a later explicit decision accepts that cost. Issue #56 later completed the TypeScript runner migration and removed the Python runner path.

Decision ​

Use Bun-first TypeScript as the Vibe Core implementation direction.

  • Bun is a required Vibe Core development and execution tool on native Windows, Ubuntu WSL, and CachyOS.
  • The shared mise inventory owns the Bun installation for those lanes.
  • Node and pnpm remain managed for the docs site, npm-distributed CLIs, and projects that declare them. Bun does not replace them for unrelated workstation workflows.
  • The active Vibe runner is the Bun-first TypeScript CLI under .vibe/src/. The previous Python runner is not kept as a second runtime path.

Consequences ​

  • Vibe doctor/status diagnostics should report the managed Bun runtime.
  • Mise source policy should treat Bun as a critical Vibe Core tool.
  • Bootstrap and tool docs should describe Bun as Vibe-scoped, not as a broad dotfiles runtime replacement.
  • Vibe Core runner work can assume Bun is available through the managed tool inventory after normal lane bootstrap.

Alternatives considered ​

  • Stay Python and modularise. Rejected by the issue #46 decision because the early codebase stage makes the rewrite cost acceptable.
  • Use Node-first TypeScript. Rejected for Vibe Core's primary path, while keeping Node compatibility practical where it does not dominate the design.
  • Keep a permanent Python/TypeScript hybrid. Rejected unless a later explicit decision accepts the extra runtime cost.

Follow-up work ​

  • Continue hardening the Bun runner with focused parity tests as new Vibe behavior lands.