@danypops/pi-lector 0.9.1 → 0.9.3

package/extension/src/git-operations.ts

@@ -1,6 +1,8 @@
-import type { GitDiffResult, GitLogEntry, GitStatusSummary } from "@danypops/lector";
+import type { GitDiffResult, GitLogEntry, GitStatusSummary, OperationOutputs } from "@danypops/lector";
 import { lectorClient, withWorkspace, workspaceForDirectory } from "./lector-client.ts";
 
+type SymbolComparison = OperationOutputs["workspace.compareSymbolAcrossVersions"];
+
 /**
  * Thin wrappers over Lector's read-only git operations. `directory` is
  * required, same convention as find_symbols -- no implicit "whatever the
@@ -10,6 +12,7 @@ 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>;
+	compareSymbol(directory: string, path: string, symbolName: string, fromRef: string, toRef: string | undefined, maxBytes: number): Promise<SymbolComparison>;
 }
 
 export function createLectorGitOperations(): GitOperations {
@@ -42,5 +45,14 @@ export function createLectorGitOperations(): GitOperations {
 				},
 			);
 		},
+		async compareSymbol(directory, path, symbolName, fromRef, toRef, maxBytes) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.compareSymbolAcrossVersions", { workspaceId, path, symbolName, fromRef, toRef, maxBytes });
+				},
+			);
+		},
 	};
 }

package/extension/src/git-rendering.ts

@@ -1,4 +1,4 @@
-import type { GitDiffResult, GitLogEntry, GitStatusSummary } from "@danypops/lector";
+import type { GitDiffResult, GitLogEntry, GitStatusSummary, OperationOutputs } from "@danypops/lector";
 import { keyHint } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { renderDiffLines, renderTruncatedList, type TextMeasure } from "malevich-tui-components";
@@ -11,18 +11,31 @@ const DEFAULT_VISIBLE_FILES = 20;
 const DEFAULT_VISIBLE_COMMITS = 10;
 const DEFAULT_VISIBLE_DIFF_LINES = 60;
 
-export type GitAction = "status" | "log" | "diff";
+export type GitAction = "status" | "log" | "diff" | "compare-symbol";
+
+type SymbolComparison = OperationOutputs["workspace.compareSymbolAcrossVersions"];
 
 export interface GitToolDetails {
 	readonly action: GitAction;
 	readonly summary?: GitStatusSummary;
 	readonly entries?: readonly GitLogEntry[];
 	readonly result?: GitDiffResult;
+	readonly comparison?: SymbolComparison;
 }
 
-export function formatGitCall(args: { action?: unknown; directory?: unknown; ref?: unknown }, theme: LectorTheme): string {
+export function formatGitCall(
+	args: { action?: unknown; directory?: unknown; ref?: unknown; path?: unknown; symbol?: unknown; fromRef?: unknown; toRef?: unknown },
+	theme: LectorTheme,
+): string {
 	const action = typeof args.action === "string" ? args.action : "";
 	const directory = typeof args.directory === "string" ? args.directory : "";
+	if (action === "compare-symbol") {
+		const path = typeof args.path === "string" ? args.path : "";
+		const symbol = typeof args.symbol === "string" ? args.symbol : "";
+		const fromRef = typeof args.fromRef === "string" ? args.fromRef : "";
+		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}`;
+	}
 	const ref = typeof args.ref === "string" ? ` ${args.ref}` : "";
 	return `${theme.fg("toolTitle", theme.bold("git"))} ${theme.fg("muted", action)} ${theme.fg("accent", directory)}${ref}`;
 }
@@ -31,6 +44,7 @@ export function formatGitResult(details: GitToolDetails | undefined, expanded: b
 	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);
 	return formatGitDiffResult(details.result, expanded, theme);
 }
 
@@ -90,11 +104,11 @@ function formatGitLogResult(entries: readonly GitLogEntry[] | undefined, expande
  * is the still-open "render file and Git diffs as bounded native Pi
  * visuals" follow-up.
  */
-function formatGitDiffResult(result: GitDiffResult | undefined, expanded: boolean, theme: LectorTheme): string {
-	if (!result || result.diff.length === 0) return theme.fg("dim", "No differences.");
+/** Shared by formatGitDiffResult and formatCompareSymbolResult -- both display a real unified-diff string, styled and bounded the same way. */
+function renderStyledDiffLines(diff: string, truncatedUpstream: boolean, expanded: boolean, theme: LectorTheme): string {
 	const styledLines = renderDiffLines(
 		Number.MAX_SAFE_INTEGER,
-		result.diff,
+		diff,
 		{
 			add: (s) => theme.fg("success", s),
 			remove: (s) => theme.fg("error", s),
@@ -110,7 +124,20 @@ function formatGitDiffResult(result: GitDiffResult | undefined, expanded: boolea
 		visibleCount: DEFAULT_VISIBLE_DIFF_LINES,
 		formatItem: (line) => line,
 		moreLine: (hidden) => theme.fg("dim", `... ${hidden} more line${hidden === 1 ? "" : "s"} (${keyHint("app.tools.expand", "to expand")})`),
-		truncationWarning: result.truncated ? theme.fg("warning", "(diff output itself was truncated by maxBytes)") : undefined,
+		truncationWarning: truncatedUpstream ? theme.fg("warning", "(diff output itself was truncated by maxBytes)") : undefined,
 	});
 	return lines.join("\n");
 }
+
+function formatGitDiffResult(result: GitDiffResult | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!result || result.diff.length === 0) return theme.fg("dim", "No differences.");
+	return renderStyledDiffLines(result.diff, result.truncated, expanded, theme);
+}
+
+function formatCompareSymbolResult(comparison: SymbolComparison | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!comparison) return theme.fg("dim", "No result.");
+	const header = theme.fg("accent", `${comparison.path} (${comparison.symbolName}) -- ${comparison.fromRef} -> ${comparison.toRef}`);
+	if (comparison.status === "both-missing") return `${header}\n${theme.fg("dim", "symbol found at neither version")}`;
+	if (comparison.status === "unchanged") return `${header}\n${theme.fg("dim", "unchanged")}`;
+	return `${header}\n${renderStyledDiffLines(comparison.diff, comparison.truncated, expanded, theme)}`;
+}

package/extension/src/index.ts

@@ -14,6 +14,7 @@ import type {
 	MutationHistoryEntry,
 	NpmPackageCandidate,
 	OperationOutputs,
+	PackageEcosystem,
 	PackageSourceOperationResult,
 	RepoFetchResult,
 	SourcegraphCodeCandidate,
@@ -25,7 +26,7 @@ import type {
 	WorkspaceMapResult,
 	WorkspaceQueryOutcome,
 } from "@danypops/lector";
-import { DEFAULT_EXTERNAL_SEARCH_MAX_RESULTS } from "@danypops/lector";
+import { DEFAULT_EXTERNAL_SEARCH_MAX_RESULTS, PACKAGE_ECOSYSTEMS } from "@danypops/lector";
 import {
 	type AgentToolResult,
 	createEditToolDefinition,
@@ -85,8 +86,18 @@ import { createLectorLineEditOperations } from "./line-edit-operations.ts";
 import { formatLineEditCall, formatLineEditResult } from "./line-edit-rendering.ts";
 import { createMutationHistoryOperations } from "./mutation-history-operations.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 { createLectorPackageSourceOperations, type PackageSourceListPage } from "./package-source-operations.ts";
+import {
+	buildPackageSourceListTableRows,
+	formatPackageSourceCall,
+	formatPackageSourceCleanResult,
+	formatPackageSourceListResult,
+	formatPackageSourceRemoveResult,
+	formatPackageSourceResult,
+	PACKAGE_SOURCE_LIST_TABLE_COLUMNS,
+	PACKAGE_SOURCE_LIST_VISIBLE_ROWS,
+	packageSourceListMoreLine,
+} from "./package-source-rendering.ts";
 import { createLectorReadOperations } from "./read-operations.ts";
 import { createReferenceBasedRenameOperations } from "./reference-based-rename-operations.ts";
 import { createRenameOperations } from "./rename-operations.ts";
@@ -1033,17 +1044,26 @@ export default function (pi: ExtensionAPI) {
 			name: "git",
 			label: "Git",
 			description:
-				"Working tree status, recent commit log, and unified diff 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).",
-			promptSnippet: "Show a repository's status, log, or diff",
+				"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",
 			promptGuidelines: [
-				"maxCount is required for action=log; maxBytes is required for action=diff -- 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 -- 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.",
 			],
 			parameters: Type.Object({
-				action: Type.String({ description: "status | log | diff" }),
+				action: Type.String({ description: "status | log | diff | compare-symbol" }),
 				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" })),
-				maxBytes: Type.Optional(Type.Number({ description: "Maximum diff size in bytes before truncating -- required for action=diff" })),
+				maxBytes: Type.Optional(
+					Type.Number({ description: "Maximum diff/comparison size in bytes before truncating -- required for action=diff/compare-symbol" }),
+				),
+				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" }),
+				),
 			}),
 			async execute(_toolCallId, params) {
 				const directory = resolve(cwd, params.directory);
@@ -1066,6 +1086,13 @@ export default function (pi: ExtensionAPI) {
 					const details: GitToolDetails = { action: "diff", result };
 					return { content: [{ type: "text", text: result.diff.length === 0 ? "No differences." : result.diff }], details };
 				}
+				if (params.action === "compare-symbol") {
+					if (!params.path || !params.symbol || !params.fromRef) throw new Error("git action=compare-symbol requires path, symbol, and fromRef");
+					if (params.maxBytes === undefined) throw new Error("git action=compare-symbol requires maxBytes");
+					const comparison = await gitOperations.compareSymbol(directory, params.path, params.symbol, params.fromRef, params.toRef, params.maxBytes);
+					const details: GitToolDetails = { action: "compare-symbol", comparison };
+					return { content: [{ type: "text", text: JSON.stringify(comparison) }], details };
+				}
 				throw new Error(`unknown git action: ${String(params.action)}`);
 			},
 			renderCall(args, theme, context) {
@@ -1355,23 +1382,78 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
+		type PackageSourceToolDetails =
+			| { readonly action: "resolve"; readonly result: PackageSourceOperationResult }
+			| { readonly action: "list"; readonly page: PackageSourceListPage }
+			| { readonly action: "remove"; readonly result: { removed: boolean } }
+			| { readonly action: "clean"; readonly result: { removed: number; skipped: number } };
+
+		/** A real type guard, not an assertion -- params.ecosystem arrives as a bare TypeBox string; this is the one place that turns it into PackageEcosystem, with a runtime check backing the narrowing. */
+		function isPackageEcosystem(value: string): value is PackageEcosystem {
+			return (PACKAGE_ECOSYSTEMS as readonly string[]).includes(value);
+		}
+		function optionalPackageEcosystem(value: string | undefined): PackageEcosystem | undefined {
+			if (value === undefined) return undefined;
+			if (!isPackageEcosystem(value)) throw new Error(`ecosystem must be one of ${PACKAGE_ECOSYSTEMS.join(", ")}; got "${value}"`);
+			return value;
+		}
+		function requirePackageEcosystem(value: string | undefined): PackageEcosystem {
+			if (value === undefined || !isPackageEcosystem(value)) {
+				throw new Error(`ecosystem must be one of ${PACKAGE_ECOSYSTEMS.join(", ")}; got "${value ?? ""}"`);
+			}
+			return value;
+		}
+
 		const packageSourceOperations = createLectorPackageSourceOperations();
 		pi.registerTool({
 			name: "package_source",
 			label: "Package Source",
 			description:
-				"Resolve an installed npm package to verified exact repository source. Uses the project's lockfile, bounded registry metadata, and an exact Git ref/commit; registers verified source as a read-only workspace for the other Lector tools.",
-			promptSnippet: "Resolve an installed npm package to exact read-only source",
+				"Resolve, list, remove, or clean bookkeeping for installed npm packages resolved to verified exact repository source. action=resolve uses the project's lockfile, bounded registry metadata, and an exact Git ref/commit; registers verified source as a read-only workspace for the other Lector tools. action=list reports every package coordinate already resolved this way -- no re-resolution, no network. action=remove drops one bookkeeping entry by its exact ecosystem/name/resolvedVersion; refuses if it is still a currently-registered workspace. action=clean removes every non-in-use entry, optionally scoped to one ecosystem. Neither remove nor clean deletes the underlying repo_cache disk entry -- use repo_cache(action=evict) for that, since a monorepo can share one checkout across several package coordinates.",
+			promptSnippet: "Resolve, list, remove, or clean verified package source bookkeeping",
 			parameters: Type.Object({
-				directory: Type.String({ description: "Project directory containing the npm-family lockfile" }),
-				name: Type.String({ description: "Installed package name, including scope when present" }),
-				version: Type.Optional(Type.String({ description: "Exact installed version; required when the lockfile contains several versions" })),
+				action: Type.Optional(Type.Union([Type.Literal("resolve"), Type.Literal("list"), Type.Literal("remove"), Type.Literal("clean")])),
+				directory: Type.Optional(Type.String({ description: "Required for action=resolve -- project directory containing the npm-family lockfile" })),
+				name: Type.Optional(Type.String({ description: "Required for action=resolve/remove -- installed package name, including scope when present" })),
+				version: Type.Optional(
+					Type.String({ description: "action=resolve only -- exact installed version; required when the lockfile contains several versions" }),
+				),
 				registry: Type.Optional(Type.String({ description: "npm registry URL; defaults to the public npm registry" })),
+				ecosystem: Type.Optional(Type.String({ description: "Required for action=remove; optional filter for action=list/clean" })),
+				resolvedVersion: Type.Optional(Type.String({ description: "Required for action=remove -- the exact resolved version to remove" })),
+				text: Type.Optional(Type.String({ description: "action=list only -- case-insensitive substring match across ecosystem/name/resolvedVersion" })),
+				maxResults: Type.Optional(Type.Number({ description: "Required for action=list -- maximum entries to return in this page" })),
+				cursor: Type.Optional(Type.String({ description: "action=list only -- opaque cursor from a prior call's nextCursor, to fetch the next page" })),
 			}),
-			async execute(_toolCallId, params) {
+			async execute(_toolCallId, params): Promise<AgentToolResult<PackageSourceToolDetails>> {
+				if (params.action === "list") {
+					if (params.maxResults === undefined) throw new Error("package_source action=list requires maxResults");
+					const page = await packageSourceOperations.list({
+						ecosystem: optionalPackageEcosystem(params.ecosystem),
+						text: params.text,
+						maxResults: params.maxResults,
+						cursor: params.cursor,
+					});
+					return { content: [{ type: "text", text: JSON.stringify(page) }], details: { action: "list", page } };
+				}
+				if (params.action === "remove") {
+					if (!params.name || !params.resolvedVersion) throw new Error("package_source action=remove requires ecosystem, name, and resolvedVersion");
+					const result = await packageSourceOperations.remove(
+						requirePackageEcosystem(params.ecosystem),
+						params.registry ?? null,
+						params.name,
+						params.resolvedVersion,
+					);
+					return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "remove", result } };
+				}
+				if (params.action === "clean") {
+					const result = await packageSourceOperations.clean(optionalPackageEcosystem(params.ecosystem));
+					return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "clean", result } };
+				}
+				if (!params.directory || !params.name) throw new Error("package_source action=resolve requires directory and name");
 				const directory = resolve(cwd, params.directory);
 				const result = await packageSourceOperations.resolve(directory, params.name, params.version ?? null, params.registry ?? null);
-				return { content: [{ type: "text", text: JSON.stringify(result) }], details: { result } };
+				return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "resolve", result } };
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
@@ -1379,7 +1461,7 @@ export default function (pi: ExtensionAPI) {
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {
-				if (isPartial) return new Text(theme.fg("warning", "Resolving package source..."), 0, 0);
+				if (isPartial) return new Text(theme.fg("warning", "Working on package source..."), 0, 0);
 				if (context.isError) {
 					const errorText = result.content
 						.filter((block) => block.type === "text")
@@ -1387,9 +1469,26 @@ export default function (pi: ExtensionAPI) {
 						.join("\n");
 					return new Text(theme.fg("error", errorText || "package_source failed"), 0, 0);
 				}
-				const details = result.details as { result?: PackageSourceOperationResult } | undefined;
+				const details = result.details as PackageSourceToolDetails | undefined;
+				// A non-empty list renders as a real, bounded Table -- the human channel actually shows
+				// package/workspace/path/size, not just a bare count, capped at PACKAGE_SOURCE_LIST_VISIBLE_ROWS
+				// since the index can grow arbitrarily large even though maxResults bounds any one page.
+				if (details?.action === "list" && details.page.entries.length > 0) {
+					return renderBoundedTable({
+						columns: PACKAGE_SOURCE_LIST_TABLE_COLUMNS,
+						rows: buildPackageSourceListTableRows(details.page.entries),
+						expanded,
+						visibleRowCount: PACKAGE_SOURCE_LIST_VISIBLE_ROWS,
+						moreLine: packageSourceListMoreLine(theme),
+						measure: tableMeasure,
+						headerStyle: (s) => theme.fg("muted", theme.bold(s)),
+					});
+				}
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatPackageSourceResult(details?.result, expanded, theme));
+				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));
 				return text;
 			},
 		});

package/extension/src/package-source-operations.ts

@@ -1,8 +1,16 @@
-import { DEFAULT_PACKAGE_SOURCE_BOUNDS, type PackageSourceOperationResult } from "@danypops/lector";
+import { DEFAULT_PACKAGE_SOURCE_BOUNDS, type PackageEcosystem, type PackageSourceListEntry, type PackageSourceOperationResult } from "@danypops/lector";
 import { lectorClient } from "./lector-client.ts";
 
+export interface PackageSourceListPage {
+	readonly entries: readonly PackageSourceListEntry[];
+	readonly nextCursor: string | null;
+}
+
 export interface PackageSourceOperations {
 	resolve(directory: string, name: string, requestedVersion: string | null, registry: string | null): Promise<PackageSourceOperationResult>;
+	list(options: { ecosystem?: PackageEcosystem; text?: string; maxResults: number; cursor?: string }): Promise<PackageSourceListPage>;
+	remove(ecosystem: PackageEcosystem, registry: string | null, name: string, resolvedVersion: string): Promise<{ removed: boolean }>;
+	clean(ecosystem: PackageEcosystem | undefined): Promise<{ removed: number; skipped: number }>;
 }
 
 export function createLectorPackageSourceOperations(): PackageSourceOperations {
@@ -17,5 +25,17 @@ export function createLectorPackageSourceOperations(): PackageSourceOperations {
 				bounds: DEFAULT_PACKAGE_SOURCE_BOUNDS,
 			});
 		},
+		async list(options) {
+			const client = await lectorClient();
+			return client.call("package.listSources", options);
+		},
+		async remove(ecosystem, registry, name, resolvedVersion) {
+			const client = await lectorClient();
+			return client.call("package.removeSource", { ecosystem, registry, name, resolvedVersion });
+		},
+		async clean(ecosystem) {
+			const client = await lectorClient();
+			return client.call("package.cleanSources", { ecosystem });
+		},
 	};
 }

package/extension/src/package-source-rendering.ts

@@ -1,14 +1,36 @@
-import type { PackageSourceOperationResult } from "@danypops/lector";
-import { renderTruncatedList } from "malevich-tui-components";
+import type { PackageSourceListEntry, PackageSourceOperationResult } from "@danypops/lector";
+import { keyHint } from "@earendil-works/pi-coding-agent";
+import { renderTruncatedList, type TableColumn } from "malevich-tui-components";
 import type { LectorTheme } from "./lector-tui-theme.ts";
 
 const DEFAULT_VISIBLE_CANDIDATES = 5;
 
-export function formatPackageSourceCall(args: { directory?: unknown; name?: unknown; version?: unknown }, theme: LectorTheme): string {
+/** Table has no row-count bound of its own; the underlying index can grow arbitrarily large even though package.listSources's own maxResults bounds any one page. Mirrors REPO_CACHE_VISIBLE_ROWS. */
+export const PACKAGE_SOURCE_LIST_VISIBLE_ROWS = 20;
+
+type PackageSourceAction = "resolve" | "list" | "remove" | "clean";
+
+export function formatPackageSourceCall(
+	args: { action?: unknown; directory?: unknown; name?: unknown; version?: unknown; ecosystem?: unknown; resolvedVersion?: unknown; text?: unknown },
+	theme: LectorTheme,
+): string {
+	const label = theme.fg("toolTitle", theme.bold("package_source"));
+	const action: PackageSourceAction = args.action === "list" || args.action === "remove" || args.action === "clean" ? args.action : "resolve";
+	if (action === "list") {
+		const text = typeof args.text === "string" && args.text.length > 0 ? ` ${theme.fg("dim", args.text)}` : "";
+		return `${label} ${theme.fg("accent", "list")}${text}`;
+	}
+	if (action === "remove" || action === "clean") {
+		const name = typeof args.name === "string" ? args.name : "";
+		const version = typeof args.resolvedVersion === "string" ? `@${args.resolvedVersion}` : "";
+		const ecosystem = typeof args.ecosystem === "string" ? args.ecosystem : "";
+		const identity = name ? `${name}${version}` : ecosystem;
+		return `${label} ${theme.fg("accent", action)}${identity ? ` ${theme.fg("dim", identity)}` : ""}`;
+	}
 	const name = typeof args.name === "string" ? args.name : "";
 	const version = typeof args.version === "string" ? `@${args.version}` : "";
 	const directory = typeof args.directory === "string" ? args.directory : "";
-	return `${theme.fg("toolTitle", theme.bold("package_source"))} ${theme.fg("accent", `${name}${version}`)} ${theme.fg("dim", directory)}`.trim();
+	return `${label} ${theme.fg("accent", `${name}${version}`)} ${theme.fg("dim", directory)}`.trim();
 }
 
 export function formatPackageSourceResult(result: PackageSourceOperationResult | undefined, expanded: boolean, theme: LectorTheme): string {
@@ -42,3 +64,54 @@ export function formatPackageSourceResult(result: PackageSourceOperationResult |
 	if (outcome.status === "mismatched") return theme.fg("error", `Source mismatch (${outcome.code}): expected ${outcome.expected}, got ${outcome.actual}.`);
 	return theme.fg("warning", `Source unavailable (${outcome.code}).`);
 }
+
+/** Empty-state fallback only -- a non-empty page renders as a real Table (see buildPackageSourceListTableRows) so the human channel actually shows what's resolved, not just a bare count. Mirrors formatRepoCacheListResult. */
+export function formatPackageSourceListResult(
+	page: { entries: readonly PackageSourceListEntry[]; nextCursor?: string | null } | undefined,
+	theme: LectorTheme,
+): string {
+	const count = page?.entries.length ?? 0;
+	return count === 0 ? theme.fg("dim", "no resolved package sources") : theme.fg("success", `${count} resolved package source${count === 1 ? "" : "s"}`);
+}
+
+/** Powers of 1024, one decimal past the first. Mirrors repo-cache-rendering.ts's own formatCacheSize -- kept as a small local duplicate rather than a shared export, matching that file's own precedent. */
+function formatCacheSize(bytes: number): string {
+	const units = ["B", "KB", "MB", "GB", "TB"] as const;
+	let value = bytes;
+	let unitIndex = 0;
+	while (value >= 1024 && unitIndex < units.length - 1) {
+		value /= 1024;
+		unitIndex++;
+	}
+	return `${unitIndex === 0 ? value : value.toFixed(1)} ${units[unitIndex]}`;
+}
+
+export function buildPackageSourceListTableRows(entries: readonly PackageSourceListEntry[]): Record<string, string>[] {
+	return entries.map((entry) => ({
+		package: `${entry.name}@${entry.resolvedVersion}`,
+		workspace: entry.workspaceId,
+		path: entry.cachePath,
+		size: entry.cacheSizeBytes === null ? "unknown" : formatCacheSize(entry.cacheSizeBytes),
+	}));
+}
+
+export const PACKAGE_SOURCE_LIST_TABLE_COLUMNS: TableColumn[] = [
+	{ header: "Package", key: "package" },
+	{ header: "Workspace", key: "workspace" },
+	{ header: "Path", key: "path" },
+	{ header: "Size", key: "size" },
+];
+
+export function packageSourceListMoreLine(theme: LectorTheme): (hiddenCount: number) => string {
+	return (hiddenCount) => theme.fg("dim", `... ${hiddenCount} more (${keyHint("app.tools.expand", "to expand")})`);
+}
+
+export function formatPackageSourceRemoveResult(result: { removed: boolean } | undefined, theme: LectorTheme): string {
+	if (!result) return theme.fg("dim", "No result.");
+	return result.removed ? theme.fg("success", "removed") : theme.fg("dim", "not recorded for that coordinate");
+}
+
+export function formatPackageSourceCleanResult(result: { removed: number; skipped: number } | undefined, theme: LectorTheme): string {
+	if (!result) return theme.fg("dim", "No result.");
+	return theme.fg("success", `removed ${result.removed}, skipped ${result.skipped} (still in use)`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.9.1",
+	"version": "0.9.3",
 	"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/vehicle-client": "^0.1.1",
-		"@danypops/lector": "^0.10.0",
+		"@danypops/lector": "^0.12.0",
 		"malevich-tui-components": "^0.19.0"
 	},
 	"devDependencies": {