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

package/README.md

@@ -363,7 +363,10 @@ Options:
              with a built-in web UI. See
              https://github.com/NoiseByNorthwest/php-spx for more information.
                                                                         [string]
-  --scripts  Execute any configured lifecycle scripts. [boolean] [default: true]
+  --scripts    Execute any configured lifecycle scripts.
+                                                      [boolean] [default: true]
+  --auto-port  Automatically find available ports when configured ports are
+               busy.                                  [boolean]
 ```
 
 ### `wp-env stop`
@@ -591,8 +594,10 @@ You can customize the WordPress installation, plugins and themes that the develo
 | `"phpVersion"`       | `string\|null` | `null`                                 | The PHP version to use. If `null` is specified, `wp-env` will use the default version used with production release of WordPress. |
 | `"plugins"`          | `string[]`     | `[]`                                   | A list of plugins to install and activate in the environment.                                                                    |
 | `"themes"`           | `string[]`     | `[]`                                   | A list of themes to install in the environment.                                                                                  |
-| `"port"`             | `integer`      | `8888`                                 | The primary port number to use for the installation. You'll access the instance through the port: 'http://localhost:8888'.       |
+| `"port"`             | `integer`      | `8888`                                 | The port number to use for the installation. |
 | `"testsEnvironment"` | `boolean`      | `false`                                | _Deprecated._ Whether to create a separate test environment with its own database and containers. Use `--config` with a separate config file instead. |
+| `"testsPort"`        | `integer`      | `8889`                                 | The port number for the test site. |
+| `"autoPort"`         | `boolean`      | `false`                                | Whether to automatically find available HTTP ports when configured ports are busy. |
 | `"config"`           | `Object`       | See below.                             | Mapping of wp-config.php constants to their desired values.                                                                      |
 | `"mappings"`         | `Object`       | `"{}"`                                 | Mapping of WordPress directories to local directories to be mounted in the WordPress instance.                                   |
 | `"mysqlPort"`        | `integer`      | `null` (randomly assigned)             | The MySQL port number to expose.                                                                                                 |
@@ -603,6 +608,18 @@ You can customize the WordPress installation, plugins and themes that the develo
 
 _Note: the port number environment variable (`WP_ENV_PORT`) takes precedence over the .wp-env.json value._
 
+### Automatic Port Selection
+
+By default, `wp-env` uses fixed ports (`8888` for development, `8889` for tests). If a port is busy, Docker will report an error at start time.
+
+To opt in to automatic port selection, pass the `--auto-port` flag:
+
+```sh
+wp-env start --auto-port
+```
+
+When `--auto-port` (or `"autoPort": true`) is enabled and a configured port is busy, `wp-env` scans upward from the configured port to find the next available one (for example: `8888`, `8889`, `8890`, ...). Automatic port selection is disabled when `CI` is set.
+
 Several types of strings can be passed into the `core`, `plugins`, `themes`, and `mappings` fields.
 
 | Type              | Format                                       | Example(s)                                                                                                                         |
@@ -785,7 +802,8 @@ You can tell `wp-env` to use a custom port number so that your instance does not
 
 These can also be set via environment variables:
 
-- `WP_ENV_PORT` to override the web server's port.
+- `WP_ENV_PORT` to override the development environment's web server's port.
+- `WP_ENV_TESTS_PORT` to override the testing environment's web server's port.
 - phpMyAdmin is not enabled by default. Enable it with `"phpmyadmin": true` in `.wp-env.json`. The Docker runtime port can also be overridden via `WP_ENV_PHPMYADMIN_PORT`.
 - By default, MySQL isn't exposed to the host, which means no chance of port conflicts. But this can also be overridden via `WP_ENV_MYSQL_PORT`.
 

package/lib/cli.js

@@ -151,6 +151,11 @@ module.exports = function cli() {
 				choices: getAvailableRuntimes(),
 				default: 'docker',
 			} );
+			args.option( 'auto-port', {
+				type: 'boolean',
+				describe:
+					'Automatically find available ports when configured ports are busy. Overrides the .wp-env.json "autoPort" setting.',
+			} );
 		},
 		withSpinner( env.start )
 	);

package/lib/commands/start.js

@@ -22,14 +22,15 @@ const { getRuntime, getSavedRuntime, saveRuntime } = 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 {string|null} options.config  Path to a custom .wp-env.json configuration file.
+ * @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 {boolean}     options.autoPort If true, automatically find available ports when configured ports are busy.
+ * @param {string|null} options.config   Path to a custom .wp-env.json configuration file.
  */
 module.exports = async function start( {
 	spinner,
@@ -39,6 +40,7 @@ module.exports = async function start( {
 	scripts,
 	debug,
 	runtime: runtimeName = 'docker',
+	autoPort,
 	config: customConfigPath,
 } ) {
 	spinner.text = 'Reading configuration.';
@@ -50,8 +52,14 @@ module.exports = async function start( {
 		await checkForLegacyInstall( spinner );
 	}
 
-	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath, {
+		resolvePorts: true,
+		autoPort,
+		spinner,
+	} );
 	config.debug = debug;
+	config.xdebug = xdebug;
+	config.spx = spx;
 
 	// Check if switching runtimes and prompt user to destroy old environment first.
 	const savedRuntime = await getSavedRuntime( config.workDirectoryPath );
@@ -109,9 +117,6 @@ module.exports = async function start( {
 		result = await runtime.start( config, {
 			spinner,
 			update,
-			xdebug,
-			spx,
-			debug,
 		} );
 
 		// Save the runtime type after successful start.

package/lib/config/load-config.js

@@ -13,6 +13,7 @@ const md5 = require( '../md5' );
 const { parseConfig, getConfigFilePath } = require( './parse-config' );
 const { ValidationError } = require( './validate-config' );
 const postProcessConfig = require( './post-process-config' );
+const { createPortResolver } = require( '../resolve-available-ports' );
 
 /**
  * @typedef {import('./parse-config').WPRootConfig} WPRootConfig
@@ -36,14 +37,19 @@ const postProcessConfig = require( './post-process-config' );
 /**
  * Loads any configuration from a given directory.
  *
- * @param {string}      configDirectoryPath The directory we want to load the config from.
- * @param {string|null} customConfigPath    Optional custom config file path.
+ * @param {string}      configDirectoryPath  The directory we want to load the config from.
+ * @param {string|null} customConfigPath     Optional custom config file path.
+ * @param {Object}      options              Options for loading the config.
+ * @param {boolean}     options.resolvePorts Whether HTTP ports should be resolved for this command.
+ * @param {boolean}     options.autoPort     CLI override for automatic port selection.
+ * @param {Object}      options.spinner      A CLI spinner used by the port resolver.
  *
  * @return {Promise<WPConfig>} The config object we've loaded.
  */
 module.exports = async function loadConfig(
 	configDirectoryPath,
-	customConfigPath = null
+	customConfigPath = null,
+	{ resolvePorts = false, autoPort, spinner } = {}
 ) {
 	const configFilePath = getConfigFilePath(
 		configDirectoryPath,
@@ -75,10 +81,25 @@ module.exports = async function loadConfig(
 		customConfigPath
 	);
 
+	let portResolver;
+	if ( resolvePorts ) {
+		let shouldAutoPort =
+			autoPort !== undefined ? autoPort : config.autoPort;
+
+		// Automatic port selection is undesirable in CI where determinism matters.
+		if ( process.env.CI ) {
+			shouldAutoPort = false;
+		}
+
+		if ( shouldAutoPort ) {
+			portResolver = createPortResolver( spinner );
+		}
+	}
+
 	// Make sure to perform any additional post-processing that
 	// may be needed before the config object is ready for
 	// consumption elsewhere in the tool.
-	config = postProcessConfig( config );
+	config = await postProcessConfig( config, { portResolver } );
 
 	return {
 		name: path.basename( configDirectoryPath ),

package/lib/config/parse-config.js

@@ -35,6 +35,7 @@ const mergeConfigs = require( './merge-configs' );
  * @typedef WPRootConfigOptions
  * @property {number}                               port                          The port to use in the development environment.
  * @property {number}                               testsPort                     The port to use in the tests environment.
+ * @property {boolean}                              autoPort                      Whether to automatically select a nearby available HTTP port.
  * @property {Object.<string, string|null>}         lifecycleScripts              The scripts to run at certain points in the command lifecycle.
  * @property {Object.<string, string|null>}         lifecycleScripts.afterStart   The script to run after the "start" command has completed.
  * @property {Object.<string, string|null>}         lifecycleScripts.afterClean   The script to run after the "clean" command has completed.
@@ -89,6 +90,7 @@ const DEFAULT_ENVIRONMENT_CONFIG = {
 	themes: [],
 	port: 8888,
 	testsPort: 8889,
+	autoPort: false,
 	mysqlPort: null,
 	phpmyadmin: false,
 	phpmyadminPort: null,
@@ -385,6 +387,14 @@ async function parseRootConfig( configFile, rawConfig, options ) {
 		checkPort( configFile, `testsPort`, rawConfig.testsPort );
 		parsedConfig.testsPort = rawConfig.testsPort;
 	}
+	if ( rawConfig.autoPort !== undefined ) {
+		if ( typeof rawConfig.autoPort !== 'boolean' ) {
+			throw new ValidationError(
+				`Invalid ${ configFile }: "autoPort" must be a boolean.`
+			);
+		}
+		parsedConfig.autoPort = rawConfig.autoPort;
+	}
 	if ( rawConfig.testsEnvironment !== undefined ) {
 		if ( typeof rawConfig.testsEnvironment !== 'boolean' ) {
 			throw new ValidationError(
@@ -470,6 +480,7 @@ async function parseEnvironmentConfig(
 		// configuration options that we will parse.
 		switch ( key ) {
 			case 'testsPort':
+			case 'autoPort':
 			case 'testsEnvironment':
 			case 'lifecycleScripts':
 			case 'env': {

package/lib/config/post-process-config.js

@@ -5,6 +5,7 @@
 const mergeConfigs = require( './merge-configs' );
 const addOrReplacePort = require( './add-or-replace-port' );
 const { ValidationError } = require( './validate-config' );
+const { resolveConfigPorts } = require( '../resolve-available-ports' );
 
 /**
  * @typedef {import('./parse-config').WPRootConfig} WPRootConfig
@@ -14,15 +15,27 @@ const { ValidationError } = require( './validate-config' );
 /**
  * Performs any additional post-processing on the config object.
  *
- * @param {WPEnvironmentConfig} config The config to process.
+ * @param {WPEnvironmentConfig} config               The config to process.
+ * @param {Object}              options              Options for post-processing.
+ * @param {Object}              options.portResolver An optional port resolver for automatic port selection.
  *
- * @return {WPEnvironmentConfig} The config after post-processing.
+ * @return {Promise<WPEnvironmentConfig>} The config after post-processing.
  */
-module.exports = function postProcessConfig( config ) {
+module.exports = async function postProcessConfig(
+	config,
+	{ portResolver } = {}
+) {
 	// Make sure that we're operating on a config object that has
 	// complete environment configs for convenience.
 	config = mergeRootToEnvironments( config );
 
+	// Resolve ports after merging (so environment ports are finalized)
+	// but before appending ports to URLs. This way appendPortToWPConfigs
+	// uses the resolved ports and we don't need to fix URLs afterward.
+	if ( portResolver ) {
+		config = await resolveConfigPorts( config, portResolver );
+	}
+
 	config = appendPortToWPConfigs( config );
 
 	validate( config );
@@ -66,6 +79,10 @@ function mergeRootToEnvironments( config ) {
 			delete config.testsPort;
 		}
 	}
+	if ( config.autoPort !== undefined ) {
+		removedRootOptions.autoPort = config.autoPort;
+		delete config.autoPort;
+	}
 	if ( config.lifecycleScripts !== undefined ) {
 		removedRootOptions.lifecycleScripts = config.lifecycleScripts;
 		delete config.lifecycleScripts;
@@ -117,7 +134,10 @@ function appendPortToWPConfigs( config ) {
 			continue;
 		}
 
-		if ( config.env[ env ].port === undefined ) {
+		if (
+			config.env[ env ].port === undefined ||
+			config.env[ env ].port === null
+		) {
 			continue;
 		}
 
@@ -157,10 +177,12 @@ function validatePortUniqueness( config ) {
 		if ( env === 'tests' && testsDisabled ) {
 			continue;
 		}
-		if ( config.env[ env ].port === undefined ) {
-			throw new ValidationError(
-				`The "${ env }" environment has an invalid port.`
-			);
+		if (
+			config.env[ env ].port === undefined ||
+			config.env[ env ].port === null
+		) {
+			// Null ports will be resolved later; skip validation.
+			continue;
 		}
 
 		environmentPorts[ env ] = config.env[ env ].port;

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

@@ -21,6 +21,7 @@ jest.mock( '../../wordpress', () => ( {
 const DEFAULT_CONFIG = {
 	port: 8888,
 	testsPort: 8889,
+	autoPort: false,
 	mysqlPort: null,
 	phpmyadmin: false,
 	phpmyadminPort: null,
@@ -192,6 +193,19 @@ describe( 'parseConfig', () => {
 		expect( parsed ).toEqual( expected );
 	} );
 
+	it( 'should accept autoPort as a boolean', async () => {
+		readRawConfigFile.mockImplementation( async ( configFile ) => {
+			if ( configFile === '/test/gutenberg/.wp-env.json' ) {
+				return {
+					autoPort: true,
+				};
+			}
+		} );
+
+		const parsed = await parseConfig( '/test/gutenberg', '/cache' );
+		expect( parsed.autoPort ).toEqual( true );
+	} );
+
 	it( 'should parse core, plugin, theme, and mapping sources', async () => {
 		readRawConfigFile.mockImplementation( async ( configFile ) => {
 			if ( configFile === '/test/gutenberg/.wp-env.json' ) {
@@ -377,6 +391,24 @@ describe( 'parseConfig', () => {
 		);
 	} );
 
+	it( 'throws for non-boolean autoPort', async () => {
+		readRawConfigFile.mockImplementation( async ( configFile ) => {
+			if ( configFile === '/test/gutenberg/.wp-env.json' ) {
+				return {
+					autoPort: 'true',
+				};
+			}
+		} );
+
+		await expect(
+			parseConfig( '/test/gutenberg', '/cache' )
+		).rejects.toEqual(
+			new ValidationError(
+				`Invalid /test/gutenberg/.wp-env.json: "autoPort" must be a boolean.`
+			)
+		);
+	} );
+
 	it( 'throws for root-only config options', async () => {
 		readRawConfigFile.mockImplementation( async ( configFile ) => {
 			if ( configFile === '/test/gutenberg/.wp-env.json' ) {
@@ -406,6 +438,42 @@ describe( 'parseConfig', () => {
 		);
 	} );
 
+	it( 'throws when port is null', async () => {
+		readRawConfigFile.mockImplementation( async ( configFile ) => {
+			if ( configFile === '/test/gutenberg/.wp-env.json' ) {
+				return {
+					port: null,
+				};
+			}
+		} );
+
+		await expect(
+			parseConfig( '/test/gutenberg', '/cache' )
+		).rejects.toEqual(
+			new ValidationError(
+				`Invalid /test/gutenberg/.wp-env.json: "port" must be an integer.`
+			)
+		);
+	} );
+
+	it( 'throws when testsPort is null', async () => {
+		readRawConfigFile.mockImplementation( async ( configFile ) => {
+			if ( configFile === '/test/gutenberg/.wp-env.json' ) {
+				return {
+					testsPort: null,
+				};
+			}
+		} );
+
+		await expect(
+			parseConfig( '/test/gutenberg', '/cache' )
+		).rejects.toEqual(
+			new ValidationError(
+				`Invalid /test/gutenberg/.wp-env.json: "testsPort" must be an integer.`
+			)
+		);
+	} );
+
 	it( 'should parse phpmyadmin configuration for a given environment', async () => {
 		readRawConfigFile.mockImplementation( async ( configFile ) => {
 			if ( configFile === '/test/gutenberg/.wp-env.json' ) {

package/lib/config/test/post-process-config.js

@@ -10,8 +10,8 @@ describe( 'postProcessConfig', () => {
 		jest.clearAllMocks();
 	} );
 
-	it( 'should merge relevant root options into environment options', () => {
-		const processed = postProcessConfig( {
+	it( 'should merge relevant root options into environment options', async () => {
+		const processed = await postProcessConfig( {
 			port: 123,
 			testsPort: 456,
 			coreSource: {
@@ -152,8 +152,8 @@ describe( 'postProcessConfig', () => {
 		} );
 	} );
 
-	it( 'should not merge some root options into environment options', () => {
-		const processed = postProcessConfig( {
+	it( 'should not merge some root options into environment options', async () => {
+		const processed = await postProcessConfig( {
 			port: 8888,
 			testsPort: 8889,
 			lifecycleScripts: {
@@ -183,8 +183,8 @@ describe( 'postProcessConfig', () => {
 	} );
 
 	describe( 'appendPortToWPConfigs', () => {
-		it( 'should add port to certain environment config options', () => {
-			const processed = postProcessConfig( {
+		it( 'should add port to certain environment config options', async () => {
+			const processed = await postProcessConfig( {
 				port: 123,
 				config: {
 					WP_TESTS_DOMAIN: 'localhost',
@@ -231,8 +231,8 @@ describe( 'postProcessConfig', () => {
 			} );
 		} );
 
-		it( 'should not overwrite port in WP_HOME', () => {
-			const processed = postProcessConfig( {
+		it( 'should not overwrite port in WP_HOME', async () => {
+			const processed = await postProcessConfig( {
 				env: {
 					development: {
 						port: 123,
@@ -274,11 +274,35 @@ describe( 'postProcessConfig', () => {
 				},
 			} );
 		} );
+
+		it( 'should not append port to URLs when port is null', async () => {
+			const processed = await postProcessConfig( {
+				port: null,
+				testsPort: null,
+				config: {
+					WP_TESTS_DOMAIN: 'localhost',
+					WP_SITEURL: 'http://localhost',
+					WP_HOME: 'http://localhost',
+				},
+				env: {
+					development: {},
+					tests: {},
+				},
+			} );
+
+			// Null ports should not be appended to URLs.
+			expect( processed.env.development.config.WP_SITEURL ).toEqual(
+				'http://localhost'
+			);
+			expect( processed.env.tests.config.WP_SITEURL ).toEqual(
+				'http://localhost'
+			);
+		} );
 	} );
 
 	describe( 'validatePortUniqueness', () => {
-		it( 'should fail when two environments have the same port', () => {
-			expect( () => {
+		it( 'should fail when two environments have the same port', async () => {
+			await expect(
 				postProcessConfig( {
 					env: {
 						development: {
@@ -288,16 +312,16 @@ describe( 'postProcessConfig', () => {
 							port: 123,
 						},
 					},
-				} );
-			} ).toThrow(
+				} )
+			).rejects.toThrow(
 				new ValidationError(
 					'The "development" and "tests" environments may not have the same port.'
 				)
 			);
 		} );
 
-		it( 'should skip port validation for disabled tests environment', () => {
-			expect( () => {
+		it( 'should skip port validation for disabled tests environment', async () => {
+			await expect(
 				postProcessConfig( {
 					testsEnvironment: false,
 					port: 123,
@@ -305,14 +329,28 @@ describe( 'postProcessConfig', () => {
 						development: {},
 						tests: {},
 					},
-				} );
-			} ).not.toThrow();
+				} )
+			).resolves.toBeDefined();
+		} );
+
+		it( 'should not fail when both environments have null ports', async () => {
+			const processed = await postProcessConfig( {
+				port: null,
+				testsPort: null,
+				env: {
+					development: {},
+					tests: {},
+				},
+			} );
+
+			expect( processed.env.development.port ).toEqual( null );
+			expect( processed.env.tests.port ).toEqual( null );
 		} );
 	} );
 
 	describe( 'testsEnvironment', () => {
-		it( 'should ignore env overrides entirely when testsEnvironment is false', () => {
-			const processed = postProcessConfig( {
+		it( 'should ignore env overrides entirely when testsEnvironment is false', async () => {
+			const processed = await postProcessConfig( {
 				testsEnvironment: false,
 				port: 123,
 				testsPort: 456,

package/lib/port-utils.js

@@ -0,0 +1,87 @@
+'use strict';
+/**
+ * External dependencies
+ */
+const net = require( 'net' );
+
+const DEFAULT_MIN_PORT = 49152;
+const DEFAULT_MAX_PORT = 65535;
+
+/**
+ * Checks if a port is available for use.
+ *
+ * @param {number} port The port to check.
+ * @return {Promise<boolean>} True if the port is available, false otherwise.
+ */
+async function isPortAvailable( port ) {
+	return new Promise( ( resolve ) => {
+		const server = net.createServer();
+
+		server.once( 'error', ( err ) => {
+			if ( err.code === 'EADDRINUSE' || err.code === 'EACCES' ) {
+				resolve( false );
+			} else {
+				// For other errors, assume port is not available
+				resolve( false );
+			}
+		} );
+
+		server.once( 'listening', () => {
+			server.close( () => {
+				resolve( true );
+			} );
+		} );
+
+		server.listen( port, '0.0.0.0' );
+	} );
+}
+
+/**
+ * Finds an available port, starting with the preferred port.
+ * Falls back to scanning upward from the preferred port.
+ *
+ * @param {Object}   options               Options for finding a port.
+ * @param {number}   options.preferredPort The preferred port to try first.
+ * @param {number}   options.minPort       Minimum port for fallback scanning.
+ * @param {number}   options.maxPort       Maximum port for fallback scanning.
+ * @param {number[]} options.exclude       Ports to exclude from selection.
+ * @return {Promise<number>} An available port number.
+ * @throws {Error} If no available port is found within the range.
+ */
+async function findAvailablePort( {
+	preferredPort,
+	minPort = preferredPort,
+	maxPort = DEFAULT_MAX_PORT,
+	exclude = [],
+} ) {
+	// Try the preferred port first if it's not excluded
+	if ( ! exclude.includes( preferredPort ) ) {
+		const isAvailable = await isPortAvailable( preferredPort );
+		if ( isAvailable ) {
+			return preferredPort;
+		}
+	}
+
+	// If preferred port is not available, scan upward from the selected minimum.
+	const startPort = Math.max( minPort, preferredPort + 1 );
+	for ( let port = startPort; port <= maxPort; port++ ) {
+		if ( exclude.includes( port ) ) {
+			continue;
+		}
+		const isAvailable = await isPortAvailable( port );
+		if ( isAvailable ) {
+			return port;
+		}
+	}
+
+	throw new Error(
+		`No available port found in range ${ startPort }-${ maxPort }.`
+	);
+}
+
+module.exports = {
+	isPortAvailable,
+	findAvailablePort,
+	DEFAULT_MIN_PORT,
+	DEFAULT_MAX_PORT,
+};