fix: harden portable updater workflow

Author: kigner

scripts/build_update_release.ps1

@@ -11,7 +11,8 @@ param(
     [string]$PythonDepsSource = "",
     [switch]$IncludeUpdater,
     [string]$UpdaterMinisignBinary = "",
-    [ValidatePattern('^\d+\.\d+\.\d+$')][string]$MinimumUpdater = "1.1.0",
+    [ValidatePattern('^\d+\.\d+\.\d+$')][string]$MinimumUpdater = "1.1.1",
+    [string]$SupportedFrom = ">=0.2.0",
     [switch]$Stable,
     [switch]$AllowDirty
 )
@@ -254,6 +255,18 @@ if (-not (Test-Path -LiteralPath $MinisignPublicKey -PathType Leaf)) {
 if ((Get-Content -LiteralPath $MinisignPublicKey -Raw -Encoding UTF8) -match 'REPLACE_WITH_') {
     throw "Refusing to use a placeholder minisign public key."
 }
+$packagedUpdaterVersion = (Get-Content -LiteralPath (Join-Path $repoRoot "updater\updater.version") -Raw).Trim()
+if ([version]$packagedUpdaterVersion -lt [version]$MinimumUpdater) {
+    throw "Repository updater $packagedUpdaterVersion is older than -MinimumUpdater $MinimumUpdater."
+}
+if ([string]::IsNullOrWhiteSpace($SupportedFrom)) {
+    throw "-SupportedFrom cannot be empty."
+}
+foreach ($clause in ($SupportedFrom -split '\s+' | Where-Object { $_ -ne "" })) {
+    if ($clause -notmatch '^(>=|<=|>|<|=)?\d+(?:\.\d+){1,3}$') {
+        throw "Unsupported -SupportedFrom clause '$clause'."
+    }
+}
 if ($null -eq (Get-Command $MinisignPath -ErrorAction SilentlyContinue)) {
     throw "Minisign executable not found: $MinisignPath"
 }
@@ -285,7 +298,7 @@ $manifest = [ordered]@{
     product = "audiocpp-portable"
     platform = "windows-x64"
     version = $Version
-    supported_from = ">=0.2.0 <0.3.0"
+    supported_from = $SupportedFrom
     minimum_updater = $MinimumUpdater
     components = @($components | ForEach-Object { ConvertTo-ManifestComponent $_ })
     preserve = $preserveRules

scripts/build_updater_bootstrap.ps1

@@ -1,6 +1,6 @@
 [CmdletBinding()]
 param(
-    [string]$Version = "0.2.0",
+    [ValidatePattern('^\d+\.\d+\.\d+$')][string]$Version = "0.2.0",
     [Parameter(Mandatory = $true)][string]$MinisignBinary,
     [Parameter(Mandatory = $true)][string]$PublicKeyPath,
     [string]$OutputPath = ""
@@ -47,6 +47,12 @@ try {
     $versionValue.components.app = $Version
     $versionValue.components.core_cpu = $Version
     $versionValue.components.core_cuda = $Version
+    $updaterVersion = (Get-Content -LiteralPath (Join-Path $repoRoot "updater\updater.version") -Raw).Trim()
+    if ($null -eq $versionValue.components.PSObject.Properties["updater"]) {
+        $versionValue.components | Add-Member -NotePropertyName "updater" -NotePropertyValue $updaterVersion
+    } else {
+        $versionValue.components.updater = $updaterVersion
+    }
     $versionValue | ConvertTo-Json -Depth 10 | Set-Content -LiteralPath (Join-Path $stage "version.json") -Encoding UTF8
 
     New-Item -ItemType Directory -Path $outputDirectory -Force | Out-Null

tests/updater/run_tests.ps1

@@ -7,6 +7,7 @@ $ProgressPreference = "SilentlyContinue"
 
 $repoRoot = [IO.Path]::GetFullPath((Join-Path $PSScriptRoot "..\.."))
 $testRoot = Join-Path $PSScriptRoot ".tmp-$PID"
+$testUpdaterVersion = (Get-Content -LiteralPath (Join-Path $repoRoot "updater\updater.version") -Raw).Trim()
 $requiredPreserve = @(
     "models/**",
     "webui/voice/**",
@@ -33,6 +34,7 @@ function New-TestBundle {
     param([string]$Name)
     $root = Join-Path $testRoot $Name
     New-Item -ItemType Directory -Path (Join-Path $root "updater") -Force | Out-Null
+    Copy-Item -LiteralPath (Join-Path $repoRoot "update.bat") -Destination (Join-Path $root "update.bat")
     Copy-Item -LiteralPath (Join-Path $repoRoot "updater\updater.ps1") -Destination (Join-Path $root "updater\updater.ps1")
     Copy-Item -LiteralPath (Join-Path $repoRoot "updater\apply-update.ps1") -Destination (Join-Path $root "updater\apply-update.ps1")
     Copy-Item -LiteralPath (Join-Path $repoRoot "updater\updater.version") -Destination (Join-Path $root "updater\updater.version")
@@ -50,7 +52,7 @@ function New-TestBundle {
         channel = "stable"
         platform = "windows-x64"
         python = "3.11"
-        components = [ordered]@{ app = "0.2.0"; core_cpu = "0.2.0"; core_cuda = "0.2.0"; python_env = "0.2.0"; updater = "1.1.0" }
+        components = [ordered]@{ app = "0.2.0"; core_cpu = "0.2.0"; core_cuda = "0.2.0"; python_env = "0.2.0"; updater = $testUpdaterVersion }
     }
     Write-Json $version (Join-Path $root "version.json")
     return $root
@@ -132,7 +134,7 @@ function New-CustomManifest {
     param(
         [string]$Directory,
         [object[]]$Components,
-        [string]$MinimumUpdater = "1.1.0",
+        [string]$MinimumUpdater = $testUpdaterVersion,
         [string[]]$HealthChecks = @()
     )
     $value = [ordered]@{
@@ -271,6 +273,17 @@ function Invoke-TestUpdater {
     return [pscustomobject]@{ ExitCode = $exitCode; Output = ($output -join "`n") }
 }
 
+function Invoke-TestBatchUpdater {
+    param(
+        [string]$Root,
+        [string[]]$Arguments
+    )
+    $batchPath = Join-Path $Root "update.bat"
+    $output = @(& $batchPath @Arguments 2>&1)
+    $exitCode = $LASTEXITCODE
+    return [pscustomobject]@{ ExitCode = $exitCode; Output = ($output -join "`n") }
+}
+
 function Test-CheckMode {
     $root = New-TestBundle "check"
     $assets = Join-Path $root "assets"
@@ -282,6 +295,30 @@ function Test-CheckMode {
     Assert-True ((Read-JsonFile (Join-Path $root "version.json")).version -eq "0.2.0") "check mode changed version.json"
 }
 
+function Test-BatchStableChannelCheck {
+    $root = New-TestBundle "batch entry with spaces"
+    $assets = Join-Path $root "release assets"
+    New-Item -ItemType Directory -Path $assets -Force | Out-Null
+    $archive = New-TestArchive $assets "app.zip" "webui/managed.txt"
+    $manifest = New-TestManifest $assets $archive
+    $stable = Join-Path $assets "stable.json"
+    Write-Json ([ordered]@{
+        schema = 1
+        channel = "stable"
+        version = "0.2.1"
+        manifest_url = $manifest
+        signature_url = "$manifest.minisig"
+        notes_url = "https://example.invalid/audio.cpp/v0.2.1"
+    }) $stable
+    $result = Invoke-TestBatchUpdater $root @(
+        "--check", "-StableUrl", $stable,
+        "-MinisignPath", (Join-Path $root "updater\test-minisign.cmd"),
+        "-PublicKeyPath", (Join-Path $root "updater\test-public-key.txt")
+    )
+    Assert-True ($result.ExitCode -eq 0) "update.bat stable-channel check failed: $($result.Output)"
+    Assert-True ($result.Output -match "Target version\s+: 0\.2\.1") "update.bat did not report the stable target version"
+}
+
 function Read-JsonFile {
     param([string]$Path)
     return Get-Content -LiteralPath $Path -Raw -Encoding UTF8 | ConvertFrom-Json
@@ -344,10 +381,20 @@ function Test-ProtectedPathAndLock {
     Assert-True ($result.ExitCode -ne 0) "updater accepted a protected payload path"
 
     New-Item -ItemType Directory -Path (Join-Path $root "_update") -Force | Out-Null
-    Set-Content -LiteralPath (Join-Path $root "_update\update.lock") -Value "owned by another process" -Encoding ASCII
+    $lockPath = Join-Path $root "_update\update.lock"
+    $lockStream = [IO.File]::Open($lockPath, [IO.FileMode]::CreateNew, [IO.FileAccess]::Write, [IO.FileShare]::None)
+    try {
+        $result = Invoke-TestUpdater $root "--check" $manifest
+        Assert-True ($result.ExitCode -ne 0) "updater ignored an active lock"
+        Assert-True (Test-Path -LiteralPath $lockPath) "updater removed another process's active lock"
+    } finally {
+        $lockStream.Dispose()
+    }
+
+    Set-Content -LiteralPath $lockPath -Value "stale interrupted update" -Encoding ASCII
     $result = Invoke-TestUpdater $root "--check" $manifest
-    Assert-True ($result.ExitCode -ne 0) "updater ignored an existing lock"
-    Assert-True (Test-Path -LiteralPath (Join-Path $root "_update\update.lock")) "updater removed another process's lock"
+    Assert-True ($result.ExitCode -eq 0) "updater did not recover from a stale lock: $($result.Output)"
+    Assert-True (-not (Test-Path -LiteralPath $lockPath)) "updater left the recovered stale lock behind"
 }
 
 function Test-PythonDependencyUpdateAndRollback {
@@ -466,7 +513,7 @@ function Test-ReleaseBuilder {
         "audiocpp-core-cpu-win-x64-v0.2.1.zip",
         "audiocpp-core-cuda-win-x64-v0.2.1.zip",
         "audiocpp-python-deps-py311-win-x64-v0.2.1.zip",
-        "audiocpp-updater-v1.1.0.zip",
+        "audiocpp-updater-v$testUpdaterVersion.zip",
         "manifest-v0.2.1.json",
         "manifest-v0.2.1.json.minisig",
         "stable.json",
@@ -479,6 +526,7 @@ function Test-ReleaseBuilder {
     $manifest = Read-JsonFile (Join-Path $output "manifest-v0.2.1.json")
     Assert-True (@($manifest.components).Count -eq 5) "release manifest does not contain all five component types"
     Assert-True (@($manifest.preserve) -contains "webui/voice/**") "release manifest omitted voice preservation"
+    Assert-True ([string]$manifest.supported_from -eq ">=0.2.0") "release manifest does not keep bootstrap installs eligible for later versions"
     $stable = Read-JsonFile (Join-Path $output "stable.json")
     Assert-True ([string]$stable.manifest_url -match '/v0\.2\.1-windows-prebuilt/manifest-v0\.2\.1\.json$') "stable.json points at the wrong manifest"
 
@@ -494,13 +542,16 @@ function Test-ReleaseBuilder {
     foreach ($relative in @("update.bat", "version.json", "updater\updater.ps1", "updater\apply-update.ps1", "updater\updater.version", "updater\public-key.txt", "updater\minisign.exe")) {
         Assert-True (Test-Path -LiteralPath (Join-Path $bootstrapExpanded $relative) -PathType Leaf) "bootstrap ZIP omitted $relative"
     }
+    $bootstrapVersion = Read-JsonFile (Join-Path $bootstrapExpanded "version.json")
+    Assert-True ([string]$bootstrapVersion.components.updater -eq $testUpdaterVersion) "bootstrap version.json does not match updater.version"
 }
 
 try {
     if (Test-Path -LiteralPath $testRoot) { Remove-Item -LiteralPath $testRoot -Recurse -Force }
     New-Item -ItemType Directory -Path $testRoot -Force | Out-Null
     $tests = @(
         "Test-CheckMode",
+        "Test-BatchStableChannelCheck",
         "Test-DryRunAndHashValidation",
         "Test-ApplySuccessAndPreserve",
         "Test-RollbackOnHealthFailure",

update.bat

@@ -1,15 +1,7 @@
 @echo off
 setlocal
 
-set "ROOT=%~dp0"
-set "UPDATER=%ROOT%updater\updater.ps1"
-
-if not exist "%UPDATER%" (
-  echo [audio.cpp updater] Missing: "%UPDATER%"
-  exit /b 2
-)
-
-powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File "%UPDATER%" %*
+"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoLogo -NoProfile -ExecutionPolicy Bypass -File "%~dp0updater\updater.ps1" %*
 set "EXIT_CODE=%ERRORLEVEL%"
 
 if "%~1"=="" (

updater/README.md

@@ -30,6 +30,11 @@ secret key outside the repository and outside the portable package.
 Release assets are generated by `scripts/build_update_release.ps1`. The
 self-contained updater acceptance test is `tests/updater/run_tests.ps1`.
 
+`update.bat` is intentionally only a launcher. Argument parsing, online checks,
+downloads, validation, locking, installation, health checks, and rollback all
+live in the PowerShell scripts so updater maintenance does not require batch
+logic changes.
+
 Generate the one-time overlay patch for existing `0.2.0` bundles with:
 
 ```powershell
@@ -51,6 +56,11 @@ CPU/CUDA executables with:
   -Stable
 ```
 
+The default compatibility range is `>=0.2.0`, so bundles that receive the
+one-time 0.2.0 bootstrap remain eligible for later 0.3.x and newer releases.
+Use `-SupportedFrom` only when a future release intentionally drops an older
+portable layout.
+
 When Python dependencies change, prepare a directory with this layout and pass
 it as `-PythonDepsSource`:
 
@@ -112,7 +122,7 @@ Build a release containing dependency and updater components with:
   -PythonDepsSource C:\release-work\python-deps-v0.2.1 `
   -IncludeUpdater `
   -UpdaterMinisignBinary C:\release-tools\minisign.exe `
-  -MinimumUpdater 1.1.0 `
+  -MinimumUpdater 1.1.1 `
   -MinisignSecretKey C:\secure\audio-cpp.key `
   -MinisignPublicKey C:\release-tools\audio-cpp.pub `
   -MinisignPath C:\release-tools\minisign.exe `
@@ -123,6 +133,17 @@ Omit `-PythonDepsSource` when dependencies did not change. Omit
 `-IncludeUpdater` when updater files did not change. The release builder always
 generates app, core-cpu, and core-cuda snapshots.
 
+For every stable online release, publish the generated `stable.json`, signed
+manifest, manifest signature, and all component ZIPs in the same non-draft,
+non-prerelease GitHub Release, and mark that Release as latest. The updater's
+permanent channel URL is GitHub's `releases/latest/download/stable.json`; if the
+latest Release omits `stable.json`, online checks will correctly fail instead
+of installing an ambiguous payload.
+
+After publishing, extract the bootstrap over a clean 0.2.0 portable copy and
+run `update.bat --check`. Do not distribute the bootstrap until that command
+reports the newly published target version through the default channel URL.
+
 The bootstrap ZIP is the small net-disk patch described by the release plan.
 It contains the updater and local version metadata, but no models, Python
 environment, application payload, or runtime binaries.