nucleic-brush/NUCLEIC_FORK.md

# Nucleic fork of brush

Vendored copy of [reubeno/brush](https://github.com/reubeno/brush), pinned at
tag **`brush-shell-v0.4.0`** (upstream commit `96a26d0`), consumed by the
`shell/` workspace to build **nash**, the Nucleic agent shell
([docs/NASH.md](../../docs/NASH.md)).

Every fork change is marked with a `// nash:` comment. Current patches:

| File | Change |
| --- | --- |
| `brush-shell/src/productinfo.rs` | `PRODUCT_NAME` → `nash`; display string identifies the fork |
| `brush-shell/src/args.rs` | usage/version strings rebranded |
| `brush-core/src/expansion.rs` | corpus divergence D1: added `ExpansionPiece::LiteralText` — literal unquoted text is never field-split (bash splits only expansion results) but keeps glob characters active. Parameter-expansion substitutions (`${v:-word}` etc.) convert back to splittable at the expansion boundary; `ExpanderOptions.field_split_literal_text` lets data-string callers opt in. Upstream candidate. |
| `brush-core/src/completion.rs` | `compgen -W` word list opts into `field_split_literal_text` (the -W string is data) |
| `brush-shell/tests/cases/compat/ifs.yaml` | removed `known_failure` from 3 IFS tests the D1 fix repairs |
| `brush-core/src/gate.rs` (new) + `lib.rs` | the `Gate` trait (docs/NASH.md §4.2): process-global, verdict-shaped hook; allow-all default so an unconfigured shell behaves exactly like upstream |
| `brush-core/src/commands.rs` | `SimpleCommand::execute` split into gate wrapper + `execute_inner`: `on_exec` before dispatch (Deny short-circuits), completion correlated through all three spawn-result variants |
| `brush-core/src/processes.rs` | `ChildProcess.gate_token` + `on_exit` reporting from `wait()`/`poll()` (128+signal for signal deaths) |
| `brush-shell/src/entry.rs` | `set_exit_hook` seam so nash can flush its event buffer before `process::exit` |
| `brush-core/src/gate.rs` | M2 (docs/NASH.md §5.2–5.3): `RedirectRecord`/`RedirectReadback` + `ExecStart.redirects` + `Gate::on_cmdsub` default hook |
| `brush-core/src/interp.rs` | `ExecutionParameters.nash_redirects` accumulator; `setup_redirect` records file (`>`,`>>`,`<`,`2>`,`&>`,`<>`), heredoc, and here-string redirects |
| `brush-core/src/commands.rs` | gate wrapper drains `nash_redirects` into `ExecStart` for post-run read-back |
| `brush-core/src/expansion.rs` | command-substitution arm calls `gate().on_cmdsub` with the trimmed output |

Verification (this container): brush compat suite `2067 ran: 1684 succeeded, 6
failed, 377 known to fail, 38 skipped` — the 6 failures are identical to a
pristine `brush-shell-v0.4.0` baseline run (environmental: ANSI-C quote and
`echo -e` oracle differences, syntax-error formatting, missing `hexdump`), i.e.
zero fork-caused regressions; +3 successes vs baseline are the repaired IFS
tests. nash corpus: 94/94.

Planned (M2 remainder, per docs/NASH.md §5.3): inline tees on the pipe wiring
in `interp.rs::spawn_pipeline_processes` (the `std::io::pipe()` links between
`a | b` stages) — the one data-flow channel not yet tapped. Deferred as the most
invasive change (async copier + backpressure + SIGPIPE); regular-file
redirections, heredoc/here-string, and command substitution are all captured.

Updating: diff against the upstream tag, re-vendor, re-apply `// nash:` patches
(grep for the marker), then re-run `shell/corpus/replay.py` and the brush compat
suite (`cargo test -p brush-shell --test brush-compat-tests`).