pi-readseek 0.3.20 → 0.3.21

package/index.ts

@@ -5,22 +5,22 @@ import { registerGrepTool } from "./src/grep.js";
 import { registerSgTool, isSgAvailable } from "./src/sg.js";
 import { registerRefsTool } from "./src/refs.js";
 import { registerWriteTool } from "./src/write.js";
+import { SessionAnchors } from "./src/session-anchors.js";
+
 export default function piReadseekExtension(pi: ExtensionAPI): void {
-	const readPaths = new Set<string>();
-	const noteRead = (absolutePath: string) => {
-		readPaths.add(absolutePath);
-	};
-	const wasReadInSession = (absolutePath: string) => readPaths.has(absolutePath);
+	const sessionAnchors = new SessionAnchors();
+	const markAnchored = (absolutePath: string) => sessionAnchors.markAnchored(absolutePath);
+	const hasFreshAnchors = (absolutePath: string) => sessionAnchors.hasFreshAnchors(absolutePath);
 
-	registerReadTool(pi, { onSuccessfulRead: noteRead });
-	registerEditTool(pi, { wasReadInSession });
+	registerReadTool(pi, { onSuccessfulRead: markAnchored });
+	registerEditTool(pi, { wasReadInSession: hasFreshAnchors });
 	const sgAvailable = isSgAvailable();
 	const searchGuideline = sgAvailable
 		? "Use grep summary for counts; use search for structural code patterns."
 		: "Use grep summary for counts; install @jarkkojs/readseek to enable search.";
 
-	registerGrepTool(pi, { searchGuideline, onFileAnchored: noteRead });
-	registerSgTool(pi, { onFileAnchored: noteRead });
-	registerRefsTool(pi, { onFileAnchored: noteRead });
-	registerWriteTool(pi, { onFileAnchored: noteRead });
+	registerGrepTool(pi, { searchGuideline, onFileAnchored: markAnchored });
+	registerSgTool(pi, { onFileAnchored: markAnchored });
+	registerRefsTool(pi, { onFileAnchored: markAnchored });
+	registerWriteTool(pi, { onFileAnchored: markAnchored });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.3.20",
+  "version": "0.3.21",
   "description": "Pi extension for readseek-backed hash-anchored read/edit/grep, structural code maps, structural search, and file exploration",
   "type": "module",
   "exports": {

package/src/edit.ts

@@ -22,6 +22,7 @@ import { buildEditPreviewKey, buildPendingEditPreviewData, resolvePendingDiffPre
 import { buildDiffData, type DiffBlockRange } from "./diff-data.js";
 import { clampLineToWidth, clampLinesToWidth, linkToolPath, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
 import { DiffPreviewComponent } from "./tui-diff-component.js";
+import type { FreshAnchorsPredicate } from "./tool-types.js";
 
 import { resolveEditDiffDisplay } from "./readseek-settings.js";
 
@@ -134,7 +135,7 @@ function mapEditFileError(err: any, filePath: string, displayPath: string, phase
 }
 
 export interface EditToolOptions {
-	wasReadInSession?: (absolutePath: string) => boolean;
+	wasReadInSession?: FreshAnchorsPredicate;
 	syntaxValidate?: SyntaxValidateOptions["syntaxValidate"];
 }
 
@@ -142,7 +143,7 @@ export interface ExecuteEditOptions {
 	params: unknown;
 	signal: AbortSignal | undefined;
 	cwd: string;
-	wasReadInSession?: (absolutePath: string) => boolean;
+	wasReadInSession?: FreshAnchorsPredicate;
 	syntaxValidate?: SyntaxValidateOptions["syntaxValidate"];
 }
 

package/src/grep.ts

@@ -18,6 +18,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { formatGrepCallText, formatGrepResultText } from "./grep-render-helpers.js";
 import { coerceObviousBase10Int } from "./coerce-obvious-int.js";
 import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderToolLabel, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
+import type { FileAnchoredCallback } from "./tool-types.js";
 
 const GREP_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/grep.md", import.meta.url),
@@ -180,7 +181,7 @@ function escapeForRegex(s: string): string {
 
 interface GrepToolOptions {
 	searchGuideline?: string;
-	onFileAnchored?: (absolutePath: string) => void;
+	onFileAnchored?: FileAnchoredCallback;
 }
 
 export interface ExecuteGrepOptions {
@@ -189,7 +190,7 @@ export interface ExecuteGrepOptions {
 	signal: AbortSignal | undefined;
 	onUpdate: any;
 	cwd: string;
-	onFileAnchored?: (absolutePath: string) => void;
+	onFileAnchored?: FileAnchoredCallback;
 }
 
 export async function executeGrep(opts: ExecuteGrepOptions): Promise<any> {

package/src/read.ts

@@ -27,6 +27,7 @@ import { readseekRead } from "./readseek-client.js";
 import { Text } from "@earendil-works/pi-tui";
 import { formatReadCallText, formatReadResultText } from "./read-render-helpers.js";
 import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderToolLabel, resolveRenderResultContext, summaryLine, wrapReadHashlinesForWidth } from "./tui-render-utils.js";
+import type { FileAnchoredCallback } from "./tool-types.js";
 
 const READ_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/read.md", import.meta.url),
@@ -43,7 +44,7 @@ interface ReadParams {
 }
 
 interface ReadToolOptions {
-	onSuccessfulRead?: (absolutePath: string) => void;
+	onSuccessfulRead?: FileAnchoredCallback;
 }
 
 export interface ExecuteReadOptions {
@@ -52,7 +53,7 @@ export interface ExecuteReadOptions {
 	signal: AbortSignal | undefined;
 	onUpdate: any;
 	cwd: string;
-	onSuccessfulRead?: (absolutePath: string) => void;
+	onSuccessfulRead?: FileAnchoredCallback;
 }
 
 export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolResult<any>> {

package/src/refs.ts

@@ -8,6 +8,7 @@ import { buildReadseekLineWithHash, buildToolErrorResult } from "./readseek-valu
 import { resolveToCwd } from "./path-utils.js";
 import { isReadseekAvailable, readseekRefs, type ReadseekReference } from "./readseek-client.js";
 import { buildRefsOutput, type RefsOutputFile, type RefsOutputLine } from "./refs-output.js";
+import type { FileAnchoredCallback } from "./tool-types.js";
 
 import { clampLineToWidth, renderAnchoredFilesResult, renderToolLabel } from "./tui-render-utils.js";
 
@@ -33,7 +34,17 @@ export function isRefsAvailable(): boolean {
 }
 
 interface RefsToolOptions {
-  onFileAnchored?: (absolutePath: string) => void;
+  onFileAnchored?: FileAnchoredCallback;
+}
+
+/**
+ * Inputs for executing the references tool without registering it.
+ */
+export interface ExecuteRefsOptions {
+  params: unknown;
+  signal: AbortSignal | undefined;
+  cwd: string;
+  onFileAnchored?: FileAnchoredCallback;
 }
 
 function refsLine(reference: ReadseekReference): RefsOutputLine {
@@ -61,6 +72,72 @@ function groupReferences(references: ReadseekReference[], cwd: string): RefsOutp
   return [...files.values()];
 }
 
+/**
+ * Executes identifier reference lookup and returns readseek-anchored matches.
+ */
+export async function executeRefs(opts: ExecuteRefsOptions): Promise<any> {
+  const { params, signal, cwd, onFileAnchored } = opts;
+  const p = params as RefsParams;
+  if (p.ignored && !p.others) {
+    return buildToolErrorResult("refs", "invalid-parameter", "Error: refs parameter 'ignored' requires 'others'");
+  }
+  if (p.scope && p.line === undefined) {
+    return buildToolErrorResult("refs", "invalid-parameter", "Error: refs parameter 'scope' requires 'line'");
+  }
+  const searchPath = resolveToCwd(p.path ?? ".", cwd);
+
+  try {
+    await fsStat(searchPath);
+  } catch (err: any) {
+    if (err?.code === "ENOENT") {
+      return buildToolErrorResult("refs", "path-not-found", `Error: path '${p.path ?? "."}' does not exist`, {
+        path: p.path ?? searchPath,
+      });
+    }
+    if (err?.code === "EACCES" || err?.code === "EPERM") {
+      return buildToolErrorResult("refs", "permission-denied", `Error: permission denied for path '${p.path ?? "."}'`, {
+        path: p.path ?? searchPath,
+      });
+    }
+    const message = `Error: could not access path '${p.path ?? "."}': ${err?.message ?? String(err)}`;
+    return buildToolErrorResult("refs", "fs-error", message, {
+      path: p.path ?? searchPath,
+      details: { fsCode: err?.code, fsMessage: err?.message },
+    });
+  }
+
+  try {
+    const references = await readseekRefs(searchPath, p.name, {
+      scope: p.scope,
+      line: p.line,
+      column: p.column,
+      language: p.lang,
+      cached: p.cached,
+      others: p.others,
+      ignored: p.ignored,
+      signal,
+    });
+    const files = groupReferences(references, cwd);
+    const builtOutput = buildRefsOutput({ name: p.name, files });
+    for (const file of files) {
+      onFileAnchored?.(file.path);
+    }
+    return {
+      content: [{ type: "text", text: builtOutput.text }],
+      details: { readseekValue: builtOutput.readseekValue },
+    };
+  } catch (err: any) {
+    const message = String(err?.message || err);
+    const missingReadseek = err?.code === "ENOENT" || /Cannot find package|Cannot find module|no such file/i.test(message);
+    return buildToolErrorResult(
+      "refs",
+      missingReadseek ? "readseek-not-installed" : "readseek-execution-error",
+      message,
+      missingReadseek ? { hint: "Run npm install to install @jarkkojs/readseek." } : {},
+    );
+  }
+}
+
 export function registerRefsTool(pi: ExtensionAPI, options: RefsToolOptions = {}) {
   const toolConfig = {
     callable: true,
@@ -90,65 +167,7 @@ export function registerRefsTool(pi: ExtensionAPI, options: RefsToolOptions = {}
     }),
     ptc: toolConfig,
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-      const p = params as RefsParams;
-      if (p.ignored && !p.others) {
-        return buildToolErrorResult("refs", "invalid-parameter", "Error: refs parameter 'ignored' requires 'others'");
-      }
-      if (p.scope && p.line === undefined) {
-        return buildToolErrorResult("refs", "invalid-parameter", "Error: refs parameter 'scope' requires 'line'");
-      }
-      const searchPath = resolveToCwd(p.path ?? ".", ctx.cwd);
-
-      try {
-        await fsStat(searchPath);
-      } catch (err: any) {
-        if (err?.code === "ENOENT") {
-          return buildToolErrorResult("refs", "path-not-found", `Error: path '${p.path ?? "."}' does not exist`, {
-            path: p.path ?? searchPath,
-          });
-        }
-        if (err?.code === "EACCES" || err?.code === "EPERM") {
-          return buildToolErrorResult("refs", "permission-denied", `Error: permission denied for path '${p.path ?? "."}'`, {
-            path: p.path ?? searchPath,
-          });
-        }
-        const message = `Error: could not access path '${p.path ?? "."}': ${err?.message ?? String(err)}`;
-        return buildToolErrorResult("refs", "fs-error", message, {
-          path: p.path ?? searchPath,
-          details: { fsCode: err?.code, fsMessage: err?.message },
-        });
-      }
-
-      try {
-        const references = await readseekRefs(searchPath, p.name, {
-          scope: p.scope,
-          line: p.line,
-          column: p.column,
-          language: p.lang,
-          cached: p.cached,
-          others: p.others,
-          ignored: p.ignored,
-          signal,
-        });
-        const files = groupReferences(references, ctx.cwd);
-        const builtOutput = buildRefsOutput({ name: p.name, files });
-        for (const file of files) {
-          options.onFileAnchored?.(file.path);
-        }
-        return {
-          content: [{ type: "text", text: builtOutput.text }],
-          details: { readseekValue: builtOutput.readseekValue },
-        };
-      } catch (err: any) {
-        const message = String(err?.message || err);
-        const missingReadseek = err?.code === "ENOENT" || /Cannot find package|Cannot find module|no such file/i.test(message);
-        return buildToolErrorResult(
-          "refs",
-          missingReadseek ? "readseek-not-installed" : "readseek-execution-error",
-          message,
-          missingReadseek ? { hint: "Run npm install to install @jarkkojs/readseek." } : {},
-        );
-      }
+      return executeRefs({ params, signal, cwd: ctx.cwd, onFileAnchored: options.onFileAnchored });
     },
     renderCall(args: any, theme: any, ...rest: any[]) {
       const context = rest[0] ?? {};

package/src/session-anchors.ts

@@ -0,0 +1,20 @@
+/**
+ * Tracks files that have fresh hashline anchors in the current extension session.
+ */
+export class SessionAnchors {
+  readonly #paths = new Set<string>();
+
+  /**
+   * Records that a file has produced anchors usable by later edit calls.
+   */
+  markAnchored(absolutePath: string): void {
+    this.#paths.add(absolutePath);
+  }
+
+  /**
+   * Returns whether a file has fresh anchors in the current session.
+   */
+  hasFreshAnchors(absolutePath: string): boolean {
+    return this.#paths.has(absolutePath);
+  }
+}

package/src/sg.ts

@@ -8,6 +8,7 @@ import { buildReadseekLineWithHash, buildToolErrorResult, type ReadseekLine } fr
 import { resolveToCwd } from "./path-utils.js";
 import { isReadseekAvailable, readseekSearch, type ReadseekHashline, type ReadseekSearchFileOutput } from "./readseek-client.js";
 import { buildSgOutput } from "./sg-output.js";
+import type { FileAnchoredCallback } from "./tool-types.js";
 
 import { clampLineToWidth, renderAnchoredFilesResult, renderToolLabel } from "./tui-render-utils.js";
 
@@ -53,7 +54,17 @@ export function isSgAvailable(): boolean {
 }
 
 interface SgToolOptions {
-  onFileAnchored?: (absolutePath: string) => void;
+  onFileAnchored?: FileAnchoredCallback;
+}
+
+/**
+ * Inputs for executing the structural search tool without registering it.
+ */
+export interface ExecuteSgOptions {
+  params: unknown;
+  signal: AbortSignal | undefined;
+  cwd: string;
+  onFileAnchored?: FileAnchoredCallback;
 }
 
 function readseekLineFromSearch(line: ReadseekHashline): ReadseekLine {
@@ -87,6 +98,112 @@ function readseekLanguageForPath(language: string | undefined, searchPath: strin
   return language;
 }
 
+/**
+ * Executes structural search and returns readseek-anchored matches.
+ */
+export async function executeSg(opts: ExecuteSgOptions): Promise<any> {
+  const { params, signal, cwd, onFileAnchored } = opts;
+  const p = params as SgParams;
+  if (p.ignored && !p.others) {
+    const message = "Error: search parameter 'ignored' requires 'others'";
+    return buildToolErrorResult("search", "invalid-parameter", message);
+  }
+  const searchPath = resolveToCwd(p.path ?? ".", cwd);
+  let searchPathIsFile = false;
+
+  try {
+    const stat = await fsStat(searchPath);
+    searchPathIsFile = stat.isFile();
+  } catch (err: any) {
+    if (err?.code === "ENOENT") {
+      const message = `Error: path '${p.path ?? "."}' does not exist`;
+      return buildToolErrorResult("search", "path-not-found", message, { path: p.path ?? searchPath });
+    }
+    if (err?.code === "EACCES" || err?.code === "EPERM") {
+      const message = `Error: permission denied for path '${p.path ?? "."}'`;
+      return buildToolErrorResult("search", "permission-denied", message, { path: p.path ?? searchPath });
+    }
+    const message = `Error: could not access path '${p.path ?? "."}': ${err?.message ?? String(err)}`;
+    return buildToolErrorResult("search", "fs-error", message, { path: p.path ?? searchPath, details: { fsCode: err?.code, fsMessage: err?.message } });
+  }
+
+  try {
+    const effectiveLang = readseekLanguageForPath(p.lang, searchPath, searchPathIsFile);
+    const results = await readseekSearch(searchPath, p.pattern, {
+      language: effectiveLang,
+      cached: p.cached,
+      others: p.others,
+      ignored: p.ignored,
+      signal,
+    });
+    if (results.length === 0) {
+      const emptyOutput = buildSgOutput({ pattern: p.pattern, files: [] });
+      return {
+        content: [{ type: "text", text: emptyOutput.text }],
+        details: {
+          readseekValue: emptyOutput.readseekValue,
+        },
+      };
+    }
+
+    const readseekFiles: Array<{
+      displayPath: string;
+      path: string;
+      ranges: SgRange[];
+      lines: ReadseekLine[];
+      symbols?: SgEnclosingSymbol[];
+    }> = [];
+
+    for (const result of results) {
+      const abs = path.isAbsolute(result.file) ? result.file : path.resolve(cwd, result.file);
+      const display = path.relative(cwd, abs) || abs;
+      const ranges = result.matches.map((match) => ({ startLine: match.start_line, endLine: match.end_line }));
+      const mergedRanges = mergeRanges(ranges);
+      const lines = linesFromSearchResult(result, mergedRanges);
+      if (lines.length === 0) continue;
+      readseekFiles.push({
+        displayPath: display,
+        path: abs,
+        ranges: mergedRanges.map((range) => ({ ...range })),
+        lines,
+      });
+    }
+
+    if (readseekFiles.length === 0) {
+      const emptyOutput = buildSgOutput({ pattern: p.pattern, files: [] });
+      return {
+        content: [{ type: "text", text: emptyOutput.text }],
+        details: {
+          readseekValue: emptyOutput.readseekValue,
+        },
+      };
+    }
+
+    const builtOutput = buildSgOutput({
+      pattern: p.pattern,
+      files: readseekFiles,
+    });
+    for (const readseekFile of readseekFiles) {
+      onFileAnchored?.(readseekFile.path);
+    }
+    return {
+      content: [{ type: "text", text: builtOutput.text }],
+      details: {
+        readseekValue: builtOutput.readseekValue,
+      },
+    };
+  } catch (err: any) {
+    const message = String(err?.message || err);
+    const missingReadseek = err?.code === "ENOENT" || /Cannot find package|Cannot find module|no such file/i.test(message);
+    return buildToolErrorResult(
+      "search",
+      missingReadseek ? "readseek-not-installed" : "readseek-execution-error",
+      message,
+      missingReadseek ? { hint: "Run npm install to install @jarkkojs/readseek." } : {},
+    );
+  }
+}
+
 export function registerSgTool(pi: ExtensionAPI, options: SgToolOptions = {}) {
   const toolConfig = {
     callable: true,
@@ -113,105 +230,7 @@ export function registerSgTool(pi: ExtensionAPI, options: SgToolOptions = {}) {
     }),
     ptc: toolConfig,
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-      const p = params as SgParams;
-      if (p.ignored && !p.others) {
-        const message = "Error: search parameter 'ignored' requires 'others'";
-        return buildToolErrorResult("search", "invalid-parameter", message);
-      }
-      const searchPath = resolveToCwd(p.path ?? ".", ctx.cwd);
-      let searchPathIsFile = false;
-
-      try {
-        const stat = await fsStat(searchPath);
-        searchPathIsFile = stat.isFile();
-      } catch (err: any) {
-        if (err?.code === "ENOENT") {
-          const message = `Error: path '${p.path ?? "."}' does not exist`;
-          return buildToolErrorResult("search", "path-not-found", message, { path: p.path ?? searchPath });
-        }
-        if (err?.code === "EACCES" || err?.code === "EPERM") {
-          const message = `Error: permission denied for path '${p.path ?? "."}'`;
-          return buildToolErrorResult("search", "permission-denied", message, { path: p.path ?? searchPath });
-        }
-        const message = `Error: could not access path '${p.path ?? "."}': ${err?.message ?? String(err)}`;
-        return buildToolErrorResult("search", "fs-error", message, { path: p.path ?? searchPath, details: { fsCode: err?.code, fsMessage: err?.message } });
-      }
-
-      try {
-        const effectiveLang = readseekLanguageForPath(p.lang, searchPath, searchPathIsFile);
-        const results = await readseekSearch(searchPath, p.pattern, {
-          language: effectiveLang,
-          cached: p.cached,
-          others: p.others,
-          ignored: p.ignored,
-          signal,
-        });
-        if (results.length === 0) {
-          const emptyOutput = buildSgOutput({ pattern: p.pattern, files: [] });
-          return {
-            content: [{ type: "text", text: emptyOutput.text }],
-            details: {
-              readseekValue: emptyOutput.readseekValue,
-            },
-          };
-        }
-
-        const readseekFiles: Array<{
-          displayPath: string;
-          path: string;
-          ranges: SgRange[];
-          lines: ReadseekLine[];
-          symbols?: SgEnclosingSymbol[];
-        }> = [];
-
-        for (const result of results) {
-          const abs = path.isAbsolute(result.file) ? result.file : path.resolve(ctx.cwd, result.file);
-          const display = path.relative(ctx.cwd, abs) || abs;
-          const ranges = result.matches.map((match) => ({ startLine: match.start_line, endLine: match.end_line }));
-          const mergedRanges = mergeRanges(ranges);
-          const lines = linesFromSearchResult(result, mergedRanges);
-          if (lines.length === 0) continue;
-          readseekFiles.push({
-            displayPath: display,
-            path: abs,
-            ranges: mergedRanges.map((range) => ({ ...range })),
-            lines,
-          });
-        }
-
-        if (readseekFiles.length === 0) {
-          const emptyOutput = buildSgOutput({ pattern: p.pattern, files: [] });
-          return {
-            content: [{ type: "text", text: emptyOutput.text }],
-            details: {
-              readseekValue: emptyOutput.readseekValue,
-            },
-          };
-        }
-
-        const builtOutput = buildSgOutput({
-          pattern: p.pattern,
-          files: readseekFiles,
-        });
-        for (const readseekFile of readseekFiles) {
-          options.onFileAnchored?.(readseekFile.path);
-        }
-        return {
-          content: [{ type: "text", text: builtOutput.text }],
-          details: {
-            readseekValue: builtOutput.readseekValue,
-          },
-        };
-      } catch (err: any) {
-        const message = String(err?.message || err);
-        const missingReadseek = err?.code === "ENOENT" || /Cannot find package|Cannot find module|no such file/i.test(message);
-        return buildToolErrorResult(
-          "search",
-          missingReadseek ? "readseek-not-installed" : "readseek-execution-error",
-          message,
-          missingReadseek ? { hint: "Run npm install to install @jarkkojs/readseek." } : {},
-        );
-      }
+      return executeSg({ params, signal, cwd: ctx.cwd, onFileAnchored: options.onFileAnchored });
     },
     renderCall(args: any, theme: any, ...rest: any[]) {
       const context = rest[0] ?? {};

package/src/tool-types.ts

@@ -0,0 +1,9 @@
+/**
+ * Callback used when a tool returns fresh anchors for a file path.
+ */
+export type FileAnchoredCallback = (absolutePath: string) => void;
+
+/**
+ * Predicate used by mutating tools to check whether a file has session-fresh anchors.
+ */
+export type FreshAnchorsPredicate = (absolutePath: string) => boolean;

package/src/write.ts

@@ -16,6 +16,7 @@ import { generateCompactOrFullDiff, normalizeToLF, hasBareCarriageReturn } from
 import { buildDiffData, type DiffData } from "./diff-data.js";
 import { clampLineToWidth, clampLinesToWidth, isRendererExpanded, linkToolPath, renderToolLabel, summaryLine } from "./tui-render-utils.js";
 import { DiffPreviewComponent } from "./tui-diff-component.js";
+import type { FileAnchoredCallback } from "./tool-types.js";
 
 const WRITE_PENDING_PREVIEW_STATE_KEY = "hashline-write-pending-preview";
 
@@ -113,7 +114,7 @@ function generateWriteDiff(previousContent: string, nextContent: string): { diff
 }
 
 export interface WriteToolOptions {
-  onFileAnchored?: (absolutePath: string) => void;
+  onFileAnchored?: FileAnchoredCallback;
 }
 
 type MappedFsError = {