Merge pull request #999 from Automattic/issue-994-replay-export

Fix replay export restore blueprint

Author: chubes4

package-lock.json

@@ -19,6 +19,7 @@
   "dependencies": {
     "@automattic/wp-codebox-core": "file:../runtime-core",
     "@wp-playground/cli": "^3.1.35",
+    "@wp-playground/storage": "^3.1.35",
     "@wp-playground/wordpress-builds": "^0.9.4",
     "@types/pngjs": "^6.0.5",
     "pixelmatch": "^7.2.0",

packages/runtime-playground/package.json

@@ -7,8 +7,9 @@ import { existsSync } from "node:fs"
 import { createServer as createHttpServer, type Server as HttpServer } from "node:http"
 import { mkdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises"
 import { homedir } from "node:os"
-import { basename, join } from "node:path"
+import { basename, dirname, join } from "node:path"
 import { createServer as createNetServer } from "node:net"
+import * as PlaygroundStorage from "@wp-playground/storage"
 import { resolveWordPressRelease } from "@wp-playground/wordpress"
 
 export interface PlaygroundCliModule {
@@ -103,7 +104,7 @@ export async function startPlaygroundCliServer(spec: RuntimeCreateSpec, mounts:
           wp: localAssetServer?.url ?? wordpressStartupAsset?.wp,
           php: spec.environment.phpVersion,
           "site-url": spec.preview?.siteUrl,
-          blueprint: playgroundBlueprint(spec.environment.blueprint, spec.policy, spec.preview?.siteUrl),
+          blueprint: playgroundCliBlueprint(spec),
         })
       } finally {
         await localAssetServer?.close()
@@ -135,6 +136,49 @@ export async function startPlaygroundCliServer(spec: RuntimeCreateSpec, mounts:
   }
 }
 
+function playgroundCliBlueprint(spec: RuntimeCreateSpec): unknown {
+  const blueprint = playgroundBlueprint(spec.environment.blueprint, spec.policy, spec.preview?.siteUrl)
+  if (blueprint !== spec.environment.blueprint) {
+    return blueprint
+  }
+
+  return localBlueprintPackageFilesystem(spec) ?? blueprint
+}
+
+function localBlueprintPackageFilesystem(spec: RuntimeCreateSpec): LocalBlueprintPackageFilesystem | undefined {
+  const task = spec.metadata?.task
+  if (!task || typeof task !== "object" || Array.isArray(task)) {
+    return undefined
+  }
+
+  const blueprintPath = (task as Record<string, unknown>).blueprintPath
+  if (typeof blueprintPath !== "string" || blueprintPath.length === 0) {
+    return undefined
+  }
+
+  return new LocalBlueprintPackageFilesystem(blueprintPath)
+}
+
+class LocalBlueprintPackageFilesystem {
+  private readonly filesystem: ReadableBlueprintFilesystem
+  private readonly blueprintFileName: string
+
+  constructor(blueprintPath: string) {
+    const NodeJsFilesystem = (PlaygroundStorage as unknown as { NodeJsFilesystem: new(root: string) => ReadableBlueprintFilesystem }).NodeJsFilesystem
+    this.filesystem = new NodeJsFilesystem(dirname(blueprintPath))
+    this.blueprintFileName = basename(blueprintPath)
+  }
+
+  read(path: string): ReturnType<ReadableBlueprintFilesystem["read"]> {
+    const normalizedPath = path.replace(/\\/g, "/").replace(/^\/+/, "")
+    return this.filesystem.read(normalizedPath === "blueprint.json" ? this.blueprintFileName : normalizedPath)
+  }
+}
+
+interface ReadableBlueprintFilesystem {
+  read(path: string): Promise<unknown>
+}
+
 async function startPlaygroundCliWithDynamicPortRetry(callback: (port: number) => Promise<PlaygroundCliServer>, fixedPreviewPort: boolean): Promise<PlaygroundCliServer> {
   const attempts = fixedPreviewPort ? 1 : 6
   for (let attempt = 1; attempt <= attempts; attempt++) {

packages/runtime-playground/src/playground-cli-runner.ts

@@ -7,7 +7,7 @@ import {
   type ArtifactManifest,
   type RuntimeInfo,
 } from "@automattic/wp-codebox-core"
-import { runtimeSnapshotRestorePhp, type RuntimeSnapshotArtifact } from "./runtime-snapshot.js"
+import { runtimeSnapshotRestorePhp, runtimeSnapshotRestorePhpFromFile, type RuntimeSnapshotArtifact } from "./runtime-snapshot.js"
 
 export interface ReplayableWordPressSiteBundleOptions {
   directory: string
@@ -244,22 +244,28 @@ export function buildReplayExportBlueprint(
   snapshot: RuntimeSnapshotArtifact,
   options: Pick<ReplayableWordPressSiteBundleOptions, "landingPage"> = {},
 ): Record<string, unknown> {
+  const snapshotPath = "/tmp/wp-codebox-runtime-snapshot.json"
   return {
     $schema: "https://playground.wordpress.net/blueprint-schema.json",
     preferredVersions: {
       wp: snapshot.compatibility.wordpressVersion,
       php: snapshot.compatibility.phpVersion,
     },
     landingPage: options.landingPage ?? "/",
-    steps: [],
-    "x-wp-codebox": {
-      schema: "wp-codebox/replay-export-blueprint/v1",
-      replayStatus: "external-runtime-snapshot",
-      snapshotPath: "files/runtime-snapshot.json",
-      restoreCommand: "wordpress.run-php",
-      restoreCode: "runtimeSnapshotRestorePhp(files/runtime-snapshot.json)",
-      note: "The runtime snapshot is stored beside this blueprint instead of embedded as one large runPHP string.",
-    },
+    steps: [
+      {
+        step: "writeFile",
+        path: snapshotPath,
+        data: {
+          resource: "bundled",
+          path: "files/runtime-snapshot.json",
+        },
+      },
+      {
+        step: "runPHP",
+        code: runtimeSnapshotRestorePhpFromFile(snapshotPath),
+      },
+    ],
   }
 }
 
@@ -277,6 +283,13 @@ export function buildReplayableWordPressSiteLimitations(
       activePlugins: snapshot.metadata.activePlugins,
     },
     source: options.source ?? { kind: "unspecified" },
+    restore: {
+      schema: "wp-codebox/replay-export-blueprint/v1",
+      replayStatus: "external-runtime-snapshot",
+      snapshotPath: "files/runtime-snapshot.json",
+      restoreSteps: ["writeFile", "runPHP"],
+      note: "The runtime snapshot is stored beside the blueprint instead of embedded as one large runPHP string.",
+    },
     limitations: [
       "The bundle replays captured database tables and wp-content files only.",
       "The exporter input must be policy-approved by the caller; this builder does not acquire or authorize private site sources.",

packages/runtime-playground/src/replayable-wordpress-site-bundle.ts

@@ -373,11 +373,28 @@ echo wp_codebox_snapshot_json_encode( array(
 }
 
 export function runtimeSnapshotRestorePhp(payload: RuntimeSnapshotArtifact): string {
-  return `${String.raw`
+  return runtimeSnapshotRestorePhpForPayload(`${String.raw`
 $payload = json_decode(<<<'WP_CODEBOX_SNAPSHOT_JSON'
 `}${JSON.stringify(payload)}${String.raw`
 WP_CODEBOX_SNAPSHOT_JSON
 , true );
+`}`)
+}
+
+export function runtimeSnapshotRestorePhpFromFile(path: string): string {
+  const encodedPath = JSON.stringify(path)
+  return runtimeSnapshotRestorePhpForPayload(`${String.raw`
+$wp_codebox_snapshot_path = `}${encodedPath}${String.raw`;
+$wp_codebox_snapshot_json = file_get_contents( $wp_codebox_snapshot_path );
+if ( false === $wp_codebox_snapshot_json ) {
+    throw new RuntimeException( 'Failed to read WordPress runtime snapshot payload: ' . $wp_codebox_snapshot_path );
+}
+$payload = json_decode( $wp_codebox_snapshot_json, true );
+`}`)
+}
+
+function runtimeSnapshotRestorePhpForPayload(payloadLoaderPhp: string): string {
+  return `${payloadLoaderPhp}${String.raw`
 
 if ( ! is_array( $payload ) || ( $payload['schema'] ?? '' ) !== 'wp-codebox/wordpress-runtime-snapshot/v1' ) {
     throw new RuntimeException( 'Invalid WordPress runtime snapshot payload.' );

packages/runtime-playground/src/runtime-snapshot.ts

@@ -0,0 +1,83 @@
+import { validateBlueprint } from "@wp-playground/blueprints"
+import { buildReplayExportBlueprint } from "../packages/runtime-playground/src/replayable-wordpress-site-bundle.ts"
+import type { RuntimeSnapshotArtifact } from "../packages/runtime-playground/src/runtime-snapshot.ts"
+
+const snapshot: RuntimeSnapshotArtifact = {
+  schema: "wp-codebox/wordpress-runtime-snapshot/v1",
+  version: 1,
+  id: "snapshot-smoke",
+  createdAt: "2026-06-15T00:00:00.000Z",
+  compatibility: {
+    backend: "wordpress-playground",
+    wordpressVersion: "latest",
+    phpVersion: "8.3",
+  },
+  metadata: {
+    runtime: {
+      id: "runtime-smoke",
+      backend: "wordpress-playground",
+      status: "destroyed",
+      createdAt: "2026-06-15T00:00:00.000Z",
+      environment: {
+        kind: "wordpress",
+        name: "runtime-smoke",
+        version: "latest",
+      },
+    },
+    mounts: [],
+    mountedInputs: [],
+    activeTheme: "twentytwentyfour",
+    activePlugins: [],
+    wpContentPath: "/wordpress/wp-content",
+  },
+  database: { tables: [] },
+  files: [
+    {
+      scope: "wp-content",
+      path: "smoke.txt",
+      bytes: 5,
+      sha256: "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
+      base64: "aGVsbG8=",
+    },
+  ],
+  hashes: {
+    database: { algorithm: "sha256", value: "database-smoke" },
+    files: { algorithm: "sha256", value: "files-smoke" },
+  },
+}
+
+const blueprint = buildReplayExportBlueprint(snapshot)
+const validation = validateBlueprint(blueprint)
+
+if (!validation.valid) {
+  throw new Error(`Replay export blueprint is not schema-valid: ${JSON.stringify(validation.errors, null, 2)}`)
+}
+
+if ("x-wp-codebox" in blueprint) {
+  throw new Error("Replay export blueprint must not include top-level x-wp-codebox metadata")
+}
+
+if (!Array.isArray(blueprint.steps) || blueprint.steps.length === 0) {
+  throw new Error("Replay export blueprint must include restore steps")
+}
+
+const serialized = JSON.stringify(blueprint)
+if (serialized.includes(snapshot.files[0].base64)) {
+  throw new Error("Replay export blueprint must not inline runtime snapshot file payloads")
+}
+
+const [writeSnapshotStep, restoreStep] = blueprint.steps as Array<Record<string, unknown>>
+if (writeSnapshotStep?.step !== "writeFile") {
+  throw new Error("Replay export blueprint must first write the external runtime snapshot into Playground")
+}
+
+const writeSnapshotData = writeSnapshotStep.data as Record<string, unknown> | undefined
+if (writeSnapshotData?.resource !== "bundled" || writeSnapshotData.path !== "files/runtime-snapshot.json") {
+  throw new Error("Replay export blueprint must reference files/runtime-snapshot.json as a bundled external resource")
+}
+
+if (restoreStep?.step !== "runPHP" || typeof restoreStep.code !== "string" || !restoreStep.code.includes("file_get_contents")) {
+  throw new Error("Replay export blueprint must restore by reading the written runtime snapshot file")
+}
+
+console.log("replay-export-blueprint-smoke passed")

scripts/replay-export-blueprint-smoke.ts

@@ -61,6 +61,7 @@ export const smokeGroups = {
       tsxSmoke("artifact-diagnostics-normalizer-smoke"),
       tsxSmoke("partial-artifact-discovery-smoke"),
       tsxSmoke("mounted-workspace-diff-smoke"),
+      tsxSmoke("replay-export-blueprint-smoke"),
     ],
   },
   runtime: {