Cline rules

1# Bun (tooling) and Node (runtime)
2 
3This repo uses **bun** for package management and task running, and **Node** as
4the execution runtime. Both are correct at the same time; the distinction is the
5source of most confusion, so keep it straight before editing scripts, configs,
6docs, or comments.
7 
8## Use bun for tooling
9 
10- `bun install` (never `npm install` / `npm ci`)
11- `bun run <script>` (never `npm run <script>`)
12- `bunx <bin>` (never `npx <bin>`)
13- `bun <file>.ts` to run a TS entrypoint directly (no `ts-node` / `tsx`)
14- `bun esbuild.mjs` to drive the build (esbuild/vite are still the bundlers)
15- `bun run --parallel ...` for parallel tasks
16 
17The root `bun.lock` is the single lockfile for the whole workspace, including
18`apps/vscode`, `webview-ui`, and `testing-platform`. There are no per-package npm
19lockfiles.
20 
21## Node is the runtime — do NOT rewrite these to bun
22 
23The build product runs on Node: the VS Code extension host loads
24`dist/extension.js` as CommonJS under Node, and the standalone `cline-core` is a
25Node process. The following are Node runtime/ABI references and are correct as-is:
26 
27| Reference | Why it is Node |
28|-----------|----------------|
29| esbuild `platform: "node"` / `target: "node..."` | The bundle targets the Node runtime (extension host, standalone core). |
30| `TARGET_NODE_VERSION` (`scripts/package-standalone.mjs`) | Pins the Node ABI of the bundled standalone runtime (matches the JetBrains-packaged Node). |
31| `prebuild-install --target=<node version>` | Downloads native `.node` binaries for that Node ABI. |
32| `NODE_PATH=... node cline-core.js` | The standalone core is launched by Node, not bun. |
33| `node:` import specifiers (e.g. `node:fs`) | Node builtin module scheme; unrelated to tooling. |
34| `process.versions.node`, `engines.node`, `@types/node` | Runtime version probe / declared runtime / its types. |
35| `ELECTRON_RUN_AS_NODE` | VS Code/Electron runs the extension host as Node. |
36 
37When a file legitimately uses both bun and node (e.g. `package-standalone.mjs`
38does `bun install` but `prebuild-install --target=<node>`), the `node` token is
39the runtime/ABI target, not tooling. If unsure, leave it.
40 
41## Tests: bun vs the VS Code host
42 
43A test file's runner is decided by its import:
44 
45- **`import ... from "bun:test"`** → runs under `bun test` (the node-side unit
46  suites + the SDK/model-catalog suites). `scripts/run-bun-unit-tests.ts`
47  discovers these by the `bun:test` import and runs one isolated bun process per
48  file. `build-tests.js` excludes them from the integration compile so the
49  `bun:test` builtin never reaches Node.
50- **`import ... from "mocha"`** → runs under `@vscode/test-cli` in a real VS Code
51  extension host (Node). These exercise the live `vscode` API and cannot run
52  under bun.
53 
54So a file imports `bun:test` XOR `mocha`. Don't add `bun:test` to a test that
55needs the real extension host.
56