@xynogen/pix-runtime 0.15.2 → 0.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-runtime",
-	"version": "0.15.2",
+	"version": "0.16.1",
 	"description": "Pix shared runtime — versioned pix.json config, atomic persistence, typed change events",
 	"type": "module",
 	"main": "src/index.ts",

package/src/exec.ts

@@ -97,7 +97,7 @@ export interface ToolExecOptions {
 	onStatus?: (status: ToolStatus) => void;
 	/** Test seam for the host OS. */
 	host?: HostPlatform;
-	/** Cap on captured stdout/stderr bytes each (default 50 MB). */
+	/** Cap on captured stdout/stderr bytes each (default 50 MB). Past it the child is stopped. */
 	maxBuffer?: number;
 	/** Args are already quoted for the target (cmd.exe `/c` lines); Node must not re-quote. */
 	verbatim?: boolean;
@@ -111,7 +111,7 @@ export interface ToolRunResult {
 	/** Raw stdout for binary output (clipboard images, archives). */
 	stdoutBytes: Buffer;
 	timedOut: boolean;
-	/** Output passed `maxBuffer` and was cut. A zero exit code is then not a complete result. */
+	/** Output passed `maxBuffer`; the child was stopped and output cut. Never a complete result. */
 	truncated: boolean;
 	/** The binary that ran and where it was found. */
 	tool: ResolvedTool;
@@ -220,7 +220,11 @@ function collect(
 		let truncated = false;
 		const push = (list: Buffer[], chunk: Buffer, len: number): number => {
 			const room = cap - len;
-			if (chunk.length > room) truncated = true;
+			// Like pi.exec: stop a runaway child instead of draining output nobody keeps.
+			if (chunk.length > room) {
+				truncated = true;
+				stop();
+			}
 			if (room <= 0) return len;
 			list.push(chunk.length > room ? chunk.subarray(0, room) : chunk);
 			return len + Math.min(chunk.length, room);

package/src/icon-catalog.ts

@@ -135,11 +135,15 @@ function envMode(): IconMode {
 	return "nerd";
 }
 
-let activeMode: IconMode = envMode();
+const shared = globalThis as {
+	__pixIconState?: { mode: IconMode; listeners: Set<(mode: IconMode) => void> };
+};
+shared.__pixIconState ??= { mode: envMode(), listeners: new Set() };
+const state = shared.__pixIconState;
 
 /** Current global icon mode. */
 export function getIconMode(): IconMode {
-	return activeMode;
+	return state.mode;
 }
 
 /**
@@ -149,7 +153,7 @@ export function getIconMode(): IconMode {
  * here; setIconMode fires every callback on an actual change.
  */
 type ModeListener = (mode: IconMode) => void;
-const listeners = new Set<ModeListener>();
+const listeners = state.listeners;
 
 /** Subscribe to global icon-mode changes. Returns an unsubscribe fn. */
 export function onIconModeChange(cb: ModeListener): () => void {
@@ -163,8 +167,8 @@ export function onIconModeChange(cb: ModeListener): () => void {
  * subscribers only on an actual change (no-op re-sets are ignored).
  */
 export function setIconMode(mode: IconMode): void {
-	if (!ICON_MODES.includes(mode) || mode === activeMode) return;
-	activeMode = mode;
+	if (!ICON_MODES.includes(mode) || mode === state.mode) return;
+	state.mode = mode;
 	for (const cb of listeners) cb(mode);
 }
 
@@ -174,7 +178,7 @@ export function setIconMode(mode: IconMode): void {
  */
 export function icon(key: IconKey): string {
 	const entry = CATALOG[key];
-	return entry ? entry[activeMode] : "";
+	return entry ? entry[state.mode] : "";
 }
 
 /** Resolve a key for an explicit mode (used by /pix previews + tests). */

package/src/index.ts

@@ -32,6 +32,7 @@ export {
 	parseLfid,
 	uniqueLfid,
 } from "./lfid.ts";
+export { type PackageSettings, registerPackageSettings } from "./pix-command.ts";
 export {
 	config,
 	createRuntime,

package/src/once.ts

@@ -10,7 +10,25 @@
  * skip, new instance => run. The registry lives on globalThis because jiti
  * (`moduleCache: false`) re-evaluates this module on every load pass.
  */
-export function once(pi: object, key: string, fn: () => void): void {
+type PackageHost = {
+	events?: {
+		emit(channel: string, data: unknown): void;
+		on(channel: string, handler: (data: unknown) => void): unknown;
+	};
+};
+
+const PACKAGE_QUERY = "pix:package-loaded";
+
+/** Check after extension loading (for example, session_start), not factory order. */
+export function isPackageLoaded(pi: PackageHost, key: string): boolean {
+	const loaded = (globalThis as { __pixOnce?: WeakMap<object, Set<string>> }).__pixOnce;
+	if (loaded?.get(pi)?.has(key)) return true;
+	const query = { key, loaded: false };
+	pi.events?.emit(PACKAGE_QUERY, query);
+	return query.loaded;
+}
+
+export function once(pi: PackageHost, key: string, fn: () => void): void {
 	const g = globalThis as { __pixOnce?: WeakMap<object, Set<string>> };
 	if (!g.__pixOnce) g.__pixOnce = new WeakMap<object, Set<string>>();
 	const registry = g.__pixOnce;
@@ -18,6 +36,12 @@ export function once(pi: object, key: string, fn: () => void): void {
 	if (!loaded) {
 		loaded = new Set<string>();
 		registry.set(pi, loaded);
+		pi.events?.on(PACKAGE_QUERY, (data) => {
+			if (!data || typeof data !== "object" || !("key" in data) || !("loaded" in data)) return;
+			if (typeof data.key === "string" && registry.get(pi)?.has(data.key)) {
+				data.loaded = true;
+			}
+		});
 	}
 	if (loaded.has(key)) return;
 	loaded.add(key);

package/src/os.ts

@@ -8,6 +8,7 @@
 
 import { randomUUID } from "node:crypto";
 import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { userInfo } from "node:os";
 import { join } from "node:path";
 import { resolveTool } from "./binaries/resolve.ts";
 import { quoteForCmd, runTool, runToolSync } from "./exec.ts";
@@ -19,6 +20,19 @@ export interface OsOptions {
 	host?: HostPlatform;
 }
 
+/** Current OS account name; unavailable accounts do not prevent startup. */
+export function username(): string | undefined {
+	try {
+		return (
+			userInfo()
+				.username.replace(/[\x00-\x1f\x7f-\x9f]/g, "")
+				.trim() || undefined
+		);
+	} catch {
+		return undefined;
+	}
+}
+
 // ── Open a URL or path ──────────────────────────────────────────────────────
 
 export interface OpenOptions extends OsOptions {
@@ -32,7 +46,7 @@ export function openCommand(
 	target: string,
 	host: HostPlatform,
 	app?: string,
-): { name: string; args: string[]; verbatim?: boolean } {
+): { name: string; args: string[]; verbatim?: boolean; cwd?: string } {
 	if (host.os === "darwin") return { name: "open", args: app ? ["-a", app, target] : [target] };
 	if (host.os === "win32") {
 		// `start` is a cmd.exe builtin; "" is its window-title argument.
@@ -40,8 +54,9 @@ export function openCommand(
 		return { name: "cmd", args: ["/d", "/s", "/c", `"${parts.join(" ")}"`], verbatim: true };
 	}
 	if (host.wsl && !app) {
-		// WSL: hand the target to Windows so the user's default browser opens.
-		return { name: "wslview", args: [target] };
+		// WSL: hand the target to Windows so the user's default browser opens. Windows programs
+		// cannot start from a long `\\wsl.localhost\...` cwd, so start from `/`.
+		return { name: "wslview", args: [target], cwd: "/" };
 	}
 	return { name: app ?? "xdg-open", args: [target] };
 }
@@ -57,6 +72,7 @@ export async function openTarget(target: string, opts: OpenOptions = {}): Promis
 	if (cmd.name === "wslview" && !resolveTool("wslview", opts))
 		cmd = openCommand(target, { ...host, wsl: false });
 	const result = await runTool(cmd.name, cmd.args, {
+		cwd: cmd.cwd,
 		env: opts.env,
 		host,
 		timeoutMs: opts.timeoutMs ?? 15_000,
@@ -126,10 +142,16 @@ export function pickPreferredMime(types: readonly string[]): string | null {
 }
 
 /** Output bytes when the tool exists and exits 0; null otherwise (probing, never throws). */
-function probe(name: string, args: string[], timeoutMs: number, opts: OsOptions): Buffer | null {
+function probe(
+	name: string,
+	args: string[],
+	timeoutMs: number,
+	opts: OsOptions,
+	cwd?: string,
+): Buffer | null {
 	if (!resolveTool(name, opts)) return null;
 	try {
-		const r = runToolSync(name, args, { env: opts.env, host: opts.host, timeoutMs });
+		const r = runToolSync(name, args, { env: opts.env, host: opts.host, timeoutMs, cwd });
 		return r.code === 0 ? r.stdoutBytes : null;
 	} catch {
 		return null;
@@ -189,7 +211,8 @@ function viaPowerShell(host: HostPlatform, opts: OsOptions): ClipboardImage | nu
 			"if ($img) { $img.Save($path, [System.Drawing.Imaging.ImageFormat]::Png); Write-Output 'ok' } else { Write-Output 'empty' }",
 		].join("; ");
 		const args = ["-NoProfile", "-STA", "-Command", script];
-		const out = probe("powershell", args, POWERSHELL_TIMEOUT_MS, opts);
+		// From WSL, Windows programs cannot start from a long `\\wsl.localhost\...` cwd.
+		const out = probe("powershell", args, POWERSHELL_TIMEOUT_MS, opts, host.wsl ? "/" : undefined);
 		if (out?.toString("utf-8").trim() !== "ok") return null;
 		const bytes = readFileSync(tmpFile);
 		return bytes.length ? { bytes, mimeType: "image/png" } : null;

package/src/pix-command.ts

@@ -18,7 +18,8 @@ import {
 } from "@earendil-works/pi-tui";
 import { createBinariesTab } from "./binaries-tab.ts";
 import { icon } from "./icon-catalog.ts";
-import type { PixRuntime } from "./runtime.ts";
+import { isPackageLoaded } from "./once.ts";
+import { type PixRuntime, pixRuntime } from "./runtime.ts";
 import { type DeepPartial, deepMerge, type SectionHandle } from "./schema.ts";
 import { collapseSection } from "./sections/collapse.ts";
 import { compactionSection } from "./sections/compaction.ts";
@@ -41,6 +42,21 @@ function row<T>(r: SettingRow<T>): SettingRow<unknown> {
 	return r as SettingRow<unknown>;
 }
 
+/** Pi-owned theme row: not stored in pix.json, applied through `ctx.ui.setTheme`. */
+interface ThemeRow {
+	kind: "theme";
+	section: string;
+	label: string;
+	values: readonly string[];
+	current: () => string;
+}
+
+type Row = SettingRow<unknown> | ThemeRow;
+
+function isThemeRow(row: Row): row is ThemeRow {
+	return "kind" in row;
+}
+
 /** Render a token count as a compact label: 1_000_000 → "1M", 150_000 → "150k". */
 function formatTokens(tokens: number): string {
 	return tokens % 1_000_000 === 0 ? `${tokens / 1_000_000}M` : `${tokens / 1000}k`;
@@ -213,11 +229,34 @@ function binariesEnv(runtime: PixRuntime): NodeJS.ProcessEnv {
 }
 
 const TABS = ["Settings", "Binaries", "Footer"] as const;
+/** Most frequently changed tabs sit leftmost; unknown package tabs go before rare ones. */
+const TAB_ORDER = ["Settings", "Tools", "MCP", "Optimizer", "Web", "Voice"];
+const RARE_TABS = ["Footer", "Binaries"];
+function tabRank(label: string): number {
+	const common = TAB_ORDER.indexOf(label);
+	if (common >= 0) return common;
+	const rare = RARE_TABS.indexOf(label);
+	return rare >= 0 ? 100 + rare : 50;
+}
+const SECTION_PACKAGES: Record<string, string> = {
+	Compaction: "pix-core",
+	Edit: "pix-diagnostics",
+	Gate: "pix-gate",
+	Footer: "pix-footer",
+};
+
+function visibleSettings(pi: ExtensionAPI): SettingRow<unknown>[] {
+	return SETTINGS.filter(
+		(row) =>
+			!SECTION_PACKAGES[row.section] ||
+			isPackageLoaded(pi, SECTION_PACKAGES[row.section] as string),
+	);
+}
 
-function buildSummary(runtime: PixRuntime): string {
+function buildSummary(runtime: PixRuntime, settings: SettingRow<unknown>[]): string {
 	const lines = [`Pix Settings (${runtime.path})`, ""];
 	let lastSection = "";
-	for (const row of SETTINGS) {
+	for (const row of settings) {
 		if (row.section !== lastSection) {
 			if (lastSection) lines.push("");
 			lines.push(`[${row.section}]`);
@@ -236,12 +275,63 @@ function buildSummary(runtime: PixRuntime): string {
 	return lines.join("\n");
 }
 
+export type PackageSettings = {
+	id: string;
+	label: string;
+	open(ctx: ExtensionCommandContext): Promise<void>;
+};
+
+const SETTINGS_QUERY = "pix:settings";
+const COMMAND_QUERY = "pix:settings-command";
+
+/** Register only from an active package factory; Pi clears subscriptions on reload. */
+export function registerPackageSettings(pi: ExtensionAPI, settings: PackageSettings): void {
+	pi.events?.on(SETTINGS_QUERY, (data: unknown) => {
+		if (data instanceof Map) data.set(settings.id, settings);
+	});
+	registerPixCommand(pi, pixRuntime());
+}
+
+function packageSettings(pi: ExtensionAPI): PackageSettings[] {
+	const entries = new Map<string, PackageSettings>();
+	pi.events?.emit(SETTINGS_QUERY, entries);
+	return [...entries.values()].sort((a, b) => a.label.localeCompare(b.label));
+}
+
 export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void {
+	const claim = { registered: false };
+	pi.events?.emit(COMMAND_QUERY, claim);
+	if (claim.registered) return;
+	pi.events?.on(COMMAND_QUERY, (data: unknown) => {
+		if (data && typeof data === "object" && "registered" in data) data.registered = true;
+	});
 	pi.registerCommand("pix", {
-		description: "pix: open shared settings (edit pix.json)",
-		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+		description: "pix: open shared settings (edit pix.json); /pix <tab> opens that tab",
+		getArgumentCompletions: (prefix: string) => {
+			const p = prefix.trim().toLowerCase();
+			const items = [...TABS, ...packageSettings(pi).map((entry) => entry.label)]
+				.map((label) => label.toLowerCase())
+				.filter((name) => name.startsWith(p))
+				.map((name) => ({ value: name, label: name }));
+			return items.length ? items : null;
+		},
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			// Re-parse pix.json so section parsers remain the single validation source.
 			await runtime.reload({ origin: "command", source: "pix" });
+			const panels = packageSettings(pi);
+			const settings = visibleSettings(pi);
+			// Pi owns the active theme (settings.json); `/pix` only cycles it through `ctx.ui.setTheme`.
+			const themeNames = (ctx.ui.getAllThemes?.() ?? []).map((t) => t.name).sort();
+			const themeRow: ThemeRow | undefined =
+				themeNames.length > 1
+					? {
+							kind: "theme",
+							section: "Pretty",
+							label: "theme",
+							values: themeNames,
+							current: () => ctx.ui.theme.name ?? "",
+						}
+					: undefined;
 			// SAFETY: Runtime UI supports custom overlays beyond the published command context type.
 			const ui = ctx.ui as unknown as {
 				custom?: (f: unknown, opts?: unknown) => Promise<unknown>;
@@ -249,7 +339,12 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 			};
 
 			if (typeof ui.custom !== "function") {
-				ui.notify(buildSummary(runtime), "info");
+				ui.notify(
+					[buildSummary(runtime, settings), ...panels.map((panel) => `[${panel.label}]`)].join(
+						"\n",
+					),
+					"info",
+				);
 				return;
 			}
 
@@ -272,7 +367,77 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 					let visibleBodyLines = 1;
 					let maxBodyOffset = 0;
 					let inspectingPage = false;
-					let tab: (typeof TABS)[number] = "Settings";
+					const tabs = [
+						...TABS.filter(
+							(name) => name !== "Footer" || settings.some((row) => row.section === "Footer"),
+						),
+						...panels.map((entry) => entry.label),
+					].sort((a, b) => tabRank(a) - tabRank(b));
+					const wanted = (args ?? "").trim().toLowerCase();
+					let tab = tabs.find((name) => name.toLowerCase() === wanted) ?? "Settings";
+					let embedded:
+						| { render(width: number): string[]; handleInput(data: string): void; dispose?(): void }
+						| undefined;
+					let leavePanel: (() => void) | undefined;
+					let panelGeneration = 0;
+					let panelShrink = 1;
+					const mountPanel = () => {
+						const generation = ++panelGeneration;
+						leavePanel?.();
+						embedded?.dispose?.();
+						embedded = undefined;
+						leavePanel = undefined;
+						const panel = panels.find((entry) => entry.label === tab);
+						if (!panel) return;
+						const panelContext = {
+							...ctx,
+							ui: {
+								...ctx.ui,
+								custom: async (
+									factory: (
+										tui: unknown,
+										theme: unknown,
+										kb: unknown,
+										done: (value: unknown) => void,
+									) => NonNullable<typeof embedded>,
+								) => {
+									if (generation !== panelGeneration) return null;
+									return new Promise<unknown>((resolve) => {
+										leavePanel = () => resolve(null);
+										// The /pix tab row takes one line; render() shrinks the panel's terminal until both fit.
+										const panelTui = {
+											...tui,
+											terminal: {
+												...tui.terminal,
+												get rows() {
+													return Math.max(
+														1,
+														(tui.terminal?.rows ?? process.stdout.rows ?? 24) - panelShrink,
+													);
+												},
+											},
+										};
+										embedded = factory(panelTui, theme, kb, (value: unknown) => {
+											if (generation !== panelGeneration) return resolve(null);
+											if (value == null) {
+												embedded = undefined;
+												done(null);
+											}
+											resolve(value);
+										});
+										tui.requestRender();
+									});
+								},
+							},
+						} as unknown as ExtensionCommandContext;
+						void panel.open(panelContext).catch((error) => {
+							if (generation === panelGeneration)
+								ui.notify(
+									`pix: ${panel.label}: ${error instanceof Error ? error.message : String(error)}`,
+									"error",
+								);
+						});
+					};
 					let binaries: ReturnType<typeof createBinariesTab> | undefined;
 					const binariesTab = () => {
 						binaries ??= createBinariesTab({
@@ -283,25 +448,44 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 						return binaries;
 					};
 					const tabBar = () =>
-						TABS.map((name) =>
-							name === tab
-								? theme.fg("accent", theme.bold(`  ${name}  `))
-								: theme.fg("muted", `  ${name}  `),
-						).join(theme.fg("muted", "│"));
+						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";
+						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();
+						mountPanel();
 					};
 
-					const rows = () =>
-						SETTINGS.filter((r) => (r.section === "Footer") === (tab === "Footer"));
+					// `/pix <tab>` opens straight into that tab.
+					if (tab === "Binaries") binariesTab().refresh();
+					mountPanel();
+
+					const rows = (): Row[] => {
+						const list = settings.filter((r) => (r.section === "Footer") === (tab === "Footer"));
+						return tab === "Settings" && themeRow ? [themeRow, ...list] : list;
+					};
 					const cycle = (direction: -1 | 1) => {
 						const row = rows()[selected];
 						if (!row) return;
+						if (isThemeRow(row)) {
+							const cur = row.values.indexOf(row.current());
+							const start = cur === -1 && direction === -1 ? 0 : cur;
+							const next = row.values[(start + direction + row.values.length) % row.values.length];
+							const result = next ? ctx.ui.setTheme(next) : undefined;
+							if (result && !result.success)
+								ui.notify(`pix: theme ${next}: ${result.error ?? "failed"}`, "error");
+							tui.requestRender();
+							return;
+						}
 						// Functional updater: the runtime queue serializes writes, and the
 						// callback sees the latest committed value — so rapid presses each
 						// advance exactly one step instead of collapsing on a stale snapshot.
@@ -370,6 +554,26 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 								maxBodyOffset = result.maxBodyOffset;
 								return result.lines;
 							}
+							if (!TABS.some((name) => name === tab)) {
+								if (embedded) {
+									let lines = embedded.render(width);
+									// Keep the composite inside the same budget as built-in tabs.
+									for (let tries = 0; lines.length + 1 > frame.maxHeight && tries < 8; tries++) {
+										panelShrink += lines.length + 1 - frame.maxHeight;
+										lines = embedded.render(width);
+									}
+									const panelWidth = visibleWidth(lines[0] ?? "");
+									lines.splice(1, 0, ...frameRows(panelWidth, [tabBar()], frame).slice(1, -1));
+									return lines;
+								}
+								return frameModal({
+									...frame,
+									header: [tabBar(), ""],
+									body: [theme.fg("dim", `  Loading ${tab} settings…`)],
+									footer: ["", tabGuide + guideSep + guide("esc", "close")],
+									bodyOffset: 0,
+								}).lines;
+							}
 							const settings = rows();
 							const labelW = Math.max(...settings.map((r) => r.label.length));
 							const body: string[] = [];
@@ -386,8 +590,8 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 								const sel = i === selected;
 								const cursor = sel ? theme.fg("accent", "→") : " ";
 								const label = theme.fg(sel ? "accent" : "text", row.label.padEnd(labelW));
-								const value = row.read(runtime.get(row.handle));
-								const isDefault = value === row.read(row.handle.defaults);
+								const value = isThemeRow(row) ? row.current() : row.read(runtime.get(row.handle));
+								const isDefault = isThemeRow(row) || value === row.read(row.handle.defaults);
 								settingBodyLines[i] = body.length;
 								body.push(`${cursor} ${label}  ${theme.fg(isDefault ? "dim" : "success", value)}`);
 							}
@@ -415,6 +619,11 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 							maxBodyOffset = result.maxBodyOffset;
 							return result.lines;
 						},
+						dispose: () => {
+							panelGeneration++;
+							leavePanel?.();
+							embedded?.dispose?.();
+						},
 						invalidate: () => {},
 						handleInput: (data: string) => {
 							if (tab === "Binaries" && binariesTab().editing) {
@@ -435,6 +644,10 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 								tui.requestRender();
 								return;
 							}
+							if (!TABS.some((name) => name === tab) && embedded) {
+								embedded.handleInput(data);
+								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);