refactor: unify builtins in one place

2026-08-08 09:58:34 +02:00
parent 08819b279c
commit 2ee9943563
454 changed files with 59110 additions and 67520 deletions
@@ -2,34 +2,27 @@

 Contributor map for Rust workspace members under `crates/`. They are implementation details behind `@oh-my-pi/pi-natives` and its embedded shell; package consumers use JavaScript entrypoints, not these crate APIs.

-The root `Cargo.toml` includes `crates/pi-*` and `crates/vendor/*` as workspace members. It also patches crates.io `brush-core` and `brush-builtins` to the vendored copies.
+The root `Cargo.toml` includes `crates/pi-*` and `crates/vendor/*` as workspace members. It also patches crates.io `brush-core` to the vendored copy.

 ## First-party crates

 | Crate           | Path                                              | Role and consumers                                                                                                                                              |
 | --------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `pi-natives`    | [`crates/pi-natives`](../crates/pi-natives)       | Top-level N-API `cdylib`. It exposes the JS-visible API and depends on `pi-ast`, `pi-iso`, `pi-shell`, `pi-voice`, `pi-walker`, and `pi-uutils-ctx`.            |
+| `pi-natives`    | [`crates/pi-natives`](../crates/pi-natives)       | Top-level N-API `cdylib`. It exposes the JS-visible API and depends on `pi-ast`, `pi-iso`, `pi-shell`, `pi-voice`, and `pi-walker`.                              |
+| `pi-builtins`   | [`crates/pi-builtins`](../crates/pi-builtins)     | Every builtin the embedded shell installs: a patched fork of brush's POSIX/bash builtins, plus one module per in-process command-line utility (`cat`, `grep`/`rg`, `sed`, `ls`, `find`, `jq`, `fd`, `diff`, `ps`, `top`, `kill`, the moreutils set, …). `src/host.rs` holds the `Utility` trait and the `Host` view of the shell (stdio, working directory, exported environment, cancellation) that the utilities run against. Ports of uutils coreutils/findutils/sed and jaq live here too; see the crate `LICENSE` for third-party notices. |
 | `pi-shell`      | [`crates/pi-shell`](../crates/pi-shell)           | Persistent embedded brush shell, command execution/minimization, process plumbing, filesystem walking, and in-process command integration used by `pi-natives`. |
 | `pi-voice`      | [`crates/pi-voice`](../crates/pi-voice)           | Cross-platform microphone/playback and Opus/WebRTC support used by the `AudioCapture`, `AudioPlayback`, and `LiveWebRtcPeer` bindings.                          |
 | `pi-ast`        | [`crates/pi-ast`](../crates/pi-ast)               | tree-sitter/ast-grep language registry, matching/editing, block analysis, and summarization support across the workspace grammar set.                           |
 | `pi-iso`        | [`crates/pi-iso`](../crates/pi-iso)               | Isolation backend implementations and diffing for APFS, Linux/Windows clone/reflink paths, overlayfs, ProjFS, and recursive copy fallback.                      |
 | `pi-walker`     | [`crates/pi-walker`](../crates/pi-walker)         | Parallel, cache-aware filesystem walker using ignore rules and globsets; shared by native grep/glob/workspace paths and shell commands.                         |
-| `pi_uu_grep`    | [`crates/pi-uu-grep`](../crates/pi-uu-grep)       | ripgrep-library-backed `grep` implementation with `pi-uutils-ctx` I/O/path routing. In-process shell builtin entrypoint: `pi_uu_grep::run`.                     |
-| `pi_uu_diff`    | [`crates/pi-uu-diff`](../crates/pi-uu-diff)       | `similar`-backed `diff` with `pi-uutils-ctx` I/O/path routing. In-process shell builtin entrypoint: `pi_uu_diff::run`.                                          |
-| `pi-uutils-ctx` | [`crates/pi-uutils-ctx`](../crates/pi-uutils-ctx) | Thread-local stdin/stdout/stderr and working-directory context for embedding vendored uutils and custom commands without changing process-global state.         |
-
-Crate package names intentionally differ for the two custom uutils-style commands: their Cargo packages are `pi_uu_grep` and `pi_uu_diff` (underscores), while their directories use hyphens.

 ## Vendored workspace crates

-| Group                 | Paths                                                                                                                        | Purpose                                                                                                                                                             |
-| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Brush                 | [`crates/vendor/brush-core`](../crates/vendor/brush-core), [`crates/vendor/brush-builtins`](../crates/vendor/brush-builtins) | Vendored shell engine and POSIX/bash builtins consumed by `pi-shell`. Their manifests retain upstream package metadata; workspace patches select these local forks. |
-| uutils commands       | `crates/vendor/uu-*`                                                                                                         | In-process coreutils-style command crates consumed selectively by `pi-shell`, including file, text, checksum, process/system, and pipeline utilities.               |
-| Shared uutils support | [`crates/vendor/uu-checksum-common`](../crates/vendor/uu-checksum-common) and other dependency crates in `vendor/`           | Supporting code required by the selected command crates; not direct N-API modules.                                                                                  |
-| jq implementation     | [`crates/vendor/jaq`](../crates/vendor/jaq)                                                                                  | In-process JSON query command used by the shell.                                                                                                                    |
+| Group | Paths | Purpose |
+| ----- | ----- | ------- |
+| Brush | [`crates/vendor/brush-core`](../crates/vendor/brush-core) | Vendored shell engine consumed by `pi-shell` and `pi-builtins`. Its manifest retains upstream package metadata; a workspace patch selects this local fork. |

-`pi-shell/Cargo.toml` is the authoritative list of commands linked into the embedded shell. A directory being a workspace member does not by itself mean that `pi-natives` exposes it as a JavaScript API.
+`pi_builtins::utility_builtins()` and `pi_builtins::process_builtins()` are the authoritative lists of the commands linked into the embedded shell; `pi-shell` decides which of them to register. A directory being a workspace member does not by itself mean that `pi-natives` exposes it as a JavaScript API.

 ## Boundary map

@@ -38,9 +31,8 @@ Crate package names intentionally differ for the two custom uutils-style command
  -> pi-natives (N-API conversion, platform bindings, task boundaries)
       -> pi-ast / pi-iso / pi-voice / pi-walker
       -> pi-shell
-            -> brush-core + brush-builtins
-            -> pi_uu_grep + pi_uu_diff + vendored uu-* + jaq
-            -> pi-uutils-ctx (per-invocation I/O and cwd)
+            -> brush-core (parser, expansion, interpreter)
+            -> pi-builtins (bash builtins + utility builtins; host.rs: per-invocation I/O and cwd)
 ```

 For the loader and JS boundary, see: