pi-readseek 0.4.29 → 0.5.0

package/src/readseek-client.ts

@@ -7,6 +7,7 @@ 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";
+import { resolveReadSeekTimeoutMs } from "./readseek-settings.js";
 
 export interface ReadSeekHashline {
 	line: number;
@@ -108,21 +109,15 @@ export interface ReadSeekCheckOutput {
 	diagnostics: ReadSeekDiagnostic[];
 }
 
-export interface ReadSeekTranscriptRegion {
-	text: string;
-	quad: [number, number, number, number, number, number, number, number];
-}
-
-export interface ReadSeekTranscript {
-	text: string;
-	regions: ReadSeekTranscriptRegion[];
-}
+export type ReadSeekOcrText = string;
 
 export interface ReadSeekDetectedObject {
 	label: string;
 	bbox: [number, number, number, number];
 }
 
+export type ReadSeekImageMode = "ocr" | "caption" | "objects";
+
 export type ReadSeekDetection =
 	| {
 			kind: "source";
@@ -143,7 +138,7 @@ export type ReadSeekDetection =
 			width: number;
 			height: number;
 			animated: boolean;
-			transcribe?: ReadSeekTranscript;
+			ocr?: ReadSeekOcrText;
 			caption?: string;
 			objects?: ReadSeekDetectedObject[];
 		}
@@ -154,6 +149,8 @@ export type ReadSeekDetection =
 			mime?: string;
 		};
 
+type ReadSeekImageDetection = Extract<ReadSeekDetection, { kind: "image" }>;
+
 interface ReadSeekSearchOptions {
 	language?: string;
 	cached?: boolean;
@@ -162,13 +159,6 @@ interface ReadSeekSearchOptions {
 	signal?: AbortSignal;
 }
 
-interface ReadSeekDetectOptions {
-	transcribe?: boolean;
-	caption?: boolean;
-	objects?: boolean;
-	signal?: AbortSignal;
-}
-
 function normalizeLanguage(language: string): string {
 	return language === "java" ? "Java" : language;
 }
@@ -223,36 +213,43 @@ 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 {
+function readSeekPackageDir(): string {
 	return path.dirname(require.resolve("@jarkkojs/readseek/package.json"));
 }
 
-function readseekBinaryPath(): string {
-	if (process.env.READSEEK_BIN) return process.env.READSEEK_BIN;
+const READSEEK_PLATFORM_PACKAGES: Record<string, string> = {
+	"darwin-arm64": "@jarkkojs/readseek-darwin-arm64",
+	"linux-x64": "@jarkkojs/readseek-linux-x64",
+	"win32-x64": "@jarkkojs/readseek-win32-x64",
+};
 
-	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}`);
-		}
-	})();
+function readSeekPlatform(): string {
+	return `${process.platform}-${process.arch}`;
+}
 
-	const packageJson = require.resolve(`${platformPackage}/package.json`, { paths: [readseekPackageDir()] });
+function readSeekBinaryPath(): string {
+	const platform = readSeekPlatform();
+	const platformPackage = READSEEK_PLATFORM_PACKAGES[platform];
+	if (!platformPackage) {
+		const supported = Object.keys(READSEEK_PLATFORM_PACKAGES).join(", ");
+		throw new Error(`@jarkkojs/readseek ships no binary for ${platform}; it supports ${supported}`);
+	}
+
+	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 {
+/**
+ * Report whether a readseek binary can be resolved for the running platform,
+ * along with the reason when it cannot. Used to keep the readseek tools out of
+ * the active set on hosts that readseek publishes no binary for.
+ */
+export function readSeekBinaryAvailability(): { available: true } | { available: false; reason: string } {
 	try {
-		readseekBinaryPath();
-		return true;
-	} catch {
-		return false;
+		readSeekBinaryPath();
+		return { available: true };
+	} catch (err) {
+		return { available: false, reason: classifyReadSeekFailure(err).message };
 	}
 }
 
@@ -325,13 +322,18 @@ function defaultReadSeekDir(): string | null {
 
 const DEFAULT_READSEEK_TIMEOUT_MS = 120_000;
 
-function readseekTimeoutMs(): number {
-	const raw = process.env.READSEEK_TIMEOUT_MS;
-	if (raw !== undefined && raw !== "") {
-		const parsed = Number(raw);
-		if (Number.isFinite(parsed) && parsed > 0) return parsed;
-	}
-	return DEFAULT_READSEEK_TIMEOUT_MS;
+function readSeekTimeoutMs(): number {
+	return resolveReadSeekTimeoutMs() ?? DEFAULT_READSEEK_TIMEOUT_MS;
+}
+
+const READSEEK_USAGE_HINT = /\n\s*Run readseek(?: [\w-]+)* --help for more information\.?\s*$/;
+
+function readSeekErrorMessage(stderr: string): string {
+	return stderr
+		.replace(READSEEK_USAGE_HINT, "")
+		.replace(/^error:\s*/i, "")
+		.replace(/\s*\n\s*/g, " ")
+		.trim();
 }
 
 async function spawnReadSeekRaw(args: string[], options: RunReadSeekOptions = {}): Promise<string> {
@@ -353,8 +355,8 @@ async function spawnReadSeekRaw(args: string[], options: RunReadSeekOptions = {}
 
 		const stdin = options.stdin;
 		const stdio: StdioOptions = [stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"];
-		const child = spawn(readseekBinaryPath(), args, { stdio, signal: options.signal });
-		const timeoutMs = options.timeoutMs ?? readseekTimeoutMs();
+		const child = spawn(readSeekBinaryPath(), args, { stdio, signal: options.signal });
+		const timeoutMs = options.timeoutMs ?? readSeekTimeoutMs();
 		timeout = setTimeout(() => {
 			child.kill("SIGKILL");
 			fail(new Error(`readseek timed out after ${timeoutMs} ms`));
@@ -399,8 +401,8 @@ async function spawnReadSeekRaw(args: string[], options: RunReadSeekOptions = {}
 			const stdout = Buffer.concat(stdoutChunks).toString("utf-8");
 			const stderr = Buffer.concat(stderrChunks).toString("utf-8").trim();
 			if (code === 0) succeed(stdout);
-			else if (signal) fail(new Error((stderr || `readseek killed by signal ${signal}`).replace(/^error:\s*/i, "")));
-			else fail(new Error((stderr || `readseek exited with status ${code}`).replace(/^error:\s*/i, "")));
+			else if (signal) fail(new Error(readSeekErrorMessage(stderr) || `readseek killed by signal ${signal}`));
+			else fail(new Error(readSeekErrorMessage(stderr) || `readseek exited with status ${code}`));
 		});
 	});
 }
@@ -419,11 +421,11 @@ async function ensureDefaultReadSeekDir(): Promise<string | null> {
 	return defaultReadSeekDirInit;
 }
 
-async function readseekInvocationArgs(args: string[]): Promise<string[]> {
+async function readSeekInvocationArgs(args: string[]): Promise<string[]> {
 	if (isOwnReadSeekRepository()) return args;
 
-	const readseekDir = await ensureDefaultReadSeekDir();
-	return readseekDir ? ["--readseek-dir", readseekDir, ...args] : args;
+	const readSeekDir = await ensureDefaultReadSeekDir();
+	return readSeekDir ? ["--readseek-dir", readSeekDir, ...args] : args;
 }
 
 interface RunReadSeekOptions {
@@ -433,7 +435,7 @@ interface RunReadSeekOptions {
 }
 
 async function runReadSeekRaw(args: string[], options: RunReadSeekOptions = {}): Promise<string> {
-	return spawnReadSeekRaw(await readseekInvocationArgs(args), options);
+	return spawnReadSeekRaw(await readSeekInvocationArgs(args), options);
 }
 
 async function runReadSeek(args: string[], options: RunReadSeekOptions = {}): Promise<unknown> {
@@ -556,11 +558,15 @@ function parseSearchOutput(value: unknown): ReadSeekSearchOutput {
 	};
 }
 
-export async function readseekRead(filePath: string, startLine?: number, endLine?: number): Promise<ReadSeekReadOutput> {
-	const args = ["read", filePath];
-	if (startLine !== undefined) args.push("--start", String(startLine));
+export async function readSeekRead(
+	filePath: string,
+	startLine?: number,
+	endLine?: number,
+	options: { signal?: AbortSignal } = {},
+): Promise<ReadSeekReadOutput> {
+	const args = ["read", startLine === undefined ? filePath : `${filePath}:${startLine}`];
 	if (endLine !== undefined) args.push("--end", String(endLine));
-	return parseReadOutput(await runReadSeek(args));
+	return parseReadOutput(await runReadSeek(args, { signal: options.signal }));
 }
 
 function fileMapFromReadSeekOutput(output: ReadSeekMapOutput, filePath: string, totalBytes: number): FileMap | null {
@@ -575,7 +581,7 @@ function fileMapFromReadSeekOutput(output: ReadSeekMapOutput, filePath: string,
 	};
 }
 
-export async function readseekMap(
+export async function readSeekMap(
 	filePath: string,
 	totalBytes: number,
 	options: { signal?: AbortSignal } = {},
@@ -584,7 +590,7 @@ export async function readseekMap(
 	return fileMapFromReadSeekOutput(output, filePath, totalBytes);
 }
 
-export async function readseekSearch(
+export async function readSeekSearch(
 	target: string,
 	pattern: string,
 	options: ReadSeekSearchOptions = {},
@@ -597,13 +603,13 @@ export async function readseekSearch(
 	return parseSearchOutput(await runReadSeek(args, { signal: options.signal })).results;
 }
 
-export async function readseekMapContent(
+export async function readSeekMapContent(
 	filePath: string,
 	content: string,
 	options: { signal?: AbortSignal } = {},
 ): Promise<FileMap | null> {
 	const output = parseMapOutput(
-		await runReadSeek(["map", "--stdin", filePath], { signal: options.signal, stdin: content }),
+		await runReadSeek(["map", `stdin:${filePath}`], { signal: options.signal, stdin: content }),
 	);
 	return fileMapFromReadSeekOutput(output, filePath, Buffer.byteLength(content, "utf8"));
 }
@@ -638,7 +644,7 @@ function parseRefsOutput(value: unknown): ReadSeekRefsOutput {
 	};
 }
 
-export async function readseekRefs(
+export async function readSeekRefs(
 	target: string,
 	name: string,
 	options: ReadSeekRefsOptions = {},
@@ -678,34 +684,18 @@ function parseCheckOutput(value: unknown): ReadSeekCheckOutput {
 	};
 }
 
-export async function readseekCheck(
+export async function readSeekCheck(
 	filePath: string,
 	content: string,
 	options: { signal?: AbortSignal } = {},
 ): Promise<ReadSeekCheckOutput> {
 	return parseCheckOutput(
-		await runReadSeek(["check", "--stdin", filePath], { signal: options.signal, stdin: content }),
+		await runReadSeek(["check", `stdin:${filePath}`], { signal: options.signal, stdin: content }),
 	);
 }
 
-function parseTranscript(value: unknown): ReadSeekTranscript | undefined {
-	if (value === undefined || value === null) return undefined;
-	if (typeof value !== "object") throw new Error("invalid readseek detect transcribe");
-	const transcribe = value as Record<string, unknown>;
-	if (!Array.isArray(transcribe.regions)) throw new Error("invalid readseek detect transcribe.regions");
-	return {
-		text: requireString(transcribe.text, "transcribe.text"),
-		regions: transcribe.regions.map((region) => {
-			if (!region || typeof region !== "object") throw new Error("invalid readseek detect transcribe region");
-			const item = region as Record<string, unknown>;
-			const quad = item.quad;
-			if (!Array.isArray(quad) || quad.length !== 8) throw new Error("invalid readseek detect transcribe quad");
-			return {
-				text: requireString(item.text, "transcribe.region.text"),
-				quad: quad.map((n, i) => requireNumber(n, `transcribe.region.quad[${i}]`)) as ReadSeekTranscriptRegion["quad"],
-			};
-		}),
-	};
+function parseOcrText(value: unknown): ReadSeekOcrText | undefined {
+	return optionalString(value, "ocr");
 }
 
 function parseDetectedObjects(value: unknown): ReadSeekDetectedObject[] | undefined {
@@ -745,7 +735,7 @@ function parseDetectOutput(value: unknown): ReadSeekDetection {
 			width: requireNumber(output.width, "width"),
 			height: requireNumber(output.height, "height"),
 			animated: requireBoolean(output.animated, "animated"),
-			transcribe: parseTranscript(output.transcribe),
+			ocr: parseOcrText(output.ocr),
 			caption: optionalString(output.caption, "caption"),
 			objects: parseDetectedObjects(output.objects),
 		};
@@ -765,16 +755,48 @@ function parseDetectOutput(value: unknown): ReadSeekDetection {
 	return { kind: "text", type, file, mime };
 }
 
-export async function readseekDetect(
+export async function readSeekDetect(
+	filePath: string,
+	options: { signal?: AbortSignal } = {},
+): Promise<ReadSeekDetection> {
+	return parseDetectOutput(await runReadSeek(["detect", filePath], { signal: options.signal }));
+}
+
+/**
+ * Analyze an image with each requested vision mode and merge the payloads into
+ * a single detection. readseek accepts one `--image` mode per invocation, so
+ * modes that fail are dropped as long as at least one produced a payload;
+ * otherwise the first failure is rethrown.
+ */
+export async function readSeekImage(
 	filePath: string,
-	options: ReadSeekDetectOptions = {},
+	modes: ReadSeekImageMode[],
+	options: { signal?: AbortSignal } = {},
 ): Promise<ReadSeekDetection> {
-	const args = ["detect"];
-	if (options.transcribe) args.push("--transcribe");
-	if (options.caption) args.push("--caption");
-	if (options.objects) args.push("--objects");
-	args.push(filePath);
-	return parseDetectOutput(await runReadSeek(args, { signal: options.signal }));
+	const results = await Promise.allSettled(
+		modes.map(async (mode) =>
+			parseDetectOutput(await runReadSeek(["read", "--image", mode, filePath], { signal: options.signal })),
+		),
+	);
+
+	let merged: ReadSeekImageDetection | undefined;
+	for (const result of results) {
+		if (result.status !== "fulfilled" || result.value.kind !== "image") continue;
+		const detection = result.value;
+		merged = merged === undefined
+			? detection
+			: {
+				...merged,
+				ocr: detection.ocr ?? merged.ocr,
+				caption: detection.caption ?? merged.caption,
+				objects: detection.objects ?? merged.objects,
+			};
+	}
+	if (merged !== undefined) return merged;
+
+	const failure = results.find((result) => result.status === "rejected");
+	if (failure?.status === "rejected") throw failure.reason;
+	throw new Error(`readseek returned no image analysis for ${filePath}`);
 }
 
 // --- Rename ---
@@ -831,9 +853,44 @@ interface RenameOptions {
 	signal?: AbortSignal;
 }
 
+function parseRenameConflicts(value: unknown, field: string): RenameConflict[] {
+	if (value === undefined) return [];
+	if (!Array.isArray(value)) throw new Error(`invalid readseek ${field}`);
+	return value.map((item) => {
+		if (!item || typeof item !== "object") throw new Error(`invalid readseek ${field} entry`);
+		const c = item as Record<string, unknown>;
+		return {
+			line: requireNumber(c.line, `${field}.line`),
+			column: requireNumber(c.column, `${field}.column`),
+			reason: requireString(c.reason, `${field}.reason`),
+		};
+	});
+}
+
+function parseRenameEdits(value: unknown, field: string): RenameEdit[] {
+	if (value === undefined) return [];
+	if (!Array.isArray(value)) throw new Error(`invalid readseek ${field}`);
+	return value.map((item) => {
+		if (!item || typeof item !== "object") throw new Error(`invalid readseek ${field} entry`);
+		const e = item as Record<string, unknown>;
+		return {
+			line: requireNumber(e.line, `${field}.line`),
+			start_column: requireNumber(e.start_column, `${field}.start_column`),
+			end_column: requireNumber(e.end_column, `${field}.end_column`),
+			start_byte: requireNumber(e.start_byte, `${field}.start_byte`),
+			end_byte: requireNumber(e.end_byte, `${field}.end_byte`),
+			occurrence: requireString(e.occurrence, `${field}.occurrence`),
+			line_hash: requireString(e.line_hash, `${field}.line_hash`),
+			text: requireString(e.text, `${field}.text`),
+		};
+	});
+}
+
 function parseRenameOutput(value: unknown): RenameOutput {
 	if (!value || typeof value !== "object") throw new Error("invalid readseek rename output");
 	const output = value as Record<string, unknown>;
+	const others = output.others;
+	if (others !== undefined && !Array.isArray(others)) throw new Error("invalid readseek others");
 	return {
 		file: requireString(output.file, "file"),
 		language: requireString(output.language, "language"),
@@ -842,46 +899,24 @@ function parseRenameOutput(value: unknown): RenameOutput {
 		old_name: requireString(output.old_name, "old_name"),
 		new_name: requireString(output.new_name, "new_name"),
 		applied: requireBoolean(output.applied, "applied"),
-		conflicts: (output.conflicts as any[] | undefined)?.map((c: Record<string, unknown>) => ({
-			line: requireNumber(c.line, "conflict.line"),
-			column: requireNumber(c.column, "conflict.column"),
-			reason: requireString(c.reason, "conflict.reason"),
-		})) ?? [],
-		edits: (output.edits as any[] | undefined)?.map((e: Record<string, unknown>) => ({
-			line: requireNumber(e.line, "edit.line"),
-			start_column: requireNumber(e.start_column, "edit.start_column"),
-			end_column: requireNumber(e.end_column, "edit.end_column"),
-			start_byte: requireNumber(e.start_byte, "edit.start_byte"),
-			end_byte: requireNumber(e.end_byte, "edit.end_byte"),
-			occurrence: requireString(e.occurrence, "edit.occurrence"),
-			line_hash: requireString(e.line_hash, "edit.line_hash"),
-			text: requireString(e.text, "edit.text"),
-		})) ?? [],
-		others: (output.others as any[] | undefined)?.map((o: Record<string, unknown>) => ({
-			file: requireString(o.file, "other.file"),
-			language: requireString(o.language, "other.language"),
-			engine: optionalString(o.engine, "other.engine"),
-			file_hash: requireString(o.file_hash, "other.file_hash"),
-			conflicts: (o.conflicts as any[] | undefined)?.map((c: Record<string, unknown>) => ({
-				line: requireNumber(c.line, "conflict.line"),
-				column: requireNumber(c.column, "conflict.column"),
-				reason: requireString(c.reason, "conflict.reason"),
-			})) ?? [],
-			edits: (o.edits as any[] | undefined)?.map((e: Record<string, unknown>) => ({
-				line: requireNumber(e.line, "edit.line"),
-				start_column: requireNumber(e.start_column, "edit.start_column"),
-				end_column: requireNumber(e.end_column, "edit.end_column"),
-				start_byte: requireNumber(e.start_byte, "edit.start_byte"),
-				end_byte: requireNumber(e.end_byte, "edit.end_byte"),
-				occurrence: requireString(e.occurrence, "edit.occurrence"),
-				line_hash: requireString(e.line_hash, "edit.line_hash"),
-				text: requireString(e.text, "edit.text"),
-			})) ?? [],
-		})) ?? [],
+		conflicts: parseRenameConflicts(output.conflicts, "conflicts"),
+		edits: parseRenameEdits(output.edits, "edits"),
+		others: (others as unknown[] | undefined)?.map((entry) => {
+			if (!entry || typeof entry !== "object") throw new Error("invalid readseek other");
+			const o = entry as Record<string, unknown>;
+			return {
+				file: requireString(o.file, "other.file"),
+				language: requireString(o.language, "other.language"),
+				engine: optionalString(o.engine, "other.engine"),
+				file_hash: requireString(o.file_hash, "other.file_hash"),
+				conflicts: parseRenameConflicts(o.conflicts, "other.conflicts"),
+				edits: parseRenameEdits(o.edits, "other.edits"),
+			};
+		}) ?? [],
 	};
 }
 
-export async function readseekRename(
+export async function readSeekRename(
 	filePath: string,
 	options: RenameOptions,
 ): Promise<RenameOutput> {
@@ -968,13 +1003,13 @@ function parseIdentifyOutput(value: unknown): IdentifyOutput {
 	};
 }
 
-export async function readseekIdentify(
+export async function readSeekIdentify(
 	filePath: string,
 	content: string,
 	options: IdentifyOptions = {},
 ): Promise<IdentifyOutput> {
-	const args = ["identify", "--stdin", filePath];
-	if (options.line !== undefined) args.push("--line", String(options.line));
+	const target = options.line === undefined ? `stdin:${filePath}` : `stdin:${filePath}:${options.line}`;
+	const args = ["identify", target];
 	if (options.column !== undefined) args.push("--column", String(options.column));
 	if (options.language) args.push("--language", options.language);
 	return parseIdentifyOutput(await runReadSeek(args, { signal: options.signal, stdin: content }));
@@ -994,9 +1029,7 @@ export interface DefLocation {
 }
 
 interface DefOptions {
-	name?: string;
-	fromIdentify?: boolean;
-	identifyInput?: string;
+	name: string;
 	language?: string;
 	cached?: boolean;
 	others?: boolean;
@@ -1025,21 +1058,14 @@ function parseDefCompact(value: unknown): DefLocation[] {
 	});
 }
 
-export async function readseekDef(
+export async function readSeekDef(
 	target: string,
-	options: DefOptions = {},
+	options: DefOptions,
 ): Promise<DefLocation[]> {
-	const args = ["def", target, "--format", "plain"];
-	if (options.fromIdentify) {
-		args.push("--from-identify");
-	}
-	if (options.name) {
-		args.push(options.name);
-	}
+	const args = ["def", target, "--format", "plain", options.name];
 	if (options.language) args.push("--language", options.language);
 	if (options.cached) args.push("--cached");
 	if (options.others) args.push("--others");
 	if (options.ignored) args.push("--ignored");
-	const stdin = options.fromIdentify && options.identifyInput ? options.identifyInput : undefined;
-	return parseDefCompact(await runReadSeek(args, { signal: options.signal, stdin }));
+	return parseDefCompact(await runReadSeek(args, { signal: options.signal }));
 }

package/src/readseek-params.ts

@@ -16,7 +16,7 @@ export function langParam() {
  * TypeBox fragment for the Git-scope parameters shared by every readseek
  * search tool. Returns fresh schema instances so each tool spreads its own.
  */
-export function readseekGitSearchParams() {
+export function readSeekGitSearchParams() {
   return {
     cached: Type.Optional(Type.Boolean({ description: "In a Git repository, search tracked/indexed files" })),
     others: Type.Optional(Type.Boolean({ description: "In a Git repository, search untracked files" })),