@herbertgao/pi-extensions 2026.9.1 → 2026.9.3

package/node_modules/pi-lens/dist/tools/ast-grep-outline.js

@@ -29,19 +29,8 @@ export function createAstGrepOutlineTool(astGrepClient) {
     return {
         name: "ast_grep_outline",
         label: "AST-Grep Outline",
-        description: "Syntax-only code structure (symbols, imports, exports, and members) via " +
-            "`ast-grep outline`. Fast, local, no index/LSP/cross-file semantics — useful " +
-            "for languages or structures where pi-lens's own extractor is weak, or for a " +
-            "raw second opinion.\n\n" +
-            "Prefer module_report for pi-lens-aware navigation (who-uses-this, " +
-            "complexity/fanout, recommendedReads, blast radius, callback handles). Use " +
-            "ast_grep_outline when you want the syntax tree's own view of a file or a " +
-            "whole directory.\n\n" +
-            "Returns JSON: per file, `items[]` with name/symbolType/signature/range, " +
-            "`isExported`/`isImport`, nested `members[]` (with `isPublic`), and ready " +
-            "`read` args on every entry. NOTE: structure only — an outline is NOT a read " +
-            "of a symbol's body (use read_symbol/read_enclosing for that).",
-        promptSnippet: "Syntax-only code outline via ast-grep (no index/LSP); module_report is the richer default",
+        description: "Return syntax-only symbols, imports, exports, and members with ast-grep. An outline shows structure, not a symbol body, and does not satisfy read-before-edit; use read_symbol or read_enclosing for body coverage. Example: outline `src/` before choosing a symbol to read.",
+        promptSnippet: "Inspect syntax without index or LSP",
         renderResult: compactRenderResult(({ details, isError, text }) => {
             if (isError) {
                 return `ast_grep_outline — ${text.split("\n")[0] ?? "error"}`;

package/node_modules/pi-lens/dist/tools/ast-grep-replace.js

@@ -32,17 +32,8 @@ export function createAstGrepReplaceTool(astGrepClient) {
     return {
         name: "ast_grep_replace",
         label: "AST Replace",
-        description: "Replace code using AST-aware pattern matching. IMPORTANT: Use specific AST patterns, not text. Dry-run by default (use apply=true to apply).\n\n" +
-            "✅ GOOD patterns (single AST node):\n" +
-            "  - pattern='console.log($MSG)' rewrite='logger.info($MSG)'\n" +
-            "  - pattern='var $X' rewrite='let $X'\n" +
-            "  - pattern='function $NAME() { }' rewrite='' (delete)\n\n" +
-            "❌ BAD patterns (will error):\n" +
-            "  - Raw text without code structure\n" +
-            '  - Missing parentheses: use it($TEST) not it"text"\n' +
-            "  - Incomplete code fragments\n\n" +
-            "Always use 'paths' to scope to specific files/folders. Dry-run first to preview changes.",
-        promptSnippet: "AST-aware structural find-and-replace",
+        description: 'Find and rewrite code by AST structure; preview by default. Example: `{pattern: "var $X", rewrite: "let $X", apply: false}`.',
+        promptSnippet: "Preview an AST-aware code rewrite",
         renderResult: compactRenderResult(({ details, isError, text }) => {
             if (details?.stalePreview) {
                 return `ast_grep_replace — stale preview, re-run with apply:false`;
@@ -93,6 +84,9 @@ export function createAstGrepReplaceTool(astGrepClient) {
             const lang = (params.lang ?? "").replace(/^"|"$/g, "");
             const pathsCount = paths?.length ?? 1;
             const applyFlag = apply ?? false;
+            // MCP passes Infinity so the shared result seam receives the complete
+            // tool rendering. Pi keeps the historical 50-item content contract.
+            const resultMaxItems = ctx.resultMaxItems ?? 50;
             function logOutcome(outcome, details = {}) {
                 try {
                     logAstGrepToolEvent({
@@ -193,7 +187,7 @@ export function createAstGrepReplaceTool(astGrepClient) {
                         details: {},
                     };
                 }
-                const output = astGrepClient.formatMatches(ruleResult.matches, !applyFlag, true);
+                const output = astGrepClient.formatMatches(ruleResult.matches, !applyFlag, true, resultMaxItems);
                 logOutcome(ruleResult.matches.length === 0 ? "no_matches" : "success", {
                     matchCount: ruleResult.matches.length,
                 });
@@ -230,7 +224,8 @@ export function createAstGrepReplaceTool(astGrepClient) {
                 };
             }
             const isDryRun = !applyFlag;
-            const output = astGrepClient.formatMatches(result.matches, isDryRun, true);
+            const output = astGrepClient.formatMatches(result.matches, isDryRun, true, // showModeIndicator
+            resultMaxItems);
             logOutcome(result.matches.length === 0 ? "no_matches" : "success", {
                 matchCount: result.matches.length,
                 truncated: result.truncated,

package/node_modules/pi-lens/dist/tools/ast-grep-search.js

@@ -140,9 +140,10 @@ function toMatchLocations(matches, contextLines) {
 }
 function suggestedDump(lang) {
     return {
-        tool: "ast_grep_dump",
+        tool: "ast_grep_search",
+        mode: "dump",
         lang,
-        note: "Run ast_grep_dump on a small representative source snippet (not a whole file) to inspect AST node kinds before retrying ast_grep_search.",
+        note: "Run ast_grep_search with dump=true on a small representative source snippet (not a whole file) to inspect AST node kinds before retrying the search.",
     };
 }
 function lineCount(value) {
@@ -221,28 +222,37 @@ function getPatternHint(pattern, lang, selector) {
             return 'Hint: Rust fn patterns need params and body. Try "fn $NAME($$$) { $$$ }"';
         }
     }
-    return "Hint: No matches. Retry once with a smaller valid AST pattern scoped to the same paths (for example a call like `foo($$$ARGS)`, an import statement, or `function $NAME($$$ARGS) { $$$BODY }`). If you're actually looking for a name/usage rather than a structural pattern, prefer symbol_search (ranked identifier search) or module_report (file outline) over another AST retry; lsp_navigation findReferences finds exact call sites once you have a definition. If that also fails, use grep for text search, or ast_grep_dump on a small representative snippet to inspect node kinds.";
+    return "Hint: No matches. Retry once with a smaller valid AST pattern scoped to the same paths (for example a call like `foo($$$ARGS)`, an import statement, or `function $NAME($$$ARGS) { $$$BODY }`). If you're actually looking for a name/usage rather than a structural pattern, prefer symbol_search (ranked identifier search) or module_report (file outline) over another AST retry; lsp_navigation findReferences finds exact call sites once you have a definition. If that also fails, use grep for text search, or ast_grep_search with dump=true on a small representative snippet to inspect node kinds.";
+}
+/** One-session response for callers holding a pre-fold tool name. */
+export function astGrepDumpCompatibilityResult(params, surface) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: `The ast_grep_dump tool was retired. Call ${surface === "mcp" ? "pilens_" : ""}ast_grep_search with dump=true and put the snippet in pattern instead.`,
+            },
+        ],
+        isError: true,
+        details: {
+            compatibility: "ast_grep_dump -> ast_grep_search",
+            call: {
+                tool: surface === "mcp" ? "pilens_ast_grep_search" : "ast_grep_search",
+                arguments: {
+                    dump: true,
+                    pattern: params.source,
+                    lang: params.lang,
+                },
+            },
+        },
+    };
 }
 export function createAstGrepSearchTool(astGrepClient) {
     return {
         name: "ast_grep_search",
         label: "AST Search",
-        description: "Search code using AST-aware pattern matching. IMPORTANT: Use specific AST patterns, NOT text search.\n\n" +
-            "✅ GOOD patterns (complete AST shapes; $$$ accepts zero or more nodes):\n" +
-            "  - function $NAME($$$ARGS) { $$$BODY } (function declaration)\n" +
-            "  - fetchMetrics($$$ARGS)             (call with any arguments)\n" +
-            '  - import { $$$NAMES } from "module-name" (exact string-literal import)\n' +
-            "  - console.log($MSG)                 (method call)\n\n" +
-            "❌ BAD patterns (multiple nodes / raw text):\n" +
-            '  - it"test name"                     (missing parens - use it($TEST))\n' +
-            "  - console.log without args           (incomplete code)\n" +
-            "  - arbitrary text without code structure\n\n" +
-            'Metavariables match AST nodes, not text inside quoted string literals: `from "$PATH"` matches the literal text $PATH. Use an exact quoted string for a known import, or grep for wildcard text. ' +
-            "Use 'paths' to scope to specific files/folders. " +
-            "Use 'nodeKind' to find every node of a known AST kind, or 'ast_grep_dump' first when the kind is unknown. " +
-            "Avoid 'selector' unless you know the exact AST node kind; it narrows matching and does not extract fields. " +
-            'If this tool is inactive, call pi_lens_activate_tools with tools=["ast_grep_search"]; activation takes effect next turn. If zero matches, retry once with a simpler AST pattern, then use ast_grep_dump on a small representative snippet before falling back to grep.',
-        promptSnippet: "AST-aware structural code search",
+        description: "Search source by AST structure rather than text. Example: find calls with `console.log($MSG)`.",
+        promptSnippet: "Search source by AST structure",
         renderResult: compactRenderResult(({ details, isError, text }) => {
             if (details?.validateOnly) {
                 const mode = details.mode ?? "pattern";
@@ -260,59 +270,58 @@ export function createAstGrepSearchTool(astGrepClient) {
             return `ast_grep_search — ${count}${ofTotal} match${count === 1 && !ofTotal ? "" : "es"}${applied}`;
         }),
         parameters: Type.Object({
-            pattern: Type.Optional(Type.String({
-                description: "AST pattern (use function/class/call context, not text). Required unless `rule` or `nodeKind` is provided. Do not put metavariables inside quoted string literals; they match literally.",
-            })),
+            dump: Type.Optional(Type.Boolean()),
+            pattern: Type.Optional(Type.String({ description: "AST pattern." })),
             lang: Type.String({
                 enum: [...LANGUAGES],
                 description: "Target language",
             }),
             paths: Type.Optional(Type.Array(Type.String(), {
                 maxItems: MAX_PATHS,
-                description: `Specific files/folders to search (max ${MAX_PATHS} entries)`,
+                description: "Files or directories to search.",
             })),
             selector: Type.Optional(Type.String({
-                description: "Advanced: restrict search to a specific AST node kind (for example 'call_expression' or 'function_declaration'). This narrows matching; it does not extract fields from matches.",
+                description: "AST node kind filter.",
             })),
             context: Type.Optional(Type.Number({
-                description: "Show N lines before/after each match for context",
+                description: "Context lines around matches.",
             })),
             nodeKind: Type.Optional(Type.String({
-                description: "Expert grammar-specific escape hatch: find every node of this exact AST kind (for example `call_expression`) without writing a pattern. Node kinds are not universal across languages; use ast_grep_dump to discover them. Mutually exclusive with `pattern` and `rule`; can be combined with structural constraints.",
+                description: "AST node kind without a pattern.",
             })),
             insideKind: Type.Optional(Type.String({
-                description: 'Restrict matches to nodes inside an ancestor of this AST node kind. Example: `insideKind: "function_declaration"` finds the pattern only when it appears inside a function body. Searches all ancestors (stopBy: end), not just the immediate parent. Synthesizes a YAML rule — takes precedence over `selector` and `strictness`.',
+                description: "Ancestor AST node kind filter.",
             })),
             hasKind: Type.Optional(Type.String({
-                description: 'Restrict matches to nodes whose immediate child has this AST node kind (ast-grep default stopBy: neighbor). Example: `hasKind: "await_expression"`.',
+                description: "Immediate-child AST node kind filter.",
             })),
             hasDescendantKind: Type.Optional(Type.String({
-                description: "Restrict matches to nodes containing this AST node kind anywhere in their descendants. Explicit recursive form (`stopBy: end`); use this instead of `hasKind` when nesting is not immediate.",
+                description: "Recursive descendant AST node kind filter.",
             })),
             follows: Type.Optional(Type.String({
-                description: 'Restrict matches to nodes that immediately follow a sibling matching this pattern. Example: `follows: "return $X"` finds the pattern only when preceded by a return statement.',
+                description: "Preceding sibling pattern filter.",
             })),
             precedes: Type.Optional(Type.String({
-                description: "Restrict matches to nodes that immediately precede a sibling matching this pattern.",
+                description: "Following sibling pattern filter.",
             })),
             rule: Type.Optional(Type.String({
-                description: "Raw ast-grep YAML rule. When provided, routes through `sg scan --config` instead of `sg run -p`, unlocking the full rule DSL. Takes precedence over `pattern` and structural-intent params. The YAML must include `id` and `language` fields.",
+                description: "Raw ast-grep YAML rule.",
             })),
             skip: Type.Optional(Type.Number({
-                description: "Match offset for pagination. Skip the first N matches and return the next page. Use when results are truncated — increment by the page size to retrieve subsequent pages.",
+                description: "Matches to skip for pagination.",
             })),
             maxMatches: Type.Optional(Type.Number({
-                description: `Cap on matches returned per call (default ${DEFAULT_PAGE_SIZE}, max ${MAX_PAGE_SIZE}). Lower it to keep a broad search compact; raise it to page less. Also sets the pagination step for skip.`,
+                description: "Maximum matches to return.",
             })),
             groupByFile: Type.Optional(Type.Boolean({
-                description: "Render results grouped by file (one line per file with L<line>:<col> locations) instead of each match's body. Compact distribution view for high-volume searches; match read-slices remain in details.matchLocations.",
+                description: "Group matches by file.",
             })),
             strictness: Type.Optional(Type.String({
                 enum: ["smart", "relaxed", "ast", "cst", "signature", "template"],
-                description: "Pattern matching strictness. 'smart' (default) ignores comments and whitespace. 'relaxed' also ignores unnamed nodes like punctuation — useful when optional trailing commas cause misses. 'ast' ignores all whitespace. 'signature' matches only structural shape, ignoring bodies.",
+                description: "Pattern matching strictness.",
             })),
             validateOnly: Type.Optional(Type.Boolean({
-                description: "Validate/compile the pattern or rule without scanning project files. Helps distinguish a bad pattern/rule from a real no-match result.",
+                description: "Validate without scanning.",
             })),
         }),
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -321,7 +330,7 @@ export function createAstGrepSearchTool(astGrepClient) {
             const abortSignal = combineAbortSignals(_signal, ctx.signal);
             const startedAt = Date.now();
             const deadlineAt = startedAt + AST_GREP_SEARCH_TIMEOUT_MS;
-            const { paths, nodeKind, selector, context, skip, maxMatches, groupByFile, strictness, rule, insideKind, hasKind, hasDescendantKind, follows, precedes, validateOnly, } = params;
+            const { paths, nodeKind, selector, context, skip, maxMatches, groupByFile, strictness, rule, insideKind, hasKind, hasDescendantKind, follows, precedes, validateOnly, dump, } = params;
             const pattern = typeof params.pattern === "string" ? params.pattern : "";
             const rawLang = typeof params.lang === "string" ? params.lang : "";
             const normalizedNodeKind = typeof nodeKind === "string" ? nodeKind.trim() : "";
@@ -329,6 +338,7 @@ export function createAstGrepSearchTool(astGrepClient) {
             const lang = rawLang.replace(/^"|"$/g, "");
             const searchPathsCount = paths?.length ?? 1;
             const executionOptions = { signal: abortSignal, deadlineAt };
+            const dumpMode = dump === true;
             function logOutcome(outcome, details = {}) {
                 try {
                     const errorRaw = _telemetryErrorForTest(details.errorRaw);
@@ -401,7 +411,7 @@ export function createAstGrepSearchTool(astGrepClient) {
                         details: {},
                     };
                 }
-                if (!hasPattern && !hasRawRule && !hasNodeKind) {
+                if (!dumpMode && !hasPattern && !hasRawRule && !hasNodeKind) {
                     logOutcome("error", {
                         errorRaw: "pattern is required unless rule or nodeKind is provided",
                     });
@@ -456,6 +466,40 @@ export function createAstGrepSearchTool(astGrepClient) {
                 }
                 if (abortSignal?.aborted)
                     return abortError();
+                if (dumpMode) {
+                    if (!pattern.trim()) {
+                        const errorRaw = "source is required when dump is true";
+                        logOutcome("error", { errorRaw });
+                        return {
+                            content: [{ type: "text", text: `Error: ${errorRaw}` }],
+                            isError: true,
+                            details: { mode: "dump", lang },
+                        };
+                    }
+                    const result = await astGrepClient.dumpAst(pattern, lang);
+                    if (result.error) {
+                        logOutcome("error", { errorRaw: result.error });
+                        return {
+                            content: [
+                                { type: "text", text: `Error: ${result.error}` },
+                            ],
+                            isError: true,
+                            details: { mode: "dump", lang },
+                        };
+                    }
+                    const output = result.output ?? "";
+                    logOutcome("success", { matchCount: lineCount(output) });
+                    return {
+                        content: [{ type: "text", text: output }],
+                        details: {
+                            mode: "dump",
+                            lang,
+                            matchCount: lineCount(output),
+                            totalMatches: lineCount(output),
+                            truncated: false,
+                        },
+                    };
+                }
                 if (!hasRawRule &&
                     hasPattern &&
                     looksLikeRuleYamlOrPlainText(pattern)) {

package/node_modules/pi-lens/dist/tools/effective-config.js

@@ -33,12 +33,12 @@ function summarize(view) {
         `${selected} server(s) selected${deniedClause} · ` +
         `${tools} tool(s)`);
 }
-export function createEffectiveConfigTool(getProjectRoot) {
+export function createEffectiveConfigTool(getProjectRoot, getNoTools) {
     return {
         name: "effective_config",
         label: "Effective Config",
-        description: "The resolved pi-lens configuration with the provenance of every decision — which file and tier each setting came from, and the trust decision that applied. Pass `file` to also get, for that path, its language, every LSP server with the reason it was selected or denied (including which tier's config denied it, which a nearer file cannot lift), and the lint/format runners that would dispatch. Answers 'why is X running/selected' without reading logs. Redacted by construction: it reports sources, never values — no env values, no command arguments beyond the binary, and config paths are home-relative.",
-        promptSnippet: "Resolved config + provenance — why a server or tool is selected",
+        description: "Explain resolved configuration and provenance. Response is redacted by construction: it contains no environment values, no command arguments beyond the binary, and home-relative paths; a tier-denied LSP decision cannot be lifted by a nearer config. Example: pass `file` to see why its LSP server is selected.",
+        promptSnippet: "Explain resolved configuration",
         renderResult: compactRenderResult(({ details, isError }) => isError
             ? "effective_config — failed"
             : (details?.summary ?? "effective_config")),
@@ -57,6 +57,7 @@ export function createEffectiveConfigTool(getProjectRoot) {
                 cwd,
                 ...(params.file === undefined ? {} : { file: params.file }),
                 redact: true,
+                noTools: getNoTools?.(),
             });
             const summary = summarize(view);
             return {

package/node_modules/pi-lens/dist/tools/lens-diagnostic-mark.js

@@ -178,16 +178,7 @@ getIdentity) {
     return {
         name: "lens_diagnostic_mark",
         label: "Mark Diagnostic",
-        description: "Record a disposition for a lens_diagnostics finding, using the exact filePath/rule/message/line " +
-            "it was reported with. false-positive/suppress persist across sessions; defer lasts only for the " +
-            "current session (resurfaces next time); flagged marks it for you to come back and fix, and shows " +
-            "up tagged in a later lens_diagnostics mode=full. suppress additionally writes a `pi-lens-ignore: " +
-            "<rule>` comment into the source above the flagged line — rule is required for suppress. " +
-            "The line is verified/reanchored against current diagnostics before writing (#802): if a live " +
-            "diagnostic for this tool/rule/message is now at a different line, that line is used instead of " +
-            "the one you passed. When suppressing several findings in the SAME file in one turn, work " +
-            "bottom-up (highest line number first) — each inserted comment shifts later lines down by one, " +
-            "and reanchoring can't always disambiguate two nearby findings.",
+        description: "Record a disposition for a diagnostic. Exact reported identity is required; suppress re-anchors against live diagnostics and writes an inline ignore comment, apply multiple suppressions bottom-up, and defer is session-only. Example: mark a false positive with its reported file, line, rule, and message.",
         promptSnippet: "Use lens_diagnostic_mark to dismiss a false-positive, suppress a won't-fix, defer, or flag a finding to fix later",
         parameters: Type.Object({
             filePath: Type.String({