@danypops/pi-lector 0.12.13 → 0.12.15

package/extension/src/git/operations.ts

@@ -3,9 +3,15 @@ import { lectorClient, withWorkspace, workspaceForDirectory } from "../lector-cl
 import { invokeLectorVehicleOperation, type LectorVehicleCall } from "../vehicle-client.ts";
 
 type SymbolComparison = OperationOutputs["workspace.compareSymbolAcrossVersions"];
+type GitWorktreeAddResult = OperationOutputs["workspace.gitWorktreeAdd"];
+type GitWorktreeRemoveResult = OperationOutputs["workspace.gitWorktreeRemove"];
+type GitGrepResult = OperationOutputs["workspace.gitGrep"];
+type GitListFilesResult = OperationOutputs["workspace.gitListFiles"];
 
 /** Matches GIT_READ_PERMISSIONS' own declared value server-side (git/operation-registration.ts). */
 const GIT_READ_PERMISSIONS = ["workspace:read"];
+/** Matches GIT_WORKTREE_WRITE_PERMISSIONS' own declared value server-side (git/operation-registration.ts). */
+const GIT_WORKTREE_WRITE_PERMISSIONS = ["workspace:write"];
 
 /**
  * Thin wrappers over Lector's read-only git operations. `directory` is
@@ -24,6 +30,31 @@ export interface GitOperations {
 	log(directory: string, maxCount: number, call: LectorVehicleCall): Promise<readonly GitLogEntry[]>;
 	diff(directory: string, ref: string | undefined, maxBytes: number, call: LectorVehicleCall): Promise<GitDiffResult>;
 	compareSymbol(directory: string, path: string, symbolName: string, fromRef: string, toRef: string | undefined, maxBytes: number): Promise<SymbolComparison>;
+	/** A path's exact blob content at `ref`, without checking anything out -- Tier 1's own showFile, undefined content meaning the path did not exist there. */
+	showFile(directory: string, ref: string, path: string, call: LectorVehicleCall): Promise<string | undefined>;
+	/** Text search across `ref`'s own tree, no checkout -- the ref-scoped equivalent of search_code. pathspecs narrows the search (glob-based, e.g. "*.go"). */
+	grep(
+		directory: string,
+		ref: string,
+		pattern: string,
+		pathspecs: readonly string[] | undefined,
+		maxMatches: number,
+		maxBytes: number,
+		call: LectorVehicleCall,
+	): Promise<GitGrepResult>;
+	/** Every file path in `ref`'s own tree, no checkout -- pathspecs narrows the listing (prefix-based, not glob-based like grep's). */
+	listFiles(directory: string, ref: string, pathspecs: readonly string[] | undefined, maxResults: number, call: LectorVehicleCall): Promise<GitListFilesResult>;
+	/** True iff ancestorRef is a real ancestor of (or the exact same commit as) ref -- the backport/reachability check "was this fix ported to this branch" actually needs. */
+	isAncestor(directory: string, ancestorRef: string, ref: string, call: LectorVehicleCall): Promise<boolean>;
+	/**
+	 * Materializes a real, disposable, read-only project at `ref` via a detached git worktree.
+	 * The returned `path` is a real directory every other pi-lector tool already accepts as its
+	 * own `directory` argument (find_symbols, search_code, git itself, ...) -- no separate
+	 * workspaceId ever needs to reach the agent.
+	 */
+	worktreeAdd(directory: string, ref: string, forceRefresh: boolean | undefined, call: LectorVehicleCall): Promise<GitWorktreeAddResult>;
+	/** `directory` is the worktree's own path (worktreeAdd's returned `path`), not the source repo's -- it resolves to the exact same workspace via the same git-root walk every other tool already uses. */
+	worktreeRemove(directory: string, call: LectorVehicleCall): Promise<GitWorktreeRemoveResult>;
 }
 
 export function createLectorGitOperations(): GitOperations {
@@ -63,5 +94,71 @@ export function createLectorGitOperations(): GitOperations {
 				},
 			);
 		},
+		async worktreeAdd(directory, ref, forceRefresh, call) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				({ workspaceId }) =>
+					invokeLectorVehicleOperation<GitWorktreeAddResult>(
+						"workspace.gitWorktreeAdd",
+						{ workspaceId, ref, forceRefresh },
+						GIT_WORKTREE_WRITE_PERMISSIONS,
+						call,
+					),
+			);
+		},
+		async worktreeRemove(directory, call) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				({ workspaceId }) =>
+					invokeLectorVehicleOperation<GitWorktreeRemoveResult>("workspace.gitWorktreeRemove", { workspaceId }, GIT_WORKTREE_WRITE_PERMISSIONS, call),
+			);
+		},
+		async showFile(directory, ref, path, call) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				async ({ workspaceId }) => {
+					const { content } = await invokeLectorVehicleOperation<{ content: string | undefined }>(
+						"workspace.gitShowFile",
+						{ workspaceId, ref, path },
+						GIT_READ_PERMISSIONS,
+						call,
+					);
+					return content;
+				},
+			);
+		},
+		async grep(directory, ref, pattern, pathspecs, maxMatches, maxBytes, call) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				({ workspaceId }) =>
+					invokeLectorVehicleOperation<GitGrepResult>(
+						"workspace.gitGrep",
+						{ workspaceId, ref, pattern, pathspecs, maxMatches, maxBytes },
+						GIT_READ_PERMISSIONS,
+						call,
+					),
+			);
+		},
+		async listFiles(directory, ref, pathspecs, maxResults, call) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				({ workspaceId }) =>
+					invokeLectorVehicleOperation<GitListFilesResult>("workspace.gitListFiles", { workspaceId, ref, pathspecs, maxResults }, GIT_READ_PERMISSIONS, call),
+			);
+		},
+		async isAncestor(directory, ancestorRef, ref, call) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				async ({ workspaceId }) => {
+					const { isAncestor } = await invokeLectorVehicleOperation<{ isAncestor: boolean }>(
+						"workspace.gitIsAncestor",
+						{ workspaceId, ancestorRef, ref },
+						GIT_READ_PERMISSIONS,
+						call,
+					);
+					return isAncestor;
+				},
+			);
+		},
 	};
 }

package/extension/src/git/rendering.ts

@@ -11,9 +11,13 @@ const DEFAULT_VISIBLE_FILES = 20;
 const DEFAULT_VISIBLE_COMMITS = 10;
 const DEFAULT_VISIBLE_DIFF_LINES = 60;
 
-export type GitAction = "status" | "log" | "diff" | "compare-symbol";
+export type GitAction = "status" | "log" | "diff" | "compare-symbol" | "worktree-add" | "worktree-remove" | "show" | "grep-ref" | "ls-ref" | "is-ancestor";
 
 type SymbolComparison = OperationOutputs["workspace.compareSymbolAcrossVersions"];
+type GitWorktreeAddResult = OperationOutputs["workspace.gitWorktreeAdd"];
+type GitWorktreeRemoveResult = OperationOutputs["workspace.gitWorktreeRemove"];
+type GitGrepResult = OperationOutputs["workspace.gitGrep"];
+type GitListFilesResult = OperationOutputs["workspace.gitListFiles"];
 
 export interface GitToolDetails {
 	readonly action: GitAction;
@@ -21,10 +25,26 @@ export interface GitToolDetails {
 	readonly entries?: readonly GitLogEntry[];
 	readonly result?: GitDiffResult;
 	readonly comparison?: SymbolComparison;
+	readonly worktreeAdd?: GitWorktreeAddResult;
+	readonly worktreeRemove?: GitWorktreeRemoveResult;
+	readonly showFile?: { readonly ref: string; readonly path: string; readonly content: string | undefined };
+	readonly grep?: GitGrepResult;
+	readonly listFiles?: GitListFilesResult;
+	readonly isAncestor?: { readonly ancestorRef: string; readonly ref: string; readonly result: boolean };
 }
 
 export function formatGitCall(
-	args: { action?: unknown; directory?: unknown; ref?: unknown; path?: unknown; symbol?: unknown; fromRef?: unknown; toRef?: unknown },
+	args: {
+		action?: unknown;
+		directory?: unknown;
+		ref?: unknown;
+		path?: unknown;
+		symbol?: unknown;
+		fromRef?: unknown;
+		toRef?: unknown;
+		pattern?: unknown;
+		ancestorRef?: unknown;
+	},
 	theme: LectorTheme,
 ): string {
 	const action = typeof args.action === "string" ? args.action : "";
@@ -36,15 +56,85 @@ export function formatGitCall(
 		const toRef = typeof args.toRef === "string" ? ` -> ${args.toRef}` : "";
 		return `${theme.fg("toolTitle", theme.bold("git"))} ${theme.fg("muted", action)} ${theme.fg("accent", `${directory}/${path}`)} (${symbol}) ${fromRef}${toRef}`;
 	}
+	if (action === "is-ancestor") {
+		const ancestorRef = typeof args.ancestorRef === "string" ? args.ancestorRef : "";
+		const ref = typeof args.ref === "string" ? args.ref : "";
+		return `${theme.fg("toolTitle", theme.bold("git"))} ${theme.fg("muted", action)} ${theme.fg("accent", directory)} ${ancestorRef} -> ${ref}`;
+	}
+	if (action === "grep-ref") {
+		const ref = typeof args.ref === "string" ? args.ref : "";
+		const pattern = typeof args.pattern === "string" ? args.pattern : "";
+		return `${theme.fg("toolTitle", theme.bold("git"))} ${theme.fg("muted", action)} ${theme.fg("accent", directory)} ${ref} "${pattern}"`;
+	}
+	if (action === "show") {
+		const ref = typeof args.ref === "string" ? args.ref : "";
+		const path = typeof args.path === "string" ? args.path : "";
+		return `${theme.fg("toolTitle", theme.bold("git"))} ${theme.fg("muted", action)} ${theme.fg("accent", `${directory}/${path}`)} @ ${ref}`;
+	}
 	const ref = typeof args.ref === "string" ? ` ${args.ref}` : "";
 	return `${theme.fg("toolTitle", theme.bold("git"))} ${theme.fg("muted", action)} ${theme.fg("accent", directory)}${ref}`;
 }
 
+function formatGitWorktreeAddResult(result: GitWorktreeAddResult | undefined, theme: LectorTheme): string {
+	if (!result) return theme.fg("dim", "No result.");
+	const verb = result.created ? "created" : "reused existing";
+	return [theme.fg("accent", `${verb} worktree at ${result.ref} (${result.commit.slice(0, 8)})`), theme.fg("muted", result.path)].join("\n");
+}
+
+function formatGitWorktreeRemoveResult(result: GitWorktreeRemoveResult | undefined, theme: LectorTheme): string {
+	if (!result) return theme.fg("dim", "No result.");
+	return theme.fg("accent", "worktree removed");
+}
+
+function formatGitShowFileResult(details: GitToolDetails["showFile"], theme: LectorTheme): string {
+	if (!details) return theme.fg("dim", "No result.");
+	if (details.content === undefined) return theme.fg("dim", `"${details.path}" does not exist at ${details.ref}`);
+	return details.content;
+}
+
+function formatGitGrepResult(result: GitGrepResult | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!result || result.matches.length === 0) return theme.fg("dim", "No matches.");
+	const lines = renderTruncatedList({
+		items: result.matches,
+		expanded,
+		visibleCount: DEFAULT_VISIBLE_FILES,
+		formatItem: (match) => `${theme.fg("accent", `${match.path}:${match.line}`)}:${match.text}`,
+		moreLine: moreLine(theme),
+		truncationWarning: result.truncated ? theme.fg("warning", "(also bounded by maxMatches/maxBytes)") : undefined,
+	});
+	return lines.join("\n");
+}
+
+function formatGitListFilesResult(result: GitListFilesResult | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!result || result.paths.length === 0) return theme.fg("dim", "No files.");
+	const lines = renderTruncatedList({
+		items: result.paths,
+		expanded,
+		visibleCount: DEFAULT_VISIBLE_FILES,
+		formatItem: (path) => path,
+		moreLine: moreLine(theme),
+		truncationWarning: result.truncated ? theme.fg("warning", "(bounded by maxResults)") : undefined,
+	});
+	return lines.join("\n");
+}
+
+function formatGitIsAncestorResult(details: GitToolDetails["isAncestor"], theme: LectorTheme): string {
+	if (!details) return theme.fg("dim", "No result.");
+	const verb = details.result ? "is" : "is not";
+	return theme.fg("accent", `${details.ancestorRef} ${verb} an ancestor of ${details.ref}`);
+}
+
 export function formatGitResult(details: GitToolDetails | undefined, expanded: boolean, theme: LectorTheme): string {
 	if (!details) return theme.fg("dim", "No result.");
 	if (details.action === "status") return formatGitStatusResult(details.summary, expanded, theme);
 	if (details.action === "log") return formatGitLogResult(details.entries, expanded, theme);
 	if (details.action === "compare-symbol") return formatCompareSymbolResult(details.comparison, expanded, theme);
+	if (details.action === "worktree-add") return formatGitWorktreeAddResult(details.worktreeAdd, theme);
+	if (details.action === "worktree-remove") return formatGitWorktreeRemoveResult(details.worktreeRemove, theme);
+	if (details.action === "show") return formatGitShowFileResult(details.showFile, theme);
+	if (details.action === "grep-ref") return formatGitGrepResult(details.grep, expanded, theme);
+	if (details.action === "ls-ref") return formatGitListFilesResult(details.listFiles, expanded, theme);
+	if (details.action === "is-ancestor") return formatGitIsAncestorResult(details.isAncestor, theme);
 	return formatGitDiffResult(details.result, expanded, theme);
 }
 

package/extension/src/index.ts

@@ -1246,26 +1246,54 @@ export default function (pi: ExtensionAPI) {
 			name: "git",
 			label: "Git",
 			description:
-				"Working tree status, recent commit log, unified diff, and one symbol's own declaration diff across two versions, for a real git repository, in one tool. Fails clearly if `directory` is not inside a git repository. ACTIONS: status (working tree state, ahead/behind tracking), log (recent commits, bounded by maxCount), diff (unified diff against `ref`, defaulting to HEAD, bounded by maxBytes), compare-symbol (a named symbol's own declaration text diffed between fromRef and toRef, or fromRef and the current working tree when toRef is omitted -- tree-sitter syntactic tier only, TypeScript/JavaScript files only, no project-aware cross-reference resolution).",
-			promptSnippet: "Show a repository's status, log, diff, or one symbol's diff across versions",
+				"Working tree status, recent commit log, unified diff, one symbol's own declaration diff across two versions, ref-scoped blob/text/ancestry queries with no checkout, and a real disposable checkout at another ref, for a real git repository, in one tool. Fails clearly if `directory` is not inside a git repository. ACTIONS: status (working tree state, ahead/behind tracking), log (recent commits, bounded by maxCount), diff (unified diff against `ref`, defaulting to HEAD, bounded by maxBytes), compare-symbol (a named symbol's own declaration text diffed between fromRef and toRef, or fromRef and the current working tree when toRef is omitted -- tree-sitter syntactic tier only, TypeScript/JavaScript files only, no project-aware cross-reference resolution), show (a path's exact blob content at `ref`, no checkout), grep-ref (text search across `ref`'s own tree, no checkout -- the ref-scoped equivalent of search_code), ls-ref (every file path in `ref`'s own tree, no checkout), is-ancestor (is `ancestorRef` a real ancestor of, or the same commit as, `ref` -- the backport/reachability check \"was this fix ported to this branch\" actually needs), worktree-add (materializes `ref` as a real, read-only project via a detached git worktree and returns its own `directory` -- pass that straight to find_symbols/search_code/this tool itself for full semantic queries against another branch/commit, not just text), worktree-remove (releases and deletes a worktree-add-created checkout -- `directory` is that checkout's own returned directory, not the source repo's).",
+			promptSnippet:
+				"Show a repository's status, log, diff, one symbol's diff across versions, a ref-scoped blob/text/ancestry query, or a real checkout at another ref",
 			promptGuidelines: [
-				"maxCount is required for action=log; maxBytes is required for action=diff/compare-symbol -- every bounded query needs its bound stated explicitly, never defaulted silently.",
+				"maxCount is required for action=log; maxBytes is required for action=diff/compare-symbol/grep-ref -- every bounded query needs its bound stated explicitly, never defaulted silently.",
 				"path, symbol, and fromRef are required for action=compare-symbol; toRef is optional and means 'the current working tree' when omitted.",
+				"ref is required for action=worktree-add. A repeated worktree-add for the same (directory, ref) reuses the existing checkout unless forceRefresh is set -- use that when ref is a branch that may have moved.",
+				"action=worktree-remove's directory is worktree-add's own returned directory, never the source repo's -- always call it once done with a worktree to reclaim disk.",
+				"ref and path are required for action=show; ref and pattern (maxMatches, maxBytes) are required for action=grep-ref; ref (maxResults) is required for action=ls-ref; ancestorRef and ref are required for action=is-ancestor. None of the four checks anything out -- prefer them over worktree-add/find_symbols for a quick existence/text/ancestry answer.",
 			],
 			parameters: Type.Object({
-				action: Type.String({ description: "status | log | diff | compare-symbol" }),
+				action: Type.String({ description: "status | log | diff | compare-symbol | show | grep-ref | ls-ref | is-ancestor | worktree-add | worktree-remove" }),
 				directory: Type.String({ description: "Directory inside the repository to check, absolute or relative to the current working directory" }),
 				maxCount: Type.Optional(Type.Number({ description: "Maximum number of commits to return, most recent first -- required for action=log" })),
-				ref: Type.Optional(Type.String({ description: "Ref to diff against; defaults to HEAD -- only used for action=diff" })),
+				ref: Type.Optional(
+					Type.String({
+						description:
+							"Ref to diff against (defaults to HEAD) for action=diff, or to check out/query for action=worktree-add/show/grep-ref/ls-ref/is-ancestor (required for those)",
+					}),
+				),
 				maxBytes: Type.Optional(
-					Type.Number({ description: "Maximum diff/comparison size in bytes before truncating -- required for action=diff/compare-symbol" }),
+					Type.Number({
+						description: "Maximum diff/comparison/grep output size in bytes before truncating -- required for action=diff/compare-symbol/grep-ref",
+					}),
+				),
+				path: Type.Optional(
+					Type.String({ description: "File path (relative to directory) containing the symbol, or to read -- required for action=compare-symbol/show" }),
 				),
-				path: Type.Optional(Type.String({ description: "File path (relative to directory) containing the symbol -- required for action=compare-symbol" })),
 				symbol: Type.Optional(Type.String({ description: "Exact symbol name to compare -- required for action=compare-symbol" })),
 				fromRef: Type.Optional(Type.String({ description: "Git ref for the 'before' version -- required for action=compare-symbol" })),
 				toRef: Type.Optional(
 					Type.String({ description: "Git ref for the 'after' version; omit to compare against the current working tree -- action=compare-symbol only" }),
 				),
+				forceRefresh: Type.Optional(
+					Type.Boolean({
+						description: "action=worktree-add only: recreate an already-reused worktree at ref's current tip instead of returning the existing one",
+					}),
+				),
+				pattern: Type.Optional(Type.String({ description: "Text pattern to search for -- required for action=grep-ref" })),
+				pathspecs: Type.Optional(
+					Type.Array(Type.String(), {
+						description:
+							'Narrows action=grep-ref (glob-based, e.g. "*.go") or action=ls-ref (prefix-based, e.g. "pkg/dpll"); omitted searches/lists the whole tree',
+					}),
+				),
+				maxMatches: Type.Optional(Type.Number({ description: "Maximum grep matches to return -- required for action=grep-ref" })),
+				maxResults: Type.Optional(Type.Number({ description: "Maximum file paths to return -- required for action=ls-ref" })),
+				ancestorRef: Type.Optional(Type.String({ description: "The candidate ancestor ref -- required for action=is-ancestor" })),
 			}),
 			async execute(toolCallId, params, signal, _onUpdate, ctx): Promise<AgentToolResult<GitToolDetails>> {
 				const directory = resolve(cwd, params.directory);
@@ -1296,6 +1324,43 @@ export default function (pi: ExtensionAPI) {
 					const details: GitToolDetails = { action: "compare-symbol", comparison };
 					return { content: [{ type: "text", text: JSON.stringify(comparison) }], details };
 				}
+				if (params.action === "worktree-add") {
+					if (!params.ref) throw new Error("git action=worktree-add requires ref");
+					const worktreeAdd = await gitOperations.worktreeAdd(directory, params.ref, params.forceRefresh, vehicleCall);
+					const details: GitToolDetails = { action: "worktree-add", worktreeAdd };
+					return { content: [{ type: "text", text: JSON.stringify(worktreeAdd) }], details };
+				}
+				if (params.action === "worktree-remove") {
+					const worktreeRemove = await gitOperations.worktreeRemove(directory, vehicleCall);
+					const details: GitToolDetails = { action: "worktree-remove", worktreeRemove };
+					return { content: [{ type: "text", text: JSON.stringify(worktreeRemove) }], details };
+				}
+				if (params.action === "show") {
+					if (!params.ref || !params.path) throw new Error("git action=show requires ref and path");
+					const content = await gitOperations.showFile(directory, params.ref, params.path, vehicleCall);
+					const details: GitToolDetails = { action: "show", showFile: { ref: params.ref, path: params.path, content } };
+					return { content: [{ type: "text", text: content ?? `"${params.path}" does not exist at ${params.ref}` }], details };
+				}
+				if (params.action === "grep-ref") {
+					if (!params.ref || !params.pattern) throw new Error("git action=grep-ref requires ref and pattern");
+					if (params.maxMatches === undefined || params.maxBytes === undefined) throw new Error("git action=grep-ref requires maxMatches and maxBytes");
+					const grep = await gitOperations.grep(directory, params.ref, params.pattern, params.pathspecs, params.maxMatches, params.maxBytes, vehicleCall);
+					const details: GitToolDetails = { action: "grep-ref", grep };
+					return { content: [{ type: "text", text: JSON.stringify(grep) }], details };
+				}
+				if (params.action === "ls-ref") {
+					if (!params.ref) throw new Error("git action=ls-ref requires ref");
+					if (params.maxResults === undefined) throw new Error("git action=ls-ref requires maxResults");
+					const listFiles = await gitOperations.listFiles(directory, params.ref, params.pathspecs, params.maxResults, vehicleCall);
+					const details: GitToolDetails = { action: "ls-ref", listFiles };
+					return { content: [{ type: "text", text: JSON.stringify(listFiles) }], details };
+				}
+				if (params.action === "is-ancestor") {
+					if (!params.ancestorRef || !params.ref) throw new Error("git action=is-ancestor requires ancestorRef and ref");
+					const result = await gitOperations.isAncestor(directory, params.ancestorRef, params.ref, vehicleCall);
+					const details: GitToolDetails = { action: "is-ancestor", isAncestor: { ancestorRef: params.ancestorRef, ref: params.ref, result } };
+					return { content: [{ type: "text", text: JSON.stringify({ isAncestor: result }) }], details };
+				}
 				throw new Error(`unknown git action: ${String(params.action)}`);
 			},
 			renderCall(args, theme, context) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.12.13",
+	"version": "0.12.15",
 	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
 	"license": "MIT",
 	"type": "module",