Motivation for the change, related issues

Today, Playground enables Xdebug during boot which may be surprising to users. If the debugger breaks at the first line, the user will be debugging the Playground boot process. Let's skip this by default and consider adding a command line flag to enable boot-time Xdebug breaks.

Implementation details

A big change in this PR is that the first Playground worker is now only used during boot. We discard it after that boot and setup process completes. Some positive consequences of this change are:

• Reflects the truth that the Playground worker has special configuration and responsibilities as part of the boot process.
• Allows us to be clear that all post-boot workers are based on the same configuration and truth. There is no remaining special boot-time worker that might behave differently from the others.
• Allows us to control whether the boot-and-setup worker has Xdebug enabled separately from the regular workers.

Testing Instructions (or ideally a Blueprint)

Before checking out this branch:

• Create a local directory at the top level of your Playground working dir that can be mounted as /wordpress
• Run npx nx unbuilt-asyncify playground-cli -- server --mount-dir <local-dir> /wordpress so Playground will download and install WordPress in your local directory.
• Open the local directory as a project root in Visual Studio Code, select the debug pane, and create a launch.json file containing the following configuration:

  {
      "name": "PR test for WP Playground CLI - Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
          "/": "${workspaceFolder}/.playground-xdebug-root",
          "/wordpress": "${workspaceFolder}/"
      },
      "stopOnEntry": true,
  }
  

• Start the "PR test for WP Playground CLI - Listen for Xdebug" debug target within vscode
• cd into the local WP dir and run the following command and confirm that vscode hit a breakpoint before the "WordPress is running on http://127.0.0.1:9400" message is printed:
  node --experimental-strip-types --experimental-transform-types --disable-warning=ExperimentalWarning --import ../packages/meta/src/node-es-module-loader/register.mts ../packages/playground/cli/src/cli.ts server --auto-mount=. --verbosity=debug --skip-wordpress-setup --xdebug --experimental-unsafe-ide-integration --php=8.3 --experimental-multi-worker=4

After checking out this branch:

• Open the previously created local WP dir as the workspace root within vscode
• Run the "PR test for WP Playground CLI - Listen for Xdebug" debug target
• cd into the local WP dir, re-run the above node command, and confirm that no breakpoint was hit during the boot process.

It looks like Xdebug support relies upon being set up in the initial worker. Currently, this PR breaks the Xdebug feature. Will look at fixing that.

It looks like Xdebug support relies upon being set up in the initial worker. Currently, this PR breaks the Xdebug feature. Will look at fixing that.

It turns out that, even though we were relaying the --xdebug option when creating subsequent workers, the boot function for the v1 workers was only using the xdebug flag for the initial worker. This is now fixed.

The v2 worker appears to consider the xdebug flag for both initial and subsequent workers.

This is almost ready. There are a few remaining test failures, and I'm looking at those.

It turns out that using a using a pool of non-initial workers revealed some bugs like:

• PHP Version wasn't being respected by the Blueprints v1 handler, except for the initial worker. It looks like this happened when we adjusted Blueprint v1 resolution. It worked for the primary worker but wasn't fully wired for subsequent workers.
• The v1 followSymlinks flag wasn't being properly passed to non-primary workers.

These are now fixed, and the tests are passing again.

I think this is ready for review. Note, this PR includes some cleanup-related refactor from #2836, and it would probably make more sense to review that one before this one.

Looks solid and isn't that big of a change now that the other PR has landed. Let's wait for the tests to confirm my rebase didn't break it and merge. Yay! 🎉