@pify/pretty 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pifydev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @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.
+
+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`.
+
+## 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 |
+| `write` | `Write y.md · 34 lines` → `✓ written` | — |
+| `grep`/`find` | `Grep TODO in src` → `7 matches` | Match list |
+| `ls` | `List packages` → `23 entries` | Listing |
+
+Expand with pi's standard toggle (Ctrl+O on a tool block). Failures always show the first error line in the error color.
+
+## Per-tool opt-out
+
+Each renderer toggles independently (persisted per session):
+
+```
+/pretty            # show which renderers are on
+/pretty bash       # toggle one back to pi's default rendering
+```
+
+## 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.
+
+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.
+
+## License
+
+MIT © [Pify maintainers](https://github.com/pifydev)

package/extensions/pretty.ts

@@ -0,0 +1,276 @@
+/**
+ * @pify/pretty — compact, theme-aware rendering for pi's built-in tools.
+ *
+ * Pure rendering: every tool is re-registered with its ORIGINAL execute
+ * delegated untouched (pi's official built-in-tool-renderer pattern); only
+ * renderCall/renderResult change. Collapsed one-line summaries expand with
+ * pi's standard toggle; read results get syntax highlighting via pi's own
+ * highlightCode; edit diffs are colorized with +N −M stats. Each renderer
+ * toggles independently with /pretty <tool> (zentui's opt-in principle),
+ * persisted per session.
+ *
+ * Design synthesis: compact summary shapes (ykn0309/pi-pretty-tui),
+ * delegate-execute renderer pattern (pi examples), theme-aware minimalism
+ * (giladbarnea/pi-pretty-bash), per-surface opt-in (pi-zentui).
+ */
+import {
+  createBashTool,
+  createEditTool,
+  createFindTool,
+  createGrepTool,
+  createLsTool,
+  createReadTool,
+  createWriteTool,
+  getLanguageFromPath,
+  highlightCode,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+import { PRETTY_CONFIG, isPrettyTool, replayBranch, statusLines, toggleTool } from "../src/config.ts";
+import { colorizeDiff, diffStats, statsLabel } from "../src/diff.ts";
+import {
+  bashCall,
+  bashSummary,
+  editCall,
+  listCall,
+  matchSummary,
+  readCall,
+  readSummary,
+  searchCall,
+  writeCall,
+} from "../src/summary.ts";
+import {
+  DEFAULT_CONFIG,
+  isRecord,
+  textContent,
+  type PrettyConfig,
+  type PrettyTool,
+  type ThemeLike,
+} from "../src/types.ts";
+
+const PREVIEW_LINES = 12;
+
+type AnyTool = {
+  name: string;
+  description: string;
+  parameters: unknown;
+  execute: (...args: never[]) => unknown;
+  [key: string]: unknown;
+};
+
+export default function pretty(pi: ExtensionAPI) {
+  let config: PrettyConfig = DEFAULT_CONFIG;
+  let originals: Record<PrettyTool, AnyTool> | null = null;
+
+  function isFailed(result: unknown): boolean {
+    return isRecord(result) && result.isError === true;
+  }
+
+  function clip(text: string, expanded: boolean): string {
+    if (expanded) return text;
+    const lines = text.split("\n");
+    if (lines.length <= PREVIEW_LINES) return text;
+    return `${lines.slice(0, PREVIEW_LINES).join("\n")}\n…`;
+  }
+
+  function buildOriginals(cwd: string): Record<PrettyTool, AnyTool> {
+    return {
+      read: createReadTool(cwd) as unknown as AnyTool,
+      bash: createBashTool(cwd) as unknown as AnyTool,
+      edit: createEditTool(cwd) as unknown as AnyTool,
+      write: createWriteTool(cwd) as unknown as AnyTool,
+      grep: createGrepTool(cwd) as unknown as AnyTool,
+      find: createFindTool(cwd) as unknown as AnyTool,
+      ls: createLsTool(cwd) as unknown as AnyTool,
+    };
+  }
+
+  /** Renderers per tool; delegate execution to the original untouched. */
+  function renderersFor(tool: PrettyTool): Record<string, unknown> {
+    switch (tool) {
+      case "read":
+        return {
+          renderCall: (args: { path?: string; offset?: number; limit?: number }, theme: ThemeLike) =>
+            new Text(readCall(theme, args ?? {}), 0, 0),
+          renderResult: (
+            result: unknown,
+            options: { expanded?: boolean; isPartial?: boolean },
+            theme: ThemeLike,
+          ) => {
+            if (options.isPartial) return new Text(theme.fg("warning", "Reading…"), 0, 0);
+            const output = textContent(result);
+            const failed = isFailed(result);
+            const truncated =
+              isRecord(result) && isRecord(result.details) && isRecord(result.details.truncation)
+                ? result.details.truncation.truncated === true
+                : false;
+            const summary = readSummary(theme, output, truncated, failed);
+            if (!options.expanded || failed) return new Text(summary, 0, 0);
+            const path =
+              isRecord(result) && isRecord(result.details) && typeof result.details.path === "string"
+                ? result.details.path
+                : "";
+            const language = path ? getLanguageFromPath(path) : undefined;
+            let body = output;
+            try {
+              if (language) body = highlightCode(output, language).join("\n");
+            } catch {
+              // highlighting is best-effort
+            }
+            return new Text(`${summary}\n${body}`, 0, 0);
+          },
+        };
+      case "bash":
+        return {
+          renderCall: (args: { command?: string }, theme: ThemeLike, context: { expanded?: boolean }) =>
+            new Text(bashCall(theme, args?.command ?? "", context?.expanded === true), 0, 0),
+          renderResult: (
+            result: unknown,
+            options: { expanded?: boolean; isPartial?: boolean },
+            theme: ThemeLike,
+          ) => {
+            const output = textContent(result);
+            if (options.isPartial) {
+              return new Text(`${theme.fg("warning", "Running…")}\n${clip(output, false)}`, 0, 0);
+            }
+            const failed = isFailed(result);
+            const summary = bashSummary(theme, output, failed);
+            const body = output && (options.expanded || failed) ? `\n${clip(output, options.expanded === true)}` : "";
+            return new Text(summary + body, 0, 0);
+          },
+        };
+      case "edit":
+        return {
+          renderCall: (args: { path?: string }, theme: ThemeLike) => new Text(editCall(theme, args ?? {}), 0, 0),
+          renderResult: (
+            result: unknown,
+            options: { expanded?: boolean; isPartial?: boolean },
+            theme: ThemeLike,
+          ) => {
+            if (options.isPartial) return new Text(theme.fg("warning", "Editing…"), 0, 0);
+            if (isFailed(result)) {
+              return new Text(theme.fg("error", textContent(result).split("\n")[0] || "Edit failed"), 0, 0);
+            }
+            const diff =
+              isRecord(result) && isRecord(result.details) && typeof result.details.diff === "string"
+                ? result.details.diff
+                : "";
+            const stats = statsLabel(theme, diffStats(diff));
+            if (!options.expanded) return new Text(stats, 0, 0);
+            return new Text(`${stats}\n${colorizeDiff(theme, diff)}`, 0, 0);
+          },
+        };
+      case "write":
+        return {
+          renderCall: (args: { path?: string; content?: string }, theme: ThemeLike) =>
+            new Text(writeCall(theme, args ?? {}), 0, 0),
+          renderResult: (
+            result: unknown,
+            options: { expanded?: boolean; isPartial?: boolean },
+            theme: ThemeLike,
+          ) => {
+            if (options.isPartial) return new Text(theme.fg("warning", "Writing…"), 0, 0);
+            if (isFailed(result)) {
+              return new Text(theme.fg("error", textContent(result).split("\n")[0] || "Write failed"), 0, 0);
+            }
+            return new Text(theme.fg("success", "✓ written"), 0, 0);
+          },
+        };
+      case "grep":
+      case "find":
+        return {
+          renderCall: (
+            args: { pattern?: string; path?: string; glob?: string },
+            theme: ThemeLike,
+          ) => new Text(searchCall(theme, tool === "grep" ? "Grep" : "Find", args ?? {}), 0, 0),
+          renderResult: (
+            result: unknown,
+            options: { expanded?: boolean; isPartial?: boolean },
+            theme: ThemeLike,
+          ) => {
+            if (options.isPartial) return new Text(theme.fg("warning", "Searching…"), 0, 0);
+            const output = textContent(result);
+            const failed = isFailed(result);
+            const summary = matchSummary(
+              theme,
+              output,
+              failed,
+              tool === "grep" ? { one: "match", many: "matches" } : { one: "result", many: "results" },
+            );
+            if (!options.expanded || failed || !output) return new Text(summary, 0, 0);
+            return new Text(`${summary}\n${clip(output, true)}`, 0, 0);
+          },
+        };
+      case "ls":
+        return {
+          renderCall: (args: { path?: string }, theme: ThemeLike) => new Text(listCall(theme, args ?? {}), 0, 0),
+          renderResult: (
+            result: unknown,
+            options: { expanded?: boolean; isPartial?: boolean },
+            theme: ThemeLike,
+          ) => {
+            if (options.isPartial) return new Text(theme.fg("warning", "Listing…"), 0, 0);
+            const output = textContent(result);
+            const failed = isFailed(result);
+            const summary = matchSummary(theme, output, failed, { one: "entry", many: "entries" });
+            if (!options.expanded || failed) return new Text(summary, 0, 0);
+            return new Text(`${summary}\n${clip(output, true)}`, 0, 0);
+          },
+        };
+    }
+  }
+
+  /** (Re-)register one tool with or without pretty renderers. */
+  function applyTool(tool: PrettyTool): void {
+    if (!originals) return;
+    const original = originals[tool];
+    const withPretty = !config.disabled.includes(tool);
+    pi.registerTool({
+      ...original,
+      ...(withPretty ? renderersFor(tool) : {}),
+    } as never);
+  }
+
+  function applyAll(): void {
+    if (!originals) return;
+    for (const tool of Object.keys(originals) as PrettyTool[]) applyTool(tool);
+  }
+
+  // ── Lifecycle ────────────────────────────────────────────────────────
+
+  pi.on("session_start", async (_event, ctx) => {
+    originals = buildOriginals(ctx.cwd);
+    config = replayBranch(ctx.sessionManager.getBranch() as never);
+    applyAll();
+  });
+
+  pi.on("session_tree", async (_event, ctx) => {
+    config = replayBranch(ctx.sessionManager.getBranch() as never);
+    applyAll();
+  });
+
+  // ── Command ──────────────────────────────────────────────────────────
+
+  pi.registerCommand("pretty", {
+    description: "Toggle pretty tool rendering: /pretty [read|bash|edit|write|grep|find|ls]",
+    handler: async (args, ctx: ExtensionContext) => {
+      if (!ctx.hasUI) return;
+      const target = (args ?? "").trim().toLowerCase();
+      if (!target) {
+        ctx.ui.notify(`Pretty renderers\n${statusLines(config).join("\n")}\nToggle with /pretty <tool>`, "info");
+        return;
+      }
+      if (!isPrettyTool(target)) {
+        ctx.ui.notify(`Unknown tool "${target}". Tools: read, bash, edit, write, grep, find, ls`, "warning");
+        return;
+      }
+      config = toggleTool(config, target);
+      pi.appendEntry(PRETTY_CONFIG, config);
+      applyTool(target);
+      const on = !config.disabled.includes(target);
+      ctx.ui.notify(`pretty ${target}: ${on ? "on" : "off"}`, "info");
+    },
+  });
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@pify/pretty",
+  "version": "0.1.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",
+    "pi-extension",
+    "pi",
+    "pify",
+    "pretty",
+    "tui"
+  ],
+  "homepage": "https://github.com/pifydev/pretty#readme",
+  "bugs": {
+    "url": "https://github.com/pifydev/pretty/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pifydev/pretty.git"
+  },
+  "license": "MIT",
+  "author": "Pify maintainers",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": ["./extensions/pretty.ts"]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": { "optional": true },
+    "@earendil-works/pi-tui": { "optional": true }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/config.ts

@@ -0,0 +1,40 @@
+import {
+  DEFAULT_CONFIG,
+  PRETTY_TOOLS,
+  isRecord,
+  type BranchEntryLike,
+  type PrettyConfig,
+  type PrettyTool,
+} from "./types.ts";
+
+export const PRETTY_CONFIG = "pretty-config";
+
+export function isPrettyTool(name: string): name is PrettyTool {
+  return (PRETTY_TOOLS as readonly string[]).includes(name);
+}
+
+/** Snapshot-based replay: last pretty-config entry on the branch wins. */
+export function replayBranch(entries: BranchEntryLike[]): PrettyConfig {
+  let config = DEFAULT_CONFIG;
+  for (const entry of entries) {
+    if (entry.type !== "custom" || entry.customType !== PRETTY_CONFIG) continue;
+    const data = entry.data;
+    if (!isRecord(data) || !Array.isArray(data.disabled)) continue;
+    config = {
+      disabled: data.disabled.filter((t): t is PrettyTool => typeof t === "string" && isPrettyTool(t)),
+    };
+  }
+  return config;
+}
+
+export function toggleTool(config: PrettyConfig, tool: PrettyTool): PrettyConfig {
+  return config.disabled.includes(tool)
+    ? { disabled: config.disabled.filter((t) => t !== tool) }
+    : { disabled: [...config.disabled, tool] };
+}
+
+export function statusLines(config: PrettyConfig): string[] {
+  return PRETTY_TOOLS.map(
+    (tool) => `${config.disabled.includes(tool) ? "○" : "●"} ${tool}`,
+  );
+}

package/src/diff.ts

@@ -0,0 +1,36 @@
+import type { ThemeLike } from "./types.ts";
+
+export interface DiffStats {
+  added: number;
+  removed: number;
+}
+
+/** Count +/− lines in a display diff (ignores headers like +++/---). */
+export function diffStats(diff: string): DiffStats {
+  let added = 0;
+  let removed = 0;
+  for (const line of diff.split("\n")) {
+    if (line.startsWith("+++") || line.startsWith("---")) continue;
+    if (line.startsWith("+")) added++;
+    else if (line.startsWith("-")) removed++;
+  }
+  return { added, removed };
+}
+
+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");
+}

package/src/summary.ts

@@ -0,0 +1,77 @@
+import { countLines, type ThemeLike } from "./types.ts";
+
+/**
+ * Pure one-line summary builders for tool calls and results
+ * (ykn0309-style compact rendering). All return plain strings; the
+ * extension wraps them in pi-tui Text components.
+ */
+
+function title(theme: ThemeLike, name: string): string {
+  return theme.fg("toolTitle", theme.bold(name)) + " ";
+}
+
+export function readCall(theme: ThemeLike, args: { path?: string; offset?: number; limit?: number }): string {
+  const range =
+    args.offset || args.limit
+      ? theme.fg("dim", ` · lines ${args.offset ?? 1}${args.limit ? `–${(args.offset ?? 1) + args.limit - 1}` : "+"}`)
+      : "";
+  return title(theme, "Read") + theme.fg("accent", args.path ?? "") + range;
+}
+
+export function readSummary(theme: ThemeLike, output: string, truncated: boolean, failed: boolean): string {
+  if (failed) return theme.fg("error", output.split("\n")[0] || "Read failed");
+  const lines = countLines(output);
+  return theme.fg("dim", `${lines} ${lines === 1 ? "line" : "lines"}${truncated ? " · truncated" : ""}`);
+}
+
+export function bashCall(theme: ThemeLike, command: string, expanded: boolean): string {
+  const lines = command.split(/\r\n|\r|\n/);
+  const head = lines[0] ?? "";
+  const omitted = lines.length - 1;
+  const shown = expanded || omitted === 0 ? command : `${head} ${theme.fg("dim", `… (+${omitted} ${omitted === 1 ? "line" : "lines"})`)}`;
+  return title(theme, "Bash") + theme.fg("accent", shown);
+}
+
+export function bashSummary(theme: ThemeLike, output: string, failed: boolean): string {
+  if (failed) {
+    const first = output.split("\n").find((l) => l.trim()) ?? "Command failed";
+    return theme.fg("error", `✗ ${first}`);
+  }
+  const lines = countLines(output);
+  return theme.fg("success", "✓") + theme.fg("dim", lines > 0 ? ` ${lines} output ${lines === 1 ? "line" : "lines"}` : " done");
+}
+
+export function editCall(theme: ThemeLike, args: { path?: string }): string {
+  return title(theme, "Edit") + theme.fg("accent", args.path ?? "");
+}
+
+export function writeCall(theme: ThemeLike, args: { path?: string; content?: string }): string {
+  const lines = typeof args.content === "string" ? args.content.split("\n").length : 0;
+  return title(theme, "Write") + theme.fg("accent", args.path ?? "") + theme.fg("dim", ` · ${lines} ${lines === 1 ? "line" : "lines"}`);
+}
+
+export function searchCall(
+  theme: ThemeLike,
+  name: string,
+  args: { pattern?: string; path?: string; glob?: string },
+): string {
+  const pattern = args.pattern ?? args.glob ?? "";
+  const where = args.path ? theme.fg("dim", ` in ${args.path}`) : "";
+  return title(theme, name) + theme.fg("accent", pattern) + where;
+}
+
+export function listCall(theme: ThemeLike, args: { path?: string }): string {
+  return title(theme, "List") + theme.fg("accent", args.path ?? ".");
+}
+
+export function matchSummary(
+  theme: ThemeLike,
+  output: string,
+  failed: boolean,
+  noun: { one: string; many: string },
+): string {
+  if (failed) return theme.fg("error", output.split("\n")[0] || "failed");
+  const lines = countLines(output);
+  if (lines === 0) return theme.fg("dim", `no ${noun.many}`);
+  return theme.fg("dim", `${lines} ${lines === 1 ? noun.one : noun.many}`);
+}

package/src/types.ts

@@ -0,0 +1,46 @@
+/**
+ * Local structural types for @pify/pretty.
+ * No imports from pi packages: src/ typechecks and runs standalone.
+ */
+
+/** Painter surface the summary builders need (subset of pi-tui Theme). */
+export interface ThemeLike {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+}
+
+/** The tools this extension can re-render. */
+export const PRETTY_TOOLS = ["read", "bash", "edit", "write", "grep", "find", "ls"] as const;
+export type PrettyTool = (typeof PRETTY_TOOLS)[number];
+
+export interface PrettyConfig {
+  /** Renderers the user turned off (defaults: all on). */
+  disabled: PrettyTool[];
+}
+
+export const DEFAULT_CONFIG: PrettyConfig = { disabled: [] };
+
+export interface BranchEntryLike {
+  type?: string;
+  customType?: string;
+  data?: unknown;
+  [key: string]: unknown;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Extract joined text from a tool result's content blocks. */
+export function textContent(result: unknown): string {
+  if (!isRecord(result) || !Array.isArray(result.content)) return "";
+  return result.content
+    .filter((c): c is { type: string; text: string } => isRecord(c) && c.type === "text" && typeof c.text === "string")
+    .map((c) => c.text)
+    .join("\n");
+}
+
+export function countLines(text: string): number {
+  if (!text) return 0;
+  return text.split("\n").filter((l) => l.trim() !== "").length;
+}