Bun Standalone Compilation#

Decant's release binaries are produced with bun build --compile, which bundles all source code and assets into a single self-contained executable. Because Decant uses bun:sqlite, the shipped artifact must be a Bun binary — the npm launcher selects a platform-specific Bun-compiled binary at runtime rather than running under Node. 1

The Worker Entrypoint Problem#

bun build --compile does not automatically infer modules passed to new Worker(...). Any file spawned as a worker at runtime must be listed as an explicit entrypoint on the bun build command line, or it will not be embedded in the executable and will fail to resolve when called. 2

The failure mode is subtle: the compiled binary passes shallow checks like --help or --version but breaks only when the worker-backed code path runs — typically during sync or token-economics calculation. 3

Current Entrypoints#

The buildTargetArgs function assembles the full bun build invocation. The currently embedded entrypoints are:

• src/cli.ts — the main CLI entrypoint
• src/sync-worker.ts — background sync worker
• src/stats-worker.ts — token-economics / analytics worker

The command takes the form:

bun build --compile --target <bun-target> src/cli.ts src/sync-worker.ts src/stats-worker.ts --outfile <out>

When a release version is specified, --env=DECANT_BUILD_VERSION* is injected before the entrypoints so the version string is baked into the binary. 4

Distribution Contract: Three Places to Update#

When a worker is added or renamed, three parts of the distribution contract must change together 5:

1. scripts/distribution.ts — buildTargetArgs() — add or rename the entrypoint path in the args array. 6
2. test/distribution.test.ts — exact args assertion — the test hard-asserts the full argument list, so it will fail immediately on any mismatch. 7
3. scripts/dist-check.ts — native staging smoke test — exercises meaningful worker-backed output (POST /api/sync and /api/analytics/token-economics) rather than just process startup. 8

The test in distribution.test.ts is the fastest guardrail: it calls buildTargetArgs directly and asserts the exact slice ["src/cli.ts", "src/sync-worker.ts", "src/stats-worker.ts"], so forgetting to update it causes a local failure before anything is built. 9

Running the Distribution Check#

just check runs the full local smoke: builds the native binary, exercises both sync and analytics, then packs and installs the npm launcher and platform packages end-to-end. 10

The same workflow can be run directly:

# Build native binary only
bun run scripts/build-binaries.ts --target native --out-dir /tmp/decant-bin

# Build + pack + install (full staging check)
bun run scripts/dist-check.ts

See scripts/dist-check.ts for the exact build → serve → sync → analytics → pack → install sequence.

Determinism Note#

Bun does not formally guarantee deterministic --compile output across builds. The release pipeline includes a non-blocking canary that diffs pre-signing hashes across rebuilds of the same tag; it warns rather than fails until consistency is confirmed across multiple releases. 11