ripgrep 0.0.0 → 0.0.1

package/LICENSE.md

@@ -0,0 +1,52 @@
+# License
+
+## zigrep
+
+The MIT License (MIT)
+
+Copyright (c) 2026 Pooya Parsa <pooya@pi0.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+---
+
+## Third-party notices
+
+This project builds and redistributes binaries of [ripgrep](https://github.com/BurntSushi/ripgrep),
+Copyright (c) 2015 Andrew Gallant.
+
+ripgrep is dual-licensed under **The MIT License** and **The Unlicense**; you
+may use it under the terms of either. For zigrep's redistribution, we rely on
+the MIT license terms. The upstream license texts are preserved in this
+repository at:
+
+- [vendor/ripgrep/LICENSE-MIT](vendor/ripgrep/LICENSE-MIT)
+- [vendor/ripgrep/UNLICENSE](vendor/ripgrep/UNLICENSE)
+- [vendor/ripgrep/COPYING](vendor/ripgrep/COPYING)
+
+Any distribution of the `rg` binary produced by this project must include a
+copy of one of the above ripgrep license texts, per the MIT license's notice
+requirement. The Unlicense imposes no such requirement, so recipients who
+prefer it may instead rely on the Unlicense terms.
+
+ripgrep transitively depends on a number of Rust crates, each under their own
+permissive license (typically MIT or Apache-2.0). When shipping a compiled
+`rg` binary, you should also reproduce those notices; they can be generated
+from the upstream source tree with tools such as `cargo about` or
+`cargo-license`.

package/README.md

@@ -0,0 +1,79 @@
+# ripgrep-node
+
+[ripgrep](https://github.com/BurntSushi/ripgrep) in a compact and cross-platform npm package. Works with Node.js, Bun, and Deno without native binaries. Bundler-friendly, with the WASM embedded as z85+brotli.
+
+## CLI
+
+```sh
+npx ripgrep TODO src/
+```
+
+Or install globally:
+
+```sh
+npm i -g ripgrep
+rg TODO src/
+```
+
+## Programmatic API
+
+```js
+import { ripgrep } from "ripgrep";
+
+const { code } = await ripgrep(["--json", "TODO", "src"]);
+// 0 = matches found, 1 = no matches, 2 = error
+```
+
+### `ripgrep(args, options)`
+
+Runs ripgrep with the given CLI arguments and returns a `{ code }` result object. Output is written to the host's `process.stdout` / `process.stderr`.
+
+Options:
+
+- `env` — environment variables passed to the WASI instance (default: `process.env`).
+- `preopens` — WASI preopened directories mapping guest paths to host paths (default: `{ ".": process.cwd() }`). Required for ripgrep to see any files on disk.
+- `returnOnExit` — when `true`, `proc_exit` returns the exit code instead of terminating the process (default: `true`).
+- `nodeWasi` — use Node's built-in `node:wasi` instead of the bundled WASI shim (default: `false`, also enabled via `ZIGREP_NODE_WASI=1`).
+
+### `rgPath`
+
+Absolute filesystem path to a JS shim that runs ripgrep via `ripgrep`. Drop-in replacement for `rgPath` from `vscode-ripgrep` / `@vscode/ripgrep`-style consumers that spawn the binary directly:
+
+```js
+import { spawn } from "node:child_process";
+import { rgPath } from "ripgrep";
+
+spawn(rgPath, ["TODO", "src"], { stdio: "inherit" });
+```
+
+## How it works
+
+- ripgrep is cross-compiled to `wasm32-wasip1` via [`cargo zigbuild`](https://github.com/rust-cross/cargo-zigbuild), using Zig as the C compiler/linker.
+- The resulting `.wasm` is brotli-compressed and z85-encoded into `lib/_rg.wasm.mjs`, so it ships as a plain ESM module — no `.wasm` asset resolution or postinstall needed.
+- On first use, the z85 blob is decoded and decompressed, then cached to the OS temp directory (`$TMPDIR/ripgrep-wasm-<hash>.wasm`). Subsequent calls (even across processes) skip decoding entirely. The z85 string itself is wrapped in a function so V8 lazy-parses it only when needed.
+- The compiled `WebAssembly.Module` is memoized in-process — repeated `ripgrep()` calls only pay the compilation cost once. Fresh instances are still created per-call since WASI state (memory, file descriptors) is per-instance.
+- A minimal WASI preview1 shim (`lib/_wasi.mjs`, ~20 syscalls, backed by `node:fs`) instantiates the module. Works uniformly on Node, Bun, and Deno.
+- ripgrep's TTY color detection doesn't survive the WASI boundary, so `ripgrep()` auto-injects `--color=ansi` when the host stdout is a TTY and the caller hasn't picked a color mode.
+
+## Building from source
+
+Requirements:
+
+- `zig` (tested with 0.15.2)
+- `rustc` + `cargo` (tested with 1.90.0)
+- [`cargo-zigbuild`](https://github.com/rust-cross/cargo-zigbuild): `cargo install cargo-zigbuild`
+- `rustup target add wasm32-wasip1`
+
+Then:
+
+```sh
+git submodule update --init --recursive
+zig build           # → dist/rg-wasm32-wasip1.wasm
+node build.ts       # inline wasm into lib/_rg.wasm.mjs
+```
+
+Native cross-compiled binaries (macOS / Linux / Windows) are also available via `zig build native`, but they are not part of the published npm package — WASI is the only shipped flavor.
+
+## License
+
+MIT. ripgrep itself is licensed under MIT / Unlicense by its authors — see [vendor/ripgrep](vendor/ripgrep).