@wordpress/env 10.38.1-next.v.0 → 11.0.1-next.v.0

package/README.md

@@ -20,10 +20,39 @@ The database credentials are: user `root`, password `password`. For a comprehens
 
 `wp-env` relies on a few commonly used developer tools:
 
--   **Docker**. `wp-env` is powered by Docker. There are instructions available for installing Docker on [Windows](https://docs.docker.com/desktop/install/windows-install/) (we recommend the WSL2 backend), [macOS](https://docs.docker.com/docker-for-mac/install/), and [Linux](https://docs.docker.com/desktop/install/linux-install/).
+-   **Docker**. `wp-env` is powered by Docker by default. There are instructions available for installing Docker on [Windows](https://docs.docker.com/desktop/install/windows-install/) (we recommend the WSL2 backend), [macOS](https://docs.docker.com/docker-for-mac/install/), and [Linux](https://docs.docker.com/desktop/install/linux-install/).
 -   **Node.js**. `wp-env` is written as a Node script. We recommend using a Node version manager like [nvm](https://github.com/nvm-sh/nvm) to install the latest LTS version. Alternatively, you can [download it directly here](https://nodejs.org/en/download).
 -   **git**. Git is used for downloading software from source control, such as WordPress, plugins, and themes. [You can find the installation instructions here.](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
 
+## Experimental: WordPress Playground Runtime
+
+`wp-env` now supports an experimental alternative runtime using [WordPress Playground](https://wordpress.github.io/wordpress-playground/). Playground runs WordPress entirely in WebAssembly, eliminating the need for Docker.
+
+To use the Playground runtime:
+
+```sh
+$ wp-env start --runtime=playground
+```
+
+### Playground vs Docker
+
+| Feature | Docker | Playground |
+|---------|--------|------------|
+| Requires Docker | Yes | No |
+| Test environment | Yes | No |
+| Xdebug | Yes | Yes |
+| SPX profiling | Yes | No |
+| phpMyAdmin | Yes | No |
+| MySQL database | Yes | No (SQLite) |
+| Multisite | Yes | Yes |
+| Custom PHP version | Yes | Yes |
+| Plugin/theme mounting | Yes | Yes |
+| `wp-env run` command | Yes | No |
+
+The Playground runtime is ideal for quick testing or environments where Docker is unavailable. However, it lacks some features available in the Docker runtime, such as the tests environment and the `run` command for executing arbitrary commands.
+
+Once started with a runtime, wp-env will automatically detect and use the same runtime for subsequent commands (`stop`, `destroy`, etc.) until the environment is destroyed.
+
 ## Installation
 
 ### Installation as a global package
@@ -284,6 +313,9 @@ Options:
   --debug    Enable debug output.                     [boolean] [default: false]
   --update   Download source updates and apply WordPress configuration.
                                                       [boolean] [default: false]
+  --runtime  Select the runtime to use. "docker" uses Docker containers,
+             "playground" uses WordPress Playground (experimental).
+                                  [string] [choices: "docker", "playground"]
   --xdebug   Enables Xdebug. If not passed, Xdebug is turned off. If no modes
              are set, uses "debug". You may set multiple Xdebug modes by passing
              them in a comma-separated list: `--xdebug=develop,coverage`. See
@@ -466,16 +498,36 @@ Options:
   --watch    Watch for logs as they happen.            [boolean] [default: true]
 ```
 
-### `wp-env install-path`
+### `wp-env status`
 
-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.
+Get the status of the wp-env environment including whether it's running, URLs, ports, and configuration.
 
 Example:
 
 ```sh
-$ wp-env install-path
+$ wp-env status
+
+status: running
+    - runtime: docker
+    - install path: /home/user/.wp-env/63263e6506becb7b8613b02d42280a49
+    - config: /home/user/my-plugin
+
+environment:
+        - url: http://localhost:8888
+        - multisite: no
+        - xdebug: off
+        - http port: 8888
+        - mysql port: 13306
+        - test http port: 8889
+```
+
+```sh
+$ wp-env status --help
+Get the status of the wp-env environment including URLs, ports, and configuration.
 
-/home/user/.wp-env/63263e6506becb7b8613b02d42280a49
+Options:
+  --debug    Enable debug output.                      [boolean] [default: false]
+  --json     Output status as JSON.                    [boolean] [default: false]
 ```
 
 ## .wp-env.json

package/lib/cli.js

@@ -6,7 +6,6 @@ const chalk = require( 'chalk' );
 const ora = require( 'ora' );
 const yargs = require( 'yargs' );
 const terminalLink = require( 'terminal-link' );
-const { execSync } = require( 'child_process' );
 
 /**
  * Internal dependencies
@@ -16,9 +15,10 @@ const env = require( './env' );
 const parseXdebugMode = require( './parse-xdebug-mode' );
 const parseSpxMode = require( './parse-spx-mode' );
 const {
-	RUN_CONTAINERS,
-	validateRunContainer,
-} = require( './validate-run-container' );
+	getAvailableRuntimes,
+	getRuntime,
+	UnsupportedCommandError,
+} = require( './runtime' );
 
 // Colors.
 const boldWhite = chalk.bold.white;
@@ -45,7 +45,11 @@ const withSpinner =
 				process.exit( 0 );
 			},
 			( error ) => {
-				if (
+				if ( error instanceof UnsupportedCommandError ) {
+					// Error is an unsupported command in the current runtime.
+					spinner.fail( error.message );
+					process.exit( 1 );
+				} else if (
 					error instanceof env.ValidationError ||
 					error instanceof env.LifecycleScriptError
 				) {
@@ -87,16 +91,6 @@ const withSpinner =
 	};
 
 module.exports = function cli() {
-	// Do nothing if Docker is unavailable.
-	try {
-		execSync( 'docker info', { stdio: 'ignore' } );
-	} catch {
-		console.error(
-			chalk.red( 'Could not connect to Docker. Is it running?' )
-		);
-		process.exit( 1 );
-	}
-
 	yargs.usage( wpPrimary( '$0 <command>' ) );
 	yargs.option( 'debug', {
 		type: 'boolean',
@@ -150,6 +144,13 @@ module.exports = function cli() {
 				describe: 'Execute any configured lifecycle scripts.',
 				default: true,
 			} );
+			args.option( 'runtime', {
+				type: 'string',
+				describe:
+					'The runtime environment to use. "docker" uses Docker containers, "playground" uses WordPress Playground (experimental).',
+				choices: getAvailableRuntimes(),
+				default: 'docker',
+			} );
 		},
 		withSpinner( env.start )
 	);
@@ -201,6 +202,10 @@ module.exports = function cli() {
 		'$0 logs --no-watch --environment=tests',
 		'Displays the latest logs for the e2e test environment without watching.'
 	);
+	// Get run containers from Docker runtime (run command is Docker-only for now)
+	const dockerRuntime = getRuntime( 'docker' );
+	const runContainers = dockerRuntime.getRunContainers();
+
 	yargs.command(
 		'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.',
@@ -216,8 +221,7 @@ module.exports = function cli() {
 				type: 'string',
 				describe:
 					'The underlying Docker service to run the command on.',
-				choices: RUN_CONTAINERS,
-				coerce: validateRunContainer,
+				choices: runContainers,
 			} );
 			args.positional( 'command', {
 				type: 'array',
@@ -254,10 +258,16 @@ module.exports = function cli() {
 		withSpinner( env.destroy )
 	);
 	yargs.command(
-		'install-path',
-		'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 )
+		'status',
+		'Get the status of the wp-env environment including URLs, ports, and configuration.',
+		( args ) => {
+			args.option( 'json', {
+				type: 'boolean',
+				describe: 'Output status as JSON.',
+				default: false,
+			} );
+		},
+		withSpinner( env.status )
 	);
 
 	return yargs;

package/lib/commands/clean.js

@@ -2,14 +2,14 @@
 /**
  * External dependencies
  */
-const { v2: dockerCompose } = require( 'docker-compose' );
+const path = require( 'path' );
 
 /**
  * Internal dependencies
  */
-const initConfig = require( '../init-config' );
-const { configureWordPress, resetDatabase } = require( '../wordpress' );
 const { executeLifecycleScript } = require( '../execute-lifecycle-script' );
+const { loadConfig } = require( '../config' );
+const { getRuntime, detectRuntime } = require( '../runtime' );
 
 /**
  * @typedef {import('../wordpress').WPEnvironment} WPEnvironment
@@ -31,43 +31,12 @@ module.exports = async function clean( {
 	scripts,
 	debug,
 } ) {
-	const config = await initConfig( { spinner, debug } );
+	const config = await loadConfig( path.resolve( '.' ) );
+	const runtime = getRuntime( detectRuntime( config.workDirectoryPath ) );
 
-	const description = `${ environment } environment${
-		environment === 'all' ? 's' : ''
-	}`;
-	spinner.text = `Cleaning ${ description }.`;
-
-	const tasks = [];
-
-	// Start the database first to avoid race conditions where all tasks create
-	// different docker networks with the same name.
-	await dockerCompose.upOne( 'mysql', {
-		config: config.dockerComposeConfigPath,
-		log: config.debug,
-	} );
-
-	if ( environment === 'all' || environment === 'development' ) {
-		tasks.push(
-			resetDatabase( 'development', config )
-				.then( () => configureWordPress( 'development', config ) )
-				.catch( () => {} )
-		);
-	}
-
-	if ( environment === 'all' || environment === 'tests' ) {
-		tasks.push(
-			resetDatabase( 'tests', config )
-				.then( () => configureWordPress( 'tests', config ) )
-				.catch( () => {} )
-		);
-	}
-
-	await Promise.all( tasks );
+	await runtime.clean( config, { environment, spinner, debug } );
 
 	if ( scripts ) {
 		await executeLifecycleScript( 'afterClean', config, spinner );
 	}
-
-	spinner.text = `Cleaned ${ description }.`;
 };

package/lib/commands/destroy.js

@@ -2,21 +2,16 @@
 /**
  * External dependencies
  */
-const { v2: dockerCompose } = require( 'docker-compose' );
 const fs = require( 'fs' ).promises;
 const path = require( 'path' );
 const { confirm } = require( '@inquirer/prompts' );
 
-/**
- * Promisified dependencies
- */
-const { rimraf } = require( 'rimraf' );
-
 /**
  * Internal dependencies
  */
 const { loadConfig } = require( '../config' );
 const { executeLifecycleScript } = require( '../execute-lifecycle-script' );
+const { getRuntime, detectRuntime } = require( '../runtime' );
 
 /**
  * Destroy the development server.
@@ -36,9 +31,9 @@ module.exports = async function destroy( { spinner, scripts, debug } ) {
 		return;
 	}
 
-	spinner.info(
-		'WARNING! This will remove Docker containers, volumes, networks, and images associated with the WordPress instance.'
-	);
+	const runtime = getRuntime( detectRuntime( config.workDirectoryPath ) );
+
+	spinner.info( runtime.getDestroyWarningMessage() );
 
 	let yesDelete = false;
 	try {
@@ -61,24 +56,9 @@ module.exports = async function destroy( { spinner, scripts, debug } ) {
 		return;
 	}
 
-	spinner.text = 'Removing docker images, volumes, and networks.';
-
-	await dockerCompose.down( {
-		config: config.dockerComposeConfigPath,
-		commandOptions: [ '--volumes', '--remove-orphans', '--rmi', 'all' ],
-		log: debug,
-	} );
-
-	spinner.text = 'Removing local files.';
-	// 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 );
+	await runtime.destroy( config, { spinner, debug } );
 
 	if ( scripts ) {
 		await executeLifecycleScript( 'afterDestroy', config, spinner );
 	}
-
-	spinner.text = 'Removed WordPress environment.';
 };

package/lib/commands/index.js

@@ -8,7 +8,7 @@ const clean = require( './clean' );
 const run = require( './run' );
 const destroy = require( './destroy' );
 const logs = require( './logs' );
-const installPath = require( './install-path' );
+const status = require( './status' );
 
 module.exports = {
 	start,
@@ -17,5 +17,5 @@ module.exports = {
 	run,
 	destroy,
 	logs,
-	installPath,
+	status,
 };

package/lib/commands/logs.js

@@ -2,12 +2,13 @@
 /**
  * External dependencies
  */
-const { v2: dockerCompose } = require( 'docker-compose' );
+const path = require( 'path' );
 
 /**
  * Internal dependencies
  */
-const initConfig = require( '../init-config' );
+const { loadConfig } = require( '../config' );
+const { getRuntime, detectRuntime } = require( '../runtime' );
 
 /**
  * Displays the Docker & PHP logs on the given environment.
@@ -19,59 +20,7 @@ const initConfig = require( '../init-config' );
  * @param {boolean} options.debug       True if debug mode is enabled.
  */
 module.exports = async function logs( { environment, watch, spinner, debug } ) {
-	const config = await initConfig( { spinner, debug } );
-
-	// If we show text while watching the logs, it will continue showing up every
-	// few lines in the logs as they happen, which isn't a good look. So only
-	// show the message if we are not watching the logs.
-	if ( ! watch ) {
-		spinner.text = `Showing logs for the ${ environment } environment.`;
-	}
-
-	const servicesToWatch =
-		environment === 'all'
-			? [ 'tests-wordpress', 'wordpress' ]
-			: [ environment === 'tests' ? 'tests-wordpress' : 'wordpress' ];
-
-	const output = await Promise.all( [
-		...servicesToWatch.map( ( service ) =>
-			dockerCompose.logs( service, {
-				config: config.dockerComposeConfigPath,
-				log: watch, // Must log inline if we are watching the log output.
-				commandOptions: watch ? [ '--follow' ] : [],
-			} )
-		),
-	] );
-
-	// Combine the results from each docker output.
-	const result = output.reduce(
-		( acc, current ) => {
-			if ( current.out ) {
-				acc.out = acc.out.concat( current.out );
-			}
-			if ( current.err ) {
-				acc.err = acc.err.concat( current.err );
-			}
-			if ( current.exitCode !== 0 ) {
-				acc.hasNon0ExitCode = true;
-			}
-			return acc;
-		},
-		{ out: '', err: '', hasNon0ExitCode: false }
-	);
-
-	if ( result.out.length ) {
-		console.log(
-			process.stdout.isTTY ? `\n\n${ result.out }\n\n` : result.out
-		);
-	} else if ( result.err.length ) {
-		console.error(
-			process.stdout.isTTY ? `\n\n${ result.err }\n\n` : result.err
-		);
-		if ( result.hasNon0ExitCode ) {
-			throw result.err;
-		}
-	}
-
-	spinner.text = 'Finished showing logs.';
+	const config = await loadConfig( path.resolve( '.' ) );
+	const runtime = getRuntime( detectRuntime( config.workDirectoryPath ) );
+	await runtime.logs( config, { environment, watch, spinner, debug } );
 };

package/lib/commands/run.js

@@ -2,18 +2,13 @@
 /**
  * External dependencies
  */
-const { spawn } = require( 'child_process' );
 const path = require( 'path' );
 
 /**
  * Internal dependencies
  */
-const initConfig = require( '../init-config' );
-const getHostUser = require( '../get-host-user' );
-
-/**
- * @typedef {import('../config').WPConfig} WPConfig
- */
+const { loadConfig } = require( '../config' );
+const { getRuntime, detectRuntime } = require( '../runtime' );
 
 /**
  * Runs an arbitrary command on the given Docker container.
@@ -34,7 +29,8 @@ module.exports = async function run( {
 	spinner,
 	debug,
 } ) {
-	const config = await initConfig( { spinner, debug } );
+	const config = await loadConfig( path.resolve( '.' ) );
+	const runtime = getRuntime( detectRuntime( config.workDirectoryPath ) );
 
 	// 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.
@@ -42,106 +38,5 @@ module.exports = async function run( {
 		command.push( ...doubleDashedArgs );
 	}
 
-	// Shows a contextual tip for the given command.
-	const joinedCommand = command.join( ' ' );
-	showCommandTips( joinedCommand, container, spinner );
-
-	await spawnCommandDirectly( config, container, command, envCwd, spinner );
-
-	spinner.text = `Ran \`${ joinedCommand }\` in '${ container }'.`;
+	await runtime.run( config, { container, command, envCwd, spinner, debug } );
 };
-
-/**
- * Runs an arbitrary command on the given Docker container.
- *
- * @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}   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 ) {
-	// 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',
-		// Remove spaces and single quotes from both ends of the path.
-		// This is needed because Windows treats single quotes as a literal character.
-		envCwd.trim().replace( /^'|'$/g, '' )
-	);
-
-	const composeCommand = [
-		'compose',
-		'-f',
-		config.dockerComposeConfigPath,
-		'exec',
-		'-w',
-		envCwd,
-		'--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-
-		// compose on the CLI directly.
-		const childProc = spawn(
-			'docker',
-			composeCommand,
-			{ stdio: 'inherit' },
-			spinner
-		);
-		childProc.on( 'error', reject );
-		childProc.on( 'exit', ( code ) => {
-			// Code 130 is set if the user tries to exit with ctrl-c before using
-			// ctrl-d (so it is not an error which should fail the script.)
-			if ( code === 0 || code === 130 ) {
-				resolve();
-			} else {
-				reject( `Command failed with exit code ${ code }` );
-			}
-		} );
-	} );
-}
-
-/**
- * This shows a contextual tip for the command being run. Certain commands (like
- * 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} 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( joinedCommand, container, spinner ) {
-	if ( ! joinedCommand.length ) {
-		return;
-	}
-
-	const tip = `Starting '${ joinedCommand }' on the ${ container } container. ${ ( () => {
-		switch ( joinedCommand ) {
-			case 'bash':
-				return 'Exit bash with ctrl-d.';
-			case 'wp shell':
-				return 'Exit the WordPress shell with ctrl-c.';
-			default:
-				return '';
-		}
-	} )() }\n`;
-	spinner.info( tip );
-}