@wp-playground/blueprints 3.1.44 → 3.1.46

package/lib/compile.d.ts

@@ -4,6 +4,7 @@ import { type CompileBlueprintV1Options, type CompiledBlueprintV1 } from './v1/c
 import type { BlueprintV1Declaration } from './v1/types';
 import type { BlueprintV2Declaration } from './v2/blueprint-v2-declaration';
 import { type CompiledBlueprintV2 } from './v2/compile';
+import type { ResolveRuntimeConfigurationOptions } from './resolve-runtime-configuration';
 export type BlueprintExecutionPath = 'v1' | 'v2';
 export type CompiledBlueprintForExecution = {
     version: 1;
@@ -16,9 +17,10 @@ export type CompiledBlueprintForExecution = {
     compiled: CompiledBlueprintV2;
     run: (playground: UniversalPHP) => Promise<void>;
 };
-export interface CompileBlueprintForExecutionOptions extends Omit<CompileBlueprintV1Options, 'onBlueprintValidated' | 'streamBundledFile'> {
+export interface CompileBlueprintForExecutionOptions extends Omit<CompileBlueprintV1Options, 'onBlueprintValidated' | 'streamBundledFile'>, ResolveRuntimeConfigurationOptions {
     onBlueprintValidated?: (blueprint: BlueprintDeclaration) => void;
 }
+type BlueprintExecutionInput = Blueprint | BlueprintBundle | string;
 /**
  * Compiles a Blueprint into the shape consumers need before execution.
  *
@@ -26,4 +28,5 @@ export interface CompileBlueprintForExecutionOptions extends Omit<CompileBluepri
  * backwards compatibility. This helper is the version-aware entrypoint that
  * newer callers can migrate to as Blueprint v2 support grows.
  */
-export declare function compileBlueprintForExecution(input: Blueprint | BlueprintBundle, options?: CompileBlueprintForExecutionOptions): Promise<CompiledBlueprintForExecution>;
+export declare function compileBlueprintForExecution(input: BlueprintExecutionInput, options?: CompileBlueprintForExecutionOptions): Promise<CompiledBlueprintForExecution>;
+export {};

package/lib/invalid-blueprint-error.d.ts

@@ -0,0 +1,5 @@
+/** Thrown when a Blueprint declaration does not conform to its schema. */
+export declare class InvalidBlueprintError extends Error {
+    readonly validationErrors?: unknown;
+    constructor(message: string, validationErrors?: unknown);
+}

package/lib/reflection.d.ts

@@ -2,7 +2,7 @@ import type { Blueprint, BlueprintBundle } from './types';
 import type { BlueprintV1Declaration } from './v1/types';
 import type { BlueprintV2Declaration } from './v2/blueprint-v2-declaration';
 export declare function isBlueprintBundle(input: any): input is BlueprintBundle;
-export declare function getBlueprintDeclaration(blueprint: Blueprint): Promise<BlueprintV1Declaration | BlueprintV2Declaration>;
+export declare function getBlueprintDeclaration(blueprint: Blueprint | string): Promise<BlueprintV1Declaration | BlueprintV2Declaration>;
 export type BlueprintType = 'bundle' | 'declaration';
 export declare class BlueprintReflection {
     private readonly declaration;

package/lib/resolve-runtime-configuration.d.ts

@@ -1,2 +1,14 @@
 import type { Blueprint, RuntimeConfiguration } from './types';
-export declare function resolveRuntimeConfiguration(blueprint: Blueprint): Promise<RuntimeConfiguration>;
+import { type BlueprintV2SiteMode } from './v2/resolve-runtime-configuration';
+export type ResolveRuntimeConfigurationOptions = {
+    /** Determines whether WordPress is selected for download or checked in place. */
+    siteMode?: BlueprintV2SiteMode;
+};
+/**
+ * Resolves the runtime settings required before executing a Blueprint.
+ *
+ * Blueprint v1 settings come from its compiled form. Blueprint v2 settings are
+ * delegated to the v2 runtime configuration resolver. Existing-site mode
+ * validates WordPress constraints without selecting a release to download.
+ */
+export declare function resolveRuntimeConfiguration(blueprint: Blueprint, options?: ResolveRuntimeConfigurationOptions): Promise<RuntimeConfiguration>;

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

@@ -29,6 +29,10 @@ export interface ImportWxrStep<ResourceType> {
      * @default true
      */
     rewriteUrls?: boolean;
+    /**
+     * Explicit URL replacements to apply when URL rewriting is enabled.
+     */
+    urlMapping?: Record<string, string>;
     /**
      * Whether to import comments from the WXR file.
      *
@@ -41,6 +45,22 @@ export interface ImportWxrStep<ResourceType> {
      * @default "admin"
      */
     defaultAuthorUsername?: string;
+    /**
+     * How to assign imported WXR authors to local WordPress users.
+     *
+     * @default "default-author"
+     */
+    authorsMode?: 'create' | 'default-author' | 'map';
+    /**
+     * Remote WXR author usernames keyed to existing local usernames.
+     */
+    authorsMap?: Record<string, string>;
+    /**
+     * Whether to create local users for imported WXR authors.
+     *
+     * @default false
+     */
+    importUsers?: boolean;
     /**
      * The importer to use. Possible values:
      *

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

@@ -11,10 +11,17 @@ import type { StepHandler } from '.';
  */
 export interface ResetDataStep {
     step: 'resetData';
+    /**
+     * Content types to remove. When omitted, all posts, pages, custom post
+     * types, and comments are removed.
+     */
+    contentTypes?: Array<'posts' | 'pages' | 'comments'>;
 }
 /**
- * Deletes WordPress posts and comments and sets the auto increment sequence
- * for the posts and comments tables to 0.
+ * Deletes the selected WordPress content through WordPress APIs so dependent
+ * records are removed with it. Empty tables have their sequences reset so
+ * later imports receive the identifiers they would on a site without the
+ * removed content.
  *
  * @param playground Playground client.
  */

package/lib/v1/compile.d.ts

@@ -5,10 +5,8 @@ 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);
-}
+import { InvalidBlueprintError } from '../invalid-blueprint-error';
+export { InvalidBlueprintError };
 /**
  * Error thrown when a single Blueprint step fails during execution.
  *

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

@@ -1,15 +1,5 @@
 import type { BlueprintBundle } from '../types';
-import type { BlueprintV1Declaration } from '../v1/types';
 import type { V2Schema } from './wep-1-blueprint-v2-schema/appendix-A-blueprint-v2-schema';
 type BlueprintV2Declaration = V2Schema.BlueprintV2;
 export type BlueprintV2 = BlueprintV2Declaration | BlueprintBundle;
 export type { BlueprintV2Declaration };
-export type RawBlueprintV2Data = string | BlueprintV2Declaration | undefined;
-export type ParsedBlueprintV1orV2String = {
-    type: 'inline-file';
-    contents: string;
-} | {
-    type: 'file-reference';
-    reference: string;
-};
-export declare function parseBlueprintDeclaration(source: RawBlueprintV2Data | ParsedBlueprintV1orV2String | BlueprintV1Declaration): ParsedBlueprintV1orV2String;

package/lib/v2/compile.d.ts

@@ -1,13 +1,16 @@
 import type { UniversalPHP } from '@php-wasm/universal';
 import type { RuntimeConfiguration } from '../types';
+import type { ResolveRuntimeConfigurationOptions } from '../resolve-runtime-configuration';
 import { type CompileBlueprintV1Options } from '../v1/compile';
 import type { StepDefinition } from '../steps';
 import type { BlueprintV2Declaration } from './blueprint-v2-declaration';
+import { type BlueprintV2SiteMode } from './resolve-runtime-configuration';
 export declare class UnsupportedBlueprintV2FeatureError extends Error {
     readonly featurePath: string;
     constructor(featurePath: string, message?: string);
 }
 type BlueprintV2ApplicationOptions = BlueprintV2Declaration['applicationOptions'];
+type BlueprintV2ContentBaseline = NonNullable<BlueprintV2Declaration['contentBaseline']>;
 type BlueprintV2Constants = NonNullable<BlueprintV2Declaration['constants']>;
 type BlueprintV2SiteOptions = NonNullable<BlueprintV2Declaration['siteOptions']>;
 type BlueprintV2MuPlugin = NonNullable<BlueprintV2Declaration['muPlugins']>[number];
@@ -28,6 +31,13 @@ export type BlueprintV2StepPlanLoweringResult = {
     unsupportedPlan: BlueprintV2ExecutionPlan;
 };
 export type BlueprintV2ExecutionPlanItem = {
+    type: 'applyContentBaseline';
+    contentBaseline: BlueprintV2ContentBaseline;
+    sourcePath: '/contentBaseline';
+} | {
+    type: 'applyUsersBaseline';
+    sourcePath: '/usersBaseline';
+} | {
     type: 'defineWpConfigConsts';
     consts: BlueprintV2Constants;
 } | {
@@ -87,7 +97,10 @@ export type CompiledBlueprintV2 = {
     unsupportedPlan: BlueprintV2ExecutionPlan;
     run: (playground: UniversalPHP) => Promise<void>;
 };
-export type CompileBlueprintV2Options = Pick<CompileBlueprintV1Options, 'streamBundledFile'>;
+export type CompileBlueprintV2Options = Pick<CompileBlueprintV1Options, 'progress' | 'streamBundledFile'> & ResolveRuntimeConfigurationOptions & {
+    onBlueprintValidated?: (blueprint: BlueprintV2Declaration) => void;
+};
+export type ResolveBlueprintV2WordPressSourceOptions = Pick<CompileBlueprintV1Options, 'corsProxy' | 'gitAdditionalHeadersCallback' | 'progress' | 'semaphore' | 'streamBundledFile'>;
 /**
  * Compiles a Blueprint v2 declaration into the pieces the TypeScript runner can
  * understand today.
@@ -98,6 +111,14 @@ export type CompileBlueprintV2Options = Pick<CompileBlueprintV1Options, 'streamB
  * any partial work is applied.
  */
 export declare function compileBlueprintV2(declaration: BlueprintV2Declaration, options?: CompileBlueprintV2Options): Promise<CompiledBlueprintV2>;
+/**
+ * Loads a custom WordPress source into the file expected by the boot API.
+ *
+ * Built-in versions and HTTP(S) ZIP URLs already use each consumer's normal
+ * WordPress download path. Execution-context, inline, and Git references need
+ * the Blueprint resource loader to turn them into a concrete archive first.
+ */
+export declare function resolveBlueprintV2WordPressSource(declaration: BlueprintV2Declaration, options?: ResolveBlueprintV2WordPressSourceOptions): Promise<File | undefined>;
 /**
  * Converts the top-level Blueprint v2 fields into a simple ordered plan.
  *
@@ -105,7 +126,7 @@ export declare function compileBlueprintV2(declaration: BlueprintV2Declaration,
  * and records where each item came from, which makes unsupported items visible
  * instead of silently dropping them during lowering.
  */
-export declare function createBlueprintV2ExecutionPlan(declaration: BlueprintV2Declaration): BlueprintV2ExecutionPlan;
+export declare function createBlueprintV2ExecutionPlan(declaration: BlueprintV2Declaration, siteMode?: BlueprintV2SiteMode): BlueprintV2ExecutionPlan;
 /**
  * Converts the supported v2 plan items into v1-compatible step records.
  *

package/lib/v2/resolve-runtime-configuration.d.ts

@@ -0,0 +1,20 @@
+import type { BlueprintDeclaration, RuntimeConfiguration } from '../types';
+import type { BlueprintV2Declaration } from './blueprint-v2-declaration';
+/**
+ * Resolves the runtime settings required by a Blueprint v2 declaration.
+ *
+ * This module owns the v2 support boundary: unsupported declarations and
+ * runtime sources are rejected here instead of falling back to v1 behavior.
+ * The validation callback runs before any runtime source is resolved.
+ */
+export declare function resolveBlueprintV2RuntimeConfiguration(declaration: BlueprintDeclaration, siteMode?: BlueprintV2SiteMode, onBlueprintValidated?: (declaration: BlueprintV2Declaration) => void): Promise<RuntimeConfiguration>;
+/** Describes whether Playground creates a site or applies to mounted files. */
+export type BlueprintV2SiteMode = 'create-new-site' | 'apply-to-existing-site';
+/**
+ * Verifies that an existing site satisfies its Blueprint v2 WordPress version.
+ *
+ * Only constraint objects restrict an existing site. Shorthand versions,
+ * including `latest` and concrete releases, are new-site selection hints.
+ * `preferred` is also a selection hint and does not narrow compatibility.
+ */
+export declare function assertBlueprintV2WordPressVersionCompatibility(declaration: BlueprintV2Declaration, installedVersion: string): Promise<void>;

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

@@ -0,0 +1,17 @@
+import type { BlueprintValidationResult } from '../v1/compile';
+export type BlueprintV2ValidationError = {
+    path: string;
+    message: string;
+};
+export type BlueprintV2ValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    errors: BlueprintV2ValidationError[];
+};
+/** Validates an unknown value against the complete Blueprint v2 schema. */
+export declare function validateBlueprintV2(blueprintMaybe: unknown): BlueprintV2ValidationResult;
+/** Returns actionable AJV errors with location data for editors and tooling. */
+export declare function validateBlueprintV2Declaration(blueprintMaybe: unknown): BlueprintValidationResult;
+/** Rejects an invalid value before any Blueprint v2 runtime work begins. */
+export declare function assertValidBlueprintV2Declaration(blueprintMaybe: unknown): void;

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,17 +191,21 @@ export declare namespace V2Schema {
          */
         constants?: WordPressConstants;
         /**
-         * WordPress version to install.
+         * WordPress version to install or require.
+         *
+         * 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 setting up the entire site, this will be used to resolve the
-         * installed WordPress version. The latest version matching the constraint
-         * will be chosen.
+         * 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.
          *
-         * 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.
+         * A data reference supplies the WordPress files for a newly created site.
          *
-         * @default "latest".
+         * @default "latest"
          */
         wordpressVersion?: DataSources.WordPressVersion | DataSources.DataReference | {
             min: DataSources.WordPressVersionConstraintVersion;
@@ -275,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>;
         /**
@@ -317,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.
@@ -357,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 = {
         /**
@@ -373,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.FileDataReference | DataSources.FileDataReference[];
-    } & URLMappingConfig) | ({
+    } | ({
         type: 'posts';
-        source: DataSources.FileDataReference | DataSources.FileDataReference[] | WordPressPost | WordPressPost[];
+        source: DataSources.FileDataReference | WordPressPost | (DataSources.FileDataReference | WordPressPost)[];
     } & URLMappingConfig)
     /**
      * WXR files to import.
@@ -532,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;
         /**
@@ -584,6 +644,8 @@ 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;
         /**
@@ -1063,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. */
@@ -1315,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[];
@@ -1347,6 +1413,14 @@ 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';
         /**
@@ -1417,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;
     };

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,7 +72,9 @@ export declare namespace DataSources {
      * ```
      */
     export type InlineDirectory = {
+        /** @pattern ^(?!(?:\.|\.\.)$)[^/]+$ */
         directoryName: string;
+        /** @propertyNames { "pattern": "^(?!(?:\\.|\\.\\.)$)[^/]+$" } */
         files: Record<string, InlineFileContent | NestedInlineDirectory>;
     };
     /**
@@ -75,6 +83,7 @@ export declare namespace DataSources {
      * Its directory name comes from the parent `files` record key.
      */
     export type NestedInlineDirectory = {
+        /** @propertyNames { "pattern": "^(?!(?:\\.|\\.\\.)$)[^/]+$" } */
         files: Record<string, InlineFileContent | NestedInlineDirectory>;
     };
     /**
@@ -95,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;
     };
@@ -105,7 +116,7 @@ export declare namespace DataSources {
     /**
      * A data reference that must resolve to a single file.
      */
-    export type FileDataReference = URLReference | ExecutionContextPath | InlineFile;
+    export type FileDataReference = URLReference | ExecutionContextPath | TargetSitePath | InlineFile;
     /**
      * }}}
      */
@@ -117,24 +128,39 @@ 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 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 */
     /**
@@ -166,16 +192,21 @@ export declare namespace DataSources {
      */
     export type ThemeDirectoryReference = Slug | `${Slug}@${SimpleVersionExpression}`;
     /**
-     * WordPress version, e.g. "latest", "beta", "trunk", "6.4",
+     * 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 = 'beta' | 'trunk' | 'nightly' | SimpleVersionExpression | `${SimpleVersionExpression}-${WordPressVersionSuffix}`;
+    export type WordPressVersion = 'none' | 'beta' | 'trunk' | 'nightly' | SimpleVersionExpression | `${SimpleVersionExpression}-${WordPressVersionSuffix}`;
     /**
      * PHP version, e.g. "8.1", "8.1.3", or "next".
      *
@@ -185,14 +216,22 @@ export declare namespace DataSources {
      *
      * The PHPVersion type is only meaningful in the top-level
      * `phpVersion` property.
+     *
+     * @asType string
+     * @pattern ^(?:latest|next|\d+\.\d+(?:\.\d+)?)$
      */
     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>;