pi-readseek 0.1.0

package/src/readseek-client.ts

@@ -0,0 +1,343 @@
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { DetailLevel } from "./readseek/enums.js";
+import type { FileMap, FileSymbol } from "./readseek/types.js";
+import { SymbolKind } from "./readseek/enums.js";
+
+interface ReadseekHashline {
+	line: number;
+	hash: string;
+	text: string;
+}
+
+export interface ReadseekReadOutput {
+	file: string;
+	language: string;
+	line_count: number;
+	file_hash: string;
+	start_line: number;
+	end_line: number;
+	hashlines: ReadseekHashline[];
+}
+
+interface ReadseekSymbol {
+	kind: string;
+	name: string;
+	address: string;
+	start_line: number;
+	end_line: number;
+	start_hash: string;
+	end_hash: string;
+}
+
+interface ReadseekMapOutput {
+	file: string;
+	language: string;
+	line_count: number;
+	file_hash: string;
+	symbols: ReadseekSymbol[];
+}
+
+export interface ReadseekSearchCapture {
+	name: string;
+	start_line: number;
+	end_line: number;
+	start_hash: string;
+	end_hash: string;
+	hashlines: ReadseekHashline[];
+}
+
+export interface ReadseekSearchMatch {
+	pattern_index: number;
+	start_line: number;
+	end_line: number;
+	start_hash: string;
+	end_hash: string;
+	hashlines: ReadseekHashline[];
+	captures: ReadseekSearchCapture[];
+}
+
+export interface ReadseekSearchFileOutput {
+	file: string;
+	language: string;
+	file_hash: string;
+	matches: ReadseekSearchMatch[];
+}
+
+interface ReadseekSearchOutput {
+	results: ReadseekSearchFileOutput[];
+}
+
+function normalizeLanguage(language: string): string {
+	return language === "java" ? "Java" : language;
+}
+
+function normalizeKind(kind: string): FileSymbol["kind"] {
+	if (kind === "constructor") return SymbolKind.Method;
+	if (Object.values(SymbolKind).includes(kind as SymbolKind)) return kind as FileSymbol["kind"];
+	return SymbolKind.Unknown;
+}
+
+function symbolsFromReadseek(symbols: ReadseekSymbol[]): FileSymbol[] {
+	const byAddress = new Map<string, FileSymbol[]>();
+	const entries: Array<{ address: string; parentAddress: string; symbol: FileSymbol }> = [];
+
+	for (const symbol of symbols) {
+		const address = symbol.address || symbol.name;
+		const parentAddress = address.includes(".") ? address.slice(0, address.lastIndexOf(".")) : "";
+		const fileSymbol: FileSymbol = {
+			name: symbol.name,
+			kind: normalizeKind(symbol.kind),
+			startLine: symbol.start_line,
+			endLine: symbol.end_line,
+		};
+		const bucket = byAddress.get(address);
+		if (bucket) bucket.push(fileSymbol);
+		else byAddress.set(address, [fileSymbol]);
+		entries.push({ address, parentAddress, symbol: fileSymbol });
+	}
+
+	const roots: FileSymbol[] = [];
+	for (const entry of entries) {
+		const parent = entry.parentAddress ? byAddress.get(entry.parentAddress)?.[0] : undefined;
+		if (parent) {
+			parent.children ??= [];
+			parent.children.push(entry.symbol);
+		} else {
+			roots.push(entry.symbol);
+		}
+	}
+
+	return roots;
+}
+
+const require = createRequire(import.meta.url);
+
+function readseekPackageDir(): string {
+	return path.dirname(require.resolve("@jarkkojs/readseek/package.json"));
+}
+
+export function readseekBinaryPath(): string {
+	const platformPackage = (() => {
+		switch (process.platform) {
+			case "darwin":
+				return "@jarkkojs/readseek-darwin-arm64";
+			case "linux":
+				return "@jarkkojs/readseek-linux-x64";
+			case "win32":
+				return "@jarkkojs/readseek-win32-x64";
+			default:
+				throw new Error(`unsupported readseek platform: ${process.platform}`);
+		}
+	})();
+
+	const packageJson = require.resolve(`${platformPackage}/package.json`, { paths: [readseekPackageDir()] });
+	return path.join(path.dirname(packageJson), "bin", process.platform === "win32" ? "readseek.exe" : "readseek");
+}
+
+export function isReadseekAvailable(): boolean {
+	try {
+		readseekBinaryPath();
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function runReadseek(args: string[], options: { signal?: AbortSignal } = {}): Promise<unknown> {
+	const { stdout, stderr } = await new Promise<{ stdout: string; stderr: string }>((resolve, reject) => {
+		const child = spawn(readseekBinaryPath(), args, { stdio: ["ignore", "pipe", "pipe"], signal: options.signal });
+		const stdoutChunks: Buffer[] = [];
+		const stderrChunks: Buffer[] = [];
+		let stdoutBytes = 0;
+
+		child.stdout.on("data", (chunk: Buffer) => {
+			stdoutBytes += chunk.length;
+			if (stdoutBytes > 32 * 1024 * 1024) {
+				child.kill();
+				reject(new Error("readseek output exceeded 32 MiB"));
+				return;
+			}
+			stdoutChunks.push(chunk);
+		});
+		child.stderr.on("data", (chunk: Buffer) => stderrChunks.push(chunk));
+		child.on("error", (error: any) => reject(error));
+		child.on("close", (code) => {
+			const stdout = Buffer.concat(stdoutChunks).toString("utf-8");
+			const stderr = Buffer.concat(stderrChunks).toString("utf-8").trim();
+			if (code === 0) resolve({ stdout, stderr });
+			else reject(new Error((stderr || `readseek exited with status ${code}`).replace(/^error:\s*/i, "")));
+		});
+	});
+	void stderr;
+	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}`);
+	return value;
+}
+
+function requireString(value: unknown, field: string): string {
+	if (typeof value !== "string") throw new Error(`invalid readseek ${field}`);
+	return value;
+}
+
+function parseReadOutput(value: unknown): ReadseekReadOutput {
+	if (!value || typeof value !== "object") throw new Error("invalid readseek read output");
+	const output = value as Record<string, unknown>;
+	const hashlines = output.hashlines;
+	if (!Array.isArray(hashlines)) throw new Error("invalid readseek hashlines");
+	return {
+		file: requireString(output.file, "file"),
+		language: requireString(output.language, "language"),
+		line_count: requireNumber(output.line_count, "line_count"),
+		file_hash: requireString(output.file_hash, "file_hash"),
+		start_line: requireNumber(output.start_line, "start_line"),
+		end_line: requireNumber(output.end_line, "end_line"),
+		hashlines: hashlines.map((line) => {
+			if (!line || typeof line !== "object") throw new Error("invalid readseek hashline");
+			const item = line as Record<string, unknown>;
+			return {
+				line: requireNumber(item.line, "hashline.line"),
+				hash: requireString(item.hash, "hashline.hash"),
+				text: requireString(item.text, "hashline.text"),
+			};
+		}),
+	};
+}
+
+function parseMapOutput(value: unknown): ReadseekMapOutput {
+	if (!value || typeof value !== "object") throw new Error("invalid readseek map output");
+	const output = value as Record<string, unknown>;
+	const symbols = output.symbols;
+	if (!Array.isArray(symbols)) throw new Error("invalid readseek symbols");
+	return {
+		file: requireString(output.file, "file"),
+		language: requireString(output.language, "language"),
+		line_count: requireNumber(output.line_count, "line_count"),
+		file_hash: requireString(output.file_hash, "file_hash"),
+		symbols: symbols.map((symbol) => {
+			if (!symbol || typeof symbol !== "object") throw new Error("invalid readseek symbol");
+			const item = symbol as Record<string, unknown>;
+			return {
+				kind: requireString(item.kind, "symbol.kind"),
+				name: requireString(item.name, "symbol.name"),
+				address: requireString(item.address, "symbol.address"),
+				start_line: requireNumber(item.start_line, "symbol.start_line"),
+				end_line: requireNumber(item.end_line, "symbol.end_line"),
+				start_hash: requireString(item.start_hash, "symbol.start_hash"),
+				end_hash: requireString(item.end_hash, "symbol.end_hash"),
+			};
+		}),
+	};
+}
+
+function parseSearchHashlines(value: unknown, field: string): ReadseekHashline[] {
+	if (!Array.isArray(value)) throw new Error(`invalid readseek ${field}`);
+	return value.map((line) => {
+		if (!line || typeof line !== "object") throw new Error(`invalid readseek ${field}`);
+		const item = line as Record<string, unknown>;
+		return {
+			line: requireNumber(item.line, `${field}.line`),
+			hash: requireString(item.hash, `${field}.hash`),
+			text: requireString(item.text, `${field}.text`),
+		};
+	});
+}
+
+function parseSearchOutput(value: unknown): ReadseekSearchOutput {
+	if (!value || typeof value !== "object") throw new Error("invalid readseek search output");
+	const output = value as Record<string, unknown>;
+	if (!Array.isArray(output.results)) throw new Error("invalid readseek search results");
+	return {
+		results: output.results.map((result) => {
+			if (!result || typeof result !== "object") throw new Error("invalid readseek search result");
+			const file = result as Record<string, unknown>;
+			if (!Array.isArray(file.matches)) throw new Error("invalid readseek search matches");
+			return {
+				file: requireString(file.file, "search.file"),
+				language: requireString(file.language, "search.language"),
+				file_hash: requireString(file.file_hash, "search.file_hash"),
+				matches: file.matches.map((match) => {
+					if (!match || typeof match !== "object") throw new Error("invalid readseek search match");
+					const item = match as Record<string, unknown>;
+					if (!Array.isArray(item.captures)) throw new Error("invalid readseek search captures");
+					return {
+						pattern_index: requireNumber(item.pattern_index, "search.match.pattern_index"),
+						start_line: requireNumber(item.start_line, "search.match.start_line"),
+						end_line: requireNumber(item.end_line, "search.match.end_line"),
+						start_hash: requireString(item.start_hash, "search.match.start_hash"),
+						end_hash: requireString(item.end_hash, "search.match.end_hash"),
+						hashlines: parseSearchHashlines(item.hashlines, "search.match.hashlines"),
+						captures: item.captures.map((capture) => {
+							if (!capture || typeof capture !== "object") throw new Error("invalid readseek search capture");
+							const captureItem = capture as Record<string, unknown>;
+							return {
+								name: requireString(captureItem.name, "search.capture.name"),
+								start_line: requireNumber(captureItem.start_line, "search.capture.start_line"),
+								end_line: requireNumber(captureItem.end_line, "search.capture.end_line"),
+								start_hash: requireString(captureItem.start_hash, "search.capture.start_hash"),
+								end_hash: requireString(captureItem.end_hash, "search.capture.end_hash"),
+								hashlines: parseSearchHashlines(captureItem.hashlines, "search.capture.hashlines"),
+							};
+						}),
+					};
+				}),
+			};
+		}),
+	};
+}
+
+export async function readseekRead(filePath: string, startLine: number, endLine: number): Promise<ReadseekReadOutput> {
+	return parseReadOutput(await runReadseek([
+		"read",
+		filePath,
+		"--start",
+		String(startLine),
+		"--end",
+		String(endLine),
+	]));
+}
+
+export async function readseekMap(filePath: string, totalBytes: number): Promise<FileMap | null> {
+	const output = parseMapOutput(await runReadseek(["map", filePath]));
+	if (output.language === "unknown" && output.symbols.length === 0) return null;
+	return {
+		path: filePath,
+		totalLines: output.line_count,
+		totalBytes,
+		language: normalizeLanguage(output.language),
+		detailLevel: DetailLevel.Full,
+		imports: [],
+		symbols: symbolsFromReadseek(output.symbols),
+	};
+}
+
+export async function readseekSearch(
+	target: string,
+	pattern: string,
+	language?: string,
+	signal?: AbortSignal,
+): Promise<ReadseekSearchFileOutput[]> {
+	const args = ["search", target, pattern];
+	if (language) args.push("--language", language);
+	return parseSearchOutput(await runReadseek(args, { signal })).results;
+}
+
+export async function readseekMapContent(filePath: string, content: string): Promise<FileMap | null> {
+	const tempDir = await mkdtemp(path.join(tmpdir(), "readseek-map-"));
+	const tempPath = path.join(tempDir, path.basename(filePath) || `content${path.extname(filePath)}` || "content");
+	try {
+		await writeFile(tempPath, content, "utf8");
+		const map = await readseekMap(tempPath, Buffer.byteLength(content, "utf8"));
+		if (!map) return null;
+		return { ...map, path: filePath };
+	} finally {
+		await rm(tempDir, { recursive: true, force: true });
+	}
+}

package/src/readseek-error-codes.ts

@@ -0,0 +1,54 @@
+/**
+ * READSEEK error code taxonomy — single source of truth.
+ *
+ * Every error returned via `readseekValue.error.code` MUST be a key in this map.
+ * To add a new error: extend this object with a kebab-case code, a one-line
+ * description, and the trigger condition. Codes are stable: renaming is a
+ * breaking change for downstream consumers.
+ *
+ * Distinction:
+ * - errors (this file): fatal — the tool could not produce its primary result.
+ * - warnings (ReadseekWarning): non-fatal — the tool produced a result but flagged
+ *   something the agent should know.
+ */
+export const READSEEK_ERROR_CODES = {
+  // read
+  "file-not-found": { description: "Target file does not exist", trigger: "fs ENOENT on read" },
+  "path-is-directory": { description: "Path resolves to a directory, not a file", trigger: "fs EISDIR on read" },
+  "permission-denied": { description: "Filesystem refused access", trigger: "fs EACCES or EPERM" },
+  "fs-error": { description: "Unexpected filesystem failure outside the specific classified cases", trigger: "non-ENOENT/non-EISDIR/non-EACCES/non-EPERM fs error while reading, writing, or stat'ing a path" },
+  "offset-past-end": { description: "Requested offset exceeds file length", trigger: "offset > total lines" },
+  "invalid-params-combo": { description: "Mutually exclusive parameters combined", trigger: "e.g. symbol + offset, bundle + map, map + symbol" },
+  "invalid-offset": { description: "offset is not a positive integer", trigger: "non-int or value < 1" },
+  "invalid-limit": { description: "limit is not a positive integer", trigger: "non-int or value < 1" },
+
+  // edit
+  "file-not-read": { description: "edit called on a path that was not read in this session", trigger: "wasReadInSession returned false" },
+  "hash-mismatch": { description: "edit anchors do not verify against current file contents", trigger: "applyHashlineEdits detected stale anchors" },
+  "no-op": { description: "edits produced identical content", trigger: "originalNormalized === result after applying edits" },
+  "text-not-found": { description: "replace.old_text not present in file", trigger: "replaceText returned 0 matches" },
+  "binary-file": { description: "edit refused because file is binary", trigger: "isBinaryBuffer detected NUL bytes" },
+  "invalid-edit-variant": { description: "edits[i] is not exactly one of set_line/replace_lines/insert_after/replace", trigger: "exactly-one variant check failed" },
+
+  // grep
+  "binary-file-target": { description: "grep target is a binary file", trigger: "explicit binary path supplied" },
+  "passthrough-unparsed": { description: "builtin grep result format unrecognized", trigger: "passthrough warning from underlying tool" },
+
+  // search
+  "readseek-not-installed": { description: "readseek CLI is not installed", trigger: "ENOENT on `readseek` invocation or bundled package resolution failure" },
+  "readseek-execution-error": { description: "readseek search exited with an error", trigger: "non-zero exit or invalid search output" },
+
+  // find / ls (shared shape)
+  "path-not-found": { description: "search/target path does not exist", trigger: "stat failed on path" },
+  "path-not-directory": { description: "path is a file, not a directory", trigger: "stat returned non-directory" },
+
+  // write
+  "binary-content": { description: "content written to write tool looks binary", trigger: "looksLikeBinary on supplied content" },
+
+  "syntax-regression": {
+    description: "edit introduced new tree-sitter syntax errors compared to pre-edit content",
+    trigger: "post-write validator detected net-new ERROR or MISSING nodes (block mode)",
+  },
+} as const;
+
+export type ReadseekErrorCode = keyof typeof READSEEK_ERROR_CODES;

package/src/readseek-settings.ts

@@ -0,0 +1,287 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface ReadseekJsonSettings {
+  grep?: { maxLines?: number; maxBytes?: number };
+  mapCache?: { dir?: string; enabled?: boolean };
+  edit?: { diffDisplay?: "collapsed" | "expanded" };
+}
+
+export interface ReadseekSettingsWarning {
+  source: string;
+  message: string;
+  path?: string;
+}
+
+export interface ReadseekSettingsResult {
+  settings: ReadseekJsonSettings;
+  warnings: ReadseekSettingsWarning[];
+}
+
+let pathOverride: { globalSettingsPath?: string; projectSettingsPath?: string } | null = null;
+
+export function __setReadseekSettingsPathsForTest(paths: {
+  globalSettingsPath?: string;
+  projectSettingsPath?: string;
+}): void {
+  pathOverride = { ...paths };
+}
+
+export function __resetReadseekSettingsPathsForTest(): void {
+  pathOverride = null;
+}
+
+function defaultGlobalSettingsPath(): string {
+  return join(homedir(), ".pi/agent/readseek/settings.json");
+}
+
+function defaultProjectSettingsPath(): string {
+  return join(process.cwd(), ".pi/readseek/settings.json");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function invalid(source: string, path: string): ReadseekSettingsWarning {
+  return { source, path, message: `Invalid readseek setting at ${path}` };
+}
+
+function readJsonObjectEnd(text: string, open: number): number {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+
+  for (let i = open; i < text.length; i += 1) {
+    const char = text[i];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === '"') inString = false;
+      continue;
+    }
+
+    if (char === '"') {
+      inString = true;
+    } else if (char === "{") {
+      depth += 1;
+    } else if (char === "}") {
+      depth -= 1;
+      if (depth === 0) return i;
+    }
+  }
+
+  return -1;
+}
+
+function readJsonStringEnd(text: string, quote: number): number {
+  let escaped = false;
+  for (let i = quote + 1; i < text.length; i += 1) {
+    const char = text[i];
+    if (escaped) escaped = false;
+    else if (char === "\\") escaped = true;
+    else if (char === '"') return i;
+  }
+  return -1;
+}
+
+function readTopLevelObjectBodies(rawText: string, section: string): string[] {
+  const bodies: string[] = [];
+  let depth = 0;
+
+  for (let i = 0; i < rawText.length; i += 1) {
+    const char = rawText[i];
+    if (char === '"') {
+      const end = readJsonStringEnd(rawText, i);
+      if (end < 0) return bodies;
+
+      if (depth === 1) {
+        const fieldName = rawText.slice(i + 1, end);
+        let cursor = end + 1;
+        while (/\s/.test(rawText[cursor] ?? "")) cursor += 1;
+
+        if (rawText[cursor] === ":") {
+          cursor += 1;
+          while (/\s/.test(rawText[cursor] ?? "")) cursor += 1;
+          if (fieldName === section && rawText[cursor] === "{") {
+            const objectEnd = readJsonObjectEnd(rawText, cursor);
+            if (objectEnd < 0) return bodies;
+            bodies.push(rawText.slice(cursor + 1, objectEnd));
+            i = objectEnd;
+            continue;
+          }
+        }
+      }
+      i = end;
+    } else if (char === "{") {
+      depth += 1;
+    } else if (char === "}") {
+      depth = Math.max(0, depth - 1);
+    }
+  }
+
+  return bodies;
+}
+
+function rawFieldTokens(rawText: string, path: string): string[] {
+  const [section, key] = path.split(".");
+  const bodies = readTopLevelObjectBodies(rawText, section);
+  if (bodies.length !== 1) return [];
+
+  const body = bodies[0];
+  const tokens: string[] = [];
+  let depth = 0;
+
+  for (let i = 0; i < body.length; i += 1) {
+    const char = body[i];
+    if (char === '"') {
+      const end = readJsonStringEnd(body, i);
+      if (end < 0) return tokens;
+
+      if (depth === 0) {
+        const fieldName = body.slice(i + 1, end);
+        let cursor = end + 1;
+        while (/\s/.test(body[cursor] ?? "")) cursor += 1;
+
+        if (body[cursor] === ":") {
+          cursor += 1;
+          while (/\s/.test(body[cursor] ?? "")) cursor += 1;
+          if (fieldName === key) {
+            const valueStart = cursor;
+            while (cursor < body.length && !/[,}\s]/.test(body[cursor])) cursor += 1;
+            tokens.push(body.slice(valueStart, cursor));
+          }
+        }
+      }
+      i = end;
+    } else if (char === "{" || char === "[") {
+      depth += 1;
+    } else if (char === "}" || char === "]") {
+      depth = Math.max(0, depth - 1);
+    }
+  }
+
+  return tokens;
+}
+
+function isStrictJsonPositiveInteger(rawText: string, path: string, value: unknown): value is number {
+  const tokens = rawFieldTokens(rawText, path);
+  return (
+    typeof value === "number" &&
+    Number.isSafeInteger(value) &&
+    value > 0 &&
+    tokens.length === 1 &&
+    /^[1-9][0-9]*$/.test(tokens[0])
+  );
+}
+
+function readPositive(
+  raw: Record<string, unknown>,
+  key: string,
+  path: string,
+  source: string,
+  rawText: string,
+  warnings: ReadseekSettingsWarning[],
+): number | undefined {
+  if (!(key in raw)) return undefined;
+  if (isStrictJsonPositiveInteger(rawText, path, raw[key])) return raw[key];
+  warnings.push(invalid(source, path));
+  return undefined;
+}
+
+function readBoolean(
+  raw: Record<string, unknown>,
+  key: string,
+  path: string,
+  source: string,
+  warnings: ReadseekSettingsWarning[],
+): boolean | undefined {
+  if (!(key in raw)) return undefined;
+  if (typeof raw[key] === "boolean") return raw[key];
+  warnings.push(invalid(source, path));
+  return undefined;
+}
+
+function validateSettings(raw: unknown, source: string, rawText: string): ReadseekSettingsResult {
+  const settings: ReadseekJsonSettings = {};
+  const warnings: ReadseekSettingsWarning[] = [];
+  if (!isRecord(raw)) return { settings, warnings };
+
+  if (isRecord(raw.grep)) {
+    const grep: NonNullable<ReadseekJsonSettings["grep"]> = {};
+    const maxLines = readPositive(raw.grep, "maxLines", "grep.maxLines", source, rawText, warnings);
+    if (maxLines !== undefined) grep.maxLines = maxLines;
+    const maxBytes = readPositive(raw.grep, "maxBytes", "grep.maxBytes", source, rawText, warnings);
+    if (maxBytes !== undefined) grep.maxBytes = maxBytes;
+    if (Object.keys(grep).length > 0) settings.grep = grep;
+  }
+
+  if (isRecord(raw.mapCache)) {
+    const mapCache: NonNullable<ReadseekJsonSettings["mapCache"]> = {};
+    if ("dir" in raw.mapCache) {
+      if (typeof raw.mapCache.dir === "string" && raw.mapCache.dir.length > 0) mapCache.dir = raw.mapCache.dir;
+      else warnings.push(invalid(source, "mapCache.dir"));
+    }
+    const enabled = readBoolean(raw.mapCache, "enabled", "mapCache.enabled", source, warnings);
+    if (enabled !== undefined) mapCache.enabled = enabled;
+    if (Object.keys(mapCache).length > 0) settings.mapCache = mapCache;
+  }
+
+  if (isRecord(raw.edit)) {
+    const edit: NonNullable<ReadseekJsonSettings["edit"]> = {};
+    if ("diffDisplay" in raw.edit) {
+      const value = raw.edit.diffDisplay;
+      if (value === "collapsed" || value === "expanded") edit.diffDisplay = value;
+      else warnings.push(invalid(source, "edit.diffDisplay"));
+    }
+    if (Object.keys(edit).length > 0) settings.edit = edit;
+  }
+
+  return { settings, warnings };
+}
+
+function readSettingsFile(path: string): ReadseekSettingsResult {
+  if (!existsSync(path)) return { settings: {}, warnings: [] };
+
+  try {
+    const text = readFileSync(path, "utf8");
+    return validateSettings(JSON.parse(text) as unknown, path, text);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { settings: {}, warnings: [{ source: path, message: `Invalid JSON: ${message}` }] };
+  }
+}
+
+function mergeSettings(base: ReadseekJsonSettings, override: ReadseekJsonSettings): ReadseekJsonSettings {
+  const merged: ReadseekJsonSettings = {};
+  const grep = { ...(base.grep ?? {}), ...(override.grep ?? {}) };
+  if (Object.keys(grep).length > 0) merged.grep = grep;
+  const mapCache = { ...(base.mapCache ?? {}), ...(override.mapCache ?? {}) };
+  if (Object.keys(mapCache).length > 0) merged.mapCache = mapCache;
+  const edit = { ...(base.edit ?? {}), ...(override.edit ?? {}) };
+  if (Object.keys(edit).length > 0) merged.edit = edit;
+  return merged;
+}
+
+export function resolveReadseekJsonSettings(): ReadseekSettingsResult {
+  const globalPath = pathOverride?.globalSettingsPath ?? defaultGlobalSettingsPath();
+  const projectPath = pathOverride?.projectSettingsPath ?? defaultProjectSettingsPath();
+  const globalResult = readSettingsFile(globalPath);
+  const projectResult = readSettingsFile(projectPath);
+  return {
+    settings: mergeSettings(globalResult.settings, projectResult.settings),
+    warnings: [...globalResult.warnings, ...projectResult.warnings],
+  };
+}
+
+export function resolveEditDiffDisplay(env: NodeJS.ProcessEnv = process.env): "collapsed" | "expanded" {
+  const raw = env.PI_HASHLINE_EDIT_DIFF_DISPLAY;
+  if (typeof raw === "string") {
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "expanded" || normalized === "collapsed") return normalized;
+  }
+  const json = resolveReadseekJsonSettings().settings.edit?.diffDisplay;
+  if (json === "expanded" || json === "collapsed") return json;
+  return "collapsed";
+}