[Playground CLI] Separate Blueprints v1 and Blueprints v2 code paths (#2396)

## Motivation for the change, related issues

Reorganizes Playground CLI code:

* `src/blueprints-v1` has all the code specific to Blueprints v1
* `src/blueprints-v2` has all the code specific to Blueprints v2
* `tests` has all the unit tests

No other changes are made

## Testing Instructions (or ideally a Blueprint)

Confirm the CI checks pass.

Author: adamziel

.github/workflows/ci.yml

@@ -293,7 +293,7 @@ jobs:
               with:
                   submodules: true
             - uses: ./.github/actions/prepare-playground
-            - run: packages/playground/cli/src/test/test-running-unbuilt-cli.sh
+            - run: packages/playground/cli/tests/test-running-unbuilt-cli.sh
 
     build:
         runs-on: ubuntu-latest

packages/playground/cli/src/blueprints-v1/blueprints-v1-handler.ts

@@ -0,0 +1,292 @@
+import { logger } from '@php-wasm/logger';
+import { EmscriptenDownloadMonitor, ProgressTracker } from '@php-wasm/progress';
+import type { SupportedPHPVersion } from '@php-wasm/universal';
+import { consumeAPI } from '@php-wasm/universal';
+import type {
+	BlueprintBundle,
+	BlueprintDeclaration,
+} from '@wp-playground/blueprints';
+import { compileBlueprint, isBlueprintBundle } from '@wp-playground/blueprints';
+import { RecommendedPHPVersion, zipDirectory } from '@wp-playground/common';
+import fs from 'fs';
+import path from 'path';
+import { resolveWordPressRelease } from '@wp-playground/wordpress';
+import {
+	CACHE_FOLDER,
+	cachedDownload,
+	fetchSqliteIntegration,
+	readAsFile,
+} from './download';
+import type { PlaygroundCliBlueprintV1Worker } from './worker-thread-v1';
+// @ts-ignore
+import importedWorkerV1UrlString from './worker-thread-v1?worker&url';
+import type { MessagePort as NodeMessagePort } from 'worker_threads';
+import type { RunCLIArgs, SpawnedWorker } from '../run-cli';
+
+/**
+ * Boots Playground CLI workers using Blueprint version 1.
+ *
+ * Progress tracking, downloads, steps, and all other features are
+ * implemented in TypeScript and orchestrated by this class.
+ */
+export class BlueprintsV1Handler {
+	private phpVersion: SupportedPHPVersion | undefined;
+	private lastProgressMessage = '';
+
+	private siteUrl: string;
+	private processIdSpaceLength: number;
+	private args: RunCLIArgs;
+
+	constructor(
+		args: RunCLIArgs,
+		options: {
+			siteUrl: string;
+			processIdSpaceLength: number;
+		}
+	) {
+		this.args = args;
+		this.siteUrl = options.siteUrl;
+		this.processIdSpaceLength = options.processIdSpaceLength;
+	}
+
+	getWorkerUrl() {
+		return importedWorkerV1UrlString;
+	}
+
+	async bootPrimaryWorker(
+		phpPort: NodeMessagePort,
+		fileLockManagerPort: NodeMessagePort
+	) {
+		const compiledBlueprint = await this.compileInputBlueprint(
+			this.args['additional-blueprint-steps'] || []
+		);
+		this.phpVersion = compiledBlueprint.versions.php;
+
+		let wpDetails: any = undefined;
+		// @TODO: Rename to FetchProgressMonitor. There's nothing Emscripten
+		// about that class anymore.
+		const monitor = new EmscriptenDownloadMonitor();
+		if (!this.args.skipWordPressSetup) {
+			let progressReached100 = false;
+			monitor.addEventListener('progress', ((
+				e: CustomEvent<ProgressEvent & { finished: boolean }>
+			) => {
+				if (progressReached100) {
+					return;
+				}
+
+				// @TODO Every progress bar will want percentages. The
+				//       download monitor should just provide that.
+				const { loaded, total } = e.detail;
+				// Use floor() so we don't report 100% until truly there.
+				const percentProgress = Math.floor(
+					Math.min(100, (100 * loaded) / total)
+				);
+				progressReached100 = percentProgress === 100;
+
+				if (!this.args.quiet) {
+					this.writeProgressUpdate(
+						process.stdout,
+						`Downloading WordPress ${percentProgress}%...`,
+						progressReached100
+					);
+				}
+			}) as any);
+
+			wpDetails = await resolveWordPressRelease(this.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
+			  );
+
+		logger.log(`Fetching SQLite integration plugin...`);
+		const sqliteIntegrationPluginZip = this.args.skipSqliteSetup
+			? undefined
+			: await fetchSqliteIntegration(monitor);
+
+		const followSymlinks = this.args.followSymlinks === true;
+		const trace = this.args.experimentalTrace === true;
+
+		const mountsBeforeWpInstall = this.args['mount-before-install'] || [];
+		const mountsAfterWpInstall = this.args.mount || [];
+
+		const playground = consumeAPI<PlaygroundCliBlueprintV1Worker>(phpPort);
+
+		// Comlink communication proxy
+		await playground.isConnected();
+
+		logger.log(`Booting WordPress...`);
+
+		await playground.useFileLockManager(fileLockManagerPort);
+		await playground.bootAsPrimaryWorker({
+			phpVersion: this.phpVersion,
+			wpVersion: compiledBlueprint.versions.wp,
+			absoluteUrl: this.siteUrl,
+			mountsBeforeWpInstall,
+			mountsAfterWpInstall,
+			wordPressZip: wordPressZip && (await wordPressZip!.arrayBuffer()),
+			sqliteIntegrationPluginZip:
+				await sqliteIntegrationPluginZip!.arrayBuffer(),
+			firstProcessId: 0,
+			processIdSpaceLength: this.processIdSpaceLength,
+			followSymlinks,
+			trace,
+			internalCookieStore: this.args.internalCookieStore,
+			withXdebug: this.args.xdebug,
+		});
+
+		if (
+			wpDetails &&
+			!this.args['mount-before-install'] &&
+			!fs.existsSync(preinstalledWpContentPath)
+		) {
+			logger.log(`Caching preinstalled WordPress for the next boot...`);
+			fs.writeFileSync(
+				preinstalledWpContentPath,
+				(await zipDirectory(playground, '/wordpress'))!
+			);
+			logger.log(`Cached!`);
+		}
+
+		return playground;
+	}
+
+	async bootSecondaryWorker({
+		worker,
+		fileLockManagerPort,
+		firstProcessId,
+	}: {
+		worker: SpawnedWorker;
+		fileLockManagerPort: NodeMessagePort;
+		firstProcessId: number;
+	}) {
+		const additionalPlayground = consumeAPI<PlaygroundCliBlueprintV1Worker>(
+			worker.phpPort
+		);
+
+		await additionalPlayground.isConnected();
+		await additionalPlayground.useFileLockManager(fileLockManagerPort);
+		await additionalPlayground.bootAsSecondaryWorker({
+			phpVersion: this.phpVersion,
+			absoluteUrl: this.siteUrl,
+			mountsBeforeWpInstall: this.args['mount-before-install'] || [],
+			mountsAfterWpInstall: this.args['mount'] || [],
+			// Skip WordPress zip because we share the /wordpress directory
+			// populated by the initial worker.
+			wordPressZip: undefined,
+			// Skip SQLite integration plugin for now because we
+			// will copy it from primary's `/internal` directory.
+			sqliteIntegrationPluginZip: undefined,
+			dataSqlPath: '/wordpress/wp-content/database/.ht.sqlite',
+			firstProcessId,
+			processIdSpaceLength: this.processIdSpaceLength,
+			followSymlinks: this.args.followSymlinks === true,
+			trace: this.args.experimentalTrace === true,
+			// @TODO: Move this to the request handler or else every worker
+			//        will have a separate cookie store.
+			internalCookieStore: this.args.internalCookieStore,
+			withXdebug: this.args.xdebug,
+		});
+		await additionalPlayground.isReady();
+		return additionalPlayground;
+	}
+
+	async compileInputBlueprint(additionalBlueprintSteps: any[]) {
+		const args = this.args;
+		const resolvedBlueprint = args.blueprint as BlueprintDeclaration;
+		/**
+		 * @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?
+		 */
+		const blueprint: BlueprintDeclaration | BlueprintBundle =
+			isBlueprintBundle(resolvedBlueprint)
+				? resolvedBlueprint
+				: {
+						login: args.login,
+						...(resolvedBlueprint || {}),
+						preferredVersions: {
+							php:
+								args.php ??
+								resolvedBlueprint?.preferredVersions?.php ??
+								RecommendedPHPVersion,
+							wp:
+								args.wp ??
+								resolvedBlueprint?.preferredVersions?.wp ??
+								'latest',
+							...(resolvedBlueprint?.preferredVersions || {}),
+						},
+				  };
+
+		const tracker = new ProgressTracker();
+		let lastCaption = '';
+		let progressReached100 = false;
+		tracker.addEventListener('progress', (e: any) => {
+			if (progressReached100) {
+				return;
+			}
+			progressReached100 = e.detail.progress === 100;
+
+			// Use floor() so we don't report 100% until truly there.
+			const progressInteger = Math.floor(e.detail.progress);
+			lastCaption =
+				e.detail.caption || lastCaption || 'Running the Blueprint';
+			const message = `${lastCaption.trim()} – ${progressInteger}%`;
+			if (!args.quiet) {
+				this.writeProgressUpdate(
+					process.stdout,
+					message,
+					progressReached100
+				);
+			}
+		});
+		return await compileBlueprint(blueprint as BlueprintDeclaration, {
+			progress: tracker,
+			additionalSteps: additionalBlueprintSteps,
+		});
+	}
+
+	writeProgressUpdate(
+		writeStream: NodeJS.WriteStream,
+		message: string,
+		finalUpdate: boolean
+	) {
+		if (message === this.lastProgressMessage) {
+			// Avoid repeating the same message
+			return;
+		}
+		this.lastProgressMessage = message;
+
+		if (writeStream.isTTY) {
+			// Overwrite previous progress updates in-place for a quieter UX.
+			writeStream.cursorTo(0);
+			writeStream.write(message);
+			writeStream.clearLine(1);
+
+			if (finalUpdate) {
+				writeStream.write('\n');
+			}
+		} else {
+			// Fall back to writing one line per progress update
+			writeStream.write(`${message}\n`);
+		}
+	}
+}

packages/playground/cli/src/download.ts renamed to packages/playground/cli/src/blueprints-v1/download.ts

@@ -15,7 +15,7 @@ import { bootWordPress } from '@wp-playground/wordpress';
 import { rootCertificates } from 'tls';
 import { jspi } from 'wasm-feature-detect';
 import { MessageChannel, type MessagePort, parentPort } from 'worker_threads';
-import { mountResources } from './mounts';
+import { mountResources } from '../mounts';
 
 export interface Mount {
 	hostPath: string;

packages/playground/cli/src/worker-thread.ts renamed to packages/playground/cli/src/blueprints-v1/worker-thread-v1.ts

@@ -0,0 +1,45 @@
+import type { BlueprintDeclaration } from '@wp-playground/blueprints';
+
+export type BlueprintV2Declaration = string | BlueprintDeclaration | undefined;
+export type ParsedBlueprintV2Declaration =
+	| { type: 'inline-file'; contents: string }
+	| { type: 'file-reference'; reference: string };
+
+export function parseBlueprintDeclaration(
+	source: BlueprintV2Declaration | ParsedBlueprintV2Declaration
+): ParsedBlueprintV2Declaration {
+	if (
+		typeof source === 'object' &&
+		'type' in source &&
+		['inline-file', 'file-reference'].includes(source.type)
+	) {
+		return source;
+	}
+	if (!source) {
+		return {
+			type: 'inline-file',
+			contents: '{}',
+		};
+	}
+	if (typeof source !== 'string') {
+		// If source is an object, assume it's a Blueprint declaration object and
+		// convert it to a JSON string.
+		return {
+			type: 'inline-file',
+			contents: JSON.stringify(source),
+		};
+	}
+	try {
+		// If source is valid JSON, return it as is.
+		JSON.parse(source);
+		return {
+			type: 'inline-file',
+			contents: source,
+		};
+	} catch {
+		return {
+			type: 'file-reference',
+			reference: source,
+		};
+	}
+}