feat: first-class Bun compatibility (core, timer, logger-console, loader, include)

[ebowwa]

Summary

Makes this fork a first-class Bun-compatible Cordis implementation while preserving the Node implementation, tests, and a clean merge path against cordiverse/cordis.

Verified under Bun 1.3.14 (1.3.14+0d9b296af): cordis core, @cordisjs/plugin-timer, @cordisjs/plugin-logger-console (node and browser exports), @cordisjs/plugin-loader, @cordisjs/plugin-include. @cordisjs/plugin-hmr remains Node-only by design (requires Node ESM internals).

Full details in docs/BUN_COMPATIBILITY.md, docs/BUN_PORT_PLAN.md, docs/BUN_PORT_STATUS.md, and docs/BUN_BENCH.md.

What's included

1. Bun behavioral suite — tests/bun/ (68 tests, 13 spec files)

58 core + 7 browser-export tests run on stock Bun; 3 are gated on the oven-sh/bun#32856 PR build and skip cleanly when it isn't installed (verified). Covers every required scenario: function/object/class plugins; sync & async effects; reverse disposal order; nested plugin cleanup; provide/inject (activation, removal+reactivation, replacement); isolated contexts; all five dispatch modes; timer cleanup; JSON & YAML config loading; dynamic TypeScript plugin loading; repeated load/dispose cycles with no duplicated listeners/timers; process shutdown with complete root-fiber disposal; supervisor restart ordering; the browser export of logger-console (method routing, identity pass-through, no DOM needed, zero node: specifiers); and (on the PR build) awaited disposal before --hot reactivation with no resource duplication.

2. Bun CLI & development supervisor

• packages/core/bin.bun.js — Bun entrypoint mirroring bin.js, with graceful SIGINT/SIGTERM root-fiber disposal. Stores the root context on globalThis and disposes the previous root before booting a new one (the correct strategy for --hot's in-process re-evaluation; a no-op under --watch, where globalThis is reset per reload). When the runtime provides import.meta.hot, disposal is additionally driven by the runtime's awaited dispose phase — see item 3.
• packages/core/bin.bun.watch.js — dev reload supervisor. Measured on Bun 1.3.14, per Bun's watch-mode docs: --watch is a hard restart (globalThis fresh per reload — old root unreachable, Cordis disposers never run; no public before-reload hook) and --hot is the in-process soft reload preserving globalThis, where live state duplicates across reloads on stock Bun. The supervisor restarts a child process instead: SIGTERM → complete root disposal → respawn, using public APIs only. Restart ordering (dispose before activate) is asserted by tests.

3. Upstream integration — oven-sh/bun#32856 (import.meta.hot for bun --hot)

This fork consumes the PR as a downstream integration fixture — no Bun fork or source changes:

• PR build installed via bunx bun-pr 32856 (Aug 13, 2026 CI artifact)
• bin.bun.js registers import.meta.hot.dispose(() => disposePrevious()) when available (no-op on stock Bun/Node)
• tests/bun/hot.spec.ts proves: an async disposer (150 ms) completes before the next generation activates, timers never duplicate across 3 generations, a module the next generation no longer imports is disposed and its resources stop (the PR's removed-modules claim), a broken generation still disposes the old root and recovers on the next valid edit, and SIGINT exits 0
• Result: every Cordis case — root-fiber disposal, async cleanup, dynamic plugins, removed plugins, repeated reloads, failed evaluation — passed on the first PR build tried, on macOS arm64 and Linux CI. No bug to report upstream. When the PR ships in a release, drop the PR-binary gating and document --hot as the supported in-process dev reload
• Known --hot limitation (verified, documented): editing cordis.yml triggers no reload — config files are outside the module graph; the supervisor's fs.watch does catch config edits

4. CI matrix — .github/workflows/bun.yml

Pinned Bun 1.3.14 job (bun install → build → bun test tests/bun → Node suite), plus a best-effort bunx bun-pr 32856 install step and the bun#32856 integration suite (download failures leave those tests skipped; real failures fail CI) — alongside the untouched upstream build.yml.

5. Benchmarks & profiles — bench/ + docs/BUN_BENCH.md

• Fork vs upstream control (cordiverse/cordis@8cc9e33 in a worktree, run identically): statistically indistinguishable under Node — consistent with zero runtime-source changes
• Node vs Bun: Bun faster on every Cordis operation (~5x plugin lifecycle, ~3x timers, ~4x include boot, ~80x fresh TS module eval); timer-settle-bound workloads runtime-neutral
• Cold start: Cordis core boot parity (~23 ms); Node's TS penalty is the tsx toolchain
• Memory: no leak on either runtime over 600 load/dispose cycles
• CPU profiles: top Cordis hotspot is reflect.ts proxy machinery on both runtimes

Changes vs upstream

Additive only — 39 files, 3711 insertions, 0 deletions, zero changes to any packages/*/src:

• Root package.json: +cordis / @cordisjs/plugin-loader / @cordisjs/plugin-timer / @cordisjs/plugin-include devDeps (resolution under Bun's isolated workspace node_modules for bench and the loader's fallback import; no-op under Yarn hoisting) and +3 additive scripts (test:bun, start:bun, dev:bun)
• packages/loader/package.json stays upstream-identical — declaring plugin-include there created a plugin-loader → plugin-include → plugin-loader cycle in yakumo-tsc's build graph, so the devDep lives at the root instead
• New files only: tests/bun/**, bench/, docs/BUN_*.md, packages/core/bin.bun*.js, .github/workflows/bun.yml

No public Cordis semantics were changed. No Bun internals were accessed. No Bun-side defects were found (the two candidate findings reproduced identically on Node — documented as parity facts — and the stock-Bun --hot cleanup gap is being fixed upstream by bun#32856, which passed all Cordis cases here).

Test plan

• bun test tests/bun — 68/68 pass (248 expect calls)
• HOME=/tmp/... bun test tests/bun/hot.spec.ts — 0 pass / 3 skip / 0 fail (clean skip without the PR build)
• tests/bun/hot.spec.ts stable across 3 consecutive runs
• Node suite (vitest via yakumo) — 19 files / 163 tests pass
• Both suites re-run green at every phase boundary
• yakumo esbuild + tsc — exit 0 (re-run after every dependency-graph change)
• bun install at root — 864 packages