@xynogen/pix-runtime 0.10.2 → 0.12.2

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);

package/src/safe-path.ts

@@ -0,0 +1,101 @@
+/**
+ * safe-path.ts — pre-flight check before a tool writes to a model-chosen path.
+ *
+ * The rules differ per OS: system dirs, path separators, and case. Callers get
+ * one call and a reason they can show to the model.
+ */
+
+import { constants as fsConstants } from "node:fs";
+import { access, lstat } from "node:fs/promises";
+import { posix, win32 } from "node:path";
+import { homeDir } from "./paths.ts";
+import { currentPlatform, type HostPlatform } from "./platform.ts";
+
+export type PathValidation = { ok: true; path: string } | { ok: false; reason: string };
+
+export interface SafePathOptions {
+	env?: NodeJS.ProcessEnv;
+	host?: HostPlatform;
+}
+
+/** Absolute prefixes that never get tool output, for this host. */
+export function sensitivePrefixes(opts: SafePathOptions = {}): string[] {
+	const host = opts.host ?? currentPlatform();
+	const env = opts.env ?? process.env;
+	const p = host.os === "win32" ? win32 : posix;
+	const home = homeDir(env, host.os);
+	const secrets = [".ssh", ".aws", ".gnupg", p.join(".config", "gh")].map((d) => p.join(home, d));
+	if (host.os !== "win32") return ["/etc", "/proc", "/sys", "/boot", ...secrets];
+	const sys = [env.SystemRoot ?? "C:\\Windows", env.ProgramFiles, env["ProgramFiles(x86)"]];
+	const appData = env.APPDATA ?? p.join(home, "AppData", "Roaming");
+	return [...sys, p.join(appData, "GitHub CLI"), ...secrets].filter((d): d is string => !!d);
+}
+
+/** True when `path` is `prefix` or inside it. Case-insensitive on Windows. */
+function isUnder(path: string, prefix: string, host: HostPlatform): boolean {
+	const p = host.os === "win32" ? win32 : posix;
+	// win32.relative already compares case-insensitively.
+	const rel = p.relative(p.resolve(prefix), p.resolve(path));
+	return rel !== ".." && !rel.startsWith(`..${p.sep}`) && !p.isAbsolute(rel);
+}
+
+/**
+ * Rejects null bytes, sensitive system locations, symlinks (target or any
+ * existing parent — Windows junctions count), existing directories, and paths
+ * with no writable existing ancestor.
+ */
+export async function validateOutputPath(
+	absPath: string,
+	opts: SafePathOptions = {},
+): Promise<PathValidation> {
+	const host = opts.host ?? currentPlatform();
+	const p = host.os === "win32" ? win32 : posix;
+	if (absPath.includes("\0")) return { ok: false, reason: "path contains a null byte" };
+	// `\\?\C:\Windows\x` and `\\.\C:\...` reach the same files as `C:\Windows\x`, but
+	// win32.relative() sees another root, so isUnder() would miss them. Normal
+	// output paths never need a device or namespace prefix.
+	if (host.os === "win32" && /^[\\/]{2}[?.][\\/]|^\\\?\?\\/.test(absPath))
+		return { ok: false, reason: `refusing a Windows device or namespace path: ${absPath}` };
+
+	for (const prefix of sensitivePrefixes({ ...opts, host })) {
+		if (isUnder(absPath, prefix, host))
+			return { ok: false, reason: `refusing to write under ${prefix}` };
+	}
+
+	// lstat does not follow symlinks. That is the point here.
+	try {
+		const st = await lstat(absPath);
+		if (st.isSymbolicLink()) return { ok: false, reason: `target is a symlink: ${absPath}` };
+		if (st.isDirectory())
+			return { ok: false, reason: `target is an existing directory: ${absPath}` };
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code !== "ENOENT")
+			return { ok: false, reason: `cannot stat target: ${(err as Error).message}` };
+	}
+
+	// Every existing ancestor must not be a symlink (stops a safe-looking dir → /etc
+	// redirect). The nearest one must be writable so mkdir -p works.
+	const parent = p.dirname(absPath);
+	let nearest: string | null = null;
+	for (let cursor = parent; cursor !== p.dirname(cursor); cursor = p.dirname(cursor)) {
+		let st: Awaited<ReturnType<typeof lstat>>;
+		try {
+			st = await lstat(cursor);
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code === "ENOENT") continue;
+			return { ok: false, reason: `cannot stat parent: ${(err as Error).message}` };
+		}
+		if (st.isSymbolicLink()) return { ok: false, reason: `parent is a symlink: ${cursor}` };
+		if (st.isDirectory() && nearest === null) nearest = cursor;
+	}
+	if (nearest === null)
+		return { ok: false, reason: `no existing ancestor directory for ${parent}` };
+	try {
+		// ponytail: W_OK reads only the read-only attribute on Windows, not ACLs.
+		// A denied ACL still fails later at mkdir/writeFile with a clear EPERM.
+		await access(nearest, fsConstants.W_OK);
+	} catch {
+		return { ok: false, reason: `no writable ancestor directory: ${nearest}` };
+	}
+	return { ok: true, path: absPath };
+}

package/src/testing.ts

@@ -3,9 +3,9 @@
  * never touch the real agent directory or the process singleton.
  */
 
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { mkdtempSync, rmSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
+import { tempDir } from "./paths.ts";
 import { FileStorage } from "./persistence.ts";
 import { createRuntime, type PixRuntime } from "./runtime.ts";
 
@@ -16,9 +16,25 @@ export interface IsolatedRuntime {
 	cleanup(): void;
 }
 
+/**
+ * True when this process may create symlinks. Windows allows it only in Developer
+ * Mode or as admin (else EPERM). Use it to skip symlink tests: `it.skipIf(!canSymlink())`.
+ */
+export function canSymlink(): boolean {
+	const dir = mkdtempSync(join(tempDir(), "pix-symlink-probe-"));
+	try {
+		symlinkSync(dir, join(dir, "link"), "dir");
+		return true;
+	} catch {
+		return false;
+	} finally {
+		rmSync(dir, { recursive: true, force: true });
+	}
+}
+
 /** Create a runtime backed by a fresh temp directory. */
 export function createIsolatedRuntime(): IsolatedRuntime {
-	const agentDir = mkdtempSync(join(tmpdir(), "pix-runtime-"));
+	const agentDir = mkdtempSync(join(tempDir(), "pix-runtime-"));
 	const runtime = createRuntime({ agentDir, storage: new FileStorage(agentDir) });
 	return {
 		runtime,

package/src/user-shell.ts

@@ -0,0 +1,51 @@
+/**
+ * user-shell.ts — pick the shell for user `!` commands, per OS.
+ *
+ * - Windows: PowerShell (Pi resolves pwsh 7, else powershell.exe 5.1). Pi's
+ *   default is Git Bash, which is not what a Windows user types into `!`.
+ * - POSIX: $SHELL when it is not bash. zsh also needs rc + aliases: `zsh -c`
+ *   is non-interactive and resolves aliases at parse time, so we source
+ *   .zshrc and then `eval` the command to get a fresh parse boundary.
+ */
+
+import { homeDir } from "./paths.ts";
+import { currentPlatform, type HostPlatform } from "./platform.ts";
+
+export type UserShell =
+	| { kind: "powershell"; wrap(command: string): string }
+	| { kind: "posix"; shellPath: string; wrap(command: string): string };
+
+export interface UserShellOptions {
+	host?: HostPlatform;
+	shell?: string;
+	home?: string;
+}
+
+/** Guarded: `$PSStyle` exists only in PowerShell 7.2+. Strips ANSI color from output. */
+// ponytail: duplicated from pix-powershell (Package Independence). One line, keep both in sync.
+export const PLAIN_TEXT_PREAMBLE = "if ($PSStyle) { $PSStyle.OutputRendering = 'PlainText' }\n";
+
+/** Single-quote a string for POSIX shell embedding. */
+function quote(s: string): string {
+	return `'${s.replace(/'/g, "'\\''")}'`;
+}
+
+export function userShell(opts: UserShellOptions = {}): UserShell | undefined {
+	const host = opts.host ?? currentPlatform();
+	// ponytail: no opt-out back to Git Bash on Windows. Add a pix.json knob on request.
+	if (host.os === "win32") {
+		return { kind: "powershell", wrap: (command) => `${PLAIN_TEXT_PREAMBLE}${command}` };
+	}
+	const shell = "shell" in opts ? opts.shell : process.env.SHELL;
+	if (!shell) return undefined;
+	const name = shell.split("/").pop() ?? "";
+	if (name === "bash") return undefined;
+	if (name !== "zsh") return { kind: "posix", shellPath: shell, wrap: (command) => command };
+	// ponytail: only zsh gets rc wrapping. fish/nu run with shellPath alone. Add their rc logic on request.
+	const rc = quote(`${opts.home ?? homeDir()}/.zshrc`);
+	return {
+		kind: "posix",
+		shellPath: shell,
+		wrap: (command) => `. ${rc} 2>/dev/null; eval ${quote(command)}`,
+	};
+}

package/src/which.ts

@@ -16,15 +16,24 @@
 import { accessSync, constants, statSync } from "node:fs";
 import { access, stat } from "node:fs/promises";
 import { delimiter, isAbsolute, join, sep } from "node:path";
+import { currentPlatform } from "./platform.ts";
 
-const isWindows = process.platform === "win32";
+const isWindows = currentPlatform().os === "win32";
 
 /** Windows executable extensions, from `PATHEXT` with a sane fallback. */
 function pathExtensions(env: NodeJS.ProcessEnv): string[] {
 	if (!isWindows) return [""];
 	const raw = env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD";
-	// Leading "" lets an already-suffixed name (foo.exe) match as-is.
-	return ["", ...raw.split(";").filter(Boolean)];
+	// Leading "" lets an already-suffixed name (foo.exe) match as-is. Lowercased:
+	// NTFS matches either case, and the returned path should read `rtk.exe`, not
+	// `rtk.EXE`, since that is how the files are conventionally named.
+	return [
+		"",
+		...raw
+			.split(";")
+			.filter(Boolean)
+			.map((ext) => ext.toLowerCase()),
+	];
 }
 
 /** Directories to scan, from `PATH`. Windows also probes the current directory first. */
@@ -40,7 +49,15 @@ export interface FindExecutableOptions {
 }
 
 function candidatesFor(name: string, env: NodeJS.ProcessEnv): string[] {
-	const exts = pathExtensions(env);
+	let exts = pathExtensions(env);
+	// Windows cannot spawn an extensionless file (npm ships a `npm` sh script
+	// beside `npm.cmd`), so only accept the bare name when it already carries a
+	// PATHEXT extension.
+	if (isWindows) {
+		const lower = name.toLowerCase();
+		const suffixed = exts.some((ext) => ext && lower.endsWith(ext));
+		exts = suffixed ? [""] : exts.filter(Boolean);
+	}
 	const withExts = (base: string): string[] => exts.map((ext) => base + ext);
 	// A name with a separator (or absolute) is a direct path — do not scan PATH.
 	if (isAbsolute(name) || name.includes(sep) || (isWindows && name.includes("/"))) {