@watercol/pi-lens-simple

@watercol/pi-lens-simple is an unofficial simplified fork of pi-lens, focused on AST search/replace, LSP navigation/diagnostics, and lightweight post-write feedback.

This package is not an official release from the original pi-lens project. It is based on pi-lens by Apostolos Mantzaris and keeps the original MIT license attribution.

What It Does

@watercol/pi-lens-simple currently exposes a narrow tool surface:

• AST-aware search and replace with ast-grep
• LSP navigation and diagnostics
• automatic LSP diagnostic feedback after write / edit
• basic read/write bookkeeping for safer edits

It deliberately does not run the old automatic formatter/autofix pipeline, test runners, project scans, turn-end findings, widget diagnostics, Semgrep dispatch, or context-injection flows.

Install

pi install npm:@watercol/pi-lens-simple

Pi Extension Surface

Tools

• ast_grep_search
• ast_grep_replace
• lsp_navigation
• lsp_diagnostics

Commands

• /lens-toggle
• /lens-allow-edit <path>
• /lens-lsp-status

Flags

• --no-lens
• --no-lsp
• --no-read-guard

Hooks

@watercol/pi-lens-simple registers only the slim lifecycle hooks needed for the current surface:

• resources_discover
• session_start
• turn_start
• tool_call
• tool_result
• session_shutdown

AST Search and Replace

ast_grep_search and ast_grep_replace use ast-grep to match code by structure rather than text. Patterns must be valid code shapes for the target lang, with ast-grep metavariables added.

Good starting patterns:

| Language | Pattern | Use | |---|---|---| | TypeScript/JavaScript | fetchMetrics($$$ARGS) | call with any number of args | | TypeScript/JavaScript | function $NAME($$$ARGS) { $$$BODY } | function declaration | | TypeScript/JavaScript | import { $NAMES } from $PATH | named import | | Python | class $NAME | class declaration | | Python | def $NAME($$$ARGS) $$$BODY | function declaration; no colon or braces | | Python | $OBJ.$METHOD($$$ARGS) | method call | | Go | func $NAME($$$ARGS) { $$$BODY } | function declaration | | Rust | fn $NAME($$$ARGS) { $$$BODY } | function declaration |

Metavariables:

• $X matches one AST node and captures it.
• $$$ matches zero or more AST nodes without a capture.
• $$$ARGS matches zero or more AST nodes and captures the list.

Useful parameters:

• paths scopes the search to specific files/folders.
• context shows surrounding source lines.
• strictness: "relaxed" can recover from punctuation-sensitive misses.
• insideKind, hasKind, follows, and precedes synthesize an ast-grep YAML rule for structural constraints.
• rule accepts a raw ast-grep YAML rule when the full DSL is needed.
• skip paginates large result sets.

ast_grep_replace is dry-run by default. Use apply: true only after reviewing the preview.

LSP Navigation and Diagnostics

lsp_diagnostics actively checks one file, a folder, or an explicit filePaths batch:

lsp_diagnostics({ filePath: "src/file.ts" })
lsp_diagnostics({ filePaths: ["src/a.ts", "src/b.ts"], severity: "all" })

lsp_navigation provides IDE-style code intelligence:

• definition
• references
• hover
• signatureHelp
• documentSymbol
• findSymbol
• workspaceSymbol
• codeAction
• rename
• rename_file
• implementation
• prepareCallHierarchy
• incomingCalls
• outgoingCalls
• workspaceDiagnostics
• capabilities

Line and character positions are 1-based. For position-based operations, pass symbol when you know the line but not the exact column. signatureHelp only works inside a function or method call's parentheses; if it returns empty, use hover or definition instead of retrying nearby declaration positions.

Post-Write/Edit Feedback

After a write or edit tool result, pi-lens appends current LSP diagnostics for the changed file:

pi-lens LSP: src/file.ts - 2 diagnostic(s)

This path is intentionally LSP-only. It does not call the legacy dispatch pipeline, formatters, autofixers, test runners, project scans, or turn-end context injection.

Read Guard

The slim read guard keeps basic file bookkeeping:

• read records delivered line coverage.
• write marks the file as agent-authored.
• edit checks whether the target file has been read before editing.

Use /lens-allow-edit <path> to allow a single edit, or --no-read-guard to disable the guard.

MCP Server

The bundled MCP server exposes only the slim tool set:

• pilens_ast_grep_search
• pilens_ast_grep_replace
• pilens_lsp_navigation
• pilens_lsp_diagnostics

Other legacy MCP facades are not part of the current surface.

Skills

The package exposes only these skill directories:

• skills/ast-grep
• skills/write-ast-grep-rule
• skills/lsp-navigation

These skills are written for the slim AST/LSP surface and avoid removed-tool recovery paths.

Development

npm run lint          # strict type-check, includes tests
npm run build         # emit in-place JS used by vitest imports
npm test              # full vitest suite
npm run build:dist    # refresh dist for local package/MCP use; do not commit dist

Because source imports use .js specifiers while development edits happen in .ts, run npm run build before targeted Vitest runs after TypeScript changes.