@f5xc-salesdemos/pi-utils 14.0.2

package/src/color.ts

@@ -0,0 +1,204 @@
+/**
+ * Color manipulation utilities for hex colors.
+ *
+ * @example
+ * ```ts
+ * import { hexToHsv, hsvToHex } from "@f5xc-salesdemos/pi-utils";
+ *
+ * // Work with HSV directly
+ *
+ * // Or work with HSV directly
+ * const hsv = hexToHsv("#4ade80");
+ * hsv.h = (hsv.h + 90) % 360;
+ * const newHex = hsvToHex(hsv);
+ * ```
+ */
+
+export interface HSV {
+	/** Hue in degrees (0-360) */
+	h: number;
+	/** Saturation (0-1) */
+	s: number;
+	/** Value/brightness (0-1) */
+	v: number;
+}
+
+export interface RGB {
+	/** Red (0-255) */
+	r: number;
+	/** Green (0-255) */
+	g: number;
+	/** Blue (0-255) */
+	b: number;
+}
+
+/**
+ * Parse a hex color string to RGB.
+ * Supports #RGB, #RRGGBB formats.
+ */
+export function hexToRgb(hex: string): RGB {
+	const h = hex.startsWith("#") ? hex.slice(1) : hex;
+	if (h.length === 3) {
+		return {
+			r: parseInt(h[0] + h[0], 16),
+			g: parseInt(h[1] + h[1], 16),
+			b: parseInt(h[2] + h[2], 16),
+		};
+	}
+	return {
+		r: parseInt(h.slice(0, 2), 16),
+		g: parseInt(h.slice(2, 4), 16),
+		b: parseInt(h.slice(4, 6), 16),
+	};
+}
+
+/**
+ * Convert RGB to hex color string.
+ */
+export function rgbToHex(rgb: RGB): string {
+	const toHex = (n: number) =>
+		Math.max(0, Math.min(255, Math.round(n)))
+			.toString(16)
+			.padStart(2, "0");
+	return `#${toHex(rgb.r)}${toHex(rgb.g)}${toHex(rgb.b)}`;
+}
+
+/**
+ * Convert RGB to HSV.
+ */
+export function rgbToHsv(rgb: RGB): HSV {
+	const r = rgb.r / 255;
+	const g = rgb.g / 255;
+	const b = rgb.b / 255;
+
+	const max = Math.max(r, g, b);
+	const min = Math.min(r, g, b);
+	const d = max - min;
+
+	let h = 0;
+	if (d !== 0) {
+		if (max === r) h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
+		else if (max === g) h = ((b - r) / d + 2) / 6;
+		else h = ((r - g) / d + 4) / 6;
+	}
+
+	return {
+		h: h * 360,
+		s: max === 0 ? 0 : d / max,
+		v: max,
+	};
+}
+
+/**
+ * Convert HSV to RGB.
+ */
+export function hsvToRgb(hsv: HSV): RGB {
+	const { s, v } = hsv;
+	const h = ((hsv.h % 360) + 360) % 360; // Normalize to 0-360
+
+	const i = Math.floor(h / 60);
+	const f = h / 60 - i;
+	const p = v * (1 - s);
+	const q = v * (1 - f * s);
+	const t = v * (1 - (1 - f) * s);
+
+	let r: number, g: number, b: number;
+	switch (i % 6) {
+		case 0:
+			r = v;
+			g = t;
+			b = p;
+			break;
+		case 1:
+			r = q;
+			g = v;
+			b = p;
+			break;
+		case 2:
+			r = p;
+			g = v;
+			b = t;
+			break;
+		case 3:
+			r = p;
+			g = q;
+			b = v;
+			break;
+		case 4:
+			r = t;
+			g = p;
+			b = v;
+			break;
+		default:
+			r = v;
+			g = p;
+			b = q;
+			break;
+	}
+
+	return {
+		r: Math.round(r * 255),
+		g: Math.round(g * 255),
+		b: Math.round(b * 255),
+	};
+}
+
+/**
+ * Convert hex color to HSV.
+ */
+export function hexToHsv(hex: string): HSV {
+	return rgbToHsv(hexToRgb(hex));
+}
+
+/**
+ * Convert HSV to hex color.
+ */
+export function hsvToHex(hsv: HSV): string {
+	return rgbToHex(hsvToRgb(hsv));
+}
+
+/**
+ * Shift the hue of a hex color by a given number of degrees.
+ */
+export function shiftHue(hex: string, degrees: number): string {
+	const hsv = hexToHsv(hex);
+	hsv.h = (hsv.h + degrees) % 360;
+	if (hsv.h < 0) hsv.h += 360;
+	return hsvToHex(hsv);
+}
+export interface HSVAdjustment {
+	/** Hue shift in degrees (additive) */
+	h?: number;
+	/** Saturation multiplier */
+	s?: number;
+	/** Value/brightness multiplier */
+	v?: number;
+}
+
+/**
+ * Adjust HSV components of a hex color.
+ *
+ * @param hex - Hex color string (#RGB or #RRGGBB)
+ * @param adj - Adjustments: h is additive degrees, s and v are multipliers
+ * @returns New hex color string
+ *
+ * @example
+ * ```ts
+ * // Shift hue +60°, reduce saturation to 71%
+ * adjustHsv("#00ff88", { h: 60, s: 0.71 }) // "#4a9eff"
+ * ```
+ */
+export function adjustHsv(hex: string, adj: HSVAdjustment): string {
+	const hsv = hexToHsv(hex);
+	if (adj.h !== undefined) {
+		hsv.h = (hsv.h + adj.h) % 360;
+		if (hsv.h < 0) hsv.h += 360;
+	}
+	if (adj.s !== undefined) {
+		hsv.s = Math.max(0, Math.min(1, hsv.s * adj.s));
+	}
+	if (adj.v !== undefined) {
+		hsv.v = Math.max(0, Math.min(1, hsv.v * adj.v));
+	}
+	return hsvToHex(hsv);
+}

package/src/dirs.ts

@@ -0,0 +1,425 @@
+/**
+ * Centralized path helpers for xcsh config directories.
+ *
+ * Uses PI_CONFIG_DIR (default ".xcsh") for the config root and
+ * PI_CODING_AGENT_DIR to override the agent directory.
+ *
+ * On Linux, if XDG_DATA_HOME / XDG_STATE_HOME / XDG_CACHE_HOME environment
+ * variables are set, paths are redirected to XDG-compliant locations under
+ * $XDG_*_HOME/xcsh/. This requires running `xcsh config migrate` first to
+ * move data to the new locations. No filesystem existence checks are performed
+ * — if the env var is set, xcsh trusts that the migration has been done.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { engines, version } from "../package.json" with { type: "json" };
+
+/** App name (e.g. "xcsh") */
+export const APP_NAME: string = "xcsh";
+
+/** Config directory name (e.g. ".xcsh") */
+export const CONFIG_DIR_NAME: string = ".xcsh";
+
+/** Version (e.g. "1.0.0") */
+export const VERSION: string = version;
+
+/** Minimum Bun version */
+export const MIN_BUN_VERSION: string = engines.bun.replace(/[^0-9.]/g, "");
+
+// =============================================================================
+// Project directory
+// =============================================================================
+
+/**
+ * On macOS, strip /private prefix only when both paths resolve to the same location.
+ * This preserves aliases like /private/tmp -> /tmp without rewriting unrelated paths.
+ */
+function standardizeMacOSPath(p: string): string {
+	if (process.platform !== "darwin" || !p.startsWith("/private/")) return p;
+	const stripped = p.slice("/private".length);
+	try {
+		if (fs.realpathSync(p) === fs.realpathSync(stripped)) {
+			return stripped;
+		}
+	} catch {}
+	return p;
+}
+
+export function resolveEquivalentPath(inputPath: string): string {
+	const resolvedPath = path.resolve(inputPath);
+	try {
+		return fs.realpathSync(resolvedPath);
+	} catch {
+		return resolvedPath;
+	}
+}
+
+export function normalizePathForComparison(inputPath: string): string {
+	const resolvedPath = resolveEquivalentPath(inputPath);
+	return process.platform === "win32" ? resolvedPath.toLowerCase() : resolvedPath;
+}
+
+export function pathIsWithin(root: string, candidate: string): boolean {
+	const normalizedRoot = normalizePathForComparison(root);
+	const normalizedCandidate = normalizePathForComparison(candidate);
+	const relative = path.relative(normalizedRoot, normalizedCandidate);
+	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+export function relativePathWithinRoot(root: string, candidate: string): string | null {
+	if (!pathIsWithin(root, candidate)) return null;
+	const normalizedRoot = normalizePathForComparison(root);
+	const normalizedCandidate = normalizePathForComparison(candidate);
+	const relative = path.relative(normalizedRoot, normalizedCandidate);
+	return relative || null;
+}
+
+let projectDir = standardizeMacOSPath(process.cwd());
+
+/** Get the project directory. */
+export function getProjectDir(): string {
+	return projectDir;
+}
+
+/** Set the project directory. */
+export function setProjectDir(dir: string): void {
+	projectDir = standardizeMacOSPath(path.resolve(dir));
+	process.chdir(projectDir);
+}
+
+/** Get the config directory name relative to home (e.g. ".xcsh" or PI_CONFIG_DIR override). */
+export function getConfigDirName(): string {
+	return process.env.PI_CONFIG_DIR || CONFIG_DIR_NAME;
+}
+
+/** Get the config agent directory name relative to home (e.g. ".xcsh/agent" or PI_CONFIG_DIR + "/agent"). */
+export function getConfigAgentDirName(): string {
+	return `${getConfigDirName()}/agent`;
+}
+
+// =============================================================================
+// DirResolver — cached, XDG-aware path resolution
+// =============================================================================
+
+type XdgCategory = "data" | "state" | "cache";
+
+/**
+ * Resolves and caches all xcsh directory paths. On Linux, when XDG environment
+ * variables are set, paths are redirected under $XDG_*_HOME/xcsh/. A new
+ * instance is created whenever the agent directory changes, which naturally
+ * invalidates all cached paths.
+ */
+class DirResolver {
+	readonly configRoot: string;
+	readonly agentDir: string;
+
+	// Per-category base dirs. Without XDG, all three equal configRoot / agentDir.
+	// With XDG on Linux, they point to $XDG_*_HOME/xcsh/.
+	readonly #rootDirs: Record<XdgCategory, string>;
+	readonly #agentDirs: Record<XdgCategory, string>;
+
+	readonly #rootCache = new Map<string, string>();
+	readonly #agentCache = new Map<string, string>();
+
+	constructor(agentDirOverride?: string) {
+		this.configRoot = path.join(os.homedir(), getConfigDirName());
+
+		const defaultAgent = path.join(this.configRoot, "agent");
+		this.agentDir = agentDirOverride ? path.resolve(agentDirOverride) : defaultAgent;
+		const isDefault = this.agentDir === defaultAgent;
+
+		// XDG is a Linux convention. On other platforms, or for non-default
+		// profiles, all categories resolve to the legacy paths.
+		let xdgData: string | undefined;
+		let xdgState: string | undefined;
+		let xdgCache: string | undefined;
+		if ((process.platform === "linux" || process.platform === "darwin") && isDefault) {
+			const resolveIf = (envVar: string) => {
+				const value = process.env[envVar];
+				if (value) {
+					try {
+						const joined = path.join(value, APP_NAME);
+						if (fs.existsSync(joined)) {
+							return joined;
+						}
+					} catch {}
+				}
+				return undefined;
+			};
+			xdgData = resolveIf("XDG_DATA_HOME");
+			xdgState = resolveIf("XDG_STATE_HOME");
+			xdgCache = resolveIf("XDG_CACHE_HOME");
+		}
+
+		this.#rootDirs = {
+			data: xdgData ?? this.configRoot,
+			state: xdgState ?? this.configRoot,
+			cache: xdgCache ?? this.configRoot,
+		};
+		// XDG flattens the agent/ prefix: ~/.xcsh/agent/sessions → $XDG_DATA_HOME/xcsh/sessions
+		this.#agentDirs = {
+			data: xdgData ?? this.agentDir,
+			state: xdgState ?? this.agentDir,
+			cache: xdgCache ?? this.agentDir,
+		};
+	}
+
+	/** Config-root subdirectory, with optional XDG override. */
+	rootSubdir(subdir: string, xdg?: XdgCategory): string {
+		const cached = this.#rootCache.get(subdir);
+		if (cached) return cached;
+		const base = xdg ? this.#rootDirs[xdg] : this.configRoot;
+		const result = path.join(base, subdir);
+		this.#rootCache.set(subdir, result);
+		return result;
+	}
+
+	/** Agent subdirectory, with optional XDG override. */
+	agentSubdir(userAgentDir: string | undefined, subdir: string, xdg?: XdgCategory): string {
+		if (!userAgentDir || userAgentDir === this.agentDir) {
+			const cached = this.#agentCache.get(subdir);
+			if (cached) return cached;
+			const base = xdg ? this.#agentDirs[xdg] : this.agentDir;
+			const result = path.join(base, subdir);
+			this.#agentCache.set(subdir, result);
+			return result;
+		}
+		return path.join(userAgentDir, subdir);
+	}
+}
+
+let dirs = new DirResolver(process.env.PI_CODING_AGENT_DIR);
+
+// =============================================================================
+// Root directories
+// =============================================================================
+
+/** Get the config root directory (~/.xcsh). */
+export function getConfigRootDir(): string {
+	return dirs.configRoot;
+}
+
+/** Set the coding agent directory. Creates a fresh resolver, invalidating all cached paths. */
+export function setAgentDir(dir: string): void {
+	dirs = new DirResolver(dir);
+	process.env.PI_CODING_AGENT_DIR = dir;
+}
+
+/** Get the agent config directory (~/.xcsh/agent). */
+export function getAgentDir(): string {
+	return dirs.agentDir;
+}
+
+/** Get the project-local config directory (.xcsh). */
+export function getProjectAgentDir(cwd: string = getProjectDir()): string {
+	return path.join(cwd, CONFIG_DIR_NAME);
+}
+
+// =============================================================================
+// Config-root subdirectories (~/.xcsh/*)
+// =============================================================================
+
+/** Get the reports directory (~/.xcsh/reports). */
+export function getReportsDir(): string {
+	return dirs.rootSubdir("reports", "state");
+}
+
+/** Get the logs directory (~/.xcsh/logs). */
+export function getLogsDir(): string {
+	return dirs.rootSubdir("logs", "state");
+}
+
+/** Get the path to a dated log file (~/.xcsh/logs/xcsh.YYYY-MM-DD.log). */
+export function getLogPath(date = new Date()): string {
+	return path.join(getLogsDir(), `${APP_NAME}.${date.toISOString().slice(0, 10)}.log`);
+}
+
+/** Get the plugins directory (~/.xcsh/plugins). */
+export function getPluginsDir(): string {
+	return dirs.rootSubdir("plugins", "data");
+}
+
+/** Where npm installs packages (~/.xcsh/plugins/node_modules). */
+export function getPluginsNodeModules(): string {
+	return path.join(getPluginsDir(), "node_modules");
+}
+
+/** Plugin manifest (~/.xcsh/plugins/package.json). */
+export function getPluginsPackageJson(): string {
+	return path.join(getPluginsDir(), "package.json");
+}
+
+/** Plugin lock file (~/.xcsh/plugins/xcsh-plugins.lock.json). */
+export function getPluginsLockfile(): string {
+	return path.join(getPluginsDir(), "xcsh-plugins.lock.json");
+}
+
+/** Get the remote mount directory (~/.xcsh/remote). */
+export function getRemoteDir(): string {
+	return dirs.rootSubdir("remote", "data");
+}
+
+/** Get the SSH control socket directory (~/.xcsh/ssh-control). */
+export function getSshControlDir(): string {
+	return dirs.rootSubdir("ssh-control", "state");
+}
+
+/** Get the remote host info directory (~/.xcsh/remote-host). */
+export function getRemoteHostDir(): string {
+	return dirs.rootSubdir("remote-host", "data");
+}
+
+/** Get the managed Python venv directory (~/.xcsh/python-env). */
+export function getPythonEnvDir(): string {
+	return dirs.rootSubdir("python-env", "data");
+}
+
+/** Get the puppeteer sandbox directory (~/.xcsh/puppeteer). */
+export function getPuppeteerDir(): string {
+	return dirs.rootSubdir("puppeteer", "cache");
+}
+
+/** Get the worktree base directory (~/.xcsh/wt). */
+export function getWorktreeBaseDir(): string {
+	return dirs.rootSubdir("wt", "data");
+}
+
+/** Get the path to a worktree directory (~/.xcsh/wt/<project>/<id>). */
+export function getWorktreeDir(encodedProject: string, id: string): string {
+	return path.join(getWorktreeBaseDir(), encodedProject, id);
+}
+
+/** Get the GPU cache path (~/.xcsh/gpu_cache.json). */
+export function getGpuCachePath(): string {
+	return dirs.rootSubdir("gpu_cache.json", "cache");
+}
+
+/** Get the natives directory (~/.xcsh/natives). */
+export function getNativesDir(): string {
+	return dirs.rootSubdir("natives", "cache");
+}
+
+/** Get the stats database path (~/.xcsh/stats.db). */
+export function getStatsDbPath(): string {
+	return dirs.rootSubdir("stats.db", "data");
+}
+
+// =============================================================================
+// Agent subdirectories (~/.xcsh/agent/*)
+// =============================================================================
+
+/** Get the path to agent.db (SQLite database for settings and auth storage). */
+export function getAgentDbPath(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "agent.db", "data");
+}
+
+/** Get the path to history.db (SQLite database for session history). */
+export function getHistoryDbPath(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "history.db", "data");
+}
+
+/** Get the path to models.db (model cache database). */
+export function getModelDbPath(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "models.db", "data");
+}
+
+/** Get the directory path for the shared search DB state (~/.xcsh/agent/search-db). */
+export function getSearchDbDir(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "search-db", "data");
+}
+
+/** Get the sessions directory (~/.xcsh/agent/sessions). */
+export function getSessionsDir(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "sessions", "data");
+}
+
+/** Get the content-addressed blob store directory (~/.xcsh/agent/blobs). */
+export function getBlobsDir(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "blobs", "data");
+}
+
+/** Get the custom themes directory (~/.xcsh/agent/themes). */
+export function getCustomThemesDir(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "themes");
+}
+
+/** Get the tools directory (~/.xcsh/agent/tools). */
+export function getToolsDir(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "tools");
+}
+
+/** Get the slash commands directory (~/.xcsh/agent/commands). */
+export function getCommandsDir(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "commands");
+}
+
+/** Get the prompts directory (~/.xcsh/agent/prompts). */
+export function getPromptsDir(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "prompts");
+}
+
+/** Get the user-level Python modules directory (~/.xcsh/agent/modules). */
+export function getAgentModulesDir(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "modules");
+}
+
+/** Get the memories directory (~/.xcsh/agent/memories). */
+export function getMemoriesDir(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "memories", "state");
+}
+
+/** Get the terminal sessions directory (~/.xcsh/agent/terminal-sessions). */
+export function getTerminalSessionsDir(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "terminal-sessions", "state");
+}
+
+/** Get the crash log path (~/.xcsh/agent/xcsh-crash.log). */
+export function getCrashLogPath(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "xcsh-crash.log", "state");
+}
+
+/** Get the debug log path (~/.xcsh/agent/xcsh-debug.log). */
+export function getDebugLogPath(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, `${APP_NAME}-debug.log`, "state");
+}
+
+// =============================================================================
+// Project subdirectories (.xcsh/*)
+// =============================================================================
+
+/** Get the project-level Python modules directory (.xcsh/modules). */
+export function getProjectModulesDir(cwd: string = getProjectDir()): string {
+	return path.join(getProjectAgentDir(cwd), "modules");
+}
+
+/** Get the project-level prompts directory (.xcsh/prompts). */
+export function getProjectPromptsDir(cwd: string = getProjectDir()): string {
+	return path.join(getProjectAgentDir(cwd), "prompts");
+}
+
+/** Get the project-level plugin overrides path (.xcsh/plugin-overrides.json). */
+export function getProjectPluginOverridesPath(cwd: string = getProjectDir()): string {
+	return path.join(getProjectAgentDir(cwd), "plugin-overrides.json");
+}
+
+// =============================================================================
+// MCP config paths
+// =============================================================================
+
+/** Get the primary MCP config file path (first candidate). */
+export function getMCPConfigPath(scope: "user" | "project", cwd: string = getProjectDir()): string {
+	if (scope === "user") {
+		return path.join(getAgentDir(), "mcp.json");
+	}
+	return path.join(getProjectAgentDir(cwd), "mcp.json");
+}
+
+/** Get the SSH config file path. */
+export function getSSHConfigPath(scope: "user" | "project", cwd: string = getProjectDir()): string {
+	if (scope === "user") {
+		return path.join(getAgentDir(), "ssh.json");
+	}
+	return path.join(getProjectAgentDir(cwd), "ssh.json");
+}

package/src/env.ts

@@ -0,0 +1,84 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { getAgentDir, getConfigRootDir } from "./dirs";
+
+/**
+ * Parses a .env file synchronously and extracts key-value string pairs.
+ * Ignores lines that are empty or start with '#'. Trims whitespace.
+ * Allows values to be quoted with single or double quotes.
+ * Returns an object of key-value pairs.
+ */
+function parseEnvFile(filePath: string): Record<string, string> {
+	const result: Record<string, string> = {};
+	try {
+		const content = fs.readFileSync(filePath, "utf-8");
+		for (const line of content.split("\n")) {
+			const trimmed = line.trim();
+			// Skip comments and blank lines
+			if (!trimmed || trimmed.startsWith("#")) continue;
+
+			const eqIndex = trimmed.indexOf("=");
+			if (eqIndex === -1) continue;
+
+			const key = trimmed.slice(0, eqIndex).trim();
+			let value = trimmed.slice(eqIndex + 1).trim();
+
+			// Remove surrounding quotes (" or ')
+			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+				value = value.slice(1, -1);
+			}
+
+			result[key] = value;
+		}
+	} catch {
+		// File doesn't exist or can't be read - return empty result
+	}
+
+	// XCSH_ overrides PI_
+	for (const k in result) {
+		if (k.startsWith("XCSH_")) {
+			result[`PI_${k.slice(5)}`] = result[k];
+		}
+	}
+
+	return result;
+}
+
+// Eagerly parse the user's $HOME/.env and the current project's .env (from cwd)
+const homeEnv = parseEnvFile(path.join(os.homedir(), ".env"));
+const piEnv = parseEnvFile(path.join(getConfigRootDir(), ".env"));
+const agentEnv = parseEnvFile(path.join(getAgentDir(), ".env"));
+const projectEnv = parseEnvFile(path.join(process.cwd(), ".env"));
+
+for (const file of [projectEnv, agentEnv, piEnv, homeEnv]) {
+	for (const [key, value] of Object.entries(file)) {
+		if (!Bun.env[key]) {
+			Bun.env[key] = value;
+		}
+	}
+}
+
+/**
+ * Intentional re-export of Bun.env.
+ *
+ * All users should import this env module (import { $env } from "@f5xc-salesdemos/pi-utils")
+ * before using environment variables. This ensures that .env files have been loaded and
+ * overrides (project, home) have been applied, so $env always reflects the correct values.
+ */
+export const $env: Record<string, string> = Bun.env as Record<string, string>;
+
+/**
+ * Resolve the first environment variable value from the given keys.
+ * @param keys - The keys to resolve.
+ * @returns The first environment variable value, or undefined if no value is found.
+ */
+export function $pickenv(...keys: string[]): string | undefined {
+	for (const key of keys) {
+		const value = Bun.env[key]?.trim();
+		if (value) {
+			return value;
+		}
+	}
+	return undefined;
+}