@danypops/pi-lector 0.1.0

package/extension/src/edit-operations.ts

@@ -0,0 +1,77 @@
+import { type ContentHash, remoteErrorIs } from "@danypops/lector";
+import type { EditOperations } from "@earendil-works/pi-coding-agent";
+import { lectorClient, withWorkspace, workspaceForPath } from "./lector-client.ts";
+import { toWorkspaceRelativePath } from "./workspace-relative-path.ts";
+
+/**
+ * EditOperations backed by Lector's hash-guarded exactEdit. The workspace
+ * for each call is resolved from the absolute path being edited, not a
+ * fixed cwd -- see workspaceForPath.
+ *
+ * pi's own EditOperations interface has no seam for passing a hash from
+ * readFile to writeFile -- it calls ops.readFile, computes the oldText/
+ * newText replacement itself, then calls ops.writeFile(absolutePath, content)
+ * with no memory of what was read. readFile() here stashes the hash it just
+ * observed in a short-lived per-absolutePath slot; writeFile() consumes
+ * (and clears) it as exactEdit's expectedHash. This is safe because pi's
+ * built-in edit tool already serializes readFile-then-writeFile for one
+ * absolutePath through withFileMutationQueue -- no other mutation on the
+ * same path can land between this readFile and this writeFile.
+ *
+ * A StaleExpectedHash here means the file changed on disk after the model's
+ * oldText was computed against a specific earlier read -- it surfaces as a
+ * real edit failure, not a silent retry: retrying would mean re-reading
+ * fresh content the model never saw and applying an oldText match computed
+ * against stale content, which could silently corrupt the file.
+ */
+export function createLectorEditOperations(): EditOperations {
+	const observedHashByPath = new Map<string, ContentHash>();
+
+	return {
+		async readFile(absolutePath) {
+			return withWorkspace(
+				() => workspaceForPath(absolutePath),
+				async ({ workspaceId, root }) => {
+					const client = await lectorClient();
+					const relativePath = toWorkspaceRelativePath(root, absolutePath);
+					const { content, hash } = await client.call("workspace.rawRead", { workspaceId, path: relativePath });
+					observedHashByPath.set(absolutePath, hash);
+					return Buffer.from(content, "utf-8");
+				},
+			);
+		},
+
+		async writeFile(absolutePath, content) {
+			const expectedHash = observedHashByPath.get(absolutePath) ?? null;
+			observedHashByPath.delete(absolutePath);
+			await withWorkspace(
+				() => workspaceForPath(absolutePath),
+				async ({ workspaceId, root }) => {
+					const client = await lectorClient();
+					const relativePath = toWorkspaceRelativePath(root, absolutePath);
+					try {
+						await client.call("workspace.exactEdit", { workspaceId, path: relativePath, expectedHash, content });
+					} catch (error) {
+						if (remoteErrorIs(error, "StaleExpectedHash")) {
+							throw new Error(`"${relativePath}" changed on disk since it was last read; re-read the file and retry the edit.`);
+						}
+						throw error;
+					}
+				},
+			);
+		},
+
+		async access(absolutePath) {
+			// workspace.rawRead itself rejects a missing entry -- exactly the "not accessible"
+			// signal pi's edit tool expects access() to throw for.
+			await withWorkspace(
+				() => workspaceForPath(absolutePath),
+				async ({ workspaceId, root }) => {
+					const client = await lectorClient();
+					const relativePath = toWorkspaceRelativePath(root, absolutePath);
+					await client.call("workspace.rawRead", { workspaceId, path: relativePath });
+				},
+			);
+		},
+	};
+}

package/extension/src/find-symbols-operations.ts

@@ -0,0 +1,34 @@
+import type { WorkspaceSymbol } from "@danypops/lector";
+import { lectorClient, withWorkspace, workspaceForDirectory } from "./lector-client.ts";
+
+/**
+ * Thin wrapper over workspace.findSymbols. No seedFile parameter here or
+ * anywhere above this call: Lector's discoverSeedFile() bounded
+ * auto-discovery fully absorbs that tsserver implementation detail, so a
+ * pi tool schema (and the model calling it) never needs to know it exists.
+ *
+ * `directory` is required, not an optional override with a hidden default:
+ * exactly like rawRead/exactEdit require an explicit path rather than
+ * defaulting to "whatever file was last touched," a symbol query requires
+ * an explicit project rather than silently defaulting to the session's own
+ * cwd. The caller passes cwd itself to search the current project -- there
+ * is no implicit fallback anywhere in this module.
+ */
+export interface FindSymbolsOperations {
+	findSymbols(query: string, directory: string): Promise<readonly WorkspaceSymbol[]>;
+}
+
+export function createLectorFindSymbolsOperations(): FindSymbolsOperations {
+	return {
+		async findSymbols(query, directory) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					const { symbols } = await client.call("workspace.findSymbols", { workspaceId, query });
+					return symbols;
+				},
+			);
+		},
+	};
+}

package/extension/src/find-symbols-rendering.ts

@@ -0,0 +1,54 @@
+import type { WorkspaceSymbol } from "@danypops/lector";
+import { keyHint } from "@earendil-works/pi-coding-agent";
+import { colorForKind, formatLocation, type LectorTheme } from "./lector-tui-theme.ts";
+
+/**
+ * Custom TUI rendering for find_symbols -- the one Lector-backed tool with
+ * no built-in pi-coding-agent equivalent to inherit rendering from. read/
+ * write/edit get syntax highlighting, diffs, and truncation banners for
+ * free via createReadToolDefinition/etc.; this tool needs its own, built
+ * the same way pi's own built-ins are (see @earendil-works/pi-coding-agent's
+ * read.js/write.js/edit.js and the todo.ts example) -- theme.fg/theme.bold
+ * plus keyHint for the expand affordance, not ad-hoc plain text.
+ */
+export type FindSymbolsTheme = LectorTheme;
+
+const DEFAULT_VISIBLE_RESULTS = 8;
+
+export function formatFindSymbolsCall(args: { query?: unknown; directory?: unknown }, theme: FindSymbolsTheme): string {
+	const query = typeof args.query === "string" ? args.query : "";
+	let content = `${theme.fg("toolTitle", theme.bold("find_symbols"))} ${theme.fg("accent", `"${query}"`)}`;
+	if (typeof args.directory === "string" && args.directory.length > 0) {
+		content += ` ${theme.fg("muted", `in ${args.directory}`)}`;
+	}
+	return content;
+}
+
+/** One result line, kind-padded to the widest kind actually present so the name column lines up. */
+function formatSymbolLine(symbol: WorkspaceSymbol, theme: FindSymbolsTheme, kindColumnWidth: number): string {
+	const kind = theme.fg(colorForKind(symbol.kind), symbol.kind.padEnd(kindColumnWidth));
+	const name = theme.fg("text", theme.bold(symbol.name));
+	const location = formatLocation(theme, symbol.location.path, symbol.location.line, symbol.location.character);
+	return `${kind}  ${name}  ${location}`;
+}
+
+export function formatFindSymbolsResult(symbols: readonly WorkspaceSymbol[] | undefined, query: string, expanded: boolean, theme: FindSymbolsTheme): string {
+	if (!symbols || symbols.length === 0) {
+		return theme.fg("dim", `No symbols found matching "${query}".`);
+	}
+
+	const kindColumnWidth = Math.max(...symbols.map((symbol) => symbol.kind.length));
+	const displayCount = expanded ? symbols.length : Math.min(symbols.length, DEFAULT_VISIBLE_RESULTS);
+	const lines = [theme.fg("muted", `${symbols.length} symbol${symbols.length === 1 ? "" : "s"} matching "${query}":`)];
+
+	for (const symbol of symbols.slice(0, displayCount)) {
+		lines.push(formatSymbolLine(symbol, theme, kindColumnWidth));
+	}
+
+	const remaining = symbols.length - displayCount;
+	if (remaining > 0) {
+		lines.push(theme.fg("dim", `... ${remaining} more (${keyHint("app.tools.expand", "to expand")})`));
+	}
+
+	return lines.join("\n");
+}

package/extension/src/git-operations.ts

@@ -0,0 +1,46 @@
+import type { GitDiffResult, GitLogEntry, GitStatusSummary } from "@danypops/lector";
+import { lectorClient, withWorkspace, workspaceForDirectory } from "./lector-client.ts";
+
+/**
+ * Thin wrappers over Lector's read-only git operations. `directory` is
+ * required, same convention as find_symbols -- no implicit "whatever the
+ * session's cwd is" fallback.
+ */
+export interface GitOperations {
+	status(directory: string): Promise<GitStatusSummary>;
+	log(directory: string, maxCount: number): Promise<readonly GitLogEntry[]>;
+	diff(directory: string, ref: string | undefined, maxBytes: number): Promise<GitDiffResult>;
+}
+
+export function createLectorGitOperations(): GitOperations {
+	return {
+		async status(directory) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.gitStatus", { workspaceId });
+				},
+			);
+		},
+		async log(directory, maxCount) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					const { entries } = await client.call("workspace.gitLog", { workspaceId, maxCount });
+					return entries;
+				},
+			);
+		},
+		async diff(directory, ref, maxBytes) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.gitDiff", { workspaceId, ref, maxBytes });
+				},
+			);
+		},
+	};
+}

package/extension/src/git-rendering.ts

@@ -0,0 +1,64 @@
+import type { GitDiffResult, GitLogEntry, GitStatusSummary } from "@danypops/lector";
+import { keyHint } from "@earendil-works/pi-coding-agent";
+import type { LectorTheme } from "./lector-tui-theme.ts";
+
+const DEFAULT_VISIBLE_FILES = 20;
+const DEFAULT_VISIBLE_COMMITS = 10;
+const DEFAULT_VISIBLE_DIFF_LINES = 60;
+
+export function formatGitStatusCall(args: { directory?: unknown }, theme: LectorTheme): string {
+	const directory = typeof args.directory === "string" ? args.directory : "";
+	return `${theme.fg("toolTitle", theme.bold("git_status"))} ${theme.fg("accent", directory)}`;
+}
+
+export function formatGitStatusResult(summary: GitStatusSummary | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!summary) return theme.fg("dim", "No status available.");
+	const branch = summary.current ?? "(detached)";
+	const tracking = summary.tracking ? `, tracking ${summary.tracking} (+${summary.ahead}/-${summary.behind})` : "";
+	const lines = [theme.fg("accent", `On branch ${branch}${tracking}`)];
+	if (summary.files.length === 0) {
+		lines.push(theme.fg("dim", "working tree clean"));
+		return lines.join("\n");
+	}
+	const displayCount = expanded ? summary.files.length : Math.min(DEFAULT_VISIBLE_FILES, summary.files.length);
+	for (const file of summary.files.slice(0, displayCount)) {
+		const code = `${file.indexStatus}${file.workingDirStatus}`;
+		lines.push(file.renamedFrom ? `${code} ${file.renamedFrom} -> ${file.path}` : `${code} ${file.path}`);
+	}
+	const remaining = summary.files.length - displayCount;
+	if (remaining > 0) lines.push(theme.fg("dim", `... ${remaining} more (${keyHint("app.tools.expand", "to expand")})`));
+	return lines.join("\n");
+}
+
+export function formatGitLogCall(args: { directory?: unknown; maxCount?: unknown }, theme: LectorTheme): string {
+	const directory = typeof args.directory === "string" ? args.directory : "";
+	return `${theme.fg("toolTitle", theme.bold("git_log"))} ${theme.fg("accent", directory)}`;
+}
+
+export function formatGitLogResult(entries: readonly GitLogEntry[] | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!entries || entries.length === 0) return theme.fg("dim", "No commits found.");
+	const displayCount = expanded ? entries.length : Math.min(DEFAULT_VISIBLE_COMMITS, entries.length);
+	const lines = entries
+		.slice(0, displayCount)
+		.map((entry) => `${theme.fg("accent", entry.sha.slice(0, 8))} ${entry.authoredAt} ${entry.authorName} -- ${entry.message}`);
+	const remaining = entries.length - displayCount;
+	if (remaining > 0) lines.push(theme.fg("dim", `... ${remaining} more (${keyHint("app.tools.expand", "to expand")})`));
+	return lines.join("\n");
+}
+
+export function formatGitDiffCall(args: { directory?: unknown; ref?: unknown }, theme: LectorTheme): string {
+	const directory = typeof args.directory === "string" ? args.directory : "";
+	const ref = typeof args.ref === "string" ? ` ${args.ref}` : "";
+	return `${theme.fg("toolTitle", theme.bold("git_diff"))} ${theme.fg("accent", directory)}${ref}`;
+}
+
+export function formatGitDiffResult(result: GitDiffResult | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!result || result.diff.length === 0) return theme.fg("dim", "No differences.");
+	const lines = result.diff.split("\n");
+	const displayCount = expanded ? lines.length : Math.min(DEFAULT_VISIBLE_DIFF_LINES, lines.length);
+	const shown = lines.slice(0, displayCount).join("\n");
+	const remaining = lines.length - displayCount;
+	const truncationNote = remaining > 0 ? `\n${theme.fg("dim", `... ${remaining} more lines (${keyHint("app.tools.expand", "to expand")})`)}` : "";
+	const boundedNote = result.truncated ? `\n${theme.fg("warning", "(diff output itself was truncated by maxBytes)")}` : "";
+	return shown + truncationNote + boundedNote;
+}