@danypops/pi-lector 0.12.15 → 0.13.1

package/extension/src/bounded-poll.ts

@@ -0,0 +1,19 @@
+/**
+ * Idempotent start/stop wrapper over setInterval -- a second start() is a no-op rather than a
+ * competing timer, and stop() is safe to call even if never started. Same shape as pi-papyrus's,
+ * pi-pipes', pi-packed's, and pi-tickets' own BoundedPoll.
+ */
+export class BoundedPoll {
+	private timer: ReturnType<typeof setInterval> | undefined;
+
+	start(intervalMs: number, tick: () => void): void {
+		if (this.timer) return;
+		this.timer = setInterval(tick, intervalMs);
+	}
+
+	stop(): void {
+		if (!this.timer) return;
+		clearInterval(this.timer);
+		this.timer = undefined;
+	}
+}

package/extension/src/index.ts

@@ -129,6 +129,7 @@ import { formatSearchCall, formatSearchResult } from "./search/rendering.ts";
 import { type AnnotationAnchorInput, createLectorSymbolAnnotationOperations } from "./symbol-annotation/operations.ts";
 import { formatAnnotationDetail, formatAnnotationListSummary, formatAnnotationSummary } from "./symbol-annotation/rendering.ts";
 import type { LectorVehicleCall } from "./vehicle-client.ts";
+import { CachingOverlay } from "./workspace-cache/caching-overlay.ts";
 import {
 	type CachePresentationState,
 	cacheContextMessage,
@@ -278,6 +279,7 @@ export default function (pi: ExtensionAPI) {
 		};
 	});
 
+	let cachingOverlay: CachingOverlay | undefined;
 	pi.on("session_shutdown", (_event, ctx) => {
 		sessionGeneration++;
 		cacheStatesByRoot.clear();
@@ -285,6 +287,7 @@ export default function (pi: ExtensionAPI) {
 		lastInjectedSummary = undefined;
 		uiContext = undefined;
 		ctx.ui.setStatus("lector-cache", undefined);
+		cachingOverlay?.dispose();
 	});
 
 	pi.on("session_start", (_event, ctx) => {
@@ -295,6 +298,14 @@ export default function (pi: ExtensionAPI) {
 		lastInjectedSummary = undefined;
 		uiContext = ctx;
 		setNewWorkspaceObserver((root) => startMonitoringRoot(root, ctx));
+		if (ctx.hasUI) {
+			// The persistent widget counterpart to the single-line "lector-cache" status above --
+			// enumerates EVERY workspace currently caching, not just this session's own cwd root.
+			cachingOverlay ??= new CachingOverlay();
+			cachingOverlay.setUI(ctx.ui);
+			void cachingOverlay.refresh();
+			cachingOverlay.startPolling();
+		}
 		const thisGeneration = sessionGeneration;
 		void nearestGitWorkspaceRoot(cwd)
 			.then((projectRoot) => {

package/extension/src/workspace-cache/caching-overlay.ts

@@ -0,0 +1,124 @@
+/**
+ * Persistent above-editor widget for currently-active symbol-graph caching jobs -- mirrors
+ * pi-papyrus's own TaskOverlay/NoteOverlay, pi-pipes' own JobsOverlay, and pi-packed's own
+ * DoctorOverlay: factory-form ctx.ui.setWidget registration, requestRender on refresh, hides the
+ * widget entirely (setWidget(key, undefined)) rather than an empty box once nothing is caching.
+ *
+ * workspace.activeCachingJobs enumerates every workspace with a currently active (queued/
+ * running) population job -- see packages/lector/src/service/symbol-graph/cache-query-handlers.ts.
+ */
+import type { ExtensionUIContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { TUI } from "@earendil-works/pi-tui";
+import { AutoRotatingWindow } from "malevich-tui-components";
+import { BoundedPoll } from "../bounded-poll.js";
+import { lectorClient, type RetryingLectorClient } from "../lector-client.js";
+import { buildCachingWidgetProjection, type CachingWidgetProjection, LECTOR_CACHING_WIDGET_VISIBLE_ROWS, renderCachingWidgetLines } from "./caching-widget.js";
+
+const WIDGET_KEY = "pi-lector-caching";
+
+/** Matches pi-papyrus's/pi-pipes' own 15-20s cadence -- workspace.activeCachingJobs is a cheap in-memory read. */
+export const CACHING_WIDGET_POLL_INTERVAL_MS = 15_000;
+
+/** How often the widget's own auto-rotating overflow page advances. */
+export const CACHING_WIDGET_ROTATION_INTERVAL_MS = 6_000;
+
+const EMPTY_PROJECTION: CachingWidgetProjection = { rows: [], total: 0 };
+
+export class CachingOverlay {
+	private uiCtx: ExtensionUIContext | undefined;
+	private registered = false;
+	private tui: TUI | undefined;
+	private projection: CachingWidgetProjection = EMPTY_PROJECTION;
+	private readonly poll = new BoundedPoll();
+	/** Repaint-only ticker (no data refetch) so the widget's own auto-rotating page visibly
+	 * advances even when nothing else has changed. */
+	private readonly rotationPoll = new BoundedPoll();
+	private readonly rotation = new AutoRotatingWindow({
+		totalRows: 0,
+		pageSize: LECTOR_CACHING_WIDGET_VISIBLE_ROWS,
+		intervalMs: CACHING_WIDGET_ROTATION_INTERVAL_MS,
+	});
+
+	constructor(private readonly connect: () => Promise<RetryingLectorClient> = lectorClient) {}
+
+	setUI(ctx: ExtensionUIContext): void {
+		if (ctx !== this.uiCtx) {
+			this.uiCtx = ctx;
+			this.registered = false;
+			this.tui = undefined;
+		}
+	}
+
+	/** Never throws: called from a poll timer and from session_start, neither of which should turn
+	 * a best-effort status widget into a crashed extension host over a daemon that isn't running
+	 * yet or a rendering bug. */
+	async refresh(): Promise<void> {
+		try {
+			const client = await this.connect();
+			const result = await client.call("workspace.activeCachingJobs", {});
+			this.projection = buildCachingWidgetProjection(result.jobs);
+		} catch {
+			this.projection = EMPTY_PROJECTION;
+		}
+		try {
+			this.render();
+		} catch {
+			// A rendering bug must not crash the extension host over a best-effort status widget.
+		}
+	}
+
+	private render(): void {
+		if (!this.uiCtx) return;
+
+		if (this.projection.total === 0) {
+			if (this.registered) {
+				this.uiCtx.setWidget(WIDGET_KEY, undefined);
+				this.registered = false;
+				this.tui = undefined;
+				this.rotationPoll.stop();
+			}
+			return;
+		}
+
+		if (!this.registered) {
+			this.uiCtx.setWidget(
+				WIDGET_KEY,
+				(tui: TUI, theme: Theme) => {
+					this.tui = tui;
+					return {
+						render: (width: number) => renderCachingWidgetLines(theme, this.projection, width, this.rotation),
+						invalidate: () => {
+							// Theme changed -- force re-registration, matching every other overlay in this ecosystem.
+							this.registered = false;
+							this.tui = undefined;
+						},
+					};
+				},
+				{ placement: "aboveEditor" },
+			);
+			this.registered = true;
+			this.rotationPoll.start(CACHING_WIDGET_ROTATION_INTERVAL_MS, () => this.tui?.requestRender());
+		} else {
+			this.tui?.requestRender();
+		}
+	}
+
+	startPolling(intervalMs: number = CACHING_WIDGET_POLL_INTERVAL_MS): void {
+		this.poll.start(intervalMs, () => {
+			void this.refresh();
+		});
+	}
+
+	stopPolling(): void {
+		this.poll.stop();
+	}
+
+	dispose(): void {
+		this.stopPolling();
+		this.rotationPoll.stop();
+		this.uiCtx?.setWidget(WIDGET_KEY, undefined);
+		this.registered = false;
+		this.tui = undefined;
+		this.uiCtx = undefined;
+	}
+}

package/extension/src/workspace-cache/caching-widget.ts

@@ -0,0 +1,73 @@
+/**
+ * Pure projection/render pair for the Caching widget -- mirrors pi-papyrus's own task-widget.ts /
+ * pi-pipes' own jobs-widget.ts / pi-packed's own doctor-widget.ts split: the daemon's
+ * workspace.activeCachingJobs result in, a bounded intermediate shape out, no I/O, no TUI, fully
+ * unit-testable without a real daemon or terminal. See caching-overlay.ts for the stateful
+ * ctx.ui.setWidget-registered class that drives these from a live poll.
+ */
+import { vehicleWidgetTitle } from "@danypops/vehicle-client-pi/widget-header";
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { type AutoRotatingWindow, renderCardRow, type TextMeasure } from "malevich-tui-components";
+
+const measure: TextMeasure = { visibleWidth, truncateToWidth, wrapTextWithAnsi };
+
+/** The daemon's own manifest name (see packages/lector/src/service.ts's `new VehicleRegistry({ name: "lector" })`). */
+const VEHICLE_NAME = "lector";
+
+/** Visible rows per page before the auto-rotating overflow hint pages to the next. */
+export const LECTOR_CACHING_WIDGET_VISIBLE_ROWS = 5;
+
+export interface CachingWidgetRow {
+	workspaceId: string;
+	status: "queued" | "running" | "waiting-for-resources";
+}
+
+export interface CachingWidgetProjection {
+	rows: CachingWidgetRow[];
+	total: number;
+}
+
+export function buildCachingWidgetProjection(jobs: readonly CachingWidgetRow[]): CachingWidgetProjection {
+	return { rows: [...jobs], total: jobs.length };
+}
+
+function cachingRowLine(theme: { fg(color: string, text: string): string }, row: CachingWidgetRow, width: number): string {
+	const glyph =
+		row.status === "waiting-for-resources"
+			? theme.fg("warning", "\u23f8")
+			: row.status === "queued"
+				? theme.fg("muted", "\u2022")
+				: theme.fg("accent", "\u25b6");
+	return truncateToWidth(`${glyph} ${row.workspaceId}`, width, "\u2026");
+}
+
+/** "Lector · Caching · <N>", plus a "page/total ⟳" suffix once genuinely paging. */
+function cachingCardLabel(projection: CachingWidgetProjection, rotation?: AutoRotatingWindow): string {
+	const base = vehicleWidgetTitle(VEHICLE_NAME, "Caching", `${projection.total}`);
+	return rotation?.isPaging ? `${base} \u00b7 ${rotation.pageIndex + 1}/${rotation.pageCount} \u27f3` : base;
+}
+
+/** Renders the widget as a single bordered card -- `[]` (hide the whole widget) when nothing is
+ * currently caching, matching every other overlay's own "hide when nothing to show" convention. */
+export function renderCachingWidgetLines(
+	theme: { fg(color: string, text: string): string },
+	projection: CachingWidgetProjection,
+	width: number,
+	rotation?: AutoRotatingWindow,
+): string[] {
+	if (projection.total === 0) return [];
+	rotation?.setTotalRows(projection.rows.length);
+	const { start, end } = rotation?.currentPageBounds() ?? { start: 0, end: projection.rows.length };
+	const visibleRows = projection.rows.slice(start, end);
+
+	return renderCardRow(
+		[
+			{
+				label: cachingCardLabel(projection, rotation),
+				render: (innerWidth: number) => visibleRows.map((row) => cachingRowLine(theme, row, innerWidth)),
+			},
+		],
+		width,
+		{ measure, frameStyle: (s) => theme.fg("borderMuted", s) },
+	);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.12.15",
+	"version": "0.13.1",
 	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
 	"license": "MIT",
 	"type": "module",
@@ -22,10 +22,10 @@
 		"@danypops/vehicle-client-pi": "^0.43.0"
 	},
 	"dependencies": {
+		"@danypops/lector": "^0.19.9",
 		"@danypops/vehicle-client": "^0.10.3",
 		"@danypops/vehicle-core": "^0.17.1",
-		"@danypops/lector": "^0.19.3",
-		"malevich-tui-components": "^0.25.0",
+		"malevich-tui-components": "^0.32.1",
 		"picomatch": "^4.0.5"
 	},
 	"devDependencies": {