feat(commands): add tee as a virtual command in JavaScript and Rust

[konard]

Closes #14.

What the issue asked

How tee command is implemented? Is it possible to reproduce it in pure js?
May be we should have such a virtual command [...] Does tee command support interactive mode?

Yes to the first — and it already existed. The second answer is "no, and here is
why", documented in both READMEs rather than papered over.

Root cause

js/src/commands/$.tee.mjs was present in the tree but never registered.
registerBuiltins() in js/src/$.mjs skipped it, so every $`tee ...`
fell through to /bin/sh -l -c 'tee ...' and ran the system GNU binary. The
existing tee tests passed because they were exercising /usr/bin/tee, not this
code.

Reproduced before fixing:

$ node -e "import('./js/src/\$.mjs').then(({listCommands}) => console.log(listCommands().includes('tee')))"
false

Now $`which tee` reports tee: shell builtin, which the test suite
asserts so the command cannot silently fall back to the system binary again.

A second bug found on the way

Running the new example under Node returned "INHERIT" instead of the piped
text. That is not a tee bug — it reproduces on a clean main:

$ node -e "import('./js/src/\$.mjs').then(async ({\$}) => console.log((await \$\`echo hello | cat\`).stdout))"
inherit

The stdin option carries either input data or one of the stdio mode
keywords (inherit, ignore, pipe). Both virtual command runners treated any
string as data, so the mode keyword became the command's input. runVirtualHandler
compounded it by spreading ...options after stdin: currentInput, letting the
pipeline's own stdin option overwrite input piped from the previous stage.

Fixed with a single stdinDataFromOptions() helper in js/src/$.stream-utils.mjs
used by both runners, and by moving the options spread ahead of args/stdin.

Rust is unaffected by construction: StdinOption keeps modes and content in
separate variants, so a mode can never be read as data. Tests lock that in.

Cross-language parity

Per review feedback, tee is implemented in both supported languages, not
just JavaScript:

	JavaScript	Rust
Implementation	js/src/commands/$.tee.mjs	rust/src/commands/tee.rs
Registration	registerBuiltins() in js/src/$.mjs	try_virtual_command in lib.rs and pipeline.rs
Listed by which	✅	✅ (rust/src/commands/which.rs)
Tests	18 in js/tests/builtin-commands.test.mjs	10 unit + 14 integration

Both follow GNU coreutils 9.4: -a/--append, -i/--ignore-interrupts,
clustered short flags (-ai), -- as an option terminator, a bare - treated
as a file named -, input always copied to stdout, and a write failure reported
on stderr with exit code 1 while the remaining files are still written.

Reproduction and verification

Behaviour	Test
tee resolves to the built-in, not the system binary	tee should be a virtual command, not the system binary
Mode keyword is never command input	virtual-command-stdin.test.mjs, node-process-regressions.mjs, test_stdin_mode_is_not_virtual_command_input
Piped input beats the stdin option	piped input wins over the pipeline stdin option (bun + node + Rust)
Write failure continues, exact stderr	builtin-commands.test.mjs, builtin_commands.rs
Each README example	tee should keep a mid-pipeline stage flowing, test_readme_tee_pipeline_example

The three Node regression tests fail on a clean main and pass here, which is
what makes this a verified fix rather than an assumed one.

On interactive mode

Virtual commands receive stdin as one completed buffer: a pipeline reads each
upstream stage to the end before handing the result on. So this tee is a
pipeline stage, not a live terminal filter, and cannot echo keystrokes as you
type them. The interactive: true option applies to spawned system processes.
This is stated in both READMEs and in js/examples/tee-command.mjs instead of
being claimed as supported.

A third bug found on the way (CI)

The first push of these tests passed on Linux and timed out on Windows and
macOS. Root cause, reproduced locally rather than guessed:

bun test evaluates js/tests/test-helper.mjs once, so the
beforeEach/afterEach reset hooks it registers at module scope belong to
whichever test file imported it first. Every later file runs with no cleanup, so
a file such as js/tests/raw-function.test.mjs — which calls
disableVirtualCommands() in its own beforeEach — leaves virtual commands
disabled for the files that follow it. Bun's file order is neither alphabetical
nor identical across platforms, which is why only two runners failed.

With virtual commands disabled, $`cat` is the real binary, and a real
command run with stdin: 'inherit' never finishes: the runner pumps the parent's
stdin into a pipe and the child waits for an EOF that never arrives. Hence the
10 s timeout and exit code 143.

experiments/issue-14/stdin-inherit-blocks.mjs reproduces that hang in one
command under both runtimes. The tests now enable virtual commands themselves
and assert the stdin invariant through a purpose-built probe command that spawns
nothing, so they no longer depend on state left by unrelated files.

Note for a follow-up, out of scope here: that stdin: 'inherit' hang is
pre-existing behaviour on main under both Bun and Node, and it happens even
when the parent's stdin is /dev/null. This PR does not change it.

Also in this PR

• js/examples/tee-command.mjs replaces three ad-hoc example scripts
  (test-unix-tee.mjs, test-virtual-tee.mjs, tee-interactive-demo.mjs).
• js/README.md claimed 18 built-in commands while already enumerating 21; the
  real count with tee is 22.
• One changeset in js/.changeset/ and a fragment in rust/changelog.d/ so the
  release automation picks this up.

Local checks

bun run lint, bun run format:check, bun run check:duplication,
cargo fmt --check, cargo clippy --all-targets --all-features -D warnings,
cargo test --all-features (470 passed), node --test Node suites (9 passed),
and BASE_REF=main .github/scripts/check-language-parity.sh all pass.

bun test js/tests/ reports 1440 pass / 11 skip / 28 fail; all 28 are jq
tests that fail identically on a clean main because jq is not installed in
this sandbox. CI installs it. The full suite was also run with stdin held open
(sleep 600 | bun test js/tests/) to prove no test blocks on inherited stdin:
no timeouts.

[konard]

Double check we use all the best practices from latest version of command stream, and also implement it in all supported languages, not just JavaScript.

[konard]

🤖 AI Work Session Started

Starting automated work session at 2026-09-15T22:41:38.166Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait for the session to finish, and provide your feedback.

Runtime: solve v2.29.0 · tool claude · model opus · task image konard/hive-mind-dind:2.29.0@sha256:11a236d03854cbaea86fdd7ca06265c912cf0b67d1fcc9b3eb60bd84c43ff749

[konard]

Working session summary

PR #130 is finished and fully green.

CI on 6ff2788 — all five workflows passing:

Workflow	Result
JavaScript checks and release	success (bun on ubuntu/macos/windows, node 20/22/24, lint, changeset)
Rust checks and release	success (ubuntu/macos/windows, fmt, clippy, sizes)
Security	success
Language parity check	success
Repository quality checks	success

The Windows/macOS timeout that failed the previous push (0a5a6df) is fixed. Root cause, reproduced locally rather than inferred: bun test evaluates js/tests/test-helper.mjs once, so the reset hooks it registers at module scope bind only to the first file that imports it; js/tests/raw-function.test.mjs then leaves disableVirtualCommands() in effect for every file bun happens to run after it, and bun's file order differs per platform. With virtual commands off, $`cat` becomes the real binary, and a real process run with stdin: 'inherit' never reaches EOF — hence the 10 s timeout and exit 143. The regression tests now enable virtual commands themselves and assert the invariant through a purpose-built probe command that spawns nothing (`js/tests/virtual-command-st

Rest of the working session summary (1 KB)

din.test.mjs:39-61`, `js/tests/node-process-regressions.mjs`). `experiments/issue-14/stdin-inherit-blocks.mjs` reproduces the underlying hang in one command.

**Final state:**
- Working tree clean, nothing unpushed, `origin/main` contains nothing not already in the branch.
- Full bun suite run with stdin held open: 1440 pass / 11 skip / 28 fail, **0 timeouts** — the 28 failures are `jq` tests that fail identically on a clean `main` because `jq` isn't installed in this sandbox; CI installs it and they pass there.
- PR description updated with the third-bug (CI) section and corrected counts; PR is out of draft and `MERGEABLE`.
- No unaddressed feedback: the only two PR comments are from 22:18 and 22:41 UTC (the parity request, addressed by the Rust implementation, and the draft-mode marker); the issue has no comments.

One thing left deliberately unfixed and called out in the PR body as out of scope: `await $({stdin: 'inherit'})`/bin/cat`` never resolves under either Bun or Node, even with stdin at `/dev/null`. Verified identically on a clean `main` worktree, so it is pre-existing and not introduced here.

https://github.com/link-foundation/command-stream/pull/130

---

This summary was automatically extracted from the AI working session output.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost: $20.833266

📊 Context and tokens usage:

Claude Opus 5: (5 sub-sessions)

1. 117.2K / 1M (12%) input tokens, 20.2K / 128K (16%) output tokens
2. 114.7K / 1M (11%) input tokens, 38.0K / 128K (30%) output tokens
3. 117.0K / 1M (12%) input tokens, 33.4K / 128K (26%) output tokens
4. 115.7K / 1M (12%) input tokens, 42.5K / 128K (33%) output tokens
5. 39.6K / 1M (4%) input tokens, 4.3K / 128K (3%) output tokens

Total: (13.1K new + 435.1K cache writes + 23.9M cache reads) input tokens, 179.3K output tokens, $20.833266 cost

🤖 Models used:

• Tool: Anthropic Claude Code
• Requested: opus (claude-opus-5)
• Thinking level: high (~23999 tokens)
• Model: Claude Opus 5 (claude-opus-5)

📎 Log file uploaded as Gist (8477KB)

• View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

🎉 Auto-merged

This pull request has been automatically merged by hive-mind.

• All CI checks have passed

---

Auto-merged by hive-mind with --auto-merge flag