Studio CLI: Add support for xdebug beta flag (#2316)

Author: bcotrim

cli/commands/site/set.ts

@@ -11,6 +11,7 @@ import {
 import { SiteCommandLoggerAction as LoggerAction } from 'common/logger-actions';
 import {
 	getSiteByFolder,
+	isXdebugBetaEnabled,
 	lockAppdata,
 	readAppdata,
 	saveAppdata,
@@ -41,30 +42,38 @@ export interface SetCommandOptions {
 	https?: boolean;
 	php?: string;
 	wp?: string;
+	xdebug?: boolean;
 }
 
 export async function runCommand(
 	sitePath: string,
 	options: SetCommandOptions
 ): Promise< { usedWpCli: boolean } > {
-	const { name, domain, https, php, wp } = options;
+	const { name, domain, https, php, wp, xdebug } = options;
 
 	if (
 		name === undefined &&
 		domain === undefined &&
 		https === undefined &&
 		php === undefined &&
-		wp === undefined
+		wp === undefined &&
+		xdebug === undefined
 	) {
 		throw new LoggerError(
-			__( 'At least one option (--name, --domain, --https, --php, --wp) is required.' )
+			__( 'At least one option (--name, --domain, --https, --php, --wp, --xdebug) is required.' )
 		);
 	}
 
 	if ( name !== undefined && ! name.trim() ) {
 		throw new LoggerError( __( 'Site name cannot be empty.' ) );
 	}
 
+	if ( xdebug !== undefined && ! ( await isXdebugBetaEnabled() ) ) {
+		throw new LoggerError(
+			__( 'Xdebug support is a beta feature. Enable it in Studio settings first.' )
+		);
+	}
+
 	try {
 		logger.reportStart( LoggerAction.LOAD_SITES, __( 'Loading site…' ) );
 		let site = await getSiteByFolder( sitePath );
@@ -90,20 +99,37 @@ export async function runCommand(
 			}
 		}
 
+		if ( xdebug === true ) {
+			const otherXdebugSite = initialAppdata.sites.find(
+				( s ) => s.enableXdebug && s.id !== site.id
+			);
+			if ( otherXdebugSite ) {
+				throw new LoggerError(
+					sprintf(
+						/* translators: %s: site name */
+						__( 'Only one site can have Xdebug enabled at a time. Disable Xdebug on "%s" first.' ),
+						otherXdebugSite.name
+					)
+				);
+			}
+		}
+
 		const nameChanged = name !== undefined && name !== site.name;
 		const domainChanged = domain !== undefined && domain !== site.customDomain;
 		const httpsChanged = https !== undefined && https !== site.enableHttps;
 		const phpChanged = php !== undefined && php !== site.phpVersion;
 		const wpChanged = wp !== undefined;
+		const xdebugChanged = xdebug !== undefined && xdebug !== site.enableXdebug;
 
-		const hasChanges = nameChanged || domainChanged || httpsChanged || phpChanged || wpChanged;
+		const hasChanges =
+			nameChanged || domainChanged || httpsChanged || phpChanged || wpChanged || xdebugChanged;
 		if ( ! hasChanges ) {
 			throw new LoggerError(
 				__( 'No changes to apply. The site already has the specified settings.' )
 			);
 		}
 
-		const needsRestart = domainChanged || httpsChanged || phpChanged || wpChanged;
+		const needsRestart = domainChanged || httpsChanged || phpChanged || wpChanged || xdebugChanged;
 		const oldDomain = site.customDomain;
 
 		try {
@@ -126,6 +152,9 @@ export async function runCommand(
 			if ( phpChanged ) {
 				foundSite.phpVersion = php!;
 			}
+			if ( xdebugChanged ) {
+				foundSite.enableXdebug = xdebug;
+			}
 
 			await saveAppdata( appdata );
 			site = foundSite;
@@ -219,7 +248,8 @@ export const registerCommand = ( yargs: StudioArgv ) => {
 	return yargs.command( {
 		command: 'set',
 		describe: __( 'Configure site settings' ),
-		builder: ( yargs ) => {
+		builder: async ( yargs ) => {
+			const showXdebug = await isXdebugBetaEnabled();
 			return yargs
 				.option( 'name', {
 					type: 'string',
@@ -260,6 +290,11 @@ export const registerCommand = ( yargs: StudioArgv ) => {
 						}
 						return value;
 					},
+				} )
+				.option( 'xdebug', {
+					type: 'boolean',
+					description: __( 'Enable Xdebug (beta feature)' ),
+					hidden: ! showXdebug,
 				} );
 		},
 		handler: async ( argv ) => {
@@ -270,6 +305,7 @@ export const registerCommand = ( yargs: StudioArgv ) => {
 					https: argv.https,
 					php: argv.php,
 					wp: argv.wp,
+					xdebug: argv.xdebug,
 				} );
 				// WP-CLI leaves handles open, so we need to explicitly exit
 				// See: cli/lib/run-wp-cli-command.ts FIXME comment

cli/commands/site/status.ts

@@ -2,7 +2,7 @@ import { __, _n } from '@wordpress/i18n';
 import CliTable3 from 'cli-table3';
 import { getWordPressVersion } from 'common/lib/get-wordpress-version';
 import { SiteCommandLoggerAction as LoggerAction } from 'common/logger-actions';
-import { getSiteByFolder, getSiteUrl } from 'cli/lib/appdata';
+import { getSiteByFolder, getSiteUrl, isXdebugBetaEnabled } from 'cli/lib/appdata';
 import { connect, disconnect } from 'cli/lib/pm2-manager';
 import { getPrettyPath } from 'cli/lib/utils';
 import { isServerRunning } from 'cli/lib/wordpress-server-manager';
@@ -28,6 +28,9 @@ export async function runCommand( siteFolder: string, format: 'table' | 'json' )
 		autoLoginUrl.pathname = `/studio-auto-login`;
 		autoLoginUrl.searchParams.set( 'redirect_to', `/wp-admin/` );
 
+		const xdebugStatus = site.enableXdebug ? __( 'Enabled' ) : __( 'Disabled' );
+		const showXdebug = await isXdebugBetaEnabled();
+
 		const siteData: {
 			key: string;
 			value: string | undefined;
@@ -45,6 +48,7 @@ export async function runCommand( siteFolder: string, format: 'table' | 'json' )
 			{ key: __( 'Status' ), value: status },
 			{ key: __( 'PHP version' ), value: site.phpVersion },
 			{ key: __( 'WP version' ), value: wpVersion },
+			{ key: __( 'Xdebug' ), value: xdebugStatus, hidden: ! showXdebug },
 			{ key: __( 'Admin username' ), value: 'admin' },
 			{ key: __( 'Admin password' ), value: site.adminPassword },
 		].filter( ( { value, hidden } ) => value && ! hidden );

cli/commands/site/tests/set.test.ts

@@ -2,6 +2,7 @@ import { getDomainNameValidationError } from 'common/lib/domains';
 import { arePathsEqual } from 'common/lib/fs-utils';
 import {
 	getSiteByFolder,
+	isXdebugBetaEnabled,
 	unlockAppdata,
 	readAppdata,
 	saveAppdata,
@@ -26,6 +27,7 @@ jest.mock( 'common/lib/fs-utils', () => ( {
 jest.mock( 'cli/lib/appdata', () => ( {
 	...jest.requireActual( 'cli/lib/appdata' ),
 	getSiteByFolder: jest.fn(),
+	isXdebugBetaEnabled: jest.fn(),
 	lockAppdata: jest.fn().mockResolvedValue( undefined ),
 	unlockAppdata: jest.fn().mockResolvedValue( undefined ),
 	readAppdata: jest.fn(),
@@ -70,6 +72,7 @@ describe( 'CLI: studio site set', () => {
 
 		( arePathsEqual as jest.Mock ).mockReturnValue( true );
 		( getSiteByFolder as jest.Mock ).mockResolvedValue( getTestSite() );
+		( isXdebugBetaEnabled as jest.Mock ).mockResolvedValue( true );
 		( readAppdata as jest.Mock ).mockResolvedValue( testAppdata );
 		( connect as jest.Mock ).mockResolvedValue( undefined );
 		( disconnect as jest.Mock ).mockResolvedValue( undefined );
@@ -88,7 +91,7 @@ describe( 'CLI: studio site set', () => {
 	describe( 'Validation', () => {
 		it( 'should throw when no options provided', async () => {
 			await expect( runCommand( testSitePath, {} ) ).rejects.toThrow(
-				'At least one option (--name, --domain, --https, --php, --wp) is required.'
+				'At least one option (--name, --domain, --https, --php, --wp, --xdebug) is required.'
 			);
 		} );
 
@@ -329,6 +332,94 @@ describe( 'CLI: studio site set', () => {
 		} );
 	} );
 
+	describe( 'Xdebug changes', () => {
+		it( 'should throw when beta feature is not enabled', async () => {
+			( isXdebugBetaEnabled as jest.Mock ).mockResolvedValue( false );
+
+			await expect( runCommand( testSitePath, { xdebug: true } ) ).rejects.toThrow(
+				'Xdebug support is a beta feature. Enable it in Studio settings first.'
+			);
+		} );
+
+		it( 'should throw when another site already has xdebug enabled', async () => {
+			const testSite = getTestSite();
+			const otherSite = {
+				...getTestSite(),
+				id: 'site-2',
+				name: 'Other Site',
+				path: '/other/site',
+				enableXdebug: true,
+			};
+			( getSiteByFolder as jest.Mock ).mockResolvedValue( testSite );
+			( readAppdata as jest.Mock ).mockResolvedValue( {
+				sites: [ testSite, otherSite ],
+				snapshots: [],
+			} );
+
+			await expect( runCommand( testSitePath, { xdebug: true } ) ).rejects.toThrow(
+				'Only one site can have Xdebug enabled at a time. Disable Xdebug on "Other Site" first.'
+			);
+		} );
+
+		it( 'should update xdebug setting without restart when site is stopped', async () => {
+			await runCommand( testSitePath, { xdebug: true } );
+
+			const savedAppdata = ( saveAppdata as jest.Mock ).mock.calls[ 0 ][ 0 ];
+			expect( savedAppdata.sites[ 0 ].enableXdebug ).toBe( true );
+			expect( stopWordPressServer ).not.toHaveBeenCalled();
+			expect( startWordPressServer ).not.toHaveBeenCalled();
+		} );
+
+		it( 'should restart running site when xdebug changes', async () => {
+			( isServerRunning as jest.Mock ).mockResolvedValue( testProcessDescription );
+
+			await runCommand( testSitePath, { xdebug: true } );
+
+			expect( stopWordPressServer ).toHaveBeenCalledWith( 'site-1' );
+			expect( startWordPressServer ).toHaveBeenCalled();
+		} );
+
+		it( 'should disable xdebug', async () => {
+			const siteWithXdebug = { ...getTestSite(), enableXdebug: true };
+			( getSiteByFolder as jest.Mock ).mockResolvedValue( siteWithXdebug );
+			( readAppdata as jest.Mock ).mockResolvedValue( {
+				sites: [ siteWithXdebug ],
+				snapshots: [],
+			} );
+
+			await runCommand( testSitePath, { xdebug: false } );
+
+			const savedAppdata = ( saveAppdata as jest.Mock ).mock.calls[ 0 ][ 0 ];
+			expect( savedAppdata.sites[ 0 ].enableXdebug ).toBe( false );
+		} );
+
+		it( 'should throw when xdebug is already enabled', async () => {
+			const siteWithXdebug = { ...getTestSite(), enableXdebug: true };
+			( getSiteByFolder as jest.Mock ).mockResolvedValue( siteWithXdebug );
+			( readAppdata as jest.Mock ).mockResolvedValue( {
+				sites: [ siteWithXdebug ],
+				snapshots: [],
+			} );
+
+			await expect( runCommand( testSitePath, { xdebug: true } ) ).rejects.toThrow(
+				'No changes to apply. The site already has the specified settings.'
+			);
+		} );
+
+		it( 'should throw when xdebug is already disabled', async () => {
+			const siteWithXdebugDisabled = { ...getTestSite(), enableXdebug: false };
+			( getSiteByFolder as jest.Mock ).mockResolvedValue( siteWithXdebugDisabled );
+			( readAppdata as jest.Mock ).mockResolvedValue( {
+				sites: [ siteWithXdebugDisabled ],
+				snapshots: [],
+			} );
+
+			await expect( runCommand( testSitePath, { xdebug: false } ) ).rejects.toThrow(
+				'No changes to apply. The site already has the specified settings.'
+			);
+		} );
+	} );
+
 	describe( 'Error handling', () => {
 		it( 'should throw when site not found', async () => {
 			( getSiteByFolder as jest.Mock ).mockRejectedValue( new Error( 'Site not found' ) );

cli/commands/site/tests/status.test.ts

@@ -1,5 +1,5 @@
 import { getWordPressVersion } from 'common/lib/get-wordpress-version';
-import { getSiteByFolder, getSiteUrl } from 'cli/lib/appdata';
+import { getSiteByFolder, getSiteUrl, isXdebugBetaEnabled } from 'cli/lib/appdata';
 import { connect, disconnect } from 'cli/lib/pm2-manager';
 import { isServerRunning } from 'cli/lib/wordpress-server-manager';
 import { runCommand } from '../status';
@@ -8,6 +8,7 @@ jest.mock( 'cli/lib/appdata', () => ( {
 	...jest.requireActual( 'cli/lib/appdata' ),
 	getSiteByFolder: jest.fn(),
 	getSiteUrl: jest.fn(),
+	isXdebugBetaEnabled: jest.fn(),
 	getAppdataDirectory: jest.fn().mockReturnValue( '/test/appdata' ),
 } ) );
 jest.mock( 'cli/lib/pm2-manager' );
@@ -36,6 +37,7 @@ describe( 'CLI: studio site status', () => {
 
 		( getSiteByFolder as jest.Mock ).mockResolvedValue( testSite );
 		( getSiteUrl as jest.Mock ).mockReturnValue( 'http://localhost:8080' );
+		( isXdebugBetaEnabled as jest.Mock ).mockResolvedValue( true );
 		( connect as jest.Mock ).mockResolvedValue( undefined );
 		( disconnect as jest.Mock ).mockResolvedValue( undefined );
 		( isServerRunning as jest.Mock ).mockResolvedValue( false );
@@ -78,6 +80,7 @@ describe( 'CLI: studio site status', () => {
 						Status: '🔴 Offline',
 						'PHP version': '8.0',
 						'WP version': '6.4',
+						Xdebug: 'Disabled',
 						'Admin username': 'admin',
 						'Admin password': 'password123',
 					},
@@ -105,6 +108,7 @@ describe( 'CLI: studio site status', () => {
 						Status: '🟢 Online',
 						'PHP version': '8.0',
 						'WP version': '6.4',
+						Xdebug: 'Disabled',
 						'Admin username': 'admin',
 						'Admin password': 'password123',
 					},
@@ -143,10 +147,35 @@ describe( 'CLI: studio site status', () => {
 						'Site URL': 'http://localhost:8080/',
 						'Site Path': '/path/to/site',
 						Status: '🔴 Offline',
-						'PHP version': undefined,
 						'WP version': '6.4',
+						Xdebug: 'Disabled',
 						'Admin username': 'admin',
-						'Admin password': undefined,
+					},
+					null,
+					2
+				)
+			);
+
+			consoleSpy.mockRestore();
+		} );
+
+		it( 'should hide xdebug when beta feature is disabled', async () => {
+			( isXdebugBetaEnabled as jest.Mock ).mockResolvedValue( false );
+
+			const consoleSpy = jest.spyOn( console, 'log' ).mockImplementation();
+
+			await runCommand( '/path/to/site', 'json' );
+
+			expect( consoleSpy ).toHaveBeenCalledWith(
+				JSON.stringify(
+					{
+						'Site URL': 'http://localhost:8080/',
+						'Site Path': '/path/to/site',
+						Status: '🔴 Offline',
+						'PHP version': '8.0',
+						'WP version': '6.4',
+						'Admin username': 'admin',
+						'Admin password': 'password123',
 					},
 					null,
 					2

cli/lib/appdata.ts

@@ -28,12 +28,14 @@ const siteSchema = z
 		autoStart: z.boolean().optional(),
 		url: z.string().optional(),
 		latestCliPid: z.number().optional(),
+		enableXdebug: z.boolean().optional(),
 	} )
 	.passthrough();
 
 const betaFeaturesSchema = z
 	.object( {
 		multiWorkerSupport: z.boolean().optional(),
+		xdebugSupport: z.boolean().optional(),
 	} )
 	.passthrough();
 
@@ -148,6 +150,15 @@ export async function unlockAppdata(): Promise< void > {
 	await unlockFileAsync( LOCKFILE_PATH );
 }
 
+export async function isXdebugBetaEnabled(): Promise< boolean > {
+	try {
+		const appdata = await readAppdata();
+		return appdata.betaFeatures?.xdebugSupport ?? false;
+	} catch {
+		return false;
+	}
+}
+
 export async function getAuthToken(): Promise< ValidatedAuthToken > {
 	try {
 		const { authToken } = await readAppdata();