Merge branch 'main' into codex/document-pkg-pr-new-preview-builds

Author: fengmk2

.claude/skills/test-pkg-pr-new-migrate/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: test-pkg-pr-new-migrate
+description: Verify a pkg.pr.new build of vite-plus against a real project before release — run `vp migrate` from the pkg.pr.new commit against a local project, deps resolved through the registry bridge. Use when asked to verify/e2e-test a pkg.pr.new build against a project, "test PR #<N> on <project>", or check a prerelease against a repo.
+allowed-tools: Bash, Read
+---
+
+# Verify a pkg.pr.new build against one project
+
+Installs an isolated global `vp` built from a registry bridge commit build and runs `vp migrate` on a specified local project. The global CLI and the migrated project both pin `vite-plus`/`vite` to the clearly-defined `0.0.0-commit.<sha>` build. `vp migrate` itself writes the bridge registry into the project's `.npmrc` (or `.yarnrc.yml` for Yarn Berry) so the deps resolve, during this run and in the project's own CI; this script only force-stages that file past `.gitignore`.
+
+Required inputs: a `<PR-or-SHA>` (the build to verify) and a `<project-path>`. If either is missing from the request, **ask the user** for it — never guess the PR/SHA, as the build under test is the user's choice.
+
+```bash
+.github/scripts/test-pkg-pr-new-migrate.sh <PR-or-SHA> <project-path> [migrate-options...]
+# e.g.
+.github/scripts/test-pkg-pr-new-migrate.sh 1891 /path/to/npmx.dev --no-interactive
+```
+
+- First arg is a PR number or commit SHA; the script resolves the immutable commit via the bridge `x-commit-key` header and verifies the bridge serves it (the pkg.pr.new publish workflow registers each commit).
+- Never touches `~/.vite-plus`; clears only the workspace ROOT lockfile + `node_modules` before migrating; refuses a dirty worktree unless `ALLOW_DIRTY=1`; prints the project's `git status`/`diff` at the end — inspect that to confirm the migration result.
+
+**The build under test must include the "migrate writes the bridge registry" feature** (this session's work / current branch head onward). The harness no longer writes the registry itself — it relies on `vp migrate` doing it. Testing an older build with this harness would leave the project with no bridge registry, so its deps resolve from npmjs (`ERR_PNPM_NO_MATCHING_VERSION` on the `0.0.0-commit.<sha>` version). Always verify a fresh build of the branch, not a stale published commit.
+
+The script prints the resolved versions at the end, querying one package at a time (npm/yarn/bun `why` only accept a single package; `-r` is pnpm-only). Each must resolve to exactly ONE version: `vite-plus` and `vite` at the expected `0.0.0-commit.<sha>` (vite via the `@voidzero-dev/vite-plus-core` alias), `vitest` at the bundled upstream version. Multiple versions, or a stale/wrong version, means the migration or install is broken. To re-check by hand:
+
+```bash
+cd <project-path>
+# pnpm: one call, recursive across workspaces
+vp why -r vite-plus vite vitest
+# npm / yarn / bun: one package per call, no -r
+vp why vite-plus && vp why vite && vp why vitest
+```

.claude/skills/verify-interactive-cli/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: verify-interactive-cli
+description: Drive and capture vp's interactive (clack) prompts in a tmux session to verify interactive UX and catch spinner-over-prompt bugs that snap tests (which run non-interactively) miss. Use when asked to test/verify/capture an interactive vp command's prompts (vp migrate, vp create, ...), reproduce a prompt-rendering bug, or show the real interactive CLI output for a PR.
+allowed-tools: Bash, Read
+---
+
+# Verify vp's interactive CLI prompts
+
+Snap tests run `vp` non-interactively, so interactive clack prompts (hooks / agent / editor confirms, the Node-version upgrade confirm) and TTY-only rendering bugs are never exercised. This skill drives the real prompts in a TTY (via tmux), captures clean output, and can catch a spinner animating underneath an active prompt (a real, recurring UX bug class, e.g. the "Preparing migration" and "Checking Node.js version support" spinners).
+
+## Prerequisites
+
+- `tmux` (macOS has none by default): `brew install tmux`.
+- The global `vp` must contain the code under test. To exercise working-tree changes, rebuild first: `pnpm bootstrap-cli` (~5 min), then confirm with `vp --version`.
+
+## Driver
+
+`interactive-cli-tmux-driver.sh` is bundled in this skill's directory.
+
+```bash
+# Run to completion, auto-accepting every prompt's DEFAULT; prints a clean transcript.
+.claude/skills/verify-interactive-cli/interactive-cli-tmux-driver.sh <project-dir> "vp migrate"
+
+# STOP at a specific prompt (do NOT answer it) and check for a spinner animating under it.
+.claude/skills/verify-interactive-cli/interactive-cli-tmux-driver.sh <project-dir> "vp migrate" "Upgrade Node.js"
+```
+
+How it works:
+
+- Runs the command in a detached tmux session; `tmux capture-pane -p` yields clean text (clack's in-place redraws overwrite, so only resolved lines remain), far cleaner than `expect`'s raw ANSI capture.
+- Auto-accepts each prompt's default by sending Enter when the pane goes STABLE. A waiting prompt is static; animating spinners keep the pane changing, so Enter never fires mid-work.
+- End-detection uses `; echo "$M1$M2 exit=$?"` where M1/M2 are split vars, so the literal end marker is not in the typed command line (otherwise a grep matches the echoed command, not the program output).
+- With a STOP_AT regex it halts at the target prompt and captures twice ~3s apart: identical captures = static prompt (OK); differing captures (or a `Checking ... (Xs)` line) = a spinner is animating under the prompt = a UX bug.
+
+## Setting up a target project
+
+Create a throwaway project that triggers the prompts you want to see, e.g. a fresh Vite app whose `.node-version` is below the supported range to exercise the Node-upgrade confirm:
+
+```bash
+mkdir -p /tmp/vp-demo && cd /tmp/vp-demo
+printf '{\n  "name":"d","private":true,"type":"module","packageManager":"pnpm@10.18.0",\n  "scripts":{"build":"vite build","test":"vitest run"},\n  "devDependencies":{"vite":"^8.0.0","vitest":"^4.1.0"}\n}\n' > package.json
+echo "24.3.0" > .node-version
+printf 'import { defineConfig } from "vite";\nexport default defineConfig({});\n' > vite.config.ts
+git init -q && git add -A && git -c user.email=x@x -c user.name=x commit -qm init
+```
+
+## When you find a spinner-over-prompt bug
+
+Fix it test-first: the prompt's code must pause the migration progress spinner before the confirm renders. Assert the call order is `['pause', 'confirm']`. Reference fix: `upgradeUnsupportedNodeVersions` (in `packages/cli/src/migration/migrator/setup.ts`) takes a `pauseProgress` callback that `bin.ts` wires to `clearMigrationProgress`, called right before `prompts.confirm`.
+
+## Gotchas
+
+- clack's active-prompt marker here is `›` (not always `◆`); detect a waiting prompt by pane stability, not a specific glyph.
+- `VP_SKIP_INSTALL=1` skips the dependency install but breaks steps that load `vite.config.ts` (e.g. the prettier auto-migration) because `vite` isn't installed; use it only when you stop before the install step.
+- A `&` inside a background task detaches the script, so the task reports "completed" early while it keeps running; poll a status file or `capture-pane` to track real progress.

.claude/skills/verify-interactive-cli/interactive-cli-tmux-driver.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+# Drive and capture an interactive `vp` (clack) prompt flow inside tmux, to verify
+# interactive UX that snap tests (which run non-interactively) never cover.
+#
+# Usage:
+#   interactive-cli-tmux-driver.sh <project-dir> "<command>" [STOP_AT_REGEX]
+#     interactive-cli-tmux-driver.sh /tmp/demo "vp migrate"
+#     interactive-cli-tmux-driver.sh /tmp/demo "vp migrate" "Upgrade Node.js"
+#
+# No STOP_AT  : run to completion, auto-accepting every prompt's DEFAULT (Enter),
+#               then print a clean transcript.
+# With STOP_AT: drive prompts until one matching the regex appears, then STOP
+#               (do NOT answer it) and capture the pane twice 3s apart. Identical
+#               captures => prompt is static (good). Differing captures (or a
+#               "Checking ... (Xs)" line) => a spinner is animating UNDER the
+#               prompt -- a real UX bug (this is how the Node-upgrade confirm
+#               spinner-overlap was found).
+#
+# Why tmux and not `expect`: expect's raw capture is full of ANSI cursor/redraw
+# noise; `tmux capture-pane -p` returns clean text because in-place redraws
+# overwrite and only the resolved lines remain in scrollback.
+# macOS has no tmux/timeout by default: `brew install tmux`.
+set -u
+DIR="${1:?project dir}"; CMD="${2:?command, e.g. \"vp migrate\"}"; STOP_AT="${3:-}"
+command -v tmux >/dev/null || { echo "need tmux: brew install tmux" >&2; exit 1; }
+S="clicap_$$"
+cap1="$(mktemp)"; cap2="$(mktemp)"
+
+tmux kill-session -t "$S" 2>/dev/null
+tmux new-session -d -s "$S" -x 100 -y 50
+tmux set-option -t "$S" history-limit 50000
+# M1/M2 are split so the end marker never appears in the TYPED command line --
+# otherwise a grep for it matches the echoed command, not the program output.
+tmux send-keys -t "$S" 'export PS1="$ " PROMPT="%% " M1=CLI M2=CAPDONE' Enter; sleep 1
+tmux send-keys -t "$S" "cd '$DIR'" Enter; sleep 1
+tmux send-keys -t "$S" 'clear' Enter; sleep 1
+tmux send-keys -t "$S" "$CMD"'; echo "$M1$M2 exit=$?"' Enter
+
+prev=""; stable=0; sent=0
+for i in $(seq 1 180); do
+  sleep 2
+  pane="$(tmux capture-pane -t "$S" -p -S -120 2>/dev/null)"
+  # reached the prompt we want to inspect -> stop without answering it
+  if [ -n "$STOP_AT" ] && printf '%s' "$pane" | grep -q "$STOP_AT"; then
+    tmux capture-pane -t "$S" -p -S -60 > "$cap1"; sleep 3
+    tmux capture-pane -t "$S" -p -S -60 > "$cap2"
+    if diff -q "$cap1" "$cap2" >/dev/null; then
+      echo "STATIC prompt (nothing animating underneath) -- OK"
+    else
+      echo "ANIMATING under the prompt (likely spinner-over-prompt bug):"
+      diff "$cap1" "$cap2"
+    fi
+    echo "--- prompt ---"; sed -n "/$STOP_AT/,\$p" "$cap1"
+    tmux kill-session -t "$S" 2>/dev/null; rm -f "$cap1" "$cap2"; exit 0
+  fi
+  # program finished
+  printf '%s' "$pane" | grep -q "CLICAPDONE exit=" && break
+  # A waiting prompt makes the pane STABLE; animating spinners keep it changing,
+  # so this won't fire mid-work. Accept the default with Enter, once per state.
+  if [ "$pane" = "$prev" ]; then
+    stable=$((stable+1))
+    if [ "$stable" -ge 2 ] && [ "$sent" -eq 0 ]; then tmux send-keys -t "$S" Enter; sent=1; fi
+  else
+    prev="$pane"; stable=0; sent=0
+  fi
+done
+
+echo "=== clean transcript ==="
+tmux capture-pane -t "$S" -p -S -3000
+tmux kill-session -t "$S" 2>/dev/null; rm -f "$cap1" "$cap2"