@wordpress/env 6.0.0 → 7.0.0

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

@@ -0,0 +1,305 @@
+'use strict';
+/**
+ * Internal dependencies
+ */
+const {
+	ValidationError,
+	checkString,
+	checkPort,
+	checkStringArray,
+	checkObjectWithValues,
+	checkVersion,
+	checkValidURL,
+} = require( '../validate-config' );
+
+describe( 'validate-config', () => {
+	describe( 'checkString', () => {
+		it( 'throws when not a string', () => {
+			expect( () => checkString( 'test.json', 'test', 1234 ) ).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be a string.'
+				)
+			);
+		} );
+
+		it( 'passes for string', () => {
+			expect( () =>
+				checkString( 'test.json', 'test', 'test' )
+			).not.toThrow();
+		} );
+	} );
+
+	describe( 'checkPort', () => {
+		it( 'throws when not a number', () => {
+			expect( () => checkPort( 'test.json', 'test', 'test' ) ).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be an integer.'
+				)
+			);
+
+			expect( () =>
+				checkPort( 'test.json', 'test', { test: 'test' } )
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be an integer.'
+				)
+			);
+		} );
+
+		it( 'throws when port out of range', () => {
+			expect( () => checkPort( 'test.json', 'test', -1 ) ).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be a valid port.'
+				)
+			);
+
+			expect( () => checkPort( 'test.json', 'test', 99999999 ) ).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be a valid port.'
+				)
+			);
+		} );
+
+		it( 'passes for valid port', () => {
+			expect( () =>
+				checkPort( 'test.json', 'test', 8888 )
+			).not.toThrow();
+		} );
+	} );
+
+	describe( 'checkStringArray', () => {
+		it( 'throws when not an array', () => {
+			expect( () =>
+				checkStringArray( 'test.json', 'test', 'test' )
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be an array.'
+				)
+			);
+
+			expect( () =>
+				checkStringArray( 'test.json', 'test', { test: 'test' } )
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be an array.'
+				)
+			);
+		} );
+
+		it( 'throws when array contains non-strings', () => {
+			expect( () =>
+				checkStringArray( 'test.json', 'test', [ 12 ] )
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be an array of strings.'
+				)
+			);
+
+			expect( () =>
+				checkStringArray( 'test.json', 'test', [ 'test', 12 ] )
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be an array of strings.'
+				)
+			);
+		} );
+
+		it( 'passes for string arrays', () => {
+			expect( () =>
+				checkStringArray( 'test.json', 'test', [] )
+			).not.toThrow();
+			expect( () =>
+				checkStringArray( 'test.json', 'test', [ 'test' ] )
+			).not.toThrow();
+		} );
+	} );
+
+	describe( 'checkObjectWithValues', () => {
+		it( 'throws when not an object', () => {
+			expect( () =>
+				checkObjectWithValues( 'test.json', 'test', 'test', [] )
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be an object.'
+				)
+			);
+
+			expect( () =>
+				checkObjectWithValues( 'test.json', 'test', [ 'test' ], [] )
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be an object.'
+				)
+			);
+		} );
+
+		it( 'throws when no allowed types are given', () => {
+			expect( () =>
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: 'test' },
+					[]
+				)
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test.test" must be a .'
+				)
+			);
+		} );
+
+		it( 'throws when type is not allowed', () => {
+			expect( () =>
+				checkObjectWithValues( 'test.json', 'test', { test: 'test' }, [
+					'number',
+				] )
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test.test" must be a number.'
+				)
+			);
+
+			expect( () =>
+				checkObjectWithValues( 'test.json', 'test', { test: 1 }, [
+					'string',
+				] )
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test.test" must be a string.'
+				)
+			);
+
+			expect( () =>
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: [ 'test' ] },
+					[ 'object', 'string' ]
+				)
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test.test" must be a object or string.'
+				)
+			);
+		} );
+
+		it( 'passes when type is allowed', () => {
+			expect( () =>
+				checkObjectWithValues( 'test.json', 'test', { test: 'test' }, [
+					'string',
+				] )
+			).not.toThrow();
+			expect( () =>
+				checkObjectWithValues( 'test.json', 'test', { test: 1 }, [
+					'number',
+				] )
+			).not.toThrow();
+			expect( () =>
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: { nested: 'test' } },
+					[ 'object' ]
+				)
+			).not.toThrow();
+			expect( () =>
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: [ 'test' ] },
+					[ 'array' ]
+				)
+			).not.toThrow();
+		} );
+	} );
+
+	describe( 'checkVersion', () => {
+		it( 'throws for invalid input', () => {
+			expect( () => checkVersion( 'test.json', 'test', 'test' ) ).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be a string of the format "X", "X.X", or "X.X.X".'
+				)
+			);
+
+			expect( () => checkVersion( 'test.json', 'test', 123 ) ).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be a string.'
+				)
+			);
+		} );
+
+		it( 'passes for different version formats', () => {
+			expect( () =>
+				checkVersion( 'test.json', 'test', '1' )
+			).not.toThrow();
+			expect( () =>
+				checkVersion( 'test.json', 'test', '1.1' )
+			).not.toThrow();
+			expect( () =>
+				checkVersion( 'test.json', 'test', '1.1.1' )
+			).not.toThrow();
+			expect( () =>
+				checkVersion( 'test.json', 'test', '15.7.2' )
+			).not.toThrow();
+			expect( () =>
+				checkVersion( 'test.json', 'test', '26634543' )
+			).not.toThrow();
+		} );
+	} );
+
+	describe( 'checkValidURL', () => {
+		it( 'throws for invaid URLs', () => {
+			expect( () =>
+				checkValidURL( 'test.json', 'test', 'localhost' )
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be a valid URL.'
+				)
+			);
+
+			expect( () => checkValidURL( 'test.json', 'test', '' ) ).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be a valid URL.'
+				)
+			);
+
+			expect( () => checkValidURL( 'test.json', 'test', 123 ) ).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be a valid URL.'
+				)
+			);
+		} );
+
+		it( 'passes for valid URLs', () => {
+			expect( () =>
+				checkValidURL( 'test.json', 'test', 'http://test.com' )
+			).not.toThrow();
+			expect( () =>
+				checkValidURL( 'test.json', 'test', 'https://test.com' )
+			).not.toThrow();
+			expect( () =>
+				checkValidURL( 'test.json', 'test', 'http://test' )
+			).not.toThrow();
+			expect( () =>
+				checkValidURL(
+					'test.json',
+					'test',
+					'http://test/test?test=test'
+				)
+			).not.toThrow();
+			expect( () =>
+				checkValidURL( 'test.json', 'test', 'http://test.co.uk' )
+			).not.toThrow();
+			expect( () =>
+				checkValidURL( 'test.json', 'test', 'https://test.co.uk:8888' )
+			).not.toThrow();
+			expect( () =>
+				checkValidURL(
+					'test.json',
+					'test',
+					'http://test.co.uk:8888/test?test=test#test'
+				)
+			).not.toThrow();
+		} );
+	} );
+} );

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,105 +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 .wp-env.json: "${ envPrefix }mappings.${ wpDir }" should be a string.`
+				`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 ${ 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.`
 		);
 	}
 
-	checkValidURL( envPrefix, config.config, 'WP_SITEURL' );
-	checkValidURL( envPrefix, config.config, 'WP_HOME' );
-
-	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 input and throws if it isn't a valid URL.
+ * Validates the url and throws if it isn't valid.
  *
- * @param {string} envPrefix The environment we're validating.
- * @param {Object} config    The configuration object we're looking at.
- * @param {string} configKey The configuration key we're validating.
+ * @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( envPrefix, config, configKey ) {
-	if ( config[ configKey ] === undefined ) {
-		return;
-	}
-
+function checkValidURL( configFile, configKey, url ) {
 	try {
-		new URL( config[ configKey ] );
+		new URL( url );
 	} catch {
 		throw new ValidationError(
-			`Invalid .wp-env.json: "${ envPrefix }config.${ configKey }" must be a valid URL.`
+			`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,
+	};
+};