## Motivation for the change, related issues

Populates the new `php-wasm-xdebug-bridge` package which will connect
Xdebug with Browser Devtools.

[Roadmap](#2315)

## Related issues and pull requests

- #2346
- #2398
- #2288

## Implementation details

- DBGP communication TCP server, which the bridge uses to communication
between PHP.wasm XDebug and the CDP server. XDebug defaultly discusses
on port 9003. While the DBGP server is set on port 9003 by default.

- CDP Websocket Server, which communicates between the Browser Devtools
and the DBGP server, with the help of a bridge. The default port is
9229.

- XDebug <-> CDP Bridge, which ties the above implementations together.
It plays with all the specificities of the DBGP protocol and the CDP
protocol.

- A `startBridge` function that will initialize the servers, get the
soon-to-be-debugged files and return the built bridge.

- A CLI tool that will start the bridge between the browser and a
XDebug.

## Testing Instructions

Create a `xdebug.php` PHP file at the root of the repository :

```php
<?php

$test = 42;  // Set a breakpoint on this line

echo "Output!\n";

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

test();
```

### From Wordpress-Playground repository

1. Run the `xdebug-bridge` command in a first terminal : 

```
> npx nx run php-wasm-xdebug-bridge:dev

...

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

2. Run the `php-wasm-cli` command in a second terminal : 

```
> nx run php-wasm-cli:dev --xdebug xdebug.php

Output!
Hello Xdebug World!
```

### From non-related Playground project

1. Install dependencies

```
npm install @php-wasm/cli @php-wasm/xdebug-bridge
```

2. Run the `xdebug-bridge` command in a first terminal : 

```
> npx xdebug-bridge

...

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

3. Run the `@php-wasm/cli` command in a second terminal : 

```
> npx cli --xdebug xdebug.php

Output!
Hello Xdebug World!
```

<img width="748" height="409" alt="screencapture"
src="https://github.com/user-attachments/assets/b0232831-c9b3-4bb2-95aa-b1d51b72766e"
/>

---------

Co-authored-by: mho22 <[email protected]>

)

## 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.