pi-squire 0.11.0 → 0.13.0

package/src/tmux.ts

@@ -1,6 +1,8 @@
 // The tmux operations `delegate` needs, behind an interface so tests can use a
 // fake. This client talks to tmux with `execFile` and no shell.
-import { execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
+
+import type { WindowPlacement } from "./window-placement.ts";
 
 /** One window to open: its name, working directory, command and environment. */
 export type WindowSpec = {
@@ -10,8 +12,41 @@ export type WindowSpec = {
 	env: Readonly<Record<string, string>>;
 };
 
-/** One window as tmux lists it: its id, its name, and whether the program in its pane has exited. */
-export type TmuxWindow = { id: string; name: string; exited: boolean };
+/** One window as tmux lists it: its id, its session's name, its name, and whether the program in its pane has exited. */
+export type TmuxWindow = { id: string; session: string; name: string; exited: boolean };
+
+/** A window just opened: its id and the name of the session it is in, when known. */
+export type OpenedWindow = { id: string; session: string | undefined };
+
+/** The oldest tmux delegate windows need: `new-session -e` and `display-popup` arrived in 3.2. */
+export const MIN_TMUX = { major: 3, minor: 2 } as const;
+
+export type TmuxVersion = { text: string; major: number; minor: number };
+
+/** Parse `tmux -V` output such as `tmux 3.7b` or `tmux next-3.4`; a build with no number (`tmux master`) counts as current. */
+export function parseTmuxVersion(output: string): TmuxVersion {
+	const text = output.trim();
+	const match = /(\d+)\.(\d+)/.exec(text);
+	if (match === null) return { text, major: Number.POSITIVE_INFINITY, minor: 0 };
+	return { text, major: Number(match[1]), minor: Number(match[2]) };
+}
+
+/** Refuse a tmux older than `MIN_TMUX`, naming the version found. */
+export async function requireTmuxVersion(tmux: { version(): Promise<TmuxVersion> }): Promise<void> {
+	const found = await tmux.version();
+	if (found.major < MIN_TMUX.major || (found.major === MIN_TMUX.major && found.minor < MIN_TMUX.minor)) {
+		throw new Error(`delegate windows need tmux ${MIN_TMUX.major}.${MIN_TMUX.minor} or later; this is ${found.text}`);
+	}
+}
+
+/**
+ * The companion session for a parent in `parentSession`: its own when that is
+ * a companion session (marked by pi-squire when it made it), else the name
+ * plus `-squire`. The name alone says nothing: a user's session may end in it.
+ */
+export function companionName(parentSession: string, isCompanion: boolean): string {
+	return isCompanion ? parentSession : `${parentSession}-squire`;
+}
 
 /**
  * Why a window could not be opened, and whether one may exist anyway:
@@ -19,7 +54,7 @@ export type TmuxWindow = { id: string; name: string; exited: boolean };
  * Anything else, a timeout or a malformed answer included, is `unknown`.
  */
 export class WindowOpenError extends Error {
-	readonly certainty: "not-opened" | "unknown";
+	certainty: "not-opened" | "unknown";
 	constructor(message: string, certainty: "not-opened" | "unknown") {
 		super(message);
 		this.name = "WindowOpenError";
@@ -27,15 +62,45 @@ export class WindowOpenError extends Error {
 	}
 }
 
+/** A window as the popup needs it: its id and its name, which titles the popup. */
+export type PopupWindow = { id: string; name: string };
+
+/** The session the parent's pane is in: its id (`$N`) and name. */
+export type OwnSession = { id: string; name: string };
+
 export interface TmuxClient {
 	/** Whether this process runs in a tmux pane. */
 	insideTmux(): boolean;
-	/** Open a detached window and return its id (for example `@3`). */
-	openWindow(spec: WindowSpec): Promise<string>;
+	/** The tmux version, asked once. */
+	version(): Promise<TmuxVersion>;
+	/**
+	 * Open a detached window and return its id (for example `@3`) and session.
+	 * `current` opens it in the parent's session; `companion` in
+	 * `<parent's session>-squire`, created when it does not exist.
+	 */
+	openWindow(spec: WindowSpec, placement: WindowPlacement): Promise<OpenedWindow>;
 	/** Every window on the server, in one tmux call. */
 	listWindows(): Promise<TmuxWindow[]>;
 	/** Kill a window. */
 	kill(windowId: string): Promise<void>;
+	/** The session the parent's pane is in; undefined when it cannot be told. */
+	ownSession(): Promise<OwnSession | undefined>;
+	/** The most recently active client attached to the session named `session`; undefined when none is. */
+	clientFor(session: string): Promise<string | undefined>;
+	/** Show the window to a client: `switch-client -c <client> -t @N`. */
+	switchTo(client: string, windowId: string): Promise<void>;
+	/**
+	 * Open a popup over a client that attaches to the window's session at the
+	 * window. `display-popup` returns only when the popup closes, so this
+	 * resolves once the popup was launched, not when it ends, and a launch that
+	 * fails at once rejects. `onExit` runs when the popup's process ends, however
+	 * the popup was closed, and not when the launch failed.
+	 */
+	popup(client: string, window: PopupWindow, onExit: () => void): Promise<void>;
+	/** Close the popup on a client (`display-popup -C`). */
+	closePopup(client: string): Promise<void>;
+	/** The window's visible pane as text (`capture-pane -p`). */
+	capture(windowId: string): Promise<string>;
 }
 
 /** Run one tmux command and return its stdout; never a shell. */
@@ -56,64 +121,239 @@ function runTmux(args: string[], timeout: number): Promise<string> {
 	});
 }
 
+type Run = (args: string[]) => Promise<string>;
+type Parent = { id: string; name: string; companion: boolean };
+
+/** The user option that marks a session pi-squire made for delegate windows. */
+const COMPANION_OPTION = "@squire-companion";
+
+/** The id, name and companion mark of the session the pane in `TMUX_PANE` belongs to, when known. */
+async function parentSession(run: Run): Promise<Parent | undefined> {
+	const pane = process.env.TMUX_PANE;
+	if (pane === undefined || pane === "") return undefined;
+	// Only the line's terminator goes: trailing spaces are legal in a session name.
+	const format = `#{session_id}\t#{${COMPANION_OPTION}}\t#{session_name}`;
+	const out = (await run(["display-message", "-p", "-t", pane, "-F", format])).replace(/\r?\n$/, "");
+	// The name comes last, so it is whatever follows the second tab.
+	const [id, marker, ...name] = out.split("\t");
+	return id.trim() === "" ? undefined : { id: id.trim(), name: name.join("\t"), companion: marker === "1" };
+}
+
+/** How long a launched popup may take to fail before it counts as shown. */
+const POPUP_SETTLE_MS = 300;
+
+/**
+ * Launch `display-popup`, which blocks until the popup closes, detached and
+ * outside `runTmux`'s timeout. Resolves once it is up; rejects on a spawn
+ * error or an exit within the settle time. Its stderr is read only until then
+ * and then released, so the open popup keeps nothing of this process alive;
+ * `onExit` runs when the popup's process ends, however it was closed.
+ */
+function launchPopup(args: string[], onExit: () => void): Promise<void> {
+	return new Promise((resolve, reject) => {
+		let settled = false;
+		let stderr = "";
+		const child = spawn("tmux", args, { detached: true, stdio: ["ignore", "ignore", "pipe"] });
+		const onData = (chunk: Buffer): void => {
+			if (stderr.length < 4096) stderr += chunk.toString();
+		};
+		child.stderr?.on("data", onData);
+		const settle = (error?: Error): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			child.stderr?.off("data", onData);
+			child.stderr?.destroy();
+			if (error === undefined) resolve();
+			else reject(error);
+		};
+		const timer = setTimeout(() => settle(), POPUP_SETTLE_MS);
+		child.on("error", (err) => settle(err));
+		child.on("close", (code) => {
+			if (!settled && code !== 0) {
+				settle(new Error(stderr.trim() !== "" ? stderr.trim() : `tmux display-popup exited with ${code}`));
+				return;
+			}
+			settle();
+			onExit();
+		});
+		child.unref();
+	});
+}
+
+const envArgs = (spec: WindowSpec): string[] =>
+	Object.entries(spec.env).flatMap(([key, value]) => ["-e", `${key}=${value}`]);
+
+/** Dispatch one create; after dispatch even an error or timeout may have left a window. */
+async function create(run: Run, args: string[]): Promise<string> {
+	let out: string;
+	try {
+		out = await run(args);
+	} catch (err) {
+		throw new WindowOpenError((err as Error).message, "unknown");
+	}
+	const windowId = out.trim();
+	if (!/^@[0-9]+$/.test(windowId)) throw new WindowOpenError("tmux reported an invalid window id", "unknown");
+	return windowId;
+}
+
+const failedWith = (err: unknown, text: string): boolean =>
+	err instanceof WindowOpenError && err.message.includes(text);
+
+/**
+ * Open a window in the companion session: `new-window`, then on a missing
+ * session one `new-session` that makes the delegate its first window and sets
+ * `detach-on-destroy off` and the companion mark on that session only, then `new-window` again when
+ * another launch created the session first.
+ */
+async function openCompanion(run: Run, spec: WindowSpec, session: string): Promise<string> {
+	const newWindow = [
+		"new-window",
+		"-d",
+		"-P",
+		"-F",
+		"#{window_id}",
+		"-n",
+		spec.name,
+		"-c",
+		spec.cwd,
+		...envArgs(spec),
+		"-t",
+		`=${session}:`,
+		"--",
+		...spec.argv,
+	];
+	try {
+		return await create(run, newWindow);
+	} catch (err) {
+		// tmux resolves the target before it creates anything, so nothing was dispatched that could create a window.
+		if (!failedWith(err, "can't find session")) throw err;
+		(err as WindowOpenError).certainty = "not-opened";
+	}
+	const newSession = ["new-session", "-d", "-s", session, "-n", spec.name, "-c", spec.cwd, ...envArgs(spec)];
+	newSession.push("-P", "-F", "#{window_id}", "--", ...spec.argv);
+	newSession.push(";", "set-option", "-t", `=${session}:`, "detach-on-destroy", "off");
+	newSession.push(";", "set-option", "-t", `=${session}:`, COMPANION_OPTION, "1");
+	try {
+		return await create(run, newSession);
+	} catch (err) {
+		if (!failedWith(err, "duplicate session")) throw err;
+	}
+	return create(run, newWindow);
+}
+
+/** Open a window in the parent's own session, as delegates always did. */
+function openCurrent(run: Run, spec: WindowSpec, parent: Parent | undefined): Promise<string> {
+	const args = ["new-window", "-d", "-P", "-F", "#{window_id}", "-n", spec.name, "-c", spec.cwd, ...envArgs(spec)];
+	if (parent !== undefined) args.push("-t", parent.id);
+	args.push("--", ...spec.argv);
+	return create(run, args);
+}
+
+/** The methods that reach a delegate's window from the user's terminal: clients, switch, popup, capture. */
+function navigation(
+	run: Run,
+): Pick<TmuxClient, "ownSession" | "clientFor" | "switchTo" | "popup" | "closePopup" | "capture"> {
+	return {
+		async ownSession() {
+			const parent = await parentSession(run);
+			return parent === undefined || parent.name === "" ? undefined : { id: parent.id, name: parent.name };
+		},
+
+		async clientFor(session) {
+			const out = await run(["list-clients", "-t", `=${session}:`, "-F", "#{client_activity}\t#{client_name}"]);
+			let best: { activity: number; name: string } | undefined;
+			for (const line of out.split("\n")) {
+				const [activity, ...name] = line.split("\t");
+				const at = Number(activity);
+				if (name.length === 0 || Number.isNaN(at)) continue;
+				if (best === undefined || at > best.activity) best = { activity: at, name: name.join("\t") };
+			}
+			return best?.name;
+		},
+
+		async switchTo(client, windowId) {
+			await run(["switch-client", "-c", client, "-t", windowId]);
+		},
+
+		async popup(client, window, onExit) {
+			if (!/^@[0-9]+$/.test(window.id)) throw new Error(`${window.id} is not a tmux window id`);
+			const sessionId = (await run(["display-message", "-p", "-t", window.id, "-F", "#{session_id}"])).trim();
+			if (!/^\$[0-9]+$/.test(sessionId)) throw new Error(`tmux reported an invalid session id for ${window.id}`);
+			// Ids are `@N` and `$N` only; quoted so the popup's shell does not expand `$N`.
+			const command = `tmux select-window -t '${window.id}' \\; attach-session -t '${sessionId}'`;
+			await launchPopup(
+				["display-popup", "-c", client, "-E", "-w", "90%", "-h", "90%", "-T", window.name, command],
+				onExit,
+			);
+		},
+
+		async closePopup(client) {
+			await run(["display-popup", "-C", "-c", client]);
+		},
+
+		async capture(windowId) {
+			return run(["capture-pane", "-p", "-t", windowId]);
+		},
+	};
+}
+
 /**
- * The real client. A window is opened in the session of the pane in
- * `TMUX_PANE`, not in whatever session a client happens to have attached, so
- * it works with several clients on one server.
+ * The real client. A window is opened relative to the session of the pane in
+ * `TMUX_PANE`, not whatever session a client happens to have attached, so it
+ * works with several clients on one server.
  */
 export function createTmuxClient(options: { timeoutMs?: number } = {}): TmuxClient {
 	const timeoutMs = options.timeoutMs ?? 10_000;
-	const run = (args: string[]) => runTmux(args, timeoutMs);
-
-	/** The id of the session this pane belongs to, when known. */
-	async function targetSession(): Promise<string | undefined> {
-		const pane = process.env.TMUX_PANE;
-		if (pane === undefined || pane === "") return undefined;
-		const sessionId = (await run(["display-message", "-p", "-t", pane, "-F", "#{session_id}"])).trim();
-		return sessionId === "" ? undefined : sessionId;
-	}
+	const run: Run = (args) => runTmux(args, timeoutMs);
+	let cachedVersion: Promise<TmuxVersion> | undefined;
 
 	return {
 		insideTmux: () => (process.env.TMUX ?? "") !== "",
 
-		async openWindow(spec) {
-			const args = ["new-window", "-d", "-P", "-F", "#{window_id}", "-n", spec.name, "-c", spec.cwd];
-			for (const [key, value] of Object.entries(spec.env)) args.push("-e", `${key}=${value}`);
-			let session: string | undefined;
+		version() {
+			// The in-flight ask is shared; a failed one is forgotten so the next call asks again.
+			cachedVersion ??= run(["-V"]).then(parseTmuxVersion, (err: unknown) => {
+				cachedVersion = undefined;
+				throw err;
+			});
+			return cachedVersion;
+		},
+
+		async openWindow(spec, placement) {
+			let parent: Parent | undefined;
 			try {
-				session = await targetSession();
+				parent = await parentSession(run);
 			} catch (err) {
 				// The lookup only reads; no window can exist yet.
 				throw new WindowOpenError((err as Error).message, "not-opened");
 			}
-			if (session !== undefined) args.push("-t", session);
-			args.push("--", ...spec.argv);
-			let out: string;
-			try {
-				out = await run(args);
-			} catch (err) {
-				// After dispatch even an error or timeout may have left a window.
-				throw new WindowOpenError((err as Error).message, "unknown");
+			const known = parent === undefined || parent.name === "" ? undefined : parent.name;
+			if (placement === "current") return { id: await openCurrent(run, spec, parent), session: known };
+			if (known === undefined) {
+				throw new WindowOpenError("could not tell which tmux session this pane is in (TMUX_PANE)", "not-opened");
 			}
-			const windowId = out.trim();
-			if (!/^@[0-9]+$/.test(windowId)) throw new WindowOpenError("tmux reported an invalid window id", "unknown");
-			return windowId;
+			const session = companionName(known, parent?.companion === true);
+			return { id: await openCompanion(run, spec, session), session };
 		},
 
 		async listWindows() {
-			// The name goes last: it is the one field that could hold a tab.
-			const out = await run(["list-windows", "-a", "-F", "#{window_id}\t#{pane_dead}\t#{window_name}"]);
+			// The window name goes last: it is the one field that could hold a tab.
+			const format = "#{window_id}\t#{pane_dead}\t#{session_name}\t#{window_name}";
+			const out = await run(["list-windows", "-a", "-F", format]);
 			return out
 				.split("\n")
 				.filter((line) => line.trim() !== "")
 				.map((line) => {
-					const [id, dead, ...name] = line.split("\t");
-					return { id, name: name.join("\t"), exited: dead === "1" };
+					const [id, dead, session, ...name] = line.split("\t");
+					return { id, session, name: name.join("\t"), exited: dead === "1" };
 				});
 		},
 
 		async kill(windowId) {
 			await run(["kill-window", "-t", windowId]);
 		},
+
+		...navigation(run),
 	};
 }