cline--cline/.clinerules/bun-and-node.md

Bun (tooling) and Node (runtime)

This repo uses bun for package management and task running, and Node as the execution runtime. Both are correct at the same time; the distinction is the source of most confusion, so keep it straight before editing scripts, configs, docs, or comments.

Use bun for tooling

• bun install (never npm install / npm ci)
• bun run <script> (never npm run <script>)
• bunx <bin> (never npx <bin>)
• bun <file>.ts to run a TS entrypoint directly (no ts-node / tsx)
• bun esbuild.mjs to drive the build (esbuild/vite are still the bundlers)
• bun run --parallel ... for parallel tasks

The root bun.lock is the single lockfile for the whole workspace, including apps/vscode, webview-ui, and testing-platform. There are no per-package npm lockfiles.

Node is the runtime — do NOT rewrite these to bun

The build product runs on Node: the VS Code extension host loads dist/extension.js as CommonJS under Node, and the standalone cline-core is a Node process. The following are Node runtime/ABI references and are correct as-is:

Reference	Why it is Node
esbuild platform: "node" / target: "node..."	The bundle targets the Node runtime (extension host, standalone core).
TARGET_NODE_VERSION (scripts/package-standalone.mjs)	Pins the Node ABI of the bundled standalone runtime (matches the JetBrains-packaged Node).
prebuild-install --target=<node version>	Downloads native .node binaries for that Node ABI.
NODE_PATH=... node cline-core.js	The standalone core is launched by Node, not bun.
node: import specifiers (e.g. node:fs)	Node builtin module scheme; unrelated to tooling.
process.versions.node, engines.node, @types/node	Runtime version probe / declared runtime / its types.
ELECTRON_RUN_AS_NODE	VS Code/Electron runs the extension host as Node.

When a file legitimately uses both bun and node (e.g. package-standalone.mjs does bun install but prebuild-install --target=<node>), the node token is the runtime/ABI target, not tooling. If unsure, leave it.

Tests: bun vs the VS Code host

A test file's runner is decided by its import:

• import ... from "bun:test" → runs under bun test (the node-side unit suites + the SDK/model-catalog suites). scripts/run-bun-unit-tests.ts discovers these by the bun:test import and runs one isolated bun process per file. build-tests.js excludes them from the integration compile so the bun:test builtin never reaches Node.
• import ... from "mocha" → runs under @vscode/test-cli in a real VS Code extension host (Node). These exercise the live vscode API and cannot run under bun.

So a file imports bun:test XOR mocha. Don't add bun:test to a test that needs the real extension host.