feat(install): support VP_PR_VERSION for pkg.pr.new testing (#1578)

## Summary

Add `VP_PR_VERSION` env var to both `install.sh` and `install.ps1` so
users can install an unreleased PR build (or any commit) via pkg.pr.new
for temporary testing. Since npm releases only ship from `main`,
pkg.pr.new is the only available testing channel for in-flight changes.

When `VP_PR_VERSION` is set, the installer:
- Bypasses the npm registry (no metadata fetch)
- Downloads the CLI platform tarball from
`https://pkg.pr.new/voidzero-dev/vite-plus/@voidzero-dev/vite-plus-cli-{platform}@{PR_or_SHA}`
- Writes `vite-plus` in the wrapper `package.json` as
`https://pkg.pr.new/voidzero-dev/vite-plus@{PR_or_SHA}` — the published
pkg.pr.new tarball already rewrites scoped workspace deps to matching
pkg.pr.new URLs by commit SHA, so pnpm pulls in a coherent PR build.
- Installs into `~/.vite-plus/pkg-pr-new-{PR_or_SHA}/` — a non-semver
dir name so `cleanup_old_versions` won't auto-delete it.
- Errors early if combined with `VP_LOCAL_TGZ`.

## Usage

```bash
# bash / macOS / Linux
curl -fsSL https://vite.plus | VP_PR_VERSION=1569 bash
```

```powershell
# Windows
$env:VP_PR_VERSION = "1569"; irm https://vite.plus/ps1 | iex
```

`VP_PR_VERSION` accepts either a PR number (e.g. `1569`) or a commit
SHA.

## Test plan

End-to-end verified against #1569 in a sandboxed `HOME`:

- [x] `vp --version` reports `v0.0.0-pkg-pr-new.c178e90` (matches PR
#1569 commit)
- [x] `node_modules/vite-plus/package.json` version matches the PR build
- [x] Transitive `@voidzero-dev/vite-plus-core` resolves via pkg.pr.new
URL with the same commit SHA
- [x] `pnpm-lock.yaml` records `vite-plus.specifier:
https://pkg.pr.new/voidzero-dev/vite-plus@1569`
- [x] Normal (no `VP_PR_VERSION`) flow unchanged — still hits npm
registry
- [x] `VP_PR_VERSION` + `VP_LOCAL_TGZ` errors early as expected
- [x] `bash -n` passes on `install.sh`

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes the installation path and download sources in the
cross-platform installers, which could break installs or pull unintended
artifacts if the new URL construction/branching logic is wrong. Scope is
limited to `install.sh`/`install.ps1` and guarded by an opt-in env var.
> 
> **Overview**
> Adds `VP_PR_VERSION` to `install.sh` and `install.ps1` to install
unreleased PR/commit builds via `pkg.pr.new`, bypassing npm
metadata/version resolution.
> 
> When set, the installers (1) refuse to run alongside `VP_LOCAL_TGZ`,
(2) download the platform CLI tarball from `pkg.pr.new`, (3) install
into a synthetic non-semver version directory (`pkg-pr-new-...`) to
avoid old-version cleanup, and (4) write the wrapper `package.json`
dependency as a `pkg.pr.new` URL so `pnpm` pulls a coherent PR build of
`vite-plus` and its workspace deps.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
247c17e. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: fengmk2

packages/cli/install.ps1

@@ -9,6 +9,9 @@
 #   VP_HOME - Installation directory (default: $env:USERPROFILE\.vite-plus)
 #   NPM_CONFIG_REGISTRY - Custom npm registry URL (default: https://registry.npmjs.org)
 #   VP_LOCAL_TGZ - Path to local vite-plus.tgz (for development/testing)
+#   VP_PR_VERSION - PR number or commit SHA to install from pkg.pr.new
+#                   (for temporary testing of unreleased builds, e.g. VP_PR_VERSION=1569).
+#                   When set, overrides VP_VERSION and bypasses the npm registry.
 
 $ErrorActionPreference = "Stop"
 
@@ -20,6 +23,10 @@ $NpmRegistry = if ($env:NPM_CONFIG_REGISTRY) { $env:NPM_CONFIG_REGISTRY.TrimEnd(
 $LocalTgz = $env:VP_LOCAL_TGZ
 # Local binary path (set by install-global-cli.ts for local dev)
 $LocalBinary = $env:VP_LOCAL_BINARY
+# pkg.pr.new PR number or commit SHA (for temporary testing of unreleased builds)
+$PrVersion = $env:VP_PR_VERSION
+# pkg.pr.new base URL for fetching tarballs and constructing dependency URLs
+$PkgPrNewBase = "https://pkg.pr.new/voidzero-dev/vite-plus"
 
 function Write-Info {
     param([string]$Message)
@@ -418,6 +425,10 @@ function Main {
     Write-Host "VITE+" -ForegroundColor Blue -NoNewline
     Write-Host "..."
 
+    if ($PrVersion -and $LocalTgz) {
+        Write-Error-Exit "VP_PR_VERSION and VP_LOCAL_TGZ cannot be used together"
+    }
+
     # Suppress progress bars for cleaner output
     $ProgressPreference = 'SilentlyContinue'
 
@@ -434,6 +445,12 @@ function Main {
         if ($ViteVersion -eq "latest" -or $ViteVersion -eq "test") {
             $ViteVersion = "local-dev"
         }
+    } elseif ($PrVersion) {
+        # pkg.pr.new mode: skip npm metadata, use a synthetic version label.
+        # Non-semver label keeps the directory out of Cleanup-OldVersions and
+        # makes it obvious in ~/.vite-plus which install is the PR build.
+        $ViteVersion = "pkg-pr-new-$PrVersion"
+        Write-Info "Using pkg.pr.new version: $PrVersion"
     } else {
         # Fetch package metadata and resolve version from npm
         $ViteVersion = Get-VersionFromMetadata
@@ -465,10 +482,15 @@ function Main {
             Write-Error-Exit "VP_LOCAL_BINARY must be set when using VP_LOCAL_TGZ"
         }
     } else {
-        # Download from npm registry — extract only the vp binary from CLI platform package
+        # Download CLI platform tarball — npm registry or pkg.pr.new (when PrVersion is set)
         $platformSuffix = Get-PlatformSuffix -Platform $platform
-        $packageName = "@voidzero-dev/vite-plus-cli-$platformSuffix"
-        $platformUrl = "$NpmRegistry/$packageName/-/vite-plus-cli-$platformSuffix-$ViteVersion.tgz"
+        if ($PrVersion) {
+            # pkg.pr.new redirects this URL to the platform tarball for the matching PR/commit
+            $platformUrl = "$PkgPrNewBase/@voidzero-dev/vite-plus-cli-$platformSuffix@$PrVersion"
+        } else {
+            $packageName = "@voidzero-dev/vite-plus-cli-$platformSuffix"
+            $platformUrl = "$NpmRegistry/$packageName/-/vite-plus-cli-$platformSuffix-$ViteVersion.tgz"
+        }
 
         $platformTempFile = New-TemporaryFile
         try {
@@ -506,13 +528,16 @@ function Main {
     # Generate wrapper package.json that declares vite-plus as a dependency.
     # pnpm will install vite-plus and all transitive deps via `vp install`.
     # The packageManager field pins pnpm to a known-good version.
+    # pkg.pr.new tarballs pre-rewrite scoped workspace deps to matching URLs by
+    # commit SHA, so pointing vite-plus at one URL pulls in a coherent PR build.
+    $vitePlusSpec = if ($PrVersion) { "$PkgPrNewBase@$PrVersion" } else { $ViteVersion }
     $wrapperJson = @{
         name = "vp-global"
         version = $ViteVersion
         private = $true
         packageManager = "pnpm@10.33.0"
         dependencies = @{
-            "vite-plus" = $ViteVersion
+            "vite-plus" = $vitePlusSpec
         }
     } | ConvertTo-Json -Depth 10
     Set-Content -Path (Join-Path $VersionDir "package.json") -Value $wrapperJson

packages/cli/install.sh

@@ -11,6 +11,9 @@
 #   NPM_CONFIG_REGISTRY - Custom npm registry URL (default: https://registry.npmjs.org)
 #   VP_NODE_MANAGER - Set to "yes" or "no" to skip interactive prompt (for CI/devcontainers)
 #   VP_LOCAL_TGZ - Path to local vite-plus.tgz (for development/testing)
+#   VP_PR_VERSION - PR number or commit SHA to install from pkg.pr.new
+#                   (for temporary testing of unreleased builds, e.g. VP_PR_VERSION=1569).
+#                   When set, overrides VP_VERSION and bypasses the npm registry.
 
 set -e
 
@@ -31,6 +34,10 @@ NPM_REGISTRY="${NPM_REGISTRY%/}"
 LOCAL_TGZ="${VP_LOCAL_TGZ:-}"
 # Local binary path (set by install-global-cli.ts for local dev)
 LOCAL_BINARY="${VP_LOCAL_BINARY:-}"
+# pkg.pr.new PR number or commit SHA (for temporary testing of unreleased builds)
+PR_VERSION="${VP_PR_VERSION:-}"
+# pkg.pr.new base URL for fetching tarballs and constructing dependency URLs
+PKG_PR_NEW_BASE="https://pkg.pr.new/voidzero-dev/vite-plus"
 
 # Colors for output
 RED='\033[0;31m'
@@ -842,6 +849,10 @@ main() {
   echo ""
   echo -e "Setting up VITE+..."
 
+  if [ -n "$PR_VERSION" ] && [ -n "$LOCAL_TGZ" ]; then
+    error "VP_PR_VERSION and VP_LOCAL_TGZ cannot be used together"
+  fi
+
   check_requirements
 
   local platform
@@ -857,6 +868,12 @@ main() {
     if [ "$VP_VERSION" = "latest" ] || [ "$VP_VERSION" = "test" ]; then
       VP_VERSION="local-dev"
     fi
+  elif [ -n "$PR_VERSION" ]; then
+    # pkg.pr.new mode: skip npm metadata, use a synthetic version label.
+    # Non-semver label keeps the directory out of cleanup_old_versions and
+    # makes it obvious in `~/.vite-plus/` which install is the PR build.
+    VP_VERSION="pkg-pr-new-${PR_VERSION}"
+    info "Using pkg.pr.new version: ${PR_VERSION}"
   else
     # Fetch package metadata and resolve version from npm
     get_version_from_metadata
@@ -896,10 +913,16 @@ main() {
     fi
     chmod +x "$BIN_DIR/$binary_name"
   else
-    # Download from npm registry — extract only the vp binary from CLI platform package
+    # Download CLI platform tarball — npm registry or pkg.pr.new (when PR_VERSION is set)
     get_platform_suffix "$platform"
-    local package_name="@voidzero-dev/vite-plus-cli-${PLATFORM_SUFFIX}"
-    local platform_url="${NPM_REGISTRY}/${package_name}/-/vite-plus-cli-${PLATFORM_SUFFIX}-${VP_VERSION}.tgz"
+    local platform_url
+    if [ -n "$PR_VERSION" ]; then
+      # pkg.pr.new redirects this URL to the platform tarball for the matching PR/commit
+      platform_url="${PKG_PR_NEW_BASE}/@voidzero-dev/vite-plus-cli-${PLATFORM_SUFFIX}@${PR_VERSION}"
+    else
+      local package_name="@voidzero-dev/vite-plus-cli-${PLATFORM_SUFFIX}"
+      platform_url="${NPM_REGISTRY}/${package_name}/-/vite-plus-cli-${PLATFORM_SUFFIX}-${VP_VERSION}.tgz"
+    fi
 
     # Create temp directory for extraction
     local platform_temp_dir
@@ -920,14 +943,20 @@ main() {
   # pnpm will install vite-plus and all transitive deps via `vp install`.
   # The packageManager field pins pnpm to a known-good version, ensuring
   # consistent behavior regardless of the user's global pnpm version.
+  # pkg.pr.new tarballs pre-rewrite scoped workspace deps to matching URLs by
+  # commit SHA, so pointing vite-plus at one URL pulls in a coherent PR build.
+  local vite_plus_spec="$VP_VERSION"
+  if [ -n "$PR_VERSION" ]; then
+    vite_plus_spec="${PKG_PR_NEW_BASE}@${PR_VERSION}"
+  fi
   cat > "$VERSION_DIR/package.json" <<WRAPPER_EOF
 {
   "name": "vp-global",
   "version": "$VP_VERSION",
   "private": true,
   "packageManager": "pnpm@10.33.0",
   "dependencies": {
-    "vite-plus": "$VP_VERSION"
+    "vite-plus": "$vite_plus_spec"
   }
 }
 WRAPPER_EOF