Add replay package export step

Author: chubes4

README.md

@@ -1081,6 +1081,17 @@ Current bundles include:
 - `files/diffs/<mount>.patch`: unified text diff from the mount baseline (a seeded baseline directory, or the git `HEAD` of a git work-tree mount) to the sandbox output.
 - `files/mounts/<index>/...`: copied file contents from readwrite mounts.
 
+Recipes that import a generated site into a clean runtime can export replay evidence before final artifact collection with a workflow step:
+
+```json
+{
+  "command": "wordpress.export-replay-package",
+  "args": ["label=studio-web-replay", "landing-page=/"]
+}
+```
+
+The step writes `files/replay-package/manifest.json`, `blueprint.after.json`, `blueprint.after-notes.json`, and `files/runtime-snapshot.json` under the runtime artifact root. Its stdout is a `wp-codebox/wordpress-replay-export/v1` envelope with `importMs`, `materializeMs`, `snapshotMs`, `exportMs`, `databaseTables`, `wpContentFiles`, `snapshotBytes`, and `blueprintBytes`. The exported `blueprint.after.json` keeps the runtime snapshot as a referenced package file instead of embedding the full snapshot as one large `runPHP` string.
+
 `metadata.json` points to the canonical changed-files, patch, test-results, review, and mount-diff artifact paths under `artifacts`. It also includes `provenance` derived from data WP Codebox already has: task input/context where available, WP Codebox runtime version, WordPress version, mounted component/mount metadata, and agent/provider/model fields passed to the sandbox runner. `files/diffs/<mount>.patch` remains available for per-mount detail; `files/patch.diff` is the combined review/apply-back patch surface.
 
 ### `files/test-results.json`

packages/runtime-core/src/command-registry.ts

@@ -63,6 +63,20 @@ export const commandRegistry = [
     recipe: true,
     handler: { kind: "playground", method: "runCaptureStateBundle" },
   },
+  {
+    id: "wordpress.export-replay-package",
+    description: "Export the current imported WordPress runtime as a replay package with a compact blueprint, external runtime snapshot, notes, manifest, and metrics.",
+    acceptedArgs: [
+      { name: "label", description: "Optional human-readable export label recorded in the command output and package source metadata.", format: "string" },
+      { name: "output-dir", description: "Optional package directory relative to the runtime artifact root; defaults to files/replay-package.", format: "relative path" },
+      { name: "landing-page", description: "Optional replay landing page recorded in blueprint.after.json.", format: "path" },
+      { name: "import-ms", description: "Optional importer duration supplied by the caller so replay export metrics can include the preceding import phase.", format: "non-negative integer" },
+    ],
+    outputShape: "wp-codebox/wordpress-replay-export/v1 JSON with import/materialization/snapshot/export metrics and manifest, blueprint.after.json, blueprint.after-notes.json, and files/runtime-snapshot.json artifact paths.",
+    policyRequirement: "Runtime policy commands must include wordpress.export-replay-package.",
+    recipe: true,
+    handler: { kind: "playground", method: "runExportReplayPackage" },
+  },
   {
     id: "wordpress.ability",
     description: "Execute a registered WordPress Ability in the sandbox.",

packages/runtime-playground/src/artifact-bundle-builder.ts

@@ -142,6 +142,7 @@ export class ArtifactBundleBuilder {
         .filter((ref): ref is typeof ref & { path: string } => typeof ref.path === "string" && ref.path.length > 0)
         .map((ref) => artifactManifestFile(join(source.artifactRoot, ref.path), "runtime-snapshot", "application/json")),
     )
+    const replayExportPackageFiles = replayExportPackageManifestFiles(source.artifactRoot, source.commands)
     const capturedMounts = await source.captureMountedFiles(filesDirectory, redactor)
     const { mountDiffs, changedFiles, patch, diagnostics: mountDiffDiagnostics } = await source.captureMountDiffs(filesDirectory, redactor)
     const changedFilesJson = redactor.redact("files/changed-files.json", `${JSON.stringify(changedFiles, null, 2)}\n`)
@@ -323,6 +324,7 @@ export class ArtifactBundleBuilder {
       ...source.pluginCheckManifestFiles(),
       ...source.themeCheckManifestFiles(),
       ...runtimeSnapshotFiles,
+      ...replayExportPackageFiles,
       ...mountDiffs.map((diff) => artifactManifestFile(join(source.artifactRoot, diff.artifactPath), "diff", "text/x-diff")),
       ...capturedMounts.files.map((file) =>
         artifactManifestFile(join(source.artifactRoot, file.artifactPath), "file", file.contentType),
@@ -1087,6 +1089,50 @@ function artifactPreviewContentType(path: string): string {
   return "application/octet-stream"
 }
 
+function replayExportPackageManifestFiles(artifactRoot: string, commands: ExecutionResult[]): ArtifactManifestFile[] {
+  return commands.flatMap((command) => {
+    if (command.command !== "wordpress.export-replay-package" || command.exitCode !== 0) {
+      return []
+    }
+
+    let output: unknown
+    try {
+      output = JSON.parse(command.stdout.trim() || "{}")
+    } catch {
+      return []
+    }
+
+    const envelope = asRecord(output)
+    const artifacts = asRecord(envelope?.artifacts)
+    const directory = stringValue(envelope?.directory)
+    if (envelope?.schema !== "wp-codebox/wordpress-replay-export/v1" || !directory || !artifacts) {
+      return []
+    }
+
+    const refs: Array<{ key: string; kind: string; contentType: string }> = [
+      { key: "manifest", kind: "replay-package-manifest", contentType: "application/json" },
+      { key: "blueprint", kind: "blueprint-after", contentType: "application/json" },
+      { key: "snapshot", kind: "runtime-snapshot", contentType: "application/json" },
+      { key: "notes", kind: "blueprint-after-notes", contentType: "application/json" },
+    ]
+
+    return refs.flatMap((ref) => {
+      const artifactPath = stringValue(artifacts[ref.key])
+      if (!artifactPath) {
+        return []
+      }
+
+      const absolutePath = join(directory, artifactPath)
+      const manifestPath = relative(artifactRoot, absolutePath).replace(/\\/g, "/")
+      if (manifestPath.startsWith("..") || manifestPath.startsWith("/")) {
+        return []
+      }
+
+      return [artifactManifestFile(join(artifactRoot, manifestPath), ref.kind, ref.contentType)]
+    })
+  })
+}
+
 function asRecord(value: unknown): Record<string, unknown> | undefined {
   return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined
 }

packages/runtime-playground/src/command-router.ts

@@ -8,6 +8,7 @@ interface PlaygroundCommandRuntime {
   runPhp(spec: ExecutionSpec): Promise<string>
   runWpCli(spec: ExecutionSpec): Promise<string>
   runCaptureStateBundle(spec: ExecutionSpec): Promise<string>
+  runExportReplayPackage(spec: ExecutionSpec): Promise<string>
   runRestRequest(spec: ExecutionSpec): Promise<string>
   runAbility(spec: ExecutionSpec): Promise<string>
   runBench(spec: ExecutionSpec): Promise<string>
@@ -30,6 +31,7 @@ const playgroundCommandHandlers = {
   "wordpress.run-php": (runtime, spec) => runtime.runPhp(spec),
   "wordpress.wp-cli": (runtime, spec) => runtime.runWpCli(spec),
   "wordpress.capture-state-bundle": (runtime, spec) => runtime.runCaptureStateBundle(spec),
+  "wordpress.export-replay-package": (runtime, spec) => runtime.runExportReplayPackage(spec),
   "wordpress.rest-request": (runtime, spec) => runtime.runRestRequest(spec),
   "wordpress.ability": (runtime, spec) => runtime.runAbility(spec),
   "wordpress.bench": (runtime, spec) => runtime.runBench(spec),

packages/runtime-playground/src/index.ts

@@ -4,6 +4,6 @@ export { browserArtifactMetrics, type BrowserArtifactMetricsResult } from "./bro
 export { createHostCommandTool, type HostCommandToolConfig } from "./host-command-tool.js"
 export { PlaygroundRuntimeBackend, createPlaygroundRuntimeBackend, playgroundRuntimeBackendProvider } from "./playground-runtime.js"
 export { preflightPhpWasmRuntimeAssets, PhpWasmRuntimeAssetIntegrityError, type PhpWasmRuntimeAssetPreflight, type PhpWasmRuntimeAssetPreflightOptions } from "./php-wasm-preflight.js"
-export { buildReplayableWordPressSiteBlueprint, buildReplayableWordPressSiteLimitations, writeReplayableWordPressSiteBundle, type ReplayableWordPressSiteBundle, type ReplayableWordPressSiteBundleManifest, type ReplayableWordPressSiteBundleOptions } from "./replayable-wordpress-site-bundle.js"
+export { buildReplayExportBlueprint, buildReplayableWordPressSiteBlueprint, buildReplayableWordPressSiteLimitations, writeReplayExportPackage, writeReplayableWordPressSiteBundle, type ReplayExportPackage, type ReplayExportPackageOptions, type ReplayableWordPressSiteBundle, type ReplayableWordPressSiteBundleManifest, type ReplayableWordPressSiteBundleOptions } from "./replayable-wordpress-site-bundle.js"
 export type { RuntimeSnapshotArtifact } from "./runtime-snapshot.js"
 export type { PlaygroundCliModule } from "./playground-cli-runner.js"

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

@@ -18,6 +18,7 @@ import { materializePlaygroundMountsFromVfs } from "./mount-materialization.js"
 import { runAbilityCommand, runBenchCommand, runCorePhpunitCommand, runPhpCommand, runPhpunitCommand, runPluginCheckCommand, runRestRequestCommand, runThemeCheckCommand } from "./wordpress-command-runners.js"
 import { PlaygroundSnapshotRestoreError, contentDigest, mountsFromSnapshot, runtimeSnapshotExportPayload, runtimeSnapshotExportPhp, runtimeSnapshotPayload, runtimeSnapshotRestorePhp, runtimeSpecFromSnapshot, snapshotDigest, type RuntimeSnapshotArtifact } from "./runtime-snapshot.js"
 import { createRuntimeWpCliBridge, type RuntimeWpCliBridge } from "./runtime-wp-cli-bridge.js"
+import { writeReplayExportPackage } from "./replayable-wordpress-site-bundle.js"
 import { preflightPhpWasmRuntimeAssets } from "./php-wasm-preflight.js"
 import { previewReviewerAccess } from "./preview-reviewer-access.js"
 import type {
@@ -823,6 +824,67 @@ class PlaygroundRuntime implements Runtime {
     }, null, 2)}\n`
   }
 
+  async runExportReplayPackage(spec: ExecutionSpec): Promise<string> {
+    const label = stringArg(spec.args ?? [], "label")
+    const landingPage = stringArg(spec.args ?? [], "landing-page")
+    const outputDirectory = replayExportOutputDirectory(this.artifactRoot, stringArg(spec.args ?? [], "output-dir"))
+    const importMs = nonNegativeIntegerStringArg(spec.args ?? [], "import-ms") ?? 0
+
+    const materializeStartedAtMs = Date.now()
+    let materialization: Awaited<ReturnType<typeof materializePlaygroundMountsFromVfs>> | undefined
+    if (this.status !== "destroyed" && this.cliServerPromise) {
+      materialization = await materializePlaygroundMountsFromVfs(await this.cliServerPromise, this.mounts)
+      if (materialization.materialized > 0 || materialization.deleted > 0 || materialization.skipped > 0) {
+        this.recordEvent("runtime.mounts.materialized", { ...materialization, source: "wordpress.export-replay-package" })
+      }
+    }
+    const materializeMs = Date.now() - materializeStartedAtMs
+
+    const snapshotStartedAtMs = Date.now()
+    const snapshot = await this.snapshot()
+    const snapshotMs = Date.now() - snapshotStartedAtMs
+    const payload = await runtimeSnapshotPayload(snapshot)
+
+    const exportStartedAtMs = Date.now()
+    const replayPackage = await writeReplayExportPackage(payload, {
+      directory: outputDirectory,
+      landingPage,
+      importMs,
+      materializeMs,
+      snapshotMs,
+      source: {
+        ...(label ? { label } : {}),
+        command: "wordpress.export-replay-package",
+        runtimeId: this.runtimeId,
+        snapshotId: snapshot.id,
+        artifactRoot: this.artifactRoot,
+        ...(materialization ? { materialization } : {}),
+      },
+    })
+    replayPackage.metrics.exportMs = Date.now() - exportStartedAtMs
+
+    this.recordEvent("runtime.replay-package.exported", {
+      directory: replayPackage.directory,
+      metrics: replayPackage.metrics,
+      artifacts: replayPackage.artifacts,
+    })
+
+    return `${JSON.stringify({
+      schema: "wp-codebox/wordpress-replay-export/v1",
+      status: replayPackage.status,
+      ...(label ? { label } : {}),
+      replayStatus: "replayable-runtime-state",
+      directory: replayPackage.directory,
+      metrics: replayPackage.metrics,
+      artifacts: replayPackage.artifacts,
+      manifest: {
+        id: replayPackage.manifest.id,
+        contentDigest: replayPackage.manifest.contentDigest,
+        createdAt: replayPackage.manifest.createdAt,
+      },
+    }, null, 2)}\n`
+  }
+
   async runPluginCheck(spec: ExecutionSpec): Promise<string> {
     const server = await this.bootPlayground()
     const result = await runPluginCheckCommand({
@@ -1065,6 +1127,25 @@ function stringArg(args: string[], name: string): string | undefined {
   return value && value.length > 0 ? value : undefined
 }
 
+function nonNegativeIntegerStringArg(args: string[], name: string): number | undefined {
+  const value = stringArg(args, name)
+  if (!value) {
+    return undefined
+  }
+
+  const parsed = Number.parseInt(value, 10)
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : undefined
+}
+
+function replayExportOutputDirectory(artifactRoot: string, requested: string | undefined): string {
+  const relativePath = requested?.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "") || "files/replay-package"
+  if (relativePath.length === 0 || relativePath.includes("..")) {
+    throw new Error("wordpress.export-replay-package output-dir must be a relative path inside the runtime artifact root")
+  }
+
+  return join(artifactRoot, relativePath)
+}
+
 function wpContentRelativePath(path: string): string | undefined {
   const normalized = path.replace(/\\/g, "/").replace(/\/+$/g, "")
   const marker = "/wp-content/"