@xynogen/pix-runtime 0.10.2 → 0.13.0

package/src/os.ts

@@ -0,0 +1,250 @@
+/**
+ * os.ts — jobs that need a different program on each OS, behind one call.
+ *
+ * Packages ask for the job ("open this URL", "read the clipboard image"); this
+ * module picks the program for the host and runs it through `exec.ts`, so the
+ * binary still comes from binary.json / `<agentDir>/bin` / known dirs / PATH.
+ */
+
+import { randomUUID } from "node:crypto";
+import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveTool } from "./binaries/resolve.ts";
+import { quoteForCmd, runTool, runToolSync } from "./exec.ts";
+import { tempDir } from "./paths.ts";
+import { currentPlatform, type HostPlatform } from "./platform.ts";
+
+export interface OsOptions {
+	env?: NodeJS.ProcessEnv;
+	host?: HostPlatform;
+}
+
+// ── Open a URL or path ──────────────────────────────────────────────────────
+
+export interface OpenOptions extends OsOptions {
+	/** Browser/app name or path. Default: the OS default handler. */
+	app?: string;
+	timeoutMs?: number;
+}
+
+/** Program + args that open `target` on `host` (exported for tests). */
+export function openCommand(
+	target: string,
+	host: HostPlatform,
+	app?: string,
+): { name: string; args: string[]; verbatim?: boolean } {
+	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.
+		const parts = ["start", '""', ...(app ? [quoteForCmd(app)] : []), quoteForCmd(target)];
+		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] };
+	}
+	return { name: app ?? "xdg-open", args: [target] };
+}
+
+/**
+ * Open a URL or file with the OS default handler (or `app`). Throws a
+ * BinaryMissingError with an install hint when the opener is missing, or an
+ * Error with the opener's stderr when it exits non-zero.
+ */
+export async function openTarget(target: string, opts: OpenOptions = {}): Promise<void> {
+	const host = opts.host ?? currentPlatform();
+	let cmd = openCommand(target, host, opts.app);
+	if (cmd.name === "wslview" && !resolveTool("wslview", opts))
+		cmd = openCommand(target, { ...host, wsl: false });
+	const result = await runTool(cmd.name, cmd.args, {
+		env: opts.env,
+		host,
+		timeoutMs: opts.timeoutMs ?? 15_000,
+		verbatim: cmd.verbatim,
+	});
+	if (result.code !== 0)
+		throw new Error(result.stderr.trim() || `${cmd.name} exited with code ${result.code}`);
+}
+
+// ── Git ─────────────────────────────────────────────────────────────────────────
+
+export interface GitOptions extends OsOptions {
+	cwd: string;
+	timeoutMs?: number;
+	signal?: AbortSignal;
+	maxBuffer?: number;
+}
+
+/**
+ * `git args…` in `cwd`: stdout on exit 0, null on any git failure (not a
+ * repo, timeout, abort, or output cut at `maxBuffer`). A missing git binary rejects with BinaryMissingError
+ * so the caller can surface the install hint once (pix-pretty warnBinaryMissing).
+ */
+export async function runGit(args: readonly string[], opts: GitOptions): Promise<string | null> {
+	const r = await runTool("git", args, {
+		cwd: opts.cwd,
+		env: opts.env,
+		host: opts.host,
+		timeoutMs: opts.timeoutMs ?? 5_000,
+		signal: opts.signal,
+		maxBuffer: opts.maxBuffer,
+	}).catch((err: unknown) => {
+		if (err instanceof Error && err.name === "BinaryMissingError") throw err;
+		return null;
+	});
+	return r && r.code === 0 && !r.truncated ? r.stdout : null;
+}
+
+// ── Clipboard image ─────────────────────────────────────────────────────────
+
+const LIST_TIMEOUT_MS = 1000;
+const READ_TIMEOUT_MS = 3000;
+const POWERSHELL_TIMEOUT_MS = 5000;
+
+/** Preference order mirrors Pi: PNG first, then other lossless/animated formats. */
+const SUPPORTED_MIME = ["image/png", "image/jpeg", "image/webp", "image/gif"];
+
+export interface ClipboardImage {
+	bytes: Buffer;
+	mimeType: string;
+}
+
+function baseMime(mimeType: string): string {
+	return mimeType.split(";")[0]?.trim().toLowerCase() ?? mimeType.toLowerCase();
+}
+
+export function pickPreferredMime(types: readonly string[]): string | null {
+	const normalized = types
+		.map((t) => t.trim())
+		.filter(Boolean)
+		.map((t) => ({ raw: t, base: baseMime(t) }));
+	for (const preferred of SUPPORTED_MIME) {
+		const match = normalized.find((t) => t.base === preferred);
+		if (match) return match.raw;
+	}
+	return normalized.find((t) => t.base.startsWith("image/"))?.raw ?? 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 {
+	if (!resolveTool(name, opts)) return null;
+	try {
+		const r = runToolSync(name, args, { env: opts.env, host: opts.host, timeoutMs });
+		return r.code === 0 ? r.stdoutBytes : null;
+	} catch {
+		return null;
+	}
+}
+
+function lines(buf: Buffer | null): string[] {
+	return buf
+		? buf
+				.toString("utf-8")
+				.split(/\r?\n/)
+				.map((t) => t.trim())
+				.filter(Boolean)
+		: [];
+}
+
+function viaWlPaste(opts: OsOptions): ClipboardImage | null {
+	const selected = pickPreferredMime(
+		lines(probe("wl-paste", ["--list-types"], LIST_TIMEOUT_MS, opts)),
+	);
+	if (!selected) return null;
+	const data = probe("wl-paste", ["--type", selected, "--no-newline"], READ_TIMEOUT_MS, opts);
+	return data?.length ? { bytes: data, mimeType: baseMime(selected) } : null;
+}
+
+function viaXclip(opts: OsOptions): ClipboardImage | null {
+	const targets = lines(
+		probe("xclip", ["-selection", "clipboard", "-t", "TARGETS", "-o"], LIST_TIMEOUT_MS, opts),
+	);
+	const preferred = targets.length > 0 ? pickPreferredMime(targets) : null;
+	for (const mimeType of preferred ? [preferred, ...SUPPORTED_MIME] : SUPPORTED_MIME) {
+		const data = probe(
+			"xclip",
+			["-selection", "clipboard", "-t", mimeType, "-o"],
+			READ_TIMEOUT_MS,
+			opts,
+		);
+		if (data?.length) return { bytes: data, mimeType: baseMime(mimeType) };
+	}
+	return null;
+}
+
+/** Windows clipboard via PowerShell — native Windows, or from WSL via powershell.exe. */
+function viaPowerShell(host: HostPlatform, opts: OsOptions): ClipboardImage | null {
+	const tmpFile = join(tempDir(), `pix-clip-${randomUUID()}.png`);
+	try {
+		const winPath =
+			host.os === "win32"
+				? tmpFile
+				: lines(probe("wslpath", ["-w", tmpFile], LIST_TIMEOUT_MS, opts))[0];
+		if (!winPath) return null;
+		const script = [
+			"Add-Type -AssemblyName System.Windows.Forms",
+			"Add-Type -AssemblyName System.Drawing",
+			`$path = '${winPath.split("'").join("''")}'`,
+			"$img = [System.Windows.Forms.Clipboard]::GetImage()",
+			"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);
+		if (out?.toString("utf-8").trim() !== "ok") return null;
+		const bytes = readFileSync(tmpFile);
+		return bytes.length ? { bytes, mimeType: "image/png" } : null;
+	} catch {
+		return null;
+	} finally {
+		try {
+			unlinkSync(tmpFile);
+		} catch {
+			// best-effort cleanup
+		}
+	}
+}
+
+/**
+ * Read an image from the system clipboard, or null when there is none (or no
+ * clipboard tool). Windows and WSL use PowerShell; Linux uses wl-paste/xclip.
+ * macOS and Termux return null (no dependency-free bridge).
+ */
+export function readClipboardImage(opts: OsOptions = {}): ClipboardImage | null {
+	const host = opts.host ?? currentPlatform();
+	const env = opts.env ?? process.env;
+	if (host.os === "win32") return viaPowerShell(host, opts);
+	if (host.os !== "linux") return null;
+	const wayland = Boolean(env.WAYLAND_DISPLAY) || env.XDG_SESSION_TYPE === "wayland";
+	let image: ClipboardImage | null = null;
+	if (wayland || host.wsl) image = viaWlPaste(opts) ?? viaXclip(opts);
+	if (!image && host.wsl) image = viaPowerShell(host, opts);
+	if (!image && !wayland) image = viaXclip(opts);
+	return image;
+}
+
+/** {@link readClipboardImage}, spilled to a temp file. Returns the path or null. */
+export function readClipboardImageToFile(opts: OsOptions = {}): string | null {
+	const image = readClipboardImage(opts);
+	if (!image) return null;
+	const ext = extForMime(image.mimeType);
+	const filePath = join(tempDir(), `pix-clipboard-${randomUUID()}.${ext}`);
+	try {
+		writeFileSync(filePath, image.bytes);
+		return filePath;
+	} catch {
+		return null;
+	}
+}
+
+export function extForMime(mimeType: string): string {
+	switch (baseMime(mimeType)) {
+		case "image/jpeg":
+			return "jpg";
+		case "image/webp":
+			return "webp";
+		case "image/gif":
+			return "gif";
+		default:
+			return "png";
+	}
+}

package/src/paths.ts

@@ -0,0 +1,87 @@
+/**
+ * paths.ts — canonical Pi/pix directories, pure and env-injectable.
+ *
+ * `agentDir()` mirrors Pi's `getAgentDir()` (PI_CODING_AGENT_DIR, `~`-expanded,
+ * else `~/.pi/agent`) so code that runs outside a Pi process (CLIs, tests) and
+ * code inside it agree. `binDir()` is the same folder Pi downloads fd/rg into.
+ *
+ * Home resolution never trusts `HOME` alone: it is unset in a Windows Pi process,
+ * which silently turned `HOME ?? ""` paths into cwd-relative ones.
+ */
+
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * User home. For the live process this is exactly `os.homedir()` (what Pi's
+ * `getAgentDir` uses). An injected env (tests) is read instead: USERPROFILE on
+ * Windows, HOME elsewhere, falling back to `os.homedir()`.
+ */
+export function homeDir(
+	env: NodeJS.ProcessEnv = process.env,
+	os: NodeJS.Platform = process.platform,
+): string {
+	if (env === process.env) return homedir();
+	const fromEnv = os === "win32" ? env.USERPROFILE : env.HOME;
+	return fromEnv || homedir();
+}
+
+/** Expand a leading `~` / `~/` / `~\` against {@link homeDir}. */
+export function expandHome(path: string, env: NodeJS.ProcessEnv = process.env): string {
+	if (path === "~") return homeDir(env);
+	if (path.startsWith("~/") || path.startsWith("~\\")) return join(homeDir(env), path.slice(2));
+	return path;
+}
+
+/** Pi agent dir: `PI_CODING_AGENT_DIR` (tilde-expanded) or `~/.pi/agent`. */
+export function agentDir(env: NodeJS.ProcessEnv = process.env): string {
+	const override = env.PI_CODING_AGENT_DIR;
+	if (override) return expandHome(override, env);
+	return join(homeDir(env), ".pi", "agent");
+}
+
+/** Pi's managed binary dir (`<agentDir>/bin`), shared with Pi's fd/rg downloads. */
+export function binDir(env: NodeJS.ProcessEnv = process.env): string {
+	return join(agentDir(env), "bin");
+}
+
+/**
+ * Project config dir: `<cwd>/.pi` (Pi's project `settings.json`, `mcp.json`,
+ * `agents/`, `plans/`, `lsp.json`). With no `cwd` it returns the relative `.pi`,
+ * for paths that resolve against the process cwd or show in text.
+ */
+export function projectDir(cwd = "."): string {
+	return join(cwd, ".pi");
+}
+
+/**
+ * OS temp dir, shared with every other program. Never delete it whole, only
+ * your own entries in it. For the live process this is exactly `os.tmpdir()`.
+ * An injected env (tests) is read instead: TEMP/TMP on Windows, TMPDIR
+ * elsewhere, falling back to `os.tmpdir()`.
+ */
+export function tempDir(
+	env: NodeJS.ProcessEnv = process.env,
+	os: NodeJS.Platform = process.platform,
+): string {
+	if (env === process.env) return tmpdir();
+	const fromEnv = os === "win32" ? env.TEMP || env.TMP : env.TMPDIR;
+	return fromEnv || tmpdir();
+}
+
+/**
+ * Absolute path to a file shipped next to a module: `moduleFile(import.meta.url, "..", "SOP.md")`.
+ * Use it for package assets (SOP.md, skills/). It does not use `URL.pathname`, which gives
+ * `/C:/...` on Windows. It does not use `require.resolve("<pkg>/package.json")`, which Node
+ * rejects when `exports` omits it.
+ */
+export function moduleFile(moduleUrl: string, ...segments: string[]): string {
+	return resolve(dirname(fileURLToPath(moduleUrl)), ...segments);
+}
+
+/** Pi cache root: `$XDG_CACHE_HOME/pi` or `~/.cache/pi`. */
+export function cacheDir(env: NodeJS.ProcessEnv = process.env): string {
+	const xdg = env.XDG_CACHE_HOME;
+	return join(xdg || join(homeDir(env), ".cache"), "pi");
+}

package/src/persistence.ts

@@ -9,6 +9,7 @@
 import {
 	closeSync,
 	existsSync,
+	linkSync,
 	mkdirSync,
 	openSync,
 	readFileSync,
@@ -18,6 +19,7 @@ import {
 	writeFileSync,
 	writeSync,
 } from "node:fs";
+import { hostname } from "node:os";
 import { dirname, join } from "node:path";
 import type { RawDocument } from "./schema.ts";
 
@@ -38,19 +40,62 @@ export class ConfigLockError extends ConfigWriteError {
 	}
 }
 
+/** The config file is not valid JSON or not a JSON object. Never overwrite it. */
+export class ConfigParseError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ConfigParseError";
+	}
+}
+
 /** 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;
+	/**
+	 * Read-modify-write under the cross-process lock: `fn` gets the current file
+	 * text and returns the new contents (atomically written) or undefined (no
+	 * write). Another process cannot write between the read and the write.
+	 */
+	transact(fn: (raw: string | undefined) => string | undefined): void;
 	ensureDir(): void;
 }
 
-const LOCK_STALE_MS = 30_000;
+// A healthy holder keeps the lock for milliseconds (read + write + rename).
+// Stale must be shorter than the retry budget, or a crashed holder makes every
+// writer fail until it expires.
+const LOCK_STALE_MS = 4_000;
 const LOCK_RETRY_MS = 25;
 const LOCK_MAX_RETRIES = 200; // ~5s budget
 
+interface LockOwner {
+	pid: number;
+	host: string;
+}
+
+function parseOwner(text: string): LockOwner | undefined {
+	try {
+		const o = JSON.parse(text) as Partial<LockOwner>;
+		return typeof o.pid === "number" && typeof o.host === "string"
+			? { pid: o.pid, host: o.host }
+			: undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** True only when the owner ran on this host and its process is gone. */
+function ownerIsDead(owner: LockOwner | undefined): boolean {
+	if (!owner || owner.host !== hostname() || owner.pid === process.pid) return false;
+	try {
+		process.kill(owner.pid, 0);
+		return false;
+	} catch (err) {
+		// EPERM: the process exists under another user.
+		return (err as NodeJS.ErrnoException).code === "ESRCH";
+	}
+}
+
 /** Node/Bun filesystem storage rooted at `<agentDir>/pix.json`. */
 export class FileStorage implements StorageAdapter {
 	readonly path: string;
@@ -75,28 +120,63 @@ export class FileStorage implements StorageAdapter {
 	}
 
 	private acquireLock(): void {
+		const me = JSON.stringify({ pid: process.pid, host: hostname() } satisfies LockOwner);
 		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;
+					writeSync(fd, me);
+				} finally {
+					closeSync(fd);
 				}
-				Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_RETRY_MS);
+				return;
+			} catch (err) {
+				// Only EEXIST means "another writer holds it". EACCES/EROFS/ENOSPC will
+				// not clear by waiting, so fail at once with the real cause.
+				if ((err as NodeJS.ErrnoException).code !== "EEXIST")
+					throw new ConfigLockError(`could not create ${this.lockPath}`, err);
 			}
+			if (this.reclaimIfStale()) continue;
+			Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_RETRY_MS);
+		}
+		throw new ConfigLockError(`could not acquire ${this.lockPath} (held by another process)`);
+	}
+
+	/**
+	 * Remove the lock when its owner process is dead (same host) or it is older
+	 * than {@link LOCK_STALE_MS}. Returns true when the caller should retry now.
+	 *
+	 * The lock moves away by rename, which is atomic, so only one waiter takes a
+	 * given lock file. If that file is not the one judged stale (another waiter
+	 * already reclaimed it and a new holder wrote a fresh lock), it goes back with
+	 * linkSync, which never overwrites.
+	 * ponytail: a third writer can still lock in the few microseconds between the
+	 * rename and the link. Then the restored holder loses mutual exclusion once.
+	 * Upgrade path: an OS file lock (flock / LockFileEx) through a native addon.
+	 */
+	private reclaimIfStale(): boolean {
+		let text: string;
+		let mtimeMs: number;
+		try {
+			text = readFileSync(this.lockPath, "utf-8");
+			mtimeMs = statSync(this.lockPath).mtimeMs;
+		} catch {
+			return true; // The lock vanished between open and read: retry at once.
+		}
+		if (!ownerIsDead(parseOwner(text)) && Date.now() - mtimeMs <= LOCK_STALE_MS) return false;
+		const moved = `${this.lockPath}.stale-${process.pid}-${Math.random().toString(36).slice(2)}`;
+		try {
+			renameSync(this.lockPath, moved);
+		} catch {
+			return true; // Another waiter took it first.
 		}
-		throw new ConfigLockError(`could not acquire ${this.lockPath}`);
+		try {
+			if (readFileSync(moved, "utf-8") !== text) linkSync(moved, this.lockPath);
+		} catch {
+			// EEXIST: a newer lock exists, which is correct. Unreadable: treat as stale.
+		}
+		rmSync(moved, { force: true });
+		return true;
 	}
 
 	private releaseLock(): void {
@@ -107,9 +187,19 @@ export class FileStorage implements StorageAdapter {
 		}
 	}
 
-	writeAtomic(contents: string): void {
+	transact(fn: (raw: string | undefined) => string | undefined): void {
 		this.ensureDir();
 		this.acquireLock();
+		try {
+			const contents = fn(this.readRaw());
+			if (contents !== undefined) this.writeAtomic(contents);
+		} finally {
+			this.releaseLock();
+		}
+	}
+
+	/** Temp file + rename. The caller holds the lock. */
+	private writeAtomic(contents: string): void {
 		const tmp = `${this.path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
 		try {
 			writeFileSync(tmp, contents, { mode: 0o600 });
@@ -121,8 +211,6 @@ export class FileStorage implements StorageAdapter {
 				/* ignore */
 			}
 			throw new ConfigWriteError(`write failed: ${this.path}`, err);
-		} finally {
-			this.releaseLock();
 		}
 	}
 }
@@ -149,16 +237,22 @@ export class WriteQueue {
 
 // ── Raw document read/parse ──────────────────────────────────────────────────
 
+/**
+ * Parse the config file. Missing or empty means `{}`. Invalid JSON or a
+ * non-object throws {@link ConfigParseError}: a hand-edit typo must never be
+ * read as "all defaults" and then written back over the user's file.
+ */
 export function parseRawDocument(text: string | undefined): RawDocument {
-	if (!text) return {};
+	if (!text?.trim()) return {};
+	let parsed: unknown;
 	try {
-		const parsed = JSON.parse(text) as unknown;
-		return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-			? (parsed as RawDocument)
-			: {};
-	} catch {
-		return {};
+		parsed = JSON.parse(text);
+	} catch (err) {
+		throw new ConfigParseError(`invalid JSON: ${(err as Error).message}`);
 	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+		throw new ConfigParseError("top level is not a JSON object");
+	return parsed as RawDocument;
 }
 
 export function serializeRawDocument(doc: RawDocument): string {