typescript-virtual-container 1.2.7 → 1.2.9

package/dist/modules/linuxRootfs.js

@@ -0,0 +1,297 @@
+/**
+ * linuxRootfs.ts
+ *
+ * Bootstraps a realistic Linux directory hierarchy in the VFS.
+ * Called once during VirtualShell initialization. Idempotent — skips
+ * paths that already exist so FS-mode snapshots survive restarts.
+ */
+import * as os from "node:os";
+// ─── helpers ────────────────────────────────────────────────────────────────
+function ensureDir(vfs, path, mode = 0o755) {
+    if (!vfs.exists(path))
+        vfs.mkdir(path, mode);
+}
+function ensureFile(vfs, path, content, mode = 0o644) {
+    if (!vfs.exists(path))
+        vfs.writeFile(path, content, { mode });
+}
+// ─── /etc ────────────────────────────────────────────────────────────────────
+function bootstrapEtc(vfs, hostname, props) {
+    ensureDir(vfs, "/etc");
+    // os-release — authoritative distro identity used by neofetch, lsb_release
+    ensureFile(vfs, "/etc/os-release", `${[
+        `NAME="Fortune GNU/Linux"`,
+        `PRETTY_NAME="${props.os}"`,
+        `ID=fortune`,
+        `ID_LIKE=debian`,
+        `HOME_URL="https://github.com/itsrealfortune/typescript-virtual-container"`,
+        `VERSION_CODENAME=aurora`,
+        `VERSION_ID="1.0"`,
+    ].join("\n")}\n`);
+    ensureFile(vfs, "/etc/debian_version", "12.0\n");
+    ensureFile(vfs, "/etc/hostname", `${hostname}\n`);
+    ensureFile(vfs, "/etc/shells", "/bin/sh\n/bin/bash\n/usr/bin/bash\n");
+    ensureFile(vfs, "/etc/profile", `${[
+        "export PATH=/usr/local/bin:/usr/bin:/bin",
+        "export PS1='\\u@\\h:\\w\\$ '",
+    ].join("\n")}\n`);
+    ensureFile(vfs, "/etc/issue", `Fortune GNU/Linux 1.0 \\n \\l\n`);
+    ensureFile(vfs, "/etc/motd", [
+        "",
+        `Welcome to ${props.os}`,
+        `Kernel: ${props.kernel}`,
+        "",
+    ].join("\n"));
+    // APT sources
+    ensureDir(vfs, "/etc/apt");
+    ensureDir(vfs, "/etc/apt/sources.list.d");
+    ensureFile(vfs, "/etc/apt/sources.list", `${[
+        "# Fortune GNU/Linux package sources",
+        "deb [virtual] fortune://packages.fortune.local aurora main contrib",
+        "deb [virtual] fortune://security.fortune.local aurora-security main",
+    ].join("\n")}\n`);
+    // network stubs
+    ensureDir(vfs, "/etc/network");
+    ensureFile(vfs, "/etc/network/interfaces", `${[
+        "auto lo",
+        "iface lo inet loopback",
+        "",
+        "auto eth0",
+        "iface eth0 inet dhcp",
+    ].join("\n")}\n`);
+    ensureFile(vfs, "/etc/resolv.conf", "nameserver 1.1.1.1\nnameserver 8.8.8.8\n");
+    ensureFile(vfs, "/etc/hosts", `${[
+        "127.0.0.1   localhost",
+        `127.0.1.1   ${hostname}`,
+        "::1         localhost ip6-localhost ip6-loopback",
+    ].join("\n")}\n`);
+    ensureDir(vfs, "/etc/cron.d");
+    ensureDir(vfs, "/etc/init.d");
+    ensureDir(vfs, "/etc/systemd");
+    ensureDir(vfs, "/etc/systemd/system");
+}
+// ─── /etc/passwd + /etc/group + /etc/shadow ─────────────────────────────────
+export function syncEtcPasswd(vfs, users) {
+    const userList = users.listUsers();
+    const passwdLines = [
+        "root:x:0:0:root:/root:/bin/bash",
+        "daemon:x:1:1:daemon:/usr/sbin:/usr/sbin/nologin",
+        "www-data:x:33:33:www-data:/var/www:/usr/sbin/nologin",
+        "nobody:x:65534:65534:nobody:/nonexistent:/usr/sbin/nologin",
+    ];
+    let uid = 1000;
+    for (const u of userList) {
+        if (u === "root")
+            continue;
+        passwdLines.push(`${u}:x:${uid}:${uid}::/home/${u}:/bin/bash`);
+        uid++;
+    }
+    vfs.writeFile("/etc/passwd", `${passwdLines.join("\n")}\n`);
+    const groupLines = [
+        "root:x:0:",
+        "daemon:x:1:",
+        `sudo:x:27:${userList.filter((u) => users.isSudoer(u)).join(",")}`,
+        `users:x:100:${userList.filter((u) => u !== "root").join(",")}`,
+        "nogroup:x:65534:",
+    ];
+    vfs.writeFile("/etc/group", `${groupLines.join("\n")}\n`);
+    // shadow — fake hashes, never real
+    const shadowLines = [
+        "root:*:19000:0:99999:7:::",
+        "daemon:*:19000:0:99999:7:::",
+    ];
+    for (const u of userList) {
+        if (u === "root")
+            continue;
+        shadowLines.push(`${u}:!:19000:0:99999:7:::`);
+    }
+    vfs.writeFile("/etc/shadow", `${shadowLines.join("\n")}\n`, { mode: 0o640 });
+}
+// ─── /proc ───────────────────────────────────────────────────────────────────
+export function refreshProc(vfs, props, hostname, shellStartTime) {
+    ensureDir(vfs, "/proc");
+    const uptimeSec = Math.floor((Date.now() - shellStartTime) / 1000);
+    vfs.writeFile("/proc/uptime", `${uptimeSec}.00 ${Math.floor(uptimeSec * 0.9)}.00\n`);
+    const totalMemKb = Math.floor(os.totalmem() / 1024);
+    const freeMemKb = Math.floor(os.freemem() / 1024);
+    const availMemKb = Math.floor(freeMemKb * 0.95);
+    vfs.writeFile("/proc/meminfo", `${[
+        `MemTotal:       ${String(totalMemKb).padStart(10)} kB`,
+        `MemFree:        ${String(freeMemKb).padStart(10)} kB`,
+        `MemAvailable:   ${String(availMemKb).padStart(10)} kB`,
+        `Buffers:        ${String(Math.floor(totalMemKb * 0.02)).padStart(10)} kB`,
+        `Cached:         ${String(Math.floor(totalMemKb * 0.15)).padStart(10)} kB`,
+        `SwapTotal:      ${String(Math.floor(totalMemKb * 0.5)).padStart(10)} kB`,
+        `SwapFree:       ${String(Math.floor(totalMemKb * 0.5)).padStart(10)} kB`,
+    ].join("\n")}\n`);
+    const cpus = os.cpus();
+    const cpuLines = [];
+    for (let i = 0; i < cpus.length; i++) {
+        const c = cpus[i];
+        if (!c)
+            continue;
+        const mhz = (c.speed).toFixed(3);
+        cpuLines.push(`processor\t: ${i}`, `model name\t: ${c.model}`, `cpu MHz\t\t: ${mhz}`, `cache size\t: 8192 KB`, "");
+    }
+    vfs.writeFile("/proc/cpuinfo", `${cpuLines.join("\n")}\n`);
+    vfs.writeFile("/proc/version", `Linux version ${props.kernel} (fortune@build) (gcc version 12.2.0) #1 SMP\n`);
+    vfs.writeFile("/proc/hostname", `${hostname}\n`);
+    // /proc/loadavg
+    const load = (Math.random() * 0.5).toFixed(2);
+    vfs.writeFile("/proc/loadavg", `${load} ${load} ${load} 1/1 1\n`);
+    // /proc/net stubs
+    ensureDir(vfs, "/proc/net");
+    ensureFile(vfs, "/proc/net/dev", `${[
+        "Inter-|   Receive                                                |  Transmit",
+        " face |bytes    packets errs drop fifo frame compressed multicast|bytes    packets errs drop fifo colls carrier compressed",
+        "    lo:       0       0    0    0    0     0          0         0        0       0    0    0    0     0       0          0",
+        "  eth0:  131072    1024    0    0    0     0          0         0    65536     512    0    0    0     0       0          0",
+    ].join("\n")}\n`);
+}
+// ─── /sys ─────────────────────────────────────────────────────────────────────
+function bootstrapSys(vfs, props) {
+    ensureDir(vfs, "/sys");
+    ensureDir(vfs, "/sys/devices");
+    ensureDir(vfs, "/sys/devices/virtual");
+    ensureDir(vfs, "/sys/devices/virtual/dmi");
+    ensureDir(vfs, "/sys/devices/virtual/dmi/id");
+    ensureFile(vfs, "/sys/devices/virtual/dmi/id/sys_vendor", "Fortune Systems\n");
+    ensureFile(vfs, "/sys/devices/virtual/dmi/id/product_name", "VirtualContainer v1\n");
+    ensureFile(vfs, "/sys/devices/virtual/dmi/id/board_name", "fortune-board\n");
+    ensureDir(vfs, "/sys/class");
+    ensureDir(vfs, "/sys/class/net");
+    ensureDir(vfs, "/sys/kernel");
+    ensureFile(vfs, "/sys/kernel/hostname", "fortune-vm\n");
+    ensureFile(vfs, "/sys/kernel/osrelease", `${props.kernel}\n`);
+    ensureFile(vfs, "/sys/kernel/ostype", "Linux\n");
+}
+// ─── /dev ─────────────────────────────────────────────────────────────────────
+function bootstrapDev(vfs) {
+    ensureDir(vfs, "/dev");
+    ensureFile(vfs, "/dev/null", "", 0o666);
+    ensureFile(vfs, "/dev/zero", "", 0o666);
+    ensureFile(vfs, "/dev/random", "", 0o444);
+    ensureFile(vfs, "/dev/urandom", "", 0o444);
+    ensureDir(vfs, "/dev/pts");
+    ensureDir(vfs, "/dev/shm");
+}
+// ─── /usr ─────────────────────────────────────────────────────────────────────
+function bootstrapUsr(vfs) {
+    ensureDir(vfs, "/usr");
+    ensureDir(vfs, "/usr/bin");
+    ensureDir(vfs, "/usr/sbin");
+    ensureDir(vfs, "/usr/local");
+    ensureDir(vfs, "/usr/local/bin");
+    ensureDir(vfs, "/usr/local/lib");
+    ensureDir(vfs, "/usr/local/share");
+    ensureDir(vfs, "/usr/share");
+    ensureDir(vfs, "/usr/share/doc");
+    ensureDir(vfs, "/usr/share/man");
+    ensureDir(vfs, "/usr/share/man/man1");
+    ensureDir(vfs, "/usr/lib");
+    // Stub binaries so `which` can find built-in commands
+    const builtins = [
+        "sh", "bash", "ls", "cat", "echo", "grep", "find", "sort",
+        "head", "tail", "cut", "tr", "sed", "awk", "wc", "tee",
+        "tar", "gzip", "gunzip", "touch", "mkdir", "rm", "mv", "cp",
+        "chmod", "ln", "pwd", "env", "date", "sleep", "id", "whoami",
+        "hostname", "uname", "ps", "kill", "df", "du", "curl", "wget",
+        "nano", "diff", "uniq", "xargs", "base64",
+    ];
+    for (const bin of builtins) {
+        ensureFile(vfs, `/usr/bin/${bin}`, `#!/bin/sh\nexec builtin ${bin} "$@"\n`, 0o755);
+    }
+    // lsb_release script
+    ensureFile(vfs, "/usr/bin/lsb_release", "#!/bin/sh\nexec lsb_release \"$@\"\n", 0o755);
+}
+// ─── /var ─────────────────────────────────────────────────────────────────────
+function bootstrapVar(vfs) {
+    ensureDir(vfs, "/var");
+    ensureDir(vfs, "/var/log");
+    ensureDir(vfs, "/var/tmp");
+    ensureDir(vfs, "/var/run");
+    ensureDir(vfs, "/var/cache");
+    ensureDir(vfs, "/var/cache/apt");
+    ensureDir(vfs, "/var/cache/apt/archives");
+    ensureDir(vfs, "/var/lib");
+    ensureDir(vfs, "/var/lib/apt");
+    ensureDir(vfs, "/var/lib/apt/lists");
+    ensureDir(vfs, "/var/lib/dpkg");
+    ensureDir(vfs, "/var/lib/dpkg/info");
+    // dpkg status — starts empty, apt install populates it
+    ensureFile(vfs, "/var/lib/dpkg/status", "");
+    ensureFile(vfs, "/var/lib/dpkg/available", "");
+    // syslog stub
+    ensureFile(vfs, "/var/log/syslog", `${new Date().toUTCString()} fortune kernel: Virtual container started\n`);
+    ensureFile(vfs, "/var/log/auth.log", "");
+    ensureFile(vfs, "/var/log/dpkg.log", "");
+    ensureFile(vfs, "/var/log/apt/history.log", "");
+    ensureFile(vfs, "/var/log/apt/term.log", "");
+}
+// ─── /bin + /sbin symlinks ────────────────────────────────────────────────────
+function bootstrapBin(vfs) {
+    // On modern Debian/Ubuntu /bin is a symlink to /usr/bin
+    if (!vfs.exists("/bin")) {
+        vfs.symlink("/usr/bin", "/bin");
+    }
+    if (!vfs.exists("/sbin")) {
+        vfs.symlink("/usr/sbin", "/sbin");
+    }
+    if (!vfs.exists("/lib")) {
+        ensureDir(vfs, "/lib");
+    }
+    if (!vfs.exists("/lib64")) {
+        ensureDir(vfs, "/lib64");
+    }
+}
+// ─── /tmp ─────────────────────────────────────────────────────────────────────
+function bootstrapTmp(vfs) {
+    ensureDir(vfs, "/tmp", 0o1777);
+}
+// ─── /root ────────────────────────────────────────────────────────────────────
+function bootstrapRoot(vfs) {
+    ensureDir(vfs, "/root", 0o700);
+    ensureFile(vfs, "/root/.bashrc", `${[
+        "# root .bashrc",
+        "export PS1='\\[\\033[0;31m\\]\\u@\\h\\[\\033[0m\\]:\\[\\033[0;34m\\]\\w\\[\\033[0m\\]# '",
+        "export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+        "alias ll='ls -la'",
+        "alias la='ls -A'",
+    ].join("\n")}\n`);
+    ensureFile(vfs, "/root/.profile", "[ -f ~/.bashrc ] && . ~/.bashrc\n");
+    // Fix: /home/root should map to /root for root user
+    if (!vfs.exists("/home/root")) {
+        vfs.symlink("/root", "/home/root");
+    }
+}
+// ─── /opt + /srv + /mnt + /media ─────────────────────────────────────────────
+function bootstrapMisc(vfs) {
+    ensureDir(vfs, "/opt");
+    ensureDir(vfs, "/srv");
+    ensureDir(vfs, "/mnt");
+    ensureDir(vfs, "/media");
+}
+// ─── main entry point ─────────────────────────────────────────────────────────
+/**
+ * Bootstraps the full Linux rootfs hierarchy in the VFS.
+ * Safe to call multiple times — idempotent.
+ *
+ * @param vfs Target virtual filesystem.
+ * @param users User manager (for /etc/passwd sync).
+ * @param hostname Virtual hostname.
+ * @param props Shell properties (kernel, os, arch).
+ * @param shellStartTime Unix ms of shell creation (for uptime).
+ */
+export function bootstrapLinuxRootfs(vfs, users, hostname, props, shellStartTime) {
+    bootstrapEtc(vfs, hostname, props);
+    bootstrapSys(vfs, props);
+    bootstrapDev(vfs);
+    bootstrapUsr(vfs);
+    bootstrapVar(vfs);
+    bootstrapBin(vfs);
+    bootstrapTmp(vfs);
+    bootstrapRoot(vfs);
+    bootstrapMisc(vfs);
+    refreshProc(vfs, props, hostname, shellStartTime);
+    syncEtcPasswd(vfs, users);
+}

package/dist/modules/neofetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"neofetch.d.ts","sourceRoot":"","sources":["../../src/modules/neofetch.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAsGvD,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAkKD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CA0E9D"}
+{"version":3,"file":"neofetch.d.ts","sourceRoot":"","sources":["../../src/modules/neofetch.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAsGvD,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAkKD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CA2E9D"}

package/dist/modules/neofetch.js

@@ -255,6 +255,7 @@ export function buildNeofetchOutput(info) {
         `Kernel: ${fields.kernel}`,
         `Uptime: ${uptime}`,
         // `Packages: ${fields.packages}`,
+        `Packages: ${fields.packages}`,
         `Shell: ${fields.shell}`,
         // `Shell Props: ${fields.shellProps}`,
         `Resolution: ${fields.resolution}`,

package/dist/standalone.js

@@ -1,6 +1,9 @@
 import { VirtualSftpServer, VirtualShell, VirtualSshServer } from ".";
 const hostname = process.env.SSH_MIMIC_HOSTNAME ?? "typescript-vm";
-const virtualShell = new VirtualShell(hostname);
+const virtualShell = new VirtualShell(hostname, undefined, {
+    mode: "fs",
+    snapshotPath: ".vfs",
+});
 virtualShell.addCommand("demo", [], () => {
     return {
         stdout: "This is a demo command. It does nothing useful.",

package/package.json

@@ -4,7 +4,7 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
-  "version": "1.2.7",
+  "version": "1.2.9",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -25,6 +25,7 @@
     "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",

package/src/SSHMimic/executor.ts

@@ -1,4 +1,4 @@
-import { runCommand as runSingleCommand } from "../commands";
+import { runCommandDirect } from "../commands";
 import { resolvePath } from "../commands/helpers";
 import type { CommandMode, CommandResult, ShellEnv } from "../types/commands";
 import type { Pipeline, PipelineCommand, Script, Statement } from "../types/pipeline";
@@ -117,8 +117,7 @@ async function executeSingleCommandWithRedirections(
 		catch { return { stderr: `${cmd.inputFile}: No such file or directory`, exitCode: 1 }; }
 	}
 
-	const rawInput = [cmd.name, ...cmd.args].join(" ");
-	const result = await runSingleCommand(rawInput, authUser, hostname, mode, cwd, shell, stdin, env);
+	const result = await runCommandDirect(cmd.name, cmd.args, authUser, hostname, mode, cwd, shell, stdin, env);
 
 	if (cmd.outputFile) {
 		const outputPath = resolvePath(cwd, cmd.outputFile);
@@ -160,8 +159,7 @@ async function executePipelineChain(
 			catch { return { stderr: `${cmd.inputFile}: No such file or directory`, exitCode: 1 }; }
 		}
 
-		const rawInput = [cmd.name, ...cmd.args].join(" ");
-		const result = await runSingleCommand(rawInput, authUser, hostname, mode, cwd, shell, currentOutput, env);
+		const result = await runCommandDirect(cmd.name, cmd.args, authUser, hostname, mode, cwd, shell, currentOutput, env);
 		exitCode = result.exitCode ?? 0;
 
 		if (i === commands.length - 1 && cmd.outputFile) {

package/src/VirtualFileSystem/binaryPack.ts

@@ -0,0 +1,219 @@
+/**
+ * Binary serialisation format for VirtualFileSystem snapshots.
+ *
+ * Replaces the JSON+base64 approach. No external dependencies.
+ *
+ * Wire format (little-endian throughout):
+ *
+ *   File header:
+ *     [4]  magic  = 0x56 0x46 0x53 0x21  ("VFS!")
+ *     [1]  version = 0x01
+ *
+ *   Node (recursive):
+ *     [1]  type    = 0x01 (file) | 0x02 (directory)
+ *     [2]  name length (uint16)
+ *     [N]  name bytes (utf8)
+ *     [4]  mode (uint32)
+ *     [8]  createdAt ms (float64)
+ *     [8]  updatedAt ms (float64)
+ *
+ *   File node extra:
+ *     [1]  compressed flag (0x00 | 0x01)
+ *     [4]  content length (uint32)
+ *     [N]  content bytes (raw — no base64)
+ *
+ *   Directory node extra:
+ *     [4]  children count (uint32)
+ *     [N]  children nodes (recursive)
+ *
+ * Total overhead vs JSON+base64 for 1 MB of file data:
+ *   JSON+base64 :  ~1.37 MB (base64 33% bloat) + JSON string wrapping
+ *   Binary pack :  ~1.00 MB + ~40 bytes/node header  → ~27% smaller, no string parsing
+ */
+
+import type { InternalDirectoryNode, InternalFileNode, InternalNode } from "./internalTypes";
+
+const MAGIC = Buffer.from([0x56, 0x46, 0x53, 0x21]); // "VFS!"
+const VERSION = 0x01;
+const TYPE_FILE = 0x01;
+const TYPE_DIR  = 0x02;
+
+// ── Encoder ───────────────────────────────────────────────────────────────────
+
+class Encoder {
+	private chunks: Buffer[] = [];
+
+	write(buf: Buffer): void { this.chunks.push(buf); }
+
+	writeUint8(n: number): void {
+		const b = Buffer.allocUnsafe(1);
+		b.writeUInt8(n, 0);
+		this.chunks.push(b);
+	}
+
+	writeUint16(n: number): void {
+		const b = Buffer.allocUnsafe(2);
+		b.writeUInt16LE(n, 0);
+		this.chunks.push(b);
+	}
+
+	writeUint32(n: number): void {
+		const b = Buffer.allocUnsafe(4);
+		b.writeUInt32LE(n, 0);
+		this.chunks.push(b);
+	}
+
+	writeFloat64(n: number): void {
+		const b = Buffer.allocUnsafe(8);
+		b.writeDoubleBE(n, 0);
+		this.chunks.push(b);
+	}
+
+	writeString(s: string): void {
+		const encoded = Buffer.from(s, "utf8");
+		this.writeUint16(encoded.length);
+		this.chunks.push(encoded);
+	}
+
+	writeBytes(bytes: Buffer): void {
+		this.writeUint32(bytes.length);
+		this.chunks.push(bytes);
+	}
+
+	toBuffer(): Buffer { return Buffer.concat(this.chunks); }
+}
+
+function encodeNode(enc: Encoder, node: InternalNode): void {
+	if (node.type === "file") {
+		const f = node as InternalFileNode;
+		enc.writeUint8(TYPE_FILE);
+		enc.writeString(f.name);
+		enc.writeUint32(f.mode);
+		enc.writeFloat64(f.createdAt.getTime());
+		enc.writeFloat64(f.updatedAt.getTime());
+		enc.writeUint8(f.compressed ? 0x01 : 0x00);
+		enc.writeBytes(f.content);
+	} else {
+		const d = node as InternalDirectoryNode;
+		enc.writeUint8(TYPE_DIR);
+		enc.writeString(d.name);
+		enc.writeUint32(d.mode);
+		enc.writeFloat64(d.createdAt.getTime());
+		enc.writeFloat64(d.updatedAt.getTime());
+		const children = Array.from(d.children.values());
+		enc.writeUint32(children.length);
+		for (const child of children) encodeNode(enc, child);
+	}
+}
+
+/**
+ * Serialise an in-memory VFS root to a compact binary Buffer.
+ * No base64, no JSON. ~27% smaller than the JSON+base64 format for typical VFS trees.
+ */
+export function encodeVfs(root: InternalDirectoryNode): Buffer {
+	const enc = new Encoder();
+	enc.write(MAGIC);
+	enc.writeUint8(VERSION);
+	encodeNode(enc, root);
+	return enc.toBuffer();
+}
+
+// ── Decoder ───────────────────────────────────────────────────────────────────
+
+class Decoder {
+	private pos = 0;
+	constructor(private readonly buf: Buffer) {}
+
+	readUint8(): number { return this.buf.readUInt8(this.pos++); }
+
+	readUint16(): number {
+		const v = this.buf.readUInt16LE(this.pos);
+		this.pos += 2;
+		return v;
+	}
+
+	readUint32(): number {
+		const v = this.buf.readUInt32LE(this.pos);
+		this.pos += 4;
+		return v;
+	}
+
+	readFloat64(): number {
+		const v = this.buf.readDoubleBE(this.pos);
+		this.pos += 8;
+		return v;
+	}
+
+	readString(): string {
+		const len = this.readUint16();
+		const s = this.buf.toString("utf8", this.pos, this.pos + len);
+		this.pos += len;
+		return s;
+	}
+
+	readBytes(): Buffer {
+		const len = this.readUint32();
+		const b = this.buf.slice(this.pos, this.pos + len);
+		this.pos += len;
+		return b;
+	}
+
+	remaining(): number { return this.buf.length - this.pos; }
+}
+
+function decodeNode(dec: Decoder): InternalNode {
+	const type = dec.readUint8();
+	const name = dec.readString();
+	const mode = dec.readUint32();
+	const createdAt = new Date(dec.readFloat64());
+	const updatedAt = new Date(dec.readFloat64());
+
+	if (type === TYPE_FILE) {
+		const compressed = dec.readUint8() === 0x01;
+		const content = dec.readBytes();
+		return { type: "file", name, mode, createdAt, updatedAt, compressed, content } satisfies InternalFileNode;
+	}
+
+	if (type === TYPE_DIR) {
+		const count = dec.readUint32();
+		const children = new Map<string, InternalNode>();
+		for (let i = 0; i < count; i++) {
+			const child = decodeNode(dec);
+			children.set(child.name, child);
+		}
+		return { type: "directory", name, mode, createdAt, updatedAt, children } satisfies InternalDirectoryNode;
+	}
+
+	throw new Error(`[VFS binary] Unknown node type: 0x${type.toString(16)}`);
+}
+
+/**
+ * Deserialise a binary Buffer produced by {@link encodeVfs} back into an
+ * InternalDirectoryNode tree. Throws on magic/version mismatch or truncation.
+ */
+export function decodeVfs(buf: Buffer): InternalDirectoryNode {
+	if (buf.length < 5) throw new Error("[VFS binary] Buffer too short");
+
+	const magic = buf.slice(0, 4);
+	if (!magic.equals(MAGIC)) {
+		throw new Error("[VFS binary] Invalid magic — not a VFS binary snapshot");
+	}
+
+	const dec = new Decoder(buf);
+	// skip magic (4) + version (1)
+	for (let i = 0; i < 5; i++) dec.readUint8();
+
+	const root = decodeNode(dec);
+	if (root.type !== "directory") {
+		throw new Error("[VFS binary] Root node must be a directory");
+	}
+	return root as InternalDirectoryNode;
+}
+
+/**
+ * Returns true if `buf` looks like a VFS binary snapshot (starts with magic bytes).
+ * Used to auto-detect format when loading from disk.
+ */
+export function isBinarySnapshot(buf: Buffer): boolean {
+	return buf.length >= 4 && buf.slice(0, 4).equals(MAGIC);
+}

package/src/VirtualFileSystem/index.ts

@@ -7,6 +7,7 @@ import type {
 	InternalFileNode,
 	InternalNode,
 } from "./internalTypes";
+import { decodeVfs, encodeVfs, isBinarySnapshot } from "./binaryPack";
 import { getNode, getParentDirectory, normalizePath } from "./path";
 import type {
 	RemoveOptions,
@@ -24,8 +25,8 @@ import type {
  * "memory" — pure in-memory, no disk I/O (default).
  *
  * "fs"     — mirrors the VFS tree to a directory on the host filesystem.
- *             `snapshotPath` must be set to the directory where the JSON
- *             snapshot file will be read/written.
+ *             `snapshotPath` must be set to the directory where the binary
+ *             snapshot file will be read/written (`vfs-snapshot.vfsb`).
  */
 export type VfsPersistenceMode = "memory" | "fs";
 
@@ -53,7 +54,7 @@ export interface VfsOptions {
  * **Memory mode** (default) — all state lives in a fast recursive tree.
  * Use `toSnapshot()` / `fromSnapshot()` / `importSnapshot()` for serialisation.
  *
- * **FS mode** — same in-memory tree, but `restoreMirror()` loads a JSON
+ * **FS mode** — same in-memory tree, but `restoreMirror()` loads a binary
  * snapshot from disk and `flushMirror()` writes it back.  This gives you
  * persistent VFS state across process restarts without any real POSIX filesystem
  * semantics leaking through.
@@ -86,7 +87,7 @@ class VirtualFileSystem extends EventEmitter {
 			}
 			this.snapshotFile = path.resolve(
 				options.snapshotPath,
-				"vfs-snapshot.json",
+				"vfs-snapshot.vfsb",
 			);
 		} else {
 			this.snapshotFile = null;
@@ -151,7 +152,8 @@ class VirtualFileSystem extends EventEmitter {
 	// ── Persistence ───────────────────────────────────────────────────────────
 
 	/**
-	 * In `"fs"` mode: reads the JSON snapshot from disk and hydrates the tree.
+	 * In `"fs"` mode: reads the binary snapshot (`vfs-snapshot.vfsb`) from disk.
+	 * Automatically falls back to legacy JSON format for backward compatibility.
 	 * Silently succeeds when the snapshot file does not exist yet.
 	 *
 	 * In `"memory"` mode: no-op (kept for API compatibility).
@@ -162,9 +164,16 @@ class VirtualFileSystem extends EventEmitter {
 		if (!fsSync.existsSync(this.snapshotFile)) return;
 
 		try {
-			const raw = fsSync.readFileSync(this.snapshotFile, "utf8");
-			const snapshot: VfsSnapshot = JSON.parse(raw);
-			this.root = this.deserializeDir(snapshot.root, "");
+			const raw = fsSync.readFileSync(this.snapshotFile);
+			if (isBinarySnapshot(raw)) {
+				// Fast binary format (current)
+				this.root = decodeVfs(raw);
+			} else {
+				// Legacy JSON fallback — auto-migrates on next flushMirror()
+				const snapshot: VfsSnapshot = JSON.parse(raw.toString("utf8"));
+				this.root = this.deserializeDir(snapshot.root, "");
+				console.info("[VirtualFileSystem] Migrating legacy JSON snapshot to binary format.");
+			}
 			this.emit("snapshot:restore", { path: this.snapshotFile });
 		} catch (err) {
 			// Corrupt or unreadable snapshot — start fresh and warn
@@ -176,7 +185,8 @@ class VirtualFileSystem extends EventEmitter {
 	}
 
 	/**
-	 * In `"fs"` mode: serialises the in-memory tree to a JSON snapshot on disk.
+	 * In `"fs"` mode: serialises the in-memory tree to a binary snapshot on disk
+	 * (`vfs-snapshot.vfsb`). ~27% smaller and significantly faster than JSON+base64.
 	 * The directory is created if it does not exist.
 	 *
 	 * In `"memory"` mode: emits `"mirror:flush"` and returns (no disk write).
@@ -189,8 +199,8 @@ class VirtualFileSystem extends EventEmitter {
 
 		const dir = path.dirname(this.snapshotFile);
 		fsSync.mkdirSync(dir, { recursive: true });
-		const snapshot = this.toSnapshot();
-		fsSync.writeFileSync(this.snapshotFile, JSON.stringify(snapshot), "utf8");
+		const binary = encodeVfs(this.root);
+		fsSync.writeFileSync(this.snapshotFile, binary);
 		this.emit("mirror:flush", { path: this.snapshotFile });
 	}