@wp-playground/blueprints 3.1.43 → 3.1.45

package/lib/v2/wep-1-blueprint-v2-schema/appendix-B-data-sources.d.ts

@@ -12,6 +12,8 @@ export declare namespace DataSources {
      * optionally contain usernames and passwords if needed.
      *
      * @see https://url.spec.whatwg.org/
+     * @asType string
+     * @pattern ^[Hh][Tt][Tt][Pp][Ss]?://[^/?#]+
      */
     export type URLReference = `http://${string}` | `https://${string}`;
     /**
@@ -27,6 +29,9 @@ export declare namespace DataSources {
      *   still the directory where blueprint.json is located.
      *
      * It is not possible to escape the Blueprint Execution Context via "../" sequences.
+     *
+     * @asType string
+     * @pattern ^(?!.*(?:^|/)\.\.(?:/|$))(?:\./|/).*$
      */
     export type ExecutionContextPath = `/${string}` | `./${string}`;
     /**
@@ -42,6 +47,7 @@ export declare namespace DataSources {
      * ```
      */
     export type InlineFile = {
+        /** @pattern ^(?!(?:\.|\.\.)$)[^/]+$ */
         filename: string;
         content: InlineFileContent;
     };
@@ -66,8 +72,19 @@ export declare namespace DataSources {
      * ```
      */
     export type InlineDirectory = {
+        /** @pattern ^(?!(?:\.|\.\.)$)[^/]+$ */
         directoryName: string;
-        files: Record<string, InlineFileContent | InlineDirectory>;
+        /** @propertyNames { "pattern": "^(?!(?:\\.|\\.\\.)$)[^/]+$" } */
+        files: Record<string, InlineFileContent | NestedInlineDirectory>;
+    };
+    /**
+     * A child directory inside an inline directory.
+     *
+     * Its directory name comes from the parent `files` record key.
+     */
+    export type NestedInlineDirectory = {
+        /** @propertyNames { "pattern": "^(?!(?:\\.|\\.\\.)$)[^/]+$" } */
+        files: Record<string, InlineFileContent | NestedInlineDirectory>;
     };
     /**
      * A reference to a remote git repository.
@@ -87,6 +104,8 @@ export declare namespace DataSources {
          * A path inside the git repository this data reference points to.
          *
          * Defaults to the root of the repository.
+         *
+         * @pattern ^(?!.*(?:^|/)\.\.(?:/|$)).*$
          */
         pathInRepository?: string;
     };
@@ -94,6 +113,10 @@ export declare namespace DataSources {
      * A union of all general data reference types.
      */
     export type DataReference = URLReference | ExecutionContextPath | InlineFile | InlineDirectory | GitPath;
+    /**
+     * A data reference that must resolve to a single file.
+     */
+    export type FileDataReference = URLReference | ExecutionContextPath | TargetSitePath | InlineFile;
     /**
      * }}}
      */
@@ -105,20 +128,40 @@ export declare namespace DataSources {
      */
     /** Helper types {{{ */
     /**
-     * A slug is a string matching the following regex:
-     *
-     * ```
-     * ^[a-zA-Z0-9_-]+$
-     * ```
+     * A WordPress.org directory slug.
      *
-     * This constraint may be expressed in TypeScript, but it would come at the
-     * expense of readability. This document will thus alias the general `string`
-     * type to `Slug`. Every reference to the `Slug` type should be treated as a
-     * string matching the above regex.
+     * Slugs are intentionally treated as opaque strings. Playground should not
+     * reject future WordPress.org slug formats just because they do not match the
+     * directory conventions common today.
      */
     export type Slug = string;
+    /**
+     * @asType string
+     * @pattern ^(?:latest|\d+\.\d+(?:\.\d+)?)$
+     */
     export type SimpleVersionExpression = 'latest' | `${number}.${number}` | `${number}.${number}.${number}`;
-    export type WordPressVersionSuffix = `beta${number}` | `rc${number}`;
+    export type VersionNumberComponent = `${bigint}`;
+    /**
+     * @asType string
+     * @pattern ^\d+\.\d+(?:\.\d+)?$
+     */
+    export type ComparableVersionExpression = `${VersionNumberComponent}.${VersionNumberComponent}` | `${VersionNumberComponent}.${VersionNumberComponent}.${VersionNumberComponent}`;
+    export type WordPressVersionSuffix = `beta${VersionNumberComponent}` | `rc${VersionNumberComponent}`;
+    /**
+     * @asType string
+     * @pattern ^\d+\.\d+(?:\.\d+)?(?:-(?:beta\d+|[Rr][Cc]\d+))?$
+     */
+    export type WordPressVersionConstraintVersion = ComparableVersionExpression | `${ComparableVersionExpression}-${WordPressVersionSuffix}`;
+    /**
+     * @asType string
+     * @pattern ^(?:latest|\d+\.\d+(?:\.\d+)?(?:-(?:beta\d+|[Rr][Cc]\d+))?)$
+     */
+    export type WordPressVersionPreferredVersion = 'latest' | WordPressVersionConstraintVersion;
+    /**
+     * @asType string
+     * @pattern ^(?:latest|\d+\.\d+(?:\.\d+)?)$
+     */
+    export type PHPVersionConstraintVersion = SimpleVersionExpression;
     /** }}} Helper types */
     /**
      * Plugin directory reference, e.g. "jetpack", "jetpack@6.4", or "akismet@6.4.3".
@@ -149,30 +192,46 @@ export declare namespace DataSources {
      */
     export type ThemeDirectoryReference = Slug | `${Slug}@${SimpleVersionExpression}`;
     /**
-     * WordPress version, e.g. "6.4", "6.4.3", "6.8-RC1", or "6.7-beta2".
+     * WordPress version, e.g. "latest", "beta", "trunk", "none", "6.4",
+     * "6.4.3", "6.8-RC1", or "6.7-beta2".
      *
      * These refer to slugs of specific WordPress releases as listed in
      * the first table column on https://wordpress.org/download/releases/.
+     * "none" is not a release. It means the Blueprint runs PHP without
+     * installing WordPress.
      *
      * The WordPressVersion type is only meaningful in the top-level
      * `wordpressVersion` property.
+     *
+     * @asType string
+     * @pattern ^(?:latest|beta|trunk|nightly|none|\d+\.\d+(?:\.\d+)?(?:-(?:beta\d+|[Rr][Cc]\d+))?)$
      */
-    export type WordPressVersion = SimpleVersionExpression | `${SimpleVersionExpression}-${WordPressVersionSuffix}`;
+    export type WordPressVersion = 'none' | 'beta' | 'trunk' | 'nightly' | SimpleVersionExpression | `${SimpleVersionExpression}-${WordPressVersionSuffix}`;
     /**
-     * PHP version, e.g. "8.1" or "8.1.3".
+     * PHP version, e.g. "8.1", "8.1.3", or "next".
      *
      * These refer to PHP versions as listed in https://www.php.net/releases/.
+     * `next` previews the php-src development branch and is currently
+     * supported by the web runtime only.
      *
      * The PHPVersion type is only meaningful in the top-level
      * `phpVersion` property.
+     *
+     * @asType string
+     * @pattern ^(?:latest|next|\d+\.\d+(?:\.\d+)?)$
      */
-    export type PHPVersion = SimpleVersionExpression;
+    export type PHPVersion = SimpleVersionExpression | 'next';
     /**
-     * A path within the built WordPress site, relative to the WordPress root
+     * A path within the target WordPress site, relative to the WordPress root
      * directory. For example, site:wp-content/uploads/2024/01/image.jpg.
      *
-     * This type is only meaningful in imperative Blueprint steps for operations
-     * such as creating new files or moving files and directories.
+     * Unlike an execution-context path, this path is resolved from the mutable
+     * target filesystem when the consuming step runs. Earlier steps may therefore
+     * create the referenced file. The runner must keep the path inside the target
+     * WordPress root; it never names a file on the host filesystem.
+     *
+     * @asType string
+     * @pattern ^site:(?!\/*$)(?!\.\.(?:/|$))(?!.*\/\.\.(?:/|$)).+$
      */
     export type TargetSitePath = `site:${string}`;
     export {};

package/lib/validate-blueprint-declaration.d.ts

@@ -0,0 +1,6 @@
+import { type BlueprintValidationResult } from './v1/compile';
+/**
+ * Validates either Blueprint declaration version without loading the v2
+ * validator for v1 declarations.
+ */
+export declare function validateBlueprintDeclaration(blueprintMaybe: unknown): Promise<BlueprintValidationResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-playground/blueprints",
-  "version": "3.1.43",
+  "version": "3.1.45",
   "exports": {
     ".": {
       "import": "./index.js",
@@ -25,22 +25,22 @@
     "access": "public",
     "directory": "../../../dist/packages/playground/blueprints"
   },
-  "gitHead": "7cc9b0e4e673406ca2d1eaf9cbcb40fdb86563fe",
+  "gitHead": "d8132e032daf7c1ac2fd568af48444d84a59ced2",
   "engines": {
     "node": ">=20.10.0",
     "npm": ">=10.2.3"
   },
   "dependencies": {
     "ajv": "8.18.0",
-    "@wp-playground/storage": "3.1.43",
-    "@php-wasm/util": "3.1.43",
-    "@wp-playground/common": "3.1.43",
-    "@php-wasm/logger": "3.1.43",
-    "@php-wasm/universal": "3.1.43",
-    "@wp-playground/wordpress": "3.1.43",
-    "@php-wasm/progress": "3.1.43",
-    "@php-wasm/web-service-worker": "3.1.43",
-    "@php-wasm/stream-compression": "3.1.43"
+    "@php-wasm/universal": "3.1.45",
+    "@wp-playground/storage": "3.1.45",
+    "@php-wasm/util": "3.1.45",
+    "@php-wasm/logger": "3.1.45",
+    "@wp-playground/wordpress": "3.1.45",
+    "@php-wasm/progress": "3.1.45",
+    "@wp-playground/common": "3.1.45",
+    "@php-wasm/web-service-worker": "3.1.45",
+    "@php-wasm/stream-compression": "3.1.45"
   },
   "packageManager": "npm@10.9.2",
   "overrides": {

package/schema-readme.md

@@ -1,10 +1,11 @@
-The JSON schema stored in this directory describes how to validate
-the Blueprints and is autogenerated from the Blueprints TypeScript types.
+The public JSON schema stored in this directory describes both Blueprint
+declaration versions and is autogenerated from the Blueprint TypeScript types.
 
-The Blueprint schema validator stored in this directory is used to validate
-Blueprints and is autogenerated from the Blueprints JSON schema.
+The existing `blueprint-schema-validator.js` remains the v1 runtime validator.
+Blueprint v2 has its own validator, so adding one version cannot silently
+change validation of the other.
 
-Whenever the types are modified, the schema and validator need to be
+Whenever the types are modified, the schemas and validators need to be
 rebuilt using `nx build playground-blueprints` and then committed to
 the repository.