@linxiraos/pi-utils 1.0.0

package/src/vterm.ts

@@ -0,0 +1,8 @@
+/** Behavior-compatible reimplementation of @xterm/headless's used surface. */
+export * from "./vterm/buffer";
+export * from "./vterm/terminal";
+
+import { Terminal } from "./vterm/terminal";
+
+const vterm = { Terminal };
+export default vterm;

package/src/which.ts

@@ -0,0 +1,234 @@
+// OS-agnostic "which" helper with robust macOS toolchain lookup and flexible cache control.
+//
+// - Falls back to macOS Xcode/CLT toolchain directories if standard `Bun.which()` fails on Darwin.
+//   Resolves the active developer directory via $DEVELOPER_DIR / /var/db/xcode_select_link symlink
+//   to avoid spawning xcrun subprocesses.
+// - Supports four cache modes (`none`, `fresh`, `ro`, `cached`) for control over discovery cost and determinism.
+// - Computes a stable cache key from command + options to avoid redundant lookups within a process.
+// - Returns path to resolved binary or null if not found.
+//
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+type CacheKey = string | bigint | number;
+
+// Tools shipped by Xcode / Command Line Tools that callers actually look up.
+// Keeps the set small so darwinWhich can fast-reject non-Xcode commands without
+// touching the filesystem.  Only needs entries for binaries that live *exclusively*
+// in toolchain dirs (not on a typical $PATH).
+const XCODE_BINS = new Set([
+	// Compilers & driver aliases
+	"clang",
+	"clang++",
+	"gcc",
+	"g++",
+	"cc",
+	"c++",
+	"cpp",
+	"c89",
+	"c99",
+	"swift",
+	"swiftc",
+	"swift-frontend",
+	// Language servers (LSP)
+	"clangd",
+	"sourcekit-lsp",
+	// Linker & archive tools
+	"ld",
+	"ld-classic",
+	"ar",
+	"ranlib",
+	"libtool",
+	"as",
+	"lipo",
+	"install_name_tool",
+	"codesign_allocate",
+	// Build utilities
+	"make",
+	"gnumake",
+	"m4",
+	"flex",
+	"bison",
+	"yacc",
+	"lex",
+	// VCS (CLT ships git)
+	"git",
+	"git-receive-pack",
+	"git-upload-pack",
+	"git-upload-archive",
+	"git-shell",
+	"scalar",
+	// Debugger
+	"lldb",
+	"lldb-dap",
+	// Binary inspection
+	"nm",
+	"otool",
+	"objdump",
+	"strings",
+	"strip",
+	"size",
+	"dsymutil",
+	"dwarfdump",
+	"lipo",
+	"vtool",
+	// Clang tooling
+	"clang-format",
+	"swift-format",
+]);
+
+// Prefixes for versioned binaries (e.g. python3.9, pip3.12, pydoc3.9, 2to3-3.9)
+const XCODE_BIN_PREFIXES = ["python", "pip", "pydoc", "2to3"];
+
+function isXcodeBin(command: string): boolean {
+	if (XCODE_BINS.has(command)) return true;
+	for (const prefix of XCODE_BIN_PREFIXES) {
+		if (command.startsWith(prefix)) return true;
+	}
+	return false;
+}
+
+// Resolve the active Xcode developer directory once, without spawning any process.
+// Priority: $DEVELOPER_DIR env → /var/db/xcode_select_link symlink → common fallback paths.
+function getDeveloperDirs(): string | null {
+	// 1. Explicit env override
+	const envDir = process.env.DEVELOPER_DIR;
+	if (envDir && fs.existsSync(envDir)) {
+		return envDir;
+	}
+
+	// 2. xcode-select stores the active path as a symlink
+	try {
+		return fs.readlinkSync("/var/db/xcode_select_link");
+	} catch {
+		// symlink may not exist on minimal installs
+	}
+	// 3. Common locations
+	for (const candidate of ["/Applications/Xcode.app/Contents/Developer", "/Library/Developer/CommandLineTools"]) {
+		if (fs.existsSync(candidate)) {
+			return candidate;
+		}
+	}
+	return null;
+}
+
+// Build the list of extra toolchain bin directories to check on macOS.
+// Computed lazily once from the resolved developer directory.
+let macosToolPaths: Map<string, string> | undefined;
+function getMacosToolPaths(): Map<string, string> {
+	if (macosToolPaths) return macosToolPaths;
+	const paths: string[] = [
+		// Always check Command Line Tools (may be independent of Xcode)
+		"/Library/Developer/CommandLineTools/usr/bin",
+	];
+	const devDir = getDeveloperDirs();
+	if (devDir) {
+		paths.push(path.join(devDir, "usr/bin"), path.join(devDir, "Toolchains/XcodeDefault.xctoolchain/usr/bin"));
+	}
+
+	// Deduplicate (e.g. devDir may already be CommandLineTools)
+	macosToolPaths = new Map<string, string>();
+	for (const dir of Array.from(new Set(paths))) {
+		try {
+			for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+				if (entry.isFile() || entry.isSymbolicLink()) {
+					if (macosToolPaths.has(entry.name)) {
+						continue;
+					}
+					macosToolPaths.set(entry.name, path.join(dir, entry.name));
+				}
+			}
+		} catch {
+			// dir doesn't exist or isn't readable
+		}
+	}
+	return macosToolPaths;
+}
+
+// Map: cache key -> resolved binary path or null (not found)
+const toolCache = new Map<CacheKey, string | null>();
+
+/**
+ * Cache policy for which lookups.
+ */
+export const enum WhichCachePolicy {
+	/**
+	 * Use cached result if available.
+	 */
+	Cached = 0,
+	/**
+	 * Bypass cache and perform a new lookup.
+	 */
+	Bypass,
+	/**
+	 * Always update cache.
+	 */
+	Fresh,
+	/**
+	 * Read-only, serves from cache if present, but doesn't write.
+	 */
+	ReadOnly,
+}
+
+// Extension: additional cache policy for tool path lookup
+export interface WhichOptions extends Bun.WhichOptions {
+	/**
+	 * Cache policy for the lookup.
+	 * Defaults to `WhichCachePolicy.Fresh`.
+	 */
+	cache?: WhichCachePolicy;
+}
+
+// Darwin-specific "which" shim: consult Xcode/CLT toolchain directories after $PATH.
+// Uses cached directory listings instead of per-command existsSync or xcrun subprocesses.
+function darwinWhich(command: string, options?: Bun.WhichOptions): string | null {
+	const regular = Bun.which(command, options);
+	if (regular) return regular;
+	if (isXcodeBin(command)) {
+		return getMacosToolPaths().get(command) ?? null;
+	}
+	return null;
+}
+
+// Which function that incorporates Darwin Xcode logic if platform reports as 'darwin'
+export const whichFresh = os.platform() === "darwin" ? darwinWhich : Bun.which;
+
+// Derive stable cache key from command and lookup options
+function cacheKey(command: string, options?: Bun.WhichOptions): CacheKey {
+	if (!options) return command;
+	if (!options.cwd && !options.PATH) return command;
+	let h = Bun.hash(command);
+	if (options.cwd) h = Bun.hash(options.cwd, h);
+	if (options.PATH) h = Bun.hash(options.PATH, h);
+	return h;
+}
+
+/**
+ * Locate binary on PATH (with flexible caching).
+ *
+ * @param command - Binary name to resolve
+ * @param options - Bun.WhichOptions plus `cache` control
+ * @returns Filesystem path if found, else null
+ */
+export function $which(command: string, options?: WhichOptions): string | null {
+	const cachePolicy = options?.cache ?? WhichCachePolicy.Cached;
+	const lookupOptions =
+		options?.PATH !== undefined || process.env.PATH === undefined ? options : { ...options, PATH: process.env.PATH };
+	let key: CacheKey | undefined;
+
+	if (cachePolicy !== WhichCachePolicy.Bypass) {
+		key = cacheKey(command, lookupOptions);
+		if (cachePolicy !== WhichCachePolicy.Fresh) {
+			const cached = toolCache.get(key);
+			if (cached !== undefined) return cached;
+		}
+	}
+
+	const result = whichFresh(command, lookupOptions);
+	if (key != null && cachePolicy !== WhichCachePolicy.ReadOnly) {
+		toolCache.set(key, result);
+	}
+	return result;
+}

package/src/worker-host.ts

@@ -0,0 +1,100 @@
+import { stripWindowsExtendedLengthPathPrefix } from "./path";
+
+/** Prefix reserved for argv selectors dispatched by the shared CLI worker host. */
+export const WORKER_HOST_SELECTOR_PREFIX = "__omp_worker_";
+
+/** Whether an argv value selects a worker hosted by the shared CLI entrypoint. */
+export function isWorkerHostSelector(value: string | undefined): value is string {
+	return value?.startsWith(WORKER_HOST_SELECTOR_PREFIX) ?? false;
+}
+
+/**
+ * Main-module path declared by self-dispatching CLI entrypoints — entries
+ * whose top-level argv handling routes hidden `__omp_*` worker selectors.
+ * Worker spawn sites re-enter this module via `new Worker(entry, { argv })`,
+ * so every distribution (source, npm bundle, compiled binary) needs exactly
+ * one JavaScript entrypoint. Never set under `bun test`, SDK embedding, or
+ * standalone package bins — those hosts load worker modules directly.
+ */
+let workerHostMain: string | null = null;
+
+/** Called by CLI entrypoints whose main module dispatches worker argv selectors. */
+export function declareWorkerHostEntry(): void {
+	workerHostMain = stripWindowsExtendedLengthPathPrefix(Bun.main);
+}
+
+/** Main-module path of the self-dispatching CLI host, or null outside it. */
+export function workerHostEntry(): string | null {
+	return workerHostMain;
+}
+
+/**
+ * Buffers messages a Bun worker thread receives before its real handler is
+ * attached, then hands them off once it is.
+ *
+ * Bun delivers messages the parent posted before the worker spawned exactly
+ * once — when the worker entry module's top-level evaluation completes — to the
+ * `message` listeners present at that moment. A worker whose handler attaches
+ * via a later `await import(...)` therefore misses that flush. The
+ * self-dispatching CLI host imports each worker module dynamically from inside
+ * its argv dispatch, so the worker's own `parentPort.on("message")` lands after
+ * the flush and the parent's synchronously-posted `init` handshake is dropped —
+ * every run then stalls until the init timeout fires and silently falls back to
+ * the inline worker (issue: eval cells always taking the full timeout).
+ *
+ * The host calls {@link installWorkerInbox} synchronously in the entry's sync
+ * prefix (before importing the worker module) so a `parentPort` listener exists
+ * at flush time; the worker module then {@link consumeWorkerInbox}es it and
+ * binds the real handler, replaying anything buffered. Re-dispatching through
+ * `parentPort.emit("message", …)` is not an option — Bun's port is an
+ * `EventTarget` whose `emit` throws — so the inbox calls the handler directly.
+ */
+export interface WorkerInbox {
+	/** Route buffered and subsequent messages to `handler`; returns an unbind fn. */
+	bind(handler: (message: unknown) => void): () => void;
+}
+
+/** Minimal `parentPort` surface the inbox needs (Node/Bun `MessagePort`). */
+interface MessageListenerPort {
+	on(event: "message", listener: (value: unknown) => void): unknown;
+}
+
+let pendingInbox: WorkerInbox | null = null;
+
+/**
+ * Attach a buffering `message` listener on `port` synchronously and stash the
+ * resulting inbox for the worker module to {@link consumeWorkerInbox}. MUST be
+ * called in the entry module's synchronous prefix — before the worker module is
+ * imported — so the listener exists when Bun flushes pre-spawn messages.
+ */
+export function installWorkerInbox(port: MessageListenerPort): WorkerInbox {
+	const queue: unknown[] = [];
+	let handler: ((message: unknown) => void) | null = null;
+	port.on("message", (data: unknown) => {
+		if (handler) handler(data);
+		else queue.push(data);
+	});
+	const inbox: WorkerInbox = {
+		bind(next) {
+			handler = next;
+			for (const data of queue) next(data);
+			queue.length = 0;
+			return () => {
+				if (handler === next) handler = null;
+			};
+		},
+	};
+	pendingInbox = inbox;
+	return inbox;
+}
+
+/**
+ * Take the inbox installed by {@link installWorkerInbox} for this worker, or
+ * `null` when the worker module was loaded directly (no host pre-buffering, so
+ * the module's own synchronous top-level listener already wins the flush).
+ */
+export function consumeWorkerInbox(): WorkerInbox | null {
+	const inbox = pendingInbox;
+	pendingInbox = null;
+	return inbox;
+}

package/src/xml.ts

@@ -0,0 +1,313 @@
+/** Behavior-compatible reimplementation of fast-xml-parser's used surface. */
+
+/** Context supplied to an array-selection callback. */
+export type XMLArraySelector = (
+	tagName: string,
+	jPath: string,
+	isLeafNode: boolean,
+	isAttribute: boolean | null,
+) => boolean;
+
+/** Options supported by {@link XMLParser}. */
+export interface XMLParserOptions {
+	/** Omits attributes when true (default). */
+	ignoreAttributes?: boolean;
+	/** Prefix applied to attribute property names. */
+	attributeNamePrefix?: string;
+	/** Property used for text alongside children or attributes. */
+	textNodeName?: string;
+	/** Trims ordinary text and attribute values. */
+	trimValues?: boolean;
+	/** Coerces numeric and boolean element text. */
+	parseTagValue?: boolean;
+	/** Coerces numeric and boolean attribute values. */
+	parseAttributeValue?: boolean;
+	/** Controls entity processing and its expansion ceiling. */
+	processEntities?: boolean | { maxTotalExpansions?: number };
+	/** Selects element or attribute properties that must always be arrays. */
+	isArray?: XMLArraySelector;
+}
+
+type XmlObject = Record<string, unknown>;
+
+const STANDARD_ENTITIES: Record<string, string> = { amp: "&", apos: "'", gt: ">", lt: "<", quot: '"' };
+
+interface ParsedElement {
+	name: string;
+	value: unknown;
+	leaf: boolean;
+}
+
+interface ParserSettings {
+	ignoreAttributes: boolean;
+	attributeNamePrefix: string;
+	textNodeName: string;
+	trimValues: boolean;
+	parseTagValue: boolean;
+	parseAttributeValue: boolean;
+	processEntities: boolean;
+	maxTotalExpansions: number;
+	isArray?: XMLArraySelector;
+}
+
+/** Parses XML into the object shape used by the document converters. */
+export class XMLParser {
+	readonly #settings: ParserSettings;
+
+	constructor(options: XMLParserOptions = {}) {
+		this.#settings = {
+			ignoreAttributes: options.ignoreAttributes ?? true,
+			attributeNamePrefix: options.attributeNamePrefix ?? "@_",
+			textNodeName: options.textNodeName ?? "#text",
+			trimValues: options.trimValues ?? true,
+			parseTagValue: options.parseTagValue ?? true,
+			parseAttributeValue: options.parseAttributeValue ?? false,
+			processEntities: options.processEntities !== false,
+			maxTotalExpansions:
+				typeof options.processEntities === "object"
+					? (options.processEntities.maxTotalExpansions ?? 100_000)
+					: 100_000,
+			isArray: options.isArray,
+		};
+	}
+
+	/** Parses one XML document. */
+	parse(xml: string): unknown {
+		return new XmlReader(xml, this.#settings).parseDocument();
+	}
+}
+
+class XmlReader {
+	readonly #xml: string;
+	readonly #settings: ParserSettings;
+	readonly #entities = new Map<string, string>();
+	#position = 0;
+	#expansions = 0;
+
+	constructor(xml: string, settings: ParserSettings) {
+		this.#xml = xml.charCodeAt(0) === 0xfeff ? xml.slice(1) : xml;
+		this.#settings = settings;
+	}
+
+	parseDocument(): XmlObject {
+		const document: XmlObject = {};
+		while (this.#position < this.#xml.length) {
+			if (this.#xml.startsWith("<!--", this.#position)) {
+				this.#skipThrough("-->");
+				continue;
+			}
+			if (this.#xml.startsWith("<!DOCTYPE", this.#position)) {
+				this.#readDoctype();
+				continue;
+			}
+			if (this.#xml.startsWith("<?", this.#position)) {
+				this.#readProcessingInstruction(document);
+				continue;
+			}
+			if (this.#xml[this.#position] === "<") {
+				const element = this.#readElement("");
+				this.#addValue(document, element.name, element.name, element.value, element.leaf, null);
+				continue;
+			}
+			this.#position++;
+		}
+		return document;
+	}
+
+	#readElement(parentPath: string): ParsedElement {
+		this.#position++;
+		const name = this.#readName();
+		const path = parentPath ? `${parentPath}.${name}` : name;
+		const attributes: [string, string][] = [];
+		let selfClosing = false;
+		while (this.#position < this.#xml.length) {
+			this.#skipWhitespace();
+			if (this.#xml.startsWith("/>", this.#position)) {
+				this.#position += 2;
+				selfClosing = true;
+				break;
+			}
+			if (this.#xml[this.#position] === ">") {
+				this.#position++;
+				break;
+			}
+			const attributeName = this.#readName();
+			this.#skipWhitespace();
+			let value = "true";
+			if (this.#xml[this.#position] === "=") {
+				this.#position++;
+				this.#skipWhitespace();
+				value = this.#readAttributeValue();
+			}
+			attributes.push([attributeName, value]);
+		}
+
+		const children: XmlObject = {};
+		let text = "";
+		let hasChildren = false;
+		if (!selfClosing) {
+			while (this.#position < this.#xml.length) {
+				if (this.#xml.startsWith(`</${name}`, this.#position)) {
+					this.#position += name.length + 2;
+					const close = this.#xml.indexOf(">", this.#position);
+					this.#position = close < 0 ? this.#xml.length : close + 1;
+					break;
+				}
+				if (this.#xml.startsWith("<![CDATA[", this.#position)) {
+					const end = this.#xml.indexOf("]]>", this.#position + 9);
+					const raw = this.#xml.slice(this.#position + 9, end < 0 ? this.#xml.length : end);
+					const normalized = raw;
+					text += this.#settings.parseTagValue ? String(coerceValue(normalized)) : normalized;
+					this.#position = end < 0 ? this.#xml.length : end + 3;
+					continue;
+				}
+				if (this.#xml.startsWith("<!--", this.#position)) {
+					this.#skipThrough("-->");
+					continue;
+				}
+				if (this.#xml.startsWith("<?", this.#position)) {
+					this.#skipThrough("?>");
+					continue;
+				}
+				if (this.#xml[this.#position] === "<") {
+					const child = this.#readElement(path);
+					hasChildren = true;
+					this.#addValue(children, child.name, `${path}.${child.name}`, child.value, child.leaf, null);
+					continue;
+				}
+				const next = this.#xml.indexOf("<", this.#position);
+				const end = next < 0 ? this.#xml.length : next;
+				const normalized = this.#normalizeText(this.#xml.slice(this.#position, end), true);
+				text += this.#settings.parseTagValue ? String(coerceValue(normalized)) : normalized;
+				this.#position = end;
+			}
+		}
+
+		const hasAttributes = !this.#settings.ignoreAttributes && attributes.length > 0;
+		const parsedText = this.#settings.parseTagValue ? coerceValue(text) : text;
+		if (!hasChildren && !hasAttributes) return { name, value: parsedText, leaf: true };
+		if (text !== "") children[this.#settings.textNodeName] = parsedText;
+		if (hasAttributes) {
+			for (const [attributeName, raw] of attributes) {
+				const key = `${this.#settings.attributeNamePrefix}${attributeName}`;
+				const value = this.#settings.parseAttributeValue ? coerceValue(raw) : raw;
+				this.#addValue(children, key, `${path}.${attributeName}`, value, true, true);
+			}
+		}
+		return { name, value: children, leaf: !hasChildren };
+	}
+
+	#readAttributeValue(): string {
+		const quote = this.#xml[this.#position];
+		if (quote === '"' || quote === "'") {
+			const start = ++this.#position;
+			const end = this.#xml.indexOf(quote, start);
+			this.#position = end < 0 ? this.#xml.length : end + 1;
+			return this.#normalizeText(this.#xml.slice(start, end < 0 ? this.#xml.length : end), true);
+		}
+		const start = this.#position;
+		while (this.#position < this.#xml.length && !/[\s>]/.test(this.#xml[this.#position])) this.#position++;
+		return this.#normalizeText(this.#xml.slice(start, this.#position), true);
+	}
+
+	#readProcessingInstruction(target: XmlObject): void {
+		this.#position += 2;
+		const name = this.#readName();
+		const bodyStart = this.#position;
+		const end = this.#xml.indexOf("?>", bodyStart);
+		const body = this.#xml.slice(bodyStart, end < 0 ? this.#xml.length : end);
+		this.#position = end < 0 ? this.#xml.length : end + 2;
+		const value: XmlObject = {};
+		let hasAttribute = false;
+		const attributePattern = /([^\s=]+)\s*=\s*(["'])(.*?)\2/g;
+		for (const match of body.matchAll(attributePattern)) {
+			if (!this.#settings.ignoreAttributes) {
+				value[`${this.#settings.attributeNamePrefix}${match[1]}`] = this.#normalizeText(match[3]!, true);
+				hasAttribute = true;
+			}
+		}
+		target[`?${name}`] = hasAttribute ? value : "";
+	}
+
+	#readDoctype(): void {
+		const start = this.#position;
+		let bracketDepth = 0;
+		let quote = "";
+		while (this.#position < this.#xml.length) {
+			const char = this.#xml[this.#position++];
+			if (quote) {
+				if (char === quote) quote = "";
+			} else if (char === '"' || char === "'") quote = char;
+			else if (char === "[") bracketDepth++;
+			else if (char === "]") bracketDepth--;
+			else if (char === ">" && bracketDepth === 0) break;
+		}
+		const declaration = this.#xml.slice(start, this.#position);
+		const entityPattern = /<!ENTITY\s+([^\s]+)\s+(["'])(.*?)\2\s*>/gs;
+		for (const match of declaration.matchAll(entityPattern)) this.#entities.set(match[1]!, match[3]!);
+	}
+
+	#normalizeText(value: string, entities: boolean): string {
+		let normalized = this.#settings.trimValues ? value.trim() : value;
+		if (entities && this.#settings.processEntities && normalized.includes("&"))
+			normalized = this.#expandEntities(normalized);
+		return normalized;
+	}
+
+	#expandEntities(value: string, stack?: ReadonlySet<string>): string {
+		return value.replace(/&([A-Za-z_:][\w.:-]*);/g, (whole, name: string) => {
+			const standard = STANDARD_ENTITIES[name];
+			if (standard !== undefined) return standard;
+			const replacement = this.#entities.get(name);
+			if (replacement === undefined || stack?.has(name)) return whole;
+			this.#expansions++;
+			if (this.#expansions > this.#settings.maxTotalExpansions) throw new Error("Entity expansion limit exceeded");
+			const nextStack = new Set(stack);
+			nextStack.add(name);
+			return this.#expandEntities(replacement, nextStack);
+		});
+	}
+
+	#addValue(
+		target: XmlObject,
+		name: string,
+		path: string,
+		value: unknown,
+		leaf: boolean,
+		attribute: boolean | null,
+	): void {
+		const present = Object.hasOwn(target, name);
+		if (present) {
+			const current = target[name];
+			if (Array.isArray(current)) current.push(value);
+			else target[name] = [current, value];
+			return;
+		}
+		const forceArray = this.#settings.isArray?.(name, path, leaf, attribute) ?? false;
+		target[name] = forceArray ? [value] : value;
+	}
+
+	#readName(): string {
+		const start = this.#position;
+		while (this.#position < this.#xml.length && !/[\s/>=]/.test(this.#xml[this.#position])) this.#position++;
+		return this.#xml.slice(start, this.#position);
+	}
+
+	#skipWhitespace(): void {
+		while (this.#position < this.#xml.length && /\s/.test(this.#xml[this.#position])) this.#position++;
+	}
+
+	#skipThrough(marker: string): void {
+		const end = this.#xml.indexOf(marker, this.#position + marker.length);
+		this.#position = end < 0 ? this.#xml.length : end + marker.length;
+	}
+}
+
+function coerceValue(value: string): unknown {
+	if (value === "true") return true;
+	if (value === "false") return false;
+	if (value !== "" && /^[+-]?(?:0[xX][\da-fA-F]+|(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?)$/.test(value)) {
+		return Number(value);
+	}
+	return value;
+}