# pi-ast-grep
Pi package that makes ast-grep a first-class tool in agent sessions.
## Why
`ast-grep outline` gives agents a fast local map of code structure: between `rg` and a full LSP, syntax-aware, no index to maintain, and extensible through declarative extraction rules.
This package pins `@ast-grep/cli@0.44.1`, including the bounded outline queue, config-loaded custom-language outline rules, more bundled language extractors, and the full alpha outline surface. It prefers its package-local binary so every Mac gets the same behavior regardless of Homebrew state.
## Tools
- `ast_grep_outline` — code structure map for files/directories.
- `ast_grep_search` — structural search with `ast-grep run`.
- `ast_grep_rewrite` — structural rewrite with `ast-grep run --rewrite`; defaults to preview diff, `mode: "apply"` mutates files with `--update-all`.
- `ast_grep_scan` — run project/rule/inline-rule scans; `mode: "apply"` applies rule fixes with `--update-all`.
- `ast_grep_test` — validate YAML rules and snapshots; snapshot updates are explicit and return source-control receipts.
- `ast_grep_doctor` — verify binary resolution, minimum version, and outline support.
The mutating tools return `jj` status/diff receipts when the repo is jj-backed, then fall back to Git. Search/rewrite failures include AST-pattern hints for common regex mistakes instead of leaving the agent to flail.
## Install in Pi
Install the public repo package on each machine:
```bash
pi install git:github.com/joelhooks/pi-ast-grep@main
```
Pi clones the package and runs `npm install`, which installs the pinned `@ast-grep/cli@0.44.1` binary under the package. Then restart Pi or run `/reload` in an interactive session.
## Development
```bash
npm install
npm run check
npm run smoke
```
## Notes
- The tools call ast-grep with argv arrays, not shell strings.
- Binary resolution is deterministic and cross-platform: package-local CLI, npm platform package/PATH, then standard Homebrew paths.
- The package is our Pi-native tool surface. It borrows useful error guidance and portability ideas from [`code-yeongyu/pi-ast-grep`](https://github.com/code-yeongyu/pi-ast-grep), while keeping the broader outline/search/rewrite/scan/test workflow we actually use.
- Output is truncated to 2,000 lines or 50 KiB; full output is saved to a temp file when truncated.
- Rewrite/apply flows are intentionally sharp: preview broad codemods, use `mode: "apply"` when the pattern/rules/paths/globs are narrow enough to trust, then inspect the returned diff.