pi-lens 4.2.1 → 4.4.0

package/dist/scripts/lib/skills-predicate.mjs

@@ -1,129 +0,0 @@
-// The ONE structural replica of pi's own skill-loading walk (#2626 review
-// round 2, F1/F2).
-//
-// Two independent detectors used to answer "does this directory tree hold a
-// skill pi would load" with two DIFFERENT, hand-rolled heuristics that both
-// diverged from pi's real resolver:
-//   - `clients/skills-resolver.ts` (a `SKILL.md` one level down only, no
-//     recursion, no root `.md` acceptance, no symlink-follow, no dot/
-//     node_modules skip)
-//   - `scripts/install-selftest.mjs`'s `countSkillFiles` (recursed
-//     UNBOUNDED — would double-count a `SKILL.md` sitting inside another
-//     skill's own resource subdirectory — with no dot/node_modules skip, no
-//     root `.md` acceptance, no symlink handling)
-// Neither matched `loadSkillsFromDirInternal` in
-// `@earendil-works/pi-coding-agent` `dist/core/skills.js` (mirrored by
-// `collectSkillEntries` in `dist/core/package-manager.js`, byte-identical
-// walk, confirmed against the 0.85.1 tarball). This module is the fold: BOTH
-// consumers now derive from `collectSkillEntryPaths` below.
-//
-// Discovery rules, replicated from `loadSkillsFromDirInternal` (verified
-// against the extracted 0.85.1 `skills.js`):
-//   1. If `dir` directly contains a (non-symlink-broken) `SKILL.md`, `dir` IS
-//      one skill root — return immediately, do NOT look at `dir`'s other
-//      entries or recurse into its subdirectories (a `SKILL.md` inside a
-//      skill's own reference/ subfolder is the skill's OWN resource, not a
-//      second skill).
-//   2. Otherwise, skip dot-prefixed entries and `node_modules`; recurse into
-//      every remaining subdirectory (same two rules, one level down); at the
-//      OUTERMOST call only (`isRoot`), a loose `*.md` file directly in `dir`
-//      also counts (pi's `includeRootFiles`, true only for the top call).
-//   3. A symlink is followed via `statSync` (broken symlink = skip) for BOTH
-//      the `SKILL.md` check and the directory/file classification in step 2.
-//
-// Deliberately NOT replicated (out of #2626's scope — packaging/path
-// resolution, not skill-content validation):
-//   - `.gitignore`/`.ignore`/`.fdignore` matching inside the skills tree.
-//   - frontmatter parsing: pi additionally requires a non-empty `description`
-//     field before a discovered file becomes a loaded skill. A `SKILL.md`
-//     file that exists but fails THAT validation is a content-authoring
-//     defect a maintainer would see in normal use, not a silent zero.
-// Both gaps mean this predicate can be a bit more OPTIMISTIC than pi's true
-// count in a pathological case (an ignored or description-less file still
-// counts as "found" here); it is never more PESSIMISTIC — every real skill
-// pi loads is found by this walk too — which is the direction #2626 cares
-// about (never claim "no skills" when pi would load one).
-import * as fs from "node:fs";
-import * as path from "node:path";
-/**
- * Symlink-aware entry classification, mirroring `loadSkillsFromDirInternal`'s
- * own `entry.isSymbolicLink() ? statSync(fullPath) : entry`.
- * @param {string} fullPath
- * @param {import("node:fs").Dirent} entry
- * @returns {"file" | "dir" | "other"}
- */
-function resolvedEntryKind(fullPath, entry) {
-    if (entry.isSymbolicLink()) {
-        try {
-            const stats = fs.statSync(fullPath);
-            if (stats.isDirectory())
-                return "dir";
-            if (stats.isFile())
-                return "file";
-            return "other";
-        }
-        catch {
-            return "other"; // broken symlink
-        }
-    }
-    if (entry.isDirectory())
-        return "dir";
-    if (entry.isFile())
-        return "file";
-    return "other";
-}
-/**
- * The structural walk over an ALREADY-READ directory listing — split out
- * from `collectSkillEntryPaths` so a caller that already has `entries` (a
- * top-level ENOENT/EACCES distinction, say) is not forced into a second
- * `readdirSync`.
- * @param {string} dir
- * @param {import("node:fs").Dirent[]} entries
- * @param {boolean} isRoot
- * @returns {string[]} absolute paths of every `SKILL.md` (or, at the root,
- *   loose `.md`) file pi's own resolver would treat as a skill entry point.
- */
-export function scanEntriesForSkills(dir, entries, isRoot) {
-    for (const entry of entries) {
-        if (entry.name === "SKILL.md" &&
-            resolvedEntryKind(path.join(dir, entry.name), entry) === "file") {
-            return [path.join(dir, entry.name)];
-        }
-    }
-    const found = [];
-    for (const entry of entries) {
-        if (entry.name.startsWith(".") || entry.name === "node_modules") {
-            continue;
-        }
-        const fullPath = path.join(dir, entry.name);
-        const kind = resolvedEntryKind(fullPath, entry);
-        if (kind === "dir") {
-            found.push(...collectSkillEntryPaths(fullPath, false));
-            continue;
-        }
-        if (isRoot && kind === "file" && entry.name.endsWith(".md")) {
-            found.push(fullPath);
-        }
-    }
-    return found;
-}
-/**
- * Every skill entry point under `dir`, recursively, per pi's discovery
- * rules. Fail-closed: a `readdirSync` error at `dir` (absent, unreadable) or
- * any recursed-into subdirectory returns `[]` for that branch rather than
- * throwing — matching `loadSkillsFromDirInternal`'s own bare `try { … }
- * catch {}` per directory.
- * @param {string} dir
- * @param {boolean} [isRoot]
- * @returns {string[]}
- */
-export function collectSkillEntryPaths(dir, isRoot = true) {
-    let entries;
-    try {
-        entries = fs.readdirSync(dir, { withFileTypes: true });
-    }
-    catch {
-        return [];
-    }
-    return scanEntriesForSkills(dir, entries, isRoot);
-}

package/dist/tools/activate-tools.js

@@ -1,87 +0,0 @@
-/**
- * pi_lens_activate_tools — the loader tool that bootstraps pi's dynamic
- * tooling (registered-but-inactive tools activated via `pi.setActiveTools`).
- *
- * A handful of pi-lens tools are situational (structural ast-grep
- * search/replace/outline/dump, LSP go-to-definition/references/rename) —
- * useful on many turns, but not every turn. On hosts that support it, pi
- * lets an extension register such tools inactive and expose a small
- * always-active loader the model calls to activate a subset by name
- * (docs: https://github.com/earendil-works/pi, packages/coding-agent/docs/
- * extensions.md, "Dynamic Tool Loading"). Newly activated tools appear
- * starting the NEXT turn — no reload needed.
- *
- * This tool stays always-active (it has to, to bootstrap activation). It is
- * a no-op catalog lookup on hosts where the caller never wired
- * `setActiveTools`/`getActiveTools` (see the feature-detected gating in
- * index.ts) — the situational tools are registered statically active there
- * instead, so calling this tool is harmless, just unnecessary.
- */
-import { Type } from "../clients/deps/typebox.js";
-export function createActivateToolsTool(pi, lazyTools, options = {}) {
-    const lazyNames = lazyTools.map((t) => t.name);
-    const lazyNameSet = new Set(lazyNames);
-    return {
-        name: "pi_lens_activate_tools",
-        label: "Activate pi-lens Tools",
-        description: 'Activate registered situational tools for the next turn. Example: `{tools: ["lsp_navigation"]}`.',
-        promptSnippet: "Activate a situational tool",
-        parameters: Type.Object({
-            tools: Type.Array(Type.String({ enum: lazyNames }), {
-                minItems: 1,
-                description: "Names of situational tools to activate, e.g. `lsp_navigation`.",
-            }),
-        }),
-        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-            const requested = Array.isArray(params.tools)
-                ? params.tools.filter((t) => typeof t === "string" && lazyNameSet.has(t))
-                : [];
-            if (Array.isArray(params.tools)) {
-                for (const name of params.tools) {
-                    if (typeof name === "string" && !lazyNameSet.has(name))
-                        options.onRejected?.(name);
-                }
-            }
-            if (requested.length === 0) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `No valid tool names given. Available: ${lazyNames.join(", ")}`,
-                        },
-                    ],
-                    isError: true,
-                    details: { matches: [], added: [] },
-                };
-            }
-            // Additive only, per the docs' contract: never drop currently active
-            // tools in the same call.
-            // Remember every requested tool, not just the newly-added ones: a
-            // tool that is already active still has to survive the next
-            // fork/reload/resume restore.
-            options.onActivated?.(requested, ctx);
-            const active = typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [];
-            const activeSet = new Set(active);
-            const added = requested.filter((name) => !activeSet.has(name));
-            const merged = [...new Set([...active, ...added])];
-            if (added.length > 0 && typeof pi.setActiveTools === "function") {
-                pi.setActiveTools(merged);
-                options.onMutation?.({
-                    addedCount: added.length,
-                    removedCount: 0,
-                    reason: "lazy_activation",
-                    deferralApplies: options.deferredToolSupport?.(ctx) ?? false,
-                });
-            }
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Activated: ${requested.join(", ")}. Available starting next turn.`,
-                    },
-                ],
-                details: { matches: requested, added },
-            };
-        },
-    };
-}

package/dist/tools/ast-grep-outline.js

@@ -1,137 +0,0 @@
-import * as path from "node:path";
-import { Type } from "../clients/deps/typebox.js";
-import { compactRenderResult } from "./render-compact.js";
-import { LANGUAGES } from "./shared.js";
-// Cap the wire payload so an outline over a large directory can't flood context.
-const MAX_FILES = 50;
-const MAX_ITEMS_PER_FILE = 200;
-/** Attach ready `read` args (1-based) to each item/member from its 0-based range. */
-function withReadHandles(filePath, item) {
-    const { members, ...rest } = item;
-    const offset = item.range.start.line + 1;
-    const limit = Math.max(1, item.range.end.line - item.range.start.line + 1);
-    return {
-        ...rest,
-        read: { path: filePath, offset, limit },
-        ...(members
-            ? { members: members.map((m) => withReadHandles(filePath, m)) }
-            : {}),
-    };
-}
-function errorResult(text) {
-    return {
-        content: [{ type: "text", text }],
-        isError: true,
-        details: {},
-    };
-}
-export function createAstGrepOutlineTool(astGrepClient) {
-    return {
-        name: "ast_grep_outline",
-        label: "AST-Grep Outline",
-        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"}`;
-            }
-            const files = details?.files ?? 0;
-            const items = details?.items ?? 0;
-            const trunc = details?.truncatedFiles ? " (truncated)" : "";
-            return `ast_grep_outline — ${items} symbols across ${files} file${files === 1 ? "" : "s"}${trunc}`;
-        }),
-        parameters: Type.Object({
-            paths: Type.Array(Type.String(), {
-                minItems: 1,
-                maxItems: 100,
-                description: "Files or directories to outline (workspace-relative or absolute).",
-            }),
-            lang: Type.Optional(Type.String({
-                enum: [...LANGUAGES],
-                description: "Restrict to one language. Required for stdin; for paths, ast-grep infers per file when omitted.",
-            })),
-            items: Type.Optional(Type.String({
-                enum: ["auto", "structure", "exports", "imports", "all"],
-                description: "Which top-level items to include. auto = `structure` for a file, `exports` for a directory (default).",
-            })),
-            view: Type.Optional(Type.String({
-                enum: ["auto", "names", "signatures", "digest", "expanded"],
-                description: "Text presentation level for the underlying outline; `expanded` shows members.",
-            })),
-            type: Type.Optional(Type.Array(Type.String(), {
-                description: 'Keep only these symbol types, e.g. ["class","function"].',
-            })),
-            match: Type.Optional(Type.String({
-                description: "Keep only top-level items whose name matches this regex.",
-            })),
-            pubMembers: Type.Optional(Type.Boolean({
-                description: "Show only public members in member views.",
-            })),
-            globs: Type.Optional(Type.Array(Type.String(), {
-                description: 'Include/exclude file globs for directory input, e.g. ["*.ts","!**/dist/**"].',
-            })),
-        }),
-        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-            const cwd = ctx.cwd || ".";
-            const rawPaths = (params.paths ?? []).filter((p) => typeof p === "string" && p.trim().length > 0);
-            if (rawPaths.length === 0)
-                return errorResult("paths is required");
-            // Resolve relative paths against the workspace; pass absolute paths to the
-            // CLI (execFile-style args — no shell interpolation).
-            const absPaths = rawPaths.map((p) => path.isAbsolute(p) ? p : path.resolve(cwd, p));
-            if (!(await astGrepClient.ensureAvailable())) {
-                return errorResult("ast-grep CLI not found. Install: npm i -D @ast-grep/cli");
-            }
-            let result;
-            try {
-                result = await astGrepClient.outline(absPaths, {
-                    lang: params.lang,
-                    items: params.items,
-                    view: params.view,
-                    types: params.type,
-                    match: params.match,
-                    pubMembers: params.pubMembers,
-                    globs: params.globs,
-                });
-            }
-            catch (err) {
-                return errorResult(`Error: ${err instanceof Error ? err.message : String(err)}`);
-            }
-            if (result.error)
-                return errorResult(`Error: ${result.error}`);
-            const files = (result.output ?? []).slice(0, MAX_FILES);
-            const truncatedFiles = (result.output?.length ?? 0) > MAX_FILES;
-            const outline = files.map((file) => ({
-                path: file.path,
-                language: file.language,
-                items: file.items
-                    .slice(0, MAX_ITEMS_PER_FILE)
-                    .map((item) => withReadHandles(file.path, item)),
-                ...(file.items.length > MAX_ITEMS_PER_FILE
-                    ? { truncatedItems: file.items.length - MAX_ITEMS_PER_FILE }
-                    : {}),
-            }));
-            const totalItems = files.reduce((n, f) => n + f.items.length, 0);
-            if (outline.length === 0) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: "No outline items found (syntax-only — try module_report, or check lang/paths).",
-                        },
-                    ],
-                    details: { files: 0, items: 0 },
-                };
-            }
-            return {
-                content: [{ type: "text", text: JSON.stringify({ outline }) }],
-                details: {
-                    files: outline.length,
-                    items: totalItems,
-                    syntaxOnly: true,
-                    ...(truncatedFiles ? { truncatedFiles: true } : {}),
-                },
-            };
-        },
-    };
-}

package/dist/tools/ast-grep-replace.js

@@ -1,244 +0,0 @@
-/**
- * ast_grep_replace tool definition
- *
- * Extracted from index.ts for maintainability.
- */
-import { Type } from "../clients/deps/typebox.js";
-import { astGrepRemediationHint, classifyAstGrepError, logAstGrepToolEvent, } from "../clients/ast-grep-tool-logger.js";
-import { hasStructuralIntent, synthesizeReplaceRule, } from "../clients/ast-grep-yaml-synth.js";
-import { compactRenderResult } from "./render-compact.js";
-/**
- * Build the agent-facing error text, appending a remediation hint derived from
- * the same classification we log. Curated spawn errors return null from the
- * hint map (their message already carries guidance), so this only adds value
- * for the raw-stderr categories.
- */
-function errorTextWithHint(raw) {
-    const hint = astGrepRemediationHint(classifyAstGrepError(raw));
-    return hint ? `Error: ${raw}\n\n${hint}` : `Error: ${raw}`;
-}
-import { LANGUAGES } from "./shared.js";
-function lineCount(value) {
-    if (!value)
-        return 0;
-    let lines = 1;
-    for (let i = 0; i < value.length; i++) {
-        if (value.charCodeAt(i) === 10)
-            lines++;
-    }
-    return lines;
-}
-export function createAstGrepReplaceTool(astGrepClient) {
-    return {
-        name: "ast_grep_replace",
-        label: "AST 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`;
-            }
-            if (isError) {
-                return `ast_grep_replace — ${text.split("\n")[0] ?? "error"}`;
-            }
-            const n = details?.matchCount ?? 0;
-            const state = details?.applied ? "applied" : "preview";
-            return `ast_grep_replace — ${n} match${n === 1 ? "" : "es"}, ${state}`;
-        }),
-        parameters: Type.Object({
-            pattern: Type.String({
-                description: "AST pattern to match (be specific with context)",
-            }),
-            rewrite: Type.String({
-                description: "Replacement using meta-variables from pattern",
-            }),
-            lang: Type.String({
-                enum: [...LANGUAGES],
-                description: "Target language",
-            }),
-            paths: Type.Optional(Type.Array(Type.String(), { description: "Specific files/folders" })),
-            insideKind: Type.Optional(Type.String({
-                description: "Restrict matches to nodes inside an ancestor of this AST node kind. Synthesizes a YAML rule.",
-            })),
-            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"`.',
-            })),
-            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.",
-            })),
-            follows: Type.Optional(Type.String({
-                description: "Restrict matches to nodes that immediately follow a sibling matching this pattern.",
-            })),
-            precedes: Type.Optional(Type.String({
-                description: "Restrict matches to nodes that immediately precede a sibling matching this pattern.",
-            })),
-            apply: Type.Optional(Type.Boolean({ description: "Apply changes (default: false)" })),
-            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. 'ast' ignores all whitespace.",
-            })),
-        }),
-        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-            const startedAt = Date.now();
-            const { pattern, rewrite, paths, apply, strictness, insideKind, hasKind, hasDescendantKind, follows, precedes, } = params;
-            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({
-                        tool: "ast_grep_replace",
-                        lang,
-                        pattern,
-                        patternLineCount: lineCount(pattern),
-                        rewrite,
-                        rewriteLineCount: lineCount(rewrite ?? ""),
-                        pathsCount,
-                        applied: applyFlag,
-                        outcome,
-                        errorKind: outcome === "error"
-                            ? classifyAstGrepError(details.errorRaw)
-                            : undefined,
-                        errorRaw: details.errorRaw,
-                        matchCount: details.matchCount ?? 0,
-                        truncated: details.truncated ?? false,
-                        durationMs: Date.now() - startedAt,
-                    });
-                }
-                catch {
-                    // Telemetry must never break the tool path.
-                }
-            }
-            if (!(await astGrepClient.ensureAvailable())) {
-                logOutcome("error", { errorRaw: "ast-grep CLI not found" });
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: "ast-grep CLI not found. Install: npm i -D @ast-grep/cli",
-                        },
-                    ],
-                    isError: true,
-                    details: {},
-                };
-            }
-            const searchPaths = paths?.length ? paths : [ctx.cwd || "."];
-            // Phase 3: structural-intent params → synthesize YAML with fix: field
-            if (hasStructuralIntent({
-                insideKind,
-                hasKind,
-                hasDescendantKind,
-                follows,
-                precedes,
-            })) {
-                let ruleYaml;
-                try {
-                    ruleYaml = synthesizeReplaceRule({
-                        pattern,
-                        lang,
-                        rewrite,
-                        insideKind,
-                        hasKind,
-                        hasDescendantKind,
-                        follows,
-                        precedes,
-                    });
-                }
-                catch (err) {
-                    logOutcome("error", { errorRaw: String(err) });
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: `Error synthesizing rule: ${err}`,
-                            },
-                        ],
-                        isError: true,
-                        details: {},
-                    };
-                }
-                const ruleResult = await astGrepClient.replaceWithRule(ruleYaml, searchPaths, applyFlag);
-                if (ruleResult.stalePreview) {
-                    logOutcome("error", { errorRaw: "stale_preview" });
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: "Stale preview — pattern no longer matches. Re-run with apply: false.",
-                            },
-                        ],
-                        isError: true,
-                        details: { stalePreview: true },
-                    };
-                }
-                if (ruleResult.error) {
-                    logOutcome("error", { errorRaw: ruleResult.error });
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: errorTextWithHint(ruleResult.error),
-                            },
-                        ],
-                        isError: true,
-                        details: {},
-                    };
-                }
-                const output = astGrepClient.formatMatches(ruleResult.matches, !applyFlag, true, resultMaxItems);
-                logOutcome(ruleResult.matches.length === 0 ? "no_matches" : "success", {
-                    matchCount: ruleResult.matches.length,
-                });
-                return {
-                    content: [{ type: "text", text: output }],
-                    details: {
-                        matchCount: ruleResult.matches.length,
-                        applied: applyFlag,
-                    },
-                };
-            }
-            const result = await astGrepClient.replace(pattern, rewrite, lang, searchPaths, applyFlag, { strictness });
-            if (result.stalePreview) {
-                logOutcome("error", { errorRaw: "stale_preview" });
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: "Stale preview — the pattern no longer matches any files. The file content has changed since your last apply: false preview. Re-run with apply: false to get a fresh preview before applying.",
-                        },
-                    ],
-                    isError: true,
-                    details: { stalePreview: true },
-                };
-            }
-            if (result.error) {
-                logOutcome("error", { errorRaw: result.error });
-                return {
-                    content: [
-                        { type: "text", text: errorTextWithHint(result.error) },
-                    ],
-                    isError: true,
-                    details: {},
-                };
-            }
-            const isDryRun = !applyFlag;
-            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,
-            });
-            return {
-                content: [{ type: "text", text: output }],
-                details: {
-                    matchCount: result.matches.length,
-                    totalMatches: result.totalMatches,
-                    truncated: result.truncated,
-                    applied: applyFlag,
-                },
-            };
-        },
-    };
-}