@pablozaiden/installer 0.0.10 → 0.2.0

package/README.md

@@ -23,6 +23,14 @@ Supported targets are:
 | --- | --- |
 | `linux` | `x64`, `arm64` |
 | `darwin` | `x64`, `arm64` |
+| `windows` | `x64`, `arm64` |
+
+Windows assets add the executable extension after the target:
+
+```text
+<assetPrefix>-<tag>-windows-<arch>.exe
+<assetPrefix>-<tag>-windows-<arch>.exe.sha256
+```
 
 Tags may be provided as `1.2.3` or `v1.2.3`; release assets are always resolved with the `v` tag form published by GitHub releases.
 
@@ -69,9 +77,20 @@ The target repository should publish an installer manifest at either:
 - `.github/installer.json`
 - `.installer.json`
 
+On Windows, run the PowerShell installer:
+
+```powershell
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/pablozaiden/installer/main/install.ps1))) pablozaiden/link
+```
+
+It installs `<name>.exe` into `$HOME/.local/bin` by default and adds that
+directory to the user `PATH`. Pass `-NoModifyPath` to print guidance without
+changing `PATH`.
+
 The installer:
 
-1. Detects Linux/macOS and x64/arm64.
+1. Detects Linux/macOS and x64/arm64; the PowerShell entrypoint detects
+   Windows x64/arm64.
 2. Loads the target repository's manifest.
 3. Fetches the latest GitHub release.
 4. Downloads each configured binary asset.
@@ -101,7 +120,8 @@ Single-binary example:
   },
   "platforms": {
     "linux": ["x64", "arm64"],
-    "darwin": ["x64", "arm64"]
+    "darwin": ["x64", "arm64"],
+    "windows": ["x64", "arm64"]
   }
 }
 ```
@@ -164,12 +184,18 @@ Use `runUpdateCommand` from an installed binary's `update` command.
 import { runUpdateCommand } from "@pablozaiden/installer";
 import { MYPROJECT_VERSION } from "./version";
 
-export async function runCliCommand(command: { kind: string; checkOnly?: boolean; version?: string }) {
+export async function runCliCommand(command: {
+  kind: string;
+  checkOnly?: boolean;
+  version?: string;
+  preRelease?: boolean;
+}) {
   if (command.kind === "update") {
     return await runUpdateCommand(
       {
         checkOnly: command.checkOnly ?? false,
         version: command.version,
+        preRelease: command.preRelease,
       },
       {
         repository: "pablozaiden/myproject",
@@ -183,6 +209,12 @@ export async function runCliCommand(command: { kind: string; checkOnly?: boolean
 }
 ```
 
+Set `preRelease: true` to consider published prereleases. The updater selects
+the prerelease with the highest semantic version only when it is newer than
+the latest stable release; otherwise, it uses the stable release. The same
+selection applies to `checkOnly`. An explicit `version` continues to install
+that exact release.
+
 For a CLI with a companion binary installed beside it:
 
 ```ts
@@ -214,15 +246,22 @@ await runUpdateCommand(
 The updater supports:
 
 - latest release checks,
+- opt-in prerelease selection when a prerelease is newer than the latest stable release,
 - explicit version installs,
-- semver comparison including prereleases,
+- SemVer comparison including prereleases, with build metadata ignored for precedence,
 - GitHub release metadata validation,
-- Linux/macOS x64/arm64 target resolution,
+- Linux/macOS/Windows x64/arm64 target resolution,
 - checksum verification before replacement,
 - source-mode rejection when running from `bun`,
 - staged temp-file replacement with executable permission preservation,
 - companion binary updates that are committed together with the primary binary and rolled back on replacement failure.
 
+Windows cannot replace a running executable. The updater stages and verifies
+the complete update, then starts a detached PowerShell helper. The helper waits
+for the current process to exit, applies all replacements as one rollback-aware
+operation, and writes `<binary>.update-error.log` beside the executable if the
+deferred operation fails.
+
 Exported helpers include:
 
 ```ts
@@ -310,7 +349,8 @@ jobs:
 The workflow:
 
 - runs on GitHub release publication,
-- builds `linux-x64`, `linux-arm64`, `darwin-x64`, and `darwin-arm64`,
+- builds `linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64`,
+  `windows-x64`, and `windows-arm64`,
 - exports `TAG`, `VERSION`, `RELEASE_TARGET`, `BUN_TARGET`, `BINARY_NAME`, `ASSET_PREFIX`, and `ASSET_PATH` to each build command,
 - stages release assets using the shared naming convention,
 - generates `.sha256` files by default,

package/install.ps1

@@ -0,0 +1,444 @@
+[CmdletBinding()]
+param(
+  [Parameter(Position = 0)]
+  [string]$Repository,
+  [string]$Ref = "main",
+  [string[]]$Binary = @(),
+  [string[]]$AssetPrefix = @(),
+  [string]$InstallDir,
+  [ValidateSet("required", "optional", "none")]
+  [string]$Checksum = "required",
+  [switch]$NoModifyPath,
+  [switch]$Help
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$InstallerVersion = "0.0.0-development"
+$DefaultInstallDir = '$HOME/.local/bin'
+$DefaultManifestPaths = @(".github/installer.json", ".installer.json")
+$DefaultChecksumExtension = ".sha256"
+$ChecksumWasSpecified = $PSBoundParameters.ContainsKey("Checksum")
+
+function Show-Usage {
+  @"
+Usage:
+  install.ps1 <owner>/<repo> [options]
+
+Options:
+  -Ref <ref>                  Repository ref used to read manifests (default: main)
+  -Binary <name[]>            Binary names when no manifest is available
+  -AssetPrefix <prefix[]>     Asset prefixes corresponding to -Binary values
+  -InstallDir <dir>           Install directory (default: `$HOME/.local/bin)
+  -Checksum required|optional|none
+  -NoModifyPath               Do not add the install directory to the user PATH
+  -Help                       Show this help
+"@
+}
+
+function Fail([string]$Message) {
+  [Console]::Error.WriteLine("Error: $Message")
+  exit 1
+}
+
+function Invoke-Download {
+  param(
+    [Parameter(Mandatory = $true)]
+    [string]$Uri,
+    [Parameter(Mandatory = $true)]
+    [string]$OutFile
+  )
+
+  Invoke-WebRequest -UseBasicParsing -Uri $Uri -OutFile $OutFile
+}
+
+function Invoke-JsonRequest([string]$Uri) {
+  return Invoke-RestMethod -UseBasicParsing -Uri $Uri -Headers @{
+    "User-Agent" = "pablozaiden-installer"
+    "Accept" = "application/vnd.github+json"
+  }
+}
+
+function Invoke-RawJsonRequest([string]$Uri) {
+  $response = Invoke-WebRequest -UseBasicParsing -Uri $Uri -Headers @{
+    "User-Agent" = "pablozaiden-installer"
+    "Accept" = "application/json"
+  }
+  return ConvertFrom-Json -InputObject ([string]$response.Content)
+}
+
+function Test-HttpStatus {
+  param(
+    [Parameter(Mandatory = $true)]
+    [object]$ErrorRecord,
+    [Parameter(Mandatory = $true)]
+    [int]$StatusCode
+  )
+
+  $responseProperty = $ErrorRecord.Exception.PSObject.Properties["Response"]
+  if ($null -eq $responseProperty -or $null -eq $responseProperty.Value) {
+    return $false
+  }
+  $statusProperty = $responseProperty.Value.PSObject.Properties["StatusCode"]
+  return $null -ne $statusProperty -and [int]$statusProperty.Value -eq $StatusCode
+}
+
+function Expand-InstallDirectory([string]$Value) {
+  if ($Value -eq '$HOME' -or $Value -eq "~") {
+    return $HOME
+  }
+  if ($Value.StartsWith('$HOME/') -or $Value.StartsWith('$HOME\')) {
+    return Join-Path $HOME $Value.Substring(6)
+  }
+  if ($Value.StartsWith("~/") -or $Value.StartsWith("~\")) {
+    return Join-Path $HOME $Value.Substring(2)
+  }
+  return $Value
+}
+
+function Get-ReleaseArchitecture {
+  $architecture = $env:PROCESSOR_ARCHITEW6432
+  if ([string]::IsNullOrWhiteSpace($architecture)) {
+    $architecture = $env:PROCESSOR_ARCHITECTURE
+  }
+  switch ($architecture.ToUpperInvariant()) {
+    "AMD64" { return "x64" }
+    "ARM64" { return "arm64" }
+    default { Fail "Unsupported architecture: $architecture. Supported architectures are x64 and arm64." }
+  }
+}
+
+function Get-Manifest {
+  param(
+    [Parameter(Mandatory = $true)]
+    [string]$TargetRepository,
+    [Parameter(Mandatory = $true)]
+    [string]$TargetRef
+  )
+
+  $rawBaseUrl = if ($env:RAW_BASE_URL) {
+    $env:RAW_BASE_URL.TrimEnd("/")
+  } else {
+    "https://raw.githubusercontent.com"
+  }
+
+  foreach ($path in $DefaultManifestPaths) {
+    $uri = "$rawBaseUrl/$TargetRepository/$TargetRef/$path"
+    try {
+      $manifest = Invoke-RawJsonRequest $uri
+      return [PSCustomObject]@{
+        Path = $path
+        Value = $manifest
+      }
+    } catch {
+      if (Test-HttpStatus -ErrorRecord $_ -StatusCode 404) {
+        continue
+      }
+      throw
+    }
+  }
+  return $null
+}
+
+function Assert-ManifestPlatform {
+  param(
+    [Parameter(Mandatory = $true)]
+    [object]$Manifest,
+    [Parameter(Mandatory = $true)]
+    [string]$Architecture
+  )
+
+  $platformsProperty = $Manifest.PSObject.Properties["platforms"]
+  if ($null -eq $platformsProperty) {
+    return
+  }
+  $windowsProperty = $platformsProperty.Value.PSObject.Properties["windows"]
+  if ($null -eq $windowsProperty -or @($windowsProperty.Value) -notcontains $Architecture) {
+    Fail "Manifest does not support platform windows-$Architecture."
+  }
+}
+
+function Get-ExpectedChecksum {
+  param(
+    [Parameter(Mandatory = $true)]
+    [string]$ChecksumPath,
+    [Parameter(Mandatory = $true)]
+    [string]$AssetName
+  )
+
+  $plainHashes = @()
+  foreach ($line in (Get-Content -LiteralPath $ChecksumPath)) {
+    $match = [regex]::Match($line.Trim(), '^([0-9a-fA-F]{64})(?:\s+\*?(.+))?$')
+    if (-not $match.Success) {
+      continue
+    }
+    $hash = $match.Groups[1].Value.ToLowerInvariant()
+    $fileName = $match.Groups[2].Value.Trim()
+    if ($fileName) {
+      if ([IO.Path]::GetFileName($fileName) -eq $AssetName) {
+        return $hash
+      }
+      continue
+    }
+    $plainHashes += $hash
+  }
+  if ($plainHashes.Count -eq 1) {
+    return $plainHashes[0]
+  }
+  Fail "Checksum for $AssetName did not contain a valid SHA-256 entry."
+}
+
+function Get-Sha256([string]$Path) {
+  $stream = [IO.File]::OpenRead($Path)
+  $algorithm = [Security.Cryptography.SHA256]::Create()
+  try {
+    return [BitConverter]::ToString($algorithm.ComputeHash($stream)).Replace("-", "").ToLowerInvariant()
+  } finally {
+    $algorithm.Dispose()
+    $stream.Dispose()
+  }
+}
+
+function Install-Binary {
+  param(
+    [Parameter(Mandatory = $true)]
+    [string]$TargetRepository,
+    [Parameter(Mandatory = $true)]
+    [string]$Tag,
+    [Parameter(Mandatory = $true)]
+    [string]$Architecture,
+    [Parameter(Mandatory = $true)]
+    [string]$TargetInstallDir,
+    [Parameter(Mandatory = $true)]
+    [string]$ChecksumPolicy,
+    [Parameter(Mandatory = $true)]
+    [string]$ChecksumExtension,
+    [Parameter(Mandatory = $true)]
+    [object]$BinaryDefinition
+  )
+
+  $name = [string]$BinaryDefinition.name
+  $prefixProperty = $BinaryDefinition.PSObject.Properties["assetPrefix"]
+  $assetPrefix = if ($null -eq $prefixProperty -or [string]::IsNullOrWhiteSpace([string]$prefixProperty.Value)) {
+    $name
+  } else {
+    [string]$prefixProperty.Value
+  }
+  $requiredProperty = $BinaryDefinition.PSObject.Properties["required"]
+  $required = $null -eq $requiredProperty -or [bool]$requiredProperty.Value
+  $assetName = "$assetPrefix-$Tag-windows-$Architecture.exe"
+  $releaseBaseUrl = if ($env:GITHUB_RELEASE_BASE_URL) {
+    $env:GITHUB_RELEASE_BASE_URL.TrimEnd("/")
+  } else {
+    "https://github.com"
+  }
+  $downloadUrl = "$releaseBaseUrl/$TargetRepository/releases/download/$Tag/$assetName"
+  $tempFile = [IO.Path]::GetTempFileName()
+  $checksumFile = [IO.Path]::GetTempFileName()
+
+  try {
+    [Console]::WriteLine("Downloading $assetName...")
+    try {
+      Invoke-Download -Uri $downloadUrl -OutFile $tempFile
+    } catch {
+      if (-not $required -and (Test-HttpStatus -ErrorRecord $_ -StatusCode 404)) {
+        [Console]::WriteLine("Skipping optional binary $name; $assetName was not published.")
+        return $false
+      }
+      throw
+    }
+
+    if ($ChecksumPolicy -eq "none") {
+      [Console]::WriteLine("Skipping checksum verification for $assetName; checksum policy is none.")
+    } else {
+      $checksumName = "$assetName$ChecksumExtension"
+      $checksumUrl = "$downloadUrl$ChecksumExtension"
+      $checksumDownloaded = $true
+      try {
+        Invoke-Download -Uri $checksumUrl -OutFile $checksumFile
+      } catch {
+        if ($ChecksumPolicy -eq "required" -or -not (Test-HttpStatus -ErrorRecord $_ -StatusCode 404)) {
+          throw
+        }
+        [Console]::WriteLine("Skipping checksum verification for $assetName; $checksumName was not published.")
+        $checksumDownloaded = $false
+      }
+      if ($checksumDownloaded) {
+        [Console]::WriteLine("Verifying $checksumName...")
+        $expected = Get-ExpectedChecksum -ChecksumPath $checksumFile -AssetName $assetName
+        $actual = Get-Sha256 $tempFile
+        if ($expected -ne $actual) {
+          Fail "Checksum verification failed for $assetName`: expected $expected, got $actual."
+        }
+      }
+    }
+
+    $fileName = if ($name.EndsWith(".exe", [StringComparison]::OrdinalIgnoreCase)) {
+      $name
+    } else {
+      "$name.exe"
+    }
+    $targetPath = Join-Path $TargetInstallDir $fileName
+    Move-Item -LiteralPath $tempFile -Destination $targetPath -Force
+    [Console]::WriteLine("Installed $name to $targetPath")
+    return $true
+  } finally {
+    Remove-Item -LiteralPath $tempFile -Force -ErrorAction SilentlyContinue
+    Remove-Item -LiteralPath $checksumFile -Force -ErrorAction SilentlyContinue
+  }
+}
+
+function Add-UserPath([string]$Directory) {
+  $fullDirectory = [IO.Path]::GetFullPath($Directory).TrimEnd("\")
+  $currentEntries = @($env:Path -split ";" | Where-Object { $_ })
+  $alreadyCurrent = $currentEntries | Where-Object {
+    try {
+      [IO.Path]::GetFullPath(
+        [Environment]::ExpandEnvironmentVariables($_.Trim().Trim('"'))
+      ).TrimEnd("\").Equals($fullDirectory, [StringComparison]::OrdinalIgnoreCase)
+    } catch {
+      $false
+    }
+  }
+  if ($alreadyCurrent) {
+    [Console]::WriteLine("")
+    [Console]::WriteLine("Installation complete!")
+    return
+  }
+
+  if ($NoModifyPath) {
+    [Console]::WriteLine("")
+    [Console]::WriteLine("Warning: $fullDirectory is not in PATH.")
+    [Console]::WriteLine("Add it to your user PATH before invoking installed binaries by name.")
+    return
+  }
+
+  $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
+  $userEntries = @($userPath -split ";" | Where-Object { $_ })
+  $alreadyUser = $userEntries | Where-Object {
+    try {
+      [IO.Path]::GetFullPath(
+        [Environment]::ExpandEnvironmentVariables($_.Trim().Trim('"'))
+      ).TrimEnd("\").Equals($fullDirectory, [StringComparison]::OrdinalIgnoreCase)
+    } catch {
+      $false
+    }
+  }
+  if (-not $alreadyUser) {
+    $nextUserPath = if ([string]::IsNullOrWhiteSpace($userPath)) {
+      $fullDirectory
+    } else {
+      "$fullDirectory;$userPath"
+    }
+    [Environment]::SetEnvironmentVariable("Path", $nextUserPath, "User")
+  }
+  $env:Path = "$fullDirectory;$env:Path"
+  [Console]::WriteLine("")
+  [Console]::WriteLine("Added $fullDirectory to the user PATH.")
+  [Console]::WriteLine("Open a new terminal before invoking installed binaries by name.")
+}
+
+if ($Help) {
+  Show-Usage
+  exit 0
+}
+if ([string]::IsNullOrWhiteSpace($Repository)) {
+  Show-Usage
+  exit 1
+}
+if ($env:OS -ne "Windows_NT") {
+  Fail "install.ps1 supports Windows only. Use install.sh on Linux or macOS."
+}
+if ($Repository -notmatch '^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$') {
+  Fail "Repository must be <owner>/<repo>."
+}
+
+$architecture = Get-ReleaseArchitecture
+[Console]::WriteLine("Installer version: $InstallerVersion")
+[Console]::WriteLine("Detected platform: windows-$architecture")
+
+$manifestResult = Get-Manifest -TargetRepository $Repository -TargetRef $Ref
+$binaries = @()
+$checksumPolicy = $Checksum
+$checksumExtension = $DefaultChecksumExtension
+$postInstallMessage = $null
+
+if ($null -ne $manifestResult) {
+  [Console]::WriteLine("Loaded installer manifest: $($manifestResult.Path)")
+  $manifest = $manifestResult.Value
+  if ($manifest.schemaVersion -ne 1) {
+    Fail "Unsupported installer manifest schemaVersion: $($manifest.schemaVersion). Supported schemaVersion is 1."
+  }
+  Assert-ManifestPlatform -Manifest $manifest -Architecture $architecture
+  if ($manifest.PSObject.Properties["repo"]) {
+    $Repository = [string]$manifest.repo
+  }
+  if ($manifest.PSObject.Properties["installDir"]) {
+    $InstallDir = [string]$manifest.installDir
+  }
+  if (-not $ChecksumWasSpecified -and $manifest.PSObject.Properties["checksums"]) {
+    $checksumPolicy = if ([bool]$manifest.checksums.required) { "required" } else { "optional" }
+    if ($manifest.checksums.PSObject.Properties["extension"]) {
+      $checksumExtension = [string]$manifest.checksums.extension
+    }
+  }
+  $binaries = @($manifest.binaries)
+  if ($manifest.PSObject.Properties["postInstallMessage"]) {
+    $postInstallMessage = [string]$manifest.postInstallMessage
+  }
+} else {
+  if ($Binary.Count -eq 0) {
+    Fail "No installer manifest found. Add .github/installer.json or pass -Binary <name>."
+  }
+  for ($index = 0; $index -lt $Binary.Count; $index += 1) {
+    $prefix = if ($index -lt $AssetPrefix.Count) { $AssetPrefix[$index] } else { $Binary[$index] }
+    $binaries += [PSCustomObject]@{
+      name = $Binary[$index]
+      assetPrefix = $prefix
+      required = $true
+    }
+  }
+}
+
+if ($binaries.Count -eq 0) {
+  Fail "No binaries configured for installation."
+}
+if ([string]::IsNullOrWhiteSpace($InstallDir)) {
+  $InstallDir = $DefaultInstallDir
+}
+$InstallDir = Expand-InstallDirectory $InstallDir
+New-Item -ItemType Directory -Path $InstallDir -Force | Out-Null
+
+$apiBaseUrl = if ($env:GITHUB_API_BASE_URL) {
+  $env:GITHUB_API_BASE_URL.TrimEnd("/")
+} else {
+  "https://api.github.com"
+}
+[Console]::WriteLine("Fetching latest release...")
+$release = Invoke-JsonRequest "$apiBaseUrl/repos/$Repository/releases/latest"
+$tag = [string]$release.tag_name
+if ([string]::IsNullOrWhiteSpace($tag)) {
+  Fail "Could not determine latest release version."
+}
+[Console]::WriteLine("Latest version: $tag")
+
+foreach ($binaryDefinition in $binaries) {
+  $installed = Install-Binary `
+    -TargetRepository $Repository `
+    -Tag $tag `
+    -Architecture $architecture `
+    -TargetInstallDir $InstallDir `
+    -ChecksumPolicy $checksumPolicy `
+    -ChecksumExtension $checksumExtension `
+    -BinaryDefinition $binaryDefinition
+  $messageProperty = $binaryDefinition.PSObject.Properties["postInstallMessage"]
+  if ($installed -and $null -ne $messageProperty -and $messageProperty.Value) {
+    [Console]::WriteLine([string]$messageProperty.Value)
+  }
+}
+
+if ($postInstallMessage) {
+  [Console]::WriteLine($postInstallMessage)
+}
+Add-UserPath $InstallDir

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pablozaiden/installer",
-  "version": "0.0.10",
+  "version": "0.2.0",
   "description": "Reusable GitHub release binary installer and updater utilities",
   "repository": {
     "type": "git",
@@ -12,6 +12,7 @@
     "index.ts",
     "src/**/*",
     "install.sh",
+    "install.ps1",
     "README.md"
   ],
   "exports": {

package/src/contract.ts

@@ -11,9 +11,11 @@ export const SUPPORTED_RELEASE_TARGETS = [
   "linux-arm64",
   "darwin-x64",
   "darwin-arm64",
+  "windows-x64",
+  "windows-arm64",
 ] as const;
 
-export type ReleaseOs = "linux" | "darwin";
+export type ReleaseOs = "linux" | "darwin" | "windows";
 export type ReleaseArch = "x64" | "arm64";
 export type ReleaseTarget = `${ReleaseOs}-${ReleaseArch}`;
 
@@ -44,7 +46,7 @@ type ParsedVersion = {
 };
 
 function parseVersion(value: string): ParsedVersion | null {
-  const parsed = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(normalizeReleaseVersion(value));
+  const parsed = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(normalizeReleaseVersion(value));
   if (!parsed) {
     return null;
   }
@@ -133,7 +135,11 @@ export function parseReleaseTarget(target: string): ReleasePlatform {
 }
 
 export function resolveReleasePlatform(platform: string, arch: string): ReleasePlatform {
-  const os = platform === "linux" || platform === "darwin" ? platform : undefined;
+  const os = platform === "win32"
+    ? "windows"
+    : platform === "linux" || platform === "darwin" || platform === "windows"
+      ? platform
+      : undefined;
   const normalizedArch = arch === "x64" || arch === "amd64"
     ? "x64"
     : arch === "arm64" || arch === "aarch64"
@@ -147,11 +153,18 @@ export function resolveReleasePlatform(platform: string, arch: string): ReleaseP
     };
   }
 
-  throw new Error(`Unsupported platform: ${platform}-${arch}. Supported release targets are Linux and macOS on x64 and arm64.`);
+  throw new Error(`Unsupported platform: ${platform}-${arch}. Supported release targets are Linux, macOS, and Windows on x64 and arm64.`);
 }
 
 export function buildReleaseAssetName(assetPrefix: string, tag: string, target: ReleasePlatform): string {
-  return `${assetPrefix}-${normalizeReleaseTag(tag)}-${target.os}-${target.arch}`;
+  const extension = target.os === "windows" ? ".exe" : "";
+  return `${assetPrefix}-${normalizeReleaseTag(tag)}-${target.os}-${target.arch}${extension}`;
+}
+
+export function releaseBinaryFileName(binaryName: string, target: ReleasePlatform): string {
+  return target.os === "windows" && !binaryName.toLowerCase().endsWith(".exe")
+    ? `${binaryName}.exe`
+    : binaryName;
 }
 
 export function assertGitHubRepository(value: string): GitHubRepository {

package/src/manifest.ts

@@ -26,7 +26,7 @@ export type InstallerManifest = {
   installDir?: string;
   binaries: InstallerManifestBinary[];
   checksums?: InstallerChecksumPolicy;
-  platforms?: Partial<Record<"linux" | "darwin", Array<"x64" | "arm64">>>;
+  platforms?: Partial<Record<"linux" | "darwin" | "windows", Array<"x64" | "arm64">>>;
   postInstallMessage?: string;
 };
 
@@ -118,7 +118,7 @@ function parsePlatforms(value: unknown): InstallerManifest["platforms"] {
   }
   const raw = expectObject(value, "platforms");
   const platforms: InstallerManifest["platforms"] = {};
-  for (const os of ["linux", "darwin"] as const) {
+  for (const os of ["linux", "darwin", "windows"] as const) {
     const arches = raw[os];
     if (arches === undefined) {
       continue;
@@ -168,7 +168,7 @@ function normalizeTargets(platforms: InstallerManifest["platforms"]): ReleaseTar
     return [...SUPPORTED_RELEASE_TARGETS];
   }
   const targets: ReleaseTarget[] = [];
-  for (const os of ["linux", "darwin"] as const) {
+  for (const os of ["linux", "darwin", "windows"] as const) {
     for (const arch of platforms[os] ?? []) {
       targets.push(`${os}-${arch}`);
     }

package/src/update.ts

@@ -10,6 +10,7 @@ import {
   githubApiRepositoryUrl,
   normalizeReleaseTag,
   normalizeReleaseVersion,
+  releaseBinaryFileName,
   resolveReleasePlatform,
   type GitHubRepository,
   type ReleasePlatform,
@@ -18,6 +19,7 @@ import {
 export type UpdateCommandOptions = {
   checkOnly: boolean;
   version?: string;
+  preRelease?: boolean;
 };
 
 export type UpdaterChecksumPolicy = {
@@ -62,6 +64,8 @@ export type UpdaterDependencies = {
   renameFile: (from: string, to: string) => Promise<void>;
   removeFile: (path: string) => Promise<void>;
   statFile: (path: string) => Promise<{ mode: number }>;
+  getCurrentProcessId: () => number;
+  spawnDetached: (command: string, args: readonly string[]) => Promise<void>;
 };
 
 export type GitHubReleaseAsset = {
@@ -72,6 +76,8 @@ export type GitHubReleaseAsset = {
 export type GitHubRelease = {
   tag_name: string;
   assets: GitHubReleaseAsset[];
+  draft?: boolean;
+  prerelease?: boolean;
 };
 
 export type ResolvedReleaseAsset = {
@@ -98,6 +104,102 @@ type StagedBinaryReplacement = {
   backupPath: string;
 };
 
+function powerShellString(value: string): string {
+  return `'${value.replaceAll("'", "''")}'`;
+}
+
+function windowsUpdateHelper(
+  stagedReplacements: StagedBinaryReplacement[],
+  statusPath: string,
+  parentProcessId: number,
+): string {
+  const replacements = stagedReplacements.map((staged) => [
+    "  [PSCustomObject]@{",
+    `    TargetPath = ${powerShellString(staged.target.targetPath)}`,
+    `    TempDirectory = ${powerShellString(staged.tempDirectory)}`,
+    `    TempPath = ${powerShellString(staged.tempPath)}`,
+    `    BackupPath = ${powerShellString(staged.backupPath)}`,
+    "  }",
+  ].join("\n")).join("\n");
+
+  return String.raw`
+$ErrorActionPreference = "Stop"
+$ParentProcessId = ${String(parentProcessId)}
+$StatusPath = ${powerShellString(statusPath)}
+$replacements = @(
+${replacements}
+)
+$utf8 = [System.Text.UTF8Encoding]::new($false)
+
+function Write-UpdateStatus([string]$Message) {
+  [System.IO.File]::WriteAllText($StatusPath, $Message, $utf8)
+}
+
+Write-UpdateStatus "Update helper started."
+$deadline = [DateTime]::UtcNow.AddMinutes(5)
+
+while ($ParentProcessId -gt 0) {
+  try {
+    $parentProcess = [System.Diagnostics.Process]::GetProcessById($ParentProcessId)
+    if ($parentProcess.HasExited) {
+      break
+    }
+  } catch [System.ArgumentException] {
+    break
+  }
+  if ([DateTime]::UtcNow -ge $deadline) {
+    Write-UpdateStatus "Timed out waiting for process $ParentProcessId to exit."
+    exit 1
+  }
+  [System.Threading.Thread]::Sleep(100)
+}
+
+$movedBackups = [System.Collections.Generic.List[object]]::new()
+$installedReplacements = [System.Collections.Generic.List[object]]::new()
+
+try {
+  foreach ($replacement in $replacements) {
+    [System.IO.File]::Move($replacement.TargetPath, $replacement.BackupPath)
+    $movedBackups.Add($replacement)
+    [System.IO.File]::Move($replacement.TempPath, $replacement.TargetPath)
+    $installedReplacements.Add($replacement)
+  }
+} catch {
+  $failure = $_.Exception.Message
+  try {
+    for ($index = $installedReplacements.Count - 1; $index -ge 0; $index -= 1) {
+      [System.IO.File]::Delete($installedReplacements[$index].TargetPath)
+    }
+    for ($index = $movedBackups.Count - 1; $index -ge 0; $index -= 1) {
+      [System.IO.File]::Move(
+        $movedBackups[$index].BackupPath,
+        $movedBackups[$index].TargetPath
+      )
+    }
+  } catch {
+    $failure = $failure + " Rollback failed: " + $_.Exception.Message
+  }
+  Write-UpdateStatus $failure
+  exit 1
+}
+
+[System.IO.File]::Delete($StatusPath)
+$cleanupDirectories = [System.Collections.Generic.HashSet[string]]::new(
+  [System.StringComparer]::OrdinalIgnoreCase
+)
+foreach ($replacement in $replacements) {
+  [void]$cleanupDirectories.Add($replacement.TempDirectory)
+}
+foreach ($directory in $cleanupDirectories) {
+  try {
+    [System.IO.Directory]::Delete($directory, $true)
+  } catch {
+    Write-UpdateStatus ("Update installed but cleanup failed: " + $_.Exception.Message)
+  }
+}
+`;
+}
+
 function createDefaultUpdateDependencies(): UpdaterDependencies {
   return {
     fetchFn: fetch,
@@ -127,6 +229,20 @@ function createDefaultUpdateDependencies(): UpdaterDependencies {
       const result = await stat(path);
       return { mode: result.mode };
     },
+    getCurrentProcessId: () => process.pid,
+    spawnDetached: async (command, args) => {
+      // Bun's detached children remain in its kill-on-close job object on Windows.
+      const bootstrap = Bun.spawn(["cmd.exe", "/d", "/c", "start", "", "/b", command, ...args], {
+        stdin: "ignore",
+        stdout: "ignore",
+        stderr: "ignore",
+        windowsHide: true,
+      });
+      const exitCode = await bootstrap.exited;
+      if (exitCode !== 0) {
+        throw new Error(`Failed to launch the deferred updater (cmd.exe exited with ${String(exitCode)}).`);
+      }
+    },
   };
 }
 
@@ -158,15 +274,102 @@ export function parseGitHubRelease(value: unknown): GitHubRelease {
   if (!Array.isArray(raw["assets"])) {
     throw new Error("release.assets must be an array.");
   }
+  const draft = parseOptionalBoolean(raw["draft"], "release.draft");
+  const prerelease = parseOptionalBoolean(raw["prerelease"], "release.prerelease");
   return {
     tag_name: raw["tag_name"],
     assets: raw["assets"].map(assertReleaseAsset),
+    ...(draft === undefined ? {} : { draft }),
+    ...(prerelease === undefined ? {} : { prerelease }),
   };
 }
 
+function parseOptionalBoolean(value: unknown, label: string): boolean | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "boolean") {
+    throw new Error(`${label} must be a boolean.`);
+  }
+  return value;
+}
+
+function parseGitHubReleaseList(value: unknown): GitHubRelease[] {
+  if (!Array.isArray(value)) {
+    throw new Error("releases must be an array.");
+  }
+  return value.map((entry, index) => {
+    const release = parseGitHubRelease(entry);
+    if (release.draft === undefined) {
+      throw new Error(`releases[${index}].draft must be a boolean.`);
+    }
+    if (release.prerelease === undefined) {
+      throw new Error(`releases[${index}].prerelease must be a boolean.`);
+    }
+    return release;
+  });
+}
+
+async function fetchGitHubApiResponse(
+  config: UpdaterConfig,
+  url: string,
+  dependencies: Pick<UpdaterDependencies, "fetchFn">,
+): Promise<Response> {
+  return await dependencies.fetchFn(url, {
+    headers: {
+      accept: "application/vnd.github+json",
+      "user-agent": config.userAgent ?? `${config.binaryName}-updater`,
+      "x-github-api-version": DEFAULT_GITHUB_API_VERSION,
+    },
+  });
+}
+
+async function parseGitHubApiResponse(response: Response, metadataName: string): Promise<unknown> {
+  try {
+    return await response.json();
+  } catch (error) {
+    throw new Error(`Failed to parse ${metadataName}: ${String(error)}`);
+  }
+}
+
+function hasNextReleasePage(response: Response): boolean {
+  return response.headers.get("link")
+    ?.split(",")
+    .some(link => /;\s*rel="?next"?\s*(?:;|$)/i.test(link)) ?? false;
+}
+
+async function fetchGitHubReleases(
+  repository: GitHubRepository,
+  config: UpdaterConfig,
+  dependencies: Pick<UpdaterDependencies, "fetchFn">,
+): Promise<GitHubRelease[]> {
+  const releasesUrl = `${githubApiRepositoryUrl(repository)}/releases`;
+  const releases: GitHubRelease[] = [];
+  let page = 1;
+
+  while (true) {
+    const response = await fetchGitHubApiResponse(
+      config,
+      `${releasesUrl}?per_page=100&page=${String(page)}`,
+      dependencies,
+    );
+    if (!response.ok) {
+      throw new Error(`Failed to load prerelease metadata: GitHub returned ${String(response.status)}.`);
+    }
+    const pageReleases = parseGitHubReleaseList(
+      await parseGitHubApiResponse(response, "prerelease metadata"),
+    );
+    releases.push(...pageReleases);
+    if (!hasNextReleasePage(response)) {
+      return releases;
+    }
+    page += 1;
+  }
+}
+
 export async function fetchGitHubRelease(
   config: UpdaterConfig,
-  command: Pick<UpdateCommandOptions, "version">,
+  command: Pick<UpdateCommandOptions, "version" | "preRelease">,
   dependencies: Pick<UpdaterDependencies, "fetchFn" | "out">,
 ): Promise<GitHubRelease> {
   const repository = assertGitHubRepository(config.repository);
@@ -175,13 +378,7 @@ export async function fetchGitHubRelease(
     ? `${githubApiRepositoryUrl(repository)}/releases/tags/${tag}`
     : `${githubApiRepositoryUrl(repository)}/releases/latest`;
   dependencies.out(tag ? `Fetching release metadata for ${tag}...` : "Fetching release metadata...");
-  const response = await dependencies.fetchFn(releaseUrl, {
-    headers: {
-      accept: "application/vnd.github+json",
-      "user-agent": config.userAgent ?? `${config.binaryName}-updater`,
-      "x-github-api-version": DEFAULT_GITHUB_API_VERSION,
-    },
-  });
+  const response = await fetchGitHubApiResponse(config, releaseUrl, dependencies);
 
   if (response.status === 404 && tag) {
     throw new Error(`Release not found: ${tag}`);
@@ -190,13 +387,27 @@ export async function fetchGitHubRelease(
     throw new Error(`Failed to load release metadata: GitHub returned ${String(response.status)}.`);
   }
 
-  let rawBody: unknown;
-  try {
-    rawBody = await response.json();
-  } catch (error) {
-    throw new Error(`Failed to parse release metadata: ${String(error)}`);
+  const release = parseGitHubRelease(await parseGitHubApiResponse(response, "release metadata"));
+  if (tag || !command.preRelease) {
+    return release;
+  }
+
+  dependencies.out("Checking for a newer prerelease...");
+  const prereleases = (await fetchGitHubReleases(repository, config, dependencies))
+    .filter(candidate => candidate.prerelease === true && candidate.draft !== true);
+  const newestPrerelease = prereleases.reduce<GitHubRelease | undefined>(
+    (newest, candidate) => !newest || compareReleaseVersions(candidate.tag_name, newest.tag_name) > 0
+      ? candidate
+      : newest,
+    undefined,
+  );
+  if (
+    newestPrerelease
+    && compareReleaseVersions(newestPrerelease.tag_name, release.tag_name) > 0
+  ) {
+    return newestPrerelease;
   }
-  return parseGitHubRelease(rawBody);
+  return release;
 }
 
 export function resolveReleaseAsset(
@@ -307,7 +518,7 @@ export async function verifyReleaseAssetChecksum(
 
 async function resolveInstalledBinaryPath(binaryName: string, productName: string, dependencies: UpdaterDependencies): Promise<string> {
   const executablePath = dependencies.getExecutablePath();
-  const executableName = basename(executablePath);
+  const executableName = basename(executablePath).toLowerCase().replace(/\.exe$/, "");
   if (executableName === "bun" || executableName.startsWith("bun-")) {
     throw new Error(`${binaryName} update only works from an installed ${productName} binary. Use the installer script when running from source.`);
   }
@@ -323,6 +534,7 @@ async function stageInstalledBinaryReplacement(
   asset: ResolvedReleaseAsset,
   config: UpdaterConfig,
   checksumPolicy: Required<UpdaterChecksumPolicy>,
+  platform: ReleasePlatform,
   dependencies: UpdaterDependencies,
 ): Promise<StagedBinaryReplacement> {
   const targetPath = target.targetPath;
@@ -343,9 +555,11 @@ async function stageInstalledBinaryReplacement(
     await verifyReleaseAssetChecksum(asset, payload, checksumPolicy, dependencies);
     await dependencies.writeBinary(tempPath, payload);
 
-    const installedBinaryStat = await dependencies.statFile(targetPath);
-    const executableMode = installedBinaryStat.mode & 0o777;
-    await dependencies.chmodFile(tempPath, executableMode || 0o755);
+    if (platform.os !== "windows") {
+      const installedBinaryStat = await dependencies.statFile(targetPath);
+      const executableMode = installedBinaryStat.mode & 0o777;
+      await dependencies.chmodFile(tempPath, executableMode || 0o755);
+    }
     staged = true;
     return {
       target,
@@ -404,11 +618,41 @@ async function replaceStagedBinaryReplacements(
   }
 }
 
-async function resolveInstalledBinaryTargets(config: UpdaterConfig, dependencies: UpdaterDependencies): Promise<InstalledBinaryTarget[]> {
+async function scheduleWindowsBinaryReplacements(
+  stagedReplacements: StagedBinaryReplacement[],
+  dependencies: UpdaterDependencies,
+): Promise<void> {
+  const primary = stagedReplacements.at(-1);
+  if (!primary) {
+    throw new Error("No staged Windows binary replacements were provided.");
+  }
+  const statusPath = `${primary.target.targetPath}.update-error.log`;
+  const parentProcessId = dependencies.getCurrentProcessId();
+  const encodedHelper = Buffer.from(
+    windowsUpdateHelper(stagedReplacements, statusPath, parentProcessId),
+    "utf16le",
+  ).toString("base64");
+  await dependencies.removeFile(statusPath);
+  await dependencies.spawnDetached("powershell.exe", [
+    "-NoLogo",
+    "-NoProfile",
+    "-NonInteractive",
+    "-ExecutionPolicy",
+    "Bypass",
+    "-EncodedCommand",
+    encodedHelper,
+  ]);
+}
+
+async function resolveInstalledBinaryTargets(
+  config: UpdaterConfig,
+  platform: ReleasePlatform,
+  dependencies: UpdaterDependencies,
+): Promise<InstalledBinaryTarget[]> {
   const primaryPath = await resolveInstalledBinaryPath(config.binaryName, config.productName ?? config.binaryName, dependencies);
   const targets: InstalledBinaryTarget[] = [];
   for (const companion of config.companionBinaries ?? []) {
-    const companionPath = join(dirname(primaryPath), companion.binaryName);
+    const companionPath = join(dirname(primaryPath), releaseBinaryFileName(companion.binaryName, platform));
     if (await dependencies.fileExists(companionPath)) {
       targets.push({
         binaryName: companion.binaryName,
@@ -472,15 +716,33 @@ export async function runUpdateCommand(
   }
 
   const stagedReplacements: StagedBinaryReplacement[] = [];
+  let deferredWindowsReplacement = false;
   try {
-    const installedTargets = await resolveInstalledBinaryTargets(normalizedConfig, dependencies);
+    const installedTargets = await resolveInstalledBinaryTargets(normalizedConfig, releasePlatform, dependencies);
     for (const target of installedTargets) {
       const asset = resolveReleaseAsset(release, releasePlatform, {
         binaryName: target.binaryName,
         assetPrefix: target.assetPrefix,
         checksum: checksumPolicy,
       });
-      stagedReplacements.push(await stageInstalledBinaryReplacement(target, asset, normalizedConfig, checksumPolicy, dependencies));
+      stagedReplacements.push(await stageInstalledBinaryReplacement(
+        target,
+        asset,
+        normalizedConfig,
+        checksumPolicy,
+        releasePlatform,
+        dependencies,
+      ));
+    }
+
+    if (releasePlatform.os === "windows") {
+      await scheduleWindowsBinaryReplacements(stagedReplacements, dependencies);
+      deferredWindowsReplacement = true;
+      dependencies.out(
+        `Staged ${normalizedConfig.productName ?? normalizedConfig.binaryName} ${primaryAsset.version}. `
+        + `The update will complete after process ${String(dependencies.getCurrentProcessId())} exits.`,
+      );
+      return 0;
     }
 
     await replaceStagedBinaryReplacements(stagedReplacements, normalizedConfig, dependencies);
@@ -493,7 +755,9 @@ export async function runUpdateCommand(
       }
     }
   } finally {
-    await cleanupStagedBinaryReplacements(stagedReplacements, dependencies);
+    if (!deferredWindowsReplacement) {
+      await cleanupStagedBinaryReplacements(stagedReplacements, dependencies);
+    }
   }
 
   return 0;