@pablozaiden/installer 0.0.10 → 0.1.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"]
   }
 }
 ```
@@ -217,12 +237,18 @@ The updater supports:
 - explicit version installs,
 - semver comparison including prereleases,
 - 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 +336,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.1.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}`;
 
@@ -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,
@@ -62,6 +63,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 = {
@@ -98,6 +101,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 +226,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)}).`);
+      }
+    },
   };
 }
 
@@ -307,7 +420,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 +436,7 @@ async function stageInstalledBinaryReplacement(
   asset: ResolvedReleaseAsset,
   config: UpdaterConfig,
   checksumPolicy: Required<UpdaterChecksumPolicy>,
+  platform: ReleasePlatform,
   dependencies: UpdaterDependencies,
 ): Promise<StagedBinaryReplacement> {
   const targetPath = target.targetPath;
@@ -343,9 +457,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 +520,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 +618,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 +657,9 @@ export async function runUpdateCommand(
       }
     }
   } finally {
-    await cleanupStagedBinaryReplacements(stagedReplacements, dependencies);
+    if (!deferredWindowsReplacement) {
+      await cleanupStagedBinaryReplacements(stagedReplacements, dependencies);
+    }
   }
 
   return 0;