@nredd/pi-session-kit 0.0.0-stage → 0.4.0

package/src/diff/git.ts

@@ -0,0 +1,289 @@
+/**
+ * Read-only git access for `/diff`. Every call is an argv spawn (no shell) with `--no-pager
+ * --literal-pathspecs`, `GIT_OPTIONAL_LOCKS=0` so a diff never takes the index lock another pi
+ * session may be holding, a hard output cap and a timeout.
+ */
+
+import { spawn } from "node:child_process";
+import { lstat, open, readlink } from "node:fs/promises";
+import { join } from "node:path";
+import { type DiffFile, PER_FILE_BYTES, parseUnifiedDiff } from "./parse.ts";
+
+export const TOTAL_BYTES = 2 * 1024 * 1024;
+export const MAX_UNTRACKED_FILES = 500;
+const GIT_TIMEOUT_MS = 30_000;
+const KILL_GRACE_MS = 2_000;
+/** After SIGKILL, how long to wait for `close` before resolving with what we have. */
+const CLOSE_GRACE_MS = 1_000;
+const SNIFF_BYTES = 8000;
+
+export interface GitOutput {
+	stdout: Buffer;
+	stderr: string;
+	code: number | null;
+	/** Output hit `maxBytes`; git was stopped. */
+	truncated: boolean;
+	spawnError?: string;
+}
+
+/** Signal only the detached group; a reaped leader's bare pid may already have been reused. */
+function killTree(pid: number, sig: NodeJS.Signals): void {
+	try {
+		process.kill(-pid, sig);
+	} catch {
+		// already gone
+	}
+}
+
+/**
+ * Run git in its own process group so a timeout or the output cap stops the whole tree (hooks,
+ * filter drivers, ssh). SIGTERM first, SIGKILL after `KILL_GRACE_MS`, then a hard resolve
+ * `CLOSE_GRACE_MS` later so a grandchild holding the pipes cannot hang the caller.
+ */
+export function runGit(
+	args: readonly string[],
+	opts: { cwd: string; maxBytes?: number; timeoutMs?: number; cmd?: string },
+): Promise<GitOutput> {
+	const maxBytes = opts.maxBytes ?? TOTAL_BYTES;
+	return new Promise((resolve) => {
+		const child = spawn(
+			opts.cmd ?? "git",
+			["--no-pager", "--literal-pathspecs", "-c", "core.quotepath=false", "-c", "color.ui=false", ...args],
+			{
+				cwd: opts.cwd,
+				stdio: ["ignore", "pipe", "pipe"],
+				detached: true,
+				env: { ...process.env, GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0", LC_ALL: "C" },
+			},
+		);
+		const chunks: Buffer[] = [];
+		let size = 0;
+		let truncated = false;
+		let stderr = "";
+		let done = false;
+		let stopping = false;
+		let escalated = false;
+		let closed = false;
+		const timers: NodeJS.Timeout[] = [];
+		const finish = (code: number | null, spawnError?: string) => {
+			if (done || (stopping && !escalated)) return;
+			done = true;
+			for (const t of timers) clearTimeout(t);
+			child.stdout.destroy();
+			child.stderr.destroy();
+			resolve({ stdout: Buffer.concat(chunks), stderr, code, truncated, spawnError });
+		};
+		const stop = () => {
+			if (stopping || done || child.pid === undefined) return;
+			stopping = true;
+			const pid = child.pid;
+			killTree(pid, "SIGTERM");
+			timers.push(
+				setTimeout(() => {
+					if (done) return;
+					killTree(pid, "SIGKILL");
+					escalated = true;
+					if (closed) finish(child.exitCode);
+					else timers.push(setTimeout(() => finish(child.exitCode), CLOSE_GRACE_MS));
+				}, KILL_GRACE_MS),
+			);
+		};
+		timers.push(setTimeout(stop, opts.timeoutMs ?? GIT_TIMEOUT_MS));
+		child.stdout.on("data", (chunk: Buffer) => {
+			if (truncated) return;
+			const room = maxBytes - size;
+			if (chunk.length > room) {
+				chunks.push(chunk.subarray(0, room));
+				size = maxBytes;
+				truncated = true;
+				stop();
+			} else {
+				chunks.push(chunk);
+				size += chunk.length;
+			}
+		});
+		child.stderr.on("data", (chunk: Buffer) => {
+			if (stderr.length < 4096) stderr += chunk.toString("utf8");
+		});
+		child.once("error", (e) => finish(null, e.message));
+		child.once("close", (code) => {
+			closed = true;
+			// Closed pipes do not prove the process group is gone. Await escalation when stopping.
+			finish(code);
+		});
+	});
+}
+
+export type LoadResult =
+	| { ok: true; files: DiffFile[]; label: string; notices: string[]; root: string }
+	| { ok: false; error: string };
+
+const BAD_REF = /^(-|$)|[\s\0]/;
+
+function firstLine(text: string): string {
+	return text.trim().split("\n")[0] ?? "";
+}
+
+/** Resolve the repo root, or explain why this is not a usable work tree. */
+export async function repoRoot(cwd: string): Promise<{ root: string } | { error: string }> {
+	const r = await runGit(["rev-parse", "--show-toplevel"], { cwd, maxBytes: 4096 });
+	if (r.spawnError) return { error: `cannot run git: ${r.spawnError}` };
+	if (r.code !== 0) return { error: "not a git repository (or no work tree here)" };
+	return { root: r.stdout.toString("utf8").trim() };
+}
+
+/** The ref to diff the work tree against: `ref`, else HEAD, else the empty tree in a repo with no commits. */
+async function resolveBase(
+	root: string,
+	ref: string | undefined,
+): Promise<{ base: string; label: string } | { error: string }> {
+	if (ref !== undefined) {
+		if (BAD_REF.test(ref)) return { error: `invalid ref ${JSON.stringify(ref)}` };
+		return { base: ref, label: ref };
+	}
+	const head = await runGit(["rev-parse", "--verify", "--quiet", "HEAD^{commit}"], { cwd: root, maxBytes: 4096 });
+	if (head.code === 0) return { base: "HEAD", label: "HEAD" };
+	const empty = await runGit(["hash-object", "-t", "tree", "/dev/null"], { cwd: root, maxBytes: 4096 });
+	const hash = empty.stdout.toString("utf8").trim();
+	if (empty.code !== 0 || !hash) return { error: "cannot resolve HEAD or the empty tree" };
+	return { base: hash, label: "empty tree (no commits yet)" };
+}
+
+/** Tracked changes (work tree + index vs base) and untracked files, parsed and capped. */
+export async function loadDiff(cwd: string, ref?: string): Promise<LoadResult> {
+	const repo = await repoRoot(cwd);
+	if ("error" in repo) return { ok: false, error: repo.error };
+	const root = repo.root;
+	const resolved = await resolveBase(root, ref);
+	if ("error" in resolved) return { ok: false, error: resolved.error };
+
+	const diff = await runGit(
+		["diff", "--no-color", "--no-ext-diff", "--no-textconv", "--src-prefix=a/", "--dst-prefix=b/", resolved.base, "--"],
+		{ cwd: root },
+	);
+	if (diff.spawnError) return { ok: false, error: `cannot run git: ${diff.spawnError}` };
+	if (diff.code !== 0 && !diff.truncated) {
+		const why = firstLine(diff.stderr) || `git diff exited with ${diff.code}`;
+		return { ok: false, error: ref ? `bad ref ${JSON.stringify(ref)}: ${why}` : why };
+	}
+	const notices: string[] = [];
+	const files = parseUnifiedDiff(diff.stdout.toString("utf8"));
+	if (diff.truncated) {
+		notices.push(`diff output cut at ${TOTAL_BYTES / 1024 / 1024}MB; later files are missing`);
+		const last = files.at(-1);
+		if (last && !last.notice) last.notice = "patch cut by the total output cap";
+	}
+
+	// Untracked files only make sense against the work tree, not for a `a..b` commit range.
+	if (ref === undefined || !ref.includes("..")) {
+		const budget = Math.max(0, TOTAL_BYTES - diff.stdout.length);
+		files.push(...(await untrackedFiles(root, budget, notices)));
+	}
+	return { ok: true, files, label: resolved.label, notices, root };
+}
+
+async function untrackedFiles(root: string, budget: number, notices: string[]): Promise<DiffFile[]> {
+	const ls = await runGit(["ls-files", "--others", "--exclude-standard", "-z"], { cwd: root });
+	if (ls.code !== 0) {
+		notices.push(`could not list untracked files: ${firstLine(ls.stderr)}`);
+		return [];
+	}
+	const paths = ls.stdout.toString("utf8").split("\0").filter(Boolean).sort();
+	const out: DiffFile[] = [];
+	let remaining = budget;
+	for (const path of paths.slice(0, MAX_UNTRACKED_FILES)) {
+		const file = await untrackedPatch(root, path, Math.min(PER_FILE_BYTES, remaining));
+		remaining -= file.lines.reduce((n, l) => n + l.length + 1, 0);
+		out.push(file);
+	}
+	if (paths.length > MAX_UNTRACKED_FILES) {
+		notices.push(`${paths.length - MAX_UNTRACKED_FILES} more untracked files not listed`);
+	}
+	return out;
+}
+
+/** A synthetic "new file" patch for an untracked path, size-capped, binary and symlink aware. */
+export async function untrackedPatch(root: string, path: string, capBytes: number): Promise<DiffFile> {
+	const header = [`diff --git a/${path} b/${path}`, "new file (untracked)", "--- /dev/null", `+++ b/${path}`];
+	const base = { path, status: "untracked" as const, hunkStart: header.length, additions: 0, deletions: 0 };
+	const note = (lines: string[], notice?: string): DiffFile => ({ ...base, lines: [...header, ...lines], notice });
+	const full = join(root, path);
+	try {
+		const st = await lstat(full);
+		if (st.isSymbolicLink()) {
+			const target = await readlink(full);
+			return { ...base, lines: [...header, "@@ -0,0 +1 @@", `+-> ${target}`], additions: 1 };
+		}
+		if (!st.isFile())
+			return { ...base, status: "untracked", hunkStart: header.length, lines: [...header, "\\ not a regular file"] };
+		if (capBytes <= 0) return note(["\\ content omitted: output budget exhausted"]);
+		const handle = await open(full, "r");
+		let buf: Buffer;
+		try {
+			buf = Buffer.alloc(Math.min(st.size, capBytes + 1));
+			const { bytesRead } = await handle.read(buf, 0, buf.length, 0);
+			buf = buf.subarray(0, bytesRead);
+		} finally {
+			await handle.close();
+		}
+		if (buf.subarray(0, SNIFF_BYTES).includes(0)) {
+			return { ...base, status: "untracked", lines: [...header, `\\ binary file (${st.size} bytes)`] };
+		}
+		if (st.size === 0) return note(["\\ empty file"]);
+		let cut = buf.length > capBytes;
+		const text = buf.subarray(0, Math.min(buf.length, capBytes)).toString("utf8");
+		const lines = text.split("\n");
+		if (lines.at(-1) === "") lines.pop();
+		// The `+` prefix and newline add bytes, so the cap is applied to the patch lines themselves.
+		const body: string[] = [];
+		let bytes = 0;
+		for (const l of lines) {
+			bytes += l.length + 2;
+			if (bytes > capBytes) {
+				cut = true;
+				break;
+			}
+			body.push(`+${l}`);
+		}
+		const shown = body.length;
+		const missingNewline = !cut && !text.endsWith("\n");
+		const hunk = `@@ -0,0 +1,${shown} @@`;
+		return {
+			...base,
+			lines: [...header, hunk, ...body, ...(missingNewline ? ["\"] : [])],
+			additions: shown,
+			notice: cut ? `file truncated at ${Math.round(capBytes / 1024)}KB (${st.size} bytes total)` : undefined,
+		};
+	} catch (error) {
+		return note([`\\ unreadable: ${(error as Error).message}`]);
+	}
+}
+
+/** `git diff --stat` for the tracked changes plus `?? path` lines, for non-TUI output. */
+export async function loadStat(
+	cwd: string,
+	ref?: string,
+): Promise<{ ok: true; text: string } | { ok: false; error: string }> {
+	const repo = await repoRoot(cwd);
+	if ("error" in repo) return { ok: false, error: repo.error };
+	const resolved = await resolveBase(repo.root, ref);
+	if ("error" in resolved) return { ok: false, error: resolved.error };
+	const stat = await runGit(["diff", "--no-color", "--no-ext-diff", "--stat", resolved.base, "--"], {
+		cwd: repo.root,
+		maxBytes: 256 * 1024,
+	});
+	if (stat.code !== 0 && !stat.truncated) {
+		const why = firstLine(stat.stderr) || `git diff exited with ${stat.code}`;
+		return { ok: false, error: ref ? `bad ref ${JSON.stringify(ref)}: ${why}` : why };
+	}
+	let text = stat.stdout.toString("utf8").trimEnd();
+	if (ref === undefined || !ref.includes("..")) {
+		const ls = await runGit(["ls-files", "--others", "--exclude-standard", "-z"], {
+			cwd: repo.root,
+			maxBytes: 256 * 1024,
+		});
+		const untracked = ls.stdout.toString("utf8").split("\0").filter(Boolean).sort();
+		if (untracked.length > 0) text += `${text ? "\n" : ""}${untracked.map((p) => `?? ${p}`).join("\n")}`;
+	}
+	return { ok: true, text };
+}

package/src/diff/index.ts

@@ -0,0 +1,65 @@
+/**
+ * `/diff [ref]`: read-only overlay over `git diff` (work tree + index vs HEAD, or vs `ref`) plus
+ * untracked files. A command, not a tool, so Plan mode allows it. Outside the TUI it prints the
+ * `--stat` instead.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { KitConfig } from "../config.ts";
+import { say } from "../output.ts";
+import { DiffView } from "./component.ts";
+import { loadDiff, loadStat } from "./git.ts";
+
+const STATUS_KEY = "session-kit:diff";
+export const MESSAGE_TYPE = "session-kit:diff";
+
+export function register(pi: ExtensionAPI, _config: KitConfig): void {
+	pi.registerCommand("diff", {
+		description: "Browse the git diff (work tree + staged vs HEAD, or vs <ref>) and untracked files",
+		async handler(args: string, ctx: ExtensionCommandContext) {
+			const words = args.trim().split(/\s+/).filter(Boolean);
+			if (words.length > 1) {
+				ctx.ui.notify("usage: /diff [ref]", "warning");
+				return;
+			}
+			const ref = words[0];
+
+			if (ctx.mode !== "tui") {
+				const stat = await loadStat(ctx.cwd, ref);
+				if (!stat.ok) say(pi, ctx, MESSAGE_TYPE, `/diff: ${stat.error}`, "error");
+				else say(pi, ctx, MESSAGE_TYPE, stat.text || "/diff: no changes", "info");
+				return;
+			}
+
+			ctx.ui.setStatus(STATUS_KEY, "diff: loading...");
+			let loaded: Awaited<ReturnType<typeof loadDiff>>;
+			try {
+				loaded = await loadDiff(ctx.cwd, ref);
+			} finally {
+				ctx.ui.setStatus(STATUS_KEY, undefined);
+			}
+			if (!loaded.ok) {
+				ctx.ui.notify(`/diff: ${loaded.error}`, "error");
+				return;
+			}
+			if (loaded.files.length === 0) {
+				ctx.ui.notify(`/diff: no changes vs ${loaded.label}`, "info");
+				return;
+			}
+			const { files, label, notices } = loaded;
+			await ctx.ui.custom<void>(
+				(tui, theme, _kb, done) =>
+					new DiffView({
+						files,
+						label,
+						notices,
+						theme,
+						rows: () => tui.terminal.rows,
+						requestRender: () => tui.requestRender(),
+						onClose: () => done(),
+					}),
+				{ overlay: true, overlayOptions: { anchor: "top-left", width: "100%", maxHeight: "100%", margin: 0 } },
+			);
+		},
+	});
+}

package/src/diff/parse.ts

@@ -0,0 +1,180 @@
+/** Unified diff text -> per-file sections with status, counts and per-line kinds. */
+
+export type FileStatus = "modified" | "added" | "deleted" | "renamed" | "copied" | "binary" | "mode" | "untracked";
+export type LineKind = "meta" | "hunk" | "added" | "removed" | "context";
+
+export interface DiffFile {
+	/** Path to show (the new path for renames). */
+	path: string;
+	oldPath?: string;
+	status: FileStatus;
+	/** Raw patch lines, header first, without line terminators. */
+	lines: string[];
+	/** Index into `lines` of the first hunk header, or `lines.length` when there is none. */
+	hunkStart: number;
+	additions: number;
+	deletions: number;
+	/** Set when `lines` was cut at the per-file cap; additions/deletions still count everything. */
+	notice?: string;
+}
+
+export const PER_FILE_BYTES = 200 * 1024;
+
+/** Decode a git C-style quoted path (`"a\tb"`, octal escapes are UTF-8 bytes). */
+export function unquoteC(s: string): string {
+	if (!(s.length >= 2 && s.startsWith('"') && s.endsWith('"'))) return s;
+	const bytes: number[] = [];
+	const body = s.slice(1, -1);
+	const simple: Record<string, number> = { n: 10, t: 9, r: 13, a: 7, b: 8, f: 12, v: 11, '"': 34, "\\": 92 };
+	for (let i = 0; i < body.length; i++) {
+		const ch = body[i] as string;
+		if (ch !== "\\") {
+			bytes.push(...Buffer.from(ch, "utf8"));
+			continue;
+		}
+		const next = body[i + 1] ?? "";
+		const octal = /^[0-7]{1,3}/.exec(body.slice(i + 1, i + 4));
+		if (octal) {
+			bytes.push(Number.parseInt(octal[0], 8));
+			i += octal[0].length;
+		} else if (next in simple) {
+			bytes.push(simple[next] as number);
+			i += 1;
+		} else {
+			bytes.push(92);
+		}
+	}
+	return Buffer.from(bytes).toString("utf8");
+}
+
+function stripPrefix(p: string): string {
+	const bare = unquoteC(p.replace(/\t.*$/, ""));
+	return bare.replace(/^[ab]\//, "");
+}
+
+/** Paths from the `diff --git a/x b/y` line alone (used when no ---/+++ lines exist). */
+function headerPaths(line: string): { oldPath: string; newPath: string } {
+	const rest = line.slice("diff --git ".length);
+	const quoted = /^("(?:[^"\\]|\\.)*") ("(?:[^"\\]|\\.)*")$/.exec(rest);
+	if (quoted) return { oldPath: stripPrefix(quoted[1] as string), newPath: stripPrefix(quoted[2] as string) };
+	const n = (rest.length - 5) / 2;
+	if (Number.isInteger(n) && n > 0 && rest.slice(2, 2 + n) === rest.slice(rest.length - n)) {
+		const p = rest.slice(rest.length - n);
+		return { oldPath: p, newPath: p };
+	}
+	const m = /^a\/(.*) b\/(.*)$/.exec(rest);
+	return m ? { oldPath: m[1] as string, newPath: m[2] as string } : { oldPath: rest, newPath: rest };
+}
+
+function finishFile(lines: string[], overflow: { lines: number } | undefined, capBytes: number): DiffFile {
+	const first = lines[0] ?? "";
+	const hdr = headerPaths(first);
+	let status: FileStatus = "modified";
+	let oldPath = hdr.oldPath;
+	let newPath = hdr.newPath;
+	let hunkStart = lines.length;
+	let additions = 0;
+	let deletions = 0;
+	let sawMode = false;
+	let sawContent = false;
+	for (let i = 1; i < lines.length; i++) {
+		const l = lines[i] as string;
+		if (hunkStart === lines.length) {
+			if (l.startsWith("@@")) {
+				hunkStart = i;
+				sawContent = true;
+				continue;
+			}
+			if (l.startsWith("new file mode")) status = "added";
+			else if (l.startsWith("deleted file mode")) status = "deleted";
+			else if (l.startsWith("rename from ")) {
+				status = "renamed";
+				oldPath = unquoteC(l.slice("rename from ".length));
+			} else if (l.startsWith("rename to ")) newPath = unquoteC(l.slice("rename to ".length));
+			else if (l.startsWith("copy from ")) {
+				status = "copied";
+				oldPath = unquoteC(l.slice("copy from ".length));
+			} else if (l.startsWith("copy to ")) newPath = unquoteC(l.slice("copy to ".length));
+			else if (l.startsWith("Binary files ") || l.startsWith("GIT binary patch")) {
+				status = "binary";
+				sawContent = true;
+			} else if (l.startsWith("old mode") || l.startsWith("new mode")) sawMode = true;
+			else if (l.startsWith("--- ") && l !== "--- /dev/null") oldPath = stripPrefix(l.slice(4));
+			else if (l.startsWith("+++ ") && l !== "+++ /dev/null") newPath = stripPrefix(l.slice(4));
+		} else if (l.startsWith("+")) additions++;
+		else if (l.startsWith("-")) deletions++;
+	}
+	if (status === "modified" && sawMode && !sawContent) status = "mode";
+	if (status === "deleted") newPath = oldPath;
+	const file: DiffFile = {
+		path: newPath,
+		status,
+		lines,
+		hunkStart,
+		additions,
+		deletions,
+	};
+	if (oldPath !== newPath) file.oldPath = oldPath;
+	if (overflow) {
+		file.notice = `patch truncated: ${overflow.lines} more lines not shown (${Math.round(capBytes / 1024)}KB per-file cap)`;
+		// Counts of the lines we dropped are unknown to the loop above; recount happens in parseUnifiedDiff.
+	}
+	return file;
+}
+
+/** Parse `git diff` output. `perFileBytes` bounds the lines kept per file; counts stay exact. */
+export function parseUnifiedDiff(text: string, perFileBytes = PER_FILE_BYTES): DiffFile[] {
+	const files: DiffFile[] = [];
+	if (!text) return files;
+	const all = text.split("\n");
+	if (all.at(-1) === "") all.pop();
+	let current: string[] | undefined;
+	let bytes = 0;
+	let dropped = 0;
+	let extra = { additions: 0, deletions: 0 };
+	let inHunk = false;
+
+	const flush = () => {
+		if (!current) return;
+		const file = finishFile(current, dropped > 0 ? { lines: dropped } : undefined, perFileBytes);
+		file.additions += extra.additions;
+		file.deletions += extra.deletions;
+		files.push(file);
+	};
+
+	for (const line of all) {
+		if (line.startsWith("diff --git ")) {
+			flush();
+			current = [line];
+			bytes = line.length + 1;
+			dropped = 0;
+			extra = { additions: 0, deletions: 0 };
+			inHunk = false;
+			continue;
+		}
+		if (!current) continue;
+		if (line.startsWith("@@")) inHunk = true;
+		if (bytes + line.length + 1 > perFileBytes) {
+			dropped++;
+			if (inHunk && line.startsWith("+")) extra.additions++;
+			else if (inHunk && line.startsWith("-")) extra.deletions++;
+			continue;
+		}
+		bytes += line.length + 1;
+		current.push(line);
+	}
+	flush();
+	return files;
+}
+
+/** Kind of every line of a file section, for colouring. */
+export function classifyLines(file: DiffFile): LineKind[] {
+	return file.lines.map((line, i) => {
+		if (i < file.hunkStart) return "meta";
+		if (line.startsWith("@@")) return "hunk";
+		if (line.startsWith("+")) return "added";
+		if (line.startsWith("-")) return "removed";
+		if (line.startsWith("\\")) return "meta";
+		return "context";
+	});
+}

package/src/diff/view.ts

@@ -0,0 +1,98 @@
+/** Pure helpers for the `/diff` overlay: sanitising, width fitting, scroll math, layout. */
+
+import { sliceByColumn, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+export const TAB_WIDTH = 4;
+export const ELLIPSIS = "…";
+
+/** Make arbitrary file text safe for a terminal: C0/C1 controls become `^X`, tabs expand. */
+export function sanitize(text: string, tabWidth = TAB_WIDTH): string {
+	let out = "";
+	let col = 0;
+	for (const ch of text) {
+		const code = ch.codePointAt(0) ?? 0;
+		if (ch === "\t") {
+			const pad = tabWidth - (col % tabWidth);
+			out += " ".repeat(pad);
+			col += pad;
+		} else if (code < 0x20) {
+			out += `^${String.fromCharCode(code + 64)}`;
+			col += 2;
+		} else if (code === 0x7f) {
+			out += "^?";
+			col += 2;
+		} else if (code >= 0x80 && code < 0xa0) {
+			out += "?";
+			col += 1;
+		} else if (code === 0x2028 || code === 0x2029) {
+			out += "?";
+			col += 1;
+		} else {
+			out += ch;
+			col += visibleWidth(ch);
+		}
+	}
+	return out;
+}
+
+/** Exactly `width` columns: truncated with an ellipsis when too long, space padded when short. */
+export function fitCols(text: string, width: number): string {
+	if (width <= 0) return "";
+	return truncateToWidth(text, width, ELLIPSIS, true);
+}
+
+/** Columns `[from, from + width)` of plain text, padded to `width`. Never splits a wide char. */
+export function window(text: string, from: number, width: number): string {
+	if (width <= 0) return "";
+	const slice = from > 0 ? sliceByColumn(text, from, width, true) : text;
+	return fitCols(slice, width);
+}
+
+/** Shorten a path from the left so the file name stays visible: `…/dir/file.ts`. */
+export function fitPathLeft(path: string, width: number): string {
+	if (width <= 0) return "";
+	const w = visibleWidth(path);
+	if (w <= width) return fitCols(path, width);
+	if (width === 1) return ELLIPSIS;
+	return fitCols(`${ELLIPSIS}${sliceByColumn(path, w - (width - 1), width - 1, true)}`, width);
+}
+
+export function clamp(n: number, lo: number, hi: number): number {
+	return Math.max(lo, Math.min(hi, n));
+}
+
+/** Largest valid scroll offset for `total` lines in a `viewport`-line window. */
+export function maxScroll(total: number, viewport: number): number {
+	return Math.max(0, total - Math.max(1, viewport));
+}
+
+export function clampScroll(offset: number, total: number, viewport: number): number {
+	return clamp(offset, 0, maxScroll(total, viewport));
+}
+
+/** Lines moved by PgUp/PgDn: a window minus one line of overlap. */
+export function pageSize(viewport: number): number {
+	return Math.max(1, viewport - 1);
+}
+
+/** First visible list row so that `selected` is visible in `viewport` rows, keeping `top` when possible. */
+export function listTop(top: number, selected: number, total: number, viewport: number): number {
+	const h = Math.max(1, viewport);
+	let t = top;
+	if (selected < t) t = selected;
+	else if (selected >= t + h) t = selected - h + 1;
+	return clamp(t, 0, Math.max(0, total - h));
+}
+
+export interface Layout {
+	left: number;
+	sep: number;
+	right: number;
+}
+
+/** Split the width between file list, separator and patch. Always sums to `width`. */
+export function layout(width: number): Layout {
+	if (width < 24) return { left: 0, sep: 0, right: Math.max(0, width) };
+	const left = clamp(Math.floor(width * 0.28), 14, 44);
+	return { left, sep: 1, right: width - left - 1 };
+}