Settle the API shape

Author: adamziel

.eslintrc.json

@@ -11,7 +11,12 @@
 					{
 						"enforceBuildableLibDependency": true,
 						"allow": [],
-						"depConstraints": []
+						"depConstraints": [
+							{
+								"sourceTag": "*",
+								"notDependOnLibsWithTags": ["scope:web-client"]
+							}
+						]
 					}
 				],
 				"no-inner-declarations": 0,

packages/php-wasm/cli/project.json

@@ -34,7 +34,7 @@
 			"options": {
 				"scriptPath": "dist/packages/php-wasm/cli/main.js"
 			},
-			"dependsOn": ["build", "^build-for-cli-run"]
+			"dependsOn": ["build"]
 		},
 		"publish": {
 			"executor": "nx:run-commands",

packages/php-wasm/node/.eslintrc.json

@@ -4,15 +4,7 @@
 	"overrides": [
 		{
 			"files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
-			"rules": {
-				"@nrwl/nx/enforce-module-boundaries": [
-					"error",
-					{
-						"enforceBuildableLibDependency": true,
-						"allow": ["@php-wasm/universal"]
-					}
-				]
-			}
+			"rules": {}
 		},
 		{
 			"files": ["*.ts", "*.tsx"],

packages/php-wasm/progress/src/lib/progress-tracker.ts

@@ -153,7 +153,10 @@ export class ProgressTracker extends EventTarget {
 	 * subTracker1.set(100);
 	 * ```
 	 */
-	stage(weight: number, caption = ''): ProgressTracker {
+	stage(weight?: number, caption = ''): ProgressTracker {
+		if (!weight) {
+			weight = this._selfWeight;
+		}
 		if (this._selfWeight - weight < -Number.EPSILON) {
 			throw new Error(
 				`Cannot add a stage with weight ${weight} as the total weight of registered stages would exceed 1.`

packages/php-wasm/universal/project.json

@@ -4,7 +4,7 @@
 	"sourceRoot": "packages/php-wasm/universal/src",
 	"projectType": "library",
 	"targets": {
-		"build-for-cli-run": {
+		"build": {
 			"executor": "@nrwl/vite:build",
 			"outputs": ["{options.outputPath}"],
 			"options": {

packages/php-wasm/web/.eslintrc.json

@@ -4,14 +4,7 @@
 	"overrides": [
 		{
 			"files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
-			"rules": {
-				"@nrwl/nx/enforce-module-boundaries": [
-					"error",
-					{
-						"allow": ["php-wasm-universal"]
-					}
-				]
-			}
+			"rules": {}
 		},
 		{
 			"files": ["*.ts", "*.tsx"],

packages/playground/blueprints/src/lib/steps/apply-wordpress-patches/index.ts

@@ -9,8 +9,6 @@ export interface PatchOptions {
 	patchSiteUrl?: boolean;
 	disableSiteHealth?: boolean;
 	disableWpNewBlogNotification?: boolean;
-	replaceRequestsTransports?: boolean;
-	allowWpOrgHosts?: boolean;
 }
 
 export async function applyWordPressPatches(
@@ -38,9 +36,6 @@ export async function applyWordPressPatches(
 	if (options.disableWpNewBlogNotification !== false) {
 		await patch.disableWpNewBlogNotification();
 	}
-	if (options.allowWpOrgHosts !== false) {
-		await patch.allowWpOrgHosts();
-	}
 }
 
 class WordPressPatcher {
@@ -78,6 +73,7 @@ class WordPressPatcher {
 			'<?php phpinfo(); '
 		);
 	}
+
 	async patchSiteUrl() {
 		await patchFile(
 			this.php,
@@ -91,6 +87,7 @@ class WordPressPatcher {
 				?>${contents}`
 		);
 	}
+
 	async disableSiteHealth() {
 		await patchFile(
 			this.php,
@@ -102,30 +99,14 @@ class WordPressPatcher {
 				)
 		);
 	}
+
 	async disableWpNewBlogNotification() {
 		await patchFile(
 			this.php,
 			`${this.wordpressPath}/wp-config.php`,
-			// The original version of this function crashes WASM WordPress, let's define an empty one instead.
+			// The original version of this function crashes WASM PHP, let's define an empty one instead.
 			(contents) =>
 				`${contents} function wp_new_blog_notification(...$args){} `
 		);
 	}
-
-	async allowWpOrgHosts() {
-		await this.php.mkdirTree(`${this.wordpressPath}/wp-content/mu-plugins`);
-		await this.php.writeFile(
-			`${this.wordpressPath}/wp-content/mu-plugins/0-allow-wp-org.php`,
-			`<?php
-			// Needed because gethostbyname( 'wordpress.org' ) returns
-			// a private network IP address for some reason.
-			add_filter( 'allowed_redirect_hosts', function( $deprecated = '' ) {
-				return array( 
-					'wordpress.org',
-					'api.wordpress.org',
-					'downloads.wordpress.org',
-				);
-			} );`
-		);
-	}
 }

packages/playground/client/project.json

@@ -121,5 +121,5 @@
 			}
 		}
 	},
-	"tags": []
+	"tags": ["scope:web-client"]
 }

packages/playground/client/src/index.ts

@@ -25,69 +25,79 @@ export interface StartPlaygroundOptions {
 	blueprint?: Blueprint;
 }
 
-const officialRemoteOrigin = 'https://playground.wordpress.net';
-
 /**
  * Loads playground in iframe and returns a PlaygroundClient instance.
- * Optionally
  *
  * @param iframe Any iframe with Playground's remote.html loaded.
  * @param options Options for loading the playground.
  * @returns A PlaygroundClient instance.
  */
-export async function startPlayground(
-	options: StartPlaygroundOptions
-): Promise<PlaygroundClient> {
-	const blueprint: Blueprint = {
-		...(options.blueprint || {}),
-		preferredVersions: {
-			php: '8.0',
-			wp: 'latest',
-			...(options.blueprint?.preferredVersions || {}),
-		},
-	};
-	const tracker = options.progressTracker || new ProgressTracker();
-	tracker.setCaption('Preparing WordPress');
+export async function startPlaygroundWeb({
+	iframe,
+	blueprint,
+	remoteUrl,
+	progressTracker = new ProgressTracker(),
+	disableProgressBar,
+}: StartPlaygroundOptions): Promise<PlaygroundClient> {
+	assertValidRemote(remoteUrl);
+	remoteUrl = setQueryParams(remoteUrl, {
+		progressbar: !disableProgressBar,
+	});
+	progressTracker.setCaption('Preparing WordPress');
+	if (!blueprint) {
+		return doStartPlaygroundWeb(iframe, remoteUrl, progressTracker);
+	}
 
 	const compiled = compileBlueprint(blueprint, {
-		progress: tracker.stage(0.5),
+		progress: progressTracker.stage(0.5),
 	});
+	const playground = await doStartPlaygroundWeb(
+		iframe,
+		setQueryParams(remoteUrl, {
+			php: compiled.versions.php,
+			wp: compiled.versions.wp,
+		}),
+		progressTracker
+	);
+	await runBlueprintSteps(compiled, playground);
+	await playground.goTo(compiled.landingPage);
+	return playground;
+}
 
-	// Load playground in an iframe
+/**
+ * Internal function to connect an iframe to the playground remote.
+ *
+ * @param iframe
+ * @param remoteUrl
+ * @param progressTracker
+ * @returns
+ */
+async function doStartPlaygroundWeb(
+	iframe: HTMLIFrameElement,
+	remoteUrl: string,
+	progressTracker: ProgressTracker
+) {
 	await new Promise((resolve) => {
-		options.iframe.src = remoteURL(
-			options.remoteUrl,
-			compiled?.versions.php,
-			compiled?.versions.wp,
-			options.disableProgressBar
-		);
-		options.iframe.addEventListener('load', resolve, false);
+		iframe.src = remoteUrl;
+		iframe.addEventListener('load', resolve, false);
 	});
 
-	// Connect the Comlink client
-	const playground = createClient(options.iframe);
+	// Connect the Comlink client and wait until the
+	// playground is ready.
+	const playground = consumeAPI<PlaygroundClient>(
+		iframe.contentWindow!
+	) as PlaygroundClient;
 	await playground.connected;
-
-	// Wait for playground to be ready and display the progress
-	tracker.pipe(playground);
-	const downloadTracker = compiled.steps.length
-		? tracker.stage(0.5)
-		: tracker;
-	await playground.onDownloadProgress(downloadTracker.loadingListener);
+	progressTracker.pipe(playground);
+	await playground.onDownloadProgress(
+		progressTracker.stage().loadingListener
+	);
 	await playground.isReady();
-
-	await runBlueprintSteps(compiled, playground);
-	await playground.goTo(compiled.landingPage);
-
 	return playground;
 }
 
-function remoteURL(
-	remoteHtmlUrl: string,
-	php: string,
-	wp: string,
-	disableProgressBar = false
-) {
+const officialRemoteOrigin = 'https://playground.wordpress.net';
+function assertValidRemote(remoteHtmlUrl: string) {
 	const url = new URL(remoteHtmlUrl);
 	if (
 		(url.origin === officialRemoteOrigin || url.hostname === 'localhost') &&
@@ -98,20 +108,22 @@ function remoteURL(
 				`Expected origin to be ${officialRemoteOrigin}/remote.html.`
 		);
 	}
+}
 
-	const qs = new URLSearchParams({
-		php,
-		wp,
-	});
-	if (!disableProgressBar) {
-		qs.set('progressbar', '1');
+function setQueryParams(url: string, params: Record<string, unknown>) {
+	const urlObject = new URL(url);
+	const qs = new URLSearchParams(urlObject.search);
+	for (const [key, value] of Object.entries(params)) {
+		if (value !== undefined && value !== null && value !== false) {
+			qs.set(key, value.toString());
+		}
 	}
-	url.search = qs.toString();
-	return url.toString();
+	urlObject.search = qs.toString();
+	return urlObject.toString();
 }
 
 /**
- * @deprecated Use `loadPlayground` instead.
+ * @deprecated Use `startPlayground` instead.
  *
  * @param iframe Any iframe with Playground's remote.html loaded.
  * @param options Optional. If `loadRemote` is set, the iframe's `src` will be set to that URL.
@@ -122,24 +134,18 @@ export async function connectPlayground(
 	iframe: HTMLIFrameElement,
 	options?: { loadRemote?: string }
 ): Promise<PlaygroundClient> {
+	console.warn(
+		'`connectPlayground` is deprecated and will be removed. Use `startPlayground` instead.'
+	);
 	if (options?.loadRemote) {
-		return startPlayground({
+		return startPlaygroundWeb({
 			iframe,
 			remoteUrl: options.loadRemote,
 		});
 	}
-	const client = createClient(iframe);
+	const client = consumeAPI<PlaygroundClient>(
+		iframe.contentWindow!
+	) as PlaygroundClient;
 	await client.connected;
 	return client;
 }
-
-export function createClient(iframe: HTMLIFrameElement): PlaygroundClient {
-	const client = consumeAPI<PlaygroundClient>(iframe.contentWindow!);
-
-	/*
-	 * consumeAPI returns Remote<PlaygroundClient>. However,
-	 * PlaygroundClient is has a better DX while still being
-	 * compatible with Remote<PlaygroundClient>. Let's typecast:
-	 */
-	return client as PlaygroundClient;
-}

packages/playground/node/package.json

@@ -1,4 +1,5 @@
 {
 	"name": "@wp-playground/node",
-	"version": "0.0.1"
+	"version": "0.0.1",
+	"private": true
 }