@danypops/pi-packed 0.27.13 → 0.28.0

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
+ * and pi-pipes' 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/doctor-overlay.ts

@@ -0,0 +1,156 @@
+/**
+ * Persistent above-editor widget for real doctor.run issues -- mirrors pi-papyrus's own
+ * TaskOverlay/NoteOverlay and pi-pipes' own JobsOverlay: factory-form ctx.ui.setWidget
+ * registration, requestRender on refresh, hides the widget entirely (setWidget(key, undefined))
+ * rather than an empty box once the report is clean.
+ *
+ * doctor.run lives exclusively on the daemon's Vehicle protocol surface (/vehicle/*), not the
+ * legacy PackedExtensionClient RPC surface packed.ts's Natives wraps (see ExtensionOperationName
+ * in protocol.ts -- "doctor.run" is not one of them) -- this overlay builds its own reconnecting
+ * VehicleClient the same way vehicle-tools.ts's registerPackedVehicle does.
+ *
+ * Polled at a conservative interval (see DOCTOR_WIDGET_POLL_INTERVAL_MS): unlike Tasks/Notes/Jobs,
+ * doctor.run is a real daemon-wide scan (extension smoke tests, npm-tree walks, systemd
+ * shell-outs), not a cheap row read.
+ */
+import type { DoctorReport } from "@danypops/pi-packed/doctor-format";
+import { createReconnectingVehicleClient } from "@danypops/vehicle-client/daemon-client";
+import { RemoteVehicleClient } from "@danypops/vehicle-client/http";
+import type { VehicleClient } from "@danypops/vehicle-core";
+import type { ExtensionUIContext, Theme } from "@earendil-works/pi-coding-agent";
+import { AutoRotatingWindow } from "malevich-tui-components";
+import { BoundedPoll } from "./bounded-poll.js";
+import {
+	buildDoctorWidgetProjection,
+	type DoctorWidgetProjection,
+	PACKED_DOCTOR_WIDGET_VISIBLE_ROWS,
+	renderDoctorWidgetLines,
+} from "./doctor-widget.js";
+import { currentVehicleClientTarget } from "./vehicle-target.js";
+
+const WIDGET_KEY = "pi-packed-doctor";
+
+/** doctor.run is a real daemon-wide scan, not a cheap row read -- a much longer interval than
+ * Tasks/Notes/Jobs' own 15-20s cadence. */
+export const DOCTOR_WIDGET_POLL_INTERVAL_MS = 90_000;
+
+/** How often the widget's own auto-rotating overflow page advances. */
+export const DOCTOR_WIDGET_ROTATION_INTERVAL_MS = 6_000;
+
+const EMPTY_PROJECTION: DoctorWidgetProjection = { issues: [], total: 0 };
+
+function defaultClient(): VehicleClient {
+	// connectRetry:true (vehicle-client's own bounded background retry budget) covers a daemon
+	// that crashed and is mid systemd-restart -- matches registerPackedVehicle's own construction.
+	return createReconnectingVehicleClient(
+		async () => {
+			const resolved = currentVehicleClientTarget();
+			if (!resolved) throw new Error("Packed daemon is not running");
+			return new RemoteVehicleClient({ baseUrl: resolved.baseUrl, token: resolved.token });
+		},
+		{ connectRetry: true },
+	);
+}
+
+export class DoctorOverlay {
+	private uiCtx: ExtensionUIContext | undefined;
+	private registered = false;
+	// biome-ignore lint/suspicious/noExplicitAny: same TUI-handle shape every other overlay in this ecosystem keeps untyped (requestRender is all that's used).
+	private tui: any | undefined;
+	private projection: DoctorWidgetProjection = 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: PACKED_DOCTOR_WIDGET_VISIBLE_ROWS,
+		intervalMs: DOCTOR_WIDGET_ROTATION_INTERVAL_MS,
+	});
+	private readonly client: VehicleClient;
+
+	constructor(client: VehicleClient = defaultClient()) {
+		this.client = client;
+	}
+
+	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 report = await this.client.invoke<DoctorReport>("doctor.run", 1, {}, { permissions: ["packed:read"] });
+			this.projection = buildDoctorWidgetProjection(report);
+		} 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,
+				// biome-ignore lint/suspicious/noExplicitAny: tui is only ever used for requestRender(), matching every other overlay in this ecosystem.
+				(tui: any, theme: Theme) => {
+					this.tui = tui;
+					return {
+						render: (width: number) => renderDoctorWidgetLines(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(DOCTOR_WIDGET_ROTATION_INTERVAL_MS, () => this.tui?.requestRender?.());
+		} else {
+			this.tui?.requestRender?.();
+		}
+	}
+
+	startPolling(intervalMs: number = DOCTOR_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/doctor-render.ts

@@ -1,14 +1,30 @@
 /**
- * doctor.run's own curated presenter -- its DoctorReport output shape (five array fields, several
- * with nested arrays/objects per row: duplicateDependencies' own locations array, extensions'
- * own registrations object) defeats every heuristic in vehicle-render's generic shape-probing
- * chain, so without this it fell all the way through to a raw JSON.stringify dump -- a real, live
- * incident, not a hypothetical. Reuses formatDoctorReport, the exact same human-readable text the
- * CLI's own `packed doctor` (non-JSON) path already renders, so the tool and the CLI never drift
- * into two different descriptions of the same report.
+ * doctor.run's own curated renderResult -- its DoctorReport output shape (five array fields,
+ * several with nested arrays/objects per row: duplicateDependencies' own locations array,
+ * extensions' own registrations object) defeats every heuristic in vehicle-render's generic
+ * shape-probing chain, so without this it fell all the way through to a raw JSON.stringify dump
+ * -- a real, live incident, not a hypothetical.
+ *
+ * A FULL renderResult override via registerVehicleTools' `renderers` option, deliberately NOT
+ * `renderPresenters`: without any presentations/renderers override at all, EVERY real doctor.run
+ * invocation gets a generic vehicle.tool-details/v1 "json"-view presentation projected and
+ * PERSISTED at invocation time (createTool's own default presentationProjector), and that
+ * projected presentation always wins ahead of a renderPresenters entry -- renderPresenters only
+ * ever customizes the output-to-Component step for the non-projected branch, never overriding an
+ * already-successful projection (see vehicle-render/result-rendering.ts's own renderVehicleResult:
+ * `if (projected) return renderProjectedPresentation(...)` runs before presenters are ever
+ * consulted). A real, live incident: wiring this as renderPresenters first left the raw JSON view
+ * rendering completely unchanged after release. `renderers.renderResult` sets
+ * presentationProjector to undefined for this one operation (see tool-creation.ts's own
+ * presentationProjector selection), so this function is now responsible for the operation's every
+ * result shape -- it delegates to the shared generic renderer (renderVehicleResult) for anything
+ * that isn't a real, complete DoctorReport (a partial/error state, a historical session row, or a
+ * future field addition), rather than re-implementing that handling here.
  */
 import { type DoctorReport, formatDoctorReport } from "@danypops/pi-packed/doctor-format";
-import type { VehiclePresenter } from "@danypops/vehicle-client-pi/vehicle-render";
+import { renderVehicleResult } from "@danypops/vehicle-client-pi/vehicle-render";
+import type { VehicleOperationDescriptor } from "@danypops/vehicle-core";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { asciiTextMeasure, CollapsibleText } from "malevich-tui-components";
 
 const DOCTOR_REPORT_COLLAPSED_LINES = 12;
@@ -19,14 +35,22 @@ function isDoctorReport(value: unknown): value is DoctorReport {
 	return typeof candidate.ok === "boolean" && Array.isArray(candidate.conflicts) && Array.isArray(candidate.extensions);
 }
 
-export const renderDoctorRunResult: VehiclePresenter = (output, options, theme) => {
-	if (!isDoctorReport(output)) return undefined;
-	const collapsible = new CollapsibleText({
-		text: theme.fg("text", formatDoctorReport(output, false)),
-		collapsedLines: DOCTOR_REPORT_COLLAPSED_LINES,
-		headerStyle: (s) => theme.fg("dim", s),
-		measure: asciiTextMeasure,
-	});
-	if (options.expanded) collapsible.expand();
-	return collapsible;
-};
+export function createDoctorRunRenderResult(descriptor: VehicleOperationDescriptor): NonNullable<ToolDefinition["renderResult"]> {
+	return (result, options, theme, context) => {
+		if (!context.isError && !options.isPartial) {
+			const details = result.details as { output?: unknown } | undefined;
+			const output = details && Object.hasOwn(details, "output") ? details.output : undefined;
+			if (isDoctorReport(output)) {
+				const collapsible = new CollapsibleText({
+					text: theme.fg("text", formatDoctorReport(output, false)),
+					collapsedLines: DOCTOR_REPORT_COLLAPSED_LINES,
+					headerStyle: (s) => theme.fg("dim", s),
+					measure: asciiTextMeasure,
+				});
+				if (options.expanded) collapsible.expand();
+				return collapsible;
+			}
+		}
+		return renderVehicleResult(descriptor, result, options, theme, context);
+	};
+}

package/extension/src/doctor-widget.ts

@@ -0,0 +1,86 @@
+/**
+ * Pure projection/render pair for the Doctor status widget -- mirrors pi-papyrus's own
+ * task-widget.ts / pi-pipes' own jobs-widget.ts split: a DoctorReport in, a bounded intermediate
+ * shape out, no I/O, no TUI, fully unit-testable without a real daemon or terminal. See
+ * doctor-overlay.ts for the stateful ctx.ui.setWidget-registered class that drives these from a
+ * live doctor.run poll.
+ */
+import type { DoctorReport } from "@danypops/pi-packed/doctor-format";
+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 service/src/daemon/service.ts's `new VehicleRegistry({ name: "packed" })`) -- vehicleWidgetTitle capitalizes it for display. */
+const VEHICLE_NAME = "packed";
+
+/** Visible issue rows per page before the auto-rotating overflow hint pages to the next. */
+export const PACKED_DOCTOR_WIDGET_VISIBLE_ROWS = 5;
+
+export interface DoctorWidgetIssue {
+	label: string;
+}
+
+export interface DoctorWidgetProjection {
+	issues: DoctorWidgetIssue[];
+	total: number;
+}
+
+/**
+ * Mirrors doctor.run's own `ok` computation (conflicts + non-ok extensions + serviceUnits), plus
+ * stale module-cache entries (directly actionable: "restart the daemon"). Deliberately excludes
+ * duplicateDependencies -- doctor.run's own `ok` boolean excludes them too (see doctor-format.ts's
+ * own doc comment on why), and they're common enough in this ecosystem's own staggered version
+ * rollout to be low-signal for a persistent glance-at-a-widget summary.
+ */
+export function buildDoctorWidgetProjection(report: DoctorReport): DoctorWidgetProjection {
+	const issues: DoctorWidgetIssue[] = [];
+	for (const conflict of report.conflicts) {
+		issues.push({ label: `${conflict.kind} "${conflict.name}" claimed by ${conflict.claimants.length} extensions` });
+	}
+	for (const extension of report.extensions) {
+		if (extension.status === "ok") continue;
+		issues.push({ label: `${extension.status} ${extension.name}${extension.message ? `: ${extension.message}` : ""}` });
+	}
+	for (const unit of report.serviceUnits) {
+		issues.push({ label: `${unit.package} (${unit.unitName}): ${unit.message}` });
+	}
+	for (const module of report.moduleFreshness ?? []) {
+		if (!module.stale) continue;
+		issues.push({ label: `${module.name} loaded ${module.loadedVersion ?? "?"}, disk has ${module.currentVersion ?? "?"}` });
+	}
+	return { issues, total: issues.length };
+}
+
+/** "Packed · Doctor · <N> issue(s)", plus a "page/total ⟳" suffix once genuinely paging. */
+function doctorCardLabel(projection: DoctorWidgetProjection, rotation?: AutoRotatingWindow): string {
+	const base = vehicleWidgetTitle(VEHICLE_NAME, "Doctor", `${projection.total} issue${projection.total === 1 ? "" : "s"}`);
+	return rotation?.isPaging ? `${base} · ${rotation.pageIndex + 1}/${rotation.pageCount} ⟳` : base;
+}
+
+/** Renders the widget as a single bordered card -- `[]` (hide the whole widget) when there are no
+ * real issues, matching every other overlay's own "hide when nothing to show" convention. */
+export function renderDoctorWidgetLines(
+	theme: { fg(color: string, text: string): string },
+	projection: DoctorWidgetProjection,
+	width: number,
+	rotation?: AutoRotatingWindow,
+): string[] {
+	if (projection.total === 0) return [];
+	rotation?.setTotalRows(projection.issues.length);
+	const { start, end } = rotation?.currentPageBounds() ?? { start: 0, end: projection.issues.length };
+	const visibleIssues = projection.issues.slice(start, end);
+
+	return renderCardRow(
+		[
+			{
+				label: doctorCardLabel(projection, rotation),
+				render: (innerWidth: number) =>
+					visibleIssues.map((issue) => truncateToWidth(`${theme.fg("warning", "!")} ${issue.label}`, innerWidth, "…")),
+			},
+		],
+		width,
+		{ measure, frameStyle: (s) => theme.fg("borderMuted", s) },
+	);
+}

package/extension/src/index.ts

@@ -9,6 +9,7 @@
  * Install: pi install git:github.com/DanyPops/pi-packed
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { DoctorOverlay } from "./doctor-overlay.js";
 import { formatUpdateNotice } from "./model.js";
 import { createNatives } from "./packed.js";
 import { registerProfiles } from "./profile.js";
@@ -42,6 +43,7 @@ export default async function (pi: ExtensionAPI) {
 	// the identical pi-papyrus/pi-tickets bug). session_start fires only after that initialization
 	// completes, and Pi awaits every session_start handler before the model's first turn, so
 	// registering here is both safe and still visible on turn one.
+	let doctorOverlay: DoctorOverlay | undefined;
 	pi.on("session_start", async (_event, ctx) => {
 		await registerPackedVehicle(pi);
 		if (!ctx.hasUI) return;
@@ -53,5 +55,12 @@ export default async function (pi: ExtensionAPI) {
 		} catch {
 			// mirror missing or unreadable — stay silent, never block startup.
 		}
+		doctorOverlay ??= new DoctorOverlay();
+		doctorOverlay.setUI(ctx.ui);
+		await doctorOverlay.refresh();
+		doctorOverlay.startPolling();
+	});
+	pi.on("session_shutdown", async () => {
+		doctorOverlay?.dispose();
 	});
 }

package/extension/src/vehicle-tools.ts

@@ -35,7 +35,7 @@ import { RemoteVehicleClient } from "@danypops/vehicle-client/http";
 import { registerVehicleTools } from "@danypops/vehicle-client-pi";
 import type { VehicleClient, VehicleManifest } from "@danypops/vehicle-core";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { renderDoctorRunResult } from "./doctor-render.js";
+import { createDoctorRunRenderResult } from "./doctor-render.js";
 import { currentVehicleClientTarget } from "./vehicle-target.js";
 
 /** Already covered by their own dedicated, approval-aware tools in tools.ts -- see this file's own doc comment. */
@@ -98,7 +98,7 @@ export async function registerPackedVehicle(pi: ExtensionAPI): Promise<void> {
 			// ensureVehicleShellHandle) -- no ownVehicleName/broker option needed here anymore; every
 			// vehicle in the process (including packed's own) is discovered and namespaced uniformly.
 			shell: { coreOperations: CORE_OPERATIONS },
-			renderPresenters: { "doctor.run": renderDoctorRunResult },
+			renderers: (descriptor) => (descriptor.name === "doctor.run" ? { renderResult: createDoctorRunRenderResult(descriptor) } : undefined),
 			renderCoverage: { operations: REVIEWED_OPERATIONS },
 		});
 	} catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-packed",
-  "version": "0.27.13",
+  "version": "0.28.0",
   "description": "Pi package lifecycle, validation, daemon, tools, profiles, and TUI",
   "type": "module",
   "bin": {
@@ -34,7 +34,7 @@
     "@danypops/vehicle-core": "^0.17.1",
     "@danypops/vehicle-server": "^0.25.2",
     "jiti": "^2.7.0",
-    "malevich-tui-components": "^0.21.1",
+    "malevich-tui-components": "^0.32.1",
     "publint": "0.3.22",
     "semver": "^7.8.5"
   },