typescript-virtual-container 1.2.8 → 1.3.0

package/src/utils/expand.ts

@@ -0,0 +1,238 @@
+/**
+ * expand.ts
+ *
+ * Centralised shell variable and expression expansion.
+ * Used by `runCommand` (index.ts), `echo`, and `sh.ts`.
+ *
+ * Handles (in order):
+ *   ~             tilde to $HOME
+ *   $?            last exit code
+ *   $$            mock PID
+ *   $#            argument count (0 outside scripts)
+ *   ${#VAR}       string length
+ *   ${VAR:-def}   default if unset/empty
+ *   ${VAR:=def}   assign default if unset/empty
+ *   ${VAR:+val}   alternate value if set
+ *   ${VAR}        simple braced reference
+ *   $VAR          simple reference
+ *   $((expr))     arithmetic (integer)
+ */
+
+// ─── arithmetic evaluator ────────────────────────────────────────────────────
+
+/**
+ * Evaluate a simple integer arithmetic expression.
+ * Supports: +  -  *  /  %  **  unary-  ( )
+ * Variables are resolved from `env` before evaluation.
+ * Returns NaN on syntax error.
+ */
+export function evalArith(expr: string, env: Record<string, string>): number {
+	// Substitute variable names before evaluating
+	const substituted = expr.replace(
+		/\b([A-Za-z_][A-Za-z0-9_]*)\b/g,
+		(_, name) => {
+			const val = env[name];
+			return val !== undefined && val !== "" ? val : "0";
+		},
+	);
+
+	// Whitelist: only digits, operators, spaces, parens
+	if (!/^[\d\s+\-*/%()^!&|<>=,. ]+$/.test(substituted)) return NaN;
+
+	try {
+		// Use Function constructor for safe subset (no identifiers remain)
+		// eslint-disable-next-line no-new-func
+		const result = Function(
+			`"use strict"; return (${substituted.replace(/\*\*/g, "**")});`,
+		)();
+		return typeof result === "number" ? Math.trunc(result) : NaN;
+	} catch {
+		return NaN;
+	}
+}
+
+// ─── synchronous expansion ───────────────────────────────────────────────────
+
+/**
+ * Apply a replacer only to portions of `input` that are NOT inside single quotes.
+ * Single-quoted content is passed through verbatim (POSIX sh behaviour).
+ */
+function outsideSingleQuotes(
+	input: string,
+	replacer: (chunk: string) => string,
+): string {
+	const parts: string[] = [];
+	let i = 0;
+	while (i < input.length) {
+		const sqIdx = input.indexOf("'", i);
+		if (sqIdx === -1) {
+			// No more single quotes — expand the rest
+			parts.push(replacer(input.slice(i)));
+			break;
+		}
+		// Expand the part before the single quote
+		parts.push(replacer(input.slice(i, sqIdx)));
+		// Find closing single quote — everything inside is literal
+		const closeIdx = input.indexOf("'", sqIdx + 1);
+		if (closeIdx === -1) {
+			// Unclosed quote — treat rest as literal
+			parts.push(input.slice(sqIdx));
+			break;
+		}
+		parts.push(input.slice(sqIdx, closeIdx + 1)); // include quotes
+		i = closeIdx + 1;
+	}
+	return parts.join("");
+}
+
+/**
+ * Expand all shell variable and expression forms synchronously.
+ * Does NOT handle `$(cmd)` — that requires async; see `expandAsync`.
+ * Content inside single quotes is left verbatim per POSIX sh rules.
+ *
+ * @param input     Raw string possibly containing `$VAR`, `${...}`, `$((...))`.
+ * @param env       Current session env vars.
+ * @param lastExit  Last command exit code (for `$?`).
+ * @param home      Home directory path (for `~`).
+ */
+export function expandSync(
+	input: string,
+	env: Record<string, string>,
+	lastExit = 0,
+	home?: string,
+): string {
+	const homePath = home ?? env.HOME ?? "/home/user";
+
+	return outsideSingleQuotes(input, (chunk) => {
+		let s = chunk;
+
+		// Tilde expansion — only at start of token or after `:` or whitespace
+		s = s.replace(
+			/(^|[\s:])~(\/|$)/g,
+			(_, pre, post) => `${pre}${homePath}${post}`,
+		);
+
+		// $? $$ $#
+		s = s.replace(/\$\?/g, String(lastExit));
+		s = s.replace(/\$\$/g, "1");
+		s = s.replace(/\$#/g, "0");
+
+		// $(( arithmetic )) — must come before ${ and $VAR to avoid conflicts
+		s = s.replace(/\$\(\(([^)]+(?:\([^)]*\)[^)]*)*)\)\)/g, (_, expr) => {
+			const result = evalArith(expr, env);
+			return Number.isNaN(result) ? "0" : String(result);
+		});
+
+		// ${#VAR} — string length
+		s = s.replace(/\$\{#([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) =>
+			String((env[name] ?? "").length),
+		);
+
+		// ${VAR:-default}
+		s = s.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*):-([^}]*)\}/g, (_, name, def) =>
+			env[name] !== undefined && env[name] !== "" ? (env[name] as string) : def,
+		);
+
+		// ${VAR:=default} — also assigns to env
+		s = s.replace(
+			/\$\{([A-Za-z_][A-Za-z0-9_]*):=([^}]*)\}/g,
+			(_, name, def) => {
+				if (env[name] === undefined || env[name] === "") env[name] = def;
+				return env[name] as string;
+			},
+		);
+
+		// ${VAR:+alternate}
+		s = s.replace(
+			/\$\{([A-Za-z_][A-Za-z0-9_]*):\+([^}]*)\}/g,
+			(_, name, alt) =>
+				env[name] !== undefined && env[name] !== "" ? alt : "",
+		);
+
+		// ${VAR}
+		s = s.replace(
+			/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g,
+			(_, name) => env[name] ?? "",
+		);
+
+		// $VAR
+		s = s.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_, name) => env[name] ?? "");
+
+		return s;
+	});
+}
+
+// ─── async expansion (includes $(cmd)) ──────────────────────────────────────
+
+/**
+ * Expand all shell forms including `$(cmd)` command substitution.
+ *
+ * Processes `$(...)` blocks depth-first, respecting single-quote boundaries.
+ * Then delegates to `expandSync` for the remaining forms.
+ *
+ * @param input     Raw string.
+ * @param env       Current session env vars.
+ * @param lastExit  Last exit code.
+ * @param runCmd    Async callback to execute a command and return its stdout.
+ */
+export async function expandAsync(
+	input: string,
+	env: Record<string, string>,
+	lastExit: number,
+	runCmd: (cmd: string) => Promise<string>,
+): Promise<string> {
+	// $(cmd) substitution — skip content inside single quotes
+	if (input.includes("$(")) {
+		let result = "";
+		let inSingle = false;
+		let i = 0;
+
+		while (i < input.length) {
+			const ch = input[i]!;
+
+			if (ch === "'" && !inSingle) {
+				inSingle = true;
+				result += ch;
+				i++;
+				continue;
+			}
+			if (ch === "'" && inSingle) {
+				inSingle = false;
+				result += ch;
+				i++;
+				continue;
+			}
+
+			if (!inSingle && ch === "$" && input[i + 1] === "(") {
+				// $((expr)) arithmetic — NOT a $(cmd) substitution, skip it
+				if (input[i + 2] === "(") {
+					result += ch;
+					i++;
+					continue;
+				}
+				// Find matching ) with depth tracking
+				let depth = 0;
+				let j = i + 1;
+				while (j < input.length) {
+					if (input[j] === "(") depth++;
+					else if (input[j] === ")") {
+						depth--;
+						if (depth === 0) break;
+					}
+					j++;
+				}
+				const sub = input.slice(i + 2, j).trim();
+				const out = (await runCmd(sub)).replace(/\n$/, "");
+				result += out;
+				i = j + 1;
+				continue;
+			}
+
+			result += ch;
+			i++;
+		}
+		input = result;
+	}
+
+	return expandSync(input, env, lastExit);
+}

package/src/utils/vfsDiff.ts

@@ -0,0 +1,275 @@
+/**
+ * vfsDiff.ts
+ *
+ * Snapshot diff tooling for `VirtualFileSystem`.
+ *
+ * Compares two VFS snapshots and returns structured diff results suitable
+ * for test assertions, audit logging, and deployment verification.
+ *
+ * @example
+ * ```ts
+ * import { diffSnapshots, formatDiff } from "typescript-virtual-container/utils/vfsDiff";
+ *
+ * const before = shell.vfs.toSnapshot();
+ * await client.exec("npm install && mkdir -p /app");
+ * const after = shell.vfs.toSnapshot();
+ *
+ * const diff = diffSnapshots(before, after);
+ * console.log(formatDiff(diff));
+ *
+ * // Test assertions
+ * expect(diff.added).toContain("/app");
+ * expect(diff.modified).toContain("/etc/hosts");
+ * expect(diff.removed).not.toContain("/tmp/needed-file");
+ * ```
+ */
+
+import type {
+	VfsSnapshot,
+	VfsSnapshotNode,
+	VfsSnapshotFileNode,
+	VfsSnapshotDirectoryNode,
+} from "../types/vfs";
+
+// ─── types ────────────────────────────────────────────────────────────────────
+
+/** A single changed file entry in a diff result. */
+export interface VfsDiffEntry {
+	/** Absolute VFS path of the changed node. */
+	path: string;
+	/** Node type — `"file"` or `"directory"`. */
+	type: "file" | "directory";
+}
+
+/** A modified file entry — includes before/after content for files. */
+export interface VfsDiffModified extends VfsDiffEntry {
+	type: "file";
+	/** Content before the change (decoded from base64). */
+	before: string;
+	/** Content after the change (decoded from base64). */
+	after: string;
+}
+
+/** Full result of a snapshot diff operation. */
+export interface VfsDiff {
+	/** Paths present in `after` but not in `before`. */
+	added: VfsDiffEntry[];
+	/** Paths present in `before` but not in `after`. */
+	removed: VfsDiffEntry[];
+	/** Files whose content or mode changed between snapshots. */
+	modified: VfsDiffModified[];
+	/** True when there are no differences. */
+	clean: boolean;
+}
+
+// ─── internal helpers ─────────────────────────────────────────────────────────
+
+function flattenSnapshot(
+	node: VfsSnapshotNode,
+	prefix: string,
+	out: Map<string, VfsSnapshotNode>,
+): void {
+	const path = prefix === "" ? "/" : prefix;
+	out.set(path, node);
+	if (node.type === "directory") {
+		for (const child of (node as VfsSnapshotDirectoryNode).children ?? []) {
+			flattenSnapshot(child, `${prefix}/${child.name}`, out);
+		}
+	}
+}
+
+function decodeContent(node: VfsSnapshotFileNode): string {
+	try {
+		return Buffer.from(node.contentBase64, "base64").toString("utf8");
+	} catch {
+		return node.contentBase64;
+	}
+}
+
+// ─── public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Compute the diff between two VFS snapshots.
+ *
+ * @param before  Snapshot taken before the operation.
+ * @param after   Snapshot taken after the operation.
+ * @param options Optional filtering options.
+ * @returns A structured `VfsDiff` result.
+ */
+export function diffSnapshots(
+	before: VfsSnapshot,
+	after: VfsSnapshot,
+	options: {
+		/** Glob-style path prefixes to ignore (e.g. `["/proc", "/var/log"]`). */
+		ignore?: string[];
+	} = {},
+): VfsDiff {
+	const ignorePrefixes = options.ignore ?? [];
+
+	const shouldIgnore = (path: string): boolean =>
+		ignorePrefixes.some(
+			(prefix) => path === prefix || path.startsWith(`${prefix}/`),
+		);
+
+	const beforeMap = new Map<string, VfsSnapshotNode>();
+	const afterMap = new Map<string, VfsSnapshotNode>();
+
+	flattenSnapshot(before.root, "", beforeMap);
+	flattenSnapshot(after.root, "", afterMap);
+
+	const added: VfsDiffEntry[] = [];
+	const removed: VfsDiffEntry[] = [];
+	const modified: VfsDiffModified[] = [];
+
+	// Added — in after, not in before
+	for (const [path, node] of afterMap) {
+		if (shouldIgnore(path)) continue;
+		if (!beforeMap.has(path)) {
+			added.push({ path, type: node.type });
+		}
+	}
+
+	// Removed — in before, not in after
+	for (const [path, node] of beforeMap) {
+		if (shouldIgnore(path)) continue;
+		if (!afterMap.has(path)) {
+			removed.push({ path, type: node.type });
+		}
+	}
+
+	// Modified — in both, but content or mode changed
+	for (const [path, afterNode] of afterMap) {
+		if (shouldIgnore(path)) continue;
+		const beforeNode = beforeMap.get(path);
+		if (!beforeNode) continue; // already in added
+		if (afterNode.type !== beforeNode.type) continue; // type change = add+remove
+
+		if (afterNode.type === "file" && beforeNode.type === "file") {
+			const beforeContent = decodeContent(beforeNode as VfsSnapshotFileNode);
+			const afterContent = decodeContent(afterNode as VfsSnapshotFileNode);
+			const modeChanged = afterNode.mode !== beforeNode.mode;
+			if (beforeContent !== afterContent || modeChanged) {
+				modified.push({
+					path,
+					type: "file",
+					before: beforeContent,
+					after: afterContent,
+				});
+			}
+		}
+	}
+
+	// Sort all arrays for determinism
+	const sortByPath = (a: VfsDiffEntry, b: VfsDiffEntry) =>
+		a.path.localeCompare(b.path);
+
+	added.sort(sortByPath);
+	removed.sort(sortByPath);
+	modified.sort(sortByPath);
+
+	return {
+		added,
+		removed,
+		modified,
+		clean: added.length === 0 && removed.length === 0 && modified.length === 0,
+	};
+}
+
+/**
+ * Format a `VfsDiff` as a human-readable string similar to `git diff --stat`.
+ *
+ * @param diff    Result from `diffSnapshots`.
+ * @param options Formatting options.
+ */
+export function formatDiff(
+	diff: VfsDiff,
+	options: {
+		/** Show file content changes inline. Default: false. */
+		showContent?: boolean;
+		/** Max chars of content to show per change. Default: 120. */
+		maxContentChars?: number;
+	} = {},
+): string {
+	if (diff.clean) return "(no changes)";
+
+	const { showContent = false, maxContentChars = 120 } = options;
+	const lines: string[] = [];
+
+	for (const entry of diff.added) {
+		lines.push(`+ ${entry.path}  [${entry.type}]`);
+	}
+
+	for (const entry of diff.removed) {
+		lines.push(`- ${entry.path}  [${entry.type}]`);
+	}
+
+	for (const entry of diff.modified) {
+		lines.push(`~ ${entry.path}  [modified]`);
+		if (showContent) {
+			const before = entry.before.slice(0, maxContentChars);
+			const after = entry.after.slice(0, maxContentChars);
+			lines.push(
+				`  before: ${JSON.stringify(before)}${entry.before.length > maxContentChars ? "…" : ""}`,
+			);
+			lines.push(
+				`  after:  ${JSON.stringify(after)}${entry.after.length > maxContentChars ? "…" : ""}`,
+			);
+		}
+	}
+
+	const summary = [
+		diff.added.length > 0 ? `${diff.added.length} added` : "",
+		diff.removed.length > 0 ? `${diff.removed.length} removed` : "",
+		diff.modified.length > 0 ? `${diff.modified.length} modified` : "",
+	]
+		.filter(Boolean)
+		.join(", ");
+
+	lines.push(`\n${summary}`);
+	return lines.join("\n");
+}
+
+/**
+ * Assert that a diff contains specific paths, throwing on mismatch.
+ * Designed for use in test suites.
+ *
+ * @param diff    Result from `diffSnapshots`.
+ * @param expect  Expected paths in each category.
+ * @throws When any expectation is not met.
+ */
+export function assertDiff(
+	diff: VfsDiff,
+	expect: {
+		added?: string[];
+		removed?: string[];
+		modified?: string[];
+	},
+): void {
+	const addedPaths = diff.added.map((e) => e.path);
+	const removedPaths = diff.removed.map((e) => e.path);
+	const modifiedPaths = diff.modified.map((e) => e.path);
+
+	for (const path of expect.added ?? []) {
+		if (!addedPaths.includes(path)) {
+			throw new Error(
+				`assertDiff: expected "${path}" to be added, but it was not.\nAdded: ${JSON.stringify(addedPaths)}`,
+			);
+		}
+	}
+
+	for (const path of expect.removed ?? []) {
+		if (!removedPaths.includes(path)) {
+			throw new Error(
+				`assertDiff: expected "${path}" to be removed, but it was not.\nRemoved: ${JSON.stringify(removedPaths)}`,
+			);
+		}
+	}
+
+	for (const path of expect.modified ?? []) {
+		if (!modifiedPaths.includes(path)) {
+			throw new Error(
+				`assertDiff: expected "${path}" to be modified, but it was not.\nModified: ${JSON.stringify(modifiedPaths)}`,
+			);
+		}
+	}
+}