@wordpress/env 5.16.0 → 7.0.0

package/lib/config/validate-config.js

@@ -1,8 +1,7 @@
 'use strict';
 
 /**
- * @typedef {import('./config').WPServiceConfig} WPServiceConfig
- * @typedef {import('./config').WPSource} WPSource
+ * @typedef {import('./parse-source-string').WPSource} WPSource
  */
 
 /**
@@ -12,81 +11,145 @@
 class ValidationError extends Error {}
 
 /**
- * Validates a config object by throwing a ValidationError if any of its properties
- * do not match the required format.
+ * Validates that the value is a string.
  *
- * @param {Object}  config      A config object to validate.
- * @param {?string} envLocation Identifies if the error occurred in a specific environment property.
- * @return {Object} The passed config object with no modifications.
+ * @param {string} configFile The configuration file we're validating.
+ * @param {string} configKey  The configuration key we're validating.
+ * @param {number} value      The value to check.
  */
-function validateConfig( config, envLocation ) {
-	const envPrefix = envLocation ? `env.${ envLocation }.` : '';
-	if ( config.core !== null && typeof config.core !== 'string' ) {
+function checkString( configFile, configKey, value ) {
+	if ( typeof value !== 'string' ) {
 		throw new ValidationError(
-			`Invalid .wp-env.json: "${ envPrefix }core" must be null or a string.`
+			`Invalid ${ configFile }: "${ configKey }" must be a string.`
 		);
 	}
+}
 
-	if (
-		! Array.isArray( config.plugins ) ||
-		config.plugins.some( ( plugin ) => typeof plugin !== 'string' )
-	) {
+/**
+ * Validates the port and throws if it isn't valid.
+ *
+ * @param {string} configFile The configuration file we're validating.
+ * @param {string} configKey  The configuration key we're validating.
+ * @param {number} port       The port to check.
+ */
+function checkPort( configFile, configKey, port ) {
+	if ( ! Number.isInteger( port ) ) {
 		throw new ValidationError(
-			`Invalid .wp-env.json: "${ envPrefix }plugins" must be an array of strings.`
+			`Invalid ${ configFile }: "${ configKey }" must be an integer.`
 		);
 	}
 
-	if (
-		! Array.isArray( config.themes ) ||
-		config.themes.some( ( theme ) => typeof theme !== 'string' )
-	) {
+	if ( port < 0 || port > 65535 ) {
 		throw new ValidationError(
-			`Invalid .wp-env.json: "${ envPrefix }themes" must be an array of strings.`
+			`Invalid ${ configFile }: "${ configKey }" must be a valid port.`
 		);
 	}
+}
 
-	if ( ! Number.isInteger( config.port ) ) {
+/**
+ * Validates the array and throws if it isn't valid.
+ *
+ * @param {string}   configFile The config file we're validating.
+ * @param {string}   configKey  The configuration key we're validating.
+ * @param {string[]} array      The array that we're checking.
+ */
+function checkStringArray( configFile, configKey, array ) {
+	if ( ! Array.isArray( array ) ) {
 		throw new ValidationError(
-			`Invalid .wp-env.json: "${ envPrefix }port" must be an integer.`
+			`Invalid ${ configFile }: "${ configKey }" must be an array.`
 		);
 	}
 
-	if ( typeof config.config !== 'object' ) {
+	if ( array.some( ( value ) => typeof value !== 'string' ) ) {
 		throw new ValidationError(
-			`Invalid .wp-env.json: "${ envPrefix }config" must be an object.`
+			`Invalid ${ configFile }: "${ configKey }" must be an array of strings.`
 		);
 	}
+}
 
-	if ( typeof config.mappings !== 'object' ) {
+/**
+ * Validates the object and throws if it isn't valid.
+ *
+ * @param {string}   configFile The config file we're validating.
+ * @param {string}   configKey  The configuration key we're validating.
+ * @param {string[]} obj        The object that we're checking.
+ * @param {string[]} allowTypes The types that are allowed.
+ */
+function checkObjectWithValues( configFile, configKey, obj, allowTypes ) {
+	if ( allowTypes === undefined ) {
+		allowTypes = [];
+	}
+
+	if ( typeof obj !== 'object' || Array.isArray( obj ) ) {
 		throw new ValidationError(
-			`Invalid .wp-env.json: "${ envPrefix }mappings" must be an object.`
+			`Invalid ${ configFile }: "${ configKey }" must be an object.`
 		);
 	}
 
-	for ( const [ wpDir, localDir ] of Object.entries( config.mappings ) ) {
-		if ( ! localDir || typeof localDir !== 'string' ) {
+	for ( const key in obj ) {
+		if ( ! obj[ key ] && ! allowTypes.includes( 'empty' ) ) {
+			throw new ValidationError(
+				`Invalid ${ configFile }: "${ configKey }.${ key }" must not be empty.`
+			);
+		}
+
+		// Identify arrays uniquely.
+		const type = Array.isArray( obj[ key ] ) ? 'array' : typeof obj[ key ];
+
+		if ( ! allowTypes.includes( type ) ) {
 			throw new ValidationError(
-				`Invalid .wp-env.json: "${ envPrefix }mappings.${ wpDir }" should be a string.`
+				`Invalid ${ configFile }: "${ configKey }.${ key }" must be a ${ allowTypes.join(
+					' or '
+				) }.`
 			);
 		}
 	}
+}
 
-	if (
-		config.phpVersion &&
-		! (
-			typeof config.phpVersion === 'string' &&
-			config.phpVersion.length === 3
-		)
-	) {
+/**
+ * Validates the version and throws if it isn't valid.
+ *
+ * @param {string} configFile The config file we're validating.
+ * @param {string} configKey  The configuration key we're validating.
+ * @param {string} version    The version that we're checking.
+ */
+function checkVersion( configFile, configKey, version ) {
+	if ( typeof version !== 'string' ) {
 		throw new ValidationError(
-			`Invalid .wp-env.json: "${ envPrefix }phpVersion" must be a string of the format "0.0".`
+			`Invalid ${ configFile }: "${ configKey }" must be a string.`
 		);
 	}
 
-	return config;
+	if ( ! version.match( /[0-9]+(?:\.[0-9]+)*/ ) ) {
+		throw new ValidationError(
+			`Invalid ${ configFile }: "${ configKey }" must be a string of the format "X", "X.X", or "X.X.X".`
+		);
+	}
+}
+
+/**
+ * Validates the url and throws if it isn't valid.
+ *
+ * @param {string} configFile The config file we're validating.
+ * @param {string} configKey  The configuration key we're validating.
+ * @param {string} url        The URL that we're checking.
+ */
+function checkValidURL( configFile, configKey, url ) {
+	try {
+		new URL( url );
+	} catch {
+		throw new ValidationError(
+			`Invalid ${ configFile }: "${ configKey }" must be a valid URL.`
+		);
+	}
 }
 
 module.exports = {
-	validateConfig,
 	ValidationError,
+	checkString,
+	checkPort,
+	checkStringArray,
+	checkObjectWithValues,
+	checkVersion,
+	checkValidURL,
 };

package/lib/env.js

@@ -3,9 +3,11 @@
  * Internal dependencies
  */
 const { ValidationError } = require( './config' );
+const { AfterSetupError } = require( './execute-after-setup' );
 const commands = require( './commands' );
 
 module.exports = {
 	...commands,
 	ValidationError,
+	AfterSetupError,
 };

package/lib/execute-after-setup.js

@@ -0,0 +1,51 @@
+'use strict';
+/**
+ * External dependencies
+ */
+const { execSync } = require( 'child_process' );
+
+/**
+ * @typedef {import('./config').WPConfig} WPConfig
+ */
+
+/**
+ * Error subtype which indicates that the afterSetup command failed.
+ */
+class AfterSetupError extends Error {}
+
+/**
+ * Executes any defined afterSetup command.
+ *
+ * @param {WPConfig} config  The config object to use.
+ * @param {Object}   spinner A CLI spinner which indciates progress.
+ */
+function executeAfterSetup( config, spinner ) {
+	if ( ! config.afterSetup ) {
+		return;
+	}
+
+	spinner.text = 'Executing Script: afterSetup';
+
+	try {
+		let output = execSync( config.afterSetup, {
+			encoding: 'utf-8',
+			stdio: 'pipe',
+			env: process.env,
+		} );
+
+		// Remove any trailing whitespace for nicer output.
+		output = output.trimRight();
+
+		// We don't need to bother with any output if there isn't any.
+		if ( output ) {
+			spinner.info( `After Setup:\n${ output }` );
+		}
+	} catch ( error ) {
+		throw new AfterSetupError( `After Setup:\n${ error.stderr }` );
+	}
+}
+
+module.exports = {
+	AfterSetupError,
+	executeAfterSetup,
+};

package/lib/get-host-user.js

@@ -0,0 +1,31 @@
+'use strict';
+/**
+ * External dependencies
+ */
+const os = require( 'os' );
+
+/**
+ * Gets information about the host user.
+ *
+ * @return {Object} The host user's name, uid, and gid.
+ */
+module.exports = function getHostUser() {
+	const hostUser = os.userInfo();
+
+	// On Windows the uid and gid will be -1. Since there isn't a great way to handle this,
+	// we're just going to say that the host user is root. On Windows you'll likely be
+	// using WSL to run commands inside the container, which has a uid and gid. If
+	// you aren't, you'll be mounting directories from Windows, to a Linux
+	// VM (Docker Desktop uses one), to the guest OS. I assume that
+	// when dealing with this configuration that file ownership
+	// has the same kind of magic handling that macOS uses.
+	const uid = ( hostUser.uid === -1 ? 0 : hostUser.uid ).toString();
+	const gid = ( hostUser.gid === -1 ? 0 : hostUser.gid ).toString();
+
+	return {
+		name: hostUser.username,
+		uid,
+		gid,
+		fullUser: uid + ':' + gid,
+	};
+};

package/lib/init-config.js

@@ -1,3 +1,4 @@
+'use strict';
 /**
  * External dependencies
  */
@@ -5,12 +6,11 @@ const path = require( 'path' );
 const { writeFile, mkdir } = require( 'fs' ).promises;
 const { existsSync } = require( 'fs' );
 const yaml = require( 'js-yaml' );
-const os = require( 'os' );
 
 /**
  * Internal dependencies
  */
-const { readConfig } = require( './config' );
+const { loadConfig, ValidationError } = require( './config' );
 const buildDockerComposeConfig = require( './build-docker-compose-config' );
 
 /**
@@ -39,8 +39,7 @@ module.exports = async function initConfig( {
 	xdebug = 'off',
 	writeChanges = false,
 } ) {
-	const configPath = path.resolve( '.wp-env.json' );
-	const config = await readConfig( configPath );
+	const config = await loadConfig( path.resolve( '.' ) );
 	config.debug = debug;
 
 	// Adding this to the config allows the start command to understand that the
@@ -81,13 +80,23 @@ module.exports = async function initConfig( {
 			yaml.dump( dockerComposeConfig )
 		);
 
-		await writeFile(
-			path.resolve( config.workDirectoryPath, 'Dockerfile' ),
-			dockerFileContents(
-				dockerComposeConfig.services.wordpress.image,
-				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 ) ) {
 		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.'
@@ -99,80 +108,189 @@ module.exports = async function initConfig( {
 };
 
 /**
- * Checks the configured PHP version
- * against the minimum version supported by Xdebug
+ * Generates the Dockerfile used by wp-env's `wordpress` and `tests-wordpress` instances.
  *
- * @param {WPConfig} config
- * @return {boolean} Whether the PHP version is supported by Xdebug
+ * @param {string}   env    The environment we're installing -- development or tests.
+ * @param {WPConfig} config The configuration object.
+ * @return {string} The dockerfile contents.
  */
-function checkXdebugPhpCompatibility( config ) {
-	// By default, an undefined phpVersion uses the version on the docker image,
-	// which is supported by Xdebug 3.
-	const phpCompatibility = true;
-
-	// If PHP version is defined
-	// ensure it meets the Xdebug minimum compatibility requirment.
-	if ( config.env.development.phpVersion ) {
-		const versionTokens = config.env.development.phpVersion.split( '.' );
-		const majorVer = parseInt( versionTokens[ 0 ] );
-		const minorVer = parseInt( versionTokens[ 1 ] );
+function wordpressDockerFileContents( env, config ) {
+	const phpVersion = config.env[ env ].phpVersion
+		? ':php' + config.env[ env ].phpVersion
+		: '';
 
-		if ( isNaN( majorVer ) || isNaN( minorVer ) ) {
-			throw new Error(
-				'Something went wrong when parsing the PHP version.'
-			);
-		}
+	return `FROM wordpress${ phpVersion }
 
-		// Xdebug 3 supports 7.2 and higher
-		// Ensure user has specified a compatible PHP version.
-		if ( majorVer < 7 || ( majorVer === 7 && minorVer < 2 ) ) {
-			throw new Error( 'Cannot use XDebug 3 on PHP < 7.2.' );
-		}
-	}
+# Update apt sources for archived versions of Debian.
+
+# stretch (https://lists.debian.org/debian-devel-announce/2023/03/msg00006.html)
+RUN sed -i 's|deb.debian.org/debian stretch|archive.debian.org/debian stretch|g' /etc/apt/sources.list
+RUN sed -i 's|security.debian.org/debian-security stretch|archive.debian.org/debian-security stretch|g' /etc/apt/sources.list
+RUN sed -i '/stretch-updates/d' /etc/apt/sources.list
 
-	return phpCompatibility;
+# Create the host's user so that we can match ownership in the container.
+ARG HOST_USERNAME
+ARG HOST_UID
+ARG HOST_GID
+# When the IDs are already in use we can still safely move on.
+RUN groupadd -g $HOST_GID $HOST_USERNAME || true
+RUN useradd -m -u $HOST_UID -g $HOST_GID $HOST_USERNAME || true
+
+# Install any dependencies we need in the container.
+${ installDependencies( 'wordpress', env, config ) }`;
 }
 
 /**
- * Generates the Dockerfile used by wp-env's development instance.
+ * Generates the Dockerfile used by wp-env's `cli` and `tests-cli` instances.
  *
- * @param {string}   image  The base docker image to use.
+ * @param {string}   env    The environment we're installing -- development or tests.
  * @param {WPConfig} config The configuration object.
- *
  * @return {string} The dockerfile contents.
  */
-function dockerFileContents( image, config ) {
-	// Don't install XDebug unless it is explicitly required.
-	let shouldInstallXdebug = false;
+function cliDockerFileContents( env, config ) {
+	const phpVersion = config.env[ env ].phpVersion
+		? '-php' + config.env[ env ].phpVersion
+		: '';
+
+	return `FROM wordpress:cli${ phpVersion }
+
+# Switch to root so we can create users.
+USER root
+
+# Create the host's user so that we can match ownership in the container.
+ARG HOST_USERNAME
+ARG HOST_UID
+ARG HOST_GID
+# When the IDs are already in use we can still safely move on.
+RUN addgroup -g $HOST_GID $HOST_USERNAME || true
+RUN adduser -h /home/$HOST_USERNAME -G $( getent group $HOST_GID | cut -d: -f1 ) -u $HOST_UID $HOST_USERNAME || true
+
+# Install any dependencies we need in the container.
+${ installDependencies( 'cli', env, config ) }
+	
+# Switch back to the original user now that we're done.
+USER www-data
+
+# Have the container sleep infinitely to keep it alive for us to run commands on it.
+CMD [ "/bin/sh", "-c", "while true; do sleep 2073600; done" ]
+`;
+}
+
+/**
+ * Generates content for the Dockerfile to install dependencies.
+ *
+ * @param {string}   service The kind of service that we're installing dependencies on ('wordpress' or 'cli').
+ * @param {string}   env     The environment we're installing dependencies for ('development' or 'tests').
+ * @param {WPConfig} config  The configuration object.
+ * @return {string} The Dockerfile content for installing dependencies.
+ */
+function installDependencies( service, env, config ) {
+	let dockerFileContent = '';
+
+	// At times we may need to evaluate the environment. This is because the
+	// WordPress image uses Ubuntu while the CLI image uses Alpine.
 
-	if ( config.xdebug !== 'off' ) {
-		const usingCompatiblePhp = checkXdebugPhpCompatibility( config );
+	// Start with some environment-specific dependency installations.
+	switch ( service ) {
+		case 'wordpress': {
+			dockerFileContent += `
+# Make sure we're working with the latest packages.
+RUN apt-get -qy update
 
-		if ( usingCompatiblePhp ) {
-			shouldInstallXdebug = true;
+# Install some basic PHP dependencies.
+RUN apt-get -qy install $PHPIZE_DEPS && touch /usr/local/etc/php/php.ini
+
+# Set up sudo so they can have root access.
+RUN apt-get -qy install sudo
+RUN echo "$HOST_USERNAME ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers`;
+			break;
+		}
+		case 'cli': {
+			dockerFileContent += `
+RUN apk update
+RUN apk --no-cache add $PHPIZE_DEPS && touch /usr/local/etc/php/php.ini
+RUN apk --no-cache add sudo linux-headers
+RUN echo "$HOST_USERNAME ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers`;
+			break;
+		}
+		default: {
+			throw new Error( `Invalid service "${ service }" given` );
 		}
 	}
 
-	return `FROM ${ image }
+	dockerFileContent += getXdebugConfig(
+		config.xdebug,
+		config.env[ env ].phpVersion
+	);
 
-RUN apt-get -qy install $PHPIZE_DEPS && touch /usr/local/etc/php/php.ini
-${ shouldInstallXdebug ? installXdebug( config.xdebug ) : '' }
-`;
+	// Add better PHP settings.
+	dockerFileContent += `
+RUN echo 'upload_max_filesize = 1G' >> /usr/local/etc/php/php.ini
+RUN echo 'post_max_size = 1G' >> /usr/local/etc/php/php.ini`;
+
+	// Make sure Composer is available for use in all services.
+	dockerFileContent += `
+RUN curl -sS https://getcomposer.org/installer -o /tmp/composer-setup.php
+RUN export COMPOSER_HASH=\`curl -sS https://composer.github.io/installer.sig\` && php -r "if (hash_file('SHA384', '/tmp/composer-setup.php') === '$COMPOSER_HASH') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('/tmp/composer-setup.php'); } echo PHP_EOL;"
+RUN php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=composer
+RUN rm /tmp/composer-setup.php`;
+
+	// Install any Composer packages we might need globally.
+	// Make sure to do this as the user and ensure the binaries are available in the $PATH.
+	dockerFileContent += `
+USER $HOST_USERNAME
+ENV PATH="\${PATH}:/home/$HOST_USERNAME/.composer/vendor/bin"
+RUN composer global require --dev yoast/phpunit-polyfills:"^1.0"
+USER root`;
+
+	return dockerFileContent;
 }
 
-function installXdebug( enableXdebug ) {
-	const isLinux = os.type() === 'Linux';
-	// Discover client host does not appear to work on macOS with Docker.
-	const clientDetectSettings = isLinux
-		? 'xdebug.discover_client_host=true'
-		: 'xdebug.client_host="host.docker.internal"';
+/**
+ * Gets the Xdebug config based on the options in the config object.
+ *
+ * @param {string} xdebugMode The Xdebug mode set in the config.
+ * @param {string} phpVersion The php version set in the environment.
+ * @return {string} The Xdebug config -- can be an empty string when it's not used.
+ */
+function getXdebugConfig( xdebugMode = 'off', phpVersion ) {
+	if ( xdebugMode === 'off' ) {
+		return '';
+	}
+
+	let xdebugVersion = 'xdebug';
+
+	if ( phpVersion ) {
+		const versionTokens = phpVersion.split( '.' );
+		const majorVer = parseInt( versionTokens[ 0 ] );
+		const minorVer = parseInt( versionTokens[ 1 ] );
+
+		if ( isNaN( majorVer ) || isNaN( minorVer ) ) {
+			throw new ValidationError(
+				'Something went wrong when parsing the PHP version.'
+			);
+		}
+
+		// Throw an error if someone tries to use Xdebug with an unsupported PHP version.
+		// Xdebug 3 only supports 7.2 and higher.
+		if ( majorVer < 7 || ( majorVer === 7 && minorVer < 2 ) ) {
+			throw new ValidationError(
+				`Cannot use XDebug 3 with PHP < 7.2. Your PHP version is ${ phpVersion }.`
+			);
+		}
+
+		// For now, we support PHP 7 by installing the final version of Xdebug to
+		// support PHP 7 when the environment uses that version. By default, use the
+		// latest version.
+		if ( majorVer === 7 ) {
+			xdebugVersion = 'xdebug-3.1.6';
+		}
+	}
 
 	return `
-# Install Xdebug:
-RUN if [ -z "$(pecl list | grep xdebug)" ] ; then pecl install xdebug ; fi
+RUN if [ -z "$(pecl list | grep ${ xdebugVersion })" ] ; then pecl install ${ xdebugVersion } ; fi
 RUN docker-php-ext-enable xdebug
 RUN echo 'xdebug.start_with_request=yes' >> /usr/local/etc/php/php.ini
-RUN echo 'xdebug.mode=${ enableXdebug }' >> /usr/local/etc/php/php.ini
-RUN echo '${ clientDetectSettings }' >> /usr/local/etc/php/php.ini
-	`;
+RUN echo 'xdebug.mode=${ xdebugMode }' >> /usr/local/etc/php/php.ini
+RUN echo 'xdebug.client_host="host.docker.internal"' >> /usr/local/etc/php/php.ini`;
 }

package/lib/md5.js

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

package/lib/parse-xdebug-mode.js

@@ -1,3 +1,4 @@
+'use strict';
 // See https://xdebug.org/docs/all_settings#mode
 const XDEBUG_MODES = [
 	'develop',

package/lib/retry.js

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

package/lib/test/__snapshots__/md5.js.snap

@@ -0,0 +1,9 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`md5 creates a hash of a number 1`] = `"55587a910882016321201e6ebbc9f595"`;
+
+exports[`md5 creates a hash of a object 1`] = `"a0294b0e88367a0ff800d78413356538"`;
+
+exports[`md5 creates a hash of a string 1`] = `"5d41402abc4b2a76b9719d911017c592"`;
+
+exports[`md5 creates a hash of null 1`] = `"37a6259cc0c1dae299a7866489dff0bd"`;