@wp-playground/blueprints 3.1.43 → 3.1.45

package/lib/v2/wep-1-blueprint-v2-schema/appendix-A-blueprint-v2-schema.d.ts

@@ -30,9 +30,9 @@ export declare namespace V2Schema {
          * for declaring options or opinions for different application contexts.
          *
          * To keep Blueprints portable and focused on site creation, this specification
-         * only allows two Playground-specific options. Other environments cannot declare
-         * additional options. Future versions of this specification may allow additional
-         * options – they will be discussed on a case-by-case basis.
+         * only allows a small set of Playground-specific options. Other environments
+         * cannot declare additional options. Future versions of this specification may
+         * allow additional options – they will be discussed on a case-by-case basis.
          */
         applicationOptions?: {
             /**
@@ -62,8 +62,53 @@ export declare namespace V2Schema {
                  * @default false
                  */
                 networkAccess?: boolean;
+                /**
+                 * Optional PHP extensions to load in the Playground runtime before executing
+                 * the Blueprint. Extensions omitted from this list are not disabled.
+                 */
+                loadPhpExtensions?: Array<'intl'>;
             };
         };
+        /**
+         * The content from a vanilla WordPress installation to retain before
+         * applying the rest of the Blueprint. `keep-all` leaves the installation
+         * unchanged, `empty` removes its posts, pages, and comments, a content type
+         * retains only that type, and a list retains the selected content types.
+         *
+         * This policy runs only when the current invocation creates vanilla
+         * WordPress. It is skipped when applying the Blueprint to an existing site,
+         * so it cannot erase content from that site. It is not valid when
+         * `wordpressVersion` is "none". Metadata and relationships follow their
+         * parent content. Empty content tables have their sequences reset so
+         * subsequent imports receive the identifiers they would on a site created
+         * without default content.
+         *
+         * Comments can only be retained together with both posts and pages because
+         * the schema cannot know which type contains their parent records.
+         *
+         * @default "keep-all"
+         */
+        contentBaseline?: 'keep-all' | 'empty' | Exclude<ContentType, 'comments'> | [ContentType, ...ContentType[]];
+        /**
+         * The users from a vanilla WordPress installation to retain before applying
+         * the rest of the Blueprint. `keep-all` retains the administrator created by
+         * WordPress, while `empty` removes it before creating the users declared by
+         * this Blueprint.
+         *
+         * Empty user tables have their sequences reset before those users are
+         * created.
+         *
+         * An empty user baseline requires an empty content baseline so removing the
+         * installation administrator cannot silently delete or orphan authored
+         * content. It also requires at least one declared administrator, ensuring
+         * the resulting WordPress site remains manageable.
+         *
+         * Like `contentBaseline`, this policy is skipped when applying the Blueprint
+         * to an existing site and is not valid when `wordpressVersion` is "none".
+         *
+         * @default "keep-all"
+         */
+        usersBaseline?: 'keep-all' | 'empty';
         /**
          * SITE OPTIONS {{{
          *
@@ -146,25 +191,29 @@ export declare namespace V2Schema {
          */
         constants?: WordPressConstants;
         /**
-         * WordPress version to install.
+         * WordPress version to install or require.
          *
-         * When we're setting up the entire site, this will be used to resolve the
-         * installed WordPress version. The latest version matching the constraint
-         * will be chosen.
+         * A string selects the version for a newly created site. A branch such as
+         * `6.8` selects the newest available release in that branch. Strings are
+         * selection hints and do not reject an existing site. `"none"` boots the
+         * PHP runtime without downloading WordPress or initializing its database.
          *
-         * When we're applying this Blueprint to an existing site, this will be used
-         * as an integrity check to verify that the currently installed version of
-         * WordPress installed on the target site matches the constraint.
+         * An object declares compatibility bounds. The runner chooses the newest
+         * available release within those bounds for a new site and verifies an
+         * existing site's installed version against them. `preferred` influences
+         * new-site selection without narrowing compatibility.
          *
-         * @default "latest".
+         * A data reference supplies the WordPress files for a newly created site.
+         *
+         * @default "latest"
          */
         wordpressVersion?: DataSources.WordPressVersion | DataSources.DataReference | {
-            min: DataSources.WordPressVersion;
-            max?: DataSources.WordPressVersion;
+            min: DataSources.WordPressVersionConstraintVersion;
+            max?: DataSources.WordPressVersionConstraintVersion;
             /**
              * @default "latest"
              */
-            preferred?: DataSources.WordPressVersion;
+            preferred?: DataSources.WordPressVersionPreferredVersion;
         };
         /**
          * The PHP version required for this Blueprint to work.
@@ -180,9 +229,9 @@ export declare namespace V2Schema {
          * @see https://github.com/WordPress/blueprints-library/issues/47
          */
         phpVersion?: DataSources.PHPVersion | {
-            min?: DataSources.PHPVersion;
-            recommended?: DataSources.PHPVersion;
-            max?: DataSources.PHPVersion;
+            min?: DataSources.PHPVersionConstraintVersion;
+            recommended?: DataSources.PHPVersionConstraintVersion;
+            max?: DataSources.PHPVersionConstraintVersion;
         };
         /**
          * The theme to install and also activate.
@@ -196,9 +245,13 @@ export declare namespace V2Schema {
          * @example `"activeTheme": "adventurer@4.6.0"`
          * @example
          * ```json
-         * "activeTheme": {
-         *     "source": "https://github.com/richtabor/kanso/archive/refs/heads/main.zip",
-         *     "id": "kanso"
+         * {
+         *     "version": 2,
+         *     "activeTheme": {
+         *         "source": "https://github.com/richtabor/kanso/archive/refs/heads/main.zip",
+         *         "targetDirectoryName": "kanso",
+         *         "importStarterContent": true
+         *     }
          * }
          * ```
          */
@@ -209,14 +262,17 @@ export declare namespace V2Schema {
          * Example:
          *
          * ```json
-         * themes: [
-         *     "stylish-press-theme",
-         *     "adventurer@4.6.0",
-         *     {
-         *         "source": "https://github.com/richtabor/kanso/archive/refs/heads/main.zip",
-         *         "id": "kanso"
-         *     }
-         * ]
+         * {
+         *     "version": 2,
+         *     "themes": [
+         *         "stylish-press-theme",
+         *         "adventurer@4.6.0",
+         *         {
+         *             "source": "https://github.com/richtabor/kanso/archive/refs/heads/main.zip",
+         *             "targetDirectoryName": "kanso"
+         *         }
+         *     ]
+         * }
          * ```
          */
         themes?: ThemeDefinition[];
@@ -226,16 +282,20 @@ export declare namespace V2Schema {
          * Example:
          *
          * ```json
-         * plugins: [
-         *     "jetpack",
-         *     "akismet@6.4.3",
-         *     "./query-monitor.php",
-         *     "./code-block.zip",
-         *     {
-         *         "source": "https://github.com/woocommerce/woocommerce/archive/refs/heads/6.4.3.zip",
-         *         "active": false
-         *     }
-         * ]
+         * {
+         *     "version": 2,
+         *     "plugins": [
+         *         "jetpack",
+         *         "akismet@6.4.3",
+         *         "./query-monitor.php",
+         *         "./code-block.zip",
+         *         {
+         *             "source": "https://github.com/woocommerce/woocommerce/archive/refs/heads/6.4.3.zip",
+         *             "active": false
+         *         }
+         *     ]
+         * }
+         * ```
          */
         plugins?: PluginDefinition[];
         /**
@@ -244,14 +304,15 @@ export declare namespace V2Schema {
          * Example:
          *
          * ```json
-         * muPlugins: [
-         *     {
-         *         "file": {
+         * {
+         *     "version": 2,
+         *     "muPlugins": [
+         *         {
          *             "filename": "addFilter-0.php",
          *             "content": "<?php add_action( 'requests-requests.before_request', function( &$url ) {\n$url = 'https://playground.wordpress.net/cors-proxy.php?' . $url;\n} );"
          *         }
-         *     }
-         * ]
+         *     ]
+         * }
          * ```
          */
         muPlugins?: Array<DataSources.DataReference>;
@@ -263,6 +324,8 @@ export declare namespace V2Schema {
          * throw an error.
          *
          * See https://github.com/WordPress/blueprints-library/issues/32 for more context.
+         *
+         * @propertyNames { "pattern": "^[a-z0-9_-]{1,20}$" }
          */
         postTypes?: Record<PostTypeKey, PostType | DataSources.ExecutionContextPath>;
         /**
@@ -305,7 +368,7 @@ export declare namespace V2Schema {
          * }
          * ```
          */
-        fonts?: Record<string, DataSources.DataReference | FontCollection>;
+        fonts?: Record<string, DataSources.FileDataReference | FontCollection>;
         /**
          * A list of media files to upload to the WordPress Media Library – in formats
          * supported by the WordPress Media Library.
@@ -345,6 +408,11 @@ export declare namespace V2Schema {
         }>;
         additionalStepsAfterExecution?: Array<Step>;
     };
+    /**
+     * Content types created by a vanilla WordPress installation and controlled
+     * by `contentBaseline`.
+     */
+    type ContentType = 'posts' | 'pages' | 'comments';
     type LicenseKeyword = 'AFL-3.0' | 'Apache-2.0' | 'Artistic-2.0' | 'BSL-1.0' | 'BSD-2-Clause' | 'BSD-3-Clause' | 'BSD-3-Clause-Clear' | 'BSD-4-Clause' | '0BSD' | 'CC' | 'CC0-1.0' | 'CC-BY-4.0' | 'CC-BY-SA-4.0' | 'WTFPL' | 'ECL-2.0' | 'EPL-1.0' | 'EPL-2.0' | 'EUPL-1.1' | 'AGPL-3.0' | 'GPL' | 'GPL-2.0' | 'GPL-3.0' | 'LGPL' | 'LGPL-2.1' | 'LGPL-3.0' | 'ISC' | 'LPPL-1.3c' | 'MS-PL' | 'MIT' | 'MPL-2.0' | 'OSL-3.0' | 'PostgreSQL' | 'OFL-1.1' | 'NCSA' | 'Unlicense' | 'Zlib';
     type URLMappingConfig = {
         /**
@@ -361,15 +429,17 @@ export declare namespace V2Schema {
         urlsMode?: 'rewrite' | 'preserve';
         /**
          * A mapping of base URLs to rewrite.
+         *
+         * @propertyNames { "$ref": "#/definitions/DataSources.URLReference" }
          */
         urlsMap?: Record<DataSources.URLReference, DataSources.URLReference>;
     };
-    type ContentDefinition = ({
+    type ContentDefinition = {
         type: 'mysql-dump';
-        source: DataSources.DataReference | DataSources.DataReference[];
-    } & URLMappingConfig) | ({
+        source: DataSources.FileDataReference | DataSources.FileDataReference[];
+    } | ({
         type: 'posts';
-        source: DataSources.DataReference | DataSources.DataReference[] | WordPressPost | WordPressPost[];
+        source: DataSources.FileDataReference | WordPressPost | (DataSources.FileDataReference | WordPressPost)[];
     } & URLMappingConfig)
     /**
      * WXR files to import.
@@ -377,36 +447,33 @@ export declare namespace V2Schema {
      * Example:
      *
      * ```json
-     * content: [
-     *     {
-     *         "type": "wxr",
-     *         "https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/stylish-press/woo-products.wxr"
-     *     },
-     *     {
-     *         "type": "wxr",
-     *         "url": "https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/stylish-press/site-content.wxr",
-     *         "rewriteUrls": true,
-     *         "fetchStaticAssets": false,
-     *         "users": false,
-     *         "comments": false,
-     *     }
-     * ]
+     * {
+     *     "version": 2,
+     *     "content": [
+     *         {
+     *             "type": "wxr",
+     *             "source": "https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/stylish-press/woo-products.wxr"
+     *         },
+     *         {
+     *             "type": "wxr",
+     *             "source": "https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/stylish-press/site-content.wxr",
+     *             "urlsMode": "rewrite",
+     *             "staticAssets": "hotlink",
+     *             "importUsers": false,
+     *             "importComments": false
+     *         }
+     *     ]
+     * }
      * ```
      */
-     | ({
-        type: 'wxr';
-        source: DataSources.DataReference;
+     | WXRContentDefinition;
+    type WXRContentDefinition = WXRContentBase & ({
         /**
-         * Static assets handling.
-         *
-         * Possible values:
-         *
-         * * "fetch" – Fetch the static assets and save them to the local filesystem.
-         * * "hotlink" – Hotlink the static assets from the remote site.
-         *
-         * @default "fetch".
+         * Map remote authors to existing local authors.
          */
-        staticAssets?: 'fetch' | 'hotlink';
+        authorsMode: 'map';
+        authorsMap: Record<RemoteUsername, LocalUsername>;
+    } | {
         /**
          * How to handle authors that don't exist on the current site.
          *
@@ -414,28 +481,32 @@ export declare namespace V2Schema {
          *
          * * "create" – Create a new author.
          * * "default-author" – Use the default author.
-         * * "map" – Map the author to an existing author on the current site.
          *
          * @default "create".
          */
-        authorsMode?: 'create' | 'default-author' | 'map';
+        authorsMode?: 'create' | 'default-author';
+        authorsMap?: Record<RemoteUsername, LocalUsername>;
+    });
+    type WXRContentBase = {
+        type: 'wxr';
+        source: DataSources.FileDataReference | DataSources.FileDataReference[];
         /**
-         * The default author to use when `mode` is "default-author".
+         * Static assets handling.
          *
-         * @default "admin".
-         */
-        defaultAuthorUsername?: string;
-        /**
-         * Map post authors from the remote site to the current site.
+         * Possible values:
          *
-         * When not provided, the importer will attempt to match the authors by
-         * username, email, or name.
+         * * "fetch" – Fetch the static assets and save them to the local filesystem.
+         * * "hotlink" – Hotlink the static assets from the remote site.
          *
-         * Required when `authorsMode` is "map".
+         * @default "fetch".
+         */
+        staticAssets?: 'fetch' | 'hotlink';
+        /**
+         * The default author to use when `mode` is "default-author".
          *
-         * @default undefined.
+         * @default "admin".
          */
-        authorsMap?: Record<RemoteUsername, LocalUsername>;
+        defaultAuthorUsername?: string;
         /**
          * Whether to import users from the remote site.
          *
@@ -448,15 +519,9 @@ export declare namespace V2Schema {
          * @default false.
          */
         importComments?: boolean;
-        /**
-         * Whether to import site settings from the remote site.
-         *
-         * @default false.
-         */
-        importSiteOptions?: boolean;
-    } & URLMappingConfig);
-    type MediaDefinition = DataSources.DataReference | {
-        source: DataSources.DataReference;
+    } & URLMappingConfig;
+    type MediaDefinition = DataSources.FileDataReference | {
+        source: DataSources.FileDataReference;
         title?: string;
         description?: string;
         alt?: string;
@@ -525,6 +590,8 @@ export declare namespace V2Schema {
         /**
          * An explicit directory name within wp-content/plugins to install the plugin at.
          * If not provided, it will be inferred from the plugin source.
+         *
+         * @pattern ^(?!(?:\.|\.\.)$)[^/]+$
          */
         targetDirectoryName?: string;
         /**
@@ -540,6 +607,12 @@ export declare namespace V2Schema {
          * @default "throw"
          */
         onError?: 'skip-plugin' | 'throw';
+        /**
+         * How to handle a plugin that is already installed.
+         *
+         * @default "overwrite"
+         */
+        ifAlreadyInstalled?: 'overwrite' | 'skip' | 'error';
         /**
          * Human-readable name of the plugin for the progress bar.
          *
@@ -571,8 +644,22 @@ export declare namespace V2Schema {
         /**
          * An explicit directory name within wp-content/themes to install the theme at.
          * If not provided, it will be inferred from the theme source.
+         *
+         * @pattern ^(?!(?:\.|\.\.)$)[^/]+$
          */
         targetDirectoryName?: string;
+        /**
+         * Sometimes it's fine when a theme fails to install.
+         *
+         * @default "throw"
+         */
+        onError?: 'skip-theme' | 'throw';
+        /**
+         * How to handle a theme that is already installed.
+         *
+         * @default "overwrite"
+         */
+        ifAlreadyInstalled?: 'overwrite' | 'skip' | 'error';
         /**
          * Human-readable name of the theme for the progress bar.
          *
@@ -594,8 +681,8 @@ export declare namespace V2Schema {
          */
         humanReadableName?: string;
     };
-    type RemoteUsername = 'string';
-    type LocalUsername = 'string';
+    type RemoteUsername = string;
+    type LocalUsername = string;
     /**
      * WordPress register_post_type() arguments representation. {{{
      *
@@ -1038,7 +1125,7 @@ export declare namespace V2Schema {
         /** CSS font-display value. */
         fontDisplay?: 'auto' | 'block' | 'fallback' | 'swap' | 'optional';
         /** Paths or URLs to the font files. */
-        src: DataSources.DataReference | DataSources.DataReference[];
+        src: DataSources.FileDataReference | DataSources.FileDataReference[];
         /** CSS font-stretch value. */
         fontStretch?: string;
         /** CSS ascent-override value. */
@@ -1290,6 +1377,10 @@ export declare namespace V2Schema {
         step: 'defineConstants';
         constants: WordPressConstants;
     };
+    type EnableMultisiteStep = {
+        /** Converts the target WordPress installation into a multisite network. */
+        step: 'enableMultisite';
+    };
     type ImportContentStep = {
         step: 'importContent';
         content: ContentDefinition[];
@@ -1322,12 +1413,20 @@ export declare namespace V2Schema {
         step: 'rmdir';
         path: string;
     };
+    type ResetDataStep = {
+        step: 'resetData';
+        /**
+         * Content types to remove. When omitted, all posts, pages, custom post
+         * types, and comments are removed.
+         */
+        contentTypes?: Array<ContentType>;
+    };
     type RunPHPStep = {
         step: 'runPHP';
         /**
          * The PHP file to execute.
          */
-        code: DataSources.DataReference;
+        code: DataSources.FileDataReference;
         /**
          * Environment variables to set for this run.
          */
@@ -1335,7 +1434,7 @@ export declare namespace V2Schema {
     };
     type RunSQLStep = {
         step: 'runSQL';
-        source: DataSources.DataReference;
+        source: DataSources.FileDataReference;
     };
     /**
      * Sets the site language and download translations for WordPress core
@@ -1364,7 +1463,7 @@ export declare namespace V2Schema {
         /**
          * The zip file resource to extract.
          */
-        zipFile: DataSources.DataReference;
+        zipFile: DataSources.FileDataReference;
         /**
          * The path to extract the zip file to inside the virtual filesystem.
          */
@@ -1392,7 +1491,7 @@ export declare namespace V2Schema {
          */
         active?: boolean;
     } & ThemeObjectDefinition;
-    type Step = ActivatePluginStep | ActivateThemeStep | CpStep | DefineConstantsStep | ImportContentStep | ImportMediaStep | ImportThemeStarterContentStep | PluginStep | ThemeStep | MkdirStep | MvStep | RmStep | RmdirStep | RunPHPStep | RunSQLStep | SetSiteLanguageStep | SetSiteOptionsStep | UnzipStep | WpCliStep | WriteFilesStep;
+    type Step = ActivatePluginStep | ActivateThemeStep | CpStep | DefineConstantsStep | EnableMultisiteStep | ImportContentStep | ImportMediaStep | ImportThemeStarterContentStep | PluginStep | ThemeStep | MkdirStep | MvStep | RmStep | RmdirStep | ResetDataStep | RunPHPStep | RunSQLStep | SetSiteLanguageStep | SetSiteOptionsStep | UnzipStep | WpCliStep | WriteFilesStep;
     type JsonValue = string | boolean | number | JsonValue[] | {
         [key: string]: JsonValue;
     };