@danypops/pi-lector 0.12.12 → 0.12.14

package/extension/src/git/operations.ts

@@ -3,9 +3,13 @@ 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"];
 
 /** 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 +28,15 @@ 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>;
+	/**
+	 * 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 +76,24 @@ 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),
+			);
+		},
 	};
 }

package/extension/src/git/rendering.ts

@@ -11,9 +11,11 @@ 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";
 
 type SymbolComparison = OperationOutputs["workspace.compareSymbolAcrossVersions"];
+type GitWorktreeAddResult = OperationOutputs["workspace.gitWorktreeAdd"];
+type GitWorktreeRemoveResult = OperationOutputs["workspace.gitWorktreeRemove"];
 
 export interface GitToolDetails {
 	readonly action: GitAction;
@@ -21,6 +23,8 @@ export interface GitToolDetails {
 	readonly entries?: readonly GitLogEntry[];
 	readonly result?: GitDiffResult;
 	readonly comparison?: SymbolComparison;
+	readonly worktreeAdd?: GitWorktreeAddResult;
+	readonly worktreeRemove?: GitWorktreeRemoveResult;
 }
 
 export function formatGitCall(
@@ -40,11 +44,24 @@ export function formatGitCall(
 	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");
+}
+
 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);
 	return formatGitDiffResult(details.result, expanded, theme);
 }
 

package/extension/src/index.ts

@@ -216,7 +216,7 @@ export default function (pi: ExtensionAPI) {
 	 * 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.
+	 * filesystem-wide symbol-graph scan.
 	 *
 	 * Also short-circuits a broad host directory (home directory, an XDG config/cache/data
 	 * root, a dotfile directory) the exact same way workspace.populateSymbolGraph's own
@@ -1246,17 +1246,21 @@ 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, 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), 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, 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.",
 				"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.",
 			],
 			parameters: Type.Object({
-				action: Type.String({ description: "status | log | diff | compare-symbol" }),
+				action: Type.String({ description: "status | log | diff | compare-symbol | 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 for action=worktree-add (required)" }),
+				),
 				maxBytes: Type.Optional(
 					Type.Number({ description: "Maximum diff/comparison size in bytes before truncating -- required for action=diff/compare-symbol" }),
 				),
@@ -1266,6 +1270,11 @@ export default function (pi: ExtensionAPI) {
 				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",
+					}),
+				),
 			}),
 			async execute(toolCallId, params, signal, _onUpdate, ctx): Promise<AgentToolResult<GitToolDetails>> {
 				const directory = resolve(cwd, params.directory);
@@ -1296,6 +1305,17 @@ 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 };
+				}
 				throw new Error(`unknown git action: ${String(params.action)}`);
 			},
 			renderCall(args, theme, context) {
@@ -1697,7 +1717,17 @@ export default function (pi: ExtensionAPI) {
 				if (details?.action === "list") text.setText(formatPackageSourceListResult(details.page, theme));
 				else if (details?.action === "remove") text.setText(formatPackageSourceRemoveResult(details.result, theme));
 				else if (details?.action === "clean") text.setText(formatPackageSourceCleanResult(details.result, theme));
-				else text.setText(formatPackageSourceResult(details?.action === "resolve" ? details.result : undefined, expanded, theme));
+				else if (details?.action === "resolve") text.setText(formatPackageSourceResult(details.result, expanded, theme));
+				else {
+					// A malformed/unknown-shaped details blob (e.g. a transcript row predating this
+					// schema) has no recognized action -- fail closed to the model-facing content
+					// channel first, only falling to the generic message if that's empty too.
+					const contentText = result.content
+						.filter((block) => block.type === "text")
+						.map((block) => block.text)
+						.join("\n");
+					text.setText(contentText || formatPackageSourceResult(undefined, expanded, theme));
+				}
 				return text;
 			},
 		});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.12.12",
+	"version": "0.12.14",
 	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
 	"license": "MIT",
 	"type": "module",
@@ -30,6 +30,7 @@
 	},
 	"devDependencies": {
 		"@danypops/vehicle-client-pi": "^0.43.0",
+		"@danypops/vehicle-conformance": "^0.4.0",
 		"@danypops/pi-extension-harness": "^0.2.0",
 		"@danypops/pi-tui-harness": "^0.0.1",
 		"@earendil-works/pi-ai": "^0.81.1",