pi-readseek 0.3.21 → 0.3.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.3.21",
+  "version": "0.3.23",
   "description": "Pi extension for readseek-backed hash-anchored read/edit/grep, structural code maps, structural search, and file exploration",
   "type": "module",
   "exports": {
@@ -39,7 +39,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.3.17",
+    "@jarkkojs/readseek": "^0.3.20",
     "diff": "^8.0.3",
     "ignore": "^7.0.5",
     "picomatch": "^4.0.4",

package/src/coerce-obvious-int.ts

@@ -1,30 +1,41 @@
 const BASE10_INT_RE = /^-?\d+$/;
+const MIN_SAFE_INTEGER = BigInt(Number.MIN_SAFE_INTEGER);
+const MAX_SAFE_INTEGER = BigInt(Number.MAX_SAFE_INTEGER);
 
 type CoercedIntResult =
   | { ok: true; value: number | undefined }
   | { ok: false; message: string };
 
+function formatReceived(value: unknown): string {
+  if (typeof value === "number" || typeof value === "bigint") return String(value);
+  return JSON.stringify(value) ?? String(value);
+}
+
+function invalidInteger(value: unknown, name: string): CoercedIntResult {
+  return {
+    ok: false,
+    message: `Invalid ${name}: expected a safe base-10 integer, received ${formatReceived(value)}.`,
+  };
+}
+
 export function coerceObviousBase10Int(value: unknown, name: string): CoercedIntResult {
   if (value === undefined) {
     return { ok: true, value: undefined };
   }
 
   if (typeof value === "number") {
-    if (Number.isInteger(value)) {
+    if (Number.isSafeInteger(value)) {
       return { ok: true, value };
     }
-    return {
-      ok: false,
-      message: `Invalid ${name}: expected a base-10 integer, received ${value}.`,
-    };
+    return invalidInteger(value, name);
   }
 
   if (typeof value === "string" && BASE10_INT_RE.test(value)) {
-    return { ok: true, value: Number.parseInt(value, 10) };
+    const parsed = BigInt(value);
+    if (parsed >= MIN_SAFE_INTEGER && parsed <= MAX_SAFE_INTEGER) {
+      return { ok: true, value: Number(parsed) };
+    }
   }
 
-  return {
-    ok: false,
-    message: `Invalid ${name}: expected a base-10 integer, received ${JSON.stringify(value)}.`,
-  };
+  return invalidInteger(value, name);
 }

package/src/edit-output.ts

@@ -19,6 +19,19 @@ export interface EditOutputResult {
   patch: string;
   readseekValue: ReturnType<typeof buildReadseekEditResult>;
 }
+
+const EDIT_OPERATION_NAMES = ["set_line", "replace_lines", "insert_after", "replace"] as const;
+
+type EditOperationName = (typeof EDIT_OPERATION_NAMES)[number];
+
+type EditOperationWithNewText = {
+  new_text: string;
+};
+
+function hasNewText(value: unknown): value is EditOperationWithNewText {
+  return typeof value === "object" && value !== null && typeof (value as { new_text?: unknown }).new_text === "string";
+}
+
 function getVisibleDiffStats(diff: string): { added: number; removed: number } {
   const stats = parseDiffStats(diff);
   if (stats.added > 0 || stats.removed > 0) return stats;
@@ -49,10 +62,12 @@ function extractNewTextValues(edits: unknown[] | undefined): string[] {
   const values: string[] = [];
   for (const edit of edits ?? []) {
     if (!edit || typeof edit !== "object") continue;
-    if ("set_line" in edit && typeof (edit as any).set_line?.new_text === "string") values.push((edit as any).set_line.new_text);
-    if ("replace_lines" in edit && typeof (edit as any).replace_lines?.new_text === "string") values.push((edit as any).replace_lines.new_text);
-    if ("insert_after" in edit && typeof (edit as any).insert_after?.new_text === "string") values.push((edit as any).insert_after.new_text);
-    if ("replace" in edit && typeof (edit as any).replace?.new_text === "string") values.push((edit as any).replace.new_text);
+
+    const operations = edit as Partial<Record<EditOperationName, unknown>>;
+    for (const operationName of EDIT_OPERATION_NAMES) {
+      const operation = operations[operationName];
+      if (hasNewText(operation)) values.push(operation.new_text);
+    }
   }
   return values;
 }
@@ -62,10 +77,13 @@ function formatWhitespaceOnlyWarning(semanticSummary: SemanticSummary | undefine
   return "⚠ Edit classified as whitespace-only — if you intended a behavior change, re-read to verify.";
 }
 function formatSemanticSuffix(semanticSummary: SemanticSummary | undefined): string {
-  const movedBlocks = semanticSummary?.movedBlocks ?? 0;
+  if (!semanticSummary) return "";
+
+  const movedBlocks = semanticSummary.movedBlocks ?? 0;
   if (movedBlocks <= 0) return "";
+
   const blockWord = movedBlocks === 1 ? "block" : "blocks";
-  return ` [semantic: ${semanticSummary!.classification}, ${movedBlocks} ${blockWord} moved]`;
+  return ` [semantic: ${semanticSummary.classification}, ${movedBlocks} ${blockWord} moved]`;
 }
 function formatReplaceHint(edits: unknown[] | undefined, noopEdits: unknown[]): string | undefined {
   if ((noopEdits ?? []).length > 0) return undefined;

package/src/grep-output.ts

@@ -47,6 +47,14 @@ export interface GrepOutputGroup {
   };
 }
 
+type ScopedGrepOutputGroup = GrepOutputGroup & {
+  scope: NonNullable<GrepOutputGroup["scope"]>;
+};
+
+function hasScope(group: GrepOutputGroup): group is ScopedGrepOutputGroup {
+  return group.scope !== undefined;
+}
+
 export interface BuildGrepOutputInput {
   summary: boolean;
   totalMatches: number;
@@ -100,13 +108,13 @@ function buildScopeMetadata(groups: GrepOutputGroup[], warnings: GrepScopeWarnin
   return {
     mode: "symbol" as const,
     groups: groups
-      .filter((group) => group.scope)
+      .filter(hasScope)
       .map((group) => ({
         path: group.absolutePath,
         displayPath: group.displayPath,
-        symbol: group.scope!.symbol,
+        symbol: group.scope.symbol,
         matchCount: group.matchCount,
-        matchLines: [...group.scope!.matchLines],
+        matchLines: [...group.scope.matchLines],
         lineAnchors: group.entries.flatMap((entry) => (entry.kind === "separator" ? [] : [entry.line.anchor])),
       })),
     warnings: [...warnings],
@@ -132,14 +140,16 @@ export function buildGrepOutput(input: BuildGrepOutputInput): GrepOutputResult {
     }
     text = blocks.join("\n");
   }
-  if ((input.passthroughLines?.length ?? 0) > 0) {
-    text += `\n\n${input.passthroughLines!.join("\n")}`;
+  const passthroughLines = input.passthroughLines ?? [];
+  if (passthroughLines.length > 0) {
+    text += `\n\n${passthroughLines.join("\n")}`;
   }
   if (input.limit !== undefined && input.totalMatches === input.limit) {
     text += `\n\n[Results truncated at ${input.limit} matches — refine pattern or increase limit]`;
   }
-  if (!input.summary && input.scopeMode === "symbol" && (input.scopeWarnings?.length ?? 0) > 0) {
-    text = `${input.scopeWarnings!.map((warning) => warning.message).join("\n\n")}\n\n${text}`;
+  const scopeWarnings = input.scopeWarnings ?? [];
+  if (!input.summary && input.scopeMode === "symbol" && scopeWarnings.length > 0) {
+    text = `${scopeWarnings.map((warning) => warning.message).join("\n\n")}\n\n${text}`;
   }
   const budget = resolveGrepOutputBudget();
   const truncated = truncateHead(text, {
@@ -161,7 +171,7 @@ export function buildGrepOutput(input: BuildGrepOutputInput): GrepOutputResult {
     })),
   };
   if (!input.summary && input.scopeMode === "symbol") {
-    readseekValue.scopes = buildScopeMetadata(input.groups, input.scopeWarnings ?? []);
+    readseekValue.scopes = buildScopeMetadata(input.groups, scopeWarnings);
   }
 
   return {

package/src/grep.ts

@@ -313,6 +313,16 @@ export async function executeGrep(opts: ExecuteGrepOptions): Promise<any> {
 	let candidateUnparsedCount = 0;
 	const candidateLinePattern = /^.+(?::|-)\d+(?::|-)\s/;
 
+	const addSummaryMatch = (displayPath: string, absolutePath: string) => {
+		let group = groupsByPath.get(displayPath);
+		if (!group) {
+			group = { displayPath, absolutePath, matchCount: 0, entries: [] };
+			groupsByPath.set(displayPath, group);
+		}
+		group.matchCount++;
+		totalMatches++;
+	};
+
 	const addEntry = (displayPath: string, absolutePath: string, kind: "match" | "context", line: ReadseekLine) => {
 		let group = groupsByPath.get(displayPath);
 		if (!group) {
@@ -341,6 +351,12 @@ export async function executeGrep(opts: ExecuteGrepOptions): Promise<any> {
 		}
 		parsedCount++;
 		const absolute = toAbsolutePath(parsed.displayPath);
+		if (p.summary) {
+			if (parsed.kind === "match") {
+				addSummaryMatch(parsed.displayPath, absolute);
+			}
+			continue;
+		}
 		const fileLines = await getFileLines(absolute);
 		if (fileLines === undefined) continue;
 		// Bare-CR remapping: rg treats the entire bare-CR file as line 1, and the
@@ -379,6 +395,25 @@ export async function executeGrep(opts: ExecuteGrepOptions): Promise<any> {
 		});
 	}
 
+	if (p.summary && parsedCount === 0 && candidateUnparsedCount > 0) {
+		const passthroughDetails =
+			typeof result.details === "object" && result.details !== null
+				? (result.details as Record<string, unknown>)
+				: {};
+		return {
+			...result,
+			details: {
+				...passthroughDetails,
+				readseekValue: {
+					tool: "grep",
+					summary: true,
+					totalMatches: 0,
+					records: [],
+				},
+			},
+		};
+	}
+
 	if (parsedCount === 0 && candidateUnparsedCount > 0) {
 		const warning =
 			"[hashline grep passthrough] Unparsed grep format; returned original output.";
@@ -405,7 +440,7 @@ export async function executeGrep(opts: ExecuteGrepOptions): Promise<any> {
 		};
 	}
 
-	const summary = p.summary;
+	const summary = !!p.summary;
 	const effectiveLimit = typeof p.limit === "number" ? p.limit : 100;
 	const groups = [...groupsByPath.values()];
 	for (const group of groups) {

package/src/hashline.ts

@@ -71,13 +71,16 @@ interface HashlineGlobalState {
 
 const HASHLINE_STATE_KEY = Symbol.for("pi-readseek.hashlineState.v1");
 
+type HashlineGlobalSlots = typeof globalThis & Record<symbol, HashlineGlobalState | undefined>;
+
 function getHashlineState(): HashlineGlobalState {
-	const globalObject = globalThis as any;
-	globalObject[HASHLINE_STATE_KEY] ??= {
+	const globalObject = globalThis as HashlineGlobalSlots;
+	const state = globalObject[HASHLINE_STATE_KEY] ?? {
 		h32Fn: null,
 		initPromise: null,
-	} satisfies HashlineGlobalState;
-	return globalObject[HASHLINE_STATE_KEY] as HashlineGlobalState;
+	};
+	globalObject[HASHLINE_STATE_KEY] = state;
+	return state;
 }
 
 export async function ensureHashInit(): Promise<void> {
@@ -123,6 +126,7 @@ export function parseLineRef(ref: string): { line: number; hash: string; content
 	const match = normalized.match(new RegExp(`^(\\d+):([0-9a-fA-F]{${HASH_LEN}})$`));
 	if (!match) throw new Error(`Invalid line reference "${ref}". Expected "LINE:HASH" (e.g. "5:abc").`);
 	const line = Number.parseInt(match[1], 10);
+	if (!Number.isSafeInteger(line)) throw new Error(`Line number must be a safe integer, got ${match[1]} in "${ref}".`);
 	if (line < 1) throw new Error(`Line number must be >= 1, got ${line} in "${ref}".`);
 	return { line, hash: match[2], content: contentAfterPipe };
 }

package/src/map-cache.ts

@@ -17,14 +17,17 @@ interface MapCacheGlobalState {
 
 const MAP_CACHE_STATE_KEY = Symbol.for("pi-readseek.mapCacheState.v1");
 
+type MapCacheGlobalSlots = typeof globalThis & Record<symbol, MapCacheGlobalState | undefined>;
+
 function getMapCacheState(): MapCacheGlobalState {
-	const globalObject = globalThis as any;
-	globalObject[MAP_CACHE_STATE_KEY] ??= {
+	const globalObject = globalThis as MapCacheGlobalSlots;
+	const state = globalObject[MAP_CACHE_STATE_KEY] ?? {
 		cache: new Map<string, CacheEntry>(),
 		inflight: new Map<string, Promise<FileMap | null>>(),
 		maxSize: MAP_CACHE_MAX_SIZE,
-	} satisfies MapCacheGlobalState;
-	return globalObject[MAP_CACHE_STATE_KEY] as MapCacheGlobalState;
+	};
+	globalObject[MAP_CACHE_STATE_KEY] = state;
+	return state;
 }
 
 function rememberInMemory(absPath: string, entry: CacheEntry): void {

package/src/read.ts

@@ -40,7 +40,7 @@ interface ReadParams {
 	limit?: number | string;
 	symbol?: string;
 	map?: boolean;
-	bundle?: "local";
+	bundle?: string;
 }
 
 interface ReadToolOptions {
@@ -56,6 +56,15 @@ export interface ExecuteReadOptions {
 	onSuccessfulRead?: FileAnchoredCallback;
 }
 
+function hasReadAnchors(result: AgentToolResult<any>): boolean {
+	const details = (result as { details?: unknown }).details;
+	if (!details || typeof details !== "object") return false;
+	const readseekValue = (details as { readseekValue?: unknown }).readseekValue;
+	if (!readseekValue || typeof readseekValue !== "object") return false;
+	const lines = (readseekValue as { lines?: unknown }).lines;
+	return Array.isArray(lines) && lines.length > 0;
+}
+
 export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolResult<any>> {
 	const { toolCallId, params, signal, onUpdate, cwd, onSuccessfulRead } = opts;
 	await ensureHashInit();
@@ -76,10 +85,16 @@ export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolRe
 		const message = `Invalid offset: expected a positive integer, received ${offset.value}.`;
 		return buildToolErrorResult("read", "invalid-offset", message, { path: rawParams.path });
 	}
+	const rawBundle = typeof rawParams.bundle === "string" ? rawParams.bundle.trim() : undefined;
+	const requestedMapViaBundle =
+		rawBundle === "map" ||
+		(rawBundle === "local" && rawParams.symbol === undefined && rawParams.map !== false);
 	const p = {
 		...rawParams,
 		offset: offset.value,
 		limit: limit.value,
+		map: rawParams.map === true || requestedMapViaBundle,
+		bundle: requestedMapViaBundle ? undefined : rawBundle,
 	};
 	if (rawParams.symbol !== undefined) {
 		const trimmedSymbol = typeof rawParams.symbol === "string" ? rawParams.symbol.trim() : "";
@@ -93,13 +108,17 @@ export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolRe
 	const absolutePath = resolveToCwd(rawPath, cwd);
 	const succeed = <T extends AgentToolResult<any>>(result: T): T => {
 		const isError = (result as { isError?: boolean }).isError;
-		if (!isError) {
+		if (!isError && hasReadAnchors(result)) {
 			onSuccessfulRead?.(absolutePath);
 		}
 		return result;
 	};
 
 	throwIfAborted(signal);
+	if (p.bundle !== undefined && p.bundle !== "local") {
+		const message = `Invalid bundle: expected "local", received ${JSON.stringify(p.bundle)}.`;
+		return buildToolErrorResult("read", "invalid-params-combo", message, { path: rawParams.path });
+	}
 	if (p.symbol && (p.offset !== undefined || p.limit !== undefined)) {
 		const message = "Cannot combine symbol with offset/limit. Use one or the other.";
 		return buildToolErrorResult("read", "invalid-params-combo", message, { path: rawParams.path });

package/src/readseek-client.ts

@@ -1,5 +1,7 @@
 import { spawn, type StdioOptions } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
+import { homedir } from "node:os";
 import path from "node:path";
 
 import { DetailLevel } from "./readseek/enums.js";
@@ -165,6 +167,8 @@ function symbolsFromReadseek(symbols: ReadseekSymbol[]): FileSymbol[] {
 }
 
 const require = createRequire(import.meta.url);
+const READSEEK_REPO_PACKAGE_NAMES = new Set(["@jarkkojs/readseek", "readseek"]);
+let defaultReadseekDirInit: Promise<string | null> | undefined;
 
 function readseekPackageDir(): string {
 	return path.dirname(require.resolve("@jarkkojs/readseek/package.json"));
@@ -199,12 +203,39 @@ export function isReadseekAvailable(): boolean {
 	}
 }
 
-interface RunReadseekOptions {
-	signal?: AbortSignal;
-	stdin?: string;
+function directoryExists(dirPath: string): boolean {
+	try {
+		return statSync(dirPath).isDirectory();
+	} catch {
+		return false;
+	}
 }
 
-async function runReadseekRaw(args: string[], options: RunReadseekOptions = {}): Promise<string> {
+function isOwnReadseekRepository(cwd = process.cwd()): boolean {
+	let dir = path.resolve(cwd);
+	while (true) {
+		const packageJsonPath = path.join(dir, "package.json");
+		if (existsSync(packageJsonPath)) {
+			try {
+				const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8")) as { name?: unknown };
+				if (typeof packageJson.name === "string" && READSEEK_REPO_PACKAGE_NAMES.has(packageJson.name)) return true;
+			} catch {
+				// Ignore unreadable or invalid package manifests while walking up.
+			}
+		}
+
+		const parent = path.dirname(dir);
+		if (parent === dir) return false;
+		dir = parent;
+	}
+}
+
+function defaultReadseekDir(): string | null {
+	const home = homedir();
+	return home ? path.join(home, ".pi", "readseek") : null;
+}
+
+async function spawnReadseekRaw(args: string[], options: RunReadseekOptions = {}): Promise<string> {
 	return new Promise<string>((resolve, reject) => {
 		let settled = false;
 		const fail = (error: Error): void => {
@@ -265,13 +296,43 @@ async function runReadseekRaw(args: string[], options: RunReadseekOptions = {}):
 	});
 }
 
+async function ensureDefaultReadseekDir(): Promise<string | null> {
+	const dir = defaultReadseekDir();
+	if (!dir) return null;
+	if (directoryExists(dir)) return dir;
+
+	defaultReadseekDirInit ??= spawnReadseekRaw(["--readseek-dir", dir, "init"])
+		.then(() => (directoryExists(dir) ? dir : null))
+		.catch(() => null)
+		.finally(() => {
+			defaultReadseekDirInit = undefined;
+		});
+	return defaultReadseekDirInit;
+}
+
+async function readseekInvocationArgs(args: string[]): Promise<string[]> {
+	if (isOwnReadseekRepository()) return args;
+
+	const readseekDir = await ensureDefaultReadseekDir();
+	return readseekDir ? ["--readseek-dir", readseekDir, ...args] : args;
+}
+
+interface RunReadseekOptions {
+	signal?: AbortSignal;
+	stdin?: string;
+}
+
+async function runReadseekRaw(args: string[], options: RunReadseekOptions = {}): Promise<string> {
+	return spawnReadseekRaw(await readseekInvocationArgs(args), options);
+}
+
 async function runReadseek(args: string[], options: RunReadseekOptions = {}): Promise<unknown> {
 	const stdout = await runReadseekRaw(args, options);
 	return JSON.parse(stdout) as unknown;
 }
 
 function requireNumber(value: unknown, field: string): number {
-	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`invalid readseek ${field}`);
+	if (typeof value !== "number" || !Number.isSafeInteger(value)) throw new Error(`invalid readseek ${field}: expected safe integer`);
 	return value;
 }