@xynogen/pix-runtime 0.10.2 → 0.12.2

package/src/paths.ts

@@ -0,0 +1,87 @@
+/**
+ * paths.ts — canonical Pi/pix directories, pure and env-injectable.
+ *
+ * `agentDir()` mirrors Pi's `getAgentDir()` (PI_CODING_AGENT_DIR, `~`-expanded,
+ * else `~/.pi/agent`) so code that runs outside a Pi process (CLIs, tests) and
+ * code inside it agree. `binDir()` is the same folder Pi downloads fd/rg into.
+ *
+ * Home resolution never trusts `HOME` alone: it is unset in a Windows Pi process,
+ * which silently turned `HOME ?? ""` paths into cwd-relative ones.
+ */
+
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * User home. For the live process this is exactly `os.homedir()` (what Pi's
+ * `getAgentDir` uses). An injected env (tests) is read instead: USERPROFILE on
+ * Windows, HOME elsewhere, falling back to `os.homedir()`.
+ */
+export function homeDir(
+	env: NodeJS.ProcessEnv = process.env,
+	os: NodeJS.Platform = process.platform,
+): string {
+	if (env === process.env) return homedir();
+	const fromEnv = os === "win32" ? env.USERPROFILE : env.HOME;
+	return fromEnv || homedir();
+}
+
+/** Expand a leading `~` / `~/` / `~\` against {@link homeDir}. */
+export function expandHome(path: string, env: NodeJS.ProcessEnv = process.env): string {
+	if (path === "~") return homeDir(env);
+	if (path.startsWith("~/") || path.startsWith("~\\")) return join(homeDir(env), path.slice(2));
+	return path;
+}
+
+/** Pi agent dir: `PI_CODING_AGENT_DIR` (tilde-expanded) or `~/.pi/agent`. */
+export function agentDir(env: NodeJS.ProcessEnv = process.env): string {
+	const override = env.PI_CODING_AGENT_DIR;
+	if (override) return expandHome(override, env);
+	return join(homeDir(env), ".pi", "agent");
+}
+
+/** Pi's managed binary dir (`<agentDir>/bin`), shared with Pi's fd/rg downloads. */
+export function binDir(env: NodeJS.ProcessEnv = process.env): string {
+	return join(agentDir(env), "bin");
+}
+
+/**
+ * Project config dir: `<cwd>/.pi` (Pi's project `settings.json`, `mcp.json`,
+ * `agents/`, `plans/`, `lsp.json`). With no `cwd` it returns the relative `.pi`,
+ * for paths that resolve against the process cwd or show in text.
+ */
+export function projectDir(cwd = "."): string {
+	return join(cwd, ".pi");
+}
+
+/**
+ * OS temp dir, shared with every other program. Never delete it whole, only
+ * your own entries in it. For the live process this is exactly `os.tmpdir()`.
+ * An injected env (tests) is read instead: TEMP/TMP on Windows, TMPDIR
+ * elsewhere, falling back to `os.tmpdir()`.
+ */
+export function tempDir(
+	env: NodeJS.ProcessEnv = process.env,
+	os: NodeJS.Platform = process.platform,
+): string {
+	if (env === process.env) return tmpdir();
+	const fromEnv = os === "win32" ? env.TEMP || env.TMP : env.TMPDIR;
+	return fromEnv || tmpdir();
+}
+
+/**
+ * Absolute path to a file shipped next to a module: `moduleFile(import.meta.url, "..", "SOP.md")`.
+ * Use it for package assets (SOP.md, skills/). It does not use `URL.pathname`, which gives
+ * `/C:/...` on Windows. It does not use `require.resolve("<pkg>/package.json")`, which Node
+ * rejects when `exports` omits it.
+ */
+export function moduleFile(moduleUrl: string, ...segments: string[]): string {
+	return resolve(dirname(fileURLToPath(moduleUrl)), ...segments);
+}
+
+/** Pi cache root: `$XDG_CACHE_HOME/pi` or `~/.cache/pi`. */
+export function cacheDir(env: NodeJS.ProcessEnv = process.env): string {
+	const xdg = env.XDG_CACHE_HOME;
+	return join(xdg || join(homeDir(env), ".cache"), "pi");
+}

package/src/persistence.ts

@@ -9,6 +9,7 @@
 import {
 	closeSync,
 	existsSync,
+	linkSync,
 	mkdirSync,
 	openSync,
 	readFileSync,
@@ -18,6 +19,7 @@ import {
 	writeFileSync,
 	writeSync,
 } from "node:fs";
+import { hostname } from "node:os";
 import { dirname, join } from "node:path";
 import type { RawDocument } from "./schema.ts";
 
@@ -38,19 +40,62 @@ export class ConfigLockError extends ConfigWriteError {
 	}
 }
 
+/** The config file is not valid JSON or not a JSON object. Never overwrite it. */
+export class ConfigParseError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ConfigParseError";
+	}
+}
+
 /** Filesystem adapter — tests inject an in-memory or temp-dir implementation. */
 export interface StorageAdapter {
 	readonly path: string;
 	readRaw(): string | undefined;
-	/** Atomically replace the config file contents. */
-	writeAtomic(contents: string): void;
+	/**
+	 * Read-modify-write under the cross-process lock: `fn` gets the current file
+	 * text and returns the new contents (atomically written) or undefined (no
+	 * write). Another process cannot write between the read and the write.
+	 */
+	transact(fn: (raw: string | undefined) => string | undefined): void;
 	ensureDir(): void;
 }
 
-const LOCK_STALE_MS = 30_000;
+// A healthy holder keeps the lock for milliseconds (read + write + rename).
+// Stale must be shorter than the retry budget, or a crashed holder makes every
+// writer fail until it expires.
+const LOCK_STALE_MS = 4_000;
 const LOCK_RETRY_MS = 25;
 const LOCK_MAX_RETRIES = 200; // ~5s budget
 
+interface LockOwner {
+	pid: number;
+	host: string;
+}
+
+function parseOwner(text: string): LockOwner | undefined {
+	try {
+		const o = JSON.parse(text) as Partial<LockOwner>;
+		return typeof o.pid === "number" && typeof o.host === "string"
+			? { pid: o.pid, host: o.host }
+			: undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** True only when the owner ran on this host and its process is gone. */
+function ownerIsDead(owner: LockOwner | undefined): boolean {
+	if (!owner || owner.host !== hostname() || owner.pid === process.pid) return false;
+	try {
+		process.kill(owner.pid, 0);
+		return false;
+	} catch (err) {
+		// EPERM: the process exists under another user.
+		return (err as NodeJS.ErrnoException).code === "ESRCH";
+	}
+}
+
 /** Node/Bun filesystem storage rooted at `<agentDir>/pix.json`. */
 export class FileStorage implements StorageAdapter {
 	readonly path: string;
@@ -75,28 +120,63 @@ export class FileStorage implements StorageAdapter {
 	}
 
 	private acquireLock(): void {
+		const me = JSON.stringify({ pid: process.pid, host: hostname() } satisfies LockOwner);
 		for (let i = 0; i < LOCK_MAX_RETRIES; i++) {
 			try {
 				const fd = openSync(this.lockPath, "wx", 0o600);
-				writeSync(fd, JSON.stringify({ pid: process.pid, at: Date.now() }));
-				closeSync(fd);
-				return;
-			} catch {
-				// Reclaim a stale lock only when older than the threshold.
 				try {
-					const age = Date.now() - statSync(this.lockPath).mtimeMs;
-					if (age > LOCK_STALE_MS) {
-						rmSync(this.lockPath, { force: true });
-						continue;
-					}
-				} catch {
-					// Lock vanished between open and stat — retry immediately.
-					continue;
+					writeSync(fd, me);
+				} finally {
+					closeSync(fd);
 				}
-				Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_RETRY_MS);
+				return;
+			} catch (err) {
+				// Only EEXIST means "another writer holds it". EACCES/EROFS/ENOSPC will
+				// not clear by waiting, so fail at once with the real cause.
+				if ((err as NodeJS.ErrnoException).code !== "EEXIST")
+					throw new ConfigLockError(`could not create ${this.lockPath}`, err);
 			}
+			if (this.reclaimIfStale()) continue;
+			Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_RETRY_MS);
+		}
+		throw new ConfigLockError(`could not acquire ${this.lockPath} (held by another process)`);
+	}
+
+	/**
+	 * Remove the lock when its owner process is dead (same host) or it is older
+	 * than {@link LOCK_STALE_MS}. Returns true when the caller should retry now.
+	 *
+	 * The lock moves away by rename, which is atomic, so only one waiter takes a
+	 * given lock file. If that file is not the one judged stale (another waiter
+	 * already reclaimed it and a new holder wrote a fresh lock), it goes back with
+	 * linkSync, which never overwrites.
+	 * ponytail: a third writer can still lock in the few microseconds between the
+	 * rename and the link. Then the restored holder loses mutual exclusion once.
+	 * Upgrade path: an OS file lock (flock / LockFileEx) through a native addon.
+	 */
+	private reclaimIfStale(): boolean {
+		let text: string;
+		let mtimeMs: number;
+		try {
+			text = readFileSync(this.lockPath, "utf-8");
+			mtimeMs = statSync(this.lockPath).mtimeMs;
+		} catch {
+			return true; // The lock vanished between open and read: retry at once.
+		}
+		if (!ownerIsDead(parseOwner(text)) && Date.now() - mtimeMs <= LOCK_STALE_MS) return false;
+		const moved = `${this.lockPath}.stale-${process.pid}-${Math.random().toString(36).slice(2)}`;
+		try {
+			renameSync(this.lockPath, moved);
+		} catch {
+			return true; // Another waiter took it first.
 		}
-		throw new ConfigLockError(`could not acquire ${this.lockPath}`);
+		try {
+			if (readFileSync(moved, "utf-8") !== text) linkSync(moved, this.lockPath);
+		} catch {
+			// EEXIST: a newer lock exists, which is correct. Unreadable: treat as stale.
+		}
+		rmSync(moved, { force: true });
+		return true;
 	}
 
 	private releaseLock(): void {
@@ -107,9 +187,19 @@ export class FileStorage implements StorageAdapter {
 		}
 	}
 
-	writeAtomic(contents: string): void {
+	transact(fn: (raw: string | undefined) => string | undefined): void {
 		this.ensureDir();
 		this.acquireLock();
+		try {
+			const contents = fn(this.readRaw());
+			if (contents !== undefined) this.writeAtomic(contents);
+		} finally {
+			this.releaseLock();
+		}
+	}
+
+	/** Temp file + rename. The caller holds the lock. */
+	private writeAtomic(contents: string): void {
 		const tmp = `${this.path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
 		try {
 			writeFileSync(tmp, contents, { mode: 0o600 });
@@ -121,8 +211,6 @@ export class FileStorage implements StorageAdapter {
 				/* ignore */
 			}
 			throw new ConfigWriteError(`write failed: ${this.path}`, err);
-		} finally {
-			this.releaseLock();
 		}
 	}
 }
@@ -149,16 +237,22 @@ export class WriteQueue {
 
 // ── Raw document read/parse ──────────────────────────────────────────────────
 
+/**
+ * Parse the config file. Missing or empty means `{}`. Invalid JSON or a
+ * non-object throws {@link ConfigParseError}: a hand-edit typo must never be
+ * read as "all defaults" and then written back over the user's file.
+ */
 export function parseRawDocument(text: string | undefined): RawDocument {
-	if (!text) return {};
+	if (!text?.trim()) return {};
+	let parsed: unknown;
 	try {
-		const parsed = JSON.parse(text) as unknown;
-		return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-			? (parsed as RawDocument)
-			: {};
-	} catch {
-		return {};
+		parsed = JSON.parse(text);
+	} catch (err) {
+		throw new ConfigParseError(`invalid JSON: ${(err as Error).message}`);
 	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+		throw new ConfigParseError("top level is not a JSON object");
+	return parsed as RawDocument;
 }
 
 export function serializeRawDocument(doc: RawDocument): string {

package/src/pix-command.ts

@@ -6,6 +6,7 @@
  * Headless hosts get a notify summary instead of the overlay.
  */
 
+import { dirname } from "node:path";
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import {
 	Key,
@@ -15,6 +16,7 @@ import {
 	visibleWidth,
 	wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
+import { createBinariesTab } from "./binaries-tab.ts";
 import { icon } from "./icon-catalog.ts";
 import type { PixRuntime } from "./runtime.ts";
 import type { DeepPartial, SectionHandle } from "./schema.ts";
@@ -184,6 +186,13 @@ const SETTINGS: SettingRow<unknown>[] = [
 	}),
 ];
 
+/** Env whose agent dir is the folder holding pix.json (binary.json lives beside it). */
+function binariesEnv(runtime: PixRuntime): NodeJS.ProcessEnv {
+	return { ...process.env, PI_CODING_AGENT_DIR: dirname(runtime.path) };
+}
+
+const TABS = ["Settings", "Binaries"] as const;
+
 function buildSummary(runtime: PixRuntime): string {
 	const lines = [`Pix Settings (${runtime.path})`, ""];
 	let lastSection = "";
@@ -197,6 +206,12 @@ function buildSummary(runtime: PixRuntime): string {
 		const isDefault = value === row.read(row.handle.defaults);
 		lines.push(`  ${row.label}: ${value}${isDefault ? "" : " *"}`);
 	}
+	const binaries = createBinariesTab({
+		env: binariesEnv(runtime),
+		theme: { fg: (_c, t) => t, bold: (t) => t },
+		requestRender: () => {},
+	});
+	lines.push("", "[Binaries]", ...binaries.summary());
 	return lines.join("\n");
 }
 
@@ -236,6 +251,29 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 					let visibleBodyLines = 1;
 					let maxBodyOffset = 0;
 					let inspectingPage = false;
+					let tab: (typeof TABS)[number] = "Settings";
+					let binaries: ReturnType<typeof createBinariesTab> | undefined;
+					const binariesTab = () => {
+						binaries ??= createBinariesTab({
+							env: binariesEnv(runtime),
+							theme,
+							requestRender: () => tui.requestRender(),
+						});
+						return binaries;
+					};
+					const tabBar = () =>
+						TABS.map((name) =>
+							name === tab
+								? theme.fg("accent", theme.bold(`  ${name}  `))
+								: theme.fg("muted", `  ${name}  `),
+						).join(theme.fg("muted", "│"));
+					const switchTab = (direction: -1 | 1) => {
+						const next = (TABS.indexOf(tab) + direction + TABS.length) % TABS.length;
+						tab = TABS[next] ?? "Settings";
+						bodyOffset = 0;
+						inspectingPage = false;
+						if (tab === "Binaries") binariesTab().refresh();
+					};
 
 					const cycle = (direction: -1 | 1) => {
 						const row = SETTINGS[selected];
@@ -274,6 +312,40 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 
 					return {
 						render: (width: number) => {
+							const frame = {
+								width,
+								maxHeight: modalHeight(
+									tui.terminal?.rows,
+									runtime.get(prettySection).maxRenderHeight,
+								),
+								title: `${icon("settings")} Pix Settings`,
+								titleColor: (s: string) => theme.fg("accent", theme.bold(s)),
+								color: (s: string) => theme.fg("accent", s),
+								bg: (s: string) => theme.bg("customMessageBg", s),
+							};
+							const tabGuide = guide("tab", "switch tab");
+							if (tab === "Binaries") {
+								const bt = binariesTab();
+								const view = bt.view(width);
+								const hints = view.footer.map(([key, action]) => guide(key, action)).join(guideSep);
+								const result = frameModal({
+									...frame,
+									header: [tabBar(), "", ...view.header],
+									body: view.body,
+									footer: [
+										"",
+										bt.editing
+											? hints
+											: hints + guideSep + tabGuide + guideSep + guide("esc", "close"),
+									],
+									bodyOffset,
+									selectedBodyLine: inspectingPage ? undefined : view.selectedBodyLine,
+								});
+								bodyOffset = result.bodyOffset;
+								visibleBodyLines = Math.max(1, result.visibleBodyLines);
+								maxBodyOffset = result.maxBodyOffset;
+								return result.lines;
+							}
 							const labelW = Math.max(...SETTINGS.map((r) => r.label.length));
 							const body: string[] = [];
 							const settingBodyLines: number[] = [];
@@ -295,14 +367,8 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 								body.push(`${cursor} ${label}  ${theme.fg(isDefault ? "dim" : "success", value)}`);
 							}
 							const result = frameModal({
-								width,
-								maxHeight: modalHeight(
-									tui.terminal?.rows,
-									runtime.get(prettySection).maxRenderHeight,
-								),
-								title: `${icon("settings")} Pix Settings`,
-								titleColor: (s: string) => theme.fg("accent", theme.bold(s)),
-								header: [""],
+								...frame,
+								header: [tabBar(), ""],
 								body,
 								footer: [
 									"",
@@ -312,12 +378,12 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 										guideSep +
 										guide("PgUp/PgDn", "inspect") +
 										guideSep +
+										tabGuide +
+										guideSep +
 										guide("esc", "close"),
 								],
 								bodyOffset,
 								selectedBodyLine: inspectingPage ? undefined : settingBodyLines[selected],
-								color: (s: string) => theme.fg("accent", s),
-								bg: (s: string) => theme.bg("customMessageBg", s),
 							});
 							bodyOffset = result.bodyOffset;
 							visibleBodyLines = Math.max(1, result.visibleBodyLines);
@@ -326,6 +392,24 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 						},
 						invalidate: () => {},
 						handleInput: (data: string) => {
+							if (tab === "Binaries" && binariesTab().editing) {
+								// The filter input takes ↑↓ to move through its matches.
+								const nav = !binariesTab().editingPath;
+								binariesTab().handleInput(data, {
+									up: nav && kb.matches(data, "tui.select.up"),
+									down: nav && kb.matches(data, "tui.select.down"),
+									enter: false,
+								});
+								inspectingPage = false;
+								tui.requestRender();
+								return;
+							}
+							const shiftTab = matchesKey(data, Key.shift(Key.tab));
+							if (shiftTab || matchesKey(data, Key.tab)) {
+								switchTab(shiftTab ? -1 : 1);
+								tui.requestRender();
+								return;
+							}
 							const pageUp = kb?.matches(data, "tui.select.pageUp") || matchesKey(data, Key.pageUp);
 							const pageDown =
 								kb?.matches(data, "tui.select.pageDown") || matchesKey(data, Key.pageDown);
@@ -340,9 +424,25 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 							// for letters and special keys alike — raw string compares like
 							// `data === "k"` silently fail under the Kitty keyboard protocol.
 							if (kb.matches(data, "tui.select.cancel")) {
+								if (tab === "Binaries" && binariesTab().clearFilter()) {
+									tui.requestRender();
+									return;
+								}
 								done(null);
 								return;
 							}
+							if (tab === "Binaries") {
+								const handled = binariesTab().handleInput(data, {
+									up: kb.matches(data, "tui.select.up"),
+									down: kb.matches(data, "tui.select.down"),
+									enter: kb.matches(data, "tui.select.confirm"),
+								});
+								if (handled) {
+									inspectingPage = false;
+									tui.requestRender();
+								}
+								return;
+							}
 							if (kb.matches(data, "tui.select.up")) move(-1);
 							else if (kb.matches(data, "tui.select.down")) move(1);
 							else if (matchesKey(data, Key.left)) cycle(-1);

package/src/platform.ts

@@ -0,0 +1,75 @@
+/**
+ * platform.ts — one host description for binary selection and OS branches.
+ *
+ * Pure except for two cached probes (glibc via `process.report`, WSL via
+ * `/proc/version`); every input is injectable so tests cover all hosts.
+ */
+
+import { readFileSync } from "node:fs";
+
+export type HostOs = "win32" | "linux" | "darwin" | "android";
+export type HostArch = "x64" | "arm64";
+
+export interface HostPlatform {
+	os: HostOs;
+	arch: HostArch;
+	/** Linux C library; undefined elsewhere. */
+	libc?: "glibc" | "musl";
+	/** Linux kernel under Windows Subsystem for Linux. */
+	wsl: boolean;
+	/** Termux on Android. */
+	termux: boolean;
+	/** Executable suffix. */
+	exe: "" | ".exe";
+}
+
+export interface HostProbe {
+	platform?: NodeJS.Platform;
+	arch?: string;
+	env?: NodeJS.ProcessEnv;
+	/** glibc runtime version, or undefined on musl. */
+	glibcVersion?: () => string | undefined;
+	/** Contents of `/proc/version`, or undefined when unreadable. */
+	procVersion?: () => string | undefined;
+}
+
+function defaultGlibc(): string | undefined {
+	try {
+		const report = process.report?.getReport() as { header?: { glibcVersionRuntime?: string } };
+		return report?.header?.glibcVersionRuntime;
+	} catch {
+		return undefined;
+	}
+}
+
+function defaultProcVersion(): string | undefined {
+	try {
+		return readFileSync("/proc/version", "utf-8");
+	} catch {
+		return undefined;
+	}
+}
+
+/** Describe the current host (or an injected one). */
+export function hostPlatform(probe: HostProbe = {}): HostPlatform {
+	const platform = probe.platform ?? process.platform;
+	const env = probe.env ?? process.env;
+	const arch: HostArch = (probe.arch ?? process.arch) === "arm64" ? "arm64" : "x64";
+	const termux = Boolean(env.TERMUX_VERSION) || platform === "android";
+	if (platform === "win32") return { os: "win32", arch, wsl: false, termux: false, exe: ".exe" };
+	if (platform === "darwin") return { os: "darwin", arch, wsl: false, termux: false, exe: "" };
+	if (termux) return { os: "android", arch, wsl: false, termux: true, exe: "" };
+	const glibc = (probe.glibcVersion ?? defaultGlibc)();
+	const wsl =
+		Boolean(env.WSL_DISTRO_NAME || env.WSLENV) ||
+		/microsoft|wsl/i.test((probe.procVersion ?? defaultProcVersion)() ?? "");
+	return { os: "linux", arch, libc: glibc ? "glibc" : "musl", wsl, termux: false, exe: "" };
+}
+
+let cached: HostPlatform | undefined;
+
+/** Cached {@link hostPlatform} for the running process. */
+export function currentPlatform(): HostPlatform {
+	cached ??= hostPlatform();
+	return cached;
+}