typescript-virtual-container 1.2.4 → 1.2.5

package/dist/VirtualFileSystem/index.js

@@ -1,371 +1,519 @@
 import { EventEmitter } from "node:events";
-import * as fs from "node:fs";
+import * as fsSync from "node:fs";
 import * as path from "node:path";
 import { gunzipSync, gzipSync } from "node:zlib";
-import { createPerfLogger } from "../utils/perfLogger";
-import { normalizePath } from "./path";
+import { getNode, getParentDirectory, normalizePath } from "./path";
+// ── VirtualFileSystem ─────────────────────────────────────────────────────────
 /**
- * In-memory virtual filesystem with tar.gz mirror persistence.
+ * In-memory virtual filesystem with optional JSON-snapshot persistence.
  *
- * Paths are normalized to POSIX-like absolute paths. Use
- * {@link VirtualFileSystem.restoreMirror} on startup and
- * {@link VirtualFileSystem.flushMirror} to persist pending changes.
+ * **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
+ * 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.
+ *
+ * @example
+ * ```ts
+ * // Pure in-memory (default)
+ * const vfs = new VirtualFileSystem();
+ *
+ * // With disk persistence
+ * const vfs = new VirtualFileSystem({ mode: "fs", snapshotPath: "./data" });
+ * await vfs.restoreMirror(); // load from disk (no-op if no snapshot yet)
+ * // ... use vfs ...
+ * await vfs.flushMirror();  // persist to disk
+ * ```
  */
-const perf = createPerfLogger("VirtualFileSystem");
 class VirtualFileSystem extends EventEmitter {
-    mirrorRoot;
-    ensureMirrorRoot() {
-        fs.mkdirSync(this.mirrorRoot, { recursive: true, mode: 0o755 });
-    }
-    resolveFsPath(targetPath) {
-        const normalized = normalizePath(targetPath);
-        const relativePath = normalized.slice(1);
-        const resolved = path.resolve(this.mirrorRoot, relativePath || ".");
-        const relative = path.relative(this.mirrorRoot, resolved);
-        if (relative.startsWith("..") || path.isAbsolute(relative)) {
-            throw new Error(`Invalid path '${targetPath}'.`);
-        }
-        return resolved;
-    }
-    detectGzipFile(targetPath) {
-        const fd = fs.openSync(targetPath, "r");
-        try {
-            const header = Buffer.alloc(2);
-            const bytesRead = fs.readSync(fd, header, 0, 2, 0);
-            return bytesRead === 2 && header[0] === 0x1f && header[1] === 0x8b;
+    root;
+    mode;
+    snapshotFile;
+    constructor(options = {}) {
+        super();
+        this.mode = options.mode ?? "memory";
+        if (this.mode === "fs") {
+            if (!options.snapshotPath) {
+                throw new Error('VirtualFileSystem: "snapshotPath" is required when mode is "fs".');
+            }
+            this.snapshotFile = path.resolve(options.snapshotPath, "vfs-snapshot.json");
         }
-        finally {
-            fs.closeSync(fd);
+        else {
+            this.snapshotFile = null;
         }
+        this.root = this.makeDir("", 0o755);
     }
-    computeDiskUsageBytes(targetPath) {
-        const stats = fs.statSync(targetPath);
-        if (stats.isFile()) {
-            return stats.size;
-        }
-        let total = 0;
-        for (const entry of fs.readdirSync(targetPath)) {
-            total += this.computeDiskUsageBytes(path.join(targetPath, entry));
-        }
-        return total;
+    // ── Internal helpers ──────────────────────────────────────────────────────
+    makeDir(name, mode) {
+        const now = new Date();
+        return {
+            type: "directory",
+            name,
+            mode,
+            createdAt: now,
+            updatedAt: now,
+            children: new Map(),
+        };
     }
-    renderTreeLines(targetPath, label) {
-        const lines = [label];
-        const walk = (currentPath, prefix) => {
-            const entries = fs
-                .readdirSync(currentPath, { withFileTypes: true })
-                .map((entry) => entry.name)
-                .sort((left, right) => left.localeCompare(right));
-            for (let i = 0; i < entries.length; i += 1) {
-                const name = entries[i];
-                const isLast = i === entries.length - 1;
-                const connector = isLast ? "└── " : "├── ";
-                const nextPrefix = `${prefix}${isLast ? "    " : "│   "}`;
-                const entryPath = path.join(currentPath, name);
-                const isDirectory = fs.statSync(entryPath).isDirectory();
-                lines.push(`${prefix}${connector}${name}`);
-                if (isDirectory) {
-                    walk(entryPath, nextPrefix);
-                }
-            }
+    makeFile(name, content, mode, compressed) {
+        const now = new Date();
+        return {
+            type: "file",
+            name,
+            content,
+            mode,
+            compressed,
+            createdAt: now,
+            updatedAt: now,
         };
-        walk(targetPath, "");
-        return lines.join("\n");
     }
-    /**
-     * Creates a virtual filesystem instance.
-     *
-     * @param baseDir Base directory used to resolve mirror archive location.
-     */
-    constructor(baseDir = process.cwd()) {
-        super();
-        perf.mark("constructor");
-        this.mirrorRoot = path.resolve(baseDir, ".vfs", "mirror");
+    mkdirRecursive(targetPath, mode) {
+        const normalized = normalizePath(targetPath);
+        if (normalized === "/")
+            return;
+        const parts = normalized.split("/").filter(Boolean);
+        let current = this.root;
+        let builtPath = "";
+        for (const part of parts) {
+            builtPath += `/${part}`;
+            let child = current.children.get(part);
+            if (!child) {
+                child = this.makeDir(part, mode);
+                current.children.set(part, child);
+                this.emit("dir:create", { path: builtPath, mode });
+            }
+            else if (child.type !== "directory") {
+                throw new Error(`Cannot create directory '${builtPath}': path is a file.`);
+            }
+            current = child;
+        }
     }
+    // ── Persistence ───────────────────────────────────────────────────────────
     /**
-     * Restores filesystem state from mirror archive.
+     * In `"fs"` mode: reads the JSON snapshot from disk and hydrates the tree.
+     * Silently succeeds when the snapshot file does not exist yet.
      *
-     * If archive does not exist or cannot be read, creates fresh mirror file.
+     * In `"memory"` mode: no-op (kept for API compatibility).
      */
     async restoreMirror() {
-        perf.mark("restoreMirror");
-        this.ensureMirrorRoot();
+        if (this.mode !== "fs" || !this.snapshotFile)
+            return;
+        if (!fsSync.existsSync(this.snapshotFile))
+            return;
+        try {
+            const raw = fsSync.readFileSync(this.snapshotFile, "utf8");
+            const snapshot = JSON.parse(raw);
+            this.root = this.deserializeDir(snapshot.root, "");
+            this.emit("snapshot:restore", { path: this.snapshotFile });
+        }
+        catch (err) {
+            // Corrupt or unreadable snapshot — start fresh and warn
+            console.warn(`[VirtualFileSystem] Could not restore snapshot from ${this.snapshotFile}:`, err instanceof Error ? err.message : String(err));
+        }
     }
     /**
-     * Persists current filesystem state to mirror archive.
+     * In `"fs"` mode: serialises the in-memory tree to a JSON snapshot on disk.
+     * The directory is created if it does not exist.
      *
-     * No-op when nothing changed and archive already exists.
+     * In `"memory"` mode: emits `"mirror:flush"` and returns (no disk write).
      */
     async flushMirror() {
-        perf.mark("flushMirror");
-        this.ensureMirrorRoot();
-        this.emit("mirror:flush");
+        if (this.mode !== "fs" || !this.snapshotFile) {
+            this.emit("mirror:flush");
+            return;
+        }
+        const dir = path.dirname(this.snapshotFile);
+        fsSync.mkdirSync(dir, { recursive: true });
+        const snapshot = this.toSnapshot();
+        fsSync.writeFileSync(this.snapshotFile, JSON.stringify(snapshot), "utf8");
+        this.emit("mirror:flush", { path: this.snapshotFile });
     }
-    /**
-     * Creates directory and any missing parent directories.
-     *
-     * @param targetPath Absolute or relative path to directory.
-     * @param mode POSIX-like mode bits for new directories.
-     */
+    /** Returns the current persistence mode. */
+    getMode() {
+        return this.mode;
+    }
+    /** Returns the snapshot file path used in `"fs"` mode, or `null`. */
+    getSnapshotPath() {
+        return this.snapshotFile;
+    }
+    // ── Public filesystem API ─────────────────────────────────────────────────
+    /** Creates a directory (and any missing parents). */
     mkdir(targetPath, mode = 0o755) {
-        perf.mark("mkdir");
-        this.ensureMirrorRoot();
-        const fsPath = this.resolveFsPath(targetPath);
-        if (fs.existsSync(fsPath) && !fs.statSync(fsPath).isDirectory()) {
-            throw new Error(`Cannot create directory '${normalizePath(targetPath)}': path is a file.`);
+        const normalized = normalizePath(targetPath);
+        const existing = (() => {
+            try {
+                return getNode(this.root, normalized);
+            }
+            catch {
+                return null;
+            }
+        })();
+        if (existing && existing.type !== "directory") {
+            throw new Error(`Cannot create directory '${normalized}': path is a file.`);
         }
-        fs.mkdirSync(fsPath, { recursive: true, mode });
-        this.emit("dir:create", { path: normalizePath(targetPath), mode });
+        this.mkdirRecursive(normalized, mode);
     }
     /**
-     * Writes UTF-8 text or binary content into file.
-     *
+     * Writes UTF-8 text or binary content into a file.
      * Parent directories are created when missing.
-     *
-     * @param targetPath Destination file path.
-     * @param content File content as string or Buffer.
-     * @param options Optional write behavior (mode, compression).
      */
     writeFile(targetPath, content, options = {}) {
-        perf.mark("writeFile");
-        this.ensureMirrorRoot();
         const normalized = normalizePath(targetPath);
-        const fsPath = this.resolveFsPath(normalized);
-        const parentPath = path.dirname(fsPath);
-        fs.mkdirSync(parentPath, { recursive: true, mode: 0o755 });
+        const { parent, name } = getParentDirectory(this.root, normalized, true, (p) => this.mkdirRecursive(p, 0o755));
+        const existing = parent.children.get(name);
+        if (existing?.type === "directory") {
+            throw new Error(`Cannot write file '${normalized}': path is a directory.`);
+        }
         const rawContent = Buffer.isBuffer(content)
             ? content
             : Buffer.from(content, "utf8");
         const shouldCompress = options.compress ?? false;
         const storedContent = shouldCompress ? gzipSync(rawContent) : rawContent;
-        if (fs.existsSync(fsPath) && fs.statSync(fsPath).isDirectory()) {
-            throw new Error(`Cannot write file '${normalized}': path is a directory.`);
+        const mode = options.mode ?? 0o644;
+        if (existing) {
+            const f = existing;
+            f.content = storedContent;
+            f.compressed = shouldCompress;
+            f.mode = mode;
+            f.updatedAt = new Date();
+        }
+        else {
+            parent.children.set(name, this.makeFile(name, storedContent, mode, shouldCompress));
         }
-        fs.writeFileSync(fsPath, storedContent);
-        fs.chmodSync(fsPath, options.mode ?? 0o644);
         this.emit("file:write", { path: normalized, size: storedContent.length });
     }
     /**
-     * Reads file content as UTF-8 text.
-     *
-     * Compressed files are transparently decompressed.
-     *
-     * @param targetPath Path to file.
-     * @returns UTF-8 string content.
+     * Reads file content as a UTF-8 string.
+     * Gzip-compressed files are transparently decompressed.
      */
     readFile(targetPath) {
-        perf.mark("readFile");
-        this.ensureMirrorRoot();
-        const fsPath = this.resolveFsPath(targetPath);
-        if (!fs.existsSync(fsPath) || !fs.statSync(fsPath).isFile()) {
+        const normalized = normalizePath(targetPath);
+        const node = getNode(this.root, normalized);
+        if (node.type !== "file") {
             throw new Error(`Cannot read '${targetPath}': not a file.`);
         }
-        const stored = fs.readFileSync(fsPath);
-        const raw = this.detectGzipFile(fsPath) ? gunzipSync(stored) : stored;
-        const normalized = normalizePath(targetPath);
+        const f = node;
+        const raw = f.compressed ? gunzipSync(f.content) : f.content;
         this.emit("file:read", { path: normalized, size: raw.length });
         return raw.toString("utf8");
     }
-    /**
-     * Checks whether node exists at path.
-     *
-     * @param targetPath Node path.
-     * @returns True when file or directory exists.
-     */
+    /** Reads file content as a Buffer (decompresses if needed). */
+    readFileRaw(targetPath) {
+        const normalized = normalizePath(targetPath);
+        const node = getNode(this.root, normalized);
+        if (node.type !== "file") {
+            throw new Error(`Cannot read '${targetPath}': not a file.`);
+        }
+        const f = node;
+        const raw = f.compressed ? gunzipSync(f.content) : f.content;
+        this.emit("file:read", { path: normalized, size: raw.length });
+        return raw;
+    }
+    /** Returns true when a file or directory exists at path. */
     exists(targetPath) {
-        perf.mark("exists");
         try {
-            const fsPath = this.resolveFsPath(targetPath);
-            return fs.existsSync(fsPath);
+            getNode(this.root, normalizePath(targetPath));
+            return true;
         }
         catch {
             return false;
         }
     }
-    /**
-     * Updates mode bits for file or directory.
-     *
-     * @param targetPath Node path.
-     * @param mode New POSIX-like mode.
-     */
+    /** Updates mode bits on a node. */
     chmod(targetPath, mode) {
-        perf.mark("chmod");
-        const fsPath = this.resolveFsPath(targetPath);
-        if (!fs.existsSync(fsPath)) {
-            throw new Error(`Path '${normalizePath(targetPath)}' does not exist.`);
-        }
-        fs.chmodSync(fsPath, mode);
+        getNode(this.root, normalizePath(targetPath)).mode = mode;
     }
-    /**
-     * Returns metadata for file or directory.
-     *
-     * @param targetPath Node path.
-     * @returns Typed stat object based on node type.
-     */
+    /** Returns metadata for a file or directory. */
     stat(targetPath) {
-        perf.mark("stat");
-        this.ensureMirrorRoot();
         const normalized = normalizePath(targetPath);
-        const fsPath = this.resolveFsPath(normalized);
-        if (!fs.existsSync(fsPath)) {
-            throw new Error(`Path '${normalized}' does not exist.`);
-        }
-        const stats = fs.statSync(fsPath);
-        const mode = stats.mode & 0o777;
+        const node = getNode(this.root, normalized);
         const name = normalized === "/" ? "" : path.posix.basename(normalized);
-        if (stats.isFile()) {
+        if (node.type === "file") {
+            const f = node;
             return {
                 type: "file",
                 name,
                 path: normalized,
-                mode,
-                createdAt: stats.birthtime,
-                updatedAt: stats.mtime,
-                compressed: this.detectGzipFile(fsPath),
-                size: stats.size,
+                mode: f.mode,
+                createdAt: f.createdAt,
+                updatedAt: f.updatedAt,
+                compressed: f.compressed,
+                size: f.content.length,
             };
         }
+        const d = node;
         return {
             type: "directory",
             name,
             path: normalized,
-            mode,
-            createdAt: stats.birthtime,
-            updatedAt: stats.mtime,
-            childrenCount: fs.readdirSync(fsPath).length,
+            mode: d.mode,
+            createdAt: d.createdAt,
+            updatedAt: d.updatedAt,
+            childrenCount: d.children.size,
         };
     }
-    /**
-     * Lists direct children names of directory.
-     *
-     * @param dirPath Directory path, defaults to root.
-     * @returns Sorted child names.
-     */
+    /** Lists direct children names of a directory (sorted). */
     list(dirPath = "/") {
-        perf.mark("list");
-        const fsPath = this.resolveFsPath(dirPath);
-        if (!fs.existsSync(fsPath) || !fs.statSync(fsPath).isDirectory()) {
+        const normalized = normalizePath(dirPath);
+        const node = getNode(this.root, normalized);
+        if (node.type !== "directory") {
             throw new Error(`Cannot list '${dirPath}': not a directory.`);
         }
-        return fs.readdirSync(fsPath).sort();
+        return Array.from(node.children.keys()).sort();
     }
-    /**
-     * Renders ASCII tree view of directory hierarchy.
-     *
-     * @param dirPath Directory path, defaults to root.
-     * @returns Multi-line tree string.
-     */
+    /** Renders ASCII tree view of a directory hierarchy. */
     tree(dirPath = "/") {
-        perf.mark("tree");
-        const fsPath = this.resolveFsPath(dirPath);
-        if (!fs.existsSync(fsPath) || !fs.statSync(fsPath).isDirectory()) {
+        const normalized = normalizePath(dirPath);
+        const node = getNode(this.root, normalized);
+        if (node.type !== "directory") {
             throw new Error(`Cannot render tree for '${dirPath}': not a directory.`);
         }
-        const rootLabel = dirPath === "/" ? "/" : path.posix.basename(normalizePath(dirPath));
-        return this.renderTreeLines(fsPath, rootLabel);
+        const label = dirPath === "/" ? "/" : path.posix.basename(normalized);
+        return this.renderTreeLines(node, label);
     }
-    /**
-     * Computes total stored file bytes under a path.
-     *
-     * File usage is based on in-memory stored bytes, including compressed
-     * payload size when files are marked as compressed.
-     *
-     * @param targetPath File or directory path to measure, defaults to root.
-     * @returns Total byte usage for file content under target path.
-     */
+    renderTreeLines(dir, label) {
+        const lines = [label];
+        const entries = Array.from(dir.children.keys()).sort();
+        for (let i = 0; i < entries.length; i++) {
+            const name = entries[i];
+            const child = dir.children.get(name);
+            const isLast = i === entries.length - 1;
+            const connector = isLast ? "└── " : "├── ";
+            const nextPrefix = isLast ? "    " : "│   ";
+            lines.push(`${connector}${name}`);
+            if (child.type === "directory") {
+                const sub = this.renderTreeLines(child, "")
+                    .split("\n")
+                    .slice(1)
+                    .map((l) => `${nextPrefix}${l}`);
+                lines.push(...sub);
+            }
+        }
+        return lines.join("\n");
+    }
+    /** Computes total stored bytes under a path. */
     getUsageBytes(targetPath = "/") {
-        perf.mark("getUsageBytes");
-        const fsPath = this.resolveFsPath(targetPath);
-        if (!fs.existsSync(fsPath)) {
-            throw new Error(`Path '${normalizePath(targetPath)}' does not exist.`);
+        return this.computeUsage(getNode(this.root, normalizePath(targetPath)));
+    }
+    computeUsage(node) {
+        if (node.type === "file")
+            return node.content.length;
+        let total = 0;
+        for (const child of node.children.values()) {
+            total += this.computeUsage(child);
         }
-        return this.computeDiskUsageBytes(fsPath);
+        return total;
     }
-    /**
-     * Compresses file content with gzip and flags node as compressed.
-     *
-     * @param targetPath Path to file.
-     */
+    /** Compresses a file's content with gzip in place. */
     compressFile(targetPath) {
-        perf.mark("compressFile");
-        const fsPath = this.resolveFsPath(targetPath);
-        if (!fs.existsSync(fsPath) || !fs.statSync(fsPath).isFile()) {
+        const node = getNode(this.root, normalizePath(targetPath));
+        if (node.type !== "file")
             throw new Error(`Cannot compress '${targetPath}': not a file.`);
+        const f = node;
+        if (!f.compressed) {
+            f.content = gzipSync(f.content);
+            f.compressed = true;
+            f.updatedAt = new Date();
         }
-        if (!this.detectGzipFile(fsPath)) {
-            const content = fs.readFileSync(fsPath);
-            fs.writeFileSync(fsPath, gzipSync(content));
+    }
+    /** Decompresses a gzip-compressed file in place. */
+    decompressFile(targetPath) {
+        const node = getNode(this.root, normalizePath(targetPath));
+        if (node.type !== "file")
+            throw new Error(`Cannot decompress '${targetPath}': not a file.`);
+        const f = node;
+        if (f.compressed) {
+            f.content = gunzipSync(f.content);
+            f.compressed = false;
+            f.updatedAt = new Date();
         }
     }
     /**
-     * Decompresses gzip-compressed file content.
-     *
-     * @param targetPath Path to file.
+     * Creates a symbolic link.
+     * The link node is stored with mode `0o120777` (POSIX symlink convention).
      */
-    decompressFile(targetPath) {
-        perf.mark("decompressFile");
-        const fsPath = this.resolveFsPath(targetPath);
-        if (!fs.existsSync(fsPath) || !fs.statSync(fsPath).isFile()) {
-            throw new Error(`Cannot decompress '${targetPath}': not a file.`);
+    symlink(targetPath, linkPath) {
+        const normalizedLink = normalizePath(linkPath);
+        const normalizedTarget = targetPath.startsWith("/")
+            ? normalizePath(targetPath)
+            : targetPath;
+        const { parent, name } = getParentDirectory(this.root, normalizedLink, true, (p) => this.mkdirRecursive(p, 0o755));
+        const symNode = {
+            type: "file",
+            name,
+            content: Buffer.from(normalizedTarget, "utf8"),
+            mode: 0o120777,
+            compressed: false,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+        };
+        parent.children.set(name, symNode);
+        this.emit("symlink:create", {
+            link: normalizedLink,
+            target: normalizedTarget,
+        });
+    }
+    /** Returns true when the path is a symbolic link node. */
+    isSymlink(targetPath) {
+        try {
+            const node = getNode(this.root, normalizePath(targetPath));
+            return node.type === "file" && node.mode === 0o120777;
         }
-        if (this.detectGzipFile(fsPath)) {
-            const content = fs.readFileSync(fsPath);
-            fs.writeFileSync(fsPath, gunzipSync(content));
+        catch {
+            return false;
         }
     }
     /**
-     * Removes file or directory node.
-     *
-     * @param targetPath Path to remove.
-     * @param options Removal options, including recursive delete.
+     * Resolves a symlink chain up to `maxDepth` hops.
+     * Throws when the chain is too long (circular links).
      */
+    resolveSymlink(linkPath, maxDepth = 8) {
+        let current = normalizePath(linkPath);
+        for (let depth = 0; depth < maxDepth; depth++) {
+            try {
+                const node = getNode(this.root, current);
+                if (node.type === "file" && node.mode === 0o120777) {
+                    const target = node.content.toString("utf8");
+                    current = target.startsWith("/")
+                        ? target
+                        : normalizePath(path.posix.join(path.posix.dirname(current), target));
+                    continue;
+                }
+            }
+            catch {
+                break;
+            }
+            return current;
+        }
+        throw new Error(`Too many levels of symbolic links: ${linkPath}`);
+    }
+    /** Removes a file or directory node. */
     remove(targetPath, options = {}) {
-        perf.mark("remove");
         const normalized = normalizePath(targetPath);
-        if (normalized === "/") {
+        if (normalized === "/")
             throw new Error("Cannot remove root directory.");
-        }
-        const fsPath = this.resolveFsPath(normalized);
-        if (!fs.existsSync(fsPath)) {
-            throw new Error(`Path '${normalized}' does not exist.`);
-        }
-        const stats = fs.statSync(fsPath);
-        if (stats.isDirectory() && !options.recursive) {
-            const entries = fs.readdirSync(fsPath);
-            if (entries.length > 0) {
+        const node = getNode(this.root, normalized);
+        if (node.type === "directory") {
+            const dir = node;
+            if (!options.recursive && dir.children.size > 0) {
                 throw new Error(`Directory '${normalized}' is not empty. Use recursive option.`);
             }
         }
-        if (stats.isDirectory()) {
-            fs.rmSync(fsPath, { recursive: options.recursive ?? false });
-        }
-        else {
-            fs.rmSync(fsPath);
-        }
+        const { parent, name } = getParentDirectory(this.root, normalized, false, () => { });
+        parent.children.delete(name);
+        this.emit("node:remove", { path: normalized });
     }
-    /**
-     * Moves or renames node to destination path.
-     *
-     * @param fromPath Existing source path.
-     * @param toPath Destination path.
-     */
+    /** Moves or renames a node. */
     move(fromPath, toPath) {
-        perf.mark("move");
         const fromNormalized = normalizePath(fromPath);
         const toNormalized = normalizePath(toPath);
         if (fromNormalized === "/" || toNormalized === "/") {
             throw new Error("Cannot move root directory.");
         }
-        const fromFsPath = this.resolveFsPath(fromNormalized);
-        const toFsPath = this.resolveFsPath(toNormalized);
-        if (!fs.existsSync(fromFsPath)) {
-            throw new Error(`Path '${fromNormalized}' does not exist.`);
-        }
-        if (fs.existsSync(toFsPath)) {
+        const node = getNode(this.root, fromNormalized);
+        if (this.exists(toNormalized)) {
             throw new Error(`Destination '${toNormalized}' already exists.`);
         }
-        fs.mkdirSync(path.dirname(toFsPath), { recursive: true, mode: 0o755 });
-        fs.renameSync(fromFsPath, toFsPath);
+        this.mkdirRecursive(path.posix.dirname(toNormalized), 0o755);
+        const { parent: destParent, name: destName } = getParentDirectory(this.root, toNormalized, false, () => { });
+        const { parent: srcParent, name: srcName } = getParentDirectory(this.root, fromNormalized, false, () => { });
+        srcParent.children.delete(srcName);
+        node.name = destName;
+        destParent.children.set(destName, node);
+    }
+    // ── Snapshot serialisation ─────────────────────────────────────────────────
+    /**
+     * Exports the entire filesystem as a JSON-serialisable snapshot.
+     *
+     * Works regardless of the persistence mode. Useful for test fixtures,
+     * manual backups, or passing VFS state between processes.
+     */
+    toSnapshot() {
+        return { root: this.serializeDir(this.root) };
+    }
+    serializeDir(dir) {
+        const children = [];
+        for (const child of dir.children.values()) {
+            children.push(child.type === "file"
+                ? this.serializeFile(child)
+                : this.serializeDir(child));
+        }
+        return {
+            type: "directory",
+            name: dir.name,
+            mode: dir.mode,
+            createdAt: dir.createdAt.toISOString(),
+            updatedAt: dir.updatedAt.toISOString(),
+            children,
+        };
+    }
+    serializeFile(file) {
+        return {
+            type: "file",
+            name: file.name,
+            mode: file.mode,
+            createdAt: file.createdAt.toISOString(),
+            updatedAt: file.updatedAt.toISOString(),
+            compressed: file.compressed,
+            contentBase64: file.content.toString("base64"),
+        };
+    }
+    /**
+     * Creates a new `VirtualFileSystem` instance (memory mode) from a snapshot.
+     *
+     * @example
+     * ```ts
+     * const vfs = VirtualFileSystem.fromSnapshot(savedSnapshot);
+     * ```
+     */
+    static fromSnapshot(snapshot) {
+        const vfs = new VirtualFileSystem();
+        vfs.root = vfs.deserializeDir(snapshot.root, "");
+        return vfs;
+    }
+    /**
+     * Replaces the current filesystem state with the content of a snapshot.
+     * The persistence mode is preserved.
+     *
+     * @example
+     * ```ts
+     * vfs.importSnapshot(savedSnapshot);
+     * ```
+     */
+    importSnapshot(snapshot) {
+        this.root = this.deserializeDir(snapshot.root, "");
+        this.emit("snapshot:import");
+    }
+    deserializeDir(snap, name) {
+        const dir = {
+            type: "directory",
+            name,
+            mode: snap.mode,
+            createdAt: new Date(snap.createdAt),
+            updatedAt: new Date(snap.updatedAt),
+            children: new Map(),
+        };
+        for (const child of snap.children) {
+            if (child.type === "file") {
+                const f = child;
+                dir.children.set(f.name, {
+                    type: "file",
+                    name: f.name,
+                    mode: f.mode,
+                    createdAt: new Date(f.createdAt),
+                    updatedAt: new Date(f.updatedAt),
+                    compressed: f.compressed,
+                    content: Buffer.from(f.contentBase64, "base64"),
+                });
+            }
+            else {
+                const sub = this.deserializeDir(child, child.name);
+                dir.children.set(child.name, sub);
+            }
+        }
+        return dir;
     }
 }
 export default VirtualFileSystem;