@wp-playground/blueprints 0.1.29 → 0.1.30

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wp-playground/blueprints",
-	"version": "0.1.29",
+	"version": "0.1.30",
 	"exports": {
 		".": {
 			"import": "./index.js",
@@ -20,5 +20,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "ad98893a9638c07cd9bdf849632c35db45caae0d"
+	"gitHead": "df3e9bff1de33d53d026c35a6ba5534aeff21a78"
 }

package/src/index.ts

@@ -1,13 +1,12 @@
 export * from './lib/steps';
-export type { Step } from './lib/steps';
-export { runBlueprintSteps } from './lib/run';
-export { compileBlueprint } from './lib/compile';
+export * from './lib/steps/handlers';
+export { runBlueprintSteps, compileBlueprint } from './lib/compile';
+export type { Blueprint } from './lib/blueprint';
 export type {
-	Blueprint,
-	StepDefinition,
 	CompiledStep,
 	CompiledBlueprint,
 	CompileBlueprintOptions,
+	OnStepCompleted,
 } from './lib/compile';
 export type {
 	CachedResource,

package/src/lib/blueprint.ts

@@ -0,0 +1,28 @@
+import { SupportedPHPVersion } from '@php-wasm/universal';
+import { StepDefinition } from './steps';
+
+export interface Blueprint {
+	/**
+	 * The URL to navigate to after the blueprint has been run.
+	 */
+	landingPage?: string;
+	/**
+	 * The preferred PHP and WordPress versions to use.
+	 */
+	preferredVersions?: {
+		/**
+		 * The preferred PHP version to use.
+		 * If not specified, the latest supported version will be used
+		 */
+		php: SupportedPHPVersion | 'latest';
+		/**
+		 * The preferred WordPress version to use.
+		 * If not specified, the latest supported version will be used
+		 */
+		wp: string | 'latest';
+	};
+	/**
+	 * The steps to run.
+	 */
+	steps?: Array<StepDefinition | string | undefined | false | null>;
+}

package/src/lib/{run.spec.ts → compile.spec.ts}

@@ -1,6 +1,5 @@
 import { NodePHP } from '@php-wasm/node';
-import { compileBlueprint } from './compile';
-import { runBlueprintSteps } from './run';
+import { compileBlueprint, runBlueprintSteps } from './compile';
 
 const phpVersion = '8.0';
 describe('Blueprints', () => {

package/src/lib/compile.ts

@@ -4,64 +4,36 @@ import {
 	LatestSupportedPHPVersion,
 	SupportedPHPVersion,
 	SupportedPHPVersions,
+	UniversalPHP,
 } from '@php-wasm/universal';
-import { FileReference, isFileReference, Resource } from './resources';
-import { Step } from './steps';
+import { isFileReference, Resource } from './resources';
+import { Step, StepDefinition } from './steps';
+import * as stepHandlers from './steps/handlers';
+import { Blueprint } from './blueprint';
 
-export type StepDefinition = Step<FileReference>;
-export type CompiledStep = {
-	args: Step<Resource>;
-	progress: ProgressTracker;
-};
-
-export interface Blueprint {
-	/**
-	 * The URL to navigate to after the blueprint has been run.
-	 */
-	landingPage?: string;
-	/**
-	 * The preferred PHP and WordPress versions to use.
-	 */
-	preferredVersions?: {
-		/**
-		 * The preferred PHP version to use.
-		 * If not specified, the latest supported version will be used
-		 */
-		php: SupportedPHPVersion | 'latest';
-		/**
-		 * The preferred WordPress version to use.
-		 * If not specified, the latest supported version will be used
-		 */
-		wp: string | 'latest';
-	};
-	/**
-	 * The steps to run.
-	 */
-	steps?: Array<StepDefinition | string | undefined | false | null>;
-}
+export type CompiledStep = (php: UniversalPHP) => Promise<void> | void;
 
 const supportedWordPressVersions = ['6.2', '6.1', '6.0', '5.9'] as const;
 type supportedWordPressVersion = (typeof supportedWordPressVersions)[number];
 export interface CompiledBlueprint {
-	/** The URL of the landing page for the blueprint */
-	landingPage: string;
-	/** The preferred versions of PHP and WordPress for the blueprint */
+	/** The requested versions of PHP and WordPress for the blueprint */
 	versions: {
 		php: SupportedPHPVersion;
 		wp: supportedWordPressVersion;
 	};
 	/** The compiled steps for the blueprint */
-	steps: Array<CompiledStep>;
-	/** The resources used by the compiled steps */
-	resources: Array<{ resource: Resource; step: CompiledStep }>;
-	progressTracker: ProgressTracker;
+	run: (playground: UniversalPHP) => Promise<void>;
 }
 
+export type OnStepCompleted = (output: any, step: StepDefinition) => any;
+
 export interface CompileBlueprintOptions {
 	/** Optional progress tracker to monitor progress */
 	progress?: ProgressTracker;
 	/** Optional semaphore to control access to a shared resource */
 	semaphore?: Semaphore;
+	/** Optional callback with step output */
+	onStepCompleted?: OnStepCompleted;
 }
 
 /**
@@ -77,6 +49,7 @@ export function compileBlueprint(
 	{
 		progress = new ProgressTracker(),
 		semaphore = new Semaphore({ concurrency: 3 }),
+		onStepCompleted = () => {},
 	}: CompileBlueprintOptions = {}
 ): CompiledBlueprint {
 	const steps = (blueprint.steps || []).filter(isStepDefinition);
@@ -85,15 +58,15 @@ export function compileBlueprint(
 		(total, step) => total + (step.progress?.weight || 1),
 		0
 	);
-	const compiledSteps = steps.map((step) =>
+	const compiled = steps.map((step) =>
 		compileStep(step, {
 			semaphore,
 			rootProgressTracker: progress,
 			totalProgressWeight,
 		})
 	);
+
 	return {
-		landingPage: blueprint.landingPage || '/',
 		versions: {
 			php: compileVersion(
 				blueprint.preferredVersions?.php,
@@ -106,9 +79,28 @@ export function compileBlueprint(
 				'6.2'
 			),
 		},
-		steps: compiledSteps,
-		resources: getResources(compiledSteps),
-		progressTracker: progress,
+		run: async (playground: UniversalPHP) => {
+			try {
+				// Start resolving resources early
+				for (const { asyncResources } of compiled) {
+					for (const resource of asyncResources) {
+						resource.resolve();
+					}
+				}
+
+				for (const { run, step } of compiled) {
+					const result = await run(playground);
+					onStepCompleted(result, step);
+				}
+				if ('goTo' in playground) {
+					await (playground as any).goTo(
+						blueprint.landingPage || '/'
+					);
+				}
+			} finally {
+				progress.finish();
+			}
+		},
 	};
 }
 
@@ -138,7 +130,7 @@ function compileVersion<T>(
  * @returns Whether the object is a StepDefinition
  */
 function isStepDefinition(
-	step: StepDefinition | string | undefined | false | null
+	step: Step | string | undefined | false | null
 ): step is StepDefinition {
 	return !!(typeof step === 'object' && step);
 }
@@ -160,14 +152,14 @@ interface CompileStepArgsOptions {
  * @param options Additional options for the compilation
  * @returns The compiled step
  */
-function compileStep(
-	step: StepDefinition,
+function compileStep<S extends StepDefinition>(
+	step: S,
 	{
 		semaphore,
 		rootProgressTracker,
 		totalProgressWeight,
 	}: CompileStepArgsOptions
-): CompiledStep {
+): { run: CompiledStep; step: S; asyncResources: Array<Resource> } {
 	const stepProgress = rootProgressTracker.stage(
 		(step.progress?.weight || 1) / totalProgressWeight
 	);
@@ -183,56 +175,77 @@ function compileStep(
 		args[key] = value;
 	}
 
-	const compiledStep = {
-		args: args as CompiledStep['args'],
-		progress: stepProgress,
+	const run = async (playground: UniversalPHP) => {
+		try {
+			stepProgress.fillSlowly();
+			return await stepHandlers[step.step](
+				playground,
+				await resolveArguments(args),
+				{
+					tracker: stepProgress,
+					initialCaption: step.progress?.caption,
+				}
+			);
+		} finally {
+			stepProgress.finish();
+		}
 	};
 
-	const asyncResources = getResourcesFromStep(compiledStep).filter(
-		(resource) => resource.isAsync
-	);
-
 	/**
 	 * The weight of each async resource is the same, and is the same as the
 	 * weight of the step itself.
 	 */
+	const asyncResources = getResources(args).filter(
+		(resource) => resource.isAsync
+	);
+
 	const evenWeight = 1 / (asyncResources.length + 1);
 	for (const resource of asyncResources) {
 		resource.progress = stepProgress.stage(evenWeight);
 	}
 
-	return compiledStep;
+	return { run, step, asyncResources };
 }
 
 /**
- * Gets all the resources used by compiled steps
+ * Gets the resources used by a specific compiled step
  *
- * @param steps The list of compiled steps
- * @returns The resources used by the compiled steps
+ * @param step The compiled step
+ * @returns The resources used by the compiled step
  */
-function getResources(steps: CompiledStep[]) {
-	let result: { resource: Resource; step: CompiledStep }[] = [];
-	for (const step of steps) {
-		result = result.concat(
-			getResourcesFromStep(step).map((resource) => ({ resource, step }))
-		);
+function getResources<S extends StepDefinition>(args: S) {
+	const result: Resource[] = [];
+	for (const argName in args) {
+		const resourceMaybe = (args as any)[argName];
+		if (resourceMaybe instanceof Resource) {
+			result.push(resourceMaybe);
+		}
 	}
 	return result;
 }
 
 /**
- * Gets the resources used by a specific compiled step
+ * Replaces Resource objects with their resolved values
  *
  * @param step The compiled step
  * @returns The resources used by the compiled step
  */
-function getResourcesFromStep(step: CompiledStep) {
-	const result: Resource[] = [];
-	for (const argName in step.args) {
-		const resourceMaybe = (step.args as any)[argName];
+async function resolveArguments<T extends Record<string, unknown>>(args: T) {
+	const resolved: any = {};
+	for (const argName in args) {
+		const resourceMaybe = (args as any)[argName];
 		if (resourceMaybe instanceof Resource) {
-			result.push(resourceMaybe);
+			resolved[argName] = await resourceMaybe.resolve();
+		} else {
+			resolved[argName] = resourceMaybe;
 		}
 	}
-	return result;
+	return resolved;
+}
+
+export async function runBlueprintSteps(
+	compiledBlueprint: CompiledBlueprint,
+	playground: UniversalPHP
+) {
+	await compiledBlueprint.run(playground);
 }

package/src/lib/resources.ts

@@ -159,7 +159,7 @@ export class VFSResource extends Resource {
 			this.resource.path
 		);
 		this.progress?.set(100);
-		return new File([buffer], this.resource.path);
+		return new File([buffer], this.name);
 	}
 
 	/** @inheritDoc */
@@ -220,7 +220,7 @@ export abstract class FetchResource extends Resource {
 		if (response.status !== 200) {
 			throw new Error(`Could not download "${url}"`);
 		}
-		return new File([await response.blob()], url);
+		return new File([await response.blob()], this.name);
 	}
 
 	/**

package/src/lib/steps/activate-plugin.ts

@@ -1,8 +1,7 @@
-import { UniversalPHP } from '@php-wasm/universal';
-import { BaseStep } from '.';
+import { StepHandler } from '.';
 import { asDOM } from './common';
 
-export interface ActivatePluginStep extends BaseStep {
+export interface ActivatePluginStep {
 	step: 'activatePlugin';
 	plugin: string;
 }
@@ -13,7 +12,12 @@ export interface ActivatePluginStep extends BaseStep {
  * @param playground The playground client.
  * @param plugin The plugin slug.
  */
-export async function activatePlugin(playground: UniversalPHP, plugin: string) {
+export const activatePlugin: StepHandler<ActivatePluginStep> = async (
+	playground,
+	{ plugin },
+	progress
+) => {
+	progress?.tracker.setCaption(`Activating ${plugin}`);
 	const pluginsPage = asDOM(
 		await playground.request({
 			url: '/wp-admin/plugins.php',
@@ -28,4 +32,4 @@ export async function activatePlugin(playground: UniversalPHP, plugin: string) {
 	await playground.request({
 		url: '/wp-admin/' + href,
 	});
-}
+};

package/src/lib/steps/apply-wordpress-patches/index.ts

@@ -1,13 +1,9 @@
 import { UniversalPHP } from '@php-wasm/universal';
-import { BaseStep } from '..';
+import { StepHandler } from '..';
 import { updateFile } from '../common';
 
-export interface ApplyWordPressPatchesStep extends BaseStep {
+export interface ApplyWordPressPatchesStep {
 	step: 'applyWordPressPatches';
-	wordpressPath: string;
-}
-
-export interface PatchOptions {
 	siteUrl: string;
 	wordpressPath?: string;
 	patchSqlitePlugin?: boolean;
@@ -17,10 +13,9 @@ export interface PatchOptions {
 	disableWpNewBlogNotification?: boolean;
 }
 
-export async function applyWordPressPatches(
-	php: UniversalPHP,
-	options: PatchOptions
-) {
+export const applyWordPressPatches: StepHandler<
+	ApplyWordPressPatchesStep
+> = async (php, options) => {
 	const patch = new WordPressPatcher(
 		php,
 		options.siteUrl,
@@ -42,7 +37,7 @@ export async function applyWordPressPatches(
 	if (options.disableWpNewBlogNotification !== false) {
 		await patch.disableWpNewBlogNotification();
 	}
-}
+};
 
 class WordPressPatcher {
 	php: UniversalPHP;

package/src/lib/steps/client-methods.ts

@@ -1,56 +1,121 @@
 import { PHPRunOptions, PHPRequest } from '@php-wasm/universal';
-import { BaseStep } from '.';
+import { StepHandler } from '.';
+import { fileToUint8Array } from './common';
 
-export interface RunPHPStep extends BaseStep {
+export interface RunPHPStep {
 	step: 'runPHP';
 	code: string;
 }
 
-export interface RunPHPWithOptionsStep extends BaseStep {
+export const runPHP: StepHandler<RunPHPStep> = async (playground, { code }) => {
+	return await playground.run({ code });
+};
+
+export interface RunPHPWithOptionsStep {
 	step: 'runPHPWithOptions';
 	options: PHPRunOptions;
 }
 
-export interface SetPhpIniEntryStep extends BaseStep {
+export const runPHPWithOptions: StepHandler<RunPHPWithOptionsStep> = async (
+	playground,
+	{ options }
+) => {
+	return await playground.run(options);
+};
+
+export interface SetPhpIniEntryStep {
 	step: 'setPhpIniEntry';
 	key: string;
 	value: string;
 }
 
-export interface RequestStep extends BaseStep {
+export const setPhpIniEntry: StepHandler<SetPhpIniEntryStep> = async (
+	playground,
+	{ key, value }
+) => {
+	await playground.setPhpIniEntry(key, value);
+};
+
+export interface RequestStep {
 	step: 'request';
 	request: PHPRequest;
 }
 
-export interface CpStep extends BaseStep {
+export const request: StepHandler<RequestStep> = async (
+	playground,
+	{ request }
+) => {
+	return await playground.request(request);
+};
+
+export interface CpStep {
 	step: 'cp';
 	fromPath: string;
 	toPath: string;
 }
 
-export interface MvStep extends BaseStep {
+export const cp: StepHandler<CpStep> = async (
+	playground,
+	{ fromPath, toPath }
+) => {
+	await playground.writeFile(
+		toPath,
+		await playground.readFileAsBuffer(fromPath)
+	);
+};
+
+export interface MvStep {
 	step: 'mv';
 	fromPath: string;
 	toPath: string;
 }
 
-export interface MkdirStep extends BaseStep {
+export const mv: StepHandler<MvStep> = async (
+	playground,
+	{ fromPath, toPath }
+) => {
+	await playground.mv(fromPath, toPath);
+};
+
+export interface MkdirStep {
 	step: 'mkdir';
 	path: string;
 }
 
-export interface RmStep extends BaseStep {
+export const mkdir: StepHandler<MkdirStep> = async (playground, { path }) => {
+	await playground.mkdir(path);
+};
+
+export interface RmStep {
 	step: 'rm';
 	path: string;
 }
 
-export interface RmdirStep extends BaseStep {
+export const rm: StepHandler<RmStep> = async (playground, { path }) => {
+	await playground.unlink(path);
+};
+
+export interface RmdirStep {
 	step: 'rmdir';
 	path: string;
 }
 
-export interface WriteFileStep<ResourceType> extends BaseStep {
+export const rmdir: StepHandler<RmdirStep> = async (playground, { path }) => {
+	await playground.rmdir(path);
+};
+
+export interface WriteFileStep<ResourceType> {
 	step: 'writeFile';
 	path: string;
 	data: ResourceType | string | Uint8Array;
 }
+
+export const writeFile: StepHandler<WriteFileStep<File>> = async (
+	playground,
+	{ path, data }
+) => {
+	if (data instanceof File) {
+		data = await fileToUint8Array(data);
+	}
+	await playground.writeFile(path, data);
+};

package/src/lib/steps/common.ts

@@ -20,3 +20,7 @@ export async function updateFile(
 ) {
 	await php.writeFile(path, callback(await php.readFileAsText(path)));
 }
+
+export async function fileToUint8Array(file: File) {
+	return new Uint8Array(await file.arrayBuffer());
+}

package/src/lib/steps/define-site-url.ts

@@ -1,8 +1,7 @@
-import { UniversalPHP } from '@php-wasm/universal';
-import { BaseStep } from '.';
+import { StepHandler } from '.';
 import { updateFile } from './common';
 
-export interface DefineSiteUrlStep extends BaseStep {
+export interface DefineSiteUrlStep {
 	step: 'defineSiteUrl';
 	siteUrl: string;
 }
@@ -13,7 +12,10 @@ export interface DefineSiteUrlStep extends BaseStep {
  * @param playground The playground client.
  * @param siteUrl
  */
-export async function defineSiteUrl(playground: UniversalPHP, siteUrl: string) {
+export const defineSiteUrl: StepHandler<DefineSiteUrlStep> = async (
+	playground,
+	{ siteUrl }
+) => {
 	await updateFile(
 		playground,
 		`/wordpress/wp-config.php`,
@@ -27,4 +29,4 @@ export async function defineSiteUrl(playground: UniversalPHP, siteUrl: string) {
 			}
             ?>${contents}`
 	);
-}
+};

package/src/lib/steps/handlers.ts

@@ -0,0 +1,21 @@
+export { activatePlugin } from './activate-plugin';
+export { applyWordPressPatches } from './apply-wordpress-patches';
+export {
+	rm,
+	cp,
+	mkdir,
+	rmdir,
+	mv,
+	setPhpIniEntry,
+	runPHP,
+	runPHPWithOptions,
+	request,
+	writeFile,
+} from './client-methods';
+export { defineSiteUrl } from './define-site-url';
+export { importFile, unzip, replaceSite, zipEntireSite } from './import-export';
+export { installPlugin } from './install-plugin';
+export { installTheme } from './install-theme';
+export { login } from './login';
+export { runWpInstallationWizard } from './run-wp-installation-wizard';
+export { setSiteOptions, updateUserMeta } from './site-data';