@danypops/pi-lector 0.9.6 → 0.11.0

package/extension/src/editor/explorer-component.ts

@@ -0,0 +1,241 @@
+import { join, posix } from "node:path";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { applyExplorerDiffs, summarizeExplorerDiff } from "./apply-explorer-diffs.ts";
+import type { DirectoryExplorerSession } from "./directory-explorer-operations.ts";
+import type { EditorAction } from "./editor-state.ts";
+import { EditorState } from "./editor-state.ts";
+import type { EditorTheme } from "./editor-theme.ts";
+import type { ExplorerDiff, ExplorerEntry } from "./explorer-diff.ts";
+import { diffExplorerLines, formatExplorerLine, parseExplorerLine } from "./explorer-diff.ts";
+
+export type ExplorerResult = { kind: "quit" } | { kind: "open-file"; absolutePath: string };
+
+/** Joins a directory-relative name onto `directory` ("" means the resolved root itself). */
+export function joinExplorerPath(directory: string, name: string): string {
+	return directory === "" ? name : `${directory}/${name}`;
+}
+
+/** The relative parent of a directory-relative path; "" once already at the root. */
+function parentExplorerPath(directory: string): string {
+	const parent = posix.dirname(directory);
+	return parent === "." ? "" : parent;
+}
+
+interface PendingConfirmation {
+	readonly diffs: readonly ExplorerDiff[];
+	readonly andQuit: boolean;
+}
+
+/**
+ * An oil.nvim-style directory explorer: the listing IS the buffer (EditorState/LiveBuffer,
+ * reused as-is from the file editor -- normal/insert/dd/yy/p/undo/:w all already do exactly what
+ * renaming, deleting, and creating entries as text edits needs). Enter/`-` are intercepted before
+ * EditorState ever sees them (it has no existing mapping for either, confirmed against its own
+ * normal-mode key handling) since they're navigation, not buffer edits.
+ *
+ * :w never applies silently -- it always shows a confirmation summary first (oil.nvim's own
+ * default, skip_confirm_for_simple_edits = false), even for a single change.
+ */
+export class ExplorerComponent implements Component {
+	private readonly session: DirectoryExplorerSession;
+	private readonly tui: TUI;
+	private readonly theme: EditorTheme;
+	private readonly done: (result: ExplorerResult) => void;
+
+	private currentPath = "";
+	private entries: ExplorerEntry[] = [];
+	private nextId = 1;
+	private state = new EditorState("");
+	private scrollTop = 1;
+	private statusMessage = "";
+	private confirming: PendingConfirmation | undefined;
+
+	constructor(tui: TUI, theme: EditorTheme, session: DirectoryExplorerSession, initialRelativePath: string, done: (result: ExplorerResult) => void) {
+		this.tui = tui;
+		this.theme = theme;
+		this.session = session;
+		this.done = done;
+		void this.loadDirectory(initialRelativePath);
+	}
+
+	private pending: Promise<void> = Promise.resolve();
+
+	invalidate(): void {}
+
+	/** Fire-and-forget from the real TUI's own perspective (matching Component's void-returning contract) -- tests await settled() for deterministic assertions after triggering async work. */
+	handleInput(data: string): void {
+		this.pending = this.handleInputAsync(data);
+	}
+
+	/** Resolves once every async operation triggered by the most recent handleInput() call has finished -- a test-determinism hook, not part of the Component contract. */
+	settled(): Promise<void> {
+		return this.pending;
+	}
+
+	private async handleInputAsync(data: string): Promise<void> {
+		if (this.confirming) {
+			await this.handleConfirmationInput(data);
+			this.tui.requestRender();
+			return;
+		}
+
+		if (this.state.mode === "normal") {
+			if (data === "\r" || data === "\n") {
+				await this.openCurrentLine();
+				this.tui.requestRender();
+				return;
+			}
+			if (data === "-") {
+				await this.navigateToParent();
+				this.tui.requestRender();
+				return;
+			}
+		}
+
+		this.state.handleKey(data);
+		this.scrollToKeepCursorVisible();
+		const action = this.state.pendingAction;
+		if (action) await this.performAction(action);
+		this.tui.requestRender();
+	}
+
+	private async loadDirectory(relativePath: string): Promise<void> {
+		const listing = await this.session.listDirectory(relativePath);
+		this.currentPath = relativePath;
+		this.nextId = 1;
+		this.entries = listing.entries.map((entry) => ({ id: this.nextId++, name: entry.name, kind: entry.kind }));
+		const text = this.entries.length > 0 ? this.entries.map((entry) => formatExplorerLine(entry)).join("\n") : "";
+		this.state = new EditorState(text);
+		this.confirming = undefined;
+		this.statusMessage = "";
+		this.tui.requestRender();
+	}
+
+	private async openCurrentLine(): Promise<void> {
+		const parsed = parseExplorerLine(this.state.currentLineText);
+		if (!parsed || parsed.id === null) return; // a blank line or an unsaved new entry -- nothing real to open yet
+		const entry = this.entries.find((candidate) => candidate.id === parsed.id);
+		if (!entry) return;
+
+		if (entry.kind === "directory") {
+			await this.loadDirectory(joinExplorerPath(this.currentPath, entry.name));
+			return;
+		}
+		this.done({ kind: "open-file", absolutePath: join(this.session.root, joinExplorerPath(this.currentPath, entry.name)) });
+	}
+
+	private async navigateToParent(): Promise<void> {
+		if (this.currentPath === "") return; // already at the resolved root -- v1 never widens scope above it
+		await this.loadDirectory(parentExplorerPath(this.currentPath));
+	}
+
+	private async performAction(action: EditorAction): Promise<void> {
+		switch (action.kind) {
+			case "save":
+			case "save-and-quit": {
+				const diffs = diffExplorerLines(this.entries, this.state.buffer.text.split("\n"));
+				this.state.dirty = false;
+				if (diffs.length === 0) {
+					this.statusMessage = "no changes";
+					if (action.kind === "save-and-quit") this.done({ kind: "quit" });
+					return;
+				}
+				this.confirming = { diffs, andQuit: action.kind === "save-and-quit" };
+				return;
+			}
+			case "quit":
+				this.done({ kind: "quit" });
+				return;
+			case "hover":
+				this.statusMessage = "hover is not applicable in the file explorer";
+				return;
+			default: {
+				const exhaustive: never = action;
+				throw new Error(`Unhandled editor action: ${JSON.stringify(exhaustive)}`);
+			}
+		}
+	}
+
+	private async handleConfirmationInput(data: string): Promise<void> {
+		if (!this.confirming) return;
+		if (data === "n" || data === "\x1b") {
+			this.confirming = undefined;
+			this.statusMessage = "cancelled";
+			return;
+		}
+		if (data !== "y" && data !== "\r" && data !== "\n") return;
+
+		const { diffs, andQuit } = this.confirming;
+		try {
+			await applyExplorerDiffs(this.session, this.currentPath, diffs);
+		} catch (error) {
+			this.confirming = undefined;
+			this.statusMessage = `apply failed: ${error instanceof Error ? error.message : String(error)}`;
+			return;
+		}
+		if (andQuit) {
+			this.done({ kind: "quit" });
+			return;
+		}
+		await this.loadDirectory(this.currentPath);
+		this.statusMessage = "applied";
+	}
+
+	private scrollToKeepCursorVisible(): void {
+		const viewportHeight = Math.max(1, this.tui.terminal.rows - 2);
+		if (this.state.cursorLine < this.scrollTop) this.scrollTop = this.state.cursorLine;
+		else if (this.state.cursorLine >= this.scrollTop + viewportHeight) this.scrollTop = this.state.cursorLine - viewportHeight + 1;
+	}
+
+	render(width: number): string[] {
+		if (this.confirming) return this.renderConfirmation(this.confirming, width);
+
+		const viewportHeight = Math.max(1, this.tui.terminal.rows - 2);
+		const lastLine = Math.min(this.state.buffer.lineCount, this.scrollTop + viewportHeight - 1);
+
+		const lines: string[] = [];
+		for (let line = this.scrollTop; line <= lastLine; line++) lines.push(this.renderLine(line, width));
+		while (lines.length < viewportHeight) lines.push("");
+
+		lines.push(this.renderStatusLine(width));
+		return lines;
+	}
+
+	private renderConfirmation(confirming: PendingConfirmation, width: number): string[] {
+		const lines = ["Pending changes:", "", ...confirming.diffs.map((diff) => `  ${summarizeExplorerDiff(diff)}`), "", "Apply? (y/n)"];
+		return lines.map((line) => truncateToWidth(line, width, ""));
+	}
+
+	private renderLine(line: number, width: number): string {
+		const lineText = this.state.buffer.lineText(line);
+		const isCursorLine = line === this.state.cursorLine;
+		const styled = isCursorLine ? this.renderLineWithCursor(lineText) : this.renderStyledLine(lineText);
+		return truncateToWidth(styled, width, "");
+	}
+
+	/** Dims the id prefix (a real character sequence in this terminal, not truly hidden -- see explorer-diff.ts) so it reads as secondary to the entry's own name. */
+	private renderStyledLine(lineText: string): string {
+		const match = lineText.match(/^(\d+ )(.*)$/);
+		if (!match) return lineText;
+		const [, idPart, rest] = match;
+		return `${this.theme.fg("muted", idPart ?? "")}${rest ?? ""}`;
+	}
+
+	private renderLineWithCursor(lineText: string): string {
+		const col = this.state.cursorCharacter - 1;
+		const before = this.renderStyledLine(lineText.slice(0, col));
+		const atCursor = col < lineText.length ? lineText[col] : " ";
+		const after = lineText.slice(col + 1);
+		return `${before}\x1b[7m${atCursor}\x1b[0m${after}`;
+	}
+
+	private renderStatusLine(width: number): string {
+		const modeLabel = { normal: " NORMAL ", insert: " INSERT ", command: " COMMAND " }[this.state.mode];
+		const location = this.currentPath === "" ? "/" : `/${this.currentPath}/`;
+		const left = this.state.mode === "command" ? `:${this.state.commandText}` : `${this.theme.fg("accent", modeLabel)} ${location}`;
+		const right = this.statusMessage || `${this.state.cursorLine}:${this.state.cursorCharacter}`;
+		const gap = Math.max(1, width - visibleWidth(left) - visibleWidth(right));
+		return truncateToWidth(`${left}${" ".repeat(gap)}${right}`, width, "");
+	}
+}

package/extension/src/editor/explorer-diff.ts

@@ -0,0 +1,85 @@
+import type { FileTreeEntryKind } from "@danypops/lector";
+
+/** One entry as last known from a real directory listing -- id is this explorer's own per-session identity, not anything Lector's daemon tracks. */
+export interface ExplorerEntry {
+	readonly id: number;
+	readonly name: string;
+	readonly kind: FileTreeEntryKind;
+}
+
+/** One buffer line, parsed back into its id (if any) and name. */
+export interface ParsedExplorerLine {
+	readonly id: number | null;
+	readonly name: string;
+	readonly isDirectory: boolean;
+}
+
+export type ExplorerDiff =
+	| { readonly kind: "create"; readonly name: string; readonly isDirectory: boolean }
+	| { readonly kind: "rename"; readonly id: number; readonly fromName: string; readonly toName: string }
+	| { readonly kind: "delete"; readonly id: number; readonly name: string; readonly isDirectory: boolean };
+
+/** Renders one entry as this explorer's own line format: "<id> name", a trailing "/" for directories. Ported from oil.nvim's own id-prefix convention (lua/oil/mutator/parser.lua) -- this terminal has no Neovim conceallevel equivalent, so the id is real, visible (if dimly styled) text, not truly hidden. */
+export function formatExplorerLine(entry: ExplorerEntry): string {
+	return `${entry.id} ${entry.name}${entry.kind === "directory" ? "/" : ""}`;
+}
+
+const EXISTING_LINE_PATTERN = /^(\d+) (.+)$/;
+
+function stripTrailingSlash(name: string): { name: string; isDirectory: boolean } {
+	return name.endsWith("/") ? { name: name.slice(0, -1), isDirectory: true } : { name, isDirectory: false };
+}
+
+/** Parses one buffer line back into id/name/isDirectory. Returns null for a blank line -- ignored entirely, never a new entry named "". */
+export function parseExplorerLine(rawLine: string): ParsedExplorerLine | null {
+	const trimmed = rawLine.trim();
+	if (trimmed === "") return null;
+
+	const existingMatch = trimmed.match(EXISTING_LINE_PATTERN);
+	if (existingMatch) {
+		const idText = existingMatch[1];
+		const rest = existingMatch[2];
+		if (idText === undefined || rest === undefined) return null;
+		const { name, isDirectory } = stripTrailingSlash(rest.trim());
+		return { id: Number(idText), name, isDirectory };
+	}
+
+	const { name, isDirectory } = stripTrailingSlash(trimmed);
+	return { id: null, name, isDirectory };
+}
+
+/**
+ * Diffs the explorer's current buffer lines against the original listing, matched by id -- never
+ * by line position, so reordering existing lines produces no diff at all. Every original entry
+ * not re-seen by its own id becomes a delete; every id-tagged line whose name changed becomes a
+ * rename; every line with no id tag becomes a create.
+ */
+export function diffExplorerLines(original: readonly ExplorerEntry[], currentLines: readonly string[]): ExplorerDiff[] {
+	const byId = new Map(original.map((entry) => [entry.id, entry]));
+	const unseenIds = new Set(byId.keys());
+	const diffs: ExplorerDiff[] = [];
+
+	for (const rawLine of currentLines) {
+		const parsed = parseExplorerLine(rawLine);
+		if (!parsed) continue;
+
+		if (parsed.id === null) {
+			diffs.push({ kind: "create", name: parsed.name, isDirectory: parsed.isDirectory });
+			continue;
+		}
+
+		const originalEntry = byId.get(parsed.id);
+		unseenIds.delete(parsed.id);
+		if (!originalEntry) continue; // an id that doesn't match anything real -- silently ignored, same as a stray line would be
+		if (originalEntry.name !== parsed.name) {
+			diffs.push({ kind: "rename", id: parsed.id, fromName: originalEntry.name, toName: parsed.name });
+		}
+	}
+
+	for (const id of unseenIds) {
+		const entry = byId.get(id);
+		if (entry) diffs.push({ kind: "delete", id: entry.id, name: entry.name, isDirectory: entry.kind === "directory" });
+	}
+
+	return diffs;
+}

package/extension/src/editor/explorer-flow.ts

@@ -0,0 +1,27 @@
+import { dirname, relative } from "node:path";
+import type { DirectoryExplorerSession } from "./directory-explorer-operations.ts";
+import type { ExplorerResult } from "./explorer-component.ts";
+
+export interface ExplorerFlowHost {
+	/** Shows the explorer at `relativePath` (root-relative, "" for the resolved root) and resolves once the user quits or opens a file. */
+	showExplorer(session: DirectoryExplorerSession, relativePath: string): Promise<ExplorerResult>;
+	/** Shows the real file editor for `absolutePath` and resolves once the user quits it. */
+	showEditor(absolutePath: string): Promise<void>;
+}
+
+/**
+ * Oil-style /editor-with-no-path loop: browse, open a file into the real editor, then return to
+ * the explorer -- at the directory the opened file lives in, not the resolved root -- once that
+ * editor quits, rather than closing the whole session after the first file opened.
+ */
+export async function runExplorerFlow(session: DirectoryExplorerSession, host: ExplorerFlowHost): Promise<void> {
+	let relativePath = "";
+	for (;;) {
+		const result = await host.showExplorer(session, relativePath);
+		if (result.kind === "quit") return;
+
+		await host.showEditor(result.absolutePath);
+		// path.relative(root, root) is "" directly, matching ExplorerComponent's own root-relative convention -- no "." case to normalize.
+		relativePath = relative(session.root, dirname(result.absolutePath));
+	}
+}

package/extension/src/editor/neovim-editor-component.ts

@@ -0,0 +1,196 @@
+import { extname } from "node:path";
+import type { HighlightSpan } from "@danypops/lector";
+import { highlightSpans } from "@danypops/lector";
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { EditorAction } from "./editor-state.ts";
+import { EditorState } from "./editor-state.ts";
+import type { EditorTheme } from "./editor-theme.ts";
+
+export type { EditorTheme } from "./editor-theme.ts";
+
+export interface NeovimEditorHost {
+	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>;
+	/** Real hover info from Lector's existing code-intelligence operation, or undefined when there is none at this position. */
+	hover(line: number, character: number): Promise<{ contents: string } | undefined>;
+}
+
+const CAPTURE_COLOR: Record<string, ThemeColor> = {
+	keyword: "syntaxKeyword",
+	comment: "syntaxComment",
+	string: "syntaxString",
+	number: "syntaxNumber",
+	function: "syntaxFunction",
+	type: "syntaxType",
+};
+
+/**
+ * A real, full-file, neovim-style 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 {
+	private readonly state: EditorState;
+	private readonly host: NeovimEditorHost;
+	private readonly tui: TUI;
+	private readonly theme: EditorTheme;
+	private readonly done: () => void;
+	private readonly extension: string;
+
+	private scrollTop = 1;
+	private statusMessage = "";
+	private highlightCache: { text: string; spans: readonly HighlightSpan[] } | undefined;
+
+	constructor(tui: TUI, theme: EditorTheme, host: NeovimEditorHost, content: string, done: () => void) {
+		this.tui = tui;
+		this.theme = theme;
+		this.host = host;
+		this.done = done;
+		this.extension = extname(host.filePath);
+		this.state = new EditorState(content);
+		void this.refreshHighlights();
+	}
+
+	invalidate(): void {
+		this.highlightCache = undefined;
+	}
+
+	handleInput(data: string): void {
+		this.state.handleKey(data);
+		this.scrollToKeepCursorVisible();
+		const action = this.state.pendingAction;
+		if (action) void this.performAction(action);
+		this.tui.requestRender();
+	}
+
+	private async performAction(action: EditorAction): Promise<void> {
+		switch (action.kind) {
+			case "save":
+			case "save-and-quit": {
+				try {
+					await this.host.save(this.state.buffer.text);
+					this.state.dirty = false;
+					this.statusMessage = `"${this.host.filePath}" written`;
+				} catch (error) {
+					this.statusMessage = `save failed: ${error instanceof Error ? error.message : String(error)}`;
+					this.tui.requestRender();
+					return;
+				}
+				if (action.kind === "save-and-quit") {
+					this.done();
+					return;
+				}
+				break;
+			}
+			case "quit":
+				this.done();
+				return;
+			case "hover": {
+				const hover = await this.host.hover(this.state.cursorLine, this.state.cursorCharacter);
+				const firstLine = hover?.contents.split("\n")[0];
+				this.statusMessage = firstLine ?? "no hover info at this position";
+				break;
+			}
+			default: {
+				const exhaustive: never = action;
+				throw new Error(`Unhandled editor action: ${JSON.stringify(exhaustive)}`);
+			}
+		}
+		this.tui.requestRender();
+	}
+
+	private async refreshHighlights(): Promise<void> {
+		const text = this.state.buffer.text;
+		const spans = await highlightSpans(text, this.extension);
+		this.highlightCache = { text, spans };
+		this.tui.requestRender();
+	}
+
+	private scrollToKeepCursorVisible(): void {
+		const viewportHeight = Math.max(1, this.tui.terminal.rows - 2);
+		if (this.state.cursorLine < this.scrollTop) this.scrollTop = this.state.cursorLine;
+		else if (this.state.cursorLine >= this.scrollTop + viewportHeight) this.scrollTop = this.state.cursorLine - viewportHeight + 1;
+	}
+
+	render(width: number): string[] {
+		if (this.highlightCache?.text !== this.state.buffer.text) void this.refreshHighlights();
+
+		const viewportHeight = Math.max(1, this.tui.terminal.rows - 2);
+		const gutterWidth = Math.max(3, String(this.state.buffer.lineCount).length) + 1;
+		const lastLine = Math.min(this.state.buffer.lineCount, this.scrollTop + viewportHeight - 1);
+
+		const lines: string[] = [];
+		for (let line = this.scrollTop; line <= lastLine; line++) {
+			lines.push(this.renderLine(line, gutterWidth, width - gutterWidth));
+		}
+		while (lines.length < viewportHeight) lines.push("");
+
+		lines.push(this.renderStatusLine(width));
+		return lines;
+	}
+
+	private renderLine(line: number, gutterWidth: number, contentWidth: number): string {
+		const isCursorLine = line === this.state.cursorLine;
+		const gutterNumber = isCursorLine ? String(line) : String(Math.abs(line - this.state.cursorLine));
+		const gutter = `${this.theme.fg(isCursorLine ? "text" : "muted", gutterNumber.padStart(gutterWidth - 1))} `;
+
+		const lineText = this.state.buffer.lineText(line);
+		const rendered = isCursorLine ? this.renderLineWithCursor(line, lineText) : this.renderHighlightedLine(line, lineText);
+		return gutter + truncateToWidth(rendered, contentWidth, "");
+	}
+
+	private spansForLine(line: number): readonly HighlightSpan[] {
+		if (!this.highlightCache) return [];
+		const from = this.state.buffer.offsetAt({ line, character: 1 });
+		const to = from + this.state.buffer.lineText(line).length;
+		return this.highlightCache.spans.filter((span) => span.startIndex < to && span.endIndex > from);
+	}
+
+	private renderHighlightedLine(line: number, lineText: string): string {
+		const from = this.state.buffer.offsetAt({ line, character: 1 });
+		const spans = this.spansForLine(line);
+		let result = "";
+		let cursor = 0;
+		for (const span of spans) {
+			const start = Math.max(span.startIndex - from, 0);
+			const end = Math.min(span.endIndex - from, lineText.length);
+			if (start < cursor) continue; // overlapping captures -- keep the earliest, simplest for v1
+			result += lineText.slice(cursor, start);
+			const color = CAPTURE_COLOR[span.capture];
+			result += color ? this.theme.fg(color, lineText.slice(start, end)) : lineText.slice(start, end);
+			cursor = end;
+		}
+		result += lineText.slice(cursor);
+		return result;
+	}
+
+	/** The cursor's own line: highlighted text plus an inverse-video cursor cell, matching pi-tui's own Editor cursor convention. */
+	private renderLineWithCursor(line: number, lineText: string): string {
+		const highlighted = this.renderHighlightedLine(line, lineText);
+		// Re-slicing a pre-highlighted (ANSI-embedded) string by character index would misplace the
+		// cursor inside escape codes -- render the cursor against the plain text, forgoing this
+		// line's syntax highlighting. Acceptable for v1: only one line is ever affected at a time.
+		void highlighted;
+		const col = this.state.cursorCharacter - 1;
+		const before = lineText.slice(0, col);
+		const atCursor = col < lineText.length ? lineText[col] : " ";
+		const after = col < lineText.length ? lineText.slice(col + 1) : "";
+		return `${before}\x1b[7m${atCursor}\x1b[0m${after}`;
+	}
+
+	private renderStatusLine(width: number): string {
+		const modeLabel = { normal: " NORMAL ", insert: " INSERT ", command: " COMMAND " }[this.state.mode];
+		const dirtyMarker = this.state.dirty ? " [+]" : "";
+		const position = `${this.state.cursorLine}:${this.state.cursorCharacter}`;
+		const left = this.state.mode === "command" ? `:${this.state.commandText}` : `${this.theme.fg("accent", modeLabel)} ${this.host.filePath}${dirtyMarker}`;
+		const right = this.statusMessage || position;
+		const gap = Math.max(1, width - visibleWidth(left) - visibleWidth(right));
+		return truncateToWidth(`${left}${" ".repeat(gap)}${right}`, width, "");
+	}
+}

package/extension/src/editor/operations.ts

@@ -0,0 +1,36 @@
+import type { ContentHash } from "@danypops/lector";
+import { lectorClient, withWorkspace, workspaceForPath } from "../lector-client.ts";
+import { toWorkspaceRelativePath } from "../workspace-relative-path.ts";
+
+export interface EditorFileSession {
+	readonly content: string;
+	/**
+	 * Saves through Lector's hash-guarded `workspace.exactEdit` -- deliberately NOT the
+	 * transparent stale-hash-retry behavior `createLectorWriteOperations` uses for pi's
+	 * unconditional-overwrite write tool. `/editor`'s `:w` is a human editing a file they can see
+	 * on screen; a genuinely concurrent external change must surface as a real, visible error
+	 * (StaleExpectedHash), never be silently overwritten just because the model's write-tool
+	 * contract happens to prefer that elsewhere.
+	 */
+	save(text: string): Promise<void>;
+}
+
+/** Opens `absolutePath` for `/editor`: one hash-guarded read, then a save() closure that tracks the hash across saves within the same session. */
+export function openEditorFile(absolutePath: string): Promise<EditorFileSession> {
+	return withWorkspace(
+		() => workspaceForPath(absolutePath),
+		async ({ workspaceId, root }) => {
+			const client = await lectorClient();
+			const relativePath = toWorkspaceRelativePath(root, absolutePath);
+			const { content, hash } = await client.call("workspace.rawRead", { workspaceId, path: relativePath });
+			let expectedHash: ContentHash | null = hash;
+			return {
+				content,
+				async save(text: string): Promise<void> {
+					const outcome = await client.callOnce("workspace.exactEdit", { workspaceId, path: relativePath, expectedHash, content: text });
+					expectedHash = outcome.newHash;
+				},
+			};
+		},
+	);
+}

package/extension/src/{external-search-operations.ts → external-search/operations.ts}

@@ -1,5 +1,5 @@
 import type { GithubRepoSearchResult, NpmPackageCandidate, SourcegraphCodeCandidate } from "@danypops/lector";
-import { lectorClient } from "./lector-client.ts";
+import { lectorClient } from "../lector-client.ts";
 
 /** Thin wrapper over search.githubRepos/search.npmPackages/search.sourcegraphCode -- explicit-query discovery inputs shaped for repo_cache/package_source, never open-ended discovery/trending. */
 export interface ExternalSearchOperations {

package/extension/src/{external-search-rendering.ts → external-search/rendering.ts}

@@ -1,5 +1,5 @@
 import type { GithubRepoSearchResult, NpmPackageCandidate, SourcegraphCodeCandidate } from "@danypops/lector";
-import type { LectorTheme } from "./lector-tui-theme.ts";
+import type { LectorTheme } from "../lector-tui-theme.ts";
 
 type ExternalSearchAction = "github_repos" | "npm_packages" | "sourcegraph_code";
 

package/extension/src/{find-files-operations.ts → find-files/operations.ts}

@@ -1,5 +1,5 @@
 import type { FindFilesResult } from "@danypops/lector";
-import { lectorClient, withWorkspace, workspaceForDirectory } from "./lector-client.ts";
+import { lectorClient, withWorkspace, workspaceForDirectory } from "../lector-client.ts";
 
 /**
  * Thin wrapper over workspace.findFiles -- the `find`-shaped half of the classic grep+find pair,

package/extension/src/{find-files-rendering.ts → find-files/rendering.ts}

@@ -1,7 +1,7 @@
 import type { FindFilesResult } from "@danypops/lector";
 import { keyHint } from "@earendil-works/pi-coding-agent";
 import { renderTruncatedList } from "malevich-tui-components";
-import type { LectorTheme } from "./lector-tui-theme.ts";
+import type { LectorTheme } from "../lector-tui-theme.ts";
 
 const DEFAULT_VISIBLE_PATHS = 40;
 

package/extension/src/{find-symbols-operations.ts → find-symbols/operations.ts}

@@ -1,5 +1,5 @@
 import type { OperationInputs, SymbolSearchResult } from "@danypops/lector";
-import { lectorClient, withWorkspace, workspaceForDirectory } from "./lector-client.ts";
+import { lectorClient, withWorkspace, workspaceForDirectory } from "../lector-client.ts";
 
 /**
  * Thin wrapper over workspace.findSymbols. No seedFile parameter here or

package/extension/src/{find-symbols-rendering.ts → find-symbols/rendering.ts}

@@ -1,7 +1,7 @@
 import type { SymbolSearchResult, WorkspaceSymbol } from "@danypops/lector";
 import { keyHint } from "@earendil-works/pi-coding-agent";
 import { renderTruncatedList } from "malevich-tui-components";
-import { colorForKind, formatLocation, type LectorTheme } from "./lector-tui-theme.ts";
+import { colorForKind, formatLocation, type LectorTheme } from "../lector-tui-theme.ts";
 
 /**
  * Custom TUI rendering for find_symbols -- the one Lector-backed tool with

package/extension/src/{git-operations.ts → git/operations.ts}

@@ -1,5 +1,5 @@
 import type { GitDiffResult, GitLogEntry, GitStatusSummary, OperationOutputs } from "@danypops/lector";
-import { lectorClient, withWorkspace, workspaceForDirectory } from "./lector-client.ts";
+import { lectorClient, withWorkspace, workspaceForDirectory } from "../lector-client.ts";
 
 type SymbolComparison = OperationOutputs["workspace.compareSymbolAcrossVersions"];
 

package/extension/src/{git-rendering.ts → git/rendering.ts}

@@ -2,7 +2,7 @@ import type { GitDiffResult, GitLogEntry, GitStatusSummary, OperationOutputs } f
 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";
-import type { LectorTheme } from "./lector-tui-theme.ts";
+import type { LectorTheme } from "../lector-tui-theme.ts";
 
 /** Real ANSI-aware measurement, not Malevich's own ASCII-only default -- every diff line renderDiffLines receives is already theme.fg-styled. */
 const measure: TextMeasure = { visibleWidth, truncateToWidth };