vfs: move fs interception from monkey-patching into lib/fs.js

Instead of monkey-patching fs.readFileSync, fs.statSync, etc. at
runtime in module_hooks.js, add VFS handler guards directly inside the
fs method bodies. This fixes the destructuring problem where capturing
a reference before vfs.mount() would bypass VFS:

  const { readFileSync } = require('fs');
  vfs.mount('/app');
  readFileSync('/app/file.txt'); // now works correctly

The approach:
- Add shared vfsState object and setVfsHandlers() in internal/fs/utils
- Add a null-check guard at the top of 9 sync methods in lib/fs.js
  and 3 async methods in lib/internal/fs/promises.js
- Replace installFsPatches() with a handler object registered via
  setVfsHandlers() — same logic, no monkey-patching
- Rename module_hooks.js to setup.js (no longer does monkey-patching)

When no VFS is active, the overhead is a single null comparison per
call. When the last VFS is unmounted, handlers are cleared to restore
the zero-overhead path.

Author: mcollina

lib/fs.js

@@ -127,6 +127,7 @@ const {
   validateRmOptionsSync,
   validateRmdirOptions,
   validateStringAfterArrayBufferView,
+  vfsState,
   warnOnNonPortableTemplate,
 } = require('internal/fs/utils');
 const {
@@ -271,6 +272,11 @@ let showExistsDeprecation = true;
  * @returns {boolean}
  */
 function existsSync(path) {
+  const h = vfsState.handlers;
+  if (h !== null) {
+    const result = h.existsSync(path);
+    if (result !== undefined) return result;
+  }
   try {
     path = getValidatedPath(path);
   } catch (err) {
@@ -427,6 +433,11 @@ function tryReadSync(fd, isUserFd, buffer, pos, len) {
  * @returns {string | Buffer}
  */
 function readFileSync(path, options) {
+  const h = vfsState.handlers;
+  if (h !== null) {
+    const result = h.readFileSync(path, options);
+    if (result !== undefined) return result;
+  }
   options = getOptions(options, { flag: 'r' });
 
   if (options.encoding === 'utf8' || options.encoding === 'utf-8') {
@@ -1541,6 +1552,11 @@ function readdir(path, options, callback) {
  * @returns {string | Buffer[] | Dirent[]}
  */
 function readdirSync(path, options) {
+  const h = vfsState.handlers;
+  if (h !== null) {
+    const result = h.readdirSync(path, options);
+    if (result !== undefined) return result;
+  }
   options = getOptions(options);
   path = getValidatedPath(path);
   if (options.recursive != null) {
@@ -1678,6 +1694,11 @@ function fstatSync(fd, options = { bigint: false }) {
  * @returns {Stats | undefined}
  */
 function lstatSync(path, options = { bigint: false, throwIfNoEntry: true }) {
+  const h = vfsState.handlers;
+  if (h !== null) {
+    const result = h.lstatSync(path, options);
+    if (result !== undefined) return result;
+  }
   path = getValidatedPath(path);
   if (permission.isEnabled() && !permission.has('fs.read', path)) {
     const resource = BufferIsBuffer(path) ? BufferToString(path) : path;
@@ -1707,6 +1728,11 @@ function lstatSync(path, options = { bigint: false, throwIfNoEntry: true }) {
  * @returns {Stats}
  */
 function statSync(path, options = { bigint: false, throwIfNoEntry: true }) {
+  const h = vfsState.handlers;
+  if (h !== null) {
+    const result = h.statSync(path, options);
+    if (result !== undefined) return result;
+  }
   const stats = binding.stat(
     getValidatedPath(path),
     options.bigint,
@@ -2496,6 +2522,11 @@ function appendFileSync(path, data, options) {
  * @returns {watchers.FSWatcher}
  */
 function watch(filename, options, listener) {
+  const h = vfsState.handlers;
+  if (h !== null) {
+    const result = h.watch(filename, options, listener);
+    if (result !== undefined) return result;
+  }
   if (typeof options === 'function') {
     listener = options;
   }
@@ -2563,6 +2594,11 @@ const statWatchers = new SafeMap();
  * @returns {watchers.StatWatcher}
  */
 function watchFile(filename, options, listener) {
+  const h = vfsState.handlers;
+  if (h !== null) {
+    const result = h.watchFile(filename, options, listener);
+    if (result !== undefined) return result;
+  }
   filename = getValidatedPath(filename);
   filename = pathModule.resolve(filename);
   let stat;
@@ -2605,6 +2641,10 @@ function watchFile(filename, options, listener) {
  * @returns {void}
  */
 function unwatchFile(filename, listener) {
+  const h = vfsState.handlers;
+  if (h !== null) {
+    if (h.unwatchFile(filename, listener)) return;
+  }
   filename = getValidatedPath(filename);
   filename = pathModule.resolve(filename);
   const stat = statWatchers.get(filename);
@@ -2682,6 +2722,11 @@ if (isWindows) {
  * @returns {string | Buffer}
  */
 function realpathSync(p, options) {
+  const h = vfsState.handlers;
+  if (h !== null) {
+    const result = h.realpathSync(p, options);
+    if (result !== undefined) return result;
+  }
   options = getOptions(options);
   p = toPathIfFileURL(p);
   if (typeof p !== 'string') {

lib/internal/fs/promises.js

@@ -70,6 +70,7 @@ const {
   validateRmOptions,
   validateRmdirOptions,
   validateStringAfterArrayBufferView,
+  vfsState,
   warnOnNonPortableTemplate,
 } = require('internal/fs/utils');
 const { opendir } = require('internal/fs/dir');
@@ -941,6 +942,11 @@ async function readdirRecursive(originalPath, options) {
 }
 
 async function readdir(path, options) {
+  const h = vfsState.handlers;
+  if (h !== null) {
+    const vfsResult = await h.readdir(path, options);
+    if (vfsResult !== undefined) return vfsResult;
+  }
   options = getOptions(options);
 
   // Make shallow copy to prevent mutating options from affecting results
@@ -1018,6 +1024,11 @@ async function fstat(handle, options = { bigint: false }) {
 }
 
 async function lstat(path, options = { bigint: false }) {
+  const h = vfsState.handlers;
+  if (h !== null) {
+    const vfsResult = await h.lstat(path, options);
+    if (vfsResult !== undefined) return vfsResult;
+  }
   const result = await PromisePrototypeThen(
     binding.lstat(getValidatedPath(path), options.bigint, kUsePromises),
     undefined,
@@ -1275,6 +1286,14 @@ async function readFile(path, options) {
 }
 
 async function* _watch(filename, options = kEmptyObject) {
+  const h = vfsState.handlers;
+  if (h !== null) {
+    const result = h.promisesWatch(filename, options);
+    if (result !== undefined) {
+      yield* result;
+      return;
+    }
+  }
   validateObject(options, 'options');
 
   if (options.recursive != null) {
@@ -1333,7 +1352,7 @@ module.exports = {
     writeFile,
     appendFile,
     readFile,
-    watch: !isMacOS && !isWindows ? _watch : watch,
+    watch: _watch,
     constants,
   },
 

lib/internal/fs/utils.js

@@ -915,6 +915,11 @@ const validatePosition = hideStackFrames((position, name, length) => {
   }
 });
 
+// Shared VFS handler state for fs wrapping.
+// When handlers is null, no VFS is active (zero overhead).
+const vfsState = { __proto__: null, handlers: null };
+function setVfsHandlers(handlers) { vfsState.handlers = handlers; }
+
 module.exports = {
   constants: {
     kIoMaxLength,
@@ -953,4 +958,6 @@ module.exports = {
   validateRmdirOptions,
   validateStringAfterArrayBufferView,
   warnOnNonPortableTemplate,
+  vfsState,
+  setVfsHandlers,
 };

lib/internal/vfs/file_system.js

@@ -44,15 +44,15 @@ const kVirtualCwdEnabled = Symbol('kVirtualCwdEnabled');
 const kOriginalChdir = Symbol('kOriginalChdir');
 const kOriginalCwd = Symbol('kOriginalCwd');
 
-// Lazy-loaded module hooks
+// Lazy-loaded VFS setup
 let registerVFS;
 let deregisterVFS;
 
-function loadModuleHooks() {
+function loadVfsSetup() {
   if (!registerVFS) {
-    const hooks = require('internal/vfs/module_hooks');
-    registerVFS = hooks.registerVFS;
-    deregisterVFS = hooks.deregisterVFS;
+    const setup = require('internal/vfs/setup');
+    registerVFS = setup.registerVFS;
+    deregisterVFS = setup.deregisterVFS;
   }
 }
 
@@ -228,7 +228,7 @@ class VirtualFileSystem {
     this[kMountPoint] = resolvePath(prefix);
     this[kMounted] = true;
     if (this[kModuleHooks]) {
-      loadModuleHooks();
+      loadVfsSetup();
       registerVFS(this);
     }
     if (this[kVirtualCwdEnabled]) {
@@ -244,7 +244,7 @@ class VirtualFileSystem {
   unmount() {
     this.#unhookProcessCwd();
     if (this[kModuleHooks]) {
-      loadModuleHooks();
+      loadVfsSetup();
       deregisterVFS(this);
     }
     this[kMountPoint] = null;