@zenodinh/pi-render 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,260 @@
+/**
+ * edit.test.ts — the `edit` row spec through its seam: the exported RowSpec's three functions.
+ *
+ * Fixtures are the host builtin's own shapes (provenance per fixture below). Every block names its
+ * ticket AC and its `fails_when`, and each was inverted — with the behavior-driving line mutated the
+ * block goes RED (T-17 report, INVERSION-LOG).
+ */
+
+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 { RowView, ToolResult } from "../../../core/types.ts";
+import { editRow } from "./edit.ts";
+
+/* ── fixtures ────────────────────────────────────────────────────────── */
+
+// recorded-from @earendil-works/pi-coding-agent@1.0.4, dist/core/tools/edit-diff.js generateDiffString
+//   (executed 2026-10-06): the diff string for a one-line body change is exactly this line shape —
+//   " <num> ctx" | "-<num> old" | "+<num> new", numbers padded to the width of the highest line.
+const DIFF =
+	' 1 import { a } from "./a.ts";\n 2 \n 3 export function total(items) {\n-4   return items.length;\n+4   return items.reduce((n, i) => n + i, 0);\n 5 }';
+
+// recorded-from the same host generator (executed 2026-10-06): an asymmetric change — one line
+//   replaced and one appended — so counts read from the wrong side cannot pass as the golden.
+const DIFF_ASYMMETRIC =
+	' 1 const a = 1;\n-2 export const sum = () => a;\n+2 export const sum = () => a + a;\n 3 export const label = "sum";\n+4 export const version = 2;';
+
+// recorded-from the same host, dist/core/tools/edit.js:123-134 (read 2026-10-06): args are
+//   {path, edits[]} and a successful result carries details {diff, patch, firstChangedLine}.
+const ARGS: Record<string, unknown> = {
+	path: "/work/repo/src/total.ts",
+	edits: [{ oldText: "  return items.length;", newText: "  return items.reduce((n, i) => n + i, 0);" }],
+};
+const CWD = "/work/repo";
+const RESULT: ToolResult = {
+	content: [{ type: "text", text: "Successfully replaced 1 block(s) in src/total.ts." }],
+	details: { diff: DIFF, patch: "@@ -4,1 +4,1 @@", firstChangedLine: 4 },
+};
+
+// recorded-from the same host, dist/core/tools/edit.js:118 — its thrown-message template
+//   `Could not edit file: ${path}. ${errorMessage}.`
+const ERROR_RESULT: ToolResult = {
+	content: [{ type: "text", text: "Could not edit file: src/total.ts. Error code: ENOENT." }],
+};
+
+// invented: the host carries no fixture for a settled result with no details; this is the state the
+//   predecessor's pending branch exists for (a result rendered before its diff streamed in).
+const DIFFLESS_RESULT: ToolResult = {
+	content: [{ type: "text", text: "Successfully replaced 1 block(s) in src/total.ts." }],
+};
+
+// invented: the predecessor's 80-char summary cap needs an error longer than 80 to be observable.
+const LONG_ERROR_RESULT: ToolResult = {
+	content: [
+		{
+			type: "text",
+			text: "Error: oldText matched 3 locations in src/total.ts; make it unique by adding surrounding context.",
+		},
+	],
+};
+
+/* ── marker goldens ──────────────────────────────────────────────────── */
+
+// test/fakes/paint.ts's role table, written out independently so a golden pins the exact bytes AND the
+// role: output 201/221, muted 202/222, accent 203/223, error 204/224.
+const OUTPUT = (text: string) => `\u001b[38;5;201m${text}\u001b[38;5;221m`;
+const MUTED = (text: string) => `\u001b[38;5;202m${text}\u001b[38;5;222m`;
+const ACCENT = (text: string) => `\u001b[38;5;212m${text}\u001b[38;5;232m`;
+const ERROR = (text: string) => `\u001b[38;5;204m${text}\u001b[38;5;224m`;
+const DIFF_ADDED = (text: string) => `\u001b[38;5;212m${text}\u001b[38;5;232m`;
+const DIFF_REMOVED = (text: string) => `\u001b[38;5;213m${text}\u001b[38;5;233m`;
+const DIFF_CONTEXT = (text: string) => `\u001b[38;5;214m${text}\u001b[38;5;234m`;
+
+const paint = markerPaint();
+
+/** The runtime's view derivation (T-12): host options + ctx flags arrive here. */
+function view(over: Partial<RowView> = {}): RowView {
+	return { expanded: false, isError: false, isPartial: false, ...over };
+}
+
+/* ── the exported record ─────────────────────────────────────────────── */
+
+describe("edit row spec — the exported record", () => {
+	it("AC-1: the record names the tool and its registry descriptor", () => {
+		// fails_when: the resolver table or the /render panel reads the wrong name or key
+		expect(editRow.name).toBe("edit");
+		expect(editRow.descriptor).toEqual({
+			key: "row.edit",
+			name: "Edit row",
+			defaultEnabled: true,
+			settings: [],
+		});
+	});
+});
+
+/* ── buildCall ───────────────────────────────────────────────────────── */
+
+describe("edit row spec — buildCall", () => {
+	it("AC-4: a completed call names the path relative to ctx.cwd", () => {
+		const ctx = testRenderContext({ args: ARGS, cwd: CWD });
+		// fails_when: the title drops the path, or shows it raw with the cwd prefix
+		expect(editRow.spec.buildCall(ARGS, ctx)).toEqual({ title: "edit: src/total.ts" });
+	});
+
+	it("AC-4: a half-streamed arg bag yields the tool name only", () => {
+		const ctx = testRenderContext({ args: ARGS, argsComplete: false });
+		// fails_when: a partial arg set is rendered as a path (the gate is dropped)
+		expect(editRow.spec.buildCall(ARGS, ctx)).toEqual({ title: "edit" });
+	});
+
+	it("AC-4: empty args and a legacy `file_path` each render without inventing a value", () => {
+		const empty = testRenderContext({ args: {} });
+		// fails_when: an absent path renders as a placeholder or a stray separator
+		expect(editRow.spec.buildCall({}, empty)).toEqual({ title: "edit" });
+		// fails_when: a non-string argument is coerced into the title (a fabricated value)
+		expect(editRow.spec.buildCall({ path: 42 }, empty)).toEqual({ title: "edit" });
+		const legacy = testRenderContext({ args: { file_path: "src/a.ts" } });
+		// fails_when: the predecessor's arg spelling renders as the tool name only
+		expect(editRow.spec.buildCall({ file_path: "src/a.ts" }, legacy)).toEqual({ title: "edit: src/a.ts" });
+		const outside = { path: "/other/place/a.ts" };
+		const ctx = testRenderContext({ args: outside, cwd: CWD });
+		// fails_when: a path outside the cwd is rendered as a relative walk instead of the path itself
+		expect(editRow.spec.buildCall(outside, ctx)).toEqual({ title: "edit: /other/place/a.ts" });
+	});
+});
+
+/* ── project ─────────────────────────────────────────────────────────── */
+
+describe("edit row spec — project", () => {
+	it("AC-1: collapsed is the golden changed-line summary", () => {
+		const model = editRow.spec.build(RESULT);
+		const out = editRow.spec.project(model, view(), paint);
+		// fails_when: a plausible-looking row renders the wrong counts or the wrong roles
+		expect(out).toBe(` ${ACCENT("+1")} ${DIFF_REMOVED("−1")}`);
+		assertNoRealEscapes(out);
+		// The runtime paints buildCall's title (the call line) above this body (T-12): the two lines
+		// together are the collapsed row, so this golden covers the name and the counts.
+		const ctx = testRenderContext({ args: ARGS, cwd: CWD });
+		expect(`${editRow.spec.buildCall(ARGS, ctx).title}\n${out}`).toBe(
+			`edit: src/total.ts\n ${ACCENT("+1")} ${DIFF_REMOVED("−1")}`,
+		);
+	});
+
+	it("AC-1: an asymmetric diff counts each side separately", () => {
+		const model = editRow.spec.build({ ...RESULT, details: { diff: DIFF_ASYMMETRIC, firstChangedLine: 2 } });
+		const out = editRow.spec.project(model, view(), paint);
+		// fails_when: the two counts are swapped or summed — a symmetric fixture hides exactly this
+		expect(out).toBe(` ${ACCENT("+2")} ${DIFF_REMOVED("−1")}`);
+	});
+
+	it("AC-1: expanded is the golden diff, one painted line per host line", () => {
+		const model = editRow.spec.build(RESULT);
+		const out = editRow.spec.project(model, view({ expanded: true }), paint);
+		const golden = [
+			DIFF_CONTEXT(' 1 import { a } from "./a.ts";'),
+			DIFF_CONTEXT(" 2 "),
+			DIFF_CONTEXT(" 3 export function total(items) {"),
+			DIFF_REMOVED("-4   return items.length;"),
+			DIFF_ADDED("+4   return items.reduce((n, i) => n + i, 0);"),
+			DIFF_CONTEXT(" 5 }"),
+		].join("\n");
+		// fails_when: a line loses its tone, is dropped, reordered, or split differently
+		expect(out).toBe(golden);
+		assertNoRealEscapes(out);
+	});
+
+	it("AC-1: a diff-less result reads pending collapsed and shows its text expanded", () => {
+		const model = editRow.spec.build(DIFFLESS_RESULT);
+		// fails_when: a result with no diff renders as though it carried changes
+		expect(editRow.spec.project(model, view(), paint)).toBe(` ${MUTED("· pending")}`);
+		expect(editRow.spec.project(model, view({ expanded: true }), paint)).toBe(
+			`${MUTED("diff unavailable")}\n${OUTPUT("Successfully replaced 1 block(s) in src/total.ts.")}`,
+		);
+		// fails_when: a malformed details payload renders as a diff line instead of degrading
+		for (const details of [{ diff: 42 }, "oops", undefined]) {
+			expect(editRow.spec.project(editRow.spec.build({ ...DIFFLESS_RESULT, details }), view(), paint)).toBe(
+				` ${MUTED("· pending")}`,
+			);
+		}
+		const bare = editRow.spec.build({ content: [] });
+		// fails_when: a result with no text paints an empty output line under the reason
+		expect(editRow.spec.project(bare, view({ expanded: true }), paint)).toBe(MUTED("diff unavailable"));
+	});
+
+	it("AC-2: a failed call summarises the error on the collapsed line", () => {
+		const model = editRow.spec.build(ERROR_RESULT);
+		const out = editRow.spec.project(model, view({ isError: true }), paint);
+		// fails_when: errors render blank or crash
+		expect(out).toBe(` ${ERROR("✗ Could not edit file: src/total.ts. Error code: ENOENT.")}`);
+		assertNoRealEscapes(out);
+		const bare = editRow.spec.build({ content: [{ type: "image", text: "PNG bytes" }] });
+		// invented: a non-text block carrying text — the contract renders text blocks only, so this pins the skip.
+		// fails_when: a failed call whose result carries no text block renders a blank row (or the block's caption)
+		expect(editRow.spec.project(bare, view({ isError: true }), paint)).toBe(` ${ERROR("✗ Error")}`);
+		expect(editRow.spec.project(bare, view({ isError: true, expanded: true }), paint)).toBe(ERROR("Error"));
+	});
+
+	it("AC-2: an error longer than 80 characters is summarised, not wrapped", () => {
+		const model = editRow.spec.build(LONG_ERROR_RESULT);
+		const first = LONG_ERROR_RESULT.content?.[0]?.text ?? "";
+		const out = editRow.spec.project(model, view({ isError: true }), paint);
+		// fails_when: a long error blows the one-line row (the 80-char cap is dropped)
+		expect(out).toBe(` ${ERROR(`✗ ${first.slice(0, 79)}…`)}`);
+	});
+
+	it("AC-2: expanded shows the error body with blank runs collapsed", () => {
+		const model = editRow.spec.build({
+			content: [{ type: "text", text: "Error: oldText not found.\n\n\n\nCheck the file and retry." }],
+		});
+		const out = editRow.spec.project(model, view({ isError: true, expanded: true }), paint);
+		// fails_when: the expanded error body is blank, untrimmed, or the wrong role
+		expect(out).toBe([ERROR("Error: oldText not found."), "", ERROR("Check the file and retry.")].join("\n"));
+	});
+
+	it("AC-5: every escape in every state is a paint marker", () => {
+		const states = [
+			editRow.spec.project(editRow.spec.build(RESULT), view(), paint),
+			editRow.spec.project(editRow.spec.build(RESULT), view({ expanded: true }), paint),
+			editRow.spec.project(editRow.spec.build(ERROR_RESULT), view({ isError: true }), paint),
+			editRow.spec.project(editRow.spec.build(ERROR_RESULT), view({ isError: true, expanded: true }), paint),
+			editRow.spec.project(editRow.spec.build(DIFFLESS_RESULT), view(), paint),
+			editRow.spec.project(editRow.spec.build(DIFFLESS_RESULT), view({ expanded: true }), paint),
+		];
+		// fails_when: a hardcoded colour appears (this catches it; so does the source scan below)
+		for (const out of states) {
+			assertNoRealEscapes(out);
+		}
+	});
+});
+
+/* ── source contract ─────────────────────────────────────────────────── */
+
+const SOURCE = readFileSync(fileURLToPath(new URL("./edit.ts", import.meta.url)), "utf8");
+
+describe("edit row spec — source contract", () => {
+	it("AC-3: the port carries no registration, execute wrapper, or model-facing text", () => {
+		const forbidden = [
+			{ pattern: /\bregisterTool\s*\(/, what: "a tool-name registration" },
+			{ pattern: /\bexecute\s*[(:]/, what: "an execute wrapper" },
+			{ pattern: /\b(?:promptSnippet|promptGuidelines|systemPrompt|description)\b/, what: "model-facing text" },
+			{ pattern: /\bas\s+unknown\s+as\b/, what: "an `as unknown as` cast" },
+		];
+		// fails_when: the port smuggles execution or model-facing text back in
+		expect(forbidden.filter(({ pattern }) => pattern.test(SOURCE)).map(({ what }) => what)).toEqual([]);
+	});
+
+	it("AC-3: the spec imports the type contract and nothing that can execute", () => {
+		const specifiers = [...SOURCE.matchAll(/from\s+"([^"]+)"/g)].map((match) => match[1] ?? "");
+		// fails_when: the spec grows a host, filesystem, or sibling-lane import
+		expect(specifiers).toEqual(["node:path", "../../../core/types.ts"]);
+	});
+
+	it("AC-5: no escape literal in the row source — the scan half", () => {
+		// biome-ignore lint/suspicious/noControlCharactersInRegex: the ESC introducer is what the scan looks for
+		const ESCAPE = /\\x1[bB]|\\u001[bB]|\u001b/;
+		// fails_when: a colour is hardcoded instead of coming from a paint role
+		expect(ESCAPE.test(SOURCE)).toBe(false);
+	});
+});

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

@@ -0,0 +1,213 @@
+// ported from pi-pretty-tui/src/features/edit-write-collapse/render.ts (EDIT half) — survives because:
+// the host builtin edit already returns `details.diff` (recorded: @earendil-works/pi-coding-agent@1.0.4,
+// dist/core/tools/edit.js:132), so the collapsed count summary and the expanded diff need no
+// registration; the registration, its execute wrapper and its model instructions stay behind.
+
+/**
+ * edit.ts — the `edit` row: collapsed changed-line counts, expanded diff.
+ *
+ * Boundary: `details` and the result content blocks are host payloads, so both are narrowed by
+ * `isRecord` before a field is read; args are read as strings, and only once `argsComplete`.
+ *
+ * shape: none — dispatch object does not apply: one tool name, no discriminator. The export below is
+ * trigger #7 (fixed-shape record, fields known statically); `TONE_ROLE` declares its own shape.
+ */
+
+import { relative } from "node:path";
+import type {
+	CallModel,
+	ModuleDescriptor,
+	RenderContext,
+	RowPaint,
+	RowSpec,
+	RowView,
+	ToolResult,
+} from "../../../core/types.ts";
+
+const TOOL = "edit";
+const PENDING = "pending";
+const UNAVAILABLE = "diff unavailable";
+const ADDED_MARK = "+";
+/** U+2212: a hyphen would read as diff-body text, not as a count. */
+const REMOVED_MARK = "−";
+const ERROR_MARK = "✗";
+const ELLIPSIS = "…";
+const MAX_ERROR_SUMMARY = 80;
+
+type DiffTone = "added" | "removed" | "context";
+
+interface DiffLine {
+	tone: DiffTone;
+	/** The host's line verbatim, sign and line number included. */
+	text: string;
+}
+
+interface DiffModel {
+	lines: readonly DiffLine[];
+	added: number;
+	removed: number;
+}
+
+interface EditModel {
+	/** Result text blocks joined; the error body and the diff-less fallback read it. */
+	text: string;
+	/** Absent when the result carried no diff — the host streams none until the edit lands. */
+	diff?: DiffModel;
+}
+
+/** Diff tones map straight onto the host toolDiff* tokens (paint exposes them as roles). */
+// shape: dispatch object — trigger #1, three tones → three stateless role lookups.
+const TONE_ROLE = {
+	added: "diffAdded",
+	removed: "diffRemoved",
+	context: "diffContext",
+} as const satisfies Record<DiffTone, keyof RowPaint>;
+
+// shape: none — one straight-line parse; the branch is a boundary check, not a discriminator.
+function build(result: ToolResult): EditModel {
+	const text = resultText(result);
+	const diff = diffOf(result.details);
+	return diff === undefined ? { text } : { text, diff: parseDiff(diff) };
+}
+
+// shape: none — one pass; the tone branch is a two-value classification of the line's first character.
+function parseDiff(diff: string): DiffModel {
+	const lines: DiffLine[] = [];
+	let added = 0;
+	let removed = 0;
+	for (const raw of normalizeLineEndings(diff).split("\n")) {
+		const tone = toneOf(raw);
+		if (tone === "added") added += 1;
+		else if (tone === "removed") removed += 1;
+		lines.push({ tone, text: raw });
+	}
+	return { lines, added, removed };
+}
+
+function toneOf(line: string): DiffTone {
+	if (line.startsWith("+")) return "added";
+	if (line.startsWith("-")) return "removed";
+	return "context";
+}
+
+/** The host's own edit call line is name + short path; the args gate keeps a half-streamed path out. */
+// shape: none — single collapsed-title builder; no dispatch over a discriminator.
+function buildCall(args: Record<string, unknown>, ctx: RenderContext): CallModel {
+	const path = ctx.argsComplete === false ? undefined : pathOf(args);
+	return { title: path === undefined ? TOOL : `${TOOL}: ${displayPath(ctx.cwd, path)}` };
+}
+
+// shape: none — three view-state branches of straight-line text; no dispatch over a discriminator value.
+function project(m: EditModel, view: RowView, paint: RowPaint): string {
+	if (view.isError) {
+		const lines = errorLines(m.text);
+		return view.expanded ? errorBody(lines, paint) : errorSummary(lines, paint);
+	}
+	const diff = m.diff;
+	// A diff-less result reads pending collapsed (the predecessor's port) but shows its text expanded.
+	if (diff === undefined) return view.expanded ? fallbackBody(m.text, paint) : pendingSuffix(paint);
+	return view.expanded ? diffBody(diff.lines, paint) : countsSuffix(diff, paint);
+}
+
+/** The runtime draws this body on its own line under the call line; the one-space lead is the
+    predecessor's tool-body indent (TOOL_RESULT_INDENT), so the counts read as the title's subordinate. */
+function countsSuffix(diff: DiffModel, paint: RowPaint): string {
+	return ` ${paint.diffAdded(`${ADDED_MARK}${diff.added}`)} ${paint.diffRemoved(`${REMOVED_MARK}${diff.removed}`)}`;
+}
+
+function pendingSuffix(paint: RowPaint): string {
+	return ` ${paint.muted(`· ${PENDING}`)}`;
+}
+
+function errorSummary(lines: readonly string[], paint: RowPaint): string {
+	const first = (lines.find((line) => line.trim() !== "") ?? "Error").trim();
+	const summary = first.length > MAX_ERROR_SUMMARY ? `${first.slice(0, MAX_ERROR_SUMMARY - 1)}${ELLIPSIS}` : first;
+	return ` ${paint.error(`${ERROR_MARK} ${summary}`)}`;
+}
+
+function errorBody(lines: readonly string[], paint: RowPaint): string {
+	return lines.map((line) => (line === "" ? "" : paint.error(line))).join("\n");
+}
+
+function diffBody(lines: readonly DiffLine[], paint: RowPaint): string {
+	return lines.map((line) => paint[TONE_ROLE[line.tone]](line.text)).join("\n");
+}
+
+function fallbackBody(text: string, paint: RowPaint): string {
+	const rows = [paint.muted(UNAVAILABLE)];
+	const raw = normalizeLineEndings(text).trim();
+	if (raw !== "") rows.push(...raw.split("\n").map((line) => paint.output(line)));
+	return rows.join("\n");
+}
+
+/** `details` is a host payload: the diff is read only when it is a string. */
+function diffOf(details: unknown): string | undefined {
+	if (!isRecord(details)) return undefined;
+	const diff = details.diff;
+	return typeof diff === "string" ? diff : undefined;
+}
+
+/** Only text blocks with a string body contribute; a malformed block is skipped, never thrown on. */
+function resultText(result: ToolResult): string {
+	const blocks = result.content;
+	if (!Array.isArray(blocks)) return "";
+	const parts: string[] = [];
+	for (const block of blocks) {
+		if (isRecord(block) && block.type === "text" && typeof block.text === "string") parts.push(block.text);
+	}
+	return parts.join("\n");
+}
+
+/** The host builtin's schema is `path`; `file_path` is the predecessor's legacy spelling. */
+function pathOf(args: Record<string, unknown> | undefined): string | undefined {
+	return stringArg(args, "path") ?? stringArg(args, "file_path");
+}
+
+function stringArg(args: Record<string, unknown> | undefined, key: string): string | undefined {
+	const value = args?.[key];
+	return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+/** The predecessor's shortPath without its HOME arm: a spec reads no env, so only cwd shortens. */
+function displayPath(cwd: string | undefined, raw: string): string {
+	if (cwd === undefined) return raw;
+	const rel = relative(cwd, raw);
+	return rel === "" || rel.startsWith("..") ? raw : rel;
+}
+
+/**
+ * Predecessor renderToolError: CRLF normalized, outer blanks trimmed, blank runs collapsed; a payload
+ * with no text reads "Error" so a failed call never renders blank.
+ */
+function errorLines(text: string): readonly string[] {
+	const lines: string[] = [];
+	for (const line of normalizeLineEndings(text).trim().split("\n")) {
+		if (line === "" && lines[lines.length - 1] === "") continue;
+		lines.push(line);
+	}
+	return lines[0] === "" ? ["Error"] : lines;
+}
+
+function normalizeLineEndings(text: string): string {
+	return text.replace(/\r\n?/g, "\n");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+const descriptor: ModuleDescriptor = {
+	key: "row.edit",
+	name: "Edit row",
+	defaultEnabled: true,
+	settings: [],
+};
+
+// shape: object literal satisfying the lane's fixed-shape record — trigger #7; the spec holds no
+//   closure state, so trigger #4 does not apply.
+export const editRow = {
+	name: TOOL,
+	// An `edit` result is either a diff or text and both render, so build never returns "unknown".
+	spec: { buildCall, build, project } satisfies RowSpec<EditModel>,
+	descriptor,
+};

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

@@ -0,0 +1,173 @@
+/**
+ * ls.test.ts — the ls row judged at its seam: buildCall's argument gate, build's content parse, and
+ * project's collapsed count / expanded tree under the marker paint.
+ *
+ * Every assertion drives the exported `lsRow.spec`, the same object the resolver table hands the
+ * runtime; module internals are never imported.
+ */
+
+// shape: fixtures + pinned goldens — trigger #7, a fixed set of result shapes, each with its literal
+//   expected row; a fixture framework or a table-driven runner would be ceremony over five strings.
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { assertNoRealEscapes, markerPaint, testRenderContext } from "../../../../test/fakes/index.ts";
+import type { ToolResult } from "../../../core/types/host.ts";
+import type { RowView } from "../types.ts";
+import type { LsModel } from "./ls.ts";
+import { lsRow } from "./ls.ts";
+
+const PAINT = markerPaint();
+const INDENT = "  ";
+const COLLAPSED: RowView = { expanded: false, isError: false, isPartial: false };
+const EXPANDED: RowView = { expanded: true, isError: false, isPartial: false };
+
+// Golden wraps recorded-from test/fakes/paint.ts MARKER_CODES (T-11, 2026-10-06): each role frames its
+// text in its own escape pair, so a dropped, reordered or wrong-role marker fails the golden.
+const muted = (text: string): string => `\u001b[38;5;202m${text}\u001b[38;5;222m`;
+const gutter = (text: string): string => `\u001b[38;5;206m${text}\u001b[38;5;226m`;
+const accent = (text: string): string => `\u001b[38;5;203m${text}\u001b[38;5;223m`;
+const error = (text: string): string => `\u001b[38;5;204m${text}\u001b[38;5;224m`;
+
+// Fixture provenance — shape recorded-from @earendil-works/pi-coding-agent@1.0.4
+//   dist/core/tools/ls.js:90-108 (read 2026-10-06): ONE text block whose lines are "<name>", a
+//   directory carrying a trailing "/", sorted case-insensitively.
+// Fixture provenance — entries invented: the concrete names only drive the tree layout; any real
+//   listing has this identical shape.
+const LISTING = "docs/\npackage.json\nREADME.md\nsrc/\nvitest.config.ts";
+const RESULT: ToolResult = { content: [{ type: "text", text: LISTING }] };
+
+/** Drives the seam the way the runtime does: parse once through build, then project. */
+function parse(result: ToolResult): LsModel {
+	const model = lsRow.spec.build(result, testRenderContext());
+	if (model === "unknown") throw new Error("fixture did not parse as an ls result");
+	return model;
+}
+
+function title(args: Record<string, unknown>, cwd: string, argsComplete = true): string {
+	const ctx = testRenderContext({ args, cwd, argsComplete });
+	return lsRow.spec.buildCall(args, ctx).title;
+}
+
+describe("lsRow.spec.buildCall — the call line", () => {
+	it("AC-1: a path inside cwd reads relative, and the limit rides along", () => {
+		const shown = title({ path: "/Users/dev/repo/src", limit: 20 }, "/Users/dev/repo");
+		// fails_when: the call line drops the path, shows an absolute path, or hides the limit
+		expect(shown).toBe("ls src (limit 20)");
+	});
+
+	it("AC-4: until argsComplete the title is the tool name only", () => {
+		const ctx = testRenderContext({ argsComplete: false, args: {}, cwd: "/Users/dev/repo" });
+		// fails_when: a partial or already-streamed argument value reaches the call line
+		expect(lsRow.spec.buildCall({ path: "/Users/dev/repo/src" }, ctx).title).toBe("ls");
+	});
+
+	it("AC-1: a relative argument reads as written; a path outside cwd is home-shortened", () => {
+		const outside = join(homedir(), "elsewhere", "notes");
+		// fails_when: a relative argument is joined against the wrong base, or an outside path stays absolute
+		expect(title({ path: "src" }, "/Users/dev/repo")).toBe("ls src");
+		expect(title({ path: outside }, "/Users/dev/repo")).toBe("ls ~/elsewhere/notes");
+	});
+});
+
+describe("lsRow.spec — the result projection", () => {
+	it("AC-1: the canonical listing renders the golden collapsed summary and expanded tree", () => {
+		const collapsed = lsRow.spec.project(parse(RESULT), COLLAPSED, PAINT);
+		const expanded = lsRow.spec.project(parse(RESULT), EXPANDED, PAINT);
+		// fails_when: a plausible-looking row renders the wrong count, a missing tree, or a directory as a file
+		expect(collapsed).toBe(muted("5 entries · ctrl+o to expand"));
+		expect(expanded).toBe(
+			[
+				muted("5 entries"),
+				"",
+				`${INDENT}${gutter("├── ")}${accent("docs")}`,
+				`${INDENT}${gutter("├── ")}package.json`,
+				`${INDENT}${gutter("├── ")}README.md`,
+				`${INDENT}${gutter("├── ")}${accent("src")}`,
+				`${INDENT}${gutter("└── ")}vitest.config.ts`,
+			].join("\n"),
+		);
+		const one = lsRow.spec.project(parse({ content: [{ type: "text", text: "src/" }] }), COLLAPSED, PAINT);
+		// fails_when: the summary reads "1 entries"
+		expect(one).toBe(muted("1 entry · ctrl+o to expand"));
+	});
+
+	it("AC-2: an error result puts the first error line on the collapsed row and the body when expanded", () => {
+		// invented: the host rejects ls with one line (ls.js:60,66,71); two message lines plus a blank
+		// run is the multi-line error shape the row must still fold into one collapsed line.
+		const failed: ToolResult = {
+			content: [{ type: "text", text: "Path not found: /nope\ncheck the path and retry\n\n\nmore detail" }],
+		};
+		const model = parse(failed);
+		// fails_when: errors render blank, render their body collapsed, or crash the row
+		expect(lsRow.spec.project(model, { ...COLLAPSED, isError: true }, PAINT)).toBe(
+			`${error("Path not found: /nope")}${muted(" · ctrl+o to expand")}`,
+		);
+		expect(lsRow.spec.project(model, { ...EXPANDED, isError: true }, PAINT)).toBe(
+			[
+				`${INDENT}${error("Path not found: /nope")}`,
+				`${INDENT}${error("check the path and retry")}`,
+				"",
+				`${INDENT}${error("more detail")}`,
+			].join("\n"),
+		);
+	});
+
+	it("AC-1: past the preview cap the tree ends in a count, not a last-entry connector", () => {
+		// invented: the host caps at 500 entries (ls.js:22), so the predecessor's 80-line render cap is
+		// what triggers the fold; the names only need to be 85 distinct entries.
+		const many = Array.from({ length: 85 }, (_, i) => `f${String(i).padStart(2, "0")}.ts`).join("\n");
+		const lines = lsRow.spec.project(parse({ content: [{ type: "text", text: many }] }), EXPANDED, PAINT).split("\n");
+		// fails_when: a truncated tree claims a final entry, or the hidden count is absent or wrong
+		expect(lines).toHaveLength(83);
+		expect(lines[81]).toBe(`${INDENT}${gutter("├── ")}f79.ts`);
+		expect(lines[82]).toBe(`${INDENT}${gutter("└── ")}${muted("… 5 more entries")}`);
+	});
+
+	it("AC-1: a result with no text content is unknown, so the runtime degrades to the raw row", () => {
+		// fails_when: an empty result renders a plausible-but-empty ls row
+		expect(lsRow.spec.build({ content: [] }, testRenderContext())).toBe("unknown");
+		expect(lsRow.spec.build({}, testRenderContext())).toBe("unknown");
+		expect(lsRow.spec.build({ content: [{ type: "text", text: "  \n " }] }, testRenderContext())).toBe("unknown");
+		expect(lsRow.spec.build({ content: [{ type: "image" }] }, testRenderContext())).toBe("unknown");
+	});
+});
+
+describe("lsRow — the render-only and paint-only contracts", () => {
+	// recorded-from: src/renderers/tool/specs/ls.ts, read from disk at test time.
+	const SOURCE = readFileSync(new URL("./ls.ts", import.meta.url), "utf8");
+
+	it("AC-3: the ported source carries no execute wrapper and no model-facing text", () => {
+		const patterns = [
+			/\bregisterTool\b/,
+			/\bexecute\s*[:(]/,
+			/\bwrapExecuteWithMetrics\b/,
+			/\bpromptSnippet\b/,
+			/\bsnippet\b/,
+			/\bdescription\s*:/,
+			/\bparameters\s*:/,
+		];
+		// fails_when: the port smuggles a registration, an execute wrapper, or prompt text back in
+		expect(patterns.filter((pattern) => pattern.test(SOURCE)).map(String)).toEqual([]);
+	});
+
+	it("AC-5: every escape project emits is a paint marker, and the source holds none", () => {
+		const outputs = [
+			lsRow.spec.project(parse(RESULT), COLLAPSED, PAINT),
+			lsRow.spec.project(parse(RESULT), EXPANDED, PAINT),
+			lsRow.spec.project(parse(RESULT), { ...EXPANDED, isError: true }, PAINT),
+		];
+		for (const output of outputs) assertNoRealEscapes(output);
+		// biome-ignore lint/suspicious/noControlCharactersInRegex: the escape introducer is exactly what we scan for
+		const escapeLiteral = /\\x1[bB]|\\u001[bB]|\u001b/;
+		// fails_when: a hardcoded color or reset ships in the spec instead of a paint role
+		expect(escapeLiteral.test(SOURCE)).toBe(false);
+	});
+
+	it("AC-5: the descriptor defaults the row on, with no settings", () => {
+		// fails_when: T-28 registers a row under an unexpected key, or one that starts disabled
+		expect(lsRow.name).toBe("ls");
+		expect(lsRow.descriptor).toEqual({ key: "row.ls", name: "Ls row", defaultEnabled: true, settings: [] });
+	});
+});