@heyhuynhgiabuu/pi-pretty 0.3.1 → 0.3.2

package/README.md

@@ -41,7 +41,15 @@ pi -e ./src/index.ts
 ## Terminal support for inline images
 
 Inline image previews are supported in **Ghostty**, **Kitty**, **iTerm2**, and **WezTerm**.  
-When running in **tmux**, pi-pretty uses passthrough escape sequences so inline image protocols still work.
+When running in **tmux**, pi-pretty uses passthrough escape sequences.
+
+> tmux must allow passthrough. Enable it with:
+>
+> ```tmux
+> set -g allow-passthrough on
+> ```
+>
+> (or run once in a session: `tmux set -g allow-passthrough on`)
 
 ## Configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@heyhuynhgiabuu/pi-pretty",
-	"version": "0.3.1",
+	"version": "0.3.2",
 	"description": "Pretty terminal output for pi — syntax-highlighted file reads, colored bash output, tree-view directory listings, and more.",
 	"author": "huynhgiabuu",
 	"license": "MIT",

package/release-notes/v0.3.2.md

@@ -0,0 +1,34 @@
+# pi-pretty v0.3.2
+
+## Summary
+This patch release fixes inline image rendering reliability when running `pi-pretty` inside `tmux`.
+
+## What changed
+- Fixed terminal detection in tmux for:
+  - Kitty (`KITTY_WINDOW_ID`, `KITTY_PID`)
+  - WezTerm (`WEZTERM_EXECUTABLE`, `WEZTERM_CONFIG_DIR`, `WEZTERM_CONFIG_FILE`)
+- Added tmux fallback detection via:
+  - `tmux display-message -p "#{client_termname}"`
+- Replaced static tmux detection with runtime detection to avoid stale module-load state.
+- Added explicit warning when tmux passthrough is disabled:
+  - `tmux allow-passthrough is off. Run: tmux set -g allow-passthrough on`
+- Added non-PNG warning for Kitty/Ghostty image rendering path.
+- Added test coverage for image protocol detection and tmux passthrough warning behavior.
+- Updated README with tmux passthrough setup instructions.
+
+## Files
+- `src/index.ts`
+- `test/image-rendering.test.ts`
+- `README.md`
+
+## Verification
+- `npm run typecheck` ✅
+- `npm test` ✅ (46 tests)
+- `npm run lint` ⚠️ fails due to existing Biome diagnostics in legacy code paths (pre-existing, not introduced in this patch).
+
+## Upgrade notes
+When using `tmux`, enable passthrough:
+
+```tmux
+set -g allow-passthrough on
+```

package/src/index.ts

@@ -23,6 +23,7 @@
  *   • Large-file fallback (skip highlighting, still show line numbers)
  */
 
+import * as childProcess from "node:child_process";
 import { existsSync, mkdirSync, statSync } from "node:fs";
 import { basename, dirname, extname, join, relative } from "node:path";
 
@@ -217,7 +218,45 @@ function lang(fp: string): BundledLanguage | undefined {
 
 type ImageProtocol = "iterm2" | "kitty" | "none";
 
-const IS_TMUX = !!process.env.TMUX;
+let _tmuxClientTermCache: string | null | undefined;
+let _tmuxAllowPassthroughCache: boolean | null | undefined;
+let _tmuxClientTermOverrideForTests: string | null | undefined;
+let _tmuxAllowPassthroughOverrideForTests: boolean | null | undefined;
+
+function isTmuxSession(): boolean {
+	return !!process.env.TMUX || /^(tmux|screen)/.test(process.env.TERM ?? "");
+}
+
+function normalizeTerminalName(term: string): string {
+	const t = term.toLowerCase();
+	if (t.includes("kitty")) return "kitty";
+	if (t.includes("ghostty")) return "ghostty";
+	if (t.includes("wezterm")) return "WezTerm";
+	if (t.includes("iterm")) return "iTerm.app";
+	if (t.includes("mintty")) return "mintty";
+	return term;
+}
+
+function readTmuxClientTerm(): string | null {
+	if (_tmuxClientTermOverrideForTests !== undefined) {
+		return _tmuxClientTermOverrideForTests ? normalizeTerminalName(_tmuxClientTermOverrideForTests) : null;
+	}
+	if (!isTmuxSession()) return null;
+	if (_tmuxClientTermCache !== undefined) return _tmuxClientTermCache;
+	try {
+		const term = childProcess
+			.execFileSync("tmux", ["display-message", "-p", "#{client_termname}"], {
+				encoding: "utf8",
+				stdio: ["ignore", "pipe", "ignore"],
+				timeout: 200,
+			})
+			.trim();
+		_tmuxClientTermCache = term ? normalizeTerminalName(term) : null;
+	} catch {
+		_tmuxClientTermCache = null;
+	}
+	return _tmuxClientTermCache;
+}
 
 /**
  * Detect the outer terminal when running inside tmux.
@@ -225,27 +264,34 @@ const IS_TMUX = !!process.env.TMUX;
  * the environment of the tmux server or can be inferred.
  */
 function getOuterTerminal(): string {
-	// Direct terminal (not in tmux)
-	const term = process.env.TERM_PROGRAM ?? "";
-	if (term !== "tmux" && term !== "screen") return term;
-
-	// Inside tmux: check common env vars that leak through
-	// Ghostty sets this; iTerm2 sets LC_TERMINAL
+	// Environment hints that often survive inside tmux
 	if (process.env.LC_TERMINAL === "iTerm2") return "iTerm.app";
-
-	// TERM_PROGRAM_VERSION sometimes survives into tmux
-	// Try to detect via COLORTERM or other hints
 	if (process.env.GHOSTTY_RESOURCES_DIR) return "ghostty";
+	if (process.env.KITTY_WINDOW_ID || process.env.KITTY_PID) return "kitty";
+	if (process.env.WEZTERM_EXECUTABLE || process.env.WEZTERM_CONFIG_DIR || process.env.WEZTERM_CONFIG_FILE) {
+		return "WezTerm";
+	}
 
-	// Default: assume modern terminal if truecolor is supported
-	if (process.env.COLORTERM === "truecolor" || process.env.COLORTERM === "24bit") {
-		// Can't determine exact terminal, but likely modern
-		return "unknown-modern";
+	const termProgram = process.env.TERM_PROGRAM ?? "";
+	if (termProgram && termProgram !== "tmux" && termProgram !== "screen") {
+		return normalizeTerminalName(termProgram);
 	}
-	return term;
+
+	const tmuxClientTerm = readTmuxClientTerm();
+	if (tmuxClientTerm) return tmuxClientTerm;
+
+	const term = process.env.TERM ?? "";
+	if (term) return normalizeTerminalName(term);
+	if (process.env.COLORTERM === "truecolor" || process.env.COLORTERM === "24bit") return "unknown-modern";
+	return termProgram;
 }
 
 function detectImageProtocol(): ImageProtocol {
+	const forced = (process.env.PRETTY_IMAGE_PROTOCOL ?? "").toLowerCase();
+	if (forced === "kitty" || forced === "iterm2" || forced === "none") {
+		return forced;
+	}
+
 	const term = getOuterTerminal();
 	// Ghostty and Kitty use the Kitty graphics protocol
 	if (term === "ghostty" || term === "kitty") return "kitty";
@@ -255,18 +301,67 @@ function detectImageProtocol(): ImageProtocol {
 	return "none";
 }
 
+function tmuxAllowsPassthrough(): boolean | null {
+	if (_tmuxAllowPassthroughOverrideForTests !== undefined) return _tmuxAllowPassthroughOverrideForTests;
+	if (!isTmuxSession()) return null;
+	if (_tmuxAllowPassthroughCache !== undefined) return _tmuxAllowPassthroughCache;
+	try {
+		const value = childProcess
+			.execFileSync("tmux", ["show-options", "-gv", "allow-passthrough"], {
+				encoding: "utf8",
+				stdio: ["ignore", "pipe", "ignore"],
+				timeout: 200,
+			})
+			.trim()
+			.toLowerCase();
+		_tmuxAllowPassthroughCache = value === "on" || value === "all";
+	} catch {
+		_tmuxAllowPassthroughCache = null;
+	}
+	return _tmuxAllowPassthroughCache;
+}
+
+function getTmuxPassthroughWarning(protocol: ImageProtocol): string | null {
+	if (!isTmuxSession() || protocol === "none") return null;
+	if (tmuxAllowsPassthrough() === false) {
+		return "tmux allow-passthrough is off. Run: tmux set -g allow-passthrough on";
+	}
+	return null;
+}
+
 /**
  * Wrap escape sequence for tmux passthrough.
  * tmux requires: ESC Ptmux; <escaped-sequence> ESC \
  * Inner ESC chars must be doubled.
  */
 function tmuxWrap(seq: string): string {
-	if (!IS_TMUX) return seq;
+	if (!isTmuxSession()) return seq;
 	// Double all ESC chars inside the sequence
 	const escaped = seq.split("\x1b").join("\x1b\x1b");
 	return `\x1bPtmux;${escaped}\x1b\\`;
 }
 
+export const __imageInternals = {
+	isTmuxSession,
+	getOuterTerminal,
+	detectImageProtocol,
+	tmuxWrap,
+	tmuxAllowsPassthrough,
+	getTmuxPassthroughWarning,
+	setTmuxClientTermOverrideForTests: (value: string | null | undefined) => {
+		_tmuxClientTermOverrideForTests = value;
+	},
+	setTmuxAllowPassthroughOverrideForTests: (value: boolean | null | undefined) => {
+		_tmuxAllowPassthroughOverrideForTests = value;
+	},
+	resetCachesForTests: () => {
+		_tmuxClientTermCache = undefined;
+		_tmuxAllowPassthroughCache = undefined;
+		_tmuxClientTermOverrideForTests = undefined;
+		_tmuxAllowPassthroughOverrideForTests = undefined;
+	},
+};
+
 /**
  * Render base64 image inline using iTerm2 inline image protocol.
  * Protocol: ESC ] 1337 ; File=[args] : base64data BEL
@@ -916,9 +1011,16 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 				out.push(rule(tw));
 
 				const protocol = detectImageProtocol();
-				if (protocol === "kitty") {
-					const imgCols = Math.min(tw - 4, 80);
-					out.push(renderKittyImage(d.data, { cols: imgCols }));
+				const passthroughWarning = getTmuxPassthroughWarning(protocol);
+				if (passthroughWarning) {
+					out.push(`  ${FG_YELLOW}${passthroughWarning}${RST}`);
+				} else if (protocol === "kitty") {
+					if (d.mimeType && d.mimeType !== "image/png") {
+						out.push(`  ${FG_YELLOW}Kitty/Ghostty inline preview currently supports PNG payloads (got ${d.mimeType})${RST}`);
+					} else {
+						const imgCols = Math.min(tw - 4, 80);
+						out.push(renderKittyImage(d.data, { cols: imgCols }));
+					}
 				} else if (protocol === "iterm2") {
 					const imgWidth = Math.min(tw - 4, 80);
 					out.push(

package/test/image-rendering.test.ts

@@ -0,0 +1,165 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import piPrettyExtension, { __imageInternals } from "../src/index.js";
+
+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",
+	"PRETTY_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: () => {},
+	};
+
+	piPrettyExtension(pi, {
+		sdk: {
+			createReadToolDefinition: mockToolFactory(readExec),
+			createBashToolDefinition: mockToolFactory(noopExec),
+			createLsToolDefinition: mockToolFactory(noopExec),
+			createFindToolDefinition: mockToolFactory(noopExec),
+			createGrepToolDefinition: mockToolFactory(noopExec),
+			getAgentDir: () => "/tmp/pi-pretty-test",
+		},
+		TextComponent: MockText,
+	});
+
+	return tools.get("read");
+}
+
+describe("image rendering terminal detection", () => {
+	const envSnapshot = new Map<string, string | undefined>();
+
+	beforeEach(() => {
+		for (const key of ENV_KEYS) {
+			envSnapshot.set(key, process.env[key]);
+			delete process.env[key];
+		}
+		__imageInternals.resetCachesForTests();
+	});
+
+	afterEach(() => {
+		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 explicit warning for read image when tmux passthrough is off", async () => {
+		process.env.TMUX = "/tmp/tmux-1000/default,123,0";
+		process.env.TERM_PROGRAM = "tmux";
+		process.env.KITTY_WINDOW_ID = "1";
+		__imageInternals.setTmuxAllowPassthroughOverrideForTests(false);
+
+		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("allow-passthrough is off");
+	});
+
+	it("warns on non-PNG payloads for kitty protocol", async () => {
+		process.env.TERM_PROGRAM = "kitty";
+
+		const readTool = loadReadTool(async () => ({
+			content: [{ type: "image", data: Buffer.from("jpeg").toString("base64"), mimeType: "image/jpeg" }],
+		}));
+
+		const result = await readTool.execute("t1", { path: "media/photo.jpg" }, null, null, {});
+		const rendered = readTool.renderResult(result, {}, {}, {
+			lastComponent: new MockText(),
+			isError: false,
+			state: {},
+			expanded: false,
+			invalidate: () => {},
+		});
+
+		expect(rendered.getText()).toContain("supports PNG payloads");
+	});
+});