[Node] Handle symlinked directories in Node FS mounts

[adamziel]

What it does

Makes NodeFSMountHandler preserve symlinked directories as directories when mounting host paths into PHP.wasm.

Rationale

lstatSync() reports the symlink itself, so a symlink pointing at a directory was treated like a file. statSync() fixes the placeholder decision, but NODEFS also reads the mount root path. Passing the original symlink path still leaves the mounted root shaped like the symlink.

Implementation

Resolves localPath with realpathSync() before creating the VFS placeholder and before calling FS.mount(). The placeholder is then created from statSync(mountRoot), and NODEFS receives the resolved root path.

Added a regression test that checks the actual mounted VFS node mode for both normal directories and symlinked directories. Before this PR, the symlinked-directory case produced a non-directory mount node.

Testing instructions

Focused checks run locally:

npx vitest run --config packages/php-wasm/node/vite.config.ts packages/php-wasm/node/src/test/mount.spec.ts
npx vitest run --config packages/php-wasm/node/vite.jspi.config.ts packages/php-wasm/node/src/test/mount.spec.ts

CI group checks run locally:

npx nx run php-wasm-node:test-group-3-asyncify
npx nx run php-wasm-node:test-group-3-jspi

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates NodeFSMountHandler to treat symlinked directories as directories in the VFS by following symlinks when creating mount-point placeholders, and adds a regression test for unmount cleanup when the mounted directory is the CWD.

Changes:

• Switch placeholder type detection from lstatSync() to statSync() to follow symlinks.
• Add a regression test ensuring directory-cleanup guard triggers when CWD is inside the mounted directory.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
packages/php-wasm/node/src/lib/node-fs-mount.ts	Uses statSync() so symlinked dirs get directory placeholders; adds an explanatory inline comment.
packages/php-wasm/node/src/test/mount.spec.ts	Adds a regression test covering unmount cleanup behavior when the mount is the current working directory.

Comments suppressed due to low confidence (1)

packages/php-wasm/node/src/lib/node-fs-mount.ts:39

• This error message is misleading given the new implementation: the check is now based on statSync() (which resolves symlinks), so the failure can occur for non-symlink paths and the message doesn’t reflect the actual supported mount targets. Consider rewording to something like “supports mounting only files and directories (including symlinks to files/directories)” to match the behavior.

				throw new Error(
					'Unsupported file type. PHP-wasm supports only symlinks that link to files, directories, or symlinks.'
				);

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.