Fix Playground CLI boot from native dirs on Windows

[brandonpayton]

Motivation for the change, related issues

I began this PR to run the Playground CLI tests on Windows:

It may be too much to run 100% of our unit tests on Windows in CI, but maybe we can run some integration tests for those supported platforms.

But once we started running those tests, we found a bug that prevented Playground CLI boot in Windows when mount a native /wordpress directory. Since #2446 landed, every Playground CLI instance mounts a native directory to /wordress. This is an important fix.

So this PR became a bug-fixing PR that also enables some Playground CLI tests for Windows.

Implementation details

• Add an OS matrix to the test-playground-cli section of CI.yml
• Adjust our custom Node.js module loader to produce module specifiers that also work in Windows. This means preserving paths as file:// URLs. Our run-cli tests currently rely upon this loader, and it is good to make sure contributors on Windows can use the same commands to run unbuilt Playground CLI.
• Disabling use of fs-ext package for file locking in Windows because related "RESOURCE BUSY" errors were interfering with boot.

Testing Instructions (or ideally a Blueprint)

• CI

[brandonpayton]

This is unrelated but looked like an incorrect comment to me based on the goal of the test.

[adamziel]

NICE!

[brandonpayton]

We are getting this failure for Windows:

RUN v2.1.9 D:/a/wordpress-playground/wordpress-playground/packages/playground/cli node:internal/modules/esm/load:184 throw new ERR_UNSUPPORTED_ESM_URL_SCHEME(parsed, schemes); ^ Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]: Only URLs with a scheme in: file, data, and node are supported by the default ESM loader. On Windows, absolute paths must be valid file:// URLs. Received protocol 'd:' 

It looks like it has to do with our custom module loader. Looking.

[brandonpayton]

Because it is important Playground CLI run well on Windows, I installed Windows on a VM, set up a basic dev environment, and debugged the loader issues in Windows. It was difficult getting npm install to work with node-gyp (because of other dev deps, not the optional fs-ext package). But after that was working, the loader issues were easy to fix.

Now the loader is no longer complaining, but WP boot is failing with the following error:

Error: Error connecting to the SQLite database. 

@adamziel I am worried this could be a new issue in Windows after #2446 landed. Will check and follow up here.

[brandonpayton]

Side-note:
It's funny. The actual path-related test failures for Windows here are related to the test runner.
https://github.com/WordPress/wordpress-playground/actions/runs/17818239166/job/50655545765?pr=2642#step:4:31
But there were also real path-related issues in the custom loader which are now fixed.

I can reproduce the test runner error locally in Windows, so hopefully it will not be too hard to fix.

[brandonpayton]

@adamziel I tested and confirmed:
Without the native mounts change (and with the changes in this PR), I am now able to run Playground CLI in Windows via npx nx unbuilt-asyncify playground-cli. After that change, WordPress boot fails with the error-connecting-to-sqlite message.

I plan to focus on debugging this in the morning, but I wanted to let you know in case you want to revert or at least avoid tagging a new release until we fix the issue.

[brandonpayton]

I was able to fix the vitest config so the tests can run in Windows. After that, they start running into the sqlite connection error.

[brandonpayton]

OK, it looks like the fs-ext dependency is causing problems in Windows. There are these errors during boot:

[18-Sep-2025 17:58:49 UTC] PHP Notice: file_put_contents(): Write of 13 bytes failed with errno=10 Resource busy in /internal/shared/sqlite-database-integration/wp-includes/sqlite/class-wp-sqlite-db.php on line 639 [18-Sep-2025 17:58:49 UTC] PHP Notice: file_put_contents(): Write of 28 bytes failed with errno=10 Resource busy in /internal/shared/sqlite-database-integration/wp-includes/sqlite/class-wp-sqlite-db.php on line 649 

If I move node_modules/fs-ext to node_modules/fs-ext.backup, Playground CLI skips using fs-ext and can be successfully started via npx nx unbuilt-asyncify playground-cli -- server.

I am considering what we should do here in the short term. I don't yet know the root cause, but we could remove the package dependency entirely until we know more. It would basically mean that the SQLite database wouldn't appear to be locked for external programs, but multi-worker Playground CLI would still coordinate locking to avoid corrupting the database via multiple workers.

cc @adamziel

[adamziel]

The easiest solution seems to be removing fs-ext from dependencies and opening a long-term pr to re-add it.

[adamziel]

...unless it's installed globally. Dang. Okay, can we use fs-ext based on an env variable or a cli flag? So it won't be loaded unless explicitly requested

[brandonpayton]

@adamziel, for now, I just updated the run-cli logic to avoid loading fs-ext when os.platform() == 'win32'. Initially, I tried removing the dependency entirely, thinking that it would be simple, but some of our file locking tests depend on fs-ext to the point that it was awkward to extract. In addition, I think it would be good to leave it in place where it is not causing trouble, and we can file an issue to find a solution that works better with Windows.

Does this sound OK?

[brandonpayton]

When running the full test suite in Windows, I (and I believe CI as well) were encountering failures to allocate new memory. It seemed to have something to do with the test count rather than with specific tests. I wonder if allocations of previous runCLI() calls are not being GC'd somehow during test.

As a compromise in order to get some Windows tests in, I just added a condition to run a single run-cli test for auto-mounting a WordPress dir. Then, if we have time later, we can attempt to address the issue and expand the tests that are run for Windows.

I also ended up disabling the tests for macOS because they were running into EMFILE: too many open files errors within the GitHub runner. I'd love to fix this but am willing to let it go for the moment since so many of us develop and test on macs already.

[brandonpayton]

@adamziel this PR morphed into a bug-fix PR. I think it is ready for review and merge if you're good with the approach.

[adamziel]

Yay! Good find and thank you Brandon!