@componentor/fs 3.0.2 → 3.0.4

package/README.md

@@ -311,17 +311,23 @@ await writer.close();
 ### Watch API
 
 ```typescript
-// Watch for changes
-const watcher = fs.watch('/dir', { recursive: true }, (eventType, filename) => {
-  console.log(eventType, filename); // 'change' 'file.txt'
+// Watch for changes (supports recursive + AbortSignal)
+const ac = new AbortController();
+const watcher = fs.watch('/dir', { recursive: true, signal: ac.signal }, (eventType, filename) => {
+  console.log(eventType, filename); // 'rename' 'newfile.txt' or 'change' 'file.txt'
 });
-watcher.close();
+watcher.close(); // or ac.abort()
 
-// Watch specific file with polling
+// Watch specific file with stat polling
 fs.watchFile('/file.txt', { interval: 1000 }, (curr, prev) => {
   console.log('File changed:', curr.mtimeMs !== prev.mtimeMs);
 });
 fs.unwatchFile('/file.txt');
+
+// Async iterable (promises API)
+for await (const event of fs.promises.watch('/dir', { recursive: true })) {
+  console.log(event.eventType, event.filename);
+}
 ```
 
 ### Path Utilities
@@ -362,6 +368,33 @@ constants.O_TRUNC    // 512
 constants.O_APPEND   // 1024
 ```
 
+## Maintenance Helpers
+
+Standalone utilities for VFS maintenance, recovery, and migration. Must be called from a Worker context (sync access handle requirement). Close any running `VFSFileSystem` instance first.
+
+```typescript
+import { unpackToOPFS, loadFromOPFS, repairVFS } from '@componentor/fs';
+
+// Export VFS contents to real OPFS files (clears existing OPFS files first)
+const { files, directories } = await unpackToOPFS('/my-app');
+
+// Rebuild VFS from real OPFS files (deletes .vfs.bin, creates fresh VFS)
+const { files, directories } = await loadFromOPFS('/my-app');
+
+// Attempt to recover files from a corrupt VFS binary
+const { recovered, lost, entries } = await repairVFS('/my-app');
+console.log(`Recovered ${recovered} entries, lost ${lost}`);
+for (const entry of entries) {
+  console.log(`  ${entry.type} ${entry.path} (${entry.size} bytes)`);
+}
+```
+
+| Function | Description |
+|----------|-------------|
+| `unpackToOPFS(root?)` | Read all files from VFS, write to real OPFS paths |
+| `loadFromOPFS(root?)` | Read all OPFS files, create fresh VFS with their contents |
+| `repairVFS(root?)` | Scan corrupt `.vfs.bin` for recoverable inodes, rebuild fresh VFS |
+
 ## isomorphic-git Integration
 
 ```typescript
@@ -412,23 +445,23 @@ await git.commit({
 │               sync-relay Worker (Leader)                         │
 │  ┌────────────────────────────────────────────────────────────┐  │
 │  │                     VFS Engine                             │  │
-│  │  ┌──────────────────┐  ┌─────────────┐  ┌──────────────┐  │  │
-│  │  │  VFS Binary File  │  │  Inode/Path │  │  Block Data  │  │  │
-│  │  │  (.vfs.bin OPFS)  │  │    Table    │  │   Region     │  │  │
-│  │  └──────────────────┘  └─────────────┘  └──────────────┘  │  │
+│  │  ┌──────────────────┐  ┌─────────────┐  ┌──────────────┐   │  │
+│  │  │  VFS Binary File │  │  Inode/Path │  │  Block Data  │   │  │
+│  │  │  (.vfs.bin OPFS) │  │    Table    │  │   Region     │   │  │
+│  │  └──────────────────┘  └─────────────┘  └──────────────┘   │  │
 │  └────────────────────────────────────────────────────────────┘  │
 │                            │                                     │
-│                    notifyOPFSSync()                               │
-│                     (fire & forget)                               │
+│                    notifyOPFSSync()                              │
+│                     (fire & forget)                              │
 └────────────────────────────┼─────────────────────────────────────┘
                              │
                              ▼
 ┌──────────────────────────────────────────────────────────────────┐
-│                    opfs-sync Worker                               │
+│                    opfs-sync Worker                              │
 │  ┌────────────────────┐  ┌────────────────────────────────────┐  │
-│  │  VFS → OPFS Mirror │  │  FileSystemObserver (OPFS → VFS)  │  │
-│  │  (queue + echo     │  │  External changes detected and    │  │
-│  │   suppression)     │  │  synced back to VFS engine        │  │
+│  │  VFS → OPFS Mirror │  │  FileSystemObserver (OPFS → VFS)   │  │
+│  │  (queue + echo     │  │  External changes detected and     │  │
+│  │   suppression)     │  │  synced back to VFS engine         │  │
 │  └────────────────────┘  └────────────────────────────────────┘  │
 └──────────────────────────────────────────────────────────────────┘
 
@@ -475,6 +508,31 @@ Make sure `opfsSync` is enabled (it's `true` by default). Files are mirrored to
 
 ## Changelog
 
+### v3.0.4 (2026)
+
+**Features:**
+- Add `unpackToOPFS(root?)` — export all VFS contents to real OPFS files
+- Add `loadFromOPFS(root?)` — rebuild VFS from real OPFS files (deletes and recreates `.vfs.bin`)
+- Add `repairVFS(root?)` — scan corrupt VFS binary for recoverable inodes and rebuild a clean VFS
+- Add `VFSEngine.exportAll()` for extracting all files/dirs/symlinks with their data
+
+**Bug Fixes:**
+- VFS corruption detection on init — validates magic, version, block size, inode count, section offsets, file size, and root directory existence
+- Release sync access handle on init failure (previously leaked, blocking re-acquisition)
+
+### v3.0.3 (2026)
+
+**Features:**
+- Implement `fs.watch()`, `fs.watchFile()`, `fs.unwatchFile()`, and `promises.watch()` as Node.js-compatible polyfills
+- Watch events propagate across all tabs via `BroadcastChannel`
+- `fs.watch()` supports `recursive` option and `AbortSignal` for cleanup
+- `fs.watchFile()` supports stat-based polling with configurable `interval` (default 5007ms per Node.js)
+- `promises.watch()` returns an async iterable of watch events
+
+**Internal:**
+- Leader broadcasts `{ eventType, path }` on every successful VFS mutation (no new opcodes or protocol changes)
+- Mutation tracking now runs unconditionally (previously gated on `opfsSync`)
+
 ### v3.0.2 (2026)
 
 **Bug Fixes:**
@@ -529,7 +587,7 @@ git clone https://github.com/componentor/fs
 cd fs
 npm install
 npm run build       # Build the library
-npm test            # Run unit tests (77 tests)
+npm test            # Run unit tests (97 tests)
 npm run benchmark:open  # Run benchmarks in browser
 ```