@gjuoun/ast-grep

npm binary distribution of ast-grep — install ast-grep as an npm dependency, no system install, no postinstall, no runtime download. Modeled after @vscode/ripgrep (and its sibling, @gjuoun/fd).

Use it when your tool, CLI, or agent needs ast-grep (structural search/lint/rewrite for code, powered by tree-sitter) on any machine where it is not installed — lean clients, containers, CI, remote hosts. npm install is the only setup step.

Install

npm install @gjuoun/ast-grep
# or
bun add @gjuoun/ast-grep

npm automatically installs exactly one platform package matching your os/cpu (via optionalDependencies); nothing is downloaded at runtime.

Usage

Get the binary path

import { astGrepPath } from "@gjuoun/ast-grep";

console.log(astGrepPath);
// → /path/to/node_modules/@gjuoun/ast-grep-darwin-arm64/bin/ast-grep

Run ast-grep from your code

import { spawnSync } from "node:child_process";
import { astGrepPath } from "@gjuoun/ast-grep";

const result = spawnSync(astGrepPath, ["run", "-p", "console.log($$$)", "-l", "js"], {
  encoding: "utf8",
});
console.log(result.stdout); // matching code

CommonJS works too

const { astGrepPath } = require("@gjuoun/ast-grep");

API

export const astGrepPath: string;

| Export | Type | Description | |---|---|---| | astGrepPath | string | Absolute path to the ast-grep binary for the current platform (via require.resolve against the matching platform package). |

Throws Error at import time if no platform package matches the current process.platform / process.arch — the message names the expected package and the npm install -O <pkg> fix. Upstream ast-grep ships glibc (gnu) builds only on Linux — there is no musl package to fall back to on Alpine/musl hosts (unlike @gjuoun/fd).

Platform packages

| Package | os | cpu | libc | |---|---|---|---| | @gjuoun/ast-grep-darwin-arm64 | darwin | arm64 | — | | @gjuoun/ast-grep-darwin-x64 | darwin | x64 | — | | @gjuoun/ast-grep-linux-arm64 | linux | arm64 | glibc | | @gjuoun/ast-grep-linux-x64 | linux | x64 | glibc |

No musl packages: upstream ast-grep v0.45.2 publishes gnu (glibc) Linux builds only. No Windows packages: scoped out, mirroring @gjuoun/fd's Unix-only footprint (upstream does publish *-pc-windows-msvc assets — add packages for them if Windows support is ever needed).

Development

Binaries are not committed. Rebuild them from the pinned upstream release, then test:

bun scripts/fetch.ts   # download + verify against GitHub API sha256 digest + unpack
bun test               # unit + resolver tests
bun scripts/pack-check.ts

ast-grep publishes no checksums.txt manifest, so fetch.ts verifies each downloaded app-<target>.zip against the sha256 digest reported by the GitHub Releases API (GET /repos/ast-grep/ast-grep/releases/tags/<tag>, per-asset digest field) instead of a downloaded checksums file, then pins that value into versions.json.

License

MIT © Jun Guo