Skip to content

Bun is the sole JavaScript runtime

What changed

Trailblaze’s scripted-tool subsystem now requires bun as the only JavaScript runtime on PATH. Node (and the historical node + tsx and node + ts-node combinations) is no longer a supported authoring or dispatch host.

The contract was codified in PR #3503 (squash bc93cccdc), which:

  • updated extract-tool-defs.mjs (the analyzer subprocess that powers ScriptedToolDefinitionAnalyzer’s JSON Schema extraction) to use a #!/usr/bin/env bun shebang;
  • dropped every Node fallback from the JS-runtime resolvers used by the daemon’s host-subprocess dispatch, the Gradle compileTrailblazeWorkspace task, and the workspace SDK materializer;
  • updated diagnostic strings and kdoc inside the Kotlin sources to say “bun” where they previously said “node” or “node/bun”.

The host-subprocess scripted-tool runtime (runtime: subprocess on a tool’s descriptor, or any .js / .mjs / .cjs entrypoint) now spawns bun unconditionally. The in-process QuickJS runtime is unchanged.

Why this is safe to commit to

Two factors pushed the decision from “tolerate both” to “bun-only”:

  1. Trailblaze and Claude Code are both bun-first CLI tools. Trailblaze’s extract-tool-defs.mjs analyzer, the workspace SDK bundle, and the per-trailmap typed-binding emission all benefit from bun’s startup cost (single-digit milliseconds vs. Node’s ~50 ms for a comparable subprocess). For an analyzer that’s invoked once per trailmap on every daemon-aware command, the difference compounds.

  2. Anthropic acquired Bun on 2025-12-02. Bun’s long-term funding, maintenance, and roadmap-cohesion picture improved materially once it landed under a well-resourced steward. For any framework that depends on bun in its hot path — including Trailblaze and Anthropic’s own Claude Code CLI — the acquisition reduces ecosystem-tail-risk and makes the “bun is the platform” bet structurally safer.

What this PR sweeps up

PR #3503 deliberately kept its diff focused on the Kotlin and Node-runtime resolver code — the user-facing documentation was held back to avoid bloating that PR’s review surface. This devlog accompanies a doc-only sweep across:

  • docs/publishing-a-trailmap.md — npm install bootstrap commands swapped to bun install. References to publishing TO the npm registry (npm publish / bun publish for the registry side) are preserved as registry-level concerns, since the npm package format remains the universal trailmap-distribution contract.
  • docs/scripted_tools.md — “Want full Node APIs?” reworded to “Want full Node-compatible APIs?” (Bun implements the Node API surface that QuickJS doesn’t); “bun/node subprocess” simplified to “bun subprocess”.
  • docs/scripted-tools-typed-authoring.md — node on PATH (analyzer prerequisite) updated to bun; the bun install / npm install dual-option collapsed to bun.
  • sdks/typescript/README.md — “stand-alone bun or node+tsx project” collapsed to “stand-alone bun project”; the dual-option that previously showed both bun install and npm install collapsed to bun install only.

What was deliberately left alone

  • node_modules/ as a directory — bun uses the same on-disk layout.
  • package.json as a file format — bun reads it identically.
  • Mentions of node:fs, node:child_process, etc. — these are specific API identifiers Bun implements; they’re not runtime claims.
  • Devlog entries that previously said “npm install” / “node” — those are historical record. The earlier devlogs (e.g. the npm-distribution one at 2026-05-12-npm-distribution-for-trailmaps.md) reflect what was true when they were written; preserving them as-is keeps the audit trail honest.
  • docs/CLI.md — auto-generated by ./gradlew :docs:generator:run from picocli annotations. Any remaining npm / node text in CLI.md must be fixed at the annotation source; manual edits to the generated markdown are silently overwritten on the next regeneration. A separate sweep will handle the picocli side.

References

  • PR #3503 (bc93cccdc) — the squash commit that codified the bun-only contract.
  • Anthropic / Bun acquisition announcement, 2025-12-02.