@wordpress/env 10.39.0 → 11.0.0

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,52 +107,44 @@ 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
+	// All source types (local, git, zip) can be mounted after downloading/extraction
 	for ( const [ wpDir, source ] of Object.entries(
 		envConfig.mappings || {}
 	) ) {
-		if ( source.type === 'local' || source.type === 'git' ) {
-			args.push( '--mount-dir', source.path, `/wordpress/${ wpDir }` );
-		} else {
-			throw new Error(
-				`Mapping source "${ source.path }" for "${ wpDir }" of type "${ source.type }" ` +
-					`is not supported with Playground runtime. Only local and git mappings are supported.`
-			);
-		}
+		args.push( '--mount-dir', source.path, `/wordpress/${ wpDir }` );
 	}
 
-	// Mount core source if specified
+	// Translate core source to Playground's --wp flag or mount it.
 	if ( envConfig.coreSource ) {
-		if (
-			envConfig.coreSource.type === 'local' ||
-			envConfig.coreSource.type === 'git'
-		) {
+		if ( envConfig.coreSource.type === 'zip' && envConfig.coreSource.url ) {
+			// For zip URLs, let Playground download WordPress natively.
+			args.push( '--wp', envConfig.coreSource.url );
+		} else if ( envConfig.coreSource.type === 'git' ) {
+			// For git sources, pass the version ref to Playground's --wp flag.
+			// e.g., WordPress/WordPress#6.5 → --wp 6.5
+			// WordPress/WordPress (no ref) → default "latest", no flag needed.
+			if ( envConfig.coreSource.ref ) {
+				args.push( '--wp', envConfig.coreSource.ref );
+			}
+		} else {
+			// For local sources, mount the directory and tell Playground to
+			// use the existing files instead of downloading its own copy.
 			args.push(
 				'--mount-dir-before-install',
 				envConfig.coreSource.path,
-				'/wordpress'
-			);
-		} else {
-			throw new Error(
-				`Core source of type "${ envConfig.coreSource.type }" is not supported ` +
-					`with Playground runtime. Only local and git core sources are supported.`
+				'/wordpress',
+				'--wordpress-install-mode',
+				'install-from-existing-files-if-needed'
 			);
 		}
 	}

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,71 @@ 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.';
+	}
+
+	/**
+	 * Get the status of the Playground environment.
+	 *
+	 * @param {Object} config          The wp-env config object.
+	 * @param {Object} options         Status options.
+	 * @param {Object} options.spinner A CLI spinner which indicates progress.
+	 * @return {Promise<Object>} Status object with environment information.
+	 */
+	async getStatus( config, { spinner } ) {
+		spinner.text = 'Getting environment status.';
+
+		const envConfig = config.env.development;
+		const port = envConfig.port || 8888;
+		const pidFile = path.join( config.workDirectoryPath, 'playground.pid' );
+
+		// Check if server is running.
+		let isRunning = false;
+
+		try {
+			const pidContent = await fs.readFile( pidFile, 'utf8' );
+			const pid = parseInt( pidContent.trim(), 10 );
+
+			// Check if process is still alive.
+			process.kill( pid, 0 );
+
+			// Check if server is responding.
+			await this._checkServer( port );
+			isRunning = true;
+		} catch {
+			// Process not running or server not responding.
+		}
+
+		return {
+			status: isRunning ? 'running' : 'stopped',
+			runtime: 'playground',
+			urls: {
+				development: isRunning ? `http://localhost:${ port }` : null,
+			},
+			ports: {
+				development: port,
+			},
+			config: {
+				multisite: envConfig.multisite,
+				xdebug: 'off',
+			},
+			configPath: config.configDirectoryPath,
+			installPath: config.workDirectoryPath,
+		};
 	}
 
 	/**

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

@@ -131,4 +131,151 @@ 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' },
+		} );
+	} );
+
+	describe( 'testsEnvironment', () => {
+		it( 'should omit tests services when testsEnvironment is false', () => {
+			const dockerConfig = buildDockerComposeConfig( {
+				testsEnvironment: false,
+				workDirectoryPath: '/path',
+				env: {
+					development: CONFIG,
+					tests: CONFIG,
+				},
+			} );
+
+			// Development services should exist.
+			expect( dockerConfig.services.mysql ).toBeDefined();
+			expect( dockerConfig.services.wordpress ).toBeDefined();
+			expect( dockerConfig.services.cli ).toBeDefined();
+			expect( dockerConfig.services.phpmyadmin ).toBeDefined();
+
+			// Tests services should not exist.
+			expect( dockerConfig.services[ 'tests-mysql' ] ).toBeUndefined();
+			expect(
+				dockerConfig.services[ 'tests-wordpress' ]
+			).toBeUndefined();
+			expect( dockerConfig.services[ 'tests-cli' ] ).toBeUndefined();
+			expect(
+				dockerConfig.services[ 'tests-phpmyadmin' ]
+			).toBeUndefined();
+		} );
+
+		it( 'should omit tests volumes when testsEnvironment is false', () => {
+			const dockerConfig = buildDockerComposeConfig( {
+				testsEnvironment: false,
+				workDirectoryPath: '/path',
+				env: {
+					development: CONFIG,
+					tests: CONFIG,
+				},
+			} );
+
+			// Development volumes should exist.
+			expect( dockerConfig.volumes.wordpress ).toBeDefined();
+			expect( dockerConfig.volumes.mysql ).toBeDefined();
+			expect( dockerConfig.volumes[ 'user-home' ] ).toBeDefined();
+
+			// Tests volumes should not exist.
+			expect( dockerConfig.volumes[ 'tests-wordpress' ] ).toBeUndefined();
+			expect( dockerConfig.volumes[ 'mysql-test' ] ).toBeUndefined();
+			expect( dockerConfig.volumes[ 'tests-user-home' ] ).toBeUndefined();
+		} );
+
+		it( 'should include tests services by default', () => {
+			const dockerConfig = buildDockerComposeConfig( {
+				workDirectoryPath: '/path',
+				env: {
+					development: CONFIG,
+					tests: CONFIG,
+				},
+			} );
+
+			expect( dockerConfig.services[ 'tests-mysql' ] ).toBeDefined();
+			expect( dockerConfig.services[ 'tests-wordpress' ] ).toBeDefined();
+			expect( dockerConfig.services[ 'tests-cli' ] ).toBeDefined();
+		} );
+	} );
 } );

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,31 +44,38 @@ 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 ];
-		expect( environment ).toBe( 'tests' );
+	it( 'parses reset commands for the default environment.', () => {
+		cli().parse( [ 'reset' ] );
+		const { environment, spinner } = env.reset.mock.calls[ 0 ][ 0 ];
+		expect( environment ).toBe( 'development' );
 		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' ] );
-		const { environment, spinner } = env.clean.mock.calls[ 0 ][ 0 ];
+	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( 'development' );
+		expect( spinner.text ).toBe( '' );
+	} );
+
 	it( 'parses run commands without arguments.', () => {
 		cli().parse( [ 'run', 'tests-wordpress', 'test' ] );
 		const { container, command, spinner } = env.run.mock.calls[ 0 ][ 0 ];
@@ -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": "10.39.0",
+	"version": "11.0.0",
 	"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": "eee1cfb1472f11183e40fb77465a5f13145df7ad"
+	"gitHead": "376124aa10dbc2cc0c81c964ec00b99fcfee5382"
 }

package/lib/commands/install-path.js

@@ -1,33 +0,0 @@
-'use strict';
-/**
- * External dependencies
- */
-const path = require( 'path' );
-const { existsSync } = require( 'fs' );
-
-/**
- * Internal dependencies
- */
-const { loadConfig } = require( '../config' );
-
-/**
- * Logs the path to where wp-env files are installed.
- *
- * @param {Object} options
- * @param {Object} options.spinner
- */
-module.exports = async function installPath( { spinner } ) {
-	// Stop the spinner so that stdout is not polluted.
-	spinner.stop();
-
-	const config = await loadConfig( path.resolve( '.' ) );
-
-	if ( ! existsSync( config.workDirectoryPath ) ) {
-		console.error(
-			'wp-env has not yet been initialized. Please run `wp-env start` first.'
-		);
-		process.exit( 1 );
-	}
-
-	console.log( config.workDirectoryPath );
-};