@wp-playground/blueprints 0.9.19 → 0.9.20

package/lib/blueprint.d.ts

@@ -0,0 +1,89 @@
+import { SupportedPHPExtensionBundle, SupportedPHPVersion } from '../../../../php-wasm/universal/src/index.ts';
+import { StepDefinition } from './steps';
+import { FileReference } from './resources';
+export interface Blueprint {
+    /**
+     * The URL to navigate to after the blueprint has been run.
+     */
+    landingPage?: string;
+    /**
+     * Optional description. It doesn't do anything but is exposed as
+     * a courtesy to developers who may want to document which blueprint
+     * file does what.
+     *
+     * @deprecated Use meta.description instead.
+     */
+    description?: string;
+    /**
+     * Optional metadata. Used by the Blueprints gallery at https://github.com/WordPress/blueprints
+     */
+    meta?: {
+        /**
+         * A clear and concise name for your Blueprint.
+         */
+        title: string;
+        /**
+         * A brief explanation of what your Blueprint offers.
+         */
+        description?: string;
+        /**
+         * A GitHub username of the author of this Blueprint.
+         */
+        author: string;
+        /**
+         * Relevant categories to help users find your Blueprint in the future Blueprints section on WordPress.org.
+         */
+        categories?: string[];
+    };
+    /**
+     * The preferred PHP and WordPress versions to use.
+     */
+    preferredVersions?: {
+        /**
+         * The preferred PHP version to use.
+         * If not specified, the latest supported version will be used
+         */
+        php: SupportedPHPVersion | 'latest';
+        /**
+         * The preferred WordPress version to use.
+         * If not specified, the latest supported version will be used
+         */
+        wp: string | 'latest';
+    };
+    features?: {
+        /** Should boot with support for network request via wp_safe_remote_get? */
+        networking?: boolean;
+    };
+    /**
+     * PHP Constants to define on every request
+     */
+    constants?: Record<string, string>;
+    /**
+     * WordPress plugins to install and activate
+     */
+    plugins?: Array<string | FileReference>;
+    /**
+     * WordPress site options to define
+     */
+    siteOptions?: Record<string, string> & {
+        /** The site title */
+        blogname?: string;
+    };
+    /**
+     * User to log in as.
+     * If true, logs the user in as admin/password.
+     */
+    login?: boolean | {
+        username: string;
+        password: string;
+    };
+    /**
+     * The PHP extensions to use.
+     */
+    phpExtensionBundles?: SupportedPHPExtensionBundle[];
+    /**
+     * The steps to run after every other operation in this Blueprint was
+     * executed.
+     */
+    steps?: Array<StepDefinition | string | undefined | false | null>;
+}

package/lib/compile.d.ts

@@ -0,0 +1,47 @@
+import { ProgressTracker } from '../../../../php-wasm/progress/src/index.ts';
+import { Semaphore } from '../../../../php-wasm/util/src/index.ts';
+import { SupportedPHPExtension, SupportedPHPVersion, UniversalPHP } from '../../../../php-wasm/universal/src/index.ts';
+import { StepDefinition } from './steps';
+import { Blueprint } from './blueprint';
+export type CompiledStep = (php: UniversalPHP) => Promise<void> | void;
+export interface CompiledBlueprint {
+    /** The requested versions of PHP and WordPress for the blueprint */
+    versions: {
+        php: SupportedPHPVersion;
+        wp: string;
+    };
+    /** The requested PHP extensions to load */
+    phpExtensions: SupportedPHPExtension[];
+    features: {
+        /** Should boot with support for network request via wp_safe_remote_get? */
+        networking: boolean;
+    };
+    /** 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 declare function compileBlueprint(blueprint: Blueprint, { progress, semaphore, onStepCompleted, }?: CompileBlueprintOptions): CompiledBlueprint;
+export declare function validateBlueprint(blueprintMaybe: object): {
+    valid: true;
+    errors?: undefined;
+} | {
+    valid: false;
+    errors: import("ajv").ErrorObject<string, Record<string, any>, unknown>[] | undefined;
+};
+export declare function runBlueprintSteps(compiledBlueprint: CompiledBlueprint, playground: UniversalPHP): Promise<void>;

package/lib/resources.d.ts

@@ -0,0 +1,210 @@
+import { ProgressTracker } from '../../../../php-wasm/progress/src/index.ts';
+import { UniversalPHP } from '../../../../php-wasm/universal/src/index.ts';
+import { Semaphore } from '../../../../php-wasm/util/src/index.ts';
+export declare const ResourceTypes: readonly ["vfs", "literal", "wordpress.org/themes", "wordpress.org/plugins", "url"];
+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 declare function isFileReference(ref: any): ref is FileReference;
+export interface ResourceOptions {
+    /** Optional semaphore to limit concurrent downloads */
+    semaphore?: Semaphore;
+    progress?: ProgressTracker;
+}
+export declare abstract class Resource {
+    /** Optional progress tracker to monitor progress */
+    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;
+    setPlayground(playground: UniversalPHP): void;
+    /**
+     * 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;
+}
+/**
+ * A `Resource` that represents a file in the VFS (virtual file system) of the playground.
+ */
+export declare class VFSResource extends Resource {
+    private resource;
+    progress?: ProgressTracker | undefined;
+    /**
+     * Creates a new instance of `VFSResource`.
+     * @param playground The playground client.
+     * @param resource The VFS reference.
+     * @param progress The progress tracker.
+     */
+    constructor(resource: VFSReference, progress?: ProgressTracker | undefined);
+    /** @inheritDoc */
+    resolve(): Promise<File>;
+    /** @inheritDoc */
+    get name(): string;
+}
+/**
+ * A `Resource` that represents a literal file.
+ */
+export declare class LiteralResource extends Resource {
+    private resource;
+    progress?: ProgressTracker | undefined;
+    /**
+     * Creates a new instance of `LiteralResource`.
+     * @param resource The literal reference.
+     * @param progress The progress tracker.
+     */
+    constructor(resource: LiteralReference, progress?: ProgressTracker | undefined);
+    /** @inheritDoc */
+    resolve(): Promise<File>;
+    /** @inheritDoc */
+    get name(): string;
+}
+/**
+ * A base class for `Resource`s that require fetching data from a remote URL.
+ */
+export declare abstract class FetchResource extends Resource {
+    progress?: ProgressTracker | undefined;
+    /**
+     * Creates a new instance of `FetchResource`.
+     * @param progress The progress tracker.
+     */
+    constructor(progress?: ProgressTracker | undefined);
+    /** @inheritDoc */
+    resolve(): Promise<File>;
+    /**
+     * 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(): string;
+    /** @inheritDoc */
+    get name(): string;
+    /** @inheritDoc */
+    get isAsync(): boolean;
+}
+/**
+ * A `Resource` that represents a file available from a URL.
+ */
+export declare class UrlResource extends FetchResource {
+    private resource;
+    /**
+     * Creates a new instance of `UrlResource`.
+     * @param resource The URL reference.
+     * @param progress The progress tracker.
+     */
+    constructor(resource: UrlReference, progress?: ProgressTracker);
+    /** @inheritDoc */
+    getURL(): string;
+    /** @inheritDoc */
+    protected get caption(): string;
+}
+/**
+ * A `Resource` that represents a WordPress core theme.
+ */
+export declare class CoreThemeResource extends FetchResource {
+    private resource;
+    constructor(resource: CoreThemeReference, progress?: ProgressTracker);
+    get name(): string;
+    getURL(): string;
+}
+/**
+ * A resource that fetches a WordPress plugin from wordpress.org.
+ */
+export declare class CorePluginResource extends FetchResource {
+    private resource;
+    constructor(resource: CorePluginReference, progress?: ProgressTracker);
+    /** @inheritDoc */
+    get name(): string;
+    /** @inheritDoc */
+    getURL(): string;
+}
+/**
+ * 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 declare function toDirectoryZipName(rawInput: string): string;
+/**
+ * A decorator for a resource that adds functionality such as progress tracking and caching.
+ */
+export declare class DecoratedResource<T extends Resource> extends Resource {
+    private resource;
+    constructor(resource: T);
+    /** @inheritDoc */
+    resolve(): Promise<File>;
+    /** @inheritDoc */
+    setPlayground(playground: UniversalPHP): Promise<void>;
+    /** @inheritDoc */
+    get progress(): ProgressTracker | undefined;
+    /** @inheritDoc */
+    set progress(value: ProgressTracker | undefined);
+    /** @inheritDoc */
+    get name(): string;
+    /** @inheritDoc */
+    get isAsync(): boolean;
+}
+/**
+ * A decorator for a resource that adds caching functionality.
+ */
+export declare class CachedResource<T extends Resource> extends DecoratedResource<T> {
+    protected promise?: Promise<File>;
+    /** @inheritDoc */
+    resolve(): Promise<File>;
+}
+/**
+ * A decorator for a resource that adds concurrency control functionality through a semaphore.
+ */
+export declare class SemaphoreResource<T extends Resource> extends DecoratedResource<T> {
+    private readonly semaphore;
+    constructor(resource: T, semaphore: Semaphore);
+    /** @inheritDoc */
+    resolve(): Promise<File>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wp-playground/blueprints",
-	"version": "0.9.19",
+	"version": "0.9.20",
 	"exports": {
 		".": {
 			"import": "./index.js",
@@ -21,7 +21,7 @@
 		"access": "public",
 		"directory": "../../../dist/packages/playground/blueprints"
 	},
-	"gitHead": "aafbbcdc4b0644885bd55d0ed67381952f0b16b6",
+	"gitHead": "f619fcb719128d247bec296b9339aff52101e948",
 	"engines": {
 		"node": ">=18.18.0",
 		"npm": ">=8.11.0"