Remove legacy mu-plugin files from site directories on server start (#2655)

Sites created with older Studio versions (e.g June 2024) have physical `0-*.php` mu-plugin files in `wp-content/mu-plugins/`. Newer Studio versions inject the same mu-plugins at runtime via the PHP WASM virtual filesystem (`/internal/studio/mu-plugins/`). When both copies exist, PHP encounters fatal errors like `Cannot redeclare check_current_theme_availability()`.

This PR adds a `cleanupLegacyMuPlugins()` function that removes known legacy Studio mu-plugin files from the site's `wp-content/mu-plugins/` directory before starting the WordPress server or running WP-CLI commands.

Author: sejas

apps/cli/lib/run-wp-cli-command.ts

@@ -7,7 +7,7 @@ import {
 	setPhpIniEntries,
 } from '@php-wasm/universal';
 import { createSpawnHandler } from '@php-wasm/util';
-import { getMuPlugins } from '@studio/common/lib/mu-plugins';
+import { cleanupLegacyMuPlugins, getMuPlugins } from '@studio/common/lib/mu-plugins';
 import { LatestSupportedPHPVersion } from '@studio/common/types/php-versions';
 import { __ } from '@wordpress/i18n';
 import { setupPlatformLevelMuPlugins } from '@wp-playground/wordpress';
@@ -67,6 +67,8 @@ export async function runWpCliCommand(
 
 		await php.setSpawnHandler( createNoopSpawnHandler() );
 
+		await cleanupLegacyMuPlugins( siteFolder );
+
 		// Mount mu-plugins
 		const [ studioMuPluginsHostPath, loaderMuPluginHostPath ] = await getMuPlugins( {
 			isWpAutoUpdating: false,

apps/cli/wordpress-server-child.ts

@@ -13,7 +13,7 @@
 import { dirname } from 'path';
 import { DEFAULT_PHP_VERSION } from '@studio/common/constants';
 import { isWordPressDirectory } from '@studio/common/lib/fs-utils';
-import { getMuPlugins } from '@studio/common/lib/mu-plugins';
+import { cleanupLegacyMuPlugins, getMuPlugins } from '@studio/common/lib/mu-plugins';
 import { decodePassword } from '@studio/common/lib/passwords';
 import { formatPlaygroundCliMessage } from '@studio/common/lib/playground-cli-messages';
 import { sequential } from '@studio/common/lib/sequential';
@@ -139,6 +139,8 @@ async function getBaseRunCLIArgs(
 ): Promise< RunCLIArgs > {
 	const wordpressInstallMode = await getWordPressInstallMode( config.sitePath );
 
+	await cleanupLegacyMuPlugins( config.sitePath );
+
 	const [ studioMuPluginsHostPath, loaderMuPluginHostPath ] = await getMuPlugins( {
 		isWpAutoUpdating: config.isWpAutoUpdating,
 	} );

tools/common/lib/mu-plugins.ts

@@ -5,7 +5,7 @@
  * available to WordPress instances. Shared between desktop app and CLI.
  */
 
-import { mkdtemp, writeFile } from 'fs/promises';
+import { mkdtemp, readdir, unlink, writeFile } from 'fs/promises';
 import { tmpdir } from 'os';
 import { join } from 'path';
 
@@ -521,3 +521,71 @@ export async function getMuPlugins( options: MuPluginOptions ) {
 
 	return [ studioMuPluginsHostPath, loaderMuPluginHostPath ];
 }
+
+/**
+ * Legacy mu-plugin filenames that older Studio versions wrote directly into
+ * wp-content/mu-plugins/. Newer versions inject these at runtime via the
+ * PHP WASM virtual filesystem, so on-disk copies cause "Cannot redeclare"
+ * PHP fatal errors. This list includes both current and retired filenames.
+ */
+const LEGACY_MU_PLUGIN_FILENAMES = [
+	// Current mu-plugins (from getStandardMuPlugins)
+	'0-allowed-redirect-hosts.php',
+	'0-auto-login.php',
+	'0-check-theme-availability.php',
+	'0-deactivate-jetpack-modules.php',
+	'0-disable-auto-updates.php',
+	'0-enable-auto-updates.php',
+	'0-http-request-timeout.php',
+	'0-https-for-reverse-proxy.php',
+	'0-permalinks.php',
+	'0-redirect-to-siteurl-constant.php',
+	'0-sqlite-command.php',
+	'0-studio-admin-api.php',
+	'0-studio-cli-commands.php',
+	'0-suppress-dns-get-record-warnings.php',
+	'0-thumbnails.php',
+	'0-tmp-fix-hide-plugins-spinner.php',
+	'0-tmp-fix-qm-plugin-sapi.php',
+	'0-wp-admin-trailing-slash.php',
+	// Retired mu-plugins from older Studio versions
+	'0-32bit-integer-warnings.php',
+	'0-dns-functions.php',
+	'0-sqlite.php',
+	'0-wp-config-constants-polyfill.php',
+];
+
+/**
+ * Remove legacy Studio mu-plugin files from a site's wp-content/mu-plugins/ directory.
+ *
+ * Older Studio versions wrote mu-plugin PHP files directly into the site directory.
+ * Newer versions inject them at runtime via the PHP WASM virtual filesystem.
+ * Having both copies causes PHP fatal errors like "Cannot redeclare" because
+ * the same functions are defined in both the on-disk file and the runtime-injected file.
+ *
+ * @param sitePath - Absolute path to the WordPress site directory
+ */
+export async function cleanupLegacyMuPlugins( sitePath: string ): Promise< void > {
+	const muPluginsDir = join( sitePath, 'wp-content', 'mu-plugins' );
+
+	let entries: string[];
+	try {
+		entries = await readdir( muPluginsDir );
+	} catch {
+		// Directory doesn't exist or can't be read – nothing to clean up
+		return;
+	}
+
+	const legacySet = new Set( LEGACY_MU_PLUGIN_FILENAMES );
+	const filesToRemove = entries.filter( ( name ) => legacySet.has( name ) );
+
+	await Promise.all(
+		filesToRemove.map( async ( name ) => {
+			try {
+				await unlink( join( muPluginsDir, name ) );
+			} catch {
+				// Best-effort: file may already be gone or locked
+			}
+		} )
+	);
+}

tools/common/lib/tests/mu-plugins.test.ts

@@ -0,0 +1,86 @@
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { mkdtemp, readdir } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { cleanupLegacyMuPlugins } from '@studio/common/lib/mu-plugins';
+
+describe( 'cleanupLegacyMuPlugins', () => {
+	let sitePath: string;
+
+	beforeEach( async () => {
+		sitePath = await mkdtemp( join( tmpdir(), 'studio-test-site-' ) );
+	} );
+
+	it( 'should remove legacy Studio mu-plugin files', async () => {
+		const muPluginsDir = join( sitePath, 'wp-content', 'mu-plugins' );
+		mkdirSync( muPluginsDir, { recursive: true } );
+
+		// Create legacy files that should be removed
+		const legacyFiles = [
+			'0-allowed-redirect-hosts.php',
+			'0-check-theme-availability.php',
+			'0-permalinks.php',
+			'0-thumbnails.php',
+			'0-sqlite.php',
+			'0-dns-functions.php',
+			'0-32bit-integer-warnings.php',
+		];
+		for ( const file of legacyFiles ) {
+			writeFileSync( join( muPluginsDir, file ), '<?php // legacy' );
+		}
+
+		await cleanupLegacyMuPlugins( sitePath );
+
+		for ( const file of legacyFiles ) {
+			expect( existsSync( join( muPluginsDir, file ) ) ).toBe( false );
+		}
+	} );
+
+	it( 'should not remove non-Studio mu-plugin files', async () => {
+		const muPluginsDir = join( sitePath, 'wp-content', 'mu-plugins' );
+		mkdirSync( muPluginsDir, { recursive: true } );
+
+		// Create a user mu-plugin that should NOT be removed
+		const userPlugin = 'my-custom-plugin.php';
+		writeFileSync( join( muPluginsDir, userPlugin ), '<?php // user plugin' );
+
+		// Also create a legacy file to verify selective removal
+		writeFileSync( join( muPluginsDir, '0-check-theme-availability.php' ), '<?php // legacy' );
+
+		await cleanupLegacyMuPlugins( sitePath );
+
+		expect( existsSync( join( muPluginsDir, userPlugin ) ) ).toBe( true );
+		expect( existsSync( join( muPluginsDir, '0-check-theme-availability.php' ) ) ).toBe( false );
+	} );
+
+	it( 'should handle missing wp-content/mu-plugins directory gracefully', async () => {
+		// sitePath exists but wp-content/mu-plugins does not
+		await expect( cleanupLegacyMuPlugins( sitePath ) ).resolves.toBeUndefined();
+	} );
+
+	it( 'should handle missing site path gracefully', async () => {
+		await expect( cleanupLegacyMuPlugins( '/nonexistent/path/to/site' ) ).resolves.toBeUndefined();
+	} );
+
+	it( 'should not remove sqlite-database-integration directory', async () => {
+		const muPluginsDir = join( sitePath, 'wp-content', 'mu-plugins' );
+		const sqliteDir = join( muPluginsDir, 'sqlite-database-integration' );
+		mkdirSync( sqliteDir, { recursive: true } );
+		writeFileSync( join( sqliteDir, 'load.php' ), '<?php // sqlite integration' );
+
+		await cleanupLegacyMuPlugins( sitePath );
+
+		expect( existsSync( sqliteDir ) ).toBe( true );
+		expect( existsSync( join( sqliteDir, 'load.php' ) ) ).toBe( true );
+	} );
+
+	it( 'should handle empty mu-plugins directory', async () => {
+		const muPluginsDir = join( sitePath, 'wp-content', 'mu-plugins' );
+		mkdirSync( muPluginsDir, { recursive: true } );
+
+		await cleanupLegacyMuPlugins( sitePath );
+
+		const remaining = await readdir( muPluginsDir );
+		expect( remaining ).toHaveLength( 0 );
+	} );
+} );