@danypops/pi-lector 0.12.6 → 0.12.7

package/extension/src/client-diagnostics.ts

@@ -0,0 +1,46 @@
+import type { RetryingClientDiagnosticEvent } from "@danypops/vehicle-client/daemon-client";
+
+/**
+ * Formats one createRetryingClient diagnostic event as a single, compact line -- the same real
+ * RCA gap @danypops/vehicle-client's own onEvent hook was added to close: a scrubbed "connector
+ * unavailable" error at the tool-call boundary otherwise gives no way to tell, after the fact,
+ * whether it was a genuine fresh connect() failure, a circuit-breaker short-circuit (no connect
+ * attempted at all), or an in-flight operation's stale-connection retry. Never includes a stack
+ * trace -- name and message only, matching this house's other client-diagnostic channels
+ * (@danypops/vehicle-client-pi's own client-diagnostics.ts).
+ */
+/** Never risks Object's default `[object Object]` stringification for a non-Error, non-string throw. */
+function describeError(error: unknown): { name: string; message: string } {
+	if (error instanceof Error) return { name: error.name, message: error.message };
+	if (typeof error === "string") return { name: "string", message: error };
+	if (typeof error === "number" || typeof error === "boolean" || typeof error === "bigint") return { name: typeof error, message: String(error) };
+	return { name: typeof error, message: "(unprintable value)" };
+}
+
+export function formatClientDiagnosticEvent(event: RetryingClientDiagnosticEvent): string {
+	const parts = [`[lector-client] ${event.type}`];
+	if (event.attempt !== undefined) parts.push(`attempt=${event.attempt}`);
+	if (event.consecutiveFailures !== undefined) parts.push(`consecutiveFailures=${event.consecutiveFailures}`);
+	if (event.operationId !== undefined) parts.push(`operationId=${event.operationId}`);
+	if (event.error !== undefined) {
+		const { name, message } = describeError(event.error);
+		parts.push(`error=${name}: ${message}`);
+	}
+	return parts.join(" ");
+}
+
+/**
+ * Logs a createRetryingClient diagnostic event to stderr, only when LECTOR_CLIENT_DIAG is set --
+ * zero cost and zero output for every session that never opts in, matching the env-gated
+ * convention @danypops/vehicle-client-pi's own VEHICLE_CLIENT_DIAG already established in this
+ * house. Never throws: onEvent's own contract requires it stay side-effect-light, and a broken
+ * local console (or a formatting bug) must not take down a real client call.
+ */
+export function logClientDiagnosticEvent(event: RetryingClientDiagnosticEvent): void {
+	if (!process.env.LECTOR_CLIENT_DIAG) return;
+	try {
+		console.error(formatClientDiagnosticEvent(event));
+	} catch {
+		// best-effort only -- see doc comment above.
+	}
+}

package/extension/src/index.ts

@@ -1,3 +1,5 @@
+import { readdirSync } from "node:fs";
+import { homedir } from "node:os";
 import { resolve } from "node:path";
 import type {
 	CachedRepositoryPage,
@@ -44,7 +46,7 @@ import { Type } from "typebox";
 /** Real ANSI-aware measurement for Table -- Malevich's own default is ASCII-only, unsafe against theme-styled cell/header text. */
 const tableMeasure: TextMeasure = { visibleWidth, truncateToWidth };
 
-import { isFilesystemRoot } from "@danypops/lector";
+import { classifyAutoPopulationRoot, isFilesystemRoot } from "@danypops/lector";
 import { createLectorApplyPatchOperations } from "./apply-patch/operations.ts";
 import { formatApplyPatchCall, formatApplyPatchResult } from "./apply-patch/rendering.ts";
 import { createLectorCodeIntelligenceOperations } from "./code-intelligence/operations.ts";
@@ -214,10 +216,23 @@ export default function (pi: ExtensionAPI) {
 	 * 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.
+	 *
+	 * 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
+	 * server-side gate would refuse it -- avoids the round trip (and the queue-behind-real-
+	 * projects ergonomics this caused live for ~/.pi/agent) entirely, using the identical
+	 * classification Lector itself uses so the two never drift. A readdir failure (permission,
+	 * race) is treated as "can't tell, don't block" -- the server-side gate is still authoritative.
 	 */
 	function startMonitoringRoot(root: string, ctx: Parameters<Parameters<ExtensionAPI["on"]>[1]>[1]): void {
 		if (isFilesystemRoot(root)) return;
 		if (monitoringRoots.has(root)) return;
+		try {
+			const topLevelEntries = readdirSync(root);
+			if (classifyAutoPopulationRoot({ rootPath: root, homeDir: homedir(), topLevelEntries }) === "broad-non-project") return;
+		} catch {
+			// Can't read it here -- let the server-side gate be the authoritative answer.
+		}
 		monitoringRoots.add(root);
 		const thisGeneration = sessionGeneration;
 		void monitorWorkspaceCache(cacheOperations, {

package/extension/src/lector-client.ts

@@ -11,6 +11,7 @@ import {
 	type WorkspaceResolutionRequest,
 } from "@danypops/lector";
 import { createRetryingClient, isLikelyStaleConnectionError, type RetryingClient } from "@danypops/vehicle-client/daemon-client";
+import { logClientDiagnosticEvent } from "./client-diagnostics.ts";
 
 /**
  * Lazily connects to a running Lector daemon and caches, per resolution request, the
@@ -44,6 +45,9 @@ let connector: ClientConnector = () => connectLectorClient();
 const retryingClient: RetryingClient<LectorClient> = createRetryingClient(() => connector(), {
 	label: "Lector",
 	isStaleConnectionError: (error) => error instanceof LectorDaemonUnavailable || isLikelyStaleConnectionError(error),
+	// Purely observational, opt-in via LECTOR_CLIENT_DIAG -- see client-diagnostics.ts's own doc
+	// comment for the exact RCA gap this closes.
+	onEvent: logClientDiagnosticEvent,
 });
 
 /**
@@ -220,6 +224,38 @@ export function workspaceForPathOrDirectory(path: string): Promise<ResolvedWorks
 	return resolveWorkspace({ strategy: "path-or-directory", path });
 }
 
+/** Raised by workspaceForAnnotationPath for a path that does not exist on disk at all -- a distinct, explicit failure the caller must handle, never silently guessed as "must be a file, take its dirname()." */
+export class AnnotationPathDoesNotExist extends Error {
+	constructor(readonly path: string) {
+		super(`"${path}" does not exist -- a symbol-annotation scope must be a real project directory or an existing source file`);
+		this.name = "AnnotationPathDoesNotExist";
+	}
+}
+
+/**
+ * For symbol-annotation's own `path` parameter, which genuinely means "which workspace does this
+ * belong to" and can honestly be either an existing project directory or one specific source
+ * file -- unlike workspaceForCodeIntelligencePath (files only, dirname() unconditional), a real
+ * project directory resolves via its own language markers, not its parent's. A genuinely
+ * nonexistent path throws AnnotationPathDoesNotExist rather than being silently treated as a file.
+ */
+export async function workspaceForAnnotationPath(path: string): Promise<ResolvedWorkspace> {
+	const request: WorkspaceResolutionRequest = { strategy: "code-intelligence-path-or-directory", path };
+	const key = requestCacheKey(request);
+	const cached = resolutionCache.get(key);
+	if (cached) return cached;
+	const client = await lectorClient();
+	const outcome = await client.callOnce("workspace.resolvePath", request);
+	if (!outcome.found) {
+		if (outcome.reason === "nonexistent-path") throw new AnnotationPathDoesNotExist(path);
+		throw new Error(`workspace.resolvePath unexpectedly reported not-found for code-intelligence-path-or-directory: ${path}`);
+	}
+	const resolved: ResolvedWorkspace = { workspaceId: outcome.workspaceId, root: outcome.root };
+	resolutionCache.set(key, resolved);
+	if (outcome.created) onNewWorkspace?.(outcome.root);
+	return resolved;
+}
+
 /**
  * The nearest ancestor of an already-resolved project root whose own package.json declares that
  * project as a workspace member via npm/yarn/bun's "workspaces" field -- undefined (no

package/extension/src/symbol-annotation/operations.ts

@@ -1,5 +1,5 @@
 import type { OperationInputs, OperationOutputs } from "@danypops/lector";
-import { lectorClient, withWorkspace, workspaceForCodeIntelligencePath } from "../lector-client.ts";
+import { lectorClient, withWorkspace, workspaceForAnnotationPath } from "../lector-client.ts";
 
 /** A bare symbol position an anchor is given as -- symbolNodeId and the anchor's baseline file hash are derived server-side, never supplied by the caller. */
 export interface AnnotationAnchorInput {
@@ -9,10 +9,12 @@ export interface AnnotationAnchorInput {
 }
 
 /**
- * Thin wrappers over Lector's annotation operations. Anchored to a workspace
- * via the first anchor's own path (workspaceForCodeIntelligencePath) --
- * every operation that needs a workspace already has at least one real
- * anchor position or an id whose workspace the caller already knows.
+ * Thin wrappers over Lector's annotation operations. Every operation resolves its workspace from
+ * its own `path` parameter via workspaceForAnnotationPath -- a real project directory or an
+ * existing source file, never dirname()'d unconditionally the way a plain code-intelligence
+ * path is. `path` here means "which workspace this call belongs to," not necessarily one of the
+ * operation's own anchors (create/refresh's anchors carry their own, separately-validated paths
+ * server-side).
  */
 export interface SymbolAnnotationOperations {
 	create(
@@ -46,7 +48,7 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 	return {
 		async create(path, subtype, title, body, anchors) {
 			return withWorkspace(
-				() => workspaceForCodeIntelligencePath(path),
+				() => workspaceForAnnotationPath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
 					return client.callOnce("workspace.createAnnotation", { workspaceId, subtype, title, body, anchors });
@@ -55,7 +57,7 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 		},
 		async get(path, id) {
 			return withWorkspace(
-				() => workspaceForCodeIntelligencePath(path),
+				() => workspaceForAnnotationPath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
 					return client.call("workspace.getAnnotation", { workspaceId, id });
@@ -64,7 +66,7 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 		},
 		async list(path, options = {}) {
 			return withWorkspace(
-				() => workspaceForCodeIntelligencePath(path),
+				() => workspaceForAnnotationPath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
 					return client.call("workspace.listAnnotations", {
@@ -79,7 +81,7 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 		},
 		async refresh(path, id, subtype, title, body, anchors) {
 			return withWorkspace(
-				() => workspaceForCodeIntelligencePath(path),
+				() => workspaceForAnnotationPath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
 					return client.callOnce("workspace.refreshAnnotation", { workspaceId, id, subtype, title, body, anchors });
@@ -88,7 +90,7 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 		},
 		async scrub(path, id) {
 			return withWorkspace(
-				() => workspaceForCodeIntelligencePath(path),
+				() => workspaceForAnnotationPath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
 					return client.callOnce("workspace.scrubAnnotation", { workspaceId, id });
@@ -97,7 +99,7 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 		},
 		async restore(path, id) {
 			return withWorkspace(
-				() => workspaceForCodeIntelligencePath(path),
+				() => workspaceForAnnotationPath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
 					return client.callOnce("workspace.restoreAnnotation", { workspaceId, id });
@@ -106,7 +108,7 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 		},
 		async contain(path, parentId, childId) {
 			return withWorkspace(
-				() => workspaceForCodeIntelligencePath(path),
+				() => workspaceForAnnotationPath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
 					return client.callOnce("workspace.containAnnotation", { workspaceId, parentId, childId });
@@ -115,7 +117,7 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 		},
 		async uncontain(path, parentId, childId) {
 			return withWorkspace(
-				() => workspaceForCodeIntelligencePath(path),
+				() => workspaceForAnnotationPath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
 					return client.callOnce("workspace.uncontainAnnotation", { workspaceId, parentId, childId });
@@ -124,7 +126,7 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 		},
 		async tree(path, rootId, maxDepth) {
 			return withWorkspace(
-				() => workspaceForCodeIntelligencePath(path),
+				() => workspaceForAnnotationPath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
 					return client.call("workspace.annotationTree", { workspaceId, rootId, maxDepth });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.12.6",
+	"version": "0.12.7",
 	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
 	"license": "MIT",
 	"type": "module",
@@ -18,9 +18,9 @@
 		"typebox": "*"
 	},
 	"dependencies": {
-		"@danypops/vehicle-client": "^0.2.0",
+		"@danypops/vehicle-client": "^0.8.2",
 		"@danypops/lector": "^0.18.0",
-		"malevich-tui-components": "^0.19.0",
+		"malevich-tui-components": "^0.25.0",
 		"picomatch": "^4.0.5"
 	},
 	"devDependencies": {