@xynogen/pix-runtime 0.10.2 → 0.13.0

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,9 +16,10 @@ 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";
+import { type DeepPartial, deepMerge, type SectionHandle } from "./schema.ts";
 import { collapseSection } from "./sections/collapse.ts";
 import { compactionSection } from "./sections/compaction.ts";
 import { gateSection } from "./sections/gate.ts";
@@ -182,8 +184,26 @@ const SETTINGS: SettingRow<unknown>[] = [
 		read: (v) => v.guardrails,
 		patch: (guardrails) => ({ guardrails: guardrails as "on" | "off" }),
 	}),
+	...Object.keys(prettySection.defaults.footer).map((key) => {
+		const part = key as keyof typeof prettySection.defaults.footer;
+		return row({
+			section: "Footer",
+			label: part,
+			handle: prettySection,
+			values: ["show", "hide"],
+			read: (v) => (v.footer[part] ? "show" : "hide"),
+			patch: (value) => ({ footer: { [part]: value === "show" } }),
+		});
+	}),
 ];
 
+/** 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", "Footer"] as const;
+
 function buildSummary(runtime: PixRuntime): string {
 	const lines = [`Pix Settings (${runtime.path})`, ""];
 	let lastSection = "";
@@ -197,6 +217,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,9 +262,35 @@ 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";
+						selected = 0;
+						bodyOffset = 0;
+						inspectingPage = false;
+						if (tab === "Binaries") binariesTab().refresh();
+					};
 
+					const rows = () =>
+						SETTINGS.filter((r) => (r.section === "Footer") === (tab === "Footer"));
 					const cycle = (direction: -1 | 1) => {
-						const row = SETTINGS[selected];
+						const row = rows()[selected];
 						if (!row) return;
 						// Functional updater: the runtime queue serializes writes, and the
 						// callback sees the latest committed value — so rapid presses each
@@ -258,7 +310,7 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 							const next = (cur + direction + row.values.length) % row.values.length;
 							const val = row.values[next];
 							if (val === undefined) return state;
-							return { ...state, ...(row.patch(val) as object) };
+							return deepMerge(state, row.patch(val) as DeepPartial<SettingsState>);
 						};
 						// Re-render AFTER the commit lands; the synchronous render in
 						// handleInput fires before the queued write and shows a stale value.
@@ -268,18 +320,53 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 							.catch(() => ui.notify(`pix: failed to update ${row.label}`, "error"));
 					};
 					const move = (direction: -1 | 1) => {
-						selected = (selected + direction + SETTINGS.length) % SETTINGS.length;
+						selected = (selected + direction + rows().length) % rows().length;
 						inspectingPage = false;
 					};
 
 					return {
 						render: (width: number) => {
-							const labelW = Math.max(...SETTINGS.map((r) => r.label.length));
+							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 settings = rows();
+							const labelW = Math.max(...settings.map((r) => r.label.length));
 							const body: string[] = [];
 							const settingBodyLines: number[] = [];
 							let lastSection = "";
-							for (let i = 0; i < SETTINGS.length; i++) {
-								const row = SETTINGS[i];
+							for (let i = 0; i < settings.length; i++) {
+								const row = settings[i];
 								if (!row) continue;
 								if (row.section !== lastSection) {
 									if (lastSection) body.push("");
@@ -295,14 +382,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 +393,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 +407,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 +439,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;
+}

package/src/runtime.ts

@@ -6,7 +6,6 @@
  * after a lazy load; writes are serialized and atomic.
  */
 
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { DiagnosticSink } from "./diagnostics.ts";
 import {
 	type ConfigChange,
@@ -18,8 +17,9 @@ import {
 	type SubscribeOptions,
 } from "./events.ts";
 import { importOptimizerSidecar, migrate } from "./migrations.ts";
+import { agentDir } from "./paths.ts";
 import {
-	ConfigWriteError,
+	ConfigParseError,
 	FileStorage,
 	parseRawDocument,
 	type StorageAdapter,
@@ -99,7 +99,7 @@ class RuntimeImpl implements PixRuntime {
 	private readOnly = false;
 
 	constructor(adapters: RuntimeAdapters = {}) {
-		this.agentDir = adapters.agentDir ?? getAgentDir();
+		this.agentDir = adapters.agentDir ?? agentDir();
 		this.storage = adapters.storage ?? new FileStorage(this.agentDir);
 		this.registry = adapters.registry ?? new SectionRegistry();
 	}
@@ -139,16 +139,45 @@ class RuntimeImpl implements PixRuntime {
 		try {
 			doc = parseRawDocument(this.storage.readRaw());
 		} catch (err) {
-			this.sink.push({
-				code: "READ_FAILED",
-				severity: "warning",
-				message: "config read failed; using defaults",
-				cause: err,
-			});
+			if (err instanceof ConfigParseError) this.parseFailed(err);
+			else
+				this.sink.push({
+					code: "READ_FAILED",
+					severity: "warning",
+					message: "config read failed; using defaults",
+					cause: err,
+				});
 		}
 		return this.publish(this.resolve(doc));
 	}
 
+	/** A malformed pix.json stays untouched: defaults apply, writes are refused. */
+	private parseFailed(err: ConfigParseError, path?: string): void {
+		this.sink.push({
+			code: "PARSE_ERROR",
+			severity: "error",
+			path,
+			message: `${this.storage.path}: ${err.message}. File left unchanged; fix it to save settings.`,
+			cause: err,
+		});
+	}
+
+	/** Migration + sidecar import for one raw file read. Pure except `ctx`. */
+	private planInit(raw: string | undefined, ctx: ParseContext) {
+		const doc = parseRawDocument(raw);
+		const migrated = migrate(doc, ctx);
+		const readOnly = migrated.document.$version !== CONFIG_FORMAT_VERSION;
+		let needsWrite = migrated.changed;
+		let archive: (() => void) | undefined;
+		if (!readOnly) {
+			const sidecar = importOptimizerSidecar(migrated.document, this.agentDir, ctx);
+			if (sidecar.changed) needsWrite = true;
+			archive = sidecar.archive;
+		}
+		// Do not normalize a future-version file.
+		return { working: readOnly ? doc : migrated.document, readOnly, needsWrite, archive };
+	}
+
 	snapshot(): ConfigSnapshot {
 		return this.current ?? this.lazyLoad();
 	}
@@ -182,36 +211,38 @@ class RuntimeImpl implements PixRuntime {
 			const hadLazy = this.current !== null;
 			const previous = this.current;
 			this.storage.ensureDir();
-			const doc = parseRawDocument(this.storage.readRaw());
-			const ctx = this.parseContext();
-
-			const migrated = migrate(doc, ctx);
-			this.readOnly = migrated.document.$version !== CONFIG_FORMAT_VERSION;
-
-			let working = migrated.document;
-			let needsWrite = migrated.changed;
-			let archive: (() => void) | undefined;
-
-			if (!this.readOnly) {
-				const sidecar = importOptimizerSidecar(working, this.agentDir, ctx);
-				if (sidecar.changed) needsWrite = true;
-				archive = sidecar.archive;
-			}
-
-			if (needsWrite && !this.readOnly) {
-				try {
-					this.persist(working);
-					archive?.();
-				} catch (err) {
-					this.sink.push({
-						code: "WRITE_FAILED",
-						severity: "error",
-						message: "initial migration write failed",
-						cause: err,
-					});
+			let working: RawDocument = {};
+			let needsWrite = false;
+			try {
+				// Unlocked probe: most sessions need no write, so they never take the lock.
+				let plan = this.planInit(this.storage.readRaw(), this.parseContext());
+				this.readOnly = plan.readOnly;
+				working = plan.working;
+				if (plan.needsWrite && !plan.readOnly) {
+					try {
+						// Re-plan under the lock so a concurrent writer's change survives.
+						this.storage.transact((raw) => {
+							plan = this.planInit(raw, { diagnostic: () => {} });
+							working = plan.working;
+							needsWrite = plan.needsWrite && !plan.readOnly;
+							return needsWrite ? serializeRawDocument(plan.working) : undefined;
+						});
+						if (needsWrite) plan.archive?.();
+					} catch (err) {
+						needsWrite = false;
+						if (err instanceof ConfigParseError) throw err;
+						this.sink.push({
+							code: "WRITE_FAILED",
+							severity: "error",
+							message: "initial migration write failed",
+							cause: err,
+						});
+					}
 				}
-			} else if (this.readOnly) {
-				working = doc; // do not normalize a future-version file
+			} catch (err) {
+				if (!(err instanceof ConfigParseError)) throw err;
+				this.parseFailed(err);
+				working = {};
 			}
 
 			const values = this.resolve(working);
@@ -242,6 +273,10 @@ class RuntimeImpl implements PixRuntime {
 			}
 			return snapshot;
 		});
+		// A failed init (unreadable agent dir) must not stay cached: the next call retries.
+		this.initPromise.catch(() => {
+			this.initPromise = null;
+		});
 		return this.initPromise;
 	}
 
@@ -267,10 +302,6 @@ class RuntimeImpl implements PixRuntime {
 		return stripDefaults(copy, defaults) > 0 ? copy : undefined;
 	}
 
-	private persist(doc: RawDocument): void {
-		this.storage.writeAtomic(serializeRawDocument(doc));
-	}
-
 	private changedPaths(prev: ConfigSnapshot, next: ConfigSnapshot): string[] {
 		const out: string[] = [];
 		for (const section of this.registry.all()) {
@@ -339,49 +370,56 @@ class RuntimeImpl implements PixRuntime {
 		}
 
 		const previous = this.snapshot();
-		const base = parseRawDocument(this.storage.readRaw());
 		const ctx = this.parseContext();
+		let values: Map<string, unknown> | undefined;
 
-		// Re-resolve all sections from the latest on-disk doc so unknown fields
-		// and sibling sections survive.
-		const values = new Map<string, unknown>();
-		for (const s of this.registry.all()) values.set(s.key, s.parse(base[s.key], ctx));
-
-		// Guard against a version-skewed second runtime copy whose registry
-		// lacks this section (e.g. an old npm copy handling a new handle). The
-		// functional updater would otherwise crash the whole process on
-		// `undefined`. Fall back to the handle's own parse of the raw doc.
-		const currentValue = (
-			values.has(section.key)
-				? values.get(section.key)
-				: section.__section.parse(base[section.key], ctx)
-		) as Readonly<T>;
-		const mergedValue =
-			typeof updater === "function"
-				? (updater as (c: Readonly<T>) => T)(currentValue)
-				: deepMerge(currentValue as T, updater);
-
-		// Re-validate through the section's own parse so a bad patch (NaN,
-		// Infinity, wrong type) can never enter the live snapshot.
-		const nextValue = section.__section.parse(mergedValue, ctx) as T;
-
-		if (JSON.stringify(currentValue) === JSON.stringify(nextValue)) return undefined;
-		values.set(section.key, nextValue);
-
-		const doc = this.buildRawFromValues(values, base);
 		try {
-			this.persist(doc);
-		} catch (err) {
-			this.sink.push({
-				code: "WRITE_FAILED",
-				severity: "error",
-				path: section.key,
-				message: "config write failed; snapshot unchanged",
-				cause: err,
+			// Read, patch, and write under one lock hold: a second Pi process cannot
+			// write between our read and our write, so its change is not lost.
+			this.storage.transact((raw) => {
+				const base = parseRawDocument(raw);
+
+				// Re-resolve all sections from the latest on-disk doc so unknown fields
+				// and sibling sections survive.
+				const next = new Map<string, unknown>();
+				for (const s of this.registry.all()) next.set(s.key, s.parse(base[s.key], ctx));
+
+				// Guard against a version-skewed second runtime copy whose registry
+				// lacks this section (e.g. an old npm copy handling a new handle). The
+				// functional updater would otherwise crash the whole process on
+				// `undefined`. Fall back to the handle's own parse of the raw doc.
+				const currentValue = (
+					next.has(section.key)
+						? next.get(section.key)
+						: section.__section.parse(base[section.key], ctx)
+				) as Readonly<T>;
+				const mergedValue =
+					typeof updater === "function"
+						? (updater as (c: Readonly<T>) => T)(currentValue)
+						: deepMerge(currentValue as T, updater);
+
+				// Re-validate through the section's own parse so a bad patch (NaN,
+				// Infinity, wrong type) can never enter the live snapshot.
+				const nextValue = section.__section.parse(mergedValue, ctx) as T;
+
+				if (JSON.stringify(currentValue) === JSON.stringify(nextValue)) return undefined;
+				next.set(section.key, nextValue);
+				values = next;
+				return serializeRawDocument(this.buildRawFromValues(next, base));
 			});
-			if (err instanceof ConfigWriteError) return undefined;
+		} catch (err) {
+			if (err instanceof ConfigParseError) this.parseFailed(err, section.key);
+			else
+				this.sink.push({
+					code: "WRITE_FAILED",
+					severity: "error",
+					path: section.key,
+					message: "config write failed; snapshot unchanged",
+					cause: err,
+				});
 			return undefined;
 		}
+		if (!values) return undefined;
 
 		const snapshot = this.publish(values);
 		const change: ConfigChange = {
@@ -401,7 +439,15 @@ class RuntimeImpl implements PixRuntime {
 	reload(options: ReloadOptions = {}): Promise<ConfigChange | undefined> {
 		return this.queue.run(async () => {
 			const previous = this.snapshot();
-			const doc = parseRawDocument(this.storage.readRaw());
+			let doc: RawDocument;
+			try {
+				doc = parseRawDocument(this.storage.readRaw());
+			} catch (err) {
+				// Keep the last good snapshot. Do not reset live settings to defaults.
+				if (!(err instanceof ConfigParseError)) throw err;
+				this.parseFailed(err);
+				return undefined;
+			}
 			const values = this.resolve(doc);
 			const snapshot = this.publish(values);
 			const changed = this.changedPaths(previous, snapshot);