feat: pin the install script to the requested version (#127)

The action always installed vp with the latest install.sh, so an
install-script change like the XDG directory layout in
voidzero-dev/vite-plus#2346 could break installing older versions.

The script is now fetched from the git ref matching the requested
version:

- Exact versions (`0.2.9`, `0.1.21-alpha.7`): the `v<version>` release
tag on raw.githubusercontent.com, with jsDelivr as an independent mirror
(both verified to serve `packages/cli/install.sh` back to v0.1.0).
- pkg.pr.new preview builds (`0.0.0-commit.<sha>`): the script from that
exact commit, so a preview build always installs with the script it was
built with.
- Dist-tags (`latest`, `next`): unchanged, the latest script matches
whatever they resolve to.

If all pinned sources fail (missing tag, mirror outage), the install
warns and falls back to the latest script, so availability degrades to
the previous behavior instead of blocking CI. Worst case for pinned
versions is 8 attempts across 4 URLs instead of 4 across 2.

The URL selection is shared in `src/ci/install-script-urls.ts` and
applied to the GitHub action, the Azure runtime, and the GitLab
bootstrap.

Author: fengmk2

.github/workflows/test.yml

@@ -41,6 +41,47 @@ jobs:
       - name: Verify installation
         run: vp --version
 
+  test-preview-build:
+    # End-to-end coverage for the commit-pinned install path: resolve the
+    # newest pkg.pr.new preview build (0.0.0-commit.<sha>) from the registry
+    # bridge and install it through the version input, so the install script
+    # is fetched from that build's commit instead of main.
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    # The version assertion below must see the bridge-resolved build. Pin
+    # VP_PR_VERSION to "" so a manual pr_version dispatch can't override it.
+    env:
+      VP_PR_VERSION: ""
+    steps:
+      - uses: taiki-e/checkout-action@7d1e50e93dc4fb3bba58f85018fadf77898aee8b # v1.4.2
+
+      - name: Resolve the newest preview build from the registry bridge
+        id: preview
+        shell: bash
+        run: |
+          version="$(curl -fsSL --connect-timeout 5 --max-time 15 https://registry-bridge.viteplus.dev/vite-plus \
+            | jq -r '.time | to_entries | map(select(.key | test("^0\\.0\\.0-commit\\.[0-9a-f]{40}$"))) | max_by(.value).key')"
+          if [[ ! "$version" =~ ^0\.0\.0-commit\.[0-9a-f]{40}$ ]]; then
+            echo "Unexpected preview build version from the registry bridge: ${version}" >&2
+            exit 1
+          fi
+          echo "Resolved preview build: ${version}"
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+
+      - name: Setup Vite+
+        uses: ./
+        with:
+          version: ${{ steps.preview.outputs.version }}
+          run-install: false
+          cache: false
+
+      - name: Verify installation
+        shell: bash
+        run: vp --version | grep -F "${{ steps.preview.outputs.version }}"
+
   test-node-version:
     strategy:
       fail-fast: false

dist/azure/index.mjs

@@ -53,13 +53,10 @@ setup_vp_install_viteplus_from() {
   fi
 }
 
-setup_vp_install_viteplus() {
+setup_vp_try_install_urls() {
   setup_vp_round=1
   while [ "$setup_vp_round" -le 2 ]; do
-    for setup_vp_url in \
-      "https://viteplus.dev/install.sh" \
-      "https://raw.githubusercontent.com/voidzero-dev/vite-plus/main/packages/cli/install.sh"
-    do
+    for setup_vp_url in "$@"; do
       echo "setup-vp: installing Vite+ ${SETUP_VP_VERSION} from ${setup_vp_url}"
       if setup_vp_install_viteplus_from "$setup_vp_url"; then
         return 0
@@ -72,6 +69,33 @@ setup_vp_install_viteplus() {
     fi
   done
 
+  return 1
+}
+
+# Prefer the install script pinned to the requested version's git ref (the
+# release tag, or the commit itself for a pkg.pr.new preview build): the
+# latest script tracks the latest CLI and can break installs of older
+# versions. Fall back to the latest script only after all pinned sources fail.
+# A missing tag or a full mirror outage then gives the previous behavior
+# instead of blocking CI.
+setup_vp_install_viteplus() {
+  if [ -n "$setup_vp_pinned_ref" ]; then
+    if setup_vp_try_install_urls \
+      "https://raw.githubusercontent.com/voidzero-dev/vite-plus/${setup_vp_pinned_ref}/packages/cli/install.sh" \
+      "https://cdn.jsdelivr.net/gh/voidzero-dev/vite-plus@${setup_vp_pinned_ref}/packages/cli/install.sh"
+    then
+      return 0
+    fi
+    echo "setup-vp: could not fetch the install script pinned to Vite+ ${SETUP_VP_VERSION}. Falling back to the latest install script. The latest script may not be compatible with ${SETUP_VP_VERSION}." >&2
+  fi
+
+  if setup_vp_try_install_urls \
+    "https://viteplus.dev/install.sh" \
+    "https://raw.githubusercontent.com/voidzero-dev/vite-plus/main/packages/cli/install.sh"
+  then
+    return 0
+  fi
+
   echo "setup-vp: failed to install Vite+ after retrying all installer URLs." >&2
   return 1
 }
@@ -97,6 +121,17 @@ setup_vp_pr_version=""
 if [[ "$SETUP_VP_VERSION" =~ ^0\.0\.0-commit\.([0-9a-fA-F]{40})$ ]]; then
   setup_vp_pr_version="${BASH_REMATCH[1]}"
 fi
+
+# Git ref that serves the install script for the requested version: the
+# preview build's commit, or the `v<version>` release tag for an exact
+# version. Dist-tags like "latest" do not map to a ref and keep the latest
+# script.
+setup_vp_pinned_ref=""
+if [ -n "$setup_vp_pr_version" ]; then
+  setup_vp_pinned_ref="$(printf "%s" "$setup_vp_pr_version" | tr '[:upper:]' '[:lower:]')"
+elif [[ "$SETUP_VP_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
+  setup_vp_pinned_ref="v${SETUP_VP_VERSION}"
+fi
 setup_vp_install_tmp="$(mktemp "${TMPDIR:-/tmp}/setup-vp-install.XXXXXX")"
 setup_vp_runtime_tmp="$(mktemp "${TMPDIR:-/tmp}/setup-vp-gitlab-runtime.XXXXXX.mjs")"
 trap 'rm -f "$setup_vp_install_tmp" "$setup_vp_runtime_tmp"' EXIT

dist/index.mjs

@@ -37,6 +37,29 @@ describe("installVitePlus", () => {
     expect(runInstall.mock.calls[1]?.[0]).toContain("install.sh");
   });
 
+  it("installs exact versions with the release-tag script before the latest script", async () => {
+    // Fail every attempt so the full URL order is observable.
+    const runInstall = vi.fn((_url: string) => 1);
+    const warnings: string[] = [];
+
+    await expect(
+      installVitePlus("0.2.9", {
+        platform: "linux",
+        env: { PATH: "" },
+        prependPath: () => undefined,
+        sleep: async () => undefined,
+        runInstall,
+        logWarningFn: (message) => warnings.push(message),
+      }),
+    ).rejects.toThrow(/after 8 attempts across 4 URL\(s\)/);
+
+    const urls = runInstall.mock.calls.map((call) => call[0]);
+    expect(urls[0]).toContain("/v0.2.9/packages/cli/install.sh");
+    expect(urls[1]).toContain("jsdelivr");
+    expect(urls[4]).toBe("https://viteplus.dev/install.sh");
+    expect(warnings.some((message) => message.includes("Falling back to the latest"))).toBe(true);
+  });
+
   it("routes pkg.pr.new commit builds through VP_PR_VERSION", async () => {
     const runInstall = vi.fn(() => 0);
     const sha = "a".repeat(40);

gitlab/bootstrap.sh

@@ -2,32 +2,20 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { spawnSync } from "node:child_process";
+import { getInstallScriptUrls, pkgPrNewCommitSha } from "../ci/install-script-urls.js";
 import { logWarning } from "./commands.js";
 
-const INSTALL_URLS_SH = [
-  "https://viteplus.dev/install.sh",
-  "https://raw.githubusercontent.com/voidzero-dev/vite-plus/main/packages/cli/install.sh",
-];
-const INSTALL_URLS_PS1 = [
-  "https://viteplus.dev/install.ps1",
-  "https://raw.githubusercontent.com/voidzero-dev/vite-plus/main/packages/cli/install.ps1",
-];
 const INSTALL_MAX_ROUNDS = 2;
 const INSTALL_RETRY_DELAY_MS = 2000;
 const CURL_TIMEOUT_FLAGS = "--connect-timeout 5 --max-time 15";
 const PWSH_TIMEOUT_SEC = 15;
-const PKG_PR_NEW_COMMIT_RE = /^0\.0\.0-commit\.([0-9a-f]{40})$/i;
 
 export function getVitePlusHome(platform: NodeJS.Platform = process.platform): string {
   const home =
     platform === "win32" ? process.env.USERPROFILE || homedir() : process.env.HOME || homedir();
   return join(home, ".vite-plus");
 }
 
-function pkgPrNewCommitSha(version: string): string | undefined {
-  return version.match(PKG_PR_NEW_COMMIT_RE)?.[1];
-}
-
 function runInstallCommand(
   url: string,
   env: Record<string, string>,
@@ -93,40 +81,63 @@ export async function installVitePlus(
     env.VP_NODE_MANAGER = options.nodeManager ? "yes" : "no";
   }
 
-  const urls = platform === "win32" ? INSTALL_URLS_PS1 : INSTALL_URLS_SH;
-  const maxAttempts = INSTALL_MAX_ROUNDS * urls.length;
+  // Prefer the install script pinned to the requested version's git ref. Fall
+  // back to the latest script only after all pinned sources fail (see
+  // ../ci/install-script-urls.ts for the rationale).
+  const { pinned, latest } = getInstallScriptUrls(version, platform);
+  const totalUrls = pinned.length + latest.length;
+  const maxAttempts = INSTALL_MAX_ROUNDS * totalUrls;
   let failureReason = "";
   let attempt = 0;
 
-  for (let round = 0; round < INSTALL_MAX_ROUNDS; round += 1) {
-    for (const url of urls) {
-      attempt += 1;
-      try {
-        const exitCode = runInstall(url, env, platform);
-        if (exitCode === 0) {
-          const binDir = join(getVitePlusHome(platform), "bin");
-          if (!targetEnv.PATH?.includes(binDir)) {
-            const separator = platform === "win32" ? ";" : ":";
-            targetEnv.PATH = `${binDir}${separator}${targetEnv.PATH || ""}`;
-            prependPath?.(binDir);
-          }
-          return;
+  const tryUrls = async (urls: string[]): Promise<boolean> => {
+    for (let round = 0; round < INSTALL_MAX_ROUNDS; round += 1) {
+      for (const url of urls) {
+        attempt += 1;
+        try {
+          const exitCode = runInstall(url, env, platform);
+          if (exitCode === 0) return true;
+          failureReason = `exit code ${exitCode}`;
+        } catch (error) {
+          failureReason = error instanceof Error ? error.message : String(error);
         }
-        failureReason = `exit code ${exitCode}`;
-      } catch (error) {
-        failureReason = error instanceof Error ? error.message : String(error);
-      }
 
-      if (attempt < maxAttempts) {
-        warn(
-          `setup-vp: failed to install Vite+ from ${url} (${failureReason}). Retrying in ${INSTALL_RETRY_DELAY_MS}ms... (attempt ${attempt + 1}/${maxAttempts})`,
-        );
-        await delay(INSTALL_RETRY_DELAY_MS);
+        if (attempt < maxAttempts) {
+          warn(
+            `setup-vp: failed to install Vite+ from ${url} (${failureReason}). Retrying in ${INSTALL_RETRY_DELAY_MS}ms... (attempt ${attempt + 1}/${maxAttempts})`,
+          );
+          await delay(INSTALL_RETRY_DELAY_MS);
+        }
       }
     }
+    return false;
+  };
+
+  const ensureBinInPath = (): void => {
+    const binDir = join(getVitePlusHome(platform), "bin");
+    if (!targetEnv.PATH?.includes(binDir)) {
+      const separator = platform === "win32" ? ";" : ":";
+      targetEnv.PATH = `${binDir}${separator}${targetEnv.PATH || ""}`;
+      prependPath?.(binDir);
+    }
+  };
+
+  if (pinned.length > 0) {
+    if (await tryUrls(pinned)) {
+      ensureBinInPath();
+      return;
+    }
+    warn(
+      `setup-vp: could not fetch the install script pinned to Vite+ ${version}. Falling back to the latest install script. The latest script may not be compatible with ${version}.`,
+    );
+  }
+
+  if (await tryUrls(latest)) {
+    ensureBinInPath();
+    return;
   }
 
   throw new Error(
-    `Failed to install Vite+ after ${maxAttempts} attempts across ${urls.length} URL(s): ${failureReason}`,
+    `Failed to install Vite+ after ${maxAttempts} attempts across ${totalUrls} URL(s): ${failureReason}`,
   );
 }

src/azure/install-viteplus.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from "vite-plus/test";
+import { getInstallScriptUrls, pkgPrNewCommitSha } from "./install-script-urls.js";
+
+const commitSha = "7d848b3da1987fa60b4cf18487fcc36a2a697e94";
+
+describe("pkgPrNewCommitSha", () => {
+  it("extracts the SHA from a pkg.pr.new commit build", () => {
+    expect(pkgPrNewCommitSha(`0.0.0-commit.${commitSha}`)).toBe(commitSha);
+  });
+
+  it("returns undefined for regular versions and near-miss SHA lengths", () => {
+    expect(pkgPrNewCommitSha("0.2.9")).toBeUndefined();
+    expect(pkgPrNewCommitSha(`0.0.0-commit.${commitSha.slice(0, 39)}`)).toBeUndefined();
+  });
+});
+
+describe("getInstallScriptUrls", () => {
+  it("pins an exact version to its release tag, with jsDelivr as mirror", () => {
+    const { pinned, latest } = getInstallScriptUrls("0.2.9", "linux");
+    expect(pinned).toEqual([
+      "https://raw.githubusercontent.com/voidzero-dev/vite-plus/v0.2.9/packages/cli/install.sh",
+      "https://cdn.jsdelivr.net/gh/voidzero-dev/vite-plus@v0.2.9/packages/cli/install.sh",
+    ]);
+    expect(latest).toEqual([
+      "https://viteplus.dev/install.sh",
+      "https://raw.githubusercontent.com/voidzero-dev/vite-plus/main/packages/cli/install.sh",
+    ]);
+  });
+
+  it("pins prerelease versions to their release tag", () => {
+    const { pinned } = getInstallScriptUrls("0.1.21-alpha.7", "linux");
+    expect(pinned[0]).toContain("/v0.1.21-alpha.7/");
+  });
+
+  it("pins pkg.pr.new commit builds to the commit, lowercasing the SHA", () => {
+    const { pinned } = getInstallScriptUrls(`0.0.0-commit.${commitSha.toUpperCase()}`, "linux");
+    expect(pinned).toEqual([
+      `https://raw.githubusercontent.com/voidzero-dev/vite-plus/${commitSha}/packages/cli/install.sh`,
+      `https://cdn.jsdelivr.net/gh/voidzero-dev/vite-plus@${commitSha}/packages/cli/install.sh`,
+    ]);
+  });
+
+  it.each(["latest", "next", "^0.2.0", "0.2", "0.2.x", "0.2.9+build.5", ""])(
+    "does not pin %j",
+    (version) => {
+      const { pinned, latest } = getInstallScriptUrls(version, "linux");
+      expect(pinned).toEqual([]);
+      expect(latest).toHaveLength(2);
+    },
+  );
+
+  it("uses install.ps1 on Windows for both pinned and latest URLs", () => {
+    const { pinned, latest } = getInstallScriptUrls("0.2.9", "win32");
+    for (const url of [...pinned, ...latest]) {
+      expect(url).toMatch(/install\.ps1$/);
+    }
+  });
+});