Support separate web root and WordPress core directory (#217)

## Summary

On WP Cloud sites, the web root and WordPress core directory are
separate paths:

- Web root: `/srv/htdocs` (contains `wp-content/`)
- WP root: `/srv/htdocs/__wp__/` (contains `wp-load.php`,
`wp-includes/`, `wp-admin/`)

The blueprint runner previously assumed these were always the same
directory. All subprocess scripts used `DOCROOT` to find both
`wp-content/` and `wp-load.php`, which breaks on split layouts.

This PR introduces a `WP_CORE_DIR` environment variable that points to
where WordPress core files live, independent of `DOCROOT` (the web
root). On standard installs they're identical; on WP Cloud they differ.

The `ExistingSiteResolver` auto-detects the core directory by scanning
immediate subdirectories for `wp-load.php`, so existing blueprints work
without changes. A `--wp-core-path` CLI flag is also available for
explicit configuration.

## Test plan

- [ ] New unit tests for `detect_wordpress_core_dir()` (standard layout,
`__wp__/` subdirectory, custom subdirectory, no WP found, deeply nested,
nonexistent path)
- [ ] New unit tests for `RunnerConfiguration` (default fallback,
explicit override, reset to null)
- [ ] Verify existing CI tests still pass (the change is
backwards-compatible since `WP_CORE_DIR` defaults to `DOCROOT`)
- [ ] Test on a WP Cloud site with split web/core roots

Author: adamziel

components/Blueprints/SiteResolver/class-existingsiteresolver.php

@@ -24,17 +24,26 @@ public static function resolve( Runtime $runtime, Tracker $progress, ?VersionCon
 
 		// 1. Verify it's a valid WordPress installation.
 		$progress['verify_installation']->setCaption( 'Verifying WordPress installation' );
+
+		// Auto-detect the WordPress core directory. Some hosting setups place
+		// the WordPress core files (wp-load.php, wp-admin, wp-includes) in a
+		// subdirectory while wp-content stays in the web root.
 		if ( ! $target_fs->exists( 'wp-load.php' ) ) {
-			throw new BlueprintExecutionException(
-				'The target site does not appear to be a valid WordPress installation (wp-load.php not found)'
-			);
+			$detected_core_dir = self::detect_wordpress_core_dir( $config->get_target_site_root() );
+			if ( null !== $detected_core_dir ) {
+				$config->set_wordpress_core_dir( $detected_core_dir );
+			} else {
+				throw new BlueprintExecutionException(
+					'The target site does not appear to be a valid WordPress installation (wp-load.php not found)'
+				);
+			}
 		}
 
 		// Additional check to ensure we can actually load WordPress.
 		try {
 			$result = $runtime->eval_php_code_in_subprocess(
 				'<?php
-				require_once(getenv("DOCROOT") . "/wp-load.php");
+				require_once(getenv("WP_CORE_DIR") . "/wp-load.php");
 				$is_installed = function_exists("is_blog_installed") && is_blog_installed() ? "true" : "false";
 				append_output("WordPress is installed: " . $is_installed);
 				'
@@ -61,7 +70,7 @@ public static function resolve( Runtime $runtime, Tracker $progress, ?VersionCon
 				trim(
 					$runtime->eval_php_code_in_subprocess(
 						'<?php
-						require_once(getenv("DOCROOT") . "/wp-includes/version.php");
+						require_once(getenv("WP_CORE_DIR") . "/wp-includes/version.php");
 						append_output( $wp_version );
 						'
 					)->output_file_content
@@ -92,7 +101,7 @@ public static function resolve( Runtime $runtime, Tracker $progress, ?VersionCon
 		if ( 'sqlite' === $required_engine ) {
 			$sqlite_active = $runtime->eval_php_code_in_subprocess(
 				'<?php
-				require_once(getenv("DOCROOT") . "/wp-load.php");
+				require_once(getenv("WP_CORE_DIR") . "/wp-load.php");
 				
 				// Check if SQLite integration is active
 				$sqlite_plugin = WP_CONTENT_DIR . "/plugins/sqlite-database-integration/load.php";
@@ -113,7 +122,7 @@ public static function resolve( Runtime $runtime, Tracker $progress, ?VersionCon
 			// For MySQL, verify it's not using SQLite.
 			$using_mysql = $runtime->eval_php_code_in_subprocess(
 				'<?php
-				require_once(getenv("DOCROOT") . "/wp-load.php");
+				require_once(getenv("WP_CORE_DIR") . "/wp-load.php");
 				
 				// Check if SQLite integration is NOT active
 				$active_plugins = get_option("active_plugins");
@@ -139,4 +148,52 @@ public static function resolve( Runtime $runtime, Tracker $progress, ?VersionCon
 		$progress['verify_database']->finish();
 		$progress->finish();
 	}
+
+	/**
+	 * Scans the web root for a WordPress core directory. Some hosting
+	 * setups place the core files in a subdirectory while wp-content/
+	 * stays in the web root.
+	 *
+	 * @param  string $web_root Absolute path to the web root.
+	 *
+	 * @return string|null Absolute path to the WordPress core directory, or
+	 *                     null when wp-load.php cannot be found anywhere.
+	 */
+	public static function detect_wordpress_core_dir( string $web_root ): ?string {
+		// Standard layout: wp-load.php is in the web root itself.
+		if ( file_exists( $web_root . '/wp-load.php' ) ) {
+			// If wp-load.php is a symlink pointing into a subdirectory,
+			// resolve it to find the real core directory. Some hosting
+			// setups (e.g. WP Cloud) place a symlink at the web root
+			// while the actual core files live in a subdirectory like
+			// __wp__/.
+			if ( is_link( $web_root . '/wp-load.php' ) ) {
+				$real_path = realpath( $web_root . '/wp-load.php' );
+				if ( false !== $real_path ) {
+					return dirname( $real_path );
+				}
+			}
+			return $web_root;
+		}
+
+		// Scan immediate subdirectories for wp-load.php. This covers the
+		// Check immediate subdirectories for any single-level split layout.
+		$entries = @scandir( $web_root );
+		if ( false === $entries ) {
+			return null;
+		}
+
+		foreach ( $entries as $entry ) {
+			if ( '.' === $entry || '..' === $entry ) {
+				continue;
+			}
+
+			$candidate = $web_root . '/' . $entry;
+			if ( is_dir( $candidate ) && file_exists( $candidate . '/wp-load.php' ) ) {
+				return $candidate;
+			}
+		}
+
+		return null;
+	}
 }

components/Blueprints/SiteResolver/class-newsiteresolver.php

@@ -153,7 +153,7 @@ private static function is_wordpress_installed( Runtime $runtime, Tracker $progr
 		$install_check = $runtime->eval_php_code_in_subprocess(
 			<<<'PHP'
 <?php
-		$wp_load = getenv('DOCROOT') . '/wp-load.php';
+		$wp_load = getenv('WP_CORE_DIR') . '/wp-load.php';
 		if (!file_exists($wp_load)) {
 			append_output('0');
 			exit;
@@ -164,7 +164,8 @@ private static function is_wordpress_installed( Runtime $runtime, Tracker $progr
 PHP
 			,
 			array(
-				'DOCROOT' => $runtime->get_configuration()->get_target_site_root(),
+				'DOCROOT'     => $runtime->get_configuration()->get_target_site_root(),
+				'WP_CORE_DIR' => $runtime->get_configuration()->get_wordpress_core_dir(),
 			),
 			null,
 			5

components/Blueprints/Steps/class-activatepluginstep.php

@@ -15,8 +15,8 @@ class ActivatePluginStep implements StepInterface {
 <?php
 
 define( 'WP_ADMIN', true );
-require_once getenv( 'DOCROOT' ) . '/wp-load.php';
-require_once getenv( 'DOCROOT' ) . '/wp-admin/includes/plugin.php';
+require_once getenv( 'WP_CORE_DIR' ) . '/wp-load.php';
+require_once getenv( 'WP_CORE_DIR' ) . '/wp-admin/includes/plugin.php';
 
 // Set current user to admin
 set_current_user( get_users( array( 'role' => 'Administrator' ) )[0] );

components/Blueprints/Steps/class-activatethemestep.php

@@ -16,7 +16,7 @@ class ActivateThemeStep implements StepInterface {
 <?php
 
 define( 'WP_ADMIN', true );
-require_once getenv( 'DOCROOT' ) . '/wp-load.php';
+require_once getenv( 'WP_CORE_DIR' ) . '/wp-load.php';
 
 // Set current user to admin
 set_current_user( get_users( array( 'role' => 'Administrator' ) )[0] );

components/Blueprints/Steps/class-defineconstantsstep.php

@@ -430,7 +430,7 @@ function find_first_token_index( $tokens, $type, $search = null ) {
 	return null;
 }
 
-$wp_config_path = getenv( "DOCROOT" ) . "/wp-config.php";
+$wp_config_path = getenv( "WP_CORE_DIR" ) . "/wp-config.php";
 
 if ( ! file_exists( $wp_config_path ) ) {
 	error_log( "Blueprint Error: wp-config.php file not found at " . $wp_config_path );

components/Blueprints/Steps/class-enablemultisitestep.php

@@ -22,8 +22,8 @@ public function run( Runtime $runtime, Tracker $tracker ) {
  * See: https://github.com/wp-cli/core-command/blob/f157fb37dae1d13fe7318452f932917161e83e53/src/Core_Command.php#L505
  */
 
-require_once getenv( 'DOCROOT' ) . '/wp-load.php';
-require_once getenv( 'DOCROOT' ) . '/wp-admin/includes/upgrade.php';
+require_once getenv( 'WP_CORE_DIR' ) . '/wp-load.php';
+require_once getenv( 'WP_CORE_DIR' ) . '/wp-admin/includes/upgrade.php';
 
 // need to register the multisite tables manually for some reason
 foreach ( $wpdb->tables( 'ms_global' ) as $table => $prefixed_table ) {

components/Blueprints/Steps/class-importcontentstep.php

@@ -151,7 +151,7 @@ private function importPosts( Runtime $runtime, $post ): void {
 		$runtime->eval_php_code_in_subprocess(
 			<<<'PHP'
 <?php
-require_once getenv('DOCROOT') . '/wp-load.php';
+require_once getenv('WP_CORE_DIR') . '/wp-load.php';
 foreach (json_decode(getenv('POSTS'), true) as $post) {
 	$result = wp_insert_post(wp_slash($post));
 	if (is_wp_error($result)) {

components/Blueprints/Steps/class-importmediastep.php

@@ -66,7 +66,7 @@ public function run( Runtime $runtime, Tracker $progress ) {
 		$fs             = $runtime->get_target_filesystem();
 		$wp_upload_dir  = $runtime->eval_php_code_in_subprocess(
 			'<?php
-			require_once(getenv("DOCROOT") . "/wp-load.php");
+			require_once(getenv("WP_CORE_DIR") . "/wp-load.php");
 			$upload_dir = wp_upload_dir();
 			append_output( json_encode($upload_dir) );
 			'
@@ -130,8 +130,8 @@ function ( $media ) {
 				$attachment_id = $runtime->eval_php_code_in_subprocess(
 					<<<'CODE'
 <?php
-require_once(getenv("DOCROOT") . "/wp-load.php");
-require_once(getenv("DOCROOT") . "/wp-admin/includes/image.php");
+require_once(getenv("WP_CORE_DIR") . "/wp-load.php");
+require_once(getenv("WP_CORE_DIR") . "/wp-admin/includes/image.php");
 
 $file_path = getenv("MEDIA_FILE_PATH");
 $attachment_meta = json_decode(getenv("ATTACHMENT_META"), true);

components/Blueprints/Steps/class-importthemestartercontentstep.php

@@ -65,7 +65,7 @@ function importThemeStarterContent_plugins_loaded() {
                                                                                      'accepted_args' => 0,
 );
 
-require getenv( "DOCROOT" ) . '/wp-load.php';
+require getenv( "WP_CORE_DIR" ) . '/wp-load.php';
 
 // Return early if there's no starter content.
 if ( ! get_theme_starter_content() ) {

components/Blueprints/Steps/class-installpluginstep.php

@@ -105,13 +105,13 @@ function ( $temp_dir ) use ( $runtime, $tracker, $plugin_data ) {
 					<<<'PHP'
 <?php
 
-require_once getenv( 'DOCROOT' ) . '/wp-load.php';
+require_once getenv( 'WP_CORE_DIR' ) . '/wp-load.php';
 
 define( 'WP_ADMIN', true );
 
 // Define a dummy skin for the upgrader.
 if ( ! class_exists( '\WP_Upgrader_Skin', false ) ) {
-	require_once getenv( 'DOCROOT' ) . '/wp-admin/includes/class-wp-upgrader.php';
+	require_once getenv( 'WP_CORE_DIR' ) . '/wp-admin/includes/class-wp-upgrader.php';
 
 	class Blueprint_WP_Upgrader_Skin extends WP_Upgrader_Skin {
 		public $destination;
@@ -186,11 +186,11 @@ public function after( $title = '' ) {
 	}
 }
 
-require_once getenv( 'DOCROOT' ) . '/wp-load.php';
-require_once getenv( 'DOCROOT' ) . '/wp-admin/includes/plugin.php';
-require_once getenv( 'DOCROOT' ) . '/wp-admin/includes/file.php';
-require_once getenv( 'DOCROOT' ) . '/wp-admin/includes/plugin-install.php';
-require_once getenv( 'DOCROOT' ) . '/wp-admin/includes/class-wp-upgrader.php';
+require_once getenv( 'WP_CORE_DIR' ) . '/wp-load.php';
+require_once getenv( 'WP_CORE_DIR' ) . '/wp-admin/includes/plugin.php';
+require_once getenv( 'WP_CORE_DIR' ) . '/wp-admin/includes/file.php';
+require_once getenv( 'WP_CORE_DIR' ) . '/wp-admin/includes/plugin-install.php';
+require_once getenv( 'WP_CORE_DIR' ) . '/wp-admin/includes/class-wp-upgrader.php';
 
 // Ensure filesystem access is properly set up
 WP_Filesystem();