Playground Blueprints

[adamziel]

Description

Adds Blueprints – a declarative data format for setting up new Playground instances. The big idea is:

• @wp-playground/client has python-like batteries, e.g. installPlugin, login, importFile etc
• The Blueprint is a JSON file that says which of these batteries to call and in which order
• In addition, Blueprint can invoke specific lower-level functions like php.writeFile
• External resources are declared upfront and fetch()-ed in parallel

Because Blueprints merely invoke the existing Playground client functions, an advanced user may choose to not use them at all and setup their Playground using a bootstrap script that would invoke the same publicly exported functions.

Blueprints have three advantages over using a custom JavaScript file like setup.js:

• You don’t need to run untrusted JS code – handy for wp.org or any case of sharing blueprints
• It automatically fetches files and updates progress bars
• In the future, there will be a mergeBlueprints() function to turn a list of Blueprints into a single Blueprint. Technically, it will concatenate the steps, parallelize resource fetching, and resolve any PHP and WP version constraints from all the merged Blueprints.

Example

The new loadPlayground helper makes setting up a Playground instance as easy as:

const playground = await loadPlayground({
	iframe,
	remoteUrl: `https://playground.wordpress.net/remote.html`,
	blueprint: {
		"landingPage": "/wp-admin/",
		"preferredVersions": {
			"php": "8.0",
			"wp": "latest"
		},
		"steps": [
			{ "step": "login", "username": "admin", "password": "password" },
			{
				"step": "installPlugin",
				"pluginZipFile": { "resource": "wordpress.org/plugins", "slug": "friends" }
			}
		]
	}
})

Here's a longer example. The following blueprint logs you in as admin, installs the twentytwentytwo theme, installs the gutenberg plugin, and redirects the user to /wp-admin.

{
	"landingPage": "/wp-admin/?welcome=0",
	"preferredVersions": {
		"php": "8.0",
		"wp": "latest"
	},
	"steps": [
		{
			"step": "login",
			"username": "admin",
			"password": "password"
		},
		{
			"step": "mkdir",
			"path": "/wordpress/wp-content/languages/plugins"
		},
		{
			"step": "writeFile",
			"path": "/wordpress/wp-content/languages/plugin-name/en.json",
			"data": {
				"resource": "url",
				"caption": "Downloading plugin-name language file",
				"url": "https://example.com/plugin-name/en.json"
			}
		},
		{
			"step": "setSiteOptions",
			"options": {
				"WPLANG": "en",
				"permalink_structure": "/%year%/%monthnum%/%day%/%postname%/",
				"gp_enable_local_translation": 1,
				"gp_enable_inline_translation": 1
			}
		},
		{
			"step": "updateUserMeta",
			"meta": {
				"show_welcome_panel": "0"
			},
			"userId": 1
		},
		{
			"step": "writeFile",
			"path": "/wordpress/wp-content/mu-plugins/gp-sqlite.php",
			"data": "<?php\n\tadd_filter('query', function( $query ) {\n\t\treturn str_replace( ' BINARY ', ' ', $query);\n\t} );\n"
		},
		{
			"step": "installPlugin",
			"pluginZipFile": {
				"resource": "wordpress.org/plugins",
				"slug": "glotpress-local"
			}
		}
	]
}

Steps

For the first version, Blueprints support the following steps:

export type Step<ResourceType> = (
	| {
			step: 'installPlugin';
			pluginZipFile: ResourceType;
			options?: InstallPluginOptions;
	  }
	| {
			step: 'installTheme';
			themeZipFile: ResourceType;
			options?: InstallThemeOptions;
	  }
	| {
			step: 'login';
			username?: string;
			password?: string;
	  }
	| {
			step: 'importFile';
			file: ResourceType;
	  }
	| {
			step: 'activatePlugin';
			plugin: string;
	  }
	| {
			step: 'replaceSite';
			fullSiteZip: ResourceType;
	  }
	| {
			step: 'unzip';
			zipPath: string;
			extractToPath: string;
	  }
	| {
			step: 'setSiteOptions';
			options: SiteOptions;
	  }
	| {
			step: 'updateUserMeta';
			meta: UserMeta;
			userId: number;
	  }
	| {
			step: 'runPHP';
			code: string;
	  }
	| {
			step: 'runPHPWithOptions';
			options?: PHPRunOptions;
	  }
	| {
			step: 'setPhpIniEntry';
			key: string;
			value: string;
	  }
	| {
			step: 'request';
			request: PHPRequest;
			maxRedirects?: number;
	  }
	| {
			step: 'cp';
			fromPath: string;
			toPath: string;
	  }
	| {
			step: 'mv';
			fromPath: string;
			toPath: string;
	  }
	| {
			step: 'mkdir';
			path: string;
	  }
	| {
			step: 'rm';
			path: string;
	  }
	| {
			step: 'rmdir';
			path: string;
	  }
	| {
			step: 'fetch';
			url: string;
			path: string;
	  }
	| {
			step: 'writeFile';
			path: string;
			data: ResourceType | string | Uint8Array;
	  }

Other notes

This PR also moves the progress bar UI component from Playground Website to remote.html to make reusable in other apps. Virtually every Playground consumer will want to display a progress bar, there's no need to ask everyone to reimplement it when Playground can provide a convenient API.

Solves #201
Related to #115

cc @bengreeley @akirk @dmsnell @StevenDufresne

[adamziel]

I simplified the JSON structure to remove "resources" and started on automatic progress management, applying a blueprint will now provide progress % and a human-readable caption. Some more changes incoming.

[adamziel]

I'm noodling on setting up GlotPress playground using blueprints, here's what I have so far:
https://gist.github.com/adamziel/d3270b8ce1f18b465bdcbc2dcd103f4d

[adamziel]

OK I think this is ready! See the updated example in the PR description. I'm planning to split this into smaller changesets and start merging them. If you were holding back with any feedback, now is a good time to share it.

[adamziel]

We're down to 27 updated files from 85 in the beginning. I'd say that's good enough. Let's merge!