@zenodinh/pi-render 0.0.0-stage → 0.1.0

package/src/renderers/tool/runtime.ts

@@ -0,0 +1,267 @@
+// ported from pi-pretty-tui/src/tools/bash.ts:186-200 + src/tools/read.ts:243-262 — survives because:
+// parse-once memoization and the async staleness token are the two protocols worth keeping; the
+// monkey-patched Text.render and the per-tool copies are not.
+
+/**
+ * runtime.ts — a declarative RowSpec in, host tool renderers out: parse once, project per invocation.
+ *
+ * Boundary: one runtime per row, created by the master resolver. It owns the protocol every spec would
+ * otherwise re-implement — memo, args gate, never-throw degradation, async decorate. Host shapes arrive
+ * as parameters (ctx, theme) and stay structural, so a unit test needs no pi runtime.
+ *
+ * shape: closure returning an object literal — trigger #4: the per-row memo/token live behind the
+ * renderCall/renderResult methods, with no subclassing.
+ */
+
+import type {
+	HostTheme,
+	RenderContext,
+	RenderResultOptions,
+	ToolRenderers,
+	ToolResult,
+	UiComponent,
+} from "../../core/types/host.ts";
+import type { Logger } from "../../core/types/log.ts";
+import type { RowPaint, RowPaintFactory } from "../../core/types/paint.ts";
+import type { RowSpec, RowView } from "./types.ts";
+
+/** `build`'s "unrecognized"; the runtime answers with rawRow instead of projecting. */
+const UNKNOWN = "unknown";
+const LOG_SCOPE = "tool.row";
+/** ctx.state keys are namespaced: a spec reads the same bag and must not collide with the runtime. */
+const MEMO_KEY = "piRender.memo";
+const TOKEN_KEY = "piRender.token";
+const DECORATED_KEY = "piRender.decorated";
+/** A session reaches 1,400+ rows, so cross-row parsed models are bounded by count and by size. */
+const CACHE_MAX_ENTRIES = 512;
+const CACHE_MAX_CHARS = 16_000_000;
+
+type ResultContent = NonNullable<ToolResult["content"]>;
+
+/** The per-row memo: the result.content reference and length that produced this model. */
+interface ModelMemo {
+	src: ResultContent | undefined;
+	len: number;
+	model: unknown;
+}
+
+/** One parsed model shared across rows, keyed on the stable result.content reference. */
+interface CachedModel {
+	spec: RowSpec;
+	chars: number;
+	model: unknown;
+}
+
+// Module scope, not ctx.state: reuse across rows is the point, and only here can the 512-entry /
+// 16M-char bound be enforced. Map insertion order is the recency order.
+const modelCache = new Map<ResultContent, CachedModel>();
+let cachedChars = 0;
+
+/** The runtime's own envelope; the model is a spec-defined type, not runtime-checkable. */
+function isModelMemo(value: unknown): value is ModelMemo {
+	return typeof value === "object" && value !== null && "src" in value && "len" in value && "model" in value;
+}
+
+function readMemo(ctx: RenderContext): ModelMemo | undefined {
+	const value: unknown = ctx.state[MEMO_KEY];
+	return isModelMemo(value) ? value : undefined;
+}
+
+function writeMemo(ctx: RenderContext, src: ResultContent | undefined, len: number, model: unknown): void {
+	ctx.state[MEMO_KEY] = { src, len, model };
+}
+
+/** The engine's text verbatim, collapsed to one line: the degradation contract's body. */
+function textOf(result: ToolResult): string {
+	const content = result.content;
+	if (!Array.isArray(content)) return "";
+	const parts: string[] = [];
+	for (const block of content) {
+		if (block !== null && typeof block === "object" && typeof block.text === "string") parts.push(block.text);
+	}
+	return parts
+		.join(" ")
+		.replace(/\s*\n\s*/g, " ")
+		.trim();
+}
+
+function charsOf(content: ResultContent): number {
+	let chars = 0;
+	for (const block of content) {
+		if (block !== null && typeof block === "object" && typeof block.text === "string") chars += block.text.length;
+	}
+	return chars;
+}
+
+function cacheGet(spec: RowSpec, content: ResultContent): CachedModel | undefined {
+	const hit = modelCache.get(content);
+	if (hit === undefined || hit.spec !== spec) return undefined;
+	// A hit is the most recent use: re-insert so the head is always the eviction victim.
+	modelCache.delete(content);
+	modelCache.set(content, hit);
+	return hit;
+}
+
+function cacheSet(spec: RowSpec, content: ResultContent, model: unknown): void {
+	const previous = modelCache.get(content);
+	if (previous !== undefined) cachedChars -= previous.chars;
+	modelCache.delete(content);
+	const entry: CachedModel = { spec, chars: charsOf(content), model };
+	modelCache.set(content, entry);
+	cachedChars += entry.chars;
+	while (modelCache.size > CACHE_MAX_ENTRIES || cachedChars > CACHE_MAX_CHARS) {
+		const oldest = modelCache.keys().next().value;
+		if (oldest === undefined) break;
+		const evicted = modelCache.get(oldest);
+		modelCache.delete(oldest);
+		if (evicted !== undefined) cachedChars -= evicted.chars;
+	}
+}
+
+function viewOf(options: RenderResultOptions, ctx: RenderContext): RowView {
+	return { expanded: options.expanded, isError: ctx.isError === true, isPartial: options.isPartial };
+}
+
+function rawBody(result: ToolResult, paint: RowPaint | undefined): string {
+	const text = textOf(result);
+	if (paint === undefined) return text;
+	try {
+		return paint.muted(text);
+	} catch {
+		// A theme token can throw mid-render (host fg); the degraded row must still come back.
+		return text;
+	}
+}
+
+function logFailure(log: Logger, ctx: RenderContext, err: unknown): void {
+	const key = typeof ctx.toolCallId === "string" ? ctx.toolCallId : LOG_SCOPE;
+	const text = (err instanceof Error ? err.message : String(err)).replace(/\s+/g, " ").slice(0, 200);
+	log.logOnce(key, LOG_SCOPE, `row degraded: ${text}`);
+}
+
+/** shape: closure returning an object literal — trigger #4: one stored text behind render/invalidate. */
+function textFor(ctx: RenderContext, body: string): UiComponent {
+	const reuse = ctx.lastComponent;
+	if (reuse !== undefined) {
+		const setText = reuse.setText;
+		if (setText !== undefined) {
+			setText.call(reuse, body);
+			return reuse;
+		}
+	}
+	let current = body;
+	return {
+		render(_width: number): string[] {
+			// One entry per line; an empty body still yields one line, so a degraded row never vanishes.
+			// Width is the component's own: renderResult receives none, so nothing here is width-keyed.
+			return current.split("\n");
+		},
+		invalidate(): void {
+			// The host tracks staleness; this component caches no frame.
+		},
+		setText(value: string): void {
+			current = value;
+		},
+	};
+}
+
+function nextToken(ctx: RenderContext): number {
+	const current = ctx.state[TOKEN_KEY];
+	const next = typeof current === "number" ? current + 1 : 1;
+	ctx.state[TOKEN_KEY] = next;
+	return next;
+}
+
+function applyDecorate(log: Logger, ctx: RenderContext, token: number, content: ResultContent, partial: object): void {
+	try {
+		// The content changed while decorate was in flight: the new model must not inherit this result.
+		if (ctx.state[TOKEN_KEY] !== token) return;
+		const memo = readMemo(ctx);
+		if (memo === undefined || memo.src !== content) return;
+		writeMemo(ctx, memo.src, memo.len, Object.assign({}, memo.model, partial));
+		ctx.invalidate?.();
+	} catch (err) {
+		logFailure(log, ctx, err);
+	}
+}
+
+function scheduleDecorate(
+	spec: RowSpec,
+	log: Logger,
+	ctx: RenderContext,
+	content: ResultContent,
+	model: unknown,
+): void {
+	const decorate = spec.decorate;
+	if (decorate === undefined) return;
+	if (ctx.state[DECORATED_KEY] === content) return; // one schedule per content reference
+	const token = nextToken(ctx);
+	ctx.state[DECORATED_KEY] = content;
+	// Fire-and-forget: on success ctx.invalidate redraws, on failure the log captures it; nothing awaits.
+	void decorate(model, ctx).then(
+		(partial) => {
+			applyDecorate(log, ctx, token, content, partial);
+		},
+		(err: unknown) => {
+			logFailure(log, ctx, err);
+		},
+	);
+}
+
+export function createRowRenderers(spec: RowSpec, deps: { paint: RowPaintFactory; log: Logger }): ToolRenderers {
+	const modelFor = (result: ToolResult, ctx: RenderContext): unknown => {
+		const content = Array.isArray(result.content) ? result.content : undefined;
+		const len = content === undefined ? 0 : content.length;
+		const memo = readMemo(ctx);
+		if (content !== undefined && memo !== undefined && memo.src === content && memo.len === len) return memo.model;
+
+		if (content !== undefined) {
+			const cached = cacheGet(spec, content);
+			if (cached !== undefined) {
+				writeMemo(ctx, content, len, cached.model);
+				return cached.model;
+			}
+		}
+
+		const built = spec.build(result, ctx);
+		if (built === UNKNOWN) return UNKNOWN;
+		if (content !== undefined) {
+			cacheSet(spec, content, built);
+			writeMemo(ctx, content, len, built);
+			scheduleDecorate(spec, deps.log, ctx, content, built);
+		}
+		return built;
+	};
+
+	const renderCall = (args: Record<string, unknown>, theme: HostTheme, ctx: RenderContext): UiComponent => {
+		try {
+			const paint = deps.paint(theme);
+			// A partial argument set is not a title: buildCall sees {} until the host says argsComplete.
+			const model = spec.buildCall(ctx.argsComplete === true ? args : {}, ctx);
+			return textFor(ctx, paint.title(model.title));
+		} catch (err) {
+			logFailure(deps.log, ctx, err);
+			return textFor(ctx, "");
+		}
+	};
+
+	const renderResult = (
+		result: ToolResult,
+		options: RenderResultOptions,
+		theme: HostTheme,
+		ctx: RenderContext,
+	): UiComponent => {
+		try {
+			const paint = deps.paint(theme);
+			const model = modelFor(result, ctx);
+			const body = model === UNKNOWN ? rawBody(result, paint) : spec.project(model, viewOf(options, ctx), paint);
+			return textFor(ctx, body);
+		} catch (err) {
+			// The paint may itself be the thrower, so the degraded row is built without it.
+			logFailure(deps.log, ctx, err);
+			return textFor(ctx, rawBody(result, undefined));
+		}
+	};
+
+	return { renderCall, renderResult };
+}

package/src/renderers/tool/specs/bash.test.ts

@@ -0,0 +1,110 @@
+/**
+ * bash.test.ts — the bash row spec as a specification.
+ *
+ * Behavior spec (from the T-14 port source, pi-pretty-tui/src/tools/bash.ts):
+ *   buildCall({command}, argsComplete) -> title "bash: <command>"; gate closed -> "bash" only.
+ *   build(result, ctx)                 -> { output, exitCode, durationMs, isError } with the exit
+ *                                         status inferred from the output and the time read from ctx.state.
+ *   project(model, collapsed)          -> one summary line: "<n> lines · exit <code> · <duration> · hint";
+ *                                         an error shows its message on that line instead.
+ *   project(model, expanded)           -> summary header + blank + indented output body.
+ *
+ * Enters only at the exported record's seam with the marker fake paint and testRenderContext; no
+ * module internals are imported.
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { assertNoRealEscapes, markerPaint, testRenderContext } from "../../../../test/fakes/index.ts";
+import type { RenderContext, RowView, ToolResult } from "../../../core/types.ts";
+import { bashRow } from "./bash.ts";
+
+// Marker escapes pinned from test/fakes/paint.ts:22-35 (muted 202/222, output 201/221, error 204/224);
+// a real escape cannot read as a marker because the marker codes sit off the host palette.
+const MUTED = (text: string): string => `\u001b[38;5;202m${text}\u001b[38;5;222m`;
+const OUTPUT = (text: string): string => `\u001b[38;5;201m${text}\u001b[38;5;221m`;
+const ERROR = (text: string): string => `\u001b[38;5;204m${text}\u001b[38;5;224m`;
+
+const MARKER = markerPaint();
+
+// recorded-from: pi host bash result — content is the engine's stdout verbatim, trailing newline
+// included; the single-line shape is pi-pretty-tui/src/tools/bash-collapse.test.ts:46, 2026-10-03.
+const CANONICAL: ToolResult = { content: [{ type: "text", text: "42\n" }] };
+// invented: a real `bash: <cmd>: command not found` stderr line — the literal text only has to match
+// inferExit's recorded pattern (pi-pretty-tui/src/core/helpers.ts:44-49).
+const FAILED: ToolResult = { content: [{ type: "text", text: "bash: nope: command not found\n" }] };
+
+// Assembled so a future edit cannot satisfy the scan by quoting its own needle.
+const FORBIDDEN = ["registerTool", "promptSnippet", "promptGuidelines", "sdkTool", ".execute", "as unknown as"];
+
+type BashModel = Exclude<ReturnType<typeof bashRow.spec.build>, "unknown">;
+
+function view(expanded: boolean): RowView {
+	return { expanded, isError: false, isPartial: false };
+}
+
+function parse(result: ToolResult, ctx: RenderContext): BashModel {
+	const model = bashRow.spec.build(result, ctx);
+	if (model === "unknown") throw new Error("a bash result must always parse");
+	return model;
+}
+
+describe("bash row spec", () => {
+	it("AC-1 (golden row): canonical collapsed and expanded output is byte-pinned", () => {
+		// spec: project(build(CANONICAL), collapsed) -> "1 line · exit 0 · 1.2s · ctrl+o to expand"
+		const ctx = testRenderContext({ args: { command: "npm test" }, state: { startedAt: 1_000, endedAt: 2_200 } });
+		expect(bashRow.spec.buildCall({ command: "npm test" }, ctx).title).toBe("bash: npm test");
+		const model = parse(CANONICAL, ctx);
+		// fails_when: a plausible-looking row renders wrong data (count, status, duration)
+		expect(bashRow.spec.project(model, view(false), MARKER)).toBe(MUTED("1 line · exit 0 · 1.2s · ctrl+o to expand"));
+		expect(bashRow.spec.project(model, view(true), MARKER)).toBe(
+			[MUTED("1 line · exit 0 · 1.2s"), "", `  ${OUTPUT("42")}`].join("\n"),
+		);
+	});
+
+	it("AC-2 (error row): the error summarizes collapsed and opens to its body", () => {
+		// spec: build(FAILED, isError) -> exit 1; project collapsed -> error on the summary line
+		const ctx = testRenderContext({
+			args: { command: "nope" },
+			isError: true,
+			state: { startedAt: 1_000, endedAt: 1_500 },
+		});
+		const model = parse(FAILED, ctx);
+		expect(model.exitCode).toBe(1);
+		// fails_when: errors render blank or crash
+		expect(bashRow.spec.project(model, view(false), MARKER)).toBe(
+			ERROR("bash: nope: command not found") + MUTED(" · 1 line · exit 1 · 500ms · ctrl+o to expand"),
+		);
+		expect(bashRow.spec.project(model, view(true), MARKER)).toBe(
+			[MUTED("1 line · exit 1 · 500ms"), "", `  ${ERROR("bash: nope: command not found")}`].join("\n"),
+		);
+	});
+
+	it("AC-3 (no execution ported): the source carries no registration or prompt text", () => {
+		const source = readFileSync(fileURLToPath(new URL("./bash.ts", import.meta.url)), "utf8");
+		// fails_when: the port smuggles execution back in
+		for (const needle of FORBIDDEN) expect(source, needle).not.toContain(needle);
+		expect(bashRow.name).toBe("bash");
+		expect(bashRow.descriptor).toEqual({ key: "row.bash", name: "Bash row", defaultEnabled: true, settings: [] });
+	});
+
+	it("AC-4 (args gate): the call line is the tool name only until argsComplete", () => {
+		const gated = testRenderContext({ args: {}, argsComplete: false });
+		// fails_when: fabricated argument values reach the title
+		expect(bashRow.spec.buildCall({}, gated).title).toBe("bash");
+		expect(bashRow.spec.buildCall({ command: "rm -rf /" }, gated).title).toBe("bash");
+		// the gate open with no command is still name-only, never an empty title
+		expect(bashRow.spec.buildCall({}, testRenderContext({ args: {} })).title).toBe("bash");
+	});
+
+	it("AC-5 (paint-only color): every escape in a projected row is a paint marker", () => {
+		const ctx = testRenderContext({ args: { command: "npm test" }, state: { startedAt: 1_000, endedAt: 2_200 } });
+		const model = parse(CANONICAL, ctx);
+		const collapsed = bashRow.spec.project(model, view(false), MARKER);
+		const expanded = bashRow.spec.project(model, view(true), MARKER);
+		// fails_when: a hardcoded color appears outside core/paint (marker + scan both catch it)
+		for (const output of [collapsed, expanded]) assertNoRealEscapes(output);
+		expect(collapsed).toContain("\u001b[38;5;202m");
+	});
+});

package/src/renderers/tool/specs/bash.ts

@@ -0,0 +1,168 @@
+/**
+ * bash.ts — the bash row spec: a shell call shown as one scannable summary line, expandable to output.
+ *
+ * Boundary: lane-local. Pure parse + project — the spec registers nothing and runs nothing; colors
+ * come only from the paint handed to project. Duration is read from the row's own state bag, never
+ * injected by a wrapper (the predecessor's metrics wrapper dies with registration).
+ *
+ * shape: object literal implementing RowSpec — trigger #7, the three contract fields are fixed-shape
+ * functions with no per-row state of their own, so a closure or class would be ceremony.
+ *
+ * ported from pi-pretty-tui/src/tools/bash.ts — survives because: exit-code inference, exit-line
+ * stripping, error compaction and duration formatting are pure view logic; its registration, run
+ * wrapper, metrics wrapper and render monkey-patch all die (see T-14).
+ */
+
+import type {
+	CallModel,
+	ModuleDescriptor,
+	RenderContext,
+	RowPaint,
+	RowSpec,
+	RowView,
+	ToolResult,
+} from "../../../core/types.ts";
+
+const INDENT = "  ";
+const HINT = "ctrl+o to expand";
+
+// The row's clock lives in its state bag — the host's own bash renderer keeps it there too (pi 1.0.4
+// dist/core/tools/renderers/bash.js), so no result wrapper may carry the duration.
+const STARTED_KEY = "startedAt";
+const ENDED_KEY = "endedAt";
+
+/** Parsed bash result: cleaned output plus the status, timing and failure flag it renders from. */
+interface BashModel {
+	output: string;
+	exitCode: number | null;
+	durationMs: number | null;
+	isError: boolean;
+}
+
+/** Joins the result's text blocks exactly as the host delivers them; only text blocks are rendered. */
+function textOf(result: ToolResult): string {
+	const parts: string[] = [];
+	for (const block of result.content ?? []) {
+		if (block.type === "text" && typeof block.text === "string") parts.push(block.text);
+	}
+	return parts.join("\n");
+}
+
+/** Folds a multi-line command onto one call line, so a script command never paints one row per line. */
+function flatten(command: string): string {
+	return command.replace(/[ \t]*[\r\n]+[ \t]*/g, " ").trim();
+}
+
+function normalize(text: string): string {
+	return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+
+/** Drops the host's own "Command exited with code N" trailer — the status renders in the summary. */
+function stripExitLine(text: string): string {
+	return normalize(text)
+		.split("\n")
+		.filter((line) => !/^Command exited with code \d+$/i.test(line.trim()))
+		.join("\n");
+}
+
+function trimEnd(text: string): string {
+	return text.endsWith("\n") ? text.slice(0, -1) : text;
+}
+
+/** Collapses runs of blank lines so a stack trace summarizes to a bounded body. */
+function compactError(text: string): string[] {
+	const lines: string[] = [];
+	let wasBlank = false;
+	for (const line of normalize(text).trim().split("\n")) {
+		const isBlank = line.trim() === "";
+		if (isBlank && wasBlank) continue;
+		lines.push(line);
+		wasBlank = isBlank;
+	}
+	return lines;
+}
+
+/** Infers the shell's exit status from the output when the host reports none. */
+function inferExit(text: string, fallback: number | null): number | null {
+	const match = text.match(/(?:exit code|exited with(?: code)?|exit status)[:\s]*(\d+)/i);
+	const digit = match?.[1];
+	if (digit !== undefined) return Number(digit);
+	if (text.includes("command not found") || text.includes("No such file")) return 1;
+	return fallback;
+}
+
+/** Sub-second as ms, then compact whole seconds — ports formatElapsedMs. */
+function formatDuration(ms: number): string {
+	if (ms < 1000) return `${Math.round(ms)}ms`;
+	const seconds = ms / 1000;
+	return seconds < 10 ? `${seconds.toFixed(1)}s` : `${Math.round(seconds)}s`;
+}
+
+function recordStart(ctx: RenderContext): void {
+	if (typeof ctx.state[STARTED_KEY] !== "number") ctx.state[STARTED_KEY] = Date.now();
+}
+
+function settleEnd(ctx: RenderContext): void {
+	// A streaming row has no final time yet; isPartial gates the write instead of a remove wrapper.
+	if (ctx.isPartial === true || typeof ctx.state[ENDED_KEY] === "number") return;
+	ctx.state[ENDED_KEY] = Date.now();
+}
+
+function readDuration(ctx: RenderContext): number | null {
+	const started = ctx.state[STARTED_KEY];
+	const ended = ctx.state[ENDED_KEY];
+	if (typeof started !== "number" || typeof ended !== "number") return null;
+	return Math.max(0, ended - started);
+}
+
+// shape: object literal implementing RowSpec — trigger #7, a fixed record of three stateless functions.
+const bashSpec: RowSpec<BashModel> = {
+	buildCall(args, ctx): CallModel {
+		recordStart(ctx);
+		if (ctx.argsComplete !== true) return { title: "bash" };
+		const value = args.command;
+		if (typeof value !== "string") return { title: "bash" };
+		const command = flatten(value);
+		return { title: command === "" ? "bash" : `bash: ${command}` };
+	},
+
+	build(result, ctx): BashModel | "unknown" {
+		settleEnd(ctx);
+		const raw = textOf(result);
+		const failed = ctx.isError === true;
+		const exitCode = inferExit(raw, failed ? 1 : 0);
+		return {
+			output: stripExitLine(raw),
+			exitCode,
+			durationMs: readDuration(ctx),
+			isError: failed || (exitCode !== null && exitCode !== 0),
+		};
+	},
+
+	project(m: BashModel, view: RowView, paint: RowPaint): string {
+		const body = m.isError ? compactError(m.output).join("\n") : trimEnd(m.output);
+		const count = body === "" ? 0 : body.split("\n").length;
+		const stats = [`${count} line${count === 1 ? "" : "s"}`];
+		if (m.exitCode !== null) stats.push(`exit ${m.exitCode}`);
+		if (m.durationMs !== null) stats.push(formatDuration(m.durationMs));
+
+		if (!view.expanded) {
+			const tail = `${stats.join(" · ")} · ${HINT}`;
+			if (!m.isError) return paint.muted(tail);
+			const head = body === "" ? "Error" : (body.split("\n")[0] ?? "Error");
+			return `${paint.error(head)}${paint.muted(` · ${tail}`)}`;
+		}
+
+		const header = paint.muted(stats.join(" · "));
+		if (body === "") return header;
+		const lines = body.split("\n").map((line) => `${INDENT}${m.isError ? paint.error(line) : paint.output(line)}`);
+		return [header, "", ...lines].join("\n");
+	},
+};
+
+// shape: object literal — trigger #7, the spec module record T-28 composes; fields are known statically.
+export const bashRow: { name: string; spec: RowSpec<BashModel>; descriptor: ModuleDescriptor } = {
+	name: "bash",
+	spec: bashSpec,
+	descriptor: { key: "row.bash", name: "Bash row", defaultEnabled: true, settings: [] },
+};