@adeildo/pi-harness 4.0.0

package/src/look/render/frame.ts

@@ -0,0 +1,118 @@
+// Borders with something written in them: `╭─ left ────── right ─╮`. The frame is the one place
+// that knows the box characters, so a new style is one entry here.
+import { visibleWidth } from "@earendil-works/pi-tui";
+
+import { type FitOptions, fitRegions, type Piece } from "./fit.ts";
+
+export type FrameStyle = "rounded" | "square" | "heavy" | "line";
+
+export interface BoxChars {
+	topLeft: string;
+	topRight: string;
+	bottomLeft: string;
+	bottomRight: string;
+	horizontal: string;
+	vertical: string;
+}
+
+export const BOXES: Record<FrameStyle, BoxChars> = {
+	rounded: {
+		topLeft: "╭",
+		topRight: "╮",
+		bottomLeft: "╰",
+		bottomRight: "╯",
+		horizontal: "─",
+		vertical: "│",
+	},
+	square: {
+		topLeft: "┌",
+		topRight: "┐",
+		bottomLeft: "└",
+		bottomRight: "┘",
+		horizontal: "─",
+		vertical: "│",
+	},
+	heavy: {
+		topLeft: "┏",
+		topRight: "┓",
+		bottomLeft: "┗",
+		bottomRight: "┛",
+		horizontal: "━",
+		vertical: "┃",
+	},
+	// Only the horizontal rules, the way pi draws its editor, with the data written into them.
+	line: {
+		topLeft: "─",
+		topRight: "─",
+		bottomLeft: "─",
+		bottomRight: "─",
+		horizontal: "─",
+		vertical: "",
+	},
+};
+
+export interface BorderOptions extends Pick<FitOptions, "separator" | "ellipsis"> {
+	box: BoxChars;
+	edge: "top" | "bottom";
+	/** Paints the rule and the corners. */
+	paint: (text: string) => string;
+	/**
+	 * Text that follows the left pieces and takes whatever room is left, like the working spinner.
+	 * It goes after them because it changes width all the time, and the pieces must not move.
+	 */
+	lead?: ((budget: number) => string | undefined) | undefined;
+	/** Room kept for the lead, so the pieces never squeeze it out. */
+	leadMin?: number;
+}
+
+/** Corners, one rule cell each side, and one rule cell between the two regions at least. */
+const FIXED = 5;
+/** A space on each side of a region's text. */
+const PADDING = 2;
+
+/** One border line of exactly `width` columns, with both regions fitted into it. */
+export function border(
+	width: number,
+	left: readonly Piece[],
+	right: readonly Piece[],
+	options: BorderOptions,
+): string {
+	const { box, paint } = options;
+	const [start, end] =
+		options.edge === "top" ? [box.topLeft, box.topRight] : [box.bottomLeft, box.bottomRight];
+	if (width < FIXED) return paint(box.horizontal.repeat(Math.max(0, width)));
+
+	const separatorWidth = visibleWidth(options.separator);
+	const reserve =
+		options.lead === undefined ? 0 : (options.leadMin ?? 1) + separatorWidth + PADDING;
+	const budget = width - FIXED - reserve;
+
+	const [fittedLeft = "", fittedRight = ""] =
+		budget > 0
+			? fitRegions([left, right], budget, {
+					separator: options.separator,
+					regionOverhead: PADDING,
+					ellipsis: options.ellipsis,
+				})
+			: ["", ""];
+
+	const rightCell = fittedRight === "" ? "" : ` ${fittedRight} `;
+	let leftText = fittedLeft;
+	if (options.lead !== undefined) {
+		const used =
+			visibleWidth(rightCell) + (fittedLeft === "" ? 0 : visibleWidth(fittedLeft) + separatorWidth);
+		const lead = options.lead(Math.max(1, width - FIXED - PADDING - used));
+		if (lead !== undefined && lead !== "")
+			leftText = fittedLeft === "" ? lead : `${fittedLeft}${options.separator}${lead}`;
+	}
+	const leftCell = leftText === "" ? "" : ` ${leftText} `;
+	const fill = Math.max(1, width - 4 - visibleWidth(leftCell) - visibleWidth(rightCell));
+
+	return (
+		paint(`${start}${box.horizontal}`) +
+		leftCell +
+		paint(box.horizontal.repeat(fill)) +
+		rightCell +
+		paint(`${box.horizontal}${end}`)
+	);
+}

package/src/look/render/glyphs.ts

@@ -0,0 +1,155 @@
+// One glyph per kind of data, in three sets. Nerd Font glyphs live in the private use area, so they
+// are written as escapes: a font without them shows a box, and a reviewer sees which code point it is.
+export type IconMode = "auto" | "nerd" | "unicode" | "ascii";
+export type IconSet = Exclude<IconMode, "auto">;
+
+export interface Glyphs {
+	set: IconSet;
+	folder: string;
+	branch: string;
+	host: string;
+	session: string;
+	version: string;
+	model: string;
+	effort: string;
+	context: string;
+	speed: string;
+	wait: string;
+	running: string;
+	done: string;
+	sent: string;
+	received: string;
+	cacheRead: string;
+	cacheWrite: string;
+	cost: string;
+	clock: string;
+	plug: string;
+	ahead: string;
+	behind: string;
+	staged: string;
+	modified: string;
+	untracked: string;
+	conflicted: string;
+	stashed: string;
+	/** Full and empty cells of a gauge. Blocks, so the gauge never reads as part of a border rule. */
+	fill: string;
+	empty: string;
+	/** Six rising bars, one per effort level from minimal to max. */
+	levels: readonly string[];
+	ellipsis: string;
+}
+
+const COMMON = {
+	ahead: "↑",
+	behind: "↓",
+	staged: "+",
+	modified: "~",
+	untracked: "?",
+	conflicted: "!",
+	sent: "↑",
+	received: "↓",
+};
+
+export const NERD: Glyphs = {
+	...COMMON,
+	set: "nerd",
+	folder: "\u{f07c}", // nf-fa-folder_open
+	branch: "\u{e0a0}", // nf-pl-branch
+	host: "\u{f108}", // nf-fa-desktop
+	session: "\u{f02b}", // nf-fa-tag
+	version: "π",
+	model: "\u{f06a9}", // nf-md-robot
+	effort: "\u{f09d1}", // nf-md-brain
+	context: "\u{f035b}", // nf-md-memory
+	speed: "\u{f04c5}", // nf-md-speedometer
+	wait: "\u{f252}", // nf-fa-hourglass_half
+	running: "\u{f017}", // nf-fa-clock_o
+	done: "\u{f00c}", // nf-fa-check
+	cacheRead: "\u{f1c0}", // nf-fa-database
+	cacheWrite: "\u{f0c7}", // nf-fa-floppy_o
+	cost: "$",
+	clock: "\u{f017}", // nf-fa-clock_o
+	plug: "\u{f1e6}", // nf-fa-plug
+	stashed: "\u{f01c}", // nf-fa-inbox
+	fill: "█",
+	empty: "░",
+	levels: ["▂", "▃", "▄", "▅", "▆", "▇"],
+	ellipsis: "…",
+};
+
+/** Symbols every monospace font with decent Unicode coverage has, all one column wide. */
+export const UNICODE: Glyphs = {
+	...COMMON,
+	set: "unicode",
+	folder: "▸",
+	branch: "⎇",
+	host: "⌂",
+	session: "#",
+	version: "π",
+	model: "◆",
+	effort: "✦",
+	context: "◔",
+	speed: "»",
+	wait: "⧗",
+	running: "◷",
+	done: "✓",
+	cacheRead: "≋",
+	cacheWrite: "≈",
+	cost: "$",
+	clock: "◷",
+	plug: "≫",
+	stashed: "≡",
+	fill: "█",
+	empty: "░",
+	levels: ["▂", "▃", "▄", "▅", "▆", "▇"],
+	ellipsis: "…",
+};
+
+export const ASCII: Glyphs = {
+	set: "ascii",
+	folder: "",
+	branch: "",
+	host: "@",
+	session: "#",
+	version: "v",
+	model: "",
+	effort: "",
+	context: "ctx",
+	speed: "",
+	wait: "ttft",
+	running: "",
+	done: "",
+	sent: "^",
+	received: "v",
+	cacheRead: "R",
+	cacheWrite: "W",
+	cost: "$",
+	clock: "",
+	plug: ">>",
+	ahead: "^",
+	behind: "v",
+	staged: "+",
+	modified: "~",
+	untracked: "?",
+	conflicted: "!",
+	stashed: "s",
+	fill: "#",
+	empty: "-",
+	levels: ["|", "|", "|", "|", "|", "|"],
+	ellipsis: "...",
+};
+
+const SETS: Record<IconSet, Glyphs> = { nerd: NERD, unicode: UNICODE, ascii: ASCII };
+
+/**
+ * Auto trusts a local UTF-8 terminal to have a Nerd Font. Over SSH the font lives on the other
+ * machine, so it drops to plain Unicode, and a terminal that does not speak UTF-8 gets ASCII.
+ */
+export function resolveIcons(mode: IconMode, env: NodeJS.ProcessEnv = process.env): Glyphs {
+	if (mode !== "auto") return SETS[mode];
+	if (env.TERM === "dumb") return ASCII;
+	const locale = env.LC_ALL ?? env.LC_CTYPE ?? env.LANG;
+	if (locale !== undefined && locale !== "" && !/utf-?8/i.test(locale)) return ASCII;
+	if (env.SSH_TTY !== undefined || env.SSH_CONNECTION !== undefined) return UNICODE;
+	return NERD;
+}

package/src/look/render/paint.ts

@@ -0,0 +1,137 @@
+// Colour, without a single colour value. Every role names a token of the active pi theme, so the look
+// follows whatever theme is on: the built-in ones, a custom JSON, or the desktop palette this package
+// writes from matugen. Change the theme and every piece moves with it.
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+
+/** What a piece of text is. The table below says which theme token paints it. */
+export type Role =
+	| "path"
+	| "branch"
+	| "ahead"
+	| "behind"
+	| "staged"
+	| "modified"
+	| "untracked"
+	| "conflicted"
+	| "host"
+	| "session"
+	| "version"
+	| "provider"
+	| "model"
+	| "sent"
+	| "received"
+	| "cache"
+	| "speed"
+	| "wait"
+	| "running"
+	| "done"
+	| "cost"
+	| "clock"
+	| "brand";
+
+/**
+ * The palette, as theme tokens. Syntax tokens are borrowed on purpose: a theme spends its hues there,
+ * so they give the line variety that stays in the theme's family.
+ */
+export const ROLE_TOKENS: Record<Role, ThemeColor> = {
+	path: "accent",
+	branch: "syntaxFunction",
+	ahead: "success",
+	behind: "warning",
+	staged: "success",
+	modified: "warning",
+	untracked: "muted",
+	conflicted: "error",
+	host: "syntaxType",
+	session: "mdHeading",
+	version: "muted",
+	provider: "syntaxKeyword",
+	model: "text",
+	sent: "mdLink",
+	received: "success",
+	cache: "syntaxType",
+	speed: "success",
+	wait: "syntaxNumber",
+	running: "accent",
+	done: "success",
+	cost: "syntaxNumber",
+	clock: "muted",
+	brand: "accent",
+};
+
+/** Pi gives every effort level its own token, which a theme draws as a ramp from cool to hot. */
+const EFFORT_TOKENS: Record<string, ThemeColor> = {
+	off: "thinkingOff",
+	minimal: "thinkingMinimal",
+	low: "thinkingLow",
+	medium: "thinkingMedium",
+	high: "thinkingHigh",
+	xhigh: "thinkingXhigh",
+	max: "thinkingMax",
+};
+
+export const EFFORT_LEVELS = ["minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
+export interface Paint {
+	/** Separators, units and labels sit back, so the data reads first. */
+	dim(text: string): string;
+	/** Quieter data. */
+	muted(text: string): string;
+	text(text: string): string;
+	bold(text: string): string;
+	italic(text: string): string;
+	role(role: Role, text: string): string;
+	/** The colour of one effort level. */
+	effort(level: string, text: string): string;
+	/** Calm under half, warm past 70%, alarming past 90%. */
+	stress(percent: number, text: string): string;
+	/** Money reads calm until it adds up. */
+	money(amount: number, text: string): string;
+	/** The editor frame, which pi recolours with the effort level and for bash mode. */
+	frame(text: string): string;
+}
+
+export function themePaint(theme: Theme, frame?: (text: string) => string): Paint {
+	return {
+		dim: (text) => theme.fg("dim", text),
+		muted: (text) => theme.fg("muted", text),
+		text: (text) => theme.fg("text", text),
+		bold: (text) => theme.bold(text),
+		italic: (text) => theme.italic(text),
+		role: (role, text) => theme.fg(ROLE_TOKENS[role], text),
+		effort: (level, text) => theme.fg(EFFORT_TOKENS[level] ?? "thinkingOff", text),
+		stress: (percent, text) => theme.fg(stressToken(percent), text),
+		money: (amount, text) => theme.fg(moneyToken(amount), text),
+		frame: frame ?? ((text) => theme.fg("border", text)),
+	};
+}
+
+export function stressToken(percent: number): ThemeColor {
+	if (percent >= 90) return "error";
+	if (percent >= 70) return "warning";
+	return "success";
+}
+
+function moneyToken(amount: number): ThemeColor {
+	if (amount >= 10) return "error";
+	if (amount >= 1) return "warning";
+	return ROLE_TOKENS.cost;
+}
+
+/** Used by tests and by anything drawing without a theme. */
+export const PLAIN: Paint = {
+	dim: identity,
+	muted: identity,
+	text: identity,
+	bold: identity,
+	italic: identity,
+	role: (_role, text) => text,
+	effort: (_level, text) => text,
+	stress: (_percent, text) => text,
+	money: (_amount, text) => text,
+	frame: identity,
+};
+
+function identity(text: string): string {
+	return text;
+}