@xynogen/pix-runtime 0.10.2 → 0.12.2

package/src/binaries/resolve.ts

@@ -0,0 +1,199 @@
+/**
+ * resolve.ts — synchronous, network-free binary lookup.
+ *
+ * Order: binary.json user choice → `<agentDir>/bin` → known install locations
+ * (`system`, e.g. Git Bash on Windows) → PATH. A user choice that
+ * does not resolve is "broken" and never silently falls back. An invalid
+ * binary.json is "broken" for every tool: its overrides are unknown, so no
+ * automatic path may stand in for them.
+ */
+
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { binDir } from "../paths.ts";
+import { currentPlatform, type HostPlatform } from "../platform.ts";
+import { findExecutableSync } from "../which.ts";
+import {
+	BINARY_NAMES,
+	type BinaryName,
+	type BinarySpec,
+	downloadAsset,
+	hintFor,
+	specOf,
+} from "./catalog.ts";
+import { type BinaryStoreState, cachedBinaryStore, readBinaryStore, userChoice } from "./store.ts";
+
+export type ToolSource = "user" | "bin" | "system" | "path" | "download";
+export type ToolState = "ok" | "missing" | "broken" | "unsupported";
+
+export interface ResolvedTool {
+	name: string;
+	path: string;
+	source: ToolSource;
+	/** Set only right after a download. */
+	version?: string;
+}
+
+export interface ToolLookup {
+	name: string;
+	state: ToolState;
+	path?: string;
+	source?: ToolSource;
+	/** The raw binary.json value when the user set one. */
+	choice?: string;
+	/** Why the state is "broken" when binary.json itself is invalid. */
+	error?: string;
+	hint: string;
+	usedBy: readonly string[];
+	/** True when pix can download it on this host. */
+	downloadable: boolean;
+	/** Nice-to-have: a missing optional tool is not an error. */
+	optional: boolean;
+}
+
+export interface LookupOptions {
+	env?: NodeJS.ProcessEnv;
+	host?: HostPlatform;
+	/** Pre-read store (avoids re-reading per entry in listTools). */
+	store?: BinaryStoreState;
+}
+
+export class BinaryMissingError extends Error {
+	readonly tool: string;
+	readonly hint: string;
+	readonly state: ToolState;
+	constructor(tool: string, state: ToolState, hint: string, detail?: string) {
+		const what =
+			state === "broken"
+				? `${tool}: ${detail ?? "the path set in binary.json does not exist"}`
+				: state === "unsupported"
+					? `${tool} is not used on this OS (set a path in binary.json to override)`
+					: `${tool} not found`;
+		const extra = state === "broken" ? undefined : detail;
+		super([what, extra, hint && `install: ${hint}`].filter(Boolean).join(" — "));
+		this.name = "BinaryMissingError";
+		this.tool = tool;
+		this.hint = hint;
+		this.state = state;
+	}
+}
+
+function namesOf(name: string, spec: BinarySpec | undefined): readonly string[] {
+	return spec?.names ?? [name];
+}
+
+/** Look one binary up. Unknown (non-catalog) names resolve via binary.json → bin → PATH too. */
+export function lookupTool(name: string, opts: LookupOptions = {}): ToolLookup {
+	const env = opts.env ?? process.env;
+	const host = opts.host ?? currentPlatform();
+	const spec = specOf(name);
+	const store = opts.store ?? cachedBinaryStore(env);
+	const base = {
+		name,
+		hint: spec ? hintFor(spec, host) : "",
+		usedBy: spec?.usedBy ?? [],
+		downloadable: spec ? downloadAsset(spec, host) !== undefined : false,
+		optional: spec?.optional === true,
+	};
+	// A tool for another OS stays "unsupported" even when a same-named file exists
+	// here (Ubuntu ships /usr/bin/open). pix never runs it on this host.
+	const needed =
+		!spec || (spec.os.includes(host.os) && !(spec.wslOnly && host.os === "linux" && !host.wsl));
+	if (!needed) return { ...base, state: "unsupported" };
+	if (store.error)
+		return { ...base, state: "broken", error: `binary.json is invalid (${store.error})` };
+	const choice = store.choices[name] ?? undefined;
+	const pinned = userChoice(store, name, env);
+	if (pinned) {
+		const found = findExecutableSync(pinned, { env });
+		return found
+			? { ...base, state: "ok", path: found, source: "user", choice: choice ?? undefined }
+			: { ...base, state: "broken", choice: choice ?? undefined };
+	}
+	const bin = binDir(env);
+	for (const n of namesOf(name, spec)) {
+		const local = findExecutableSync(join(bin, n), { env });
+		if (local) return { ...base, state: "ok", path: local, source: "bin" };
+	}
+	for (const known of spec?.knownPaths?.(env, host) ?? []) {
+		const hit = findExecutableSync(known, { env });
+		if (hit) return { ...base, state: "ok", path: hit, source: "system" };
+	}
+	for (const n of namesOf(name, spec)) {
+		const onPath = findExecutableSync(n, { env });
+		if (onPath) return { ...base, state: "ok", path: onPath, source: "path" };
+	}
+	return { ...base, state: "missing" };
+}
+
+/** Resolved path, or undefined when missing/broken. Sync, no network. */
+export function resolveTool(
+	name: BinaryName | (string & {}),
+	opts: LookupOptions = {},
+): ResolvedTool | undefined {
+	const hit = lookupTool(name, opts);
+	return hit.state === "ok" && hit.path && hit.source
+		? { name, path: hit.path, source: hit.source }
+		: undefined;
+}
+
+/** Like {@link resolveTool} but throws {@link BinaryMissingError} with the install hint. */
+export function requireTool(
+	name: BinaryName | (string & {}),
+	opts: LookupOptions = {},
+): ResolvedTool {
+	const hit = lookupTool(name, opts);
+	if (hit.state === "ok" && hit.path && hit.source)
+		return { name, path: hit.path, source: hit.source };
+	throw new BinaryMissingError(name, hit.state, hit.hint, hit.error);
+}
+
+/** Every catalog entry plus user-added binary.json keys, sorted by name. */
+export function listTools(opts: LookupOptions = {}): ToolLookup[] {
+	const env = opts.env ?? process.env;
+	const store = opts.store ?? readBinaryStore(env);
+	const names = new Set<string>([...BINARY_NAMES, ...Object.keys(store.choices)]);
+	return [...names].sort().map((name) => lookupTool(name, { ...opts, env, store }));
+}
+
+/** First line of `<path> <versionArgs>` (default `--version`), or undefined. 2 s cap. */
+export function toolVersion(
+	name: string,
+	path: string,
+	timeoutMs = 2000,
+): Promise<string | undefined> {
+	const spec = specOf(name);
+	if (spec?.versionArgs === null) return Promise.resolve(undefined);
+	const args = spec?.versionArgs ?? ["--version"];
+	return new Promise((resolve) => {
+		let out = "";
+		let settled = false;
+		const finish = (v: string | undefined) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve(v);
+		};
+		let child: ReturnType<typeof spawn>;
+		try {
+			child = spawn(path, [...args], { stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+		} catch {
+			resolve(undefined);
+			return;
+		}
+		const timer = setTimeout(() => {
+			child.kill();
+			finish(undefined);
+		}, timeoutMs);
+		const onData = (d: Buffer) => {
+			out += d.toString();
+		};
+		child.stdout?.on("data", onData);
+		child.stderr?.on("data", onData);
+		child.on("error", () => finish(undefined));
+		child.on("close", () => {
+			const line = out.split(/\r?\n/).find((l) => l.trim());
+			finish(line ? line.trim().slice(0, 80) : undefined);
+		});
+	});
+}

package/src/binaries/store.ts

@@ -0,0 +1,149 @@
+/**
+ * store.ts — `<agentDir>/binary.json`: the user's binary choices.
+ *
+ * Holds overrides only: a string = the exact path the user wants. A missing
+ * key (or `null`) = automatic (bin/ → known dirs → PATH → download). The full
+ * catalog lives in the `/pix` Binaries tab, not in this file. pix only writes
+ * the file to apply an edit from that tab, or to drop legacy `null` padding
+ * for catalog entries. Discovered paths are never written. Keys unknown to the
+ * catalog are preserved untouched.
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomicSync } from "../atomic-write.ts";
+import { agentDir, expandHome } from "../paths.ts";
+import { BINARY_NAMES } from "./catalog.ts";
+
+export const BINARY_FILE_VERSION = 1;
+
+export type BinaryChoices = Record<string, string | null>;
+
+export interface BinaryStoreState {
+	path: string;
+	choices: BinaryChoices;
+	/** Parse error message when the file exists but is not valid JSON. */
+	error?: string;
+}
+
+export function binaryFilePath(env: NodeJS.ProcessEnv = process.env): string {
+	return join(agentDir(env), "binary.json");
+}
+
+function parseChoices(raw: unknown): BinaryChoices {
+	const out: BinaryChoices = {};
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return out;
+	for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+		if (key.startsWith("$")) continue;
+		if (value === null) out[key] = null;
+		else if (typeof value === "string" && value.trim()) out[key] = value.trim();
+	}
+	return out;
+}
+
+/** Read binary.json. Missing file → empty choices; invalid JSON → empty choices + error. */
+export function readBinaryStore(env: NodeJS.ProcessEnv = process.env): BinaryStoreState {
+	const path = binaryFilePath(env);
+	let text: string;
+	try {
+		text = readFileSync(path, "utf-8");
+	} catch {
+		return { path, choices: {} };
+	}
+	try {
+		return { path, choices: parseChoices(JSON.parse(text)) };
+	} catch (err) {
+		return { path, choices: {}, error: err instanceof Error ? err.message : String(err) };
+	}
+}
+
+function serialize(choices: BinaryChoices): string {
+	const doc: Record<string, unknown> = { $version: BINARY_FILE_VERSION };
+	for (const key of Object.keys(choices).sort()) doc[key] = choices[key] ?? null;
+	return `${JSON.stringify(doc, null, 2)}\n`;
+}
+
+function writeIfChanged(path: string, choices: BinaryChoices): void {
+	const next = serialize(choices);
+	let current: string | undefined;
+	try {
+		current = readFileSync(path, "utf-8");
+	} catch {
+		current = undefined;
+	}
+	if (current !== next) {
+		writeFileAtomicSync(path, next, 0o644);
+		cache = undefined;
+	}
+}
+
+// Lookups run on hot paths (rtk rewrites every bash command); cache the parsed
+// file by path + mtime so a lookup costs one stat.
+let cache: { path: string; mtimeMs: number; state: BinaryStoreState } | undefined;
+
+/** {@link readBinaryStore}, cached until the file changes. */
+export function cachedBinaryStore(env: NodeJS.ProcessEnv = process.env): BinaryStoreState {
+	const path = binaryFilePath(env);
+	let mtimeMs = -1;
+	try {
+		mtimeMs = statSync(path).mtimeMs;
+	} catch {
+		/* missing file */
+	}
+	if (cache && cache.path === path && cache.mtimeMs === mtimeMs) return cache.state;
+	const state = readBinaryStore(env);
+	cache = { path, mtimeMs, state };
+	return state;
+}
+
+const CATALOG: ReadonlySet<string> = new Set(BINARY_NAMES);
+
+/** Drop `null` for catalog entries: automatic is the default, not an override. */
+function overridesOnly(choices: BinaryChoices): BinaryChoices {
+	const out: BinaryChoices = {};
+	for (const [key, value] of Object.entries(choices)) {
+		if (value === null && CATALOG.has(key)) continue;
+		out[key] = value;
+	}
+	return out;
+}
+
+/**
+ * Migrate a legacy binary.json (every catalog entry listed as `null`) to the
+ * overrides-only form. Never creates the file, and never touches an invalid
+ * file (the user must fix it; the tab shows the error).
+ */
+export function syncBinaryStore(env: NodeJS.ProcessEnv = process.env): BinaryStoreState {
+	const state = readBinaryStore(env);
+	if (state.error) return state;
+	const choices = overridesOnly(state.choices);
+	if (Object.keys(choices).length !== Object.keys(state.choices).length)
+		writeIfChanged(state.path, choices);
+	return { path: state.path, choices };
+}
+
+/** Set (string) or clear (null → key removed, automatic) one user choice. */
+export function setBinaryChoice(
+	name: string,
+	value: string | null,
+	env: NodeJS.ProcessEnv = process.env,
+): BinaryStoreState {
+	const state = readBinaryStore(env);
+	if (state.error)
+		throw new Error(`binary.json is invalid (${state.error}); fix ${state.path} first`);
+	const choices = overridesOnly(state.choices);
+	if (value?.trim()) choices[name] = value.trim();
+	else delete choices[name];
+	writeIfChanged(state.path, choices);
+	return { path: state.path, choices };
+}
+
+/** A user choice with `~` expanded, or undefined for automatic. */
+export function userChoice(
+	state: BinaryStoreState,
+	name: string,
+	env = process.env,
+): string | undefined {
+	const raw = state.choices[name];
+	return raw ? expandHome(raw, env) : undefined;
+}