pi-crew 0.2.3 → 0.2.4

package/src/utils/incremental-reader.ts

@@ -1,104 +1,104 @@
-import * as fs from "node:fs";
-
-export interface IncrementalReadState {
-	byteOffset: number;
-	lineCount: number;
-}
-
-export interface IncrementalReadResult {
-	lines: string[];
-	state: IncrementalReadState;
-	eof: boolean;
-}
-
-const CHUNK_SIZE = 64 * 1024;
-
-/**
- * Read new lines from a text file since last known byte offset.
- * Uses fs.openSync + fs.readSync for efficient incremental reading.
- */
-export function readLinesSince(filePath: string, state: IncrementalReadState): IncrementalReadResult {
-	let fd: number | undefined;
-	try {
-		fd = fs.openSync(filePath, "r");
-	} catch {
-		return { lines: [], state: { byteOffset: state.byteOffset, lineCount: state.lineCount }, eof: true };
-	}
-
-	try {
-		const stat = fs.fstatSync(fd);
-		const fileSize = stat.size;
-
-		if (fileSize <= state.byteOffset) {
-			return {
-				lines: [],
-				state: { byteOffset: fileSize, lineCount: state.lineCount },
-				eof: true,
-			};
-		}
-
-		const bytesToRead = fileSize - state.byteOffset;
-		const buf = Buffer.alloc(bytesToRead);
-		let totalRead = 0;
-
-		while (totalRead < bytesToRead) {
-			const chunkSize = Math.min(CHUNK_SIZE, bytesToRead - totalRead);
-			const bytesRead = fs.readSync(fd, buf, totalRead, chunkSize, state.byteOffset + totalRead);
-			if (bytesRead === 0) break;
-			totalRead += bytesRead;
-		}
-
-		const content = buf.toString("utf-8", 0, totalRead);
-		const lines: string[] = [];
-		let lineCount = state.lineCount;
-		let committedOffset = state.byteOffset;
-
-		let searchFrom = 0;
-		let newlineIdx: number;
-
-		while ((newlineIdx = content.indexOf("\n", searchFrom)) !== -1) {
-			const lineText = content.slice(searchFrom, newlineIdx);
-			committedOffset = state.byteOffset + newlineIdx + 1;
-			searchFrom = newlineIdx + 1;
-			if (lineText.length > 0) {
-				lines.push(lineText);
-				lineCount++;
-			}
-		}
-
-		const eof = committedOffset >= fileSize;
-
-		return {
-			lines,
-			state: { byteOffset: committedOffset, lineCount },
-			eof,
-		};
-	} finally {
-		if (fd !== undefined) {
-			try { fs.closeSync(fd); } catch { /* ignore */ }
-		}
-	}
-}
-
-/**
- * Read parsed JSON objects from a JSONL file since last known byte offset.
- * Skips malformed lines.
- */
-export function readJsonlSince<T>(filePath: string, state: IncrementalReadState): { items: T[]; state: IncrementalReadState; eof: boolean } {
-	const result = readLinesSince(filePath, state);
-	const items: T[] = [];
-
-	for (const line of result.lines) {
-		try {
-			items.push(JSON.parse(line) as T);
-		} catch {
-			// Skip malformed lines
-		}
-	}
-
-	return {
-		items,
-		state: result.state,
-		eof: result.eof,
-	};
-}
+import * as fs from "node:fs";
+
+export interface IncrementalReadState {
+	byteOffset: number;
+	lineCount: number;
+}
+
+export interface IncrementalReadResult {
+	lines: string[];
+	state: IncrementalReadState;
+	eof: boolean;
+}
+
+const CHUNK_SIZE = 64 * 1024;
+
+/**
+ * Read new lines from a text file since last known byte offset.
+ * Uses fs.openSync + fs.readSync for efficient incremental reading.
+ */
+export function readLinesSince(filePath: string, state: IncrementalReadState): IncrementalReadResult {
+	let fd: number | undefined;
+	try {
+		fd = fs.openSync(filePath, "r");
+	} catch {
+		return { lines: [], state: { byteOffset: state.byteOffset, lineCount: state.lineCount }, eof: true };
+	}
+
+	try {
+		const stat = fs.fstatSync(fd);
+		const fileSize = stat.size;
+
+		if (fileSize <= state.byteOffset) {
+			return {
+				lines: [],
+				state: { byteOffset: fileSize, lineCount: state.lineCount },
+				eof: true,
+			};
+		}
+
+		const bytesToRead = fileSize - state.byteOffset;
+		const buf = Buffer.alloc(bytesToRead);
+		let totalRead = 0;
+
+		while (totalRead < bytesToRead) {
+			const chunkSize = Math.min(CHUNK_SIZE, bytesToRead - totalRead);
+			const bytesRead = fs.readSync(fd, buf, totalRead, chunkSize, state.byteOffset + totalRead);
+			if (bytesRead === 0) break;
+			totalRead += bytesRead;
+		}
+
+		const content = buf.toString("utf-8", 0, totalRead);
+		const lines: string[] = [];
+		let lineCount = state.lineCount;
+		let committedOffset = state.byteOffset;
+
+		let searchFrom = 0;
+		let newlineIdx: number;
+
+		while ((newlineIdx = content.indexOf("\n", searchFrom)) !== -1) {
+			const lineText = content.slice(searchFrom, newlineIdx);
+			committedOffset = state.byteOffset + newlineIdx + 1;
+			searchFrom = newlineIdx + 1;
+			if (lineText.length > 0) {
+				lines.push(lineText);
+				lineCount++;
+			}
+		}
+
+		const eof = committedOffset >= fileSize;
+
+		return {
+			lines,
+			state: { byteOffset: committedOffset, lineCount },
+			eof,
+		};
+	} finally {
+		if (fd !== undefined) {
+			try { fs.closeSync(fd); } catch { /* ignore */ }
+		}
+	}
+}
+
+/**
+ * Read parsed JSON objects from a JSONL file since last known byte offset.
+ * Skips malformed lines.
+ */
+export function readJsonlSince<T>(filePath: string, state: IncrementalReadState): { items: T[]; state: IncrementalReadState; eof: boolean } {
+	const result = readLinesSince(filePath, state);
+	const items: T[] = [];
+
+	for (const line of result.lines) {
+		try {
+			items.push(JSON.parse(line) as T);
+		} catch {
+			// Skip malformed lines
+		}
+	}
+
+	return {
+		items,
+		state: result.state,
+		eof: result.eof,
+	};
+}

package/src/utils/internal-error.ts

@@ -1,6 +1,6 @@
-export function logInternalError(scope: string, error: unknown, details?: string): void {
-	if (!process.env.PI_TEAMS_DEBUG) return;
-	const message = error instanceof Error ? error.message : (typeof error === "object" && error !== null ? JSON.stringify(error) : String(error));
-	const suffix = details ? `: ${details}` : "";
-	console.error(`[pi-crew:${scope}] ${message}${suffix}`);
-}
+export function logInternalError(scope: string, error: unknown, details?: string): void {
+	if (!process.env.PI_TEAMS_DEBUG) return;
+	const message = error instanceof Error ? error.message : (typeof error === "object" && error !== null ? JSON.stringify(error) : String(error));
+	const suffix = details ? `: ${details}` : "";
+	console.error(`[pi-crew:${scope}] ${message}${suffix}`);
+}

package/src/utils/names.ts

@@ -1,27 +1,27 @@
-export function sanitizeName(name: string): string {
-	const result = name.toLowerCase().trim().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
-	return result || "unnamed";
-}
-
-export function requireString(value: unknown, label: string): { value?: string; error?: string } {
-	if (typeof value !== "string" || !value.trim()) return { error: `${label} must be a non-empty string.` };
-	return { value: value.trim() };
-}
-
-export function parseConfigObject(config: unknown): { value?: Record<string, unknown>; error?: string } {
-	let parsed = config;
-	if (typeof parsed === "string") {
-		try {
-			parsed = JSON.parse(parsed) as unknown;
-		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			return { error: `config must be valid JSON: ${message}` };
-		}
-	}
-	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { error: "config must be an object." };
-	return { value: parsed as Record<string, unknown> };
-}
-
-export function hasOwn(obj: Record<string, unknown>, key: string): boolean {
-	return Object.prototype.hasOwnProperty.call(obj, key);
-}
+export function sanitizeName(name: string): string {
+	const result = name.toLowerCase().trim().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+	return result || "unnamed";
+}
+
+export function requireString(value: unknown, label: string): { value?: string; error?: string } {
+	if (typeof value !== "string" || !value.trim()) return { error: `${label} must be a non-empty string.` };
+	return { value: value.trim() };
+}
+
+export function parseConfigObject(config: unknown): { value?: Record<string, unknown>; error?: string } {
+	let parsed = config;
+	if (typeof parsed === "string") {
+		try {
+			parsed = JSON.parse(parsed) as unknown;
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return { error: `config must be valid JSON: ${message}` };
+		}
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { error: "config must be an object." };
+	return { value: parsed as Record<string, unknown> };
+}
+
+export function hasOwn(obj: Record<string, unknown>, key: string): boolean {
+	return Object.prototype.hasOwnProperty.call(obj, key);
+}

package/src/utils/paths.ts

@@ -1,63 +1,102 @@
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-
-export function packageRoot(): string {
-	return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
-}
-
-export function userPiRoot(): string {
-	const home = process.env.PI_TEAMS_HOME?.trim() || os.homedir();
-	return path.join(home, ".pi", "agent");
-}
-
-const PROJECT_DIR_MARKERS = [".git", ".pi", ".crew", ".hg", ".svn", ".factory", ".omc"];
-const PROJECT_FILE_MARKERS = ["package.json", "pyproject.toml", "Cargo.toml", "go.mod", "pom.xml", "composer.json", "build.gradle", "build.gradle.kts"];
-
-function hasProjectMarker(dir: string): boolean {
-	for (const marker of PROJECT_DIR_MARKERS) {
-		if (fs.existsSync(path.join(dir, marker))) return true;
-	}
-	for (const file of PROJECT_FILE_MARKERS) {
-		if (fs.existsSync(path.join(dir, file))) return true;
-	}
-	return false;
-}
-
-export function findRepoRoot(cwd: string): string | undefined {
-	let current = path.resolve(cwd);
-	const root = path.parse(current).root;
-	const home = path.resolve(os.homedir());
-	const tempRoot = path.resolve(os.tmpdir());
-	while (current !== root) {
-		if (hasProjectMarker(current)) return current;
-		if (current === home || current === tempRoot) return undefined;
-		const parent = path.dirname(current);
-		if (parent === current) break;
-		current = parent;
-	}
-	if (current === home || current === tempRoot) return undefined;
-	if (hasProjectMarker(root)) return root;
-	return undefined;
-}
-
-export function projectPiRoot(cwd: string): string {
-	return path.join(findRepoRoot(cwd) ?? cwd, ".pi");
-}
-
-export function projectCrewRoot(cwd: string): string {
-	const repoRoot = findRepoRoot(cwd) ?? cwd;
-	const crewDir = path.join(repoRoot, ".crew");
-	// Keep an existing .crew/ stable even when .pi/ exists for project config.
-	if (fs.existsSync(crewDir)) return crewDir;
-	// Legacy reuse: if .pi/ already exists for the project, namespace under .pi/teams/
-	// to avoid creating a parallel .crew/ alongside an existing pi project layout.
-	const piDir = path.join(repoRoot, ".pi");
-	if (fs.existsSync(piDir)) return path.join(piDir, "teams");
-	return crewDir;
-}
-
-export function userCrewRoot(): string {
-	return path.join(userPiRoot(), "extensions", "pi-crew");
-}
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function packageRoot(): string {
+	return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+}
+
+export function userPiRoot(): string {
+	const home = process.env.PI_TEAMS_HOME?.trim() || os.homedir();
+	return path.join(home, ".pi", "agent");
+}
+
+const PROJECT_DIR_MARKERS = [".git", ".pi", ".crew", ".hg", ".svn", ".factory", ".omc"];
+const PROJECT_FILE_MARKERS = ["package.json", "pyproject.toml", "Cargo.toml", "go.mod", "pom.xml", "composer.json", "build.gradle", "build.gradle.kts"];
+
+// 2.10 — cache findRepoRoot results so repeated lookups during render ticks
+// (loadConfig, state-store helpers, powerbar, snapshot-cache, ...) skip the
+// 14 existsSync calls per ancestor level. TTL is short enough that a freshly
+// `git init`-ed marker is picked up within ~30s without forcing manual
+// invalidation in interactive sessions.
+const PROJECT_ROOT_CACHE_TTL_MS = 30_000;
+const PROJECT_ROOT_CACHE_MAX_ENTRIES = 32;
+interface ProjectRootCacheEntry {
+	repoRoot: string | undefined;
+	cachedAt: number;
+}
+const projectRootCache = new Map<string, ProjectRootCacheEntry>();
+
+function evictOldestProjectRoot(): void {
+	const oldest = projectRootCache.keys().next().value;
+	if (oldest !== undefined) projectRootCache.delete(oldest);
+}
+
+/** Drop all cached findRepoRoot results. Call from cleanupRuntime / tests. */
+export function clearProjectRootCache(): void {
+	projectRootCache.clear();
+}
+
+function hasProjectMarker(dir: string): boolean {
+	for (const marker of PROJECT_DIR_MARKERS) {
+		if (fs.existsSync(path.join(dir, marker))) return true;
+	}
+	for (const file of PROJECT_FILE_MARKERS) {
+		if (fs.existsSync(path.join(dir, file))) return true;
+	}
+	return false;
+}
+
+export function findRepoRoot(cwd: string): string | undefined {
+	const startKey = path.resolve(cwd);
+	const cached = projectRootCache.get(startKey);
+	if (cached && Date.now() - cached.cachedAt < PROJECT_ROOT_CACHE_TTL_MS) {
+		// Re-insert to refresh LRU position.
+		projectRootCache.delete(startKey);
+		projectRootCache.set(startKey, cached);
+		return cached.repoRoot;
+	}
+	const result = computeRepoRoot(startKey);
+	projectRootCache.set(startKey, { repoRoot: result, cachedAt: Date.now() });
+	while (projectRootCache.size > PROJECT_ROOT_CACHE_MAX_ENTRIES) evictOldestProjectRoot();
+	return result;
+}
+
+function computeRepoRoot(start: string): string | undefined {
+	let current = start;
+	const root = path.parse(current).root;
+	const home = path.resolve(os.homedir());
+	const tempRoot = path.resolve(os.tmpdir());
+	while (current !== root) {
+		// Stop walking before checking markers at home or temp root
+		if (current === home || current === tempRoot) return undefined;
+		if (hasProjectMarker(current)) return current;
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	if (current === home || current === tempRoot) return undefined;
+	if (hasProjectMarker(root)) return root;
+	return undefined;
+}
+
+export function projectPiRoot(cwd: string): string {
+	return path.join(findRepoRoot(cwd) ?? cwd, ".pi");
+}
+
+export function projectCrewRoot(cwd: string): string {
+	const repoRoot = findRepoRoot(cwd) ?? cwd;
+	const crewDir = path.join(repoRoot, ".crew");
+	// Keep an existing .crew/ stable even when .pi/ exists for project config.
+	if (fs.existsSync(crewDir)) return crewDir;
+	// Legacy reuse: if .pi/ already exists for the project, namespace under .pi/teams/
+	// to avoid creating a parallel .crew/ alongside an existing pi project layout.
+	const piDir = path.join(repoRoot, ".pi");
+	if (fs.existsSync(piDir)) return path.join(piDir, "teams");
+	return crewDir;
+}
+
+export function userCrewRoot(): string {
+	return path.join(userPiRoot(), "extensions", "pi-crew");
+}

package/src/utils/redaction.ts

@@ -1,44 +1,44 @@
-export const SECRET_KEY_PATTERN = /(?:^|[_.-])(token|api[-_]?key|password|passwd|secret|credential|authorization|private[-_]?key)(?:$|[_.-])/i;
-const INLINE_SECRET_PATTERN = /(^|[\s,{])(([A-Za-z0-9_.-]*(?:api[-_]?key|token|password|passwd|secret|credential|authorization|private[-_]?key)[A-Za-z0-9_.-]*)\s*[=:]\s*)([^\s,;"'}]+)/gi;
-const AUTH_HEADER_PATTERN = /\b(Authorization\s*:\s*(?:Bearer|Basic|Token)?\s*)([^\r\n]+)/gi;
-const BEARER_PATTERN = /\b(Bearer\s+)([A-Za-z0-9._~+/=-]{8,})\b/g;
-const PEM_PRIVATE_KEY_PATTERN = /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]{0,65536}?-----END [A-Z ]*PRIVATE KEY-----/g;
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-	// Exclude built-in types whose Object.entries() would produce empty arrays.
-	if (value instanceof Date || value instanceof RegExp || value instanceof Error || value instanceof Map || value instanceof Set) return false;
-	return true;
-}
-
-function isSecretKey(keyName: string): boolean {
-	return SECRET_KEY_PATTERN.test(keyName) || /^(token|apiKey|api_key|password|secret|credential|authorization|privateKey|private_key)$/i.test(keyName);
-}
-
-export function redactSecretString(value: string): string {
-	return value
-		.replace(PEM_PRIVATE_KEY_PATTERN, "***")
-		.replace(AUTH_HEADER_PATTERN, "$1***")
-		.replace(BEARER_PATTERN, "$1***")
-		.replace(INLINE_SECRET_PATTERN, "$1$2***");
-}
-
-export function redactSecrets(value: unknown, keyName = ""): unknown {
-	if (keyName && isSecretKey(keyName)) return "***";
-	if (typeof value === "string") return redactSecretString(value);
-	if (Array.isArray(value)) return value.map((item) => redactSecrets(item));
-	if (isRecord(value)) {
-		const output: Record<string, unknown> = {};
-		for (const [key, entry] of Object.entries(value)) output[key] = redactSecrets(entry, key);
-		return output;
-	}
-	return value;
-}
-
-export function redactJsonLine(line: string): string {
-	try {
-		return JSON.stringify(redactSecrets(JSON.parse(line) as unknown));
-	} catch {
-		return redactSecretString(line);
-	}
-}
+export const SECRET_KEY_PATTERN = /(?:^|[_.-])(token|api[-_]?key|password|passwd|secret|credential|authorization|private[-_]?key)(?:$|[_.-])/i;
+const INLINE_SECRET_PATTERN = /(^|[\s,{])(([A-Za-z0-9_.-]*(?:api[-_]?key|token|password|passwd|secret|credential|authorization|private[-_]?key)[A-Za-z0-9_.-]*)\s*[=:]\s*)([^\s,;"'}]+)/gi;
+const AUTH_HEADER_PATTERN = /\b(Authorization\s*:\s*(?:Bearer|Basic|Token)?\s*)([^\r\n]+)/gi;
+const BEARER_PATTERN = /\b(Bearer\s+)([A-Za-z0-9._~+/=-]{8,})\b/g;
+const PEM_PRIVATE_KEY_PATTERN = /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]{0,65536}?-----END [A-Z ]*PRIVATE KEY-----/g;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	// Exclude built-in types whose Object.entries() would produce empty arrays.
+	if (value instanceof Date || value instanceof RegExp || value instanceof Error || value instanceof Map || value instanceof Set) return false;
+	return true;
+}
+
+function isSecretKey(keyName: string): boolean {
+	return SECRET_KEY_PATTERN.test(keyName) || /^(token|apiKey|api_key|password|secret|credential|authorization|privateKey|private_key)$/i.test(keyName);
+}
+
+export function redactSecretString(value: string): string {
+	return value
+		.replace(PEM_PRIVATE_KEY_PATTERN, "***")
+		.replace(AUTH_HEADER_PATTERN, "$1***")
+		.replace(BEARER_PATTERN, "$1***")
+		.replace(INLINE_SECRET_PATTERN, "$1$2***");
+}
+
+export function redactSecrets(value: unknown, keyName = ""): unknown {
+	if (keyName && isSecretKey(keyName)) return "***";
+	if (typeof value === "string") return redactSecretString(value);
+	if (Array.isArray(value)) return value.map((item) => redactSecrets(item));
+	if (isRecord(value)) {
+		const output: Record<string, unknown> = {};
+		for (const [key, entry] of Object.entries(value)) output[key] = redactSecrets(entry, key);
+		return output;
+	}
+	return value;
+}
+
+export function redactJsonLine(line: string): string {
+	try {
+		return JSON.stringify(redactSecrets(JSON.parse(line) as unknown));
+	} catch {
+		return redactSecretString(line);
+	}
+}

package/src/utils/safe-paths.ts

@@ -1,47 +1,47 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-export function isSafePathId(value: string): boolean {
-	return /^[A-Za-z0-9_-]+$/.test(value);
-}
-
-export function assertSafePathId(kind: string, value: string): string {
-	if (!isSafePathId(value)) throw new Error(`Invalid ${kind}: ${value}`);
-	return value;
-}
-
-export function resolveContainedPath(baseDir: string, targetPath: string): string {
-	const base = path.resolve(baseDir);
-	const resolved = path.isAbsolute(targetPath) ? path.resolve(targetPath) : path.resolve(base, targetPath);
-	const relative = path.relative(base, resolved);
-	if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`Path is outside ${baseDir}: ${targetPath}`);
-	return resolved;
-}
-
-export function resolveRealContainedPath(baseDir: string, targetPath: string): string {
-	const resolved = resolveContainedPath(baseDir, targetPath);
-	let realBase: string;
-	let realTarget: string;
-	try {
-		realBase = fs.realpathSync.native(baseDir);
-	} catch (baseError) {
-		throw new Error(`Cannot resolve real path of base directory ${baseDir}: ${baseError instanceof Error ? baseError.message : String(baseError)}`);
-	}
-	try {
-		realTarget = fs.realpathSync.native(resolved);
-	} catch (targetError) {
-		if ((targetError as NodeJS.ErrnoException).code === "ENOENT") {
-			throw new Error(`Path does not exist: ${resolved}`);
-		}
-		throw new Error(`Cannot resolve real path of ${resolved}: ${targetError instanceof Error ? targetError.message : String(targetError)}`);
-	}
-	const relative = path.relative(realBase, realTarget);
-	if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`Path is outside ${baseDir}: ${targetPath}`);
-	return realTarget;
-}
-
-export function resolveContainedRelativePath(baseDir: string, relativePath: string, kind = "path"): string {
-	const normalized = relativePath.replaceAll("\\", "/").replace(/^\.\/+/, "");
-	if (!normalized || normalized.split("/").some((segment) => segment === "..") || path.isAbsolute(normalized)) throw new Error(`Invalid ${kind}: ${relativePath}`);
-	return resolveContainedPath(baseDir, path.resolve(baseDir, normalized));
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export function isSafePathId(value: string): boolean {
+	return /^[A-Za-z0-9_-]+$/.test(value);
+}
+
+export function assertSafePathId(kind: string, value: string): string {
+	if (!isSafePathId(value)) throw new Error(`Invalid ${kind}: ${value}`);
+	return value;
+}
+
+export function resolveContainedPath(baseDir: string, targetPath: string): string {
+	const base = path.resolve(baseDir);
+	const resolved = path.isAbsolute(targetPath) ? path.resolve(targetPath) : path.resolve(base, targetPath);
+	const relative = path.relative(base, resolved);
+	if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`Path is outside ${baseDir}: ${targetPath}`);
+	return resolved;
+}
+
+export function resolveRealContainedPath(baseDir: string, targetPath: string): string {
+	const resolved = resolveContainedPath(baseDir, targetPath);
+	let realBase: string;
+	let realTarget: string;
+	try {
+		realBase = fs.realpathSync.native(baseDir);
+	} catch (baseError) {
+		throw new Error(`Cannot resolve real path of base directory ${baseDir}: ${baseError instanceof Error ? baseError.message : String(baseError)}`);
+	}
+	try {
+		realTarget = fs.realpathSync.native(resolved);
+	} catch (targetError) {
+		if ((targetError as NodeJS.ErrnoException).code === "ENOENT") {
+			throw new Error(`Path does not exist: ${resolved}`);
+		}
+		throw new Error(`Cannot resolve real path of ${resolved}: ${targetError instanceof Error ? targetError.message : String(targetError)}`);
+	}
+	const relative = path.relative(realBase, realTarget);
+	if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`Path is outside ${baseDir}: ${targetPath}`);
+	return realTarget;
+}
+
+export function resolveContainedRelativePath(baseDir: string, relativePath: string, kind = "path"): string {
+	const normalized = relativePath.replaceAll("\\", "/").replace(/^\.\/+/, "");
+	if (!normalized || normalized.split("/").some((segment) => segment === "..") || path.isAbsolute(normalized)) throw new Error(`Invalid ${kind}: ${relativePath}`);
+	return resolveContainedPath(baseDir, path.resolve(baseDir, normalized));
+}