feat(tools): ast-grep structural search/rewrite and gh CLI operations

[Steel-tech]

The external-surface tranche from docs/TOOLS.md: three tools wrapping two proven binaries, each degrading explicitly — never silently — when its binary is absent.

ast_grep / ast_edit — structural code search and rewrite (ast-grep)

• ast_grep matches a pattern against the syntax tree (metavariables like $A, $$$ARGS), rendered as file:line results on the workspace's 1-based convention, capped at 200 matches. Parallel- and replay-safe.
• ast_edit rewrites those matches, previewing the diff by default and writing only on apply: true — the catalog's preview-then-resolve folded into one tool. Previews are parallel-safe; applies are serial and run through the sandbox's shell wrapper like bash (Seatbelt-confined on macOS).
• Binary discovery at call time: ast-grep, then sg — accepted only when --version identifies ast-grep, since plain sg is the Unix shell-group utility. Absence is a clear error with an install hint.
• Registry: both join Registry::standard(); inspect-mode pen children get read-only ast_grep.

github — gh CLI operations

• Raw gh arguments as an array, no shell in between: nothing needs quoting, nothing can be injected.
• The runtime derives parallel safety from the verb: views/lists/diffs/checks/searches ride alongside anything; mutations and the open-ended api stay serial, defaults closed.
• A network-denying sandbox refuses the call outright; a missing binary errors with the install + gh auth login hint; prompts are disabled so headless runs can't wedge.
• gh acts with the user's own login on remote state — outside what workspace write-confinement governs — so it registers on top-level runs only; pen children keep to the workspace.

Validation

• Stub-binary tests cover flag construction, output rendering (ast-grep's 0-based lines → 1-based, multi-line elision), the preview/apply split, failure passthrough, and parallel-safety matrices — these run everywhere, including CI. Stub helpers carry an ETXTBSY warm-up so parallel test runs can't race a fresh script's exec.
• A real-binary roundtrip (search → preview leaves the file untouched → apply rewrites it) ran green against ast-grep 0.45.1 locally; it skips cleanly where the binary is absent, like CI. One real-behavior discovery baked in: ast-grep reports "Applied N changes" on stderr, so the apply summary reads both streams.
• Full gates: cargo fmt --all --check, cargo clippy --workspace --all-targets -- -D warnings, cargo test --workspace (repeated runs) — all green, 188 tests.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KoSjfcJPjXpkVLTS2Vxwwr

[coderabbitai]

Warning

Review limit reached

@Steel-tech, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 43 minutes

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits within each organization.

For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 78f22924-4e08-4099-8565-b4c2ecc32b55

📥 Commits

Reviewing files that changed from the base of the PR and between 3ffd17c and 6059d89.

📒 Files selected for processing (7)

• README.md
• crates/cli/src/main.rs
• crates/harness/src/pen.rs
• crates/tools/src/ast.rs
• crates/tools/src/github.rs
• crates/tools/src/lib.rs
• docs/TOOLS.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}