@wordpress/env 7.0.0 → 8.1.0

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

@@ -1,10 +1,5 @@
 'use strict';
 /* eslint-disable jest/no-conditional-expect */
-/**
- * External dependencies
- */
-const path = require( 'path' );
-
 /**
  * Internal dependencies
  */
@@ -40,6 +35,7 @@ const DEFAULT_CONFIG = {
 	pluginSources: [],
 	themeSources: [],
 	config: {
+		FS_METHOD: 'direct',
 		WP_DEBUG: true,
 		SCRIPT_DEBUG: true,
 		WP_ENVIRONMENT_TYPE: 'local',
@@ -51,7 +47,11 @@ const DEFAULT_CONFIG = {
 		WP_HOME: 'http://localhost',
 	},
 	mappings: {},
-	afterSetup: null,
+	lifecycleScripts: {
+		afterStart: null,
+		afterClean: null,
+		afterDestroy: null,
+	},
 	env: {
 		development: {},
 		tests: {
@@ -76,11 +76,11 @@ describe( 'parseConfig', () => {
 		delete process.env.WP_ENV_TESTS_PORT;
 		delete process.env.WP_ENV_CORE;
 		delete process.env.WP_ENV_PHP_VERSION;
-		delete process.env.WP_ENV_AFTER_SETUP;
+		delete process.env.WP_ENV_LIFECYCLE_SCRIPT_AFTER_START;
 	} );
 
 	it( 'should return default config', async () => {
-		const parsed = await parseConfig( './', '/cache' );
+		const parsed = await parseConfig( '/test/gutenberg', '/cache' );
 
 		expect( parsed ).toEqual( DEFAULT_CONFIG );
 	} );
@@ -88,60 +88,44 @@ describe( 'parseConfig', () => {
 	it( 'should infer a core mounting default when ran from a WordPress directory', async () => {
 		detectDirectoryType.mockResolvedValue( 'core' );
 
-		const parsed = await parseConfig( './', '/cache' );
+		const parsed = await parseConfig( '/test/gutenberg', '/cache' );
 
-		expect( parsed ).toEqual( {
-			...DEFAULT_CONFIG,
-			coreSource: {
-				basename: 'gutenberg',
-				path: path.resolve( '.' ),
-				testsPath: '/cache/tests-gutenberg',
-				type: 'local',
-			},
-		} );
+		expect( parsed.pluginSources ).toHaveLength( 0 );
+		expect( parsed.themeSources ).toHaveLength( 0 );
+		expect( parsed.coreSource ).toMatchObject( { type: 'local' } );
 	} );
 
 	it( 'should infer a plugin mounting default when ran from a plugin directory', async () => {
 		detectDirectoryType.mockResolvedValue( 'plugin' );
 
-		const parsed = await parseConfig( './', '/cache' );
+		const parsed = await parseConfig( '/test/gutenberg', '/cache' );
 
-		expect( parsed ).toEqual( {
-			...DEFAULT_CONFIG,
-			pluginSources: [
-				{
-					basename: 'gutenberg',
-					path: path.resolve( '.' ),
-					type: 'local',
-				},
-			],
-		} );
+		expect( parsed.coreSource ).toMatchObject( { type: 'git' } );
+		expect( parsed.themeSources ).toHaveLength( 0 );
+		expect( parsed.pluginSources ).toHaveLength( 1 );
+		expect( parsed.pluginSources[ 0 ] ).toMatchObject( { type: 'local' } );
 	} );
 
 	it( 'should infer a theme mounting default when ran from a theme directory', async () => {
 		detectDirectoryType.mockResolvedValue( 'theme' );
 
-		const parsed = await parseConfig( './', '/cache' );
+		const parsed = await parseConfig( '/test/gutenberg', '/cache' );
 
-		expect( parsed ).toEqual( {
-			...DEFAULT_CONFIG,
-			themeSources: [
-				{
-					basename: 'gutenberg',
-					path: path.resolve( '.' ),
-					type: 'local',
-				},
-			],
-		} );
+		expect( parsed.coreSource ).toMatchObject( { type: 'git' } );
+		expect( parsed.pluginSources ).toHaveLength( 0 );
+		expect( parsed.themeSources ).toHaveLength( 1 );
+		expect( parsed.themeSources[ 0 ] ).toMatchObject( { type: 'local' } );
 	} );
 
 	it( 'should merge configs with precedence', async () => {
 		readRawConfigFile.mockImplementation( async ( configFile ) => {
-			if ( configFile === path.resolve( './.wp-env.json' ) ) {
+			if ( configFile === '/test/gutenberg/.wp-env.json' ) {
 				return {
 					core: 'WordPress/WordPress#Test',
 					phpVersion: '1.0',
-					afterSetup: 'test',
+					lifecycleScripts: {
+						afterStart: 'test',
+					},
 					env: {
 						development: {
 							port: 1234,
@@ -153,9 +137,12 @@ describe( 'parseConfig', () => {
 				};
 			}
 
-			if ( configFile === path.resolve( './.wp-env.override.json' ) ) {
+			if ( configFile === '/test/gutenberg/.wp-env.override.json' ) {
 				return {
 					phpVersion: '2.0',
+					lifecycleScripts: {
+						afterDestroy: 'test',
+					},
 					env: {
 						tests: {
 							port: 1011,
@@ -167,7 +154,7 @@ describe( 'parseConfig', () => {
 			throw new Error( 'Invalid File: ' + configFile );
 		} );
 
-		const parsed = await parseConfig( './', '/cache' );
+		const parsed = await parseConfig( '/test/gutenberg', '/cache' );
 
 		const expected = {
 			...DEFAULT_CONFIG,
@@ -181,7 +168,11 @@ describe( 'parseConfig', () => {
 				type: 'git',
 			},
 			phpVersion: '2.0',
-			afterSetup: 'test',
+			lifecycleScripts: {
+				...DEFAULT_CONFIG.lifecycleScripts,
+				afterStart: 'test',
+				afterDestroy: 'test',
+			},
 			env: {
 				development: {
 					...DEFAULT_CONFIG.env.development,
@@ -198,7 +189,7 @@ describe( 'parseConfig', () => {
 
 	it( 'should parse core, plugin, theme, and mapping sources', async () => {
 		readRawConfigFile.mockImplementation( async ( configFile ) => {
-			if ( configFile === path.resolve( '.', './.wp-env.json' ) ) {
+			if ( configFile === '/test/gutenberg/.wp-env.json' ) {
 				return {
 					core: 'WordPress/WordPress#Test',
 					plugins: [ 'WordPress/TestPlugin#Test' ],
@@ -210,16 +201,14 @@ describe( 'parseConfig', () => {
 				};
 			}
 
-			if (
-				configFile === path.resolve( '.', './.wp-env.override.json' )
-			) {
+			if ( configFile === '/test/gutenberg/.wp-env.override.json' ) {
 				return {};
 			}
 
 			throw new Error( 'Invalid File: ' + configFile );
 		} );
 
-		const parsed = await parseConfig( './', '/cache' );
+		const parsed = await parseConfig( '/test/gutenberg', '/cache' );
 
 		expect( parsed ).toEqual( {
 			...DEFAULT_CONFIG,
@@ -270,9 +259,9 @@ describe( 'parseConfig', () => {
 		process.env.WP_ENV_TESTS_PORT = 456;
 		process.env.WP_ENV_CORE = 'WordPress/WordPress#test';
 		process.env.WP_ENV_PHP_VERSION = '3.0';
-		process.env.WP_ENV_AFTER_SETUP = 'test after';
+		process.env.WP_ENV_LIFECYCLE_SCRIPT_AFTER_START = 'test after';
 
-		const parsed = await parseConfig( './', '/cache' );
+		const parsed = await parseConfig( '/test/gutenberg', '/cache' );
 
 		expect( parsed ).toEqual( {
 			...DEFAULT_CONFIG,
@@ -288,7 +277,10 @@ describe( 'parseConfig', () => {
 				type: 'git',
 			},
 			phpVersion: '3.0',
-			afterSetup: 'test after',
+			lifecycleScripts: {
+				...DEFAULT_CONFIG.lifecycleScripts,
+				afterStart: 'test after',
+			},
 			env: {
 				development: {
 					port: 123,
@@ -329,7 +321,7 @@ describe( 'parseConfig', () => {
 
 		expect.assertions( 1 );
 		try {
-			await parseConfig( './', '/cache' );
+			await parseConfig( '/test/gutenberg', '/cache' );
 		} catch ( error ) {
 			expect( error ).toEqual(
 				new ValidationError(
@@ -338,5 +330,64 @@ describe( 'parseConfig', () => {
 			);
 		}
 	} );
+
+	it( 'throws for unknown config options', async () => {
+		readRawConfigFile.mockImplementation( async ( configFile ) => {
+			if ( configFile === '/test/gutenberg/.wp-env.json' ) {
+				return {
+					test: 'test',
+				};
+			}
+
+			if ( configFile === '/test/gutenberg/.wp-env.override.json' ) {
+				return {};
+			}
+
+			throw new Error( 'Invalid File: ' + configFile );
+		} );
+
+		expect.assertions( 1 );
+		try {
+			await parseConfig( '/test/gutenberg', '/cache' );
+		} catch ( error ) {
+			expect( error ).toEqual(
+				new ValidationError(
+					`Invalid /test/gutenberg/.wp-env.json: "test" is not a configuration option.`
+				)
+			);
+		}
+	} );
+
+	it( 'throws for root-only config options', async () => {
+		readRawConfigFile.mockImplementation( async ( configFile ) => {
+			if ( configFile === '/test/gutenberg/.wp-env.json' ) {
+				return {
+					env: {
+						development: {
+							// Only the root can have environment-specific configurations.
+							env: {},
+						},
+					},
+				};
+			}
+
+			if ( configFile === '/test/gutenberg/.wp-env.override.json' ) {
+				return {};
+			}
+
+			throw new Error( 'Invalid File: ' + configFile );
+		} );
+
+		expect.assertions( 1 );
+		try {
+			await parseConfig( '/test/gutenberg', '/cache' );
+		} catch ( error ) {
+			expect( error ).toEqual(
+				new ValidationError(
+					`Invalid /test/gutenberg/.wp-env.json: "development.env" is not a configuration option.`
+				)
+			);
+		}
+	} );
 } );
 /* eslint-enable jest/no-conditional-expect */

package/lib/config/test/parse-source-string.js

@@ -45,7 +45,7 @@ describe( 'parseSourceString', () => {
 	describe( 'local sources', () => {
 		it( 'should parse relative directories', () => {
 			expect( parseSourceString( '.', options ) ).toEqual( {
-				basename: 'gutenberg',
+				basename: path.basename( path.resolve( '.' ) ),
 				path: path.resolve( '.' ),
 				type: 'local',
 			} );

package/lib/config/test/post-process-config.js

@@ -156,7 +156,9 @@ describe( 'postProcessConfig', () => {
 		const processed = postProcessConfig( {
 			port: 8888,
 			testsPort: 8889,
-			afterSetup: 'test',
+			lifecycleScripts: {
+				afterStart: 'test',
+			},
 			env: {
 				development: {},
 				tests: {},
@@ -166,7 +168,9 @@ describe( 'postProcessConfig', () => {
 		expect( processed ).toEqual( {
 			port: 8888,
 			testsPort: 8889,
-			afterSetup: 'test',
+			lifecycleScripts: {
+				afterStart: 'test',
+			},
 			env: {
 				development: {
 					port: 8888,

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

@@ -117,7 +117,7 @@ describe( 'validate-config', () => {
 	describe( 'checkObjectWithValues', () => {
 		it( 'throws when not an object', () => {
 			expect( () =>
-				checkObjectWithValues( 'test.json', 'test', 'test', [] )
+				checkObjectWithValues( 'test.json', 'test', 'test', [], false )
 			).toThrow(
 				new ValidationError(
 					'Invalid test.json: "test" must be an object.'
@@ -125,7 +125,13 @@ describe( 'validate-config', () => {
 			);
 
 			expect( () =>
-				checkObjectWithValues( 'test.json', 'test', [ 'test' ], [] )
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					[ 'test' ],
+					[],
+					false
+				)
 			).toThrow(
 				new ValidationError(
 					'Invalid test.json: "test" must be an object.'
@@ -139,33 +145,42 @@ describe( 'validate-config', () => {
 					'test.json',
 					'test',
 					{ test: 'test' },
-					[]
+					[],
+					false
 				)
 			).toThrow(
 				new ValidationError(
-					'Invalid test.json: "test.test" must be a .'
+					'Invalid test.json: "test.test" must be of type: .'
 				)
 			);
 		} );
 
 		it( 'throws when type is not allowed', () => {
 			expect( () =>
-				checkObjectWithValues( 'test.json', 'test', { test: 'test' }, [
-					'number',
-				] )
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: 'test' },
+					[ 'number' ],
+					false
+				)
 			).toThrow(
 				new ValidationError(
-					'Invalid test.json: "test.test" must be a number.'
+					'Invalid test.json: "test.test" must be of type: number.'
 				)
 			);
 
 			expect( () =>
-				checkObjectWithValues( 'test.json', 'test', { test: 1 }, [
-					'string',
-				] )
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: 1 },
+					[ 'string' ],
+					false
+				)
 			).toThrow(
 				new ValidationError(
-					'Invalid test.json: "test.test" must be a string.'
+					'Invalid test.json: "test.test" must be of type: string.'
 				)
 			);
 
@@ -174,32 +189,65 @@ describe( 'validate-config', () => {
 					'test.json',
 					'test',
 					{ test: [ 'test' ] },
-					[ 'object', 'string' ]
+					[ 'object', 'string' ],
+					false
+				)
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test.test" must be of type: object or string.'
+				)
+			);
+
+			expect( () =>
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: null },
+					[ 'object' ],
+					true
 				)
 			).toThrow(
 				new ValidationError(
-					'Invalid test.json: "test.test" must be a object or string.'
+					'Invalid test.json: "test.test" must be of type: object.'
 				)
 			);
 		} );
 
 		it( 'passes when type is allowed', () => {
 			expect( () =>
-				checkObjectWithValues( 'test.json', 'test', { test: 'test' }, [
-					'string',
-				] )
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: 'test' },
+					[ 'string' ],
+					false
+				)
+			).not.toThrow();
+			expect( () =>
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: '' },
+					[ 'string' ],
+					true
+				)
 			).not.toThrow();
 			expect( () =>
-				checkObjectWithValues( 'test.json', 'test', { test: 1 }, [
-					'number',
-				] )
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: 1 },
+					[ 'number' ],
+					false
+				)
 			).not.toThrow();
 			expect( () =>
 				checkObjectWithValues(
 					'test.json',
 					'test',
 					{ test: { nested: 'test' } },
-					[ 'object' ]
+					[ 'object' ],
+					false
 				)
 			).not.toThrow();
 			expect( () =>
@@ -207,7 +255,17 @@ describe( 'validate-config', () => {
 					'test.json',
 					'test',
 					{ test: [ 'test' ] },
-					[ 'array' ]
+					[ 'array' ],
+					false
+				)
+			).not.toThrow();
+			expect( () =>
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: null },
+					[ 'null' ],
+					false
 				)
 			).not.toThrow();
 		} );

package/lib/config/validate-config.js

@@ -74,8 +74,15 @@ function checkStringArray( configFile, configKey, array ) {
  * @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.
+ * @param {boolean}  allowEmpty Indicates whether or not empty values are allowed.
  */
-function checkObjectWithValues( configFile, configKey, obj, allowTypes ) {
+function checkObjectWithValues(
+	configFile,
+	configKey,
+	obj,
+	allowTypes,
+	allowEmpty
+) {
 	if ( allowTypes === undefined ) {
 		allowTypes = [];
 	}
@@ -87,18 +94,37 @@ function checkObjectWithValues( configFile, configKey, obj, allowTypes ) {
 	}
 
 	for ( const key in obj ) {
-		if ( ! obj[ key ] && ! allowTypes.includes( 'empty' ) ) {
-			throw new ValidationError(
-				`Invalid ${ configFile }: "${ configKey }.${ key }" must not be empty.`
-			);
+		// Some values need to be uniquely validated.
+		switch ( obj[ key ] ) {
+			case null:
+			case undefined: {
+				break;
+			}
+
+			default: {
+				if ( ! obj[ key ] && ! allowEmpty ) {
+					throw new ValidationError(
+						`Invalid ${ configFile }: "${ configKey }.${ key }" must not be empty.`
+					);
+				}
+			}
 		}
 
-		// Identify arrays uniquely.
-		const type = Array.isArray( obj[ key ] ) ? 'array' : typeof obj[ key ];
+		// Some types need to be uniquely identified.
+		let type;
+		if ( obj[ key ] === undefined ) {
+			type = 'undefined';
+		} else if ( obj[ key ] === null ) {
+			type = 'null';
+		} else if ( Array.isArray( obj[ key ] ) ) {
+			type = 'array';
+		} else {
+			type = typeof obj[ key ];
+		}
 
 		if ( ! allowTypes.includes( type ) ) {
 			throw new ValidationError(
-				`Invalid ${ configFile }: "${ configKey }.${ key }" must be a ${ allowTypes.join(
+				`Invalid ${ configFile }: "${ configKey }.${ key }" must be of type: ${ allowTypes.join(
 					' or '
 				) }.`
 			);

package/lib/env.js

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

package/lib/execute-lifecycle-script.js

@@ -0,0 +1,86 @@
+'use strict';
+/**
+ * External dependencies
+ */
+const { exec } = require( 'child_process' );
+
+/**
+ * @typedef {import('./config').WPConfig} WPConfig
+ */
+
+/**
+ * Error subtype which indicates that the lifecycle script failed.
+ */
+class LifecycleScriptError extends Error {
+	constructor( event, stderr ) {
+		super( `${ event } Error:\n${ stderr }` );
+
+		this.event = event;
+	}
+}
+
+/**
+ * Executes any defined life cycle script.
+ *
+ * @param {string}   event   The lifecycle event to run the script for.
+ * @param {WPConfig} config  The config object to use.
+ * @param {Object}   spinner A CLI spinner which indciates progress.
+ *
+ * @return {Promise} Resolves when the script has completed and rejects when there is an error.
+ */
+function executeLifecycleScript( event, config, spinner ) {
+	if ( ! config.lifecycleScripts[ event ] ) {
+		return Promise.resolve();
+	}
+
+	return new Promise( ( resolve, reject ) => {
+		// We're going to append the script output to the spinner while it's executing.
+		const spinnerMessage = `Executing ${ event } Script`;
+		spinner.text = spinnerMessage;
+
+		// Execute the script asynchronously so that it won't block the spinner.
+		const childProc = exec( config.lifecycleScripts[ event ], {
+			encoding: 'utf-8',
+			stdio: 'pipe',
+			env: process.env,
+		} );
+
+		// Collect all of the output so that we can make use of it.
+		let output = '';
+		childProc.stdout.on( 'data', ( data ) => {
+			output += data;
+
+			// Keep the spinner updated with the command output.
+			spinner.text = `${ spinnerMessage }\n${ output }`;
+		} );
+
+		// Listen for any error output so we can display it if the command fails.
+		let error = '';
+		childProc.stderr.on( 'data', ( data ) => {
+			error += data;
+		} );
+
+		// Pass any process creation errors directly up.
+		childProc.on( 'error', reject );
+
+		// Handle the completion of the command based on whether it was successful or not.
+		childProc.on( 'exit', ( code ) => {
+			if ( code === 0 ) {
+				// Keep the output of the command in debug mode.
+				if ( config.debug ) {
+					spinner.info( `${ event } Script:\n${ output.trimEnd() }` );
+				}
+
+				resolve();
+				return;
+			}
+
+			reject( new LifecycleScriptError( event, error.trimEnd() ) );
+		} );
+	} );
+}
+
+module.exports = {
+	LifecycleScriptError,
+	executeLifecycleScript,
+};

package/lib/get-host-user.js

@@ -13,14 +13,10 @@ 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();
+	// we're just going to assign them to 1000. Docker Desktop already takes care of
+	// permission-related issues using magic, so this should be fine.
+	const uid = ( hostUser.uid === -1 ? 1000 : hostUser.uid ).toString();
+	const gid = ( hostUser.gid === -1 ? 1000 : hostUser.gid ).toString();
 
 	return {
 		name: hostUser.username,