feat(cli): add VITE_PLUS_FORCE_MIGRATE env var for force migration

When VITE_PLUS_FORCE_MIGRATE=1 is set, vp migrate forces full
dependency rewriting even for projects already using vite-plus.
This replaces the fragile hack logic in patch-project.ts that
manually removed/re-added vite-plus and patched pnpm overrides.

Now patch-project.ts simply sets the env var for projects with
forceFreshMigration configured, and vp migrate handles everything
correctly including pnpm.overrides in package.json.

Author: fengmk2

.claude/skills/add-ecosystem-ci/SKILL.md

@@ -27,7 +27,7 @@ Fetch the repository's root to check if the main package.json is in a subdirecto
 
 ### 2.2 Check if Project Already Uses Vite-Plus
 
-Check the project's root `package.json` for `vite-plus` in `dependencies` or `devDependencies`. If the project already uses vite-plus, set `forceFreshMigration: true` in `repo.json`. This is required because `patch-project.ts` runs `vp migrate` with locally built tgz overrides — without this flag, `vp migrate` detects "already using Vite+" and skips override injection, so the e2e test wouldn't actually test the locally built packages.
+Check the project's root `package.json` for `vite-plus` in `dependencies` or `devDependencies`. If the project already uses vite-plus, set `forceFreshMigration: true` in `repo.json`. This tells `patch-project.ts` to set `VITE_PLUS_FORCE_MIGRATE=1` so `vp migrate` forces full dependency rewriting instead of skipping with "already using Vite+".
 
 ### 2.3 Auto-detect Commands from GitHub Workflows
 
@@ -115,5 +115,5 @@ node ecosystem-ci/clone.ts project-name
 - The `directory` field is optional - only add it if the package.json is not in the project root
 - If `directory` is specified in repo.json, it must also be specified in the workflow matrix
 - `patch-project.ts` automatically handles running `vp migrate` in the correct directory
-- `forceFreshMigration` is required for projects that already have `vite-plus` in their package.json — it removes the existing dependency before migration so the locally built tgz overrides get injected
+- `forceFreshMigration` is required for projects that already have `vite-plus` in their package.json — it sets `VITE_PLUS_FORCE_MIGRATE=1` so `vp migrate` forces full dependency rewriting instead of skipping
 - OS exclusions are added to the existing `exclude` section in the workflow matrix

ecosystem-ci/patch-project.ts

@@ -1,5 +1,4 @@
 import { execSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
@@ -22,67 +21,6 @@ const cwd = directory ? join(repoRoot, directory) : repoRoot;
 // run vp migrate
 const cli = process.env.VITE_PLUS_CLI_BIN ?? 'vp';
 
-const tgzPaths = {
-  vite: `file:${tgzDir}/voidzero-dev-vite-plus-core-0.0.0.tgz`,
-  vitest: `file:${tgzDir}/voidzero-dev-vite-plus-test-0.0.0.tgz`,
-  'vite-plus': `file:${tgzDir}/vite-plus-0.0.0.tgz`,
-  '@voidzero-dev/vite-plus-core': `file:${tgzDir}/voidzero-dev-vite-plus-core-0.0.0.tgz`,
-  '@voidzero-dev/vite-plus-test': `file:${tgzDir}/voidzero-dev-vite-plus-test-0.0.0.tgz`,
-};
-
-// Projects that already have vite-plus need it removed before migration so
-// vp migrate treats them as fresh and applies tgz overrides. Without this,
-// vp migrate detects "already using Vite+" and skips override injection.
-const forceFreshMigration = 'forceFreshMigration' in repoConfig && repoConfig.forceFreshMigration;
-if (forceFreshMigration) {
-  const pkgPath = join(cwd, 'package.json');
-  const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'));
-  delete pkg.devDependencies?.['vite-plus'];
-  delete pkg.dependencies?.['vite-plus'];
-
-  await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
-
-  // Also update pnpm-workspace.yaml overrides for projects that don't have
-  // pnpm.overrides in package.json (pnpm-workspace.yaml overrides are only
-  // used when package.json has no overrides).
-  const workspaceYamlPath = join(cwd, 'pnpm-workspace.yaml');
-  if (existsSync(workspaceYamlPath)) {
-    const yaml = await readFile(workspaceYamlPath, 'utf-8');
-    const lines = yaml.split('\n');
-    const result: string[] = [];
-    let inOverrides = false;
-
-    for (const line of lines) {
-      if (/^overrides:\s*$/.test(line)) {
-        inOverrides = true;
-        result.push('overrides:');
-        for (const [name, value] of Object.entries(tgzPaths)) {
-          const yamlKey = name.includes('@') ? `"${name}"` : name;
-          result.push(`  ${yamlKey}: ${value}`);
-        }
-        continue;
-      }
-      if (inOverrides) {
-        if (line.startsWith('  ')) {
-          continue;
-        }
-        inOverrides = false;
-      }
-      result.push(line);
-    }
-
-    if (!inOverrides && !result.some((l) => l.startsWith('overrides:'))) {
-      result.push('overrides:');
-      for (const [name, value] of Object.entries(tgzPaths)) {
-        const yamlKey = name.includes('@') ? `"${name}"` : name;
-        result.push(`  ${yamlKey}: ${value}`);
-      }
-    }
-
-    await writeFile(workspaceYamlPath, result.join('\n'), 'utf-8');
-  }
-}
-
 if (project === 'rollipop') {
   const oxfmtrc = await readFile(join(repoRoot, '.oxfmtrc.json'), 'utf-8');
   await writeFile(
@@ -92,35 +30,22 @@ if (project === 'rollipop') {
   );
 }
 
+// Projects that already use vite-plus need VITE_PLUS_FORCE_MIGRATE=1 so
+// vp migrate runs full dependency rewriting instead of skipping.
+const forceFreshMigration = 'forceFreshMigration' in repoConfig && repoConfig.forceFreshMigration;
+
 execSync(`${cli} migrate --no-agent --no-interactive`, {
   cwd,
   stdio: 'inherit',
   env: {
     ...process.env,
+    ...(forceFreshMigration ? { VITE_PLUS_FORCE_MIGRATE: '1' } : {}),
     VITE_PLUS_OVERRIDE_PACKAGES: JSON.stringify({
-      vite: tgzPaths.vite,
-      vitest: tgzPaths.vitest,
-      '@voidzero-dev/vite-plus-core': tgzPaths['@voidzero-dev/vite-plus-core'],
-      '@voidzero-dev/vite-plus-test': tgzPaths['@voidzero-dev/vite-plus-test'],
+      vite: `file:${tgzDir}/voidzero-dev-vite-plus-core-0.0.0.tgz`,
+      vitest: `file:${tgzDir}/voidzero-dev-vite-plus-test-0.0.0.tgz`,
+      '@voidzero-dev/vite-plus-core': `file:${tgzDir}/voidzero-dev-vite-plus-core-0.0.0.tgz`,
+      '@voidzero-dev/vite-plus-test': `file:${tgzDir}/voidzero-dev-vite-plus-test-0.0.0.tgz`,
     }),
-    VITE_PLUS_VERSION: tgzPaths['vite-plus'],
+    VITE_PLUS_VERSION: `file:${tgzDir}/vite-plus-0.0.0.tgz`,
   },
 });
-
-// Post-migration: ensure tgz overrides are set in pnpm.overrides in package.json.
-// vp migrate may overwrite overrides set before migration, and pnpm ignores
-// pnpm-workspace.yaml overrides when pnpm.overrides exists in package.json.
-if (forceFreshMigration) {
-  const pkgPath = join(cwd, 'package.json');
-  const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'));
-  if (!pkg.pnpm) {
-    pkg.pnpm = {};
-  }
-  if (!pkg.pnpm.overrides) {
-    pkg.pnpm.overrides = {};
-  }
-  for (const [name, value] of Object.entries(tgzPaths)) {
-    pkg.pnpm.overrides[name] = value;
-  }
-  await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
-}

packages/cli/src/migration/bin.ts

@@ -18,6 +18,7 @@ import {
   selectAgentTargetPaths,
   writeAgentInstructions,
 } from '../utils/agent.js';
+import { isForceOverrideMode } from '../utils/constants.js';
 import {
   detectEditorConflicts,
   type EditorId,
@@ -747,8 +748,9 @@ async function main() {
   const resolvedPackageManager = workspaceInfoOptional.packageManager ?? 'unknown';
 
   // Early return if already using Vite+ (only ESLint/hooks migration may be needed)
+  // In force-override mode (file: tgz overrides), skip this check and run full migration
   const rootPkg = readNearestPackageJson<PackageDependencies>(workspaceInfoOptional.rootDir);
-  if (hasVitePlusDependency(rootPkg)) {
+  if (hasVitePlusDependency(rootPkg) && !isForceOverrideMode()) {
     let didMigrate = false;
     let installDurationMs = 0;
     const report = createMigrationReport();

packages/cli/src/migration/migrator.ts

@@ -22,6 +22,7 @@ import {
   VITE_PLUS_NAME,
   VITE_PLUS_OVERRIDE_PACKAGES,
   VITE_PLUS_VERSION,
+  isForceOverrideMode,
 } from '../utils/constants.js';
 import { editJsonFile, isJsonFile, readJsonFile } from '../utils/json.js';
 import { detectPackageMetadata } from '../utils/package.js';
@@ -982,16 +983,29 @@ function rewriteRootWorkspacePackageJson(
         ...VITE_PLUS_OVERRIDE_PACKAGES,
       };
     } else if (packageManager === PackageManager.pnpm) {
-      // pnpm use overrides field at pnpm-workspace.yaml
-      // so we don't need to set overrides field at package.json
-      // remove packages from `resolutions` field and `pnpm.overrides` field if they exist
-      // https://pnpm.io/9.x/package_json#resolutions
-      for (const key of [...Object.keys(VITE_PLUS_OVERRIDE_PACKAGES), ...REMOVE_PACKAGES]) {
-        if (pkg.pnpm?.overrides?.[key]) {
-          delete pkg.pnpm.overrides[key];
-        }
-        if (pkg.resolutions?.[key]) {
-          delete pkg.resolutions[key];
+      if (isForceOverrideMode()) {
+        // In force-override mode, keep overrides in package.json pnpm.overrides
+        // because pnpm ignores pnpm-workspace.yaml overrides when pnpm.overrides
+        // exists in package.json (even with unrelated entries like rollup).
+        pkg.pnpm = {
+          ...pkg.pnpm,
+          overrides: {
+            ...pkg.pnpm?.overrides,
+            ...VITE_PLUS_OVERRIDE_PACKAGES,
+          },
+        };
+      } else {
+        // pnpm use overrides field at pnpm-workspace.yaml
+        // so we don't need to set overrides field at package.json
+        // remove packages from `resolutions` field and `pnpm.overrides` field if they exist
+        // https://pnpm.io/9.x/package_json#resolutions
+        for (const key of [...Object.keys(VITE_PLUS_OVERRIDE_PACKAGES), ...REMOVE_PACKAGES]) {
+          if (pkg.pnpm?.overrides?.[key]) {
+            delete pkg.pnpm.overrides[key];
+          }
+          if (pkg.resolutions?.[key]) {
+            delete pkg.resolutions[key];
+          }
         }
       }
       // remove dependency selector from vite, e.g. "vite-plugin-svgr>vite": "npm:vite@7.0.12"

packages/cli/src/utils/constants.ts

@@ -11,6 +11,15 @@ export const VITE_PLUS_OVERRIDE_PACKAGES: Record<string, string> = process.env
       vitest: 'npm:@voidzero-dev/vite-plus-test@latest',
     };
 
+/**
+ * When VITE_PLUS_FORCE_MIGRATE is set, force full dependency rewriting
+ * even for projects already using vite-plus. Used by ecosystem CI to
+ * override dependencies with locally built tgz packages.
+ */
+export function isForceOverrideMode(): boolean {
+  return process.env.VITE_PLUS_FORCE_MIGRATE === '1';
+}
+
 const require = createRequire(import.meta.url);
 
 export function resolve(path: string) {