Merge pull request #1005 from Automattic/issue/replay-export-snapshot-scoping

Scope replay export snapshots

Author: chubes4

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

@@ -18,6 +18,15 @@ export interface CommandDefinition {
   handler: CommandHandlerBinding
 }
 
+const snapshotScopingAcceptedArgs: CommandDefinition["acceptedArgs"] = [
+  { name: "snapshot-include-wp-content", description: "Comma-separated wp-content-relative paths to include in the runtime snapshot. Defaults to all non-excluded paths.", format: "string" },
+  { name: "snapshot-exclude-wp-content", description: "Comma-separated wp-content-relative paths to exclude from the runtime snapshot.", format: "string" },
+  { name: "snapshot-database-tables", description: "Comma-separated database table base names to include, such as posts,postmeta,options.", format: "string" },
+  { name: "snapshot-exclude-database-tables", description: "Comma-separated database table base names to exclude from the runtime snapshot.", format: "string" },
+  { name: "snapshot-option-names", description: "Comma-separated option_name values or LIKE patterns using * for the options table.", format: "string" },
+  { name: "snapshot-post-types", description: "Comma-separated post types used to scope posts and postmeta table exports.", format: "string" },
+]
+
 export const commandRegistry = [
   {
     id: "inspect-mounted-inputs",
@@ -57,6 +66,7 @@ export const commandRegistry = [
     description: "Capture the current WordPress runtime state as a portable state bundle source for replayable Playground artifacts.",
     acceptedArgs: [
       { name: "label", description: "Optional human-readable capture label recorded in the command output.", format: "string" },
+      ...snapshotScopingAcceptedArgs,
     ],
     outputShape: "wp-codebox/wordpress-state-bundle-capture/v1 JSON with runtime snapshot id, artifact refs, replay status, and capture summary.",
     policyRequirement: "Runtime policy commands must include wordpress.capture-state-bundle.",
@@ -71,6 +81,7 @@ export const commandRegistry = [
       { 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" },
+      ...snapshotScopingAcceptedArgs,
     ],
     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.",

packages/runtime-core/src/runtime-contracts.ts

@@ -859,7 +859,7 @@ export interface Runtime {
   mount(spec: MountSpec): Promise<void>
   execute(spec: ExecutionSpec): Promise<ExecutionResult>
   observe(spec: ObservationSpec): Promise<ObservationResult>
-  snapshot(): Promise<Snapshot>
+  snapshot(options?: unknown): Promise<Snapshot>
   collectArtifacts(spec?: ArtifactSpec): Promise<ArtifactBundle>
   destroy(): Promise<void>
 }

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

@@ -16,7 +16,7 @@ import type { PlaygroundCliServer } from "./preview-server.js"
 import { collectPlaygroundArtifacts } from "./runtime-artifact-helpers.js"
 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 { PlaygroundSnapshotRestoreError, contentDigest, mountsFromSnapshot, runtimeSnapshotExportPayload, runtimeSnapshotExportPhp, runtimeSnapshotPayload, runtimeSnapshotRestorePhp, runtimeSpecFromSnapshot, snapshotDigest, type RuntimeSnapshotArtifact, type RuntimeSnapshotExportOptions } 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"
@@ -344,10 +344,10 @@ class PlaygroundRuntime implements Runtime {
     return observation
   }
 
-  async snapshot(): Promise<Snapshot> {
+  async snapshot(options: RuntimeSnapshotExportOptions = {}): Promise<Snapshot> {
     const snapshotId = id("snapshot")
     const createdAt = now()
-    const payload = await this.captureRuntimeSnapshotArtifact(snapshotId, createdAt)
+    const payload = await this.captureRuntimeSnapshotArtifact(snapshotId, createdAt, options)
     const artifactPath = `files/runtime-snapshots/${snapshotId}.json`
     const absoluteArtifactPath = join(this.artifactRoot, artifactPath)
     const artifactJson = `${JSON.stringify(payload, null, 2)}\n`
@@ -398,10 +398,10 @@ class PlaygroundRuntime implements Runtime {
     return snapshot
   }
 
-  private async captureRuntimeSnapshotArtifact(snapshotId: string, createdAt: string): Promise<RuntimeSnapshotArtifact> {
+  private async captureRuntimeSnapshotArtifact(snapshotId: string, createdAt: string, options: RuntimeSnapshotExportOptions = {}): Promise<RuntimeSnapshotArtifact> {
     const server = await this.bootPlayground()
     const response = await this.runPlaygroundCommand("runtime.snapshot", server, {
-      code: bootstrapPhpCode(this.spec, runtimeSnapshotExportPhp({ excludedWpContentPaths: this.snapshotExcludedWpContentPaths() }), []),
+      code: bootstrapPhpCode(this.spec, runtimeSnapshotExportPhp({ ...options, excludedWpContentPaths: [...this.snapshotExcludedWpContentPaths(), ...(options.excludedWpContentPaths ?? [])] }), []),
     })
     assertPlaygroundResponseOk("runtime.snapshot", response)
     const captured = await runtimeSnapshotExportPayload(server, response.text)
@@ -800,7 +800,9 @@ class PlaygroundRuntime implements Runtime {
 
   async runCaptureStateBundle(spec: ExecutionSpec): Promise<string> {
     const label = stringArg(spec.args ?? [], "label")
-    const snapshot = await this.snapshot()
+    const snapshotOptions = snapshotOptionsFromArgs(spec.args ?? [])
+    const snapshot = await this.snapshot(snapshotOptions)
+    const snapshotOptionsMetadata = hasSnapshotOptions(snapshotOptions) ? { snapshotOptions } : {}
     const summary = snapshot.metadata.summary && typeof snapshot.metadata.summary === "object" && !Array.isArray(snapshot.metadata.summary)
       ? snapshot.metadata.summary as Record<string, unknown>
       : {}
@@ -820,6 +822,7 @@ class PlaygroundRuntime implements Runtime {
       summary: {
         databaseTables: summary.databaseTables ?? 0,
         wpContentFiles: summary.wpContentFiles ?? 0,
+        ...snapshotOptionsMetadata,
       },
     }, null, 2)}\n`
   }
@@ -829,6 +832,8 @@ class PlaygroundRuntime implements Runtime {
     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 snapshotOptions = snapshotOptionsFromArgs(spec.args ?? [])
+    const snapshotOptionsMetadata = hasSnapshotOptions(snapshotOptions) ? { snapshotOptions } : {}
 
     const materializeStartedAtMs = Date.now()
     let materialization: Awaited<ReturnType<typeof materializePlaygroundMountsFromVfs>> | undefined
@@ -841,7 +846,7 @@ class PlaygroundRuntime implements Runtime {
     const materializeMs = Date.now() - materializeStartedAtMs
 
     const snapshotStartedAtMs = Date.now()
-    const snapshot = await this.snapshot()
+    const snapshot = await this.snapshot(snapshotOptions)
     const snapshotMs = Date.now() - snapshotStartedAtMs
     const payload = await runtimeSnapshotPayload(snapshot)
 
@@ -857,6 +862,7 @@ class PlaygroundRuntime implements Runtime {
         command: "wordpress.export-replay-package",
         runtimeId: this.runtimeId,
         snapshotId: snapshot.id,
+        ...snapshotOptionsMetadata,
         artifactRoot: this.artifactRoot,
         ...(materialization ? { materialization } : {}),
       },
@@ -882,6 +888,7 @@ class PlaygroundRuntime implements Runtime {
         contentDigest: replayPackage.manifest.contentDigest,
         createdAt: replayPackage.manifest.createdAt,
       },
+      ...snapshotOptionsMetadata,
     }, null, 2)}\n`
   }
 
@@ -1137,6 +1144,39 @@ function nonNegativeIntegerStringArg(args: string[], name: string): number | und
   return Number.isInteger(parsed) && parsed >= 0 ? parsed : undefined
 }
 
+function stringListArg(args: string[], name: string): string[] | undefined {
+  const value = stringArg(args, name)
+  if (!value) {
+    return undefined
+  }
+
+  const values = value.split(",").map((item) => item.trim()).filter((item) => item.length > 0)
+  return values.length > 0 ? values : undefined
+}
+
+function snapshotOptionsFromArgs(args: string[]): RuntimeSnapshotExportOptions {
+  const options: RuntimeSnapshotExportOptions = {}
+  const includedWpContentPaths = stringListArg(args, "snapshot-include-wp-content")
+  const excludedWpContentPaths = stringListArg(args, "snapshot-exclude-wp-content")
+  const includedDatabaseTables = stringListArg(args, "snapshot-database-tables")
+  const excludedDatabaseTables = stringListArg(args, "snapshot-exclude-database-tables")
+  const includedOptionNames = stringListArg(args, "snapshot-option-names")
+  const includedPostTypes = stringListArg(args, "snapshot-post-types")
+
+  if (includedWpContentPaths) options.includedWpContentPaths = includedWpContentPaths
+  if (excludedWpContentPaths) options.excludedWpContentPaths = excludedWpContentPaths
+  if (includedDatabaseTables) options.includedDatabaseTables = includedDatabaseTables
+  if (excludedDatabaseTables) options.excludedDatabaseTables = excludedDatabaseTables
+  if (includedOptionNames) options.includedOptionNames = includedOptionNames
+  if (includedPostTypes) options.includedPostTypes = includedPostTypes
+
+  return options
+}
+
+function hasSnapshotOptions(options: RuntimeSnapshotExportOptions): boolean {
+  return Object.keys(options).length > 0
+}
+
 function replayExportOutputDirectory(artifactRoot: string, requested: string | undefined): string {
   const relativePath = requested?.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "") || "files/replay-package"
   if (relativePath.length === 0 || relativePath.includes("..")) {