@wp-playground/blueprints 3.1.43 → 3.1.45

package/lib/compile.d.ts

@@ -0,0 +1,32 @@
+import type { UniversalPHP } from '@php-wasm/universal';
+import type { Blueprint, BlueprintBundle, BlueprintDeclaration } from './types';
+import { type CompileBlueprintV1Options, type CompiledBlueprintV1 } from './v1/compile';
+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;
+    declaration: BlueprintV1Declaration;
+    compiled: CompiledBlueprintV1;
+    run: (playground: UniversalPHP) => Promise<void>;
+} | {
+    version: 2;
+    declaration: BlueprintV2Declaration;
+    compiled: CompiledBlueprintV2;
+    run: (playground: UniversalPHP) => Promise<void>;
+};
+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.
+ *
+ * The legacy `compileBlueprint()` export intentionally remains v1-only for
+ * 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: 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/is-git-repo-url.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Heuristically indicates whether a URL looks like a Git repository.
+ *
+ * Blueprint compilers use this to distinguish plugin/theme repository URLs
+ * from downloadable ZIP URLs. This is intentionally a small allowlist of URL
+ * shapes Playground can clone, not a general Git remote detector.
+ */
+export declare function seemsLikeGitRepoUrl(url: string): boolean;

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

@@ -17,6 +17,50 @@ export interface ImportWxrStep<ResourceType> {
     step: 'importWxr';
     /** The file to import */
     file: ResourceType;
+    /**
+     * Whether to fetch and import attachment files referenced by the WXR file.
+     *
+     * @default true
+     */
+    fetchAttachments?: boolean;
+    /**
+     * Whether to rewrite imported URLs to the current site URL.
+     *
+     * @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.
+     *
+     * @default true
+     */
+    importComments?: boolean;
+    /**
+     * The fallback local user for imported authors that cannot be mapped.
+     *
+     * @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/install-plugin.d.ts

@@ -62,10 +62,22 @@ export interface InstallPluginOptions {
      * Whether to activate the plugin after installing it.
      */
     activate?: boolean;
+    /**
+     * Parameters to expose to the plugin during its activation hook.
+     */
+    activationOptions?: Record<string, unknown>;
+    /**
+     * Whether installation/activation failures should abort the Blueprint.
+     */
+    onError?: 'skip-plugin' | 'throw';
     /**
      * The name of the folder to install the plugin to. Defaults to guessing from pluginData
      */
     targetFolderName?: string;
+    /**
+     * Human-readable plugin name for progress captions and skip warnings.
+     */
+    humanReadableName?: string;
 }
 /**
  * Installs a WordPress plugin in the Playground.

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

@@ -49,10 +49,19 @@ export interface InstallThemeOptions {
      * Whether to import the theme's starter content after installing it.
      */
     importStarterContent?: boolean;
+    /**
+     * Whether installation, activation, or starter-content failures should
+     * abort the Blueprint.
+     */
+    onError?: 'skip-theme' | 'throw';
     /**
      * The name of the folder to install the theme to. Defaults to guessing from themeData
      */
     targetFolderName?: string;
+    /**
+     * Human-readable theme name for the progress caption and skip warning.
+     */
+    humanReadableName?: string;
 }
 /**
  * Installs a WordPress theme in the Playground.

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.
  *
@@ -75,7 +73,7 @@ export interface CompileBlueprintV1Options {
      */
     additionalSteps?: any[];
 }
-export declare function compileBlueprintV1(input: BlueprintV1Declaration | BlueprintBundle, options?: Omit<CompileBlueprintV1Options, 'streamBundledFile'>): Promise<CompiledBlueprintV1>;
+export declare function compileBlueprintV1(input: BlueprintV1Declaration | BlueprintBundle, options?: CompileBlueprintV1Options): Promise<CompiledBlueprintV1>;
 export declare function isBlueprintBundle(input: any): input is BlueprintBundle;
 export declare function getBlueprintDeclaration(blueprint: BlueprintV1 | BlueprintBundle): Promise<BlueprintV1Declaration>;
 export type BlueprintValidationResult = {

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

@@ -0,0 +1,138 @@
+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];
+type BlueprintV2Theme = NonNullable<BlueprintV2Declaration['themes']>[number];
+type BlueprintV2ActiveTheme = NonNullable<BlueprintV2Declaration['activeTheme']>;
+type BlueprintV2Plugin = NonNullable<BlueprintV2Declaration['plugins']>[number];
+type BlueprintV2Fonts = NonNullable<BlueprintV2Declaration['fonts']>;
+type BlueprintV2Media = NonNullable<BlueprintV2Declaration['media']>[number];
+type BlueprintV2Role = NonNullable<BlueprintV2Declaration['roles']>[number];
+type BlueprintV2User = NonNullable<BlueprintV2Declaration['users']>[number];
+type BlueprintV2PostTypes = NonNullable<BlueprintV2Declaration['postTypes']>;
+type BlueprintV2Content = NonNullable<BlueprintV2Declaration['content']>[number];
+type BlueprintV2Step = NonNullable<BlueprintV2Declaration['additionalStepsAfterExecution']>[number];
+export type BlueprintV2ExecutionPlan = BlueprintV2ExecutionPlanItem[];
+export type BlueprintV2StepPlan = StepDefinition[];
+export type BlueprintV2StepPlanLoweringResult = {
+    steps: BlueprintV2StepPlan;
+    unsupportedPlan: BlueprintV2ExecutionPlan;
+};
+export type BlueprintV2ExecutionPlanItem = {
+    type: 'applyContentBaseline';
+    contentBaseline: BlueprintV2ContentBaseline;
+    sourcePath: '/contentBaseline';
+} | {
+    type: 'applyUsersBaseline';
+    sourcePath: '/usersBaseline';
+} | {
+    type: 'defineWpConfigConsts';
+    consts: BlueprintV2Constants;
+} | {
+    type: 'setSiteOptions';
+    options: BlueprintV2SiteOptions;
+} | {
+    type: 'installMuPlugin';
+    muPlugin: BlueprintV2MuPlugin;
+    sourcePath: string;
+} | {
+    type: 'installTheme';
+    theme: BlueprintV2Theme;
+    active: false;
+    sourcePath: string;
+} | {
+    type: 'installTheme';
+    theme: BlueprintV2ActiveTheme;
+    active: true;
+    sourcePath: string;
+} | {
+    type: 'installPlugin';
+    plugin: BlueprintV2Plugin;
+    sourcePath: string;
+} | {
+    type: 'installFonts';
+    fonts: BlueprintV2Fonts;
+} | {
+    type: 'importMedia';
+    media: BlueprintV2Media;
+    sourcePath: string;
+} | {
+    type: 'setSiteLanguage';
+    language: string;
+} | {
+    type: 'defineRoles';
+    roles: BlueprintV2Role[];
+} | {
+    type: 'defineUsers';
+    users: BlueprintV2User[];
+} | {
+    type: 'definePostTypes';
+    postTypes: BlueprintV2PostTypes;
+} | {
+    type: 'importContent';
+    content: BlueprintV2Content;
+    sourcePath: string;
+} | {
+    type: 'runStep';
+    step: BlueprintV2Step;
+    sourcePath: string;
+};
+export type CompiledBlueprintV2 = {
+    runtime: RuntimeConfiguration;
+    applicationOptions?: BlueprintV2ApplicationOptions;
+    plan: BlueprintV2ExecutionPlan;
+    steps: BlueprintV2StepPlan;
+    unsupportedPlan: BlueprintV2ExecutionPlan;
+    run: (playground: UniversalPHP) => Promise<void>;
+};
+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.
+ *
+ * It resolves runtime options, creates an ordered v2 execution plan, and lowers
+ * supported plan items into v1 step records. Fully lowered plans run through the
+ * existing v1 runner; unsupported items stay visible and block execution before
+ * 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.
+ *
+ * The plan keeps the original v2 data intact. It only decides execution order
+ * 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, siteMode?: BlueprintV2SiteMode): BlueprintV2ExecutionPlan;
+/**
+ * Converts the supported v2 plan items into v1-compatible step records.
+ *
+ * The v1 step runner already knows how to install plugins, install themes, set
+ * options, and run several imperative steps. This function reuses those shapes
+ * while keeping unsupported v2-only work in `unsupportedPlan` for future PRs.
+ */
+export declare function lowerBlueprintV2ExecutionPlan(plan: BlueprintV2ExecutionPlan): BlueprintV2StepPlanLoweringResult;
+export {};

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;