feat(crust): load project Bun bundler plugins in crust build; stop compiled executables autoloading cwd bunfig

Merged
CH
2mo ago
+1123-19

Why

crust build shells out to bun build --compile, which has no plugin flag. OpenTUI Solid apps need @opentui/solid/bun-plugin (babel-preset-solid) at bundle time; without it the compiled TUI renders nothing and hangs (React and core apps already work). Real case: gyst (chenxin-yan/gyst#34).

Two more defects surfaced while verifying against a real OpenTUI project:

  • The published crust binary is a Bun standalone, and standalones execute the cwd bunfig.toml preload. From a Solid project (preload = ["@opentui/solid/preload"]) crust dies with preload not found before any crust code runs. Consumer binaries built by crust build have the same exposure.
  • Without bun on PATH, crust compiles via BUN_BE_BUN=1 <itself>. For Bun's compiled-in default target (host os/arch, non-baseline) Bun copies the running executable onto itself as the base; the build reports success and the output segfaults at start.

What

  • --bun-plugin <specifier> (repeatable) on crust build, for --runtime bun (compile) and --runtime node (bundle); --runtime deno rejects it. Each module must default-export a BunPlugin. With plugins, crust writes a temporary driver in the project root, imports the plugins there (project resolution), runs Bun.build({ plugins, compile: { target, outfile, autoloadBunfig: false } }) with the same runner as the CLI path (real bun, else BUN_BE_BUN=1 crust), surfaces diagnostics, and removes the driver. Without plugins the existing path is unchanged. Plugins propagate to every --package target.
    crust build --entry src/cli.tsx --bun-plugin @opentui/solid/bun-plugin
    
  • --no-compile-autoload-bunfig for every compiled executable, including crust's own. .env autoload is unchanged.
  • No-Bun fallback: Bun compiles its compiled-in default target (host os/arch/libc, non-baseline) by copying the running executable onto itself, so from the BUN_BE_BUN=1 crust standalone that binary segfaults on start. Since #369 dropped the -baseline names, the canonical x64 targets are that default on x64 hosts, so crust now passes Bun's -baseline alias for the host target when running via the fallback (verified byte-identical bases on Bun 1.4.2 for linux-x64, linux-x64-musl, darwin-x64, windows-x64). arm64 hosts have no alias and are refused in planBuild before any output, naming the alternatives. Bun repro for an upstream report: /tmp/crust-tui-build.cKwiO5Gr/implementation/bun-repro.
  • Node driver refuses multi-output bundles with the same message as bun build --outfile instead of silently dropping assets.
  • Docs: build guide "Bun bundler plugins" + autoload note, modules/crust.mdx flag, modules/tui.mdx "Compiling" (Solid recipe; React/core need nothing; bun install --os "*" --cpu "*" for cross-target natives), @crustjs/tui README, CONTRIBUTING (opt-in smoke). Changeset: @crustjs/crust minor.

Tests

  • Unit (co-located): flag order/planning, deno rejection, compile args carry --no-compile-autoload-bunfig, driver JSON round-trip with spaces/quotes/backslashes, file-URL resolution, invalid/missing plugin errors and driver cleanup, multi-output node refusal, -baseline alias mapping and substitution only under the fallback runner, arm64 refusal with injected hosts, x64 host plans all eight targets without bun, package propagation to every target.
  • Integration (packages/crust/tests): real CLI + project-local transform plugin + --env-file; --runtime node --bun-plugin; crust's own binary started from a cwd with an unresolvable preload; .env still autoloaded; snapshot subprocess still honours a resolvable preload.
  • PTY smoke (opt-in CRUST_TUI_SMOKE=1, Bun.spawn terminal): Solid + --bun-plugin with the preload bunfig present โ†’ reactive marker, q โ†’ exit 0; core control. Red without the plugin (Orphan text error).

Verification

Independent lane from a pristine git archive with private Bun state: bun install --frozen-lockfile, check, check:types, test (101 pass), packages/crust build, smoke. Against a real OpenTUI project with both dist/cli.js and the fresh standalone: Solid+plugin passes in pty from neutral/project/bad-bunfig cwds, Solid without the flag fails, React/core pass, standalone starts from a preload cwd; with bun removed from PATH the standalone builds cross targets, its own baseline flavor, the six-target default and --package, and the plugin driver runs via BUN_BE_BUN. Self-copy segfault reproduced for --target bun-linux-x64 from a baseline standalone.

Rebased on main after #369/#371 (musl targets, -baseline rename, Bun 1.4 floor). No-Bun matrix rerun with the fresh crust-bun-linux-x64 standalone and an empty cache: --target bun-linux-x64 builds and runs (cache gained exactly bun-linux-x64-baseline-v1.4.2), all eight default targets build, Solid via --bun-plugin passes pty-check, bun-linux-x64-musl links /lib/ld-musl-x86_64.so.1; the raw --target bun-linux-x64 self-copy still segfaults (exit 139), so the alias is what fixes it.

Not verified: arm64 hosts (refusal unit-tested with injected targets only); cross-compiled darwin/windows artifacts only magic/size-checked.