pi-ast-grep

pi-ast-grep is a Pi extension package that adds an ast_grep custom tool for syntax-aware structural search.

It wraps the official @ast-grep/cli binary instead of a text grep. This gives Pi a compact, read-only interface to ast-grep run and ast-grep scan across the languages supported by the ast-grep CLI.

Features

• Registers one Pi tool: ast_grep.
• Supports ad-hoc structural search with command: "run" and pattern or kind.
• Supports rule/config scanning with command: "scan" and ast-grep YAML rules or sgconfig.yml.
• Uses argument arrays, not shell command strings.
• Strips accidental leading @ from path-like inputs, matching common Pi file-reference behavior.
• Produces a concise match summary with one-based file locations.
• Truncates LLM-visible output to Pi's standard limits and writes full output to a temp file when truncated.
• Read-only in v0: no rewrite, interactive edit, or update-all mode is exposed.

Installation

From npm, once published:

pi install npm:pi-ast-grep

From a local checkout:

cd pi-ast-grep
npm install
pi -e ./src/index.ts

Or install it as a local Pi package from a parent project:

pi install ./pi-ast-grep

Tool parameters

Parameter	Mode	Description
command	both	"run" or "scan". Defaults to "run".
pattern	run	ast-grep pattern, for example console.log($A).
kind	run	AST node kind, for example call_expression. Use instead of pattern.
language	run	Optional ast-grep language, for example ts, tsx, js, python, rust, go.
paths	both	Files/directories to search. Defaults to ["."].
globs	both	Include/exclude patterns passed as repeated --globs flags.
config	both	Optional sgconfig.yml path passed as top-level --config.
rule	scan	Rule YAML file path passed as --rule.
inlineRules	scan	Inline YAML passed as --inline-rules.
selector	run	Optional --selector AST kind.
strictness	run	"cst", "smart", "ast", "relaxed", or "signature".
context	run	Context lines around each match. Mutually exclusive with before/after.
before / after	run	Lines before/after each match.
json	both	"compact" or "stream". Defaults to "compact".
maxResults	both	Maximum matches shown in the summary. Defaults to 200.
timeoutMs	both	Subprocess timeout. Defaults to 30000.
includeRaw	both	Append raw ast-grep JSON. Defaults to false.

Examples

Ask Pi to search TypeScript call sites structurally:

Use ast_grep with pattern "console.log($A)", language "ts", and paths ["src"].

Equivalent tool input:

{
  "command": "run",
  "pattern": "console.log($A)",
  "language": "ts",
  "paths": ["src"]
}

Search by AST kind:

{
  "command": "run",
  "kind": "call_expression",
  "language": "ts",
  "paths": ["src"],
  "maxResults": 50
}

Scan with a rule file:

{
  "command": "scan",
  "rule": "rules/no-console.yml",
  "paths": ["src"],
  "globs": ["*.ts", "!*.test.ts"]
}

Scan using project sgconfig.yml discovery:

{
  "command": "scan",
  "paths": ["."]
}

Blocking behavior

ast_grep is a normal Pi custom tool call:

• Pi waits for the ast-grep subprocess to finish before the tool result is finalized.
• The tool honors Pi cancellation through AbortSignal and also enforces timeoutMs.
• The extension does not register a permission gate or block other Pi tools.
• The extension is read-only; it does not apply rewrites or mutate repository files.

If you meant "blocking" as in a permission/safety gate, that is intentionally out of scope for v0. Pair this extension with a permission/sandbox package if you need enforcement around later edit/write/bash operations.

Blockers and limitations

Known blockers for v0 are tracked in docs/BLOCKERS.md.

Important limitations:

• Native binary availability depends on @ast-grep/cli installing correctly for the user's platform.
• Very large result sets may hit the subprocess capture limit, Pi truncation, or timeoutMs.
• This tool intentionally does not expose ast-grep rewrite/apply flags.
• JSON output shape is owned by ast-grep CLI and may change across ast-grep versions; this package pins @ast-grep/cli to 0.43.0.
• Language support and pattern syntax are exactly the ast-grep CLI behavior, not custom Pi behavior.

Development

npm install
npm run check
npm pack --dry-run

Smoke-test the extension in Pi:

pi -e ./src/index.ts

Then ask Pi to use ast_grep against test/fixtures or another small project.

Project structure

pi-ast-grep/
  src/
    index.ts    # Pi extension entrypoint and tool registration
    schema.ts   # TypeBox schema, input normalization, validation
    cli.ts      # ast-grep binary resolution, argv construction, process execution
    output.ts   # JSON parsing, match summary, truncation, temp output files
  test/         # Node test runner tests
  docs/         # English project notes and blockers

Security notes

The tool runs the bundled ast-grep binary with explicit argv arrays. It does not concatenate user input into a shell command. It is read-only by design, but it can still read files reachable from the Pi working directory and any paths supplied by the model.

Review third-party Pi packages before installing them. Pi extensions run with your user permissions.

License

MIT