[XDebug Bridge] Load files in Devtools before running PHP with Xdebug enabled (#2527)

## Motivation for the change, related issues

Based on the following pull request : 

- #2442

The first approach was to load Devtools when running a file with Xdebug
enabled PHP.wasm. Unfortunately, the user experience was not great. e.g.
files were loaded only when executed.

The new approach opens de Devtools Source panel with the relevant loaded
files ready to be manipulated.
Once the breakpoints are set, the PHP file can be executed and paused
with Xdebug enabled PHP.wasm.

## Implementation details

- DevTools Sources Opening : Devtools Source panel is automatically
opened when bridge starts.
- Console Instructions : A startup message guides users on how to debug
with the bridge.
- Source File Loading : Relevant PHP files are preloaded in DevTools for
inspection and breakpoints.
- Pending Breakpoints : Breakpoints set before Xdebug init are applied
once the session starts.
- URI Normalization : Paths are consistently mapped between Bridge, CDP,
and DBGP.
- CDP Command Buffer : CDP requests are buffered until the bridge is
fully initialized.
- `breakOnFirstLine` Option : Allows breaking on the first executed line
when no breakpoints exist.
- Test Coverage

## Testing Instructions with Xdebug Bridge

1. Run the devtools

```
npx xdebug-bridge
```

2. Connect to the devtools

```
Starting XDebug Bridge...
Connect Chrome DevTools to CDP at:
devtools://devtools/bundled/inspector.html?ws=localhost:9229
```

3. Set a breakpoint in a file

<img width="1920" height="656" alt="screenshot-001"
src="https://github.com/user-attachments/assets/3591ea63-7344-4a53-98ee-6ff70440dbaf"
/>

4. Run the PHP script with PHP.wasm CLI and Xdebug option

```
npx php-wasm-cli test.php --xdebug
```

<img width="1920" height="651" alt="screenshot-002"
src="https://github.com/user-attachments/assets/e5c9049d-c556-41b3-b99c-a9a2000f5da4"
/>


5. Resume script execution and repeat step 4 indefinitely

<img width="1919" height="667" alt="screenshot-003"
src="https://github.com/user-attachments/assets/aacfaf3d-0afb-497e-b5cd-8d3eb0ce98de"
/>

## Testing Instructions with PHP.wasm CLI

1. Run the script with Xdebug and Devtools options

```
npx php-wasm-cli test.php --experimental-devtools --xdebug
```

2. Connect to the devtools

```
Starting XDebug Bridge...
Connect Chrome DevTools to CDP at:
devtools://devtools/bundled/inspector.html?ws=localhost:9229
```

3. It will pause on the first breakable PHP code

<img width="1920" height="651" alt="screenshot-002"
src="https://github.com/user-attachments/assets/e5c9049d-c556-41b3-b99c-a9a2000f5da4"
/>

## Testing Instructions with PHP.wasm Node

1. Write the following script 

```
import { PHP } from '@php-wasm/universal';
import { loadNodeRuntime } from '@php-wasm/node';
import { startBridge } from '@php-wasm/xdebug-bridge';


const php = new PHP(await loadNodeRuntime('8.4', {withXdebug: true}));

const bridge = await startBridge({phpInstance: php, breakOnFirstLine: true});

bridge.start();

await php.runStream({scriptPath: `test.php`});
```

1. Run the script with Node

```
node script.js
```

3. Connect to the devtools

```
Starting XDebug Bridge...
Connect Chrome DevTools to CDP at:
devtools://devtools/bundled/inspector.html?ws=localhost:9229
```

4. It will pause on the first breakable PHP code

<img width="1920" height="651" alt="screenshot-002"
src="https://github.com/user-attachments/assets/e5c9049d-c556-41b3-b99c-a9a2000f5da4"
/>


## Testing Instructions in `wordpress-playground` 

1. Run the devtools

```
nx reset && nx run php-wasm-xdebug-bridge:dev --php-root /absolute/path/to/the/debuggable/directory
```

2. Connect to the devtools

```
Starting XDebug Bridge...
Connect Chrome DevTools to CDP at:
devtools://devtools/bundled/inspector.html?ws=localhost:9229
```

3. Set a breakpoint in a file

<img width="1920" height="656" alt="screenshot-001"
src="https://github.com/user-attachments/assets/3591ea63-7344-4a53-98ee-6ff70440dbaf"
/>

5. Run the PHP script

```
nx reset && nx run php-wasm-cli:dev /absolute/path/to/the/debuggable/directory/file.php --xdebug
```

<img width="1920" height="651" alt="screenshot-002"
src="https://github.com/user-attachments/assets/e5c9049d-c556-41b3-b99c-a9a2000f5da4"
/>


6. Resume script execution and repeat step 4 indefinitely

<img width="1919" height="667" alt="screenshot-003"
src="https://github.com/user-attachments/assets/aacfaf3d-0afb-497e-b5cd-8d3eb0ce98de"
/>

Author: mho22

packages/php-wasm/cli/src/main.ts

@@ -106,7 +106,7 @@ ${process.argv[0]} ${process.execArgv.join(' ')} ${process.argv[1]}
 	useHostFilesystem(php);
 
 	if (hasDevtoolsOption && hasXdebugOption) {
-		const bridge = await startBridge({});
+		const bridge = await startBridge({ breakOnFirstLine: true });
 
 		bridge.start();
 	}

packages/php-wasm/xdebug-bridge/README.md

@@ -62,10 +62,9 @@ npx xdebug-bridge --help
 -   `dbgpPort`: Port to listen for XDebug connections (default: 9003)
 -   `phpRoot`: Root path for php files
 -   `verbosity`: Output logs and progress messages (choices: "quiet", "normal", "debug") (default: "normal")
--   `remoteRoot`: Remote root path for php files
--   `localRoot`: Local root path for php files
 -   `phpInstance`: PHP instance
 -   `getPHPFile`: Custom file listing function
+-   `breakOnFirstLine`: Breaks on the first breakable line
 
 ## Events
 
@@ -74,7 +73,7 @@ The bridge listens to events for monitoring connection activity:
 #### From Xdebug
 
 -   `connected`: Xdebug Server has started
--   `close`: Xdebug Server has stopped
+-   `disconnected`: Xdebug Server has stopped
 -   `message`: Raw XDebug data received
 -   `error`: Xdebug Server error occurred
 

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

@@ -5,6 +5,8 @@ import { type WebSocket, WebSocketServer } from 'ws';
 export class CDPServer extends EventEmitter {
 	private wss: WebSocketServer;
 	private ws: WebSocket | null = null;
+	private connected = false;
+	private buffer: any[] = [];
 
 	constructor(port = 9229) {
 		super();
@@ -28,7 +30,12 @@ export class CDPServer extends EventEmitter {
 				} catch {
 					return;
 				}
-				this.emit('message', message);
+
+				if (this.connected) {
+					this.emit('message', message);
+				} else {
+					this.buffer.push(message);
+				}
 			});
 			ws.on('close', () => {
 				this.ws = null;
@@ -38,6 +45,26 @@ export class CDPServer extends EventEmitter {
 				this.emit('error', err);
 			});
 		});
+
+		// When a new 'message' listener is registered,
+		// it replays any buffered messages on the next
+		// tick. This ensures that the listener receives
+		// all messages that arrived before it was opened.
+		// Once replayed, it clears the buffer and marks
+		// the connection as established.
+		this.on('newListener', (event) => {
+			if (event === 'message') {
+				process.nextTick(() => {
+					for (const message of this.buffer) {
+						this.emit('message', message);
+					}
+
+					this.buffer = [];
+
+					this.connected = true;
+				});
+			}
+		});
 	}
 
 	sendMessage(message: any) {

packages/php-wasm/xdebug-bridge/src/lib/dbgp-session.ts

@@ -23,7 +23,7 @@ export class DbgpSession extends EventEmitter {
 			socket.on('data', (data: Buffer) => this.onData(data.toString()));
 			socket.on('close', () => {
 				this.socket = null;
-				this.emit('close');
+				this.emit('disconnected');
 			});
 			socket.on('error', (err) => {
 				// Forward error events if needed

packages/php-wasm/xdebug-bridge/src/lib/run-cli.ts

@@ -43,7 +43,6 @@ Usage: xdebug-bridge [options]
 		.option('php-root', {
 			type: 'string',
 			description: 'Path to PHP root directory',
-			default: './',
 		})
 		.option('verbosity', {
 			type: 'string',

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

@@ -1,7 +1,7 @@
 import { logger } from '@php-wasm/logger';
 import type { PHP } from '@php-wasm/universal';
 import { readdirSync, readFileSync, lstatSync } from 'fs';
-import { join } from 'path';
+import path from 'path';
 import { CDPServer } from './cdp-server';
 import { DbgpSession } from './dbgp-session';
 import { XdebugCDPBridge } from './xdebug-cdp-bridge';
@@ -11,21 +11,21 @@ export type StartBridgeConfig = {
 	cdpHost?: string;
 	dbgpPort?: number;
 	phpRoot?: string;
-	remoteRoot?: string;
-	localRoot?: string;
 	phpInstance?: PHP;
 	getPHPFile?: (path: string) => string | Promise<string>;
+	breakOnFirstLine?: boolean;
 };
 
 export async function startBridge(config: StartBridgeConfig) {
 	const cdpPort = config.cdpPort ?? 9229;
 	const dbgpPort = config.dbgpPort ?? 9003;
 	const cdpHost = config.cdpHost ?? 'localhost';
-	const phpRoot = config.phpRoot ?? import.meta.dirname;
+	const phpRoot = config.phpRoot ?? process.cwd();
+	const breakOnFirstLine = config.breakOnFirstLine ?? false;
 
 	logger.log('Starting XDebug Bridge...');
 
-	// index.ts - Entry point to start the service
+	// Entry point to start the service
 	const cdpServer = new CDPServer(cdpPort);
 
 	logger.log('Connect Chrome DevTools to CDP at:');
@@ -48,13 +48,13 @@ export async function startBridge(config: StartBridgeConfig) {
 		const results: string[] = [];
 		const list = readdirSync(dir);
 		for (const file of list) {
-			const filePath = join(dir, file);
+			const filePath = path.join(dir, file);
 			// lstat avoids crashes when encountering symlinks
 			const stat = lstatSync(filePath);
 			if (stat && stat.isDirectory()) {
 				results.push(...getPhpFiles(filePath));
 			} else if (file.endsWith('.php')) {
-				results.push(`file://${filePath}`);
+				results.push(filePath);
 			}
 		}
 		return results;
@@ -64,20 +64,13 @@ export async function startBridge(config: StartBridgeConfig) {
 		? (path: 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) => readFileSync(path, 'utf-8');
 
 	const phpFiles = getPhpFiles(phpRoot);
 	return new XdebugCDPBridge(dbgpSession, cdpServer, {
 		knownScriptUrls: phpFiles,
-		remoteRoot: config.remoteRoot,
-		localRoot: config.localRoot,
+		phpRoot,
 		getPHPFile,
+		breakOnFirstLine,
 	});
 }