@danypops/pi-lector 0.5.0 → 0.6.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,
@@ -63,6 +66,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";
@@ -1520,6 +1530,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 ?? 20;
+				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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.5.0",
+	"version": "0.6.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.7.0"
 	},
 	"devDependencies": {
 		"@earendil-works/pi-ai": "^0.81.1",