Merge branch 'main' into fix/pnpm-short-alias-shims

Author: fengmk2

.claude/skills/release-manager/SKILL.md

@@ -19,6 +19,7 @@ Run a standard vite-plus release from version bump to published announcement. An
 When given a release PR (URL or number), do not start from step 1. First audit the release's current state, then continue from the earliest unfinished step:
 
 - Is the binding version synced? (step 2: `grep -c "'<prev>'" packages/cli/binding/index.cjs` on the release branch)
+- Do the release version examples in the migration guide and the setup, migration, and upgrade prompts match `packages/cli/package.json`? (step 2)
 - Is the PR description still the `prepare_release` boilerplate, or already a categorized changelog? (step 3)
 - Is a preview build present and for the current head? (step 4)
 - Does `main` have commits the release branch lacks? (`git log origin/release/vX.Y.Z..origin/main`, step 5)
@@ -32,7 +33,7 @@ Before post-release work, fetch `origin/main` and read its copy of this skill (`
 ## Pipeline overview
 
 1. `Prepare Release` workflow bumps versions and opens the release PR (`release/vX.Y.Z` -> `main`).
-2. Release manager: sync `binding/index.cjs`, write the changelog PR description, offer the preview-build smoke test (recommend it when the release has more than 10 commits since the previous tag), get CI green.
+2. Release manager: sync `binding/index.cjs` and the release versions in the documentation and prompts, write the changelog PR description, offer the preview-build smoke test (recommend it when the release has more than 10 commits since the previous tag), get CI green.
 3. Merging the PR pushes a `packages/cli/package.json` change to `main`, which triggers `release.yml`: build, manual approval gate, npm publish, GitHub release, Docker image, Discord notification.
 4. Release manager: polish the GitHub release notes, verify installs, announce.
 
@@ -46,7 +47,9 @@ gh workflow run prepare_release.yml --repo voidzero-dev/vite-plus -f version=X.Y
 
 The workflow bumps `packages/cli/package.json`, `packages/core/package.json`, `packages/cli/binding/Cargo.toml`, and `crates/vp_global_cli/Cargo.toml`, refreshes `Cargo.lock`, and opens a PR titled `release: vX.Y.Z` from branch `release/vX.Y.Z`. The PR body ends with `Merging this PR will trigger the release workflow.` and that line must survive every later edit.
 
-## 2. Sync the NAPI binding version (required every release)
+## 2. Sync release versions (required every release)
+
+### NAPI binding
 
 NAPI bakes the package version into version checks in `packages/cli/binding/index.cjs` (26+ sites). `prepare_release` bumps `package.json` but does not regenerate this file, so CI's `Ensure no unexpected file changes after build` step in the `CLI E2E test` job fails until it is synced. Do this immediately; do not wait for CI to fail.
 
@@ -79,7 +82,20 @@ regenerate this file, so the CI build's regeneration step produces a
 diff that the post-build no-unexpected-changes guard rejects.
 ```
 
-This is the only kind of commit that goes directly on the release branch. Everything else goes through `main` (see step 5).
+### Documentation and prompts
+
+Use the version in the release branch's `packages/cli/package.json` as the target release version in these files:
+
+- `docs/guide/migrate.md`: pnpm and npm migration command examples and matching release prose.
+- `docs/.vitepress/theme/data/migration-prompts.ts`: `setupPrompt`, `migrationPrompt`, `upgradePrompt`, and their shared instructions, including command examples and matching release prose. `CopyPrompt` uses `setupPrompt` on both the homepage and Getting Started guide.
+
+Update every `--package=vite-plus@<curr>` pin and the corresponding `For the <curr> release` and `Replace <curr>` text. Keep an exact version; do not replace it with a placeholder, a major range, or `latest`.
+
+Preserve historical versions such as the migration's source version and the release that introduced a breaking change. Leave Node.js requirements, bundled tool versions, and preview-registry instructions unchanged unless their requirements change.
+
+Commit these updates on the release branch with the binding sync or in a separate release-version sync commit. Recheck both files and the binding after a target-version change or a merge from `main`. Before merging, confirm that the guide and all three prompts use the target release in both package-manager commands and their matching prose, then run `git diff --check`.
+
+Only these release-version sync commits go directly on the release branch. Everything else goes through `main` (see step 5).
 
 ## 3. Write the release PR description
 
@@ -326,7 +342,7 @@ Two fork-CI blockers are worth fixing rather than reporting, both on the **test
 
 Match checks to the current PR head and the latest applicable workflow runs. Superseded canceled runs can leave failed aggregate checks in the PR rollup. Check required statuses with `gh pr checks <PR#> --required`, and report required reviewer approval separately from technical CI readiness.
 
-Fixes for CI failures go through a **separate PR to `main`**, never as commits on the release branch (the binding sync in step 2 is the sole exception). After the fix PR merges:
+Fixes for CI failures go through a **separate PR to `main`**, never as commits on the release branch (the release-version syncs in step 2 are the exceptions). After the fix PR merges:
 
 ```bash
 git checkout release/vX.Y.Z && git merge origin/main --no-edit && git push origin release/vX.Y.Z
@@ -341,7 +357,7 @@ Known release-branch-only failure modes:
 
 ## 6. Merge
 
-Merging the release PR is the release trigger. Before merging confirm: CI green, changelog validated, binding synced, and (if used) the preview build verified.
+Merging the release PR is the release trigger. Before merging confirm: CI green, changelog validated, binding and documentation versions synced (including all three prompts), and (if used) the preview build verified.
 
 Auto-merge being enabled is not a completed merge. Confirm `mergedAt` and the merge commit, then follow the Release run for that commit; older successful runs can have skipped publishing because the version did not change.
 
@@ -492,6 +508,7 @@ After the release ships and announcements are approved or confirmed complete, re
 
 - [ ] `prepare_release` run for the target version; release PR open
 - [ ] `binding/index.cjs` synced on the release branch (step 2 commit message shape)
+- [ ] The migration guide and all three prompts in the step 2 files use the exact target version from `packages/cli/package.json` in their command examples and matching release prose
 - [ ] PR description written from the head branch data; every PR exactly once except documented omissions; breaking changes in their own section above Highlights; no em/en dashes; closing boilerplate intact
 - [ ] Dependency-upgrade PRs consolidated; vite-task bump expanded with upstream credits; security advisories linked
 - [ ] Smoke test offered to the release manager at both levels (local sweep and fork-PR CI), with the commit count stated and a recommendation to run it when that count is above 10; if accepted, forks synced to upstream first, preview build published, and the full ecosystem-ci catalog verified via `test-pkg-pr-new-migrate` (following TESTING.md), with every failure triaged and regressions ruled out against the previous release

.github/actions/build-upstream/action.yml

@@ -31,12 +31,13 @@ runs:
     - uses: ./.github/actions/compute-native-cache-input-hash
       id: native-cache-inputs
 
-    # Include env vars (RELEASE_BUILD, DEBUG, VERSION) to ensure cache miss on release builds.
+    # Include the documentation origin so preview binaries cannot reuse release links.
     - name: Compute NAPI binding cache key
       id: cache-key
       shell: bash
       run: |
-        echo "key=napi-binding-v3-${INPUTS_TARGET}-${RELEASE_BUILD}-${DEBUG}-${VERSION}-${NPM_TAG}-${{ steps.native-cache-inputs.outputs.hash }}" >> "$GITHUB_OUTPUT"
+        DOCS_ORIGIN_HASH=$(node -e 'process.stdout.write(require("node:crypto").createHash("sha256").update(process.env.VITE_PLUS_DOCS_ORIGIN || "https://viteplus.dev").digest("hex").slice(0, 16))')
+        echo "key=napi-binding-v3-${INPUTS_TARGET}-${RELEASE_BUILD}-${DEBUG}-${VERSION}-${NPM_TAG}-${DOCS_ORIGIN_HASH}-${{ steps.native-cache-inputs.outputs.hash }}" >> "$GITHUB_OUTPUT"
       env:
         INPUTS_TARGET: ${{ inputs.target }}
 

.github/actions/clone/action.yml

@@ -47,6 +47,13 @@ runs:
         ref: ${{ steps.upstream-versions.outputs.ROLLDOWN_VITE_HASH }}
         persist-credentials: false
 
+    # Match the manifests used by sync-remote when it generated the root lockfile.
+    # setup-node installs with --frozen-lockfile, so this must run before it.
+    # The runner's preinstalled Node may not support direct TypeScript execution.
+    - name: Align vendored Vite's Vitest dependencies
+      shell: bash
+      run: npx tsx packages/tools/src/vendored-vitest.ts
+
     # Disable autocrlf to preserve LF line endings on Windows
     # This prevents prettier/eslint from failing with "Delete ␍" errors
     - name: Configure git for LF line endings

.github/scripts/__tests__/docs-fork-preview.mjs

@@ -6,6 +6,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { test } from 'node:test';
 
+import { resolveDocsSiteOrigin } from '../../../docs/.vitepress/site-origin.ts';
 import {
   authorizePreview,
   commentPreview,
@@ -241,12 +242,75 @@ await test('reuses the PR origin across commits, builds, and reruns while pinnin
   assert.match(deploy, /--preview-alias "\$PREVIEW_ALIAS"/);
 });
 
-await test('uses each PR origin for shell and PowerShell installer links', async (t) => {
+await test('resolves Workers branch origins without an explicit docs origin', () => {
+  for (const branch of ['rfc/vitest-v5-upgrade', '--RFC//Vitest_V5-Upgrade--']) {
+    assert.equal(
+      resolveDocsSiteOrigin({ WORKERS_CI: '1', WORKERS_CI_BRANCH: branch }),
+      'https://rfc-vitest-v5-upgrade-viteplus-dev.voidzero-docs.workers.dev',
+    );
+  }
+});
+
+await test('preserves explicit origins and production defaults', () => {
+  assert.equal(
+    resolveDocsSiteOrigin({
+      DOCS_SITE_ORIGIN: 'https://viteplus-staging.void.app/',
+      WORKERS_CI: '1',
+      WORKERS_CI_BRANCH: 'rfc/vitest-v5-upgrade',
+    }),
+    'https://viteplus-staging.void.app',
+  );
+  for (const env of [
+    {},
+    { DOCS_SITE_ORIGIN: '' },
+    { WORKERS_CI_BRANCH: 'rfc/vitest-v5-upgrade' },
+    { WORKERS_CI: '1' },
+    { WORKERS_CI: '1', WORKERS_CI_BRANCH: 'main' },
+  ]) {
+    assert.equal(resolveDocsSiteOrigin(env), undefined);
+  }
+});
+
+await test('matches Wrangler long-branch aliases without collisions after truncation', () => {
+  for (const [branch, hash] of [
+    [`feature/${'a'.repeat(80)}`, '288d'],
+    [`feature/${'a'.repeat(79)}b`, 'ee30'],
+  ]) {
+    const origin = resolveDocsSiteOrigin({ WORKERS_CI: '1', WORKERS_CI_BRANCH: branch });
+    assert.equal(
+      origin,
+      `https://feature-${'a'.repeat(37)}-${hash}-viteplus-dev.voidzero-docs.workers.dev`,
+    );
+    assert.equal(new URL(origin).hostname.split('.')[0].length, 63);
+  }
+});
+
+await test('requires an explicit origin when Wrangler cannot create a branch alias', () => {
+  for (const branch of ['123-fix', '___']) {
+    const env = { WORKERS_CI: '1', WORKERS_CI_BRANCH: branch };
+    assert.throws(() => resolveDocsSiteOrigin(env), /Set DOCS_SITE_ORIGIN/);
+    assert.equal(
+      resolveDocsSiteOrigin({ ...env, DOCS_SITE_ORIGIN: previewUrl(2684) }),
+      previewUrl(2684),
+    );
+  }
+});
+
+await test('uses each deploy origin for shell and PowerShell installer links', async (t) => {
   const directory = await mkdtemp(join(tmpdir(), 'docs-preview-installers-'));
   t.after(() => rm(directory, { recursive: true, force: true }));
   const snapshots = [];
-  for (const number of [2684, 2685]) {
-    const root = join(directory, String(number));
+  const cases = [
+    { env: { DOCS_SITE_ORIGIN: previewUrl(2684) }, origin: previewUrl(2684) },
+    { env: { DOCS_SITE_ORIGIN: previewUrl(2685) }, origin: previewUrl(2685) },
+    {
+      env: { WORKERS_CI: '1', WORKERS_CI_BRANCH: 'rfc/vitest-v5-upgrade' },
+      origin: 'https://rfc-vitest-v5-upgrade-viteplus-dev.voidzero-docs.workers.dev',
+    },
+    { env: {}, origin: 'https://viteplus.dev' },
+  ];
+  for (const [index, { env, origin }] of cases.entries()) {
+    const root = join(directory, String(index));
     const scripts = join(root, 'docs', '.vitepress', 'scripts');
     const output = join(root, 'docs', 'public');
     const installers = join(root, 'packages', 'cli');
@@ -258,21 +322,32 @@ await test('uses each PR origin for shell and PowerShell installer links', async
       new URL('../../../docs/.vitepress/scripts/copy-installers.mjs', import.meta.url),
       script,
     );
+    await copyFile(
+      new URL('../../../docs/.vitepress/site-origin.ts', import.meta.url),
+      join(scripts, '..', 'site-origin.ts'),
+    );
     for (const name of ['install.sh', 'install.ps1', 'install-legacy.sh', 'install-legacy.ps1']) {
       await copyFile(
         new URL(`../../../packages/cli/${name}`, import.meta.url),
         join(installers, name),
       );
     }
-    const origin = previewUrl(number);
-    execFileSync(process.execPath, [script], { env: { ...process.env, DOCS_SITE_ORIGIN: origin } });
+    execFileSync(process.execPath, [script], {
+      env: {
+        ...process.env,
+        DOCS_SITE_ORIGIN: '',
+        WORKERS_CI: '',
+        WORKERS_CI_BRANCH: '',
+        ...env,
+      },
+    });
     const shell = await readFile(join(output, 'install.sh'), 'utf8');
     const powershell = await readFile(join(output, 'install.ps1'), 'utf8');
     assert.ok(shell.includes(`${origin}/install-legacy.sh`));
     assert.ok(powershell.includes(`${origin}/install-legacy.ps1`));
     snapshots.push({ origin, shell, powershell });
   }
-  assert.equal(new Set(snapshots.map((snapshot) => snapshot.origin)).size, 2);
+  assert.equal(new Set(snapshots.map((snapshot) => snapshot.origin)).size, cases.length);
   for (const snapshot of snapshots) {
     for (const other of snapshots) {
       if (other.origin !== snapshot.origin) {

.github/scripts/__tests__/preview-docs-origin.mjs

@@ -0,0 +1,51 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { test } from 'node:test';
+
+import { resolveDocsSiteOrigin } from '../../../docs/.vitepress/site-origin.ts';
+import { previewUrl } from '../docs-fork-preview.mjs';
+import { previewDocsOrigin } from '../preview-docs-origin.ts';
+
+const pr = {
+  number: 2551,
+  head: { ref: 'rfc/vitest-v5-upgrade', repo: { full_name: 'voidzero-dev/vite-plus' } },
+  base: { repo: { full_name: 'voidzero-dev/vite-plus' } },
+};
+
+const read = (file) => readFileSync(new URL(file, import.meta.url), 'utf8');
+
+await test('uses the head branch docs for same-repo and stacked PRs', () => {
+  assert.equal(
+    previewDocsOrigin(pr),
+    'https://rfc-vitest-v5-upgrade-viteplus-dev.voidzero-docs.workers.dev',
+  );
+  for (const branch of ['--RFC//Vitest_V5-Upgrade--', `feature/${'a'.repeat(80)}`]) {
+    assert.equal(
+      previewDocsOrigin({ ...pr, head: { ...pr.head, ref: branch } }),
+      resolveDocsSiteOrigin({ WORKERS_CI: '1', WORKERS_CI_BRANCH: branch }),
+    );
+  }
+});
+
+await test('uses the PR alias for forks, never a same-named repository branch', () => {
+  assert.equal(
+    previewDocsOrigin({
+      ...pr,
+      head: { ...pr.head, repo: { full_name: 'contributor/vite-plus' } },
+    }),
+    previewUrl(pr.number),
+  );
+});
+
+await test('passes the origin to native builds and includes it in the native cache key', () => {
+  const preview = read('../../workflows/publish-preview.yml');
+  const release = read('../../workflows/reusable-release-build.yml');
+  const build = read('../../actions/build-upstream/action.yml');
+  assert.match(preview, /previewDocsOrigin\(context\.payload\.pull_request\)/);
+  assert.match(preview, /docs-origin: \$\{\{ steps\.docs\.outputs\.origin \}\}/);
+  assert.match(preview, /docs-origin: \$\{\{ needs\.prepare\.outputs\.docs-origin \}\}/);
+  assert.match(release, /default: 'https:\/\/viteplus\.dev'/);
+  assert.match(release, /VITE_PLUS_DOCS_ORIGIN: \$\{\{ inputs\.docs-origin \}\}/);
+  assert.match(build, /process\.env\.VITE_PLUS_DOCS_ORIGIN/);
+  assert.match(build, /napi-binding-v3-.*\$\{DOCS_ORIGIN_HASH\}/);
+});

.github/scripts/__tests__/upgrade-deps-utils.spec.ts

@@ -16,3 +16,9 @@ test('selects the highest stable version from the supported major', () => {
 test('returns undefined when the supported major has no stable release', () => {
   expect(findLatestStableVersionForMajor(['4.2.0-beta.1', '5.0.0'], 4)).toBeUndefined();
 });
+
+test('keeps Vitest upgrades on v5 after the migration', () => {
+  expect(
+    findLatestStableVersionForMajor(['4.1.11', '5.0.0', '5.1.0', '5.2.0-beta.1', '6.0.0'], 5),
+  ).toBe('5.1.0');
+});

.github/scripts/preview-docs-origin.ts

@@ -0,0 +1,17 @@
+import { resolveDocsSiteOrigin } from '../../docs/.vitepress/site-origin.ts';
+import { previewUrl } from './docs-fork-preview.mjs';
+
+/** Use the same URLs as Workers Builds (same-repo) and the fork docs workflow. */
+export function previewDocsOrigin(pr: {
+  number: number;
+  head: { ref: string; repo: { full_name: string } };
+  base: { repo: { full_name: string } };
+}): string {
+  if (pr.head.repo.full_name !== pr.base.repo.full_name) {
+    return previewUrl(pr.number);
+  }
+  return (
+    resolveDocsSiteOrigin({ WORKERS_CI: '1', WORKERS_CI_BRANCH: pr.head.ref }) ??
+    'https://viteplus.dev'
+  );
+}

.github/scripts/upgrade-deps.ts

@@ -73,7 +73,7 @@ type PnpmWorkspaceEntry = {
 const STABLE_SEMVER_TAG_RE = /^v?\d+\.\d+\.\d+$/;
 // Vitest major upgrades can change the bundled API, export shims, and CLI
 // behavior. Advance this only after Vite+ has adapted to the new major.
-const SUPPORTED_VITEST_MAJOR = 4;
+const SUPPORTED_VITEST_MAJOR = 5;
 
 const isFullSha = (s: string): boolean => /^[0-9a-f]{40}$/.test(s);
 
@@ -212,18 +212,15 @@ async function updatePnpmWorkspace(versions: PnpmWorkspaceVersions): Promise<voi
   let content = fs.readFileSync(filePath, 'utf8');
 
   // oxlint's trailing \n in the pattern disambiguates from oxlint-tsgolint.
-  // All @vitest/* catalog entries (browser + core direct deps) must stay pinned
+  // Official @vitest/* catalog entries (browser + core direct deps) stay pinned
   // to the same exact version as `vitest` itself, otherwise the catalog drifts
   // from VITEST_VERSION.
   const vitestExactVersionPackages = [
     '@vitest/browser',
     '@vitest/browser-playwright',
     '@vitest/browser-preview',
-    '@vitest/browser-webdriverio',
-    '@vitest/expect',
     '@vitest/mocker',
     '@vitest/pretty-format',
-    '@vitest/runner',
     '@vitest/snapshot',
     '@vitest/spy',
     '@vitest/utils',

.github/workflows/ci.yml

@@ -375,10 +375,13 @@ jobs:
         include:
           - os: namespace-profile-linux-x64-default
             target: x86_64-unknown-linux-gnu
+            test-node: 22.18.0
           - os: namespace-profile-mac-default
             target: aarch64-apple-darwin
+            test-node: 24.11.0
           - os: namespace-profile-windows-4c-8g
             target: x86_64-pc-windows-msvc
+            test-node: 26.0.0
     runs-on: ${{ matrix.os }}
     steps:
       - uses: taiki-e/checkout-action@7d1e50e93dc4fb3bba58f85018fadf77898aee8b # v1.4.2
@@ -463,8 +466,9 @@ jobs:
         run: vp check
 
       - name: Run unit tests
-        run: RUST_BACKTRACE=1 pnpm test:unit
+        run: vp env exec --node ${{ matrix.test-node }} node packages/cli/dist/bin.js test run
         env:
+          RUST_BACKTRACE: '1'
           RUST_MIN_STACK: 8388608
 
       - name: Test global package install (powershell)