Add nativeSpawn option to RunCLIArgs for host process spawning

[chubes4]

Summary

Add a nativeSpawn boolean to RunCLIArgs that enables native host process spawning via child_process.spawn for PHP's proc_open(), shell_exec(), and exec(). When enabled, the worker thread imports spawn directly instead of using the sandboxed handler that creates new PHP WASM instances.

Motivation

WordPress Studio uses runCLI() for its site daemon. PHP plugins that call proc_open() to communicate with external tools (e.g., php-mcp-client's StdioTransport for MCP servers) fail silently because the worker thread's sandboxed spawn handler creates new WASM instances instead of spawning host processes.

The sandboxed handler is correct for browser environments where host process spawning isn't possible. But in Node.js environments (CLI, Studio), native spawning should be available as an opt-in.

How AI was used in this PR

This PR was developed with Claude Code (AI pair programming). The root cause analysis, fix design, and test suite were developed collaboratively. All code has been reviewed and tested.

Changes

run-cli.ts

• Add nativeSpawn?: boolean to RunCLIArgs interface

blueprints-v1-handler.ts

• Pass nativeSpawn from RunCLIArgs to the worker's bootRequestHandler options

worker-thread-v1.ts

• Add nativeSpawn?: boolean to WorkerBootRequestHandlerOptions
• When nativeSpawn is true, the spawn handler imports child_process.spawn directly inside the worker thread instead of using sandboxedSpawnHandlerFactory
• The flag is a boolean (not a function) because spawn handlers can't be serialized across the Comlink worker thread boundary

php-proc-open.spec.ts (new test file)

• Tests for proc_open with native spawn handler
• Tests for shell_exec with native spawn handler
• Tests for proc_open failure without spawn handler

Design decisions

Boolean flag vs function reference: nativeSpawn is a boolean rather than accepting a custom SpawnHandler function because the worker thread runs in a separate Worker() context. Functions can't be serialized across the Comlink message boundary. The worker imports child_process.spawn directly when the flag is true.

Opt-in vs default: Native spawning is opt-in to preserve backward compatibility. The sandboxed handler remains the default, which is correct for browser environments and security-sensitive contexts.

Testing

Verified with comprehensive standalone tests against @php-wasm/node:

Test	Result
proc_open with stdout capture	✅
shell_exec output	✅
stderr capture	✅
Non-zero exit codes (exit 42)	✅
stdin piping (fwrite → cat → read)	✅
proc_open fails gracefully without handler	✅

Also verified in WordPress Studio CLI that the fallback path (runWpCliCommand with setSpawnHandler(spawn)) enables proc_open for WP-CLI commands.

Context

• Fixes RunCLIArgs: expose spawnHandler option for proc_open support #3480
• Companion PR: Automattic/studio#3057

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds an opt-in nativeSpawn flag to the Playground CLI worker boot flow so PHP code running under runCLI() can spawn real host processes (Node.js child_process.spawn) instead of using the sandboxed spawn handler that starts new PHP WASM instances—primarily to unblock proc_open()/shell_exec() use cases in Node environments.

Changes:

• Introduce nativeSpawn?: boolean in RunCLIArgs and propagate it into the Blueprints V1 worker boot options.
• Update the worker spawn handler selection to use native child_process.spawn when nativeSpawn is enabled.
• Add Node runtime tests verifying proc_open/shell_exec behavior with and without a spawn handler.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
test-spawn-handler.mjs	Adds a standalone manual test script to validate spawn handler propagation into proc_open/shell_exec.
packages/playground/cli/src/run-cli.ts	Extends RunCLIArgs with nativeSpawn and documents the behavior.
packages/playground/cli/src/blueprints-v1/blueprints-v1-handler.ts	Passes nativeSpawn through to the worker boot options.
packages/playground/cli/src/blueprints-v1/worker-thread-v1.ts	Switches spawn handler factory based on nativeSpawn, using host spawning when enabled.
packages/php-wasm/node/src/test/php-proc-open.spec.ts	Adds automated tests for proc_open/shell_exec with a native spawn handler.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.