pi-readseek 0.3.19 → 0.3.21

package/src/readseek-value.ts

@@ -55,8 +55,12 @@ export interface ReadseekEditResult {
   semanticSummary?: SemanticSummary;
 }
 
-export function buildReadseekLine(line: number, raw: string): ReadseekLine {
-  const hash = computeLineHash(line, raw);
+/**
+ * Build a {@link ReadseekLine} from an already-known hash. Use this when the
+ * hash is supplied by readseek (search, refs) rather than computed from `raw`;
+ * {@link buildReadseekLine} delegates here after hashing.
+ */
+export function buildReadseekLineWithHash(line: number, hash: string, raw: string): ReadseekLine {
   return {
     line,
     hash,
@@ -66,6 +70,10 @@ export function buildReadseekLine(line: number, raw: string): ReadseekLine {
   };
 }
 
+export function buildReadseekLine(line: number, raw: string): ReadseekLine {
+  return buildReadseekLineWithHash(line, computeLineHash(line, raw), raw);
+}
+
 export function buildReadseekLines(startLine: number, rawLines: string[]): ReadseekLine[] {
   return rawLines.map((raw, index) => buildReadseekLine(startLine + index, raw));
 }

package/src/refs.ts

@@ -4,13 +4,13 @@ import { Type } from "@sinclair/typebox";
 import path from "node:path";
 import { stat as fsStat } from "node:fs/promises";
 import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
-import { escapeControlCharsForDisplay } from "./hashline.js";
-import { buildToolErrorResult } from "./readseek-value.js";
+import { buildReadseekLineWithHash, buildToolErrorResult } from "./readseek-value.js";
 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, clampLinesToWidth, renderToolLabel, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
+import { clampLineToWidth, renderAnchoredFilesResult, renderToolLabel } from "./tui-render-utils.js";
 
 type RefsParams = {
   name: string;
@@ -34,16 +34,22 @@ 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 {
   return {
-    line: reference.line,
-    hash: reference.line_hash,
-    anchor: `${reference.line}:${reference.line_hash}`,
-    raw: reference.text,
-    display: escapeControlCharsForDisplay(reference.text),
+    ...buildReadseekLineWithHash(reference.line, reference.line_hash, reference.text),
     enclosingSymbol: reference.enclosingSymbol,
   };
 }
@@ -66,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,
@@ -95,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] ?? {};
@@ -165,35 +179,12 @@ export function registerRefsTool(pi: ExtensionAPI, options: RefsToolOptions = {}
       return new Text(clampLineToWidth(text, context.width), 0, 0);
     },
     renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
-      const { isPartial, isError, expanded, cwd, width } = resolveRenderResultContext(options, rest);
-
-      if (isPartial) return new Text(clampLinesToWidth([summaryLine("pending refs")], width).join("\n"), 0, 0);
-
-      const content = result.content?.[0];
-      const textContent = content?.type === "text" ? content.text : "";
-      if (isError || result.isError) {
-        const firstLine = textContent.split("\n")[0] || "Error";
-        const body = expanded && textContent ? textContent : firstLine;
-        return new Text(clampLinesToWidth(summaryLine(body).split("\n"), width).join("\n"), 0, 0);
-      }
-      const readseekValue = (result.details as any)?.readseekValue as
-        | { tool: "refs"; files: Array<{ path: string; lines: any[] }> }
-        | undefined;
-      const files = readseekValue?.files ?? [];
-      if (files.length === 0) return new Text(summaryLine("no references"), 0, 0);
-      const fileCount = files.length;
-      const totalRefs = files.reduce((sum: number, f: any) => sum + f.lines.length, 0);
-      const refWord = totalRefs === 1 ? "reference" : "references";
-      const fileWord = fileCount === 1 ? "file" : "files";
-      let text = summaryLine(`${totalRefs} ${refWord} in ${fileCount} ${fileWord}`, { hidden: !expanded });
-      if (expanded) {
-        for (const file of files.slice(0, 20)) {
-          const display = path.relative(cwd, file.path) || file.path;
-          text += "\n" + theme.fg("dim", `  ${display} (${file.lines.length})`);
-        }
-        if (files.length > 20) text += "\n" + theme.fg("muted", `  … and ${files.length - 20} more files`);
-      }
-      return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
+      return renderAnchoredFilesResult(result, options, theme, rest, {
+        pendingLabel: "pending refs",
+        emptyLabel: "no references",
+        unitSingular: "reference",
+        unitPlural: "references",
+      });
     },
   } satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
 

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

@@ -4,13 +4,13 @@ import { Type } from "@sinclair/typebox";
 import path from "node:path";
 import { stat as fsStat } from "node:fs/promises";
 import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
-import { escapeControlCharsForDisplay } from "./hashline.js";
-import { buildToolErrorResult, type ReadseekLine } from "./readseek-value.js";
+import { buildReadseekLineWithHash, buildToolErrorResult, type ReadseekLine } from "./readseek-value.js";
 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, clampLinesToWidth, renderToolLabel, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
+import { clampLineToWidth, renderAnchoredFilesResult, renderToolLabel } from "./tui-render-utils.js";
 
 type SgParams = { pattern: string; lang?: string; path?: string; cached?: boolean; others?: boolean; ignored?: boolean };
 
@@ -54,17 +54,21 @@ 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 {
-  return {
-    line: line.line,
-    hash: line.hash,
-    anchor: `${line.line}:${line.hash}`,
-    raw: line.text,
-    display: escapeControlCharsForDisplay(line.text),
-  };
+  return buildReadseekLineWithHash(line.line, line.hash, line.text);
 }
 
 function linesFromSearchResult(result: ReadseekSearchFileOutput, ranges: SgRange[]): ReadseekLine[] {
@@ -94,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,
@@ -120,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] ?? {};
@@ -230,35 +242,12 @@ export function registerSgTool(pi: ExtensionAPI, options: SgToolOptions = {}) {
       return new Text(clampLineToWidth(text, context.width), 0, 0);
     },
     renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
-      const { isPartial, isError, expanded, cwd, width } = resolveRenderResultContext(options, rest);
-
-      if (isPartial) return new Text(clampLinesToWidth([summaryLine("pending search")], width).join("\n"), 0, 0);
-
-      const content = result.content?.[0];
-      const textContent = content?.type === "text" ? content.text : "";
-      if (isError || result.isError) {
-        const firstLine = textContent.split("\n")[0] || "Error";
-        const body = expanded && textContent ? textContent : firstLine;
-        return new Text(clampLinesToWidth(summaryLine(body).split("\n"), width).join("\n"), 0, 0);
-      }
-      const readseekValue = (result.details as any)?.readseekValue as
-        | { tool: "search"; files: Array<{ path: string; lines: any[] }> }
-        | undefined;
-      const files = readseekValue?.files ?? [];
-      if (files.length === 0) return new Text(summaryLine("no matches"), 0, 0);
-      const fileCount = files.length;
-      const totalMatches = files.reduce((sum: number, f: any) => sum + f.lines.length, 0);
-      const matchWord = totalMatches === 1 ? "match" : "matches";
-      const fileWord = fileCount === 1 ? "file" : "files";
-      let text = summaryLine(`${totalMatches} ${matchWord} in ${fileCount} ${fileWord}`, { hidden: files.length > 0 && !expanded });
-      if (expanded) {
-        for (const file of files.slice(0, 20)) {
-          const display = path.relative(cwd, file.path) || file.path;
-          text += "\n" + theme.fg("dim", `  ${display} (${file.lines.length})`);
-        }
-        if (files.length > 20) text += "\n" + theme.fg("muted", `  … and ${files.length - 20} more files`);
-      }
-      return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
+      return renderAnchoredFilesResult(result, options, theme, rest, {
+        pendingLabel: "pending search",
+        emptyLabel: "no matches",
+        unitSingular: "match",
+        unitPlural: "matches",
+      });
     },
   } satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
 

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/tui-render-utils.ts

@@ -1,4 +1,5 @@
-import { getCapabilities, hyperlink, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { getCapabilities, hyperlink, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { relative } from "node:path";
 import { pathToFileURL } from "node:url";
 import { resolveToCwd } from "./path-utils.js";
 
@@ -154,3 +155,56 @@ export function wrapReadHashlinesForWidth(text: string, width: number | undefine
   }
   return output.join("\n");
 }
+
+export interface AnchoredFilesLabels {
+  pendingLabel: string;
+  emptyLabel: string;
+  unitSingular: string;
+  unitPlural: string;
+}
+
+/**
+ * Render the result summary shared by the anchored-files search tools (search,
+ * refs): a pending line, an error first-line/expanded body, an empty-result
+ * line, or a `<count> <unit> in <n> files` summary with an expandable per-file
+ * list. The four call-site differences are supplied via {@link labels}.
+ */
+export function renderAnchoredFilesResult(
+  result: any,
+  options: any,
+  theme: RendererTheme,
+  rest: any[],
+  labels: AnchoredFilesLabels,
+): Text {
+  const { isPartial, isError, expanded, cwd, width } = resolveRenderResultContext(options, rest);
+
+  if (isPartial) return new Text(clampLinesToWidth([summaryLine(labels.pendingLabel)], width).join("\n"), 0, 0);
+
+  const content = result.content?.[0];
+  const textContent = content?.type === "text" ? content.text : "";
+  if (isError || result.isError) {
+    const firstLine = textContent.split("\n")[0] || "Error";
+    const body = expanded && textContent ? textContent : firstLine;
+    return new Text(clampLinesToWidth(summaryLine(body).split("\n"), width).join("\n"), 0, 0);
+  }
+
+  const readseekValue = (result.details as any)?.readseekValue as
+    | { files: Array<{ path: string; lines: any[] }> }
+    | undefined;
+  const files = readseekValue?.files ?? [];
+  if (files.length === 0) return new Text(summaryLine(labels.emptyLabel), 0, 0);
+
+  const fileCount = files.length;
+  const total = files.reduce((sum: number, f: any) => sum + f.lines.length, 0);
+  const unitWord = total === 1 ? labels.unitSingular : labels.unitPlural;
+  const fileWord = fileCount === 1 ? "file" : "files";
+  let text = summaryLine(`${total} ${unitWord} in ${fileCount} ${fileWord}`, { hidden: !expanded });
+  if (expanded) {
+    for (const file of files.slice(0, 20)) {
+      const display = relative(cwd, file.path) || file.path;
+      text += "\n" + theme.fg("dim", `  ${display} (${file.lines.length})`);
+    }
+    if (files.length > 20) text += "\n" + theme.fg("muted", `  … and ${files.length - 20} more files`);
+  }
+  return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
+}

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 = {