@wordpress/env 6.0.0 → 8.0.0

package/lib/cli.js

@@ -13,6 +13,10 @@ const { execSync } = require( 'child_process' );
  */
 const env = require( './env' );
 const parseXdebugMode = require( './parse-xdebug-mode' );
+const {
+	RUN_CONTAINERS,
+	validateRunContainer,
+} = require( './validate-run-container' );
 
 // Colors.
 const boldWhite = chalk.bold.white;
@@ -39,8 +43,11 @@ const withSpinner =
 				process.exit( 0 );
 			},
 			( error ) => {
-				if ( error instanceof env.ValidationError ) {
-					// Error is a validation error. That means the user did something wrong.
+				if (
+					error instanceof env.ValidationError ||
+					error instanceof env.LifecycleScriptError
+				) {
+					// Error is a configuration error. That means the user did something wrong.
 					spinner.fail( error.message );
 					process.exit( 1 );
 				} else if (
@@ -96,9 +103,12 @@ module.exports = function cli() {
 		default: false,
 	} );
 
-	// Make sure any unknown arguments are passed to the command as arguments.
-	// This allows options to be passed to "run" without being quoted.
-	yargs.parserConfiguration( { 'unknown-options-as-args': true } );
+	yargs.parserConfiguration( {
+		// Treats unknown options as arguments for commands to deal with instead of discarding them.
+		'unknown-options-as-args': true,
+		// Populates '--' in the command options with arguments after the double dash.
+		'populate--': true,
+	} );
 
 	yargs.command(
 		'start',
@@ -124,6 +134,11 @@ module.exports = function cli() {
 				coerce: parseXdebugMode,
 				type: 'string',
 			} );
+			args.option( 'scripts', {
+				type: 'boolean',
+				describe: 'Execute any configured lifecycle scripts.',
+				default: true,
+			} );
 		},
 		withSpinner( env.start )
 	);
@@ -145,6 +160,11 @@ module.exports = function cli() {
 				choices: [ 'all', 'development', 'tests' ],
 				default: 'tests',
 			} );
+			args.option( 'scripts', {
+				type: 'boolean',
+				describe: 'Execute any configured lifecycle scripts.',
+				default: true,
+			} );
 		},
 		withSpinner( env.clean )
 	);
@@ -171,8 +191,8 @@ module.exports = function cli() {
 		'Displays the latest logs for the e2e test environment without watching.'
 	);
 	yargs.command(
-		'run <container> [command..]',
-		'Runs an arbitrary command in one of the underlying Docker containers. The "container" param should reference one of the underlying Docker services like "development", "tests", or "cli". To run a wp-cli command, use the "cli" or "tests-cli" service. You can also use this command to open shell sessions like bash and the WordPress shell in the WordPress instance. For example, `wp-env run cli bash` will open bash in the development WordPress instance. When using long commands with arguments and quotation marks, you need to wrap the "command" param in quotation marks. For example: `wp-env run tests-cli "wp post create --post_type=page --post_title=\'Test\'"` will create a post on the tests WordPress instance.',
+		'run <container> [command...]',
+		'Runs an arbitrary command in one of the underlying Docker containers. A double dash can be used to pass arguments to the container without parsing them. This is necessary if you are using an option that is defined below. You can use `bash` to open a shell session and both `composer` and `phpunit` are available in all WordPress and CLI containers. WP-CLI is also available in the CLI containers.',
 		( args ) => {
 			args.option( 'env-cwd', {
 				type: 'string',
@@ -183,7 +203,10 @@ module.exports = function cli() {
 			} );
 			args.positional( 'container', {
 				type: 'string',
-				describe: 'The container to run the command on.',
+				describe:
+					'The underlying Docker service to run the command on.',
+				choices: RUN_CONTAINERS,
+				coerce: validateRunContainer,
 			} );
 			args.positional( 'command', {
 				type: 'array',
@@ -210,12 +233,18 @@ module.exports = function cli() {
 		wpRed(
 			'Destroy the WordPress environment. Deletes docker containers, volumes, and networks associated with the WordPress environment and removes local files.'
 		),
-		() => {},
+		( args ) => {
+			args.option( 'scripts', {
+				type: 'boolean',
+				describe: 'Execute any configured lifecycle scripts.',
+				default: true,
+			} );
+		},
 		withSpinner( env.destroy )
 	);
 	yargs.command(
 		'install-path',
-		'Get the path where environment files are located.',
+		'Get the path where all of the environment files are stored. This includes the Docker files, WordPress, PHPUnit files, and any sources that were downloaded.',
 		() => {},
 		withSpinner( env.installPath )
 	);

package/lib/commands/clean.js

@@ -1,3 +1,4 @@
+'use strict';
 /**
  * External dependencies
  */
@@ -8,6 +9,7 @@ const dockerCompose = require( 'docker-compose' );
  */
 const initConfig = require( '../init-config' );
 const { configureWordPress, resetDatabase } = require( '../wordpress' );
+const { executeLifecycleScript } = require( '../execute-lifecycle-script' );
 
 /**
  * @typedef {import('../wordpress').WPEnvironment} WPEnvironment
@@ -20,9 +22,15 @@ const { configureWordPress, resetDatabase } = require( '../wordpress' );
  * @param {Object}                 options
  * @param {WPEnvironmentSelection} options.environment The environment to clean. Either 'development', 'tests', or 'all'.
  * @param {Object}                 options.spinner     A CLI spinner which indicates progress.
+ * @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 clean( { environment, spinner, debug } ) {
+module.exports = async function clean( {
+	environment,
+	spinner,
+	scripts,
+	debug,
+} ) {
 	const config = await initConfig( { spinner, debug } );
 
 	const description = `${ environment } environment${
@@ -57,5 +65,9 @@ module.exports = async function clean( { environment, spinner, debug } ) {
 
 	await Promise.all( tasks );
 
+	if ( scripts ) {
+		await executeLifecycleScript( 'afterClean', config, spinner );
+	}
+
 	spinner.text = `Cleaned ${ description }.`;
 };

package/lib/commands/destroy.js

@@ -1,3 +1,4 @@
+'use strict';
 /**
  * External dependencies
  */
@@ -11,35 +12,33 @@ 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' );
+const { executeLifecycleScript } = require( '../execute-lifecycle-script' );
 
 /**
  * Destroy the development server.
  *
  * @param {Object}  options
  * @param {Object}  options.spinner A CLI spinner which indicates progress.
+ * @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 destroy( { spinner, debug } ) {
-	const configPath = path.resolve( '.wp-env.json' );
-	const { dockerComposeConfigPath, workDirectoryPath } = await readConfig(
-		configPath
-	);
+module.exports = async function destroy( { spinner, scripts, debug } ) {
+	const config = await loadConfig( path.resolve( '.' ) );
 
 	try {
-		await fs.readdir( workDirectoryPath );
+		await fs.readdir( config.workDirectoryPath );
 	} catch {
 		spinner.text = 'Could not find any files to remove.';
 		return;
 	}
 
 	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,24 @@ 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( {
-		config: dockerComposeConfigPath,
-		commandOptions: [ '--stop', '-v' ],
+	await dockerCompose.down( {
+		config: config.dockerComposeConfigPath,
+		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.';
-
-	await rimraf( workDirectoryPath );
+	// 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( config.workDirectoryPath );
+
+	if ( scripts ) {
+		await executeLifecycleScript( 'afterDestroy', config, spinner );
+	}
 
 	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,7 @@ const path = require( 'path' );
  * Internal dependencies
  */
 const initConfig = require( '../init-config' );
+const getHostUser = require( '../get-host-user' );
 
 /**
  * @typedef {import('../config').WPConfig} WPConfig
@@ -19,6 +21,7 @@ const initConfig = require( '../init-config' );
  * @param {Object}   options
  * @param {string}   options.container The Docker container to run the command on.
  * @param {string[]} options.command   The command to run.
+ * @param {string[]} options.'--'      Any arguments that were passed after a double dash.
  * @param {string}   options.envCwd    The working directory for the command to be executed from.
  * @param {Object}   options.spinner   A CLI spinner which indicates progress.
  * @param {boolean}  options.debug     True if debug mode is enabled.
@@ -26,20 +29,26 @@ const initConfig = require( '../init-config' );
 module.exports = async function run( {
 	container,
 	command,
+	'--': doubleDashedArgs,
 	envCwd,
 	spinner,
 	debug,
 } ) {
 	const config = await initConfig( { spinner, debug } );
 
-	command = command.join( ' ' );
+	// Include any double dashed arguments in the command so that we can pass them to Docker.
+	// This lets users pass options that the command defines without them being parsed.
+	if ( Array.isArray( doubleDashedArgs ) ) {
+		command.push( ...doubleDashedArgs );
+	}
 
 	// Shows a contextual tip for the given command.
-	showCommandTips( command, container, spinner );
+	const joinedCommand = command.join( ' ' );
+	showCommandTips( joinedCommand, container, spinner );
 
 	await spawnCommandDirectly( config, container, command, envCwd, spinner );
 
-	spinner.text = `Ran \`${ command }\` in '${ container }'.`;
+	spinner.text = `Ran \`${ joinedCommand }\` in '${ container }'.`;
 };
 
 /**
@@ -47,25 +56,43 @@ module.exports = async function run( {
  *
  * @param {WPConfig} config    The wp-env configuration.
  * @param {string}   container The Docker container to run the command on.
- * @param {string}   command   The command to run.
+ * @param {string[]} command   The command to run.
  * @param {string}   envCwd    The working directory for the command to be executed from.
  * @param {Object}   spinner   A CLI spinner which indicates progress.
  */
 function spawnCommandDirectly( config, container, command, envCwd, spinner ) {
-	// We need to pass absolute paths to the container.
-	envCwd = path.resolve( '/var/www/html', envCwd );
+	// 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();
+
+	// Since Docker requires absolute paths, we should resolve the input to a POSIX path.
+	// This is needed because Windows resolves relative paths from the C: drive.
+	envCwd = path.posix.resolve(
+		// Not all containers have the same starting working directory.
+		container === 'mysql' || container === 'tests-mysql'
+			? '/'
+			: '/var/www/html',
+		envCwd
+	);
 
 	const composeCommand = [
 		'-f',
 		config.dockerComposeConfigPath,
-		'run',
+		'exec',
 		'-w',
 		envCwd,
-		'--rm',
-		container,
-		...command.split( ' ' ), // The command will fail if passed as a complete string.
+		'--user',
+		hostUser.fullUser,
 	];
 
+	if ( ! process.stdout.isTTY ) {
+		composeCommand.push( '-T' );
+	}
+
+	composeCommand.push( container, ...command );
+
 	return new Promise( ( resolve, reject ) => {
 		// Note: since the npm docker-compose package uses the -T option, we
 		// cannot use it to spawn an interactive command. Thus, we run docker-
@@ -73,10 +100,7 @@ function spawnCommandDirectly( config, container, command, envCwd, spinner ) {
 		const childProc = spawn(
 			'docker-compose',
 			composeCommand,
-			{
-				stdio: 'inherit',
-				shell: true,
-			},
+			{ stdio: 'inherit' },
 			spinner
 		);
 		childProc.on( 'error', reject );
@@ -97,17 +121,17 @@ function spawnCommandDirectly( config, container, command, envCwd, spinner ) {
  * bash) may have weird behavior (exit with ctrl-d instead of ctrl-c or ctrl-z),
  * so we want the user to have that information without having to ask someone.
  *
- * @param {string} command   The command for which to show a tip.
- * @param {string} container The container the command will be run on.
- * @param {Object} spinner   A spinner object to show progress.
+ * @param {string} joinedCommand The command for which to show a tip joined by spaces.
+ * @param {string} container     The container the command will be run on.
+ * @param {Object} spinner       A spinner object to show progress.
  */
-function showCommandTips( command, container, spinner ) {
-	if ( ! command.length ) {
+function showCommandTips( joinedCommand, container, spinner ) {
+	if ( ! joinedCommand.length ) {
 		return;
 	}
 
-	const tip = `Starting '${ command }' on the ${ container } container. ${ ( () => {
-		switch ( command ) {
+	const tip = `Starting '${ joinedCommand }' on the ${ container } container. ${ ( () => {
+		switch ( joinedCommand ) {
 			case 'bash':
 				return 'Exit bash with ctrl-d.';
 			case 'wp shell':

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 { executeLifecycleScript } = require( '../execute-lifecycle-script' );
 
 /**
  * @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 ) {
@@ -192,6 +209,10 @@ module.exports = async function start( { spinner, debug, update, xdebug } ) {
 		} );
 	}
 
+	if ( scripts ) {
+		await executeLifecycleScript( 'afterStart', config, spinner );
+	}
+
 	const siteUrl = config.env.development.config.WP_SITEURL;
 	const testsSiteUrl = config.env.tests.config.WP_SITEURL;
 

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' );
+};