@gavin-hu/my-pi-agent 0.14.0 → 0.15.0

package/extensions/check/tools.ts

@@ -0,0 +1,173 @@
+/**
+ * The `run_check` tool.
+ *
+ * It returns a normal result for a failing check (the command ran and the model
+ * should fix it), and an error result only when the check could not run at all.
+ * The structured content is the machine-readable mirror of the text; the tail is
+ * extra detail for the transcript and is deliberately not in that contract.
+ *
+ * A run can take minutes and can print nothing for long stretches, so `execute`
+ * publishes one partial result as soon as the runtime starts. The renderer turns
+ * that into a running line and repaints its elapsed time once a second instead
+ * of waiting for the first chunk.
+ */
+
+import type { ExtensionAPI, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import { sanitizeLine } from "../../lib/format.ts";
+import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
+import {
+	elapsedSuffix,
+	errorLine,
+	rejectionLine,
+	reuseCallText,
+	syncElapsedTimer,
+	toolCallTitle,
+} from "../../lib/tui/tool.ts";
+import { paint } from "../../lib/tui/tokens.ts";
+import { formatCheckReport } from "./format.ts";
+import { CheckResultBlock } from "./render.ts";
+import { checkErrorResult, type CheckRuntime } from "./runtime.ts";
+import type { ActiveCheck, CheckResult, RunCheckDetails } from "./types.ts";
+
+/** The tool's registered name, shared with the naming guard. */
+export const TOOL_NAME = "run_check";
+
+const TargetSchema = Type.Union(
+	[Type.Literal("test"), Type.Literal("lint"), Type.Literal("typecheck"), Type.Literal("all")],
+	{ description: "Which detected command to run; defaults to all." },
+);
+
+const FailureSchema = Type.Object({
+	path: Type.Optional(Type.String()),
+	line: Type.Optional(Type.Integer()),
+	column: Type.Optional(Type.Integer()),
+	test: Type.Optional(Type.String()),
+	message: Type.String(),
+	command: Type.String(),
+});
+
+export const RunCheckParams = Type.Object({
+	target: Type.Optional(TargetSchema),
+});
+
+export type RunCheckArgs = Static<typeof RunCheckParams>;
+
+export const RunCheckOutput = Type.Object({
+	target: TargetSchema,
+	status: Type.Union([
+		Type.Literal("passed"),
+		Type.Literal("failed"),
+		Type.Literal("timeout"),
+		Type.Literal("cancelled"),
+		Type.Literal("error"),
+	]),
+	commands: Type.Array(Type.String()),
+	exitCode: Type.Union([Type.Integer(), Type.Null()]),
+	durationMs: Type.Integer(),
+	truncated: Type.Boolean(),
+	failures: Type.Array(FailureSchema),
+});
+
+export type RunCheckStructured = Static<typeof RunCheckOutput>;
+
+/** One settled run as Pi stores it: model text, transcript details, structured mirror. */
+function resultPayload(result: CheckResult) {
+	const details: RunCheckDetails = { ...result };
+	const structured: RunCheckStructured = {
+		target: result.target,
+		status: result.status,
+		commands: result.commands,
+		exitCode: result.exitCode,
+		durationMs: result.durationMs,
+		truncated: result.truncated,
+		failures: result.failures,
+	};
+	return {
+		content: [{ type: "text" as const, text: formatCheckReport(result) }],
+		details,
+		structuredContent: structured,
+		isError: result.status === "error",
+	};
+}
+
+/** The partial result's details: no failures yet, and the commands now running. */
+function runningDetails(active: ActiveCheck): RunCheckDetails {
+	return {
+		target: active.target,
+		status: "running",
+		commands: [...active.commands],
+		exitCode: null,
+		durationMs: active.elapsedMs(),
+		truncated: false,
+		failures: [],
+	};
+}
+
+export function registerCheckTool(pi: ExtensionAPI, runtime: CheckRuntime): void {
+	pi.registerTool({
+		name: TOOL_NAME,
+		label: "Run checks",
+		description:
+			"Run the project's detected test, lint, or typecheck command (or check.command) in a supervised " +
+			"process and return structured failures. The command is a shell command from the project config or " +
+			"manifest, with a timeout and a bounded log; it can write to the project just like a shell command.",
+		promptSnippet: "Run the project's checks and return structured failures.",
+		promptGuidelines: [
+			"Use run_check before claiming a change is complete.",
+			"Prefer run_check over an ad-hoc test command so failures come back with file and line locations.",
+			"Do not start a check while another check is running.",
+		],
+		parameters: RunCheckParams,
+		outputSchema: RunCheckOutput,
+		executionMode: "sequential",
+		annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+
+		async execute(_toolCallId, params, _signal, onUpdate, ctx: ExtensionToolContext) {
+			const target = params.target ?? "all";
+			let active: ActiveCheck;
+			try {
+				active = runtime.start(target, ctx);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return resultPayload(checkErrorResult(target, message));
+			}
+			onUpdate?.({ content: [], details: runningDetails(active) });
+			return resultPayload(await active.promise);
+		},
+
+		renderCall(args, theme, context) {
+			const subject = context.argsComplete ? (args.target ?? "all") : "…";
+			const text = reuseCallText(context.lastComponent, "", "middle");
+			text.setText(toolCallTitle(theme, `${TOOL_NAME} `) + paint(theme, "meta", sanitizeLine(subject)));
+			return text;
+		},
+
+		renderResult(result, options, theme, context) {
+			const details = toolDetails<RunCheckDetails>(result.details);
+			const startedAt = syncElapsedTimer(options.isPartial, context);
+			if (!details) {
+				const text = reuseText(context.lastComponent);
+				text.setText(rejectionLine(theme, result, options.expanded));
+				return text;
+			}
+			if (details.status === "running") {
+				const text = reuseText(context.lastComponent);
+				const commands = details.commands.length > 0 ? sanitizeLine(details.commands.join(", ")) : "checks";
+				const elapsed = startedAt === undefined ? "" : elapsedSuffix(theme, Date.now() - startedAt);
+				text.setText(paint(theme, "info", `Running ${commands}…`) + elapsed);
+				return text;
+			}
+			if (details.status === "error") {
+				const text = reuseText(context.lastComponent);
+				text.setText(errorLine(theme, details.error ?? "the check could not run"));
+				return text;
+			}
+			const input = { details, expanded: options.expanded };
+			const view =
+				context.lastComponent instanceof CheckResultBlock ? context.lastComponent : new CheckResultBlock(input, theme);
+			view.setInput(input, theme);
+			return view;
+		},
+	});
+}

package/extensions/check/tui.ts

@@ -0,0 +1,195 @@
+/**
+ * The two check screens: a live run tail and a navigable failure list.
+ *
+ * `CheckRunComponent` owns only a `LinePane` over the runtime's live lines;
+ * `CheckResultComponent` is a `DockListScreen`, so the frame, the id-anchored
+ * cursor, the navigation keys, the range row, and the detail pane come from the
+ * shared base and nothing here draws chrome. Git reads, parsing, and process
+ * lifecycle stay in `runtime.ts`, so both components can be tested without a
+ * process.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
+import { formatDuration, sanitizeLine } from "../../lib/format.ts";
+import { dockListFrame, screenHint, type ScreenHint, type ViewportRowsSource } from "../../lib/tui/chrome.ts";
+import { clip } from "../../lib/tui/columns.ts";
+import { fitRows, formatRange, isCloseKey, wheelDelta } from "../../lib/tui/cursor.ts";
+import { DockListScreen, type DetailContents } from "../../lib/tui/dock-screen.ts";
+import { SEPARATORS } from "../../lib/tui/glyphs.ts";
+import { LinePane } from "../../lib/tui/line-pane.ts";
+import { emptyState, listRow } from "../../lib/tui/rows.ts";
+import { titleRule } from "../../lib/tui/rules.ts";
+import { paint } from "../../lib/tui/tokens.ts";
+import { formatFailureDetail, formatFailureLocation, formatResultSummary } from "./format.ts";
+import { readSourceExcerpt } from "./source.ts";
+import type { CheckResult, Failure } from "./types.ts";
+
+const RUN_DEFAULT_ROWS = 20;
+const RUN_CHROME_ROWS = 5;
+
+export interface CheckRunOptions {
+	command: string;
+	lines: () => readonly string[];
+	elapsedMs: () => number;
+	theme: Theme;
+	onCancel: () => void;
+	requestRender: () => void;
+	viewportRows?: ViewportRowsSource;
+}
+
+/** The live run screen: a tail, a status summary, and a cancel key. */
+export class CheckRunComponent implements Component {
+	private readonly pane = new LinePane();
+
+	constructor(private readonly options: CheckRunOptions) {
+		this.pane.open("check", { title: options.command, lines: [] });
+	}
+
+	handleInput(data: string): void {
+		if (isCloseKey(data)) {
+			this.options.onCancel();
+			return;
+		}
+		if (this.pane.handleKey(data)) this.options.requestRender();
+	}
+
+	handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+		const delta = wheelDelta(event);
+		if (delta === undefined) return undefined;
+		this.pane.setScroll(this.pane.scroll + delta * 3);
+		this.options.requestRender();
+		return { handled: true };
+	}
+
+	dispose(): void {}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const w = Math.max(1, width);
+		const lines = [...this.options.lines()];
+		this.pane.update({ lines });
+		this.pane.visible = fitRows(this.options.viewportRows, lines.length, RUN_CHROME_ROWS, RUN_DEFAULT_ROWS);
+		this.pane.fit(this.pane.visible);
+		const { start, end } = this.pane.window();
+		const body = lines.slice(start, end).map((line) => {
+			const role = line.startsWith("$ ") ? "accent" : "label";
+			return clip(paint(this.theme, role, line), w);
+		});
+		if (body.length === 0) body.push(...emptyState(this.theme, w, { label: "Starting…" }));
+		return dockListFrame({
+			header: titleRule(this.theme, w, "Check"),
+			summary: clip(
+				`  ${paint(this.theme, "meta", `running${SEPARATORS.item}${sanitizeLine(this.options.command)}${SEPARATORS.item}${formatDuration(this.options.elapsedMs())}`)}`,
+				w,
+			),
+			body,
+			range:
+				start > 0 || end < lines.length
+					? formatRange(this.theme, w, { start, end, total: lines.length, label: "line" })
+					: undefined,
+			hint: screenHint(this.theme, w, ["Esc cancel", "j/k scroll", "g/G top/end"]),
+		});
+	}
+
+	private get theme(): Theme {
+		return this.options.theme;
+	}
+}
+
+export interface CheckResultOptions {
+	result: CheckResult;
+	/** Project root used to read a failure's source excerpt. */
+	cwd: string;
+	theme: Theme;
+	onRerun: () => void;
+	onClose: () => void;
+	requestRender: () => void;
+	viewportRows?: ViewportRowsSource;
+}
+
+/**
+ * The failure list, with a per-failure detail pane.
+ *
+ * A failure carries no id of its own, but a finished run's `failures` array is
+ * fixed for the life of this screen, so the index is a stable cursor key. It is
+ * mapped once in the constructor: an `indexOf` per row per frame would be
+ * quadratic on the 200-failure cap.
+ */
+export class CheckResultComponent extends DockListScreen<Failure> {
+	private readonly ids = new Map<Failure, string>();
+
+	constructor(private readonly view: CheckResultOptions) {
+		super({
+			theme: view.theme,
+			title: "Check",
+			detailTitle: "Failure",
+			emptyList: "No failures parsed.",
+			emptyDetail: "Nothing to show.",
+			requestRender: view.requestRender,
+			onClose: view.onClose,
+			viewportRowsSource: view.viewportRows,
+		});
+		view.result.failures.forEach((failure, index) => this.ids.set(failure, String(index)));
+	}
+
+	protected rows(): readonly Failure[] {
+		return this.view.result.failures;
+	}
+
+	protected idOf(failure: Failure): string {
+		return this.ids.get(failure) ?? "0";
+	}
+
+	protected rowLine(failure: Failure, width: number, selected: boolean): string {
+		return listRow(this.theme, width, {
+			selected,
+			glyph: "✗",
+			glyphRole: "bad",
+			label: formatFailureLocation(failure),
+			labelRole: selected ? "accent" : "label",
+			trailing: "",
+		});
+	}
+
+	protected detailBlock(failure: Failure): string[] {
+		return [sanitizeLine(failure.message)];
+	}
+
+	protected summaryCells(): string[] {
+		return [paint(this.theme, "meta", formatResultSummary(this.view.result))];
+	}
+
+	protected listHints(rows: readonly Failure[]): ScreenHint[] {
+		// An empty list has nothing to open, so it offers only the two ways out.
+		if (rows.length === 0) return ["Esc close", { text: "r rerun", color: "accent" }];
+		return [
+			"Esc close",
+			{ text: "Enter detail", color: "accent" },
+			{ text: "r rerun", color: "warning" },
+			"↑/↓ select",
+		];
+	}
+
+	protected detailHints(): ScreenHint[] {
+		return ["Esc back", "j/k scroll", "g/G top/end"];
+	}
+
+	protected detailFor(failure: Failure): DetailContents {
+		// The excerpt is read once, when the pane opens, as it always has been.
+		const source = failure.path ? readSourceExcerpt(this.view.cwd, failure) : undefined;
+		return {
+			title: formatFailureLocation(failure),
+			// The base clips a detail line but never paints it, so the body keeps the
+			// role this screen gave it.
+			lines: formatFailureDetail(failure, this.view.result.tail, source).map((line) =>
+				paint(this.theme, "label", line),
+			),
+		};
+	}
+
+	protected handleVerb(key: string): void {
+		if (key === "r") this.view.onRerun();
+	}
+}

package/extensions/check/types.ts

@@ -0,0 +1,99 @@
+/**
+ * Shared types for the check extension.
+ *
+ * The extension is deliberately language-neutral: a command is a shell string,
+ * a failure is a location plus a message, and nothing here names an ecosystem.
+ * Detection and parsing are the only places that know about manifests or test
+ * runner output.
+ */
+
+/** The targets `/check` and `run_check` accept. */
+export type CheckTarget = "test" | "lint" | "typecheck" | "all";
+
+/** A command the detector or the config selected. */
+export interface CommandSpec {
+	/** Shell command, run in the project root. */
+	command: string;
+	/** The same text for display and model-facing results. */
+	label: string;
+}
+
+/** The commands detected for one project, keyed by target. */
+export type DetectedCommands = Partial<Record<Exclude<CheckTarget, "all">, CommandSpec>> & {
+	all?: CommandSpec;
+};
+
+/** One parsed failure, independent of the runner that produced it. */
+export interface Failure {
+	/** Repository-relative or absolute path, when the runner printed one. */
+	path?: string;
+	line?: number;
+	column?: number;
+	/** Test name, when the runner prints a name without a location. */
+	test?: string;
+	/** The human-readable reason, already collapsed to one line. */
+	message: string;
+	/** The command that produced this failure. */
+	command: string;
+}
+
+/** The terminal state of a check run. */
+export type CheckStatus = "passed" | "failed" | "timeout" | "cancelled" | "error";
+
+/** What one command did. */
+export interface CommandRun {
+	command: string;
+	exitCode: number | null;
+	signal: string | null;
+	timedOut: boolean;
+	cancelled: boolean;
+	output: string;
+	truncated: boolean;
+	durationMs: number;
+	error?: string;
+}
+
+/** The aggregate result of one `/check` or `run_check` call. */
+export interface CheckResult {
+	target: CheckTarget;
+	status: CheckStatus;
+	commands: string[];
+	/** Last non-null exit code, or null for timeout/cancel/spawn failure. */
+	exitCode: number | null;
+	durationMs: number;
+	truncated: boolean;
+	failures: Failure[];
+	/** Sanitized tail of the bounded output, for a detail view or fallback. */
+	tail: string;
+	error?: string;
+}
+
+/** The model-facing details and structuredContent mirror. */
+export interface RunCheckDetails {
+	target: CheckTarget;
+	/** A terminal state, or "running" for the partial result the host replaces. */
+	status: CheckStatus | "running";
+	commands: string[];
+	exitCode: number | null;
+	durationMs: number;
+	truncated: boolean;
+	failures: Failure[];
+	/** Extra detail for the transcript renderer; not in structuredContent. */
+	tail?: string;
+	/** Set when the run could not start or a command failed to spawn. */
+	error?: string;
+}
+
+/** A run that can be observed while it is still active. */
+export interface ActiveCheck {
+	target: CheckTarget;
+	commands: string[];
+	/** Sanitized lines for the live screen, oldest first. */
+	lines(): readonly string[];
+	/** Milliseconds since the run started. */
+	elapsedMs(): number;
+	/** Resolves once the run settles; never rejects. */
+	promise: Promise<CheckResult>;
+	/** Kill the active process tree and settle as cancelled. */
+	cancel(): void;
+}

package/extensions/document/README.md

@@ -281,7 +281,7 @@ repeating it would be pure duplication.
 | `paging.ts` | `formatDoc`: code-point slicing and header/truncation formatting; `summarizeDoc`: the theme-free transcript summary. |
 | `extract/file.ts` | `DocFile` / `DocExtractor`, `readDocBytes` (abort-aware read), `normalizeBodyText`. |
 | `extract/vendor.d.ts` | Ambient types for `word-extractor` and `rtf-parser` (no bundled declarations). |
-| `extract/pdf.ts` | `unpdf` extractor and `pdfTextFromResult`. |
+| `extract/pdf.ts` | Adapter over the shared `lib/pdf.ts` seam, plus the PDF body normalization. |
 | `extract/docx.ts` | `mammoth` extractor. |
 | `extract/doc.ts` | `word-extractor` extractor for legacy `.doc`. |
 | `extract/odt.ts` | `fflate` + `fast-xml-parser` extractor and `odtXmlToText`. |

package/extensions/document/extract/pdf.ts

@@ -1,25 +1,17 @@
 /**
- * PDF text extraction via the `unpdf` package.
+ * PDF text extraction, over the shared `unpdf` seam.
  *
- * `unpdf` bundles a server-friendly build of PDF.js. `extractText` with
- * `mergePages: true` returns every page's reading-order text joined with a blank
- * line, so a page break reads as a paragraph break. No OCR: a scanned or
- * image-only PDF yields little or no text.
+ * `lib/pdf.ts` owns the lazy import, the module-shape handling, and the
+ * guidance when the package is absent; this adapter reads the file and applies
+ * the body normalization `read_doc` returns for a PDF.
  */
 
+import { extractPdfText } from "../../../lib/pdf.ts";
 import { readDocBytes, type DocExtractor } from "./file.ts";
 
-/** Pull the merged text out of `unpdf`'s `{ totalPages, text }` result. Pure. */
-export function pdfTextFromResult(result: unknown): string {
-	if (typeof result === "string") return result;
-	const text = (result as { text?: unknown } | undefined)?.text;
-	return typeof text === "string" ? text : "";
-}
-
 /** Extract text from every page of a PDF. */
-export const extractPdfText: DocExtractor = async (file) => {
+export const extractPdfDocument: DocExtractor = async (file) => {
 	const bytes = await readDocBytes(file);
-	const module = await import("unpdf");
-	const result: unknown = await module.extractText(bytes, { mergePages: true });
-	return pdfTextFromResult(result).replace(/\r\n?/g, "\n").replace(/\n+$/, "");
+	const text = await extractPdfText(bytes);
+	return text.replace(/\r\n?/g, "\n").replace(/\n+$/, "");
 };

package/extensions/document/formats.ts

@@ -12,7 +12,7 @@ import type { DocExtractor } from "./extract/file.ts";
 import { extractDocText } from "./extract/doc.ts";
 import { extractDocxText } from "./extract/docx.ts";
 import { extractOdtText } from "./extract/odt.ts";
-import { extractPdfText } from "./extract/pdf.ts";
+import { extractPdfDocument } from "./extract/pdf.ts";
 import { extractRtfText } from "./extract/rtf.ts";
 import { extractXlsxText } from "./extract/xlsx.ts";
 
@@ -30,7 +30,7 @@ export interface DocumentFormat {
 }
 
 export const FORMATS = [
-	{ id: "pdf", label: "PDF", extensions: [".pdf"], defaultEnabled: true, extract: extractPdfText },
+	{ id: "pdf", label: "PDF", extensions: [".pdf"], defaultEnabled: true, extract: extractPdfDocument },
 	{ id: "docx", label: "DOCX", extensions: [".docx"], defaultEnabled: true, extract: extractDocxText },
 	{ id: "doc", label: "DOC", extensions: [".doc"], defaultEnabled: true, extract: extractDocText },
 	{ id: "odt", label: "ODT", extensions: [".odt"], defaultEnabled: true, extract: extractOdtText },