Native PHP runtime: blueprint execution via blueprints.phar

[bcotrim]

Related issues

• Fixes RSM-1322

How AI was used in this PR

This PR was largely AI-assisted. I reviewed all changes and tested end-to-end locally.

Proposed Changes

Implements blueprint execution for the native PHP runtime (php-server-child.ts), which previously threw "not supported" for the run-blueprint IPC message.

• scripts/download-wp-server-files.ts: adds blueprints-phar download entry — fetches the latest blueprints.phar from WordPress/php-toolkit GitHub releases and lands it at wp-files/blueprints/blueprints.phar, which Vite auto-copies into dist/cli/wp-files/ at build time
• apps/cli/lib/dependency-management/paths.ts: adds getBlueprintsPharPath() following the existing phar path helper pattern
• apps/cli/php-server-child.ts:
  • adds runProcessToCompletion() — spawns a process, streams stdout/stderr, sends { topic: 'activity' } IPC pings on each chunk to keep the parent alive during long installs
  • adds runBlueprint() — writes blueprint JSON to a temp file, calls php blueprints.phar exec --mode=apply-to-existing-site, cleans up on exit
  • hooks runBlueprint() into startServer() so blueprints are applied automatically after WordPress is installed
  • wires the run-blueprint IPC case to call runBlueprint() directly (used by the --no-start path)

SQLite workaround: blueprints.phar detects SQLite by checking wp-content/plugins/sqlite-database-integration/load.php, but Studio installs it in mu-plugins/. A temporary symlink plugins/ → mu-plugins/ is created before the PHAR runs and removed after. Moving SQLite from mu-plugins to plugins is a broader conversation for later.

Testing Instructions

Example blueprint

{
  "steps": [
    {
      "step": "setSiteOptions",
      "options": {
        "blogname": "Blueprint worked!"
      }
    }
  ]
}

1. npm run download:wp-server-files (or npm install) — confirm wp-files/blueprints/blueprints.phar appears
2. npm run cli:build
3. Create a native-PHP site with the included test blueprint:

   STUDIO_RUNTIME=native-php sdev site create --blueprint docs/blueprints/test-set-site-options.json
   

4. Verify the blueprint applied:

   sdev wp --path ~/Studio/<site-name> option get blogname
   # should return: Blueprint worked!
   

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

[wpmobilebot]

📊 Performance Test Results

Comparing 24e019e vs trunk

app-size

Metric	trunk	24e019e	Diff	Change
App Size (Mac)	1454.99 MB	1456.67 MB	+1.68 MB	🔴 0.1%

site-editor

Metric	trunk	24e019e	Diff	Change
load	1740 ms	1785 ms	+45 ms	⚪ 0.0%

site-startup

Metric	trunk	24e019e	Diff	Change
siteCreation	8094 ms	8084 ms	10 ms	⚪ 0.0%
siteStartup	4949 ms	4949 ms	0 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)

[fredrikekelund]

Fundamentally, this works incredibly well 👍

I took the liberty of making a few changes to address things I identified while reviewing:

• Type-safe and reusable GitHub release fetching in scripts/download-wp-server-files.ts.
• Use a queue for run-blueprint messages.
• Hardened config.blueprint types to avoid non-null assertion.
• Removed runProcessToCompletion in favor of runPhpCommand.
• Write the blueprint JSON file to the original blueprint directory so blueprint.phar can read local assets correctly.
• Use fs.rm to remove the sqlite-database-integration symlink (Claude says Windows will throw when unlinking junctions). For extra safety, this is backed up by verifying the inode before deleting.

We should investigate how blueprint.phar handles remote resources more closely. Right now, php-server-child.ts errors if blueprint.uri is an HTTP URL. We can work around that by fetching the URL before handing it to blueprint.phar, but that only work if there are no additional gotchas related to how blueprint.phar handles HTTP fetching compared to the Playground implementation.