@automattic/vip 4.1.3 → 4.1.5

package/packaging/macos/preinstall

@@ -0,0 +1,33 @@
+#!/bin/sh
+set -eu
+# Installer supplies the target volume as $3. This also permits safe tests
+# against a temporary volume tree without touching system paths.
+target="${3:?missing target volume}"
+target="${target%/}"
+base="$target/usr/local/lib/vip-cli"
+pathfile="$target/etc/paths.d/vip-cli"
+fail() { echo "VIP CLI: $*" >&2; exit 1; }
+for dir in "$target/usr" "$target/usr/local" "$target/usr/local/lib" "$base" "$base/bin" "$target/etc/paths.d"; do
+  [ ! -L "$dir" ] || fail "Refusing symlinked installation path: $dir"
+done
+# /etc is a system symlink on macOS, so it is intentionally allowed above.
+if [ -e "$base" ]; then
+  marker="$base/bin/.vip-next-installer.json"
+  [ -f "$marker" ] && [ ! -L "$marker" ] || fail 'Existing directory is not owned by the VIP CLI installer.'
+  [ "$(cat "$marker")" = '{"schema":1,"manager":"pkg"}' ] || fail 'Invalid installer ownership record.'
+  [ -f "$base/package-version" ] && [ ! -L "$base/package-version" ] || fail 'Missing installed package version.'
+  old="$(cat "$base/package-version")"
+  # Reject malformed records and downgrades before overwriting any files.
+  awk -v old="$old" -v new='@PACKAGE_VERSION@' 'BEGIN {
+    if (old !~ /^[0-9]+\.[0-9]+\.[0-9]+$/) exit 1
+    split(old, a, "."); split(new, b, ".")
+    for (i=1;i<=3;i++) { if (a[i]+0>b[i]+0) exit 1; if (a[i]+0<b[i]+0) exit 0 }
+  }' || fail 'A newer version is installed or its version record is invalid. Uninstall it before installing this version.'
+fi
+if [ -e "$pathfile" ] || [ -L "$pathfile" ]; then
+  [ -f "$pathfile" ] && [ ! -L "$pathfile" ] || fail 'Refusing to replace the existing PATH entry.'
+  [ "$(cat "$pathfile")" = '/usr/local/lib/vip-cli/bin' ] || fail 'Existing PATH entry belongs to another installation.'
+fi
+for file in "$base/bin/vip-next" "$base/bin/go-search-replace" "$base/LICENSE" "$base/uninstall.sh"; do
+  [ ! -L "$file" ] || fail "Refusing to overwrite symlink: $file"
+done

package/packaging/macos/test-install.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# System installation is restricted to disposable GitHub-hosted macOS runners.
+if [ "${VIP_INSTALLER_E2E:-}" != 1 ] || [ "${GITHUB_ACTIONS:-}" != true ] || [ "${RUNNER_ENVIRONMENT:-}" != github-hosted ]; then
+  echo 'Installer lifecycle tests require VIP_INSTALLER_E2E=1 on a GitHub-hosted runner.' >&2
+  exit 1
+fi
+base=/usr/local/lib/vip-cli
+pathfile=/etc/paths.d/vip-cli
+if [ -e "$base" ] || [ -L "$base" ] || [ -e "$pathfile" ] || [ -L "$pathfile" ] || pkgutil --pkg-info com.automattic.vip-cli >/dev/null 2>&1; then
+  echo 'Refusing to test over an existing installation or receipt.' >&2
+  exit 1
+fi
+repo="$(cd "$(dirname "$0")/../.." && pwd)"
+cd "$repo"
+stage="$(mktemp -d)"
+cleanup() {
+  if [ -f "$base/bin/.vip-next-installer.json" ] && [ -f "$base/uninstall.sh" ]; then
+    sudo /bin/sh "$base/uninstall.sh"
+  fi
+  rm -rf "$stage"
+}
+trap cleanup EXIT
+case "$(uname -m)" in arm64) arch=arm64 ;; x86_64) arch=amd64 ;; *) exit 1 ;; esac
+for v in 5.0.0-alpha.0 5.0.0-alpha.1; do
+  go build -buildvcs=false -ldflags="-X main.fixtureVersion=$v" -o "$stage/fixture" ./testdata/installer-fixture
+  go build -buildvcs=false -ldflags="-X main.fixtureVersion=$v-helper" -o "$stage/helper" ./testdata/installer-fixture
+  bash packaging/macos/build-pkg.sh "$v" "$arch" "$stage/fixture" "$stage/helper" "$stage/$v.pkg"
+done
+for v in 5.0.0-alpha.0 5.0.0-alpha.1; do
+  sudo installer -pkg "$stage/$v.pkg" -target /
+  test "$("$base/bin/vip-next" --version)" = "$v"
+  test "$("$base/bin/go-search-replace" --version)" = "$v-helper"
+  "$base/bin/vip-next" --installer-owner | grep -F '.pkg'
+  test "$(cat "$pathfile")" = "$base/bin"
+  /bin/zsh -lc 'command -v vip-next' | grep -Fx "$base/bin/vip-next"
+done
+if sudo installer -pkg "$stage/5.0.0-alpha.0.pkg" -target /; then
+  echo 'Downgrade was incorrectly accepted.' >&2
+  exit 1
+fi
+test "$("$base/bin/vip-next" --version)" = 5.0.0-alpha.1
+test "$("$base/bin/go-search-replace" --version)" = 5.0.0-alpha.1-helper
+sudo /bin/sh "$base/uninstall.sh"
+test ! -e "$base"
+test ! -e "$pathfile"
+if pkgutil --pkg-info com.automattic.vip-cli >/dev/null 2>&1; then
+  echo 'Receipt remains after uninstall.' >&2
+  exit 1
+fi
+echo 'macOS installer install/upgrade/downgrade/PATH/ownership/uninstall tests passed.'

package/packaging/macos/test_package.py

@@ -0,0 +1,74 @@
+"""Build and expand real PKGs without installing anything on the host."""
+import os
+from pathlib import Path
+import platform
+import shutil
+import subprocess
+import tempfile
+import unittest
+import xml.etree.ElementTree as ET
+
+REPO = Path(__file__).resolve().parents[2]
+
+
+@unittest.skipUnless(platform.system() == "Darwin", "requires macOS packaging tools")
+class PackageTests(unittest.TestCase):
+    def test_payload_and_preinstall(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp = Path(tmp)
+            package = tmp / "VIP CLI.pkg"
+            subprocess.run(["bash", str(REPO / "packaging/macos/build-pkg.sh"),
+                            "5.0.0-beta.1", "arm64", "/bin/echo", "/usr/bin/true", str(package)],
+                           cwd=REPO, check=True)
+            verify = ["python3", str(REPO / "packaging/macos/verify-pkg.py"), str(package), "5.0.301", "arm64", "/bin/echo", "/usr/bin/true"]
+            subprocess.run(verify, check=True)
+            # Wrong input bytes must reject the completed package, even if it
+            # was successfully produced by the native packaging tools.
+            wrong_input = verify[:-1] + ["/bin/echo"]
+            result = subprocess.run(wrong_input, capture_output=True, text=True)
+            self.assertNotEqual(result.returncode, 0)
+            self.assertIn("payload differs", result.stderr)
+            expanded = tmp / "expanded"
+            subprocess.run(["pkgutil", "--expand-full", str(package), str(expanded)], check=True)
+            distribution = ET.parse(expanded / "Distribution")
+            self.assertEqual(distribution.find("options").get("hostArchitectures"), "arm64")
+            component = expanded / "vip-cli.pkg"
+            info = ET.parse(component / "PackageInfo").getroot()
+            self.assertEqual(info.get("identifier"), "com.automattic.vip-cli")
+            self.assertEqual(info.get("version"), "5.0.301")
+            payload = component / "Payload"
+            base = payload / "usr/local/lib/vip-cli"
+            self.assertEqual((base / "bin/vip-next").read_bytes(), Path("/bin/echo").read_bytes())
+            self.assertEqual((base / "bin/go-search-replace").read_bytes(), Path("/usr/bin/true").read_bytes())
+            self.assertEqual((base / "bin/.vip-next-installer.json").read_text().strip(), '{"schema":1,"manager":"pkg"}')
+            self.assertEqual((payload / "etc/paths.d/vip-cli").read_text(), "/usr/local/lib/vip-cli/bin\n")
+            self.assertEqual((base / "package-version").read_text(), "5.0.301\n")
+            self.assertTrue(os.access(base / "uninstall.sh", os.X_OK))
+            preinstall = component / "Scripts/preinstall"
+            target = tmp / "volume"
+            target.mkdir()
+
+            def check_install(ok):
+                result = subprocess.run(["/bin/sh", str(preinstall), str(package), "/", str(target)], capture_output=True, text=True)
+                self.assertEqual(result.returncode == 0, ok, result.stdout + result.stderr)
+
+            check_install(True)
+            installed = target / "usr/local/lib/vip-cli"
+            installed.mkdir(parents=True)
+            (installed / "unrelated").write_text("keep")
+            check_install(False)
+            self.assertEqual((installed / "unrelated").read_text(), "keep")
+            shutil.copytree(base, installed, dirs_exist_ok=True)
+            check_install(True)
+            (installed / "package-version").write_text("5.0.999\n")
+            check_install(False)
+            (installed / "package-version").write_text("5.0.100\n")
+            check_install(True)
+            paths = target / "etc/paths.d"
+            paths.mkdir(parents=True)
+            (paths / "vip-cli").write_text("/another/tool\n")
+            check_install(False)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/packaging/macos/uninstall.sh

@@ -0,0 +1,24 @@
+#!/bin/sh
+set -eu
+# Remove only installer-owned files. User configuration and credentials are
+# stored elsewhere and are not touched. No recursive removal is used.
+base=/usr/local/lib/vip-cli
+pathfile=/etc/paths.d/vip-cli
+[ "$(id -u)" -eq 0 ] || { echo "Run: sudo $base/uninstall.sh" >&2; exit 1; }
+for dir in /usr /usr/local /usr/local/lib "$base" "$base/bin" /etc/paths.d; do
+  [ ! -L "$dir" ] || { echo "Refusing symlinked path: $dir" >&2; exit 1; }
+done
+marker="$base/bin/.vip-next-installer.json"
+[ -f "$marker" ] && [ ! -L "$marker" ] && [ "$(cat "$marker")" = '{"schema":1,"manager":"pkg"}' ] || {
+  echo 'This directory is not owned by the VIP CLI installer.' >&2; exit 1;
+}
+if [ -e "$pathfile" ] || [ -L "$pathfile" ]; then
+  [ ! -L "$pathfile" ] && [ -f "$pathfile" ] && [ "$(cat "$pathfile")" = '/usr/local/lib/vip-cli/bin' ] || {
+    echo 'PATH entry has changed; inspect it before uninstalling.' >&2; exit 1;
+  }
+  rm "$pathfile"
+fi
+rm -f "$base/bin/vip-next" "$base/bin/go-search-replace" "$marker" "$base/package-version" "$base/LICENSE" "$base/uninstall.sh"
+rmdir "$base/bin" "$base" 2>/dev/null || true
+pkgutil --forget com.automattic.vip-cli
+echo 'VIP CLI removed. Open a new terminal to refresh PATH.'

package/packaging/macos/verify-pkg.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Verify a built PKG's payload without installing it (including signed PKGs)."""
+import argparse
+from pathlib import Path
+import subprocess
+import tempfile
+import xml.etree.ElementTree as ET
+
+
+def verify(package, numeric_version, arch, cli, helper):
+    repo = Path(__file__).resolve().parents[2]
+    with tempfile.TemporaryDirectory() as tmp:
+        expanded = Path(tmp) / "expanded"
+        subprocess.run(["pkgutil", "--expand-full", str(package), str(expanded)], check=True)
+        distribution = ET.parse(expanded / "Distribution")
+        expected_arch = {"arm64": "arm64", "amd64": "x86_64"}[arch]
+        if distribution.find("options").get("hostArchitectures") != expected_arch:
+            raise ValueError("Incorrect installer architecture restriction")
+        domains = distribution.find("domains")
+        if domains is None or domains.attrib != {"enable_anywhere": "false", "enable_currentUserHome": "false", "enable_localSystem": "true"}:
+            raise ValueError("Installer must target the local system volume only")
+        component = expanded / "vip-cli.pkg"
+        info = ET.parse(component / "PackageInfo").getroot()
+        if (info.get("identifier"), info.get("version"), info.get("install-location")) != ("com.automattic.vip-cli", numeric_version, "/"):
+            raise ValueError("Incorrect package identity/version/install location")
+        prefix = "usr/local/lib/vip-cli/"
+        expected = {
+            prefix + "bin/vip-next": Path(cli).read_bytes(),
+            prefix + "bin/go-search-replace": Path(helper).read_bytes(),
+            prefix + "bin/.vip-next-installer.json": b'{"schema":1,"manager":"pkg"}\n',
+            prefix + "package-version": (numeric_version + "\n").encode(),
+            prefix + "LICENSE": (repo / "LICENSE").read_bytes(),
+            prefix + "uninstall.sh": (repo / "packaging/macos/uninstall.sh").read_bytes(),
+            "etc/paths.d/vip-cli": b"/usr/local/lib/vip-cli/bin\n",
+        }
+        payload = component / "Payload"
+        files = {}
+        for entry in payload.rglob("*"):
+            if entry.is_symlink():
+                raise ValueError("Unexpected symlink in installer payload")
+            if entry.is_file():
+                files[entry.relative_to(payload).as_posix()] = entry.read_bytes()
+        if files != expected:
+            raise ValueError("Installer payload differs from the signed inputs or expected files")
+        for executable in ["bin/vip-next", "bin/go-search-replace", "uninstall.sh"]:
+            if not (payload / prefix / executable).stat().st_mode & 0o111:
+                raise ValueError("Installer payload is missing executable permissions")
+        preinstall = (repo / "packaging/macos/preinstall").read_text().replace("@PACKAGE_VERSION@", numeric_version)
+        if (component / "Scripts/preinstall").read_text() != preinstall:
+            raise ValueError("Installer preinstall script differs from expected version")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("package")
+    parser.add_argument("numeric_version")
+    parser.add_argument("arch", choices=["amd64", "arm64"])
+    parser.add_argument("cli")
+    parser.add_argument("helper")
+    args = parser.parse_args()
+    verify(args.package, args.numeric_version, args.arch, args.cli, args.helper)

package/packaging/windows/build-msi.ps1

@@ -0,0 +1,153 @@
+#Requires -Version 5.1
+[CmdletBinding()]
+param(
+  [Parameter(Mandatory = $true)][ValidateNotNullOrEmpty()][string]$Version,
+  [Parameter(Mandatory = $true)][ValidateNotNullOrEmpty()][string]$CLI,
+  [Parameter(Mandatory = $true)][ValidateNotNullOrEmpty()][string]$Helper,
+  [Parameter(Mandatory = $true)][ValidateNotNullOrEmpty()][string]$Output
+)
+
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+
+$wixVersion = '5.0.2'
+$uiExtension = "WixToolset.UI.wixext/$wixVersion"
+$repoRoot = [IO.Path]::GetFullPath((Join-Path $PSScriptRoot '..\..'))
+$wixSource = Join-Path $PSScriptRoot 'vip-next.wxs'
+$licenseSource = Join-Path $repoRoot 'LICENSE'
+$tempRoot = Join-Path ([IO.Path]::GetTempPath()) ("vip-cli-msi-build-{0}" -f [Guid]::NewGuid().ToString('N'))
+$stageDir = Join-Path $tempRoot 'stage'
+$toolDir = Join-Path $tempRoot 'tools'
+$originalDotnetRollForward = [Environment]::GetEnvironmentVariable('DOTNET_ROLL_FORWARD', 'Process')
+
+function Resolve-InputFile([string]$Path, [string]$Label) {
+  if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
+    throw "$Label does not exist or is not a file: $Path"
+  }
+  return (Resolve-Path -LiteralPath $Path).ProviderPath
+}
+
+function Invoke-External([string]$Command, [string[]]$Arguments, [string]$Failure) {
+  & $Command @Arguments
+  if ($LASTEXITCODE -ne 0) { throw "$Failure (exit $LASTEXITCODE)" }
+}
+
+function Convert-LicenseToRtf([string]$Source, [string]$Destination) {
+  $body = [IO.File]::ReadAllText($Source)
+  $body = $body.Replace('\', '\\').Replace('{', '\{').Replace('}', '\}')
+  $body = $body.Replace("`r`n", "`n").Replace("`r", "`n").Replace("`n", "\par`r`n")
+  $rtf = '{\rtf1\ansi\deff0{\fonttbl{\f0\fnil\fcharset0 Segoe UI;}}\viewkind4\uc1\pard\f0\fs18 ' + $body + '}'
+  [IO.File]::WriteAllText($Destination, $rtf, (New-Object Text.ASCIIEncoding))
+}
+
+function Get-ProductCode([string]$NumericVersion) {
+  $seed = "vip-cli-msi:{9D089A27-73D9-4A31-91E1-A21A37ED94F1}:$NumericVersion"
+  $sha256 = [Security.Cryptography.SHA256]::Create()
+  try {
+    $hash = $sha256.ComputeHash([Text.Encoding]::UTF8.GetBytes($seed))
+  } finally {
+    $sha256.Dispose()
+  }
+  $hash[6] = ($hash[6] -band 0x0f) -bor 0x50
+  $hash[8] = ($hash[8] -band 0x3f) -bor 0x80
+  $hex = ([BitConverter]::ToString($hash, 0, 16)).Replace('-', '')
+  return '{' + $hex.Substring(0, 8) + '-' + $hex.Substring(8, 4) + '-' +
+    $hex.Substring(12, 4) + '-' + $hex.Substring(16, 4) + '-' + $hex.Substring(20, 12) + '}'
+}
+
+$cliPath = Resolve-InputFile $CLI 'CLI executable'
+$helperPath = Resolve-InputFile $Helper 'Helper executable'
+$licensePath = Resolve-InputFile $licenseSource 'Repository license'
+$wixSourcePath = Resolve-InputFile $wixSource 'WiX source'
+
+$outputFullPath = [IO.Path]::GetFullPath($Output)
+$outputDirectory = Split-Path -Parent $outputFullPath
+if (-not $outputDirectory) { $outputDirectory = (Get-Location).ProviderPath }
+New-Item -ItemType Directory -Force -Path $outputDirectory | Out-Null
+$outputDirectory = (Resolve-Path -LiteralPath $outputDirectory).ProviderPath
+$outputFullPath = Join-Path $outputDirectory (Split-Path -Leaf $outputFullPath)
+
+$dotnet = Get-Command dotnet -ErrorAction SilentlyContinue
+if (-not $dotnet) {
+  throw 'Building the MSI requires the .NET 8 SDK or newer. Install it and rerun packaging/windows/build-msi.ps1.'
+}
+$dotnetVersion = (& $dotnet.Source --version | Out-String).Trim()
+if ($LASTEXITCODE -ne 0 -or $dotnetVersion -notmatch '^(\d+)\.') {
+  throw 'Unable to determine the installed .NET SDK version.'
+}
+if ([int]$Matches[1] -lt 8) {
+  throw "Building the MSI requires the .NET 8 SDK or newer; found $dotnetVersion."
+}
+
+$go = Get-Command go -ErrorAction SilentlyContinue
+if (-not $go) { throw 'Building the MSI requires Go to resolve the shared numeric installer version.' }
+
+New-Item -ItemType Directory -Force -Path $stageDir, $toolDir | Out-Null
+try {
+  Push-Location $repoRoot
+  try {
+    $numericVersion = (& $go.Source run -mod=mod ./cmd/installer-version $Version | Out-String).Trim()
+    if ($LASTEXITCODE -ne 0 -or -not $numericVersion) {
+      throw "installer-version failed for $Version"
+    }
+  } finally {
+    Pop-Location
+  }
+
+  $stagedCli = Join-Path $stageDir 'vip-next.exe'
+  $stagedHelper = Join-Path $stageDir 'go-search-replace.exe'
+  Copy-Item -LiteralPath $cliPath -Destination $stagedCli
+  Copy-Item -LiteralPath $helperPath -Destination $stagedHelper
+  if ((Get-FileHash -LiteralPath $cliPath -Algorithm SHA256).Hash -ne
+      (Get-FileHash -LiteralPath $stagedCli -Algorithm SHA256).Hash) {
+    throw 'Staging modified the CLI executable bytes.'
+  }
+  if ((Get-FileHash -LiteralPath $helperPath -Algorithm SHA256).Hash -ne
+      (Get-FileHash -LiteralPath $stagedHelper -Algorithm SHA256).Hash) {
+    throw 'Staging modified the helper executable bytes.'
+  }
+
+  Copy-Item -LiteralPath $licensePath -Destination (Join-Path $stageDir 'LICENSE.txt')
+  [IO.File]::WriteAllText(
+    (Join-Path $stageDir '.vip-next-installer.json'),
+    '{"schema":1,"manager":"msi"}',
+    (New-Object Text.UTF8Encoding($false))
+  )
+  $licenseRtf = Join-Path $stageDir 'LICENSE.rtf'
+  Convert-LicenseToRtf $licensePath $licenseRtf
+
+  $env:DOTNET_ROLL_FORWARD = 'Major'
+  Invoke-External $dotnet.Source @(
+    'tool', 'install', 'wix', '--tool-path', $toolDir, '--version', $wixVersion
+  ) 'Installing the pinned WiX tool failed'
+  $wix = Join-Path $toolDir 'wix.exe'
+  if (-not (Test-Path -LiteralPath $wix -PathType Leaf)) {
+    throw "Pinned WiX executable was not installed at $wix"
+  }
+
+  Push-Location $tempRoot
+  try {
+    Invoke-External $wix @('extension', 'add', $uiExtension) 'Installing the pinned WiX UI extension failed'
+    Invoke-External $wix @(
+      'build', $wixSourcePath,
+      '-arch', 'x64',
+      '-ext', $uiExtension,
+      '-d', "NumericVersion=$numericVersion",
+      '-d', "ProductCode=$(Get-ProductCode $numericVersion)",
+      '-d', "StageDir=$stageDir",
+      '-d', "LicenseRtf=$licenseRtf",
+      '-out', $outputFullPath
+    ) 'WiX MSI build failed'
+  } finally {
+    Pop-Location
+  }
+
+  if (-not (Test-Path -LiteralPath $outputFullPath -PathType Leaf)) {
+    throw "WiX reported success but did not create $outputFullPath"
+  }
+} finally {
+  [Environment]::SetEnvironmentVariable('DOTNET_ROLL_FORWARD', $originalDotnetRollForward, 'Process')
+  if (Test-Path -LiteralPath $tempRoot) {
+    Remove-Item -LiteralPath $tempRoot -Recurse -Force
+  }
+}

package/packaging/windows/test-msi.ps1

@@ -0,0 +1,225 @@
+#Requires -Version 5.1
+[CmdletBinding()]
+param()
+
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+
+if ([Environment]::OSVersion.Platform -ne [PlatformID]::Win32NT) {
+  throw 'The MSI lifecycle test must run on a disposable Windows CI runner.'
+}
+if ($env:VIP_INSTALLER_E2E -ne '1' -or
+    $env:GITHUB_ACTIONS -notmatch '^(?i:true)$' -or
+    $env:RUNNER_ENVIRONMENT -notmatch '^(?i:github-hosted)$') {
+  throw 'Refusing to modify the host. This test requires VIP_INSTALLER_E2E=1 on a GitHub-hosted Actions runner.'
+}
+
+$identity = [Security.Principal.WindowsIdentity]::GetCurrent()
+$principal = New-Object Security.Principal.WindowsPrincipal($identity)
+if (-not $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) {
+  throw 'The MSI lifecycle test requires an elevated disposable Windows CI runner.'
+}
+
+$repoRoot = [IO.Path]::GetFullPath((Join-Path $PSScriptRoot '..\..'))
+$buildScript = Join-Path $PSScriptRoot 'build-msi.ps1'
+$verifyScript = Join-Path $PSScriptRoot 'verify-msi.ps1'
+$installDir = Join-Path $env:ProgramFiles 'Automattic\VIP CLI'
+$markerPath = Join-Path $installDir '.vip-next-installer.json'
+$pathTarget = $installDir.TrimEnd('\')
+$initialMachinePath = [Environment]::GetEnvironmentVariable('Path', 'Machine')
+$tempRoot = Join-Path ([IO.Path]::GetTempPath()) ("vip-cli-msi-e2e-{0}" -f [Guid]::NewGuid().ToString('N'))
+$logsDir = Join-Path $tempRoot 'logs'
+$testInstalledProduct = $false
+
+function Test-PathContainsTarget([AllowNull()][string]$PathValue) {
+  if ($null -eq $PathValue) { return $false }
+  foreach ($entry in $PathValue.Split(';', [StringSplitOptions]::RemoveEmptyEntries)) {
+    if ([StringComparer]::OrdinalIgnoreCase.Equals($entry.Trim().TrimEnd('\'), $pathTarget)) {
+      return $true
+    }
+  }
+  return $false
+}
+
+function Get-VipCliUninstallEntries {
+  $roots = @(
+    'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*',
+    'HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*'
+  )
+  return @(Get-ItemProperty -Path $roots -ErrorAction SilentlyContinue | Where-Object {
+    $displayName = $_.PSObject.Properties['DisplayName']
+    $installLocation = $_.PSObject.Properties['InstallLocation']
+    ($displayName -and $displayName.Value -eq 'VIP CLI') -or
+    ($installLocation -and $installLocation.Value -and
+      [StringComparer]::OrdinalIgnoreCase.Equals($installLocation.Value.TrimEnd('\'), $pathTarget))
+  })
+}
+
+function Invoke-MsiExec {
+  param(
+    [Parameter(Mandatory = $true)][ValidateSet('install', 'uninstall')][string]$Action,
+    [Parameter(Mandatory = $true)][string]$Target,
+    [Parameter(Mandatory = $true)][string]$Log,
+    [int[]]$ExpectedExitCodes = @(0)
+  )
+
+  $verb = if ($Action -eq 'install') { '/i' } else { '/x' }
+  $arguments = @($verb, "`"$Target`"", '/qn', '/norestart', '/l*v', "`"$Log`"")
+  $process = Start-Process -FilePath "$env:SystemRoot\System32\msiexec.exe" `
+    -ArgumentList $arguments `
+    -Wait -PassThru
+  if ($ExpectedExitCodes -notcontains $process.ExitCode) {
+    if (Test-Path -LiteralPath $Log) { Get-Content -LiteralPath $Log | Write-Host }
+    throw "msiexec $Action exited $($process.ExitCode); expected $($ExpectedExitCodes -join ', '). Log: $Log"
+  }
+  return $process.ExitCode
+}
+
+function New-FixtureExecutable {
+  param(
+    [Parameter(Mandatory = $true)][string]$Name,
+    [Parameter(Mandatory = $true)][string]$Version,
+    [Parameter(Mandatory = $true)][string]$Output
+  )
+
+  Push-Location $repoRoot
+  try {
+    $env:CGO_ENABLED = '0'
+    $env:GOOS = 'windows'
+    $env:GOARCH = 'amd64'
+    & go build -buildvcs=false -trimpath `
+      -ldflags "-s -w -X main.fixtureVersion=$Version" `
+      -o $Output ./testdata/installer-fixture
+    if ($LASTEXITCODE -ne 0) { throw "go build failed for $Name $Version" }
+  } finally {
+    Pop-Location
+  }
+}
+
+function Assert-InstalledPayload {
+  param(
+    [Parameter(Mandatory = $true)][string]$Version,
+    [Parameter(Mandatory = $true)][string]$ExpectedCli,
+    [Parameter(Mandatory = $true)][string]$ExpectedHelper
+  )
+
+  $installedCli = Join-Path $installDir 'vip-next.exe'
+  $installedHelper = Join-Path $installDir 'go-search-replace.exe'
+  foreach ($pair in @(@($installedCli, $ExpectedCli), @($installedHelper, $ExpectedHelper))) {
+    if (-not (Test-Path -LiteralPath $pair[0] -PathType Leaf)) { throw "Missing installed file: $($pair[0])" }
+    $actualHash = (Get-FileHash -LiteralPath $pair[0] -Algorithm SHA256).Hash
+    $expectedHash = (Get-FileHash -LiteralPath $pair[1] -Algorithm SHA256).Hash
+    if ($actualHash -ne $expectedHash) { throw "Installed bytes differ for $($pair[0])" }
+  }
+
+  $cliVersion = (& $installedCli --version | Out-String).Trim()
+  if ($LASTEXITCODE -ne 0 -or $cliVersion -ne $Version) {
+    throw "Unexpected vip-next version output: $cliVersion"
+  }
+  $helperVersion = (& $installedHelper --version | Out-String).Trim()
+  if ($LASTEXITCODE -ne 0 -or $helperVersion -ne "${Version}-helper") {
+    throw "Unexpected go-search-replace version output: $helperVersion"
+  }
+
+  if ((Get-Content -LiteralPath $markerPath -Raw) -ne '{"schema":1,"manager":"msi"}') {
+    throw 'Installer marker contents do not match the ownership contract.'
+  }
+  $installedLicense = Join-Path $installDir 'LICENSE.txt'
+  if (-not (Test-Path -LiteralPath $installedLicense -PathType Leaf) -or
+      (Get-FileHash -LiteralPath $installedLicense -Algorithm SHA256).Hash -ne
+      (Get-FileHash -LiteralPath (Join-Path $repoRoot 'LICENSE') -Algorithm SHA256).Hash) {
+    throw 'Installed license does not match the repository license.'
+  }
+  if (-not (Test-PathContainsTarget ([Environment]::GetEnvironmentVariable('Path', 'Machine')))) {
+    throw "The system PATH does not contain $installDir"
+  }
+  $owner = (& $installedCli --installer-owner | Out-String).Trim()
+  if ($LASTEXITCODE -ne 0 -or $owner -notmatch '(?i)\.msi') {
+    throw "Installed fixture did not report MSI ownership instructions: $owner"
+  }
+}
+
+if (Get-VipCliUninstallEntries) { throw 'Refusing to run with an existing VIP CLI MSI installation.' }
+if (Test-Path -LiteralPath $installDir) { throw "Refusing to run because $installDir already exists." }
+if (Test-Path -LiteralPath $markerPath) { throw "Refusing to run because $markerPath already exists." }
+if (Test-PathContainsTarget $initialMachinePath) { throw "Refusing to run because system PATH already contains $installDir." }
+if (-not (Get-Command go -ErrorAction SilentlyContinue)) { throw 'Go is required to build the lifecycle fixture executables.' }
+
+New-Item -ItemType Directory -Force -Path $logsDir | Out-Null
+
+try {
+  $versions = @('5.0.0-alpha.0', '5.0.0-alpha.1')
+  $artifacts = @{}
+  foreach ($version in $versions) {
+    $versionDir = Join-Path $tempRoot ($version -replace '[^A-Za-z0-9.-]', '-')
+    New-Item -ItemType Directory -Force -Path $versionDir | Out-Null
+    $cli = Join-Path $versionDir 'vip-next.exe'
+    $helper = Join-Path $versionDir 'go-search-replace.exe'
+    $msi = Join-Path $versionDir 'vip-next-windows-amd64.msi'
+    New-FixtureExecutable -Name 'vip-next' -Version $version -Output $cli
+    New-FixtureExecutable -Name 'go-search-replace' -Version "${version}-helper" -Output $helper
+    & $buildScript -Version $version -CLI $cli -Helper $helper -Output $msi
+    if ($LASTEXITCODE -ne 0) { throw "build-msi.ps1 failed for $version" }
+    & $verifyScript -MSI $msi -CLI $cli -Helper $helper
+    if ($LASTEXITCODE -ne 0) { throw "verify-msi.ps1 failed for $version" }
+    $artifacts[$version] = @{ CLI = $cli; Helper = $helper; MSI = $msi }
+  }
+
+  $alpha0 = $artifacts['5.0.0-alpha.0']
+  $alpha1 = $artifacts['5.0.0-alpha.1']
+  Invoke-MsiExec -Action install -Target $alpha0.MSI -Log (Join-Path $logsDir 'install-alpha.0.log')
+  $testInstalledProduct = $true
+  Assert-InstalledPayload -Version '5.0.0-alpha.0' -ExpectedCli $alpha0.CLI -ExpectedHelper $alpha0.Helper
+
+  Invoke-MsiExec -Action install -Target $alpha1.MSI -Log (Join-Path $logsDir 'upgrade-alpha.1.log')
+  Assert-InstalledPayload -Version '5.0.0-alpha.1' -ExpectedCli $alpha1.CLI -ExpectedHelper $alpha1.Helper
+
+  $downgradeExit = Invoke-MsiExec -Action install -Target $alpha0.MSI `
+    -Log (Join-Path $logsDir 'downgrade-alpha.0.log') -ExpectedExitCodes @(1603, 1638)
+  if ($downgradeExit -eq 0) { throw 'Downgrade unexpectedly succeeded.' }
+  Assert-InstalledPayload -Version '5.0.0-alpha.1' -ExpectedCli $alpha1.CLI -ExpectedHelper $alpha1.Helper
+
+  $entry = @(Get-VipCliUninstallEntries)
+  if ($entry.Count -ne 1 -or $entry[0].PSChildName -notmatch '^\{[0-9A-Fa-f-]{36}\}$') {
+    throw "Expected one uninstall registry entry, found $($entry.Count)."
+  }
+  Invoke-MsiExec -Action uninstall -Target $entry[0].PSChildName -Log (Join-Path $logsDir 'uninstall.log')
+  $testInstalledProduct = $false
+
+  foreach ($path in @(
+    (Join-Path $installDir 'vip-next.exe'),
+    (Join-Path $installDir 'go-search-replace.exe'),
+    (Join-Path $installDir 'LICENSE.txt'),
+    $markerPath
+  )) {
+    if (Test-Path -LiteralPath $path) { throw "Uninstall left managed file behind: $path" }
+  }
+  $finalMachinePath = [Environment]::GetEnvironmentVariable('Path', 'Machine')
+  if ($finalMachinePath -ne $initialMachinePath) {
+    throw 'Uninstall did not restore the exact initial system PATH.'
+  }
+  if (Get-VipCliUninstallEntries) { throw 'Uninstall registry entry remains after uninstall.' }
+} catch {
+  Get-ChildItem -LiteralPath $logsDir -Filter '*.log' -ErrorAction SilentlyContinue | ForEach-Object {
+    Write-Host "--- MSI log: $($_.FullName)"
+    Get-Content -LiteralPath $_.FullName | Write-Host
+  }
+  throw
+} finally {
+  if ($testInstalledProduct) {
+    $entries = @(Get-VipCliUninstallEntries)
+    foreach ($entry in $entries) {
+      if ($entry.PSChildName -match '^\{[0-9A-Fa-f-]{36}\}$') {
+        try {
+          Invoke-MsiExec -Action uninstall -Target $entry.PSChildName `
+            -Log (Join-Path $logsDir 'cleanup-uninstall.log') -ExpectedExitCodes @(0, 1605, 3010)
+        } catch {
+          Write-Warning "Cleanup uninstall failed: $_"
+        }
+      }
+    }
+  }
+  if (Test-Path -LiteralPath $tempRoot) {
+    Remove-Item -LiteralPath $tempRoot -Recurse -Force
+  }
+}