[Blueprints] Remove v2 experimental compatibility aliases

packages/playground/cli/src/mounts.ts

@@ -144,17 +144,10 @@ export function expandAutoMounts(args: RunCLIArgs): RunCLIArgs {
 			vfsPath,
 			autoMounted: true,
 		});
-		newArgs['additional-blueprint-steps'].push(
-			args['experimental-blueprints-v2-runner']
-				? {
-						step: 'activateTheme',
-						themeDirectoryName: themeName,
-					}
-				: {
-						step: 'activateTheme',
-						themeFolderName: themeName,
-					}
-		);
+		newArgs['additional-blueprint-steps'].push({
+			step: 'activateTheme',
+			themeFolderName: themeName,
+		});
 	} else if (containsWpContentDirectories(path)) {
 		/**
 		 * Mount each wp-content file and directory individually.

packages/playground/cli/src/run-cli.ts

@@ -327,14 +327,6 @@ export async function parseOptionsAndRunCLI(argsToParse: string[]) {
 				coerce: (value?: string) =>
 					value === '' ? ['vscode', 'phpstorm'] : [value],
 			},
-			'experimental-blueprints-v2-runner': {
-				describe:
-					'Compatibility alias for selecting the Blueprint v2 handler.',
-				type: 'boolean',
-				default: false,
-				// Keep the old opt-in available without advertising it to new callers.
-				hidden: true,
-			},
 			mode: {
 				describe:
 					'Choose whether Blueprint v2 creates a site, applies to an existing site, or only mounts files.',
@@ -634,37 +626,6 @@ export async function parseOptionsAndRunCLI(argsToParse: string[]) {
 					(arg) => arg === '--mode' || arg.startsWith('--mode=')
 				);
 
-				if (args['experimental-blueprints-v2-runner'] === true) {
-					if (args['mode'] === undefined) {
-						// Translate the v1-style install option for callers still
-						// using the legacy v2 handler flag. The old option family
-						// had two modes; `mount-only` maps directly to its "do not
-						// install WordPress" worker behavior.
-						if (
-							args['wordpress-install-mode'] ===
-							'do-not-attempt-installing'
-						) {
-							args['mode'] = 'mount-only';
-						} else {
-							args['mode'] = 'create-new-site';
-						}
-					}
-
-					// Translate v1-style capability flags for the compatibility
-					// alias.
-					const allow = (args['allow'] as string[]) || [];
-
-					if (args['followSymlinks'] === true) {
-						allow.push('follow-symlinks');
-					}
-
-					if (args['blueprint-may-read-adjacent-files'] === true) {
-						allow.push('read-local-fs');
-					}
-
-					args['allow'] = allow;
-				}
-
 				args['hasExplicitBlueprintsV2Mode'] =
 					hasExplicitBlueprintsV2Mode;
 
@@ -862,7 +823,6 @@ export interface RunCLIArgs {
 	phpExtension?: string[];
 	experimentalUnsafeIdeIntegration?: string[];
 	experimentalDevtools?: boolean;
-	'experimental-blueprints-v2-runner'?: boolean;
 	workers?: number | 'auto';
 	'experimental-multi-worker'?: number;
 	wordpressInstallMode?: WordPressInstallMode;
@@ -1788,8 +1748,7 @@ export async function runCLI(args: RunCLIArgs): Promise<RunCLIServer | void> {
  * Selects the native Blueprint v2 CLI path.
  *
  * The default CLI path remains the v1 handler. We switch to v2 only when the
- * caller passes `--mode`, uses the legacy compatibility flag, or provides a
- * resolved Blueprint v2 declaration.
+ * caller passes `--mode` or provides a resolved Blueprint v2 declaration.
  *
  * `hasExplicitBlueprintsV2Mode` must be captured before `start` or auto-mount
  * expansion because full WordPress auto-mounts still set
@@ -1803,9 +1762,6 @@ async function shouldUseBlueprintsV2Handler(
 	args: RunCLIArgs,
 	hasExplicitBlueprintsV2Mode: boolean
 ) {
-	if (args['experimental-blueprints-v2-runner']) {
-		return true;
-	}
 	if (hasExplicitBlueprintsV2Mode) {
 		return true;
 	}

packages/playground/cli/tests/mounts.spec.ts

@@ -65,22 +65,6 @@ describe('expandAutoMounts', () => {
 			]);
 		});
 
-		test('should use themeDirectoryName for v2 runner', () => {
-			const themePath = path.join(__dirname, 'mount-examples/theme');
-			const args: RunCLIArgs = {
-				...createBasicArgs(themePath),
-				'experimental-blueprints-v2-runner': true,
-			};
-			const result = expandAutoMounts(args);
-
-			expect(result['additional-blueprint-steps']).toEqual([
-				{
-					step: 'activateTheme',
-					themeDirectoryName: 'theme',
-				},
-			]);
-		});
-
 		test('should not mount non-theme directory as theme', () => {
 			const notThemePath = path.join(
 				__dirname,

packages/playground/cli/tests/run-cli.spec.ts

@@ -286,32 +286,30 @@ describe.each(blueprintVersions)(
 			}
 		});
 
-		test('should keep the experimental v2 flag as a compatibility alias', async () => {
-			const exitSpy = vi.spyOn(process, 'exit').mockImplementation(((
-				code?: number | string | null
-			) => {
-				throw new Error(
-					`process.exit unexpectedly called with "${code}"`
-				);
+		test('should reject the retired experimental v2 flag', async () => {
+			const exitSpy = vi
+				.spyOn(process, 'exit')
+				.mockImplementation((() => undefined) as any);
+			// The yargs exit is caught by parseOptionsAndRunCLI(), which exits
+			// again. Throw only once so the outer exit can return to the test.
+			exitSpy.mockImplementationOnce((() => {
+				throw new Error('Stop after the yargs failure');
 			}) as any);
+			const consoleErrorSpy = vi
+				.spyOn(console, 'error')
+				.mockImplementation(() => {});
 
 			try {
-				await using cliResult = await parseOptionsAndRunCLI([
+				await parseOptionsAndRunCLI([
 					'server',
 					'--experimental-blueprints-v2-runner',
-					'--wordpress-install-mode=do-not-attempt-installing',
-					'--verbosity=quiet',
-					'--port=0',
-					'--workers=1',
 				]);
-				const cliServer = cliResult[internalsKeyForTesting].cliServer;
-
-				expect(
-					await cliServer.playground.fileExists(
-						'/wordpress/wp-load.php'
-					)
-				).toBe(false);
+				expect(exitSpy).toHaveBeenCalledWith(1);
+				expect(consoleErrorSpy).toHaveBeenCalledWith(
+					expect.stringContaining('experimental-blueprints-v2-runner')
+				);
 			} finally {
+				consoleErrorSpy.mockRestore();
 				exitSpy.mockRestore();
 			}
 		});

packages/playground/personal-wp/src/lib/state/url/landing-page.spec.ts

@@ -33,13 +33,13 @@ describe('getBrowserPathAsLandingPage', () => {
 		).toBeUndefined();
 	});
 
-	it('strips the retired Blueprint v2 opt-in from legacy URLs', () => {
+	it('treats the retired Blueprint v2 opt-in as a WordPress query param', () => {
 		expect(
 			getBrowserPathAsLandingPage({
 				pathname: getAppBaseUrl().pathname,
 				search: '?experimental-blueprints-v2-runner=yes',
 			})
-		).toBeUndefined();
+		).toBe('/?experimental-blueprints-v2-runner=yes');
 	});
 
 	it('preserves all search params on reflected WordPress paths', () => {

packages/playground/personal-wp/src/lib/state/url/router.ts

@@ -53,8 +53,6 @@ export const PLAYGROUND_QUERY_KEYS = [
 	'import-content',
 	'page-title',
 	HEALTH_CHECK_RECOVERY_MODE_QUERY_PARAM,
-	// Retain the retired v2 opt-in so it is stripped from legacy URLs.
-	'experimental-blueprints-v2-runner',
 ];
 
 /**

packages/playground/remote/src/lib/playground-worker-endpoint.ts

@@ -84,8 +84,6 @@ export type WorkerBootOptions = {
 	/** @deprecated Use `wordpressInstallMode` instead. */
 	shouldInstallWordPress?: boolean;
 	corsProxyUrl?: string;
-	/** @deprecated Blueprint handlers are selected before boot. This option has no effect. */
-	experimentalBlueprintsV2Runner?: boolean;
 	/** Blueprint v2 declaration used for worker-side execution or preflight checks. */
 	blueprint?: BlueprintDeclaration;
 	/**