@pify/pretty 0.2.0 → 0.3.1

package/README.md

@@ -34,6 +34,22 @@ Aliases are accepted where they're obvious: `list`/`dir` → `ls`, `search`/`rg`
 
 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)
+
+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):
+
+```json
+{
+  "collapsedLines": 12,
+  "expandedLines": 200,
+  "diffLines": 200,
+  "syntaxHighlight": true,
+  "summaryClip": 100
+}
+```
+
+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.)
+
 ## 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.

package/extensions/pretty.ts

@@ -21,12 +21,15 @@ import {
   createLsTool,
   createReadTool,
   createWriteTool,
+  getAgentDir,
   getLanguageFromPath,
   highlightCode,
   type ExtensionAPI,
   type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 
 import {
   PRETTY_CONFIG,
@@ -37,7 +40,8 @@ import {
   statusLines,
 } from "../src/config.ts";
 import { colorizeDiff, diffStats, statsLabel } from "../src/diff.ts";
-import { preview } from "../src/preview.ts";
+import { limitsFrom, preview } from "../src/preview.ts";
+import { DEFAULT_SETTINGS, formatSettings, resolveSettings, type PrettySettings } from "../src/settings.ts";
 import {
   bashCall,
   bashSummary,
@@ -68,6 +72,36 @@ type AnyTool = {
 
 export default function pretty(pi: ExtensionAPI) {
   let config: PrettyConfig = DEFAULT_CONFIG;
+  let settings: PrettySettings = DEFAULT_SETTINGS;
+  let settingsSource: string | null = null;
+  let settingsWarnings: string[] = [];
+
+  /** Project settings win over global ones; neither is required. */
+  function loadSettings(cwd: string): void {
+    const candidates = [join(cwd, ".pi", "pretty.json"), join(getAgentDir(), "pretty.json")];
+    for (const file of candidates) {
+      let raw: string;
+      try {
+        raw = readFileSync(file, "utf8");
+      } catch {
+        continue;
+      }
+      try {
+        const parsed = resolveSettings(JSON.parse(raw));
+        settings = parsed.settings;
+        settingsWarnings = parsed.warnings;
+        settingsSource = file;
+      } catch (err) {
+        settings = DEFAULT_SETTINGS;
+        settingsSource = null;
+        settingsWarnings = [`${file}: ${err instanceof Error ? err.message : String(err)}`];
+      }
+      return;
+    }
+    settings = DEFAULT_SETTINGS;
+    settingsSource = null;
+    settingsWarnings = [];
+  }
   let originals: Record<PrettyTool, AnyTool> | null = null;
 
   function isFailed(result: unknown): boolean {
@@ -92,7 +126,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 ?? {}), 0, 0),
+            new Text(readCall(theme, args ?? {}, settings.summaryClip), 0, 0),
           renderResult: (
             result: unknown,
             options: { expanded?: boolean; isPartial?: boolean },
@@ -124,7 +158,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), 0, 0),
+            new Text(bashCall(theme, args?.command ?? "", context?.expanded === true, settings.summaryClip), 0, 0),
           renderResult: (
             result: unknown,
             options: { expanded?: boolean; isPartial?: boolean },
@@ -132,17 +166,17 @@ export default function pretty(pi: ExtensionAPI) {
           ) => {
             const output = textContent(result);
             if (options.isPartial) {
-              return new Text(`${theme.fg("warning", "Running…")}\n${preview(output, false)}`, 0, 0);
+              return new Text(`${theme.fg("warning", "Running…")}\n${preview(output, false, limitsFrom(settings))}`, 0, 0);
             }
             const failed = isFailed(result);
             const summary = bashSummary(theme, output, failed);
-            const body = output && (options.expanded || failed) ? `\n${preview(output, options.expanded === true)}` : "";
+            const body = output && (options.expanded || failed) ? `\n${preview(output, options.expanded === true, limitsFrom(settings))}` : "";
             return new Text(summary + body, 0, 0);
           },
         };
       case "edit":
         return {
-          renderCall: (args: { path?: string }, theme: ThemeLike) => new Text(editCall(theme, args ?? {}), 0, 0),
+          renderCall: (args: { path?: string }, theme: ThemeLike) => new Text(editCall(theme, args ?? {}, settings.summaryClip), 0, 0),
           renderResult: (
             result: unknown,
             options: { expanded?: boolean; isPartial?: boolean },
@@ -158,13 +192,13 @@ export default function pretty(pi: ExtensionAPI) {
                 : "";
             const stats = statsLabel(theme, diffStats(diff));
             if (!options.expanded) return new Text(stats, 0, 0);
-            return new Text(`${stats}\n${colorizeDiff(theme, preview(diff, true))}`, 0, 0);
+            return new Text(`${stats}\n${colorizeDiff(theme, preview(diff, true, { collapsed: settings.collapsedLines, expanded: settings.diffLines }))}`, 0, 0);
           },
         };
       case "write":
         return {
           renderCall: (args: { path?: string; content?: string }, theme: ThemeLike) =>
-            new Text(writeCall(theme, args ?? {}), 0, 0),
+            new Text(writeCall(theme, args ?? {}, settings.summaryClip), 0, 0),
           renderResult: (
             result: unknown,
             options: { expanded?: boolean; isPartial?: boolean },
@@ -183,7 +217,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 ?? {}), 0, 0),
+          ) => new Text(searchCall(theme, tool === "grep" ? "Grep" : "Find", args ?? {}, settings.summaryClip), 0, 0),
           renderResult: (
             result: unknown,
             options: { expanded?: boolean; isPartial?: boolean },
@@ -199,12 +233,12 @@ export default function pretty(pi: ExtensionAPI) {
               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${preview(output, true)}`, 0, 0);
+            return new Text(`${summary}\n${preview(output, true, limitsFrom(settings))}`, 0, 0);
           },
         };
       case "ls":
         return {
-          renderCall: (args: { path?: string }, theme: ThemeLike) => new Text(listCall(theme, args ?? {}), 0, 0),
+          renderCall: (args: { path?: string }, theme: ThemeLike) => new Text(listCall(theme, args ?? {}, settings.summaryClip), 0, 0),
           renderResult: (
             result: unknown,
             options: { expanded?: boolean; isPartial?: boolean },
@@ -215,7 +249,7 @@ export default function pretty(pi: ExtensionAPI) {
             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${preview(output, true)}`, 0, 0);
+            return new Text(`${summary}\n${preview(output, true, limitsFrom(settings))}`, 0, 0);
           },
         };
     }
@@ -241,8 +275,12 @@ export default function pretty(pi: ExtensionAPI) {
 
   pi.on("session_start", async (_event, ctx) => {
     originals = buildOriginals(ctx.cwd);
+    loadSettings(ctx.cwd);
     config = replayBranch(ctx.sessionManager.getBranch() as never);
     applyAll();
+    if (settingsWarnings.length > 0 && ctx.hasUI) {
+      ctx.ui.notify(`pretty settings: ${settingsWarnings.join("; ")}`, "warning");
+    }
   });
 
   pi.on("session_tree", async (_event, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/pretty",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Compact, theme-aware rendering for pi's built-in tools: one-line summaries, syntax-highlighted reads, colorized diffs — behavior untouched",
   "keywords": [
     "pi-package",
@@ -53,8 +53,8 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.4",
-    "@earendil-works/pi-tui": "^0.84.4",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@earendil-works/pi-tui": "^0.85.1",
     "@types/node": "^22.10.2",
     "typescript": "^5.7.2"
   },

package/src/config.ts

@@ -33,7 +33,10 @@ export function toggleTool(config: PrettyConfig, tool: PrettyTool): PrettyConfig
     : { disabled: [...config.disabled, tool] };
 }
 
-export const PRETTY_USAGE = "Usage: /pretty [status | on|off [tool…] | reset | <tool…>]  tools: read, bash, edit, write, grep, find, ls";
+export const PRETTY_USAGE = [
+  "Usage: /pretty [status | on|off [tool…] | reset | <tool…>]  tools: read, bash, edit, write, grep, find, ls",
+  "Settings: .pi/pretty.json (project) or <agentDir>/pretty.json",
+].join("\n");
 
 /** Aliases the model or a hurried user is likely to type. */
 const ALIASES: Record<string, PrettyTool> = {

package/src/preview.ts

@@ -12,6 +12,11 @@ export interface PreviewLimits {
 
 export const DEFAULT_LIMITS: PreviewLimits = { collapsed: 12, expanded: 200 };
 
+/** Limits from user settings (v0.3); the caps themselves are unchanged. */
+export function limitsFrom(settings: { collapsedLines: number; expandedLines: number }): PreviewLimits {
+  return { collapsed: settings.collapsedLines, expanded: settings.expandedLines };
+}
+
 export function preview(text: string, expanded: boolean, limits: PreviewLimits = DEFAULT_LIMITS): string {
   const max = expanded ? limits.expanded : limits.collapsed;
   const lines = text.split("\n");

package/src/settings.ts

@@ -0,0 +1,93 @@
+/**
+ * User settings for the renderers.
+ *
+ * pi-cc-extensions makes the case by example: every number in a renderer is
+ * someone's taste, and the ones that matter are the caps. A 200-line expanded
+ * body is right on a 4K monitor and absurd in a 24-row terminal, and nobody
+ * wants to fork a package to change an integer.
+ *
+ * Read from `.pi/pretty.json` in the project, else `<agentDir>/pretty.json`.
+ * Unknown keys are ignored and bad values fall back to the default, so an
+ * old or hand-edited file can never take the renderers down — the worst case
+ * is the shipped defaults, which is where everyone starts anyway.
+ */
+
+export interface PrettySettings {
+  /** Lines shown in a collapsed body (bash streaming, tool output). */
+  collapsedLines: number;
+  /** Lines shown after expanding, before "+N more lines". */
+  expandedLines: number;
+  /** Lines of an edit diff shown after expanding. */
+  diffLines: number;
+  /** Highlight expanded read results with pi's own highlighter. */
+  syntaxHighlight: boolean;
+  /** Longest path/command shown in a one-line summary. */
+  summaryClip: number;
+}
+
+export const DEFAULT_SETTINGS: PrettySettings = {
+  collapsedLines: 12,
+  expandedLines: 200,
+  diffLines: 200,
+  syntaxHighlight: true,
+  summaryClip: 100,
+};
+
+const LIMITS: Record<keyof PrettySettings, { min: number; max: number } | null> = {
+  collapsedLines: { min: 1, max: 200 },
+  expandedLines: { min: 5, max: 10_000 },
+  diffLines: { min: 5, max: 10_000 },
+  syntaxHighlight: null,
+  summaryClip: { min: 20, max: 500 },
+};
+
+/**
+ * Merge a parsed settings file over the defaults. Returns the settings that
+ * will actually be used plus a note for every value that was rejected —
+ * silently ignoring a typo is how someone spends an afternoon wondering why
+ * their config does nothing.
+ */
+export function resolveSettings(raw: unknown): { settings: PrettySettings; warnings: string[] } {
+  const settings: PrettySettings = { ...DEFAULT_SETTINGS };
+  const warnings: string[] = [];
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    if (raw !== undefined && raw !== null) warnings.push("settings file is not an object — ignored");
+    return { settings, warnings };
+  }
+
+  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (!(key in DEFAULT_SETTINGS)) {
+      warnings.push(`unknown setting "${key}"`);
+      continue;
+    }
+    const name = key as keyof PrettySettings;
+    const limit = LIMITS[name];
+    if (limit === null) {
+      if (typeof value !== "boolean") {
+        warnings.push(`"${key}" must be true or false — using ${String(DEFAULT_SETTINGS[name])}`);
+        continue;
+      }
+      (settings[name] as boolean) = value;
+      continue;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+      warnings.push(`"${key}" must be a number — using ${String(DEFAULT_SETTINGS[name])}`);
+      continue;
+    }
+    const clamped = Math.round(Math.min(limit.max, Math.max(limit.min, value)));
+    if (clamped !== value) {
+      warnings.push(`"${key}" clamped to ${clamped} (allowed ${limit.min}–${limit.max})`);
+    }
+    (settings[name] as number) = clamped;
+  }
+
+  return { settings, warnings };
+}
+
+export function formatSettings(settings: PrettySettings, source: string | null): string {
+  const width = Object.keys(settings).reduce((m, k) => Math.max(m, k.length), 0);
+  const lines = Object.entries(settings).map(
+    ([key, value]) => `  ${key.padEnd(width)}  ${String(value)}`,
+  );
+  return [source ? `Settings from ${source}` : "Settings (defaults — no pretty.json found)", ...lines].join("\n");
+}

package/src/summary.ts

@@ -10,12 +10,32 @@ 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 {
+/** Default summary clip; overridable through settings (v0.3). */
+export const DEFAULT_CLIP = 100;
+
+/**
+ * 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
+ * file, and the part nobody reads is what goes.
+ */
+export function clip(text: string, max: number = DEFAULT_CLIP): string {
+  if (max <= 0 || text.length <= max) return text;
+  if (max <= 4) return text.slice(0, max);
+  const head = Math.ceil((max - 1) / 2);
+  const tail = max - 1 - head;
+  return `${text.slice(0, head)}…${text.slice(text.length - tail)}`;
+}
+
+export function readCall(
+  theme: ThemeLike,
+  args: { path?: string; offset?: number; limit?: number },
+  max: number = DEFAULT_CLIP,
+): 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;
+  return title(theme, "Read") + theme.fg("accent", clip(args.path ?? "", max)) + range;
 }
 
 export function readSummary(theme: ThemeLike, output: string, truncated: boolean, failed: boolean): string {
@@ -24,11 +44,19 @@ export function readSummary(theme: ThemeLike, output: string, truncated: boolean
   return theme.fg("dim", `${lines} ${lines === 1 ? "line" : "lines"}${truncated ? " · truncated" : ""}`);
 }
 
-export function bashCall(theme: ThemeLike, command: string, expanded: boolean): string {
+export function bashCall(
+  theme: ThemeLike,
+  command: string,
+  expanded: boolean,
+  max: number = DEFAULT_CLIP,
+): 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"})`)}`;
+  const shown =
+    expanded || omitted === 0
+      ? clip(command, expanded ? Number.MAX_SAFE_INTEGER : max)
+      : `${clip(head, max)} ${theme.fg("dim", `… (+${omitted} ${omitted === 1 ? "line" : "lines"})`)}`;
   return title(theme, "Bash") + theme.fg("accent", shown);
 }
 
@@ -41,27 +69,36 @@ export function bashSummary(theme: ThemeLike, output: string, failed: boolean):
   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 editCall(theme: ThemeLike, args: { path?: string }, max: number = DEFAULT_CLIP): string {
+  return title(theme, "Edit") + theme.fg("accent", clip(args.path ?? "", max));
 }
 
-export function writeCall(theme: ThemeLike, args: { path?: string; content?: string }): string {
+export function writeCall(
+  theme: ThemeLike,
+  args: { path?: string; content?: string },
+  max: number = DEFAULT_CLIP,
+): 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"}`);
+  return (
+    title(theme, "Write") +
+    theme.fg("accent", clip(args.path ?? "", max)) +
+    theme.fg("dim", ` · ${lines} ${lines === 1 ? "line" : "lines"}`)
+  );
 }
 
 export function searchCall(
   theme: ThemeLike,
   name: string,
   args: { pattern?: string; path?: string; glob?: string },
+  max: number = DEFAULT_CLIP,
 ): string {
-  const pattern = args.pattern ?? args.glob ?? "";
-  const where = args.path ? theme.fg("dim", ` in ${args.path}`) : "";
+  const pattern = clip(args.pattern ?? args.glob ?? "", max);
+  const where = args.path ? theme.fg("dim", ` in ${clip(args.path, max)}`) : "";
   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 listCall(theme: ThemeLike, args: { path?: string }, max: number = DEFAULT_CLIP): string {
+  return title(theme, "List") + theme.fg("accent", clip(args.path ?? ".", max));
 }
 
 export function matchSummary(