@wp-playground/blueprints 0.1.61 → 0.2.0

package/lib/compile.d.ts

@@ -4,7 +4,7 @@ import { SupportedPHPVersion, UniversalPHP } from '@php-wasm/universal';
 import { StepDefinition } from './steps';
 import { Blueprint } from './blueprint';
 export type CompiledStep = (php: UniversalPHP) => Promise<void> | void;
-declare const supportedWordPressVersions: readonly ["6.2", "6.1", "6.0", "5.9"];
+declare const supportedWordPressVersions: readonly ["6.2", "6.1", "6.0", "5.9", "nightly"];
 type supportedWordPressVersion = (typeof supportedWordPressVersions)[number];
 export interface CompiledBlueprint {
     /** The requested versions of PHP and WordPress for the blueprint */
@@ -33,5 +33,12 @@ export interface CompileBlueprintOptions {
  * @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>;
 export {};

package/lib/steps/activate-plugin.d.ts

@@ -1,11 +1,16 @@
 import { StepHandler } from '.';
+/**
+ * @inheritDoc activatePlugin
+ */
 export interface ActivatePluginStep {
     step: 'activatePlugin';
+    /** Path to the plugin directory as absolute path (/wordpress/wp-content/plugins/plugin-name); or the plugin entry file relative to the plugins directory (plugin-name/plugin-name.php). */
     pluginPath: string;
+    /** Optional. Plugin name to display in the progress bar. */
     pluginName?: string;
 }
 /**
- * Activates a WordPress plugin in the Playground.
+ * Activates a WordPress plugin (if it's installed).
  *
  * @param playground The playground client.
  */

package/lib/steps/activate-theme.d.ts

@@ -1,10 +1,16 @@
 import { StepHandler } from '.';
+/**
+ * @inheritDoc activateTheme
+ */
 export interface ActivateThemeStep {
     step: 'activateTheme';
+    /**
+     * The name of the theme folder inside wp-content/themes/
+     */
     themeFolderName: string;
 }
 /**
- * Activates a WordPress theme in the Playground.
+ * Activates a WordPress theme (if it's installed).
  *
  * @param playground The playground client.
  * @param themeFolderName The theme folder name.

package/lib/steps/apply-wordpress-patches/index.d.ts

@@ -1,4 +1,7 @@
 import { StepHandler } from '..';
+/**
+ * @private
+ */
 export interface ApplyWordPressPatchesStep {
     step: 'applyWordPressPatches';
     siteUrl?: string;

package/lib/steps/client-methods.d.ts

@@ -41,6 +41,9 @@ export declare const runPHP: StepHandler<RunPHPStep>;
  */
 export interface RunPHPWithOptionsStep {
     step: 'runPHPWithOptions';
+    /**
+     * Run options (See /wordpress-playground/api/universal/interface/PHPRunOptions)
+     */
     options: PHPRunOptions;
 }
 /**
@@ -62,7 +65,9 @@ export declare const runPHPWithOptions: StepHandler<RunPHPWithOptionsStep>;
  */
 export interface SetPhpIniEntryStep {
     step: 'setPhpIniEntry';
+    /** Entry name e.g. "display_errors" */
     key: string;
+    /** Entry value as a string e.g. "1" */
     value: string;
 }
 /**
@@ -91,6 +96,9 @@ export declare const setPhpIniEntry: StepHandler<SetPhpIniEntryStep>;
  */
 export interface RequestStep {
     step: 'request';
+    /**
+     * Request details (See /wordpress-playground/api/universal/interface/PHPRequest)
+     */
     request: PHPRequest;
 }
 /**
@@ -113,7 +121,9 @@ export declare const request: StepHandler<RequestStep>;
  */
 export interface CpStep {
     step: 'cp';
+    /** Source path */
     fromPath: string;
+    /** Target path */
     toPath: string;
 }
 /**
@@ -136,7 +146,9 @@ export declare const cp: StepHandler<CpStep>;
  */
 export interface MvStep {
     step: 'mv';
+    /** Source path */
     fromPath: string;
+    /** Target path */
     toPath: string;
 }
 /**
@@ -157,6 +169,7 @@ export declare const mv: StepHandler<MvStep>;
  */
 export interface MkdirStep {
     step: 'mkdir';
+    /** The path of the directory you want to create */
     path: string;
 }
 /**
@@ -178,6 +191,7 @@ export declare const mkdir: StepHandler<MkdirStep>;
  */
 export interface RmStep {
     step: 'rm';
+    /** The path to remove */
     path: string;
 }
 /**
@@ -199,6 +213,7 @@ export declare const rm: StepHandler<RmStep>;
  */
 export interface RmdirStep {
     step: 'rmdir';
+    /** The path to remove */
     path: string;
 }
 /**
@@ -221,7 +236,9 @@ export declare const rmdir: StepHandler<RmdirStep>;
  */
 export interface WriteFileStep<ResourceType> {
     step: 'writeFile';
+    /** The path of the file to write to */
     path: string;
+    /** The data to write */
     data: ResourceType | string | Uint8Array;
 }
 /**

package/lib/steps/define-site-url.d.ts

@@ -1,10 +1,23 @@
 import { StepHandler } from '.';
+/**
+ * @inheritDoc defineSiteUrl
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "defineSiteUrl",
+ * 		"siteUrl": "https://playground.wordpress.net"
+ * }
+ * </code>
+ */
 export interface DefineSiteUrlStep {
     step: 'defineSiteUrl';
+    /** The URL */
     siteUrl: string;
 }
 /**
- * Sets site URL of the WordPress installation.
+ * Sets WP_HOME and WP_SITEURL constants for the WordPress installation.
  *
  * @param playground The playground client.
  * @param siteUrl

package/lib/steps/define-wp-config-consts.d.ts

@@ -1,7 +1,19 @@
 import { StepHandler } from '.';
 export declare const VFS_TMP_DIRECTORY = "/vfs-blueprints";
 /**
- * The step object for defining constants in the wp-config.php file of a WordPress installation.
+ * @inheritDoc defineWpConfigConsts
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "defineWpConfigConsts",
+ * 		"consts": {
+ *          "WP_DEBUG": true
+ *      },
+ *      "virtualize": true
+ * }
+ * </code>
  */
 export interface DefineWpConfigConstsStep {
     step: 'defineWpConfigConsts';
@@ -16,10 +28,9 @@ export interface DefineWpConfigConstsStep {
     virtualize?: boolean;
 }
 /**
- * Sets site URL of the WordPress installation.
+ * Defines the wp-config.php constants
  *
  * @param playground The playground client.
- * @param wpConfigConst An object containing the constants to be defined and the optional virtual file system configuration file path.
- * @returns Returns the virtual file system configuration file path.
+ * @param wpConfigConst
  */
 export declare const defineWpConfigConsts: StepHandler<DefineWpConfigConstsStep>;

package/lib/steps/import-export.d.ts

@@ -9,20 +9,31 @@ import { StepHandler } from '.';
  * @param playground Playground client.
  */
 export declare function zipEntireSite(playground: UniversalPHP): Promise<File>;
+/**
+ * @inheritDoc replaceSite
+ */
 export interface ReplaceSiteStep<ResourceType> {
     step: 'replaceSite';
+    /** The zip file containing the new WordPress site */
     fullSiteZip: ResourceType;
 }
 /**
- * Replace the current site with the contents of a full site zip file.
+ * Replace the current site with a site from the provided zip file.
+ * Remember to install the SQLite integration plugin in the zipped site:
+ * https://wordpress.org/plugins/sqlite-database-integration.
  *
  * @param playground Playground client.
  * @param fullSiteZip Zipped WordPress site.
  */
 export declare const replaceSite: StepHandler<ReplaceSiteStep<File>>;
+/**
+ * @inheritDoc unzip
+ */
 export interface UnzipStep {
     step: 'unzip';
+    /** The zip file to extract */
     zipPath: string;
+    /** The path to extract the zip file to */
     extractToPath: string;
 }
 /**
@@ -52,8 +63,12 @@ export declare function exportWXR(playground: UniversalPHP): Promise<File>;
  * @returns WXZ file
  */
 export declare function exportWXZ(playground: UniversalPHP): Promise<File>;
+/**
+ * @inheritDoc importFile
+ */
 export interface ImportFileStep<ResourceType> {
     step: 'importFile';
+    /** The file to import */
     file: ResourceType;
 }
 /**

package/lib/steps/run-wp-installation-wizard.d.ts

@@ -1,4 +1,7 @@
 import { StepHandler } from '.';
+/**
+ * @private
+ */
 export interface RunWpInstallationWizardStep {
     step: 'runWpInstallationWizard';
     options: WordPressInstallationOptions;

package/lib/steps/site-data.d.ts

@@ -45,7 +45,9 @@ export declare const setSiteOptions: StepHandler<SetSiteOptionsStep>;
  */
 export interface UpdateUserMetaStep {
     step: 'updateUserMeta';
+    /** An object of user meta values to set, e.g. { "first_name": "John" } */
     meta: Record<string, unknown>;
+    /** User ID */
     userId: number;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wp-playground/blueprints",
-	"version": "0.1.61",
+	"version": "0.2.0",
 	"exports": {
 		".": {
 			"import": "./index.js",
@@ -21,5 +21,9 @@
 		"access": "public",
 		"directory": "../../../dist/packages/playground/blueprints"
 	},
-	"gitHead": "f2cd7382004f7b003904b5db1d33d37fd2b1bfab"
+	"gitHead": "cd4062de74f7f18058d3f962e124d0fdff78b5a7",
+	"engines": {
+		"node": ">=16.15.1",
+		"npm": ">=8.11.0"
+	}
 }

package/schema-readme.md

@@ -0,0 +1,9 @@
+The JSON schema stored in this directory is used to validate the Blueprints
+and is autogenerated from the Blueprints TypeScript types.
+
+Whenever the types are modified, the schema needs to be rebuilt using
+`nx build playground-blueprints` and then committed to the repository.
+
+Unfortunately, it is not auto-rebuilt in `npm run dev` mode as the
+`dts-bundle-generator` utility we use for type rollyps does not support
+watching for changes.