@code-yeongyu/senpi-codemode 2026.10.31-1 → 2026.10.31-2

package/src/skill/bun/references/test.md

@@ -0,0 +1,132 @@
+# bun test in 1.4.x
+
+Composable CI recipe:
+
+```bash
+bun test --changed=main                                   # only what your branch touches
+bun test --parallel --timings=timings.json --update-timings
+bun test --parallel --shard=1/3 --timings=timings.json    # in CI, per machine
+bun test --check                                          # type-check test files + imports first; no tests run on a type error [v1.4.3]
+```
+
+## Traps — each one cost a past session hours
+
+| Trap | Fact | Fix |
+|---|---|---|
+| Timeout reaches only the first file | `setDefaultTimeout()` in a preload is file-scoped (first file only); bunfig `[test] timeout` is silently ignored (bun#7789). Only slow hosts push tests past 5 s, so it looks like a Windows flake (2026-10-20) | `bun test --timeout 30000` on the command line, or a per-test third argument (`0` = no limit) |
+| Zombie killer takes your DB with it | When a test times out, Bun SIGTERMs every child the test process spawned, including an embedded Postgres started in `beforeAll`; every later test in the file fails with "shutting down" and the failing set changes with host load (2026-10-23) | raise the budget for DB suites, or start the server outside the test process |
+| Path without `./` is a name filter | `bun test path/file.test.ts` matches files whose path CONTAINS that string; `bun test ./path/file.test.ts` runs exactly that file | start exact paths with `./` or `/`; `-t <regex>` filters by test name |
+| `expect(p).rejects` hangs after a Worker reply | `await expect(p).rejects…` reached from the continuation of an awaited Worker message deadlocks (oven-sh/bun#37189, still on 1.4.3) | `const err = await p.then(() => undefined, (e) => e)` then assert on `err` |
+| `mock.module()` reaches every importer | mocking a re-exporting entry replaces the function for modules importing it by relative path too; one file's `mock.module` of a shared logger breaks another file's `spyOn` in the same run (2026-10-26/27) | copy the real namespace first (`{ ...(await import(x)) }`), keep such tests in their own process (`bun test ./x.isolated.test.ts`) or run `--isolate` |
+| Preload patch of a builtin is invisible | a preload's `require("node:os").x = …` reaches product `import * as os` only if nothing ESM-imported that builtin before the patch; Bun snapshots the namespace at first ESM import and `module.syncBuiltinESMExports()` does not help (2026-10-29) | patch before any ESM import of the builtin, or use the product's env seam |
+| Respawned `"bun"` is not this Bun | PATH can resolve to a mise shim or a stray older `bun` in a global `.bin`; the test's `calls.log` ENOENT hid a `--version` exit 1 (2026-09-28, 10-29) | spawn `process.execPath`; surface the child's stderr when a stub log is missing |
+| Env-less child misses runtime env | `Bun.spawn` without `env` gives the child the STARTUP environment | `env: process.env` — see [session-recipes](session-recipes.md) |
+| Timed-out test keeps running | the per-test timeout marks the test failed but its body keeps executing; a body awaiting a never-settling promise is not ended at all, and `onTestFinished` runs while it is still awaiting (2026-10-12/16) | own async work in a hook registered before fixture removal; wrap a never-settles RED in an outer `timeout -k 5 <s>` |
+| Shared-helper hooks bind once | an `afterEach`/`afterAll` at module scope of a helper several files import binds only to the FIRST importer; 16 files skipped cleanup and left 106 temp dirs (2026-10-10) | register per call with `onTestFinished(() => …)` inside the helper |
+| `bun run --cwd pkg test file` runs everything | bun appends your positional AFTER the script's own (`vitest run test/ file`), so the whole suite runs (2026-09-21); `bun test` on a vitest-based package hung 12 h (2026-10-27) | invoke the package's runner directly for one file; check which runner a package uses before `bun test` |
+| Root `pathIgnorePatterns` hides a package | a root bunfig pattern silently excluded a workspace's suite; the run was green with 0 of its files (2026-09-27) | run the package's own script or explicit paths and verify the discovered file count |
+| Duplicate package.json key | every child prints `Duplicate key` on stderr, failing stderr-asserting tests (2026-10-24) | fix the JSON |
+
+Flake tools: `bun test --rerun-each 20 ./x.test.ts` runs a file N times in one process (order/leak bugs); `--randomize --seed N` reproduces order-dependent failures; `--only-failures` re-runs what failed last time; `test.failing("name", fn)` inverts a known-red test so it alerts when it starts passing; `--bail` stops at the first failure (also stops every `--parallel` worker).
+
+## --parallel: worker processes [v1.3.13, improved v1.4.0]
+
+Blog: [#bun-test-parallel](https://bun.com/blog/bun-v1.4#bun-test-parallel)
+
+```bash
+bun test --parallel          # N = CPU count
+bun test --parallel=4
+```
+
+- Files go to whichever worker frees up next. Coverage and JUnit output merged across workers; `--bail` stops every worker.
+- `--parallel` implies `--isolate`; `--no-isolate` opts out.
+- Workers expose 1-indexed `JEST_WORKER_ID` / `BUN_TEST_WORKER_ID`, so Jest setups keying DBs/ports off worker id work unchanged.
+- Preload scripts with top-level `await` complete before any worker runs tests.
+
+## --isolate: fresh global per file [v1.3.13, hardened v1.4.0]
+
+Blog: [#bun-test-isolate](https://bun.com/blog/bun-v1.4#bun-test-isolate)
+
+```bash
+bun test --isolate
+```
+
+Between files, Bun creates a new `globalThis`, clears ESM/CJS module registries, closes leaked servers/sockets/watchers/subprocesses, cancels timers, restores fake timers, and re-runs `--preload`. Transpiled source/bytecode stay cached process-wide, so only top-level code re-runs. This is how Jest/Vitest behave by default — use it to kill "passes alone, fails in the full suite" bugs. v1.4.0 fixed the 1.3.13 stability issues (fake-timer leaks, module-scope subprocess leaks, `process.chdir` bleed, N-API across files, debugger breakpoints); v1.4.1 stopped files that call `mock()`, `spyOn()`, `mock.module()` or `Bun.plugin()` from keeping their module graph alive (80 mocked files: 1591 MB → 215 MB) and stopped `TZ`, proxy and TLS settings from leaking into later files.
+
+## --shard: split across CI machines [v1.3.13]
+
+Blog: [#bun-test-shard](https://bun.com/blog/bun-v1.4#bun-test-shard)
+
+```bash
+bun test --shard=1/3   # deterministic, round-robin, 1-based (matches Jest/Vitest/Playwright)
+```
+
+Works with `--changed` and `--randomize`; an empty shard exits 0.
+
+## --timings: balance by wall time [v1.4.0]
+
+Blog: [#bun-test-timings](https://bun.com/blog/bun-v1.4#bun-test-timings)
+
+```bash
+bun test --timings=timings.json --update-timings   # record per-file durations
+bun test --shard=1/3 --timings=timings.json        # shards cut by equal time, not file count
+bun test --parallel --timings=timings.json         # workers start slowest file first (LPT scheduling)
+```
+
+The timings file is written slowest-first, so it doubles as a slow-test report. Files sharing imports stay together (warm module cache).
+
+## --changed: only affected tests [v1.3.13]
+
+Blog: [#bun-test-changed](https://bun.com/blog/bun-v1.4#bun-test-changed)
+
+```bash
+bun test --changed             # uncommitted (unstaged + staged + untracked)
+bun test --changed=main        # diff against branch/commit/tag
+bun test --changed --watch     # re-filters on every restart
+```
+
+Bun scans test imports, asks git what changed, walks the import graph backwards. tsconfig `paths` aliases (`@/*`) work. Vitest-compatible flag.
+
+## --retry and repeats [v1.3.3]
+
+Blog: [#bun-test-retry](https://bun.com/blog/bun-v1.4#bun-test-retry)
+
+```ts
+test("flaky network call", async () => { await fetch("https://example.com"); }, { retry: 5 });
+test("stress", () => { if (Math.random() < 0.1) throw new Error("uh oh!"); }, { repeats: 20 });
+```
+
+`bun test --retry <N>` sets a suite-wide default. NOTE: prefer fixing the flake (`--rerun-each`, `--randomize --seed`, `--isolate` find it); retry is a containment tool.
+
+## jest.useFakeTimers() [v1.3.4, improved v1.4.0]
+
+Blog: [#jest-usefaketimers](https://bun.com/blog/bun-v1.4#jest-usefaketimers)
+
+```ts
+import { jest, test, expect } from "bun:test";
+test("debounce", () => {
+  jest.useFakeTimers();
+  let called = 0;
+  setTimeout(() => called++, 1000);
+  jest.advanceTimersByTime(1000);
+  expect(called).toBe(1);
+  jest.useRealTimers();
+});
+```
+
+- Controls `setTimeout`, `setInterval`, `Date`. `jest.setSystemTime()` works with `advanceTimersByTime()`.
+- `@testing-library/react`'s `waitFor` detects fake timers and advances instead of sleeping. `Bun.cron` schedules can be driven by the fake clock.
+
+## Also in bun:test
+
+- `expectTypeOf<T>()` type assertions (Vitest-compatible); `test.if/skipIf/todoIf(cond)`, `test.each([...])`, `describe.each`; `onTestFinished(fn)` runs after all `afterEach` hooks (serial tests only).
+- `bun test --inspect` / `--inspect-brk` attaches the debugger to the runner; `--reporter=junit --reporter-outfile=x.xml`; inside GitHub Actions, failures are emitted as annotations automatically.
+- `--coverage-reporter=lcov` implies `--coverage` [v1.4.3]. v1.4.4 stopped counting skipped branches (`||`/`??`/`?.` right sides, code after an `await` that never resumed) and implicit constructors as covered — `% Lines`/`% Funcs` can drop after upgrading, so re-check `coverageThreshold`.
+- `--update-snapshots` keeps the old file when a run ends early (`--bail`) [v1.4.4].
+
+## Behavior changes in 1.4.x (test-related)
+
+- `jest.resetAllMocks()` now drops implementations too (matches Jest); use `clearAllMocks()` for history-only.
+- `expect().toContain()` compares with `===` not `Object.is` (`[NaN]` no longer contains `NaN`).
+- `toEqual()` compares `Temporal` objects by value.
+- Coverage percentages are stricter in v1.4.4 (above).

package/src/tool/detached-cell-manager.ts

@@ -38,12 +38,52 @@ export type {
 export class EvalCellNotFoundError extends Error {
 	readonly code = "eval_cell_not_found";
 
-	constructor(cellId: string) {
-		super(`Unknown detached eval cell "${cellId}"`);
+	constructor(cellId: string, suggestion?: string) {
+		super(
+			suggestion === undefined
+				? `Unknown detached eval cell "${cellId}"`
+				: `Unknown detached eval cell "${cellId}"; did you mean "${suggestion}"?`,
+		);
 		this.name = "EvalCellNotFoundError";
 	}
 }
 
+function editDistance(a: string, b: string): number {
+	let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+	for (let i = 1; i <= a.length; i++) {
+		const current = [i];
+		for (let j = 1; j <= b.length; j++) {
+			const substitution = (previous[j - 1] ?? 0) + (a[i - 1] === b[j - 1] ? 0 : 1);
+			current.push(Math.min((previous[j] ?? 0) + 1, (current[j - 1] ?? 0) + 1, substitution));
+		}
+		previous = current;
+	}
+	return previous[b.length] ?? 0;
+}
+
+/**
+ * The one known id within a quarter of the mistyped id's length (at least 1 edit), or undefined when
+ * none is that close or two or more tie for closest, so a suggestion never picks between candidates.
+ */
+function closestCellId(cellId: string, known: Iterable<string>): string | undefined {
+	const limit = Math.max(1, Math.floor(cellId.length / 4));
+	let best: string | undefined;
+	let bestDistance = Number.POSITIVE_INFINITY;
+	let tied = false;
+	for (const candidate of known) {
+		const distance = editDistance(cellId, candidate);
+		if (distance > limit) continue;
+		if (distance < bestDistance) {
+			best = candidate;
+			bestDistance = distance;
+			tied = false;
+		} else if (distance === bestDistance) {
+			tied = true;
+		}
+	}
+	return tied ? undefined : best;
+}
+
 export class EvalDetachedCellManager {
 	readonly #onStatusChange: ((entries: readonly EvalDetachedCellStatusEntry[]) => void) | undefined;
 	readonly #onWakeSourceState: ((state: WakeSourceState) => void) | undefined;
@@ -317,7 +357,14 @@ export class EvalDetachedCellManager {
 
 	#terminal(cellId: string): EvalDetachedCellSnapshot {
 		const snapshot = this.#terminalSnapshots.get(cellId);
-		if (snapshot === undefined) throw new EvalCellNotFoundError(cellId);
+		if (snapshot === undefined) {
+			const known = new Set([
+				...this.#cells.keys(),
+				...this.#interrupting.keys(),
+				...this.#terminalSnapshots.list().map((entry) => entry.cellId),
+			]);
+			throw new EvalCellNotFoundError(cellId, closestCellId(cellId, known));
+		}
 		return snapshot;
 	}
 }

package/src/tool/eval-argument-validator.ts

@@ -0,0 +1,59 @@
+import { type JsonObject, registerToolArgumentValidator, validateToolArguments } from "@earendil-works/pi-ai";
+import type { TSchema } from "typebox";
+import { type EvalRunField, evalRunFieldRequiredMessage, normalizeEvalSummary } from "./eval-request.ts";
+import type { EvalLanguage } from "./types.ts";
+
+type EvalArgumentValidator = Parameters<typeof registerToolArgumentValidator>[1];
+type EvalArgumentError = NonNullable<EvalArgumentValidator["errors"]>[number];
+
+const RUN_FIELDS: readonly EvalRunField[] = ["language", "code", "summary"];
+
+/**
+ * Owns eval argument validation (senpi#5138). A run call (action omitted or "run") missing a run field fails with
+ * one teaching error per missing field, before the generic anyOf validation whose per-branch dump a model cannot act
+ * on. Every other call goes through the generic validation and coercion unchanged: a failure there rethrows the generic
+ * path's own error, so its message (and the `Received arguments` block) is byte-for-byte what an unregistered schema gets.
+ */
+export function registerEvalArgumentValidator(schema: TSchema, languages: readonly EvalLanguage[]): void {
+	// The same schema under another identity, so the generic path validates it instead of calling back here.
+	const generic: TSchema = Object.create(Object.getPrototypeOf(schema), Object.getOwnPropertyDescriptors(schema));
+	const validate: EvalArgumentValidator = (value) => {
+		const missing = missingRunFieldErrors(value, languages);
+		if (missing.length > 0) {
+			validate.errors = missing;
+			return false;
+		}
+		// Throws the generic validation error unchanged when the call is invalid for any other reason.
+		const coerced: unknown = validateToolArguments(
+			{ name: "eval", description: "", parameters: generic },
+			{ type: "toolCall", id: "", name: "eval", arguments: value as JsonObject },
+		);
+		// A registered validator's input is what the caller returns, so the generic coercion lands in place.
+		if (isRecord(value) && isRecord(coerced)) {
+			for (const key of Object.keys(value)) delete value[key];
+			Object.assign(value, coerced);
+		}
+		validate.errors = null;
+		return true;
+	};
+	registerToolArgumentValidator(schema, validate);
+}
+
+function missingRunFieldErrors(value: unknown, languages: readonly EvalLanguage[]): EvalArgumentError[] {
+	if (!isRecord(value) || (value.action !== undefined && value.action !== "run")) return [];
+	return RUN_FIELDS.filter((field) => isMissing(field, value[field])).map((field) => ({
+		instancePath: "",
+		keyword: "required",
+		message: evalRunFieldRequiredMessage(field, languages),
+		params: { missingProperty: field },
+	}));
+}
+
+function isMissing(field: EvalRunField, value: unknown): boolean {
+	if (value === undefined || value === null) return true;
+	return field === "summary" && typeof value === "string" && normalizeEvalSummary(value) === undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/tool/eval-request.ts

@@ -40,16 +40,12 @@ export function parseEvalRequest(
 	}
 	if (params.action !== undefined && params.action !== "run")
 		throw new TypeError(`Unknown eval action "${String(params.action)}"`);
-	if (params.language === undefined) throw new TypeError(evalRunRequiresLanguageMessage(enabledLanguages));
+	if (params.language === undefined) throw new TypeError(evalRunFieldRequiredMessage("language", enabledLanguages));
 	if (!isEvalLanguage(params.language))
 		throw new TypeError(`eval run language must be one of: ${enabledLanguages.join(", ")}`);
-	if (typeof params.code !== "string")
-		throw new TypeError("eval run requires code: the cell body to execute, verbatim");
+	if (typeof params.code !== "string") throw new TypeError(evalRunFieldRequiredMessage("code", enabledLanguages));
 	const summary = normalizeEvalSummary(params.summary);
-	if (summary === undefined)
-		throw new TypeError(
-			"eval run requires summary (one line in the user's language): what you are working on and for what purpose",
-		);
+	if (summary === undefined) throw new TypeError(evalRunFieldRequiredMessage("summary", enabledLanguages));
 	if (params.on_timeout !== undefined && params.on_timeout !== "detach" && params.on_timeout !== "error")
 		throw new TypeError(`Unknown eval on_timeout value "${String(params.on_timeout)}"`);
 	if (params.isolate !== undefined && params.isolate !== false) {
@@ -90,6 +86,16 @@ function isEvalLanguage(value: unknown): value is EvalToolInput["language"] {
 	return value === "py" || value === "js" || value === "rb" || value === "jl";
 }
 
-function evalRunRequiresLanguageMessage(languages: readonly EvalLanguage[]): string {
-	return `eval run requires language: one of ${languages.map((language) => `"${language}"`).join(", ")}`;
+export type EvalRunField = "language" | "code" | "summary";
+
+/** The teaching error for a run call missing one of its fields, shared by argument validation and execution. */
+export function evalRunFieldRequiredMessage(field: EvalRunField, languages: readonly EvalLanguage[]): string {
+	switch (field) {
+		case "language":
+			return `eval run requires language: one of ${languages.map((language) => `"${language}"`).join(", ")}`;
+		case "code":
+			return "eval run requires code: the cell body to execute, verbatim";
+		case "summary":
+			return "eval run requires summary (one line in the user's language): what you are working on and for what purpose";
+	}
 }

package/src/tool/eval-tool-options.ts

@@ -67,7 +67,7 @@ export interface CreateEvalToolOptions {
 	readonly hostLine?: string;
 	/** Display identity of each language's runtime, shown in headers and details; `js` also selects the prompt's runtime line. */
 	readonly runtimes?: EvalRuntimes;
-	/** Absolute path of the active bun-1-4 skill; the prompt names it as MUST READ on a bun kernel. */
+	/** Absolute path of the active bun skill; the prompt names it as MUST READ on a bun kernel. */
 	readonly bunSkillPath?: string;
 	/** Kernel globals of the tools active when a cell is submitted; read once per cell. */
 	readonly kernelPreludes?: () => readonly KernelPreludeContribution[];

package/src/tool/eval-tool.ts

@@ -8,6 +8,7 @@ import {
 } from "../config/settings.ts";
 import { buildEvalPrompt } from "../prompt/eval-prompt.ts";
 import { EvalDetachedCellManager } from "./detached-cell-manager.ts";
+import { registerEvalArgumentValidator } from "./eval-argument-validator.ts";
 import { executeEvalControl } from "./detached-eval-result.ts";
 import {
 	EvalIsolateInvalidError,
@@ -66,6 +67,7 @@ export function createEvalTool(options: CreateEvalToolOptions) {
 		...(options.promptKernelPreludes === undefined ? {} : { kernelPreludes: options.promptKernelPreludes }),
 	});
 	const languages = enabledLanguageList(options.enabledLanguages);
+	registerEvalArgumentValidator(parameters, languages);
 	const cellManager =
 		options.cellManager ??
 		new EvalDetachedCellManager({

package/src/skill/bun-1-4/SKILL.md

@@ -1,45 +0,0 @@
----
-name: bun-1-4
-description: "Read before a js eval cell that installs a package, spawns a server or PTY, or starts a long run, and before any bun -e, script, server, CLI, test, bundle, or package-management work: this session's eval js kernel runs Bun 1.4+ (this skill is present only when it does). Bun 1.4 ships builtins that replace 15+ npm deps — check here BEFORE installing sharp, puppeteer/playwright (scraping), marked, node-cron, node-pty, concurrently, serve-static, tar, json5, fast-xml-parser, string-width. Triggers: eval js, bun, Bun.serve, bun test, bun build, bun install, bun run, image resize, headless browser, markdown render, cron, PTY."
----
-
-# Bun 1.4 — Use the Builtins First
-
-Bun 1.4 (2026) ships builtins that replace most utility npm packages. **Before adding a dependency or writing a workaround, check the capability map below — if Bun ships it, use the builtin.** This skill is loaded because this session's `eval` js kernel runs Bun >= 1.4; on other machines or pinned projects, confirm with `bun --version` ([v1.3.x]/[v1.4.0] tags in the references give exact minimums). Release post: <https://bun.com/blog/bun-v1.4>
-
-## Capability map — what you can do now
-
-| You want to... | Use | Replaces | Ref = `references/<name>.md` |
-|---|---|---|---|
-| Resize/convert/rotate images | `Bun.file(p).image().resize().webp().write()` | sharp | runtime-apis |
-| Headless browser: navigate, click, screenshot, evaluate, CDP | `new Bun.WebView()` | puppeteer, playwright (scraping) | runtime-apis |
-| Markdown → HTML / React / ANSI | `Bun.markdown.html() / .react() / .render()` | marked, react-markdown | runtime-apis |
-| Schedule cron jobs | `Bun.cron()` | node-cron | runtime-apis |
-| Drive a PTY (bash, vim, TUIs) from JS | `Bun.spawn([...], { terminal })` | node-pty | runtime-apis |
-| Run package scripts concurrently, glob-matched | `bun run --parallel "build:*"` | concurrently, npm-run-all | runtime-apis |
-| Parse JSON5 / JSONL / JSONC / XML / TOML; tarballs | `Bun.JSON5/.JSONL/.JSONC/.XML/.TOML`, `Bun.Archive` | json5, ndjson, jsonc-parser, fast-xml-parser, @iarna/toml, tar | runtime-apis |
-| ANSI-aware terminal text: width, slice, wrap | `Bun.stringWidth()`, `Bun.sliceAnsi()`, `Bun.wrapAnsi()` | string-width, slice-ansi, wrap-ansi | runtime-apis |
-| Call C libraries 3x faster, plain strings back | `bun:ffi` (`buffer_length`, `cstring`) | — | runtime-apis |
-| Serve a static dir (ETag/Range/304 handled) | `Bun.serve({ routes: { "/x/*": { dir } } })` | express.static, serve-static, sirv | http-networking |
-| HTTP/3 server; `fetch` protocol/compress/proxy | `http3: true`, `fetch(url, { protocol, compress, proxy })` | — | http-networking |
-| Tests across CPU workers / CI shards / changed files / flaky retry | `bun test --parallel --shard=1/3 --changed=main --retry` | jest/vitest infra | test |
-| Kill "passes alone, fails in suite" bugs | `bun test --isolate` | vitest default behavior | test |
-| React Compiler auto-memoization | `bun build --react-compiler` | babel-plugin-react-compiler | build |
-| Embed assets/dirs into a single-file executable | `bun build --compile --asset ./public` | pkg hacks | build |
-| Compile-time feature flags, in-memory bundling, metafile | `bun:bundle feature()`, `files:{}`, `metafile: true` | esbuild define/plugins | build |
-| Diff package versions, fix vulns, dedupe/prune, license audit | `bun pm diff`, `bun audit fix`, `bun dedupe`, `bun prune`, `bun pm licenses` | npm-diff, npm audit fix | install |
-| 7x faster CI installs (global virtual store) | `linker = "isolated"` in bunfig.toml | pnpm store | install |
-| Profile CPU/heap/bundle as grep-able Markdown | `bun --cpu-prof-md`, `--heap-prof-md`, `bun build --metafile-md` | Chrome DevTools round-trip | dev-tooling |
-| Native REPL; render Markdown in terminal | `bun repl`, `bun ./README.md` | node repl, glow | runtime-apis |
-| Run Playwright, vitest, Next.js 16, OpenTelemetry, dd-trace | they now just work | Node.js | node-compat-platforms |
-
-Free wins (no code change): 2x lower CPU, 13-48% less server memory, 2-2.5x faster startup — full numbers in [performance](references/performance.md).
-
-## Operating rules
-
-1. **Eval-first.** The `eval` js kernel runs on Bun (that is why this skill is present): call `Bun.*` APIs directly inside js cells. Reach for `bash` or a spawned `bun <file>` / `bun -e` only for CLI surfaces (`bun test`, `bun build`, `bun pm`) or work that needs a separate process.
-2. **Builtin-first.** The Replaces column above is a ban list for new dependencies, in production code, test helpers, and one-off scripts alike.
-3. **Read the matching reference before using an unfamiliar API** — signatures and caveats (e.g. `Bun.markdown` HTML is unsanitized, HTTP/3 is experimental) live there, not here.
-4. **Upgrading a project to 1.4 or debugging behavior that changed?** Read [breaking-changes](references/breaking-changes.md) first — YAML/TOML strictness, `.xml`/`.css` import semantics, `Bun.$` globbing, fetch header combining, and WebSocket close timing all changed.
-5. **TLS errors after upgrade are usually intentional** — 1.4 tightened certificate verification across `fetch`, `tls.connect`, `Bun.connect`, `RedisClient`. See [security](references/security.md) before loosening anything.
-6. **A long job outlives a tool call only as `bash({ command, run_in_background: true })`** — plain `&` dies with the call's PTY hangup (native backend), `nohup` at best leaves an untracked orphan a timeout still group-kills, and a non-persistent `monitor` kills its watched command at `timeout_ms`; start the job in a background session and only watch it.

package/src/skill/bun-1-4/references/dev-tooling.md

@@ -1,34 +0,0 @@
-# Bun 1.4 Dev Tooling & Observability
-
-Blog: [#dev-tooling](https://bun.com/blog/bun-v1.4#dev-tooling), [#observability](https://bun.com/blog/bun-v1.4#observability)
-
-## Markdown profilers — built for terminals and LLMs
-
-```bash
-bun --cpu-prof-md ./app.ts     # CPU profile as Markdown: hot functions by self time,
-                               # call tree, who-calls-whom. grep it, paste into a bug or an LLM.
-bun --heap-prof-md ./app.ts    # heap profile as Markdown: total size, types by retained size,
-                               # largest objects, retention chains. Includes grep recipes in the header.
-bun build ./src/index.ts --outdir ./dist --metafile-md=./dist/meta.md   # bundle-size analysis as Markdown
-```
-
-- `bun --cpu-prof` / `--heap-prof` still write `.cpuprofile` / V8-compatible `.heapsnapshot` for Chrome DevTools / VS Code.
-- `BUN_CPU_PROFILE=1` turns on the CPU profiler for a process you cannot pass flags to (e.g. a framework-spawned worker).
-- **Agent workflow: when a Bun process is slow or leaking, run the `-md` variants and read the report directly — no DevTools round-trip.**
-
-## Async stack traces [v1.4.0]
-
-Errors from async native APIs (`fs.promises`, `Bun.file()`, S3, DNS, crypto, `fetch`) point at the `await` in your code, not native frames.
-
-## Process lifetime & env flags
-
-```bash
-bun --no-orphans app.ts    # exit when parent dies; SIGKILL every descendant on exit (Linux/macOS/Windows)
-bun --no-env-file app.ts   # skip automatic .env loading (or env = false in bunfig.toml) — use in prod/CI
-```
-
-## APM / tracing works now
-
-- **`node:inspector`**: a `Session` can start/stop CPU profiles while the app runs (`Profiler.start`/`Profiler.stop`).
-- **Datadog**: `dd-trace` traces requests; `@datadog/pprof` profiles continuously (required V8 C++ APIs implemented).
-- **OpenTelemetry**: `@opentelemetry/instrumentation-http` and `-fs` export spans; `shimmer` and `require-in-the-middle` can patch bundled code.

package/src/skill/bun-1-4/references/http-networking.md

@@ -1,113 +0,0 @@
-# Bun 1.4 HTTP & Networking
-
-## Serve files & folders (replaces express.static, serve-static, sirv) [v1.4.0]
-
-Docs: <https://bun.com/docs/runtime/http/routing> · Blog: [#serve-files-folders](https://bun.com/blog/bun-v1.4#serve-files-folders)
-
-```ts
-Bun.serve({
-  routes: {
-    "/static/*": { dir: "./public" },
-  },
-});
-```
-
-- Files stream with `sendfile`; `Content-Type`, `ETag`, `Last-Modified`, `304`, and `Range` handled automatically; `index.html` served for directories.
-- Path traversal is blocked: paths normalized, and on Linux files open with `openat2` + `O_RESOLVE_BENEATH` so symlinks can't escape the directory.
-
-## Range and conditional requests [v1.3.13, improved v1.4.0]
-
-Blog: [#range-and-conditional-requests](https://bun.com/blog/bun-v1.4#range-and-conditional-requests)
-
-```ts
-Bun.serve({
-  routes: { "/video.mp4": new Response(Bun.file("./video.mp4")) },
-});
-// curl -H 'Range: bytes=0-1023' → 206 Partial Content
-// curl -H 'If-None-Match: "..."' → 304 Not Modified
-```
-
-Static routes and `Bun.file()` bodies handle `Range` (206), `If-None-Match`/`If-Modified-Since` (304), `If-Match`/`If-Unmodified-Since` (412). Video seeking and resumable downloads work out of the box.
-
-## HTTP/3 in Bun.serve() — EXPERIMENTAL [v1.3.14, improved v1.4.0]
-
-Docs: <https://bun.com/docs/runtime/http/server> · Blog: [#http-3-in-bun-serve-experimental](https://bun.com/blog/bun-v1.4#http-3-in-bun-serve-experimental)
-
-```ts
-Bun.serve({
-  port: 443,
-  tls: { /* cert, key */ },
-  http3: true,      // also listen on UDP/443
-  // h1: false,     // optional: HTTP/3 only
-  fetch(req) { return new Response("hi"); },
-});
-```
-
-- HTTP/1.1 keeps working over TCP; `Alt-Svc` header advertises H3 so browsers upgrade themselves. 2.7x faster than HTTPS/1.1 on static routes.
-- **Do not ship `http3: true` to production yet**: 0-RTT resumption disabled, `server.upgrade()` returns `false` over H3, `unix:` sockets skip the H3 listener.
-
-## HTTP/2 & HTTP/3 in fetch() — EXPERIMENTAL [v1.3.14, improved v1.4.0]
-
-Blog: [#http-2-http-3-in-fetch-experimental](https://bun.com/blog/bun-v1.4#http-2-http-3-in-fetch-experimental)
-
-```ts
-const [a, b] = await Promise.all([
-  fetch(url1, { protocol: "http2" }),  // concurrent same-origin requests share one connection
-  fetch(url2, { protocol: "http2" }),
-]);
-const res = await fetch(url3, { protocol: "http3" });
-```
-
-- Redirects, decompression, streaming behave as over HTTP/1.1.
-- Global opt-in: `BUN_FEATURE_FLAG_EXPERIMENTAL_HTTP2_CLIENT=1` or `--experimental-http3-fetch` (Bun remembers per-origin H3 support).
-
-## fetch() request compression [v1.4.0]
-
-Blog: [#fetch-request-compression](https://bun.com/blog/bun-v1.4#fetch-request-compression)
-
-```ts
-await fetch(url, {
-  method: "POST",
-  body: largeJsonString,
-  compress: "gzip", // or true, "deflate", "br", "zstd", { encoding, level }
-});
-```
-
-Buffered bodies (string, ArrayBuffer, TypedArray, Blob) are compressed and `Content-Encoding`/`Content-Length` set automatically; streaming bodies pass through unchanged.
-
-## fetch() proxy headers [v1.3.4]
-
-Blog: [#fetch-proxy-headers](https://bun.com/blog/bun-v1.4#fetch-proxy-headers)
-
-```ts
-await fetch(url, {
-  proxy: {
-    url: "http://proxy.example.com:8080",
-    headers: { "Proxy-Authorization": "Bearer token" },
-  },
-});
-```
-
-## TLS session resumption + connection reuse [v1.3.10-v1.4.0]
-
-Blog: [#tls-session-resumption](https://bun.com/blog/bun-v1.4#tls-session-resumption), [#connection-reuse](https://bun.com/blog/bun-v1.4#connection-reuse)
-
-- Second cold connection to an origin resumes at 1 RTT (32-entry per-origin LRU of BoringSSL client sessions).
-- `fetch()` reuses connections through HTTPS proxies and for requests with custom TLS options (client cert, custom CA). No code change needed.
-
-## HTML routes: sourcemaps off in production [v1.4.0]
-
-Blog: [#html-routes-sourcemaps-disabled-in-production](https://bun.com/blog/bun-v1.4#html-routes-sourcemaps-disabled-in-production)
-
-Production `Bun.serve` no longer serves sourcemaps for HTML routes (dev mode still does). Override in `bunfig.toml`:
-
-```toml
-[serve.static]
-sourcemap = "linked"
-```
-
-## Server lifecycle changes worth knowing (v1.4)
-
-- `server.stop()` now closes idle keep-alive connections immediately, waits for in-flight responses, and resolves when the last connection closes. `server.stop(true)` force-closes stalled ones.
-- `server.publish()` / `ws.publish()` return `0` (dropped/no subscribers) or `-1` (backpressure) instead of always the byte count.
-- Per-method route objects (`{ GET }`) answer `HEAD` with the GET handler automatically.

package/src/skill/bun-1-4/references/install.md

@@ -1,93 +0,0 @@
-# bun install & package management in 1.4
-
-## Global virtual store: up to 7x faster installs [v1.3.14]
-
-Blog: [#global-virtual-store-up-to-7x-faster-installs](https://bun.com/blog/bun-v1.4#global-virtual-store-up-to-7x-faster-installs)
-
-```toml
-# bunfig.toml
-[install]
-linker = "isolated"
-```
-
-With the isolated linker, packages extract once into Bun's global cache and are symlinked into `node_modules/.bun/` (one `symlink()` per package instead of one `clonefileat()`). Warm-cache CI installs of 1,400 packages: 7x faster. Opt-in for existing projects; **new monorepos default to isolated** (see below).
-
-## New subcommands [v1.4.0]
-
-Blog anchors: [#bun-pm-diff](https://bun.com/blog/bun-v1.4#bun-pm-diff), [#bun-audit-fix](https://bun.com/blog/bun-v1.4#bun-audit-fix), [#bun-dedupe](https://bun.com/blog/bun-v1.4#bun-dedupe), [#bun-prune](https://bun.com/blog/bun-v1.4#bun-prune), [#bun-pm-licenses](https://bun.com/blog/bun-v1.4#bun-pm-licenses)
-
-```bash
-bun pm diff react                    # lockfile version → latest; un-minifies before diffing;
-bun pm diff react@18.2.0 19.0.0      # summary flags new install scripts + new child_process/fs/net/vm imports
-bun pm diff ./vendored-pkg pkg@2.1.0
-
-bun audit fix                        # upgrade vulnerable packages to safe versions; --latest allows majors; --dry-run
-bun dedupe                           # collapse duplicate versions in bun.lock; --check fails CI on dupes
-bun prune --production               # delete node_modules entries not in bun.lock; --production drops devDeps
-bun pm licenses --prod --json        # dependency license inventory
-```
-
-Docker pattern: build with devDeps, ship without:
-
-```dockerfile
-RUN bun install --frozen-lockfile
-COPY . .
-RUN bun run build
-RUN bun prune --production
-```
-
-## bun update: transitive + patterns [v1.4.0]
-
-Blog: [#bun-update-updates-transitive-dependencies](https://bun.com/blog/bun-v1.4#bun-update-updates-transitive-dependencies)
-
-```bash
-bun update                    # now updates deps-of-deps too
-bun update zod                # updates zod everywhere it appears
-bun update '@types/*' --latest
-```
-
-`bun update <name>` errors (exit 1) if nothing depends on it (no longer silently adds).
-
-## Monorepo: --filter and --catalog [v1.4.0]
-
-Blog: [#bun-add-filter](https://bun.com/blog/bun-v1.4#bun-add-filter), [#bun-add-catalog](https://bun.com/blog/bun-v1.4#bun-add-catalog)
-
-```bash
-bun add zod --filter api          # add to one workspace from the repo root
-bun run --filter 'web...' build   # web + its dependencies; '...web' = its dependents
-bun add react --catalog           # add to root catalog, write "catalog:" in the workspace
-```
-
-Plain `bun add x` in a workspace whose default catalog lists `x` writes `catalog:` automatically.
-
-## Nested overrides [v1.4.0]
-
-Blog: [#nested-overrides](https://bun.com/blog/bun-v1.4#nested-overrides)
-
-```json
-{
-  "overrides": {
-    "express": { "qs": "6.13.0" },
-    "lodash@<4.17.21": "4.17.21"
-  }
-}
-```
-
-npm nested form, yarn `a/b`, pnpm `a>b` all work; overrides can be version-scoped. Lockfiles using these become `lockfileVersion: 3` (older Bun can't read them).
-
-## Supply-chain hardening
-
-- **Lockfile integrity** [v1.3.10]: `bun.lock` records SHA-512 for GitHub and tarball deps, like npm packages.
-- **`trustedDependencies` auto-trust is npm-registry-only** [v1.3.5]: a `git:`/`github:`/`file:` package named `esbuild` gets NO trust from the default list — list it yourself. Names match exactly (not by hash).
-- **`nativeDependencies`** [v1.3.2]: for packages shipping prebuilt binaries as per-platform optionalDependencies, Bun links the right binary directly instead of running postinstall. **`ignoreScripts`** skips a package's lifecycle scripts even if trusted.
-
-```json
-{ "nativeDependencies": ["esbuild"], "ignoreScripts": ["sharp"] }
-```
-
-## Defaults changed in 1.4 (see also breaking-changes.md)
-
-- New monorepos default to `linker: "isolated"` (`configVersion: 1` in bun.lock). Existing lockfiles keep hoisted. Pin `linker = "hoisted"` to opt out.
-- `bun.lock` is `lockfileVersion: 2`: out-of-registry tarballs need integrity hashes; git entries validated against path traversal. Run `bun install` to migrate.
-- A project's `bunfig.toml` now overrides `.npmrc` for the same key.
-- `bun init` writes `typescript ^7`; non-TTY `bun init` behaves as `-y`.