@zenodinh/pi-render 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,296 @@
+// ported from pi-pretty-tui/src/tools/read.ts — survives because: the compact row (skill header, docs
+// label, short path, line count) and the numbered range body are drawing logic, and none of it needed
+// the registration, the execute wrapper, the injected details or the metrics wrapper it lived in; the
+// raw escapes it drew with move to project-time paint. Two port bugs die here: the predecessor numbered
+// lines from a 0-based offset (it echoed the host's `offset` untranslated) and counted the host's own
+// continuation notice as a source line.
+
+/**
+ * read.ts — the read row: a compact file summary, and the numbered range when expanded.
+ *
+ * Boundary: the result's content blocks, `details` and the tool arguments are host payloads; each is
+ * narrowed by a predicate below before a field is read, and a result with no text block returns
+ * "unknown" so the runtime degrades to its raw row instead of drawing a plausible-but-empty one.
+ *
+ * No highlighting: a shiki engine reaches a row only through an injected dependency, and RowSpec has no
+ * deps parameter. Async highlight belongs to the runtime's decorate seam (its invalidate + staleness
+ * token), which this spec leaves unclaimed — plain numbered content stays readable and keeps `project`
+ * synchronous and allocation-light, as it re-runs on every frame.
+ *
+ * shape: none — dispatch object does not apply: the spec is one fixed record of three functions, with
+ * no discriminator and no state to close over. ReadModel and HEADER below declare their own shapes.
+ */
+
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import type {
+	CallModel,
+	ModuleDescriptor,
+	RenderContext,
+	RowPaint,
+	RowSpec,
+	RowView,
+	ToolResult,
+} from "../../../core/types.ts";
+
+/** Which of the three header shapes the row draws. */
+type HeaderKind = "path" | "docs" | "skill";
+
+/** What build parsed once: a failed read's body, or a file range with its classified header. */
+// shape: type + object literals — trigger #7, two closed parse outcomes; a region one outcome lacks is
+// `T | undefined` (trigger #8) rather than a field the other outcome has to invent.
+type ReadModel =
+	| { kind: "error"; label: string; lines: string[] }
+	| {
+			kind: "file";
+			header: HeaderKind;
+			/** Skill name, docs label, or cwd-shortened path; "" when the host sent no path. */
+			label: string;
+			/** 1-indexed number of the first shown line. */
+			offset: number;
+			lines: string[];
+			/** The host's own continuation notice, when it cut the read short. */
+			notice: string | undefined;
+	  };
+
+type FileModel = Extract<ReadModel, { kind: "file" }>;
+type ErrorModel = Extract<ReadModel, { kind: "error" }>;
+
+/** One metadata line is the collapse-first contract; a longer message is the expanded body's job. */
+const SUMMARY_MAX = 120;
+
+/** The host's user-limit notice — the one trailer it appends with no details.truncation block (read.js:132-137). */
+const MORE_LINES_NOTICE = /^\[\d+ more lines in file\. Use offset=\d+ to continue\.\]$/;
+
+/** The lead text per classification, one stateless painter each. */
+// shape: dispatch object — trigger #1, three branches on `header`, handlers stateless.
+const HEADER: Record<HeaderKind, (paint: RowPaint) => string> = {
+	path: (paint) => paint.title("→ read"),
+	docs: (paint) => paint.title("→ read docs"),
+	skill: (paint) => paint.accent("[skill]"),
+};
+
+/**
+ * The call line is the tool name only: the predecessor's read call slot was intentionally blank (the
+ * summary is the result slot's job), and this spec draws that summary itself — a path here would print
+ * twice on every collapsed row.
+ */
+function buildCall(): CallModel {
+	return { title: "read" };
+}
+
+function build(result: ToolResult, ctx: RenderContext): ReadModel | "unknown" {
+	const path = argString(ctx.args, "path");
+	if (failed(result, ctx)) {
+		const lines = compact(textOf(result) ?? "");
+		return {
+			kind: "error",
+			label: path === undefined ? "" : shortPath(ctx.cwd, path),
+			lines: lines.length > 0 ? lines : ["failed"],
+		};
+	}
+	const text = textOf(result);
+	if (text === undefined) return "unknown";
+	const content = normalize(text);
+	const split = splitNotice(content, truncatedBody(result.details));
+	const classified = classify(path, ctx.cwd, content);
+	return {
+		kind: "file",
+		header: classified.header,
+		label: classified.label,
+		offset: argOffset(ctx.args),
+		lines: trimTrailing(split.body.split("\n")),
+		notice: split.notice,
+	};
+}
+
+function project(m: ReadModel, view: RowView, paint: RowPaint): string {
+	if (m.kind === "error") return view.expanded ? errorBody(m, paint) : errorSummary(m, paint);
+	return view.expanded ? fileBody(m, paint) : fileSummary(m, paint);
+}
+
+/** `→ read <label>` / `→ read docs <label>` / `[skill] <name>`, with the range when the read starts late. */
+function header(m: FileModel, paint: RowPaint): string {
+	const range = m.offset > 1 ? paint.muted(`:${m.offset}`) : "";
+	const label = m.label === "" ? "" : ` ${paint.title(m.label)}`;
+	return `${HEADER[m.header](paint)}${label}${range}`;
+}
+
+function fileSummary(m: FileModel, paint: RowPaint): string {
+	const lines = m.lines.length;
+	return `${header(m, paint)} ${paint.muted(`${lines} ${lines === 1 ? "line" : "lines"} — ctrl+o to expand`)}`;
+}
+
+function fileBody(m: FileModel, paint: RowPaint): string {
+	// A fixed gutter width keeps the numbers aligned across frames; 3 is the predecessor's floor.
+	const width = Math.max(3, String(m.offset + m.lines.length - 1).length);
+	const numbered = m.lines.map(
+		(line, index) =>
+			`${paint.gutter(String(m.offset + index).padStart(width, " "))} ${paint.muted("│")} ${paint.output(line)}`,
+	);
+	const hint = m.header === "skill" ? ` ${paint.muted("ctrl+o to collapse")}` : "";
+	const notice = m.notice === undefined ? [] : [paint.warning(m.notice)];
+	return [header(m, paint) + hint, ...numbered, ...notice].join("\n");
+}
+
+function errorSummary(m: ErrorModel, paint: RowPaint): string {
+	const first = m.lines.find((line) => line.trim() !== "") ?? "failed";
+	const message = first.length > SUMMARY_MAX ? `${first.slice(0, SUMMARY_MAX - 1)}…` : first;
+	const label = m.label === "" ? "" : ` ${paint.title(m.label)}`;
+	return `${paint.error("→ read")}${label} ${paint.error(message)}`;
+}
+
+function errorBody(m: ErrorModel, paint: RowPaint): string {
+	return m.lines.map((line) => (line === "" ? "" : paint.error(line))).join("\n");
+}
+
+/** The host flags a failed call on the result and on the render context; either one means an error row. */
+function failed(result: ToolResult, ctx: RenderContext): boolean {
+	return result.isError === true || ctx.isError === true;
+}
+
+/** boundary: arguments are host payloads; only a non-empty string is a path. */
+function argString(args: Record<string, unknown> | undefined, key: string): string | undefined {
+	const value = args?.[key];
+	return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+/** boundary: offset is 1-indexed host input; anything else means the read started at line 1. */
+function argOffset(args: Record<string, unknown> | undefined): number {
+	const value = args?.offset;
+	return typeof value === "number" && Number.isInteger(value) && value > 1 ? value : 1;
+}
+
+/** boundary: a content block is a host payload; only a "text" block with a string body is readable. */
+function textBlock(value: unknown): string | undefined {
+	if (typeof value !== "object" || value === null) return undefined;
+	if (!("type" in value) || value.type !== "text") return undefined;
+	if (!("text" in value)) return "";
+	return typeof value.text === "string" ? value.text : "";
+}
+
+/** The joined text of the result's text blocks; undefined when the result carries none. */
+function textOf(result: ToolResult): string | undefined {
+	const blocks: unknown = result.content;
+	if (!isUnknownArray(blocks)) return undefined;
+	const texts: string[] = [];
+	for (const block of blocks) {
+		const text = textBlock(block);
+		if (text !== undefined) texts.push(text);
+	}
+	return texts.length === 0 ? undefined : texts.join("\n");
+}
+
+/** boundary: an array-shaped host payload stays `unknown[]`, so every element is narrowed on read. */
+function isUnknownArray(value: unknown): value is unknown[] {
+	return Array.isArray(value);
+}
+
+/** boundary: details is a host payload; the body the host cut is readable only as a string field. */
+function truncatedBody(details: unknown): string | undefined {
+	if (typeof details !== "object" || details === null) return undefined;
+	if (!("truncation" in details)) return undefined;
+	const truncation = details.truncation;
+	if (typeof truncation !== "object" || truncation === null) return undefined;
+	if (!("content" in truncation)) return undefined;
+	return typeof truncation.content === "string" ? truncation.content : undefined;
+}
+
+/**
+ * Separates the body from the host's trailing notice, so the notice is never numbered as a source line.
+ * `body` is the cut body from details when there is one; the user-limit notice has no details block and
+ * is recognized by its own wording.
+ */
+function splitNotice(text: string, body: string | undefined): { body: string; notice: string | undefined } {
+	if (body !== undefined && text.startsWith(body)) {
+		const notice = text.slice(body.length).trim();
+		return { body, notice: notice === "" ? undefined : notice };
+	}
+	const at = text.lastIndexOf("\n\n[");
+	const notice = at === -1 ? "" : text.slice(at + 2).trim();
+	return MORE_LINES_NOTICE.test(notice) ? { body: text.slice(0, at), notice } : { body: text, notice: undefined };
+}
+
+/** A trailing newline is a line terminator, not a last line. */
+function trimTrailing(lines: string[]): string[] {
+	let end = lines.length;
+	while (end > 0 && lines[end - 1] === "") end -= 1;
+	return end === lines.length ? lines : lines.slice(0, end);
+}
+
+/** CRLF files would otherwise leave a stray \r at every line end (P helpers.ts:12-14). */
+function normalize(text: string): string {
+	return text.replace(/\r\n?/g, "\n");
+}
+
+/** Runs of blank lines are noise on an error body; one blank line keeps paragraphs apart (P helpers.ts:63-72). */
+function compact(text: string): string[] {
+	const out: string[] = [];
+	for (const line of text.trim().split("\n")) {
+		if (line.trim() === "" && out[out.length - 1]?.trim() === "") continue;
+		out.push(line);
+	}
+	return trimTrailing(out);
+}
+
+/** The row's header text: a skill name, a docs label, or the shortened path (P read.ts:25-60). */
+function classify(
+	path: string | undefined,
+	cwd: string | undefined,
+	content: string,
+): { header: HeaderKind; label: string } {
+	if (path === undefined) return { header: "path", label: "" };
+	if (basename(path) === "SKILL.md") return { header: "skill", label: skillName(path, content) };
+	const docs = docsLabel(path, cwd);
+	return docs === undefined ? { header: "path", label: shortPath(cwd, path) } : { header: "docs", label: docs };
+}
+
+/**
+ * Inside the tree the tool ran in, the root README and `docs/`, `examples/` read as a docs row
+ * (P read.ts:25-33) — anchored at the tool's cwd here: the predecessor compared against the pi package
+ * root through `getReadmePath()`, a host import this render-only spec may not make.
+ */
+function docsLabel(path: string, cwd: string | undefined): string | undefined {
+	if (cwd === undefined) return undefined;
+	const inside = relative(cwd, resolve(cwd, path));
+	if (inside === "" || inside === ".." || inside.startsWith(`..${sep}`)) return undefined;
+	const label = inside.split(sep).join("/");
+	return label === "README.md" || label.startsWith("docs/") || label.startsWith("examples/") ? label : undefined;
+}
+
+/** SKILL.md's frontmatter `name:`, else its directory name (P read.ts:36-55). */
+function skillName(path: string, content: string): string {
+	const fallback = basename(dirname(path));
+	const lines = content.split("\n");
+	if (lines[0]?.trim() !== "---") return fallback;
+	const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+	for (const line of lines.slice(1, end === -1 ? 1 : end)) {
+		const match = /^name\s*:\s*(.+?)\s*$/.exec(line);
+		if (match === null) continue;
+		const value = (match[1] ?? "").trim();
+		const quoted = (value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"));
+		const name = quoted ? value.slice(1, -1).trim() : value;
+		return name === "" ? fallback : name;
+	}
+	return fallback;
+}
+
+/** The row shows a path the way the reader thinks of it: relative while the read is inside the tool's cwd. */
+function shortPath(cwd: string | undefined, path: string): string {
+	if (cwd === undefined) return path;
+	const absolute = resolve(cwd, path);
+	const inside = relative(cwd, absolute);
+	return inside !== "" && !inside.startsWith("..") && !isAbsolute(inside) ? inside : absolute;
+}
+
+/** The read row spec, keyed in the resolver's table by the host's own tool name. */
+// shape: none — one record of three fixed functions over the two parse outcomes above; no branch chain
+// is left for a dispatch object (the error/file split is the union, the header split is HEADER).
+export const readSpec: RowSpec<ReadModel> = { buildCall, build, project };
+
+/** The record T-28 composes: the table key, the spec, and the descriptor it registers. */
+// shape: object literal — trigger #7, the spec module record T-28 composes; fields are known statically.
+export const readRow: { name: string; spec: RowSpec<ReadModel>; descriptor: ModuleDescriptor } = {
+	name: "read",
+	spec: readSpec,
+	descriptor: { key: "row.read", name: "Read row", defaultEnabled: true, settings: [] },
+};

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

@@ -0,0 +1,197 @@
+// Fixture provenance:
+// - pi-fff fixtures (GREP_FFF, GREP_FFF_DETAILS, FUZZY, FIND_WEAK, D0..D2, and the parity bodies):
+//   invented — synthesized from pi-fff 0.11.0's formatting code via the DP4 dossier
+//   (system-analysis/working/dossier-dp4-search-fingerprints.md, 2026-10-06); no live capture exists.
+// - host fixtures (HOST_GREP): invented — synthesized from host pi 1.0.4 grep.js:206 (DP4 raw-data).
+// - the parity bodies are the format examples the predecessor parser pinned at
+//   pi-pretty-tui/src/core/fff-format.ts:12-18,31-41; it shipped no test file (verified — nothing in
+//   pi-pretty-tui imports parseGrepOutput/parseFindOutput), so AC-6 ports those expectations as fixtures.
+
+// shape: none — test module: every behavior is asserted only through the exported SEARCH_SPECS /
+// createSearchSpec seam.
+import { describe, expect, test } from "vitest";
+import { assertNoRealEscapes, markerPaint, testRenderContext } from "../../../../test/fakes/index.ts";
+import { createSearchSpec, SEARCH_SPECS, SEARCH_TOOL_NAMES, type SearchModel, type SearchToolName } from "./search.ts";
+
+const PAINT = markerPaint();
+const COLLAPSED = { expanded: false, isError: false, isPartial: false };
+const EXPANDED = { expanded: true, isError: false, isPartial: false };
+
+type MatchesModel = Extract<SearchModel, { kind: "matches" }>;
+type FilesModel = Extract<SearchModel, { kind: "files" }>;
+type EmptyModel = Extract<SearchModel, { kind: "empty" }>;
+
+function parse(name: SearchToolName, text: string, details: unknown, args: Record<string, unknown> = {}) {
+	const spec = createSearchSpec(name);
+	const row = testRenderContext({ args });
+	const invocation = row.result({ content: [{ type: "text", text }], details });
+	return { spec, model: spec.build(invocation.result, invocation.ctx) };
+}
+
+function narrowMatches(model: SearchModel | "unknown"): MatchesModel {
+	if (model === "unknown" || model.kind !== "matches") {
+		throw new Error(`expected a matches model, got ${JSON.stringify(model)}`);
+	}
+	return model;
+}
+
+function narrowFiles(model: SearchModel | "unknown"): FilesModel {
+	if (model === "unknown" || model.kind !== "files") {
+		throw new Error(`expected a files model, got ${JSON.stringify(model)}`);
+	}
+	return model;
+}
+
+function narrowEmpty(model: SearchModel | "unknown"): EmptyModel {
+	if (model === "unknown" || model.kind !== "empty") {
+		throw new Error(`expected an empty model, got ${JSON.stringify(model)}`);
+	}
+	return model;
+}
+
+const GREP_FFF = [
+	"src/payments.ts  [modified in git]",
+	" 1: export interface PaymentRequest {",
+	" 3: route(...)",
+	"",
+	"src/other.ts  [often touched file]",
+	" 7: const total = sum(payments)",
+].join("\n");
+const GREP_FFF_DETAILS = { totalMatched: 3, totalFiles: 2 };
+
+const HOST_GREP = ["src/payments.ts:1: export interface PaymentRequest {", "src/payments.ts:3: route(...)"].join("\n");
+
+const FUZZY = [
+	"[0 exact matches. Maybe you meant this?]",
+	"src/payments.ts",
+	" 1: export interface PaymentRequest {",
+].join("\n");
+
+const FIND_WEAK = [
+	"src/pay.ts",
+	"src/payments.ts",
+	"",
+	'[Query "p" produced only weak scattered fuzzy matches. Output capped at 5/30.]',
+].join("\n");
+
+// The totals pi-fff always attaches to the shapes above (DP4: FFF:1126-1131).
+const D0 = { totalMatched: 0, totalFiles: 0 };
+const D1 = { totalMatched: 1, totalFiles: 1 };
+const D2 = { totalMatched: 2, totalFiles: 2 };
+
+describe("renderers/tool/specs/search — pi-fff fingerprint rows", () => {
+	test("AC-1 a pi-fff grep result renders a grouped row with the file count and highlighted matches", () => {
+		// fails_when: raw text shown for a pi-fff result.
+		const { spec, model } = parse("ffgrep", GREP_FFF, GREP_FFF_DETAILS, { pattern: "route" });
+		const matches = narrowMatches(model);
+		expect(matches.matchCount).toBe(3);
+		expect(matches.blocks).toHaveLength(2);
+		expect(matches.blocks[0]?.path).toBe("src/payments.ts");
+		expect(matches.blocks[0]?.annotation).toBe("modified in git");
+
+		expect(spec.project(matches, COLLAPSED, PAINT)).toBe(PAINT.muted("3 matches in 2 files"));
+
+		const expanded = spec.project(matches, EXPANDED, PAINT);
+		expect(expanded).toContain(PAINT.muted("3 matches in 2 files"));
+		expect(expanded).toContain(PAINT.accent("src/payments.ts"));
+		expect(expanded).toContain(PAINT.muted("[modified in git]"));
+		expect(expanded).toContain(PAINT.match("route"));
+		assertNoRealEscapes(expanded);
+	});
+
+	test("AC-2 host builtin output is not pi-fff, so build returns unknown", () => {
+		// fails_when: host output gets pi-fff styling (a plausible-but-wrong row).
+		expect(parse("grep", HOST_GREP, undefined).model).toBe("unknown");
+		expect(parse("find", "src/payments.ts\ntest/payments.test.ts", undefined).model).toBe("unknown");
+	});
+
+	test("AC-3 the empty strings separate on details presence only", () => {
+		// fails_when: both render the same way.
+		const styled = narrowEmpty(parse("ffgrep", "No matches found", D0).model);
+		expect(styled.noun).toBe("matches");
+		const emptyRow = parse("ffgrep", "No matches found", D0);
+		expect(emptyRow.spec.project(styled, COLLAPSED, PAINT)).toBe(PAINT.muted("0 matches"));
+		expect(parse("ffgrep", "No matches found", undefined).model).toBe("unknown");
+
+		const files = narrowEmpty(parse("fffind", "No files found matching pattern", D0).model);
+		expect(files.noun).toBe("files");
+		expect(parse("fffind", "No files found matching pattern", undefined).model).toBe("unknown");
+	});
+
+	test("AC-4 the fuzzy prefix is a notice, never a phantom file header", () => {
+		// fails_when: a phantom header inflates the file count (the ported bug).
+		const matches = narrowMatches(parse("ffgrep", FUZZY, D1).model);
+		expect(matches.blocks).toHaveLength(1);
+		expect(matches.blocks[0]?.path).toBe("src/payments.ts");
+		expect(matches.notices).toEqual(["0 exact matches. Maybe you meant this?"]);
+	});
+
+	test("AC-5 a multi-sentence notice stays one notice", () => {
+		// fails_when: the weak-match notice fragments on its internal ". ".
+		const files = narrowFiles(parse("fffind", FIND_WEAK, { totalMatched: 30, totalFiles: 30 }).model);
+		expect(files.files).toHaveLength(2);
+		expect(files.notices).toEqual(['Query "p" produced only weak scattered fuzzy matches. Output capped at 5/30.']);
+	});
+
+	test("AC-1 (find) a pi-fff find result groups by directory with counts and annotations", () => {
+		// fails_when: entries render ungrouped, or a count or annotation is wrong.
+		const body = ["src/payments.ts", "test/payments.test.ts  [modified in git]", "src/api/payments.ts"].join("\n");
+		const { spec, model } = parse("fffind", body, { totalMatched: 3, totalFiles: 3 });
+		const files = narrowFiles(model);
+		expect(spec.project(files, COLLAPSED, PAINT)).toBe(PAINT.muted("3 files"));
+
+		const expanded = spec.project(files, EXPANDED, PAINT);
+		expect(expanded).toContain(PAINT.accent("src/"));
+		expect(expanded).toContain(PAINT.accent("src/api/"));
+		expect(expanded).toContain(PAINT.accent("test/"));
+		expect(expanded).toContain(PAINT.output("payments.test.ts"));
+		expect(expanded).toContain(PAINT.muted("[modified in git]"));
+		assertNoRealEscapes(expanded);
+	});
+});
+
+describe("renderers/tool/specs/search — AC-6 predecessor fff-format parity", () => {
+	test("find: bare path list, annotation suffix, empty string", () => {
+		expect(narrowFiles(parse("fffind", "src/payments.ts\ntest/payments.test.ts", D2).model).files).toHaveLength(2);
+		const annotated = narrowFiles(parse("fffind", "src/payments.ts  [modified in git]", D1).model);
+		expect(annotated.files[0]).toEqual({ path: "src/payments.ts", annotation: "modified in git" });
+		expect(narrowEmpty(parse("fffind", "No files found matching pattern", D0).model).noun).toBe("files");
+	});
+
+	test("grep: numbered match and context lines, file blocks, empty string", () => {
+		const body = ["src/payments.ts", " 2- export interface Payment {", " 3: route(...)", " 4- }"].join("\n");
+		const matches = narrowMatches(parse("ffgrep", body, D1).model);
+		expect(matches.matchCount).toBe(1);
+		expect(matches.blocks[0]?.lines.map((l) => [l.lineNo, l.isMatch])).toEqual([
+			[2, false],
+			[3, true],
+			[4, false],
+		]);
+		expect(narrowEmpty(parse("ffgrep", "No matches found", D0).model).noun).toBe("matches");
+	});
+
+	test("a notice trailer surfaces as one notice", () => {
+		const body = ["src/payments.ts", " 1: x", "", '[Continue with cursor="fff_c1" to continue]'].join("\n");
+		expect(narrowMatches(parse("ffgrep", body, D1).model).notices).toEqual([
+			'Continue with cursor="fff_c1" to continue',
+		]);
+	});
+});
+
+describe("renderers/tool/specs/search — name binding", () => {
+	test("SEARCH_SPECS carries exactly the four names, each buildCall titles its own name", () => {
+		expect(SEARCH_SPECS.map((record) => record.name)).toEqual(["find", "grep", "fffind", "ffgrep"]);
+		expect(SEARCH_TOOL_NAMES).toEqual(["find", "grep", "fffind", "ffgrep"]);
+		const row = testRenderContext({ args: { pattern: "x", path: "src" } });
+		for (const record of SEARCH_SPECS) {
+			expect(record.spec.buildCall(row.args ?? {}, row).title.startsWith(record.name)).toBe(true);
+		}
+		expect(new Set(SEARCH_SPECS.map((record) => record.descriptor.key))).toEqual(new Set(["row.search"]));
+	});
+
+	test("args gate: buildCall shows the name only until argsComplete", () => {
+		// fails_when: a partial argument value is rendered.
+		const row = testRenderContext({ args: {}, argsComplete: false });
+		expect(createSearchSpec("fffind").buildCall({}, row).title).toBe("fffind");
+	});
+});