oh-my-pi/docs/native-crates.md

Native Crates

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.

First-party crates

Crate	Path	Role and consumers
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-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	Cross-platform microphone/playback and Opus/WebRTC support used by the AudioCapture, AudioPlayback, and LiveWebRtcPeer bindings.
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	Isolation backend implementations and diffing for APFS, Linux/Windows clone/reflink paths, overlayfs, ProjFS, and recursive copy fallback.
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	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	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	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-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 and other dependency crates in vendor/	Supporting code required by the selected command crates; not direct N-API modules.
jq implementation	crates/vendor/jaq	In-process JSON query command used by the shell.

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.

Boundary map

@oh-my-pi/pi-natives JS entrypoints
  -> 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)

For the loader and JS boundary, see:

• natives-architecture.md
• natives-addon-loader-runtime.md
• natives-binding-contract.md

Subsystem details live in:

• natives-build-release-debugging.md
• natives-media-system-utils.md
• natives-rust-task-cancellation.md
• natives-shell-pty-process.md
• natives-text-search-pipeline.md
• fs-scan-cache-architecture.md

Documentation policy

These crates remain contributor-facing implementation details. Promote one to standalone user-facing documentation only when it gains a public API or executable consumed independently of @oh-my-pi/pi-natives; see user-facing-packages.md.