@wp-playground/blueprints 0.1.40 → 0.1.42

package/src/lib/compile.ts

@@ -1,262 +0,0 @@
-import { ProgressTracker } from '@php-wasm/progress';
-import { Semaphore } from '@php-wasm/util';
-import {
-	LatestSupportedPHPVersion,
-	SupportedPHPVersion,
-	SupportedPHPVersions,
-	UniversalPHP,
-} from '@php-wasm/universal';
-import { isFileReference, Resource } from './resources';
-import { Step, StepDefinition } from './steps';
-import * as stepHandlers from './steps/handlers';
-import { Blueprint } from './blueprint';
-
-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 requested versions of PHP and WordPress for the blueprint */
-	versions: {
-		php: SupportedPHPVersion;
-		wp: supportedWordPressVersion;
-	};
-	/** The compiled steps for the blueprint */
-	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;
-}
-
-/**
- * Compiles Blueprint into a form that can be executed.
- *
- * @param playground The PlaygroundClient to use for the compilation
- * @param blueprint The bBueprint to compile
- * @param options Additional options for the compilation
- * @returns The compiled blueprint
- */
-export function compileBlueprint(
-	blueprint: Blueprint,
-	{
-		progress = new ProgressTracker(),
-		semaphore = new Semaphore({ concurrency: 3 }),
-		onStepCompleted = () => {},
-	}: CompileBlueprintOptions = {}
-): CompiledBlueprint {
-	const steps = (blueprint.steps || []).filter(isStepDefinition);
-
-	const totalProgressWeight = steps.reduce(
-		(total, step) => total + (step.progress?.weight || 1),
-		0
-	);
-	const compiled = steps.map((step) =>
-		compileStep(step, {
-			semaphore,
-			rootProgressTracker: progress,
-			totalProgressWeight,
-		})
-	);
-
-	return {
-		versions: {
-			php: compileVersion(
-				blueprint.preferredVersions?.php,
-				SupportedPHPVersions,
-				LatestSupportedPHPVersion
-			),
-			wp: compileVersion(
-				blueprint.preferredVersions?.wp,
-				supportedWordPressVersions,
-				'6.2'
-			),
-		},
-		run: async (playground: UniversalPHP) => {
-			try {
-				// Start resolving resources early
-				for (const { resources } of compiled) {
-					for (const resource of resources) {
-						resource.setPlayground(playground);
-						if (resource.isAsync) {
-							resource.resolve();
-						}
-					}
-				}
-
-				for (const { run, step } of compiled) {
-					const result = await run(playground);
-					onStepCompleted(result, step);
-				}
-				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.
-					 */
-				}
-			} finally {
-				progress.finish();
-			}
-		},
-	};
-}
-
-/**
- * Compiles a preferred version string into a supported version
- *
- * @param value The value to compile
- * @param supported The list of supported versions
- * @param latest The latest supported version
- * @returns The compiled version
- */
-function compileVersion<T>(
-	value: string | undefined | null,
-	supported: readonly T[],
-	latest: string
-): T {
-	if (value && supported.includes(value as any)) {
-		return value as T;
-	}
-	return latest as T;
-}
-
-/**
- * Determines if a step is a StepDefinition object
- *
- * @param step The object to test
- * @returns Whether the object is a StepDefinition
- */
-function isStepDefinition(
-	step: Step | string | undefined | false | null
-): step is StepDefinition {
-	return !!(typeof step === 'object' && step);
-}
-
-interface CompileStepArgsOptions {
-	/** Optional semaphore to control access to a shared resource */
-	semaphore?: Semaphore;
-	/** The root progress tracker for the compilation */
-	rootProgressTracker: ProgressTracker;
-	/** The total progress weight of all the steps in the blueprint */
-	totalProgressWeight: number;
-}
-
-/**
- * Compiles a single Blueprint step into a form that can be executed
- *
- * @param playground The PlaygroundClient to use for the compilation
- * @param step The step to compile
- * @param options Additional options for the compilation
- * @returns The compiled step
- */
-function compileStep<S extends StepDefinition>(
-	step: S,
-	{
-		semaphore,
-		rootProgressTracker,
-		totalProgressWeight,
-	}: CompileStepArgsOptions
-): { run: CompiledStep; step: S; resources: Array<Resource> } {
-	const stepProgress = rootProgressTracker.stage(
-		(step.progress?.weight || 1) / totalProgressWeight
-	);
-
-	const args: any = {};
-	for (const key of Object.keys(step)) {
-		let value = (step as any)[key];
-		if (isFileReference(value)) {
-			value = Resource.create(value, {
-				semaphore,
-			});
-		}
-		args[key] = value;
-	}
-
-	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();
-		}
-	};
-
-	/**
-	 * The weight of each async resource is the same, and is the same as the
-	 * weight of the step itself.
-	 */
-	const resources = getResources(args);
-	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 { run, step, resources };
-}
-
-/**
- * Gets the resources used by a specific compiled step
- *
- * @param step The compiled step
- * @returns The resources used by the compiled 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;
-}
-
-/**
- * Replaces Resource objects with their resolved values
- *
- * @param step The compiled step
- * @returns The resources used by the compiled step
- */
-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) {
-			resolved[argName] = await resourceMaybe.resolve();
-		} else {
-			resolved[argName] = resourceMaybe;
-		}
-	}
-	return resolved;
-}
-
-export async function runBlueprintSteps(
-	compiledBlueprint: CompiledBlueprint,
-	playground: UniversalPHP
-) {
-	await compiledBlueprint.run(playground);
-}

package/src/lib/resources.ts

@@ -1,417 +0,0 @@
-import {
-	cloneResponseMonitorProgress,
-	ProgressTracker,
-} from '@php-wasm/progress';
-import { UniversalPHP } from '@php-wasm/universal';
-import { Semaphore } from '@php-wasm/util';
-import { zipNameToHumanName } from './steps/common';
-
-export const ResourceTypes = [
-	'vfs',
-	'literal',
-	'wordpress.org/themes',
-	'wordpress.org/plugins',
-	'url',
-] as const;
-
-export type VFSReference = {
-	/** Identifies the file resource as Virtual File System (VFS) */
-	resource: 'vfs';
-	/** The path to the file in the VFS */
-	path: string;
-};
-export type LiteralReference = {
-	/** Identifies the file resource as a literal file */
-	resource: 'literal';
-	/** The name of the file */
-	name: string;
-	/** The contents of the file */
-	contents: string | Uint8Array;
-};
-export type CoreThemeReference = {
-	/** Identifies the file resource as a WordPress Core theme */
-	resource: 'wordpress.org/themes';
-	/** The slug of the WordPress Core theme */
-	slug: string;
-};
-export type CorePluginReference = {
-	/** Identifies the file resource as a WordPress Core plugin */
-	resource: 'wordpress.org/plugins';
-	/** The slug of the WordPress Core plugin */
-	slug: string;
-};
-export type UrlReference = {
-	/** Identifies the file resource as a URL */
-	resource: 'url';
-	/** The URL of the file */
-	url: string;
-	/** Optional caption for displaying a progress message */
-	caption?: string;
-};
-
-export type FileReference =
-	| VFSReference
-	| LiteralReference
-	| CoreThemeReference
-	| CorePluginReference
-	| UrlReference;
-
-export function isFileReference(ref: any): ref is FileReference {
-	return (
-		ref &&
-		typeof ref === 'object' &&
-		typeof ref.resource === 'string' &&
-		ResourceTypes.includes(ref.resource)
-	);
-}
-
-export interface ResourceOptions {
-	/** Optional semaphore to limit concurrent downloads */
-	semaphore?: Semaphore;
-	progress?: ProgressTracker;
-}
-export abstract class Resource {
-	/** Optional progress tracker to monitor progress */
-	public abstract progress?: ProgressTracker;
-	/** A Promise that resolves to the file contents */
-	protected promise?: Promise<File>;
-
-	protected playground?: UniversalPHP;
-
-	/**
-	 * Creates a new Resource based on the given file reference
-	 *
-	 * @param ref The file reference to create the Resource for
-	 * @param options Additional options for the Resource
-	 * @returns A new Resource instance
-	 */
-	static create(
-		ref: FileReference,
-		{ semaphore, progress }: ResourceOptions
-	): Resource {
-		let resource: Resource;
-		switch (ref.resource) {
-			case 'vfs':
-				resource = new VFSResource(ref, progress);
-				break;
-			case 'literal':
-				resource = new LiteralResource(ref, progress);
-				break;
-			case 'wordpress.org/themes':
-				resource = new CoreThemeResource(ref, progress);
-				break;
-			case 'wordpress.org/plugins':
-				resource = new CorePluginResource(ref, progress);
-				break;
-			case 'url':
-				resource = new UrlResource(ref, progress);
-				break;
-			default:
-				throw new Error(`Invalid resource: ${ref}`);
-		}
-		resource = new CachedResource(resource);
-
-		if (semaphore) {
-			resource = new SemaphoreResource(resource, semaphore);
-		}
-
-		return resource;
-	}
-
-	setPlayground(playground: UniversalPHP) {
-		this.playground = playground;
-	}
-
-	/**
-	 * Resolves the file contents
-	 * @returns The resolved file.
-	 */
-	abstract resolve(): Promise<File>;
-
-	/** The name of the referenced file */
-	abstract get name(): string;
-
-	/** Whether this Resource is loaded asynchronously */
-	get isAsync(): boolean {
-		return false;
-	}
-}
-/**
- * A `Resource` that represents a file in the VFS (virtual file system) of the playground.
- */
-export class VFSResource extends Resource {
-	/**
-	 * Creates a new instance of `VFSResource`.
-	 * @param playground The playground client.
-	 * @param resource The VFS reference.
-	 * @param progress The progress tracker.
-	 */
-	constructor(
-		private resource: VFSReference,
-		public override progress?: ProgressTracker
-	) {
-		super();
-	}
-
-	/** @inheritDoc */
-	async resolve() {
-		const buffer = await this.playground!.readFileAsBuffer(
-			this.resource.path
-		);
-		this.progress?.set(100);
-		return new File([buffer], this.name);
-	}
-
-	/** @inheritDoc */
-	get name() {
-		return this.resource.path;
-	}
-}
-
-/**
- * A `Resource` that represents a literal file.
- */
-export class LiteralResource extends Resource {
-	/**
-	 * Creates a new instance of `LiteralResource`.
-	 * @param resource The literal reference.
-	 * @param progress The progress tracker.
-	 */
-	constructor(
-		private resource: LiteralReference,
-		public override progress?: ProgressTracker
-	) {
-		super();
-	}
-
-	/** @inheritDoc */
-	async resolve() {
-		this.progress?.set(100);
-		return new File([this.resource.contents], this.resource.name);
-	}
-
-	/** @inheritDoc */
-	get name() {
-		return this.resource.name;
-	}
-}
-
-/**
- * A base class for `Resource`s that require fetching data from a remote URL.
- */
-export abstract class FetchResource extends Resource {
-	/**
-	 * Creates a new instance of `FetchResource`.
-	 * @param progress The progress tracker.
-	 */
-	constructor(public override progress?: ProgressTracker) {
-		super();
-	}
-
-	/** @inheritDoc */
-	async resolve() {
-		this.progress?.setCaption(this.caption);
-		const url = this.getURL();
-		let response = await fetch(url);
-		response = await cloneResponseMonitorProgress(
-			response,
-			this.progress?.loadingListener ?? noop
-		);
-		if (response.status !== 200) {
-			throw new Error(`Could not download "${url}"`);
-		}
-		return new File([await response.blob()], this.name);
-	}
-
-	/**
-	 * Gets the URL to fetch the data from.
-	 * @returns The URL.
-	 */
-	protected abstract getURL(): string;
-
-	/**
-	 * Gets the caption for the progress tracker.
-	 * @returns The caption.
-	 */
-	protected get caption() {
-		return `Downloading ${this.name}`;
-	}
-
-	/** @inheritDoc */
-	get name() {
-		try {
-			return new URL(this.getURL(), 'http://example.com').pathname
-				.split('/')
-				.pop()!;
-		} catch (e) {
-			return this.getURL();
-		}
-	}
-
-	/** @inheritDoc */
-	override get isAsync(): boolean {
-		return true;
-	}
-}
-
-// eslint-disable-next-line @typescript-eslint/no-empty-function
-const noop = (() => {}) as any;
-
-/**
- * A `Resource` that represents a file available from a URL.
- */
-export class UrlResource extends FetchResource {
-	/**
-	 * Creates a new instance of `UrlResource`.
-	 * @param resource The URL reference.
-	 * @param progress The progress tracker.
-	 */
-	constructor(private resource: UrlReference, progress?: ProgressTracker) {
-		super(progress);
-	}
-
-	/** @inheritDoc */
-	getURL() {
-		return this.resource.url;
-	}
-
-	/** @inheritDoc */
-	protected override get caption() {
-		return this.resource.caption ?? super.caption;
-	}
-}
-
-let pluginProxyURL = 'https://playground.wordpress.net/plugin-proxy';
-export function setPluginProxyURL(url: string) {
-	pluginProxyURL = url;
-}
-
-/**
- * A `Resource` that represents a WordPress core theme.
- */
-export class CoreThemeResource extends FetchResource {
-	constructor(
-		private resource: CoreThemeReference,
-		progress?: ProgressTracker
-	) {
-		super(progress);
-	}
-	override get name() {
-		return zipNameToHumanName(this.resource.slug);
-	}
-	getURL() {
-		const zipName = toDirectoryZipName(this.resource.slug);
-		return `${pluginProxyURL}?theme=` + zipName;
-	}
-}
-
-/**
- * A resource that fetches a WordPress plugin from wordpress.org.
- */
-export class CorePluginResource extends FetchResource {
-	constructor(
-		private resource: CorePluginReference,
-		progress?: ProgressTracker
-	) {
-		super(progress);
-	}
-
-	/** @inheritDoc */
-	override get name() {
-		return zipNameToHumanName(this.resource.slug);
-	}
-
-	/** @inheritDoc */
-	getURL() {
-		const zipName = toDirectoryZipName(this.resource.slug);
-		return `${pluginProxyURL}?plugin=` + zipName;
-	}
-}
-
-/**
- * Transforms a plugin slug into a directory zip name.
- * If the input already ends with ".zip", returns it unchanged.
- * Otherwise, appends ".latest-stable.zip".
- */
-export function toDirectoryZipName(rawInput: string) {
-	if (!rawInput) {
-		return rawInput;
-	}
-	if (rawInput.endsWith('.zip')) {
-		return rawInput;
-	}
-	return rawInput + '.latest-stable.zip';
-}
-
-/**
- * A decorator for a resource that adds functionality such as progress tracking and caching.
- */
-export class DecoratedResource<T extends Resource> extends Resource {
-	constructor(private resource: T) {
-		super();
-	}
-
-	/** @inheritDoc */
-	async resolve() {
-		return this.resource.resolve();
-	}
-
-	/** @inheritDoc */
-	override async setPlayground(playground: UniversalPHP) {
-		return this.resource.setPlayground(playground);
-	}
-
-	/** @inheritDoc */
-	get progress() {
-		return this.resource.progress;
-	}
-
-	/** @inheritDoc */
-	set progress(value) {
-		this.resource.progress = value;
-	}
-
-	/** @inheritDoc */
-	get name() {
-		return this.resource.name;
-	}
-
-	/** @inheritDoc */
-	override get isAsync() {
-		return this.resource.isAsync;
-	}
-}
-
-/**
- * A decorator for a resource that adds caching functionality.
- */
-export class CachedResource<T extends Resource> extends DecoratedResource<T> {
-	protected override promise?: Promise<File>;
-
-	/** @inheritDoc */
-	override async resolve() {
-		if (!this.promise) {
-			this.promise = super.resolve();
-		}
-		return this.promise;
-	}
-}
-
-/**
- * A decorator for a resource that adds concurrency control functionality through a semaphore.
- */
-export class SemaphoreResource<
-	T extends Resource
-> extends DecoratedResource<T> {
-	constructor(resource: T, private readonly semaphore: Semaphore) {
-		super(resource);
-	}
-
-	/** @inheritDoc */
-	override async resolve() {
-		if (!this.isAsync) {
-			return super.resolve();
-		}
-		return this.semaphore.run(() => super.resolve());
-	}
-}

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

@@ -1,35 +0,0 @@
-import { StepHandler } from '.';
-import { asDOM } from './common';
-
-export interface ActivatePluginStep {
-	step: 'activatePlugin';
-	plugin: string;
-}
-
-/**
- * Activates a WordPress plugin in the Playground.
- *
- * @param playground The playground client.
- * @param plugin The plugin slug.
- */
-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',
-		})
-	);
-
-	const link = pluginsPage.querySelector(
-		`tr[data-slug="${plugin}"] a`
-	)! as HTMLAnchorElement;
-	const href = link.attributes.getNamedItem('href')!.value;
-
-	await playground.request({
-		url: '/wp-admin/' + href,
-	});
-};