Add post-runtime browser blueprint steps (#1747)

Author: chubes4

packages/wordpress-plugin/src/trait-wp-codebox-abilities-browser-blueprint.php

@@ -46,6 +46,24 @@ private static function browser_blueprint_with_site_artifact( array $blueprint,
 	return $merged;
 }
 
+/** @param array<string,mixed> $blueprint Runtime-materialized blueprint. @param array<string,mixed> $post_runtime_blueprint Caller steps that must run after runtime dependencies. @return array<string,mixed> */
+private static function browser_blueprint_with_post_runtime( array $blueprint, array $post_runtime_blueprint ): array {
+	if ( empty( $post_runtime_blueprint ) ) {
+		return $blueprint;
+	}
+
+	$steps      = is_array( $blueprint['steps'] ?? null ) ? $blueprint['steps'] : array();
+	$post_steps = is_array( $post_runtime_blueprint['steps'] ?? null ) ? $post_runtime_blueprint['steps'] : array();
+	$merged     = array_merge( $blueprint, $post_runtime_blueprint );
+	$merged['steps'] = array_values( array_merge( $steps, $post_steps ) );
+
+	if ( isset( $blueprint['features'] ) && isset( $post_runtime_blueprint['features'] ) && is_array( $blueprint['features'] ) && is_array( $post_runtime_blueprint['features'] ) ) {
+		$merged['features'] = array_merge( $blueprint['features'], $post_runtime_blueprint['features'] );
+	}
+
+	return $merged;
+}
+
 /** @param array<string,mixed> $blueprint Blueprint override. @param array<string,mixed> $runtime Runtime dependency specs. @return array<string,mixed> */
 private static function browser_blueprint_with_runtime( array $blueprint, array $runtime, array $playground = array() ): array {
 	$steps = is_array( $blueprint['steps'] ?? null ) ? $blueprint['steps'] : array();

packages/wordpress-plugin/src/trait-wp-codebox-abilities-execution.php

@@ -188,6 +188,7 @@ public static function create_browser_playground_session( array $input ): array|
 
 	$base_blueprint = self::browser_blueprint_with_site_artifact( is_array( $input['blueprint'] ?? null ) ? $input['blueprint'] : array(), $site_blueprint_artifact );
 	$blueprint      = self::browser_blueprint_with_runtime( $base_blueprint, $runtime, $playground );
+	$blueprint      = self::browser_blueprint_with_post_runtime( $blueprint, is_array( $input['post_runtime_blueprint'] ?? null ) ? $input['post_runtime_blueprint'] : array() );
 	$prepared_runtime = self::browser_prepared_runtime_with_blueprints( is_array( $runtime['prepared_runtime'] ?? null ) ? $runtime['prepared_runtime'] : array(), $blueprint, $playground );
 	$runtime['prepared_runtime'] = $prepared_runtime;
 	$contained_site  = self::browser_contained_site_envelope( $input, $session_id, $playground, $runtime, $prepared_runtime, 'ready' );

packages/wordpress-plugin/src/trait-wp-codebox-abilities-schemas.php

@@ -755,6 +755,7 @@ private static function wordpress_workload_run_request_schema(): array {
 			'schema'               => array( 'type' => 'string', 'const' => 'wp-codebox/wordpress-workload-run/v1' ),
 			'wordpress_version'    => self::string_property_schema( 'WordPress version requested for the disposable Playground workload.' ),
 			'blueprint'            => self::object_property_schema( 'Optional WordPress Playground blueprint object.' ),
+			'post_runtime_blueprint' => self::object_property_schema( 'Optional WordPress Playground blueprint steps to run after runtime dependencies are materialized.' ),
 			'preview'              => self::object_property_schema( 'Optional preview settings for the workload.' ),
 			'mounts'               => self::mount_schema(),
 			'runtime_stack_mounts' => self::object_array_property_schema( 'Runtime stack mounts for the disposable workload.' ),
@@ -1041,6 +1042,7 @@ private static function browser_task_input_properties( array $task_input_schema,
 		'runtime_profile'        => self::object_property_schema( $detailed ? 'Portable wp-codebox/runtime-profile/v1 descriptor normalized into browser runtime fields before session creation.' : '' ),
 		'runtime'                 => $detailed ? self::browser_runtime_input_schema() : self::object_property_schema(),
 		'blueprint'               => self::object_property_schema( $detailed ? 'Optional WordPress Playground blueprint for the browser to compile and run.' : '' ),
+		'post_runtime_blueprint'  => self::object_property_schema( $detailed ? 'Optional WordPress Playground blueprint steps to run after runtime dependencies are materialized.' : '' ),
 		'site_blueprint_artifact' => $detailed ? self::site_blueprint_artifact_input_schema() : self::object_property_schema(),
 		'artifact_files'          => $detailed ? self::artifact_files_input_schema() : array( 'type' => 'array' ),
 		'debug'                   => array(

scripts/php-browser-post-runtime-blueprint-smoke.php

@@ -0,0 +1,46 @@
+<?php
+
+define( 'ABSPATH', __DIR__ );
+
+require_once __DIR__ . '/../packages/wordpress-plugin/src/trait-wp-codebox-abilities-browser-blueprint.php';
+
+final class WP_Codebox_Post_Runtime_Blueprint_Smoke {
+	use WP_Codebox_Abilities_Browser_Blueprint;
+
+	/** @param array<string,mixed> $blueprint @param array<string,mixed> $post_runtime @return array<string,mixed> */
+	public static function merge( array $blueprint, array $post_runtime ): array {
+		$method = new ReflectionMethod( self::class, 'browser_blueprint_with_post_runtime' );
+		return $method->invoke( null, $blueprint, $post_runtime );
+	}
+}
+
+$runtime_blueprint = array(
+	'preferredVersions' => array( 'php' => '8.3' ),
+	'features'          => array( 'networking' => false ),
+	'steps'             => array(
+		array( 'step' => 'login' ),
+		array( 'step' => 'installPlugin', 'pluginData' => array( 'url' => 'runtime.zip' ) ),
+	),
+);
+$post_runtime = array(
+	'features' => array( 'networking' => true ),
+	'steps'    => array( array( 'step' => 'runPHP', 'code' => '<?php import_site();' ) ),
+);
+
+$merged = WP_Codebox_Post_Runtime_Blueprint_Smoke::merge( $runtime_blueprint, $post_runtime );
+$steps  = array_column( $merged['steps'] ?? array(), 'step' );
+
+if ( array( 'login', 'installPlugin', 'runPHP' ) !== $steps ) {
+	fwrite( STDERR, 'Post-runtime blueprint steps were not appended after runtime materialization.' . PHP_EOL );
+	exit( 1 );
+}
+if ( true !== ( $merged['features']['networking'] ?? null ) ) {
+	fwrite( STDERR, 'Post-runtime blueprint features did not override the base feature.' . PHP_EOL );
+	exit( 1 );
+}
+if ( $runtime_blueprint !== WP_Codebox_Post_Runtime_Blueprint_Smoke::merge( $runtime_blueprint, array() ) ) {
+	fwrite( STDERR, 'Empty post-runtime blueprint should preserve the runtime blueprint.' . PHP_EOL );
+	exit( 1 );
+}
+
+fwrite( STDOUT, 'OK: post-runtime blueprint ordering smoke passed.' . PHP_EOL );