vfs: add virtual process.chdir() support

Add virtual working directory support to the VFS with process.chdir()
and process.cwd() interception:

- Add `virtualCwd` option to fs.createVirtual() (disabled by default)
- Add vfs.cwd(), vfs.chdir(), and vfs.resolvePath() methods
- Intercept process.chdir() for VFS paths when virtualCwd is enabled
- Intercept process.cwd() to return virtual cwd when set
- Restore original process methods on unmount
- Add tests for basic chdir functionality and process interception
- Add worker thread tests verifying independent VFS instances
- Update documentation with examples and worker thread notes

Author: mcollina

doc/api/fs.md

@@ -8347,6 +8347,8 @@ added: REPLACEME
     fall through to the real file system. **Default:** `true`.
   * `moduleHooks` {boolean} When `true`, enables hooks for `require()` and
     `import` to load modules from the VFS. **Default:** `true`.
+  * `virtualCwd` {boolean} When `true`, enables virtual working directory
+    support via `vfs.chdir()` and `vfs.cwd()`. **Default:** `false`.
 * Returns: {VirtualFileSystem}
 
 Creates a new virtual file system instance.
@@ -8531,6 +8533,147 @@ added: REPLACEME
 
 Removes a file or directory from the VFS.
 
+#### `vfs.virtualCwdEnabled`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* {boolean}
+
+Returns `true` if virtual working directory support is enabled for this VFS
+instance. This is determined by the `virtualCwd` option passed to
+`fs.createVirtual()`.
+
+#### `vfs.cwd()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {string|null} The current virtual working directory, or `null` if
+  not set.
+
+Gets the virtual current working directory. Throws `ERR_INVALID_STATE` if
+`virtualCwd` option was not enabled when creating the VFS.
+
+```cjs
+const fs = require('node:fs');
+
+const vfs = fs.createVirtual({ virtualCwd: true });
+vfs.addDirectory('/project');
+vfs.mount('/app');
+
+console.log(vfs.cwd()); // null (not set yet)
+
+vfs.chdir('/app/project');
+console.log(vfs.cwd()); // '/app/project'
+```
+
+#### `vfs.chdir(path)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `path` {string} The directory path to set as the current working directory.
+
+Sets the virtual current working directory. The path must exist in the VFS and
+must be a directory. Throws `ENOENT` if the path does not exist, `ENOTDIR` if
+the path is not a directory, or `ERR_INVALID_STATE` if `virtualCwd` option was
+not enabled.
+
+```cjs
+const fs = require('node:fs');
+
+const vfs = fs.createVirtual({ virtualCwd: true });
+vfs.addDirectory('/project');
+vfs.addDirectory('/project/src');
+vfs.addFile('/project/src/index.js', 'module.exports = "hello";');
+vfs.mount('/app');
+
+vfs.chdir('/app/project');
+console.log(vfs.cwd()); // '/app/project'
+
+vfs.chdir('/app/project/src');
+console.log(vfs.cwd()); // '/app/project/src'
+```
+
+##### `process.chdir()` and `process.cwd()` interception
+
+When `virtualCwd` is enabled and the VFS is mounted or in overlay mode,
+`process.chdir()` and `process.cwd()` are intercepted to support transparent
+virtual working directory operations:
+
+* `process.chdir(path)` - When called with a path that resolves to the VFS,
+  the virtual cwd is updated instead of changing the real process working
+  directory. Paths outside the VFS fall through to the real `process.chdir()`.
+
+* `process.cwd()` - When a virtual cwd is set, returns the virtual cwd.
+  Otherwise, returns the real process working directory.
+
+```cjs
+const fs = require('node:fs');
+
+const vfs = fs.createVirtual({ virtualCwd: true });
+vfs.addDirectory('/project');
+vfs.mount('/virtual');
+
+const originalCwd = process.cwd();
+
+// Change to a VFS directory using process.chdir
+process.chdir('/virtual/project');
+console.log(process.cwd()); // '/virtual/project'
+console.log(vfs.cwd()); // '/virtual/project'
+
+// Change to a real directory (falls through)
+process.chdir('/tmp');
+console.log(process.cwd()); // '/tmp' (real cwd)
+
+// Restore and unmount
+process.chdir(originalCwd);
+vfs.unmount();
+```
+
+When the VFS is unmounted, `process.chdir()` and `process.cwd()` are restored
+to their original implementations.
+
+> **Note:** VFS hooks are not automatically shared with worker threads. Each
+> worker thread has its own `process` object and must set up its own VFS
+> instance if virtual cwd support is needed.
+
+#### `vfs.resolvePath(path)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `path` {string} The path to resolve.
+* Returns: {string} The resolved absolute path.
+
+Resolves a path relative to the virtual current working directory. If the path
+is absolute, it is returned as-is (normalized). If `virtualCwd` is enabled and
+a virtual cwd is set, relative paths are resolved against it. Otherwise,
+relative paths are resolved using the real process working directory.
+
+```cjs
+const fs = require('node:fs');
+
+const vfs = fs.createVirtual({ virtualCwd: true });
+vfs.addDirectory('/project');
+vfs.addDirectory('/project/src');
+vfs.mount('/app');
+
+vfs.chdir('/app/project');
+
+// Absolute paths returned as-is
+console.log(vfs.resolvePath('/other/path')); // '/other/path'
+
+// Relative paths resolved against virtual cwd
+console.log(vfs.resolvePath('src/index.js')); // '/app/project/src/index.js'
+console.log(vfs.resolvePath('./src/index.js')); // '/app/project/src/index.js'
+```
+
 ### VFS file system operations
 
 The `VirtualFileSystem` instance provides direct access to file system

lib/internal/vfs/virtual_fs.js

@@ -59,6 +59,10 @@ const kOverlay = Symbol('kOverlay');
 const kFallthrough = Symbol('kFallthrough');
 const kModuleHooks = Symbol('kModuleHooks');
 const kPromises = Symbol('kPromises');
+const kVirtualCwd = Symbol('kVirtualCwd');
+const kVirtualCwdEnabled = Symbol('kVirtualCwdEnabled');
+const kOriginalChdir = Symbol('kOriginalChdir');
+const kOriginalCwd = Symbol('kOriginalCwd');
 
 /**
  * Virtual File System implementation.
@@ -69,6 +73,7 @@ class VirtualFileSystem {
    * @param {object} [options] Configuration options
    * @param {boolean} [options.fallthrough] Whether to fall through to real fs on miss
    * @param {boolean} [options.moduleHooks] Whether to enable require/import hooks
+   * @param {boolean} [options.virtualCwd] Whether to enable virtual working directory
    */
   constructor(options = {}) {
     emitExperimentalWarning('fs.createVirtual');
@@ -79,6 +84,10 @@ class VirtualFileSystem {
     this[kFallthrough] = options.fallthrough !== false;
     this[kModuleHooks] = options.moduleHooks !== false;
     this[kPromises] = null; // Lazy-initialized
+    this[kVirtualCwdEnabled] = options.virtualCwd === true;
+    this[kVirtualCwd] = null; // Set when chdir() is called
+    this[kOriginalChdir] = null; // Saved process.chdir
+    this[kOriginalCwd] = null; // Saved process.cwd
   }
 
   /**
@@ -113,6 +122,74 @@ class VirtualFileSystem {
     return this[kFallthrough];
   }
 
+  /**
+   * Returns true if virtual working directory is enabled.
+   * @returns {boolean}
+   */
+  get virtualCwdEnabled() {
+    return this[kVirtualCwdEnabled];
+  }
+
+  // ==================== Virtual Working Directory ====================
+
+  /**
+   * Gets the virtual current working directory.
+   * Returns null if no virtual cwd is set.
+   * @returns {string|null}
+   */
+  cwd() {
+    if (!this[kVirtualCwdEnabled]) {
+      throw new ERR_INVALID_STATE('virtual cwd is not enabled');
+    }
+    return this[kVirtualCwd];
+  }
+
+  /**
+   * Sets the virtual current working directory.
+   * The path must exist in the VFS.
+   * @param {string} dirPath The directory path to set as cwd
+   */
+  chdir(dirPath) {
+    if (!this[kVirtualCwdEnabled]) {
+      throw new ERR_INVALID_STATE('virtual cwd is not enabled');
+    }
+
+    const normalized = normalizePath(dirPath);
+    const entry = this._resolveEntry(normalized);
+
+    if (!entry) {
+      throw createENOENT('chdir', normalized);
+    }
+
+    if (!entry.isDirectory()) {
+      throw createENOTDIR('chdir', normalized);
+    }
+
+    this[kVirtualCwd] = normalized;
+  }
+
+  /**
+   * Resolves a path relative to the virtual cwd if set.
+   * If the path is absolute or no virtual cwd is set, returns the path as-is.
+   * @param {string} inputPath The path to resolve
+   * @returns {string} The resolved path
+   */
+  resolvePath(inputPath) {
+    // If path is absolute, return as-is
+    if (inputPath.startsWith('/')) {
+      return normalizePath(inputPath);
+    }
+
+    // If virtual cwd is enabled and set, resolve relative to it
+    if (this[kVirtualCwdEnabled] && this[kVirtualCwd] !== null) {
+      const resolved = this[kVirtualCwd] + '/' + inputPath;
+      return normalizePath(resolved);
+    }
+
+    // Fall back to normalizing the path (will use real cwd)
+    return normalizePath(inputPath);
+  }
+
   // ==================== Entry Management ====================
 
   /**
@@ -240,6 +317,9 @@ class VirtualFileSystem {
     if (this[kModuleHooks]) {
       registerVFS(this);
     }
+    if (this[kVirtualCwdEnabled]) {
+      this._hookProcessCwd();
+    }
   }
 
   /**
@@ -253,16 +333,81 @@ class VirtualFileSystem {
     if (this[kModuleHooks]) {
       registerVFS(this);
     }
+    if (this[kVirtualCwdEnabled]) {
+      this._hookProcessCwd();
+    }
   }
 
   /**
    * Unmounts the VFS.
    */
   unmount() {
+    this._unhookProcessCwd();
     unregisterVFS(this);
     this[kMountPoint] = null;
     this[kMounted] = false;
     this[kOverlay] = false;
+    this[kVirtualCwd] = null; // Reset virtual cwd on unmount
+  }
+
+  /**
+   * Hooks process.chdir and process.cwd to support virtual cwd.
+   * @private
+   */
+  _hookProcessCwd() {
+    if (this[kOriginalChdir] !== null) {
+      // Already hooked
+      return;
+    }
+
+    const vfs = this;
+
+    // Save original process methods
+    this[kOriginalChdir] = process.chdir;
+    this[kOriginalCwd] = process.cwd;
+
+    // Override process.chdir
+    process.chdir = function chdir(directory) {
+      const normalized = normalizePath(directory);
+
+      // Check if this path is within VFS
+      if (vfs.shouldHandle(normalized)) {
+        vfs.chdir(normalized);
+        return;
+      }
+
+      // Fall through to real chdir
+      return vfs[kOriginalChdir].call(process, directory);
+    };
+
+    // Override process.cwd
+    process.cwd = function cwd() {
+      // If virtual cwd is set, return it
+      if (vfs[kVirtualCwd] !== null) {
+        return vfs[kVirtualCwd];
+      }
+
+      // Fall through to real cwd
+      return vfs[kOriginalCwd].call(process);
+    };
+  }
+
+  /**
+   * Restores original process.chdir and process.cwd.
+   * @private
+   */
+  _unhookProcessCwd() {
+    if (this[kOriginalChdir] === null) {
+      // Not hooked
+      return;
+    }
+
+    // Restore original process methods
+    process.chdir = this[kOriginalChdir];
+    process.cwd = this[kOriginalCwd];
+
+    this[kOriginalChdir] = null;
+    this[kOriginalCwd] = null;
   }
 
   // ==================== Path Resolution ====================