影 @kaged/natives

shadow ops for your [filesystem]

Rust N-API bindings that give Node and Bun native-speed grep, glob, AST search, fuzzy find, workspace profiling, and fs-cache operations — shipped as prebuilt platform binaries.

what it is

@kaged/natives is the native engine room of kaged. It wraps battle-tested Rust crates — grep-searcher, ignore, globset, ast-grep-core, inferno — behind a single typed N-API surface. One import, one loadNative(), and you get search primitives that run far closer to the metal than any JS reimplementation.

It was split out of the main kaged workspace because it has a different build chain (Rust + @napi-rs/cli) and a slower iteration cadence. It builds, tests, and publishes from GitHub Actions.

> 影 @kaged/natives
> grep ............... ripgrep-grade content search
> glob ............... gitignore-aware filesystem discovery
> ast ................ ast-grep find + structural rewrite
> fd ................. fuzzy path matching
> summary ........... structural source summaries
> workspace ......... bounded workspace scans
> prof .............. on-CPU work profiling + flamegraphs
> system nominal.

install

bun add @kaged/natives
# or
npm install @kaged/natives

The correct prebuilt binary is pulled in automatically for your platform. No Rust toolchain required to consume.

quick start

import { loadNative } from "@kaged/natives";

const native = loadNative();

// content search across the filesystem (ripgrep-grade)
const result = await native.grep({
  pattern: "loadNative",
  path: "./src",
  gitignore: true,
  context: 2,
});

console.log(result.totalMatches, "matches in", result.filesWithMatches, "files");

loadNative() resolves the platform binary once and caches it. It prefers a local dev build under native/, then falls back to the published per-platform package.

the surface

Every export is fully typed. loadNative() returns a NativeBindings object with the following methods.

grep — content search

// search a string / buffer in memory
native.search(content, { pattern, ignoreCase, context, mode });

// fast boolean test
native.hasMatch(content, pattern, ignoreCase, multiline);

// walk the filesystem, gitignore-aware, with optional streaming callback
await native.grep(
  { pattern, path, glob, gitignore: true, context: 2 },
  (err, match) => { /* streamed per match */ },
);

Output modes: content, count, filesWithMatches. Supports maxCount, offset, before/after context, column limits, multiline, AbortSignal, and timeoutMs.

glob — filesystem discovery

const { matches } = await native.glob({
  pattern: "**/*.ts",
  path: ".",
  gitignore: true,
  sortByMtime: true,
});

Returns entries with path, fileType, mtime, and size. Honors hidden-file rules, .gitignore, node_modules exclusion, and result caps.

ast — structural search & rewrite

// find by ast-grep pattern
const found = await native.astGrep({
  patterns: ["console.log($MSG)"],
  lang: "typescript",
  path: "./src",
  includeMeta: true,
});

// structural rewrite (dry-run by default)
const edit = await native.astEdit({
  rewrites: { "console.log($MSG)": "logger.debug($MSG)" },
  lang: "typescript",
  path: "./src",
  dryRun: true,
});

Match strictness spans cst · smart · ast · relaxed · signature · template. Replacement results carry per-change byte ranges and per-file counts.

fd — fuzzy path find

const { matches } = await native.fuzzyFind({
  query: "loadnat",
  path: ".",
  gitignore: true,
});

Returns scored path matches, directories flagged.

summary — structural source summaries

const summary = native.summarizeCode({ code, lang: "typescript" });

Returns kept / elided segments so large files can be condensed structurally rather than truncated blindly.

workspace — bounded scans

const ws = await native.listWorkspace({
  path: ".",
  maxDepth: 4,
  collectAgentsMd: true,
});

Depth-bounded directory listing with optional AGENTS.md collection.

prof — work profiling

const profile = native.getWorkProfile(30); // last 30s
// profile.folded, profile.summary, profile.svg (flamegraph)

fs-cache

native.invalidateFsScanCache();        // clear everything
native.invalidateFsScanCache("./src"); // scoped invalidation

supported platforms

| Platform | Triple | Status | |---|---|---| | Linux x64 | x86_64-unknown-linux-gnu | [LIVE] | | Linux arm64 | aarch64-unknown-linux-gnu | [LIVE] | | macOS x64 | x86_64-apple-darwin | [LIVE] | | macOS arm64 | aarch64-apple-darwin | [LIVE] |

Loading on an unsupported platform-arch throws a clear error rather than failing silently.

development

Requires the Rust toolchain (pinned via rust-toolchain.toml) and Bun.

bun install
bun run build       # release build → native/
bun run build:dev   # debug build
bun test
bun run typecheck
bun run format      # biome

The TypeScript types in src/types.ts are hand-written to mirror the #[napi] structs in crates/kaged-natives — there is no codegen step, so keep them in sync when Rust types change.

license

AGPL-3.0 © the kaged project

[kaged] · kaged.dev · sanctioned edge, sacred code