@xynogen/pix-runtime 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# pix-runtime
+
+Pix's small shared runtime layer. It owns the process-wide config contract:
+`~/.pi/agent/pix.json` as a single, sparse, versioned user config file, plus the
+lifecycle that keeps it coherent.
+
+It is **not** an aggregator, renderer, model-data package, or service locator.
+See `DESIGN.md` for the full contract.
+
+## What it does
+
+- Versioned, sparse `pix.json` (`$version: 1`) — defaults resolve in code.
+- Typed sections: `collapse`, `pretty`, `optimizer`, `gate`.
+- Atomic writes behind a serialized in-process queue and a short-lived
+  cross-process lock. A failed write leaves the old file intact.
+- Immutable, deeply frozen config snapshots with a monotonic revision.
+- Typed, path-filtered change events.
+- One-time migration of legacy unversioned config and the `optimizer.json`
+  sidecar.
+- The `/pix` shared-settings command.
+
+## Install
+
+```bash
+pi install npm:@xynogen/pix-runtime
+```
+
+Standalone-installable: importing an accessor lazily creates the singleton even
+without the extension factory. Installed via `pix-core` it registers `/pix` and
+session hooks once.
+
+## Usage
+
+```ts
+import { config, updateConfig, onConfigChange } from "@xynogen/pix-runtime/config";
+import { prettySection } from "@xynogen/pix-runtime/sections";
+
+const icons = config(prettySection).icons;         // synchronous read
+await updateConfig(prettySection, { icons: "ascii" });
+const off = onConfigChange((c) => render(), { paths: ["pretty.icons"] });
+```
+
+Collapse policy helpers:
+
+```ts
+import { shouldCollapse, collapseDelayMs } from "@xynogen/pix-runtime/collapse";
+```
+
+## Testing
+
+```ts
+import { createIsolatedRuntime } from "@xynogen/pix-runtime/testing";
+
+const { runtime, cleanup } = createIsolatedRuntime();
+// ... exercise runtime against a temp agent dir ...
+cleanup();
+```

package/package.json

@@ -0,0 +1,52 @@
+{
+	"name": "@xynogen/pix-runtime",
+	"version": "0.1.0",
+	"description": "Pix shared runtime — versioned pix.json config, atomic persistence, typed change events",
+	"type": "module",
+	"main": "src/index.ts",
+	"scripts": {
+		"test": "bun test"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"DESIGN.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"src/extension.ts"
+		]
+	},
+	"exports": {
+		".": "./src/index.ts",
+		"./config": "./src/runtime.ts",
+		"./sections": "./src/sections/index.ts",
+		"./collapse": "./src/collapse.ts",
+		"./testing": "./src/testing.ts"
+	},
+	"keywords": [
+		"pi",
+		"pi-package",
+		"pi-extension",
+		"config",
+		"runtime"
+	],
+	"author": "xynogen",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/xynogen/pix-mono.git",
+		"directory": "packages/pix-runtime"
+	},
+	"homepage": "https://github.com/xynogen/pix-mono/tree/main/packages/pix-runtime#readme",
+	"bugs": {
+		"url": "https://github.com/xynogen/pix-mono/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*"
+	}
+}

package/src/collapse.ts

@@ -0,0 +1,20 @@
+/**
+ * collapse.ts — pure collapse *policy* only. UI timers/state machines live in
+ * the renderer (pix-pretty), which consumes these helpers.
+ */
+
+import { pixRuntime } from "./runtime.ts";
+import { collapseSection } from "./sections/collapse.ts";
+
+/** Should a tool's output card auto-collapse? Per-tool override wins. */
+export function shouldCollapse(toolName: string): boolean {
+	const c = pixRuntime().get(collapseSection);
+	const perTool = c.tools[toolName];
+	if (typeof perTool === "boolean") return perTool;
+	return c.enabled;
+}
+
+/** Collapse delay in milliseconds. */
+export function collapseDelayMs(): number {
+	return pixRuntime().get(collapseSection).delaySec * 1000;
+}

package/src/diagnostics.ts

@@ -0,0 +1,26 @@
+import type { ConfigDiagnostic } from "./schema.ts";
+
+/** Bounded ring buffer of config diagnostics surfaced through `/pix`. */
+export class DiagnosticSink {
+	private readonly items: ConfigDiagnostic[] = [];
+
+	constructor(private readonly limit = 100) {}
+
+	push(d: Omit<ConfigDiagnostic, "at">): void {
+		this.items.push({ ...d, at: Date.now() });
+		if (this.items.length > this.limit) this.items.splice(0, this.items.length - this.limit);
+	}
+
+	all(): readonly ConfigDiagnostic[] {
+		return [...this.items];
+	}
+
+	/** Diagnostics newer than a timestamp — used for session-start aggregation. */
+	since(ts: number): readonly ConfigDiagnostic[] {
+		return this.items.filter((d) => d.at >= ts);
+	}
+
+	clear(): void {
+		this.items.length = 0;
+	}
+}

package/src/events.ts

@@ -0,0 +1,79 @@
+import { CONFIG_FORMAT_VERSION, deepFreeze, pathMatches, type SectionHandle } from "./schema.ts";
+
+// ── Snapshot ─────────────────────────────────────────────────────────────────
+
+export interface ConfigSnapshot {
+	readonly revision: number;
+	readonly formatVersion: typeof CONFIG_FORMAT_VERSION;
+	readonly loadedAt: number;
+	get<K extends string, T>(section: SectionHandle<K, T>): Readonly<T>;
+}
+
+/** Immutable snapshot backed by a frozen map of resolved section values. */
+export function makeSnapshot(revision: number, values: Map<string, unknown>): ConfigSnapshot {
+	const frozen = new Map<string, unknown>();
+	for (const [key, value] of values) frozen.set(key, deepFreeze(value));
+	const loadedAt = Date.now();
+	return {
+		revision,
+		formatVersion: CONFIG_FORMAT_VERSION,
+		loadedAt,
+		get<K extends string, T>(section: SectionHandle<K, T>): Readonly<T> {
+			return (frozen.get(section.key) ?? section.defaults) as Readonly<T>;
+		},
+	};
+}
+
+// ── Change events ────────────────────────────────────────────────────────────
+
+export type ConfigChangeOrigin = "init" | "command" | "api" | "reload" | "migration";
+
+export interface ConfigChange {
+	readonly revision: number;
+	readonly origin: ConfigChangeOrigin;
+	readonly source?: string;
+	readonly changed: readonly string[];
+	readonly previous?: ConfigSnapshot;
+	readonly current: ConfigSnapshot;
+	readonly persisted: boolean;
+}
+
+export type ConfigListener = (change: ConfigChange) => void;
+
+export interface SubscribeOptions {
+	paths?: readonly string[];
+	immediate?: boolean;
+}
+
+interface Registration {
+	listener: ConfigListener;
+	paths?: readonly string[];
+}
+
+/** In-process listener registry with path filtering and safe dispatch. */
+export class EventBus {
+	private readonly regs = new Set<Registration>();
+
+	subscribe(reg: Registration): () => void {
+		this.regs.add(reg);
+		return () => this.regs.delete(reg);
+	}
+
+	/** Dispatch in registration order over a copied list (unsubscribe-safe). */
+	emit(change: ConfigChange, onError: (err: unknown) => void): void {
+		for (const reg of [...this.regs]) {
+			if (reg.paths && !change.changed.some((c) => pathMatches(c, reg.paths as string[]))) {
+				continue;
+			}
+			try {
+				reg.listener(change);
+			} catch (err) {
+				onError(err);
+			}
+		}
+	}
+
+	clear(): void {
+		this.regs.clear();
+	}
+}

package/src/extension.ts

@@ -0,0 +1,44 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { once } from "./once.ts";
+import { registerPixCommand } from "./pix-command.ts";
+import { pixRuntime } from "./runtime.ts";
+
+/**
+ * Runtime extension entry. Idempotent per `pi` instance: registers `/pix` and
+ * session lifecycle hooks, and drives init/reload/flush of the config singleton.
+ *
+ * Standalone-installable: importing a runtime accessor lazily creates the
+ * singleton even if this factory never runs, so the factory only owns the
+ * command and lifecycle wiring.
+ */
+export default function registerRuntime(pi: ExtensionAPI): void {
+	once(pi, "pix-runtime", () => {
+		const runtime = pixRuntime();
+
+		registerPixCommand(pi, runtime);
+
+		let initialized = false;
+		pi.on("session_start", async () => {
+			if (initialized) {
+				await runtime.reload({ origin: "reload", source: "session_start" });
+			} else {
+				initialized = true;
+				await runtime.init({ origin: "init", source: "session_start" });
+			}
+			surfaceDiagnostics(pi, runtime);
+		});
+
+		pi.on("session_shutdown", async () => {
+			await runtime.flush();
+		});
+	});
+}
+
+/** Aggregate error-severity diagnostics into at most one notification. */
+function surfaceDiagnostics(pi: ExtensionAPI, runtime: ReturnType<typeof pixRuntime>): void {
+	const errors = runtime.diagnostics().filter((d) => d.severity === "error");
+	if (errors.length === 0) return;
+	const ui = (pi as unknown as { ui?: { notify?(m: string, t?: string): void } }).ui;
+	const msg = `pix config: ${errors.length} issue(s) — see ${runtime.path}`;
+	ui?.notify?.(msg, "warning");
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+export { collapseDelayMs, shouldCollapse } from "./collapse.ts";
+export type {
+	ConfigChange,
+	ConfigChangeOrigin,
+	ConfigListener,
+	ConfigSnapshot,
+	SubscribeOptions,
+} from "./events.ts";
+export { default } from "./extension.ts";
+export {
+	config,
+	createRuntime,
+	type InitOptions,
+	onConfigChange,
+	type PixRuntime,
+	pixRuntime,
+	type ReloadOptions,
+	type RuntimeAdapters,
+	reloadConfig,
+	type UpdateOptions,
+	updateConfig,
+} from "./runtime.ts";
+export type {
+	ConfigDiagnostic,
+	ConfigDiagnosticCode,
+	DeepPartial,
+	SectionHandle,
+} from "./schema.ts";
+export { CONFIG_FORMAT_VERSION, defineSection } from "./schema.ts";
+export {
+	builtinSections,
+	type CollapseConfig,
+	collapseSection,
+	type GateConfig,
+	type GateRuleConfig,
+	gateSection,
+	type OptimizerConfig,
+	optimizerSection,
+	type PrettyConfig,
+	prettySection,
+} from "./sections/index.ts";

package/src/migrations.ts

@@ -0,0 +1,142 @@
+/**
+ * migrations.ts — ordered, idempotent, pure migrations over a RawDocument plus
+ * the legacy `optimizer.json` sidecar importer.
+ *
+ * ponytail: the DESIGN.md staged optimizer mirror (keep optimizer.json as a
+ * read/write mirror for a full release train) is simplified here to a one-time
+ * import + archive. That is safe for a greenfield 0.1.0 where no published
+ * consumer delegates to runtime yet. Upgrade path: reinstate the mirror window
+ * in section 8.2 before any consumer ships runtime-backed optimizer writes.
+ */
+
+import { existsSync, readFileSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_FORMAT_VERSION, isObj, type ParseContext, type RawDocument } from "./schema.ts";
+
+const LEGACY_PRETTY_COLOR_KEYS = ["theme", "syntaxTheme", "diffColors"] as const;
+const LEGACY_DIFF_COLOR_KEYS = [
+	"bgAdd",
+	"bgDel",
+	"bgAddHighlight",
+	"bgDelHighlight",
+	"bgGutterAdd",
+	"bgGutterDel",
+	"fgAdd",
+	"fgDel",
+] as const;
+
+const OPTIMIZER_KEYS = ["caveman", "rtk", "toon", "ponytail"] as const;
+
+export interface MigrationResult {
+	document: RawDocument;
+	changed: boolean;
+}
+
+/** Detected source format of a raw document. */
+export function detectVersion(doc: RawDocument): number | "unversioned" {
+	const v = doc.$version;
+	return typeof v === "number" && Number.isFinite(v) ? v : "unversioned";
+}
+
+/**
+ * Migrate a raw document up to the current format version. Pure: returns a new
+ * document and whether anything changed. Unknown keys are preserved.
+ */
+export function migrate(input: RawDocument, ctx: ParseContext): MigrationResult {
+	const version = detectVersion(input);
+
+	if (typeof version === "number" && version > CONFIG_FORMAT_VERSION) {
+		// Future version: caller enters read-only mode. Do not mutate.
+		ctx.diagnostic({
+			code: "UNSUPPORTED_CONFIG_VERSION",
+			severity: "error",
+			message: `config $version ${version} is newer than supported ${CONFIG_FORMAT_VERSION}`,
+		});
+		return { document: input, changed: false };
+	}
+
+	const doc: RawDocument = structuredClone(input);
+	let changed = false;
+
+	// Remove legacy color keys — active themes own all colors now.
+	if (isObj(doc.pretty)) {
+		const pretty = { ...doc.pretty };
+		for (const key of LEGACY_PRETTY_COLOR_KEYS) {
+			if (key in pretty) {
+				delete pretty[key];
+				changed = true;
+			}
+		}
+		if (isObj(pretty.diff)) {
+			const diff = { ...pretty.diff };
+			for (const key of LEGACY_DIFF_COLOR_KEYS) {
+				if (key in diff) {
+					delete diff[key];
+					changed = true;
+				}
+			}
+			pretty.diff = diff;
+		}
+		doc.pretty = pretty;
+	}
+
+	if (doc.$version !== CONFIG_FORMAT_VERSION) {
+		doc.$version = CONFIG_FORMAT_VERSION;
+		changed = true;
+	}
+
+	return { document: doc, changed };
+}
+
+/**
+ * Import `optimizer.json` sidecar into `doc.optimizer` exactly once. Canonical
+ * `pix.json.optimizer.<key>` wins conflicts. Returns whether the document
+ * changed and whether the sidecar should be archived after a successful write.
+ */
+export function importOptimizerSidecar(
+	doc: RawDocument,
+	agentDir: string,
+	ctx: ParseContext,
+): { changed: boolean; archive?: () => void } {
+	const sidecarPath = join(agentDir, "optimizer.json");
+	if (!existsSync(sidecarPath)) return { changed: false };
+
+	let raw: Record<string, unknown>;
+	try {
+		const parsed = JSON.parse(readFileSync(sidecarPath, "utf-8")) as unknown;
+		if (!isObj(parsed)) throw new Error("not an object");
+		raw = parsed;
+	} catch (err) {
+		ctx.diagnostic({
+			code: "MIGRATION_FAILED",
+			severity: "warning",
+			path: "optimizer.json",
+			message: "malformed optimizer sidecar left untouched",
+			cause: err,
+		});
+		return { changed: false };
+	}
+
+	const existing = isObj(doc.optimizer) ? { ...doc.optimizer } : {};
+	let changed = false;
+	for (const key of OPTIMIZER_KEYS) {
+		const value = raw[key];
+		if (typeof value === "string" && !(key in existing)) {
+			existing[key] = value;
+			changed = true;
+		}
+	}
+	if (changed) doc.optimizer = existing;
+
+	const archive = () => {
+		let target = `${sidecarPath}.migrated-v1`;
+		if (existsSync(target)) target = `${target}.${Date.now()}`;
+		try {
+			renameSync(sidecarPath, target);
+		} catch {
+			// A competing process may have moved it — ENOENT is benign.
+		}
+	};
+
+	return { changed, archive };
+}

package/src/once.ts

@@ -0,0 +1,25 @@
+/**
+ * Per-instance idempotency guard for extension activation.
+ *
+ * pix-core (the meta-package) invokes this package's factory, and a standalone
+ * install makes Pi invoke it again — sometimes against the SAME `pi`. We must
+ * dedupe that. But Pi rebuilds the extension runtime on /new, /resume, /fork,
+ * and /reload, handing the factory a BRAND-NEW `pi`; that must re-register.
+ *
+ * Keying the registry on the `pi` instance satisfies both: same instance =>
+ * 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 {
+	const g = globalThis as { __pixOnce?: WeakMap<object, Set<string>> };
+	if (!g.__pixOnce) g.__pixOnce = new WeakMap<object, Set<string>>();
+	const registry = g.__pixOnce;
+	let loaded = registry.get(pi);
+	if (!loaded) {
+		loaded = new Set<string>();
+		registry.set(pi, loaded);
+	}
+	if (loaded.has(key)) return;
+	loaded.add(key);
+	fn();
+}

package/src/persistence.ts

@@ -0,0 +1,166 @@
+/**
+ * persistence.ts — read, sparse serialize, atomic write, and a serialized
+ * in-process write queue with a short-lived cross-process lock.
+ *
+ * A failed lock/write/rename leaves the old file intact and throws a typed
+ * error; the caller keeps the previous snapshot.
+ */
+
+import {
+	closeSync,
+	existsSync,
+	mkdirSync,
+	openSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	statSync,
+	writeFileSync,
+	writeSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import type { RawDocument } from "./schema.ts";
+
+export class ConfigWriteError extends Error {
+	constructor(
+		message: string,
+		readonly cause?: unknown,
+	) {
+		super(message);
+		this.name = "ConfigWriteError";
+	}
+}
+
+export class ConfigLockError extends ConfigWriteError {
+	constructor(message: string, cause?: unknown) {
+		super(message, cause);
+		this.name = "ConfigLockError";
+	}
+}
+
+/** 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;
+	ensureDir(): void;
+}
+
+const LOCK_STALE_MS = 30_000;
+const LOCK_RETRY_MS = 25;
+const LOCK_MAX_RETRIES = 200; // ~5s budget
+
+/** Node/Bun filesystem storage rooted at `<agentDir>/pix.json`. */
+export class FileStorage implements StorageAdapter {
+	readonly path: string;
+	private readonly lockPath: string;
+
+	constructor(agentDir: string) {
+		this.path = join(agentDir, "pix.json");
+		this.lockPath = `${this.path}.lock`;
+	}
+
+	ensureDir(): void {
+		mkdirSync(dirname(this.path), { recursive: true });
+	}
+
+	readRaw(): string | undefined {
+		try {
+			if (!existsSync(this.path)) return undefined;
+			return readFileSync(this.path, "utf-8");
+		} catch (err) {
+			throw new ConfigWriteError(`read failed: ${this.path}`, err);
+		}
+	}
+
+	private acquireLock(): void {
+		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;
+				}
+				Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_RETRY_MS);
+			}
+		}
+		throw new ConfigLockError(`could not acquire ${this.lockPath}`);
+	}
+
+	private releaseLock(): void {
+		try {
+			rmSync(this.lockPath, { force: true });
+		} catch {
+			/* best effort */
+		}
+	}
+
+	writeAtomic(contents: string): void {
+		this.ensureDir();
+		this.acquireLock();
+		const tmp = `${this.path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+		try {
+			writeFileSync(tmp, contents, { mode: 0o600 });
+			renameSync(tmp, this.path);
+		} catch (err) {
+			try {
+				rmSync(tmp, { force: true });
+			} catch {
+				/* ignore */
+			}
+			throw new ConfigWriteError(`write failed: ${this.path}`, err);
+		} finally {
+			this.releaseLock();
+		}
+	}
+}
+
+// ── In-process serialized write queue ────────────────────────────────────────
+
+/**
+ * Serializes async transactions so concurrent updates in one process never
+ * interleave reads and writes. Each task runs after the previous settles.
+ */
+export class WriteQueue {
+	private tail: Promise<unknown> = Promise.resolve();
+
+	run<T>(task: () => Promise<T>): Promise<T> {
+		const next = this.tail.then(task, task);
+		// Keep the chain alive even if a task rejects.
+		this.tail = next.then(
+			() => undefined,
+			() => undefined,
+		);
+		return next;
+	}
+}
+
+// ── Raw document read/parse ──────────────────────────────────────────────────
+
+export function parseRawDocument(text: string | undefined): RawDocument {
+	if (!text) return {};
+	try {
+		const parsed = JSON.parse(text) as unknown;
+		return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+			? (parsed as RawDocument)
+			: {};
+	} catch {
+		return {};
+	}
+}
+
+export function serializeRawDocument(doc: RawDocument): string {
+	return `${JSON.stringify(doc, null, 2)}\n`;
+}