[CLI] Accept Blueprint v2 modes without an experimental flag

[adamziel]

What it does

Makes --mode=create-new-site, --mode=apply-to-existing-site, and --mode=mount-only normal CLI options. An explicit mode now selects the Blueprint v2 handler without --experimental-blueprints-v2-runner.

The old hidden flag remains as a compatibility alias. start is unchanged: it continues to infer site setup from the project and does not accept --mode.

Rationale

The CLI already routes declarations with version: 2 through the v2 handler. Explicit mode selection was the remaining experimental gate: --mode was hidden, and the parser rejected it unless the experimental flag was also present.

That made the apply-to-existing and mount-only paths unavailable through the supported CLI interface.

Implementation

Explicit --mode still conflicts with --auto-mount, --wordpress-install-mode, and --skip-sqlite-setup. --no-auto-mount is allowed because it disables inference instead of competing with the selected mode.

The hidden compatibility flag still translates its old install and capability options for existing callers.

Testing instructions

npm exec -- nx run playground-cli:typecheck
npm exec -- nx run playground-cli:lint
npm exec -- nx run playground-cli:test-playground-cli --testFile=run-cli.spec.ts
npm exec -- nx run playground-cli:unbuilt-asyncify -- server --help

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Promotes Blueprint v2 --mode selection to a supported CLI option (no longer gated behind an experimental flag) while keeping the old experimental flag as a hidden compatibility alias.

Changes:

• Makes --mode a visible, documented CLI option and updates handler selection rules to treat explicit --mode as opting into the v2 handler
• Keeps --experimental-blueprints-v2-runner as a hidden compatibility alias that translates legacy install/capability options
• Updates CLI tests and README to reflect the new supported --mode behavior

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
packages/playground/cli/src/run-cli.ts	Exposes --mode, keeps experimental flag as hidden alias, and adjusts v2 handler selection logic/docs
packages/playground/cli/tests/run-cli.spec.ts	Updates/extends test coverage for --mode without experimental flag and for legacy alias behavior
packages/playground/cli/README.md	Documents --mode as a supported option and describes incompatibilities

Comments suppressed due to low confidence (2)

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

• These rejection tests now assert the error text is written to process.stdout.write, but parseOptionsAndRunCLI()’s error path in this PR’s context prints via console.error(...) (stderr), not stdout. As written, the tests may fail (or become misleading if other output happens to hit stdout). Recommendation (mandatory): assert against consoleErrorSpy (or spy on process.stderr.write) for these messages, and only use stdout if the implementation intentionally writes there.

import path from 'node:path';

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

• These rejection tests now assert the error text is written to process.stdout.write, but parseOptionsAndRunCLI()’s error path in this PR’s context prints via console.error(...) (stderr), not stdout. As written, the tests may fail (or become misleading if other output happens to hit stdout). Recommendation (mandatory): assert against consoleErrorSpy (or spy on process.stderr.write) for these messages, and only use stdout if the implementation intentionally writes there.

		test('should reject --mode with auto-mount', async () => {
			const consoleErrorSpy = vi
				.spyOn(console, 'error')
				.mockImplementation(() => {});
			const stdoutSpy = vi
				.spyOn(process.stdout, 'write')
				.mockImplementation(() => true);
			const exitSpy = vi
				.spyOn(process, 'exit')
				.mockImplementation((code?: number | string | null) => {
					throw new Error(`process.exit(${code})`);
				});

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.