@danypops/pi-lector 0.5.0 → 0.7.0

package/extension/src/external-search-operations.ts

@@ -0,0 +1,26 @@
+import type { GithubRepoSearchResult, NpmPackageCandidate, SourcegraphCodeCandidate } from "@danypops/lector";
+import { lectorClient } from "./lector-client.ts";
+
+/** Thin wrapper over search.githubRepos/search.npmPackages/search.sourcegraphCode -- explicit-query discovery inputs shaped for repo_cache/package_source, never open-ended discovery/trending. */
+export interface ExternalSearchOperations {
+	githubRepos(query: string, maxResults: number): Promise<GithubRepoSearchResult>;
+	npmPackages(query: string, maxResults: number): Promise<{ candidates: readonly NpmPackageCandidate[] }>;
+	sourcegraphCode(query: string, maxResults: number): Promise<{ candidates: readonly SourcegraphCodeCandidate[] }>;
+}
+
+export function createExternalSearchOperations(): ExternalSearchOperations {
+	return {
+		async githubRepos(query, maxResults) {
+			const client = await lectorClient();
+			return client.call("search.githubRepos", { query, maxResults });
+		},
+		async npmPackages(query, maxResults) {
+			const client = await lectorClient();
+			return client.call("search.npmPackages", { query, maxResults });
+		},
+		async sourcegraphCode(query, maxResults) {
+			const client = await lectorClient();
+			return client.call("search.sourcegraphCode", { query, maxResults });
+		},
+	};
+}

package/extension/src/external-search-rendering.ts

@@ -0,0 +1,27 @@
+import type { GithubRepoSearchResult, NpmPackageCandidate, SourcegraphCodeCandidate } from "@danypops/lector";
+import type { LectorTheme } from "./lector-tui-theme.ts";
+
+type ExternalSearchAction = "github_repos" | "npm_packages" | "sourcegraph_code";
+
+export function formatExternalSearchCall(action: ExternalSearchAction, args: { query?: unknown }, theme: LectorTheme): string {
+	const label = theme.fg("toolTitle", theme.bold("external_search"));
+	const query = typeof args.query === "string" ? args.query : "";
+	return `${label} ${theme.fg("accent", action)} ${theme.fg("dim", query)}`;
+}
+
+export function formatGithubRepoSearchResult(result: GithubRepoSearchResult | undefined, theme: LectorTheme): string {
+	if (!result) return theme.fg("dim", "No result.");
+	const count = result.candidates.length;
+	const summary = count === 0 ? theme.fg("dim", "no repositories matched") : theme.fg("success", `${count} repositor${count === 1 ? "y" : "ies"}`);
+	return result.authenticated ? summary : `${summary} ${theme.fg("warning", "(unauthenticated -- lower rate limit)")}`;
+}
+
+export function formatNpmPackageSearchResult(result: { candidates: readonly NpmPackageCandidate[] } | undefined, theme: LectorTheme): string {
+	const count = result?.candidates.length ?? 0;
+	return count === 0 ? theme.fg("dim", "no packages matched") : theme.fg("success", `${count} package${count === 1 ? "" : "s"}`);
+}
+
+export function formatSourcegraphCodeSearchResult(result: { candidates: readonly SourcegraphCodeCandidate[] } | undefined, theme: LectorTheme): string {
+	const count = result?.candidates.length ?? 0;
+	return count === 0 ? theme.fg("dim", "no code matches") : theme.fg("success", `${count} match${count === 1 ? "" : "es"}`);
+}

package/extension/src/index.ts

@@ -6,16 +6,19 @@ import type {
 	DocumentSymbolEntry,
 	EditOutcome,
 	FindFilesResult,
+	GithubRepoSearchResult,
 	Hover,
 	IntelligenceProvenance,
 	JobSnapshot,
 	LineEdit,
 	LineEditOutcome,
 	MutationHistoryEntry,
+	NpmPackageCandidate,
 	OperationOutputs,
 	PackageSourceOperationResult,
 	PopulateSymbolGraphResult,
 	RepoFetchResult,
+	SourcegraphCodeCandidate,
 	SymbolAnnotation,
 	SymbolNode,
 	SymbolSearchResult,
@@ -24,6 +27,7 @@ import type {
 	WorkspaceMapResult,
 	WorkspaceQueryOutcome,
 } from "@danypops/lector";
+import { DEFAULT_EXTERNAL_SEARCH_MAX_RESULTS } from "@danypops/lector";
 import {
 	type AgentToolResult,
 	createEditToolDefinition,
@@ -63,6 +67,13 @@ import {
 import { createLectorCrossWorkspaceSearchOperations } from "./cross-workspace-search-operations.ts";
 import { formatCrossWorkspaceCall, formatFindSymbolsAcrossProjectsResult, formatSearchTextAcrossProjectsResult } from "./cross-workspace-search-rendering.ts";
 import { createLectorEditOperations } from "./edit-operations.ts";
+import { createExternalSearchOperations } from "./external-search-operations.ts";
+import {
+	formatExternalSearchCall,
+	formatGithubRepoSearchResult,
+	formatNpmPackageSearchResult,
+	formatSourcegraphCodeSearchResult,
+} from "./external-search-rendering.ts";
 import { createLectorFindFilesOperations } from "./find-files-operations.ts";
 import { formatFindFilesCall, formatFindFilesResult } from "./find-files-rendering.ts";
 import { createLectorFindSymbolsOperations } from "./find-symbols-operations.ts";
@@ -73,7 +84,7 @@ import { setNewWorkspaceObserver } from "./lector-client.ts";
 import { createLectorLineEditOperations } from "./line-edit-operations.ts";
 import { formatLineEditCall, formatLineEditResult } from "./line-edit-rendering.ts";
 import { createMutationHistoryOperations } from "./mutation-history-operations.ts";
-import { nearestGitRoot } from "./nearest-workspace-root.ts";
+import { isFilesystemRoot, nearestGitRoot } from "./nearest-workspace-root.ts";
 import { createLectorPackageSourceOperations } from "./package-source-operations.ts";
 import { formatPackageSourceCall, formatPackageSourceResult } from "./package-source-rendering.ts";
 import { createLectorReadOperations } from "./read-operations.ts";
@@ -166,8 +177,16 @@ export default function (pi: ExtensionAPI) {
 		uiContext.ui.setStatus("lector-cache", uiContext.ui.theme.fg(worst, `Lector: ${summary}`));
 	}
 
-	/** Starts (or restarts, on a stale generation) monitoring one workspace root's cache lifecycle -- shared by session_start's own cwd root and every later root a tool call first touches. */
+	/**
+	 * Starts (or restarts, on a stale generation) monitoring one workspace root's cache
+	 * lifecycle -- shared by session_start's own cwd root and every later root a tool call
+	 * first touches. Refuses a bare filesystem root outright: workspaceForPath's own
+	 * intentional fallback for a raw read/write of a file outside any git repo can register
+	 * exactly this as a "new workspace", and auto-populating it would attempt a full
+	 * filesystem-wide symbol-graph scan -- confirmed live as a real, previously-shipped bug.
+	 */
 	function startMonitoringRoot(root: string, ctx: Parameters<Parameters<ExtensionAPI["on"]>[1]>[1]): void {
+		if (isFilesystemRoot(root)) return;
 		if (monitoringRoots.has(root)) return;
 		monitoringRoots.add(root);
 		const thisGeneration = sessionGeneration;
@@ -1520,6 +1539,62 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
+		type ExternalSearchToolDetails =
+			| { readonly action: "github_repos"; readonly result: GithubRepoSearchResult }
+			| { readonly action: "npm_packages"; readonly result: { candidates: readonly NpmPackageCandidate[] } }
+			| { readonly action: "sourcegraph_code"; readonly result: { candidates: readonly SourcegraphCodeCandidate[] } };
+
+		const externalSearchOperations = createExternalSearchOperations();
+		pi.registerTool({
+			name: "external_search",
+			label: "External Search",
+			description:
+				"Finds real prior art before writing new code -- explicit-query search only, never open-ended discovery/trending. action=github_repos searches GitHub repositories by name/description/topic (GitHub's own relevance ranking); candidates are shaped as direct repo_cache(action=fetch) inputs (host/owner/repo). Unauthenticated is rate-limited to 10 req/min; configure GITHUB_TOKEN on the daemon host for 30/min. action=npm_packages searches the public npm registry; candidates are shaped as direct package_source inputs (name, plus the version already returned). action=sourcegraph_code searches code content across public GitHub via sourcegraph.com -- \"which repos actually contain code matching X\", a genuinely different mode than the other two (which search names/metadata, not file contents); each candidate's repository field feeds repo_cache(action=fetch) once split on '/'. Every source is cached for a short TTL -- an identical query moments apart is served from cache, not re-fetched.",
+			promptSnippet: "Search GitHub repos, npm packages, or code content for prior art",
+			parameters: Type.Object({
+				action: Type.Union([Type.Literal("github_repos"), Type.Literal("npm_packages"), Type.Literal("sourcegraph_code")]),
+				query: Type.String({
+					description: "The search query -- repo/package name or description keywords for github_repos/npm_packages, code content for sourcegraph_code",
+				}),
+				maxResults: Type.Optional(Type.Number({ description: "Maximum candidates to return (default 20)" })),
+			}),
+			async execute(_toolCallId, params): Promise<AgentToolResult<ExternalSearchToolDetails>> {
+				const maxResults = params.maxResults ?? DEFAULT_EXTERNAL_SEARCH_MAX_RESULTS;
+				if (params.action === "github_repos") {
+					const result = await externalSearchOperations.githubRepos(params.query, maxResults);
+					return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "github_repos", result } };
+				}
+				if (params.action === "npm_packages") {
+					const result = await externalSearchOperations.npmPackages(params.query, maxResults);
+					return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "npm_packages", result } };
+				}
+				const result = await externalSearchOperations.sourcegraphCode(params.query, maxResults);
+				return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "sourcegraph_code", result } };
+			},
+			renderCall(args, theme, context) {
+				const action = args.action === "npm_packages" || args.action === "sourcegraph_code" ? args.action : "github_repos";
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatExternalSearchCall(action, args, theme));
+				return text;
+			},
+			renderResult(result, { isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Searching..."), 0, 0);
+				if (context.isError) {
+					const errorText = result.content
+						.filter((block) => block.type === "text")
+						.map((block) => block.text)
+						.join("\n");
+					return new Text(theme.fg("error", errorText || "external_search failed"), 0, 0);
+				}
+				const details = result.details as ExternalSearchToolDetails | undefined;
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				if (details?.action === "npm_packages") text.setText(formatNpmPackageSearchResult(details.result, theme));
+				else if (details?.action === "sourcegraph_code") text.setText(formatSourcegraphCodeSearchResult(details.result, theme));
+				else text.setText(formatGithubRepoSearchResult(details?.action === "github_repos" ? details.result : undefined, theme));
+				return text;
+			},
+		});
+
 		const crossWorkspaceSearchOperations = createLectorCrossWorkspaceSearchOperations();
 		pi.registerTool({
 			name: "find_symbols_across_projects",

package/extension/src/nearest-workspace-root.ts

@@ -2,39 +2,60 @@ import { existsSync } from "node:fs";
 import { dirname, join, parse } from "node:path";
 
 /**
- * The nearest enclosing git repository root starting from (and including)
- * a given directory, or undefined if none is found (e.g. /tmp scratch
- * files, dotfiles outside any repo). Callers choose their own fallback --
- * see lector-client.ts's workspaceForPath (falls back to the filesystem
- * root: any absolute path is fair game for read/write/edit, exactly as
- * Pi's built-in tools already allow) vs. workspaceForDirectory (falls back
- * to the directory itself: widening a symbol-search scope all the way to
- * the entire filesystem when a project isn't a git repo would be absurd).
- *
- * This -- not a Pi session's original cwd -- is Lector's real workspace
- * granularity. A session routinely touches many unrelated repos, sibling
- * projects, and scratch paths in one run; pi's built-in read/write/edit
- * tools have never restricted which absolute path can be touched, and
- * Lector must not either. (Real, shipped bug this fixes: read/write/edit
- * hard-locked to whatever directory the session happened to start in,
- * refusing every legitimate path outside it with a "Lector-registered
- * workspace root" error -- discovered live, in a separate session, working
- * against a completely different, unrelated repository.)
+ * The bare filesystem root is never a legitimate discovered project root, even if it happens
+ * to contain a marker file (a stray `git init /`, a leftover `package.json`) -- matches the
+ * same convention already established elsewhere in this house (oculus/survey/rust_scanner.go's
+ * findCrateRoot, oculus/locator/match.go's effectiveParent: reaching "/" during a walk-up means
+ * "not found", never "found here"). Confirmed live: without this, a Lector daemon registered
+ * "/" as a workspace and a background job attempted to symbol-graph the entire filesystem.
+ * `exists` is injectable so a test can simulate "a marker exists at the filesystem root"
+ * without ever touching the real one.
  */
-function walkUpForMarkers(startDirectory: string, markers: readonly string[]): string | undefined {
+function walkUpForMarkers(startDirectory: string, markers: readonly string[], exists: (path: string) => boolean = existsSync): string | undefined {
 	let dir = startDirectory;
 	const fsRoot = parse(dir).root;
 	while (dir !== fsRoot) {
-		if (markers.some((marker) => existsSync(join(dir, marker)))) return dir;
+		if (markers.some((marker) => exists(join(dir, marker)))) return dir;
 		const parent = dirname(dir);
 		if (parent === dir) break; // defensive: dirname must be strictly ascending
 		dir = parent;
 	}
-	return markers.some((marker) => existsSync(join(fsRoot, marker))) ? fsRoot : undefined;
+	return undefined;
+}
+
+/**
+ * The nearest enclosing git repository root starting from (and including) a given directory,
+ * or undefined if none is found (e.g. /tmp scratch files, dotfiles outside any repo, or the
+ * walk reaching the filesystem root without a match). Callers choose their own fallback -- see
+ * lector-client.ts's workspaceForPath (falls back to the filesystem root: any absolute path is
+ * fair game for read/write/edit, exactly as Pi's built-in tools already allow) vs.
+ * workspaceForDirectory (falls back to the directory itself: widening a symbol-search scope all
+ * the way to the entire filesystem when a project isn't a git repo would be absurd).
+ *
+ * This -- not a Pi session's original cwd -- is Lector's real workspace granularity. A session
+ * routinely touches many unrelated repos, sibling projects, and scratch paths in one run; Pi's
+ * built-in read/write/edit tools have never restricted which absolute path can be touched, and
+ * Lector must not either. (Real, shipped bug this fixes: read/write/edit hard-locked to
+ * whatever directory the session happened to start in, refusing every legitimate path outside
+ * it with a "Lector-registered workspace root" error -- discovered live, in a separate session,
+ * working against a completely different, unrelated repository.)
+ *
+ * `exists` is injectable for tests -- see walkUpForMarkers.
+ */
+/**
+ * True for the bare filesystem root itself ("/" on Linux/macOS, "C:\\" on Windows) -- the one
+ * path a caller must never treat as a real project to auto-index. workspaceForPath's own
+ * intentional fallback for a raw read/write of a file outside any git repo can still produce
+ * this value; callers that trigger background work (auto-population, cache monitoring) off a
+ * newly-registered workspace must check this explicitly rather than assuming
+ * nearestGitRoot/nearestProjectRoot are the only paths that can hand them a workspace root.
+ */
+export function isFilesystemRoot(path: string): boolean {
+	return parse(path).root === path;
 }
 
-export function nearestGitRoot(startDirectory: string): string | undefined {
-	return walkUpForMarkers(startDirectory, [".git"]);
+export function nearestGitRoot(startDirectory: string, exists: (path: string) => boolean = existsSync): string | undefined {
+	return walkUpForMarkers(startDirectory, [".git"], exists);
 }
 
 /**
@@ -45,6 +66,6 @@ export function nearestGitRoot(startDirectory: string): string | undefined {
  * misattributes its whole project to the repo root, handing the language server the wrong
  * rootUri (and, for TypeScript, the wrong tsconfig.json) even though a closer one exists.
  */
-export function nearestProjectRoot(startDirectory: string, rootMarkers: readonly string[]): string | undefined {
-	return walkUpForMarkers(startDirectory, [...rootMarkers, ".git"]);
+export function nearestProjectRoot(startDirectory: string, rootMarkers: readonly string[], exists: (path: string) => boolean = existsSync): string | undefined {
+	return walkUpForMarkers(startDirectory, [...rootMarkers, ".git"], exists);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.5.0",
+	"version": "0.7.0",
 	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
 	"license": "MIT",
 	"type": "module",
@@ -19,7 +19,7 @@
 	},
 	"dependencies": {
 		"@danypops/daemon-kit": "^0.22.1",
-		"@danypops/lector": "^0.6.0"
+		"@danypops/lector": "^0.8.0"
 	},
 	"devDependencies": {
 		"@earendil-works/pi-ai": "^0.81.1",