vfs: add watch and watchFile support

Add fs.watch(), fs.watchFile(), fs.unwatchFile(), and fs.promises.watch()
support for VFS-mounted paths using a polling-based implementation.

Key features:
- VFSWatcher: polling-based watcher compatible with fs.watch() interface
- VFSStatWatcher: stat-based watcher compatible with fs.watchFile()
- VFSWatchAsyncIterable: async iterator for fs.promises.watch()
- Recursive directory watching via tracked files map
- AbortSignal support for cancellation
- Overlay mode: watches VFS if file exists, falls through to real fs

The implementation follows "Approach A (VFS Priority)" where VFS files
take precedence over real filesystem files under mount points.

Author: mcollina

lib/internal/vfs/file_handle.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const {
+  DateNow,
   MathMin,
   Symbol,
 } = primordials;
@@ -385,9 +386,10 @@ class MemoryFileHandle extends VirtualFileHandle {
     // Write the data
     data.copy(this.#content, writePos);
 
-    // Update the entry's content
+    // Update the entry's content and mtime
     if (this.#entry) {
       this.#entry.content = this.#content;
+      this.#entry.mtime = DateNow();
     }
 
     // Update position if not using explicit position
@@ -466,9 +468,10 @@ class MemoryFileHandle extends VirtualFileHandle {
       this.#content = Buffer.from(buffer);
     }
 
-    // Update the entry's content
+    // Update the entry's content and mtime
     if (this.#entry) {
       this.#entry.content = this.#content;
+      this.#entry.mtime = DateNow();
     }
 
     this.position = this.#content.length;
@@ -521,9 +524,10 @@ class MemoryFileHandle extends VirtualFileHandle {
       this.#content = newContent;
     }
 
-    // Update the entry's content
+    // Update the entry's content and mtime
     if (this.#entry) {
       this.#entry.content = this.#content;
+      this.#entry.mtime = DateNow();
     }
   }
 

lib/internal/vfs/file_system.js

@@ -885,6 +885,58 @@ class VirtualFileSystem {
     return createVirtualReadStream(this, filePath, options);
   }
 
+  // ==================== Watch Operations ====================
+
+  /**
+   * Watches a file or directory for changes.
+   * @param {string} filePath The path to watch
+   * @param {object|Function} [options] Watch options or listener
+   * @param {Function} [listener] Change listener
+   * @returns {EventEmitter} A watcher that emits 'change' events
+   */
+  watch(filePath, options, listener) {
+    if (typeof options === 'function') {
+      listener = options;
+      options = {};
+    }
+
+    const providerPath = this._toProviderPath(filePath);
+    const watcher = this[kProvider].watch(providerPath, options);
+
+    if (listener) {
+      watcher.on('change', listener);
+    }
+
+    return watcher;
+  }
+
+  /**
+   * Watches a file for changes using stat polling.
+   * @param {string} filePath The path to watch
+   * @param {object|Function} [options] Watch options or listener
+   * @param {Function} [listener] Change listener
+   * @returns {EventEmitter} A stat watcher that emits 'change' events
+   */
+  watchFile(filePath, options, listener) {
+    if (typeof options === 'function') {
+      listener = options;
+      options = {};
+    }
+
+    const providerPath = this._toProviderPath(filePath);
+    return this[kProvider].watchFile(providerPath, options, listener);
+  }
+
+  /**
+   * Stops watching a file for changes.
+   * @param {string} filePath The path to stop watching
+   * @param {Function} [listener] Optional listener to remove
+   */
+  unwatchFile(filePath, listener) {
+    const providerPath = this._toProviderPath(filePath);
+    this[kProvider].unwatchFile(providerPath, listener);
+  }
+
   // ==================== Promise API ====================
 
   /**
@@ -989,6 +1041,11 @@ function createPromisesAPI(vfs) {
       const providerPath = vfs._toProviderPath(filePath);
       return provider.access(providerPath, mode);
     },
+
+    watch(filePath, options) {
+      const providerPath = vfs._toProviderPath(filePath);
+      return provider.watchAsync(providerPath, options);
+    },
   });
 }
 

lib/internal/vfs/module_hooks.js

@@ -34,6 +34,14 @@ let originalExistsSync = null;
 let originalPromisesReaddir = null;
 // Original fs/promises.lstat function
 let originalPromisesLstat = null;
+// Original fs.watch function
+let originalWatch = null;
+// Original fs.watchFile function
+let originalWatchFile = null;
+// Original fs.unwatchFile function
+let originalUnwatchFile = null;
+// Original fs/promises.watch function
+let originalPromisesWatch = null;
 // Track if hooks are installed
 let hooksInstalled = false;
 
@@ -282,6 +290,33 @@ async function findVFSForLstatAsync(filename) {
   return null;
 }
 
+/**
+ * Checks all active VFS instances for watch operations.
+ * For Approach A (VFS Priority): watch VFS if file exists, otherwise fall through.
+ * @param {string} filename The path to watch
+ * @returns {{ vfs: VirtualFileSystem }|null}
+ */
+function findVFSForWatch(filename) {
+  const normalized = normalizePath(filename);
+  for (let i = 0; i < activeVFSList.length; i++) {
+    const vfs = activeVFSList[i];
+    if (vfs.shouldHandle(normalized)) {
+      // In overlay mode, only handle if file exists in VFS
+      // In mount mode (default), always handle paths under mount point
+      if (vfs.overlay) {
+        if (vfs.existsSync(normalized)) {
+          return { vfs };
+        }
+        // File doesn't exist in VFS, fall through to real fs.watch
+        continue;
+      }
+      // Mount mode: always handle
+      return { vfs };
+    }
+  }
+  return null;
+}
+
 /**
  * Determine module format from file extension.
  * @param {string} url The file URL
@@ -565,6 +600,73 @@ function installHooks() {
     return originalPromisesLstat.call(fsPromises, path, options);
   };
 
+  // Override fs.watch
+  originalWatch = fs.watch;
+  fs.watch = function watch(filename, options, listener) {
+    // Handle optional options argument
+    if (typeof options === 'function') {
+      listener = options;
+      options = {};
+    }
+    options ??= {};
+
+    if (typeof filename === 'string' || filename instanceof URL) {
+      const pathStr = typeof filename === 'string' ? filename : filename.pathname;
+      const vfsResult = findVFSForWatch(pathStr);
+      if (vfsResult !== null) {
+        return vfsResult.vfs.watch(pathStr, options, listener);
+      }
+    }
+    return originalWatch.call(fs, filename, options, listener);
+  };
+
+  // Override fs.watchFile
+  originalWatchFile = fs.watchFile;
+  fs.watchFile = function watchFile(filename, options, listener) {
+    // Handle optional options argument
+    if (typeof options === 'function') {
+      listener = options;
+      options = {};
+    }
+    options ??= {};
+
+    if (typeof filename === 'string' || filename instanceof URL) {
+      const pathStr = typeof filename === 'string' ? filename : filename.pathname;
+      const vfsResult = findVFSForWatch(pathStr);
+      if (vfsResult !== null) {
+        return vfsResult.vfs.watchFile(pathStr, options, listener);
+      }
+    }
+    return originalWatchFile.call(fs, filename, options, listener);
+  };
+
+  // Override fs.unwatchFile
+  originalUnwatchFile = fs.unwatchFile;
+  fs.unwatchFile = function unwatchFile(filename, listener) {
+    if (typeof filename === 'string' || filename instanceof URL) {
+      const pathStr = typeof filename === 'string' ? filename : filename.pathname;
+      const vfsResult = findVFSForWatch(pathStr);
+      if (vfsResult !== null) {
+        vfsResult.vfs.unwatchFile(pathStr, listener);
+        return;
+      }
+    }
+    return originalUnwatchFile.call(fs, filename, listener);
+  };
+
+  // Override fs/promises.watch
+  originalPromisesWatch = fsPromises.watch;
+  fsPromises.watch = function watch(filename, options) {
+    if (typeof filename === 'string' || filename instanceof URL) {
+      const pathStr = typeof filename === 'string' ? filename : filename.pathname;
+      const vfsResult = findVFSForWatch(pathStr);
+      if (vfsResult !== null) {
+        return vfsResult.vfs.promises.watch(pathStr, options);
+      }
+    }
+    return originalPromisesWatch.call(fsPromises, filename, options);
+  };
+
   // Register ESM hooks using Module.registerHooks
   Module.registerHooks({
     resolve: vfsResolveHook,

lib/internal/vfs/provider.js

@@ -34,6 +34,14 @@ class VirtualProvider {
     return false;
   }
 
+  /**
+   * Returns true if this provider supports file watching.
+   * @returns {boolean}
+   */
+  get supportsWatch() {
+    return false;
+  }
+
   // === ESSENTIAL PRIMITIVES (must be implemented by subclasses) ===
 
   /**
@@ -492,6 +500,57 @@ class VirtualProvider {
     }
     throw new ERR_METHOD_NOT_IMPLEMENTED('symlinkSync');
   }
+
+  // === WATCH OPERATIONS (optional, polling-based) ===
+
+  /**
+   * Watches a file or directory for changes.
+   * Returns an EventEmitter-like object that emits 'change' and 'close' events.
+   * @param {string} path The path to watch
+   * @param {object} [options] Watch options
+   * @param {number} [options.interval] Polling interval in ms (default: 100)
+   * @param {boolean} [options.recursive] Watch subdirectories (default: false)
+   * @throws {ERR_METHOD_NOT_IMPLEMENTED} When not overridden by subclass
+   */
+  watch(path, options) {
+    throw new ERR_METHOD_NOT_IMPLEMENTED('watch');
+  }
+
+  /**
+   * Watches a file or directory for changes (async iterable version).
+   * Used by fs.promises.watch().
+   * @param {string} path The path to watch
+   * @param {object} [options] Watch options
+   * @param {number} [options.interval] Polling interval in ms (default: 100)
+   * @param {boolean} [options.recursive] Watch subdirectories (default: false)
+   * @param {AbortSignal} [options.signal] AbortSignal for cancellation
+   * @throws {ERR_METHOD_NOT_IMPLEMENTED} When not overridden by subclass
+   */
+  watchAsync(path, options) {
+    throw new ERR_METHOD_NOT_IMPLEMENTED('watchAsync');
+  }
+
+  /**
+   * Watches a file for changes using stat polling.
+   * Returns a StatWatcher-like object that emits 'change' events with stats.
+   * @param {string} path The path to watch
+   * @param {object} [options] Watch options
+   * @param {number} [options.interval] Polling interval in ms (default: 5007)
+   * @param {boolean} [options.persistent] Whether the watcher should prevent exit
+   * @throws {ERR_METHOD_NOT_IMPLEMENTED} When not overridden by subclass
+   */
+  watchFile(path, options) {
+    throw new ERR_METHOD_NOT_IMPLEMENTED('watchFile');
+  }
+
+  /**
+   * Stops watching a file for changes.
+   * @param {string} path The path to stop watching
+   * @param {Function} [listener] Optional listener to remove
+   */
+  unwatchFile(path, listener) {
+    throw new ERR_METHOD_NOT_IMPLEMENTED('unwatchFile');
+  }
 }
 
 module.exports = {