build-snapshot output fails importWordPressFiles database copy #4297

What I was trying to do

I was turning a completed local WordPress Studio site into an immutable, shareable WordPress Playground URL:

1. Export the existing SQLite-backed site with build-snapshot.
2. Place that snapshot beside a Blueprint using importWordPressFiles.
3. Publish the Blueprint bundle and launch it through ?blueprint-url=....

The export succeeds, but importing the generated snapshot fails before WordPress boots. I reduced the failure to a fresh Playground-generated site, so it does not depend on Studio, the original site, or third-party plugins.

Minimal reproduction

Create seed-blueprint.json:

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "preferredVersions": {
    "php": "8.3",
    "wp": "latest"
  },
  "steps": [
    {
      "step": "runPHP",
      "code": "<?php require '/wordpress/wp-load.php'; update_option( 'blogname', 'Snapshot import reproduction' );"
    }
  ]
}

Create restore-blueprint.json in the same directory:

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "preferredVersions": {
    "php": "8.3",
    "wp": "latest"
  },
  "steps": [
    {
      "step": "importWordPressFiles",
      "wordPressFilesZip": {
        "resource": "bundled",
        "path": "/site.zip"
      }
    }
  ]
}

Run:

npx --yes @wp-playground/cli@latest build-snapshot \
  --blueprint seed-blueprint.json \
  --outfile site.zip

npx --yes @wp-playground/cli@latest build-snapshot \
  --blueprint restore-blueprint.json \
  --blueprint-may-read-adjacent-files \
  --outfile restored.zip

Actual behavior

The first command succeeds. The second command fails:

WordPress file import failed while replacing live files. The remaining staged files were preserved for recovery at /tmp/import-wordpress-files-.../.
Error: Error when executing the blueprint step #1: Could not copy /tmp/import-wordpress-files-.../wordpress/wp-content/database to /wordpress/wp-content/database: There is no such file or directory OR the parent directory does not exist.

I also reproduced the same boundary with:

• A minimal archive containing wp-content/database/.ht.sqlite.
• A full WordPress archive containing core, wp-config.php, wp-content, and playground-export.json.
• A snapshot generated directly by the first @wp-playground/cli build-snapshot command above.

Expected behavior

An archive produced by build-snapshot should be accepted by importWordPressFiles, producing a restored snapshot with the same database state.

Environment

• @wp-playground/cli npm latest: 3.1.52
• npm latest modified: 2026-08-31
• macOS / Darwin
• PHP: 8.3
• WordPress: latest

Related context

• importWordPressFiles should leave directories untouched that are not in the ZIP file #1992 discusses wp-content replacement semantics but does not track this copy failure.
• Full-site Export / Import Format #1563 tracks the broader full-site export/import format.
• [Blueprints] Make WordPress file imports failure-safe #3848 recently strengthened failure handling in this importer and is why the staged directory is preserved, but it does not include a regression test for a build-snapshot → importWordPressFiles round trip.

A deterministic round-trip test using the two commands above would cover the user-facing contract.

AI assistance disclosure

OpenCode with openai/gpt-5.6-sol was used to reduce the reproduction, inspect the current importer boundary, and draft this report under Chris Huber's direction.