@danypops/pi-lector 0.12.7 → 0.12.9

package/extension/src/editor/editor-state.ts

@@ -7,7 +7,7 @@ export type EditorAction = { kind: "save" } | { kind: "save-and-quit" } | { kind
 const BACKSPACE_KEYS = new Set(["\x7f", "\b"]);
 
 /**
- * Pure neovim-style modal editing state machine: mode transitions, cursor motion, and buffer
+ * Pure modal editing state machine: mode transitions, cursor motion, and buffer
  * edits, with no terminal/ANSI rendering and no I/O -- save/quit/hover requests surface as
  * `pendingAction` for the hosting Component to actually perform (reading/writing through
  * Lector's hash-guarded workspace operations lives outside this class entirely). Kept

package/extension/src/editor/index.ts

@@ -0,0 +1,22 @@
+/**
+ * The real, host-agnostic editor surface -- deliberately its own subpath export
+ * (`@danypops/pi-lector/editor`), not part of this package's own Pi extension entry point
+ * (`extension/src/index.ts`, which is loaded only via Pi's own extension-discovery mechanism and
+ * has no package export of its own).
+ *
+ * Everything re-exported here has zero structural dependency on Pi's extension machinery --
+ * confirmed directly: ModalEditorComponent's own constructor only ever calls
+ * `tui.requestRender()`/`tui.terminal.rows` and `theme.fg()`/`theme.bg()` (EditorTheme is its own
+ * interface, deliberately narrowed away from pi-coding-agent's full Theme shape), and
+ * ModalEditorHost is a plain `{filePath, save, hover}` port with no Pi types anywhere in it.
+ * EditorState's own only dependency is `@danypops/lector`'s LiveBuffer -- no I/O, no rendering.
+ *
+ * This lets any real host (not just a Pi session that has loaded this package as an extension)
+ * construct and mount a real Lector editor Component directly, against its own tui/theme
+ * implementation and its own ModalEditorHost backed by whatever it wants (a Lector daemon
+ * client, a Vehicle operation, a plain filesystem call -- this package doesn't care).
+ */
+
+export { type EditorAction, type EditorMode, EditorState } from "./editor-state.ts";
+export type { EditorTheme } from "./editor-theme.ts";
+export { ModalEditorComponent, type ModalEditorHost } from "./modal-editor-component.ts";

package/extension/src/editor/{neovim-editor-component.ts → modal-editor-component.ts}

@@ -10,7 +10,7 @@ import type { EditorTheme } from "./editor-theme.ts";
 
 export type { EditorTheme } from "./editor-theme.ts";
 
-export interface NeovimEditorHost {
+export interface ModalEditorHost {
 	filePath: string;
 	/** Saves the buffer's current text through Lector's hash-guarded write. Throws (surfaced as a status message, not a crash) on a genuinely concurrent external change. */
 	save(text: string): Promise<void>;
@@ -28,16 +28,16 @@ const CAPTURE_COLOR: Record<string, ThemeColor> = {
 };
 
 /**
- * A real, full-file, neovim-style modal code editor Component -- not a CustomEditor subclass
+ * A real, full-file, modal code editor Component -- not a CustomEditor subclass
  * (that API replaces Pi's own chat input, not a full-file view; confirmed against
  * docs/tui.md's Pattern 7 and examples/extensions/modal-editor.ts). Renders as a `ctx.ui.custom`
  * overlay. Owns no authoritative state of its own past the open edit session: `EditorState`'s
  * LiveBuffer is the only in-memory copy, and every save round-trips through the host's
  * hash-guarded write -- never a second source of truth for the file's real disk content.
  */
-export class NeovimEditorComponent implements Component {
+export class ModalEditorComponent implements Component {
 	private readonly state: EditorState;
-	private readonly host: NeovimEditorHost;
+	private readonly host: ModalEditorHost;
 	private readonly tui: TUI;
 	private readonly theme: EditorTheme;
 	private readonly done: () => void;
@@ -47,7 +47,7 @@ export class NeovimEditorComponent implements Component {
 	private statusMessage = "";
 	private highlightCache: { text: string; spans: readonly HighlightSpan[] } | undefined;
 
-	constructor(tui: TUI, theme: EditorTheme, host: NeovimEditorHost, content: string, done: () => void) {
+	constructor(tui: TUI, theme: EditorTheme, host: ModalEditorHost, content: string, done: () => void) {
 		this.tui = tui;
 		this.theme = theme;
 		this.host = host;

package/extension/src/index.ts

@@ -77,7 +77,7 @@ import { createLectorEditOperations } from "./edit/operations.ts";
 import { openDirectoryExplorer } from "./editor/directory-explorer-operations.ts";
 import { ExplorerComponent, type ExplorerResult } from "./editor/explorer-component.ts";
 import { runExplorerFlow } from "./editor/explorer-flow.ts";
-import { NeovimEditorComponent, type NeovimEditorHost } from "./editor/neovim-editor-component.ts";
+import { ModalEditorComponent, type ModalEditorHost } from "./editor/modal-editor-component.ts";
 import { openEditorFile } from "./editor/operations.ts";
 import { createExternalSearchOperations } from "./external-search/operations.ts";
 import {
@@ -387,7 +387,7 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			await commandCtx.ui.custom<void>((tui, theme, _keybindings, done) => {
-				const host: NeovimEditorHost = {
+				const host: ModalEditorHost = {
 					filePath: absolutePath,
 					save: (text) => session.save(text),
 					hover: async (line, character) => {
@@ -395,7 +395,7 @@ export default function (pi: ExtensionAPI) {
 						return result.hover;
 					},
 				};
-				return new NeovimEditorComponent(tui, theme, host, session.content, () => done(undefined));
+				return new ModalEditorComponent(tui, theme, host, session.content, () => done(undefined));
 			}, editorOverlayOptions);
 		}
 
@@ -420,7 +420,7 @@ export default function (pi: ExtensionAPI) {
 		}
 
 		pi.registerCommand("editor", {
-			description: "Open a file in a neovim-style modal code editor, or a filesystem explorer with no path",
+			description: "Open a file in a modal code editor, or a filesystem explorer with no path",
 			handler: async (args, commandCtx) => {
 				const target = args.trim();
 				if (!target) {
@@ -1141,7 +1141,7 @@ export default function (pi: ExtensionAPI) {
 			name: "workspace_cache",
 			label: "Workspace Cache",
 			description:
-				"Checks or drives population of the workspace's persisted symbol graph -- the store reachable_from, symbol_annotations (anchor resolution), reference_based_rename, and workspace_map all read from, separate from the live language-server index find_symbols/hover/go_to_definition use. action=status reports not-cached/caching/partial/cached for the given bounds, without starting work. action=populate requests a scan and briefly waits for fast completion. action=wait subscribes to daemon job completion, with bounded status polling only when push delivery is unavailable. action=job_status is a point-in-time diagnostic read.",
+				"Checks or drives population of the workspace's persisted symbol graph -- the store reachable_from, symbol_annotations (anchor resolution), reference_based_rename, and workspace_map all read from, separate from the live language-server index find_symbols/hover/go_to_definition use. action=status reports not-cached/caching/partial/cached for the given bounds, without starting work. action=populate requests a scan and briefly waits for fast completion; a source file changing mid-scan (e.g. a concurrent edit or rename) is retried automatically in the background for up to a minute before surfacing as a real failure, no manual re-run needed. action=wait subscribes to daemon job completion, with bounded status polling only when push delivery is unavailable. action=job_status is a point-in-time diagnostic read.",
 			promptSnippet: "Check or force-populate the workspace's persisted symbol graph",
 			promptGuidelines: [
 				"Use action=populate with a larger maxFiles/maxSymbolsPerFile before relying on reachable_from/symbol_annotations/reference_based_rename against a workspace bigger than the default 500-file auto-scan -- their own errors (empty results, UnknownAnnotationAnchor, ReferenceBasedRenameRequiresFreshGraph) usually mean the graph never reached the files you need, not that population is simply still catching up.",

package/extension/src/reference-based-rename/operations.ts

@@ -13,6 +13,16 @@ import { lectorClient, type ResolvedWorkspace, withWorkspace, workspaceForCodeIn
  * the whole declared monorepo once (workspace_cache pointed at the repo root) and still rename a
  * file inside one of its member packages, without collapsing genuinely unrelated sibling projects
  * that were never declared together into one workspace identity.
+ *
+ * autoPopulate (Lector's own opt-in recovery from a "not-cached" graph) is applied carefully, not
+ * blanket-enabled: only once the correct FINAL scope is already known, never on a speculative
+ * first attempt that might still need widening. If a declared monorepo ancestor exists, the
+ * narrow project's own first attempt runs WITHOUT autoPopulate (so a genuinely never-populated
+ * narrow project still throws and triggers the widen-to-declared-root fallback below, exactly as
+ * before -- auto-populating the too-narrow scope here could make a rename "succeed" while
+ * silently missing a real cross-package reference the wider scope would have caught). Once widened
+ * to the declared root (or when no wider ancestor exists at all, meaning the narrow project IS the
+ * correct final scope), autoPopulate is safe and turned on -- one call converges instead of two.
  */
 export interface ReferenceBasedRenameOperations {
 	rename(fromPath: string, toPath: string, maxFiles: number, maxSymbolsPerFile: number): Promise<OperationOutputs["workspace.referenceBasedRename"]>;
@@ -21,19 +31,32 @@ export interface ReferenceBasedRenameOperations {
 export function createReferenceBasedRenameOperations(): ReferenceBasedRenameOperations {
 	return {
 		async rename(fromPath, toPath, maxFiles, maxSymbolsPerFile) {
-			const performRename = async ({ workspaceId }: ResolvedWorkspace) => {
+			const performRename = async ({ workspaceId }: ResolvedWorkspace, autoPopulate: boolean) => {
 				const client = await lectorClient();
-				return client.callOnce("workspace.referenceBasedRename", { workspaceId, fromPath, toPath, maxFiles, maxSymbolsPerFile });
+				return client.callOnce("workspace.referenceBasedRename", { workspaceId, fromPath, toPath, maxFiles, maxSymbolsPerFile, autoPopulate });
 			};
 
+			const narrow = await workspaceForCodeIntelligencePath(fromPath);
+			const declared = await workspaceForDeclaredMonorepoRoot(narrow.root);
+			if (!declared) {
+				// No wider declared ancestor -- the narrow project IS the correct, final scope, so
+				// auto-populating it directly is exactly as safe as the already-widened case below.
+				return withWorkspace(
+					() => Promise.resolve(narrow),
+					(resolved) => performRename(resolved, true),
+				);
+			}
 			try {
-				return await withWorkspace(() => workspaceForCodeIntelligencePath(fromPath), performRename);
+				return await withWorkspace(
+					() => Promise.resolve(narrow),
+					(resolved) => performRename(resolved, false),
+				);
 			} catch (error) {
 				if (!remoteErrorIs(error, "ReferenceBasedRenameRequiresFreshGraph")) throw error;
-				const narrow = await workspaceForCodeIntelligencePath(fromPath);
-				const declared = await workspaceForDeclaredMonorepoRoot(narrow.root);
-				if (!declared) throw error;
-				return withWorkspace(() => Promise.resolve(declared), performRename);
+				return withWorkspace(
+					() => Promise.resolve(declared),
+					(resolved) => performRename(resolved, true),
+				);
 			}
 		},
 	};

package/extension/src/workspace-cache/operations.ts

@@ -15,9 +15,26 @@ export interface JobWatchHandle {
 
 export type JobWatchOutcome = { readonly status: "subscribed"; readonly handle: JobWatchHandle } | { readonly status: "unavailable" };
 
+/**
+ * The daemon's own default (0/omitted -- fail fast on a WorkspaceChangedDuringPopulation race)
+ * would surface a live-editing/rename race straight to this tool's own caller as an opaque
+ * error. This tool's whole point is "make this converge for me" -- a bounded background retry
+ * costs the caller nothing extra (it runs inside the job the caller is already waiting on or
+ * polling, not as additional synchronous tool-call latency), so it defaults on here specifically,
+ * unlike the raw daemon operation which stays fail-fast by default for programmatic callers that
+ * want today's exact contract.
+ */
+const DEFAULT_POPULATE_RETRY_TIME_BUDGET_MS = 60_000;
+
 export interface WorkspaceCacheOperations {
 	status(directory: string, maxFiles: number, maxSymbolsPerFile: number): Promise<WorkspaceCacheStatus>;
-	submit(directory: string, maxFiles: number, maxSymbolsPerFile: number, waitMs?: number): Promise<JobSnapshot<PopulateSymbolGraphResult>>;
+	submit(
+		directory: string,
+		maxFiles: number,
+		maxSymbolsPerFile: number,
+		waitMs?: number,
+		retryTimeBudgetMs?: number,
+	): Promise<JobSnapshot<PopulateSymbolGraphResult>>;
 	jobStatus(jobId: string): Promise<JobSnapshot<PopulateSymbolGraphResult>>;
 	watchJob?(jobId: string, onJob: (job: JobSnapshot<PopulateSymbolGraphResult>) => void): Promise<JobWatchOutcome>;
 }
@@ -33,14 +50,14 @@ export function createWorkspaceCacheOperations(): WorkspaceCacheOperations {
 				},
 			);
 		},
-		submit(directory, maxFiles, maxSymbolsPerFile, waitMs = 0) {
+		submit(directory, maxFiles, maxSymbolsPerFile, waitMs = 0, retryTimeBudgetMs = DEFAULT_POPULATE_RETRY_TIME_BUDGET_MS) {
 			return withWorkspace(
 				() => workspaceForProjectDirectory(directory),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
 					const { job } = await client.callOnce("job.submit", {
 						operation: "workspace.populateSymbolGraph",
-						input: { workspaceId, maxFiles, maxSymbolsPerFile },
+						input: { workspaceId, maxFiles, maxSymbolsPerFile, retryTimeBudgetMs },
 						waitMs,
 					});
 					return job;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.12.7",
+	"version": "0.12.9",
 	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
 	"license": "MIT",
 	"type": "module",
@@ -12,6 +12,9 @@
 	"pi": {
 		"extensions": ["extension/src/index.ts"]
 	},
+	"exports": {
+		"./editor": "./extension/src/editor/index.ts"
+	},
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": "*",
 		"@earendil-works/pi-tui": "*",