pi-readseek 0.1.0

package/src/tool-prompt-metadata.ts

@@ -0,0 +1,76 @@
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize } from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
+
+const COMPACT_DESCRIPTIONS: Record<string, string> = {
+  "read.md": "Read text files/images by path; text has LINE:HASH anchors, images return attachments.",
+  "edit.md": "Edit existing text files using fresh LINE:HASH anchors from read, grep, search, or write.",
+  "grep.md": "Search file contents; non-summary results include LINE:HASH anchors for edits.",
+  "find.md": "Find files by glob, respecting .gitignore.",
+  "ls.md": "List one directory.",
+  "write.md": "Create or overwrite a file and return anchors.",
+  "sg.md": "Search code by AST pattern and return anchored matches.",
+};
+
+const COMPACT_GUIDELINES: Record<string, string[]> = {
+  "read.md": [
+    "Use read for file contents, images/screenshots, ranges, symbols, and edit anchors.",
+    "Use read for images; it returns attachments, so avoid OCR tools unless explicitly needed.",
+  ],
+  "edit.md": [
+    "Use edit with fresh LINE:HASH anchors for existing files.",
+    "Use edit replace only when anchored edits are impractical.",
+  ],
+  "grep.md": [
+    "Use grep for text search and edit-ready matching anchors.",
+    "Use grep summary mode when only file counts are needed.",
+  ],
+  "find.md": [
+    "Use find for recursive file discovery by glob.",
+  ],
+  "ls.md": [
+    "Use ls to list one directory, optionally with a glob filter.",
+  ],
+  "write.md": [
+    "Use write to create files or intentionally overwrite whole files.",
+    "Use edit rather than write for small changes to existing files.",
+  ],
+  "sg.md": [
+    "Use search for AST-shaped code patterns.",
+  ],
+};
+
+export interface ToolPromptMetadata {
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+}
+
+export function loadPrompt(promptUrl: URL): string {
+  return readFileSync(promptUrl, "utf-8")
+    .replaceAll("{{DEFAULT_MAX_LINES}}", String(DEFAULT_MAX_LINES))
+    .replaceAll("{{DEFAULT_MAX_BYTES}}", formatSize(DEFAULT_MAX_BYTES))
+    .trim();
+}
+
+export function firstPromptParagraph(prompt: string): string {
+  return prompt.split(/\n\s*\n/, 1)[0]?.trim() ?? prompt;
+}
+
+function promptFileName(promptUrl: URL): string {
+  return promptUrl.pathname.split("/").pop() ?? "";
+}
+
+export function defineToolPromptMetadata(options: {
+  promptUrl: URL;
+  promptSnippet: string;
+  promptGuidelines: string[];
+}): ToolPromptMetadata {
+  const prompt = loadPrompt(options.promptUrl);
+  const fileName = promptFileName(options.promptUrl);
+  const compactDescription = COMPACT_DESCRIPTIONS[fileName];
+  return {
+    description: compactDescription ?? firstPromptParagraph(prompt),
+    promptSnippet: options.promptSnippet,
+    promptGuidelines: COMPACT_GUIDELINES[fileName] ?? options.promptGuidelines,
+  };
+}

package/src/tui-diff-component.ts

@@ -0,0 +1,86 @@
+import type { Component } from "@earendil-works/pi-tui";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import type { DiffData } from "./diff-data.js";
+import { renderTuiDiff } from "./tui-diff-renderer.js";
+import { clampLineToWidth, normalizeWidth, type RendererTheme } from "./tui-render-utils.js";
+
+export interface DiffPreviewComponentOptions {
+	/**
+	 * Lines rendered before the diff body (e.g. tool summary, "pending edit"
+	 * header). Each entry is one logical line; the component is responsible
+	 * for clamping to the render-time width.
+	 */
+	prefixLines?: string[];
+	/**
+	 * Lines rendered after the diff body (e.g. trailing hints). Currently
+	 * unused but kept for symmetry.
+	 */
+	suffixLines?: string[];
+	/** Diff body data. */
+	diffData: DiffData;
+	/** Theme passed through to renderTuiDiff for color tinting. */
+	theme: RendererTheme;
+	/** Whether the diff body should render in expanded form. */
+	expanded: boolean;
+	/**
+	 * Optional fallback width used when render() receives an invalid width
+	 * (zero, negative, NaN). Defaults to 80.
+	 */
+	fallbackWidth?: number;
+}
+
+/**
+ * Self-rendering component for a tool's diff preview that defers wrapping
+ * decisions to the TUI render pass.
+ *
+ * `renderTuiDiff` (and the underlying `wrapWithHangingIndent` helper) need
+ * the real viewport width to choose between split / unified / compact / summary
+ * modes and to wrap long content rows with prefix-aligned continuation lines.
+ * Pi's `ToolRenderContext` does NOT carry the render-time width, so any
+ * pre-baked output is forced to assume a fallback (80 columns). This
+ * component holds the source data instead, then renders at the width pi's TUI
+ * actually passes in.
+ */
+export class DiffPreviewComponent implements Component {
+	private options: DiffPreviewComponentOptions;
+	private cachedWidth: number | undefined;
+	private cachedLines: string[] | undefined;
+
+	constructor(options: DiffPreviewComponentOptions) {
+		this.options = options;
+	}
+
+	update(options: DiffPreviewComponentOptions): void {
+		this.options = options;
+		this.invalidate();
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+
+	render(width: number): string[] {
+		const normalized = normalizeWidth(width, this.options.fallbackWidth ?? 80);
+		if (this.cachedLines && this.cachedWidth === normalized) return this.cachedLines;
+		const lines: string[] = [];
+		for (const prefix of this.options.prefixLines ?? []) {
+			for (const line of prefix.split("\n")) lines.push(clampLineToWidth(line, normalized));
+		}
+		const body = renderTuiDiff({
+			diffData: this.options.diffData,
+			width: normalized,
+			theme: this.options.theme,
+			expanded: this.options.expanded,
+		});
+		for (const line of body.lines) lines.push(line);
+		for (const suffix of this.options.suffixLines ?? []) {
+			for (const line of suffix.split("\n")) lines.push(clampLineToWidth(line, normalized));
+		}
+		// Final safety clamp: each rendered line must fit within the viewport.
+		const clamped = lines.map((line) => (visibleWidth(line) <= normalized ? line : clampLineToWidth(line, normalized)));
+		this.cachedLines = clamped;
+		this.cachedWidth = normalized;
+		return clamped;
+	}
+}

package/src/tui-diff-renderer.ts

@@ -0,0 +1,92 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+import type { DiffData, DiffEntry, DiffSpan } from "./diff-data.js";
+import { clampLineToWidth, clampLinesToWidth, normalizeWidth, wrapWithHangingIndent, type RendererTheme } from "./tui-render-utils.js";
+
+export type TuiDiffMode = "split" | "unified" | "compact" | "summary";
+export type RenderTuiDiffInput = { diffData: DiffData; width: number; theme: RendererTheme; expanded: boolean };
+export type RenderTuiDiffOutput = { mode: TuiDiffMode; width: number; lines: string[] };
+
+function hasOldSide(data: DiffData): boolean { return data.entries.some((e) => e.kind === "remove" || e.kind === "context"); }
+function chooseMode(width: number, data: DiffData): TuiDiffMode {
+  if (width < 24) return "summary";
+  if (width < 50) return "compact";
+  // Split mode wastes half the pane on pure-add diffs (pending creates,
+  // write to a new file) so fall back to unified when there is no old side.
+  if (width >= 100 && hasOldSide(data)) return "split";
+  return "unified";
+}
+function hunkCount(data: DiffData): number { return Math.max(1, data.blockRanges?.length ?? (data.entries.some((e) => e.kind === "add" || e.kind === "remove") ? 1 : 0)); }
+function compactHeader(data: DiffData): string { return `↳ diff +${data.stats.added} -${data.stats.removed}`; }
+function header(data: DiffData, mode: TuiDiffMode, width: number): string {
+  if (mode === "summary" && width <= 10) return `↳ diff +${data.stats.added}`;
+  const full = `${compactHeader(data)} • ${hunkCount(data)} hunk • 1 file • ${mode === "split" ? "split" : "unified"}`;
+  return visibleWidth(full) <= width ? full : clampLineToWidth(compactHeader(data), width);
+}
+function lineNo(entry: DiffEntry): string { return String(entry.kind === "add" ? entry.newLine : entry.kind === "remove" ? entry.oldLine : entry.kind === "context" ? entry.newLine : ""); }
+function gutterMarker(entry: DiffEntry): string { return entry.kind === "add" ? "+" : entry.kind === "remove" ? "-" : " "; }
+function textOf(entry: DiffEntry): string { return "text" in entry ? entry.text : ""; }
+function padRightVisual(line: string, width: number): string { const visible = visibleWidth(line); return visible >= width ? line : line + " ".repeat(width - visible); }
+function tint(theme: RendererTheme, entry: DiffEntry, text: string): string { return entry.kind === "add" ? theme.fg("success", text) : entry.kind === "remove" ? theme.fg("error", text) : theme.fg("toolOutput", text); }
+function spans(theme: RendererTheme, spans: DiffSpan[] | undefined, fallback: string): string { return spans?.map((s) => s.kind === "add" ? theme.fg("success", s.text) : s.kind === "remove" ? theme.fg("error", s.text) : s.text).join("") ?? fallback; }
+function inlineText(input: RenderTuiDiffInput, index: number, entry: DiffEntry): string {
+  const pair = input.diffData.inlineDiffs?.find((d) => entry.kind === "remove" ? d.removeLineIndex === index : entry.kind === "add" ? d.addLineIndex === index : false);
+  if (!pair) return textOf(entry);
+  return entry.kind === "remove" ? spans(input.theme, pair.removeSpans, textOf(entry)) : entry.kind === "add" ? spans(input.theme, pair.addSpans, textOf(entry)) : textOf(entry);
+}
+function unifiedRows(input: RenderTuiDiffInput, width: number): string[] {
+  const rows: string[] = [];
+  for (const [i, e] of input.diffData.entries.entries()) {
+    if (e.kind === "meta") continue;
+    const prefix = `▌${gutterMarker(e)} ${lineNo(e)} │ `;
+    const tinted = wrapWithHangingIndent(prefix, inlineText(input, i, e), width, { tint: (text) => tint(input.theme, e, text) });
+    rows.push(...tinted);
+  }
+  return rows;
+}
+function compactRows(input: RenderTuiDiffInput, width: number): string[] {
+  const rows: string[] = [];
+  for (const [i, e] of input.diffData.entries.entries()) {
+    if (e.kind !== "add" && e.kind !== "remove") continue;
+    const prefix = `▌${gutterMarker(e)} ${lineNo(e)} `;
+    const tinted = wrapWithHangingIndent(prefix, inlineText(input, i, e), width, { tint: (text) => tint(input.theme, e, text) });
+    rows.push(...tinted);
+  }
+  return rows;
+}
+function splitRows(input: RenderTuiDiffInput, width: number): string[] {
+  const pane = Math.max(10, Math.floor((width - 3) / 2));
+  const rows = [`${padRightVisual("old", pane)} │ new`];
+  const blankPane = " ".repeat(pane);
+  for (const [i, e] of input.diffData.entries.entries()) {
+    if (e.kind === "remove") {
+      const left = wrapWithHangingIndent(`▌- ${e.oldLine} │ `, inlineText(input, i, e), pane, { tint: (text) => tint(input.theme, e, text) });
+      for (const line of left) rows.push(`${padRightVisual(line, pane)} │ ${blankPane}`);
+    } else if (e.kind === "add") {
+      const right = wrapWithHangingIndent(`▌+ ${e.newLine} │ `, inlineText(input, i, e), pane, { tint: (text) => tint(input.theme, e, text) });
+      for (const line of right) rows.push(`${blankPane} │ ${line}`);
+    } else if (e.kind === "context") {
+      const left = wrapWithHangingIndent(`▌  ${e.oldLine} │ `, e.text, pane, { tint: (text) => tint(input.theme, e, text) });
+      const right = wrapWithHangingIndent(`▌  ${e.newLine} │ `, e.text, pane, { tint: (text) => tint(input.theme, e, text) });
+      const maxLen = Math.max(left.length, right.length);
+      for (let k = 0; k < maxLen; k++) {
+        const l = left[k] ?? blankPane;
+        const r = right[k] ?? blankPane;
+        rows.push(`${padRightVisual(l, pane)} │ ${r}`);
+      }
+    }
+  }
+  return rows;
+}
+function hiddenHint(hiddenLines: number, hiddenHunks: number, width: number): string {
+  const forms = [`… (${hiddenLines} more diff lines • ${hiddenHunks} more hunk${hiddenHunks === 1 ? "" : "s"} • Ctrl+O to expand)`, `… (${hiddenLines} more lines • ${hiddenHunks} hunks)`, `… (+${hiddenLines} • +${hiddenHunks}h)`, "…"];
+  return forms.find((f) => visibleWidth(f) <= width) ?? "…";
+}
+export function renderTuiDiff(input: RenderTuiDiffInput): RenderTuiDiffOutput {
+  const width = normalizeWidth(input.width);
+  const mode = chooseMode(width, input.diffData);
+  const lines = [header(input.diffData, mode, width)];
+  if (!input.expanded) return { mode, width, lines: clampLinesToWidth([...lines, hiddenHint(input.diffData.entries.length, hunkCount(input.diffData), width)], width) };
+  if (mode === "summary") return { mode, width, lines: clampLinesToWidth(lines, width) };
+  const rows = mode === "split" ? splitRows(input, width) : mode === "compact" ? compactRows(input, width) : unifiedRows(input, width);
+  return { mode, width, lines: [...lines, ...rows] };
+}

package/src/tui-render-utils.ts

@@ -0,0 +1,129 @@
+import { getCapabilities, hyperlink, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { pathToFileURL } from "node:url";
+import { resolveToCwd } from "./path-utils.js";
+
+export const SUMMARY_PREFIX = "↳";
+export const EXPAND_HINT = " • Ctrl+O to expand";
+
+export type RendererTheme = {
+  fg(style: string, text: string): string;
+  bold(text: string): string;
+};
+
+export function renderToolLabel(theme: RendererTheme, label: string): string {
+  const boldFn = typeof theme.bold === "function" ? theme.bold.bind(theme) : (text: string) => text;
+  return theme.fg("toolTitle", boldFn(label));
+}
+
+export function linkToolPath(styledText: string, rawPath: string, cwd: string): string {
+  try {
+    if (!getCapabilities().hyperlinks) return styledText;
+    const absolutePath = resolveToCwd(rawPath, cwd);
+    return hyperlink(styledText, pathToFileURL(absolutePath).href);
+  } catch {
+    return styledText;
+  }
+}
+
+export function appendExpandHint(text: string, hidden: boolean): string {
+  return hidden ? `${text}${EXPAND_HINT}` : text;
+}
+
+export function summaryLine(summary: string, options: { hidden?: boolean } = {}): string {
+  return appendExpandHint(`${SUMMARY_PREFIX} ${summary}`, !!options.hidden);
+}
+
+export function isRendererExpanded(options?: { expanded?: boolean }, context?: { expanded?: boolean }): boolean {
+  return context?.expanded ?? options?.expanded ?? false;
+}
+
+export function normalizeWidth(width: unknown, fallback = 80): number {
+  return typeof width === "number" && Number.isFinite(width) && width > 0 ? Math.floor(width) : fallback;
+}
+
+export function clampLineToWidth(line: string, width: number | undefined): string {
+  if (width === undefined || width === null) return line;
+  const normalized = normalizeWidth(width);
+  return visibleWidth(line) <= normalized ? line : truncateToWidth(line, normalized);
+}
+
+export function clampLinesToWidth(lines: string[], width: number | undefined): string[] {
+  if (width === undefined || width === null) return lines;
+  return lines.map((line) => clampLineToWidth(line, width));
+}
+
+export function wrapLinesToWidth(lines: string[], width: number | undefined): string[] {
+  if (width === undefined || width === null) return lines;
+  const normalized = normalizeWidth(width);
+  return lines.flatMap((line) => {
+    if (visibleWidth(line) <= normalized) return [line];
+    return wrapTextWithAnsi(line, normalized).map((wrapped) => clampLineToWidth(wrapped, normalized));
+  });
+}
+
+export interface WrapWithHangingIndentOptions {
+  /** Optional transform applied to each produced line (e.g. theme tinting). */
+  tint?: (text: string) => string;
+}
+
+/**
+ * Wrap a single visual row that has a leading prefix (gutter, line number,
+ * separator) such that continuation lines are indented to align with the
+ * content column. Each produced line is clamped to `width`. If `tint` is
+ * provided, it is applied to each output line so theme styling extends across
+ * wrapped rows without leaking the prefix into the colored span.
+ */
+export function wrapWithHangingIndent(
+  prefix: string,
+  content: string,
+  width: number | undefined,
+  options: WrapWithHangingIndentOptions = {},
+): string[] {
+  const tint = options.tint ?? ((text: string) => text);
+  if (width === undefined || width === null) return [tint(prefix + content)];
+  const normalized = normalizeWidth(width);
+  const combined = prefix + content;
+  if (visibleWidth(combined) <= normalized) return [tint(combined)];
+  const prefixWidth = visibleWidth(prefix);
+  const contentWidth = Math.max(1, normalized - prefixWidth);
+  const wrapped = wrapTextWithAnsi(content, contentWidth);
+  if (wrapped.length === 0) return [tint(clampLineToWidth(prefix, normalized))];
+  const indent = " ".repeat(prefixWidth);
+  return wrapped.map((line, index) =>
+    tint(clampLineToWidth(index === 0 ? prefix + line : indent + line, normalized)),
+  );
+}
+const HASHLINE_CONTENT_RE = /^(\d+:[0-9a-fA-F]+\|)(.*)$/;
+
+export function wrapReadHashlinesForWidth(text: string, width: number | undefined): string {
+  if (width === undefined || width === null) return text;
+  const normalized = normalizeWidth(width);
+  const output: string[] = [];
+  for (const line of text.split("\n")) {
+    const match = line.match(HASHLINE_CONTENT_RE);
+    if (!match) {
+      output.push(line);
+      continue;
+    }
+    if (visibleWidth(line) <= normalized) {
+      output.push(line);
+      continue;
+    }
+
+    const prefix = match[1]!;
+    const content = match[2] ?? "";
+    const prefixWidth = visibleWidth(prefix);
+    const contentWidth = Math.max(1, normalized - prefixWidth);
+    const wrappedContent = wrapTextWithAnsi(content, contentWidth).map((wrapped) => clampLineToWidth(wrapped, contentWidth));
+    if (wrappedContent.length === 0) {
+      output.push(clampLineToWidth(prefix, normalized));
+      continue;
+    }
+    output.push(clampLineToWidth(prefix + wrappedContent[0], normalized));
+    const indent = " ".repeat(prefixWidth);
+    for (const continuation of wrappedContent.slice(1)) {
+      output.push(clampLineToWidth(indent + continuation, normalized));
+    }
+  }
+  return output.join("\n");
+}