@apmantza/greedysearch-pi 1.9.1 → 2.0.0

package/src/tools/shared.ts

@@ -1,186 +1,187 @@
-/**
- * Shared types, utilities, and runSearch for Pi tool handlers
- */
-
-import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import type { ProgressUpdate, ToolResult } from "../types.js";
-
-export type { ProgressUpdate, ToolResult } from "../types.js";
-
-// Canonical source is src/search/constants.mjs — keep in sync
-const ALL_ENGINES = ["perplexity", "bing", "google"] as const;
-
-export { ALL_ENGINES };
-
-/** Strip surrounding double-quotes that some framework versions inject into string params */
-export function stripQuotes(val: string): string {
-	return val.replace(/^"|"$/g, "");
-}
-
-/**
- * Check if the CDP module is available in the package directory
- */
-export function cdpAvailable(baseDir: string): boolean {
-	return existsSync(join(baseDir, "bin", "cdp.mjs"));
-}
-
-/**
- * Create a "cdp missing" error result
- */
-export function cdpMissingResult(): ToolResult {
-	return {
-		content: [
-			{
-				type: "text",
-				text: "cdp.mjs missing — try reinstalling: pi install git:github.com/apmantza/GreedySearch-pi",
-			},
-		],
-		details: {} as Record<string, unknown>,
-	};
-}
-
-/**
- * Create an error result with a message
- */
-export function errorResult(prefix: string, e: unknown): ToolResult {
-	const msg = e instanceof Error ? e.message : String(e);
-	return {
-		content: [{ type: "text", text: `${prefix}: ${msg}` }],
-		details: {} as Record<string, unknown>,
-	};
-}
-
-/**
- * Spawn search.mjs and collect JSON results, with progress streaming via stderr.
- * Shared by GreedySearch tool handlers.
- */
-export function runSearch(
-	engine: string,
-	query: string,
-	flags: string[],
-	searchBin: string,
-	signal?: AbortSignal,
-	onProgress?: (
-		engine: string,
-		status: "done" | "error" | "needs-human",
-	) => void,
-	headless?: boolean, // defaults to true (headless is the default)
-): Promise<Record<string, unknown>> {
-	return new Promise((resolve, reject) => {
-		const allFlags = [...flags];
-		// Headless is default — only skip if explicitly false or GREEDY_SEARCH_VISIBLE=1
-		if (headless !== false && process.env.GREEDY_SEARCH_VISIBLE !== "1")
-			allFlags.push("--headless");
-		if (headless === false) allFlags.push("--always-visible");
-		// Propagate visibility preference via env (--headless flag is informational;
-		// the actual headless control in search.mjs / launch.mjs reads the env var).
-		const procEnv = { ...process.env };
-		if (headless === false) {
-			procEnv.GREEDY_SEARCH_VISIBLE = "1";
-			procEnv.GREEDY_SEARCH_ALWAYS_VISIBLE = "1";
-		}
-		const proc = spawn(
-			process.execPath,
-			[searchBin, engine, "--inline", "--stdin", ...allFlags],
-			{ stdio: ["pipe", "pipe", "pipe"], env: procEnv },
-		);
-		// Pipe query via stdin to avoid leaking it in process table command-line
-		proc.stdin.write(query);
-		proc.stdin.end();
-		let out = "";
-		let err = "";
-
-		const onAbort = () => {
-			proc.kill("SIGTERM");
-			reject(new Error("Aborted"));
-		};
-		signal?.addEventListener("abort", onAbort, { once: true });
-
-		proc.stderr.on("data", (d: Buffer) => {
-			err += d;
-			for (const line of d.toString().split("\n")) {
-				// Engine progress: perplexity/bing/google
-				const engineMatch = line.match(
-					/^PROGRESS:(perplexity|bing|google):(done|error|needs-human)$/,
-				);
-				if (engineMatch && onProgress) {
-					onProgress(
-						engineMatch[1],
-						engineMatch[2] as "done" | "error" | "needs-human",
-					);
-				}
-				// Synthesis progress: skipped (manual verification) or done/error
-				const synthMatch = line.match(
-					/^PROGRESS:synthesis:(done|error|skipped)$/,
-				);
-				if (synthMatch && onProgress) {
-					onProgress(
-						"synthesis",
-						synthMatch[1] as "done" | "error" | "needs-human",
-					);
-				}
-			}
-		});
-
-		proc.stdout.on("data", (d: Buffer) => (out += d));
-		proc.on("close", (code: number) => {
-			signal?.removeEventListener("abort", onAbort);
-			if (code !== 0) {
-				reject(new Error(err.trim() || `search.mjs exited with code ${code}`));
-			} else {
-				try {
-					resolve(JSON.parse(out.trim()));
-				} catch {
-					reject(
-						new Error(`Invalid JSON from search.mjs: ${out.slice(0, 200)}`),
-					);
-				}
-			}
-		});
-	});
-}
-
-/**
- * Build a progress callback that tracks completed engines.
- * Returns an onProgress function suitable for runSearch.
- */
-export function makeProgressTracker(
-	engines: readonly string[],
-	onUpdate: ((update: ProgressUpdate) => void) | undefined,
-	suffix: "Searching" | "Researching",
-	depth: string,
-) {
-	const completed = new Map<string, "done" | "error" | "needs-human">();
-
-	return (eng: string, status: "done" | "error" | "needs-human") => {
-		completed.set(eng, status);
-		const parts: string[] = [];
-		for (const e of engines) {
-			const s = completed.get(e);
-			if (s === "done") parts.push(`✅ ${e} done`);
-			else if (s === "error") parts.push(`❌ ${e} failed`);
-			else if (s === "needs-human")
-				parts.push(`🔓 ${e} needs manual verification`);
-			else parts.push(`⏳ ${e}`);
-		}
-		// Synthesis status: when all engines complete in non-fast mode,
-		// show synthesis progress.  Handle "skipped" status (emitted when
-		// manual verification is needed and synthesis is bypassed).
-		if (depth !== "fast" && completed.size >= 3) {
-			const synStatus = completed.get("synthesis");
-			if (synStatus === "done") parts.push("✅ synthesized");
-			else if (synStatus === "error") parts.push("❌ synthesis failed");
-			else if (synStatus === "needs-human") parts.push("⏭️ synthesis skipped");
-			else parts.push("🔄 synthesizing");
-		}
-
-		onUpdate?.({
-			content: [
-				{ type: "text", text: `**${suffix}...** ${parts.join(" · ")}` },
-			],
-			details: { _progress: true },
-		} satisfies ProgressUpdate);
-	};
-}
+/**
+ * Shared types, utilities, and runSearch for Pi tool handlers
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { ProgressUpdate, ToolResult } from "../types.js";
+
+export type { ProgressUpdate, ToolResult } from "../types.js";
+
+// Import and re-export ALL_ENGINES from constants.mjs so it's always in sync.
+// constants.mjs reads ~/.pi/greedyconfig for user overrides.
+import { ALL_ENGINES } from "../search/constants.mjs";
+export { ALL_ENGINES };
+
+/** Strip surrounding double-quotes that some framework versions inject into string params */
+export function stripQuotes(val: string): string {
+	return val.replace(/^"|"$/g, "");
+}
+
+/**
+ * Check if the CDP module is available in the package directory
+ */
+export function cdpAvailable(baseDir: string): boolean {
+	return existsSync(join(baseDir, "bin", "cdp.mjs"));
+}
+
+/**
+ * Create a "cdp missing" error result
+ */
+export function cdpMissingResult(): ToolResult {
+	return {
+		content: [
+			{
+				type: "text",
+				text: "cdp.mjs missing — try reinstalling: pi install git:github.com/apmantza/GreedySearch-pi",
+			},
+		],
+		details: {} as Record<string, unknown>,
+	};
+}
+
+/**
+ * Create an error result with a message
+ */
+export function errorResult(prefix: string, e: unknown): ToolResult {
+	const msg = e instanceof Error ? e.message : String(e);
+	return {
+		content: [{ type: "text", text: `${prefix}: ${msg}` }],
+		details: {} as Record<string, unknown>,
+	};
+}
+
+/**
+ * Spawn search.mjs and collect JSON results, with progress streaming via stderr.
+ * Shared by GreedySearch tool handlers.
+ */
+export function runSearch(
+	engine: string,
+	query: string,
+	flags: string[],
+	searchBin: string,
+	signal?: AbortSignal,
+	onProgress?: (
+		engine: string,
+		status: "done" | "error" | "needs-human",
+	) => void,
+	options: { headless?: boolean } = {},
+): Promise<Record<string, unknown>> {
+	return new Promise((resolve, reject) => {
+		const { headless = true } = options;
+		const allFlags = [...flags];
+		// Headless is default — only skip if explicitly false or GREEDY_SEARCH_VISIBLE=1
+		if (headless !== false && process.env.GREEDY_SEARCH_VISIBLE !== "1")
+			allFlags.push("--headless");
+		if (headless === false) allFlags.push("--always-visible");
+		// Propagate visibility preference via env (--headless flag is informational;
+		// the actual headless control in search.mjs / launch.mjs reads the env var).
+		const procEnv = { ...process.env };
+		if (headless === false) {
+			procEnv.GREEDY_SEARCH_VISIBLE = "1";
+			procEnv.GREEDY_SEARCH_ALWAYS_VISIBLE = "1";
+		}
+		const proc = spawn(
+			process.execPath,
+			[searchBin, engine, "--inline", "--stdin", ...allFlags],
+			{ stdio: ["pipe", "pipe", "pipe"], env: procEnv },
+		);
+		// Pipe query via stdin to avoid leaking it in process table command-line
+		proc.stdin.write(query);
+		proc.stdin.end();
+		let out = "";
+		let err = "";
+
+		const onAbort = () => {
+			proc.kill("SIGTERM");
+			reject(new Error("Aborted"));
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+
+		proc.stderr.on("data", (d: Buffer) => {
+			err += d;
+			// Match PROGRESS lines for any known engine.
+			const ENGINE_PROGRESS_RE =
+				/^PROGRESS:(perplexity|google|chatgpt|bing|gemini|semantic-scholar|semanticscholar|s2|logically):(done|error|needs-human)$/;
+			for (const line of d.toString().split("\n")) {
+				// Engine progress: any known engine
+				const engineMatch = line.match(ENGINE_PROGRESS_RE);
+				if (engineMatch && onProgress) {
+					onProgress(
+						engineMatch[1],
+						engineMatch[2] as "done" | "error" | "needs-human",
+					);
+				}
+				// Synthesis progress: skipped (manual verification) or done/error
+				const synthMatch = line.match(
+					/^PROGRESS:synthesis:(done|error|skipped)$/,
+				);
+				if (synthMatch && onProgress) {
+					onProgress(
+						"synthesis",
+						synthMatch[1] as "done" | "error" | "needs-human",
+					);
+				}
+			}
+		});
+
+		proc.stdout.on("data", (d: Buffer) => (out += d));
+		proc.on("close", (code: number) => {
+			signal?.removeEventListener("abort", onAbort);
+			if (code !== 0) {
+				reject(new Error(err.trim() || `search.mjs exited with code ${code}`));
+			} else {
+				try {
+					resolve(JSON.parse(out.trim()));
+				} catch {
+					reject(
+						new Error(`Invalid JSON from search.mjs: ${out.slice(0, 200)}`),
+					);
+				}
+			}
+		});
+	});
+}
+
+/**
+ * Build a progress callback that tracks completed engines.
+ * Returns an onProgress function suitable for runSearch.
+ */
+export function makeProgressTracker(
+	engines: readonly string[],
+	onUpdate: ((update: ProgressUpdate) => void) | undefined,
+	suffix: "Searching" | "Researching",
+	showSynthesis: boolean,
+) {
+	const completed = new Map<string, "done" | "error" | "needs-human">();
+
+	return (eng: string, status: "done" | "error" | "needs-human") => {
+		completed.set(eng, status);
+		const parts: string[] = [];
+		for (const e of engines) {
+			const s = completed.get(e);
+			if (s === "done") parts.push(`✅ ${e} done`);
+			else if (s === "error") parts.push(`❌ ${e} failed`);
+			else if (s === "needs-human")
+				parts.push(`🔓 ${e} needs manual verification`);
+			else parts.push(`⏳ ${e}`);
+		}
+		// Synthesis status is shown only when the caller explicitly requested
+		// Gemini synthesis for a multi-engine search.
+		if (showSynthesis && completed.size >= engines.length) {
+			const synStatus = completed.get("synthesis");
+			if (synStatus === "done") parts.push("✅ synthesized");
+			else if (synStatus === "error") parts.push("❌ synthesis failed");
+			else if (synStatus === "needs-human") parts.push("⏭️ synthesis skipped");
+			else parts.push("🔄 synthesizing");
+		}
+
+		onUpdate?.({
+			content: [
+				{ type: "text", text: `**${suffix}...** ${parts.join(" · ")}` },
+			],
+			details: { _progress: true },
+		} satisfies ProgressUpdate);
+	};
+}

package/src/types.ts

@@ -1,104 +1,110 @@
-/**
- * TypeScript interfaces for GreedySearch data structures
- *
- * These types document the shape of data flowing between modules.
- * They can be imported by TypeScript files (index.ts, tool handlers, formatters)
- * and used for type safety without runtime overhead.
- */
-
-// ============================================================================
-// Search Result Types
-// ============================================================================
-
-/** A single source extracted from search results */
-export interface Source {
-	url: string;
-	title: string;
-	type?: "official-docs" | "maintainer-blog" | "repo" | "community" | "website";
-	domain?: string;
-	snippet?: string;
-}
-
-/** Result from a single search engine */
-export interface SearchResult {
-	engine: string;
-	answer: string;
-	sources: Source[];
-	url?: string;
-	query?: string;
-	error?: string;
-}
-
-/** Synthesis result combining multiple engine results */
-export interface SynthesisResult {
-	answer: string;
-	agreementLevel?: "consensus" | "majority" | "mixed" | "conflicting";
-	claims?: Claim[];
-	sourceIds?: string[];
-	confidence?: ConfidenceMetrics;
-}
-
-/** A single claim within a synthesis */
-export interface Claim {
-	text: string;
-	sourceIds: string[];
-	confidence?: "high" | "medium" | "low";
-}
-
-/** Confidence metrics for a synthesis */
-export interface ConfidenceMetrics {
-	overall: number;        // 0-1
-	consensus: number;      // fraction of engines agreeing
-	sourceCount: number;
-	engineCount: number;
-}
-
-// ============================================================================
-// Source Registry Types
-// ============================================================================
-
-/** A classified source in the registry */
-export interface ClassifiedSource extends Source {
-	engineOrigin: string[];
-	isOfficial: boolean;
-	consensus: number;  // fraction of engines citing this source
-}
-
-// ============================================================================
-// Tool Result Types
-// ============================================================================
-
-/** Progress update sent via onUpdate during long-running searches */
-export interface ProgressUpdate {
-	content: Array<{ type: "text"; text: string }>;
-	details: { _progress: true };
-}
-
-/** Pi tool result format */
-export interface ToolResult {
-	content: Array<{ type: "text"; text: string }>;
-	details: Record<string, unknown>;
-}
-
-// ============================================================================
-// Engine Configuration Types
-// ============================================================================
-
-/** Engine definition for the ENGINES map */
-export interface EngineConfig {
-	/** Extractor script filename (e.g. "perplexity.mjs") */
-	script: string;
-	/** Human-readable label for progress messages */
-	label: string;
-	/** Domain pattern for source matching */
-	domain: string;
-	/** URL pattern for the engine */
-	url: string;
-}
-
-// ============================================================================
-// Constants
-// ============================================================================
-
-// Runtime defaults are in src/search/defaults.mjs (since .ts files can't be
-// imported directly by Node.js). Import DEFAULTS from there for runtime values.
+/**
+ * TypeScript interfaces for GreedySearch data structures
+ *
+ * These types document the shape of data flowing between modules.
+ * They can be imported by TypeScript files (index.ts, tool handlers, formatters)
+ * and used for type safety without runtime overhead.
+ */
+
+// ============================================================================
+// Search Result Types
+// ============================================================================
+
+/** A single source extracted from search results */
+export interface Source {
+	url: string;
+	title: string;
+	type?:
+		| "official-docs"
+		| "maintainer-blog"
+		| "repo"
+		| "academic"
+		| "community"
+		| "website";
+	domain?: string;
+	snippet?: string;
+}
+
+/** Result from a single search engine */
+export interface SearchResult {
+	engine: string;
+	answer: string;
+	sources: Source[];
+	url?: string;
+	query?: string;
+	error?: string;
+}
+
+/** Synthesis result combining multiple engine results */
+export interface SynthesisResult {
+	answer: string;
+	agreementLevel?: "consensus" | "majority" | "mixed" | "conflicting";
+	claims?: Claim[];
+	sourceIds?: string[];
+	confidence?: ConfidenceMetrics;
+}
+
+/** A single claim within a synthesis */
+export interface Claim {
+	text: string;
+	sourceIds: string[];
+	confidence?: "high" | "medium" | "low";
+}
+
+/** Confidence metrics for a synthesis */
+export interface ConfidenceMetrics {
+	overall: number; // 0-1
+	consensus: number; // fraction of engines agreeing
+	sourceCount: number;
+	engineCount: number;
+}
+
+// ============================================================================
+// Source Registry Types
+// ============================================================================
+
+/** A classified source in the registry */
+export interface ClassifiedSource extends Source {
+	engineOrigin: string[];
+	isOfficial: boolean;
+	consensus: number; // fraction of engines citing this source
+}
+
+// ============================================================================
+// Tool Result Types
+// ============================================================================
+
+/** Progress update sent via onUpdate during long-running searches */
+export interface ProgressUpdate {
+	content: Array<{ type: "text"; text: string }>;
+	details: { _progress: true };
+}
+
+/** Pi tool result format */
+export interface ToolResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: Record<string, unknown>;
+}
+
+// ============================================================================
+// Engine Configuration Types
+// ============================================================================
+
+/** Engine definition for the ENGINES map */
+export interface EngineConfig {
+	/** Extractor script filename (e.g. "perplexity.mjs") */
+	script: string;
+	/** Human-readable label for progress messages */
+	label: string;
+	/** Domain pattern for source matching */
+	domain: string;
+	/** URL pattern for the engine */
+	url: string;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+// Runtime defaults are in src/search/defaults.mjs (since .ts files can't be
+// imported directly by Node.js). Import DEFAULTS from there for runtime values.