Native PHP runtime: blueprint execution via blueprints.phar

apps/cli/commands/site/create.ts

@@ -1,6 +1,5 @@
 import crypto from 'crypto';
 import fs from 'fs';
-import os from 'os';
 import path from 'path';
 import { confirm, input, password, select } from '@inquirer/prompts';
 import { SupportedPHPVersions } from '@php-wasm/universal';
@@ -45,11 +44,7 @@ import {
 import { fetchWordPressVersions } from '@studio/common/lib/wordpress-versions';
 import { SiteCommandLoggerAction as LoggerAction } from '@studio/common/logger-actions';
 import { __, sprintf } from '@wordpress/i18n';
-import {
-	isStepDefinition,
-	type BlueprintV1Declaration,
-	type StepDefinition,
-} from '@wp-playground/blueprints';
+import { isStepDefinition, type BlueprintV1Declaration } from '@wp-playground/blueprints';
 import { bumpStat, getPlatformMetric } from 'cli/lib/bump-stat';
 import {
 	lockCliConfig,
@@ -279,71 +274,14 @@ export async function runCommand(
 		const externalPassword = options.adminPassword || blueprintCredentials?.adminPassword;
 		const adminPassword = externalPassword ? encodePassword( externalPassword ) : createPassword();
 
-		const setupSteps: StepDefinition[] = [];
-
 		const siteLanguage = await getPreferredSiteLanguage( options.wpVersion );
 
-		if ( siteLanguage && siteLanguage !== DEFAULT_LOCALE ) {
-			// For the 'latest' WP version, try using bundled language packs first to avoid
-			// a network round-trip. Fall back to the Playground setSiteLanguage step for
-			// non-latest versions or when bundled packs aren't available.
-			let isUsingBundledLanguagePacks = false;
-			if ( options.wpVersion === DEFAULT_WORDPRESS_VERSION ) {
-				isUsingBundledLanguagePacks = await copyLanguagePackToSite( sitePath, siteLanguage );
-			}
-
-			if ( isUsingBundledLanguagePacks ) {
-				setupSteps.push(
-					{
-						step: 'defineWpConfigConsts',
-						consts: {
-							WPLANG: siteLanguage,
-						},
-					},
-					{
-						step: 'setSiteOptions',
-						options: {
-							WPLANG: siteLanguage,
-						},
-					}
-				);
-			} else if ( isOnlineStatus ) {
-				setupSteps.push(
-					{
-						step: 'setSiteLanguage',
-						language: siteLanguage,
-					},
-					{
-						step: 'setSiteOptions',
-						options: {
-							WPLANG: siteLanguage,
-						},
-					}
-				);
-			}
-		}
-
-		const hasWpConfig = await pathExists( path.join( sitePath, 'wp-config.php' ) );
-		const isWordPressDirectoryInitialized = isWordPressDirResult && hasWpConfig;
-		if ( options.name && ! isWordPressDirectoryInitialized ) {
-			setupSteps.push( {
-				step: 'setSiteOptions',
-				options: {
-					blogname: options.name,
-				},
-			} );
-		}
-
-		if ( setupSteps.length > 0 ) {
-			if ( ! blueprint ) {
-				blueprint = {};
-				// Since we know the user didn't supply a blueprint, we create an empty directory to use as a
-				// fake location for the `blueprintUri`
-				const blueprintDir = fs.mkdtempSync( path.join( os.tmpdir(), 'studio-empty-blueprint-' ) );
-				blueprintUri = path.join( blueprintDir, 'blueprint.json' );
-			}
-			const existingSteps = Array.isArray( blueprint.steps ) ? blueprint.steps : [];
-			blueprint = { ...blueprint, steps: [ ...setupSteps, ...existingSteps ] };
+		if (
+			siteLanguage &&
+			siteLanguage !== DEFAULT_LOCALE &&
+			options.wpVersion === DEFAULT_WORDPRESS_VERSION
+		) {
+			await copyLanguagePackToSite( sitePath, siteLanguage );
 		}
 
 		const siteDetails: SiteData = {
@@ -394,6 +332,7 @@ export async function runCommand(
 					wpVersion: options.wpVersion,
 					blueprint,
 					blueprintUri,
+					siteLanguage,
 				} );
 				logger.reportSuccess( __( 'WordPress server started' ) );
 
@@ -437,6 +376,7 @@ export async function runCommand(
 						wpVersion: options.wpVersion,
 						blueprint,
 						blueprintUri,
+						siteLanguage,
 					} );
 					logger.reportSuccess( __( 'Blueprint applied successfully' ) );
 

apps/cli/commands/site/tests/create.test.ts

@@ -11,7 +11,7 @@ import { isOnline } from '@studio/common/lib/network-utils';
 import { portFinder } from '@studio/common/lib/port-finder';
 import { normalizeLineEndings } from '@studio/common/lib/remove-default-db-constants';
 import { getServerFilesPath } from '@studio/common/lib/well-known-paths';
-import { Blueprint, BlueprintV1Declaration, StepDefinition } from '@wp-playground/blueprints';
+import { Blueprint, BlueprintV1Declaration } from '@wp-playground/blueprints';
 import { vi, type MockInstance } from 'vitest';
 import {
 	lockCliConfig,
@@ -302,20 +302,8 @@ describe( 'CLI: studio site create', () => {
 					] ),
 				} )
 			);
-			expect( startWordPressServer ).toHaveBeenCalledWith(
-				expect.anything(),
-				expect.any( Logger ),
-				expect.objectContaining( {
-					blueprint: expect.objectContaining( {
-						steps: expect.arrayContaining( [
-							expect.objectContaining( {
-								step: 'setSiteOptions',
-								options: { blogname: 'My Custom Site' },
-							} ),
-						] ),
-					} ),
-				} )
-			);
+			// blogname is now set by playground-server-child via buildSetupSteps, not create.ts
+			expect( startWordPressServer ).toHaveBeenCalled();
 		} );
 
 		it( 'should NOT override blogname when adding existing WordPress directory with wp-config.php and name', async () => {
@@ -365,21 +353,8 @@ describe( 'CLI: studio site create', () => {
 				name: 'My Custom Site',
 			} );
 
-			// Verify setSiteOptions step IS in the blueprint steps (because wp-config.php doesn't exist)
-			expect( startWordPressServer ).toHaveBeenCalledWith(
-				expect.anything(),
-				expect.any( Logger ),
-				expect.objectContaining( {
-					blueprint: expect.objectContaining( {
-						steps: expect.arrayContaining( [
-							expect.objectContaining( {
-								step: 'setSiteOptions',
-								options: { blogname: 'My Custom Site' },
-							} ),
-						] ),
-					} ),
-				} )
-			);
+			// blogname is now set by playground-server-child via buildSetupSteps, not create.ts
+			expect( startWordPressServer ).toHaveBeenCalled();
 		} );
 
 		it( 'should use folder name as site name if no name provided', async () => {
@@ -523,7 +498,7 @@ describe( 'CLI: studio site create', () => {
 			);
 		} );
 
-		it( 'should prepend setSiteOptions step when name is provided with Blueprint', async () => {
+		it( 'should pass Blueprint through when name is provided with Blueprint', async () => {
 			await runCommand( mockSitePath, {
 				...defaultTestOptions,
 				name: 'My Site',
@@ -533,18 +508,12 @@ describe( 'CLI: studio site create', () => {
 				},
 			} );
 
+			// blogname is now set by playground-server-child via buildSetupSteps, not prepended here
 			expect( startWordPressServer ).toHaveBeenCalledWith(
 				expect.anything(),
 				expect.any( Logger ),
 				expect.objectContaining( {
-					blueprint: expect.objectContaining( {
-						steps: expect.arrayContaining( [
-							expect.objectContaining( {
-								step: 'setSiteOptions',
-								options: { blogname: 'My Site' },
-							} ),
-						] ),
-					} ),
+					blueprint: expect.any( Object ),
 				} )
 			);
 		} );
@@ -661,60 +630,37 @@ describe( 'CLI: studio site create', () => {
 			expect( disconnectFromDaemon ).toHaveBeenCalled();
 		} );
 
-		it( 'should run Blueprint when preferred language is configured but no Blueprint was given', async () => {
+		it( 'should create site with siteLanguage when preferred language is configured but no Blueprint given', async () => {
 			vi.mocked( getPreferredSiteLanguage ).mockResolvedValue( 'es_ES' );
 
 			await runCommand( mockSitePath, {
 				...defaultTestOptions,
 				noStart: true,
 			} );
 
-			expect( connectToDaemon ).toHaveBeenCalled();
-			expect( runBlueprint ).toHaveBeenCalledWith(
-				expect.any( Object ),
-				expect.any( Object ),
-				expect.objectContaining( {
-					blueprint: expect.any( Object ),
-					blueprintUri: expect.any( String ),
-				} )
-			);
+			// No blueprint to run — language steps are applied by playground-server-child on first start
+			expect( connectToDaemon ).not.toHaveBeenCalled();
+			expect( runBlueprint ).not.toHaveBeenCalled();
 			expect( startWordPressServer ).not.toHaveBeenCalled();
 			expect( consoleLogSpy ).toHaveBeenCalledWith( 'Site created successfully' );
-			expect( disconnectFromDaemon ).toHaveBeenCalled();
 		} );
 	} );
 
 	describe( 'Language Packs', () => {
-		it( 'should use bundled language packs and skip setSiteLanguage for latest WP version', async () => {
+		it( 'should use bundled language packs and pass siteLanguage for latest WP version', async () => {
 			vi.mocked( getPreferredSiteLanguage ).mockResolvedValue( 'sv_SE' );
 			vi.mocked( copyLanguagePackToSite ).mockResolvedValue( true );
 
 			await runCommand( mockSitePath, { ...defaultTestOptions } );
 
 			expect( copyLanguagePackToSite ).toHaveBeenCalledWith( mockSitePath, 'sv_SE' );
+			// Language steps (defineWpConfigConsts / setSiteLanguage) are now built by
+			// playground-server-child's buildSetupSteps, not by create.ts
 			expect( startWordPressServer ).toHaveBeenCalledWith(
 				expect.anything(),
 				expect.any( Logger ),
-				expect.objectContaining( {
-					blueprint: expect.objectContaining( {
-						steps: expect.arrayContaining( [
-							expect.objectContaining( {
-								step: 'defineWpConfigConsts',
-								consts: { WPLANG: 'sv_SE' },
-							} ),
-							expect.objectContaining( {
-								step: 'setSiteOptions',
-								options: { WPLANG: 'sv_SE' },
-							} ),
-						] ),
-					} ),
-				} )
+				expect.objectContaining( { siteLanguage: 'sv_SE' } )
 			);
-			// Should NOT include setSiteLanguage step
-			const calls = vi.mocked( startWordPressServer ).mock.calls;
-			const blueprintSteps = ( calls[ 0 ][ 2 ] as { blueprint?: BlueprintV1Declaration } )
-				?.blueprint?.steps as StepDefinition[];
-			expect( blueprintSteps.some( ( s ) => s.step === 'setSiteLanguage' ) ).toBe( false );
 		} );
 
 		it( 'should fall back to setSiteLanguage when bundled packs are not available', async () => {
@@ -723,27 +669,15 @@ describe( 'CLI: studio site create', () => {
 
 			await runCommand( mockSitePath, { ...defaultTestOptions } );
 
+			// setSiteLanguage vs defineWpConfigConsts is now decided by playground-server-child
 			expect( startWordPressServer ).toHaveBeenCalledWith(
 				expect.anything(),
 				expect.any( Logger ),
-				expect.objectContaining( {
-					blueprint: expect.objectContaining( {
-						steps: expect.arrayContaining( [
-							expect.objectContaining( {
-								step: 'setSiteLanguage',
-								language: 'sv_SE',
-							} ),
-							expect.objectContaining( {
-								step: 'setSiteOptions',
-								options: { WPLANG: 'sv_SE' },
-							} ),
-						] ),
-					} ),
-				} )
+				expect.objectContaining( { siteLanguage: 'sv_SE' } )
 			);
 		} );
 
-		it( 'should use setSiteLanguage for non-latest WP versions', async () => {
+		it( 'should pass siteLanguage for non-latest WP versions', async () => {
 			vi.mocked( getPreferredSiteLanguage ).mockResolvedValue( 'sv_SE' );
 
 			await runCommand( mockSitePath, {
@@ -752,19 +686,11 @@ describe( 'CLI: studio site create', () => {
 			} );
 
 			expect( copyLanguagePackToSite ).not.toHaveBeenCalled();
+			// setSiteLanguage step is now built by playground-server-child, not create.ts
 			expect( startWordPressServer ).toHaveBeenCalledWith(
 				expect.anything(),
 				expect.any( Logger ),
-				expect.objectContaining( {
-					blueprint: expect.objectContaining( {
-						steps: expect.arrayContaining( [
-							expect.objectContaining( {
-								step: 'setSiteLanguage',
-								language: 'sv_SE',
-							} ),
-						] ),
-					} ),
-				} )
+				expect.objectContaining( { siteLanguage: 'sv_SE' } )
 			);
 		} );
 

apps/cli/lib/daemon-client.ts

@@ -307,7 +307,7 @@ const daemonStartProcessSuccessResponseSchema = z.object( {
 export async function startProcess(
 	processName: string,
 	scriptPath: string,
-	env: Record< string, string > = {},
+	env: NodeJS.ProcessEnv = process.env,
 	args: string[] = []
 ): Promise< ProcessDescription > {
 	const response = await sendDaemonRequest( {

apps/cli/lib/dependency-management/paths.ts

@@ -51,3 +51,7 @@ export function getAiInstructionsPath(): string {
 export function getPhpMyAdminPath(): string {
 	return path.join( getWpFilesPath(), 'phpmyadmin' );
 }
+
+export function getBlueprintsPharPath(): string {
+	return path.join( getWpFilesPath(), 'blueprints', 'blueprints.phar' );
+}

apps/cli/lib/types/process-manager-ipc.ts

@@ -31,7 +31,7 @@ const daemonRequestStartProcessSchema = z.object( {
 	type: z.literal( 'start-process' ),
 	processName: z.string(),
 	scriptPath: z.string(),
-	env: z.record( z.string(), z.string() ).optional(),
+	env: z.record( z.string(), z.union( [ z.string(), z.undefined() ] ) ).optional(),
 	args: z.array( z.string() ).optional(),
 } );
 

apps/cli/lib/types/wordpress-server-ipc.ts

@@ -106,7 +106,10 @@ const childMessageActivity = z.object( {
 const childMessageResult = z.object( {
 	originalMessageId: z.string(),
 	topic: z.literal( 'result' ),
-	result: z.unknown(),
+	// `result` is `optional` so handlers that return `void` (e.g. `start-server`) survive
+	// IPC serialization — Node's default JSON IPC drops `undefined` values, leaving the key
+	// absent on the receiving side. Zod 4's `z.unknown()` rejects an absent key.
+	result: z.unknown().optional(),
 } );
 
 const childMessageError = z.object( {