feat(run): cross-platform script shell via deno_task_shell

[colinhacks]

Implements pnpm's shellEmulator via deno_task_shell (MIT): nub run script bodies run through a bundled POSIX-subset shell by default on every platform, so POSIX-isms (rm -rf, &&, $VAR) work on Windows without a system sh.

• Default-on is a deliberate divergence from pnpm (defaults off).
• Opt out: shell-emulator=false → native sh/cmd; --script-shell <path> overrides to a real shell.
• The augmentation env (PATH shim, NODE_OPTIONS, npm_*) reaches both paths, so node/tsc stays transpiled. deno's KillSignal handles SIGTERM/SIGINT.
• Scope: nub run only.

Behavior change; warrants a minor release.

Closes #399

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nub	Ready	Preview, Comment	Jul 12, 2026 7:36pm

[pullfrog]

ℹ️ No critical issues — two minor observations inline.

Reviewed changes — the initial review of routing nub run package scripts through a bundled deno_task_shell POSIX-subset shell by default on every platform.

• Add the shell_emulator module — run_inherit / run_prefixed drive deno_task_shell on a current-thread tokio runtime + LocalSet (deno's executor is !Send; trailing-& uses spawn_local), with build_env_map seeding the full parent env then layering nub's overrides because deno spawns children with env_clear.
• Refactor build_script_command to a ScriptInvocation enum — Native(Command) vs Emulated { body, env, cwd }, with the augmentation environment assembled into a single ordered env_pairs list that BOTH paths consume, so a script child sees an identical environment either way.
• Add shell_emulator(project_root) config resolver — default-on, npm_config_shell_emulator env over .npmrc, both shell-emulator and shellEmulator spellings, falsey = false/0/no/off.
• Wire signal forwarding for the emulated path — SIGTERM/SIGHUP/SIGQUIT always forwarded to deno's KillSignal; SIGINT forwarded only when stdin is not a TTY (avoids double-SIGINT); Windows relies on the Job Object plus Ctrl-C forwarding.
• Add e2e tests + docs — POSIX-ism green by default, augmentation env reaches the script, POSIX arg escaping, exit-code propagation, trailing-& (proves the LocalSet), shell-emulator=false opt-out; new "Cross-platform script shell" docs section.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

ℹ️ test is listed as a covered built-in, but deno_task_shell has no test builtin — its built-ins are cp, mv, rm, mkdir, pwd, sleep, echo, cat, exit, head, export, unset, xargs, and :. A non-builtin resolves on PATH, and Windows has no test.exe, so test fails there — the exact cross-platform gap this section claims to close. Consider dropping test from the list (or swapping in a real builtin like head).

Technical details

# Docs list a non-existent `test` builtin

## Affected sites
- `site/content/docs/runner/run.mdx:220` — "Covered: the built-ins (`rm`, `cp`, `mv`, `mkdir`, `cat`, `echo`, `test`, `xargs`, `pwd`, `sleep`, …)"

## Required outcome
- The listed built-ins are all actually provided by `deno_task_shell` so the doc's cross-platform promise holds on Windows.

## Suggested approach
- Remove `test` from the list. Optionally add `head` (a real builtin) if a replacement is wanted. Source of truth: https://docs.deno.com/runtime/reference/cli/task/#built-in-commands

[pullfrog]

ℹ️ These drains use Builder::spawn + ?, so under OS thread-create pressure run_prefixed returns an error. The native prefixed path (PipeReaders) instead falls back to an inline poll(2) drain in exactly that case (the nub ci exit-101 family noted in spawn_script_prefixed). This degrades gracefully (an error, not a panic/abort), but it's a behavioral divergence between the two prefixed paths worth a note or a follow-up.

Technical details

# Emulated prefixed path lacks the native path's thread-exhaustion fallback

## Affected sites
- `crates/nub-cli/src/shell_emulator.rs:69-76` — `run_prefixed` spawns stdout/stderr drains with `Builder::spawn(...)?`
- `crates/nub-cli/src/cli.rs` (`PipeReaders::drain`) — native path interleaves both pipes on one thread via `poll(2)` when `thread::spawn` would EAGAIN

## Required outcome
- Under thread-create pressure, a workspace `-r` / `--stream` run through the emulator behaves no worse than the native path (ideally still drains rather than erroring the single package's script).

## Open questions for the human
- Is matching the native path's inline fallback worth the complexity here, or is erroring out acceptable for the emulated path? (`block_on` already occupies the current thread, so a single-thread interleave would need `poll(2)` on the two `PipeReader`s the same way `PipeReaders` does.)

[pullfrog]

ℹ️ No new issues in the delta — one minor doc observation inline.

Reviewed changes — the delta since the prior pullfrog review (6ea1309): parse-error UX, a cwd-absolutization fix, and a signal/doc/test hardening pass.

• Point parse errors at the opt-out — parse_body wraps every parser::parse failure with EMULATOR_OPT_OUT_HINT, so a user hitting a construct outside the subset (arithmetic $((…)), unbalanced quotes) is directed to shell-emulator=false instead of a bare parse error.
• Absolutize a relative project root before deno — absolute_cwd resolves a relative cwd via std::path::absolute on both the run_inherit and run_prefixed paths. deno's ShellState::new runs assert!(cwd.is_absolute()), which under panic = "abort" would hard-abort; the native Command path tolerated a relative root via current_dir, so this makes the emulator match instead of panicking. Verified against upstream deno_task_shell main.
• Document SIGHUP's non-aborting mapping — a comment clarifies that SignalKind::Other(1) is delivered to the in-flight child but doesn't trigger deno's abort path. Confirmed accurate: Other(_).causes_abort() is false upstream.
• Harden the opt-out test — the for-loop differential now also asserts the default (emulated) run exits nonzero, documenting the accepted control-flow regression rather than only checking that abc isn't printed.
• Reword the docs subset section — adds that control-flow keywords aren't a clean parse error (they read as an unknown command, e.g. for: command not found).

The delta is a clean robustness + UX pass and introduces no new issues. The two prior informational threads (the run_prefixed thread-exhaustion divergence, and the test non-builtin in the docs) are both still open — the second is re-surfaced inline below because this commit re-touched that exact line.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

ℹ️ This reword re-touches the covered-builtins line but still lists test, which deno_task_shell does not provide as a builtin — its builtins are cp, mv, rm, mkdir, pwd, sleep, echo, cat, exit, head, export, unset, xargs, and :. A non-builtin resolves on PATH, and Windows has no test.exe, so test fails there — the exact cross-platform gap this section claims to close. Drop test from the list (optionally swap in a real builtin like head). Source: https://docs.deno.com/runtime/reference/cli/task/#built-in-commands