fix(migrate): pin browser-provider framework peers instead of writing *

When migration keeps an opt-in browser provider (@vitest/browser-playwright /
@vitest/browser-webdriverio) and adds its runtime framework peer, it wrote
`playwright`/`webdriverio` as `*` (non-deterministic). Reuse a declared lockstep
sibling's version instead (e.g. @playwright/test for playwright), resolving a
`catalog:` sibling to its concrete value, referencing the catalog when it
already owns the peer, and falling back to `*` only when nothing resolves
(npmx.dev #27).

Also extracts a shared findDeclaredSpec helper (the four-field dependency scan)
and drops an unreachable peer branch in the REMOVE_PACKAGES loop.

Claude-Session: https://claude.ai/code/session_01DQhS6o1fyQd1yjiee6W8jR

Author: fengmk2

packages/cli/src/migration/__tests__/migrator.spec.ts

@@ -584,6 +584,21 @@ describe('rewritePackageJson', () => {
     expect(pkg.devDependencies).not.toHaveProperty('@vitest/browser');
   });
 
+  it('pins the provider framework peer to a lockstep sibling instead of * (npmx.dev #27)', () => {
+    // `playwright` and `@playwright/test` release in lockstep, so a newly-added
+    // `playwright` peer should reuse the pinned @playwright/test version rather
+    // than a non-deterministic `*`.
+    const pkg = {
+      devDependencies: {
+        '@vitest/browser-playwright': '^4.0.0',
+        '@playwright/test': '1.60.0',
+        vitest: '^4.0.0',
+      },
+    };
+    rewritePackageJson(pkg, PackageManager.pnpm);
+    expect(pkg.devDependencies).toHaveProperty('playwright', '1.60.0');
+  });
+
   it('injects a direct vite devDependency for an npm project that uses an opt-in browser provider', async () => {
     // npm's flat node_modules cannot dedupe the provider's own
     // `@vitest/browser → @vitest/mocker` subtree against the one vite-plus

packages/cli/src/migration/migrator/package-json.ts

@@ -23,6 +23,8 @@ import {
 } from '../migrator.ts';
 import {
   BROWSER_PROVIDER_PEER_DEPS,
+  findDeclaredSpec,
+  resolveProviderPeerSpec,
   OPT_IN_BROWSER_PROVIDERS,
   REMOVE_PACKAGES,
   VITEST_BROWSER_DEP_NAMES,
@@ -192,19 +194,6 @@ export function rewritePackageJson(
     if (wasRemoved) {
       needVitePlus = true;
     }
-    // e.g., removing @vitest/browser-playwright should keep `playwright` in devDeps
-    const peerDep = BROWSER_PROVIDER_PEER_DEPS[name];
-    if (
-      wasRemoved &&
-      peerDep &&
-      !pkg.devDependencies?.[peerDep] &&
-      !pkg.dependencies?.[peerDep] &&
-      !pkg.peerDependencies?.[peerDep] &&
-      !pkg.optionalDependencies?.[peerDep]
-    ) {
-      pkg.devDependencies ??= {};
-      pkg.devDependencies[peerDep] = '*';
-    }
   }
   // The browser providers (webdriverio, playwright) are opt-in: vite-plus no
   // longer bundles them at runtime (each drags a heavy non-optional framework
@@ -262,14 +251,15 @@ export function rewritePackageJson(
       );
     }
     const peer = BROWSER_PROVIDER_PEER_DEPS[provider]; // 'webdriverio' / 'playwright'
-    const peerPresent =
-      pkg.dependencies?.[peer] ??
-      pkg.devDependencies?.[peer] ??
-      pkg.peerDependencies?.[peer] ??
-      pkg.optionalDependencies?.[peer];
+    const peerPresent = findDeclaredSpec(pkg, peer);
     if (peer && !peerPresent) {
       pkg.devDependencies ??= {};
-      pkg.devDependencies[peer] = '*';
+      pkg.devDependencies[peer] = resolveProviderPeerSpec(
+        pkg,
+        peer,
+        supportCatalog,
+        catalogDependencyResolver,
+      );
     }
     needVitePlus = true;
   }

packages/cli/src/migration/migrator/shared.ts

@@ -82,6 +82,51 @@ export const BROWSER_PROVIDER_PEER_DEPS: Record<string, string> = {
   '@vitest/browser-webdriverio': 'webdriverio',
 };
 
+// Lockstep sibling packages whose declared version a browser provider's runtime
+// framework peer should reuse (they publish together). Keyed by the peer name.
+export const PROVIDER_PEER_VERSION_SIBLINGS: Record<string, readonly string[]> = {
+  playwright: ['@playwright/test'],
+  webdriverio: ['@wdio/cli', '@wdio/globals'],
+};
+
+// A package's declared spec across all four dependency fields, or undefined.
+export function findDeclaredSpec(pkg: DependencyBag, name: string): string | undefined {
+  return (
+    pkg.dependencies?.[name] ??
+    pkg.devDependencies?.[name] ??
+    pkg.peerDependencies?.[name] ??
+    pkg.optionalDependencies?.[name]
+  );
+}
+
+// A deterministic spec for a browser provider's framework peer instead of `*`:
+// reference the catalog when it already owns the peer, otherwise reuse a declared
+// lockstep sibling's version (concrete, or a catalog reference resolved to its
+// concrete value), falling back to `*` only when there is no sibling. See
+// npmx.dev #27.
+export function resolveProviderPeerSpec(
+  pkg: DependencyBag,
+  peer: string,
+  supportCatalog: boolean,
+  catalogDependencyResolver?: CatalogDependencyResolver,
+): string {
+  if (supportCatalog && catalogDependencyResolver?.('catalog:', peer) !== undefined) {
+    return 'catalog:';
+  }
+  for (const sibling of PROVIDER_PEER_VERSION_SIBLINGS[peer] ?? []) {
+    const spec = findDeclaredSpec(pkg, sibling);
+    const resolved = spec?.startsWith('catalog:')
+      ? catalogDependencyResolver?.(spec, sibling)
+      : spec;
+    // Only reuse a concrete version: a `catalog:` entry may itself alias another
+    // protocol, and npm:/workspace:/file: specs aren't versions to copy.
+    if (resolved && !resolved.includes(':')) {
+      return resolved;
+    }
+  }
+  return '*';
+}
+
 // Browser-provider package names that, when present in the user's deps
 // before migration, signal vitest browser mode even if no source file
 // imports them. This covers config-only browser-mode setups (e.g.

packages/cli/src/migration/migrator/vite-plus-bootstrap.ts

@@ -55,6 +55,7 @@ import {
 import { type DependencyVersionChange, type MigrationReport } from '../report.ts';
 import {
   BROWSER_PROVIDER_PEER_DEPS,
+  resolveProviderPeerSpec,
   OPT_IN_BROWSER_PROVIDERS,
   REMOVE_PACKAGES,
   VITEST_IS_MANAGED_OVERRIDE,
@@ -387,7 +388,12 @@ function reconcileVitePlusBootstrapPackage(
     );
     if (frameworkPeer && !frameworkPresent) {
       pkg.devDependencies ??= {};
-      pkg.devDependencies[frameworkPeer] = '*';
+      pkg.devDependencies[frameworkPeer] = resolveProviderPeerSpec(
+        pkg,
+        frameworkPeer,
+        supportCatalog,
+        catalogDependencyResolver,
+      );
     }
   }