[Website] Improve error reporting

packages/playground/blueprints/src/index.ts

@@ -19,6 +19,8 @@ export {
 	isBlueprintBundle,
 	compileBlueprintV1,
 	runBlueprintV1Steps,
+	InvalidBlueprintError,
+	BlueprintStepExecutionError,
 
 	// BC:
 	compileBlueprintV1 as compileBlueprint,
@@ -49,6 +51,7 @@ export type {
 	VFSReference,
 	VFSResource,
 } from './lib/v1/resources';
+export { BlueprintFilesystemRequiredError } from './lib/v1/resources';
 export * from './lib/steps';
 export * from './lib/steps/handlers';
 export type {
@@ -61,7 +64,10 @@ export { getV2Runner } from './lib/v2/get-v2-runner';
 export { runBlueprintV2 } from './lib/v2/run-blueprint-v2';
 export type { BlueprintMessage } from './lib/v2/run-blueprint-v2';
 
-export { resolveRemoteBlueprint } from './lib/resolve-remote-blueprint';
+export {
+	resolveRemoteBlueprint,
+	BlueprintFetchError,
+} from './lib/resolve-remote-blueprint';
 export { wpContentFilesExcludedFromExport } from './lib/utils/wp-content-files-excluded-from-exports';
 export { resolveRuntimeConfiguration } from './lib/resolve-runtime-configuration';
 

packages/playground/blueprints/src/lib/resolve-remote-blueprint.ts

@@ -6,6 +6,17 @@ import {
 } from '@wp-playground/storage';
 import type { BlueprintBundle } from './types';
 
+export class BlueprintFetchError extends Error {
+	constructor(
+		message: string,
+		public readonly url: string,
+		options?: ErrorOptions
+	) {
+		super(message, options);
+		this.name = 'BlueprintFetchError';
+	}
+}
+
 /**
  * Resolves a remote blueprint from a URL.
  *
@@ -15,34 +26,42 @@ import type { BlueprintBundle } from './types';
 export async function resolveRemoteBlueprint(
 	url: string
 ): Promise<BlueprintBundle> {
-	const response = await fetch(url, {
-		credentials: 'omit',
-	});
-	if (!response.ok) {
-		throw new Error(`Failed to fetch blueprint from ${url}`);
-	}
-	const blueprintBytes = await response.arrayBuffer();
 	try {
-		const blueprintText = new TextDecoder().decode(blueprintBytes);
-		JSON.parse(blueprintText);
+		const response = await fetch(url, {
+			credentials: 'omit',
+		});
+		if (!response.ok) {
+			throw new Error(`Failed to fetch blueprint from ${url}`);
+		}
+		const blueprintBytes = await response.arrayBuffer();
+		try {
+			const blueprintText = new TextDecoder().decode(blueprintBytes);
+			JSON.parse(blueprintText);
 
-		// No exceptions, good! We're dealing with a JSON file. Let's
-		// resolve the "bundled" resources from the same remote URL.
-		return new OverlayFilesystem([
-			new InMemoryFilesystem({
-				'blueprint.json': blueprintText,
-			}),
-			new FetchFilesystem({
-				baseUrl: url,
-			}),
-		]);
-	} catch {
-		// If the blueprint is not a JSON file, check if it's a ZIP file.
-		if (await looksLikeZipFile(blueprintBytes)) {
-			return ZipFilesystem.fromArrayBuffer(blueprintBytes);
+			// No exceptions, good! We're dealing with a JSON file. Let's
+			// resolve the "bundled" resources from the same remote URL.
+			return new OverlayFilesystem([
+				new InMemoryFilesystem({
+					'blueprint.json': blueprintText,
+				}),
+				new FetchFilesystem({
+					baseUrl: url,
+				}),
+			]);
+		} catch {
+			// If the blueprint is not a JSON file, check if it's a ZIP file.
+			if (await looksLikeZipFile(blueprintBytes)) {
+				return ZipFilesystem.fromArrayBuffer(blueprintBytes);
+			}
+			throw new Error(
+				`Blueprint file at ${url} is neither a valid JSON nor a ZIP file.`
+			);
 		}
-		throw new Error(
-			`Blueprint file at ${url} is neither a valid JSON nor a ZIP file.`
+	} catch (error) {
+		throw new BlueprintFetchError(
+			`Blueprint file at ${url} is neither a valid JSON nor a ZIP file.`,
+			url,
+			{ cause: error }
 		);
 	}
 }

packages/playground/blueprints/src/lib/steps/activate-plugin.ts

@@ -98,7 +98,7 @@ export const activatePlugin: StepHandler<ActivatePluginStep> = async (
 	/**
 	 * Instead of trusting the activation response, check the active plugins list.
 	 *
-	 * We try to discard any extra output via output buffering. The output of the script below 
+	 * We try to discard any extra output via output buffering. The output of the script below
 	 * end with `{"success": true}` or `{"success": false}`. Only `{"success": true}` is
 	 * treated as a successful plugin activation.
 	 */
@@ -152,9 +152,11 @@ export const activatePlugin: StepHandler<ActivatePluginStep> = async (
 	}
 
 	throw new Error(
-		`Plugin ${pluginPath} could not be activated – WordPress exited with no error. ` +
-			`Sometimes, when $_SERVER or site options are not configured correctly, ` +
-			`WordPress exits early with a 301 redirect. ` +
-			`Inspect the "debug" logs in the console for more details.`
+		`Plugin ${pluginPath} could not be activated - WordPress exited with exit code ${activatePluginResult.exitCode}. ` +
+			`Inspect the "debug" logs in the console for more details. Output headers: ${JSON.stringify(
+				activatePluginResult.headers,
+				null,
+				2
+			)}`
 	);
 };

packages/playground/blueprints/src/lib/steps/activate-theme.ts

@@ -67,10 +67,12 @@ export const activateTheme: StepHandler<ActivateThemeStep> = async (
 	if (result.text !== 'Theme activated successfully') {
 		logger.debug(result);
 		throw new Error(
-			`Theme ${themeFolderName} could not be activated – WordPress exited with no error. ` +
-				`Sometimes, when $_SERVER or site options are not configured correctly, ` +
-				`WordPress exits early with a 301 redirect. ` +
-				`Inspect the "debug" logs in the console for more details`
+			`Theme ${themeFolderName} could not be activated - WordPress exited with exit code ${result.exitCode}. ` +
+				`Inspect the "debug" logs in the console for more details. Output headers: ${JSON.stringify(
+					result.headers,
+					null,
+					2
+				)}`
 		);
 	}
 };

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

@@ -41,6 +41,50 @@ const keyedStepHandlers = {
  */
 import blueprintValidator from '../../../public/blueprint-schema-validator';
 import { defaultWpCliPath, defaultWpCliResource } from '../steps/wp-cli';
+import type { ErrorObject } from 'ajv';
+
+export class InvalidBlueprintError extends Error {
+	constructor(message: string, public readonly validationErrors?: unknown) {
+		super(message);
+		this.name = 'InvalidBlueprintError';
+	}
+}
+
+/**
+ * Error thrown when a single Blueprint step fails during execution.
+ *
+ * This error carries structured information about the failing step so that
+ * consumers (e.g. the Playground UI) do not have to parse human‑readable
+ * error messages to understand what went wrong.
+ */
+export class BlueprintStepExecutionError extends Error {
+	public readonly stepNumber: number;
+	public readonly step: StepDefinition;
+	public readonly messages: string[];
+
+	constructor(options: {
+		stepNumber: number;
+		step: StepDefinition;
+		cause: unknown;
+	}) {
+		const { stepNumber, step, cause } = options;
+		const causeError =
+			cause instanceof Error ? cause : new Error(String(cause));
+		const baseMessage = `Error when executing the blueprint step #${stepNumber}`;
+		const fullMessage = causeError.message
+			? `${baseMessage}: ${causeError.message}`
+			: baseMessage;
+
+		super(fullMessage, { cause: causeError });
+		this.name = 'BlueprintStepExecutionError';
+		this.stepNumber = stepNumber;
+		this.step = step;
+		this.messages = (causeError.message || '')
+			.split('\n')
+			.map((line) => line.trim())
+			.filter(Boolean);
+	}
+}
 
 export type CompiledV1Step = (php: UniversalPHP) => Promise<void> | void;
 
@@ -307,14 +351,17 @@ function compileBlueprintJson(
 
 	const { valid, errors } = validateBlueprint(blueprint);
 	if (!valid) {
-		const e = new Error(
-			`Invalid blueprint: ${errors![0].message} at ${
-				errors![0].instancePath
-			}`
+		const formattedErrors = formatValidationErrors(blueprint, errors ?? []);
+
+		throw new InvalidBlueprintError(
+			`Invalid Blueprint: The Blueprint does not conform to the schema.\n\n` +
+				`Found ${
+					errors!.length
+				} validation error(s):\n\n${formattedErrors}\n\n` +
+				`Please review your Blueprint and fix these issues. ` +
+				`Learn more about the Blueprint format: https://wordpress.github.io/wordpress-playground/blueprints/data-format`,
+			errors
 		);
-		// Attach Ajv output to the thrown object for easier debugging
-		(e as any).errors = errors;
-		throw e;
 	}
 
 	onBlueprintValidated(blueprint);
@@ -378,12 +425,12 @@ function compileBlueprintJson(
 						const result = await run(playground);
 						onStepCompleted(result, step);
 					} catch (e) {
-						throw new Error(
-							`Error when executing the blueprint step #${i} (${JSON.stringify(
-								step
-							)}) ${e instanceof Error ? `: ${e.message}` : e}`,
-							{ cause: e }
-						);
+						const stepNumber = Number(i) + 1;
+						throw new BlueprintStepExecutionError({
+							stepNumber,
+							step,
+							cause: e,
+						});
 					}
 				}
 			} finally {
@@ -419,6 +466,80 @@ function compileBlueprintJson(
 	};
 }
 
+function formatValidationErrors(
+	blueprint: BlueprintV1Declaration,
+	errors: ErrorObject<string, unknown>[]
+) {
+	return errors
+		.map((err, index) => {
+			const path = err.instancePath || '/';
+			let message = err.message || 'validation failed';
+
+			// For "additional properties" errors, highlight the actual problematic key
+			let highlightedSnippet = '';
+			if (message.includes('must NOT have additional properties')) {
+				// Extract the property name from the error params
+				const additionalProperty = (err.params as any)
+					?.additionalProperty;
+				if (additionalProperty) {
+					message = `has unexpected property "${additionalProperty}"`;
+
+					// Try to show the offending key highlighted
+					try {
+						const pathParts = path.split('/').filter(Boolean);
+						let currentValue: any = blueprint;
+						for (const part of pathParts) {
+							if (
+								currentValue &&
+								typeof currentValue === 'object'
+							) {
+								currentValue = currentValue[part];
+							}
+						}
+
+						if (currentValue && typeof currentValue === 'object') {
+							const offendingValue =
+								currentValue[additionalProperty];
+							const valueStr = JSON.stringify(offendingValue);
+							highlightedSnippet = `\n  "${additionalProperty}": ${valueStr}\n  ${'^'.repeat(
+								additionalProperty.length + 2
+							)} This property is not recognized`;
+						}
+					} catch {
+						// If we can't extract context, that's okay
+					}
+				}
+			} else {
+				// For other errors, try to extract the offending value
+				try {
+					const pathParts = path.split('/').filter(Boolean);
+					let currentValue: any = blueprint;
+					for (const part of pathParts) {
+						if (currentValue && typeof currentValue === 'object') {
+							currentValue = currentValue[part];
+						}
+					}
+					if (currentValue !== undefined) {
+						const valueStr = JSON.stringify(currentValue, null, 2);
+						// Limit snippet length
+						const snippet =
+							valueStr.length > 200
+								? valueStr.substring(0, 200) + '...'
+								: valueStr;
+						highlightedSnippet = `\n  Value: ${snippet}`;
+					}
+				} catch {
+					// If we can't extract context, that's okay
+				}
+			}
+
+			return `${
+				index + 1
+			}. At path "${path}": ${message}${highlightedSnippet}`;
+		})
+		.join('\n\n');
+}
+
 export function validateBlueprint(blueprintMaybe: object) {
 	const valid = blueprintValidator(blueprintMaybe);
 	if (valid) {