@zenodinh/pi-render 0.0.0-stage → 0.1.2

package/src/renderers/tool/index.ts

@@ -0,0 +1,113 @@
+/**
+ * index.ts — the master resolver: the tool-name table, the captured host base, and one registry check
+ * per invocation — the pluggable toggle for every tool row.
+ *
+ * Boundary: the host consults this ONCE per row component construction, keyed on tool name alone, and
+ * `next()` exists only at that moment; the base renderers it hands back are captured here and reused for
+ * the component's lifetime. Both the table and the collaborators arrive as parameters (T-28 composes
+ * them), so a unit test drives the whole toggle with fake specs, a fake registry and a fake base.
+ *
+ * Replaces pi-pretty-tui's three attachment mechanisms (shadow registration, Proxy shim, orphan
+ * factories) with one resolver — none of them ported.
+ *
+ * shape: closure returning a resolver function — trigger #4: the factory builds and captures one runtime
+ * per spec, and the resolver it returns keeps no per-row state of its own.
+ */
+
+import type {
+	HostTheme,
+	Logger,
+	Registry,
+	RenderContext,
+	RenderResultOptions,
+	RowPaintFactory,
+	ToolRendererResolver,
+	ToolRenderers,
+	ToolResult,
+	UiComponent,
+} from "../../core/types.ts";
+import { createRowRenderers } from "./runtime.ts";
+import type { RowSpec } from "./types.ts";
+
+/** The host's own shell frame: chrome belongs to pi-zentui, so a row never asks for a custom one. */
+const SHELL = "default";
+const SCOPE = "tool.resolve";
+
+/** The resolver's injected collaborators — the row paint factory, plus the keyed diagnostic sink. */
+export interface MasterResolverDeps {
+	/** Region-1 row paint, resolved per render call so a theme switch repaints. Required. */
+	paint: RowPaintFactory;
+	/** Diagnostics for a spec whose runtime cannot draw. Required. */
+	log: Logger;
+}
+
+/** One table entry: the spec plus its registry key (search's four names share one key — T-20 ruling). */
+export interface SpecEntry {
+	/** The spec the runtime renders when enabled. Required. */
+	spec: RowSpec;
+	/** Registry key governing this name — explicit, because keys are not always "row." + name. Required. */
+	key: string;
+}
+
+/** The row runtime's built renderers: both slots, always (runtime.ts returns them unconditionally). */
+type RowRuntime = Required<Pick<ToolRenderers, "renderCall" | "renderResult">>;
+
+/**
+ * Base renderers pattern-match the component they are handed and clear it (host grep.js:65-67), so a
+ * delegated call gets a blank slot: a foreign component there is a type mismatch, hence a throw.
+ */
+function withoutComponent(ctx: RenderContext): RenderContext {
+	// Copy, never mutate: the host reuses its ctx object for its own bookkeeping.
+	return { ...ctx, lastComponent: undefined };
+}
+
+// shape: closure returning a resolver function — trigger #4: one runtime binding per spec is captured by
+// the factory; the resolver allocates only what a single row construction needs.
+export function createMasterResolver(
+	registry: Registry,
+	specs: Record<string, SpecEntry>,
+	deps: MasterResolverDeps,
+): ToolRendererResolver {
+	// Built ONCE per spec, never per row or per frame: the memo, args gate and decorate protocol belong to
+	// the spec. A Map, not the injected object — a bare `{}` lookup would answer for "constructor" and
+	// style a row the table never declared.
+	const runtimes = new Map<string, { renderers: RowRuntime; key: string }>();
+	for (const [name, { spec, key }] of Object.entries(specs)) {
+		const { renderCall, renderResult } = createRowRenderers(spec, deps);
+		// The host type marks the slots optional because a resolver may omit one to delegate; the runtime
+		// supplies both. A slotless runtime cannot draw a row, so that name stays with the host chain.
+		if (renderCall === undefined || renderResult === undefined) {
+			deps.log.logOnce(`runtime:${name}`, SCOPE, `row runtime for ${name} returned no renderers`);
+			continue;
+		}
+		runtimes.set(name, { renderers: { renderCall, renderResult }, key });
+	}
+
+	return (toolName, next) => {
+		const entry = runtimes.get(toolName);
+		if (entry === undefined) return next(); // not our table: the host chain answers, verbatim
+		const base = next(); // captured here and only here — next() is gone once this resolver returns
+		const key = entry.key; // explicit: search's four names share "row.search" (T-20 ruling)
+		const runtime = entry.renderers;
+
+		return {
+			renderShell: SHELL,
+			renderCall(args: Record<string, unknown>, theme: HostTheme, ctx: RenderContext): UiComponent {
+				const baseCall = base?.renderCall;
+				if (registry.isEnabled(key) || baseCall === undefined) return runtime.renderCall(args, theme, ctx);
+				return baseCall(args, theme, withoutComponent(ctx));
+			},
+			renderResult(
+				result: ToolResult,
+				options: RenderResultOptions,
+				theme: HostTheme,
+				ctx: RenderContext,
+			): UiComponent {
+				const baseResult = base?.renderResult;
+				if (registry.isEnabled(key) || baseResult === undefined)
+					return runtime.renderResult(result, options, theme, ctx);
+				return baseResult(result, options, theme, withoutComponent(ctx));
+			},
+		};
+	};
+}

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.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: [] },
+};