@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/core/init.ts

@@ -0,0 +1,223 @@
+/**
+ * Bootstrap Clio's config/data/state/cache directories on first install.
+ * Creates the full directory tree required by subsequent domains and writes
+ * defaults when absent. Idempotent.
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_SETTINGS_YAML } from "./defaults.js";
+import { readClioVersion } from "./package-root.js";
+import { clioCacheDir, clioConfigDir, clioDataDir, clioStateDir, resolveClioDirs } from "./xdg.js";
+
+export interface InitReport {
+	configDir: string;
+	dataDir: string;
+	stateDir: string;
+	cacheDir: string;
+	createdPaths: string[];
+	touchedSettings: boolean;
+}
+
+const CONFIG_SUBDIRS = ["agents"] as const;
+const DATA_SUBDIRS = ["memory", "evidence", "evals"] as const;
+const STATE_SUBDIRS = ["sessions", "audit", "receipts", "interviews", "scratch"] as const;
+
+interface InstallMetadata {
+	version: string;
+	/**
+	 * When Clio was first installed on this machine, present only when that is
+	 * actually known. Absent on a record this process had to synthesize over a
+	 * state root that already existed, where the install time is unrecoverable.
+	 */
+	installedAt?: string;
+	upgradedAt?: string;
+	/**
+	 * When this record was rebuilt because it was missing or unreadable. A repair
+	 * is not an install and must never be written into `installedAt`: `clio-coder
+	 * doctor --fix` over a wiped state root reported the repair minute as the day
+	 * the user installed Clio, and every later run repeated it as fact.
+	 */
+	repairedAt?: string;
+	/**
+	 * The version on record before the most recent version change, kept so the
+	 * first interactive launch after an upgrade can say where it came from and
+	 * `doctor` can show it. Absent on a home that has never changed version.
+	 */
+	upgradedFrom?: string;
+	/**
+	 * The version whose upgrade notice the operator has already seen. Written
+	 * by the interactive boot, once per version, so the notice never repeats.
+	 */
+	noticedVersion?: string;
+	platform: string;
+	nodeVersion: string;
+}
+
+export function initializeClioHome(): InitReport {
+	enforceHomePrefixGuard();
+
+	// Probed from the resolved paths, before the accessors below create them:
+	// clioStateDir() makes the directory it is being asked about, so anything
+	// checked after it reports a first install on every run. A root that is
+	// already there means whatever this call is about to write is a repair.
+	const resolved = resolveClioDirs();
+	const preexistingHome = existsSync(resolved.state) || existsSync(resolved.config) || existsSync(resolved.data);
+
+	const configDir = clioConfigDir();
+	const dataDir = clioDataDir();
+	const stateDir = clioStateDir();
+	const cacheDir = clioCacheDir();
+
+	const created: string[] = [];
+
+	for (const dir of [configDir, dataDir, stateDir, cacheDir]) {
+		if (!existsSync(dir)) {
+			mkdirSync(dir, { recursive: true });
+			created.push(dir);
+		}
+	}
+
+	const subdirSets: ReadonlyArray<[string, ReadonlyArray<string>]> = [
+		[configDir, CONFIG_SUBDIRS],
+		[dataDir, DATA_SUBDIRS],
+		[stateDir, STATE_SUBDIRS],
+	];
+	for (const [root, subs] of subdirSets) {
+		for (const sub of subs) {
+			const full = join(root, sub);
+			if (!existsSync(full)) {
+				mkdirSync(full, { recursive: true });
+				created.push(full);
+			}
+		}
+	}
+
+	// Structure only: an existing settings.yaml is never read, validated, or
+	// rewritten here. Content validation belongs to readSettings/doctor.
+	const settingsPath = join(configDir, "settings.yaml");
+	let touched = false;
+	if (!existsSync(settingsPath)) {
+		writeFileSync(settingsPath, DEFAULT_SETTINGS_YAML, { encoding: "utf8", mode: 0o644 });
+		created.push(settingsPath);
+		touched = true;
+	}
+
+	const credentialsPath = join(configDir, "credentials.yaml");
+	if (!existsSync(credentialsPath)) {
+		writeFileSync(
+			credentialsPath,
+			"# Managed via `clio-coder auth`. Do not edit manually unless you know what you are doing.\n{}\n",
+			{
+				encoding: "utf8",
+				mode: 0o600,
+			},
+		);
+		chmodSync(credentialsPath, 0o600);
+		created.push(credentialsPath);
+	}
+
+	// installedAt is written exactly once, at first install. Any later
+	// version/platform/node change preserves it and stamps upgradedAt instead.
+	const installPath = join(stateDir, "install.json");
+	const installMetadata = readInstallMetadata(installPath);
+	const currentVersion = readClioVersion();
+	if (!installMetadata) {
+		const payload: InstallMetadata = {
+			version: currentVersion,
+			// A first install knows when it happened. A repair does not, and saying
+			// `installedAt: now` there is a fact this process invented.
+			...(preexistingHome ? { repairedAt: new Date().toISOString() } : { installedAt: new Date().toISOString() }),
+			platform: process.platform,
+			nodeVersion: process.version,
+		};
+		writeFileSync(installPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+		created.push(installPath);
+	} else if (
+		installMetadata.version !== currentVersion ||
+		installMetadata.platform !== process.platform ||
+		installMetadata.nodeVersion !== process.version
+	) {
+		// A version change is the upgrade the record is about; a node or platform
+		// change alone keeps whatever earlier transition was on record.
+		const upgradedFrom =
+			installMetadata.version !== currentVersion ? installMetadata.version : installMetadata.upgradedFrom;
+		const payload: InstallMetadata = {
+			version: currentVersion,
+			...(installMetadata.installedAt !== undefined ? { installedAt: installMetadata.installedAt } : {}),
+			...(installMetadata.repairedAt !== undefined ? { repairedAt: installMetadata.repairedAt } : {}),
+			...(upgradedFrom !== undefined ? { upgradedFrom } : {}),
+			...(installMetadata.noticedVersion !== undefined ? { noticedVersion: installMetadata.noticedVersion } : {}),
+			upgradedAt: new Date().toISOString(),
+			platform: process.platform,
+			nodeVersion: process.version,
+		};
+		writeFileSync(installPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+	}
+
+	return { configDir, dataDir, stateDir, cacheDir, createdPaths: created, touchedSettings: touched };
+}
+
+function readInstallMetadata(path: string): InstallMetadata | null {
+	if (!existsSync(path)) return null;
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<InstallMetadata>;
+		// Either stamp is enough to call the record ours. Requiring installedAt
+		// would make every repaired record look corrupt and get re-synthesized on
+		// the next run, moving the repair time forward each time.
+		if (
+			typeof parsed.version === "string" &&
+			(typeof parsed.installedAt === "string" || typeof parsed.repairedAt === "string") &&
+			typeof parsed.platform === "string" &&
+			typeof parsed.nodeVersion === "string"
+		) {
+			return {
+				version: parsed.version,
+				...(typeof parsed.installedAt === "string" ? { installedAt: parsed.installedAt } : {}),
+				...(typeof parsed.upgradedAt === "string" ? { upgradedAt: parsed.upgradedAt } : {}),
+				...(typeof parsed.repairedAt === "string" ? { repairedAt: parsed.repairedAt } : {}),
+				...(typeof parsed.upgradedFrom === "string" ? { upgradedFrom: parsed.upgradedFrom } : {}),
+				...(typeof parsed.noticedVersion === "string" ? { noticedVersion: parsed.noticedVersion } : {}),
+				platform: parsed.platform,
+				nodeVersion: parsed.nodeVersion,
+			};
+		}
+	} catch {
+		// Repaired below by overwriting install.json with current metadata.
+	}
+	return null;
+}
+
+/**
+ * Opt-in safety check that prevents tests from clobbering a parent process's
+ * sandbox when the parent has CLIO_CODER_CONFIG_DIR/CLIO_CODER_DATA_DIR/CLIO_CODER_STATE_DIR/
+ * CLIO_CODER_CACHE_DIR set and the test only overrides CLIO_CODER_HOME. Individual env
+ * vars take precedence over CLIO_CODER_HOME inside resolveClioDirs, so a test that
+ * forgets to override all five will silently inherit the parent's paths and
+ * write into the wrong sandbox.
+ *
+ * Enable by setting CLIO_CODER_REQUIRE_HOME_PREFIX=1 in the test env. The test
+ * harness in tests/harness/spawn.ts opts in by default. We deliberately do
+ * not enable this in production because dev installs may legitimately point
+ * individual dirs outside CLIO_CODER_HOME.
+ */
+function enforceHomePrefixGuard(): void {
+	if (process.env.CLIO_CODER_REQUIRE_HOME_PREFIX !== "1") return;
+	const home = process.env.CLIO_CODER_HOME?.trim();
+	if (!home) return;
+	const dirs = resolveClioDirs();
+	const offenders: string[] = [];
+	if (!dirs.config.startsWith(home)) offenders.push(`configDir=${dirs.config}`);
+	if (!dirs.data.startsWith(home)) offenders.push(`dataDir=${dirs.data}`);
+	if (!dirs.state.startsWith(home)) offenders.push(`stateDir=${dirs.state}`);
+	if (!dirs.cache.startsWith(home)) offenders.push(`cacheDir=${dirs.cache}`);
+	if (offenders.length === 0) return;
+	throw new Error(
+		`CLIO_CODER_REQUIRE_HOME_PREFIX guardrail tripped: resolved Clio directories escape CLIO_CODER_HOME=${home}. ` +
+			`Offending paths: ${offenders.join(", ")}. ` +
+			`Individual overrides CLIO_CODER_CONFIG_DIR, CLIO_CODER_DATA_DIR, CLIO_CODER_STATE_DIR, and CLIO_CODER_CACHE_DIR take precedence ` +
+			`over CLIO_CODER_HOME, so a test that sets only CLIO_CODER_HOME inherits whatever the parent process configured. ` +
+			`Override all five env vars in lockstep to scratch subdirs (CLIO_CODER_HOME plus CLIO_CODER_CONFIG_DIR, ` +
+			`CLIO_CODER_DATA_DIR, CLIO_CODER_STATE_DIR, CLIO_CODER_CACHE_DIR pointing under it), then call resetXdgCache().`,
+	);
+}

package/src/core/json-payload.ts

@@ -0,0 +1,58 @@
+/**
+ * The spans a model message may carry its JSON payload in, in the order they
+ * are tried: the whole message, the first fenced block, then the outermost
+ * brace span.
+ *
+ * A model asked for bare JSON reaches for a fence first, and prose in front of
+ * the fence is the next most common deviation, so a reader that only tries one
+ * span refuses payloads that are correct. The fence candidate is not enough on
+ * its own either: a payload whose own strings contain a fenced block, such as a
+ * "Commands" section holding a ```bash example, truncates at the inner close
+ * and has to fall through to the brace span.
+ *
+ * Every caller parses each candidate in turn and keeps the first that yields
+ * what it needs. None of them may return or throw on the first span that merely
+ * looks plausible: the context-bootstrap reader did exactly that and turned a
+ * complete handbook into "Unterminated string in JSON".
+ */
+function jsonPayloadCandidates(text: string): string[] {
+	const trimmed = text.trim();
+	const candidates = [trimmed];
+	const fenced = /```[A-Za-z0-9_-]*\s*\n?([\s\S]*?)```/.exec(trimmed)?.[1]?.trim();
+	if (fenced !== undefined && fenced.length > 0) candidates.push(fenced);
+	const start = trimmed.indexOf("{");
+	const end = trimmed.lastIndexOf("}");
+	if (start >= 0 && end > start) candidates.push(trimmed.slice(start, end + 1));
+	return candidates;
+}
+
+export type JsonObjectPayload =
+	| { ok: true; value: Record<string, unknown> }
+	| { ok: false; reason: "not-json" | "not-object" };
+
+/**
+ * The first JSON object a model message carries, searched over every span
+ * `jsonPayloadCandidates` names. `not-json` means no span parsed at all;
+ * `not-object` means something parsed and none of it was an object, so a
+ * fenced array is refused with the reason its caller already reports.
+ *
+ * Every reader of a model's JSON answer goes through here so that a validator,
+ * the reader that follows it, and a renderer of the same text agree on what
+ * the payload is. When they held separate ideas, a fenced code report passed
+ * its validator and then threw in the reader that re-parsed the raw text.
+ */
+export function parseJsonObjectPayload(text: string): JsonObjectPayload {
+	let parsedSomething = false;
+	for (const candidate of jsonPayloadCandidates(text)) {
+		let value: unknown;
+		try {
+			value = JSON.parse(candidate) as unknown;
+		} catch {
+			continue;
+		}
+		parsedSomething = true;
+		if (value === null || typeof value !== "object" || Array.isArray(value)) continue;
+		return { ok: true, value: value as Record<string, unknown> };
+	}
+	return { ok: false, reason: parsedSomething ? "not-object" : "not-json" };
+}

package/src/core/package-root.ts

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PI_MONO_PACKAGES } from "../engine/pi-mono-names.js";
+
+let cached: string | null = null;
+let cachedClioVersion: string | null = null;
+let cachedPiMonoVersion: string | null = null;
+
+export function resolvePackageRoot(metaUrl = import.meta.url): string {
+	if (cached) return cached;
+	const override = process.env.CLIO_CODER_PACKAGE_ROOT?.trim();
+	if (override) {
+		cached = resolve(override);
+		return cached;
+	}
+	let dir = resolve(dirname(fileURLToPath(metaUrl)));
+	while (true) {
+		if (existsSync(join(dir, "package.json"))) {
+			cached = dir;
+			return dir;
+		}
+		const parent = dirname(dir);
+		if (parent === dir) {
+			throw new Error(`Could not find package.json above ${dir}`);
+		}
+		dir = parent;
+	}
+}
+
+interface PartialPackageJson {
+	version?: string;
+	dependencies?: Record<string, string>;
+}
+
+function readPackageJson(): PartialPackageJson {
+	const root = resolvePackageRoot();
+	const raw = readFileSync(join(root, "package.json"), "utf8");
+	return JSON.parse(raw) as PartialPackageJson;
+}
+
+export function readClioVersion(): string {
+	if (cachedClioVersion) return cachedClioVersion;
+	const pkg = readPackageJson();
+	cachedClioVersion = pkg.version ?? "0.0.0";
+	return cachedClioVersion;
+}
+
+export function readPiMonoVersion(): string {
+	if (cachedPiMonoVersion) return cachedPiMonoVersion;
+	const pkg = readPackageJson();
+	cachedPiMonoVersion = pkg.dependencies?.[PI_MONO_PACKAGES.agentCore] ?? "unknown";
+	return cachedPiMonoVersion;
+}

package/src/core/path-canonical.ts

@@ -0,0 +1,37 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * Resolve symlinks for an absolute path as far as the filesystem currently
+ * exists. Existing targets return their real path; missing targets return the
+ * real path of the deepest existing parent plus the unresolved tail.
+ */
+export function canonicalizeExistingPath(absPath: string): string {
+	const resolved = path.resolve(absPath);
+	try {
+		return path.resolve(realpathSync(resolved));
+	} catch {
+		// Fall through to parent-prefix canonicalization for missing targets and
+		// paths whose final component cannot be resolved.
+	}
+
+	const tail: string[] = [];
+	let cursor = resolved;
+	while (true) {
+		const parent = path.dirname(cursor);
+		if (parent === cursor) {
+			try {
+				return path.resolve(realpathSync(cursor), ...tail);
+			} catch {
+				return resolved;
+			}
+		}
+		tail.unshift(path.basename(cursor));
+		cursor = parent;
+		try {
+			return path.resolve(realpathSync(cursor), ...tail);
+		} catch {
+			// Keep walking toward the filesystem root.
+		}
+	}
+}

package/src/core/process-identity.ts

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+
+/**
+ * Process identity for durable owner records. A pid alone cannot tell "the
+ * holder is gone" from "the pid was reused", so records carry the owner's birth
+ * token as well; every adjudicator in the tree reads it from here.
+ */
+
+function readProcStartTime(pid: number): string | null {
+	try {
+		const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+		const close = stat.lastIndexOf(")");
+		const fields = stat.slice(close + 2).split(" ");
+		return fields[19] ?? null; // field 22; slice begins at field 3
+	} catch {
+		return null;
+	}
+}
+/**
+ * True when this platform can distinguish "pid is gone" from "pid cannot be
+ * inspected". Where it can, a missing token proves the owner is dead. Where it
+ * cannot, a missing token proves nothing, so reclamation falls back to a
+ * liveness signal and the lease expiry rather than assuming the owner died.
+ */
+export const BIRTH_TOKEN_SOURCE_AVAILABLE = readProcStartTime(process.pid) !== null;
+
+export function processBirthToken(pid = process.pid): string | null {
+	const started = readProcStartTime(pid);
+	if (started !== null) return started;
+	return BIRTH_TOKEN_SOURCE_AVAILABLE ? null : `pid-${pid}`;
+}
+export function processAlive(pid: number): boolean {
+	if (!Number.isFinite(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		// EPERM means the pid exists but belongs to another user.
+		return (error as NodeJS.ErrnoException).code === "EPERM";
+	}
+}

package/src/core/recent-models.ts

@@ -0,0 +1,91 @@
+/**
+ * Recently selected target/model refs ("targetId/wireModelId").
+ *
+ * Recents are runtime state, not user configuration, so they live in the state
+ * dir (recent-models.json) and never in settings.yaml. Keeping them out
+ * of the settings file means an Alt+L model pick does not rewrite settings.yaml
+ * just to bump a recency list, which would fire the config watcher in every
+ * other running session. Favorites (modelSelector.favorites) remain in
+ * settings.yaml because they are deliberate user configuration.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { safeResourceWrite } from "./safe-resource-write.js";
+import { clioStateDir, stateRootRemoved } from "./xdg.js";
+
+export function recentModelsPath(): string {
+	return join(clioStateDir(), "recent-models.json");
+}
+
+let cache: string[] | null = null;
+let cachePath: string | null = null;
+
+function readFromDisk(path: string): string[] | null {
+	if (!existsSync(path)) return null;
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+		if (!Array.isArray(parsed)) return [];
+		const seen = new Set<string>();
+		const out: string[] = [];
+		for (const entry of parsed) {
+			if (typeof entry !== "string") continue;
+			const trimmed = entry.trim();
+			if (trimmed.length === 0 || seen.has(trimmed)) continue;
+			seen.add(trimmed);
+			out.push(trimmed);
+		}
+		return out;
+	} catch {
+		// A corrupted file counts as empty rather than absent so a stale legacy
+		// settings list cannot resurrect over fresher (but unreadable) state.
+		return [];
+	}
+}
+
+function writeToDisk(path: string, refs: ReadonlyArray<string>): void {
+	safeResourceWrite(path, `${JSON.stringify(refs, null, "\t")}\n`, { encoding: "utf8" });
+}
+
+/**
+ * Current recents, newest first, truncated to `limit`. An absent or unreadable
+ * file is an empty list.
+ */
+export function listRecentModels(options?: { limit?: number }): string[] {
+	const path = recentModelsPath();
+	if (cache === null || cachePath !== path) {
+		cache = readFromDisk(path) ?? [];
+		cachePath = path;
+	}
+	const limit = Math.max(1, Math.floor(options?.limit ?? 12));
+	return cache.slice(0, limit);
+}
+
+/** Move `ref` to the front of the recents list and persist to the state dir. */
+export function rememberRecentModel(ref: string, limit: number): string[] {
+	const path = recentModelsPath();
+	// Re-read so refs remembered by other processes since our last load are
+	// merged instead of overwritten. Plain last-writer-wins on the file is
+	// acceptable for a recency list; no lock needed.
+	const base = readFromDisk(path) ?? (cachePath === path && cache !== null ? cache : []);
+	const max = Math.max(1, Math.floor(limit));
+	const next = [ref, ...base.filter((entry) => entry !== ref)].slice(0, max);
+	cache = next;
+	cachePath = path;
+	// An Alt+L model pick in a session outliving `clio-coder uninstall` must not
+	// rebuild the state root around recent-models.json. The in-memory list still
+	// updates so the picker behaves for the rest of the run; see stateRootRemoved().
+	if (stateRootRemoved()) return next;
+	try {
+		writeToDisk(path, next);
+	} catch {
+		// Best-effort, as above.
+	}
+	return next;
+}
+
+/** Test hook: clear the in-process cache after CLIO_* dir overrides change. */
+export function resetRecentModelsCache(): void {
+	cache = null;
+	cachePath = null;
+}

package/src/core/residency-protection.ts

@@ -0,0 +1,56 @@
+/**
+ * Wire model ids the operator's configuration references, each tagged with the
+ * role it serves. The residency layer (src/engine/apis/residency.ts) protects
+ * these from eviction by any other Clio stream: a scout worker must never
+ * unload the orchestrator's coder, and no profile may evict another profile's
+ * model. The orchestrator derives the set from its live effective settings;
+ * dispatch copies it onto each WorkerSpec so worker subprocesses protect the
+ * same models.
+ *
+ * The role travels with the id because an eviction message that names only a
+ * model id reads as an anonymous collision. A resident serving `memory` is the
+ * proactive-memory plane; unloading it silently stops task memory rather than
+ * freeing a spare model, and the operator has to be told which plane they are
+ * about to lose.
+ */
+
+import type { ClioSettings } from "./config.js";
+
+/**
+ * Which plane of the operator's configuration references a model:
+ *   - `chat`: the orchestrator model, the one the interactive session talks to.
+ *   - `memory`: the background plane for proactive task memory.
+ *   - `worker`: the worker default or one of the worker profiles.
+ *   - `target-default`: a target's `defaultModel`, the fallback any session picks up.
+ */
+export type ResidencyRole = "chat" | "memory" | "worker" | "target-default";
+
+/** One configured model id and the role its configuration entry serves. */
+export interface ProtectedModelRef {
+	modelId: string;
+	role: ResidencyRole;
+}
+
+/**
+ * Configured model ids with their roles. The first role that claims an id wins,
+ * ordered chat > memory > worker > target-default, so a model serving both the
+ * chat plane and a target default is reported by the more specific role.
+ */
+export function protectedResidencyModels(settings: ClioSettings): ProtectedModelRef[] {
+	const byId = new Map<string, ResidencyRole>();
+	const add = (id: string | null | undefined, role: ResidencyRole): void => {
+		const trimmed = id?.trim();
+		if (!trimmed || byId.has(trimmed)) return;
+		byId.set(trimmed, role);
+	};
+	add(settings.orchestrator.model, "chat");
+	add(settings.background.model, "memory");
+	add(settings.workers.default.model, "worker");
+	for (const profile of Object.values(settings.workers.profiles ?? {})) add(profile.model, "worker");
+	for (const target of settings.targets) add(target.defaultModel, "target-default");
+	return [...byId].map(([modelId, role]) => ({ modelId, role }));
+}
+
+export function protectedResidencyModelIds(settings: ClioSettings): string[] {
+	return protectedResidencyModels(settings).map((ref) => ref.modelId);
+}

package/src/core/resolve-config-value.ts

@@ -0,0 +1,88 @@
+import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join, resolve, sep } from "node:path";
+
+const commandResultCache = new Map<string, string | undefined>();
+
+export interface ConfigValueWarning {
+	code: "dynamic-command-in-static-resolution";
+	message: string;
+	command: string;
+}
+
+export interface ResolveConfigValueOptions {
+	env?: NodeJS.ProcessEnv;
+	cwd?: string;
+	onWarning?: (warning: ConfigValueWarning) => void;
+}
+
+function env(options?: ResolveConfigValueOptions): NodeJS.ProcessEnv {
+	return options?.env ?? process.env;
+}
+
+function shellCommand(command: string): string | undefined {
+	const isWindows = process.platform === "win32";
+	const shell = isWindows ? process.env.ComSpec || "cmd.exe" : process.env.SHELL || "/bin/sh";
+	const args = isWindows ? ["/d", "/s", "/c", command] : ["-lc", command];
+	const result = spawnSync(shell, args, {
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "ignore"],
+		timeout: 10_000,
+		windowsHide: true,
+	});
+	if (result.error || result.status !== 0) return undefined;
+	const value = result.stdout.trim();
+	return value.length > 0 ? value : undefined;
+}
+
+function executeCommand(commandConfig: string): string | undefined {
+	if (commandResultCache.has(commandConfig)) return commandResultCache.get(commandConfig);
+	const value = shellCommand(commandConfig.slice(1));
+	commandResultCache.set(commandConfig, value);
+	return value;
+}
+
+function warnStaticCommand(config: string, options?: ResolveConfigValueOptions): void {
+	options?.onWarning?.({
+		code: "dynamic-command-in-static-resolution",
+		message: "bang-prefixed config command left literal by static config value resolver",
+		command: config.slice(1),
+	});
+}
+
+export function expandConfigValue(value: string, options?: ResolveConfigValueOptions): string {
+	const sourceEnv = env(options);
+	return value.replace(/\$(\w+)|\$\{([^}]+)\}/g, (match, bare: string | undefined, braced: string | undefined) => {
+		const key = bare ?? braced;
+		if (!key) return match;
+		return sourceEnv[key] ?? "";
+	});
+}
+
+export function expandConfigPath(value: string, options?: ResolveConfigValueOptions): string {
+	const cwd = options?.cwd ?? process.cwd();
+	const expandedEnv = expandConfigValue(value.trim(), options);
+	let expanded = expandedEnv;
+	if (expanded === "~") {
+		expanded = homedir();
+	} else if (expanded.startsWith(`~${sep}`) || expanded.startsWith("~/")) {
+		expanded = `${homedir()}${expanded.slice(1)}`;
+	} else if (expanded.startsWith("~")) {
+		expanded = join(homedir(), expanded.slice(1));
+	}
+	return resolve(cwd, expanded);
+}
+
+function resolveStaticConfigValue(config: string, options?: ResolveConfigValueOptions): string | undefined {
+	if (config.startsWith("!")) warnStaticCommand(config, options);
+	const sourceEnv = env(options);
+	const envValue = sourceEnv[config];
+	if (envValue !== undefined && envValue.length > 0) return envValue;
+	const expanded = expandConfigValue(config, options);
+	return expanded.length > 0 ? expanded : undefined;
+}
+
+export function resolveDynamicConfigValue(config: string, options?: ResolveConfigValueOptions): string | undefined {
+	if (config.startsWith("!")) return executeCommand(config);
+	return resolveStaticConfigValue(config, options);
+}