[ xdebug ] Add --experimental-devtools option in Playground CLI

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,