@wp-playground/blueprints 3.0.22 → 3.0.31

package/lib/reflection.d.ts

@@ -14,6 +14,6 @@ export declare class BlueprintReflection {
     getVersion(): number;
     getDeclaration(): import("./v2/wep-1-blueprint-v2-schema/appendix-A-blueprint-v2-schema").V2Schema.BlueprintV2 | BlueprintV1Declaration;
     isBundle(): boolean;
-    getBundle(): import("@wp-playground/storage").Filesystem | undefined;
+    getBundle(): import("@wp-playground/storage").ReadableFilesystemBackend | undefined;
     getBlueprint(): Blueprint;
 }

package/lib/resolve-remote-blueprint.d.ts

@@ -1,4 +1,8 @@
 import type { BlueprintBundle } from './types';
+export declare class BlueprintFetchError extends Error {
+    readonly url: string;
+    constructor(message: string, url: string, options?: ErrorOptions);
+}
 /**
  * Resolves a remote blueprint from a URL.
  *

package/lib/steps/run-php-with-options.d.ts

@@ -7,12 +7,10 @@ import type { PHPRunOptions } from '@php-wasm/universal';
  *
  * <code>
  * {
- * 		"step": "runPHP",
+ * 		"step": "runPHPWithOptions",
  * 		"options": {
- * 			"code": "<?php echo $_SERVER['CONTENT_TYPE']; ?>",
- * 			"headers": {
- * 				"Content-type": "text/plain"
- * 			}
+ * 			"code": "<?php require_once '/wordpress/wp-load.php'; update_option('blogname', file_get_contents('php://input'));?>",
+ * 			"body": "Site Name Modified by runPHPWithOptions"
  * 		}
  * }
  * </code>

package/lib/steps/run-sql.d.ts

@@ -28,8 +28,10 @@ export interface RunSqlStep<ResourceType> {
 /**
  * Run one or more SQL queries.
  *
- * This step will treat each non-empty line in the input SQL as a query and
- * try to execute it using `$wpdb`. Queries spanning multiple lines are not
- * yet supported.
+ * This step uses WP_MySQL_Naive_Query_Stream to parse and execute SQL queries using
+ * streaming semantics. It supports multiline queries, comments, and queries
+ * separated by semicolons. Each query is executed using `$wpdb`. This step assumes
+ * a presence of the `sqlite-database-integration` plugin that ships the required
+ * query tokenizer classes.
  */
 export declare const runSql: StepHandler<RunSqlStep<File>>;

package/lib/types.d.ts

@@ -1,4 +1,4 @@
-import type { Filesystem } from '@wp-playground/storage';
+import type { ReadableFilesystemBackend } from '@wp-playground/storage';
 import type { BlueprintV1, BlueprintV1Declaration, ExtraLibrary, PHPConstants } from './v1/types';
 import type { BlueprintV2, BlueprintV2Declaration } from './v2/blueprint-v2-declaration';
 import type { SupportedPHPVersion } from '@php-wasm/universal';
@@ -6,7 +6,7 @@ import type { SupportedPHPVersion } from '@php-wasm/universal';
  * A filesystem structure containing a /blueprint.json file and any
  * resources referenced by that blueprint.
  */
-export type BlueprintBundle = Filesystem;
+export type BlueprintBundle = ReadableFilesystemBackend;
 export type BlueprintDeclaration = BlueprintV1Declaration | BlueprintV2Declaration;
 export type Blueprint = BlueprintV1 | BlueprintV2;
 export interface RuntimeConfiguration {

package/lib/v1/compile.d.ts

@@ -1,9 +1,31 @@
 import { ProgressTracker } from '@php-wasm/progress';
 import { Semaphore } from '@php-wasm/util';
 import type { SupportedPHPVersion, UniversalPHP } from '@php-wasm/universal';
-import type { StepDefinition } from '../steps';
+import type { Step, StepDefinition } from '../steps';
 import type { BlueprintV1Declaration, ExtraLibrary, StreamBundledFile, BlueprintV1 } from './types';
 import type { BlueprintBundle } from '../types';
+import type { ErrorObject } from 'ajv';
+export declare class InvalidBlueprintError extends Error {
+    readonly validationErrors?: unknown;
+    constructor(message: string, validationErrors?: unknown);
+}
+/**
+ * Error thrown when a single Blueprint step fails during execution.
+ *
+ * This error carries structured information about the failing step so that
+ * consumers (e.g. the Playground UI) do not have to parse human‑readable
+ * error messages to understand what went wrong.
+ */
+export declare class BlueprintStepExecutionError extends Error {
+    readonly stepNumber: number;
+    readonly step: StepDefinition;
+    readonly messages: string[];
+    constructor(options: {
+        stepNumber: number;
+        step: StepDefinition;
+        cause: unknown;
+    });
+}
 export type CompiledV1Step = (php: UniversalPHP) => Promise<void> | void;
 export interface CompiledBlueprintV1 {
     /** The requested versions of PHP and WordPress for the blueprint */
@@ -12,6 +34,7 @@ export interface CompiledBlueprintV1 {
         wp: string;
     };
     features: {
+        /** Should boot with support for Intl dynamic extension */
         intl: boolean;
         /** Should boot with support for network request via wp_safe_remote_get? */
         networking: boolean;
@@ -42,6 +65,11 @@ export interface CompileBlueprintV1Options {
      * A filesystem to use for the blueprint.
      */
     streamBundledFile?: StreamBundledFile;
+    /**
+     * Additional headers to pass to git operations.
+     * A function that returns headers based on the URL being accessed.
+     */
+    gitAdditionalHeadersCallback?: (url: string) => Record<string, string>;
     /**
      * Additional steps to add to the blueprint.
      */
@@ -50,11 +78,18 @@ export interface CompileBlueprintV1Options {
 export declare function compileBlueprintV1(input: BlueprintV1Declaration | BlueprintBundle, options?: Omit<CompileBlueprintV1Options, 'streamBundledFile'>): Promise<CompiledBlueprintV1>;
 export declare function isBlueprintBundle(input: any): input is BlueprintBundle;
 export declare function getBlueprintDeclaration(blueprint: BlueprintV1 | BlueprintBundle): Promise<BlueprintV1Declaration>;
-export declare function validateBlueprint(blueprintMaybe: object): {
+export type BlueprintValidationResult = {
     valid: true;
-    errors?: undefined;
 } | {
     valid: false;
-    errors: import("ajv").ErrorObject<string, Record<string, any>, unknown>[] | undefined;
+    errors: ErrorObject[];
 };
+export declare function validateBlueprint(blueprintMaybe: object): BlueprintValidationResult;
+/**
+ * Determines if a step is a StepDefinition object
+ *
+ * @param step The object to test
+ * @returns Whether the object is a StepDefinition
+ */
+export declare function isStepDefinition(step: Step | string | undefined | false | null): step is StepDefinition;
 export declare function runBlueprintV1Steps(compiledBlueprint: CompiledBlueprintV1, playground: UniversalPHP): Promise<void>;

package/lib/v1/resources.d.ts

@@ -3,8 +3,18 @@ import type { FileTree, UniversalPHP } from '@php-wasm/universal';
 import type { Semaphore } from '@php-wasm/util';
 import { StreamedFile } from '@php-wasm/stream-compression';
 import type { StreamBundledFile } from './types';
+export declare class BlueprintFilesystemRequiredError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when a resource could not be downloaded from a URL.
+ */
+export declare class ResourceDownloadError extends Error {
+    readonly url: string;
+    constructor(message: string, url: string, options?: ErrorOptions);
+}
 export type { FileTree };
-export declare const ResourceTypes: readonly ["vfs", "literal", "wordpress.org/themes", "wordpress.org/plugins", "url", "git:directory", "bundled"];
+export declare const ResourceTypes: readonly ["vfs", "literal", "wordpress.org/themes", "wordpress.org/plugins", "url", "git:directory", "bundled", "zip"];
 export type VFSReference = {
     /** Identifies the file resource as Virtual File System (VFS) */
     resource: 'vfs';
@@ -68,9 +78,44 @@ export type BundledReference = {
     /** The path to the file in the Blueprint */
     path: string;
 };
-export type FileReference = VFSReference | LiteralReference | CoreThemeReference | CorePluginReference | UrlReference | BundledReference;
+export type ZipWrapperReference = {
+    /** Identifies the resource as a ZIP wrapper */
+    resource: 'zip';
+    /** The inner resource to wrap in a ZIP file */
+    inner: FileReference | DirectoryReference;
+    /** Optional filename for the ZIP (defaults to inner resource name + .zip) */
+    name?: string;
+};
+export type FileReference = VFSReference | LiteralReference | CoreThemeReference | CorePluginReference | UrlReference | BundledReference | ZipWrapperReference;
 export type DirectoryReference = GitDirectoryReference | DirectoryLiteralReference;
 export declare function isResourceReference(ref: any): ref is FileReference;
+/**
+ * Checks if a URL is a github-proxy.com URL that can be rewritten.
+ *
+ * @param url The URL to check
+ * @returns true if the URL is a github-proxy.com URL
+ */
+export declare function isGithubProxyUrl(url: string): boolean;
+/**
+ * Rewrites a github-proxy.com URL to an equivalent Blueprint resource reference.
+ *
+ * github-proxy.com is being deprecated. This function enables automatic migration
+ * of existing Blueprints that use github-proxy.com URLs to native Blueprint resources.
+ *
+ * Supported URL patterns:
+ * - `?repo=owner/name` - Full repository at default branch
+ * - `?repo=owner/name&branch=trunk` - Full repository at specific branch
+ * - `?repo=owner/name&pr=123` - Full repository at PR head
+ * - `?repo=owner/name&commit=abc` - Full repository at specific commit
+ * - `?repo=owner/name&release=v1.0` - Full repository at release tag
+ * - `?repo=owner/name&directory=subdir` - Subdirectory of repository
+ * - `?repo=owner/name&release=v1.0&asset=file.zip` - Release asset download
+ * - `https://github-proxy.com/https://github.com/...` - Direct GitHub URL proxy
+ *
+ * @param url The github-proxy.com URL to rewrite
+ * @returns A ZipWrapperReference (wrapping git:directory) or UrlReference, or null if URL cannot be rewritten
+ */
+export declare function rewriteGithubProxyUrl(url: string): ZipWrapperReference | UrlReference | null;
 export declare abstract class Resource<T extends File | Directory> {
     /** Optional progress tracker to monitor progress */
     protected _progress?: ProgressTracker;
@@ -92,12 +137,13 @@ export declare abstract class Resource<T extends File | Directory> {
      * @param options Additional options for the Resource
      * @returns A new Resource instance
      */
-    static create(ref: FileReference | DirectoryReference, { semaphore, progress, corsProxy, streamBundledFile, }: {
+    static create(ref: FileReference | DirectoryReference, { semaphore, progress, corsProxy, streamBundledFile, gitAdditionalHeadersCallback, }: {
         /** Optional semaphore to limit concurrent downloads */
         semaphore?: Semaphore;
         progress?: ProgressTracker;
         corsProxy?: string;
         streamBundledFile?: StreamBundledFile;
+        gitAdditionalHeadersCallback?: (url: string) => Record<string, string>;
     }): Resource<File | Directory>;
 }
 export declare abstract class ResourceDecorator<T extends File | Directory> extends Resource<T> {
@@ -204,6 +250,7 @@ export declare class GitDirectoryResource extends Resource<Directory> {
     private options?;
     constructor(reference: GitDirectoryReference, _progress?: ProgressTracker, options?: {
         corsProxy?: string;
+        additionalHeaders?: (url: string) => Record<string, string>;
     });
     resolve(): Promise<{
         name: string;
@@ -290,3 +337,19 @@ export declare class BundledResource extends Resource<File> {
     /** @inheritDoc */
     get isAsync(): boolean;
 }
+/**
+ * A `Resource` that wraps another resource and outputs it as a ZIP file.
+ * This is useful for converting directory resources to ZIP files, enabling
+ * compatibility with steps that expect ZIP input (like `unzip`).
+ */
+export declare class ZipResource extends Resource<File> {
+    private reference;
+    private innerResource;
+    constructor(reference: ZipWrapperReference, innerResource: Resource<File | Directory>, _progress?: ProgressTracker);
+    /** @inheritDoc */
+    resolve(): Promise<File>;
+    /** @inheritDoc */
+    get name(): string;
+    /** @inheritDoc */
+    get isAsync(): boolean;
+}

package/lib/v1/types.d.ts

@@ -61,6 +61,7 @@ export type BlueprintV1Declaration = {
         wp: string | 'latest';
     };
     features?: {
+        /** Should boot with support for Intl dynamic extension */
         intl?: boolean;
         /** Should boot with support for network request via wp_safe_remote_get? */
         networking?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-playground/blueprints",
-  "version": "3.0.22",
+  "version": "3.0.31",
   "exports": {
     ".": {
       "import": "./index.js",
@@ -8,6 +8,10 @@
     },
     "./package.json": "./package.json"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/WordPress/wordpress-playground"
+  },
   "type": "module",
   "main": "./index.cjs",
   "module": "./index.js",
@@ -21,7 +25,7 @@
     "access": "public",
     "directory": "../../../dist/packages/playground/blueprints"
   },
-  "gitHead": "a624d1a97dc639e152d335e6a801b2fad7f6b594",
+  "gitHead": "e28b6d2a2e663abc3cbb8fce9a3c5cc8abaa5bbe",
   "engines": {
     "node": ">=20.18.3",
     "npm": ">=10.1.0"
@@ -41,22 +45,24 @@
     "pako": "1.0.10",
     "pify": "2.3.0",
     "readable-stream": "3.6.2",
+    "selfsigned": "2.4.1",
     "sha.js": "2.4.12",
     "simple-get": "4.0.1",
     "wasm-feature-detect": "1.8.0",
     "ws": "8.18.3",
     "yargs": "17.7.2",
-    "@php-wasm/node-polyfills": "3.0.22",
-    "@wp-playground/storage": "3.0.22",
-    "@wp-playground/common": "3.0.22",
-    "@php-wasm/universal": "3.0.22",
-    "@php-wasm/util": "3.0.22",
-    "@php-wasm/node": "3.0.22",
-    "@wp-playground/wordpress": "3.0.22",
-    "@php-wasm/logger": "3.0.22",
-    "@php-wasm/progress": "3.0.22",
-    "@php-wasm/stream-compression": "3.0.22",
-    "@php-wasm/web": "3.0.22"
+    "@php-wasm/node-polyfills": "3.0.31",
+    "@wp-playground/storage": "3.0.31",
+    "@wp-playground/common": "3.0.31",
+    "@php-wasm/universal": "3.0.31",
+    "@php-wasm/util": "3.0.31",
+    "@php-wasm/node": "3.0.31",
+    "@wp-playground/wordpress": "3.0.31",
+    "@php-wasm/logger": "3.0.31",
+    "@php-wasm/scopes": "3.0.31",
+    "@php-wasm/progress": "3.0.31",
+    "@php-wasm/stream-compression": "3.0.31",
+    "@php-wasm/web": "3.0.31"
   },
   "packageManager": "npm@10.9.2",
   "overrides": {
@@ -64,8 +70,8 @@
     "react": "18.3.1",
     "react-dom": "18.3.1",
     "typescript": "5.4.5",
-    "@playwright/test": "1.47.1",
-    "ws": "^8.18.0",
+    "@playwright/test": "1.55.1",
+    "ws": "8.18.3",
     "tmp": "0.2.5",
     "form-data": "^4.0.4"
   },