Merge branch 'trunk' into rsm-1650-codex-build-static-php-cli-binaries

Author: bcotrim

.github/dependabot.yml

@@ -25,10 +25,6 @@ updates:
       - dependency-name: "wpcom"
       - dependency-name: "wpcom-*"
 
-      # WordPress Playground & PHP WASM
-      - dependency-name: "@wp-playground/*"
-      - dependency-name: "@php-wasm/*"
-
       # TypeScript ecosystem
       - dependency-name: "typescript"
       - dependency-name: "typescript-*"
@@ -165,11 +161,6 @@ updates:
           - "electron-playwright-helpers"
           - "electron-devtools-installer"
 
-      wp-playground-php-wasm:
-        patterns:
-          - "@wp-playground/*"
-          - "@php-wasm/*"
-
       wordpress:
         patterns:
           - "@wordpress/*"
@@ -279,6 +270,8 @@ updates:
       - dependency-name: "eslint-plugin-studio"
       - dependency-name: "winreg" # v1.2.5 has a known issue: https://github.com/fresc81/node-winreg/issues/65
       - dependency-name: "@types/glob" # glob@7 (transitive) has no bundled types; @types/glob@9 is a stub for glob@9+ only
+      - dependency-name: "@wp-playground/*" # must be pinned exactly and bumped manually in lockstep — version mismatches cause runtime failures and ~450 MB bundle bloat
+      - dependency-name: "@php-wasm/*" # must be pinned exactly and bumped manually in lockstep — version mismatches cause runtime failures and ~450 MB bundle bloat
 
   # Enable version updates for GitHub Actions
   - package-ecosystem: "github-actions"

AGENTS.md

@@ -109,6 +109,8 @@ If you've built a substantial new feature — especially one generated with AI a
 
 **Port Conflicts**: Site servers dynamically allocate ports. Don't hardcode port numbers; use the port-finder utility.
 
+**CRITICAL - Playground/PHP-WASM Package Versions**: Always pin `@wp-playground/*` and `@php-wasm/*` packages to **exact versions** (no `^` or `~` ranges) in all `package.json` files. A caret range causes `install:bundle` to resolve a newer version when one publishes, creating a version conflict. npm then installs duplicate copies of all PHP WASM packages nested under the conflicting package's `node_modules/`. The `prune-php-wasm` vite plugin only removes top-level asyncify directories and misses nested copies, resulting in ~450 MB of bloat in the app bundle. More critically, different parts of Studio end up running mismatched Playground/PHP-WASM versions, which can cause subtle and hard-to-diagnose runtime failures in core site operations.
+
 ## Detailed Documentation
 
 For in-depth information, see these docs:

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

@@ -57,3 +57,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(),
 } );