@componentor/fs 3.0.7 → 3.0.9

package/README.md

@@ -509,6 +509,20 @@ Make sure `opfsSync` is enabled (it's `true` by default). Files are mirrored to
 
 ## Changelog
 
+### v3.0.9 (2026)
+
+**Improvements:**
+- `unpackToOPFS`, `loadFromOPFS`, and `repairVFS` now accept an optional `fs` parameter (a running `VFSFileSystem` instance) so they work from any tab — leader or follower — without stopping the VFS
+- When `fs` is not provided, falls back to direct `.vfs.bin` access via VFSEngine (requires VFS to be stopped or a Worker context)
+- `repairVFS` with a running instance uses OPFS as source of truth: rebuilds VFS from OPFS, then syncs back for full consistency
+
+### v3.0.8 (2026)
+
+**Improvements:**
+- Add VFS helper functions: `unpackToOPFS`, `loadFromOPFS`, and `repairVFS` for VFS maintenance, migration, and recovery
+- Helpers work in both Worker (sync access handle) and main thread (in-memory buffer + async writable) contexts
+- Remove redundant I/O call in `unpackToOPFS` directory creation
+
 ### v3.0.7 (2026)
 
 **Fixes:**

package/dist/index.js

@@ -3236,6 +3236,86 @@ var VFSEngine = class {
 };
 
 // src/helpers.ts
+var MemoryHandle = class {
+  buf;
+  len;
+  constructor(initialData) {
+    if (initialData && initialData.byteLength > 0) {
+      this.buf = new Uint8Array(initialData);
+      this.len = initialData.byteLength;
+    } else {
+      this.buf = new Uint8Array(1024 * 1024);
+      this.len = 0;
+    }
+  }
+  getSize() {
+    return this.len;
+  }
+  read(target, opts) {
+    const offset = opts?.at ?? 0;
+    const dst = new Uint8Array(target.buffer, target.byteOffset, target.byteLength);
+    const bytesToRead = Math.min(dst.length, this.len - offset);
+    if (bytesToRead <= 0) return 0;
+    dst.set(this.buf.subarray(offset, offset + bytesToRead));
+    return bytesToRead;
+  }
+  write(data, opts) {
+    const offset = opts?.at ?? 0;
+    const src = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    const needed = offset + src.length;
+    if (needed > this.buf.length) {
+      this.grow(needed);
+    }
+    this.buf.set(src, offset);
+    if (needed > this.len) this.len = needed;
+    return src.length;
+  }
+  truncate(size) {
+    if (size > this.buf.length) {
+      this.grow(size);
+    }
+    if (size > this.len) {
+      this.buf.fill(0, this.len, size);
+    }
+    this.len = size;
+  }
+  flush() {
+  }
+  close() {
+  }
+  getBuffer() {
+    return this.buf.buffer.slice(0, this.len);
+  }
+  grow(minSize) {
+    const newSize = Math.max(minSize, this.buf.length * 2);
+    const newBuf = new Uint8Array(newSize);
+    newBuf.set(this.buf.subarray(0, this.len));
+    this.buf = newBuf;
+  }
+};
+async function openVFSHandle(fileHandle) {
+  try {
+    const handle = await fileHandle.createSyncAccessHandle();
+    return { handle, isMemory: false };
+  } catch {
+    const file = await fileHandle.getFile();
+    const data = await file.arrayBuffer();
+    return { handle: new MemoryHandle(data), isMemory: true };
+  }
+}
+async function openFreshVFSHandle(fileHandle) {
+  try {
+    const handle = await fileHandle.createSyncAccessHandle();
+    return { handle, isMemory: false };
+  } catch {
+    return { handle: new MemoryHandle(), isMemory: true };
+  }
+}
+async function saveMemoryHandle(fileHandle, memHandle) {
+  const writable = await fileHandle.createWritable();
+  await writable.write(memHandle.getBuffer());
+  await writable.close();
+}
 async function navigateToRoot(root) {
   let dir = await navigator.storage.getDirectory();
   if (root && root !== "/") {
@@ -3262,15 +3342,21 @@ async function writeOPFSFile(rootDir, path, data) {
   const parentDir = await ensureParentDirs(rootDir, path);
   const name = basename2(path);
   const fileHandle = await parentDir.getFileHandle(name, { create: true });
-  const syncHandle = await fileHandle.createSyncAccessHandle();
   try {
-    syncHandle.truncate(0);
-    if (data.byteLength > 0) {
-      syncHandle.write(data, { at: 0 });
+    const syncHandle = await fileHandle.createSyncAccessHandle();
+    try {
+      syncHandle.truncate(0);
+      if (data.byteLength > 0) {
+        syncHandle.write(data, { at: 0 });
+      }
+      syncHandle.flush();
+    } finally {
+      syncHandle.close();
     }
-    syncHandle.flush();
-  } finally {
-    syncHandle.close();
+  } catch {
+    const writable = await fileHandle.createWritable();
+    await writable.write(data);
+    await writable.close();
   }
 }
 async function clearDirectory(dir, skip) {
@@ -3299,10 +3385,54 @@ async function readOPFSRecursive(dir, prefix, skip) {
   }
   return result;
 }
-async function unpackToOPFS(root = "/") {
+function readVFSRecursive(fs, vfsPath) {
+  const result = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(vfsPath, { withFileTypes: true });
+  } catch {
+    return result;
+  }
+  for (const entry of entries) {
+    const fullPath = vfsPath === "/" ? `/${entry.name}` : `${vfsPath}/${entry.name}`;
+    if (entry.isDirectory()) {
+      result.push({ path: fullPath, type: "directory" });
+      result.push(...readVFSRecursive(fs, fullPath));
+    } else {
+      try {
+        const data = fs.readFileSync(fullPath);
+        result.push({ path: fullPath, type: "file", data });
+      } catch {
+      }
+    }
+  }
+  return result;
+}
+async function unpackToOPFS(root = "/", fs) {
   const rootDir = await navigateToRoot(root);
+  if (fs) {
+    const vfsEntries = readVFSRecursive(fs, "/");
+    let files2 = 0;
+    let directories2 = 0;
+    for (const entry of vfsEntries) {
+      if (entry.type === "directory") {
+        const name = basename2(entry.path);
+        const parent = await ensureParentDirs(rootDir, entry.path);
+        await parent.getDirectoryHandle(name, { create: true });
+        directories2++;
+      } else {
+        try {
+          await writeOPFSFile(rootDir, entry.path, entry.data ?? new Uint8Array(0));
+          files2++;
+        } catch (err) {
+          console.warn(`[VFS] Failed to write OPFS file ${entry.path}: ${err.message}`);
+        }
+      }
+    }
+    return { files: files2, directories: directories2 };
+  }
   const vfsFileHandle = await rootDir.getFileHandle(".vfs.bin");
-  const handle = await vfsFileHandle.createSyncAccessHandle();
+  const { handle } = await openVFSHandle(vfsFileHandle);
   let entries;
   try {
     const engine = new VFSEngine();
@@ -3317,30 +3447,65 @@ async function unpackToOPFS(root = "/") {
   for (const entry of entries) {
     if (entry.path === "/") continue;
     if (entry.type === INODE_TYPE.DIRECTORY) {
-      await ensureParentDirs(rootDir, entry.path + "/dummy");
       const name = basename2(entry.path);
       const parent = await ensureParentDirs(rootDir, entry.path);
       await parent.getDirectoryHandle(name, { create: true });
       directories++;
-    } else if (entry.type === INODE_TYPE.FILE) {
-      await writeOPFSFile(rootDir, entry.path, entry.data ?? new Uint8Array(0));
-      files++;
-    } else if (entry.type === INODE_TYPE.SYMLINK) {
+    } else if (entry.type === INODE_TYPE.FILE || entry.type === INODE_TYPE.SYMLINK) {
       await writeOPFSFile(rootDir, entry.path, entry.data ?? new Uint8Array(0));
       files++;
     }
   }
   return { files, directories };
 }
-async function loadFromOPFS(root = "/") {
+async function loadFromOPFS(root = "/", fs) {
   const rootDir = await navigateToRoot(root);
   const opfsEntries = await readOPFSRecursive(rootDir, "", /* @__PURE__ */ new Set([".vfs.bin"]));
+  if (fs) {
+    try {
+      const rootEntries = fs.readdirSync("/");
+      for (const entry of rootEntries) {
+        try {
+          fs.rmSync(`/${entry}`, { recursive: true, force: true });
+        } catch {
+        }
+      }
+    } catch {
+    }
+    const dirs = opfsEntries.filter((e) => e.type === "directory").sort((a, b) => a.path.localeCompare(b.path));
+    let files = 0;
+    let directories = 0;
+    for (const dir of dirs) {
+      try {
+        fs.mkdirSync(dir.path, { recursive: true, mode: 493 });
+        directories++;
+      } catch {
+      }
+    }
+    const fileEntries = opfsEntries.filter((e) => e.type === "file");
+    for (const file of fileEntries) {
+      try {
+        const parentPath = file.path.substring(0, file.path.lastIndexOf("/")) || "/";
+        if (parentPath !== "/") {
+          try {
+            fs.mkdirSync(parentPath, { recursive: true, mode: 493 });
+          } catch {
+          }
+        }
+        fs.writeFileSync(file.path, new Uint8Array(file.data));
+        files++;
+      } catch (err) {
+        console.warn(`[VFS] Failed to write ${file.path}: ${err.message}`);
+      }
+    }
+    return { files, directories };
+  }
   try {
     await rootDir.removeEntry(".vfs.bin");
   } catch (_) {
   }
   const vfsFileHandle = await rootDir.getFileHandle(".vfs.bin", { create: true });
-  const handle = await vfsFileHandle.createSyncAccessHandle();
+  const { handle, isMemory } = await openFreshVFSHandle(vfsFileHandle);
   try {
     const engine = new VFSEngine();
     engine.init(handle);
@@ -3357,12 +3522,29 @@ async function loadFromOPFS(root = "/") {
       files++;
     }
     engine.flush();
+    if (isMemory) {
+      await saveMemoryHandle(vfsFileHandle, handle);
+    }
     return { files, directories };
   } finally {
     handle.close();
   }
 }
-async function repairVFS(root = "/") {
+async function repairVFS(root = "/", fs) {
+  if (fs) {
+    const loadResult = await loadFromOPFS(root, fs);
+    await unpackToOPFS(root, fs);
+    const total = loadResult.files + loadResult.directories;
+    return {
+      recovered: total,
+      lost: 0,
+      entries: []
+      // Detailed entries not available in fs-based path
+    };
+  }
+  return repairVFSRaw(root);
+}
+async function repairVFSRaw(root) {
   const rootDir = await navigateToRoot(root);
   const vfsFileHandle = await rootDir.getFileHandle(".vfs.bin");
   const file = await vfsFileHandle.getFile();
@@ -3458,7 +3640,7 @@ async function repairVFS(root = "/") {
   }
   await rootDir.removeEntry(".vfs.bin");
   const newFileHandle = await rootDir.getFileHandle(".vfs.bin", { create: true });
-  const handle = await newFileHandle.createSyncAccessHandle();
+  const { handle, isMemory } = await openFreshVFSHandle(newFileHandle);
   try {
     const engine = new VFSEngine();
     engine.init(handle);
@@ -3479,6 +3661,9 @@ async function repairVFS(root = "/") {
       if (result.status !== 0) lost++;
     }
     engine.flush();
+    if (isMemory) {
+      await saveMemoryHandle(newFileHandle, handle);
+    }
   } finally {
     handle.close();
   }