pi-lean-search 0.1.0

package/README.md

@@ -0,0 +1,55 @@
+# pi-lean-search
+
+> SearXNG search tool for Pi. Part of the [pi-lean-dimension](https://github.com/coreyryanhanson/pi-lean-dimension) web-tools suite.
+
+## Quick start
+
+```bash
+pi install npm:pi-lean-portal   # recommended: browser + /web toggle
+pi install npm:pi-lean-search   # adds web-search to /web on|off
+```
+
+Or get the full suite in one command:
+
+```bash
+pi install npm:pi-lean-dimension # portal + search, requires SearXNG server
+```
+
+## Usage
+
+| Command / Tool | Description |
+|---|---|
+| `web-search` tool | Search the web via your SearXNG instance. Agents use this automatically. |
+| `/searxng-status` | Test and diagnose the SearXNG connection. |
+
+The `web-search` tool is automatically included in `/web on` / `/web off` toggling
+when `pi-lean-portal` is also installed. The status bar shows a `● searxng` glyph
+(colored accent/blue when healthy, yellow when degraded, red when unreachable).
+
+## Configuration
+
+Set the URL of your SearXNG instance in your Pi settings file:
+
+**`~/.pi/agent/settings.json`** (global) or **`.pi/settings.json`** (project-local):
+
+```json
+{
+  "searxng": {
+    "url": "http://localhost:8888"
+  }
+}
+```
+
+- **Self-hosted SearXNG:** Run your own instance ([docs](https://docs.searxng.org/)).
+- No URL configured? The tool returns a setup message on its first call — no errors, no broken prompts.
+
+## Graceful degradation
+
+If SearXNG is unreachable or unconfigured, the `web-search` tool returns a clear
+message pointing you toward setup instructions. It never throws or breaks the agent.
+
+## Tests
+
+```bash
+npx vitest run packages/pi-lean-search/
+```

package/index.ts

@@ -0,0 +1,292 @@
+/**
+ * pi-lean-search — SearXNG search extension for Pi.
+ *
+ * Registers the `web-search` tool and a `/searxng-status` diagnostic command.
+ * Manages the `search` status bar slot with health-colored glyphs.
+ *
+ * On session_start, probes SearXNG reachability and updates the search slot:
+ *   ● searxng  (accent/blue)  — healthy and reachable
+ *   ● searxng  (warning/yellow) — server up but pipeline degraded
+ *   ● searxng  (error/red)    — unreachable
+ *
+ * Portal owns the `search` slot's "off" state: when `/web off` is called,
+ * portal writes `○ searxng` (open circle). Search overrides with the
+ * health-colored glyph on session_start.
+ */
+
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { readSearxngUrl } from "./search-config.js";
+import { webSearchTool } from "./web-search-tool.js";
+
+// ─── Module-level state ───────────────────────────────────────────
+
+/** Cached SearXNG URL (read once at startup, stable mid-session). */
+let _searxngUrl: string | undefined;
+
+// ─── Health probes ───────────────────────────────────────────────
+
+/**
+ * Lightweight server probe — fetches the SearXNG root HTML page.
+ * Fast (~ms) because it only needs the HTTP response, not the full
+ * aggregation pipeline.
+ */
+async function checkServerReachable(
+	url: string,
+	signal?: AbortSignal,
+): Promise<boolean> {
+	try {
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), 2000);
+
+		let res: Response;
+		try {
+			const mergedSignal = signal
+				? combineAbortSignals(signal, controller.signal)
+				: (controller.signal as AbortSignal);
+			res = await fetch(url, { signal: mergedSignal });
+		} finally {
+			clearTimeout(timeoutId);
+		}
+
+		return res.ok && res.status === 200;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Full-pipeline probe — verifies the search API actually works end-to-end.
+ * Triggers upstream engine aggregation, so it takes longer (5s timeout).
+ */
+async function checkSearchReachable(
+	url: string,
+	signal?: AbortSignal,
+): Promise<boolean> {
+	const normalized = url.replace(/\/+$/, "");
+	const searchUrl = `${normalized}/search?q=ping&format=json`;
+
+	try {
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), 5000);
+
+		let res: Response;
+		try {
+			const mergedSignal = signal
+				? combineAbortSignals(signal, controller.signal)
+				: (controller.signal as AbortSignal);
+			res = await fetch(searchUrl, {
+				signal: mergedSignal,
+				headers: { Accept: "application/json" },
+			});
+		} finally {
+			clearTimeout(timeoutId);
+		}
+
+		if (!res.ok || res.status !== 200) return false;
+		const text = await res.text();
+		if (!text) return false;
+		JSON.parse(text);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Combine two AbortSignals into one that aborts when either aborts.
+ */
+function combineAbortSignals(...signals: AbortSignal[]): AbortSignal {
+	const controller = new AbortController();
+	for (const sig of signals) {
+		if (sig.aborted) {
+			controller.abort(sig.reason);
+			return controller.signal;
+		}
+		sig.addEventListener("abort", () => controller.abort(sig.reason), {
+			once: true,
+		});
+	}
+	return controller.signal;
+}
+
+// ─── Status slot helpers ──────────────────────────────────────────
+
+/**
+ * Normalize the SearXNG URL for display (strip protocol prefix for brevity).
+ */
+function displayUrl(url: string): string {
+	return url.replace(/^https?:\/\//, "");
+}
+
+/**
+ * Set the `search` status slot with a health-colored glyph.
+ *
+ * Coloring:
+ *   - Healthy:   accent (blue) — same as browser on
+ *   - Degraded:  warning (yellow/gold) — server up but pipeline broken
+ *   - Unhealthy: error (red) — unreachable or unconfigured
+ *
+ * Portal writes `○ searxng` on /web off; search overrides here on
+ * session_start or /searxng-status.
+ */
+function setSearchStatus(
+	ctx: ExtensionContext,
+	healthy: boolean | null,
+	degraded: boolean,
+): void {
+	if (healthy === null) {
+		// Unconfigured — no glyph
+		try {
+			ctx.ui.setStatus("search", "");
+		} catch {
+			// ctx.ui may be unavailable during shutdown
+		}
+		return;
+	}
+
+	if (!healthy) {
+		// Unreachable
+		try {
+			ctx.ui.setStatus("search", ctx.ui.theme.fg("error", "●") + " searxng");
+		} catch {
+			// ignore
+		}
+		return;
+	}
+
+	if (degraded) {
+		// Server up but pipeline broken
+		try {
+			ctx.ui.setStatus("search", ctx.ui.theme.fg("warning", "●") + " searxng");
+		} catch {
+			// ignore
+		}
+		return;
+	}
+
+	// Healthy
+	try {
+		ctx.ui.setStatus("search", ctx.ui.theme.fg("accent", "●") + " searxng");
+	} catch {
+		// ignore
+	}
+}
+
+// ─── Extension entry point ────────────────────────────────────────
+
+export default function (pi: ExtensionAPI) {
+	// Read config at startup
+	_searxngUrl = readSearxngUrl();
+
+	// ── Register the web-search tool ─────────────────────────
+	pi.registerTool(webSearchTool);
+
+	// ── Session start: health probe + status update ──────────
+	pi.on("session_start", async (_event, ctx) => {
+		// Re-read config in case it changed between sessions
+		_searxngUrl = readSearxngUrl();
+
+		if (!_searxngUrl) {
+			// Unconfigured — clear the slot
+			setSearchStatus(ctx, null, false);
+			return;
+		}
+
+		// Check if web-search tools are currently active (portal
+		// restores toggle state before search's session_start fires).
+		const activeTools = pi.getActiveTools();
+		if (!activeTools.includes("web-search")) {
+			// Tools are off — don't override portal's ○ searxng
+			return;
+		}
+
+		const reachable = await checkServerReachable(
+			_searxngUrl,
+			ctx.signal ?? undefined,
+		);
+
+		if (reachable) {
+			setSearchStatus(ctx, true, false);
+			ctx.ui.notify(
+				`🔍 SearXNG at ${displayUrl(_searxngUrl)} is available`,
+				"info",
+			);
+		} else {
+			setSearchStatus(ctx, false, false);
+			ctx.ui.notify(
+				`⚠ SearXNG at ${displayUrl(_searxngUrl)} is unreachable. ` +
+					"Web search will degrade gracefully with error messages.",
+				"warning",
+			);
+		}
+	});
+
+	// ── Session shutdown: clean up ───────────────────────────
+	pi.on("session_shutdown", async (_event, ctx) => {
+		try {
+			ctx?.ui?.setStatus?.("search", "");
+		} catch {
+			// ctx.ui may not be available during shutdown
+		}
+	});
+
+	// ── Manual status check command ──────────────────────────
+	pi.registerCommand("searxng-status", {
+		description:
+			"Test the full SearXNG search pipeline (server + aggregation) " +
+			"and update the status bar. Use when web-search returns " +
+			"errors or when you've just started/restarted SearXNG.",
+		handler: async (_args, ctx) => {
+			if (!_searxngUrl) {
+				ctx.ui.notify(
+					"❌ SearXNG is not configured. " +
+						"Set `searxng.url` in your Pi settings.json.",
+					"error",
+				);
+				setSearchStatus(ctx, false, false);
+				return;
+			}
+
+			// Full pipeline probe (slower, triggers aggregation)
+			const searchOk = await checkSearchReachable(
+				_searxngUrl,
+				ctx.signal ?? undefined,
+			);
+
+			if (searchOk) {
+				setSearchStatus(ctx, true, false);
+				ctx.ui.notify(
+					`✅ SearXNG search pipeline is working at ${displayUrl(_searxngUrl)}`,
+					"info",
+				);
+				return;
+			}
+
+			// Distinguish: server down vs pipeline broken
+			const serverOk = await checkServerReachable(
+				_searxngUrl,
+				ctx.signal ?? undefined,
+			);
+
+			if (serverOk) {
+				setSearchStatus(ctx, true, true); // degraded
+				ctx.ui.notify(
+					"⚠ SearXNG server is up but the search pipeline " +
+						"may be broken (aggregation failed). " +
+						"Try /searxng-status again after a moment.",
+					"warning",
+				);
+			} else {
+				setSearchStatus(ctx, false, false);
+				ctx.ui.notify(
+					`❌ SearXNG at ${displayUrl(_searxngUrl)} is not responding. ` +
+						"Check that the SearXNG service is running.",
+					"error",
+				);
+			}
+		},
+	});
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+	"name": "pi-lean-search",
+	"version": "0.1.0",
+	"description": "Pi extension. SearXNG search tool for Pi. Pairs with pi-lean-portal's /web toggle (soft peer — search-only installs are valid).",
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"searxng",
+		"search",
+		"web"
+	],
+	"license": "AGPL-3.0-only",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/coreyryanhanson/pi-lean-dimension.git",
+		"directory": "packages/pi-lean-search"
+	},
+	"type": "module",
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"index.ts",
+		"LICENSE",
+		"web-search-tool.ts",
+		"search-config.ts",
+		"verify-ship-manifest.ts",
+		"ship-manifest.test.ts",
+		"README.md"
+	],
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"scripts": {
+		"prepack": "cp ../../LICENSE ./LICENSE",
+		"test": "vitest run"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
+		"pi-lean-portal": "*",
+		"typebox": "*"
+	},
+	"peerDependenciesMeta": {
+		"pi-lean-portal": {
+			"optional": true
+		}
+	}
+}

package/search-config.ts

@@ -0,0 +1,63 @@
+/**
+ * Config reader for pi-lean-search.
+ *
+ * Reads `searxng.url` from Pi's merged settings.json files
+ * (global ~/.pi/agent/settings.json + project-local .pi/settings.json).
+ *
+ * The expected shape in settings.json:
+ * ```json
+ * { "searxng": { "url": "http://localhost:8888" } }
+ * ```
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// ─── Config paths ─────────────────────────────────────────────────
+
+/** Global pi settings path. */
+const GLOBAL_SETTINGS_PATH = join(homedir(), ".pi", "agent", "settings.json");
+
+/** Project-local pi settings path (relative to cwd). */
+const PROJECT_SETTINGS_PATH = ".pi/settings.json";
+
+// ─── Reader ───────────────────────────────────────────────────────
+
+function readSettingsFile(path: string): Record<string, unknown> {
+	try {
+		if (!existsSync(path)) return {};
+		const raw = readFileSync(path, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+			return parsed as Record<string, unknown>;
+		}
+		return {};
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Read the configured SearXNG URL from merged Pi settings.
+ *
+ * Looks up `searxng.url` in:
+ *   1. `~/.pi/agent/settings.json` (global)
+ *   2. `.pi/settings.json` (project-local, overrides global)
+ *
+ * Returns the URL string if configured, or `undefined` if absent
+ * (caller should degrade gracefully — the tool returns a setup
+ * message when no URL is configured).
+ */
+export function readSearxngUrl(): string | undefined {
+	const global = readSettingsFile(GLOBAL_SETTINGS_PATH);
+	const project = readSettingsFile(PROJECT_SETTINGS_PATH);
+	const merged = { ...global, ...project };
+
+	const searxng = merged.searxng;
+	if (searxng && typeof searxng === "object" && !Array.isArray(searxng)) {
+		const url = (searxng as Record<string, unknown>).url;
+		if (typeof url === "string" && url.length > 0) return url;
+	}
+	return undefined;
+}

package/ship-manifest.test.ts

@@ -0,0 +1,12 @@
+import { verifyShipManifest } from "./verify-ship-manifest.js";
+import { describe, expect, it } from "vitest";
+
+describe("publish manifest", () => {
+	it("`package.json` `files` array covers every production .ts module across the tree", () => {
+		expect(verifyShipManifest(import.meta.url).missing).toEqual([]);
+	});
+
+	it("every `files` entry points at something on disk — a stale entry ships nothing", () => {
+		expect(verifyShipManifest(import.meta.url).stale).toEqual([]);
+	});
+});

package/verify-ship-manifest.ts

@@ -0,0 +1,96 @@
+/**
+ * Ship-manifest verification helper.
+ *
+ * Walks a package directory for production `.ts` files and compares them to
+ * the `files` array in `package.json`. Used by `ship-manifest.test.ts` files
+ * across the monorepo so every published package can prove its npm tarball
+ * actually contains the modules it imports at runtime.
+ *
+ * Ported from pi-lean-portal's verify-ship-manifest.ts (rpiv-mono pattern).
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SKIP_DIRS = new Set(["node_modules", "docs", "__tests__"]);
+const SKIP_FILES = new Set(["test-fixtures.ts"]);
+/** Entries that won't exist on disk at rest but are valid (generated at pack time, e.g. by prepack). */
+const SKIP_STALE = new Set(["LICENSE"]);
+
+export interface ShipManifestResult {
+	declared: readonly string[];
+	onDisk: readonly string[];
+	missing: readonly string[];
+	stale: readonly string[];
+}
+
+export function verifyShipManifest(
+	packageDirOrUrl: string,
+): ShipManifestResult {
+	const packageDir = packageDirOrUrl.startsWith("file:")
+		? dirname(fileURLToPath(packageDirOrUrl))
+		: packageDirOrUrl;
+	const pkgRaw = readFileSync(resolve(packageDir, "package.json"), "utf8");
+	const pkg = JSON.parse(pkgRaw) as { files?: string[] };
+	const declared = pkg.files ?? [];
+	const exactFiles = new Set<string>();
+	const dirPrefixes: string[] = [];
+	for (const entry of declared) {
+		// Negation patterns (`!foo/`) are npm `files`-array syntax for excluding
+		// sub-paths within an included directory. They have no on-disk counterpart;
+		// skip them for existence checks and staleness detection.
+		if (entry.startsWith("!")) continue;
+		if (entry.endsWith("/")) dirPrefixes.push(entry);
+		else if (isDirOnDisk(packageDir, entry)) dirPrefixes.push(`${entry}/`);
+		else exactFiles.add(entry);
+	}
+
+	const onDisk = walkProductionTs(packageDir, packageDir);
+	const missing = onDisk.filter((f) => !isCovered(f, exactFiles, dirPrefixes));
+	const stale = declared.filter(
+		(entry) =>
+			!entry.startsWith("!") &&
+			!SKIP_STALE.has(entry) &&
+			!existsSync(resolve(packageDir, entry)),
+	);
+
+	return { declared, onDisk, missing, stale };
+}
+
+function isDirOnDisk(packageDir: string, entry: string): boolean {
+	try {
+		return statSync(resolve(packageDir, entry)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+function isCovered(
+	file: string,
+	exactFiles: Set<string>,
+	dirPrefixes: readonly string[],
+): boolean {
+	if (exactFiles.has(file)) return true;
+	for (const prefix of dirPrefixes) {
+		if (file.startsWith(prefix)) return true;
+	}
+	return false;
+}
+
+function walkProductionTs(root: string, dir: string): string[] {
+	const out: string[] = [];
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		if (entry.name.startsWith(".")) continue;
+		if (entry.isDirectory() && SKIP_DIRS.has(entry.name)) continue;
+		const abs = resolve(dir, entry.name);
+		if (entry.isDirectory()) {
+			out.push(...walkProductionTs(root, abs));
+			continue;
+		}
+		if (!entry.isFile() || !entry.name.endsWith(".ts")) continue;
+		if (entry.name.endsWith(".test.ts") || SKIP_FILES.has(entry.name)) continue;
+		out.push(relative(root, abs));
+	}
+	return out;
+}