@wordpress/env 11.0.1-next.v.0 → 11.0.1-next.v.202602091733.0

package/README.md

@@ -186,7 +186,7 @@ To reset the database:
 **⚠️ WARNING: This will permanently delete any posts, pages, media, etc. in the local WordPress installation.**
 
 ```sh
-$ wp-env clean all
+$ wp-env reset all
 $ wp-env start
 ```
 
@@ -295,6 +295,42 @@ Here is a summary:
 
 `wp-env` creates generated files in the `wp-env` home directory. By default, this is `~/.wp-env`. The exception is Linux, where files are placed at `~/wp-env` [for compatibility with Snap Packages](https://github.com/WordPress/gutenberg/issues/20180#issuecomment-587046325). The `wp-env` home directory contains a subdirectory for each project named `/$md5_of_project_path`. To change the `wp-env` home directory, set the `WP_ENV_HOME` environment variable. For example, running `WP_ENV_HOME="something" wp-env start` will download the project files to the directory `./something/$md5_of_project_path` (relative to the current directory).
 
+### Global options
+
+These options apply to all `wp-env` commands:
+
+```
+--debug    Enable debug output.                      [boolean] [default: false]
+--config   Path to a custom .wp-env.json configuration file.           [string]
+```
+
+The `--config` option allows you to use a custom configuration file instead of the default `.wp-env.json`. This is useful for running multiple parallel environments from the same directory.
+
+When using a custom config file, the override file is derived from its name. For example:
+- `--config=staging.json` will look for `staging.override.json`
+- `--config=./configs/dev.wp-env.json` will look for `./configs/dev.wp-env.override.json`
+
+#### Running parallel environments
+
+You can run multiple wp-env environments from the same folder by using different config files and ports:
+
+```sh
+# Start first environment with default config
+wp-env start
+
+# Start second environment with custom config on different ports
+WP_ENV_PORT=8890 WP_ENV_TESTS_PORT=8891 wp-env start --config=./staging.json
+
+# Check status of each environment
+wp-env status
+wp-env status --config=./staging.json
+
+# Stop specific environment
+wp-env stop --config=./staging.json
+```
+
+Each config file gets its own isolated Docker containers and data, so changes in one environment don't affect the other.
+
 ### `wp-env start`
 
 The start command installs and initializes the WordPress environment, which includes downloading any specified remote sources. By default, `wp-env` will not update or re-configure the environment except when the configuration file changes. Tell `wp-env` to update sources and apply the configuration options again with `wp-env start --update`. This will not overwrite any existing content.
@@ -340,15 +376,15 @@ Options:
   --debug            Enable debug output.             [boolean] [default: false]
 ```
 
-### `wp-env clean [environment]`
+### `wp-env reset [environment]`
 
 ```sh
-wp-env clean [environment]
+wp-env reset [environment]
 
-Cleans the WordPress databases.
+Resets the WordPress databases.
 
 Positionals:
-  environment  Which environments' databases to clean.
+  environment  Which environments' databases to reset.
             [string] [choices: "all", "development", "tests"] [default: "tests"]
 
 Options:
@@ -469,17 +505,32 @@ To set the permalink to the year, month, and post name:
 wp-env run cli "wp rewrite structure /%year%/%monthnum%/%postname%/"
 ```
 
+### `wp-env cleanup`
+
+```sh
+wp-env cleanup
+
+Cleanup the WordPress environment. Removes docker containers, volumes, networks,
+and local files, but preserves docker images for faster re-starts.
+
+Options:
+  --debug    Enable debug output.                     [boolean] [default: false]
+  --scripts  Execute any configured lifecycle scripts. [boolean] [default: true]
+  --force    Skip the confirmation prompt.            [boolean] [default: false]
+```
+
 ### `wp-env destroy`
 
 ```sh
 wp-env destroy
 
-Destroy the WordPress environment. Deletes docker containers, volumes, and
-networks associated with the WordPress environment and removes local files.
+Destroy the WordPress environment. Deletes docker containers, volumes, networks,
+and images associated with the WordPress environment and removes local files.
 
 Options:
   --debug    Enable debug output.                     [boolean] [default: false]
   --scripts  Execute any configured lifecycle scripts. [boolean] [default: true]
+  --force    Skip the confirmation prompt.            [boolean] [default: false]
 ```
 
 ### `wp-env logs [environment]`
@@ -629,7 +680,8 @@ example, `WP_ENV_LIFECYCLE_SCRIPT_AFTER_START`. Keep in mind that these will be
 build won't break on subsequent executions.
 
 * `afterStart`: Runs after `wp-env start` has finished setting up the environment.
-* `afterClean`: Runs after `wp-env clean` has finished cleaning the environment.
+* `afterReset`: Runs after `wp-env reset` has finished resetting the environment.
+* `afterCleanup`: Runs after `wp-env cleanup` has cleaned up the environment.
 * `afterDestroy`: Runs after `wp-env destroy` has destroyed the environment.
 
 ## Examples
@@ -769,7 +821,7 @@ You can tell `wp-env` to use a specific PHP version for compatibility and testin
 
 ### Multisite support
 
-You can tell `wp-env`  if the site should be multisite enabled. This can also be set via the environment variable `WP_ENV_MULTISITE`.
+You can tell `wp-env` if the site should be multisite enabled.
 
 ```json
 {

package/lib/cli.js

@@ -18,6 +18,7 @@ const {
 	getAvailableRuntimes,
 	getRuntime,
 	UnsupportedCommandError,
+	EnvironmentNotInitializedError,
 } = require( './runtime' );
 
 // Colors.
@@ -45,8 +46,11 @@ const withSpinner =
 				process.exit( 0 );
 			},
 			( error ) => {
-				if ( error instanceof UnsupportedCommandError ) {
-					// Error is an unsupported command in the current runtime.
+				if (
+					error instanceof UnsupportedCommandError ||
+					error instanceof EnvironmentNotInitializedError
+				) {
+					// Error is a known user-facing error.
 					spinner.fail( error.message );
 					process.exit( 1 );
 				} else if (
@@ -97,6 +101,11 @@ module.exports = function cli() {
 		describe: 'Enable debug output.',
 		default: false,
 	} );
+	yargs.option( 'config', {
+		type: 'string',
+		describe: 'Path to a custom .wp-env.json configuration file.',
+		requiresArg: true,
+	} );
 
 	yargs.parserConfiguration( {
 		// Treats unknown options as arguments for commands to deal with instead of discarding them.
@@ -162,13 +171,31 @@ module.exports = function cli() {
 		() => {},
 		withSpinner( env.stop )
 	);
+	yargs.command(
+		'reset [environment]',
+		wpYellow( 'Resets the WordPress databases.' ),
+		( args ) => {
+			args.positional( 'environment', {
+				type: 'string',
+				describe: "Which environments' databases to reset.",
+				choices: [ 'all', 'development', 'tests' ],
+				default: 'tests',
+			} );
+			args.option( 'scripts', {
+				type: 'boolean',
+				describe: 'Execute any configured lifecycle scripts.',
+				default: true,
+			} );
+		},
+		withSpinner( env.reset )
+	);
 	yargs.command(
 		'clean [environment]',
-		wpYellow( 'Cleans the WordPress databases.' ),
+		chalk.gray( '[Deprecated: use reset] Resets the WordPress databases.' ),
 		( args ) => {
 			args.positional( 'environment', {
 				type: 'string',
-				describe: "Which environments' databases to clean.",
+				describe: "Which environments' databases to reset.",
 				choices: [ 'all', 'development', 'tests' ],
 				default: 'tests',
 			} );
@@ -246,7 +273,7 @@ module.exports = function cli() {
 	yargs.command(
 		'destroy',
 		wpRed(
-			'Destroy the WordPress environment. Deletes docker containers, volumes, and networks associated with the WordPress environment and removes local files.'
+			'Destroy the WordPress environment. Deletes docker containers, volumes, networks, and images associated with the WordPress environment and removes local files.'
 		),
 		( args ) => {
 			args.option( 'scripts', {
@@ -254,9 +281,33 @@ module.exports = function cli() {
 				describe: 'Execute any configured lifecycle scripts.',
 				default: true,
 			} );
+			args.option( 'force', {
+				type: 'boolean',
+				describe: 'Skip the confirmation prompt.',
+				default: false,
+			} );
 		},
 		withSpinner( env.destroy )
 	);
+	yargs.command(
+		'cleanup',
+		wpYellow(
+			'Cleanup the WordPress environment. Removes docker containers, volumes, networks, and local files, but preserves docker images for faster re-starts.'
+		),
+		( args ) => {
+			args.option( 'scripts', {
+				type: 'boolean',
+				describe: 'Execute any configured lifecycle scripts.',
+				default: true,
+			} );
+			args.option( 'force', {
+				type: 'boolean',
+				describe: 'Skip the confirmation prompt.',
+				default: false,
+			} );
+		},
+		withSpinner( env.cleanup )
+	);
 	yargs.command(
 		'status',
 		'Get the status of the wp-env environment including URLs, ports, and configuration.',

package/lib/commands/clean.js

@@ -17,25 +17,34 @@ const { getRuntime, detectRuntime } = require( '../runtime' );
  */
 
 /**
- * Wipes the development server's database, the tests server's database, or both.
+ * @deprecated Use `reset` instead.
+ *
+ * Resets the development server's database, the tests server's database, or both.
  *
  * @param {Object}                 options
- * @param {WPEnvironmentSelection} options.environment The environment to clean. Either 'development', 'tests', or 'all'.
+ * @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 clean( {
 	environment,
 	spinner,
 	scripts,
 	debug,
+	config: customConfigPath,
 } ) {
-	const config = await loadConfig( path.resolve( '.' ) );
-	const runtime = getRuntime( detectRuntime( config.workDirectoryPath ) );
+	spinner.warn( 'The `clean` command is deprecated. Use `reset` instead.' );
+
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
+	const runtime = getRuntime(
+		await detectRuntime( config.workDirectoryPath )
+	);
 
 	await runtime.clean( config, { environment, spinner, debug } );
 
+	// Execute afterClean for backwards compatibility.
 	if ( scripts ) {
 		await executeLifecycleScript( 'afterClean', config, spinner );
 	}

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 status = require( './status' );
 
 module.exports = {
 	start,
 	stop,
+	reset,
 	clean,
 	run,
 	destroy,
+	cleanup,
 	logs,
 	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(
@@ -76,6 +110,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.