can1357
34e099148a
- Added `gen-npm-packages.ts` script to generate per-platform leaf packages under `npm/-/`. - Updated CI release publisher to generate and publish leaf packages before rewriting the core manifest with pinned `optionalDependencies`. - Core package now ships only JS loader and declarations; installs fetch only the host platform's `.node` binary.
81 lines
2.8 KiB
Markdown
81 lines
2.8 KiB
Markdown
# @oh-my-pi/pi-natives
|
|
|
|
Native Rust functionality via N-API.
|
|
|
|
## What's Inside
|
|
|
|
- **Grep**: Regex-based search powered by ripgrep's engine with native file walking and matching
|
|
- **Find**: Glob-based file/directory discovery with gitignore support (pure TypeScript via `globPaths`)
|
|
- **SIXEL**: Terminal image encoding for SIXEL-capable terminals (decode, resize, encode in one pass)
|
|
|
|
General-purpose image processing (decode/resize/encode for files and buffers)
|
|
lives in [`Bun.Image`](https://bun.com/docs/runtime/image) on the JS side; this
|
|
crate only ships the SIXEL encoder because no built-in equivalent exists for
|
|
that terminal protocol.
|
|
|
|
## Usage
|
|
|
|
```typescript
|
|
import { grep, find, encodeSixel } from "@oh-my-pi/pi-natives";
|
|
|
|
// Grep for a pattern
|
|
const results = await grep({
|
|
pattern: "TODO",
|
|
path: "/path/to/project",
|
|
glob: "*.ts",
|
|
context: 2,
|
|
});
|
|
|
|
// Find files
|
|
const files = await find({
|
|
pattern: "*.rs",
|
|
path: "/path/to/project",
|
|
fileType: "file",
|
|
});
|
|
|
|
// SIXEL encode for a terminal cell box (px)
|
|
const sequence = encodeSixel(pngBytes, widthPx, heightPx);
|
|
```
|
|
|
|
## Building
|
|
|
|
```bash
|
|
# Build native addon from workspace root (requires Rust)
|
|
bun run build
|
|
|
|
# Type check
|
|
bun run check
|
|
```
|
|
|
|
## Architecture
|
|
|
|
`@oh-my-pi/pi-natives` publishes a small core package plus generated
|
|
platform-specific optional dependency packages:
|
|
|
|
```
|
|
crates/pi-natives/ # Rust source (workspace member)
|
|
src/lib.rs # N-API exports
|
|
src/sixel.rs # SIXEL terminal-image encoding
|
|
Cargo.toml # Rust dependencies
|
|
native/ # Core loader files and local/CI native build outputs
|
|
index.js # Public native export surface
|
|
loader-state.js # Platform, ISA variant, and addon resolution
|
|
embedded-addon.js # Standalone binary embed stub/generated metadata
|
|
pi_natives.<platform>-<arch>-modern.node # x64 modern ISA (local/CI artifact)
|
|
pi_natives.<platform>-<arch>-baseline.node # x64 baseline ISA (local/CI artifact)
|
|
pi_natives.<platform>-<arch>.node # non-x64 build artifact
|
|
npm/<platform>-<arch>/ # Generated at publish time, not committed
|
|
package.json # @oh-my-pi/pi-natives-<platform>-<arch>
|
|
*.node # Only that platform's addon binary or x64 ISA variants
|
|
src/ # TypeScript wrappers and generated declarations source
|
|
native.ts
|
|
index.ts
|
|
```
|
|
|
|
The published core package contains only the JS loader, declarations, README,
|
|
and `package.json`. Release publishing generates one leaf package per supported
|
|
`os`/`cpu` pair and injects those leaves into the core manifest as pinned
|
|
`optionalDependencies`, so package managers install only the host platform's
|
|
native addon. x64 leaves include every built ISA variant, and the loader keeps
|
|
choosing between `baseline` and `modern` at runtime.
|