@xynogen/pix-pretty 1.6.3 → 1.7.0

package/README.md

@@ -21,6 +21,10 @@ Complete rendering and formatting solution for Pi Coding Agent with syntax highl
 - **Atomic deletion** - Delete entire paste markers as single units
 - **Type-aware labels** - Visual distinction between image and text pastes
 
+### Permission Dialog Overlay
+
+- **Shared gate overlay** - `showOverlay(ui, config)` (export `./gate-overlay`) is the one permission-dialog component used by both `pix-gate` and `pix-sudo`. Two modes: `mode:"confirm"` shows a SelectList only; `mode:"sudo"` shows a SelectList then a masked password stage. Returns `{ action: "approved" | "denied" | "timeout", password? }`. All dialogs are padded (`Box` `paddingX=2`, `paddingY=1`). The simpler `./confirm` export stays for plain boolean Yes/No prompts — `gate-overlay` is its richer multi-choice, password-capable sibling.
+
 ### Reasoning Tag Rendering
 
 - **Live streaming** - Splits `<think>`/`<thinking>` regions into native Pi `thinking` content blocks token-by-token during streaming

package/package.json

@@ -1,12 +1,14 @@
 {
 	"name": "@xynogen/pix-pretty",
-	"version": "1.6.3",
+	"version": "1.7.0",
 	"description": "Enhanced tool output rendering with syntax highlighting, file icons, tree views, FFF search, and paste chip formatting",
 	"type": "module",
 	"main": "src/index.ts",
 	"exports": {
 		".": "./src/index.ts",
 		"./ansi": "./src/ansi.ts",
+		"./confirm": "./src/confirm.ts",
+		"./progress": "./src/progress.ts",
 		"./config": "./src/config.ts",
 		"./diff": "./src/diff.ts",
 		"./diff-render": "./src/diff-render.ts",
@@ -18,7 +20,8 @@
 		"./types": "./src/types.ts",
 		"./utils": "./src/utils.ts",
 		"./resize": "./src/resize.ts",
-		"./context": "./src/tools/context.ts"
+		"./context": "./src/tools/context.ts",
+		"./gate-overlay": "./src/gate-overlay.ts"
 	},
 	"scripts": {
 		"test": "bun test"
@@ -28,13 +31,6 @@
 		"README.md",
 		"LICENSE"
 	],
-	"pi": {
-		"extensions": [
-			"./src/index.ts",
-			"./src/paste-chips.ts",
-			"./src/thinking.ts"
-		]
-	},
 	"keywords": [
 		"pi",
 		"pi-package",

package/src/confirm.ts

@@ -0,0 +1,174 @@
+/**
+ * pix-pretty/confirm — reusable Yes/No confirmation overlay.
+ *
+ * A single coloured SelectList overlay (Yes / No) with optional title, body
+ * lines and an auto-cancel countdown. Mirrors the confirm stage of pix-sudo
+ * so any extension can get the same look without re-implementing it.
+ *
+ * Returns true on confirm, false on deny / cancel / timeout.
+ */
+
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import { Box, type SelectItem, SelectList, Text } from "@earendil-works/pi-tui";
+
+// Minimal structural type for the `ctx.ui.custom` host call. Kept local so the
+// component has no hard dependency on a specific Pi context shape.
+interface CustomTheme {
+	fg(color: string, text: string): string;
+	bg(color: string, text: string): string;
+	bold(text: string): string;
+}
+
+interface CustomComponent {
+	render(width: number): string[];
+	invalidate(): void;
+	handleInput(data: string): void;
+	focused?: boolean;
+}
+
+export interface ConfirmUI {
+	custom<T>(
+		cb: (
+			tui: { requestRender(): void },
+			theme: CustomTheme,
+			kb: unknown,
+			done: (v: T) => void,
+		) => CustomComponent,
+		opts?: { overlay?: boolean },
+	): Promise<T | undefined>;
+}
+
+export interface ConfirmOptions {
+	/** Title shown bold at the top (e.g. "Update Pi & extensions?"). */
+	title: string;
+	/** Optional body lines rendered under the title. */
+	body?: string[];
+	/** Label for the confirm choice. Default "Yes". */
+	confirmLabel?: string;
+	/** Label for the deny choice. Default "No". */
+	denyLabel?: string;
+	/** Accent colour for border + selection. Default "accent". */
+	accent?: string;
+	/** Auto-cancel after this many ms (0 disables). Default 0. */
+	timeoutMs?: number;
+}
+
+const SECOND_MS = 1000;
+const COUNTDOWN_WARN_S = 5;
+
+/**
+ * Show a Yes/No overlay. Resolves true on confirm, false otherwise.
+ */
+export function confirmOverlay(
+	ui: ConfirmUI,
+	opts: ConfirmOptions,
+): Promise<boolean> {
+	const accent = opts.accent ?? "accent";
+	const timeoutMs = opts.timeoutMs ?? 0;
+
+	return new Promise((resolve) => {
+		const controller = new AbortController();
+		const timer =
+			timeoutMs > 0
+				? setTimeout(() => controller.abort(), timeoutMs)
+				: undefined;
+
+		ui.custom<boolean>(
+			(tui, theme, _kb, done) => {
+				let ticker: ReturnType<typeof setInterval> | undefined;
+
+				const choices: SelectItem[] = [
+					{
+						value: "yes",
+						label: opts.confirmLabel ?? "Yes",
+						description: "Proceed",
+					},
+					{
+						value: "no",
+						label: opts.denyLabel ?? "No",
+						description: "Cancel",
+					},
+				];
+
+				const selectList = new SelectList(choices, choices.length, {
+					selectedPrefix: (t) => theme.fg(accent, t),
+					selectedText: (t) => theme.fg(accent, t),
+					description: (t) => theme.fg("muted", t),
+					scrollInfo: (t) => theme.fg("dim", t),
+					noMatch: (t) => theme.fg("warning", t),
+				});
+
+				const container = new Box(0, 0, (s) => theme.bg("customMessageBg", s));
+				container.addChild(
+					new DynamicBorder((s: string) => theme.fg(accent, s)),
+				);
+				container.addChild(
+					new Text(theme.fg(accent, theme.bold(opts.title)), 1, 0),
+				);
+
+				for (const line of opts.body ?? []) {
+					container.addChild(new Text(theme.fg("text", line), 1, 0));
+				}
+
+				if (timeoutMs > 0) {
+					const deadlineMs = Date.now() + timeoutMs;
+					const countdownText = new Text("", 1, 0);
+					const updateCountdown = () => {
+						const remaining = Math.max(
+							0,
+							Math.ceil((deadlineMs - Date.now()) / SECOND_MS),
+						);
+						countdownText.setText(
+							theme.fg("dim", "Auto-cancel in ") +
+								theme.fg(
+									remaining <= COUNTDOWN_WARN_S ? accent : "muted",
+									`${remaining}s`,
+								),
+						);
+					};
+					updateCountdown();
+					ticker = setInterval(() => {
+						updateCountdown();
+						tui.requestRender();
+					}, SECOND_MS);
+					container.addChild(countdownText);
+				}
+
+				container.addChild(selectList);
+				container.addChild(
+					new Text(
+						theme.fg("dim", "↑↓ navigate • enter select • esc cancel"),
+						1,
+						0,
+					),
+				);
+				container.addChild(
+					new DynamicBorder((s: string) => theme.fg(accent, s)),
+				);
+
+				const finish = (value: boolean) => {
+					if (timer !== undefined) clearTimeout(timer);
+					if (ticker !== undefined) clearInterval(ticker);
+					done(value);
+				};
+
+				selectList.onSelect = (item) => finish(item.value === "yes");
+				selectList.onCancel = () => finish(false);
+				controller.signal.addEventListener("abort", () => finish(false));
+
+				return {
+					render: (w: number) => container.render(w),
+					invalidate: () => container.invalidate(),
+					handleInput: (data: string) => {
+						selectList.handleInput(data);
+						tui.requestRender();
+					},
+				};
+			},
+			{ overlay: true },
+		).then((result) => {
+			if (timer !== undefined) clearTimeout(timer);
+			resolve(result ?? false);
+		});
+	});
+}

package/src/gate-overlay.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, test } from "bun:test";
+import { type OverlayUI, showOverlay } from "./gate-overlay.ts";
+
+// ── Mock host ─────────────────────────────────────────────────────────────────
+//
+// Drive showOverlay deterministically without a real TUI. The mock invokes the
+// builder callback (so components initialise + wire their handlers), captures
+// the rendered lines, then hands a `drive(comp, done)` hook to the test which
+// triggers selectList.onSelect / maskedInput.onSubmit / etc via the real
+// component instances — exactly what real keyboard input would do.
+
+const theme = {
+	fg: (_c: string, t: string) => t,
+	bg: (_c: string, t: string) => t,
+	bold: (t: string) => t,
+};
+
+interface Wired {
+	render(w: number): string[];
+	invalidate(): void;
+	handleInput(d: string): void;
+}
+
+/**
+ * Build a mock UI. `drive` receives the rendered lines and a `feed` fn that
+ * pushes raw input strings into the component. To trigger a selection we feed
+ * the SelectList keys; simpler: we expose the live component so the test can
+ * call its handlers. We do the latter via the captured component ref.
+ */
+function makeUI(
+	onReady: (comp: Wired, finish: (v: unknown) => void) => void,
+): OverlayUI {
+	return {
+		custom: async <T>(
+			cb: (
+				tui: { requestRender(): void },
+				th: typeof theme,
+				kb: unknown,
+				done: (v: T) => void,
+			) => Wired,
+		): Promise<T | undefined> => {
+			let resolved: T | undefined;
+			const done = (v: T) => {
+				resolved = v;
+			};
+			const comp = cb({ requestRender: () => {} }, theme, undefined, done);
+			comp.render(80); // initialise render path
+			onReady(comp, done as (v: unknown) => void);
+			return resolved;
+		},
+	};
+}
+
+// SelectList handles "\r" (enter) to select the highlighted item, and arrow
+// keys to move. The first item is highlighted by default.
+const ENTER = "\r";
+const DOWN = "\x1b[B";
+
+describe("showOverlay — confirm mode", () => {
+	test("selecting the approve choice (first) returns approved", async () => {
+		const result = await showOverlay(
+			makeUI((comp) => {
+				comp.handleInput(ENTER); // select item 0 = "yes"
+			}),
+			{ mode: "confirm", title: "T", timeoutMs: 0 },
+		);
+		expect(result.action).toBe("approved");
+		expect(result.password).toBeUndefined();
+	});
+
+	test("selecting the deny choice (second) returns denied", async () => {
+		const result = await showOverlay(
+			makeUI((comp) => {
+				comp.handleInput(DOWN); // move to item 1 = "no"
+				comp.handleInput(ENTER);
+			}),
+			{ mode: "confirm", title: "T", timeoutMs: 0 },
+		);
+		expect(result.action).toBe("denied");
+	});
+
+	test("deny-first ordering: item 0 is the deny choice when configured so", async () => {
+		const result = await showOverlay(
+			makeUI((comp) => {
+				comp.handleInput(ENTER); // select item 0
+			}),
+			{
+				mode: "confirm",
+				title: "Critical",
+				timeoutMs: 0,
+				approveValue: "yes",
+				choices: [
+					{ value: "no", label: "Block", description: "deny" },
+					{ value: "yes", label: "Allow", description: "approve" },
+				],
+			},
+		);
+		// item 0 = "no" => not the approveValue => denied
+		expect(result.action).toBe("denied");
+	});
+
+	test("renders title and body lines", async () => {
+		let captured: string[] = [];
+		await showOverlay(
+			makeUI((comp) => {
+				captured = comp.render(80);
+				comp.handleInput(ENTER);
+			}),
+			{
+				mode: "confirm",
+				title: "MY TITLE",
+				body: ["body-line-x"],
+				timeoutMs: 0,
+			},
+		);
+		const joined = captured.join("\n");
+		expect(joined).toContain("MY TITLE");
+		expect(joined).toContain("body-line-x");
+	});
+});
+
+describe("showOverlay — sudo mode", () => {
+	test("approve then submit password returns approved + real password", async () => {
+		const result = await showOverlay(
+			makeUI((comp) => {
+				comp.handleInput(ENTER); // select item 0 = "yes" => switch to password stage
+				comp.handleInput("s3cret"); // type into MaskedInput
+				comp.handleInput(ENTER); // submit
+			}),
+			{ mode: "sudo", title: "ROOT", timeoutMs: 0 },
+		);
+		expect(result.action).toBe("approved");
+		expect(result.password).toBe("s3cret");
+	});
+
+	test("deny at select stage returns denied, never reaches password", async () => {
+		const result = await showOverlay(
+			makeUI((comp) => {
+				comp.handleInput(DOWN); // item 1 = "no"
+				comp.handleInput(ENTER);
+			}),
+			{ mode: "sudo", title: "ROOT", timeoutMs: 0 },
+		);
+		expect(result.action).toBe("denied");
+		expect(result.password).toBeUndefined();
+	});
+
+	test("password is masked in render (● not plaintext)", async () => {
+		let pwFrame: string[] = [];
+		await showOverlay(
+			makeUI((comp) => {
+				comp.handleInput(ENTER); // to password stage
+				comp.handleInput("abc");
+				pwFrame = comp.render(80);
+				comp.handleInput(ENTER); // submit so the promise resolves
+			}),
+			{ mode: "sudo", title: "ROOT", timeoutMs: 0 },
+		);
+		const joined = pwFrame.join("\n");
+		expect(joined).not.toContain("abc");
+		expect(joined).toContain("●");
+	});
+});

package/src/gate-overlay.ts

@@ -0,0 +1,310 @@
+/**
+ * pix-pretty/gate-overlay — shared permission dialog component.
+ *
+ * One component, two modes:
+ *   "confirm" — SelectList only. Used by pix-gate for command gating.
+ *   "sudo"    — SelectList → masked password input. Used by pix-sudo.
+ *
+ * Both modes share: colored border, title, body lines, countdown.
+ *
+ * Design goals:
+ *   - Pure function — no side effects, no global state.
+ *   - Fully unit-testable: inject a mock `ui` to drive inputs deterministically.
+ *   - Single source of truth for the overlay look across pix-gate and pix-sudo.
+ */
+
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import {
+	Box,
+	Input,
+	type SelectItem,
+	SelectList,
+	Text,
+} from "@earendil-works/pi-tui";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export type OverlayAction = "approved" | "denied" | "timeout";
+
+export interface OverlayResult {
+	action: OverlayAction;
+	/** Only present when action === "approved" and mode === "sudo". */
+	password?: string;
+}
+
+export interface OverlayChoice {
+	value: string;
+	label: string;
+	description: string;
+}
+
+interface BaseConfig {
+	/** Accent colour token (e.g. "error", "warning", "accent"). Default "accent". */
+	accent?: string;
+	/** Title shown bold at the top. */
+	title: string;
+	/** Optional body lines under the title. */
+	body?: string[];
+	/** Auto-deny after this many ms. 0 = no timeout. Default 30_000. */
+	timeoutMs?: number;
+	/**
+	 * Choices shown in the SelectList.
+	 * The choice whose value === approveValue counts as approval.
+	 * Default: [{ value:"yes", label:"Allow" }, { value:"no", label:"Deny" }]
+	 */
+	choices?: OverlayChoice[];
+	/** Which choice value means "approved". Default "yes". */
+	approveValue?: string;
+}
+
+export interface ConfirmConfig extends BaseConfig {
+	mode: "confirm";
+}
+
+export interface SudoConfig extends BaseConfig {
+	mode: "sudo";
+	/** Label for the password input hint. Default "Sudo password:" */
+	passwordLabel?: string;
+}
+
+export type OverlayConfig = ConfirmConfig | SudoConfig;
+
+// Minimal structural types — no hard dep on a specific Pi context shape.
+interface OverlayTheme {
+	fg(color: string, text: string): string;
+	bg(color: string, text: string): string;
+	bold(text: string): string;
+}
+
+interface OverlayTui {
+	requestRender(): void;
+}
+
+interface OverlayComponent {
+	render(width: number): string[];
+	invalidate(): void;
+	handleInput(data: string): void;
+	focused?: boolean;
+}
+
+export interface OverlayUI {
+	custom<T>(
+		cb: (
+			tui: OverlayTui,
+			theme: OverlayTheme,
+			kb: unknown,
+			done: (v: T) => void,
+		) => OverlayComponent,
+		opts?: { overlay?: boolean },
+	): Promise<T | undefined>;
+}
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+const SECOND_MS = 1_000;
+const COUNTDOWN_WARN_S = 5;
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+const DEFAULT_CHOICES: OverlayChoice[] = [
+	{ value: "yes", label: "Allow", description: "Proceed" },
+	{ value: "no", label: "Deny", description: "Block" },
+];
+
+// ── Masked input (● per char) ─────────────────────────────────────────────────
+
+class MaskedInput extends Input {
+	override render(width: number): string[] {
+		const real = this.getValue();
+		this.setValue("●".repeat(real.length));
+		const lines = super.render(width);
+		this.setValue(real);
+		return lines;
+	}
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+/**
+ * Show a permission overlay and resolve the user's decision.
+ *
+ * @example — gate confirm
+ * ```ts
+ * const result = await showOverlay(ui, {
+ *   mode: "confirm",
+ *   title: "⚠️  DANGEROUS",
+ *   body: ["rm -rf /tmp/work"],
+ *   accent: "warning",
+ *   timeoutMs: 30_000,
+ *   choices: [
+ *     { value: "yes", label: "Allow", description: "Run the command" },
+ *     { value: "no",  label: "Deny",  description: "Block it"        },
+ *   ],
+ * });
+ * ```
+ *
+ * @example — sudo prompt
+ * ```ts
+ * const result = await showOverlay(ui, {
+ *   mode: "sudo",
+ *   title: "🔐 ROOT COMMAND REQUEST",
+ *   body: ["Intent: install package", "Command: apt install foo"],
+ *   accent: "error",
+ * });
+ * if (result.action === "approved") runWithSudo(cmd, result.password!);
+ * ```
+ */
+export function showOverlay(
+	ui: OverlayUI,
+	config: OverlayConfig,
+): Promise<OverlayResult> {
+	const accent = config.accent ?? "accent";
+	const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const choices = config.choices ?? DEFAULT_CHOICES;
+	const approveVal = config.approveValue ?? "yes";
+
+	return new Promise((resolve) => {
+		const controller = new AbortController();
+		const timer =
+			timeoutMs > 0
+				? setTimeout(() => controller.abort(), timeoutMs)
+				: undefined;
+
+		ui.custom<OverlayResult>(
+			(tui, theme, _kb, done) => {
+				// ── state ───────────────────────────────────────────────────────
+				type Stage = "select" | "password";
+				let stage: Stage = "select";
+
+				// ── components ──────────────────────────────────────────────────
+				const selectItems: SelectItem[] = choices.map((c) => ({
+					value: c.value,
+					label: c.label,
+					description: c.description,
+				}));
+
+				const selectList = new SelectList(selectItems, selectItems.length, {
+					selectedPrefix: (t) => theme.fg(accent, t),
+					selectedText: (t) => theme.fg(accent, t),
+					description: (t) => theme.fg("muted", t),
+					scrollInfo: (t) => theme.fg("dim", t),
+					noMatch: (t) => theme.fg("warning", t),
+				});
+
+				const maskedInput = new MaskedInput();
+				const passwordHint = new Text("", 1, 0);
+				const helpText = new Text("", 1, 0);
+				const countdownText = new Text("", 1, 0);
+
+				// ── container ───────────────────────────────────────────────────
+				// padding: 2 cols horizontal, 1 row vertical around all dialog content
+				const container = new Box(2, 1, (s) => theme.bg("customMessageBg", s));
+				container.addChild(
+					new DynamicBorder((s: string) => theme.fg(accent, s)),
+				);
+				container.addChild(
+					new Text(theme.fg(accent, theme.bold(config.title)), 1, 0),
+				);
+
+				for (const line of config.body ?? []) {
+					container.addChild(new Text(theme.fg("text", line), 1, 0));
+				}
+
+				// ── countdown ───────────────────────────────────────────────────
+				let ticker: ReturnType<typeof setInterval> | undefined;
+				if (timeoutMs > 0) {
+					const deadlineMs = Date.now() + timeoutMs;
+					const updateCountdown = () => {
+						const remaining = Math.max(
+							0,
+							Math.ceil((deadlineMs - Date.now()) / SECOND_MS),
+						);
+						countdownText.setText(
+							theme.fg("dim", "Auto-deny in ") +
+								theme.fg(
+									remaining <= COUNTDOWN_WARN_S ? accent : "muted",
+									`${remaining}s`,
+								),
+						);
+					};
+					updateCountdown();
+					ticker = setInterval(() => {
+						updateCountdown();
+						tui.requestRender();
+					}, SECOND_MS);
+					container.addChild(countdownText);
+				}
+
+				// ── select stage (always starts here) ───────────────────────────
+				helpText.setText(
+					theme.fg("dim", "↑↓ navigate • enter select • esc deny"),
+				);
+				container.addChild(selectList);
+				container.addChild(helpText);
+				container.addChild(
+					new DynamicBorder((s: string) => theme.fg(accent, s)),
+				);
+
+				// ── finish helper ────────────────────────────────────────────────
+				const finish = (result: OverlayResult) => {
+					if (timer !== undefined) clearTimeout(timer);
+					if (ticker !== undefined) clearInterval(ticker);
+					done(result);
+				};
+
+				// ── stage: password (sudo mode only) ────────────────────────────
+				const switchToPassword = () => {
+					stage = "password";
+					container.removeChild(selectList);
+					container.removeChild(helpText);
+
+					const label =
+						config.mode === "sudo"
+							? (config.passwordLabel ?? "Sudo password:")
+							: "Password:";
+					passwordHint.setText(theme.fg("muted", label));
+					container.addChild(passwordHint);
+					container.addChild(maskedInput);
+					container.addChild(
+						new Text(theme.fg("dim", "enter confirm • esc cancel"), 1, 0),
+					);
+					tui.requestRender();
+				};
+
+				// ── event wiring ─────────────────────────────────────────────────
+				selectList.onSelect = (item) => {
+					if (item.value !== approveVal) {
+						finish({ action: "denied" });
+					} else if (config.mode === "sudo") {
+						switchToPassword();
+					} else {
+						finish({ action: "approved" });
+					}
+				};
+				selectList.onCancel = () => finish({ action: "denied" });
+
+				maskedInput.onSubmit = (pw) =>
+					finish({ action: "approved", password: pw });
+				maskedInput.onEscape = () => finish({ action: "denied" });
+
+				controller.signal.addEventListener("abort", () =>
+					finish({ action: "timeout" }),
+				);
+
+				// ── component interface ──────────────────────────────────────────
+				return {
+					render: (w) => container.render(w),
+					invalidate: () => container.invalidate(),
+					handleInput: (data) => {
+						if (stage === "select") selectList.handleInput(data);
+						else maskedInput.handleInput(data);
+						tui.requestRender();
+					},
+				};
+			},
+			{ overlay: true },
+		).then((result) => {
+			if (timer !== undefined) clearTimeout(timer);
+			resolve(result ?? { action: "timeout" });
+		});
+	});
+}