@xynogen/pix-runtime 0.1.0

package/src/pix-command.ts

@@ -0,0 +1,188 @@
+/**
+ * pix-command.ts — the `/pix` command: unified settings overlay for pix.json.
+ *
+ * Runtime owns this because it edits the shared document. Rows are declared
+ * here against typed sections; persistence goes through `runtime.update()`.
+ * Headless hosts get a notify summary instead of the overlay.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { PixRuntime } from "./runtime.ts";
+import type { DeepPartial, SectionHandle } from "./schema.ts";
+import { collapseSection } from "./sections/collapse.ts";
+import { gateSection } from "./sections/gate.ts";
+import { optimizerSection } from "./sections/optimizer.ts";
+import { prettySection } from "./sections/pretty.ts";
+
+interface SettingRow<T> {
+	section: string;
+	label: string;
+	handle: SectionHandle<string, T>;
+	values: readonly string[];
+	read: (v: T) => string;
+	patch: (value: string) => DeepPartial<T>;
+}
+
+/** Capture a row's section type, then erase it so rows can share one list. */
+function row<T>(r: SettingRow<T>): SettingRow<unknown> {
+	return r as SettingRow<unknown>;
+}
+
+const SETTINGS: SettingRow<unknown>[] = [
+	row({
+		section: "Pretty",
+		label: "icons",
+		handle: prettySection,
+		values: ["nerd", "unicode", "ascii"],
+		read: (v) => v.icons,
+		patch: (value) => ({ icons: value as "nerd" | "unicode" | "ascii" }),
+	}),
+	row({
+		section: "Pretty",
+		label: "ls style",
+		handle: prettySection,
+		values: ["grid", "tree"],
+		read: (v) => v.lsStyle,
+		patch: (value) => ({ lsStyle: value as "grid" | "tree" }),
+	}),
+	row({
+		section: "Collapse",
+		label: "enabled",
+		handle: collapseSection,
+		values: ["true", "false"],
+		read: (v) => String(v.enabled),
+		patch: (value) => ({ enabled: value === "true" }),
+	}),
+	row({
+		section: "Collapse",
+		label: "delay (sec)",
+		handle: collapseSection,
+		values: ["5", "10", "15", "20", "30", "60"],
+		read: (v) => String(v.delaySec),
+		patch: (value) => ({ delaySec: Number(value) }),
+	}),
+	row({
+		section: "Optimizer",
+		label: "caveman",
+		handle: optimizerSection,
+		values: ["off", "lite", "full", "ultra", "micro"],
+		read: (v) => v.caveman,
+		patch: (value) => ({ caveman: value as "off" | "lite" | "full" | "ultra" | "micro" }),
+	}),
+	row({
+		section: "Optimizer",
+		label: "rtk",
+		handle: optimizerSection,
+		values: ["on", "off"],
+		read: (v) => v.rtk,
+		patch: (value) => ({ rtk: value as "on" | "off" }),
+	}),
+	row({
+		section: "Gate",
+		label: "disable defaults",
+		handle: gateSection,
+		values: ["false", "true"],
+		read: (v) => String(v.disableDefaults),
+		patch: (value) => ({ disableDefaults: value === "true" }),
+	}),
+];
+
+function buildSummary(runtime: PixRuntime): string {
+	const lines = [`pix settings (${runtime.path})`, ""];
+	let lastSection = "";
+	for (const row of SETTINGS) {
+		if (row.section !== lastSection) {
+			if (lastSection) lines.push("");
+			lines.push(`[${row.section}]`);
+			lastSection = row.section;
+		}
+		const value = row.read(runtime.get(row.handle));
+		const isDefault = value === row.values[0];
+		lines.push(`  ${row.label}: ${value}${isDefault ? "" : " *"}`);
+	}
+	return lines.join("\n");
+}
+
+export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void {
+	pi.registerCommand("pix", {
+		description: "pix: open shared settings (edit pix.json)",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			const ui = ctx.ui as unknown as {
+				custom?: (f: unknown, opts?: unknown) => Promise<unknown>;
+				notify(m: string, t?: "info" | "warning" | "error"): void;
+			};
+
+			if (typeof ui.custom !== "function") {
+				ui.notify(buildSummary(runtime), "info");
+				return;
+			}
+
+			const boxW = 52;
+			await ui.custom(
+				(
+					tui: { requestRender(): void },
+					theme: {
+						fg(c: string, t: string): string;
+						bold(t: string): string;
+					},
+					_kb: unknown,
+					done: (v: null) => void,
+				) => {
+					let selected = 0;
+
+					const cycle = (direction: -1 | 1) => {
+						const row = SETTINGS[selected];
+						if (!row) return;
+						const cur = row.values.indexOf(row.read(runtime.get(row.handle)));
+						const next = (cur + direction + row.values.length) % row.values.length;
+						const val = row.values[next];
+						if (val === undefined) return;
+						void runtime.update(row.handle, row.patch(val), { origin: "command", source: "pix" });
+					};
+					const move = (direction: -1 | 1) => {
+						selected = (selected + direction + SETTINGS.length) % SETTINGS.length;
+					};
+
+					return {
+						render: () => {
+							const labelW = Math.max(...SETTINGS.map((r) => r.label.length));
+							const lines: string[] = [theme.fg("accent", theme.bold("  pix settings")), ""];
+							let lastSection = "";
+							for (let i = 0; i < SETTINGS.length; i++) {
+								const row = SETTINGS[i]!;
+								if (row.section !== lastSection) {
+									if (lastSection) lines.push("");
+									lines.push(theme.fg("dim", `  ${row.section}`));
+									lastSection = row.section;
+								}
+								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.values[0];
+								lines.push(`${cursor} ${label}  ${theme.fg(isDefault ? "dim" : "success", value)}`);
+							}
+							lines.push("");
+							lines.push(theme.fg("dim", "←→ change · ↑↓ move · esc close"));
+							return lines;
+						},
+						invalidate: () => {},
+						handleInput: (data: string) => {
+							if (data === "k" || data === "\u001b[A") move(-1);
+							else if (data === "j" || data === "\u001b[B") move(1);
+							else if (data === "h" || data === "\u001b[D") cycle(-1);
+							else if (data === "l" || data === "\u001b[C" || data === " " || data === "\r")
+								cycle(1);
+							else if (data === "\u001b" || data === "q") {
+								done(null);
+								return;
+							} else return;
+							tui.requestRender();
+						},
+					};
+				},
+				{ overlay: true, overlayOptions: { anchor: "center", width: boxW, maxHeight: "80%" } },
+			);
+		},
+	});
+}

package/src/registry.ts

@@ -0,0 +1,38 @@
+/**
+ * registry.ts — internal built-in section registry.
+ *
+ * V1 keeps registration internal: there is no public `registerSection()` until
+ * a real optional-package use case proves its lifecycle. Duplicate keys fail at
+ * construction. Unknown raw sections are preserved elsewhere (persistence), so
+ * this closed set does not block forward compatibility.
+ */
+
+import type { ConfigSection, SectionHandle } from "./schema.ts";
+import { builtinSections } from "./sections/index.ts";
+
+export class SectionRegistry {
+	private readonly byKey = new Map<string, ConfigSection<unknown>>();
+
+	constructor(handles: readonly SectionHandle<string, unknown>[] = builtinSections) {
+		for (const handle of handles) this.add(handle);
+	}
+
+	private add(handle: SectionHandle<string, unknown>): void {
+		if (this.byKey.has(handle.key)) {
+			throw new Error(`pix-runtime: duplicate section key "${handle.key}"`);
+		}
+		this.byKey.set(handle.key, handle.__section);
+	}
+
+	get(key: string): ConfigSection<unknown> | undefined {
+		return this.byKey.get(key);
+	}
+
+	all(): ConfigSection<unknown>[] {
+		return [...this.byKey.values()];
+	}
+
+	keys(): string[] {
+		return [...this.byKey.keys()];
+	}
+}

package/src/runtime.test.ts

@@ -0,0 +1,244 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { migrate } from "./migrations.ts";
+import type { StorageAdapter } from "./persistence.ts";
+import { createRuntime } from "./runtime.ts";
+import { stripDefaults } from "./schema.ts";
+import { collapseSection } from "./sections/collapse.ts";
+import { gateSection } from "./sections/gate.ts";
+import { optimizerSection } from "./sections/optimizer.ts";
+import { prettySection } from "./sections/pretty.ts";
+import { createIsolatedRuntime, type IsolatedRuntime } from "./testing.ts";
+
+let iso: IsolatedRuntime | null = null;
+function fresh(): IsolatedRuntime {
+	iso = createIsolatedRuntime();
+	return iso;
+}
+afterEach(() => {
+	iso?.cleanup();
+	iso = null;
+});
+
+function readConfig(dir: string): Record<string, unknown> {
+	const p = join(dir, "pix.json");
+	return existsSync(p) ? (JSON.parse(readFileSync(p, "utf-8")) as Record<string, unknown>) : {};
+}
+
+describe("schema and normalization", () => {
+	it("resolves defaults for a missing file", () => {
+		const { runtime } = fresh();
+		expect(runtime.get(prettySection).icons).toBe("nerd");
+		expect(runtime.get(collapseSection).enabled).toBe(true);
+		expect(runtime.get(optimizerSection).rtk).toBe("on");
+	});
+
+	it("falls back invalid fields individually and diagnoses bad gate regex", () => {
+		const { runtime, agentDir } = fresh();
+		writeFileSync(
+			join(agentDir, "pix.json"),
+			JSON.stringify({
+				pretty: { icons: "bogus", maxRenderLines: -5 },
+				gate: { extraRules: [{ pattern: "(" }, { pattern: "ok" }] },
+			}),
+		);
+		runtime.reload();
+		expect(runtime.get(prettySection).icons).toBe("nerd");
+		expect(runtime.get(prettySection).maxRenderLines).toBe(150);
+		expect(runtime.get(gateSection).extraRules).toHaveLength(1);
+		expect(runtime.diagnostics().some((d) => d.code === "INVALID_VALUE")).toBe(true);
+	});
+
+	it("returns deeply frozen snapshots", () => {
+		const { runtime } = fresh();
+		const pretty = runtime.get(prettySection) as { icons: string };
+		expect(() => {
+			pretty.icons = "ascii";
+		}).toThrow();
+	});
+
+	it("strips defaults recursively", () => {
+		const section: Record<string, unknown> = {
+			icons: "nerd",
+			diff: { splitMinWidth: 150, splitMinCodeWidth: 99 },
+		};
+		const remaining = stripDefaults(section, prettySection.defaults as Record<string, unknown>);
+		expect(remaining).toBeGreaterThan(0);
+		expect(section).toEqual({ diff: { splitMinCodeWidth: 99 } });
+	});
+});
+
+describe("persistence", () => {
+	it("writes only non-default values and preserves unknown fields", async () => {
+		const { runtime, agentDir } = fresh();
+		writeFileSync(join(agentDir, "pix.json"), JSON.stringify({ future: { x: 1 } }));
+		await runtime.init();
+		await runtime.update(prettySection, { icons: "ascii" });
+		const doc = readConfig(agentDir);
+		expect(doc.$version).toBe(1);
+		expect(doc.future).toEqual({ x: 1 });
+		expect(doc.pretty).toEqual({ icons: "ascii" });
+		expect(doc.collapse).toBeUndefined(); // all defaults → omitted
+	});
+
+	it("leaves no temp file after a successful write", async () => {
+		const { runtime, agentDir } = fresh();
+		await runtime.update(collapseSection, { delaySec: 30 });
+		const p = join(agentDir, "pix.json");
+		const dir = readFileSync(p, "utf-8");
+		expect(dir).toContain("30");
+		// no stray tmp files
+		const { readdirSync } = await import("node:fs");
+		expect(readdirSync(agentDir).some((f) => f.includes(".tmp-"))).toBe(false);
+	});
+
+	it("no-op updates neither write nor emit", async () => {
+		const { runtime } = fresh();
+		const change = await runtime.update(prettySection, { icons: "nerd" });
+		expect(change).toBeUndefined();
+	});
+
+	it("functional updater sees the latest on-disk value", async () => {
+		const { runtime, agentDir } = fresh();
+		writeFileSync(join(agentDir, "pix.json"), JSON.stringify({ collapse: { delaySec: 20 } }));
+		const change = await runtime.update(collapseSection, (c) => ({
+			...c,
+			delaySec: c.delaySec + 5,
+		}));
+		expect(change?.current.get(collapseSection).delaySec).toBe(25);
+	});
+
+	it("preserves the snapshot when a write fails", async () => {
+		const storage: StorageAdapter = {
+			path: "/virtual/pix.json",
+			readRaw: () => undefined,
+			ensureDir: () => {},
+			writeAtomic: () => {
+				throw new Error("disk full");
+			},
+		};
+		const runtime = createRuntime({ agentDir: "/virtual", storage });
+		const change = await runtime.update(prettySection, { icons: "ascii" });
+		expect(change).toBeUndefined();
+		expect(runtime.get(prettySection).icons).toBe("nerd");
+		expect(runtime.diagnostics().some((d) => d.code === "WRITE_FAILED")).toBe(true);
+	});
+
+	it("serializes concurrent updates without lost fields", async () => {
+		const { runtime, agentDir } = fresh();
+		await Promise.all([
+			runtime.update(prettySection, { icons: "ascii" }),
+			runtime.update(collapseSection, { delaySec: 30 }),
+			runtime.update(optimizerSection, { caveman: "lite" }),
+		]);
+		const doc = readConfig(agentDir);
+		expect((doc.pretty as { icons: string }).icons).toBe("ascii");
+		expect((doc.collapse as { delaySec: number }).delaySec).toBe(30);
+		expect((doc.optimizer as { caveman: string }).caveman).toBe("lite");
+	});
+});
+
+describe("migration", () => {
+	it("adds $version and strips legacy color keys", () => {
+		const { document, changed } = migrate(
+			{ pretty: { icons: "ascii", theme: "x", diff: { bgAdd: "#000", splitMinWidth: 170 } } },
+			{ diagnostic: () => {} },
+		);
+		expect(changed).toBe(true);
+		expect(document.$version).toBe(1);
+		const pretty = document.pretty as Record<string, unknown>;
+		expect(pretty.theme).toBeUndefined();
+		expect((pretty.diff as Record<string, unknown>).bgAdd).toBeUndefined();
+		expect((pretty.diff as Record<string, unknown>).splitMinWidth).toBe(170);
+	});
+
+	it("imports optimizer.json once and archives it", async () => {
+		const { runtime, agentDir } = fresh();
+		writeFileSync(
+			join(agentDir, "optimizer.json"),
+			JSON.stringify({ caveman: "ultra", rtk: "off" }),
+		);
+		await runtime.init();
+		expect(runtime.get(optimizerSection).caveman).toBe("ultra");
+		expect(runtime.get(optimizerSection).rtk).toBe("off");
+		expect(existsSync(join(agentDir, "optimizer.json"))).toBe(false);
+		expect(existsSync(join(agentDir, "optimizer.json.migrated-v1"))).toBe(true);
+	});
+
+	it("canonical optimizer value wins a sidecar conflict", async () => {
+		const { runtime, agentDir } = fresh();
+		writeFileSync(join(agentDir, "pix.json"), JSON.stringify({ optimizer: { caveman: "lite" } }));
+		writeFileSync(join(agentDir, "optimizer.json"), JSON.stringify({ caveman: "ultra" }));
+		await runtime.init();
+		expect(runtime.get(optimizerSection).caveman).toBe("lite");
+	});
+
+	it("enters read-only mode for a future version", async () => {
+		const { runtime, agentDir } = fresh();
+		writeFileSync(join(agentDir, "pix.json"), JSON.stringify({ $version: 999 }));
+		await runtime.init();
+		const change = await runtime.update(prettySection, { icons: "ascii" });
+		expect(change).toBeUndefined();
+		expect(runtime.diagnostics().some((d) => d.code === "UNSUPPORTED_CONFIG_VERSION")).toBe(true);
+	});
+});
+
+describe("events and lifecycle", () => {
+	it("emits changed paths and current snapshot", async () => {
+		const { runtime } = fresh();
+		const seen: string[][] = [];
+		runtime.subscribe((c) => seen.push([...c.changed]));
+		await runtime.update(prettySection, { icons: "ascii" });
+		expect(seen).toEqual([["pretty.icons"]]);
+	});
+
+	it("respects path filters", async () => {
+		const { runtime } = fresh();
+		let hits = 0;
+		runtime.subscribe(() => hits++, { paths: ["optimizer.*"] });
+		await runtime.update(prettySection, { icons: "ascii" });
+		expect(hits).toBe(0);
+		await runtime.update(optimizerSection, { caveman: "lite" });
+		expect(hits).toBe(1);
+	});
+
+	it("delivers an immediate snapshot to new subscribers", () => {
+		const { runtime } = fresh();
+		let got: string | undefined;
+		runtime.subscribe(
+			(c) => {
+				got = c.current.get(prettySection).icons;
+			},
+			{ immediate: true },
+		);
+		expect(got).toBe("nerd");
+	});
+
+	it("isolates listener errors", async () => {
+		const { runtime } = fresh();
+		runtime.subscribe(() => {
+			throw new Error("boom");
+		});
+		let ok = false;
+		runtime.subscribe(() => {
+			ok = true;
+		});
+		await runtime.update(prettySection, { icons: "ascii" });
+		expect(ok).toBe(true);
+		expect(runtime.diagnostics().some((d) => d.code === "LISTENER_FAILED")).toBe(true);
+	});
+
+	it("init is single-flight and idempotent", async () => {
+		const { runtime } = fresh();
+		const [a, b] = await Promise.all([runtime.init(), runtime.init()]);
+		expect(a).toBe(b);
+	});
+
+	it("reset restores defaults", async () => {
+		const { runtime } = fresh();
+		await runtime.update(prettySection, { icons: "ascii" });
+		await runtime.reset(prettySection);
+		expect(runtime.get(prettySection).icons).toBe("nerd");
+	});
+});