@wordpress/env 11.0.2-next.v.202602271551.0 → 11.1.0

package/lib/resolve-available-ports.js

@@ -0,0 +1,136 @@
+'use strict';
+/**
+ * Internal dependencies
+ */
+const { findAvailablePort, isPortAvailable } = require( './port-utils' );
+
+/**
+ * Port definitions to resolve. Each entry maps a config path to its
+ * environment and property. MySQL ports are excluded because they
+ * already support Docker-native auto-assignment via `null`.
+ */
+const PORT_DEFINITIONS = [
+	{ env: 'development', property: 'port' },
+	{ env: 'tests', property: 'port' },
+	{ env: 'development', property: 'phpmyadminPort' },
+	{ env: 'tests', property: 'phpmyadminPort' },
+];
+
+/**
+ * Well-known preferred ports for auto-resolved HTTP port properties.
+ * Auto-port tries these first and then scans upward to find a free port.
+ */
+const PREFERRED_PORTS = {
+	'development.port': 8888,
+	'tests.port': 8889,
+};
+
+/**
+ * Creates a port resolver that tracks used ports.
+ *
+ * The resolver is designed to be called during config post-processing,
+ * after environments have been merged but before URLs are set. This
+ * allows `appendPortToWPConfigs` to use the resolved ports directly.
+ *
+ * @param {Object} spinner A CLI spinner for displaying progress.
+ * @return {Object} A port resolver with a `resolve` method.
+ */
+function createPortResolver( spinner ) {
+	const usedPorts = [];
+
+	return {
+		/**
+		 * Resolves a single port, finding an alternative if it's busy.
+		 *
+		 * @param {number}  preferredPort The preferred port to use.
+		 * @param {string}  configPath    Config path for error messages (e.g. "env.development.port").
+		 * @param {boolean} strict        When true, fail if the port is busy instead of finding an alternative.
+		 * @return {Promise<number>} The resolved port number.
+		 */
+		async resolve( preferredPort, configPath, strict = false ) {
+			if ( spinner ) {
+				spinner.text = `Checking ${ configPath } availability.`;
+			}
+
+			// When the user set an explicit port, only use that port.
+			if ( strict ) {
+				if ( usedPorts.includes( preferredPort ) ) {
+					throw new Error(
+						`Port ${ preferredPort } (${ configPath }) conflicts with another wp-env service. ` +
+							`Set a different port or enable automatic port selection with --auto-port or "autoPort": true.`
+					);
+				}
+				const available = await isPortAvailable( preferredPort );
+				if ( ! available ) {
+					throw new Error(
+						`Port ${ preferredPort } (${ configPath }) is busy. ` +
+							`Free the port, set a different one, or enable automatic port selection with --auto-port or "autoPort": true.`
+					);
+				}
+				usedPorts.push( preferredPort );
+				return preferredPort;
+			}
+
+			try {
+				const resolvedPort = await findAvailablePort( {
+					preferredPort,
+					exclude: usedPorts,
+				} );
+
+				usedPorts.push( resolvedPort );
+
+				return resolvedPort;
+			} catch ( error ) {
+				throw new Error(
+					`Could not find available port for ${ configPath }: ${ error.message }`
+				);
+			}
+		},
+	};
+}
+
+/**
+ * Resolves available ports on a config object. Iterates over the
+ * defined port properties and resolves each one that has a value.
+ *
+ * @param {Object} config       The config object (after mergeRootToEnvironments).
+ * @param {Object} portResolver A port resolver created by `createPortResolver`.
+ * @return {Promise<Object>} The config with resolved ports.
+ */
+async function resolveConfigPorts( config, portResolver ) {
+	for ( const { env, property } of PORT_DEFINITIONS ) {
+		const currentValue = config.env[ env ][ property ];
+
+		// Skip unconfigured ports (phpmyadminPort defaults to null
+		// and should stay null when not explicitly set).
+		if ( currentValue === undefined ) {
+			continue;
+		}
+
+		// Use a well-known preferred port when one isn't explicitly set.
+		// For explicit ports, use the configured value.
+		const key = `${ env }.${ property }`;
+		const preferredPort = currentValue ?? PREFERRED_PORTS[ key ];
+
+		// Still null after lookup (e.g. phpmyadminPort set to null).
+		if ( ! preferredPort ) {
+			continue;
+		}
+
+		// When --auto-port is active (the only time this runs),
+		// always auto-fallback to an available port.
+		const configPath = `env.${ key }`;
+		config.env[ env ][ property ] = await portResolver.resolve(
+			preferredPort,
+			configPath
+		);
+	}
+
+	return config;
+}
+
+module.exports = {
+	createPortResolver,
+	resolveConfigPorts,
+	PORT_DEFINITIONS,
+};

package/lib/runtime/docker/{init-config.js → docker-config.js}

@@ -10,7 +10,7 @@ const yaml = require( 'js-yaml' );
 /**
  * Internal dependencies
  */
-const { loadConfig, ValidationError } = require( '../../config' );
+const { ValidationError } = require( '../../config' );
 const buildDockerComposeConfig = require( './build-docker-compose-config' );
 
 /**
@@ -18,109 +18,62 @@ const buildDockerComposeConfig = require( './build-docker-compose-config' );
  */
 
 /**
- * Initializes the local environment so that Docker commands can be run. Reads
- * ./.wp-env.json, creates ~/.wp-env, ~/.wp-env/docker-compose.yml, and
- * ~/.wp-env/Dockerfile.
+ * Writes Docker configuration files (docker-compose.yml and Dockerfiles) for
+ * a fully resolved config. Called only by the `start` command.
  *
- * @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}      options.xdebug           The Xdebug mode to set. Defaults to "off".
- * @param {string}      options.spx              The SPX mode to set. Defaults to "off".
- * @param {boolean}     options.writeChanges     If true, writes the parsed config to the
- *                                               required docker files like docker-compose
- *                                               and Dockerfile. By default, this is false
- *                                               and only the `start` command writes any
- *                                               changes.
- * @param {string|null} options.customConfigPath Path to a custom .wp-env.json configuration file.
- * @return {WPConfig} The-env config object.
+ * The config must already have ports resolved, and `debug`, `xdebug`, and
+ * `spx` properties set before calling this function.
+ *
+ * @param {WPConfig} config A fully resolved wp-env config object.
+ * @return {WPConfig} The config object (unchanged).
  */
-module.exports = async function initConfig( {
-	spinner,
-	debug,
-	xdebug = 'off',
-	spx = 'off',
-	writeChanges = false,
-	customConfigPath = null,
-} ) {
-	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
-	config.debug = debug;
-
-	// Adding this to the config allows the start command to understand that the
-	// config has changed when only the xdebug param has changed. This is needed
-	// so that Docker will rebuild the image whenever the xdebug flag changes.
-	config.xdebug = xdebug;
-
-	// Adding this to the config allows the start command to understand that the
-	// config has changed when only the spx param has changed. This is needed
-	// so that Docker will rebuild the image whenever the spx flag changes.
-	config.spx = spx;
-
+async function writeDockerFiles( config ) {
 	const dockerComposeConfig = buildDockerComposeConfig( config );
 
-	if ( config.debug ) {
-		spinner.info(
-			`Config:\n${ JSON.stringify(
-				config,
-				null,
-				4
-			) }\n\nDocker Compose Config:\n${ JSON.stringify(
-				dockerComposeConfig,
-				null,
-				4
-			) }`
-		);
-		spinner.start();
-	}
+	await mkdir( config.workDirectoryPath, { recursive: true } );
 
-	/**
-	 * We avoid writing changes most of the time so that we can better pass params
-	 * to the start command. For example, say you start wp-env with Xdebug enabled.
-	 * If you then run another command, like opening bash in the wp instance, it
-	 * would turn off Xdebug in the Dockerfile because it wouldn't have the --xdebug
-	 * arg. This basically makes it such that wp-env start is the only command
-	 * which updates any of the Docker configuration.
-	 */
-	if ( writeChanges ) {
-		await mkdir( config.workDirectoryPath, { recursive: true } );
-
-		await writeFile(
-			config.dockerComposeConfigPath,
-			yaml.dump( dockerComposeConfig )
-		);
+	await writeFile(
+		config.dockerComposeConfigPath,
+		yaml.dump( dockerComposeConfig )
+	);
 
-		// Write Dockerfiles for each service we provided.
-		// (WordPress and CLI services, then a development and test environment for each.)
-		for ( const imageType of [ 'WordPress', 'CLI' ] ) {
-			for ( const envType of [ 'development', 'tests' ] ) {
-				if (
-					envType === 'tests' &&
-					config.testsEnvironment === false
-				) {
-					continue;
-				}
-				await writeFile(
-					path.resolve(
-						config.workDirectoryPath,
-						`${
-							envType === 'tests' ? 'Tests-' : ''
-						}${ imageType }.Dockerfile`
-					),
-					imageType === 'WordPress'
-						? wordpressDockerFileContents( envType, config )
-						: cliDockerFileContents( envType, config )
-				);
-			}
+	// Write four Dockerfiles for each service we provided.
+	// (WordPress and CLI services, then a development and test environment for each.)
+	for ( const imageType of [ 'WordPress', 'CLI' ] ) {
+		for ( const envType of [ 'development', 'tests' ] ) {
+			await writeFile(
+				path.resolve(
+					config.workDirectoryPath,
+					`${
+						envType === 'tests' ? 'Tests-' : ''
+					}${ imageType }.Dockerfile`
+				),
+				imageType === 'WordPress'
+					? wordpressDockerFileContents( envType, config )
+					: cliDockerFileContents( envType, config )
+			);
 		}
-	} else if ( ! existsSync( config.workDirectoryPath ) ) {
+	}
+
+	return config;
+}
+
+/**
+ * Verifies that the Docker environment has been initialized (i.e. `wp-env
+ * start` has been run at least once). Exits with an error message when the
+ * work directory does not exist.
+ *
+ * @param {WPConfig} config  The wp-env config object.
+ * @param {Object}   spinner A CLI spinner which indicates progress.
+ */
+function ensureDockerInitialized( config, spinner ) {
+	if ( ! existsSync( config.workDirectoryPath ) ) {
 		spinner.fail(
 			'wp-env has not yet been initialized. Please run `wp-env start` to install the WordPress instance before using any other commands. This is only necessary to set up the environment for the first time; it is typically not necessary for the instance to be running after that in order to use other commands.'
 		);
 		process.exit( 1 );
 	}
-
-	return config;
-};
+}
 
 /**
  * Generates the Dockerfile used by wp-env's `wordpress` and `tests-wordpress` instances.
@@ -377,3 +330,8 @@ RUN echo 'spx.http_ip_whitelist="*"' >> /usr/local/etc/php/php.ini
 RUN echo 'spx.data_dir="/tmp/spx"' >> /usr/local/etc/php/php.ini
 RUN mkdir -p /tmp/spx && chmod 777 /tmp/spx`;
 }
+
+module.exports = {
+	writeDockerFiles,
+	ensureDockerInitialized,
+};

package/lib/runtime/docker/index.js

@@ -16,7 +16,10 @@ const exec = util.promisify( require( 'child_process' ).exec );
 /**
  * Internal dependencies
  */
-const initConfig = require( './init-config' );
+const {
+	writeDockerFiles,
+	ensureDockerInitialized,
+} = require( './docker-config' );
 const getHostUser = require( './get-host-user' );
 const downloadSources = require( './download-sources' );
 const downloadWPPHPUnit = require( './download-wp-phpunit' );
@@ -94,23 +97,15 @@ class DockerRuntime {
 	 * @param {Object}   options         Start 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.debug   True if debug mode is enabled.
 	 * @return {Promise<Object>} Result object with message and siteUrl.
 	 */
-	async start( config, { spinner, update, xdebug, spx, debug } ) {
-		// Initialize Docker-specific files (docker-compose.yml, Dockerfiles)
-		const fullConfig = await initConfig( {
-			spinner,
-			debug,
-			xdebug,
-			spx,
-			writeChanges: true,
-			customConfigPath: config.customConfigPath,
-		} );
+	async start( config, { spinner, update } ) {
+		// Write Docker-specific files (docker-compose.yml, Dockerfiles).
+		// The config already has ports resolved and xdebug/spx set by start.js.
+		const fullConfig = await writeDockerFiles( config );
+		const debug = fullConfig.debug;
 
-		const testsEnabled = fullConfig.testsEnvironment !== false;
+		const testsEnabled = config.testsEnvironment !== false;
 
 		// Check if the hash of the config has changed. If so, run configuration.
 		const configHash = md5( fullConfig );
@@ -404,16 +399,12 @@ class DockerRuntime {
 	 * @param {boolean}  options.debug   True if debug mode is enabled.
 	 */
 	async stop( config, { spinner, debug } ) {
-		const { dockerComposeConfigPath } = await initConfig( {
-			spinner,
-			debug,
-			customConfigPath: config.customConfigPath,
-		} );
+		ensureDockerInitialized( config, spinner );
 
 		spinner.text = 'Stopping WordPress.';
 
 		await dockerCompose.down( {
-			config: dockerComposeConfigPath,
+			config: config.dockerComposeConfigPath,
 			log: debug,
 		} );
 
@@ -485,13 +476,9 @@ class DockerRuntime {
 	 * @param {boolean}  options.debug       True if debug mode is enabled.
 	 */
 	async clean( config, { environment, spinner, debug } ) {
-		const fullConfig = await initConfig( {
-			spinner,
-			debug,
-			customConfigPath: config.customConfigPath,
-		} );
+		ensureDockerInitialized( config, spinner );
 
-		const testsEnabled = fullConfig.testsEnvironment !== false;
+		const testsEnabled = config.testsEnvironment !== false;
 
 		if ( ! testsEnabled && environment === 'tests' ) {
 			throw new Error(
@@ -522,16 +509,14 @@ class DockerRuntime {
 		}
 
 		await dockerCompose.upMany( mysqlServices, {
-			config: fullConfig.dockerComposeConfigPath,
-			log: fullConfig.debug,
+			config: config.dockerComposeConfigPath,
+			log: debug,
 		} );
 
 		if ( environment === 'all' || environment === 'development' ) {
 			tasks.push(
-				resetDatabase( 'development', fullConfig )
-					.then( () =>
-						configureWordPress( 'development', fullConfig )
-					)
+				resetDatabase( 'development', config )
+					.then( () => configureWordPress( 'development', config ) )
 					.catch( () => {} )
 			);
 		}
@@ -541,8 +526,8 @@ class DockerRuntime {
 			( environment === 'all' || environment === 'tests' )
 		) {
 			tasks.push(
-				resetDatabase( 'tests', fullConfig )
-					.then( () => configureWordPress( 'tests', fullConfig ) )
+				resetDatabase( 'tests', config )
+					.then( () => configureWordPress( 'tests', config ) )
 					.catch( () => {} )
 			);
 		}
@@ -570,9 +555,8 @@ class DockerRuntime {
 	 * @param {string[]} options.command   The command to run.
 	 * @param {string}   options.envCwd    The working directory.
 	 * @param {Object}   options.spinner   A CLI spinner which indicates progress.
-	 * @param {boolean}  options.debug     True if debug mode is enabled.
 	 */
-	async run( config, { container, command, envCwd, spinner, debug } ) {
+	async run( config, { container, command, envCwd, spinner } ) {
 		// Validate the container name (throws for deprecated containers)
 		validateRunContainer( container );
 
@@ -585,22 +569,13 @@ class DockerRuntime {
 			);
 		}
 
-		const fullConfig = await initConfig( {
-			spinner,
-			debug,
-			customConfigPath: config.customConfigPath,
-		} );
+		ensureDockerInitialized( config, spinner );
 
 		// Shows a contextual tip for the given command.
 		const joinedCommand = command.join( ' ' );
 		this._showCommandTips( joinedCommand, container, spinner );
 
-		await this._spawnCommandDirectly(
-			fullConfig,
-			container,
-			command,
-			envCwd
-		);
+		await this._spawnCommandDirectly( config, container, command, envCwd );
 
 		spinner.text = `Ran \`${ joinedCommand }\` in '${ container }'.`;
 	}
@@ -613,16 +588,11 @@ class DockerRuntime {
 	 * @param {string}   options.environment The environment to show logs for.
 	 * @param {boolean}  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.
 	 */
-	async logs( config, { environment, watch, spinner, debug } ) {
-		const fullConfig = await initConfig( {
-			spinner,
-			debug,
-			customConfigPath: config.customConfigPath,
-		} );
+	async logs( config, { environment, watch, spinner } ) {
+		ensureDockerInitialized( config, spinner );
 
-		const testsEnabled = fullConfig.testsEnvironment !== false;
+		const testsEnabled = config.testsEnvironment !== false;
 
 		if ( ! testsEnabled && environment === 'tests' ) {
 			throw new Error(
@@ -651,7 +621,7 @@ class DockerRuntime {
 		const output = await Promise.all( [
 			...servicesToWatch.map( ( service ) =>
 				dockerCompose.logs( service, {
-					config: fullConfig.dockerComposeConfigPath,
+					config: config.dockerComposeConfigPath,
 					log: watch, // Must log inline if we are watching the log output.
 					commandOptions: watch ? [ '--follow' ] : [],
 				} )
@@ -703,18 +673,17 @@ class DockerRuntime {
 	async getStatus( config, { spinner, debug } ) {
 		spinner.text = 'Getting environment status.';
 
-		const fullConfig = await initConfig( {
-			spinner,
-			debug,
-			customConfigPath: config.customConfigPath,
-		} );
+		ensureDockerInitialized( config, spinner );
+
 		const dockerComposeConfig = {
-			config: fullConfig.dockerComposeConfigPath,
+			config: config.dockerComposeConfigPath,
 			log: debug,
 		};
 
 		// Check if containers are running by trying to get a port.
 		let isRunning = false;
+		let developmentPort = null;
+		let testsPort = null;
 		let mySQLPort = null;
 		let phpmyadminPort = null;
 
@@ -726,7 +695,19 @@ class DockerRuntime {
 			);
 			isRunning = true;
 
-			if ( fullConfig.env.development.phpmyadmin ) {
+			developmentPort = await this._getPublicDockerPort(
+				'wordpress',
+				80,
+				dockerComposeConfig
+			);
+
+			testsPort = await this._getPublicDockerPort(
+				'tests-wordpress',
+				80,
+				dockerComposeConfig
+			);
+
+			if ( config.env.development.phpmyadmin ) {
 				phpmyadminPort = await this._getPublicDockerPort(
 					'phpmyadmin',
 					80,
@@ -737,9 +718,9 @@ class DockerRuntime {
 			// Containers are not running.
 		}
 
-		const siteUrl = fullConfig.env.development.config.WP_SITEURL;
+		const siteUrl = config.env.development.config.WP_SITEURL;
 
-		const testsEnabled = fullConfig.testsEnvironment !== false;
+		const testsEnabled = config.testsEnvironment !== false;
 
 		return {
 			status: isRunning ? 'running' : 'stopped',
@@ -752,18 +733,18 @@ class DockerRuntime {
 						: null,
 			},
 			ports: {
-				development: fullConfig.env.development.port,
+				development: developmentPort,
 				...( testsEnabled && {
-					tests: fullConfig.env.tests.port,
+					tests: testsPort,
 				} ),
 				mysql: mySQLPort,
 			},
 			config: {
-				multisite: fullConfig.env.development.multisite,
-				xdebug: fullConfig.xdebug || 'off',
+				multisite: config.env.development.multisite,
+				xdebug: config.xdebug || 'off',
 			},
-			configPath: fullConfig.configDirectoryPath,
-			installPath: fullConfig.workDirectoryPath,
+			configPath: config.configDirectoryPath,
+			installPath: config.workDirectoryPath,
 		};
 	}
 

package/lib/runtime/playground/index.js

@@ -87,13 +87,11 @@ class PlaygroundRuntime {
 	/**
 	 * Start the WordPress Playground environment.
 	 *
-	 * @param {Object}  config          The wp-env config object.
-	 * @param {Object}  options         Start options.
-	 * @param {Object}  options.spinner A CLI spinner which indicates progress.
-	 * @param {boolean} options.debug   True if debug mode is enabled.
-	 * @param {string}  options.xdebug  The Xdebug mode to set.
+	 * @param {Object} config          The wp-env config object.
+	 * @param {Object} options         Start options.
+	 * @param {Object} options.spinner A CLI spinner which indicates progress.
 	 */
-	async start( config, { spinner, debug, xdebug } ) {
+	async start( config, { spinner } ) {
 		const envConfig = config.env.development;
 
 		spinner.text = 'Starting WordPress Playground.';
@@ -127,7 +125,7 @@ class PlaygroundRuntime {
 					downloadSource( source, {
 						onProgress: () => {}, // Progress tracking could be added
 						spinner,
-						debug,
+						debug: config.debug,
 					} )
 				)
 			);
@@ -148,7 +146,6 @@ class PlaygroundRuntime {
 		// Get mount arguments
 		const mountArgs = getMountArgs( config );
 
-		// Determine port
 		const port = envConfig.port || 8888;
 		const phpVersion = envConfig.phpVersion || '8.2';
 
@@ -166,7 +163,7 @@ class PlaygroundRuntime {
 			...mountArgs,
 		];
 
-		if ( debug ) {
+		if ( config.debug ) {
 			cliArgs.push( '--verbosity', 'debug' );
 		}
 
@@ -174,7 +171,7 @@ class PlaygroundRuntime {
 			cliArgs.push( '--phpmyadmin' );
 		}
 
-		if ( xdebug ) {
+		if ( config.xdebug && config.xdebug !== 'off' ) {
 			cliArgs.push( '--xdebug' );
 		}
 
@@ -425,17 +422,16 @@ class PlaygroundRuntime {
 	/**
 	 * Reset the WordPress database.
 	 *
-	 * @param {Object}  config          The wp-env config object.
-	 * @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.
+	 * @param {Object} config          The wp-env config object.
+	 * @param {Object} options         Reset options.
+	 * @param {Object} options.spinner A CLI spinner which indicates progress.
 	 */
-	async clean( config, { spinner, debug } ) {
+	async clean( config, { spinner } ) {
 		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 } );
+		await this.start( config, { spinner } );
 
 		spinner.text = 'Reset WordPress Playground environment.';
 	}

package/lib/test/cli.js

@@ -34,8 +34,21 @@ describe( 'env cli', () => {
 
 	it( 'parses start commands.', () => {
 		cli().parse( [ 'start' ] );
-		const { spinner } = env.start.mock.calls[ 0 ][ 0 ];
+		const { spinner, autoPort } = env.start.mock.calls[ 0 ][ 0 ];
 		expect( spinner.text ).toBe( '' );
+		expect( autoPort ).toBeUndefined();
+	} );
+
+	it( 'parses start commands with --auto-port.', () => {
+		cli().parse( [ 'start', '--auto-port' ] );
+		const { autoPort } = env.start.mock.calls[ 0 ][ 0 ];
+		expect( autoPort ).toBe( true );
+	} );
+
+	it( 'parses start commands with --no-auto-port.', () => {
+		cli().parse( [ 'start', '--no-auto-port' ] );
+		const { autoPort } = env.start.mock.calls[ 0 ][ 0 ];
+		expect( autoPort ).toBe( false );
 	} );
 
 	it( 'parses stop commands.', () => {