@wordpress/env 10.39.0 → 11.0.0

package/lib/commands/cleanup.js

@@ -0,0 +1,79 @@
+'use strict';
+/**
+ * External dependencies
+ */
+const fs = require( 'fs' ).promises;
+const path = require( 'path' );
+const { confirm } = require( '@inquirer/prompts' );
+
+/**
+ * Internal dependencies
+ */
+const { loadConfig } = require( '../config' );
+const { executeLifecycleScript } = require( '../execute-lifecycle-script' );
+const { getRuntime, detectRuntime } = require( '../runtime' );
+
+/**
+ * Cleanup the development server.
+ *
+ * Removes Docker containers, volumes, networks, and local files,
+ * but preserves Docker images for faster re-starts.
+ *
+ * @param {Object}      options
+ * @param {Object}      options.spinner A CLI spinner which indicates progress.
+ * @param {boolean}     options.scripts Indicates whether or not lifecycle scripts should be executed.
+ * @param {boolean}     options.force   If true, skips the confirmation prompt.
+ * @param {boolean}     options.debug   True if debug mode is enabled.
+ * @param {string|null} options.config  Path to a custom .wp-env.json configuration file.
+ */
+module.exports = async function cleanup( {
+	spinner,
+	scripts,
+	force,
+	debug,
+	config: customConfigPath,
+} ) {
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
+
+	try {
+		await fs.readdir( config.workDirectoryPath );
+	} catch {
+		spinner.text = 'Could not find any files to remove.';
+		return;
+	}
+
+	const runtime = getRuntime(
+		await detectRuntime( config.workDirectoryPath )
+	);
+
+	spinner.info( runtime.getCleanupWarningMessage() );
+
+	let yesDelete = force;
+	if ( ! force ) {
+		try {
+			yesDelete = await confirm( {
+				message: 'Are you sure you want to continue?',
+				default: false,
+			} );
+		} catch ( error ) {
+			if ( error.name === 'ExitPromptError' ) {
+				console.log( 'Cancelled.' );
+				process.exit( 1 );
+			}
+			throw error;
+		}
+	}
+
+	spinner.start();
+
+	if ( ! yesDelete ) {
+		spinner.text = 'Cancelled.';
+		return;
+	}
+
+	await runtime.cleanup( config, { spinner, debug } );
+
+	if ( scripts ) {
+		await executeLifecycleScript( 'afterCleanup', config, spinner );
+	}
+};

package/lib/commands/destroy.js

@@ -16,13 +16,21 @@ const { getRuntime, detectRuntime } = require( '../runtime' );
 /**
  * Destroy the development server.
  *
- * @param {Object}  options
- * @param {Object}  options.spinner A CLI spinner which indicates progress.
- * @param {boolean} options.scripts Indicates whether or not lifecycle scripts should be executed.
- * @param {boolean} options.debug   True if debug mode is enabled.
+ * @param {Object}      options
+ * @param {Object}      options.spinner A CLI spinner which indicates progress.
+ * @param {boolean}     options.scripts Indicates whether or not lifecycle scripts should be executed.
+ * @param {boolean}     options.force   If true, skips the confirmation prompt.
+ * @param {boolean}     options.debug   True if debug mode is enabled.
+ * @param {string|null} options.config  Path to a custom .wp-env.json configuration file.
  */
-module.exports = async function destroy( { spinner, scripts, debug } ) {
-	const config = await loadConfig( path.resolve( '.' ) );
+module.exports = async function destroy( {
+	spinner,
+	scripts,
+	force,
+	debug,
+	config: customConfigPath,
+} ) {
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
 
 	try {
 		await fs.readdir( config.workDirectoryPath );
@@ -31,22 +39,26 @@ module.exports = async function destroy( { spinner, scripts, debug } ) {
 		return;
 	}
 
-	const runtime = getRuntime( detectRuntime( config.workDirectoryPath ) );
+	const runtime = getRuntime(
+		await detectRuntime( config.workDirectoryPath )
+	);
 
 	spinner.info( runtime.getDestroyWarningMessage() );
 
-	let yesDelete = false;
-	try {
-		yesDelete = await confirm( {
-			message: 'Are you sure you want to continue?',
-			default: false,
-		} );
-	} catch ( error ) {
-		if ( error.name === 'ExitPromptError' ) {
-			console.log( 'Cancelled.' );
-			process.exit( 1 );
+	let yesDelete = force;
+	if ( ! force ) {
+		try {
+			yesDelete = await confirm( {
+				message: 'Are you sure you want to continue?',
+				default: false,
+			} );
+		} catch ( error ) {
+			if ( error.name === 'ExitPromptError' ) {
+				console.log( 'Cancelled.' );
+				process.exit( 1 );
+			}
+			throw error;
 		}
-		throw error;
 	}
 
 	spinner.start();

package/lib/commands/index.js

@@ -4,18 +4,22 @@
  */
 const start = require( './start' );
 const stop = require( './stop' );
+const reset = require( './reset' );
 const clean = require( './clean' );
 const run = require( './run' );
 const destroy = require( './destroy' );
+const cleanup = require( './cleanup' );
 const logs = require( './logs' );
-const installPath = require( './install-path' );
+const status = require( './status' );
 
 module.exports = {
 	start,
 	stop,
+	reset,
 	clean,
 	run,
 	destroy,
+	cleanup,
 	logs,
-	installPath,
+	status,
 };

package/lib/commands/logs.js

@@ -13,14 +13,23 @@ const { getRuntime, detectRuntime } = require( '../runtime' );
 /**
  * Displays the Docker & PHP logs on the given environment.
  *
- * @param {Object}  options
- * @param {Object}  options.environment The environment to run the command in (develop or tests).
- * @param {Object}  options.watch       If true, follow along with log output.
- * @param {Object}  options.spinner     A CLI spinner which indicates progress.
- * @param {boolean} options.debug       True if debug mode is enabled.
+ * @param {Object}      options
+ * @param {Object}      options.environment The environment to run the command in (develop or tests).
+ * @param {Object}      options.watch       If true, follow along with log output.
+ * @param {Object}      options.spinner     A CLI spinner which indicates progress.
+ * @param {boolean}     options.debug       True if debug mode is enabled.
+ * @param {string|null} options.config      Path to a custom .wp-env.json configuration file.
  */
-module.exports = async function logs( { environment, watch, spinner, debug } ) {
-	const config = await loadConfig( path.resolve( '.' ) );
-	const runtime = getRuntime( detectRuntime( config.workDirectoryPath ) );
+module.exports = async function logs( {
+	environment,
+	watch,
+	spinner,
+	debug,
+	config: customConfigPath,
+} ) {
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
+	const runtime = getRuntime(
+		await detectRuntime( config.workDirectoryPath )
+	);
 	await runtime.logs( config, { environment, watch, spinner, debug } );
 };

package/lib/commands/reset.js

@@ -0,0 +1,46 @@
+'use strict';
+/**
+ * External dependencies
+ */
+const path = require( 'path' );
+
+/**
+ * Internal dependencies
+ */
+const { executeLifecycleScript } = require( '../execute-lifecycle-script' );
+const { loadConfig } = require( '../config' );
+const { getRuntime, detectRuntime } = require( '../runtime' );
+
+/**
+ * @typedef {import('../wordpress').WPEnvironment} WPEnvironment
+ * @typedef {import('../wordpress').WPEnvironmentSelection} WPEnvironmentSelection
+ */
+
+/**
+ * Resets the development server's database, the tests server's database, or both.
+ *
+ * @param {Object}                 options
+ * @param {WPEnvironmentSelection} options.environment The environment to reset. Either 'development', 'tests', or 'all'.
+ * @param {Object}                 options.spinner     A CLI spinner which indicates progress.
+ * @param {boolean}                options.scripts     Indicates whether or not lifecycle scripts should be executed.
+ * @param {boolean}                options.debug       True if debug mode is enabled.
+ * @param {string|null}            options.config      Path to a custom .wp-env.json configuration file.
+ */
+module.exports = async function reset( {
+	environment,
+	spinner,
+	scripts,
+	debug,
+	config: customConfigPath,
+} ) {
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
+	const runtime = getRuntime(
+		await detectRuntime( config.workDirectoryPath )
+	);
+
+	await runtime.clean( config, { environment, spinner, debug } );
+
+	if ( scripts ) {
+		await executeLifecycleScript( 'afterReset', config, spinner );
+	}
+};

package/lib/commands/run.js

@@ -13,13 +13,14 @@ const { getRuntime, detectRuntime } = require( '../runtime' );
 /**
  * Runs an arbitrary command on the given Docker container.
  *
- * @param {Object}   options
- * @param {string}   options.container The Docker container to run the command on.
- * @param {string[]} options.command   The command to run.
- * @param {string[]} options.'--'      Any arguments that were passed after a double dash.
- * @param {string}   options.envCwd    The working directory for the command to be executed from.
- * @param {Object}   options.spinner   A CLI spinner which indicates progress.
- * @param {boolean}  options.debug     True if debug mode is enabled.
+ * @param {Object}      options
+ * @param {string}      options.container The Docker container to run the command on.
+ * @param {string[]}    options.command   The command to run.
+ * @param {string[]}    options.'--'      Any arguments that were passed after a double dash.
+ * @param {string}      options.envCwd    The working directory for the command to be executed from.
+ * @param {Object}      options.spinner   A CLI spinner which indicates progress.
+ * @param {boolean}     options.debug     True if debug mode is enabled.
+ * @param {string|null} options.config    Path to a custom .wp-env.json configuration file.
  */
 module.exports = async function run( {
 	container,
@@ -28,9 +29,12 @@ module.exports = async function run( {
 	envCwd,
 	spinner,
 	debug,
+	config: customConfigPath,
 } ) {
-	const config = await loadConfig( path.resolve( '.' ) );
-	const runtime = getRuntime( detectRuntime( config.workDirectoryPath ) );
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
+	const runtime = getRuntime(
+		await detectRuntime( config.workDirectoryPath )
+	);
 
 	// Include any double dashed arguments in the command so that we can pass them to Docker.
 	// This lets users pass options that the command defines without them being parsed.

package/lib/commands/start.js

@@ -12,7 +12,7 @@ const { rimraf } = require( 'rimraf' );
  */
 const { loadConfig } = require( '../config' );
 const { executeLifecycleScript } = require( '../execute-lifecycle-script' );
-const { getRuntime } = require( '../runtime' );
+const { getRuntime, getSavedRuntime, saveRuntime } = require( '../runtime' );
 
 /**
  * @typedef {import('../config').WPConfig} WPConfig
@@ -21,14 +21,15 @@ const { getRuntime } = require( '../runtime' );
 /**
  * Starts the development server.
  *
- * @param {Object}  options
- * @param {Object}  options.spinner A CLI spinner which indicates progress.
- * @param {boolean} options.update  If true, update sources.
- * @param {string}  options.xdebug  The Xdebug mode to set.
- * @param {string}  options.spx     The SPX mode to set.
- * @param {boolean} options.scripts Indicates whether or not lifecycle scripts should be executed.
- * @param {boolean} options.debug   True if debug mode is enabled.
- * @param {string}  options.runtime The runtime to use ('docker' or 'playground').
+ * @param {Object}      options
+ * @param {Object}      options.spinner A CLI spinner which indicates progress.
+ * @param {boolean}     options.update  If true, update sources.
+ * @param {string}      options.xdebug  The Xdebug mode to set.
+ * @param {string}      options.spx     The SPX mode to set.
+ * @param {boolean}     options.scripts Indicates whether or not lifecycle scripts should be executed.
+ * @param {boolean}     options.debug   True if debug mode is enabled.
+ * @param {string}      options.runtime The runtime to use ('docker' or 'playground').
+ * @param {string|null} options.config  Path to a custom .wp-env.json configuration file.
  */
 module.exports = async function start( {
 	spinner,
@@ -38,6 +39,7 @@ module.exports = async function start( {
 	scripts,
 	debug,
 	runtime: runtimeName = 'docker',
+	config: customConfigPath,
 } ) {
 	spinner.text = 'Reading configuration.';
 
@@ -48,9 +50,41 @@ module.exports = async function start( {
 		await checkForLegacyInstall( spinner );
 	}
 
-	const config = await loadConfig( path.resolve( '.' ) );
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
 	config.debug = debug;
 
+	// Check if switching runtimes and prompt user to destroy old environment first.
+	const savedRuntime = await getSavedRuntime( config.workDirectoryPath );
+	if ( savedRuntime && savedRuntime !== runtimeName ) {
+		spinner.stop();
+		let shouldDestroy = false;
+		try {
+			shouldDestroy = await confirm( {
+				message: `Environment was previously started with '${ savedRuntime }' runtime. Destroy it and start with '${ runtimeName }'?`,
+				default: true,
+			} );
+		} catch ( error ) {
+			if ( error.name === 'ExitPromptError' ) {
+				console.log( 'Cancelled.' );
+				process.exit( 1 );
+			}
+			throw error;
+		}
+
+		if ( ! shouldDestroy ) {
+			spinner.fail(
+				`Aborted. Run 'wp-env destroy' manually or start with '--runtime=${ savedRuntime }'.`
+			);
+			process.exit( 1 );
+		}
+
+		// User confirmed - destroy old runtime first.
+		spinner.start();
+		spinner.text = `Destroying previous ${ savedRuntime } environment.`;
+		const oldRuntime = getRuntime( savedRuntime );
+		await oldRuntime.destroy( config, { spinner } );
+	}
+
 	if ( ! config.detectedLocalConfig ) {
 		const { configDirectoryPath } = config;
 		spinner.warn(
@@ -59,10 +93,13 @@ module.exports = async function start( {
 		spinner.start();
 	}
 
-	// Display Playground limitations info
-	if ( runtimeName === 'playground' ) {
-		spinner.info(
-			'Note: Playground runtime does not support a separate tests environment. Only the development environment will be started.\n'
+	if ( config.testsEnvironment !== false ) {
+		spinner.warn(
+			'Warning: wp-env starts both development and tests environments by default.\n' +
+				'This behavior is deprecated and will be removed in a future version.\n' +
+				'To avoid this warning, add "testsEnvironment": false to your .wp-env.json.\n' +
+				'The "env", "testsPort", and "testsEnvironment" options are also deprecated.\n' +
+				'Use the --config option with a separate config file for test environments instead.\n'
 		);
 		spinner.start();
 	}
@@ -76,6 +113,9 @@ module.exports = async function start( {
 			spx,
 			debug,
 		} );
+
+		// Save the runtime type after successful start.
+		await saveRuntime( runtimeName, config.workDirectoryPath );
 	} catch ( error ) {
 		// Attempt to stop any partially-started environment so that
 		// processes do not linger after a failed start.

package/lib/commands/status.js

@@ -0,0 +1,160 @@
+'use strict';
+/**
+ * External dependencies
+ */
+const path = require( 'path' );
+const { existsSync } = require( 'fs' );
+const chalk = require( 'chalk' );
+
+/**
+ * Internal dependencies
+ */
+const { loadConfig } = require( '../config' );
+const { getRuntime, detectRuntime } = require( '../runtime' );
+
+/**
+ * Check if an environment has been initialized by looking for runtime-specific files.
+ *
+ * @param {Object} config The wp-env configuration object.
+ * @return {boolean} True if the environment has been initialized.
+ */
+function isEnvironmentInitialized( config ) {
+	// Check for Docker's docker-compose.yml
+	if ( existsSync( config.dockerComposeConfigPath ) ) {
+		return true;
+	}
+
+	// Check for Playground's blueprint file
+	const playgroundBlueprintPath = path.join(
+		config.workDirectoryPath,
+		'playground-blueprint.json'
+	);
+	if ( existsSync( playgroundBlueprintPath ) ) {
+		return true;
+	}
+
+	return false;
+}
+
+/**
+ * Outputs the status of the wp-env environment.
+ *
+ * @param {Object}      options
+ * @param {Object}      options.spinner A CLI spinner which indicates progress.
+ * @param {boolean}     options.debug   True if debug mode is enabled.
+ * @param {boolean}     options.json    True to output as JSON.
+ * @param {string|null} options.config  Path to a custom .wp-env.json configuration file.
+ */
+module.exports = async function status( {
+	spinner,
+	debug,
+	json,
+	config: customConfigPath,
+} ) {
+	spinner.text = 'Getting environment status.';
+
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
+
+	// Check if environment is initialized by looking for runtime-specific files.
+	// We check for these files specifically because the work directory may exist
+	// just from caching the WordPress version, but these files are only created
+	// when `wp-env start` is actually run.
+	if ( ! isEnvironmentInitialized( config ) ) {
+		spinner.stop();
+		if ( json ) {
+			console.log(
+				JSON.stringify( {
+					status: 'uninitialized',
+					installPath: config.workDirectoryPath,
+					configPath: config.configDirectoryPath,
+				} )
+			);
+		} else {
+			console.log( formatNotInitialized( config ) );
+		}
+		return;
+	}
+
+	// Detect and get runtime.
+	const runtimeName = await detectRuntime( config.workDirectoryPath );
+	const runtime = getRuntime( runtimeName );
+
+	// Get status from runtime.
+	const statusData = await runtime.getStatus( config, { spinner, debug } );
+
+	spinner.stop();
+	if ( json ) {
+		console.log( JSON.stringify( statusData ) );
+	} else {
+		console.log( formatStatus( statusData ) );
+	}
+};
+
+/**
+ * Format status for human-readable output when not initialized.
+ *
+ * @param {Object} config The config object.
+ * @return {string} Formatted output.
+ */
+function formatNotInitialized( config ) {
+	const indent = '    - ';
+	return `
+${ chalk.bold( 'status' ) }: ${ chalk.red( 'uninitialized' ) }
+${ indent }install path: ${ chalk.dim( config.workDirectoryPath ) }
+${ indent }config: ${ chalk.dim( config.configDirectoryPath ) }
+
+${ chalk.dim( 'Run `wp-env start` to initialize the environment.' ) }
+`;
+}
+
+/**
+ * Format status data for human-readable output.
+ *
+ * @param {Object} status The status object from runtime.
+ * @return {string} Formatted output.
+ */
+function formatStatus( status ) {
+	const statusColor = status.status === 'running' ? chalk.green : chalk.red;
+	const indent = '    - ';
+
+	let output = `
+${ chalk.bold( 'status' ) }: ${ statusColor( status.status ) }
+${ indent }runtime: ${ chalk.dim( status.runtime ) }
+${ indent }install path: ${ chalk.dim( status.installPath ) }
+${ indent }config: ${ chalk.dim( status.configPath ) }
+`;
+
+	// Environment section.
+	output += `\n${ chalk.bold( 'environment' ) }:\n`;
+	if ( status.urls?.development ) {
+		output += `${ indent }url: ${ chalk.dim( status.urls.development ) }\n`;
+	}
+	output += `${ indent }multisite: ${ chalk.dim(
+		status.config?.multisite ? 'yes' : 'no'
+	) }\n`;
+	output += `${ indent }xdebug: ${ chalk.dim(
+		status.config?.xdebug || 'off'
+	) }\n`;
+	if ( status.ports?.development ) {
+		output += `${ indent }http port: ${ chalk.dim(
+			status.ports.development
+		) }\n`;
+	}
+	if ( status.urls?.phpmyadmin ) {
+		output += `${ indent }phpmyadmin url: ${ chalk.dim(
+			status.urls.phpmyadmin
+		) }\n`;
+	}
+	if ( status.ports?.mysql ) {
+		output += `${ indent }mysql port: ${ chalk.dim(
+			status.ports.mysql
+		) }\n`;
+	}
+	if ( status.ports?.tests ) {
+		output += `${ indent }test http port: ${ chalk.dim(
+			status.ports.tests
+		) }\n`;
+	}
+
+	return output;
+}

package/lib/commands/stop.js

@@ -13,12 +13,19 @@ const { getRuntime, detectRuntime } = require( '../runtime' );
 /**
  * Stops the development server.
  *
- * @param {Object}  options
- * @param {Object}  options.spinner A CLI spinner which indicates progress.
- * @param {boolean} options.debug   True if debug mode is enabled.
+ * @param {Object}      options
+ * @param {Object}      options.spinner A CLI spinner which indicates progress.
+ * @param {boolean}     options.debug   True if debug mode is enabled.
+ * @param {string|null} options.config  Path to a custom .wp-env.json configuration file.
  */
-module.exports = async function stop( { spinner, debug } ) {
-	const config = await loadConfig( path.resolve( '.' ) );
-	const runtime = getRuntime( detectRuntime( config.workDirectoryPath ) );
+module.exports = async function stop( {
+	spinner,
+	debug,
+	config: customConfigPath,
+} ) {
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
+	const runtime = getRuntime(
+		await detectRuntime( config.workDirectoryPath )
+	);
 	await runtime.stop( config, { spinner, debug } );
 };

package/lib/config/get-config-from-environment-vars.js

@@ -23,7 +23,6 @@ const { checkPort, checkVersion, checkString } = require( './validate-config' );
  * @property {?number}                  phpmyadminPort   An override for the development environment's phpMyAdmin port.
  * @property {?WPSource}                coreSource       An override for all environment's coreSource.
  * @property {?string}                  phpVersion       An override for all environment's PHP version.
- * @property {?boolean}                 multisite        An override for if environmen should be multisite.
  * @property {?Object.<string, string>} lifecycleScripts An override for various lifecycle scripts.
  */
 
@@ -69,10 +68,6 @@ module.exports = function getConfigFromEnvironmentVars( cacheDirectoryPath ) {
 		environmentConfig.phpVersion = process.env.WP_ENV_PHP_VERSION;
 	}
 
-	if ( process.env.WP_ENV_MULTISITE ) {
-		environmentConfig.multisite = !! process.env.WP_ENV_MULTISITE;
-	}
-
 	return environmentConfig;
 };
 
@@ -108,6 +103,8 @@ function getLifecycleScriptOverrides() {
 	const lifecycleEnvironmentVars = {
 		WP_ENV_LIFECYCLE_SCRIPT_AFTER_START: 'afterStart',
 		WP_ENV_LIFECYCLE_SCRIPT_AFTER_CLEAN: 'afterClean',
+		WP_ENV_LIFECYCLE_SCRIPT_AFTER_RESET: 'afterReset',
+		WP_ENV_LIFECYCLE_SCRIPT_AFTER_CLEANUP: 'afterCleanup',
 		WP_ENV_LIFECYCLE_SCRIPT_AFTER_DESTROY: 'afterDestroy',
 	};
 	for ( const envVar in lifecycleEnvironmentVars ) {