[ xdebug ] Bridge DBGP session with CDP server

CHANGELOG.md

@@ -4,61 +4,59 @@ All notable changes to this project are documented in this file by a CI job
 that runs on every NPM release. The file follows the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 format.
 
-## [v2.0.1] (2025-07-23) 
+## [v2.0.1] (2025-07-23)
 
 ### Blueprints
 
-- Rewrite paths in the wp-cli step. Improve error reporting. ([#2406](https://github.com/WordPress/wordpress-playground/pull/2406))
+-   Rewrite paths in the wp-cli step. Improve error reporting. ([#2406](https://github.com/WordPress/wordpress-playground/pull/2406))
 
 ### Contributors
 
 The following contributors merged PRs in this release:
 
 @adamziel
 
-
-## [v2.0.0] (2025-07-23) 
+## [v2.0.0] (2025-07-23)
 
 ### Enhancements
 
-- [Playground CLI] Improve error reporting. ([#2401](https://github.com/WordPress/wordpress-playground/pull/2401))
-- [Playground CLI] Kebab-case yargs options declarations. ([#2399](https://github.com/WordPress/wordpress-playground/pull/2399))
+-   [Playground CLI] Improve error reporting. ([#2401](https://github.com/WordPress/wordpress-playground/pull/2401))
+-   [Playground CLI] Kebab-case yargs options declarations. ([#2399](https://github.com/WordPress/wordpress-playground/pull/2399))
 
 ### Blueprints
 
-- Expose Blueprints v2 runner in Playground CLI. ([#2394](https://github.com/WordPress/wordpress-playground/pull/2394))
-- Extract Blueprint v1-specific parts of Playground CLI. ([#2392](https://github.com/WordPress/wordpress-playground/pull/2392))
-- [Playground CLI] Separate Blueprints v1 and Blueprints v2 code paths. ([#2396](https://github.com/WordPress/wordpress-playground/pull/2396))
+-   Expose Blueprints v2 runner in Playground CLI. ([#2394](https://github.com/WordPress/wordpress-playground/pull/2394))
+-   Extract Blueprint v1-specific parts of Playground CLI. ([#2392](https://github.com/WordPress/wordpress-playground/pull/2392))
+-   [Playground CLI] Separate Blueprints v1 and Blueprints v2 code paths. ([#2396](https://github.com/WordPress/wordpress-playground/pull/2396))
 
 ### Tools
 
-- [XDebug] Add a mock @php-wasm/xdebug-bridge package. ([#2398](https://github.com/WordPress/wordpress-playground/pull/2398))
+-   [XDebug] Add a mock @php-wasm/xdebug-bridge package. ([#2398](https://github.com/WordPress/wordpress-playground/pull/2398))
 
 ### Documentation
 
-- Adding Brazilian Portuguese translation for developer documentation. ([#2391](https://github.com/WordPress/wordpress-playground/pull/2391))
+-   Adding Brazilian Portuguese translation for developer documentation. ([#2391](https://github.com/WordPress/wordpress-playground/pull/2391))
 
 ### Website
 
-- [Remote] Use CORS proxy in embedded Playgrounds. ([#2369](https://github.com/WordPress/wordpress-playground/pull/2369))
+-   [Remote] Use CORS proxy in embedded Playgrounds. ([#2369](https://github.com/WordPress/wordpress-playground/pull/2369))
 
 ### Bug Fixes
 
-- CLI: Fix --login option and "landingPage" Blueprint property. ([#2344](https://github.com/WordPress/wordpress-playground/pull/2344))
+-   CLI: Fix --login option and "landingPage" Blueprint property. ([#2344](https://github.com/WordPress/wordpress-playground/pull/2344))
 
 ### Various
 
-- Add Japanese translations to steps and steps shorthands. ([#2386](https://github.com/WordPress/wordpress-playground/pull/2386))
-- Add OPCache support. ([#2400](https://github.com/WordPress/wordpress-playground/pull/2400))
-- [Node] Gracefully handle connection errors in the outbound network proxy. ([#2370](https://github.com/WordPress/wordpress-playground/pull/2370))
+-   Add Japanese translations to steps and steps shorthands. ([#2386](https://github.com/WordPress/wordpress-playground/pull/2386))
+-   Add OPCache support. ([#2400](https://github.com/WordPress/wordpress-playground/pull/2400))
+-   [Node] Gracefully handle connection errors in the outbound network proxy. ([#2370](https://github.com/WordPress/wordpress-playground/pull/2370))
 
 ### Contributors
 
 The following contributors merged PRs in this release:
 
 @adamziel @fellyph @shimotmk @zaerl
 
-
 ## [v1.2.3] (2025-07-21)
 
 ### Enhancements

package.json

@@ -67,6 +67,7 @@
 	"dependencies": {
 		"@preact/signals-react": "1.3.6",
 		"@reduxjs/toolkit": "2.6.1",
+		"@types/xml2js": "0.4.14",
 		"@wordpress/dataviews": "4.5.0",
 		"@zip.js/zip.js": "2.7.57",
 		"ajv": "8.12.0",
@@ -87,6 +88,7 @@
 		"react-transition-group": "4.4.5",
 		"sha.js": "2.4.11",
 		"wasm-feature-detect": "1.8.0",
+		"xml2js": "0.6.2",
 		"yargs": "17.7.2"
 	},
 	"devDependencies": {

packages/docs/site/docs/main/changelog.md

@@ -9,61 +9,59 @@ All notable changes to this project are documented in this file by a CI job
 that runs on every NPM release. The file follows the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 format.
 
-## [v2.0.1] (2025-07-23) 
+## [v2.0.1] (2025-07-23)
 
 ### Blueprints
 
-- Rewrite paths in the wp-cli step. Improve error reporting. ([#2406](https://github.com/WordPress/wordpress-playground/pull/2406))
+-   Rewrite paths in the wp-cli step. Improve error reporting. ([#2406](https://github.com/WordPress/wordpress-playground/pull/2406))
 
 ### Contributors
 
 The following contributors merged PRs in this release:
 
 @adamziel
 
-
-## [v2.0.0] (2025-07-23) 
+## [v2.0.0] (2025-07-23)
 
 ### Enhancements
 
-- [Playground CLI] Improve error reporting. ([#2401](https://github.com/WordPress/wordpress-playground/pull/2401))
-- [Playground CLI] Kebab-case yargs options declarations. ([#2399](https://github.com/WordPress/wordpress-playground/pull/2399))
+-   [Playground CLI] Improve error reporting. ([#2401](https://github.com/WordPress/wordpress-playground/pull/2401))
+-   [Playground CLI] Kebab-case yargs options declarations. ([#2399](https://github.com/WordPress/wordpress-playground/pull/2399))
 
 ### Blueprints
 
-- Expose Blueprints v2 runner in Playground CLI. ([#2394](https://github.com/WordPress/wordpress-playground/pull/2394))
-- Extract Blueprint v1-specific parts of Playground CLI. ([#2392](https://github.com/WordPress/wordpress-playground/pull/2392))
-- [Playground CLI] Separate Blueprints v1 and Blueprints v2 code paths. ([#2396](https://github.com/WordPress/wordpress-playground/pull/2396))
+-   Expose Blueprints v2 runner in Playground CLI. ([#2394](https://github.com/WordPress/wordpress-playground/pull/2394))
+-   Extract Blueprint v1-specific parts of Playground CLI. ([#2392](https://github.com/WordPress/wordpress-playground/pull/2392))
+-   [Playground CLI] Separate Blueprints v1 and Blueprints v2 code paths. ([#2396](https://github.com/WordPress/wordpress-playground/pull/2396))
 
 ### Tools
 
-- [XDebug] Add a mock @php-wasm/xdebug-bridge package. ([#2398](https://github.com/WordPress/wordpress-playground/pull/2398))
+-   [XDebug] Add a mock @php-wasm/xdebug-bridge package. ([#2398](https://github.com/WordPress/wordpress-playground/pull/2398))
 
 ### Documentation
 
-- Adding Brazilian Portuguese translation for developer documentation. ([#2391](https://github.com/WordPress/wordpress-playground/pull/2391))
+-   Adding Brazilian Portuguese translation for developer documentation. ([#2391](https://github.com/WordPress/wordpress-playground/pull/2391))
 
 ### Website
 
-- [Remote] Use CORS proxy in embedded Playgrounds. ([#2369](https://github.com/WordPress/wordpress-playground/pull/2369))
+-   [Remote] Use CORS proxy in embedded Playgrounds. ([#2369](https://github.com/WordPress/wordpress-playground/pull/2369))
 
 ### Bug Fixes
 
-- CLI: Fix --login option and "landingPage" Blueprint property. ([#2344](https://github.com/WordPress/wordpress-playground/pull/2344))
+-   CLI: Fix --login option and "landingPage" Blueprint property. ([#2344](https://github.com/WordPress/wordpress-playground/pull/2344))
 
 ### Various
 
-- Add Japanese translations to steps and steps shorthands. ([#2386](https://github.com/WordPress/wordpress-playground/pull/2386))
-- Add OPCache support. ([#2400](https://github.com/WordPress/wordpress-playground/pull/2400))
-- [Node] Gracefully handle connection errors in the outbound network proxy. ([#2370](https://github.com/WordPress/wordpress-playground/pull/2370))
+-   Add Japanese translations to steps and steps shorthands. ([#2386](https://github.com/WordPress/wordpress-playground/pull/2386))
+-   Add OPCache support. ([#2400](https://github.com/WordPress/wordpress-playground/pull/2400))
+-   [Node] Gracefully handle connection errors in the outbound network proxy. ([#2370](https://github.com/WordPress/wordpress-playground/pull/2370))
 
 ### Contributors
 
 The following contributors merged PRs in this release:
 
 @adamziel @fellyph @shimotmk @zaerl
 
-
 ## [v1.2.3] (2025-07-21)
 
 ### Enhancements

packages/php-wasm/xdebug-bridge/.eslintrc.json

@@ -8,7 +8,9 @@
 		},
 		{
 			"files": ["*.ts", "*.tsx"],
-			"rules": {}
+			"rules": {
+				"no-console": 0
+			}
 		},
 		{
 			"files": ["*.js", "*.jsx"],

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

@@ -13,24 +13,21 @@ npm install @php-wasm/xdebug-bridge
 ### Programmatic API
 
 ```typescript
-import { startXDebugBridge } from '@php-wasm/xdebug-bridge';
+import { startBridge } from './xdebug-bridge/src/start-bridge';
 
 // Start with default settings
-const server = startXDebugBridge();
+const server = startBridge();
 await server.start();
 
 // Start with custom configuration
-const server = startXDebugBridge({
-	protocol: 'cdp', // or 'dap'
-	xdebugServerPort: 9003, // XDebug connection port
-	xdebugServerHost: 'localhost',
-	verbose: false, // Silent mode
+const server = startBridge({
+	cdpHost: 'localhost', // CDP connection host
+	cdpPort: 9229, // CDP connection port
+	dbgpPort: 9003, // XDebug connection port
+	phpRoot: './', // Root to directory
 });
 
 await server.start();
-
-// Stop the server
-await server.stop();
 ```
 
 ### CLI Usage
@@ -42,29 +39,31 @@ npx xdebug-bridge
 # Custom port and verbose logging
 npx xdebug-bridge --port 9000 --verbose
 
-# DAP protocol, bind to all interfaces
-npx xdebug-bridge --protocol dap --host 0.0.0.0
-
 # Show help
 npx xdebug-bridge --help
 ```
 
 ## Configuration Options
 
--   `protocol`: Protocol to use ('cdp' or 'dap', default: 'cdp')
--   `xdebugServerPort`: Port to listen for XDebug connections (default: 9003)
--   `xdebugServerHost`: Host to bind to (default: 'localhost')
--   `verbose`: Enable verbose logging (default: false for API, true for CLI)
--   `logger`: Custom logger function
+-   `cdpPort`: Port to listen for CDP connections (default: 9229)
+-   `cdpHost`: Host to bind to (default: 'localhost')
+-   `dbgpPort`: Port to listen for XDebug connections (default: 9003)
+-   `phpRoot`: Root path for php files;
+-   `remoteRoot`: Remote root path for php files;
+-   `localRoot`: Local root path for php files;
+-   `phpInstance`: PHP instance
+-   `getPHPFile`: Custom file listing function
 
 ## Events
 
-The server emits events for monitoring connection activity:
+The bridge listens to events for monitoring connection activity:
+
+-   `connected`: Xdebug Server has started
+-   `close`: Xdebug Server has stopped
+-   `message`: Raw XDebug data received
+-   `error`: Xdebug Server error occurred
 
--   `started`: Server has started
--   `stopped`: Server has stopped
--   `connection`: New XDebug connection established
--   `disconnection`: XDebug connection closed
--   `xdebugData`: Raw XDebug data received
--   `error`: Server error occurred
--   `socketError`: Socket-level error occurred
+-   `clientConnected`: Devtools client connected
+-   `clientDisconnected`: Devtools client disconnected
+-   `message`: Raw Devtools data received
+-   `error`: Devtools client error occurred

packages/php-wasm/xdebug-bridge/package.json

@@ -26,7 +26,7 @@
 	"type": "module",
 	"main": "./index.cjs",
 	"module": "./index.js",
-	"bin": "cli.js",
+	"bin": "xdebug-bridge.js",
 	"typedoc": {
 		"entryPoint": "./src/index.ts",
 		"readmeFile": "./README.md",

packages/php-wasm/xdebug-bridge/project.json

@@ -29,7 +29,7 @@
 			"executor": "@nx/vite:build",
 			"outputs": ["{options.outputPath}"],
 			"options": {
-				"main": "dist/packages/php-wasm/xdebug-bridge/index.js",
+				"main": "dist/packages/php-wasm/xdebug-bridge/src/cli.js",
 				"outputPath": "dist/packages/php-wasm/xdebug-bridge"
 			},
 			"defaultConfiguration": "production",
@@ -45,27 +45,40 @@
 		"dev": {
 			"executor": "nx:run-commands",
 			"options": {
-				"command": "bun --watch ./packages/php-wasm/xdebug-bridge/src/cli.ts",
+				"command": "node --no-warnings --experimental-wasm-stack-switching --experimental-wasm-jspi --loader=./packages/meta/src/node-es-module-loader/loader.mts ./packages/php-wasm/xdebug-bridge/src/cli.ts",
 				"tty": true
 			}
 		},
+		"lint": {
+			"executor": "@nx/eslint:lint",
+			"outputs": ["{options.outputFile}"],
+			"options": {
+				"lintFilePatterns": ["packages/php-wasm/xdebug-bridge/**/*.ts"]
+			}
+		},
+		"package-for-self-hosting": {
+			"executor": "@wp-playground/nx-extensions:package-for-self-hosting",
+			"dependsOn": ["build"]
+		},
 		"test": {
 			"executor": "@nx/vite:test",
 			"outputs": [
 				"{workspaceRoot}/coverage/packages/php-wasm/xdebug-bridge"
 			],
 			"options": {
 				"reportsDirectory": "../../../coverage/packages/php-wasm/xdebug-bridge",
-				"testFiles": ["tests/mock-test.spec.ts"]
+				"testFiles": ["mock-test.spec.ts"]
 			}
 		},
-		"lint": {
-			"executor": "@nx/eslint:lint",
-			"outputs": ["{options.outputFile}"],
+		"typecheck": {
+			"executor": "nx:run-commands",
 			"options": {
-				"lintFilePatterns": ["packages/php-wasm/xdebug-bridge/**/*.ts"]
+				"commands": [
+					"tsc -p packages/php-wasm/xdebug-bridge/tsconfig.lib.json --noEmit",
+					"tsc -p packages/php-wasm/xdebug-bridge/tsconfig.spec.json --noEmit"
+				]
 			}
 		}
 	},
-	"tags": ["php-wasm"]
+	"tags": ["scope:php-binaries"]
 }

packages/php-wasm/xdebug-bridge/public/xdebug-bridge.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import './cli.js';