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

package/extensions/check/render.ts

@@ -0,0 +1,185 @@
+/**
+ * The `run_check` transcript block.
+ *
+ * The `/check` screens live in `tui.ts` and the model report in `format.ts`;
+ * this is the one result a session keeps inline. It is a capped view of the same
+ * `details`: a status line, the first few failures, and the bounded tail when
+ * nothing parsed. The transcript never prints the model report, and `/check`
+ * remains the full navigable list.
+ *
+ * Every field comes from command output, a manifest script name, or project
+ * config, so each is sanitized before the theme is applied.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import { sanitizeLine } from "../../lib/format.ts";
+import { clip } from "../../lib/tui/columns.ts";
+import { expandHint, GLYPHS, SEPARATORS } from "../../lib/tui/glyphs.ts";
+import { listRow } from "../../lib/tui/rows.ts";
+import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
+import { earlierHint } from "../../lib/tui/tool.ts";
+import { MODEL_FAILURES, formatFailureLine, formatResultSummary, hasFailureLocation } from "./format.ts";
+import type { Failure, RunCheckDetails } from "./types.ts";
+
+/** Failure rows a collapsed transcript result shows. */
+export const COLLAPSED_ROWS = 5;
+/** Tail lines a collapsed unparsed result shows. */
+export const COLLAPSED_TAIL_ROWS = 5;
+
+/** The design role a check status is drawn in. */
+function statusRole(status: RunCheckDetails["status"]): TuiRole {
+	switch (status) {
+		case "passed":
+			return "ok";
+		case "failed":
+		case "error":
+			return "bad";
+		case "timeout":
+			return "warn";
+		case "cancelled":
+			return "meta";
+		case "running":
+			return "info";
+	}
+}
+
+/** Width-1 glyph for a check status, from the shared vocabulary. */
+function statusGlyph(status: RunCheckDetails["status"]): string {
+	switch (status) {
+		case "passed":
+			return GLYPHS.check;
+		case "failed":
+			return GLYPHS.jobsFailure;
+		case "timeout":
+			return GLYPHS.warn;
+		case "cancelled":
+			return GLYPHS.stopped;
+		case "error":
+			return GLYPHS.cross;
+		case "running":
+			return GLYPHS.jobsRunning;
+	}
+}
+
+/**
+ * The summary line: the screen's wording plus the two facts it leaves to a
+ * detail row, the exit code of an unparsed failure and a dropped log prefix.
+ */
+function formatStatusSummary(details: RunCheckDetails): string {
+	const text = formatResultSummary(details);
+	const extras: string[] = [];
+	const parsed = details.failures.some(hasFailureLocation);
+	if (!parsed && (details.status === "failed" || details.status === "timeout") && details.exitCode !== null) {
+		extras.push(`exit ${details.exitCode}`);
+	}
+	if (details.truncated) extras.push("log truncated");
+	return extras.length === 0 ? text : `${text}${SEPARATORS.item}${extras.join(SEPARATORS.item)}`;
+}
+
+/** One parsed failure: its location and reason, plus its command when several ran. */
+function failureRow(failure: Failure, theme: Theme, width: number, showCommand: boolean): string {
+	const command = showCommand ? `${SEPARATORS.item}${sanitizeLine(failure.command)}` : "";
+	return listRow(theme, width, {
+		marker: false,
+		glyph: GLYPHS.jobsFailure,
+		glyphRole: "bad",
+		label: `${formatFailureLine(failure)}${command}`,
+		labelRole: "label",
+	});
+}
+
+/** A command that failed without a parseable location, named by its command. */
+function unparsedRow(failure: Failure, theme: Theme, width: number): string {
+	return listRow(theme, width, {
+		marker: false,
+		glyph: GLYPHS.jobsFailure,
+		glyphRole: "bad",
+		label: `${sanitizeLine(failure.command)}${SEPARATORS.item}${sanitizeLine(failure.message)}`,
+		labelRole: "meta",
+	});
+}
+
+/** `… N more failures`, pointing at the expand key or at `/check`. */
+function moreFailures(theme: Theme, width: number, hidden: number, expandable: boolean): string {
+	const note = paint(theme, "faint", `… ${hidden} more failure${hidden === 1 ? "" : "s"}`);
+	const next = expandable ? expandHint(theme) : paint(theme, "faint", "/check lists all");
+	return clip(`${note} ${next}`, width);
+}
+
+/** The bounded tail, newest lines last, with the number dropped by the collapse. */
+function tailLines(tail: string, theme: Theme, width: number, expanded: boolean): string[] {
+	const all = tail.split("\n").map((line) => sanitizeLine(line).replaceAll("\t", "    "));
+	while (all.length > 0 && all[all.length - 1] === "") all.pop();
+	const shown = expanded ? all : all.slice(Math.max(0, all.length - COLLAPSED_TAIL_ROWS));
+	const lines: string[] = [];
+	if (shown.length < all.length) {
+		lines.push(clip(earlierHint(theme, all.length - shown.length, "lines"), width));
+	}
+	for (const line of shown) lines.push(clip(paint(theme, "label", line), width));
+	return lines;
+}
+
+/** What a result block draws: the run's details and whether the view is expanded. */
+export interface CheckResultInput {
+	details: RunCheckDetails;
+	expanded: boolean;
+}
+
+/**
+ * The transcript result: one status line, then parsed failures up to the cap,
+ * then the bounded tail when nothing parsed. Reused across renders so the
+ * transcript updates it in place.
+ */
+export class CheckResultBlock implements Component {
+	private input: CheckResultInput;
+	private theme: Theme;
+
+	constructor(input: CheckResultInput, theme: Theme) {
+		this.input = input;
+		this.theme = theme;
+	}
+
+	/** Update in place so the transcript can reuse this component across renders. */
+	setInput(input: CheckResultInput, theme: Theme): void {
+		this.input = input;
+		this.theme = theme;
+	}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const w = Math.max(1, width);
+		const theme = this.theme;
+		const { details, expanded } = this.input;
+		const role = statusRole(details.status);
+		const lines = [
+			clip(`${paint(theme, role, statusGlyph(details.status))} ${paint(theme, role, formatStatusSummary(details))}`, w),
+		];
+
+		const parsed = details.failures.filter(hasFailureLocation);
+		const unparsed = details.failures.filter((failure) => !hasFailureLocation(failure));
+		const limit = expanded ? MODEL_FAILURES : COLLAPSED_ROWS;
+		const shown = parsed.slice(0, limit);
+		for (const failure of shown) {
+			lines.push(failureRow(failure, theme, w, details.commands.length > 1));
+		}
+		if (parsed.length > shown.length) {
+			lines.push(moreFailures(theme, w, parsed.length - shown.length, !expanded));
+		}
+		// A command that failed without a location is named after the parsed rows;
+		// when no row parsed at all, the tail is the honest evidence instead.
+		if (parsed.length > 0) {
+			for (const failure of unparsed) lines.push(unparsedRow(failure, theme, w));
+			return lines;
+		}
+
+		const tail = details.tail ?? "";
+		if (details.status === "passed" || details.status === "error" || tail.trim() === "") return lines;
+		lines.push(
+			clip(paint(theme, "meta", details.status === "failed" ? "no parsed failure; last output:" : "last output:"), w),
+		);
+		lines.push(...tailLines(tail, theme, w, expanded));
+		return lines;
+	}
+}

package/extensions/check/runner.ts

@@ -0,0 +1,176 @@
+/**
+ * One-shot process runner for the check extension.
+ *
+ * A check is foreground and bounded: it streams stdout/stderr, keeps only a
+ * tail, and dies with the command. This is deliberately smaller than `job`:
+ * there is no registry, reattachment, stdin pipe, or detached lifetime. The
+ * spawn and tree-kill seams are the shared ones in `lib/spawn.ts`.
+ */
+
+import { defaultKillTree, defaultSpawn, type KillTreeFn, type SpawnedProcess, type SpawnFn } from "../../lib/spawn.ts";
+
+export interface RunOptions {
+	cwd: string;
+	command: string;
+	/** Wall-clock limit; 0 disables it. */
+	timeoutMs: number;
+	/** Bytes kept from the end of stdout+stderr. */
+	maxLogBytes: number;
+	signal?: AbortSignal;
+	/** Called with raw chunks as they arrive, for the live screen. */
+	onOutput?: (chunk: string) => void;
+}
+
+export interface RunOutcome {
+	exitCode: number | null;
+	signal: string | null;
+	timedOut: boolean;
+	cancelled: boolean;
+	/** The retained tail, not necessarily the whole output. */
+	output: string;
+	truncated: boolean;
+	durationMs: number;
+	/** A spawn failure, if the command could not start. */
+	error?: string;
+}
+
+export interface RunnerOptions {
+	spawn?: SpawnFn;
+	killTree?: KillTreeFn;
+	now?: () => number;
+	/** Time between SIGTERM and SIGKILL; tests shorten it. */
+	killGraceMs?: number;
+}
+
+/**
+ * A string buffer that keeps the last `maxBytes` bytes.
+ *
+ * Output is already a string; slicing by characters is close enough at a
+ * megabyte scale, and keeps a multi-byte character whole. `truncated` is set
+ * once anything is dropped.
+ */
+export class BoundedLog {
+	private buffer = "";
+	private truncated = false;
+
+	constructor(private readonly maxBytes: number) {}
+
+	append(chunk: string): void {
+		if (!chunk) return;
+		this.buffer += chunk;
+		if (Buffer.byteLength(this.buffer) <= this.maxBytes) return;
+		this.truncated = true;
+		this.buffer = this.buffer.slice(-this.maxBytes);
+	}
+
+	text(): string {
+		return this.buffer;
+	}
+
+	get wasTruncated(): boolean {
+		return this.truncated;
+	}
+}
+
+/** The checker's env: no color, no pager, no interactive prompts, CI mode. */
+export function checkEnv(base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+	return {
+		...base,
+		CI: "1",
+		NO_COLOR: "1",
+		FORCE_COLOR: "0",
+		TERM: "dumb",
+		GIT_PAGER: "cat",
+		PAGER: "cat",
+	};
+}
+
+/** Build a runner over injected process seams. */
+export function createRunner(options: RunnerOptions = {}): (options: RunOptions) => Promise<RunOutcome> {
+	const spawn = options.spawn ?? defaultSpawn;
+	const killTree = options.killTree ?? defaultKillTree;
+	const now = options.now ?? (() => Date.now());
+	const killGraceMs = options.killGraceMs ?? 2_000;
+
+	return (run) =>
+		new Promise<RunOutcome>((resolve) => {
+			const started = now();
+			const log = new BoundedLog(run.maxLogBytes);
+			let settled = false;
+			let timedOut = false;
+			let cancelled = false;
+			let spawnError: string | undefined;
+			let killTimer: ReturnType<typeof setTimeout> | undefined;
+			let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
+			let child: SpawnedProcess | undefined;
+
+			const settle = (exitCode: number | null, signal: string | null): void => {
+				if (settled) return;
+				settled = true;
+				if (killTimer) clearTimeout(killTimer);
+				if (timeoutTimer) clearTimeout(timeoutTimer);
+				run.signal?.removeEventListener("abort", onAbort);
+				resolve({
+					exitCode,
+					signal,
+					timedOut,
+					cancelled,
+					output: log.text(),
+					truncated: log.wasTruncated,
+					durationMs: Math.max(0, now() - started),
+					...(spawnError ? { error: spawnError } : {}),
+				});
+			};
+
+			const stop = (reason: "timeout" | "abort"): void => {
+				if (settled) return;
+				if (reason === "timeout") timedOut = true;
+				else cancelled = true;
+				const pid = child?.pid;
+				if (!pid) {
+					child?.kill("SIGTERM");
+					return;
+				}
+				killTree(pid, "SIGTERM");
+				killTimer = setTimeout(() => {
+					if (!settled) killTree(pid, "SIGKILL", true);
+				}, killGraceMs);
+				killTimer.unref?.();
+			};
+
+			const onAbort = (): void => stop("abort");
+			if (run.signal?.aborted) {
+				cancelled = true;
+				settle(null, null);
+				return;
+			}
+			run.signal?.addEventListener("abort", onAbort, { once: true });
+
+			try {
+				child = spawn(run.command, { cwd: run.cwd, env: checkEnv() });
+			} catch (error) {
+				spawnError = error instanceof Error ? error.message : String(error);
+				settle(null, null);
+				return;
+			}
+
+			const onData = (chunk: Buffer | string): void => {
+				const text = String(chunk);
+				log.append(text);
+				if (run.onOutput) run.onOutput(text);
+			};
+			child.stdout?.on("data", onData);
+			child.stderr?.on("data", onData);
+			child.on("error", (error) => {
+				spawnError = error.message;
+				// Node follows an error with close; still settle if a fake does not.
+				settle(null, null);
+			});
+			child.on("close", (code, signal) => settle(code, signal));
+
+			if (run.timeoutMs > 0) {
+				timeoutTimer = setTimeout(() => stop("timeout"), run.timeoutMs);
+				timeoutTimer.unref?.();
+			}
+		});
+}

package/extensions/check/runtime.ts

@@ -0,0 +1,244 @@
+/**
+ * The check runtime: planning, sequencing, the live line buffer, and the one
+ * active run.
+ *
+ * Detection is synchronous; a run is a sequence of bounded one-shot processes.
+ * The runtime knows nothing about a language, a package manager, or a test
+ * framework: it receives `CommandSpec`s and hands their output to the parser.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { resolveEffectiveCwd } from "../../lib/env.ts";
+import { stripControlChars } from "../../lib/format.ts";
+import { LineSplitter } from "../../lib/lines.ts";
+import { loadConfig, type CheckConfig } from "./config.ts";
+import { planCommands } from "./detect.ts";
+import { failureKey, parseFailures } from "./failures.ts";
+import { createRunner, type RunOutcome } from "./runner.ts";
+import type { ActiveCheck, CheckResult, CheckStatus, CheckTarget, CommandSpec, Failure } from "./types.ts";
+
+/** Lines kept for the live screen and the tail. */
+const MAX_LINES = 5_000;
+/** Lines in the tail shown in a detail view / model fallback. */
+const TAIL_LINES = 40;
+/** Characters kept from one output line before the TUI clips it. */
+const MAX_LINE_CHARS = 2_000;
+/** Failures retained across commands. */
+const MAX_FAILURES = 200;
+
+/** A planning or lifecycle error a command/tool can show verbatim. */
+export class CheckError extends Error {}
+
+export interface CheckRuntime {
+	/** Start a run and return its observable handle. Throws `CheckError`. */
+	start(target: CheckTarget, ctx: ExtensionContext, onUpdate?: () => void): ActiveCheck;
+	/** Run to completion; planning errors become an error result, not a throw. */
+	run(target: CheckTarget, ctx: ExtensionContext): Promise<CheckResult>;
+	isRunning(): boolean;
+	/** Cancel and release the active run (idempotent). */
+	shutdown(): void;
+}
+
+export interface CheckRuntimeOptions {
+	/** Fixed config, for tests; production loads it per run. */
+	config?: CheckConfig;
+	/** Runner seam, for tests. */
+	runner?: (options: {
+		cwd: string;
+		command: string;
+		timeoutMs: number;
+		maxLogBytes: number;
+		signal?: AbortSignal;
+		onOutput?: (chunk: string) => void;
+	}) => Promise<RunOutcome>;
+	now?: () => number;
+}
+
+/** One sanitized line, bounded so a minified error cannot bloat the buffer. */
+function cleanLine(line: string): string {
+	return stripControlChars(line.replace(/\r$/, "")).slice(0, MAX_LINE_CHARS);
+}
+
+/** An error result for a plan or lifecycle failure. */
+export function checkErrorResult(target: CheckTarget, message: string): CheckResult {
+	return {
+		target,
+		status: "error",
+		commands: [],
+		exitCode: null,
+		durationMs: 0,
+		truncated: false,
+		failures: [],
+		tail: "",
+		error: message,
+	};
+}
+
+/** Dedupe failures across commands, preserving command provenance. */
+function mergeFailures(failures: readonly Failure[]): Failure[] {
+	const seen = new Set<string>();
+	const merged: Failure[] = [];
+	for (const failure of failures) {
+		const key = failureKey(failure, { command: true });
+		if (seen.has(key)) continue;
+		seen.add(key);
+		merged.push(failure);
+		if (merged.length >= MAX_FAILURES) break;
+	}
+	return merged;
+}
+
+export function createCheckRuntime(options: CheckRuntimeOptions = {}): CheckRuntime {
+	const now = options.now ?? (() => Date.now());
+	const runner = options.runner ?? createRunner();
+	let active: ActiveCheck | undefined;
+	let controller: AbortController | undefined;
+
+	const configFor = (cwd: string): CheckConfig => options.config ?? loadConfig(cwd);
+
+	const execute = async (
+		target: CheckTarget,
+		cwd: string,
+		config: CheckConfig,
+		commands: readonly CommandSpec[],
+		lines: string[],
+		signal: AbortSignal,
+		onUpdate?: () => void,
+	): Promise<CheckResult> => {
+		const started = now();
+		const outcomes: RunOutcome[] = [];
+		const failures: Failure[] = [];
+		const splitter = new LineSplitter();
+		let status: CheckStatus = "passed";
+		let error: string | undefined;
+
+		const append = (line: string): void => {
+			lines.push(cleanLine(line));
+			if (lines.length > MAX_LINES) lines.splice(0, lines.length - MAX_LINES);
+		};
+		const flush = (): void => {
+			for (const line of splitter.flush()) append(line);
+		};
+		const onOutput = (chunk: string): void => {
+			for (const line of splitter.push(chunk)) append(line);
+			onUpdate?.();
+		};
+
+		for (const spec of commands) {
+			if (signal.aborted) {
+				status = "cancelled";
+				break;
+			}
+			append(`$ ${spec.command}`);
+			let outcome: RunOutcome;
+			try {
+				outcome = await runner({
+					cwd,
+					command: spec.command,
+					timeoutMs: config.timeoutMs,
+					maxLogBytes: config.maxLogBytes,
+					signal,
+					onOutput,
+				});
+			} catch (failure) {
+				status = "error";
+				error = failure instanceof Error ? failure.message : String(failure);
+				break;
+			}
+			flush();
+			outcomes.push(outcome);
+			if (outcome.cancelled) {
+				status = "cancelled";
+				break;
+			}
+			if (outcome.timedOut) {
+				status = "timeout";
+				break;
+			}
+			if (outcome.error) {
+				status = "error";
+				error = outcome.error;
+				break;
+			}
+			if (outcome.exitCode !== 0) {
+				status = "failed";
+				failures.push(...parseFailures(outcome.output, spec.command, outcome.exitCode));
+			}
+			append("");
+		}
+
+		const exitCode =
+			outcomes.find((outcome) => outcome.exitCode !== null && outcome.exitCode !== 0)?.exitCode ??
+			outcomes.at(-1)?.exitCode ??
+			null;
+		const tail = lines.slice(-TAIL_LINES).join("\n");
+		onUpdate?.();
+		return {
+			target,
+			status,
+			commands: commands.map((spec) => spec.label),
+			exitCode,
+			durationMs: Math.max(0, now() - started),
+			truncated: outcomes.some((outcome) => outcome.truncated),
+			failures: mergeFailures(failures),
+			tail,
+			...(error ? { error } : {}),
+		};
+	};
+
+	const start = (target: CheckTarget, ctx: ExtensionContext, onUpdate?: () => void): ActiveCheck => {
+		if (active) throw new CheckError("A check is already running.");
+		const cwd = resolveEffectiveCwd(ctx.cwd);
+		const config = configFor(cwd);
+		const planned = planCommands(cwd, target, config.command);
+		if (!planned.ok) throw new CheckError(planned.error);
+		const commands = planned.commands;
+		if (commands.length === 0) throw new CheckError("No check command detected.");
+
+		const started = now();
+		const lines: string[] = [];
+		const runController = new AbortController();
+		controller = runController;
+		let handle: ActiveCheck;
+		const promise = execute(target, cwd, config, commands, lines, runController.signal, onUpdate)
+			.catch((error) => checkErrorResult(target, error instanceof Error ? error.message : String(error)))
+			.finally(() => {
+				if (controller === runController) controller = undefined;
+				if (active === handle) active = undefined;
+			});
+		handle = {
+			target,
+			commands: commands.map((spec) => spec.label),
+			lines: () => lines,
+			elapsedMs: () => Math.max(0, now() - started),
+			promise,
+			cancel: () => runController.abort(),
+		};
+		active = handle;
+		return handle;
+	};
+
+	const run = async (target: CheckTarget, ctx: ExtensionContext): Promise<CheckResult> => {
+		let handle: ActiveCheck;
+		try {
+			handle = start(target, ctx);
+		} catch (error) {
+			if (error instanceof CheckError) return checkErrorResult(target, error.message);
+			return checkErrorResult(target, error instanceof Error ? error.message : String(error));
+		}
+		return handle.promise;
+	};
+
+	const shutdown = (): void => {
+		controller?.abort();
+		controller = undefined;
+		active = undefined;
+	};
+
+	return {
+		start,
+		run,
+		isRunning: () => active !== undefined,
+		shutdown,
+	};
+}

package/extensions/check/source.ts

@@ -0,0 +1,80 @@
+/**
+ * Read a small source excerpt around a parsed failure's location.
+ *
+ * The path comes from command output, so it is treated as untrusted: it must
+ * resolve inside the project root (including through symlinks), be a regular
+ * file, and pass a size/NUL check before any text is returned. Anything else
+ * is a reason the detail pane can show while it falls back to the run tail.
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { isInside, isInsideReal } from "../../lib/path.ts";
+import type { Failure } from "./types.ts";
+
+/** Lines shown before and after the target line. */
+export const SOURCE_CONTEXT = 5;
+
+/** Largest source file read for a detail pane. */
+export const MAX_SOURCE_BYTES = 512 * 1024;
+
+export interface SourceExcerpt {
+	/** 1-based line number of the first returned row. */
+	startLine: number;
+	/** 1-based line number of the last returned row. */
+	endLine: number;
+	/** 1-based target line. */
+	targetLine: number;
+	/** Raw file lines, one per row, without line numbers or markers. */
+	lines: string[];
+}
+
+export type SourceResult = { ok: true; excerpt: SourceExcerpt } | { ok: false; reason: string };
+
+/** A source excerpt for a failure, or the reason one cannot be shown. */
+export function readSourceExcerpt(cwd: string, failure: Failure): SourceResult {
+	if (!failure.path) return { ok: false, reason: "no file location" };
+	if (failure.line === undefined || !Number.isFinite(failure.line) || failure.line < 1) {
+		return { ok: false, reason: "no line number" };
+	}
+
+	const root = resolve(cwd);
+	const absolute = isAbsolute(failure.path) ? resolve(failure.path) : resolve(root, failure.path);
+	if (!isInside(root, absolute) || !isInsideReal(root, absolute)) {
+		return { ok: false, reason: "outside the project" };
+	}
+
+	let stat;
+	try {
+		stat = statSync(absolute);
+	} catch {
+		return { ok: false, reason: "file is missing" };
+	}
+	if (!stat.isFile()) return { ok: false, reason: "not a regular file" };
+	if (stat.size > MAX_SOURCE_BYTES) return { ok: false, reason: "file is too large" };
+
+	let text: string;
+	try {
+		text = readFileSync(absolute, "utf-8");
+	} catch {
+		return { ok: false, reason: "file could not be read" };
+	}
+	if (text.includes("\u0000")) return { ok: false, reason: "binary file" };
+
+	const fileLines = text.split(/\r?\n/);
+	if (failure.line > fileLines.length) {
+		return { ok: false, reason: `line ${failure.line} is outside the file (${fileLines.length} lines)` };
+	}
+
+	const startLine = Math.max(1, failure.line - SOURCE_CONTEXT);
+	const endLine = Math.min(fileLines.length, failure.line + SOURCE_CONTEXT);
+	return {
+		ok: true,
+		excerpt: {
+			startLine,
+			endLine,
+			targetLine: failure.line,
+			lines: fileLines.slice(startLine - 1, endLine),
+		},
+	};
+}