Embedder support for wrapping the Node runtime (not just selecting one)

[colinhacks]

PR #1079 lets an embedder point aube at a Node for lifecycle scripts — a version manager selecting a toolchain. It can't express an embedder that wraps Node rather than selecting one: an instrumenting runtime, a transpiling loader, a sandbox. That case needs three things the current hook doesn't carry.

• Three independent paths, not one. Today node_bin_dir becomes the PATH entry, NODE, and npm_node_execpath at once (node_bin = bin_dir.join("node")). A wrapper needs them distinct: its shim dir on PATH, NODE at the shim so $NODE child.js in a script stays wrapped, and npm_node_execpath at the real node, which node-gyp and native-addon tooling read to find Node's install prefix.
• A lifecycle-script env contribution. For a wrapper the environment is the mechanism: a NODE_OPTIONS preload is how you interpose without patching Node. There's no hook for it today.
• Every spawn path, not just the install scope. The seed_embedder_node hook only applies inside runtime::scope, so dlx/exec/run/node never see it. A selector that misses a path falls back to the ambient node; a wrapper silently runs dependencies unwrapped, which is worse than not wrapping.

The proposal is to let an embedder describe a Node invocation rather than a bin dir:

pub struct EmbedderRuntime {
    pub bin_dir: Option<PathBuf>,        // PATH entry; need not contain `node`
    pub node_program: Option<PathBuf>,   // `NODE` and the spawn program; None => bin_dir.join(node)
    pub node_execpath: Option<PathBuf>,  // `npm_node_execpath`; None => node_program
    pub version: Option<String>,         // supplied, not probed
    pub env: Vec<(OsString, OsString)>,  // applied last to every lifecycle spawn
}

Embedder side. The host resolves its own runtime, then describes how Node should be invoked — per call, or registered once so every spawn path sees it:

let runtime = EmbedderRuntime {
    bin_dir: Some(shim_dir.clone()),         // …/shim — on PATH, holds the wrapper `node`
    node_execpath: Some(real_node.clone()),  // …/node-24.4.1/bin/node — the real binary
    version: Some("24.4.1".into()),
    env: vec![("NODE_OPTIONS".into(), "--import /…/preload.mjs".into())],
    ..Default::default()                     // node_program defaults to bin_dir/node
};

// Per call, as #1079 does today.
aube::embed::install(InstallOptions { runtime: Some(runtime.clone()), ..opts }).await?;

// Or once at startup, so dlx / exec / run / node are covered too.
aube::embed::set_embedder_runtime(runtime);

Script side. A dependency's postinstall then runs with:

PATH=/…/shim:/…/node_modules/.bin:…
NODE=/…/shim/node
npm_node_execpath=/…/node-24.4.1/bin/node
NODE_OPTIONS=--import /…/preload.mjs

Each of these then does the right thing:

node build.js        # resolves through PATH to the shim, so it runs wrapped
"$NODE" build.js     # same, for a script that re-spawns explicitly
node-gyp rebuild     # builds against npm_node_execpath, the real Node

Every field is optional and unset reproduces today's behavior, so standalone aube is unchanged. The existing node_bin_dir becomes the degenerate case ({ bin_dir }). Registration is set-once and first-write-wins, the same shape as set_embedder / set_embedder_defaults, with a per-call value taking precedence, so the ambient path costs no mutable runtime global.

Nub does this today in a fork — it augments Node through a preload — and runs it in production. Happy to open a PR if the direction's welcome.

[jdx]

this is going to be a big change but I think it's necessary, I'm working on it

[jdx]

Thanks for the detailed write-up — the direction is welcome, and the decomposition (three distinct paths + an env contribution + every spawn path) held up. This is now implemented in #1086.

What landed, relative to the proposal:

• Builder instead of a bare struct. EmbedderRuntime::selector(bin_dir) (the mise-style case; reproduces node_bin_dir exactly) and EmbedderRuntime::wrapper(node_program).real_node(…).path_dir(…).version(…). Named constructors keep the cross-defaulting chain from producing an invalid combination (e.g. a PATH dir with no node in it).
• The three paths split as proposed — bin_dir on PATH, node_program as NODE + the spawn program, node_execpath as npm_node_execpath. PATH defaults to dirname(node_program) for a wrapper.
• Env merge is per-var: .env_append("NODE_OPTIONS", "--import …") space-joins after the user's resolved nodeOptions instead of clobbering it; .env_set(…) replaces. Applied last on every spawn, surviving the script jail's env_clear.
• set_embedder_runtime is set-once/first-write-wins like set_embedder, with a per-call InstallOptions.runtime taking precedence — and it's honored regardless of runtime_switching.
• version is supplied, not probed; when omitted, engines checks probe node_execpath lazily (memoized), so the shim is never spawned just to read a version.
• Every spawn path: exec/run were decoupled from process cwd and node gained a supervised-spawn variant, so embed::{run, exec, dlx, node} now exist alongside install/add, each rooted at an explicit project_dir.

We also read through nub's tree (the EngineContext seam in vendor/aube) to check the fit against what you run in production, and closed two gaps that surfaced:

• internal_node: nub hands aube's internal node spawns (pnpmfile hooks, security scanner, version probes) the real binary while scripts get the shim — node_program alone couldn't express that. New builder knob; defaults to node_program.
• Per-call runtime on the run-class entry points: nub's shim dir is a fresh nonce'd temp dir per command, which a set-once global can't express — embed::{run, exec, dlx, node} take an optional per-call EmbedderRuntime, scoped through the task-local runtime slot.

From the mapping, this should let nub drop its runtime-seam patches (env_overlay/path_prepends on ScriptSettings, the runtime_node_* tiers in runtime.rs/engines.rs): NODE→shim + npm_node_execpath→real is wrapper().real_node(), NODE_PATH/NODE_COMPILE_CACHE are env_set, and the version tier is .version(). One semantic difference worth confirming against your setup: an explicit EmbedderRuntime wins outright, rather than sitting below a switched runtime the way nub's fallback tier does — since nub resolves the same pin sources (engines/devEngines/.node-version/.nvmrc) before calling in, that should be equivalent in practice.

The other fork seams (the disk-materialize/extract hooks, the UA token, config-posture flags) are out of scope here, but happy to discuss those separately if you want to shrink the fork further.

Feedback on the API shape welcome before it merges.

This comment was generated by Claude.

[jdx]

@colinhacks if you wouldn't mind reviewing the PR I'd like you to sign off on it first

[colinhacks]

Looks good to me! I say we ship if you're happy with it and continue discussing the other seams separately 👍

[colinhacks]

Confirming the semantic difference you flagged: equivalent for nub. The NUB profile sets runtime_switching = false, so aube's runtime resolver stays inert and the switched tier is never populated — rung 1 only ever holds an explicit EmbedderRuntime. "Wins outright" and "sits above a switched runtime" coincide here, so nothing to reconcile.

One gap does block dropping path_prepends. Lifecycle PATH composes as:

entries.push(project_bin);                    // node_modules/.bin
// The switched Node runtime sits between project bins and the
// inherited PATH: ... while anything installed into `.bin` still wins.
if let Some(dir) = &settings.node_bin_dir { entries.push(dir.clone()); }

.bin winning is right for a selector — a package's own node bin should beat a version manager's pin. For a wrapper it is this thread's third bullet: a dependency that ships a node bin (or a nested .bin/node) makes the script run unwrapped, silently. path_dir cannot express "ahead of node_modules/.bin", which is where nub's path_prepends lands today (position 0, via compose_overlay_path).

Two shapes would close it: a path_prepend(dir) that lands at position 0, or wrapper()'s path dir leading while selector()'s keeps the current placement — the selector/wrapper split already encodes the distinction, so the ordering could follow it.

Related and minor: resolve() derives bin_dir from node_program.parent() with no opt-out, so "supply NODE, leave PATH alone" isn't expressible. Not blocking for us.

AI-assisted — Tool: Claude Code; model: anthropic/claude-opus-5; version: unavailable.

[jdx]

Thanks for catching this — confirmed, and PR #1188 addresses it.

Wrapper runtime directories now lead dependency and project .bin directories, while selectors retain the existing project-local-bin-first ordering. The same ordering is applied to lifecycle scripts, run, and shell-mode exec / dlx. The review follow-up also keeps the public ScriptSettings struct source-compatible by carrying the precedence bit in private scoped state.

Once merged, this should unblock nub from dropping path_prepends. The separate ability to supply NODE without changing PATH remains out of scope for this PR.

AI-assisted — Tool: Codex; model: openai/gpt-5; version: unavailable.

[jdx]

Follow-up PR #1189 now covers the remaining PATH opt-out.

It adds EmbedderRuntime::without_path(): the configured program remains NODE and is still used for direct aube spawns, while bare node commands resolve from the inherited PATH. path_dir(...) and without_path() use last-call-wins semantics, and selectors retain their selected Node program when PATH mutation is disabled.

The PR is stacked on #1188 so its diff contains only this follow-up and can be retargeted to main after #1188 merges.

AI-assisted — Tool: Codex; model: openai/gpt-5; version: unavailable.