Website query API: Continue plugin installs on error

packages/playground/blueprints/src/index.ts

@@ -7,6 +7,8 @@ export type {
 	CompiledBlueprint,
 	CompileBlueprintOptions,
 	OnStepCompleted,
+	OnStepError,
+	ShouldBoot,
 } from './lib/compile';
 export type {
 	CachedResource,

packages/playground/blueprints/src/lib/compile.ts

@@ -11,7 +11,12 @@ import {
 } from '@php-wasm/universal';
 import type { SupportedPHPExtensionBundle } from '@php-wasm/universal';
 import { FileReference, isFileReference, Resource } from './resources';
-import { Step, StepDefinition } from './steps';
+import {
+	Step,
+	StepDefinition,
+	StepFailMode,
+	defaultStepFailModes,
+} from './steps';
 import * as stepHandlers from './steps/handlers';
 import { Blueprint } from './blueprint';
 
@@ -48,7 +53,11 @@ export interface CompiledBlueprint {
 	run: (playground: UniversalPHP) => Promise<void>;
 }
 
-export type OnStepCompleted = (output: any, step: StepDefinition) => any;
+export type OnStepCompleted = (step: StepDefinition, result: any) => any;
+export type OnStepError = (step: StepDefinition, error: any) => any;
+export type ShouldBoot = (
+	completedStatus: Map<StepDefinition, boolean>
+) => boolean;
 
 export interface CompileBlueprintOptions {
 	/** Optional progress tracker to monitor progress */
@@ -57,8 +66,21 @@ export interface CompileBlueprintOptions {
 	semaphore?: Semaphore;
 	/** Optional callback with step output */
 	onStepCompleted?: OnStepCompleted;
+	onStepError?: OnStepError;
+	shouldBoot?: ShouldBoot;
 }
 
+/**
+ * Convert a settled Promise into a boolean indicating if it resolved or rejected.
+ */
+const isSettledPromiseResolved = <P extends Promise<any>>(
+	promise: P
+): Promise<boolean> =>
+	promise.then(
+		() => true,
+		() => false
+	);
+
 /**
  * Compiles Blueprint into a form that can be executed.
  *
@@ -73,6 +95,8 @@ export function compileBlueprint(
 		progress = new ProgressTracker(),
 		semaphore = new Semaphore({ concurrency: 3 }),
 		onStepCompleted = () => {},
+		onStepError,
+		shouldBoot,
 	}: CompileBlueprintOptions = {}
 ): CompiledBlueprint {
 	blueprint = {
@@ -171,33 +195,92 @@ export function compileBlueprint(
 			networking: blueprint.features?.networking ?? false,
 		},
 		run: async (playground: UniversalPHP) => {
+			const stepStatus = new Map<StepDefinition, Promise<void>>();
+			const stepPromises = new Map<
+				StepDefinition,
+				{
+					resolve: (result: any) => void;
+					reject: (error: any) => void;
+				}
+			>();
+			for (const { step, failMode } of compiled) {
+				const promise = new Promise<void>((resolve, reject) => {
+					stepPromises.set(step, { resolve, reject });
+				});
+				stepStatus.set(step, promise);
+			}
+
 			try {
 				// Start resolving resources early
-				for (const { resources } of compiled) {
+				for (const { resources, step, failMode } of compiled) {
+					const stepPromise = stepPromises.get(step);
 					for (const resource of resources) {
 						resource.setPlayground(playground);
 						if (resource.isAsync) {
-							resource.resolve();
+							resource.resolve().catch(function (error) {
+								stepPromise?.reject(error);
+							});
 						}
 					}
 				}
 
-				for (const { run, step } of compiled) {
-					const result = await run(playground);
-					onStepCompleted(result, step);
+				/**
+				 * When a compiled step's `run` method is called, it
+				 * uses `resolveArguments` to await dependent resources.
+				 */
+				for (const { run, step, failMode } of compiled) {
+					const stepPromise = stepPromises.get(step);
+					let result;
+					try {
+						result = await run(playground);
+					} catch (error) {
+						stepPromise?.reject(result);
+						if (onStepError) {
+							onStepError(step, error);
+						} else if (failMode === 'abort') {
+							throw error;
+						}
+						/**
+						 * Skip - This allows the default shouldBoot() below to
+						 * consider the step completed.
+						 */
+						stepStatus.set(step, Promise.resolve());
+						continue;
+					}
+					stepPromise?.resolve(result);
+					onStepCompleted(step, result);
 				}
 			} finally {
-				try {
-					await (playground as any).goTo(
-						blueprint.landingPage || '/'
+				const completedStatus = new Map();
+				for (const { step } of compiled) {
+					completedStatus.set(
+						step,
+						await isSettledPromiseResolved(
+							stepStatus.get(step) as Promise<any>
+						)
 					);
-				} catch (e) {
-					/*
-					 * NodePHP exposes no goTo method.
-					 * We can't use `goto` in playground here,
-					 * because it may be a Comlink proxy object
-					 * with no such method.
-					 */
+				}
+
+				// Either someone made a choice to boot or all steps succeeded.
+				const boot = shouldBoot
+					? shouldBoot(completedStatus)
+					: await isSettledPromiseResolved(
+							Promise.all([...stepStatus.values()])
+					  );
+
+				if (boot) {
+					try {
+						await (playground as any)?.goTo(
+							blueprint.landingPage || '/'
+						);
+					} catch (e) {
+						/*
+						 * NodePHP exposes no goTo method.
+						 * We can't use `goto` in playground here,
+						 * because it may be a Comlink proxy object
+						 * with no such method.
+						 */
+					}
 				}
 				progress.finish();
 			}
@@ -327,7 +410,12 @@ function compileStep<S extends StepDefinition>(
 		rootProgressTracker,
 		totalProgressWeight,
 	}: CompileStepArgsOptions
-): { run: CompiledStep; step: S; resources: Array<Resource> } {
+): {
+	run: CompiledStep;
+	step: S;
+	resources: Array<Resource>;
+	failMode: StepFailMode;
+} {
 	const stepProgress = rootProgressTracker.stage(
 		(step.progress?.weight || 1) / totalProgressWeight
 	);
@@ -373,7 +461,13 @@ function compileStep<S extends StepDefinition>(
 		resource.progress = stepProgress.stage(evenWeight);
 	}
 
-	return { run, step, resources };
+	return {
+		run,
+		step,
+		resources,
+		failMode:
+			(step.failMode || defaultStepFailModes.get(step.step)) ?? 'abort',
+	};
 }
 
 /**

packages/playground/blueprints/src/lib/steps/index.ts

@@ -35,7 +35,15 @@ export type StepDefinition = Step & {
 		weight?: number;
 		caption?: string;
 	};
+	/**
+	 * Option to decide what to do when a step fails:
+	 * - `abort`: Stop the entire blueprint (default)
+	 * - `skip`: Continue running the other steps
+	 */
+	failMode?: StepFailMode;
 };
+export type StepFailMode = 'abort' | 'skip';
+export const defaultStepFailModes = new Map<string, StepFailMode>();
 
 export { wpContentFilesExcludedFromExport } from './common';
 

packages/playground/client/src/index.ts

@@ -34,6 +34,8 @@ import {
 	Blueprint,
 	compileBlueprint,
 	OnStepCompleted,
+	OnStepError,
+	ShouldBoot,
 	runBlueprintSteps,
 } from '@wp-playground/blueprints';
 import { consumeAPI } from '@php-wasm/web';
@@ -46,6 +48,8 @@ export interface StartPlaygroundOptions {
 	disableProgressBar?: boolean;
 	blueprint?: Blueprint;
 	onBlueprintStepCompleted?: OnStepCompleted;
+	onBlueprintStepError?: OnStepError;
+	shouldBoot?: ShouldBoot;
 }
 
 /**
@@ -62,6 +66,7 @@ export async function startPlaygroundWeb({
 	progressTracker = new ProgressTracker(),
 	disableProgressBar,
 	onBlueprintStepCompleted,
+	onBlueprintStepError,
 }: StartPlaygroundOptions): Promise<PlaygroundClient> {
 	assertValidRemote(remoteUrl);
 	allowStorageAccessByUserActivation(iframe);
@@ -76,6 +81,7 @@ export async function startPlaygroundWeb({
 	const compiled = compileBlueprint(blueprint, {
 		progress: progressTracker.stage(0.5),
 		onStepCompleted: onBlueprintStepCompleted,
+		onStepError: onBlueprintStepError,
 	});
 	const playground = await doStartPlaygroundWeb(
 		iframe,

packages/playground/website/src/lib/hooks.ts

@@ -1,6 +1,7 @@
 import { useEffect, useRef, useState } from 'react';
 import { Blueprint, startPlaygroundWeb } from '@wp-playground/client';
 import type { PlaygroundClient } from '@wp-playground/client';
+import type { Step, CorePluginReference } from '@wp-playground/blueprints';
 import { getRemoteUrl } from './config';
 
 interface UsePlaygroundOptions {
@@ -40,10 +41,25 @@ export function usePlayground({ blueprint, storage }: UsePlaygroundOptions) {
 			remoteUrl.searchParams.set('storage', storage);
 		}
 
+		const onBlueprintStepError = (step: Step, error: Error) => {
+			if (step.step === 'installPlugin') {
+				// TODO: Open modal to display error message
+				alert(
+					`Failed to install: ${
+						(step.pluginZipFile as CorePluginReference).slug ||
+						'plugin'
+					}`
+				);
+			}
+
+			// Fall through to step option failMode to abort or skip
+		};
+
 		startPlaygroundWeb({
 			iframe,
 			remoteUrl: remoteUrl.toString(),
 			blueprint,
+			onBlueprintStepError,
 		}).then(async (playground) => {
 			playground.onNavigation((url) => setUrl(url));
 			setPlayground(() => playground);

packages/playground/wordpress/build/build.js

@@ -175,7 +175,9 @@ versions = Object.keys(versions)
 // Write the updated JSON back to the file
 await fs.writeFile(versionsPath, JSON.stringify(versions, null, 2));
 
-const latestStableVersion = Object.keys(versions).filter((v) => v.match(/^\d/))[0];
+const latestStableVersion = Object.keys(versions).filter((v) =>
+	v.match(/^\d/)
+)[0];
 
 // Refresh get-wordpress-module.ts
 const getWordPressModulePath = `${outputJsDir}/get-wordpress-module.ts`;
@@ -186,7 +188,9 @@ const getWordPressModuleContent = `
  * This file must statically exists in the project because of the way
  * vite resolves imports.
  */
-export function getWordPressModule(wpVersion: string = ${JSON.stringify(latestStableVersion)}) {
+export function getWordPressModule(wpVersion: string = ${JSON.stringify(
+	latestStableVersion
+)}) {
 	switch (wpVersion) {
 		${Object.keys(versions)
 			.map(