@oh-my-pi/pi-utils 13.18.0 → 14.0.2

package/src/procmgr.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import * as timers from "node:timers";
 import type { Subprocess } from "bun";
 import { $env } from "./env";
+import { $which } from "./which";
 
 export interface ShellConfig {
 	shell: string;
@@ -60,18 +61,6 @@ function getShellPrefix(): string | undefined {
 	return $env.PI_SHELL_PREFIX || $env.CLAUDE_CODE_SHELL_PREFIX;
 }
 
-/**
- * Find bash executable on PATH (Windows)
- */
-function findBashOnPath(): string | null {
-	try {
-		return Bun.which("bash.exe");
-	} catch {
-		// Ignore errors
-	}
-	return null;
-}
-
 /**
  * Build full shell config from a shell path.
  */
@@ -89,7 +78,7 @@ function buildConfig(shell: string): ShellConfig {
  */
 export function resolveBasicShell(): string | undefined {
 	for (const name of ["bash", "bash.exe", "sh", "sh.exe"]) {
-		const resolved = Bun.which(name);
+		const resolved = $which(name);
 		if (resolved) return resolved;
 	}
 
@@ -152,7 +141,7 @@ export function getShellConfig(customShellPath?: string): ShellConfig {
 		}
 
 		// 3. Fallback: search bash.exe on PATH (Cygwin, MSYS2, WSL, etc.)
-		const bashOnPath = findBashOnPath();
+		const bashOnPath = $which("bash.exe");
 		if (bashOnPath) {
 			cachedShellConfig = buildConfig(bashOnPath);
 			return cachedShellConfig;

package/src/prompt.ts

@@ -0,0 +1,401 @@
+import type { HelperDelegate, HelperOptions, Template, TemplateDelegate } from "handlebars";
+import Handlebars from "handlebars";
+
+export type { HelperDelegate, HelperOptions, Template, TemplateDelegate };
+
+export type PromptRenderPhase = "pre-render" | "post-render";
+
+export interface PromptFormatOptions {
+	renderPhase?: PromptRenderPhase;
+	replaceAsciiSymbols?: boolean;
+	boldRfc2119Keywords?: boolean;
+}
+
+// Opening XML tag (not self-closing, not closing)
+const OPENING_XML = /^<([a-z_-]+)(?:\s+[^>]*)?>$/;
+// Closing XML tag
+const CLOSING_XML = /^<\/([a-z_-]+)>$/;
+// Handlebars block start: {{#if}}, {{#has}}, {{#list}}, etc.
+const OPENING_HBS = /^\{\{#/;
+// Handlebars block end: {{/if}}, {{/has}}, {{/list}}, etc.
+const CLOSING_HBS = /^\{\{\//;
+// List item (- or * or 1.)
+const LIST_ITEM = /^(?:[-*]\s|\d+\.\s)/;
+// Table row
+const TABLE_ROW = /^\|.*\|$/;
+// Table separator (|---|---|)
+const TABLE_SEP = /^\|[-:\s|]+\|$/;
+
+/** RFC 2119 keywords used in prompts. */
+const RFC2119_KEYWORDS = /\b(?:MUST NOT|SHOULD NOT|SHALL NOT|RECOMMENDED|REQUIRED|OPTIONAL|SHOULD|SHALL|MUST|MAY)\b/g;
+
+function boldRfc2119Keywords(line: string): string {
+	return line.replace(RFC2119_KEYWORDS, (match, offset, source) => {
+		const isAlreadyBold =
+			source[offset - 2] === "*" &&
+			source[offset - 1] === "*" &&
+			source[offset + match.length] === "*" &&
+			source[offset + match.length + 1] === "*";
+		if (isAlreadyBold) {
+			return match;
+		}
+		return `**${match}**`;
+	});
+}
+
+/** Compact a table row by trimming cell padding */
+function compactTableRow(line: string): string {
+	const cells = line.split("|");
+	return cells.map(c => c.trim()).join("|");
+}
+
+/** Compact a table separator row */
+function compactTableSep(line: string): string {
+	const cells = line.split("|").filter(c => c.trim());
+	const normalized = cells.map(c => {
+		const trimmed = c.trim();
+		const left = trimmed.startsWith(":");
+		const right = trimmed.endsWith(":");
+		if (left && right) return ":---:";
+		if (left) return ":---";
+		if (right) return "---:";
+		return "---";
+	});
+	return `|${normalized.join("|")}|`;
+}
+
+function replaceCommonAsciiSymbols(line: string): string {
+	return line
+		.replace(/\.{3}/g, "…")
+		.replace(/<->/g, "↔")
+		.replace(/->/g, "→")
+		.replace(/<-/g, "←")
+		.replace(/!=/g, "≠")
+		.replace(/<=/g, "≤")
+		.replace(/>=/g, "≥");
+}
+
+export function format(content: string, options: PromptFormatOptions = {}): string {
+	const {
+		renderPhase = "post-render",
+		replaceAsciiSymbols = false,
+		boldRfc2119Keywords: shouldBoldRfc2119 = false,
+	} = options;
+	const isPreRender = renderPhase === "pre-render";
+	const lines = content.split("\n");
+	const result: string[] = [];
+	let inCodeBlock = false;
+	const topLevelTags: string[] = [];
+
+	for (let i = 0; i < lines.length; i++) {
+		let line = lines[i].trimEnd();
+		let trimmedStart = line.trimStart();
+		if (trimmedStart.startsWith("```") || trimmedStart.startsWith("~~~")) {
+			inCodeBlock = !inCodeBlock;
+			result.push(line);
+			continue;
+		}
+
+		if (inCodeBlock) {
+			result.push(line);
+			continue;
+		}
+
+		if (replaceAsciiSymbols) {
+			line = replaceCommonAsciiSymbols(line);
+		}
+		trimmedStart = line.trimStart();
+		const trimmed = line.trim();
+
+		const isOpeningXml = OPENING_XML.test(trimmedStart) && !trimmedStart.endsWith("/>");
+		if (isOpeningXml && line.length === trimmedStart.length) {
+			const match = OPENING_XML.exec(trimmedStart);
+			if (match) topLevelTags.push(match[1]);
+		}
+
+		const closingMatch = CLOSING_XML.exec(trimmedStart);
+		if (closingMatch) {
+			const tagName = closingMatch[1];
+			if (topLevelTags.length > 0 && topLevelTags[topLevelTags.length - 1] === tagName) {
+				topLevelTags.pop();
+			}
+		} else if (isPreRender && trimmedStart.startsWith("{{")) {
+			/* keep indentation as-is in pre-render for Handlebars markers */
+		} else if (TABLE_SEP.test(trimmedStart)) {
+			const leadingWhitespace = line.slice(0, line.length - trimmedStart.length);
+			line = `${leadingWhitespace}${compactTableSep(trimmedStart)}`;
+		} else if (TABLE_ROW.test(trimmedStart)) {
+			const leadingWhitespace = line.slice(0, line.length - trimmedStart.length);
+			line = `${leadingWhitespace}${compactTableRow(trimmedStart)}`;
+		}
+
+		if (shouldBoldRfc2119) {
+			line = boldRfc2119Keywords(line);
+		}
+
+		const isBlank = trimmed === "";
+		if (isBlank) {
+			const prevLine = result[result.length - 1]?.trim() ?? "";
+			const nextLine = lines[i + 1]?.trim() ?? "";
+
+			if (LIST_ITEM.test(nextLine)) {
+				continue;
+			}
+
+			if (OPENING_XML.test(prevLine) || (isPreRender && OPENING_HBS.test(prevLine))) {
+				continue;
+			}
+
+			if (CLOSING_XML.test(nextLine) || (isPreRender && CLOSING_HBS.test(nextLine))) {
+				continue;
+			}
+
+			const prevIsBlank = prevLine === "";
+			if (prevIsBlank) {
+				continue;
+			}
+		}
+
+		if (CLOSING_XML.test(trimmed) || (isPreRender && CLOSING_HBS.test(trimmed))) {
+			while (result.length > 0 && result[result.length - 1].trim() === "") {
+				result.pop();
+			}
+		}
+
+		result.push(line);
+	}
+
+	while (result.length > 0 && result[result.length - 1].trim() === "") {
+		result.pop();
+	}
+
+	return result.join("\n");
+}
+
+export interface TemplateContext extends Record<string, unknown> {
+	args?: string[];
+	ARGUMENTS?: string;
+	arguments?: string;
+}
+
+const handlebars = Handlebars.create();
+
+handlebars.registerHelper("arg", function (this: TemplateContext, index: number | string): string {
+	const args = this.args ?? [];
+	const parsedIndex = typeof index === "number" ? index : Number.parseInt(index, 10);
+	if (!Number.isFinite(parsedIndex)) return "";
+	const zeroBased = parsedIndex - 1;
+	if (zeroBased < 0) return "";
+	return args[zeroBased] ?? "";
+});
+
+/**
+ * {{#list items prefix="- " suffix="" join="\n"}}{{this}}{{/list}}
+ * Renders an array with customizable prefix, suffix, and join separator.
+ * Note: Use \n in join for newlines (will be unescaped automatically).
+ */
+handlebars.registerHelper(
+	"list",
+	function (this: unknown, context: unknown[], options: Handlebars.HelperOptions): string {
+		if (!Array.isArray(context) || context.length === 0) return "";
+		const prefix = (options.hash.prefix as string) ?? "";
+		const suffix = (options.hash.suffix as string) ?? "";
+		const rawSeparator = (options.hash.join as string) ?? "\n";
+		const separator = rawSeparator.replace(/\\n/g, "\n").replace(/\\t/g, "\t");
+		return context.map(item => `${prefix}${options.fn(item)}${suffix}`).join(separator);
+	},
+);
+
+/**
+ * {{join array ", "}}
+ * Joins an array with a separator (default: ", ").
+ */
+handlebars.registerHelper("join", (context: unknown[], separator?: unknown): string => {
+	if (!Array.isArray(context)) return "";
+	const sep = typeof separator === "string" ? separator : ", ";
+	return context.join(sep);
+});
+
+/**
+ * {{default value "fallback"}}
+ * Returns the value if truthy, otherwise returns the fallback.
+ */
+handlebars.registerHelper("default", (value: unknown, defaultValue: unknown): unknown => value || defaultValue);
+
+/**
+ * {{pluralize count "item" "items"}}
+ * Returns "1 item" or "5 items" based on count.
+ */
+handlebars.registerHelper(
+	"pluralize",
+	(count: number, singular: string, plural: string): string => `${count} ${count === 1 ? singular : plural}`,
+);
+
+/**
+ * {{#when value "==" compare}}...{{else}}...{{/when}}
+ * Conditional block with comparison operators: ==, ===, !=, !==, >, <, >=, <=
+ */
+handlebars.registerHelper(
+	"when",
+	function (this: unknown, lhs: unknown, operator: string, rhs: unknown, options: Handlebars.HelperOptions): string {
+		const ops: Record<string, (a: unknown, b: unknown) => boolean> = {
+			"==": (a, b) => a === b,
+			"===": (a, b) => a === b,
+			"!=": (a, b) => a !== b,
+			"!==": (a, b) => a !== b,
+			">": (a, b) => (a as number) > (b as number),
+			"<": (a, b) => (a as number) < (b as number),
+			">=": (a, b) => (a as number) >= (b as number),
+			"<=": (a, b) => (a as number) <= (b as number),
+		};
+		const fn = ops[operator];
+		if (!fn) return options.inverse(this);
+		return fn(lhs, rhs) ? options.fn(this) : options.inverse(this);
+	},
+);
+
+/**
+ * {{#ifAny a b c}}...{{else}}...{{/ifAny}}
+ * True if any argument is truthy.
+ */
+handlebars.registerHelper("ifAny", function (this: unknown, ...args: unknown[]): string {
+	const options = args.pop() as Handlebars.HelperOptions;
+	return args.some(Boolean) ? options.fn(this) : options.inverse(this);
+});
+
+/**
+ * {{#ifAll a b c}}...{{else}}...{{/ifAll}}
+ * True if all arguments are truthy.
+ */
+handlebars.registerHelper("ifAll", function (this: unknown, ...args: unknown[]): string {
+	const options = args.pop() as Handlebars.HelperOptions;
+	return args.every(Boolean) ? options.fn(this) : options.inverse(this);
+});
+
+/**
+ * {{#table rows headers="Col1|Col2"}}{{col1}}|{{col2}}{{/table}}
+ * Generates a markdown table from an array of objects.
+ */
+handlebars.registerHelper(
+	"table",
+	function (this: unknown, context: unknown[], options: Handlebars.HelperOptions): string {
+		if (!Array.isArray(context) || context.length === 0) return "";
+		const headersStr = options.hash.headers as string | undefined;
+		const headers = headersStr?.split("|") ?? [];
+		const separator = headers.map(() => "---").join(" | ");
+		const headerRow = headers.length > 0 ? `| ${headers.join(" | ")} |\n| ${separator} |\n` : "";
+		const rows = context.map(item => `| ${options.fn(item).trim()} |`).join("\n");
+		return headerRow + rows;
+	},
+);
+
+/**
+ * {{#codeblock lang="diff"}}...{{/codeblock}}
+ * Wraps content in a fenced code block.
+ */
+handlebars.registerHelper("codeblock", function (this: unknown, options: Handlebars.HelperOptions): string {
+	const lang = (options.hash.lang as string) ?? "";
+	const content = options.fn(this).trim();
+	return `\`\`\`${lang}\n${content}\n\`\`\``;
+});
+
+/**
+ * {{#xml "tag"}}content{{/xml}}
+ * Wraps content in XML-style tags. Returns empty string if content is empty.
+ */
+handlebars.registerHelper("xml", function (this: unknown, tag: string, options: Handlebars.HelperOptions): string {
+	const content = options.fn(this).trim();
+	if (!content) return "";
+	return `<${tag}>\n${content}\n</${tag}>`;
+});
+
+/**
+ * {{escapeXml value}}
+ * Escapes XML special characters: & < > "
+ */
+handlebars.registerHelper("escapeXml", (value: unknown): string => {
+	if (value == null) return "";
+	return String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+});
+
+/**
+ * {{len array}}
+ * Returns the length of an array or string.
+ */
+handlebars.registerHelper("len", (value: unknown): number => {
+	if (Array.isArray(value)) return value.length;
+	if (typeof value === "string") return value.length;
+	return 0;
+});
+
+/**
+ * {{add a b}}
+ * Adds two numbers.
+ */
+handlebars.registerHelper("add", (a: number, b: number): number => (a ?? 0) + (b ?? 0));
+
+/**
+ * {{sub a b}}
+ * Subtracts b from a.
+ */
+handlebars.registerHelper("sub", (a: number, b: number): number => (a ?? 0) - (b ?? 0));
+
+/**
+ * {{#has collection item}}...{{else}}...{{/has}}
+ * Checks if an array includes an item or if a Set/Map has a key.
+ */
+handlebars.registerHelper(
+	"has",
+	function (this: unknown, collection: unknown, item: unknown, options: Handlebars.HelperOptions): string {
+		let found = false;
+		if (Array.isArray(collection)) {
+			found = collection.includes(item);
+		} else if (collection instanceof Set) {
+			found = collection.has(item);
+		} else if (collection instanceof Map) {
+			found = collection.has(item);
+		} else if (collection && typeof collection === "object") {
+			if (typeof item === "string" || typeof item === "number" || typeof item === "symbol") {
+				found = item in collection;
+			}
+		}
+		return found ? options.fn(this) : options.inverse(this);
+	},
+);
+
+/**
+ * {{includes array item}}
+ * Returns true if array includes item. For use in other helpers.
+ */
+handlebars.registerHelper("includes", (collection: unknown, item: unknown): boolean => {
+	if (Array.isArray(collection)) return collection.includes(item);
+	if (collection instanceof Set) return collection.has(item);
+	if (collection instanceof Map) return collection.has(item);
+	return false;
+});
+
+/**
+ * {{not value}}
+ * Returns logical NOT of value. For use in subexpressions.
+ */
+handlebars.registerHelper("not", (value: unknown): boolean => !value);
+
+handlebars.registerHelper("jsonStringify", (value: unknown): string => JSON.stringify(value));
+
+export function registerHelper(name: string, fn: HelperDelegate): void {
+	handlebars.registerHelper(name, fn);
+}
+
+export function registerPartial(name: string, fn: Template): void {
+	handlebars.registerPartial(name, fn);
+}
+
+export function compile(template: string): (context: TemplateContext) => string {
+	return handlebars.compile(template, { noEscape: true, strict: false });
+}
+
+export function render(template: string, context: TemplateContext = {}): string {
+	const compiled = compile(template);
+	const rendered = compiled(context ?? {});
+	return format(rendered, { renderPhase: "post-render" });
+}

package/src/which.ts

@@ -0,0 +1,230 @@
+// 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";
+
+// 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<string | bigint, 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);
+	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): string | bigint {
+	if (!options) return command;
+	if (!options.cwd && !options.PATH) return command;
+	let h = Bun.hash.xxHash64(command);
+	if (options.cwd) h = Bun.hash.xxHash64(options.cwd, h);
+	if (options.PATH) h = Bun.hash.xxHash64(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;
+	let key: string | bigint | undefined;
+
+	if (cachePolicy !== WhichCachePolicy.Bypass) {
+		key = cacheKey(command, options);
+		if (cachePolicy !== WhichCachePolicy.Fresh) {
+			const cached = toolCache.get(key);
+			if (cached !== undefined) return cached;
+		}
+	}
+
+	const result = whichFresh(command, options);
+	if (key != null && cachePolicy !== WhichCachePolicy.ReadOnly) {
+		toolCache.set(key, result);
+	}
+	return result;
+}