test-emu --emulator avr8js: auto npm install fails silently with ERR_MODULE_NOT_FOUND

[zackees]

Summary

fbuild test-emu --emulator avr8js is documented to auto-run npm install avr8js@0.21.0 --prefix ~/.fbuild/cache/avr8js-node on first use. In practice, on a Windows host with Node.js 24 + npm on PATH, the auto-install did not run (or ran silently and did not populate the cache). The subsequent `headless.mjs` execution failed with:

node:internal/modules/run_main:107
    triggerUncaughtException(
    ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'avr8js' imported from C:\Users\niteris\AppData\Local\Temp\.tmp2HdzES\headless.mjs
Did you mean to import \"avr8js/dist/cjs/index.js\"?
    at Object.getPackageJSONURL (node:internal/modules/package_json_reader:301:9)
    ...
Node.js v24.14.1
avr8js ATmega328P test-emu failed: failed: avr8js exited with code 1

The error surfaces from Node, not from fbuild, so there's no actionable hint that the cache-install step was supposed to have run.

Reproduction

On a Windows host with fbuild 2.1.16 and Node 24 installed but ~/.fbuild/cache/avr8js-node/ empty:

fbuild test-emu --emulator avr8js --timeout 10 --expect \"Hello\"

against a uno project → ERR_MODULE_NOT_FOUND as above.

Requested changes

1. Fail fast with a clear message when ~/.fbuild/cache/avr8js-node/node_modules/avr8js/ is missing. Print something like: "avr8js cache not populated at ; running `npm install avr8js@0.21.0`…" before invoking node.
2. Retry or auto-install on demand if the cache dir is missing at test-emu start. Currently the install seems to be tied to a different code path that didn't fire.
3. Optional: add a --refresh-emu-cache flag so CI can force reinstall, and a --no-auto-install flag so CI can fail fast if the cache wasn't pre-seeded by a separate setup step.
4. Optional: consider bundling avr8js as an offline vendored dependency in the wheel so Node is the only external requirement. Current situation: requires node AND npm AND network access AND successful install, any of which can silently fail.

Why this matters for FastLED

FastLED is migrating its AVR8JS CI from a Docker container (which pre-bundles avr8js) to fbuild test-emu. Without either fail-fast diagnostics or reliable auto-install, every CI run risks a silent cache miss. Working around it in CI with a belt-and-suspenders npm install -g avr8js@0.21.0 step is possible but defeats the point of fbuild owning the emulator lifecycle.

Environment

• fbuild 2.1.16 (via pip, PyO3-compiled Rust)
• Windows 10
• Node.js 24.14.1 + npm on PATH

Filed from an agent working on the FastLED CI migration.