@wordpress/env 5.16.0 → 7.0.0

package/lib/commands/start.js

@@ -1,3 +1,4 @@
+'use strict';
 /**
  * External dependencies
  */
@@ -30,6 +31,7 @@ const {
 } = require( '../wordpress' );
 const { didCacheChange, setCache } = require( '../cache' );
 const md5 = require( '../md5' );
+const { executeAfterSetup } = require( '../execute-after-setup' );
 
 /**
  * @typedef {import('../config').WPConfig} WPConfig
@@ -41,11 +43,18 @@ const CONFIG_CACHE_KEY = 'config_checksum';
  *
  * @param {Object}  options
  * @param {Object}  options.spinner A CLI spinner which indicates progress.
- * @param {boolean} options.debug   True if debug mode is enabled.
  * @param {boolean} options.update  If true, update sources.
  * @param {string}  options.xdebug  The Xdebug 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.
  */
-module.exports = async function start( { spinner, debug, update, xdebug } ) {
+module.exports = async function start( {
+	spinner,
+	update,
+	xdebug,
+	scripts,
+	debug,
+} ) {
 	spinner.text = 'Reading configuration.';
 	await checkForLegacyInstall( spinner );
 
@@ -152,12 +161,20 @@ module.exports = async function start( { spinner, debug, update, xdebug } ) {
 
 	spinner.text = 'Starting WordPress.';
 
-	await dockerCompose.upMany( [ 'wordpress', 'tests-wordpress' ], {
-		...dockerComposeConfig,
-		commandOptions: shouldConfigureWp
-			? [ '--build', '--force-recreate' ]
-			: [],
-	} );
+	await dockerCompose.upMany(
+		[ 'wordpress', 'tests-wordpress', 'cli', 'tests-cli' ],
+		{
+			...dockerComposeConfig,
+			commandOptions: shouldConfigureWp
+				? [ '--build', '--force-recreate' ]
+				: [],
+		}
+	);
+
+	// Make sure we've consumed the custom CLI dockerfile.
+	if ( shouldConfigureWp ) {
+		await dockerCompose.buildOne( [ 'cli' ], { ...dockerComposeConfig } );
+	}
 
 	// Only run WordPress install/configuration when config has changed.
 	if ( shouldConfigureWp ) {
@@ -186,6 +203,11 @@ module.exports = async function start( { spinner, debug, update, xdebug } ) {
 			} ),
 		] );
 
+		// Execute any configured command that should run after the environment has finished being set up.
+		if ( scripts ) {
+			executeAfterSetup( config, spinner );
+		}
+
 		// Set the cache key once everything has been configured.
 		await setCache( CONFIG_CACHE_KEY, configHash, {
 			workDirectoryPath,
@@ -193,7 +215,7 @@ module.exports = async function start( { spinner, debug, update, xdebug } ) {
 	}
 
 	const siteUrl = config.env.development.config.WP_SITEURL;
-	const e2eSiteUrl = `http://${ config.env.tests.config.WP_TESTS_DOMAIN }:${ config.env.tests.port }/`;
+	const testsSiteUrl = config.env.tests.config.WP_SITEURL;
 
 	const { out: mySQLAddress } = await dockerCompose.port(
 		'mysql',
@@ -213,7 +235,7 @@ module.exports = async function start( { spinner, debug, update, xdebug } ) {
 		.concat( siteUrl ? ` at ${ siteUrl }` : '.' )
 		.concat( '\n' )
 		.concat( 'WordPress test site started' )
-		.concat( e2eSiteUrl ? ` at ${ e2eSiteUrl }` : '.' )
+		.concat( testsSiteUrl ? ` at ${ testsSiteUrl }` : '.' )
 		.concat( '\n' )
 		.concat( `MySQL is listening on port ${ mySQLPort }` )
 		.concat(

package/lib/commands/stop.js

@@ -1,3 +1,4 @@
+'use strict';
 /**
  * External dependencies
  */

package/lib/config/add-or-replace-port.js

@@ -0,0 +1,41 @@
+'use strict';
+/**
+ * Internal dependencies
+ */
+const { ValidationError } = require( './validate-config' );
+
+/**
+ * Adds or replaces the port to the given domain or URI.
+ *
+ * @param {string}        input     The domain or URI to operate on.
+ * @param {number|string} port      The port to append.
+ * @param {boolean}       [replace] Indicates whether or not the port should be replaced if one is already present. Defaults to true.
+ *
+ * @return {string} The string with the port added or replaced.
+ */
+module.exports = function addOrReplacePort( input, port, replace = true ) {
+	// This matches both domains and URIs with an optional port and anything
+	// that remains after. We can use this to build an output string that
+	// adds or replaces the port without making any other changes to the input.
+	const matches = input.match(
+		/^((?:.+:\/\/)?[a-z0-9.\-]+)(?::([0-9]+))?(.*)$/i
+	);
+	if ( ! matches ) {
+		throw new ValidationError( `Invalid domain or uri: ${ input }.` );
+	}
+
+	// When a port is already present we will do nothing if the caller doesn't want it to be replaced.
+	if ( matches[ 2 ] !== undefined && ! replace ) {
+		return input;
+	}
+
+	// There's never a reason to add the default ports.
+	// We use == to catch both string and number ports.
+	// eslint-disable-next-line eqeqeq
+	if ( port == 80 || port == 443 ) {
+		return input;
+	}
+
+	// Place the port in the correct location in the input.
+	return matches[ 1 ] + ':' + port + matches[ 3 ];
+};

package/lib/config/db-env.js

@@ -1,3 +1,4 @@
+'use strict';
 // Username and password used in all databases.
 const credentials = {
 	WORDPRESS_DB_USER: 'root',

package/lib/config/detect-directory-type.js

@@ -18,7 +18,7 @@ const finished = util.promisify( stream.finished );
  * Detects whether the given directory is a WordPress installation, a plugin or a theme.
  *
  * @param {string} directoryPath The directory to detect.
- * @return {string|null} 'core' if the directory is a WordPress installation, 'plugin' if it is a plugin, 'theme' if it is a theme, or null if we can't tell.
+ * @return {Promise<string|null>} 'core' if the directory is a WordPress installation, 'plugin' if it is a plugin, 'theme' if it is a theme, or null if we can't tell.
  */
 module.exports = async function detectDirectoryType( directoryPath ) {
 	// If we have a `wp-includes/version.php` file, then this is a Core install.

package/lib/config/get-cache-directory.js

@@ -0,0 +1,39 @@
+'use strict';
+/**
+ * External dependencies
+ */
+const path = require( 'path' );
+const fs = require( 'fs' ).promises;
+const os = require( 'os' );
+
+/**
+ * Gets the directory in which generated files are created.
+ *
+ * By default: '~/.wp-env/'. On Linux with snap packages: '~/wp-env/'. Can be
+ * overridden with the WP_ENV_HOME environment variable.
+ *
+ * @return {Promise<string>} The absolute path to the `wp-env` home directory.
+ */
+module.exports = async function getCacheDirectory() {
+	// Allow user to override download location.
+	if ( process.env.WP_ENV_HOME ) {
+		return path.resolve( process.env.WP_ENV_HOME );
+	}
+
+	/**
+	 * Installing docker with Snap Packages on Linux is common, but does not
+	 * support hidden directories. Therefore we use a public directory when
+	 * snap packages exist.
+	 *
+	 * @see https://github.com/WordPress/gutenberg/issues/20180#issuecomment-587046325
+	 */
+	let usesSnap;
+	try {
+		await fs.stat( '/snap' );
+		usesSnap = true;
+	} catch {
+		usesSnap = false;
+	}
+
+	return path.resolve( os.homedir(), usesSnap ? 'wp-env' : '.wp-env' );
+};

package/lib/config/get-config-from-environment-vars.js

@@ -0,0 +1,86 @@
+'use strict';
+/**
+ * Internal dependencies
+ */
+const {
+	parseSourceString,
+	includeTestsPath,
+} = require( './parse-source-string' );
+const { checkPort, checkVersion, checkString } = require( './validate-config' );
+
+/**
+ * @typedef {import('./parse-source-string').WPSource} WPSource
+ */
+
+/**
+ * Environment variable configuration.
+ *
+ * @typedef WPEnvironmentVariableConfig
+ * @property {?number}   port       An override for the development environment's port.
+ * @property {?number}   testsPort  An override for the testing environment's port.
+ * @property {?WPSource} coreSource An override for all environment's coreSource.
+ * @property {?string}   phpVersion An override for all environment's PHP version.
+ */
+
+/**
+ * Gets configuration options from environment variables.
+ *
+ * @param {string} cacheDirectoryPath Path to the work directory located in ~/.wp-env.
+ *
+ * @return {WPEnvironmentVariableConfig} Any configuration options parsed from the environment variables.
+ */
+module.exports = function getConfigFromEnvironmentVars( cacheDirectoryPath ) {
+	const environmentConfig = {
+		port: getPortFromEnvironmentVariable( 'WP_ENV_PORT' ),
+		testsPort: getPortFromEnvironmentVariable( 'WP_ENV_TESTS_PORT' ),
+	};
+
+	if ( process.env.WP_ENV_CORE ) {
+		environmentConfig.coreSource = includeTestsPath(
+			parseSourceString( process.env.WP_ENV_CORE, {
+				cacheDirectoryPath,
+			} ),
+			{ cacheDirectoryPath }
+		);
+	}
+
+	if ( process.env.WP_ENV_PHP_VERSION ) {
+		checkVersion(
+			'environment variable',
+			'WP_ENV_PHP_VERSION',
+			process.env.WP_ENV_PHP_VERSION
+		);
+		environmentConfig.phpVersion = process.env.WP_ENV_PHP_VERSION;
+	}
+
+	if ( process.env.WP_ENV_AFTER_SETUP ) {
+		checkString(
+			'environment variable',
+			'WP_ENV_AFTER_SETUP',
+			process.env.WP_ENV_AFTER_SETUP
+		);
+		environmentConfig.afterSetup = process.env.WP_ENV_AFTER_SETUP;
+	}
+
+	return environmentConfig;
+};
+
+/**
+ * Parses an environment variable which should be a port.
+ *
+ * @param {string} varName The environment variable to check (e.g. WP_ENV_PORT).
+ *
+ * @return {number} The parsed port number
+ */
+function getPortFromEnvironmentVariable( varName ) {
+	if ( ! process.env[ varName ] ) {
+		return undefined;
+	}
+
+	const port = parseInt( process.env[ varName ] );
+
+	// Throw an error if it is not parseable as a number.
+	checkPort( 'environment variable', varName, port );
+
+	return port;
+}

package/lib/config/index.js

@@ -1,18 +1,20 @@
+'use strict';
 /**
  * Internal dependencies
  */
-const readConfig = require( './config' );
+const loadConfig = require( './load-config' );
 const { ValidationError } = require( './validate-config' );
 const dbEnv = require( './db-env' );
 
 /**
- * @typedef {import('./config').WPConfig} WPConfig
- * @typedef {import('./config').WPServiceConfig} WPServiceConfig
- * @typedef {import('./config').WPSource} WPSource
+ * @typedef {import('./load-config').WPConfig} WPConfig
+ * @typedef {import('./parse-config').WPRootConfig} WPRootConfig
+ * @typedef {import('./parse-config').WPEnvironmentConfig} WPEnvironmentConfig
+ * @typedef {import('./parse-source-string').WPSource} WPSource
  */
 
 module.exports = {
 	ValidationError,
-	readConfig,
+	loadConfig,
 	dbEnv,
 };

package/lib/config/load-config.js

@@ -0,0 +1,92 @@
+'use strict';
+/**
+ * External dependencies
+ */
+const path = require( 'path' );
+const fs = require( 'fs' ).promises;
+
+/**
+ * Internal dependencies
+ */
+const getCacheDirectory = require( './get-cache-directory' );
+const md5 = require( '../md5' );
+const { parseConfig, getConfigFilePath } = require( './parse-config' );
+const postProcessConfig = require( './post-process-config' );
+
+/**
+ * @typedef {import('./parse-config').WPRootConfig} WPRootConfig
+ * @typedef {import('./parse-config').WPEnvironmentConfig} WPEnvironmentConfig
+ */
+
+/**
+ * wp-env configuration.
+ *
+ * @typedef WPConfig
+ * @property {string}                               name                    Name of the environment.
+ * @property {string}                               configDirectoryPath     Path to the .wp-env.json file.
+ * @property {string}                               workDirectoryPath       Path to the work directory located in ~/.wp-env.
+ * @property {string}                               dockerComposeConfigPath Path to the docker-compose.yml file.
+ * @property {boolean}                              detectedLocalConfig     If true, wp-env detected local config and used it.
+ * @property {string}                               afterSetup              The command(s) to run after configuring WordPress on start and clean.
+ * @property {Object.<string, WPEnvironmentConfig>} env                     Specific config for different environments.
+ * @property {boolean}                              debug                   True if debug mode is enabled.
+ */
+
+/**
+ * Loads any configuration from a given directory.
+ *
+ * @param {string} configDirectoryPath The directory we want to load the config from.
+ *
+ * @return {WPConfig} The config object we've loaded.
+ */
+module.exports = async function loadConfig( configDirectoryPath ) {
+	const configFilePath = getConfigFilePath( configDirectoryPath );
+
+	const cacheDirectoryPath = path.resolve(
+		await getCacheDirectory(),
+		md5( configFilePath )
+	);
+
+	// Parse any configuration we found in the given directory.
+	// This comes merged and prepared for internal consumption.
+	let config = await parseConfig( configDirectoryPath, cacheDirectoryPath );
+
+	// 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 );
+
+	return {
+		name: path.basename( configDirectoryPath ),
+		dockerComposeConfigPath: path.resolve(
+			cacheDirectoryPath,
+			'docker-compose.yml'
+		),
+		configDirectoryPath,
+		workDirectoryPath: cacheDirectoryPath,
+		detectedLocalConfig: await hasLocalConfig( [
+			configFilePath,
+			getConfigFilePath( configDirectoryPath, 'override' ),
+		] ),
+		afterSetup: config.afterSetup,
+		env: config.env,
+	};
+};
+
+/**
+ * Checks to see whether or not there is any configuration present in the directory.
+ *
+ * @param {string[]} configFilePaths The config files we want to check for existence.
+ *
+ * @return {Promise<boolean>} A promise indicating whether or not a local config is present.
+ */
+async function hasLocalConfig( configFilePaths ) {
+	for ( const filePath of configFilePaths ) {
+		try {
+			await fs.stat( filePath );
+			return true;
+		} catch {}
+	}
+
+	return false;
+}

package/lib/config/merge-configs.js

@@ -0,0 +1,104 @@
+'use strict';
+/**
+ * @typedef {import('./parse-config').WPEnvironmentConfig} WPEnvironmentConfig
+ */
+
+/**
+ * Deep-merges the values in the given service environment. This allows us to
+ * merge the wp-config.php values instead of overwriting them.
+ *
+ * @param {WPEnvironmentConfig} defaultConfig The default config options.
+ * @param {...string}           configs       The config options to merge.
+ *
+ * @return {WPEnvironmentConfig} The merged config object.
+ */
+module.exports = function mergeConfigs( defaultConfig, ...configs ) {
+	// Start with our default config object. This has all
+	// of the options filled out already and we can use
+	// that to make performing the merge easier.
+	let config = defaultConfig;
+
+	// Merge the configs
+	for ( const merge of configs ) {
+		config = mergeConfig( config, merge );
+	}
+
+	return config;
+};
+
+/**
+ * Merges a config object into another.
+ *
+ * @param {WPEnvironmentConfig} config  The config object to be merged into.
+ * @param {WPEnvironmentConfig} toMerge The config object to merge.
+ *
+ * @return {WPEnvironmentConfig} The merged config object.
+ */
+function mergeConfig( config, toMerge ) {
+	// Begin by updating any of the config options that the object already has.
+	for ( const option in config ) {
+		// We don't need to do anything if the merge source doesn't have a property to give.
+		if ( toMerge[ option ] === undefined ) {
+			continue;
+		}
+
+		switch ( option ) {
+			// Some config options are merged together instead of entirely replaced.
+			case 'config':
+			case 'mappings': {
+				config[ option ] = Object.assign(
+					config[ option ],
+					toMerge[ option ]
+				);
+				break;
+			}
+
+			// Environment-specific config options are recursively merged.
+			case 'env': {
+				for ( const environment in config.env ) {
+					// Once again, we don't need to do anything if the merge source has nothing to give.
+					if ( toMerge.env[ environment ] === undefined ) {
+						continue;
+					}
+
+					config.env[ environment ] = mergeConfig(
+						config.env[ environment ],
+						toMerge.env[ environment ]
+					);
+				}
+				break;
+			}
+
+			default: {
+				config[ option ] = toMerge[ option ];
+				break;
+			}
+		}
+	}
+
+	// Next, add any new options that the config object doesn't already have.
+	for ( const option in toMerge ) {
+		// Environment-specific config options should be checked individually.
+		if ( option === 'env' ) {
+			for ( const environment in toMerge.env ) {
+				// The presence of the environment means it would have been merged above.
+				if ( config.env[ environment ] !== undefined ) {
+					continue;
+				}
+
+				config.env[ environment ] = toMerge[ environment ];
+			}
+
+			continue;
+		}
+
+		// As above, the presence of the option means it would have been merged above.
+		if ( config[ option ] !== undefined ) {
+			continue;
+		}
+
+		config[ option ] = toMerge[ option ];
+	}
+
+	return config;
+}