[Blueprints] Rename Blueprints v1 types, add Blueprint v2 types (#2648)

## Motivation for the change, related issues

Renames Blueprint v1-related types an explicit "v1" in the name.
Declares Blueprint v2-related types such as the schema from the
[proposal](https://github.com/Automattic/WordPress-extension-proposals/blob/trunk/wep-1-blueprint-v2-schema/proposal.md).

A part of #2586. 

## Breaking changes 

This is a breaking change with respect to TypeScript types. The type
named `Blueprint` now means `BlueprintV1 | BlueprintV2` which is a
broader type than before. Therefore, let's do a major version bump after
merging this PR. There are no breaking changes in runtime. cc
@brandonpayton

## Testing Instructions (or ideally a Blueprint)

CI

Author: adamziel

packages/docs/site/src/components/BlueprintsAPI/model.tsx

@@ -5,7 +5,10 @@ const BlueprintsApi = getModule('@wp-playground/blueprints');
 export const BlueprintSteps = BlueprintsApi.children
 	.filter((entry) => entry.name.match(/Step$/))
 	.filter(
-		(entry) => !['CompiledStep', 'GenericStep', 'Step'].includes(entry.name)
+		(entry) =>
+			!['CompiledStep', 'CompiledV1Step', 'GenericStep', 'Step'].includes(
+				entry.name
+			)
 	)
 	.filter((entry) => !entry?.flags?.isPrivate)
 	.map((entry) => entry.name)

packages/playground/blueprints/src/index.ts

@@ -2,23 +2,29 @@
 import '@php-wasm/node-polyfills';
 
 export type {
-	Blueprint,
-	BlueprintBundle,
+	BlueprintV1,
 	BlueprintV1Declaration,
-	// For backwards compatibility:
-	BlueprintV1Declaration as BlueprintDeclaration,
 	PHPConstants,
 } from './lib/v1/types';
+export type {
+	Blueprint,
+	BlueprintBundle,
+	BlueprintDeclaration,
+} from './lib/types';
 export {
-	compileBlueprint,
 	getBlueprintDeclaration,
 	isBlueprintBundle,
-	runBlueprintSteps,
+	compileBlueprintV1,
+	runBlueprintV1Steps,
+
+	// BC:
+	compileBlueprintV1 as compileBlueprint,
+	runBlueprintV1Steps as runBlueprintSteps,
 } from './lib/v1/compile';
 export type {
-	CompileBlueprintOptions,
-	CompiledBlueprint,
-	CompiledStep,
+	CompileBlueprintV1Options,
+	CompiledBlueprintV1,
+	CompiledV1Step,
 	OnStepCompleted,
 } from './lib/v1/compile';
 export type {
@@ -43,8 +49,8 @@ export type {
 export * from './lib/steps';
 export * from './lib/steps/handlers';
 export type {
-	BlueprintV2Declaration,
-	ParsedBlueprintV2Declaration,
+	RawBlueprintV2Data,
+	ParsedBlueprintV2String,
 } from './lib/v2/blueprint-v2-declaration';
 export { getV2Runner } from './lib/v2/get-v2-runner';
 export { runBlueprintV2 } from './lib/v2/run-blueprint-v2';

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

@@ -4,7 +4,7 @@ import {
 	OverlayFilesystem,
 	ZipFilesystem,
 } from '@wp-playground/storage';
-import type { BlueprintBundle } from './v1/types';
+import type { BlueprintBundle } from './types';
 
 /**
  * Resolves a remote blueprint from a URL.

packages/playground/blueprints/src/lib/types.ts

@@ -0,0 +1,13 @@
+import type { Filesystem } from '@wp-playground/storage';
+import type { V2Schema } from './v2/wep-1-blueprint-v2-schema/appendix-A-blueprint-v2-schema';
+import type { BlueprintV1, BlueprintV1Declaration } from './v1/types';
+import type { RawBlueprintV2Data } from './v2/blueprint-v2-declaration';
+
+/**
+ * A filesystem structure containing a /blueprint.json file and any
+ * resources referenced by that blueprint.
+ */
+export type BlueprintBundle = Filesystem;
+
+export type BlueprintDeclaration = BlueprintV1Declaration | RawBlueprintV2Data;
+export type Blueprint = BlueprintV1 | V2Schema.BlueprintV2;

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

@@ -1,7 +1,7 @@
 import { PHP } from '@php-wasm/universal';
 import {
-	compileBlueprint,
-	runBlueprintSteps,
+	compileBlueprintV1,
+	runBlueprintV1Steps,
 	validateBlueprint,
 } from './compile';
 import { defineWpConfigConsts } from '../steps/define-wp-config-consts';
@@ -26,8 +26,8 @@ describe('Blueprints', () => {
 	});
 
 	it('should run a basic blueprint', async () => {
-		await runBlueprintSteps(
-			await compileBlueprint({
+		await runBlueprintV1Steps(
+			await compileBlueprintV1({
 				steps: [
 					{
 						step: 'writeFile',
@@ -84,8 +84,8 @@ describe('Blueprints', () => {
 	});
 
 	it('Should boot with WP-CLI support if the wpCli feature is enabled', async () => {
-		await runBlueprintSteps(
-			await compileBlueprint({
+		await runBlueprintV1Steps(
+			await compileBlueprintV1({
 				extraLibraries: ['wp-cli'],
 			}),
 			php
@@ -101,9 +101,9 @@ describe('Blueprints', () => {
 		);
 		const zipData = fs.readFileSync(zipPath).buffer;
 		const zipBundle = ZipFilesystem.fromArrayBuffer(zipData);
-		const compiledBlueprint = await compileBlueprint(zipBundle);
+		const compiledBlueprint = await compileBlueprintV1(zipBundle);
 
-		await runBlueprintSteps(compiledBlueprint, php);
+		await runBlueprintV1Steps(compiledBlueprint, php);
 
 		expect(php.fileExists('/index.php')).toBe(true);
 		expect(php.readFileAsText('/index.php')).toContain('<?php echo');
@@ -130,9 +130,9 @@ describe('Blueprints', () => {
 				],
 			}),
 		});
-		const compiledBlueprint = await compileBlueprint(fileTreeBundle);
+		const compiledBlueprint = await compileBlueprintV1(fileTreeBundle);
 
-		await runBlueprintSteps(compiledBlueprint, php);
+		await runBlueprintV1Steps(compiledBlueprint, php);
 
 		expect(php.fileExists('/text_file.txt')).toBe(true);
 		expect(php.readFileAsText('/text_file.txt')).toContain(

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

@@ -11,11 +11,11 @@ import type { Step, StepDefinition, WriteFileStep } from '../steps';
 import * as allStepHandlers from '../steps/handlers';
 import type {
 	BlueprintV1Declaration,
-	BlueprintBundle,
 	ExtraLibrary,
 	StreamBundledFile,
-	Blueprint,
+	BlueprintV1,
 } from './types';
+import type { BlueprintBundle } from '../types';
 import { logger } from '@php-wasm/logger';
 
 // @TODO: Configure this in the `wp-cli` step, not here.
@@ -42,9 +42,9 @@ const keyedStepHandlers = {
 import blueprintValidator from '../../../public/blueprint-schema-validator';
 import { defaultWpCliPath, defaultWpCliResource } from '../steps/wp-cli';
 
-export type CompiledStep = (php: UniversalPHP) => Promise<void> | void;
+export type CompiledV1Step = (php: UniversalPHP) => Promise<void> | void;
 
-export interface CompiledBlueprint {
+export interface CompiledBlueprintV1 {
 	/** The requested versions of PHP and WordPress for the blueprint */
 	versions: {
 		php: SupportedPHPVersion;
@@ -62,7 +62,7 @@ export interface CompiledBlueprint {
 
 export type OnStepCompleted = (output: any, step: StepDefinition) => any;
 
-export interface CompileBlueprintOptions {
+export interface CompileBlueprintV1Options {
 	/** Optional progress tracker to monitor progress */
 	progress?: ProgressTracker;
 	/** Optional semaphore to control access to a shared resource */
@@ -87,11 +87,11 @@ export interface CompileBlueprintOptions {
 	additionalSteps?: any[];
 }
 
-export async function compileBlueprint(
+export async function compileBlueprintV1(
 	input: BlueprintV1Declaration | BlueprintBundle,
-	options: Omit<CompileBlueprintOptions, 'streamBundledFile'> = {}
-): Promise<CompiledBlueprint> {
-	const finalOptions: CompileBlueprintOptions = {
+	options: Omit<CompileBlueprintV1Options, 'streamBundledFile'> = {}
+): Promise<CompiledBlueprintV1> {
+	const finalOptions: CompileBlueprintV1Options = {
 		...options,
 	};
 
@@ -113,7 +113,7 @@ export function isBlueprintBundle(input: any): input is BlueprintBundle {
 }
 
 export async function getBlueprintDeclaration(
-	blueprint: Blueprint
+	blueprint: BlueprintV1 | BlueprintBundle
 ): Promise<BlueprintV1Declaration> {
 	if (!isBlueprintBundle(blueprint)) {
 		return blueprint;
@@ -140,8 +140,8 @@ function compileBlueprintJson(
 		corsProxy,
 		streamBundledFile,
 		additionalSteps,
-	}: CompileBlueprintOptions = {}
-): CompiledBlueprint {
+	}: CompileBlueprintV1Options = {}
+): CompiledBlueprintV1 {
 	blueprint = structuredClone(blueprint);
 
 	blueprint = {
@@ -502,7 +502,7 @@ interface CompileStepArgsOptions {
 	/**
 	 * Proxy URL to use for cross-origin requests.
 	 *
-	 * @see CompileBlueprintOptions.corsProxy
+	 * @see CompileBlueprintV1Options.corsProxy
 	 */
 	corsProxy?: string;
 	/**
@@ -528,7 +528,7 @@ function compileStep<S extends StepDefinition>(
 		corsProxy,
 		streamBundledFile,
 	}: CompileStepArgsOptions
-): { run: CompiledStep; step: S; resources: Array<Resource<any>> } {
+): { run: CompiledV1Step; step: S; resources: Array<Resource<any>> } {
 	const stepProgress = rootProgressTracker.stage(
 		(step.progress?.weight || 1) / totalProgressWeight
 	);
@@ -615,8 +615,8 @@ async function resolveArguments<T extends Record<string, unknown>>(args: T) {
 	return resolved;
 }
 
-export async function runBlueprintSteps(
-	compiledBlueprint: CompiledBlueprint,
+export async function runBlueprintV1Steps(
+	compiledBlueprint: CompiledBlueprintV1,
 	playground: UniversalPHP
 ) {
 	await compiledBlueprint.run(playground);

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

@@ -2,7 +2,7 @@ import type { SupportedPHPVersion } from '@php-wasm/universal';
 import type { StepDefinition } from '../steps';
 import type { FileReference } from './resources';
 import type { StreamedFile } from '@php-wasm/stream-compression';
-import type { Filesystem } from '@wp-playground/storage';
+import type { BlueprintBundle } from '../types';
 
 export type ExtraLibrary =
 	// Install WP-CLI during boot.
@@ -12,13 +12,7 @@ export type PHPConstants = Record<string, string | boolean | number>;
 
 export type StreamBundledFile = (relativePath: string) => Promise<StreamedFile>;
 
-export type Blueprint = BlueprintBundle | BlueprintV1Declaration;
-
-/**
- * A filesystem structure containing a /blueprint.json file and any
- * resources referenced by that blueprint.
- */
-export type BlueprintBundle = Filesystem;
+export type BlueprintV1 = BlueprintV1Declaration | BlueprintBundle;
 
 /**
  * The Blueprint declaration, typically stored in a blueprint.json file.

packages/playground/blueprints/src/lib/v2/blueprint-v2-declaration.ts

@@ -1,16 +1,13 @@
 import type { BlueprintV1Declaration } from '../v1/types';
 
-export type BlueprintV2Declaration =
-	| string
-	| BlueprintV1Declaration
-	| undefined;
-export type ParsedBlueprintV2Declaration =
+export type RawBlueprintV2Data = string | BlueprintV1Declaration | undefined;
+export type ParsedBlueprintV2String =
 	| { type: 'inline-file'; contents: string }
 	| { type: 'file-reference'; reference: string };
 
 export function parseBlueprintDeclaration(
-	source: BlueprintV2Declaration | ParsedBlueprintV2Declaration
-): ParsedBlueprintV2Declaration {
+	source: RawBlueprintV2Data | ParsedBlueprintV2String
+): ParsedBlueprintV2String {
 	if (
 		typeof source === 'object' &&
 		'type' in source &&

packages/playground/blueprints/src/lib/v2/run-blueprint-v2.ts

@@ -6,8 +6,8 @@ import {
 import { phpVar } from '@php-wasm/util';
 import { getV2Runner } from './get-v2-runner';
 import {
-	type BlueprintV2Declaration,
-	type ParsedBlueprintV2Declaration,
+	type RawBlueprintV2Data,
+	type ParsedBlueprintV2String,
 	parseBlueprintDeclaration,
 } from './blueprint-v2-declaration';
 
@@ -32,7 +32,7 @@ export type BlueprintMessage =
 interface RunV2Options {
 	php: UniversalPHP;
 	cliArgs?: string[];
-	blueprint: BlueprintV2Declaration | ParsedBlueprintV2Declaration;
+	blueprint: RawBlueprintV2Data | ParsedBlueprintV2String;
 	blueprintOverrides?: {
 		wordpressVersion?: string;
 		additionalSteps?: any[];