typescript-virtual-container 1.2.8 → 1.3.0

package/dist/utils/expand.js

@@ -0,0 +1,183 @@
+/**
+ * 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, env) {
+    // 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, replacer) {
+    const parts = [];
+    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, env, lastExit = 0, home) {
+    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] : 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];
+        });
+        // ${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, env, lastExit, runCmd) {
+    // $(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/dist/utils/vfsDiff.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 } from "../types/vfs";
+/** 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;
+}
+/**
+ * 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 declare function diffSnapshots(before: VfsSnapshot, after: VfsSnapshot, options?: {
+    /** Glob-style path prefixes to ignore (e.g. `["/proc", "/var/log"]`). */
+    ignore?: string[];
+}): VfsDiff;
+/**
+ * Format a `VfsDiff` as a human-readable string similar to `git diff --stat`.
+ *
+ * @param diff    Result from `diffSnapshots`.
+ * @param options Formatting options.
+ */
+export declare 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;
+/**
+ * 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 declare function assertDiff(diff: VfsDiff, expect: {
+    added?: string[];
+    removed?: string[];
+    modified?: string[];
+}): void;
+//# sourceMappingURL=vfsDiff.d.ts.map

package/dist/utils/vfsDiff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vfsDiff.d.ts","sourceRoot":"","sources":["../../src/utils/vfsDiff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EACX,WAAW,EAIX,MAAM,cAAc,CAAC;AAItB,oDAAoD;AACpD,MAAM,WAAW,YAAY;IAC5B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;CAC3B;AAED,uEAAuE;AACvE,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;CACd;AAED,gDAAgD;AAChD,MAAM,WAAW,OAAO;IACvB,oDAAoD;IACpD,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,oDAAoD;IACpD,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,0CAA0C;IAC1C,KAAK,EAAE,OAAO,CAAC;CACf;AA4BD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC5B,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE;IACR,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACb,GACJ,OAAO,CAsET;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACzB,IAAI,EAAE,OAAO,EACb,OAAO,GAAE;IACR,wDAAwD;IACxD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;CACpB,GACJ,MAAM,CAsCR;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACzB,IAAI,EAAE,OAAO,EACb,MAAM,EAAE;IACP,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB,GACC,IAAI,CA4BN"}

package/dist/utils/vfsDiff.js

@@ -0,0 +1,177 @@
+/**
+ * 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");
+ * ```
+ */
+// ─── internal helpers ─────────────────────────────────────────────────────────
+function flattenSnapshot(node, prefix, out) {
+    const path = prefix === "" ? "/" : prefix;
+    out.set(path, node);
+    if (node.type === "directory") {
+        for (const child of node.children ?? []) {
+            flattenSnapshot(child, `${prefix}/${child.name}`, out);
+        }
+    }
+}
+function decodeContent(node) {
+    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, after, options = {}) {
+    const ignorePrefixes = options.ignore ?? [];
+    const shouldIgnore = (path) => ignorePrefixes.some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
+    const beforeMap = new Map();
+    const afterMap = new Map();
+    flattenSnapshot(before.root, "", beforeMap);
+    flattenSnapshot(after.root, "", afterMap);
+    const added = [];
+    const removed = [];
+    const modified = [];
+    // 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);
+            const afterContent = decodeContent(afterNode);
+            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, b) => 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, options = {}) {
+    if (diff.clean)
+        return "(no changes)";
+    const { showContent = false, maxContentChars = 120 } = options;
+    const lines = [];
+    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, expect) {
+    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)}`);
+        }
+    }
+}

package/package.json

@@ -4,7 +4,7 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
-  "version": "1.2.8",
+  "version": "1.3.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -25,9 +25,11 @@
     "lint": "bunx --bun @biomejs/biome lint ./src",
     "lint:write": "bunx --bun @biomejs/biome lint --write ./src",
     "test": "bunx --bun @biomejs/biome test ./src",
+    "test-battery": "bun test tests/",
     "build": "tsc --project tsconfig.json",
     "deploy:npm": "npm publish --access public",
     "bench": "rm -rf .benchmark-shells/ && bun benchmark-virtualshell.ts",
+    "standalone-build:wo-sftp": "bunx esbuild src/standalone-wo-sftp.ts --bundle --platform=node --target=node18 --outfile=standalone-wo-sftp.js --tree-shaking=true --minify --sourcemap",
     "publish-package": "bash ./scripts/publish-package.sh",
     "standalone-build": "bunx esbuild src/standalone.ts --bundle --platform=node --target=node18 --outfile=standalone.js --tree-shaking=true --minify --sourcemap"
   },

package/src/SSHMimic/exec.ts

@@ -17,7 +17,16 @@ export function runExec(
 	shell: VirtualShell,
 ): void {
 	Promise.resolve(
-		runCommand(cmd, authUser, hostname, "exec", `/home/${authUser}`, shell, undefined, makeDefaultEnv(authUser, hostname)),
+		runCommand(
+			cmd,
+			authUser,
+			hostname,
+			"exec",
+			`/home/${authUser}`,
+			shell,
+			undefined,
+			makeDefaultEnv(authUser, hostname),
+		),
 	)
 		.then((result) => {
 			if (result.stdout) {