Pin Bun 1.4.0, compose the asset matrix, share the download cache

[arcaputo3]

Stack 1/N onto #13. Base is agent/idiomatic-scalajs-mill-workflows, not main.

Why

Bun 1.4.0 shipped 2026-08-20, six days before #13 pinned 1.3.14 in eleven places — and the pin was hard to move:

• bundledChecksum matched the version with an if (version == "1.3.14") literal, so any other version had no checksum.
• bunArchiveSha256 was rejected unless bunArchiveUrl was set too, contradicting its own scaladoc ("or for an unbundled Bun version"). There was no way to run a newer Bun without hand-writing a GitHub release URL.
• With bunVerifyVersion defaulting true, a developer whose system Bun was not exactly the pin got a hard failure.

What changed

Checksums. Version → asset → sha256 table holding 1.3.14 and 1.4.0. All 24 entries verified against the official SHASUMS256.txt for each release.

Asset matrix. distribution now composes bun-{os}-{arch}[-musl][-baseline].zip from (os, arch, musl, baseline) and returns Left for combinations Bun does not publish (-musl is Linux-only, -baseline is x64-only). This adds builds the plugin previously could not download at all: musl for Alpine, and -baseline for x64 CPUs without AVX2. 12 assets per version, up from 6.

musl is auto-detected from the presence of the musl dynamic loader. -baseline is opt-in via bunUseBaseline, because the JVM cannot see CPU feature flags and guessing wrong surfaces as SIGILL rather than a diagnosable error.

Unbundled versions. bunArchiveSha256 now works on its own, deriving the URL from bunVersion and the detected platform — the behavior the scaladoc already promised. A custom bunArchiveUrl still requires a checksum so a mirror stays verified.

Shared download cache. downloadedBunExecutable is a task on the trait, so a build with N Bun modules downloaded the ~35 MB archive N times into N separate task dests. Downloads are now cached under ~/.cache/mill-bun, keyed by the verified checksum — so a cache hit is proof of the right bytes, and a partial or tampered download can never be reused. Override with MILL_BUN_CACHE_DIR.

One pin. BunToolchainModule.DefaultBunVersion is the single source of truth; bunVersion and bunTypesVersion both derive from it. @types/bun publishes in lockstep with Bun, so the stale 1.3.11 pin (against a 1.3.14 Bun) can no longer drift.

Integration suite uses the managed toolchain. forkEnv set MILL_BUN_USE_SYSTEM=true, so the suite tested whatever Bun the developer had installed rather than the version the plugin pins — and broke outright the moment the pin moved ahead of the local Bun. It now defaults to the managed toolchain; the shared cache makes that affordable. Export MILL_BUN_USE_SYSTEM=true to run against a local Bun.

Verification

• Unit: 57 passing (was 51). New coverage for asset composition, rejection of impossible combinations, musl detection, cache-publish races, and a completeness check asserting every asset of every pinned version has a well-formed checksum.
• Integration: 37 passing against managed Bun 1.4.0, with exactly one cached archive shared across all fixture workspaces.

rm -rf ~/.cache/mill-bun
./mill --no-server millbun.test.testForked
./mill --no-server millbun.integration
find ~/.cache/mill-bun -type f | wc -l   # 1

Note

millbun/integration/resources/typescript-env now sets bunVerifyVersion = false. Its bun-proxy script execs whatever Bun is on PATH, so its --version reports the developer's Bun, not the pin — that fixture tests env propagation, not version pinning.

🤖 Generated with Claude Code