diff --git a/home/dot_config/powershell/README.md b/home/dot_config/powershell/README.md index 69cd944b..1ce83586 100644 --- a/home/dot_config/powershell/README.md +++ b/home/dot_config/powershell/README.md @@ -41,18 +41,39 @@ After installation, start a new PowerShell session. Type `aliases` to see all av ### Winget Upgrade Commands -- `wup` or `winup` - Check for and upgrade all winget packages with a 3-second countdown +- `wup` or `winup` - Check for and upgrade winget packages with a 3-second countdown - `Test-WingetUpdates` - Check if any package updates are available (returns true/false) - `Invoke-WingetUpgrade` - Full upgrade function with customizable options +**Soak time:** by default, `Invoke-WingetUpgrade` only installs package versions +that have been published in [winget-pkgs](https://github.com/microsoft/winget-pkgs) +for at least 7 days. Each package is pinned to the newest version that is old +enough; packages without one are skipped and listed in the summary. A version's +age is when its manifest folder was added to winget-pkgs, looked up through the +GitHub API (`gh api` when signed in, otherwise unauthenticated requests, which +also covers a gh token blocked by SAML enforcement). When the age can't be +determined, the package is skipped. Soak needs the Microsoft.WinGet.Client +module. winget has no native minimum package age yet; once +[microsoft/winget-cli#6178](https://github.com/microsoft/winget-cli/issues/6178) +lands, this can move to winget's own setting. + **Examples:** ```powershell # Check for updates Test-WingetUpdates -# Upgrade all packages (3-second countdown) +# Upgrade packages to versions at least 7 days old (3-second countdown) wup +# Preview what would be upgraded, to which version, and what is skipped +Invoke-WingetUpgrade -WhatIf + +# Require versions to be at least 14 days old +Invoke-WingetUpgrade -SoakDays 14 + +# Upgrade everything to the newest version, regardless of age +Invoke-WingetUpgrade -NoSoak + # Upgrade immediately without countdown Invoke-WingetUpgrade -CountdownSeconds 0 diff --git a/home/dot_config/powershell/modules/DotfilesHelpers/Public/WingetUtilities.ps1 b/home/dot_config/powershell/modules/DotfilesHelpers/Public/WingetUtilities.ps1 index 9187f0a6..cafa2013 100644 --- a/home/dot_config/powershell/modules/DotfilesHelpers/Public/WingetUtilities.ps1 +++ b/home/dot_config/powershell/modules/DotfilesHelpers/Public/WingetUtilities.ps1 @@ -85,15 +85,277 @@ function Test-WingetUpdates { return $false } +# Soak time: only upgrade to package versions that have been published in +# microsoft/winget-pkgs for at least N days. winget has no native minimum +# package age yet (see microsoft/winget-cli#6178), so the age is derived from +# the community repository: a version folder that already existed in the +# repository N days ago was first committed at least N days ago. + +function Get-WingetManifestPath { + # Private helper: 'Git.Git' -> 'manifests/g/Git/Git'. + [CmdletBinding()] + [OutputType([string])] + param( + [Parameter(Mandatory = $true)] + [ValidateNotNullOrEmpty()] + [string]$PackageId + ) + + $first = $PackageId.Substring(0, 1).ToLowerInvariant() + return "manifests/$first/$(($PackageId -split '\.') -join '/')" +} + +function Invoke-WingetPkgsGh { + # Private helper: single `gh api` call so tests can mock the process launch. + [CmdletBinding()] + param( + [Parameter(Mandatory = $true)] + [string]$Endpoint + ) + + # Native stderr becomes an ErrorRecord; under a caller's 'Stop' preference, + # Windows PowerShell 5.1 would turn it into a terminating error. + $ErrorActionPreference = 'Continue' + $output = & gh api --hostname github.com $Endpoint 2>&1 + return [PSCustomObject]@{ + ExitCode = $LASTEXITCODE + Output = ($output | Out-String).Trim() + } +} + +function Invoke-WingetPkgsApi { + <# + .SYNOPSIS + Private helper: GET a GitHub REST endpoint for the public winget-pkgs repo. + .DESCRIPTION + Uses `gh api` when gh is available, which gets the authenticated rate + limit. When gh fails (SAML enforcement on the microsoft org, a bad + token, rate limiting), the rest of the run falls back to unauthenticated + requests, which work because winget-pkgs is public (60 requests/hour). + Returns $null for HTTP 404 and throws on any other failure. + #> + [CmdletBinding()] + param( + [Parameter(Mandatory = $true)] + [string]$Endpoint + ) + + if (-not $script:WingetPkgsGhDisabled -and (Get-Command gh -ErrorAction SilentlyContinue)) { + try { + $result = Invoke-WingetPkgsGh -Endpoint $Endpoint + } + catch { + $result = [PSCustomObject]@{ ExitCode = 1; Output = "$_" } + } + if ($result.ExitCode -eq 0) { + return ($result.Output | ConvertFrom-Json) + } + if ($result.Output -match 'HTTP 404') { + return $null + } + Write-Verbose "gh api $Endpoint failed; using unauthenticated requests for the rest of this run: $($result.Output)" + $script:WingetPkgsGhDisabled = $true + } + + $headers = @{ Accept = 'application/vnd.github+json'; 'User-Agent' = 'DevSecNinja-dotfiles-winget-soak' } + try { + return (Invoke-RestMethod -Uri "https://api.github.com/$Endpoint" -Headers $headers -ErrorAction Stop) + } + catch { + $statusCode = $null + try { $statusCode = [int]$_.Exception.Response.StatusCode } catch { $statusCode = $null } + if ($statusCode -eq 404) { + return $null + } + if ("$_" -match 'rate limit') { + throw "GitHub API rate limit reached (unauthenticated: 60 requests/hour)" + } + throw "GitHub API request for $Endpoint failed: $($_.Exception.Message)" + } +} + +function Get-WingetSoakCutoffRef { + # Private helper: the winget-pkgs master commit as of the cutoff time. + [CmdletBinding()] + [OutputType([string])] + param( + [Parameter(Mandatory = $true)] + [datetime]$Cutoff + ) + + $until = $Cutoff.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ', [System.Globalization.CultureInfo]::InvariantCulture) + $commits = @(Invoke-WingetPkgsApi -Endpoint "repos/microsoft/winget-pkgs/commits?sha=master&until=$until&per_page=1") + if ($commits.Count -eq 0 -or -not $commits[0].sha) { + throw "No winget-pkgs commit found before $until" + } + return [string]$commits[0].sha +} + +function Get-WingetSoakedVersion { + # Private helper: version folders that existed for a package at the cutoff commit. + [CmdletBinding()] + param( + [Parameter(Mandatory = $true)] + [string]$PackageId, + + [Parameter(Mandatory = $true)] + [string]$Ref + ) + + $path = Get-WingetManifestPath -PackageId $PackageId + # A 404 means the package was not in winget-pkgs yet at the cutoff. + $entries = @(Invoke-WingetPkgsApi -Endpoint "repos/microsoft/winget-pkgs/contents/$path`?ref=$Ref") + return @($entries | Where-Object { $_ -and $_.type -eq 'dir' } | ForEach-Object { [string]$_.name }) +} + +function Select-WingetSoakTarget { + <# + .SYNOPSIS + Private helper: pick the newest upgrade that has soaked long enough. + .DESCRIPTION + Walks AvailableVersions (newest first, as winget returns them) and + returns the first version that is newer than the installed one and + present in SoakedVersions. Version ordering is left to winget via the + package's CompareToVersion method, which also understands installed + versions such as '< 8.12.46.29'. + #> + [CmdletBinding()] + param( + [Parameter(Mandatory = $true)] + $Package, + + [Parameter(Mandatory = $false)] + [AllowEmptyCollection()] + [string[]]$SoakedVersions = @() + ) + + $soaked = @{} + foreach ($version in $SoakedVersions) { $soaked[$version] = $true } + + foreach ($version in @($Package.AvailableVersions)) { + if ("$($Package.CompareToVersion($version))" -ne 'Lesser') { + continue + } + if ($soaked.ContainsKey($version)) { + return $version + } + } + return $null +} + +function Get-WingetSoakPlan { + <# + .SYNOPSIS + Private helper: decide which version to upgrade each package to. + .DESCRIPTION + Returns one object per package with Target set to the version to + install, or Target $null and a Reason when the package is skipped. + Fails closed: when the manifest dates cannot be determined, the package + is skipped with a warning. + #> + [CmdletBinding()] + param( + [Parameter(Mandatory = $true)] + [AllowEmptyCollection()] + [object[]]$Packages, + + [Parameter(Mandatory = $true)] + [int]$SoakDays, + + [Parameter(Mandatory = $true)] + [datetime]$Cutoff + ) + + $script:WingetPkgsGhDisabled = $false + $refError = $null + $ref = $null + try { + $ref = Get-WingetSoakCutoffRef -Cutoff $Cutoff + } + catch { + $refError = $_.Exception.Message + } + + foreach ($package in $Packages) { + $newest = @($package.AvailableVersions) | Select-Object -First 1 + $item = [PSCustomObject]@{ + Id = $package.Id + Name = $package.Name + InstalledVersion = $package.InstalledVersion + Newest = $newest + Target = $null + Reason = $null + } + + $lookupError = $refError + if (-not $lookupError) { + try { + $soaked = @(Get-WingetSoakedVersion -PackageId $package.Id -Ref $ref) + $item.Target = Select-WingetSoakTarget -Package $package -SoakedVersions $soaked + if (-not $item.Target) { + $item.Reason = "no update is $SoakDays+ days old yet (newest: $newest)" + } + } + catch { + $lookupError = $_.Exception.Message + } + } + + if ($lookupError) { + $item.Reason = "could not determine manifest dates: $lookupError" + Write-Warning "Skipping $($package.Id): $($item.Reason)" + } + + $item + } +} + +function Invoke-WingetCountdown { + # Private helper: cancellable countdown, skipped in CI/non-interactive sessions. + [CmdletBinding()] + param( + [Parameter(Mandatory = $true)] + [int]$Seconds + ) + + if ($Seconds -le 0) { return } + + if ([bool]$env:CI -or -not [Environment]::UserInteractive) { + Write-Host "`n[SKIP] Skipping countdown (CI/non-interactive environment)" -ForegroundColor Yellow + return + } + + Write-Host "`nExecution Phase: Starting upgrade in $Seconds seconds..." -ForegroundColor Yellow + Write-Host " Press Ctrl+C to cancel" -ForegroundColor Gray + for ($i = $Seconds; $i -gt 0; $i--) { + Write-Host " $i..." -ForegroundColor Yellow + Start-Sleep -Seconds 1 + } + Write-Host " GO!" -ForegroundColor Green +} + function Invoke-WingetUpgrade { <# .SYNOPSIS - Upgrades all winget packages after a countdown timer. + Upgrades winget packages to versions that have soaked for a number of days. .DESCRIPTION Performs winget package upgrades with a 3-second countdown that can be cancelled. Only runs if updates are detected. Uses Microsoft.WinGet.Client module when available. + By default each package is upgraded to the newest available version that has + been published in microsoft/winget-pkgs for at least SoakDays days (7 by + default), so brand-new releases get time to be pulled or fixed before they + land on this machine. Packages without such a version are skipped and listed + in the summary. A version's age is the time since its manifest folder was + added to winget-pkgs, looked up through the GitHub API (gh api when signed + in, unauthenticated requests otherwise). When the age cannot be determined, + the package is skipped (fail closed). Soak requires the Microsoft.WinGet.Client + module. + + winget has no native minimum package age yet; see + https://github.com/microsoft/winget-cli/issues/6178. + .PARAMETER CountdownSeconds Number of seconds to wait before starting the upgrade. Defaults to 3. Set to 0 to skip countdown. @@ -105,9 +367,28 @@ function Invoke-WingetUpgrade { Use the Microsoft.WinGet.Client PowerShell module instead of winget.exe. Defaults to true for better performance and compatibility. + .PARAMETER SoakDays + Minimum number of days a package version must have been published in + winget-pkgs before it is installed. Defaults to 7. 0 disables the soak. + + .PARAMETER NoSoak + Disable the soak and upgrade every package to its newest version. + .EXAMPLE Invoke-WingetUpgrade - Checks for updates, then upgrades all packages after 3-second countdown. + Checks for updates, then upgrades packages to versions at least 7 days old after a 3-second countdown. + + .EXAMPLE + Invoke-WingetUpgrade -WhatIf + Shows which packages would be upgraded, to which version, and which are skipped. + + .EXAMPLE + Invoke-WingetUpgrade -SoakDays 14 + Only installs versions that have been published for at least 14 days. + + .EXAMPLE + Invoke-WingetUpgrade -NoSoak + Upgrades all packages to their newest version, regardless of age. .EXAMPLE Invoke-WingetUpgrade -CountdownSeconds 0 @@ -121,7 +402,7 @@ function Invoke-WingetUpgrade { Requires Microsoft.WinGet.Client module or winget.exe to be installed. Press Ctrl+C during countdown to cancel. #> - [CmdletBinding()] + [CmdletBinding(SupportsShouldProcess = $true)] param( [Parameter(Mandatory = $false)] [int]$CountdownSeconds = 3, @@ -130,11 +411,25 @@ function Invoke-WingetUpgrade { [switch]$Force, [Parameter(Mandatory = $false)] - [bool]$UseWingetModule = $true + [bool]$UseWingetModule = $true, + + [Parameter(Mandatory = $false)] + [ValidateRange(0, 365)] + [int]$SoakDays = 7, + + [Parameter(Mandatory = $false)] + [switch]$NoSoak ) + $soakEnabled = (-not $NoSoak) -and $SoakDays -gt 0 + $isWhatIf = [bool]$WhatIfPreference + $countdown = if ($isWhatIf) { 0 } else { $CountdownSeconds } + Write-Host "`n>> Winget Package Upgrade" -ForegroundColor Cyan Write-Host "================================" -ForegroundColor Cyan + if ($soakEnabled) { + Write-Host "Soak: only versions published $SoakDays+ days ago (use -NoSoak to disable)" -ForegroundColor Gray + } # Detection phase (skip if Force is specified) if (-not $Force) { @@ -150,30 +445,6 @@ function Invoke-WingetUpgrade { Write-Host "`n[WARN] Skipping detection phase (Force mode)" -ForegroundColor Yellow } - # Countdown phase - if ($CountdownSeconds -gt 0) { - # Skip countdown in CI or non-interactive environments - $isCI = [bool]$env:CI - $isNonInteractive = -not [Environment]::UserInteractive - - if ($isCI -or $isNonInteractive) { - Write-Host "`n[SKIP] Skipping countdown (CI/non-interactive environment)" -ForegroundColor Yellow - } - else { - Write-Host "`nExecution Phase: Starting upgrade in $CountdownSeconds seconds..." -ForegroundColor Yellow - Write-Host " Press Ctrl+C to cancel" -ForegroundColor Gray - - for ($i = $CountdownSeconds; $i -gt 0; $i--) { - Write-Host " $i..." -ForegroundColor Yellow - Start-Sleep -Seconds 1 - } - Write-Host " GO!" -ForegroundColor Green - } - } - - # Execution phase - Write-Host "`n>> Starting package upgrades..." -ForegroundColor Cyan - # Check if Microsoft.WinGet.Client is available $wingetModule = Get-Module -Name Microsoft.WinGet.Client -ListAvailable -ErrorAction SilentlyContinue @@ -181,40 +452,108 @@ function Invoke-WingetUpgrade { try { Import-Module Microsoft.WinGet.Client -ErrorAction Stop + Write-Host "`n>> Planning package upgrades..." -ForegroundColor Cyan Write-Host " Using Microsoft.WinGet.Client module..." -ForegroundColor Gray # Get packages with updates - $packagesToUpdate = Get-WinGetPackage -Source winget | Where-Object { $_.IsUpdateAvailable } + $packagesToUpdate = @(Get-WinGetPackage -Source winget | Where-Object { $_.IsUpdateAvailable }) - if (-not $packagesToUpdate -or $packagesToUpdate.Count -eq 0) { + if ($packagesToUpdate.Count -eq 0) { Write-Host "[OK] No packages to upgrade" -ForegroundColor Green return } - Write-Host " Found $($packagesToUpdate.Count) package(s) to upgrade`n" -ForegroundColor Gray + if ($soakEnabled) { + $cutoff = (Get-Date).ToUniversalTime().AddDays(-$SoakDays) + Write-Host " Checking winget-pkgs for versions published before $($cutoff.ToString('yyyy-MM-dd HH:mm')) UTC..." -ForegroundColor Gray + $plan = @(Get-WingetSoakPlan -Packages $packagesToUpdate -SoakDays $SoakDays -Cutoff $cutoff) + } + else { + $plan = @($packagesToUpdate | ForEach-Object { + [PSCustomObject]@{ + Id = $_.Id + Name = $_.Name + InstalledVersion = $_.InstalledVersion + Newest = @($_.AvailableVersions) | Select-Object -First 1 + Target = $null + Reason = $null + } + }) + } + + $toUpgrade = @($plan | Where-Object { -not $_.Reason }) + $skipped = @($plan | Where-Object { $_.Reason }) + + Write-Host "`nUpgrade plan:" -ForegroundColor Cyan + foreach ($item in $toUpgrade) { + $version = if ($item.Target) { $item.Target } else { $item.Newest } + $note = if ($item.Target -and $item.Target -ne $item.Newest) { " (newest $($item.Newest) is under $SoakDays days old)" } else { '' } + Write-Host (" {0,-40} {1} -> {2}{3}" -f $item.Id, $item.InstalledVersion, $version, $note) + } + if ($toUpgrade.Count -eq 0) { + Write-Host " (nothing to upgrade)" -ForegroundColor Gray + } + if ($skipped.Count -gt 0) { + Write-Host "Skipped:" -ForegroundColor Yellow + foreach ($item in $skipped) { + Write-Host (" {0,-40} {1}" -f $item.Id, $item.Reason) -ForegroundColor Yellow + } + } + + if ($toUpgrade.Count -eq 0) { + Write-Host "`n[OK] Nothing to upgrade yet" -ForegroundColor Green + return + } + + Invoke-WingetCountdown -Seconds $countdown + if (-not $isWhatIf) { + Write-Host "`n>> Starting package upgrades..." -ForegroundColor Cyan + } # Upgrade each package $successCount = 0 $failCount = 0 - foreach ($package in $packagesToUpdate) { - Write-Host " Upgrading $($package.Name)..." -NoNewline + foreach ($item in $toUpgrade) { + $action = if ($item.Target) { "Upgrade to $($item.Target)" } else { 'Upgrade to latest' } + if (-not $PSCmdlet.ShouldProcess($item.Id, $action)) { + continue + } + + Write-Host " Upgrading $($item.Name)..." -NoNewline + + $updateParams = @{ + Id = $item.Id + Source = 'winget' + Mode = 'Silent' + Force = $true + ErrorAction = 'Stop' + } + if ($item.Target) { + $updateParams['Version'] = $item.Target + $updateParams['MatchOption'] = 'Equals' + } try { - Update-WinGetPackage -Id $package.Id -Source winget -Mode Silent -Force -ErrorAction Stop | Out-Null + Update-WinGetPackage @updateParams | Out-Null Write-Host " OK" -ForegroundColor Green $successCount++ } catch { Write-Host " FAIL" -ForegroundColor Red - Write-Warning "Failed to upgrade $($package.Name): $_" + Write-Warning "Failed to upgrade $($item.Name): $_" $failCount++ } } + if ($isWhatIf) { + return + } + Write-Host "`nUpgrade Summary:" -ForegroundColor Cyan Write-Host " Successful: $successCount" -ForegroundColor Green Write-Host " Failed: $failCount" -ForegroundColor $(if ($failCount -gt 0) { 'Red' } else { 'Gray' }) + Write-Host " Skipped: $($skipped.Count)" -ForegroundColor $(if ($skipped.Count -gt 0) { 'Yellow' } else { 'Gray' }) } catch { Write-Warning "Failed to use Microsoft.WinGet.Client module: $_" @@ -225,12 +564,23 @@ function Invoke-WingetUpgrade { # Fallback to winget.exe if module not available or failed if (-not $UseWingetModule -or -not $wingetModule) { + if ($soakEnabled) { + Write-Warning "Soak requires the Microsoft.WinGet.Client module (Install-Module -Name Microsoft.WinGet.Client). Rerun with -NoSoak to upgrade everything with winget.exe." + return + } + if (-not (Get-Command winget -ErrorAction SilentlyContinue)) { Write-Error "Neither Microsoft.WinGet.Client module nor winget.exe is available." Write-Error "Please install Microsoft.WinGet.Client: Install-Module -Name Microsoft.WinGet.Client" return } + if (-not $PSCmdlet.ShouldProcess('all winget packages', 'winget upgrade --all')) { + return + } + + Invoke-WingetCountdown -Seconds $countdown + Write-Host "`n>> Starting package upgrades..." -ForegroundColor Cyan Write-Host " Using winget.exe..." -ForegroundColor Gray winget upgrade --all --source winget --silent --accept-package-agreements --accept-source-agreements diff --git a/tests/powershell/Profile.Tests.ps1 b/tests/powershell/Profile.Tests.ps1 index 3f8afba1..886cacad 100644 --- a/tests/powershell/Profile.Tests.ps1 +++ b/tests/powershell/Profile.Tests.ps1 @@ -304,6 +304,14 @@ Describe "DotfilesHelpers Module" { 'Get-ChezmoiBranchConfirmation' 'Test-ChezmoiSourceBranch' 'Get-GitCredentialSwitchConfirmation' + 'Get-WingetManifestPath' + 'Invoke-WingetPkgsGh' + 'Invoke-WingetPkgsApi' + 'Get-WingetSoakCutoffRef' + 'Get-WingetSoakedVersion' + 'Select-WingetSoakTarget' + 'Get-WingetSoakPlan' + 'Invoke-WingetCountdown' 'Invoke-GitHubCli' 'Invoke-OnePasswordCli' 'ConvertFrom-OnePasswordReference' diff --git a/tests/powershell/WingetUpgrade.Tests.ps1 b/tests/powershell/WingetUpgrade.Tests.ps1 index ad27047c..e24a83c4 100644 --- a/tests/powershell/WingetUpgrade.Tests.ps1 +++ b/tests/powershell/WingetUpgrade.Tests.ps1 @@ -163,6 +163,219 @@ Describe "Winget Upgrade Functions" -Tag "Unit" { } } +Describe "Winget Soak" -Tag "Unit" { + BeforeAll { + # Stubs for CI runners without Microsoft.WinGet.Client. Pinned upgrades + # pass -Version/-MatchOption, so the stub must declare them for mocking. + $updateCmd = Get-Command Update-WinGetPackage -ErrorAction SilentlyContinue + if (-not $updateCmd -or -not $updateCmd.Parameters.ContainsKey('Version')) { + function global:Update-WinGetPackage { + [CmdletBinding()] + param([string]$Id, [string]$Source, [string]$Mode, [switch]$Force, [string]$Version, [string]$MatchOption) + } + } + if (-not (Get-Command Get-WinGetPackage -ErrorAction SilentlyContinue)) { + function global:Get-WinGetPackage { param([string]$Source) } + } + + # Mimics PSInstalledCatalogPackage, including winget's CompareToVersion. + function New-TestWingetPackage { + param([string]$Id, [string]$Installed, [string[]]$Available) + $pkg = [PSCustomObject]@{ + Id = $Id + Name = $Id + InstalledVersion = $Installed + AvailableVersions = $Available + IsUpdateAvailable = $true + } + $pkg | Add-Member -MemberType ScriptMethod -Name CompareToVersion -Value { + param($Other) + $mine = [version]$this.InstalledVersion + $theirs = [version]$Other + if ($mine -lt $theirs) { 'Lesser' } elseif ($mine -gt $theirs) { 'Greater' } else { 'Equal' } + } + return $pkg + } + + $script:FixedNow = [datetime]::new(2026, 11, 20, 12, 0, 0, [DateTimeKind]::Utc) + } + + Context "Version selection" { + It "maps package IDs to winget-pkgs manifest paths" { + InModuleScope DotfilesHelpers { + Get-WingetManifestPath -PackageId 'Git.Git' | Should -Be 'manifests/g/Git/Git' + Get-WingetManifestPath -PackageId 'Microsoft.VisualStudio.2022.Community' | + Should -Be 'manifests/m/Microsoft/VisualStudio/2022/Community' + } + } + + It "picks the newest version that is old enough, not the newest overall" { + $pkg = New-TestWingetPackage -Id 'Test.Pkg' -Installed '1.0.0' -Available @('1.3.0', '1.2.0', '1.1.0', '1.0.0') + InModuleScope DotfilesHelpers -Parameters @{ Pkg = $pkg } { + Select-WingetSoakTarget -Package $Pkg -SoakedVersions @('1.0.0', '1.1.0', '1.2.0') | Should -Be '1.2.0' + } + } + + It "returns nothing when only the installed or older versions are old enough" { + $pkg = New-TestWingetPackage -Id 'Test.Pkg' -Installed '1.0.0' -Available @('1.1.0', '1.0.0', '0.9.0') + InModuleScope DotfilesHelpers -Parameters @{ Pkg = $pkg } { + Select-WingetSoakTarget -Package $Pkg -SoakedVersions @('0.9.0', '1.0.0') | Should -BeNullOrEmpty + } + } + } + + Context "GitHub API transport" { + BeforeEach { + InModuleScope DotfilesHelpers { $script:WingetPkgsGhDisabled = $false } + Mock Get-Command { [PSCustomObject]@{ Name = 'gh' } } -ParameterFilter { $Name -eq 'gh' } -ModuleName DotfilesHelpers + Mock Invoke-RestMethod { @([PSCustomObject]@{ sha = 'from-rest' }) } -ModuleName DotfilesHelpers + } + + It "uses gh api when it works" { + Mock Invoke-WingetPkgsGh { [PSCustomObject]@{ ExitCode = 0; Output = '[{"sha":"from-gh"}]' } } -ModuleName DotfilesHelpers + + $result = InModuleScope DotfilesHelpers { @(Invoke-WingetPkgsApi -Endpoint 'repos/microsoft/winget-pkgs/commits') } + + $result[0].sha | Should -Be 'from-gh' + Should -Invoke Invoke-RestMethod -Times 0 -ModuleName DotfilesHelpers + } + + It "falls back to unauthenticated requests on a SAML 403 and stops using gh" { + Mock Invoke-WingetPkgsGh { + [PSCustomObject]@{ ExitCode = 1; Output = 'gh: Resource protected by organization SAML enforcement. (HTTP 403)' } + } -ModuleName DotfilesHelpers + + $result = InModuleScope DotfilesHelpers { + $null = Invoke-WingetPkgsApi -Endpoint 'repos/microsoft/winget-pkgs/commits' + @(Invoke-WingetPkgsApi -Endpoint 'repos/microsoft/winget-pkgs/commits') + } + + $result[0].sha | Should -Be 'from-rest' + Should -Invoke Invoke-WingetPkgsGh -Times 1 -Exactly -ModuleName DotfilesHelpers + Should -Invoke Invoke-RestMethod -Times 2 -Exactly -ModuleName DotfilesHelpers + } + + It "falls back to unauthenticated requests when the gh call itself throws" { + Mock Invoke-WingetPkgsGh { throw 'gh: Resource protected by organization SAML enforcement. (HTTP 403)' } -ModuleName DotfilesHelpers + + $result = InModuleScope DotfilesHelpers { @(Invoke-WingetPkgsApi -Endpoint 'repos/microsoft/winget-pkgs/commits') } + + $result[0].sha | Should -Be 'from-rest' + } + + It "treats a gh 404 as a missing path without falling back" { + Mock Invoke-WingetPkgsGh { [PSCustomObject]@{ ExitCode = 1; Output = 'gh: Not Found (HTTP 404)' } } -ModuleName DotfilesHelpers + + InModuleScope DotfilesHelpers { Invoke-WingetPkgsApi -Endpoint 'repos/x/y/contents/z' } | Should -BeNullOrEmpty + Should -Invoke Invoke-RestMethod -Times 0 -ModuleName DotfilesHelpers + } + + It "reports an unauthenticated rate limit clearly" { + Mock Invoke-WingetPkgsGh { [PSCustomObject]@{ ExitCode = 1; Output = 'gh: API rate limit exceeded (HTTP 403)' } } -ModuleName DotfilesHelpers + Mock Invoke-RestMethod { throw 'API rate limit exceeded for 203.0.113.1.' } -ModuleName DotfilesHelpers + + { InModuleScope DotfilesHelpers { Invoke-WingetPkgsApi -Endpoint 'repos/microsoft/winget-pkgs/commits' } } | + Should -Throw '*rate limit reached*' + } + } + + Context "Invoke-WingetUpgrade" { + BeforeEach { + Mock Get-Module { [PSCustomObject]@{ Name = 'Microsoft.WinGet.Client' } } -ParameterFilter { $Name -eq 'Microsoft.WinGet.Client' } -ModuleName DotfilesHelpers + Mock Import-Module { } -ModuleName DotfilesHelpers + Mock Get-Date { $script:FixedNow } -ModuleName DotfilesHelpers + Mock Update-WinGetPackage { } -ModuleName DotfilesHelpers + $script:hostOutput = @() + Mock Write-Host { $script:hostOutput += "$Object" } -ModuleName DotfilesHelpers + + $script:testPackages = @( + New-TestWingetPackage -Id 'Old.Enough' -Installed '1.0.0' -Available @('1.2.0', '1.1.0', '1.0.0') + New-TestWingetPackage -Id 'Too.Fresh' -Installed '2.0.0' -Available @('2.1.0', '2.0.0') + ) + Mock Get-WinGetPackage { $script:testPackages } -ModuleName DotfilesHelpers + + # At the cutoff, Old.Enough 1.1.0 existed but 1.2.0 and Too.Fresh 2.1.0 did not. + Mock Invoke-WingetPkgsApi { + if ($Endpoint -like '*/commits*') { return [PSCustomObject]@{ sha = 'cutoff-sha' } } + if ($Endpoint -like '*/o/Old/Enough*') { + return @('1.0.0', '1.1.0') | ForEach-Object { [PSCustomObject]@{ name = $_; type = 'dir' } } + } + return [PSCustomObject]@{ name = '2.0.0'; type = 'dir' } + } -ModuleName DotfilesHelpers + } + + It "soaks 7 days by default and pins each upgrade to the soaked version" { + Invoke-WingetUpgrade -Force -CountdownSeconds 0 + + Should -Invoke Invoke-WingetPkgsApi -ModuleName DotfilesHelpers -Times 1 -Exactly -ParameterFilter { + $Endpoint -like '*until=2026-11-13T12:00:00Z*' + } + Should -Invoke Update-WinGetPackage -ModuleName DotfilesHelpers -Times 1 -Exactly -ParameterFilter { + $Id -eq 'Old.Enough' -and $Version -eq '1.1.0' -and $MatchOption -eq 'Equals' + } + Should -Invoke Update-WinGetPackage -ModuleName DotfilesHelpers -Times 0 -ParameterFilter { $Id -eq 'Too.Fresh' } + ($script:hostOutput -join "`n") | Should -Match 'Too\.Fresh\s+no update is 7\+ days old yet \(newest: 2\.1\.0\)' + } + + It "honours -SoakDays" { + Invoke-WingetUpgrade -Force -CountdownSeconds 0 -SoakDays 14 + + Should -Invoke Invoke-WingetPkgsApi -ModuleName DotfilesHelpers -Times 1 -Exactly -ParameterFilter { + $Endpoint -like '*until=2026-11-06T12:00:00Z*' + } + } + + It "upgrades everything to the newest version with " -TestCases @( + @{ Name = '-NoSoak'; Params = @{ NoSoak = $true } } + @{ Name = '-SoakDays 0'; Params = @{ SoakDays = 0 } } + ) { + Invoke-WingetUpgrade -Force -CountdownSeconds 0 @Params + + Should -Invoke Invoke-WingetPkgsApi -ModuleName DotfilesHelpers -Times 0 + Should -Invoke Update-WinGetPackage -ModuleName DotfilesHelpers -Times 2 -Exactly -ParameterFilter { -not $Version } + } + + It "skips only the package whose dates cannot be determined (fail closed)" { + Mock Invoke-WingetPkgsApi { + if ($Endpoint -like '*/commits*') { return [PSCustomObject]@{ sha = 'cutoff-sha' } } + if ($Endpoint -like '*/t/Too/Fresh*') { throw 'GitHub API request failed: 500' } + return [PSCustomObject]@{ name = '1.1.0'; type = 'dir' } + } -ModuleName DotfilesHelpers + + Invoke-WingetUpgrade -Force -CountdownSeconds 0 -WarningVariable warnings -WarningAction SilentlyContinue + + Should -Invoke Update-WinGetPackage -ModuleName DotfilesHelpers -Times 1 -Exactly -ParameterFilter { $Id -eq 'Old.Enough' } + ($warnings -join "`n") | Should -Match 'Skipping Too\.Fresh: could not determine manifest dates' + } + + It "skips every package when the cutoff commit cannot be found" { + Mock Invoke-WingetPkgsApi { throw 'GitHub API rate limit reached' } -ModuleName DotfilesHelpers + + Invoke-WingetUpgrade -Force -CountdownSeconds 0 -WarningAction SilentlyContinue + + Should -Invoke Update-WinGetPackage -ModuleName DotfilesHelpers -Times 0 + ($script:hostOutput -join "`n") | Should -Match 'Nothing to upgrade yet' + } + + It "shows the plan without upgrading under -WhatIf" { + Invoke-WingetUpgrade -Force -CountdownSeconds 0 -WhatIf + + Should -Invoke Update-WinGetPackage -ModuleName DotfilesHelpers -Times 0 + ($script:hostOutput -join "`n") | Should -Match 'Old\.Enough\s+1\.0\.0 -> 1\.1\.0' + } + + It "does not fall back to an unsoaked winget.exe upgrade without the module" { + Mock Get-Module { $null } -ParameterFilter { $Name -eq 'Microsoft.WinGet.Client' } -ModuleName DotfilesHelpers + Mock Get-Command { $null } -ParameterFilter { $Name -eq 'winget' } -ModuleName DotfilesHelpers + + Invoke-WingetUpgrade -Force -CountdownSeconds 0 -WarningVariable warnings -WarningAction SilentlyContinue -ErrorVariable errors -ErrorAction SilentlyContinue + + ($warnings -join "`n") | Should -Match 'Soak requires the Microsoft\.WinGet\.Client module' + $errors | Should -BeNullOrEmpty + } + } +} + Describe "Winget Upgrade Script" -Tag "Integration" { Context "Decoupled from chezmoi update" { # The winget upgrade is intentionally NOT wired into 'chezmoi apply' / @@ -356,8 +569,8 @@ Describe "E2E: Winget Upgrade Workflow" -Tag "E2E" { $hasUpdates = Test-WingetUpdates -UseWingetModule $true $hasUpdates | Should -Be $true - # Run upgrade with no countdown - { Invoke-WingetUpgrade -CountdownSeconds 0 -UseWingetModule $true } | Should -Not -Throw + # Run upgrade with no countdown (soak covered in "Winget Soak" tests) + { Invoke-WingetUpgrade -CountdownSeconds 0 -UseWingetModule $true -NoSoak } | Should -Not -Throw # Verify upgrade was called Should -Invoke Update-WinGetPackage -Times 1 -ModuleName DotfilesHelpers