@wordpress/env 6.0.0 → 7.0.0

package/lib/commands/destroy.js

@@ -1,3 +1,4 @@
+'use strict';
 /**
  * External dependencies
  */
@@ -11,12 +12,11 @@ const inquirer = require( 'inquirer' );
  * Promisified dependencies
  */
 const rimraf = util.promisify( require( 'rimraf' ) );
-const exec = util.promisify( require( 'child_process' ).exec );
 
 /**
  * Internal dependencies
  */
-const { readConfig } = require( '../../lib/config' );
+const { loadConfig } = require( '../config' );
 
 /**
  * Destroy the development server.
@@ -26,9 +26,8 @@ const { readConfig } = require( '../../lib/config' );
  * @param {boolean} options.debug   True if debug mode is enabled.
  */
 module.exports = async function destroy( { spinner, debug } ) {
-	const configPath = path.resolve( '.wp-env.json' );
-	const { dockerComposeConfigPath, workDirectoryPath } = await readConfig(
-		configPath
+	const { dockerComposeConfigPath, workDirectoryPath } = await loadConfig(
+		path.resolve( '.' )
 	);
 
 	try {
@@ -39,7 +38,7 @@ module.exports = async function destroy( { spinner, debug } ) {
 	}
 
 	spinner.info(
-		'WARNING! This will remove Docker containers, volumes, and networks associated with the WordPress instance.'
+		'WARNING! This will remove Docker containers, volumes, networks, and images associated with the WordPress instance.'
 	);
 
 	const { yesDelete } = await inquirer.prompt( [
@@ -58,44 +57,20 @@ module.exports = async function destroy( { spinner, debug } ) {
 		return;
 	}
 
-	spinner.text = 'Removing WordPress docker containers.';
+	spinner.text = 'Removing docker images, volumes, and networks.';
 
-	await dockerCompose.rm( {
+	await dockerCompose.down( {
 		config: dockerComposeConfigPath,
-		commandOptions: [ '--stop', '-v' ],
+		commandOptions: [ '--volumes', '--remove-orphans', '--rmi', 'all' ],
 		log: debug,
 	} );
 
-	const directoryHash = path.basename( workDirectoryPath );
-
-	spinner.text = 'Removing docker volumes.';
-	await removeDockerItems( 'volume', directoryHash );
-
-	spinner.text = 'Removing docker networks.';
-	await removeDockerItems( 'network', directoryHash );
-
 	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.
+	await new Promise( ( resolve ) => setTimeout( resolve, 10000 ) );
 	await rimraf( workDirectoryPath );
 
 	spinner.text = 'Removed WordPress environment.';
 };
-
-/**
- * Removes docker items, like networks or volumes, matching the given name.
- *
- * @param {string} itemType The item type, like "network" or "volume"
- * @param {string} name     Remove items whose name match this string.
- */
-async function removeDockerItems( itemType, name ) {
-	const { stdout: items } = await exec(
-		`docker ${ itemType } ls -q --filter name=${ name }`
-	);
-	if ( items ) {
-		await exec(
-			`docker ${ itemType } rm ${ items
-				.split( '\n' ) // TODO: use os.EOL?
-				.join( ' ' ) }`
-		);
-	}
-}

package/lib/commands/index.js

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

package/lib/commands/install-path.js

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

package/lib/commands/logs.js

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

package/lib/commands/run.js

@@ -1,3 +1,4 @@
+'use strict';
 /**
  * External dependencies
  */
@@ -8,6 +9,8 @@ const path = require( 'path' );
  * Internal dependencies
  */
 const initConfig = require( '../init-config' );
+const getHostUser = require( '../get-host-user' );
+const { ValidationError } = require( '../config' );
 
 /**
  * @typedef {import('../config').WPConfig} WPConfig
@@ -30,6 +33,8 @@ module.exports = async function run( {
 	spinner,
 	debug,
 } ) {
+	validateContainerExistence( container );
+
 	const config = await initConfig( { spinner, debug } );
 
 	command = command.join( ' ' );
@@ -42,6 +47,42 @@ module.exports = async function run( {
 	spinner.text = `Ran \`${ command }\` in '${ container }'.`;
 };
 
+/**
+ * Validates the container option and throws if it is invalid.
+ *
+ * @param {string} container The Docker container to run the command on.
+ */
+function validateContainerExistence( container ) {
+	// Give better errors for containers that we have removed.
+	if ( container === 'phpunit' ) {
+		throw new ValidationError(
+			"The 'phpunit' container has been removed. Please use 'wp-env run tests-cli --env-cwd=wp-content/path/to/plugin phpunit' instead."
+		);
+	}
+	if ( container === 'composer' ) {
+		throw new ValidationError(
+			"The 'composer' container has been removed. Please use 'wp-env run cli --env-cwd=wp-content/path/to/plugin composer' instead."
+		);
+	}
+
+	// Provide better error output than Docker's "service does not exist" messaging.
+	const validContainers = [
+		'mysql',
+		'tests-mysql',
+		'wordpress',
+		'tests-wordpress',
+		'cli',
+		'tests-cli',
+	];
+	if ( ! validContainers.includes( container ) ) {
+		throw new ValidationError(
+			`The '${ container }' container does not exist. Valid selections are: ${ validContainers.join(
+				', '
+			) }`
+		);
+	}
+}
+
 /**
  * Runs an arbitrary command on the given Docker container.
  *
@@ -52,16 +93,31 @@ module.exports = async function run( {
  * @param {Object}   spinner   A CLI spinner which indicates progress.
  */
 function spawnCommandDirectly( config, container, command, envCwd, spinner ) {
+	// Both the `wordpress` and `tests-wordpress` containers have the host's
+	// user so that they can maintain ownership parity with the host OS.
+	// We should run any commands as that user so that they are able
+	// to interact with the files mounted from the host.
+	const hostUser = getHostUser();
+
 	// We need to pass absolute paths to the container.
-	envCwd = path.resolve( '/var/www/html', envCwd );
+	envCwd = path.resolve(
+		// Not all containers have the same starting working directory.
+		container === 'mysql' || container === 'tests-mysql'
+			? '/'
+			: '/var/www/html',
+		envCwd
+	);
 
+	const isTTY = process.stdout.isTTY;
 	const composeCommand = [
 		'-f',
 		config.dockerComposeConfigPath,
-		'run',
+		'exec',
+		! isTTY ? '-T' : '',
 		'-w',
 		envCwd,
-		'--rm',
+		'--user',
+		hostUser.fullUser,
 		container,
 		...command.split( ' ' ), // The command will fail if passed as a complete string.
 	];

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,

package/lib/commands/stop.js

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

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

@@ -1,3 +1,4 @@
+'use strict';
 /**
  * Internal dependencies
  */
@@ -6,9 +7,10 @@ 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 {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.
+ * @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 ) {
@@ -27,6 +29,13 @@ module.exports = function addOrReplacePort( input, port, replace = true ) {
 		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;
+}