@wordpress/env 11.0.1-next.v.0 → 11.0.1-next.v.20260206T143.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
 ```
 
@@ -340,15 +340,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 +469,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 +644,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 +785,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 (
@@ -162,13 +166,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 +268,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 +276,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,10 +17,12 @@ 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.
@@ -31,11 +33,16 @@ module.exports = async function clean( {
 	scripts,
 	debug,
 } ) {
+	spinner.warn( 'The `clean` command is deprecated. Use `reset` instead.' );
+
 	const config = await loadConfig( path.resolve( '.' ) );
-	const runtime = getRuntime( detectRuntime( config.workDirectoryPath ) );
+	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,70 @@
+'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.
+ */
+module.exports = async function cleanup( { spinner, scripts, force, debug } ) {
+	const config = await loadConfig( path.resolve( '.' ) );
+
+	try {
+		await fs.readdir( config.workDirectoryPath );
+	} catch {
+		spinner.text = 'Could not find any files to remove.';
+		return;
+	}
+
+	const runtime = getRuntime( 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

@@ -19,9 +19,10 @@ const { getRuntime, detectRuntime } = require( '../runtime' );
  * @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.
  */
-module.exports = async function destroy( { spinner, scripts, debug } ) {
+module.exports = async function destroy( { spinner, scripts, force, debug } ) {
 	const config = await loadConfig( path.resolve( '.' ) );
 
 	try {
@@ -31,22 +32,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

@@ -21,6 +21,8 @@ const { getRuntime, detectRuntime } = require( '../runtime' );
  */
 module.exports = async function logs( { environment, watch, spinner, debug } ) {
 	const config = await loadConfig( path.resolve( '.' ) );
-	const runtime = getRuntime( detectRuntime( config.workDirectoryPath ) );
+	const runtime = getRuntime(
+		await detectRuntime( config.workDirectoryPath )
+	);
 	await runtime.logs( config, { environment, watch, spinner, debug } );
 };

package/lib/commands/reset.js

@@ -0,0 +1,42 @@
+'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.
+ */
+module.exports = async function reset( {
+	environment,
+	spinner,
+	scripts,
+	debug,
+} ) {
+	const config = await loadConfig( path.resolve( '.' ) );
+	const runtime = getRuntime( detectRuntime( config.workDirectoryPath ) );
+
+	await runtime.clean( config, { environment, spinner, debug } );
+
+	if ( scripts ) {
+		await executeLifecycleScript( 'afterReset', config, spinner );
+	}
+};

package/lib/commands/run.js

@@ -30,7 +30,9 @@ module.exports = async function run( {
 	debug,
 } ) {
 	const config = await loadConfig( path.resolve( '.' ) );
-	const runtime = getRuntime( detectRuntime( config.workDirectoryPath ) );
+	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
@@ -51,6 +51,38 @@ module.exports = async function start( {
 	const config = await loadConfig( path.resolve( '.' ) );
 	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 +108,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/stop.js

@@ -19,6 +19,8 @@ const { getRuntime, detectRuntime } = require( '../runtime' );
  */
 module.exports = async function stop( { spinner, debug } ) {
 	const config = await loadConfig( path.resolve( '.' ) );
-	const runtime = getRuntime( detectRuntime( config.workDirectoryPath ) );
+	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/parse-config.js

@@ -235,6 +235,8 @@ async function getDefaultConfig(
 		lifecycleScripts: {
 			afterStart: null,
 			afterClean: null,
+			afterReset: null,
+			afterCleanup: null,
 			afterDestroy: null,
 		},
 		env: {
@@ -312,6 +314,12 @@ function getEnvironmentVarOverrides( cacheDirectoryPath ) {
 		overrideConfig.env.tests.phpVersion = overrides.phpVersion;
 	}
 
+	if ( overrides.multisite ) {
+		overrideConfig.multisite = overrides.multisite;
+		overrideConfig.env.development.multisite = overrides.multisite;
+		overrideConfig.env.tests.multisite = overrides.multisite;
+	}
+
 	return overrideConfig;
 }
 

package/lib/config/test/__snapshots__/config-integration.js.snap

@@ -71,7 +71,9 @@ exports[`Config Integration should load local and override configuration files 1
   },
   "lifecycleScripts": {
     "afterClean": null,
+    "afterCleanup": null,
     "afterDestroy": "test",
+    "afterReset": null,
     "afterStart": null,
   },
   "name": "gutenberg",
@@ -150,7 +152,9 @@ exports[`Config Integration should load local configuration file 1`] = `
   },
   "lifecycleScripts": {
     "afterClean": null,
+    "afterCleanup": null,
     "afterDestroy": null,
+    "afterReset": null,
     "afterStart": "test",
   },
   "name": "gutenberg",
@@ -229,7 +233,9 @@ exports[`Config Integration should use default configuration 1`] = `
   },
   "lifecycleScripts": {
     "afterClean": null,
+    "afterCleanup": null,
     "afterDestroy": null,
+    "afterReset": null,
     "afterStart": null,
   },
   "name": "gutenberg",
@@ -310,7 +316,9 @@ exports[`Config Integration should use environment variables over local and over
   },
   "lifecycleScripts": {
     "afterClean": null,
+    "afterCleanup": null,
     "afterDestroy": null,
+    "afterReset": null,
     "afterStart": "test",
   },
   "name": "gutenberg",

package/lib/config/test/parse-config.js

@@ -52,6 +52,8 @@ const DEFAULT_CONFIG = {
 	lifecycleScripts: {
 		afterStart: null,
 		afterClean: null,
+		afterReset: null,
+		afterCleanup: null,
 		afterDestroy: null,
 	},
 	env: {

package/lib/runtime/docker/build-docker-compose-config.js

@@ -181,6 +181,19 @@ module.exports = function buildDockerComposeConfig( config ) {
 		config.env.tests.phpmyadminPort ?? ''
 	}}:80`;
 
+	// MySQL healthcheck using MariaDB's official healthcheck.sh script.
+	// --connect: verifies TCP connection and that entrypoint has finished
+	// --innodb_initialized: ensures InnoDB storage engine is fully initialized
+	// MARIADB_AUTO_UPGRADE env var ensures healthcheck user exists for existing installations.
+	// Timing is generous to support slow CI environments.
+	const mysqlHealthcheck = {
+		test: [ 'CMD', 'healthcheck.sh', '--connect', '--innodb_initialized' ],
+		interval: '5s',
+		timeout: '10s',
+		retries: 12,
+		start_period: '60s',
+	};
+
 	return {
 		services: {
 			mysql: {
@@ -191,8 +204,11 @@ module.exports = function buildDockerComposeConfig( config ) {
 					MYSQL_ROOT_PASSWORD:
 						dbEnv.credentials.WORDPRESS_DB_PASSWORD,
 					MYSQL_DATABASE: dbEnv.development.WORDPRESS_DB_NAME,
+					// Ensures healthcheck user is created for existing installations.
+					MARIADB_AUTO_UPGRADE: '1',
 				},
 				volumes: [ 'mysql:/var/lib/mysql' ],
+				healthcheck: mysqlHealthcheck,
 			},
 			'tests-mysql': {
 				image: 'mariadb:lts',
@@ -202,11 +218,18 @@ module.exports = function buildDockerComposeConfig( config ) {
 					MYSQL_ROOT_PASSWORD:
 						dbEnv.credentials.WORDPRESS_DB_PASSWORD,
 					MYSQL_DATABASE: dbEnv.tests.WORDPRESS_DB_NAME,
+					// Ensures healthcheck user is created for existing installations.
+					MARIADB_AUTO_UPGRADE: '1',
 				},
 				volumes: [ 'mysql-test:/var/lib/mysql' ],
+				healthcheck: mysqlHealthcheck,
 			},
 			wordpress: {
-				depends_on: [ 'mysql' ],
+				depends_on: {
+					mysql: {
+						condition: 'service_healthy',
+					},
+				},
 				build: {
 					context: '.',
 					dockerfile: 'WordPress.Dockerfile',
@@ -224,7 +247,11 @@ module.exports = function buildDockerComposeConfig( config ) {
 				extra_hosts: [ 'host.docker.internal:host-gateway' ],
 			},
 			'tests-wordpress': {
-				depends_on: [ 'tests-mysql' ],
+				depends_on: {
+					'tests-mysql': {
+						condition: 'service_healthy',
+					},
+				},
 				build: {
 					context: '.',
 					dockerfile: 'Tests-WordPress.Dockerfile',

package/lib/runtime/docker/index.js

@@ -11,7 +11,6 @@ const { rimraf } = require( 'rimraf' );
 /**
  * Promisified dependencies
  */
-const sleep = util.promisify( setTimeout );
 const exec = util.promisify( require( 'child_process' ).exec );
 
 /**
@@ -26,7 +25,6 @@ const {
 	validateRunContainer,
 } = require( './validate-run-container' );
 const {
-	checkDatabaseConnection,
 	configureWordPress,
 	resetDatabase,
 	setupWordPressDirectories,
@@ -174,7 +172,7 @@ class DockerRuntime {
 		}
 
 		await Promise.all( [
-			dockerCompose.upOne( 'mysql', {
+			dockerCompose.upMany( [ 'mysql', 'tests-mysql' ], {
 				...dockerComposeConfig,
 				commandOptions: shouldConfigureWp
 					? [ '--build', '--force-recreate' ]
@@ -250,19 +248,6 @@ class DockerRuntime {
 		if ( shouldConfigureWp ) {
 			spinner.text = 'Configuring WordPress.';
 
-			try {
-				await checkDatabaseConnection( fullConfig );
-			} catch ( error ) {
-				// Wait 30 seconds for MySQL to accept connections.
-				await retry( () => checkDatabaseConnection( fullConfig ), {
-					times: 30,
-					delay: 1000,
-				} );
-
-				// It takes 3-4 seconds for MySQL to be ready after it starts accepting connections.
-				await sleep( 4000 );
-			}
-
 			// Retry WordPress installation in case MySQL *still* wasn't ready.
 			await Promise.all( [
 				retry(
@@ -369,6 +354,15 @@ class DockerRuntime {
 		return 'WARNING! This will remove Docker containers, volumes, networks, and images associated with the WordPress instance.';
 	}
 
+	/**
+	 * Get the warning message for cleanup confirmation.
+	 *
+	 * @return {string} Warning message.
+	 */
+	getCleanupWarningMessage() {
+		return 'WARNING! This will remove Docker containers, volumes, networks, and local files associated with the WordPress instance. Docker images will be preserved.';
+	}
+
 	/**
 	 * Stop the Docker containers.
 	 *
@@ -413,7 +407,8 @@ class DockerRuntime {
 		spinner.text = 'Removing local files.';
 		// Note: there is a race condition where docker compose actually hasn't finished
 		// by this point, which causes rimraf to fail. We need to wait at least 2.5-5s,
-		// but using 10s in case it's dependant on the machine.
+		// but using 10s in case it's dependent on the machine. Removing images takes
+		// longer so we use a longer wait time here.
 		await new Promise( ( resolve ) => setTimeout( resolve, 10000 ) );
 		await rimraf( config.workDirectoryPath );
 
@@ -421,11 +416,38 @@ class DockerRuntime {
 	}
 
 	/**
-	 * Clean/reset the WordPress database.
+	 * Cleanup the Docker containers and remove local files, but preserve images.
+	 *
+	 * @param {WPConfig} config          The wp-env config object.
+	 * @param {Object}   options         Cleanup options.
+	 * @param {Object}   options.spinner A CLI spinner which indicates progress.
+	 * @param {boolean}  options.debug   True if debug mode is enabled.
+	 */
+	async cleanup( config, { spinner, debug } ) {
+		spinner.text = 'Removing docker containers, volumes, and networks.';
+
+		await dockerCompose.down( {
+			config: config.dockerComposeConfigPath,
+			commandOptions: [ '--volumes', '--remove-orphans' ],
+			log: debug,
+		} );
+
+		spinner.text = 'Removing local files.';
+		// Note: there is a race condition where docker compose actually hasn't finished
+		// by this point, which causes rimraf to fail. We need to wait at least 2.5-5s,
+		// but since we're not removing images, the wait can be shorter.
+		await new Promise( ( resolve ) => setTimeout( resolve, 3000 ) );
+		await rimraf( config.workDirectoryPath );
+
+		spinner.text = 'Cleaned up WordPress environment.';
+	}
+
+	/**
+	 * Reset the WordPress database.
 	 *
 	 * @param {WPConfig} config              The wp-env config object.
-	 * @param {Object}   options             Clean options.
-	 * @param {string}   options.environment The environment to clean.
+	 * @param {Object}   options             Reset options.
+	 * @param {string}   options.environment The environment to reset.
 	 * @param {Object}   options.spinner     A CLI spinner which indicates progress.
 	 * @param {boolean}  options.debug       True if debug mode is enabled.
 	 */
@@ -435,13 +457,23 @@ class DockerRuntime {
 		const description = `${ environment } environment${
 			environment === 'all' ? 's' : ''
 		}`;
-		spinner.text = `Cleaning ${ description }.`;
+		spinner.text = `Resetting ${ description }.`;
 
 		const tasks = [];
 
-		// Start the database first to avoid race conditions where all tasks create
-		// different docker networks with the same name.
-		await dockerCompose.upOne( 'mysql', {
+		// Start the appropriate MySQL service(s) first to avoid race conditions
+		// where parallel tasks try to create docker networks with the same name.
+		// The dependency chain (cli -> wordpress -> mysql with service_healthy)
+		// ensures MySQL is ready before database operations run.
+		const mysqlServices = [];
+		if ( environment === 'all' || environment === 'development' ) {
+			mysqlServices.push( 'mysql' );
+		}
+		if ( environment === 'all' || environment === 'tests' ) {
+			mysqlServices.push( 'tests-mysql' );
+		}
+
+		await dockerCompose.upMany( mysqlServices, {
 			config: fullConfig.dockerComposeConfigPath,
 			log: fullConfig.debug,
 		} );
@@ -466,7 +498,7 @@ class DockerRuntime {
 
 		await Promise.all( tasks );
 
-		spinner.text = `Cleaned ${ description }.`;
+		spinner.text = `Reset ${ description }.`;
 	}
 
 	/**

package/lib/runtime/docker/wordpress.js

@@ -47,20 +47,6 @@ function isWPMajorMinorVersionLower( version, compareVersion ) {
 	return versionNumber < compareVersionNumber;
 }
 
-/**
- * Checks a WordPress database connection. An error is thrown if the test is
- * unsuccessful.
- *
- * @param {WPConfig} config The wp-env config object.
- */
-async function checkDatabaseConnection( { dockerComposeConfigPath, debug } ) {
-	await dockerCompose.run( 'cli', 'wp db check', {
-		config: dockerComposeConfigPath,
-		commandOptions: [ '--rm' ],
-		log: debug,
-	} );
-}
-
 /**
  * Configures WordPress for the given environment by installing WordPress,
  * activating all plugins, and activating the first theme. These steps are
@@ -316,7 +302,6 @@ async function copyCoreFiles( fromPath, toPath ) {
 }
 
 module.exports = {
-	checkDatabaseConnection,
 	configureWordPress,
 	resetDatabase,
 	setupWordPressDirectories,

package/lib/runtime/errors.js

@@ -12,6 +12,17 @@ class UnsupportedCommandError extends Error {
 	}
 }
 
+/**
+ * Error thrown when the environment has not been initialized.
+ */
+class EnvironmentNotInitializedError extends Error {
+	constructor() {
+		super( 'Environment not initialized. Run `wp-env start` first.' );
+		this.name = 'EnvironmentNotInitializedError';
+	}
+}
+
 module.exports = {
 	UnsupportedCommandError,
+	EnvironmentNotInitializedError,
 };

package/lib/runtime/index.js

@@ -1,17 +1,17 @@
 'use strict';
 
-/**
- * External dependencies
- */
-const { existsSync } = require( 'fs' );
-const path = require( 'path' );
-
 /**
  * Internal dependencies
  */
 const DockerRuntime = require( './docker' );
 const PlaygroundRuntime = require( './playground' );
-const { UnsupportedCommandError } = require( './errors' );
+const {
+	UnsupportedCommandError,
+	EnvironmentNotInitializedError,
+} = require( './errors' );
+const { setCache, getCache } = require( '../cache' );
+
+const RUNTIME_CACHE_KEY = 'runtime';
 
 const runtimes = {
 	docker: DockerRuntime,
@@ -42,28 +42,50 @@ function getAvailableRuntimes() {
 }
 
 /**
- * Detect which runtime was used based on files in the work directory.
- * Returns 'playground' if playground-blueprint.json exists, otherwise 'docker'.
+ * Save the runtime type to the cache file.
+ * Called when start command initializes the environment.
+ *
+ * @param {string} runtimeName       The runtime name ('docker' or 'playground').
+ * @param {string} workDirectoryPath Path to the wp-env work directory.
+ */
+async function saveRuntime( runtimeName, workDirectoryPath ) {
+	await setCache( RUNTIME_CACHE_KEY, runtimeName, { workDirectoryPath } );
+}
+
+/**
+ * Get the saved runtime type from cache.
+ *
+ * @param {string} workDirectoryPath Path to the wp-env work directory.
+ * @return {Promise<string|undefined>} The saved runtime name, or undefined if not set.
+ */
+async function getSavedRuntime( workDirectoryPath ) {
+	return await getCache( RUNTIME_CACHE_KEY, { workDirectoryPath } );
+}
+
+/**
+ * Detect which runtime was used by reading from the cache.
+ * Throws EnvironmentNotInitializedError if no runtime has been saved.
  *
  * @param {string} workDirectoryPath Path to the wp-env work directory.
- * @return {string} Runtime name ('docker' or 'playground').
+ * @return {Promise<string>} Runtime name ('docker' or 'playground').
+ * @throws {EnvironmentNotInitializedError} If environment not initialized.
  */
-function detectRuntime( workDirectoryPath ) {
-	const playgroundBlueprintFile = path.join(
-		workDirectoryPath,
-		'playground-blueprint.json'
-	);
-	if ( existsSync( playgroundBlueprintFile ) ) {
-		return 'playground';
+async function detectRuntime( workDirectoryPath ) {
+	const savedRuntime = await getSavedRuntime( workDirectoryPath );
+	if ( ! savedRuntime ) {
+		throw new EnvironmentNotInitializedError();
 	}
-	return 'docker';
+	return savedRuntime;
 }
 
 module.exports = {
 	getRuntime,
 	getAvailableRuntimes,
 	detectRuntime,
+	saveRuntime,
+	getSavedRuntime,
 	DockerRuntime,
 	PlaygroundRuntime,
 	UnsupportedCommandError,
+	EnvironmentNotInitializedError,
 };

package/lib/runtime/playground/blueprint-builder.js

@@ -107,21 +107,13 @@ function getMountArgs( config ) {
 	}
 
 	// Mount themes
+	// All theme types (local, git, zip) can be mounted after downloading/extraction
 	for ( const theme of envConfig.themeSources || [] ) {
-		if ( theme.type === 'local' || theme.type === 'git' ) {
-			args.push(
-				'--mount-dir',
-				theme.path,
-				`/wordpress/wp-content/themes/${ theme.basename }`
-			);
-		} else {
-			throw new Error(
-				`Theme source "${ theme.basename || theme.path }" of type "${
-					theme.type
-				}" ` +
-					`is not supported with Playground runtime. Only local and git themes are supported.`
-			);
-		}
+		args.push(
+			'--mount-dir',
+			theme.path,
+			`/wordpress/wp-content/themes/${ theme.basename }`
+		);
 	}
 
 	// Mount custom mappings

package/lib/runtime/playground/index.js

@@ -75,6 +75,15 @@ class PlaygroundRuntime {
 		return 'WARNING! This will remove the WordPress Playground environment and all local files.';
 	}
 
+	/**
+	 * Get the warning message for cleanup confirmation.
+	 *
+	 * @return {string} Warning message.
+	 */
+	getCleanupWarningMessage() {
+		return 'WARNING! This will remove the WordPress Playground environment and all local files.';
+	}
+
 	/**
 	 * Start the WordPress Playground environment.
 	 *
@@ -350,6 +359,25 @@ class PlaygroundRuntime {
 		spinner.text = 'Removed WordPress Playground environment.';
 	}
 
+	/**
+	 * Cleanup the WordPress Playground environment.
+	 *
+	 * For Playground, cleanup is the same as destroy since there are no
+	 * shared resources like Docker images to preserve.
+	 *
+	 * @param {Object} config          The wp-env config object.
+	 * @param {Object} options         Cleanup options.
+	 * @param {Object} options.spinner A CLI spinner which indicates progress.
+	 */
+	async cleanup( config, { spinner } ) {
+		await this.stop( config, { spinner } );
+
+		spinner.text = 'Removing local files.';
+		await rimraf( config.workDirectoryPath );
+
+		spinner.text = 'Cleaned up WordPress Playground environment.';
+	}
+
 	/**
 	 * Run a command in the Playground environment.
 	 *
@@ -367,21 +395,21 @@ class PlaygroundRuntime {
 	}
 
 	/**
-	 * Clean/reset the WordPress database.
+	 * Reset the WordPress database.
 	 *
 	 * @param {Object}  config          The wp-env config object.
-	 * @param {Object}  options         Clean options.
+	 * @param {Object}  options         Reset options.
 	 * @param {Object}  options.spinner A CLI spinner which indicates progress.
 	 * @param {boolean} options.debug   True if debug mode is enabled.
 	 */
 	async clean( config, { spinner, debug } ) {
-		spinner.text = 'Cleaning WordPress Playground environment.';
+		spinner.text = 'Resetting WordPress Playground environment.';
 
 		// For Playground, we restart the server to reset the database
 		await this.stop( config, { spinner } );
 		await this.start( config, { spinner, debug } );
 
-		spinner.text = 'Cleaned WordPress Playground environment.';
+		spinner.text = 'Reset WordPress Playground environment.';
 	}
 
 	/**

package/lib/test/build-docker-compose-config.js

@@ -131,4 +131,87 @@ describe( 'buildDockerComposeConfig', () => {
 		expect( dockerConfig.volumes.wordpress ).toBe( undefined );
 		expect( dockerConfig.volumes[ 'tests-wordpress' ] ).toBe( undefined );
 	} );
+
+	it( 'should add healthcheck to mysql services', () => {
+		const config = buildDockerComposeConfig( {
+			workDirectoryPath: '/some/path',
+			env: {
+				development: {
+					port: 8888,
+					mysqlPort: 3306,
+					coreSource: null,
+					pluginSources: [],
+					themeSources: [],
+					mappings: {},
+				},
+				tests: {
+					port: 8889,
+					mysqlPort: 3307,
+					coreSource: null,
+					pluginSources: [],
+					themeSources: [],
+					mappings: {},
+				},
+			},
+		} );
+
+		expect( config.services.mysql.healthcheck ).toBeDefined();
+		expect( config.services.mysql.healthcheck.test ).toEqual( [
+			'CMD',
+			'healthcheck.sh',
+			'--connect',
+			'--innodb_initialized',
+		] );
+		expect( config.services.mysql.healthcheck.interval ).toBe( '5s' );
+		expect( config.services.mysql.healthcheck.timeout ).toBe( '10s' );
+		expect( config.services.mysql.healthcheck.retries ).toBe( 12 );
+		expect( config.services.mysql.healthcheck.start_period ).toBe( '60s' );
+
+		// Verify MARIADB_AUTO_UPGRADE is set for existing installations
+		expect( config.services.mysql.environment.MARIADB_AUTO_UPGRADE ).toBe(
+			'1'
+		);
+
+		expect( config.services[ 'tests-mysql' ].healthcheck ).toBeDefined();
+		expect( config.services[ 'tests-mysql' ].healthcheck.test ).toEqual( [
+			'CMD',
+			'healthcheck.sh',
+			'--connect',
+			'--innodb_initialized',
+		] );
+		expect(
+			config.services[ 'tests-mysql' ].environment.MARIADB_AUTO_UPGRADE
+		).toBe( '1' );
+	} );
+
+	it( 'should use service_healthy condition for WordPress depends_on', () => {
+		const config = buildDockerComposeConfig( {
+			workDirectoryPath: '/some/path',
+			env: {
+				development: {
+					port: 8888,
+					mysqlPort: 3306,
+					coreSource: null,
+					pluginSources: [],
+					themeSources: [],
+					mappings: {},
+				},
+				tests: {
+					port: 8889,
+					mysqlPort: 3307,
+					coreSource: null,
+					pluginSources: [],
+					themeSources: [],
+					mappings: {},
+				},
+			},
+		} );
+
+		expect( config.services.wordpress.depends_on ).toEqual( {
+			mysql: { condition: 'service_healthy' },
+		} );
+		expect( config.services[ 'tests-wordpress' ].depends_on ).toEqual( {
+			'tests-mysql': { condition: 'service_healthy' },
+		} );
+	} );
 } );

package/lib/test/cli.js

@@ -19,8 +19,11 @@ jest.mock( '../env', () => {
 	return {
 		start: jest.fn( Promise.resolve.bind( Promise ) ),
 		stop: jest.fn( Promise.resolve.bind( Promise ) ),
+		reset: jest.fn( Promise.resolve.bind( Promise ) ),
 		clean: jest.fn( Promise.resolve.bind( Promise ) ),
 		run: jest.fn( Promise.resolve.bind( Promise ) ),
+		destroy: jest.fn( Promise.resolve.bind( Promise ) ),
+		cleanup: jest.fn( Promise.resolve.bind( Promise ) ),
 		ValidationError: actual.ValidationError,
 		LifecycleScriptError: actual.LifecycleScriptError,
 	};
@@ -41,26 +44,33 @@ describe( 'env cli', () => {
 		expect( spinner.text ).toBe( '' );
 	} );
 
-	it( 'parses clean commands for the default environment.', () => {
-		cli().parse( [ 'clean' ] );
-		const { environment, spinner } = env.clean.mock.calls[ 0 ][ 0 ];
+	it( 'parses reset commands for the default environment.', () => {
+		cli().parse( [ 'reset' ] );
+		const { environment, spinner } = env.reset.mock.calls[ 0 ][ 0 ];
 		expect( environment ).toBe( 'tests' );
 		expect( spinner.text ).toBe( '' );
 	} );
-	it( 'parses clean commands for all environments.', () => {
-		cli().parse( [ 'clean', 'all' ] );
-		const { environment, spinner } = env.clean.mock.calls[ 0 ][ 0 ];
+	it( 'parses reset commands for all environments.', () => {
+		cli().parse( [ 'reset', 'all' ] );
+		const { environment, spinner } = env.reset.mock.calls[ 0 ][ 0 ];
 		expect( environment ).toBe( 'all' );
 		expect( spinner.text ).toBe( '' );
 	} );
-	it( 'parses clean commands for the development environment.', () => {
-		cli().parse( [ 'clean', 'development' ] );
-		const { environment, spinner } = env.clean.mock.calls[ 0 ][ 0 ];
+	it( 'parses reset commands for the development environment.', () => {
+		cli().parse( [ 'reset', 'development' ] );
+		const { environment, spinner } = env.reset.mock.calls[ 0 ][ 0 ];
 		expect( environment ).toBe( 'development' );
 		expect( spinner.text ).toBe( '' );
 	} );
-	it( 'parses clean commands for the tests environment.', () => {
-		cli().parse( [ 'clean', 'tests' ] );
+	it( 'parses reset commands for the tests environment.', () => {
+		cli().parse( [ 'reset', 'tests' ] );
+		const { environment, spinner } = env.reset.mock.calls[ 0 ][ 0 ];
+		expect( environment ).toBe( 'tests' );
+		expect( spinner.text ).toBe( '' );
+	} );
+
+	it( 'parses clean (deprecated) commands for the default environment.', () => {
+		cli().parse( [ 'clean' ] );
 		const { environment, spinner } = env.clean.mock.calls[ 0 ][ 0 ];
 		expect( environment ).toBe( 'tests' );
 		expect( spinner.text ).toBe( '' );
@@ -81,6 +91,32 @@ describe( 'env cli', () => {
 		expect( spinner.text ).toBe( '' );
 	} );
 
+	it( 'parses destroy commands.', () => {
+		cli().parse( [ 'destroy' ] );
+		const { spinner, scripts, force } = env.destroy.mock.calls[ 0 ][ 0 ];
+		expect( spinner.text ).toBe( '' );
+		expect( scripts ).toBe( true );
+		expect( force ).toBe( false );
+	} );
+	it( 'parses destroy commands with --force flag.', () => {
+		cli().parse( [ 'destroy', '--force' ] );
+		const { force } = env.destroy.mock.calls[ 0 ][ 0 ];
+		expect( force ).toBe( true );
+	} );
+
+	it( 'parses cleanup commands.', () => {
+		cli().parse( [ 'cleanup' ] );
+		const { spinner, scripts, force } = env.cleanup.mock.calls[ 0 ][ 0 ];
+		expect( spinner.text ).toBe( '' );
+		expect( scripts ).toBe( true );
+		expect( force ).toBe( false );
+	} );
+	it( 'parses cleanup commands with --force flag.', () => {
+		cli().parse( [ 'cleanup', '--force' ] );
+		const { force } = env.cleanup.mock.calls[ 0 ][ 0 ];
+		expect( force ).toBe( true );
+	} );
+
 	it( 'handles successful commands with messages.', async () => {
 		env.start.mockResolvedValueOnce( 'success message' );
 		cli().parse( [ 'start' ] );

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/env",
-	"version": "11.0.1-next.v.0+5aba098fc",
+	"version": "11.0.1-next.v.20260206T143.0+81f8de885",
 	"description": "A zero-config, self contained local WordPress environment for development and testing.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -64,5 +64,5 @@
 	"scripts": {
 		"test": "echo \"Error: run tests from root\" && exit 1"
 	},
-	"gitHead": "d730f9e00f5462d1b9d2660632850f5f43ccff44"
+	"gitHead": "6ae3fbb907e6c309ff6a0685e5e5ff0c2ee23b15"
 }