pi-readseek 0.1.0

package/src/ls.ts

@@ -0,0 +1,293 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "@sinclair/typebox";
+import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
+import { readdir, stat } from "node:fs/promises";
+import { resolveToCwd } from "./path-utils.js";
+import { buildReadseekError } from "./readseek-value.js";
+import { coerceObviousBase10Int } from "./coerce-obvious-int.js";
+import { clampLineToWidth, clampLinesToWidth, isRendererExpanded, linkToolPath, renderToolLabel, summaryLine } from "./tui-render-utils.js";
+
+const MAX_BYTES = 50 * 1024; // 50 KB
+const DEFAULT_LIMIT = 500;
+
+const LS_PROMPT_METADATA = defineToolPromptMetadata({
+  promptUrl: new URL("../prompts/ls.md", import.meta.url),
+  promptSnippet: "List one directory with directories first and dotfiles included",
+  promptGuidelines: [
+    "Use ls to inspect one directory; use find for recursive discovery.",
+    "Use ls glob to narrow a single-directory listing.",
+    "Use read, not ls, for file contents.",
+  ],
+});
+
+export const LS_READSEEK = {
+  callable: true,
+  enabled: true,
+  policy: "read-only" as const,
+  readOnly: true,
+  pythonName: "ls",
+  defaultExposure: "safe-by-default" as const,
+};
+
+export interface LsEntry {
+  name: string;
+  type: "file" | "dir";
+}
+
+export interface LsReadseekValue {
+  tool: "ls";
+  path: string;
+  totalEntries: number;
+  truncated: boolean;
+  entries: LsEntry[];
+}
+
+function sortEntries(entries: LsEntry[]): LsEntry[] {
+  const dirs = entries.filter((e) => e.type === "dir");
+  const files = entries.filter((e) => e.type === "file");
+  const cmp = (a: LsEntry, b: LsEntry) => {
+    const lower = a.name.toLowerCase().localeCompare(b.name.toLowerCase());
+    return lower !== 0 ? lower : a.name.localeCompare(b.name);
+  };
+  dirs.sort(cmp);
+  files.sort(cmp);
+  return [...dirs, ...files];
+}
+
+function formatOutput(entries: LsEntry[], totalCount: number, truncated: boolean): string {
+  const lines: string[] = [];
+  for (const e of entries) {
+    lines.push(e.type === "dir" ? `${e.name}/` : e.name);
+  }
+  if (truncated) {
+    const remaining = totalCount - entries.length;
+    lines.push(`[… ${remaining} more entries — use glob to narrow results]`);
+  }
+  if (entries.length === 0 && !truncated) {
+    return "(empty directory)";
+  }
+  let text = lines.join("\n");
+  const bytes = Buffer.byteLength(text, "utf8");
+  if (bytes > MAX_BYTES) {
+    text = Buffer.from(text, "utf8").subarray(0, MAX_BYTES).toString("utf8") + "\n[… truncated at 50 KB]";
+  }
+  return text;
+}
+
+function validateGlobBalance(glob: string): string | null {
+  let brackets = 0;
+  let braces = 0;
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i];
+    if (ch === "\\") {
+      i++;
+      continue;
+    }
+    if (ch === "[") brackets++;
+    else if (ch === "]") {
+      if (brackets === 0) return "Unmatched ']'.";
+      brackets--;
+    } else if (ch === "{") braces++;
+    else if (ch === "}") {
+      if (braces === 0) return "Unmatched '}'.";
+      braces--;
+    }
+  }
+  if (brackets !== 0) return "Unterminated character class.";
+  if (braces !== 0) return "Unterminated brace expansion.";
+  return null;
+}
+
+export function registerLsTool(pi: ExtensionAPI) {
+  const tool: Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof LS_READSEEK } = {
+    name: "ls",
+    label: "ls",
+    description: LS_PROMPT_METADATA.description,
+    promptSnippet: LS_PROMPT_METADATA.promptSnippet,
+    promptGuidelines: LS_PROMPT_METADATA.promptGuidelines,
+    ptc: LS_READSEEK,
+    parameters: Type.Object({
+      path: Type.Optional(Type.String({ description: "Directory path" })),
+      limit: Type.Optional(
+        Type.Union(
+          [Type.Number(), Type.String()],
+          { description: "Max entries" },
+        ),
+      ),
+      glob: Type.Optional(Type.String({ description: "Glob filter" })),
+    }),
+    async execute(
+      _toolCallId: string,
+      params: { path?: string; limit?: number | string; glob?: string },
+      _signal: AbortSignal | undefined,
+      _onUpdate: any,
+      ctx: any,
+    ) {
+      const cwd: string = ctx?.cwd ?? process.cwd();
+      const targetPath = params.path ? resolveToCwd(params.path, cwd) : cwd;
+      const limitCoerced = coerceObviousBase10Int(params.limit, "limit");
+      if (!limitCoerced.ok) {
+        return {
+          content: [{ type: "text" as const, text: limitCoerced.message }],
+          isError: true,
+          details: {
+            readseekValue: {
+              tool: "ls" as const,
+              ok: false,
+              path: params.path ?? targetPath,
+              error: buildReadseekError("invalid-limit", limitCoerced.message),
+            },
+          },
+        };
+      }
+      if (limitCoerced.value !== undefined && limitCoerced.value < 1) {
+        const message = `Invalid limit: expected a positive integer, received ${limitCoerced.value}.`;
+        return {
+          content: [{ type: "text" as const, text: message }],
+          isError: true,
+          details: {
+            readseekValue: {
+              tool: "ls" as const,
+              ok: false,
+              path: params.path ?? targetPath,
+              error: buildReadseekError("invalid-limit", message),
+            },
+          },
+        };
+      }
+      const limit = limitCoerced.value ?? DEFAULT_LIMIT;
+
+      // Check if path exists and is a directory
+      let pathStat;
+      try {
+        pathStat = await stat(targetPath);
+      } catch (err: any) {
+        const target = params.path ?? targetPath;
+        const code =
+          err?.code === "EACCES" || err?.code === "EPERM"
+            ? "permission-denied"
+            : err?.code === "ENOENT"
+              ? "path-not-found"
+              : "fs-error";
+        const message =
+          code === "permission-denied"
+            ? `Error: permission denied for path '${target}'`
+            : code === "path-not-found"
+              ? `Error: path '${target}' does not exist`
+              : `Error: could not access path '${target}': ${err?.message ?? String(err)}`;
+        return {
+          content: [{ type: "text" as const, text: message }],
+          isError: true,
+          details: {
+            readseekValue: {
+              tool: "ls",
+              ok: false,
+              path: target,
+              error: buildReadseekError(code, message, undefined, code === "fs-error"
+                ? { fsCode: err?.code, fsMessage: err?.message }
+                : undefined),
+            },
+          },
+        };
+      }
+      if (!pathStat.isDirectory()) {
+        const message = `Error: '${params.path ?? targetPath}' is a file, not a directory. Use read to inspect files.`;
+        return {
+          content: [{ type: "text" as const, text: message }],
+          isError: true,
+          details: {
+            readseekValue: {
+              tool: "ls",
+              ok: false,
+              path: params.path ?? targetPath,
+              error: buildReadseekError(
+                "path-not-directory",
+                message,
+                `Use read(${JSON.stringify(params.path ?? targetPath)}) to inspect files.`,
+              ),
+            },
+          },
+        };
+      }
+
+      // Read directory
+      const dirents = await readdir(targetPath, { withFileTypes: true });
+      let allEntries: LsEntry[] = dirents.map((d) => ({
+        name: d.name,
+        type: d.isDirectory() ? ("dir" as const) : ("file" as const),
+      }));
+
+      // Apply glob filter
+      if (params.glob) {
+        const balanceError = validateGlobBalance(params.glob);
+        if (balanceError) {
+          const message = `Invalid glob ${JSON.stringify(params.glob)}: ${balanceError}`;
+          return {
+            content: [{ type: "text" as const, text: message }],
+            isError: true,
+            details: {
+              readseekValue: {
+                tool: "ls" as const,
+                ok: false,
+                path: params.path ?? targetPath,
+                error: buildReadseekError("invalid-params-combo", message),
+              },
+            },
+          };
+        }
+        const picomatch = (await import("picomatch" as any)).default;
+        const isMatch = picomatch(params.glob);
+        allEntries = allEntries.filter((e) => isMatch(e.name));
+      }
+
+      // Sort: dirs first, then files, each group alpha case-insensitive
+      const sorted = sortEntries(allEntries);
+      const totalCount = sorted.length;
+      const truncated = totalCount > limit;
+      const displayed = truncated ? sorted.slice(0, limit) : sorted;
+
+      const text = formatOutput(displayed, totalCount, truncated);
+      const readseekValue: LsReadseekValue = {
+        tool: "ls",
+        path: targetPath,
+        totalEntries: totalCount,
+        truncated,
+        entries: displayed,
+      };
+
+      return {
+        content: [{ type: "text" as const, text }],
+        details: { readseekValue },
+      };
+    },
+
+    renderCall(args: any, theme: any, context: any = {}) {
+      const { path } = args as { path?: string };
+      const cwd = context.cwd ?? process.cwd();
+      const displayPath = path ?? ".";
+      const linkedPath = linkToolPath(theme.fg("muted", displayPath), displayPath, cwd);
+      return new Text(clampLineToWidth(`${renderToolLabel(theme, "ls")} ${linkedPath}`, context.width), 0, 0);
+    },
+
+    renderResult(result: any, options: any, theme: any, context: any = {}) {
+      const expanded = isRendererExpanded(options, context);
+      const width = context.width ?? options?.width;
+      const output = result.content[0]?.type === "text" ? (result.content[0] as { type: "text"; text: string }).text : "";
+      if (result.isError || context.isError) {
+        const firstLine = output.split("\n")[0] || "error";
+        const body = expanded && output ? output : firstLine;
+        return new Text(clampLinesToWidth(summaryLine(body).split("\n"), width).join("\n"), 0, 0);
+      }
+      const readseekValue = result.details?.readseekValue as { totalEntries?: number } | undefined;
+      const total = readseekValue?.totalEntries ?? output.split("\n").filter(Boolean).length;
+      if (total === 0) return new Text(summaryLine("no entries"), 0, 0);
+      let text = summaryLine(`${total} ${total === 1 ? "entry" : "entries"} returned`, { hidden: !!output && !expanded });
+      if (expanded && output) text += `\n${output}`;
+      return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
+    },
+  };
+
+  pi.registerTool(tool);
+  return tool;
+}

package/src/map-cache.ts

@@ -0,0 +1,152 @@
+import { stat } from "node:fs/promises";
+import type { FileMap } from "./readseek/types.js";
+import { generateMap, generateMapWithIdentity, READSEEK_MAPPER_IDENTITY } from "./readseek/mapper.js";
+import {
+  computeKey,
+  contentHashFor64k,
+  readCached,
+  writeCached,
+  persistenceEnabled,
+} from "./persistent-map-cache.js";
+interface CacheEntry {
+	mtimeMs: number;
+	contentHash: string;
+	map: FileMap | null;
+}
+export const MAP_CACHE_MAX_SIZE = 500;
+
+interface MapCacheGlobalState {
+	cache: Map<string, CacheEntry>;
+	maxSize: number;
+}
+
+const MAP_CACHE_STATE_KEY = Symbol.for("pi-readseek.mapCacheState.v1");
+
+function getMapCacheState(): MapCacheGlobalState {
+	const globalObject = globalThis as any;
+	globalObject[MAP_CACHE_STATE_KEY] ??= {
+		cache: new Map<string, CacheEntry>(),
+		maxSize: MAP_CACHE_MAX_SIZE,
+	} satisfies MapCacheGlobalState;
+	return globalObject[MAP_CACHE_STATE_KEY] as MapCacheGlobalState;
+}
+
+function rememberInMemory(absPath: string, entry: CacheEntry): void {
+	const state = getMapCacheState();
+	if (state.cache.has(absPath)) state.cache.delete(absPath);
+	state.cache.set(absPath, entry);
+	if (state.cache.size > state.maxSize) {
+		const oldestKey = state.cache.keys().next().value;
+		if (oldestKey !== undefined) state.cache.delete(oldestKey);
+	}
+}
+
+async function stableContentHash(
+	absPath: string,
+	mtimeMs: number,
+	expectedHash: string,
+): Promise<string | null> {
+	if (!expectedHash) return null;
+	const currentStat = await stat(absPath);
+	if (currentStat.mtimeMs !== mtimeMs) return null;
+	const currentHash = await contentHashFor64k(absPath);
+	if (!currentHash || currentHash !== expectedHash) return null;
+	return currentHash;
+}
+
+/**
+ * Get or generate a structural file map, with mtime-based caching.
+ * Returns null on any failure — never throws.
+ */
+export async function getOrGenerateMap(absPath: string): Promise<FileMap | null> {
+	try {
+		const fileStat = await stat(absPath);
+		const { mtimeMs } = fileStat;
+		const state = getMapCacheState();
+		const cached = state.cache.get(absPath);
+		if (cached && cached.mtimeMs === mtimeMs) {
+			const currentHash = await contentHashFor64k(absPath);
+			if (currentHash && currentHash === cached.contentHash) {
+				state.cache.delete(absPath);
+				state.cache.set(absPath, cached);
+				return cached.map;
+			}
+		}
+		if (!persistenceEnabled()) {
+			const map = await generateMap(absPath);
+			const hash = await contentHashFor64k(absPath);
+			rememberInMemory(absPath, { mtimeMs, contentHash: hash, map });
+			return map;
+		}
+
+		let preContentHash = "";
+		try {
+			preContentHash = await contentHashFor64k(absPath);
+			if (preContentHash) {
+				const key = computeKey(
+					absPath,
+					mtimeMs,
+					preContentHash,
+					READSEEK_MAPPER_IDENTITY.mapperName,
+					READSEEK_MAPPER_IDENTITY.mapperVersion,
+				);
+				const fromDisk = await readCached(key);
+				if (fromDisk) {
+					rememberInMemory(absPath, { mtimeMs, contentHash: preContentHash, map: fromDisk });
+					return fromDisk;
+				}
+			}
+		} catch {
+			// fall through to regeneration on a disk-cache miss
+		}
+		const { map, mapperName, mapperVersion } = await generateMapWithIdentity(absPath);
+		const persistentIdentity = { mapperName, mapperVersion };
+		let stableHash: string | null = null;
+		let shouldRemember = true;
+		if (preContentHash) {
+			try {
+				stableHash = await stableContentHash(absPath, mtimeMs, preContentHash);
+				shouldRemember = stableHash !== null;
+			} catch {
+				shouldRemember = false;
+			}
+		}
+		if (shouldRemember) {
+			const hash = stableHash ?? preContentHash ?? "";
+			rememberInMemory(absPath, { mtimeMs, contentHash: hash, map });
+		}
+		if (map && stableHash) {
+			try {
+				const key = computeKey(
+					absPath,
+					mtimeMs,
+					stableHash,
+					persistentIdentity.mapperName,
+					persistentIdentity.mapperVersion,
+				);
+				await writeCached(key, map);
+			} catch {
+				// never fail the caller on a cache-write miss
+			}
+		}
+		return map;
+	} catch {
+		return null;
+	}
+}
+export function setMapCacheMaxSize(size: number): void {
+	getMapCacheState().maxSize = size;
+}
+
+/**
+ * Clear the map cache. Exported for testing.
+ */
+export function clearMapCache(): void {
+	const state = getMapCacheState();
+	state.cache.clear();
+	state.maxSize = MAP_CACHE_MAX_SIZE;
+}
+
+export function __getInMemoryMapCacheSizeForTest(): number {
+	return getMapCacheState().cache.size;
+}

package/src/path-utils.ts

@@ -0,0 +1,24 @@
+import * as os from "os";
+import { isAbsolute, resolve as resolvePath } from "path";
+
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+
+function normalizeUnicodeSpaces(str: string): string {
+	return str.replace(UNICODE_SPACES, " ");
+}
+
+function normalizeAtPrefix(filePath: string): string {
+	return filePath.startsWith("@") ? filePath.slice(1) : filePath;
+}
+
+function expandPath(filePath: string): string {
+	const normalized = normalizeUnicodeSpaces(normalizeAtPrefix(filePath));
+	if (normalized === "~") return os.homedir();
+	if (normalized.startsWith("~/")) return os.homedir() + normalized.slice(1);
+	return normalized;
+}
+
+export function resolveToCwd(filePath: string, cwd: string): string {
+	const expanded = expandPath(filePath);
+	return isAbsolute(expanded) ? expanded : resolvePath(cwd, expanded);
+}