@pify/pretty 0.2.0 → 0.3.0

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 {
@@ -132,11 +166,11 @@ 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);
           },
         };
@@ -158,7 +192,7 @@ 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":
@@ -199,7 +233,7 @@ 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":
@@ -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.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",
@@ -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");
+}