[ xdebug ] Add --experimental-unsafe-ide-integration option in PHP.wasm CLI

packages/php-wasm/cli-util/.eslintrc.json

@@ -0,0 +1,18 @@
+{
+	"extends": ["../../../.eslintrc.json"],
+	"ignorePatterns": ["!**/*"],
+	"overrides": [
+		{
+			"files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+			"rules": {}
+		},
+		{
+			"files": ["*.ts", "*.tsx"],
+			"rules": {}
+		},
+		{
+			"files": ["*.js", "*.jsx"],
+			"rules": {}
+		}
+	]
+}

packages/php-wasm/cli-util/README.md

@@ -0,0 +1,11 @@
+# php-wasm-cli-util
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build php-wasm-cli-util` to build the library.
+
+## Running unit tests
+
+Run `nx test php-wasm-cli-util` to execute the unit tests via [Vitest](https://vitest.dev).

packages/php-wasm/cli-util/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@php-wasm/cli-util",
+	"version": "3.0.22",
+	"description": "Utilities for PHP.wasm related CLIs",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/WordPress/wordpress-playground"
+	},
+	"homepage": "https://developer.wordpress.org/playground",
+	"author": "The WordPress contributors",
+	"contributors": [
+		{
+			"name": "Adam Zielinski",
+			"email": "[email protected]",
+			"url": "https://github.com/adamziel"
+		}
+	],
+	"exports": {
+		".": {
+			"import": "./index.js",
+			"require": "./index.cjs"
+		},
+		"./package.json": "./package.json",
+		"./README.md": "./README.md"
+	},
+	"main": "./index.cjs",
+	"module": "./index.js",
+	"type": "module",
+	"types": "index.d.ts",
+	"typedoc": {
+		"entryPoint": "./src/index.ts",
+		"readmeFile": "./README.md",
+		"displayName": "@php-wasm/cli-util",
+		"tsconfig": "./tsconfig.lib.json"
+	},
+	"publishConfig": {
+		"access": "public",
+		"directory": "../../../dist/packages/php-wasm/cli-util"
+	},
+	"license": "GPL-2.0-or-later",
+	"gitHead": "2f8d8f3cea548fbd75111e8659a92f601cddc593",
+	"engines": {
+		"node": ">=20.18.3",
+		"npm": ">=10.1.0"
+	}
+}

packages/php-wasm/cli-util/project.json

@@ -0,0 +1,81 @@
+{
+	"name": "php-wasm-cli-util",
+	"$schema": "../../../node_modules/nx/schemas/project-schema.json",
+	"sourceRoot": "packages/php-wasm/cli-util/src",
+	"projectType": "library",
+	"targets": {
+		"build": {
+			"executor": "nx:noop",
+			"dependsOn": ["build:README"]
+		},
+		"build:README": {
+			"executor": "nx:run-commands",
+			"options": {
+				"commands": [
+					"cp packages/php-wasm/cli-util/README.md dist/packages/php-wasm/cli-util"
+				]
+			},
+			"dependsOn": ["build:package-json"]
+		},
+		"build:package-json": {
+			"executor": "@wp-playground/nx-extensions:package-json",
+			"options": {
+				"tsConfig": "packages/php-wasm/cli-util/tsconfig.lib.json",
+				"outputPath": "dist/packages/php-wasm/cli-util",
+				"buildTarget": "php-wasm-cli-util:build:bundle:production"
+			}
+		},
+		"build:bundle": {
+			"executor": "@nx/vite:build",
+			"outputs": ["{options.outputPath}"],
+			"options": {
+				"emptyOutDir": false,
+				"outputPath": "dist/packages/php-wasm/cli-util"
+			}
+		},
+		"publish": {
+			"executor": "nx:run-commands",
+			"options": {
+				"command": "node tools/scripts/publish.mjs php-wasm-cli-util {args.ver} {args.tag}"
+			},
+			"dependsOn": ["build"]
+		},
+		"package-for-self-hosting": {
+			"executor": "@wp-playground/nx-extensions:package-for-self-hosting",
+			"dependsOn": ["build"]
+		},
+		"lint": {
+			"executor": "@nx/linter:eslint",
+			"outputs": ["{options.outputFile}"],
+			"options": {
+				"useFlatConfig": false,
+				"lintFilePatterns": ["packages/php-wasm/cli-util/**/*.ts"],
+				"maxWarnings": 0
+			}
+		},
+		"test": {
+			"executor": "@nx/vite:test",
+			"outputs": ["{workspaceRoot}/coverage/packages/php-wasm/cli-util"],
+			"options": {
+				"reportsDirectory": "../../../coverage/packages/php-wasm/cli-util"
+			}
+		},
+		"test:esmcjs": {
+			"executor": "@wp-playground/nx-extensions:assert-built-esm-and-cjs",
+			"options": {
+				"outputPath": "dist/packages/php-wasm/cli-util"
+			},
+			"dependsOn": ["build"]
+		},
+		"typecheck": {
+			"executor": "nx:run-commands",
+			"options": {
+				"commands": [
+					"tsc -p packages/php-wasm/cli-util/tsconfig.lib.json --noEmit",
+					"tsc -p packages/php-wasm/cli-util/tsconfig.spec.json --noEmit"
+				]
+			}
+		}
+	},
+	"tags": ["scope:independent-from-php-binaries"]
+}

packages/php-wasm/cli-util/src/index.ts

@@ -0,0 +1 @@
+export * from './lib';

packages/php-wasm/cli-util/src/lib/index.ts

@@ -0,0 +1,2 @@
+export * from './mounts';
+export * from './xdebug-path-mappings';

packages/php-wasm/cli-util/src/lib/mounts.ts

@@ -0,0 +1,4 @@
+export interface Mount {
+	hostPath: string;
+	vfsPath: string;
+}

packages/playground/cli/src/xdebug-path-mappings.ts → packages/php-wasm/cli-util/src/lib/xdebug-path-mappings.ts

@@ -1,44 +1,44 @@
 import fs from 'fs';
 import path from 'path';
-import { type Mount } from './mounts';
+import type { Mount } from './mounts';
 import {
 	type X2jOptions,
 	type XmlBuilderOptions,
 	XMLParser,
 	XMLBuilder,
 } from 'fast-xml-parser';
-import JSONC from 'jsonc-parser';
+import * as JSONC from 'jsonc-parser';
 
 /**
- * Create a symlink to temp dir for the Playground CLI.
+ * Create a symlink to a tempory directory.
  *
  * The symlink is created to access the system temp dir
  * inside the current debugging directory.
  *
  * @param nativeDirPath The system temp dir path.
  * @param symlinkPath The symlink name.
  */
-export async function createPlaygroundCliTempDirSymlink(
+export async function createTempDirSymlink(
 	nativeDirPath: string,
 	symlinkPath: string,
 	platform: string
 ) {
 	const type =
 		platform === 'win32'
 			? // On Windows, creating a 'dir' symlink can require elevated permissions.
-			  // In this case, let's make junction points because they function like
-			  // symlinks and do not require elevated permissions.
-			  'junction'
+				// In this case, let's make junction points because they function like
+				// symlinks and do not require elevated permissions.
+				'junction'
 			: 'dir';
 	fs.symlinkSync(nativeDirPath, symlinkPath, type);
 }
 
 /**
- * Remove the temp dir symlink if it exists.
+ * Remove the given temporary directory symlink if it exists.
  *
  * @param symlinkPath The symlink path.
  */
-export async function removePlaygroundCliTempDirSymlink(symlinkPath: string) {
+export async function removeTempDirSymlink(symlinkPath: string) {
 	try {
 		const stats = fs.lstatSync(symlinkPath);
 		if (stats.isSymbolicLink()) {
@@ -52,7 +52,7 @@ export async function removePlaygroundCliTempDirSymlink(symlinkPath: string) {
 /**
  * Filters out mounts that are not in the current working directory
  *
- * @param mounts The Playground CLI mount options.
+ * @param mounts The mounts list.
  */
 function filterLocalMounts(cwd: string, mounts: Mount[]) {
 	return mounts.filter((mount) => {
@@ -91,7 +91,7 @@ export type IDEConfig = {
 	/**
 	 * The mounts to consider for debugger path mapping.
 	 */
-	mounts: Mount[];
+	mounts?: Mount[];
 	/**
 	 * The IDE key to use for the debug configuration. Defaults to 'PLAYGROUNDCLI'.
 	 */
@@ -137,7 +137,7 @@ type VSCodeConfigNode = {
 	type: string;
 	request: string;
 	port: number;
-	pathMappings: VSCodeConfigMetaData;
+	pathMappings?: VSCodeConfigMetaData;
 };
 
 const xmlParserOptions: X2jOptions = {
@@ -170,7 +170,7 @@ export type PhpStormConfigOptions = {
 	host: string;
 	port: number;
 	projectDir: string;
-	mappings: Mount[];
+	mappings?: Mount[];
 	ideKey: string;
 };
 
@@ -201,19 +201,7 @@ export function updatePhpStormConfig(
 
 	// Create the server element with path mappings
 	const serverElement: PhpStormConfigNode = {
-		server: [
-			{
-				path_mappings: mappings.map((mapping) => ({
-					mapping: [],
-					':@': {
-						'local-root': `$PROJECT_DIR$/${toPosixPath(
-							path.relative(options.projectDir, mapping.hostPath)
-						)}`,
-						'remote-root': mapping.vfsPath,
-					},
-				})),
-			},
-		],
+		server: [{}],
 		':@': {
 			name,
 			// NOTE: PhpStorm quirk: Xdebug only works when the full URL (including port)
@@ -224,6 +212,18 @@ export function updatePhpStormConfig(
 		},
 	};
 
+	if (mappings && mappings.length) {
+		serverElement.server![0].path_mappings = mappings.map((mapping) => ({
+			mapping: [],
+			':@': {
+				'local-root': `$PROJECT_DIR$/${toPosixPath(
+					path.relative(options.projectDir, mapping.hostPath)
+				)}`,
+				'remote-root': mapping.vfsPath,
+			},
+		}));
+	}
+
 	// Find or create project element
 	let projectElement = config?.find((c: PhpStormConfigNode) => !!c?.project);
 	if (projectElement) {
@@ -364,7 +364,7 @@ export function updatePhpStormConfig(
 export type VSCodeConfigOptions = {
 	name: string;
 	workspaceDir: string;
-	mappings: Mount[];
+	mappings?: Mount[];
 };
 
 /**
@@ -408,7 +408,8 @@ export function updateVSCodeConfig(
 
 	// Check if configuration already exists
 	const configurationIndex = configurationsNode?.children?.findIndex(
-		(child) => JSONC.findNodeAtLocation(child, ['name'])?.value === name
+		(child: any) =>
+			JSONC.findNodeAtLocation(child, ['name'])?.value === name
 	);
 
 	// Only add configuration if it doesn't exist
@@ -418,13 +419,16 @@ export function updateVSCodeConfig(
 			type: 'php',
 			request: 'launch',
 			port: 9003,
-			pathMappings: mappings.reduce((acc, mount) => {
+		};
+
+		if (mappings && mappings.length) {
+			configuration.pathMappings = mappings.reduce((acc, mount) => {
 				acc[mount.vfsPath] = `\${workspaceFolder}/${toPosixPath(
 					path.relative(options.workspaceDir, mount.hostPath)
 				)}`;
 				return acc;
-			}, {} as VSCodeConfigMetaData),
-		};
+			}, {} as VSCodeConfigMetaData);
+		}
 
 		// Get the current length to append at the end
 		const currentLength = configurationsNode?.children?.length || 0;
@@ -452,7 +456,7 @@ export function updateVSCodeConfig(
  * Implement necessary parameters and path mappings in IDE configuration files.
  *
  * @param name The configuration name.
- * @param mounts The Playground CLI mount options.
+ * @param mounts The mounts options.
  */
 export async function addXdebugIDEConfig({
 	name,
@@ -461,9 +465,9 @@ export async function addXdebugIDEConfig({
 	port,
 	cwd,
 	mounts,
-	ideKey = 'PLAYGROUNDCLI',
+	ideKey = 'PHPWASMCLI',
 }: IDEConfig) {
-	const mappings = filterLocalMounts(cwd, mounts);
+	const mappings = mounts ? filterLocalMounts(cwd, mounts) : [];
 	const modifiedConfig: string[] = [];
 
 	// PHPstorm
@@ -500,9 +504,8 @@ export async function addXdebugIDEConfig({
 				ideKey,
 			});
 			fs.writeFileSync(phpStormConfigFilePath, updatedXml);
+			modifiedConfig.push(phpStormRelativeConfigFilePath);
 		}
-
-		modifiedConfig.push(phpStormRelativeConfigFilePath);
 	}
 
 	// VSCode
@@ -626,7 +629,8 @@ export async function clearXdebugIDEConfig(name: string, cwd: string) {
 		]);
 
 		const configurationIndex = configurationsNode?.children?.findIndex(
-			(child) => JSONC.findNodeAtLocation(child, ['name'])?.value === name
+			(child: any) =>
+				JSONC.findNodeAtLocation(child, ['name'])?.value === name
 		);
 
 		if (configurationIndex !== undefined && configurationIndex >= 0) {
@@ -682,8 +686,8 @@ function jsoncApplyEdits(content: string, edits: JSONC.Edit[]) {
 			(edit) => `At ${edit.offset}:${edit.length} - (${edit.content})`
 		);
 		throw new Error(
-			`VS Code configuration file (.vscode/launch.json) is not valid a JSONC after Playground CLI modifications. This is likely ` +
-				`a Playground CLI bug. Please report it at https://github.com/WordPress/wordpress-playground/issues and include the contents ` +
+			`VS Code configuration file (.vscode/launch.json) is not valid a JSONC after CLI modifications. This is likely ` +
+				`a CLI bug. Please report it at https://github.com/WordPress/wordpress-playground/issues and include the contents ` +
 				`of your ".vscode/launch.json" file. \n\n Applied edits: ${formattedEdits.join(
 					'\n'
 				)}\n\n The errors are: ${formattedErrors.join('\n')}`