@wierdbytes/pi-facelift 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 huynhgiabuu
+
+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,87 @@
+# `@wierdbytes/pi-facelift`
+
+Cosmetic facelift for built-in [pi coding agent](https://github.com/earendil-works/pi/tree/main/packages/coding-agent)
+tool output.
+
+> inspired by [`pi-pretty`](https://github.com/buddingnewinsights/pi-pretty)
+
+![read / bash / ls / find / grep rendered with the open-right rounded frame](./media/demo.png)
+
+## What you get
+
+- **`read`** — syntax-highlighted file content with line numbers, plus
+  inline image rendering (Kitty / iTerm2 protocols, with tmux passthrough).
+- **`bash`** — open-right frame with the duration + status pinned to the
+  bottom border
+
+  Status color follows pi: **green** on success, **yellow** while still
+  running, **red** on non-zero / timeout / abort. The exit summary is
+  consistent across statuses (`✓ exit 0`, `✗ exit N`, `⚡ timed out`,
+  `⚡ aborted`). Duration is shown as `3.3s` / `1m3s` / `2h5m`.
+- **`ls`** — Nerd Font file icons + tree-oriented rendering.
+- **`find` / `grep`** — grouped / highlighted rendering on top of pi's
+  built-in tool implementations (no extra search backend, no extra
+  dependencies).
+
+## Install
+
+```bash
+pi install npm:@wierdbytes/pi-facelift
+```
+
+## Terminal support for inline images
+
+Inline image previews work in **Ghostty**, **Kitty**, **iTerm2**, and
+**WezTerm**. Inside `tmux`, pi-facelift uses passthrough escape
+sequences:
+
+```tmux
+set -g allow-passthrough on
+```
+
+(or run once in a session: `tmux set -g allow-passthrough on`)
+
+## Configuration
+
+All configuration is via environment variables — no settings file:
+
+| Variable                       | Default         | Notes                                                                         |
+| ------------------------------ | --------------- | ----------------------------------------------------------------------------- |
+| `FACELIFT_THEME`               | `github-dark`   | Shiki theme. Falls back to `~/.pi/agent/settings.json` `theme` if unset.      |
+| `FACELIFT_MAX_HL_CHARS`        | `80000`         | Files larger than this skip syntax highlighting (still get line numbers).     |
+| `FACELIFT_MAX_PREVIEW_LINES`   | `80`            | Body preview length for collapsed renderers.                                  |
+| `FACELIFT_CACHE_LIMIT`         | `128`           | Max number of highlighted blocks held in memory.                              |
+| `FACELIFT_ICONS`               | `nerd`          | Set to `none` / `off` to disable Nerd Font icons in `ls`/`find`/`grep`.       |
+| `FACELIFT_IMAGE_PROTOCOL`      | auto            | Force `kitty` / `iterm2` / `none`. Auto-detected from `$TERM_PROGRAM` etc.    |
+
+## Development
+
+This package lives in the [`pi-wierd-stuff`](../../README.md) monorepo.
+
+```bash
+bun install                        # from the repo root
+cd packages/facelift
+bun run test                       # 11 tests
+bun run test:watch                 # vitest watch mode
+bun run demo                       # render every tool block to your terminal
+```
+
+The `demo` script (`scripts/demo.ts`) is a visual harness — it boots the
+extension with mocked SDK tools and prints every renderer (read with
+live shiki highlighting, bash in success / non-zero / streaming /
+timeout states, ls tree, find groups, grep matches) so you can eyeball
+the open-right rounded frame, status-aware coloring, and the duration /
+exit summary in the bottom border.
+
+Typecheck (uses the global `tsc`):
+
+```bash
+bunx tsc --noEmit --target esnext --module nodenext \
+  --moduleResolution nodenext --strict --skipLibCheck \
+  --allowImportingTsExtensions \
+  index.ts
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bash-rendering.test.ts

@@ -0,0 +1,169 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { describe, expect, it } from "vitest";
+
+import piFaceliftExtension from "./index.ts";
+
+class MockText {
+	private text = "";
+	constructor(_text = "", _x = 0, _y = 0) {}
+	setText(value: string) {
+		this.text = value;
+	}
+	getText() {
+		return this.text;
+	}
+}
+
+const mockTheme = {
+	fg: (_key: string, text: string) => text,
+	bold: (text: string) => text,
+};
+
+const ansiMockTheme = {
+	fg: (_key: string, text: string) => `\x1b[31m${text}\x1b[0m`,
+	bold: (text: string) => `\x1b[1m${text}\x1b[22m`,
+};
+
+function mockToolFactory(exec: any) {
+	return (_cwd: string) => ({
+		name: "mock",
+		description: "mock",
+		parameters: { type: "object", properties: {} },
+		execute: exec,
+	});
+}
+
+function withStdoutColumns<T>(columns: number, fn: () => T): T {
+	const descriptor = Object.getOwnPropertyDescriptor(process.stdout, "columns");
+	Object.defineProperty(process.stdout, "columns", { configurable: true, value: columns });
+	try {
+		return fn();
+	} finally {
+		if (descriptor) {
+			Object.defineProperty(process.stdout, "columns", descriptor);
+		} else {
+			delete (process.stdout as NodeJS.WriteStream & { columns?: number }).columns;
+		}
+	}
+}
+
+function loadBashTool() {
+	const noopExec = async () => ({ content: [{ type: "text", text: "" }] });
+	const tools = new Map<string, any>();
+	const pi = {
+		registerTool: (tool: any) => tools.set(tool.name, tool),
+		registerCommand: () => {},
+		on: () => {},
+	};
+
+	piFaceliftExtension(pi, {
+		sdk: {
+			createReadToolDefinition: mockToolFactory(noopExec),
+			createBashToolDefinition: mockToolFactory(noopExec),
+			createLsToolDefinition: mockToolFactory(noopExec),
+			createFindToolDefinition: mockToolFactory(noopExec),
+			createGrepToolDefinition: mockToolFactory(noopExec),
+			getAgentDir: () => "/tmp/pi-facelift-test",
+		},
+		TextComponent: MockText,
+	});
+
+	return tools.get("bash");
+}
+
+describe("bash renderCall expansion", () => {
+	it("truncates long commands when collapsed", () => {
+		const bashTool = loadBashTool();
+		const command = `printf '${"x".repeat(120)}'`;
+
+		const rendered = bashTool.renderCall({ command }, mockTheme, {
+			lastComponent: new MockText(),
+			isError: false,
+			state: {},
+			expanded: false,
+			invalidate: () => {},
+		});
+
+		expect(rendered.getText()).toContain("bash");
+		expect(rendered.getText()).toContain("…");
+		expect(rendered.getText()).not.toContain(command);
+	});
+
+	it("shows the full command when expanded", () => {
+		const bashTool = loadBashTool();
+		const command = `printf '${"x".repeat(120)}'`;
+
+		const rendered = bashTool.renderCall({ command }, mockTheme, {
+			lastComponent: new MockText(),
+			isError: false,
+			state: {},
+			expanded: true,
+			invalidate: () => {},
+		});
+
+		expect(rendered.getText()).toContain(command);
+	});
+
+	it("preserves timeout text in both collapsed and expanded states", () => {
+		const bashTool = loadBashTool();
+		const command = `printf '${"x".repeat(120)}'`;
+
+		const collapsed = bashTool.renderCall({ command, timeout: 5 }, mockTheme, {
+			lastComponent: new MockText(),
+			isError: false,
+			state: {},
+			expanded: false,
+			invalidate: () => {},
+		});
+		const expanded = bashTool.renderCall({ command, timeout: 5 }, mockTheme, {
+			lastComponent: new MockText(),
+			isError: false,
+			state: {},
+			expanded: true,
+			invalidate: () => {},
+		});
+
+		expect(collapsed.getText()).toContain("5s timeout");
+		expect(expanded.getText()).toContain("5s timeout");
+	});
+
+	it("truncates expanded ANSI tool headers to fit the terminal width", () => {
+		withStdoutColumns(84, () => {
+			const bashTool = loadBashTool();
+			const command = `printf '${"界".repeat(120)}'`;
+
+			const rendered = bashTool.renderCall({ command }, ansiMockTheme, {
+				lastComponent: new MockText(),
+				isError: false,
+				state: {},
+				expanded: true,
+				invalidate: () => {},
+			});
+
+			// pi-facelift draws its own frame and pi-tui's `Text.render(width)` is
+			// called with `terminal.columns`, so frame lines should be ≤ cols.
+			for (const line of rendered.getText().split("\n")) {
+				expect(visibleWidth(line)).toBeLessThanOrEqual(84);
+			}
+		});
+	});
+
+	it("does not exceed narrow terminal widths", () => {
+		withStdoutColumns(24, () => {
+			const bashTool = loadBashTool();
+			const command = `printf '${"x".repeat(120)}'`;
+
+			const rendered = bashTool.renderCall({ command }, ansiMockTheme, {
+				lastComponent: new MockText(),
+				isError: false,
+				state: {},
+				expanded: true,
+				invalidate: () => {},
+			});
+
+			for (const line of rendered.getText().split("\n")) {
+				expect(visibleWidth(line)).toBeLessThanOrEqual(24);
+			}
+		});
+	});
+});

package/image-rendering.test.ts

@@ -0,0 +1,153 @@
+import { mkdirSync, rmSync } from "node:fs";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import piFaceliftExtension, { __imageInternals } from "./index.ts";
+
+const ENV_KEYS = [
+	"TMUX",
+	"TERM",
+	"TERM_PROGRAM",
+	"LC_TERMINAL",
+	"GHOSTTY_RESOURCES_DIR",
+	"KITTY_WINDOW_ID",
+	"KITTY_PID",
+	"WEZTERM_EXECUTABLE",
+	"WEZTERM_CONFIG_DIR",
+	"WEZTERM_CONFIG_FILE",
+	"COLORTERM",
+	"FACELIFT_IMAGE_PROTOCOL",
+] as const;
+
+class MockText {
+	private text = "";
+	constructor(_text = "", _x = 0, _y = 0) {}
+	setText(value: string) {
+		this.text = value;
+	}
+	getText() {
+		return this.text;
+	}
+}
+
+function mockToolFactory(exec: any) {
+	return (_cwd: string) => ({
+		name: "mock",
+		description: "mock",
+		parameters: { type: "object", properties: {} },
+		execute: exec,
+	});
+}
+
+function loadReadTool(readExec: any) {
+	const noopExec = async () => ({ content: [{ type: "text", text: "" }] });
+	const tools = new Map<string, any>();
+	const pi = {
+		registerTool: (tool: any) => tools.set(tool.name, tool),
+		registerCommand: () => {},
+		on: () => {},
+	};
+
+	piFaceliftExtension(pi, {
+		sdk: {
+			createReadToolDefinition: mockToolFactory(readExec),
+			createBashToolDefinition: mockToolFactory(noopExec),
+			createLsToolDefinition: mockToolFactory(noopExec),
+			createFindToolDefinition: mockToolFactory(noopExec),
+			createGrepToolDefinition: mockToolFactory(noopExec),
+			getAgentDir: () => "/tmp/pi-facelift-test",
+		},
+		TextComponent: MockText,
+	});
+
+	return tools.get("read");
+}
+
+describe("image rendering terminal detection", () => {
+	const envSnapshot = new Map<string, string | undefined>();
+	const agentDir = "/tmp/pi-facelift-test";
+
+	beforeEach(() => {
+		rmSync(agentDir, { recursive: true, force: true });
+		mkdirSync(agentDir, { recursive: true });
+		for (const key of ENV_KEYS) {
+			envSnapshot.set(key, process.env[key]);
+			delete process.env[key];
+		}
+		__imageInternals.resetCachesForTests();
+	});
+
+	afterEach(() => {
+		rmSync(agentDir, { recursive: true, force: true });
+		for (const key of ENV_KEYS) {
+			const value = envSnapshot.get(key);
+			if (value === undefined) delete process.env[key];
+			else process.env[key] = value;
+		}
+		__imageInternals.resetCachesForTests();
+	});
+
+	it("detects kitty protocol inside tmux via KITTY_WINDOW_ID", () => {
+		process.env.TMUX = "/tmp/tmux-1000/default,123,0";
+		process.env.TERM_PROGRAM = "tmux";
+		process.env.KITTY_WINDOW_ID = "1";
+
+		expect(__imageInternals.getOuterTerminal()).toBe("kitty");
+		expect(__imageInternals.detectImageProtocol()).toBe("kitty");
+	});
+
+	it("detects wezterm protocol inside tmux via WEZTERM_EXECUTABLE", () => {
+		process.env.TMUX = "/tmp/tmux-1000/default,123,0";
+		process.env.TERM_PROGRAM = "tmux";
+		process.env.WEZTERM_EXECUTABLE = "/Applications/WezTerm.app/Contents/MacOS/wezterm";
+
+		expect(__imageInternals.getOuterTerminal()).toBe("WezTerm");
+		expect(__imageInternals.detectImageProtocol()).toBe("iterm2");
+	});
+
+	it("falls back to tmux client term for outer terminal detection", () => {
+		process.env.TMUX = "/tmp/tmux-1000/default,123,0";
+		process.env.TERM_PROGRAM = "tmux";
+		__imageInternals.setTmuxClientTermOverrideForTests("xterm-kitty");
+
+		expect(__imageInternals.getOuterTerminal()).toBe("kitty");
+		expect(__imageInternals.detectImageProtocol()).toBe("kitty");
+	});
+
+	it("reports warning when tmux allow-passthrough is off", () => {
+		process.env.TMUX = "/tmp/tmux-1000/default,123,0";
+		__imageInternals.setTmuxAllowPassthroughOverrideForTests(false);
+
+		expect(__imageInternals.getTmuxPassthroughWarning("kitty")).toContain("allow-passthrough is off");
+	});
+
+	it("does not warn when tmux allow-passthrough is enabled", () => {
+		process.env.TMUX = "/tmp/tmux-1000/default,123,0";
+		__imageInternals.setTmuxAllowPassthroughOverrideForTests(true);
+
+		expect(__imageInternals.getTmuxPassthroughWarning("kitty")).toBeNull();
+	});
+
+	it("renders image metadata without a second inline preview", async () => {
+		process.env.TERM_PROGRAM = "kitty";
+
+		const readTool = loadReadTool(async () => ({
+			content: [{ type: "image", data: Buffer.from("fake").toString("base64"), mimeType: "image/png" }],
+		}));
+
+		const result = await readTool.execute("t1", { path: "media/inline-image.png" }, null, null, {});
+		const rendered = readTool.renderResult(result, {}, {}, {
+			lastComponent: new MockText(),
+			isError: false,
+			state: {},
+			expanded: false,
+			invalidate: () => {},
+		});
+
+		expect(rendered.getText()).toContain("image/png");
+		expect(rendered.getText()).not.toContain("\x1b_G");
+		expect(result.content).toEqual([
+			{ type: "image", data: Buffer.from("fake").toString("base64"), mimeType: "image/png" },
+		]);
+	});
+});