[ xdebug ] Add --experimental-devtools option in Playground CLI (#2411)

## Motivation for the change, related issues

This pull request adds a `--experimental-devtools` option in
`wp-playground/cli`.

[Roadmap](#2315)

## Related issues and pull requests

- #2408
- #2402
- #2398
- #2346
- #2288

## Implementation details

- Simple implementation of a Devtools option. It checks for a
`experimentalDevtools` argument that starts the `xdebug-to-cdp-bridge`
process.
- Changes the `StartBridgeConfig` `getPHPFile` property type from
`(path: string) => string` to `(path: string) => Promise<string>` and
adapt the related code.

## Testing Instructions

### In WordPress-Playground repository

1. Write a script like the following `cli.ts` : 

```typescript
import { runCLI } from "./packages/playground/cli/src/run-cli";

const script = `
<?php

$test = 42;

echo "Output!\n";

function test() {
	echo "Hello Xdebug World!\n";
}

test();
`;

const cliServer = await runCLI({command: 'server', xdebug: true, experimentalDevtools: true});

cliServer.playground.writeFile('xdebug.php', script);

const result = await cliServer.playground.run({scriptPath: `xdebug.php`});

console.log(result.text);
```

2. Run the following command : 

```
> node --no-warnings --experimental-wasm-stack-switching --experimental-wasm-jspi --loader=./packages/meta/src/node-es-module-loader/loader.mts cli.ts

Starting a PHP server...
Setting up WordPress undefined
Resolved WordPress release URL: https://downloads.w.org/release/wordpress-6.8.2.zip
Fetching SQLite integration plugin...
Booting WordPress...
Booted!
Running the Blueprint...
Running the Blueprint – 100%
Finished running the blueprint
WordPress is running on http://127.0.0.1:61290
Connect Chrome DevTools to CDP at:
devtools://devtools/bundled/inspector.html?ws=localhost:9229

...

Chrome connected! Initializing Xdebug receiver...
XDebug receiver running on port 9003
Running a PHP script with Xdebug enabled...
```

### In a non-related Playground project

1. Install dependencies

```
npm install @wp-playground/cli
```

2. Write a script like the following `cli.ts` :

```typescript
import { runCLI } from "@wp-playground/cli";

const script = `
<?php

$test = 42;

echo "Output!\n";

function test() {
	echo "Hello Xdebug World!\n";
}

test();
`;

const cliServer = await runCLI({command: 'server',  xdebug: true, experimentalDevtools: true});

await cliServer.playground.writeFile(`xdebug.php`, script);

const result = await cliServer.playground.run({scriptPath: `xdebug.php`});

console.log(result.text);
```

3. Run command : 

```
> node cli.js

Starting a PHP server...
Setting up WordPress undefined
Resolved WordPress release URL: https://downloads.w.org/release/wordpress-6.8.2.zip
Fetching SQLite integration plugin...
Booting WordPress...
Booted!
Running the Blueprint...
Running the Blueprint – 100%
Finished running the blueprint
WordPress is running on http://127.0.0.1:61859
Connect Chrome DevTools to CDP at:
devtools://devtools/bundled/inspector.html?ws=localhost:9229

...

Chrome connected! Initializing Xdebug receiver...
XDebug receiver running on port 9003
Running a PHP script with Xdebug enabled...
```

<img width="920" height="471" alt="screencapture"
src="https://github.com/user-attachments/assets/b3548d0e-f824-41c4-9148-3e4f106b4116"
/>

Note: It will need 23 step overs before leaving the
`auto_prepend_file.php` and entering the `xdebug.php` script.

Author: mho22

packages/php-wasm/xdebug-bridge/src/lib/start-bridge.ts

@@ -14,7 +14,7 @@ export type StartBridgeConfig = {
 	localRoot?: string;
 
 	phpInstance?: PHP;
-	getPHPFile?: (path: string) => string;
+	getPHPFile?: (path: string) => Promise<string>;
 };
 
 export async function startBridge(config: StartBridgeConfig) {
@@ -58,17 +58,21 @@ export async function startBridge(config: StartBridgeConfig) {
 	}
 
 	const getPHPFile = config.phpInstance
-		? (path: string) => config.phpInstance!.readFileAsText(path)
+		? (path: string) =>
+				new Promise<string>(() =>
+					config.phpInstance!.readFileAsText(path)
+				)
 		: config.getPHPFile
 		? config.getPHPFile
-		: (path: string) => {
-				// Default implementation: read from filesystem
-				// Convert file:/// URLs to local paths
-				const localPath = path.startsWith('file://')
-					? path.replace('file://', '')
-					: path;
-				return readFileSync(localPath, 'utf-8');
-		  };
+		: (path: string) =>
+				new Promise<string>(() => {
+					// Default implementation: read from filesystem
+					// Convert file:/// URLs to local paths
+					const localPath = path.startsWith('file://')
+						? path.replace('file://', '')
+						: path;
+					return readFileSync(localPath, 'utf-8');
+				});
 
 	const phpFiles = getPhpFiles(phpRoot);
 	return new XdebugCDPBridge(dbgpSession, cdpServer, {

packages/php-wasm/xdebug-bridge/src/lib/xdebug-cdp-bridge.ts

@@ -28,7 +28,7 @@ export interface XdebugCDPBridgeConfig {
 	knownScriptUrls: string[];
 	remoteRoot?: string;
 	localRoot?: string;
-	getPHPFile(path: string): string;
+	getPHPFile(path: string): Promise<string>;
 }
 
 export class XdebugCDPBridge {
@@ -45,7 +45,7 @@ export class XdebugCDPBridge {
 	private xdebugConnected = false;
 	private xdebugStatus = 'starting';
 	private initFileUri: string | null = null;
-	private readPHPFile: (path: string) => string;
+	private readPHPFile: (path: string) => Promise<string>;
 	private remoteRoot: string;
 	private localRoot: string;
 
@@ -212,7 +212,7 @@ export class XdebugCDPBridge {
 		return txnIdStr;
 	}
 
-	private handleCdpMessage(message: any) {
+	private async handleCdpMessage(message: any) {
 		const { id, method, params } = message;
 		let result: any = {};
 		let sendResponse = true;
@@ -423,7 +423,9 @@ export class XdebugCDPBridge {
 				)?.[0];
 				let scriptSource = '';
 				if (uri) {
-					scriptSource = this.readPHPFile(this.uriToRemotePath(uri));
+					scriptSource = await this.readPHPFile(
+						this.uriToRemotePath(uri)
+					);
 				}
 				result = { scriptSource };
 				break;

packages/playground/cli/src/run-cli.ts

@@ -47,6 +47,7 @@ import { isValidWordPressSlug } from './is-valid-wordpress-slug';
 import { resolveBlueprint } from './resolve-blueprint';
 import { BlueprintsV2Handler } from './blueprints-v2/blueprints-v2-handler';
 import { BlueprintsV1Handler } from './blueprints-v1/blueprints-v1-handler';
+import { startBridge } from '@php-wasm/xdebug-bridge';
 
 export async function parseOptionsAndRunCLI() {
 	try {
@@ -184,6 +185,11 @@ export async function parseOptionsAndRunCLI() {
 				type: 'boolean',
 				default: false,
 			})
+			.option('experimental-devtools', {
+				describe: 'Enable experimental browser development tools.',
+				type: 'boolean',
+				default: false,
+			})
 			// TODO: Should we make this a hidden flag?
 			.option('experimental-multi-worker', {
 				describe:
@@ -301,6 +307,7 @@ export interface RunCLIArgs {
 	internalCookieStore?: boolean;
 	'additional-blueprint-steps'?: any[];
 	xdebug?: boolean;
+	experimentalDevtools?: boolean;
 	'experimental-blueprints-v2-runner'?: boolean;
 
 	// --------- Blueprint V1 args -----------
@@ -535,6 +542,15 @@ export async function runCLI(args: RunCLIArgs): Promise<RunCLIServer> {
 
 				logger.log(`WordPress is running on ${absoluteUrl}`);
 
+				if (args.experimentalDevtools && args.xdebug) {
+					const bridge = await startBridge({
+						getPHPFile: async (path: string) =>
+							await playground!.readFileAsText(path),
+					});
+
+					bridge.start();
+				}
+
 				return {
 					playground,
 					server,