@pify/pretty 0.3.1 → 0.4.0

package/README.md

@@ -1,40 +1,61 @@
 # @pify/pretty
 
-Compact, theme-aware rendering for [pi](https://github.com/earendil-works/pi)'s built-in tools — one-line summaries that expand on demand, syntax-highlighted reads, colorized diffs. **Behavior is untouched**: every tool delegates to pi's original implementation; only the rendering changes.
+Compact, theme-aware rendering for [pi](https://github.com/earendil-works/pi)'s built-in tools — one-line summaries that expand on demand, syntax-highlighted reads, colourised diffs. **Behaviour is untouched**: every tool delegates to pi's original implementation, and only the rendering changes.
 
 Part of the [Pify suite](https://github.com/pifydev). Install with [`pify install pretty`](https://github.com/pifydev/cli) or `pi install npm:@pify/pretty`.
 
+## Why
+
+A long session scrolls. Twenty file reads printed in full push the thing you actually wanted to see off the top of the terminal, and the conversation becomes an archaeology exercise. Collapsing each tool call to a line you can expand keeps the shape of the session visible.
+
+Nothing here changes what a tool does. If this extension is removed, every command still behaves identically — you just get pi's default output back.
+
 ## What you see
 
 | Tool | Collapsed | Expanded |
 |---|---|---|
-| `read` | `Read src/app.ts · lines 1–50` → `50 lines` | Syntax-highlighted content (pi's own highlighter, theme-matched) |
-| `bash` | `Bash npm test` → `✓ 12 output lines` / `✗ first error line` | Output (12-line preview while running) |
-| `edit` | `Edit src/app.ts` → `+12 -3` | Colorized diff |
+| `read` | `Read src/app.ts · lines 1–50` → `50 lines` | Syntax-highlighted content, theme-matched |
+| `bash` | `Bash npm test` → `✓ 12 output lines` / `✗ first error line` | Output, with a 12-line preview while it runs |
+| `edit` | `Edit src/app.ts` → `+12 -3` | Colourised diff with word-level emphasis |
 | `write` | `Write y.md · 34 lines` → `✓ written` | — |
-| `grep`/`find` | `Grep TODO in src` → `7 matches` | Match list |
-| `ls` | `List packages` → `23 entries` | Listing |
+| `grep` / `find` | `Grep TODO in src` → `7 matches` | The match list |
+| `ls` | `List packages` → `23 entries` | The listing |
+
+Expand with pi's standard toggle (Ctrl+O on a tool block). Failures always show the first error line in the error colour, collapsed or not — a failure you have to expand to notice is a failure you will miss.
 
-Expand with pi's standard toggle (Ctrl+O on a tool block). Failures always show the first error line in the error color.
+## Seeing what actually changed
+
+Line colour tells you *that* a line changed. When the change is one argument in a forty-column call, finding it is still your job — you read both lines and spot the difference yourself, which is the work the diff was supposed to have done.
+
+So a removed line and the added line that replaced it are compared word by word, and the rendering shows the answer: what carried over goes quiet, and what actually changed keeps the diff colour.
+
+```
+- const total = sum(items, 0);      ← "0" in the removed colour, the rest muted
++ const total = sum(items, 1);      ← "1" in the added colour, the rest muted
+```
+
+The pairing is deliberately conservative. Only a removed run and an added run of the *same length* are lined up, because two lines replaced by one is a rewrite rather than two edits — pairing those would invent a correspondence that is not there. And a pair whose lines have too little in common is left alone entirely: when the whole line is the change, dimming a few incidental brackets would only mislead. Pure insertions and pure deletions have no counterpart and are coloured whole, as before.
+
+Colours come from the theme's own `toolDiffAdded` / `toolDiffRemoved` / `toolDiffContext`, so a theme that styles diffs deliberately gets what it asked for. A theme without them falls back rather than throwing — `Theme.fg` raises on a name it does not know, and a throw inside a renderer takes the row down with it.
+
+Very long lines are not word-diffed at all: the comparison is quadratic, and a minified bundle on one line is not something anyone reads a word diff of.
 
 ## Per-tool opt-out
 
-Each renderer toggles independently (persisted per session):
+Each renderer toggles independently, and the choice is persisted per session:
 
 ```
-/pretty                 # show which renderers are on
+/pretty                 # which renderers are on, and the settings in force
 /pretty bash            # toggle one back to pi's default rendering
-/pretty bash grep       # toggle several at once (v0.2)
-/pretty off             # everything back to pi's rendering (v0.2)
-/pretty on read         # explicit on/off instead of toggling (v0.2)
-/pretty reset           # all renderers back on (v0.2)
+/pretty bash grep       # toggle several at once
+/pretty off             # everything back to pi's rendering
+/pretty on read         # explicit on/off instead of toggling
+/pretty reset           # all renderers back on
 ```
 
-Aliases are accepted where they're obvious: `list`/`dir` → `ls`, `search`/`rg` → `grep`, `cat` → `read`, `sh`/`shell` → `bash`.
+Aliases are accepted where they are obvious: `list`/`dir` → `ls`, `search`/`rg` → `grep`, `cat` → `read`, `sh`/`shell` → `bash`.
 
-Expanded bodies are capped at 200 lines (v0.2) — a 5,000-line diff or grep result used to render in full and scroll the conversation away.
-
-## Settings (v0.3)
+## Settings
 
 Every cap in a renderer is somebody's taste, and the right number depends on your terminal. Put them in `.pi/pretty.json` (project) or `<agentDir>/pretty.json` (global — the project file wins):
 
@@ -48,13 +69,17 @@ Every cap in a renderer is somebody's taste, and the right number depends on you
 }
 ```
 
-Unknown keys, wrong types, and absurd numbers are reported at session start and fall back to the shipped defaults rather than taking the renderers down — a typo tells you it was a typo instead of quietly doing nothing. `/pretty` shows the settings in force and where they came from. (The case for making these configurable is [`pi-cc-extensions`](https://github.com/minuque/pi-cc-extensions)' `/ccstyle`, which does it with a whole settings panel.)
+Unknown keys, wrong types and absurd numbers are reported at session start and fall back to the shipped defaults rather than taking the renderers down — a typo should tell you it was a typo instead of quietly doing nothing. `/pretty` shows the settings in force and where they came from.
+
+Expanded bodies are capped by `expandedLines`, because a 5,000-line diff or grep result rendered in full scrolls the conversation away — which is the problem this extension exists to solve.
+
+`summaryClip` is a ceiling, not a target: the effective clip is also bounded by the width of your terminal, re-read on every render. A one-line summary wider than the terminal wraps onto two, and a collapsed row that takes two lines is not collapsed. Resizing mid-session is handled for the same reason.
 
 ## How it works
 
-The official `built-in-tool-renderer` pattern: each tool is re-registered with `createReadTool()`/`createBashTool()`/… delegating `execute` untouched, overriding only `renderCall`/`renderResult`. Highlighting uses pi's exported `highlightCode` + `getLanguageFromPath` — zero extra dependencies, colors always match your theme.
+Each tool is re-registered through pi's own `createReadTool()` / `createBashTool()` / … factories with `execute` delegated untouched, overriding only `renderCall` and `renderResult`. Highlighting uses pi's exported `highlightCode` and `getLanguageFromPath`, so colours always match your theme and there are no extra dependencies.
 
-Only one extension can own a tool's rendering: remove other pretty/TUI tool-renderer extensions (e.g. `pi-pretty`, `pi-pretty-tui`) before installing.
+Only one extension can own a tool's rendering. Remove any other tool-renderer extension before installing this one.
 
 ## License
 

package/extensions/pretty.ts

@@ -46,11 +46,13 @@ import {
   bashCall,
   bashSummary,
   editCall,
+  effectiveClip,
   listCall,
   matchSummary,
   readCall,
   readSummary,
   searchCall,
+  terminalColumns,
   writeCall,
 } from "../src/summary.ts";
 import {
@@ -74,6 +76,15 @@ export default function pretty(pi: ExtensionAPI) {
   let config: PrettyConfig = DEFAULT_CONFIG;
   let settings: PrettySettings = DEFAULT_SETTINGS;
   let settingsSource: string | null = null;
+
+  /**
+   * The clip a summary actually gets. Read per render rather than cached:
+   * terminals get resized mid-session, and a summary sized for the old width
+   * is exactly the wrapped two-line row this package exists to avoid.
+   */
+  function clipWidth(): number {
+    return effectiveClip(settings.summaryClip, terminalColumns());
+  }
   let settingsWarnings: string[] = [];
 
   /** Project settings win over global ones; neither is required. */
@@ -126,7 +137,7 @@ export default function pretty(pi: ExtensionAPI) {
       case "read":
         return {
           renderCall: (args: { path?: string; offset?: number; limit?: number }, theme: ThemeLike) =>
-            new Text(readCall(theme, args ?? {}, settings.summaryClip), 0, 0),
+            new Text(readCall(theme, args ?? {}, clipWidth()), 0, 0),
           renderResult: (
             result: unknown,
             options: { expanded?: boolean; isPartial?: boolean },
@@ -158,7 +169,7 @@ export default function pretty(pi: ExtensionAPI) {
       case "bash":
         return {
           renderCall: (args: { command?: string }, theme: ThemeLike, context: { expanded?: boolean }) =>
-            new Text(bashCall(theme, args?.command ?? "", context?.expanded === true, settings.summaryClip), 0, 0),
+            new Text(bashCall(theme, args?.command ?? "", context?.expanded === true, clipWidth()), 0, 0),
           renderResult: (
             result: unknown,
             options: { expanded?: boolean; isPartial?: boolean },
@@ -176,7 +187,7 @@ export default function pretty(pi: ExtensionAPI) {
         };
       case "edit":
         return {
-          renderCall: (args: { path?: string }, theme: ThemeLike) => new Text(editCall(theme, args ?? {}, settings.summaryClip), 0, 0),
+          renderCall: (args: { path?: string }, theme: ThemeLike) => new Text(editCall(theme, args ?? {}, clipWidth()), 0, 0),
           renderResult: (
             result: unknown,
             options: { expanded?: boolean; isPartial?: boolean },
@@ -198,7 +209,7 @@ export default function pretty(pi: ExtensionAPI) {
       case "write":
         return {
           renderCall: (args: { path?: string; content?: string }, theme: ThemeLike) =>
-            new Text(writeCall(theme, args ?? {}, settings.summaryClip), 0, 0),
+            new Text(writeCall(theme, args ?? {}, clipWidth()), 0, 0),
           renderResult: (
             result: unknown,
             options: { expanded?: boolean; isPartial?: boolean },
@@ -217,7 +228,7 @@ export default function pretty(pi: ExtensionAPI) {
           renderCall: (
             args: { pattern?: string; path?: string; glob?: string },
             theme: ThemeLike,
-          ) => new Text(searchCall(theme, tool === "grep" ? "Grep" : "Find", args ?? {}, settings.summaryClip), 0, 0),
+          ) => new Text(searchCall(theme, tool === "grep" ? "Grep" : "Find", args ?? {}, clipWidth()), 0, 0),
           renderResult: (
             result: unknown,
             options: { expanded?: boolean; isPartial?: boolean },
@@ -238,7 +249,7 @@ export default function pretty(pi: ExtensionAPI) {
         };
       case "ls":
         return {
-          renderCall: (args: { path?: string }, theme: ThemeLike) => new Text(listCall(theme, args ?? {}, settings.summaryClip), 0, 0),
+          renderCall: (args: { path?: string }, theme: ThemeLike) => new Text(listCall(theme, args ?? {}, clipWidth()), 0, 0),
           renderResult: (
             result: unknown,
             options: { expanded?: boolean; isPartial?: boolean },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/pretty",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Compact, theme-aware rendering for pi's built-in tools: one-line summaries, syntax-highlighted reads, colorized diffs — behavior untouched",
   "keywords": [
     "pi-package",

package/src/diff.ts

@@ -1,3 +1,4 @@
+import { MIN_SIMILARITY, wordDiff, type Segment } from "./words.ts";
 import type { ThemeLike } from "./types.ts";
 
 export interface DiffStats {
@@ -30,16 +31,110 @@ export function statsLabel(theme: ThemeLike, stats: DiffStats): string {
   return `${theme.fg("success", `+${stats.added}`)} ${theme.fg("error", `-${stats.removed}`)}`;
 }
 
-/** Colorize a display diff line-by-line with theme colors. */
-export function colorizeDiff(theme: ThemeLike, diff: string): string {
-  return diff
-    .split("\n")
-    .map((line) => {
-      if (line.startsWith("+++") || line.startsWith("---")) return theme.fg("dim", line);
-      if (line.startsWith("@@")) return theme.fg("accent", line);
-      if (line.startsWith("+")) return theme.fg("success", line);
-      if (line.startsWith("-")) return theme.fg("error", line);
-      return line;
-    })
-    .join("\n");
+/**
+ * pi's themes carry colours meant for exactly this — `toolDiffAdded`,
+ * `toolDiffRemoved`, `toolDiffContext` — so a theme that styles diffs
+ * deliberately gets what it asked for instead of the generic success/error
+ * pair. `Theme.fg` throws on a name it does not know, and a throw inside a
+ * renderer takes the row down with it, so unknown names fall back.
+ */
+function fg(theme: ThemeLike, color: string, fallback: string, text: string): string {
+  try {
+    return theme.fg(color, text);
+  } catch {
+    return theme.fg(fallback, text);
+  }
+}
+
+const ADDED = "toolDiffAdded";
+const REMOVED = "toolDiffRemoved";
+const CONTEXT = "toolDiffContext";
+
+function plain(theme: ThemeLike, line: string): string {
+  if (line.startsWith("+++") || line.startsWith("---")) return theme.fg("dim", line);
+  if (line.startsWith("@@")) return theme.fg("accent", line);
+  if (line.startsWith("+")) return fg(theme, ADDED, "success", line);
+  if (line.startsWith("-")) return fg(theme, REMOVED, "error", line);
+  return line;
+}
+
+/**
+ * Paint one side of a matched pair: what changed keeps the diff colour, what
+ * carried over from the other line goes quiet. Segments are emitted one after
+ * another and never nested, so there is no inner reset to swallow an outer
+ * colour — the failure mode that makes hand-built ANSI look corrupted.
+ */
+function emphasize(
+  theme: ThemeLike,
+  marker: string,
+  segments: Segment[],
+  color: string,
+  fallback: string,
+): string {
+  return (
+    fg(theme, color, fallback, marker) +
+    segments
+      .map((s) => (s.changed ? fg(theme, color, fallback, s.text) : fg(theme, CONTEXT, "dim", s.text)))
+      .join("")
+  );
+}
+
+/**
+ * Colourise a display diff.
+ *
+ * Line colour alone says *that* a line changed; when the change is one
+ * argument in a long call, finding it is still the reader's job. So a removed
+ * line and the added line that replaced it are compared word by word, and
+ * only where they are similar enough for "what changed" to mean anything.
+ * Lines with no counterpart — a pure insertion, a pure deletion, an unequal
+ * run — are coloured whole, exactly as before.
+ */
+export function colorizeDiff(theme: ThemeLike, diff: string, emphasis = true): string {
+  const lines = diff.split("\n");
+  if (!emphasis) return lines.map((line) => plain(theme, line)).join("\n");
+
+  const out: string[] = [];
+  let inHunk = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (line.startsWith("@@")) inHunk = true;
+
+    // A removed run followed by an added run of the same length is the shape
+    // an in-place change takes; anything else is an insertion or a deletion,
+    // and pairing those would invent a correspondence that is not there.
+    if (inHunk && line.startsWith("-") && !line.startsWith("---")) {
+      const removed: string[] = [];
+      let j = i;
+      while (j < lines.length && lines[j]!.startsWith("-") && !lines[j]!.startsWith("---")) removed.push(lines[j++]!);
+      const added: string[] = [];
+      let k = j;
+      while (k < lines.length && lines[k]!.startsWith("+") && !lines[k]!.startsWith("+++")) added.push(lines[k++]!);
+
+      const pairs =
+        removed.length > 0 && removed.length === added.length
+          ? removed.map((minus, index) => wordDiff(minus.slice(1), added[index]!.slice(1)))
+          : null;
+
+      if (pairs && pairs.every((pair) => pair.similarity >= MIN_SIMILARITY)) {
+        for (const [index, pair] of pairs.entries()) {
+          out.push(emphasize(theme, removed[index]![0]!, pair.removed, REMOVED, "error"));
+        }
+        for (const [index, pair] of pairs.entries()) {
+          out.push(emphasize(theme, added[index]![0]!, pair.added, ADDED, "success"));
+        }
+        i = k - 1;
+        continue;
+      }
+
+      // The run has no line-for-line correspondence, so nothing inside it
+      // does either. Emitting it whole is what stops the tail of a 2-for-1
+      // rewrite from being re-scanned and paired with the line that replaced
+      // both of them.
+      for (const minus of removed) out.push(plain(theme, minus));
+      i = j - 1;
+      continue;
+    }
+    out.push(plain(theme, line));
+  }
+  return out.join("\n");
 }

package/src/summary.ts

@@ -10,9 +10,30 @@ function title(theme: ThemeLike, name: string): string {
   return theme.fg("toolTitle", theme.bold(name)) + " ";
 }
 
-/** Default summary clip; overridable through settings (v0.3). */
+/** Default summary clip; overridable through settings. */
 export const DEFAULT_CLIP = 100;
 
+/**
+ * Room the summary line actually has, which is not the same as the number in
+ * the settings. A one-line summary that is wider than the terminal wraps to
+ * two, and the whole point of collapsing a tool call was that it took one.
+ * The reserve covers the tool name, the separators, and the indent pi puts in
+ * front of a tool block.
+ */
+const WIDTH_RESERVE = 24;
+const MIN_CLIP = 24;
+
+export function effectiveClip(configured: number, columns: number | undefined): number {
+  if (typeof columns !== "number" || !Number.isFinite(columns) || columns <= 0) return configured;
+  return Math.max(MIN_CLIP, Math.min(configured, columns - WIDTH_RESERVE));
+}
+
+/** The terminal's width, when there is a terminal to ask. */
+export function terminalColumns(): number | undefined {
+  const columns = process.stdout?.columns;
+  return typeof columns === "number" && Number.isFinite(columns) && columns > 0 ? columns : undefined;
+}
+
 /**
  * Keep a one-line summary one line. A deeply nested path or a long command
  * is clipped in the middle: the start says what it is, the end says which

package/src/words.ts

@@ -0,0 +1,137 @@
+/**
+ * Which part of the line actually changed.
+ *
+ * A diff coloured line-by-line tells you *that* a line changed. When the
+ * change is one argument in a forty-column function call, finding it is still
+ * your job — you read both lines and spot the difference yourself, which is
+ * the work the diff was supposed to have done.
+ *
+ * So a removed line and the added line that replaced it get compared word by
+ * word, and the rendering makes the difference visible: the words that
+ * carried over go quiet, and what actually changed keeps the diff colour.
+ * Dimming the unchanged part rather than brightening the changed one is
+ * deliberate — it needs no nested colour codes, so it cannot produce the
+ * broken escape sequences that come from painting a span inside a span.
+ *
+ * Zero dependencies, like the rest of this package.
+ */
+
+/** A run of characters that either changed or did not. */
+export interface Segment {
+  text: string;
+  changed: boolean;
+}
+
+export interface WordDiff {
+  /** 0…1 — how much of the two lines is shared. */
+  similarity: number;
+  removed: Segment[];
+  added: Segment[];
+}
+
+/**
+ * Split into words and the runs of separators between them, keeping both, so
+ * the segments can be concatenated back into the original line exactly.
+ */
+export function tokenize(line: string): string[] {
+  return line.match(/[A-Za-z0-9_$]+|[^A-Za-z0-9_$]+/g) ?? [];
+}
+
+/**
+ * Longest common subsequence over tokens. Quadratic, which is fine for one
+ * pair of source lines and is why `maxLineLength` exists below: a minified
+ * bundle on one line is not something anyone reads a word diff of.
+ */
+function lcsTable(a: readonly string[], b: readonly string[]): number[][] {
+  const table: number[][] = Array.from({ length: a.length + 1 }, () => new Array<number>(b.length + 1).fill(0));
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      table[i]![j] = a[i] === b[j] ? table[i + 1]![j + 1]! + 1 : Math.max(table[i + 1]![j]!, table[i]![j + 1]!);
+    }
+  }
+  return table;
+}
+
+function push(segments: Segment[], text: string, changed: boolean): void {
+  if (text === "") return;
+  const last = segments[segments.length - 1];
+  if (last && last.changed === changed) last.text += text;
+  else segments.push({ text, changed });
+}
+
+/** Longest line this will compare; past it the answer is not worth the time. */
+export const MAX_WORD_DIFF_LINE = 2000;
+
+export function wordDiff(removed: string, added: string): WordDiff {
+  if (removed === added) {
+    return {
+      similarity: 1,
+      removed: removed ? [{ text: removed, changed: false }] : [],
+      added: added ? [{ text: added, changed: false }] : [],
+    };
+  }
+  if (removed.length > MAX_WORD_DIFF_LINE || added.length > MAX_WORD_DIFF_LINE) {
+    return { similarity: 0, removed: [{ text: removed, changed: true }], added: [{ text: added, changed: true }] };
+  }
+
+  const a = tokenize(removed);
+  const b = tokenize(added);
+  const table = lcsTable(a, b);
+
+  const removedSegments: Segment[] = [];
+  const addedSegments: Segment[] = [];
+  let shared = 0;
+  let i = 0;
+  let j = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      push(removedSegments, a[i]!, false);
+      push(addedSegments, b[j]!, false);
+      shared += a[i]!.length;
+      i++;
+      j++;
+    } else if (table[i + 1]![j]! >= table[i]![j + 1]!) {
+      push(removedSegments, a[i]!, true);
+      i++;
+    } else {
+      push(addedSegments, b[j]!, true);
+      j++;
+    }
+  }
+  while (i < a.length) push(removedSegments, a[i++]!, true);
+  while (j < b.length) push(addedSegments, b[j++]!, true);
+
+  const longest = Math.max(removed.length, added.length);
+  return {
+    similarity: longest === 0 ? 1 : (2 * shared) / (removed.length + added.length),
+    removed: coalesce(removedSegments),
+    added: coalesce(addedSegments),
+  };
+}
+
+/**
+ * `a b c` → `a x y` leaves the space between the two changed words matched,
+ * which is true and unhelpful: it breaks one change into two highlighted runs
+ * with an unhighlighted gap. Whitespace surrounded by change is change.
+ */
+function coalesce(segments: Segment[]): Segment[] {
+  const out: Segment[] = [];
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i]!;
+    const bridged =
+      !segment.changed &&
+      segment.text.trim() === "" &&
+      out.length > 0 &&
+      out[out.length - 1]!.changed &&
+      segments[i + 1]?.changed === true;
+    push(out, segment.text, bridged ? true : segment.changed);
+  }
+  return out;
+}
+
+/**
+ * Below this, the two lines have too little in common for "what changed" to
+ * mean anything — the whole line is the change, and dimming a few incidental
+ * shared brackets would only mislead.
+ */
+export const MIN_SIMILARITY = 0.34;