@wordpress/env 10.38.1-next.v.0 → 11.0.0

package/lib/commands/start.js

@@ -2,53 +2,34 @@
 /**
  * External dependencies
  */
-const { v2: dockerCompose } = require( 'docker-compose' );
-const util = require( 'util' );
-const path = require( 'path' );
 const fs = require( 'fs' ).promises;
+const path = require( 'path' );
 const { confirm } = require( '@inquirer/prompts' );
-
-/**
- * Promisified dependencies
- */
-const sleep = util.promisify( setTimeout );
 const { rimraf } = require( 'rimraf' );
-const exec = util.promisify( require( 'child_process' ).exec );
 
 /**
  * Internal dependencies
  */
-const retry = require( '../retry' );
-const stop = require( './stop' );
-const initConfig = require( '../init-config' );
-const downloadSources = require( '../download-sources' );
-const downloadWPPHPUnit = require( '../download-wp-phpunit' );
-const {
-	checkDatabaseConnection,
-	configureWordPress,
-	setupWordPressDirectories,
-	readWordPressVersion,
-	canAccessWPORG,
-} = require( '../wordpress' );
-const { didCacheChange, setCache } = require( '../cache' );
-const md5 = require( '../md5' );
+const { loadConfig } = require( '../config' );
 const { executeLifecycleScript } = require( '../execute-lifecycle-script' );
+const { getRuntime, getSavedRuntime, saveRuntime } = require( '../runtime' );
 
 /**
  * @typedef {import('../config').WPConfig} WPConfig
  */
-const CONFIG_CACHE_KEY = 'config_checksum';
 
 /**
  * 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 {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,
@@ -57,250 +38,104 @@ module.exports = async function start( {
 	spx,
 	scripts,
 	debug,
+	runtime: runtimeName = 'docker',
+	config: customConfigPath,
 } ) {
 	spinner.text = 'Reading configuration.';
-	await checkForLegacyInstall( spinner );
 
-	const config = await initConfig( {
-		spinner,
-		debug,
-		xdebug,
-		spx,
-		writeChanges: true,
-	} );
+	const runtime = getRuntime( runtimeName );
 
-	if ( ! config.detectedLocalConfig ) {
-		const { configDirectoryPath } = config;
-		spinner.warn(
-			`Warning: could not find a .wp-env.json configuration file and could not determine if '${ configDirectoryPath }' is a WordPress installation, a plugin, or a theme.`
-		);
-		spinner.start();
-	}
-
-	// Check if the hash of the config has changed. If so, run configuration.
-	const configHash = md5( config );
-	const { workDirectoryPath, dockerComposeConfigPath } = config;
-	const shouldConfigureWp =
-		( update ||
-			( await didCacheChange( CONFIG_CACHE_KEY, configHash, {
-				workDirectoryPath,
-			} ) ) ) &&
-		// Don't reconfigure everything when we can't connect to the internet because
-		// the majority of update tasks involve connecting to the internet. (Such
-		// as downloading sources and pulling docker images.)
-		( await canAccessWPORG() );
-
-	const dockerComposeConfig = {
-		config: dockerComposeConfigPath,
-		log: config.debug,
-	};
-
-	if ( ! ( await canAccessWPORG() ) ) {
-		spinner.info( 'wp-env is offline' );
+	// Check for legacy Docker installs (Docker-specific UI concern)
+	if ( runtimeName === 'docker' ) {
+		await checkForLegacyInstall( spinner );
 	}
 
-	/**
-	 * If the Docker image is already running and the `wp-env` files have been
-	 * deleted, the start command will not complete successfully. Stopping
-	 * the container before continuing allows the docker entrypoint script,
-	 * which restores the files, to run again when we start the containers.
-	 *
-	 * Additionally, this serves as a way to restart the container entirely
-	 * should the need arise.
-	 *
-	 * @see https://github.com/WordPress/gutenberg/pull/20253#issuecomment-587228440
-	 */
-	if ( shouldConfigureWp ) {
-		await stop( { spinner, debug } );
-		// Update the images before starting the services again.
-		spinner.text = 'Updating docker images.';
-
-		const directoryHash = path.basename( workDirectoryPath );
-
-		// Note: when the base docker image is updated, we want that operation to
-		// also update WordPress. Since we store wordpress/tests-wordpress files
-		// as docker volumes, simply updating the image will not change those
-		// files. Thus, we need to remove those volumes in order for the files
-		// to be updated when pulling the new images.
-		const volumesToRemove = `${ directoryHash }_wordpress ${ directoryHash }_tests-wordpress`;
+	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 {
-			if ( config.debug ) {
-				spinner.text = `Removing the WordPress volumes: ${ volumesToRemove }`;
+			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 );
 			}
-			await exec( `docker volume rm ${ volumesToRemove }` );
-		} catch {
-			// Note: we do not care about this error condition because it will
-			// mostly happen when the volume already exists. This error would not
-			// stop wp-env from working correctly.
+			throw error;
 		}
 
-		await dockerCompose.pullAll( dockerComposeConfig );
-		spinner.text = 'Downloading sources.';
-	}
-
-	await Promise.all( [
-		dockerCompose.upOne( 'mysql', {
-			...dockerComposeConfig,
-			commandOptions: shouldConfigureWp
-				? [ '--build', '--force-recreate' ]
-				: [],
-		} ),
-		shouldConfigureWp && downloadSources( config, spinner ),
-	] );
-
-	if ( shouldConfigureWp ) {
-		spinner.text = 'Setting up WordPress directories';
-
-		await setupWordPressDirectories( config );
-
-		// Use the WordPress versions to download the PHPUnit suite.
-		const wpVersions = await Promise.all( [
-			readWordPressVersion(
-				config.env.development.coreSource,
-				spinner,
-				debug
-			),
-			readWordPressVersion( config.env.tests.coreSource, spinner, debug ),
-		] );
-		await downloadWPPHPUnit(
-			config,
-			{ development: wpVersions[ 0 ], tests: wpVersions[ 1 ] },
-			spinner,
-			debug
-		);
-	}
-
-	spinner.text = 'Starting WordPress.';
-
-	await dockerCompose.upMany(
-		[ 'wordpress', 'tests-wordpress', 'cli', 'tests-cli' ],
-		{
-			...dockerComposeConfig,
-			commandOptions: shouldConfigureWp
-				? [ '--build', '--force-recreate' ]
-				: [],
+		if ( ! shouldDestroy ) {
+			spinner.fail(
+				`Aborted. Run 'wp-env destroy' manually or start with '--runtime=${ savedRuntime }'.`
+			);
+			process.exit( 1 );
 		}
-	);
 
-	if ( config.env.development.phpmyadminPort ) {
-		await dockerCompose.upOne( 'phpmyadmin', {
-			...dockerComposeConfig,
-			commandOptions: shouldConfigureWp
-				? [ '--build', '--force-recreate' ]
-				: [],
-		} );
+		// 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.env.tests.phpmyadminPort ) {
-		await dockerCompose.upOne( 'tests-phpmyadmin', {
-			...dockerComposeConfig,
-			commandOptions: shouldConfigureWp
-				? [ '--build', '--force-recreate' ]
-				: [],
-		} );
+	if ( ! config.detectedLocalConfig ) {
+		const { configDirectoryPath } = config;
+		spinner.warn(
+			`Warning: could not find a .wp-env.json configuration file and could not determine if '${ configDirectoryPath }' is a WordPress installation, a plugin, or a theme.`
+		);
+		spinner.start();
 	}
 
-	// Make sure we've consumed the custom CLI dockerfile.
-	if ( shouldConfigureWp ) {
-		await dockerCompose.buildOne( [ 'cli' ], { ...dockerComposeConfig } );
+	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();
 	}
 
-	// Only run WordPress install/configuration when config has changed.
-	if ( shouldConfigureWp ) {
-		spinner.text = 'Configuring WordPress.';
+	let result;
+	try {
+		result = await runtime.start( config, {
+			spinner,
+			update,
+			xdebug,
+			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.
 		try {
-			await checkDatabaseConnection( config );
-		} catch ( error ) {
-			// Wait 30 seconds for MySQL to accept connections.
-			await retry( () => checkDatabaseConnection( config ), {
-				times: 30,
-				delay: 1000,
-			} );
-
-			// It takes 3-4 seconds for MySQL to be ready after it starts accepting connections.
-			await sleep( 4000 );
+			await runtime.stop( config, { spinner } );
+		} catch {
+			// Ignore cleanup errors.
 		}
-
-		// Retry WordPress installation in case MySQL *still* wasn't ready.
-		await Promise.all( [
-			retry( () => configureWordPress( 'development', config, spinner ), {
-				times: 2,
-			} ),
-			retry( () => configureWordPress( 'tests', config, spinner ), {
-				times: 2,
-			} ),
-		] );
-
-		// Set the cache key once everything has been configured.
-		await setCache( CONFIG_CACHE_KEY, configHash, {
-			workDirectoryPath,
-		} );
+		throw error;
 	}
 
 	if ( scripts ) {
 		await executeLifecycleScript( 'afterStart', config, spinner );
 	}
 
-	const siteUrl = config.env.development.config.WP_SITEURL;
-	const testsSiteUrl = config.env.tests.config.WP_SITEURL;
-
-	const mySQLPort = await getPublicDockerPort(
-		'mysql',
-		3306,
-		dockerComposeConfig
-	);
-
-	const testsMySQLPort = await getPublicDockerPort(
-		'tests-mysql',
-		3306,
-		dockerComposeConfig
-	);
-
-	const phpmyadminPort = config.env.development.phpmyadminPort
-		? await getPublicDockerPort( 'phpmyadmin', 80, dockerComposeConfig )
-		: null;
-
-	const testsPhpmyadminPort = config.env.tests.phpmyadminPort
-		? await getPublicDockerPort(
-				'tests-phpmyadmin',
-				80,
-				dockerComposeConfig
-		  )
-		: null;
-
-	spinner.prefixText = [
-		'WordPress development site started' +
-			( siteUrl ? ` at ${ siteUrl }` : '.' ),
-		'WordPress test site started' +
-			( testsSiteUrl ? ` at ${ testsSiteUrl }` : '.' ),
-		`MySQL is listening on port ${ mySQLPort }`,
-		`MySQL for automated testing is listening on port ${ testsMySQLPort }`,
-		phpmyadminPort &&
-			`phpMyAdmin started at http://localhost:${ phpmyadminPort }`,
-		testsPhpmyadminPort &&
-			`phpMyAdmin for automated testing started at http://localhost:${ testsPhpmyadminPort }`,
-	]
-		.filter( Boolean )
-		.join( '\n' );
+	spinner.prefixText = result.message;
 	spinner.prefixText += '\n\n';
 	spinner.text = 'Done!';
 };
 
-async function getPublicDockerPort(
-	service,
-	containerPort,
-	dockerComposeConfig
-) {
-	const { out: address } = await dockerCompose.port(
-		service,
-		containerPort,
-		dockerComposeConfig
-	);
-	return address.split( ':' ).pop().trim();
-}
-
 /**
  * Checks for legacy installs and provides
  * the user the option to delete them.

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

@@ -2,32 +2,30 @@
 /**
  * External dependencies
  */
-const { v2: dockerCompose } = require( 'docker-compose' );
+const path = require( 'path' );
 
 /**
  * Internal dependencies
  */
-const initConfig = require( '../init-config' );
+const { loadConfig } = require( '../config' );
+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 { dockerComposeConfigPath } = await initConfig( {
-		spinner,
-		debug,
-	} );
-
-	spinner.text = 'Stopping WordPress.';
-
-	await dockerCompose.down( {
-		config: dockerComposeConfigPath,
-		log: debug,
-	} );
-
-	spinner.text = 'Stopped WordPress.';
+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 ) {

package/lib/config/load-config.js

@@ -11,6 +11,7 @@ const fs = require( 'fs' ).promises;
 const getCacheDirectory = require( './get-cache-directory' );
 const md5 = require( '../md5' );
 const { parseConfig, getConfigFilePath } = require( './parse-config' );
+const { ValidationError } = require( './validate-config' );
 const postProcessConfig = require( './post-process-config' );
 
 /**
@@ -35,12 +36,31 @@ const postProcessConfig = require( './post-process-config' );
 /**
  * Loads any configuration from a given directory.
  *
- * @param {string} configDirectoryPath The directory we want to load the config from.
+ * @param {string}      configDirectoryPath The directory we want to load the config from.
+ * @param {string|null} customConfigPath    Optional custom config file path.
  *
  * @return {Promise<WPConfig>} The config object we've loaded.
  */
-module.exports = async function loadConfig( configDirectoryPath ) {
-	const configFilePath = getConfigFilePath( configDirectoryPath );
+module.exports = async function loadConfig(
+	configDirectoryPath,
+	customConfigPath = null
+) {
+	const configFilePath = getConfigFilePath(
+		configDirectoryPath,
+		'local',
+		customConfigPath
+	);
+
+	// If a custom config path was provided, verify the file exists.
+	if ( customConfigPath ) {
+		try {
+			await fs.stat( configFilePath );
+		} catch ( error ) {
+			throw new ValidationError(
+				`Config file not found: ${ configFilePath }`
+			);
+		}
+	}
 
 	const cacheDirectoryPath = path.resolve(
 		await getCacheDirectory(),
@@ -49,7 +69,11 @@ module.exports = async function loadConfig( configDirectoryPath ) {
 
 	// Parse any configuration we found in the given directory.
 	// This comes merged and prepared for internal consumption.
-	let config = await parseConfig( configDirectoryPath, cacheDirectoryPath );
+	let config = await parseConfig(
+		configDirectoryPath,
+		cacheDirectoryPath,
+		customConfigPath
+	);
 
 	// Make sure to perform any additional post-processing that
 	// may be needed before the config object is ready for
@@ -64,9 +88,15 @@ module.exports = async function loadConfig( configDirectoryPath ) {
 		),
 		configDirectoryPath,
 		workDirectoryPath: cacheDirectoryPath,
+		customConfigPath,
+		testsEnvironment: config.testsEnvironment !== false,
 		detectedLocalConfig: await hasLocalConfig( [
 			configFilePath,
-			getConfigFilePath( configDirectoryPath, 'override' ),
+			getConfigFilePath(
+				configDirectoryPath,
+				'override',
+				customConfigPath
+			),
 		] ),
 		lifecycleScripts: config.lifecycleScripts,
 		env: config.env,