New playground CLI function interface (#40)

## Motivation for the change, related issues
Details here:
https://playgroundp2.wordpress.com/2025/02/11/studio-php-execution-in-playground-cli-child-process/

## Implementation details
The PR adds the new `runCLI` function that exports the `Express` server
and the `PHPRequestHandler`.

The caller then can access to the `PHP` object as well as start/stop the
server by doing, for example:
```javascript
const res = runCLI( { command: 'server', ... } );

res.server.close( () => {
	res.requestHandler.getPrimaryPhp().exit();
} );
```

## Testing Instructions (or ideally a Blueprint)
Ensure this is still working with various flags passed:
```
bun ./packages/playground/cli/src/cli.ts server
```
Then build the package using `npm run build` and check if the
`dist/packages/playground/cli/index.js` file exists with a `runCLI`
exported.

Author: zaerl

packages/playground/cli/src/cli.ts

@@ -1,35 +1,11 @@
+import { SupportedPHPVersions } from '@php-wasm/universal';
+import { RecommendedPHPVersion } from '@wp-playground/common';
 import fs from 'fs';
 import path from 'path';
 import yargs from 'yargs';
-import readline from 'readline';
-import { startServer } from './server';
-import {
-	PHP,
-	PHPRequest,
-	PHPRequestHandler,
-	PHPResponse,
-	SupportedPHPVersion,
-	SupportedPHPVersions,
-} from '@php-wasm/universal';
-import { logger, errorLogPath } from '@php-wasm/logger';
-import {
-	Blueprint,
-	compileBlueprint,
-	runBlueprintSteps,
-} from '@wp-playground/blueprints';
 import { isValidWordPressSlug } from './is-valid-wordpress-slug';
-import { EmscriptenDownloadMonitor, ProgressTracker } from '@php-wasm/progress';
-import { createNodeFsMountHandler, loadNodeRuntime } from '@php-wasm/node';
-import { RecommendedPHPVersion, zipDirectory } from '@wp-playground/common';
-import { bootWordPress } from '@wp-playground/wordpress';
-import { rootCertificates } from 'tls';
-import {
-	CACHE_FOLDER,
-	cachedDownload,
-	fetchSqliteIntegration,
-	readAsFile,
-} from './download';
-import { resolveWordPressRelease } from '@wp-playground/wordpress';
+import { runCLI, RunCLIArgs } from './run-cli';
+
 export interface Mount {
 	hostPath: string;
 	vfsPath: string;
@@ -40,12 +16,12 @@ async function run() {
 	 * @TODO This looks similar to Query API args https://wordpress.github.io/wordpress-playground/developers/apis/query-api/
 	 *       Perhaps the two could be handled by the same code?
 	 */
-	const yargsObject = await yargs(process.argv.slice(2))
+	const yargsObject = yargs(process.argv.slice(2))
 		.usage('Usage: wp-playground <command> [options]')
 		.positional('command', {
 			describe: 'Command to run',
-			type: 'string',
-			choices: ['server', 'run-blueprint', 'build-snapshot'],
+			choices: ['server', 'run-blueprint', 'build-snapshot'] as const,
+			demandOption: true,
 		})
 		.option('outfile', {
 			describe: 'When building, write to this output file.',
@@ -142,269 +118,16 @@ async function run() {
 	yargsObject.wrap(yargsObject.terminalWidth());
 	const args = await yargsObject.argv;
 
-	if (args.quiet) {
-		// @ts-ignore
-		logger.handlers = [];
-	}
-
-	/**
-	 * TODO: This exact feature will be provided in the PHP Blueprints library.
-	 *       Let's use it when it ships. Let's also use it in the web Playground
-	 *       app.
-	 */
-	async function zipSite(outfile: string) {
-		// Fake URL for the build
-		const { php, reap } =
-			await requestHandler.processManager.acquirePHPInstance();
-		try {
-			await php.run({
-				code: `<?php
-				$zip = new ZipArchive();
-				if(false === $zip->open('/tmp/build.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE)) {
-					throw new Exception('Failed to create ZIP');
-				}
-				$files = new RecursiveIteratorIterator(
-					new RecursiveDirectoryIterator('/wordpress')
-				);
-				foreach ($files as $file) {
-					echo $file . PHP_EOL;
-					if (!$file->isFile()) {
-						continue;
-					}
-					$zip->addFile($file->getPathname(), $file->getPathname());
-				}
-				$zip->close();
-
-			`,
-			});
-			const zip = php.readFileAsBuffer('/tmp/build.zip');
-			fs.writeFileSync(outfile, zip);
-		} finally {
-			reap();
-		}
-	}
-
-	function mountResources(php: PHP, rawMounts: string[]) {
-		const parsedMounts = rawMounts.map((mount) => {
-			const [source, vfsPath] = mount.split(':');
-			return {
-				hostPath: path.resolve(process.cwd(), source),
-				vfsPath,
-			};
-		});
-		for (const mount of parsedMounts) {
-			php.mkdir(mount.vfsPath);
-			php.mount(mount.vfsPath, createNodeFsMountHandler(mount.hostPath));
-		}
-	}
-
-	function compileInputBlueprint() {
-		/**
-		 * @TODO This looks similar to the resolveBlueprint() call in the website package:
-		 * 	     https://github.com/WordPress/wordpress-playground/blob/ce586059e5885d185376184fdd2f52335cca32b0/packages/playground/website/src/main.tsx#L41
-		 *
-		 * 		 Also the Blueprint Builder tool does something similar.
-		 *       Perhaps all these cases could be handled by the same function?
-		 */
-		let blueprint: Blueprint | undefined;
-		if (args.blueprint) {
-			blueprint = args.blueprint as Blueprint;
-		} else {
-			blueprint = {
-				preferredVersions: {
-					php: args.php as SupportedPHPVersion,
-					wp: args.wp,
-				},
-				login: args.login,
-			};
-		}
-
-		const tracker = new ProgressTracker();
-		let lastCaption = '';
-		let progress100 = false;
-		tracker.addEventListener('progress', (e: any) => {
-			if (progress100) {
-				return;
-			} else if (e.detail.progress === 100) {
-				progress100 = true;
-			}
-			lastCaption =
-				e.detail.caption || lastCaption || 'Running the Blueprint';
-			readline.clearLine(process.stdout, 0);
-			readline.cursorTo(process.stdout, 0);
-			process.stdout.write(
-				'\r\x1b[K' + `${lastCaption.trim()} – ${e.detail.progress}%`
-			);
-			if (progress100) {
-				process.stdout.write('\n');
-			}
-		});
-		return compileBlueprint(blueprint as Blueprint, {
-			progress: tracker,
-		});
-	}
-
 	const command = args._[0] as string;
+
 	if (!['run-blueprint', 'server', 'build-snapshot'].includes(command)) {
 		yargsObject.showHelp();
 		process.exit(1);
 	}
 
-	const compiledBlueprint = compileInputBlueprint();
-
-	let requestHandler: PHPRequestHandler;
-	let wordPressReady = false;
+	args.command = args._[0] as any;
 
-	logger.log('Starting a PHP server...');
-
-	startServer({
-		port: args['port'] as number,
-		onBind: async (port: number) => {
-			const absoluteUrl = `http://127.0.0.1:${port}`;
-
-			logger.log(`Setting up WordPress ${args.wp}`);
-			let wpDetails: any = undefined;
-			const monitor = new EmscriptenDownloadMonitor();
-			if (!args.skipWordPressSetup) {
-				// @TODO: Rename to FetchProgressMonitor. There's nothing Emscripten
-				// about that class anymore.
-				monitor.addEventListener('progress', ((
-					e: CustomEvent<ProgressEvent & { finished: boolean }>
-				) => {
-					// @TODO Every progres bar will want percentages. The
-					//       download monitor should just provide that.
-					const percentProgress = Math.round(
-						Math.min(100, (100 * e.detail.loaded) / e.detail.total)
-					);
-					if (!args.quiet) {
-						readline.clearLine(process.stdout, 0);
-						readline.cursorTo(process.stdout, 0);
-						process.stdout.write(
-							`Downloading WordPress ${percentProgress}%...`
-						);
-					}
-				}) as any);
-
-				wpDetails = await resolveWordPressRelease(args.wp);
-			}
-			logger.log(
-				`Resolved WordPress release URL: ${wpDetails?.releaseUrl}`
-			);
-
-			const preinstalledWpContentPath =
-				wpDetails &&
-				path.join(
-					CACHE_FOLDER,
-					`prebuilt-wp-content-for-wp-${wpDetails.version}.zip`
-				);
-			const wordPressZip = !wpDetails
-				? undefined
-				: fs.existsSync(preinstalledWpContentPath)
-				? readAsFile(preinstalledWpContentPath)
-				: await cachedDownload(
-						wpDetails.releaseUrl,
-						`${wpDetails.version}.zip`,
-						monitor
-				  );
-
-			const constants: Record<string, string | number | boolean | null> =
-				{
-					WP_DEBUG: true,
-					WP_DEBUG_LOG: true,
-					WP_DEBUG_DISPLAY: false,
-				};
-
-			logger.log(`Booting WordPress...`);
-			requestHandler = await bootWordPress({
-				siteUrl: absoluteUrl,
-				createPhpRuntime: async () =>
-					await loadNodeRuntime(compiledBlueprint.versions.php),
-				wordPressZip,
-				sqliteIntegrationPluginZip: fetchSqliteIntegration(monitor),
-				sapiName: 'cli',
-				createFiles: {
-					'/internal/shared/ca-bundle.crt':
-						rootCertificates.join('\n'),
-				},
-				constants,
-				phpIniEntries: {
-					'openssl.cafile': '/internal/shared/ca-bundle.crt',
-					allow_url_fopen: '1',
-					disable_functions: '',
-				},
-				hooks: {
-					async beforeWordPressFiles(php) {
-						if (args.mountBeforeInstall) {
-							mountResources(php, args.mountBeforeInstall);
-						}
-					},
-				},
-			});
-			logger.log(`Booted!`);
-
-			const php = await requestHandler.getPrimaryPhp();
-			try {
-				if (
-					wpDetails &&
-					!args.mountBeforeInstall &&
-					!fs.existsSync(preinstalledWpContentPath)
-				) {
-					logger.log(
-						`Caching preinstalled WordPress for the next boot...`
-					);
-					fs.writeFileSync(
-						preinstalledWpContentPath,
-						await zipDirectory(php, '/wordpress')
-					);
-					logger.log(`Cached!`);
-				}
-
-				if (args.mount) {
-					mountResources(php, args.mount);
-				}
-
-				wordPressReady = true;
-
-				if (compiledBlueprint) {
-					const { php, reap } =
-						await requestHandler.processManager.acquirePHPInstance();
-					try {
-						logger.log(`Running the Blueprint...`);
-						await runBlueprintSteps(compiledBlueprint, php);
-						logger.log(`Finished running the blueprint`);
-					} finally {
-						reap();
-					}
-				}
-
-				if (command === 'build-snapshot') {
-					await zipSite(args.outfile as string);
-					logger.log(`WordPress exported to ${args.outfile}`);
-					process.exit(0);
-				} else if (command === 'run-blueprint') {
-					logger.log(`Blueprint executed`);
-					process.exit(0);
-				} else {
-					logger.log(`WordPress is running on ${absoluteUrl}`);
-				}
-			} catch (error) {
-				if (!args.debug) {
-					throw error;
-				}
-				const phpLogs = php.readFileAsText(errorLogPath);
-				throw new Error(phpLogs, { cause: error });
-			}
-		},
-		async handleRequest(request: PHPRequest) {
-			if (!wordPressReady) {
-				return PHPResponse.forHttpCode(
-					502,
-					'WordPress is not ready yet'
-				);
-			}
-			return await requestHandler.request(request);
-		},
-	});
+	return runCLI(args as RunCLIArgs);
 }
 
 run();

packages/playground/cli/src/index.ts

@@ -0,0 +1 @@
+export * from './run-cli';