@wordpress/env 7.0.0 → 8.0.0

package/lib/config/parse-config.js

@@ -14,7 +14,6 @@ const {
 } = require( './parse-source-string' );
 const {
 	ValidationError,
-	checkString,
 	checkPort,
 	checkStringArray,
 	checkObjectWithValues,
@@ -34,9 +33,13 @@ const mergeConfigs = require( './merge-configs' );
  * The root configuration options.
  *
  * @typedef WPRootConfigOptions
- * @property {number}      port       The port to use in the development environment.
- * @property {number}      testsPort  The port to use in the tests environment.
- * @property {string|null} afterSetup The command(s) to run after configuring WordPress on start and clean.
+ * @property {number}                               port                          The port to use in the development environment.
+ * @property {number}                               testsPort                     The port to use in the tests environment.
+ * @property {Object.<string, string|null>}         lifecycleScripts              The scripts to run at certain points in the command lifecycle.
+ * @property {Object.<string, string|null>}         lifecycleScripts.afterStart   The script to run after the "start" command has completed.
+ * @property {Object.<string, string|null>}         lifecycleScripts.afterClean   The script to run after the "clean" command has completed.
+ * @property {Object.<string, string|null>}         lifecycleScripts.afterDestroy The script to run after the "destroy" command has completed.
+ * @property {Object.<string, WPEnvironmentConfig>} env                           The environment-specific configuration options.
  */
 
 /**
@@ -69,6 +72,34 @@ const mergeConfigs = require( './merge-configs' );
  * @property {string}              basename Name that identifies the WordPress installation, plugin or theme.
  */
 
+/**
+ * An object containing all of the default configuration options for environment-specific configurations.
+ * Unless otherwise set at the root-level or the environment-level, these are the values that will be
+ * parsed into the environment. This is useful for tracking known configuration options since these
+ * are the only configuration options that can be set in each environment.
+ */
+const DEFAULT_ENVIRONMENT_CONFIG = {
+	core: null,
+	phpVersion: null,
+	plugins: [],
+	themes: [],
+	port: 8888,
+	testsPort: 8889,
+	mappings: {},
+	config: {
+		FS_METHOD: 'direct',
+		WP_DEBUG: true,
+		SCRIPT_DEBUG: true,
+		WP_ENVIRONMENT_TYPE: 'local',
+		WP_PHP_BINARY: 'php',
+		WP_TESTS_EMAIL: 'admin@example.org',
+		WP_TESTS_TITLE: 'Test Blog',
+		WP_TESTS_DOMAIN: 'localhost',
+		WP_SITEURL: 'http://localhost',
+		WP_HOME: 'http://localhost',
+	},
+};
+
 /**
  * Given a directory, this parses any relevant config files and
  * constructs an object in the format used internally.
@@ -164,9 +195,7 @@ async function getDefaultConfig(
 	configDirectoryPath,
 	{ shouldInferType, cacheDirectoryPath }
 ) {
-	// Our default config should try to infer what type of project
-	// this is in order to automatically map the current directory.
-	const detectedType = shouldInferType
+	const detectedDirectoryType = shouldInferType
 		? await detectDirectoryType( configDirectoryPath )
 		: null;
 
@@ -175,29 +204,40 @@ async function getDefaultConfig(
 	// config objects easier because once merged we don't need to
 	// verify that a given option exists before using it.
 	const rawConfig = {
-		core: detectedType === 'core' ? '.' : null,
-		phpVersion: null,
-		plugins: detectedType === 'plugin' ? [ '.' ] : [],
-		themes: detectedType === 'theme' ? [ '.' ] : [],
-		port: 8888,
-		testsPort: 8889,
-		mappings: {},
-		config: {
-			WP_DEBUG: true,
-			SCRIPT_DEBUG: true,
-			WP_ENVIRONMENT_TYPE: 'local',
-			WP_PHP_BINARY: 'php',
-			WP_TESTS_EMAIL: 'admin@example.org',
-			WP_TESTS_TITLE: 'Test Blog',
-			WP_TESTS_DOMAIN: 'localhost',
-			WP_SITEURL: 'http://localhost',
-			WP_HOME: 'http://localhost',
+		// Since the root config is the base "environment" config for
+		// all environments, we will start with those defaults.
+		...DEFAULT_ENVIRONMENT_CONFIG,
+
+		// When the current directory has no configuration file we support a zero-config mode of operation.
+		// This works by using the default options and inferring how to map the current directory based
+		// on the contents of the directory.
+		core:
+			detectedDirectoryType === 'core'
+				? '.'
+				: DEFAULT_ENVIRONMENT_CONFIG.core,
+		plugins:
+			detectedDirectoryType === 'plugin'
+				? [ '.' ]
+				: DEFAULT_ENVIRONMENT_CONFIG.plugins,
+		themes:
+			detectedDirectoryType === 'theme'
+				? [ '.' ]
+				: DEFAULT_ENVIRONMENT_CONFIG.themes,
+
+		// These configuration options are root-only and should not be present
+		// on environment-specific configuration objects.
+		lifecycleScripts: {
+			afterStart: null,
+			afterClean: null,
+			afterDestroy: null,
 		},
-		afterSetup: null,
 		env: {
 			development: {},
 			tests: {
-				config: { WP_DEBUG: false, SCRIPT_DEBUG: false },
+				config: {
+					WP_DEBUG: false,
+					SCRIPT_DEBUG: false,
+				},
 			},
 		},
 	};
@@ -220,6 +260,7 @@ function getEnvironmentVarOverrides( cacheDirectoryPath ) {
 	// Create a service config object so we can merge it with the others
 	// and override anything that the configuration options need to.
 	const overrideConfig = {
+		lifecycleScripts: overrides.lifecycleScripts,
 		env: {
 			development: {},
 			tests: {},
@@ -252,10 +293,6 @@ function getEnvironmentVarOverrides( cacheDirectoryPath ) {
 		overrideConfig.env.tests.phpVersion = overrides.phpVersion;
 	}
 
-	if ( overrides.afterSetup ) {
-		overrideConfig.afterSetup = overrides.afterSetup;
-	}
-
 	return overrideConfig;
 }
 
@@ -292,7 +329,10 @@ async function parseRootConfig( configFile, rawConfig, options ) {
 		configFile,
 		null,
 		rawConfig,
-		options
+		{
+			...options,
+			rootConfig: true,
+		}
 	);
 
 	// Parse any root-only options.
@@ -300,18 +340,28 @@ async function parseRootConfig( configFile, rawConfig, options ) {
 		checkPort( configFile, `testsPort`, rawConfig.testsPort );
 		parsedConfig.testsPort = rawConfig.testsPort;
 	}
-	if ( rawConfig.afterSetup !== undefined ) {
-		// Support null as a valid input.
-		if ( rawConfig.afterSetup !== null ) {
-			checkString( configFile, 'afterSetup', rawConfig.afterSetup );
-		}
-		parsedConfig.afterSetup = rawConfig.afterSetup;
+	parsedConfig.lifecycleScripts = {};
+	if ( rawConfig.lifecycleScripts ) {
+		checkObjectWithValues(
+			configFile,
+			'lifecycleScripts',
+			rawConfig.lifecycleScripts,
+			[ 'null', 'string' ],
+			true
+		);
+		parsedConfig.lifecycleScripts = rawConfig.lifecycleScripts;
 	}
 
 	// Parse the environment-specific configs so they're accessible to the root.
 	parsedConfig.env = {};
 	if ( rawConfig.env ) {
-		checkObjectWithValues( configFile, 'env', rawConfig.env, [ 'object' ] );
+		checkObjectWithValues(
+			configFile,
+			'env',
+			rawConfig.env,
+			[ 'object' ],
+			false
+		);
 		for ( const env in rawConfig.env ) {
 			parsedConfig.env[ env ] = await parseEnvironmentConfig(
 				configFile,
@@ -333,6 +383,7 @@ async function parseRootConfig( configFile, rawConfig, options ) {
  * @param {Object}      config                     A config object to parse.
  * @param {Object}      options
  * @param {string}      options.cacheDirectoryPath Path to the work directory located in ~/.wp-env.
+ * @param {boolean}     options.rootConfig         Indicates whether or not this is the root config object.
  *
  * @return {Promise<WPEnvironmentConfig>} The environment config object.
  */
@@ -348,6 +399,36 @@ async function parseEnvironmentConfig(
 
 	const environmentPrefix = environment ? environment + '.' : '';
 
+	// Before we move forward with parsing we should make sure that there aren't any
+	// configuration options that do not exist. This helps prevent silent failures
+	// when a user sets up their configuration incorrectly.
+	for ( const key in config ) {
+		if ( DEFAULT_ENVIRONMENT_CONFIG[ key ] !== undefined ) {
+			continue;
+		}
+
+		// We should also check root-only options for the root config
+		// because these aren't part of the above defaults but are
+		// configuration options that we will parse.
+		switch ( key ) {
+			case 'testsPort':
+			case 'lifecycleScripts':
+			case 'env': {
+				if ( options.rootConfig ) {
+					continue;
+				}
+
+				break;
+			}
+		}
+
+		throw new ValidationError(
+			`Invalid ${ configFile }: "${ environmentPrefix }${ key }" is not a configuration option.`
+		);
+	}
+
+	// Parse each option individually so that we can handle the validation
+	// and any conversion that is required to use the option.
 	const parsedConfig = {};
 
 	if ( config.port !== undefined ) {
@@ -401,7 +482,8 @@ async function parseEnvironmentConfig(
 			configFile,
 			`${ environmentPrefix }config`,
 			config.config,
-			[ 'string', 'number', 'boolean', 'empty' ]
+			[ 'string', 'number', 'boolean' ],
+			true
 		);
 		parsedConfig.config = config.config;
 
@@ -426,7 +508,8 @@ async function parseEnvironmentConfig(
 			configFile,
 			`${ environmentPrefix }mappings`,
 			config.mappings,
-			[ 'string' ]
+			[ 'string' ],
+			false
 		);
 		parsedConfig.mappings = Object.entries( config.mappings ).reduce(
 			( result, [ wpDir, localDir ] ) => {

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

@@ -59,9 +59,9 @@ function mergeRootToEnvironments( config ) {
 		config.env.tests.port = config.testsPort;
 		delete config.testsPort;
 	}
-	if ( config.afterSetup !== undefined ) {
-		removedRootOptions.afterSetup = config.afterSetup;
-		delete config.afterSetup;
+	if ( config.lifecycleScripts !== undefined ) {
+		removedRootOptions.lifecycleScripts = config.lifecycleScripts;
+		delete config.lifecycleScripts;
 	}
 
 	// Merge the root config and the environment configs together so that

package/lib/config/test/__snapshots__/config-integration.js.snap

@@ -2,13 +2,13 @@
 
 exports[`Config Integration should load local and override configuration files 1`] = `
 {
-  "afterSetup": null,
   "configDirectoryPath": "/test/gutenberg",
   "detectedLocalConfig": true,
   "dockerComposeConfigPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338/docker-compose.yml",
   "env": {
     "development": {
       "config": {
+        "FS_METHOD": "direct",
         "SCRIPT_DEBUG": true,
         "WP_DEBUG": true,
         "WP_ENVIRONMENT_TYPE": "local",
@@ -36,6 +36,7 @@ exports[`Config Integration should load local and override configuration files 1
     },
     "tests": {
       "config": {
+        "FS_METHOD": "direct",
         "SCRIPT_DEBUG": false,
         "WP_DEBUG": false,
         "WP_ENVIRONMENT_TYPE": "local",
@@ -62,6 +63,11 @@ exports[`Config Integration should load local and override configuration files 1
       "themeSources": [],
     },
   },
+  "lifecycleScripts": {
+    "afterClean": null,
+    "afterDestroy": "test",
+    "afterStart": null,
+  },
   "name": "gutenberg",
   "workDirectoryPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338",
 }
@@ -69,13 +75,13 @@ exports[`Config Integration should load local and override configuration files 1
 
 exports[`Config Integration should load local configuration file 1`] = `
 {
-  "afterSetup": "test",
   "configDirectoryPath": "/test/gutenberg",
   "detectedLocalConfig": true,
   "dockerComposeConfigPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338/docker-compose.yml",
   "env": {
     "development": {
       "config": {
+        "FS_METHOD": "direct",
         "SCRIPT_DEBUG": true,
         "WP_DEBUG": true,
         "WP_ENVIRONMENT_TYPE": "local",
@@ -103,6 +109,7 @@ exports[`Config Integration should load local configuration file 1`] = `
     },
     "tests": {
       "config": {
+        "FS_METHOD": "direct",
         "SCRIPT_DEBUG": false,
         "WP_DEBUG": false,
         "WP_ENVIRONMENT_TYPE": "local",
@@ -129,6 +136,11 @@ exports[`Config Integration should load local configuration file 1`] = `
       "themeSources": [],
     },
   },
+  "lifecycleScripts": {
+    "afterClean": null,
+    "afterDestroy": null,
+    "afterStart": "test",
+  },
   "name": "gutenberg",
   "workDirectoryPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338",
 }
@@ -136,13 +148,13 @@ exports[`Config Integration should load local configuration file 1`] = `
 
 exports[`Config Integration should use default configuration 1`] = `
 {
-  "afterSetup": null,
   "configDirectoryPath": "/test/gutenberg",
   "detectedLocalConfig": true,
   "dockerComposeConfigPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338/docker-compose.yml",
   "env": {
     "development": {
       "config": {
+        "FS_METHOD": "direct",
         "SCRIPT_DEBUG": true,
         "WP_DEBUG": true,
         "WP_ENVIRONMENT_TYPE": "local",
@@ -170,6 +182,7 @@ exports[`Config Integration should use default configuration 1`] = `
     },
     "tests": {
       "config": {
+        "FS_METHOD": "direct",
         "SCRIPT_DEBUG": false,
         "WP_DEBUG": false,
         "WP_ENVIRONMENT_TYPE": "local",
@@ -196,6 +209,11 @@ exports[`Config Integration should use default configuration 1`] = `
       "themeSources": [],
     },
   },
+  "lifecycleScripts": {
+    "afterClean": null,
+    "afterDestroy": null,
+    "afterStart": null,
+  },
   "name": "gutenberg",
   "workDirectoryPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338",
 }
@@ -203,13 +221,13 @@ exports[`Config Integration should use default configuration 1`] = `
 
 exports[`Config Integration should use environment variables over local and override configuration files 1`] = `
 {
-  "afterSetup": "test",
   "configDirectoryPath": "/test/gutenberg",
   "detectedLocalConfig": true,
   "dockerComposeConfigPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338/docker-compose.yml",
   "env": {
     "development": {
       "config": {
+        "FS_METHOD": "direct",
         "SCRIPT_DEBUG": true,
         "WP_DEBUG": true,
         "WP_ENVIRONMENT_TYPE": "local",
@@ -238,6 +256,7 @@ exports[`Config Integration should use environment variables over local and over
     },
     "tests": {
       "config": {
+        "FS_METHOD": "direct",
         "SCRIPT_DEBUG": false,
         "WP_DEBUG": false,
         "WP_ENVIRONMENT_TYPE": "local",
@@ -265,6 +284,11 @@ exports[`Config Integration should use environment variables over local and over
       "themeSources": [],
     },
   },
+  "lifecycleScripts": {
+    "afterClean": null,
+    "afterDestroy": null,
+    "afterStart": "test",
+  },
   "name": "gutenberg",
   "workDirectoryPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338",
 }

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

@@ -3,7 +3,6 @@
 /**
  * External dependencies
  */
-const path = require( 'path' );
 const { readFile } = require( 'fs' ).promises;
 
 /**
@@ -48,7 +47,7 @@ describe( 'Config Integration', () => {
 		delete process.env.WP_ENV_HOME;
 		delete process.env.WP_ENV_PORT;
 		delete process.env.WP_ENV_TESTS_PORT;
-		delete process.env.WP_ENV_AFTER_SETUP;
+		delete process.env.WP_ENV_LIFECYCLE_SCRIPT_AFTER_START;
 	} );
 
 	it( 'should use default configuration', async () => {
@@ -69,14 +68,18 @@ describe( 'Config Integration', () => {
 				return JSON.stringify( {
 					core: 'WordPress/WordPress#trunk',
 					port: 123,
-					afterSetup: 'test',
+					lifecycleScripts: {
+						afterStart: 'test',
+						afterClean: null,
+						afterDestroy: null,
+					},
 				} );
 			}
 
 			throw { code: 'ENOENT' };
 		} );
 
-		const config = await loadConfig( path.resolve( '/test/gutenberg' ) );
+		const config = await loadConfig( '/test/gutenberg' );
 
 		expect( config.env.development.port ).toEqual( 123 );
 		expect( config.env.tests.port ).toEqual( 8889 );
@@ -90,19 +93,29 @@ describe( 'Config Integration', () => {
 					core: 'WordPress/WordPress#trunk',
 					port: 123,
 					testsPort: 456,
+					lifecycleScripts: {
+						afterStart: 'test',
+						afterClean: null,
+						afterDestroy: null,
+					},
 				} );
 			}
 
 			if ( fileName === '/test/gutenberg/.wp-env.override.json' ) {
 				return JSON.stringify( {
 					port: 999,
+					lifecycleScripts: {
+						afterStart: null,
+						afterClean: null,
+						afterDestroy: 'test',
+					},
 				} );
 			}
 
 			throw { code: 'ENOENT' };
 		} );
 
-		const config = await loadConfig( path.resolve( '/test/gutenberg' ) );
+		const config = await loadConfig( '/test/gutenberg' );
 
 		expect( config.env.development.port ).toEqual( 999 );
 		expect( config.env.tests.port ).toEqual( 456 );
@@ -112,7 +125,7 @@ describe( 'Config Integration', () => {
 	it( 'should use environment variables over local and override configuration files', async () => {
 		process.env.WP_ENV_PORT = 12345;
 		process.env.WP_ENV_TESTS_PORT = 61234;
-		process.env.WP_ENV_AFTER_SETUP = 'test';
+		process.env.WP_ENV_LIFECYCLE_SCRIPT_AFTER_START = 'test';
 
 		readFile.mockImplementation( async ( fileName ) => {
 			if ( fileName === '/test/gutenberg/.wp-env.json' ) {
@@ -120,7 +133,11 @@ describe( 'Config Integration', () => {
 					core: 'WordPress/WordPress#trunk',
 					port: 123,
 					testsPort: 456,
-					afterSetup: 'local',
+					lifecycleScripts: {
+						afterStart: 'local',
+						afterClean: null,
+						afterDestroy: null,
+					},
 				} );
 			}
 
@@ -133,10 +150,14 @@ describe( 'Config Integration', () => {
 			throw { code: 'ENOENT' };
 		} );
 
-		const config = await loadConfig( path.resolve( '/test/gutenberg' ) );
+		const config = await loadConfig( '/test/gutenberg' );
 
 		expect( config.env.development.port ).toEqual( 12345 );
 		expect( config.env.tests.port ).toEqual( 61234 );
+		expect( config.lifecycleScripts ).toHaveProperty(
+			'afterStart',
+			'test'
+		);
 		expect( config ).toMatchSnapshot();
 	} );
 } );

package/lib/config/test/merge-configs.js

@@ -16,12 +16,18 @@ describe( 'mergeConfigs', () => {
 				config: {
 					WP_TEST: 'test',
 				},
+				lifecycleScripts: {
+					afterStart: 'test',
+				},
 			},
 			{
 				port: 8889,
 				config: {
 					WP_TEST_2: 'test-2',
 				},
+				lifecycleScripts: {
+					afterDestroy: 'test-2',
+				},
 			}
 		);
 
@@ -35,6 +41,10 @@ describe( 'mergeConfigs', () => {
 				WP_TEST: 'test',
 				WP_TEST_2: 'test-2',
 			},
+			lifecycleScripts: {
+				afterStart: 'test',
+				afterDestroy: 'test-2',
+			},
 		} );
 	} );