@cats-inc/cats-platform 0.2.8 → 0.3.4

package/scripts/windows/Install-KiroCli.ps1

@@ -43,6 +43,7 @@ param(
   [switch]$Apply,
   [switch]$Upgrade,
   [switch]$Force,
+  [switch]$DryRun,
   [switch]$Json,
   [switch]$AllowAdmin,
   [ValidateSet('auto', 'installed', 'missing')]
@@ -55,6 +56,7 @@ Set-StrictMode -Version Latest
 $ErrorActionPreference = 'Stop'
 
 . (Join-Path $PSScriptRoot '_HiddenProcess.ps1')
+. (Join-Path $PSScriptRoot '_NativeInstallerSupport.ps1')
 
 function Write-StructuredResult {
   param(
@@ -62,6 +64,10 @@ function Write-StructuredResult {
     [int]$ExitCode
   )
 
+  if (Get-Variable -Name catsInitialObservation -Scope Script -ErrorAction SilentlyContinue) {
+    Add-CatsNativeObservation -Result $Result -Before $script:catsInitialObservation -Attempted ([bool]$script:shouldInstall) -Skipped ([bool]$SkipInstaller)
+  }
+
   if ($Json) {
     $Result | ConvertTo-Json -Depth 10
   } else {
@@ -86,7 +92,11 @@ function Write-StructuredResult {
 }
 
 function Resolve-KiroExecutablePath {
-  return Join-Path $env:ProgramFiles 'Kiro-Cli\kiro-cli.exe'
+  $perUser = Join-Path $env:LOCALAPPDATA 'Kiro-Cli\kiro-cli.exe'
+  $machine = Join-Path $env:ProgramFiles 'Kiro-Cli\kiro-cli.exe'
+  if (Test-Path -LiteralPath $perUser -PathType Leaf) { return $perUser }
+  if (Test-Path -LiteralPath $machine -PathType Leaf) { return $machine }
+  return $perUser
 }
 
 function Refresh-UserPath {
@@ -145,12 +155,8 @@ function Invoke-KiroInstaller {
     }
   }
 
-  $installScript = Invoke-RestMethod 'https://cli.kiro.dev/install.ps1'
-  Invoke-Expression $installScript
-
-  return [pscustomobject]@{
-    skipped = $false
-  }
+  $installScript = Invoke-RestMethod -TimeoutSec 30 -UseBasicParsing 'https://cli.kiro.dev/install.ps1'
+  return Invoke-CatsRemoteInstaller -ScriptText $installScript
 }
 
 if (-not $CheckOnly -and -not $Apply -and -not $Upgrade -and -not $Force) {
@@ -205,9 +211,26 @@ if ($CheckOnly) {
   Write-StructuredResult -Result $result -ExitCode 0
 }
 
+if ($DryRun) {
+  Write-CatsNativePreview -Helper 'windows-kiro-native-installer' -Mode $executionMode -Detected $detected -Actions $plannedActions.ToArray() -EmitJson ([bool]$Json)
+}
+
+$installFailed = $false
+$catsInitialObservation = $detected.PSObject.Copy()
 $shouldInstall = $Force -or $Upgrade -or -not $detected.installed
+if ($Upgrade -and -not $Force -and $detected.installed -and -not $SkipInstaller -and -not $installFailed) {
+  $versionGate = Test-CatsNativeUpgrade -Provider 'kiro' -InstalledVersion $detected.detectedVersion
+  $shouldInstall = $versionGate.shouldInstall
+  if (-not $versionGate.known) { $warnings.Add('Could not compare the published version; the official installer will verify the update.') }
+  if (-not $shouldInstall) { $plannedActions.Clear() }
+}
+$installFailed = $false
 if ($shouldInstall) {
-  $installResult = Invoke-KiroInstaller
+  $installResult = try { Invoke-KiroInstaller } catch { [pscustomobject]@{ skipped = $false; success = $false; stderr = [string]$_.Exception.Message; usedPowerShell51Fallback = $false; usedWingetFallback = $false } }
+  if ($installResult.PSObject.Properties['success'] -and -not $installResult.success) {
+    $installFailed = $true
+    $warnings.Add($installResult.stderr)
+  }
   if ($installResult.skipped) {
     $warnings.Add('Installer invocation was skipped by request.')
   }
@@ -215,8 +238,9 @@ if ($shouldInstall) {
   Start-Sleep -Seconds 3
   Refresh-UserPath
   $detected = Detect-KiroInstall
-  if (-not $detected.installed -and -not $SkipInstaller) {
-    throw 'Kiro CLI installation completed but kiro-cli was still not detected.'
+  if (-not $detected.installed -and -not $SkipInstaller -and -not $installFailed) {
+    $warnings.Add('Kiro CLI installation completed but kiro-cli was still not detected.')
+    $installFailed = $true
   }
 
   if ($Force) {
@@ -232,7 +256,7 @@ $interruptions = [System.Collections.Generic.List[object]]::new()
 if ($shouldInstall) {
   $interruptions.Add([pscustomobject]@{
       kind = 'relaunch_required'
-      summary = 'Relaunch Cats Desktop Host after the Kiro CLI install step, then rerun the packaged setup check.'
+      summary = 'Run Detect Again after the Kiro CLI install step if the command is not visible yet.'
       resumable = $true
       requiresRestart = $false
       requiresElevation = $false
@@ -242,7 +266,7 @@ if ($shouldInstall) {
 $result = [pscustomobject]@{
   helper = 'windows-kiro-native-installer'
   mode = $executionMode
-  status = if ($interruptions.Count -gt 0) { [string]$interruptions[0].kind } else { 'ready' }
+  status = if ($installFailed) { 'failed' } elseif ($interruptions.Count -gt 0) { [string]$interruptions[0].kind } else { 'ready' }
   installed = [bool]$detected.installed
   detectedVersion = if ($detected.detectedVersion) { $detected.detectedVersion } else { $null }
   commandPath = $detected.commandPath
@@ -253,4 +277,4 @@ $result = [pscustomobject]@{
   manualSteps = $manualSteps.ToArray()
   interruptions = $interruptions.ToArray()
 }
-Write-StructuredResult -Result $result -ExitCode 0
+Write-StructuredResult -Result $result -ExitCode $(if ($installFailed) { 1 } else { 0 })

package/scripts/windows/Install-MetaCli.ps1

@@ -42,6 +42,7 @@ Set-StrictMode -Version Latest
 $ErrorActionPreference = 'Stop'
 
 . (Join-Path $PSScriptRoot '_HiddenProcess.ps1')
+. (Join-Path $PSScriptRoot '_NativeInstallerSupport.ps1')
 . (Join-Path $PSScriptRoot '_PackagedUninstall.ps1')
 
 function Write-StructuredResult {
@@ -50,6 +51,10 @@ function Write-StructuredResult {
     [int]$ExitCode
   )
 
+  if (Get-Variable -Name catsInitialObservation -Scope Script -ErrorAction SilentlyContinue) {
+    Add-CatsNativeObservation -Result $Result -Before $script:catsInitialObservation -Attempted ([bool]$script:shouldInstall) -Skipped ([bool]$SkipInstaller)
+  }
+
   if ($Json) {
     $Result | ConvertTo-Json -Depth 10
   } else {
@@ -364,6 +369,8 @@ if ($CheckOnly) {
     }) -ExitCode 0
 }
 
+$installFailed = $false
+$catsInitialObservation = $detected.PSObject.Copy()
 $shouldInstall = $Force -or $Upgrade -or -not $detected.installed
 $installFailed = $false
 $installSkipped = $false
@@ -423,7 +430,7 @@ $interruptions = [System.Collections.Generic.List[object]]::new()
 if ($shouldInstall -and -not $installFailed -and -not $DryRun) {
   $interruptions.Add([pscustomobject]@{
       kind = 'relaunch_required'
-      summary = 'Relaunch Cats Desktop Host after the Meta Muse install step, then rerun the packaged setup check.'
+      summary = 'Run Detect Again after the Meta Muse install step if the command is not visible yet.'
       resumable = $true
       requiresRestart = $false
       requiresElevation = $false

package/scripts/windows/Install-Node.ps1

@@ -155,7 +155,8 @@ function Test-NodeInstalled {
     return $false
   }
 
-  return [bool](Get-Command node -ErrorAction SilentlyContinue)
+  return [bool](Get-Command node -ErrorAction SilentlyContinue) -and
+    [bool](Get-Command npm -ErrorAction SilentlyContinue)
 }
 
 if (-not $CheckOnly -and -not $Apply -and -not $Upgrade -and -not $Force) {
@@ -180,6 +181,10 @@ $mode = if ($CheckOnly) {
   'apply'
 }
 
+# Each invocation inherits the long-lived Desktop host's environment. Include
+# newly installed system/user commands before check-only detection as well.
+$env:Path = [System.Environment]::GetEnvironmentVariable('Path', 'Machine') + ';' +
+  [System.Environment]::GetEnvironmentVariable('Path', 'User') + ';' + $env:Path
 $installed = Test-NodeInstalled -Mode $mode
 $detected = Get-NodeDetectedVersion -Override $DetectedVersion
 $commandPath = if ($SkipNodeProbe) { '' } else { Resolve-NodeCommandPath }

package/scripts/windows/Setup-NodeGlobalPrefix.ps1

@@ -215,6 +215,16 @@ if (-not $SkipNodeCheck) {
   }
 }
 
+if (-not $PSBoundParameters.ContainsKey('DesiredPrefix') -and $prefixProbe) {
+  $existingPrefix = [IO.Path]::GetFullPath($prefixProbe)
+  $userRoot = [IO.Path]::GetFullPath($UserHome).TrimEnd('\') + '\'
+  $npmrc = if ($env:NPM_CONFIG_USERCONFIG) { $env:NPM_CONFIG_USERCONFIG } else { Join-Path $UserHome '.npmrc' }
+  $explicitPrefix = $env:NPM_CONFIG_PREFIX -or ((Test-Path -LiteralPath $npmrc -PathType Leaf) -and
+    (Select-String -LiteralPath $npmrc -Pattern '^\s*prefix\s*=' -Quiet))
+  if ($explicitPrefix -or $existingPrefix.StartsWith($userRoot, [StringComparison]::OrdinalIgnoreCase)) {
+    $desiredPrefixPath = $existingPrefix
+  }
+}
 $pathEntries = Get-PathEntries -PathValue $pathProbe
 $needsDirectory = -not (Test-Path -LiteralPath $desiredPrefixPath -PathType Container)
 $needsPrefixUpdate = (Normalize-PathValue -Path $prefixProbe).ToLowerInvariant() -ne

package/scripts/windows/Test-WindowsInstallerSmoke.ps1

@@ -190,6 +190,8 @@ $requiredFiles = @(
   @{ Path = (Join-Path $resourcesRoot 'cats-runtime\config\providers.yaml.example'); Label = 'bundled cats-runtime provider config example' },
   @{ Path = (Join-Path $resourcesRoot 'cats-runtime\config\curated-model-catalogs.yaml.example'); Label = 'bundled cats-runtime curated model catalog example' },
   @{ Path = (Join-Path $resourcesRoot 'cats-runtime\node_modules\playwright-core\package.json'); Label = 'bundled cats-runtime external dependency marker' },
+  @{ Path = (Join-Path $resourcesRoot 'desktop\setup-assets\windows\_NativeInstallerSupport.ps1'); Label = 'bundled native version/installer support' },
+  @{ Path = (Join-Path $resourcesRoot 'desktop\setup-assets\windows\_VerifiedNpmUpdate.ps1'); Label = 'bundled verified npm update support' },
   @{ Path = (Join-Path $resourcesRoot 'desktop\setup-assets\windows\Install-Node.ps1'); Label = 'bundled Windows Node.js LTS host installer' },
   @{ Path = (Join-Path $resourcesRoot 'desktop\setup-assets\windows\Install-GitHubCli.ps1'); Label = 'bundled Windows GitHub CLI host installer' },
   @{ Path = (Join-Path $resourcesRoot 'desktop\setup-assets\windows\Setup-NodeGlobalPrefix.ps1'); Label = 'bundled Windows npm prefix helper' },

package/scripts/windows/_HiddenProcess.ps1

@@ -15,7 +15,8 @@ function Invoke-HiddenCommand {
     [Parameter(Mandatory)]
     [string]$FileName,
 
-    [string[]]$ArgumentList = @()
+    [string[]]$ArgumentList = @(),
+    [int]$TimeoutMs = 0
   )
 
   $psi = New-Object System.Diagnostics.ProcessStartInfo
@@ -36,9 +37,19 @@ function Invoke-HiddenCommand {
   }
 
   $proc = [System.Diagnostics.Process]::Start($psi)
-  $output = $proc.StandardOutput.ReadToEnd()
-  $errorOutput = $proc.StandardError.ReadToEnd()
+  $outputTask = $proc.StandardOutput.ReadToEndAsync()
+  $errorTask = $proc.StandardError.ReadToEndAsync()
+  if ($TimeoutMs -gt 0 -and -not $proc.WaitForExit($TimeoutMs)) {
+    # taskkill /T works in Windows PowerShell 5.1 as well as PowerShell 7;
+    # Process.Kill(true) is unavailable in the former. Only this owned tree is killed.
+    $null = Invoke-HiddenCommand -FileName (Join-Path $env:SystemRoot 'System32\taskkill.exe') -ArgumentList @('/PID', [string]$proc.Id, '/T', '/F')
+    if (-not $proc.HasExited) { $proc.Kill() }
+    $proc.WaitForExit()
+    return [pscustomobject]@{ ExitCode = -1; Output = ''; ErrorOutput = 'Command timed out.' }
+  }
   $proc.WaitForExit()
+  $output = $outputTask.GetAwaiter().GetResult()
+  $errorOutput = $errorTask.GetAwaiter().GetResult()
 
   return [pscustomobject]@{
     ExitCode    = $proc.ExitCode

package/scripts/windows/_NativeInstallerSupport.ps1

@@ -0,0 +1,308 @@
+<#
+.SYNOPSIS
+    Shared native installer version gates, isolated child execution and observed results.
+.DESCRIPTION
+    Dot-source from the packaged native helpers. Metadata parsing is adapted from
+    environment-bootstrap at 752dc13; no query occurs during check-only actions.
+    Vendor scripts execute in a hidden child so an upstream exit cannot end our JSON response.
+.EXAMPLE
+    . "$PSScriptRoot\_NativeInstallerSupport.ps1"
+    Test-CatsNativeUpgrade -Provider grok -InstalledVersion '1.0.0'
+#>
+. (Join-Path $PSScriptRoot '_HiddenProcess.ps1')
+
+function Get-CatsNativeLatestVersion {
+  param([string]$Provider)
+  try {
+    switch ($Provider) {
+      antigravity { return Get-AntigravityLatestVersion }
+      cursor { return Get-CursorAgentLatestVersion -InstallerText (Invoke-RestMethod 'https://cursor.com/install?win32=true' -TimeoutSec 20 -UseBasicParsing) }
+      junie { return Get-JunieLatestBuild }
+      devin { return Get-DevinLatestVersion }
+      grok { return Get-GrokLatestVersion }
+      kiro { return [string](Invoke-RestMethod 'https://prod.download.cli.kiro.dev/stable/latest/manifest.json' -TimeoutSec 20 -UseBasicParsing).version }
+      goose { return [string](Invoke-RestMethod 'https://api.github.com/repos/aaif-goose/goose/releases/latest' -TimeoutSec 20 -UseBasicParsing -Headers @{ 'User-Agent' = 'Cats-Desktop'; Accept = 'application/vnd.github+json' }).tag_name }
+      default { return $null }
+    }
+  } catch { return $null }
+}
+
+function Get-CatsNativeVersionToken {
+  param([string]$Provider, [string]$Version)
+  if ($Provider -eq 'junie') {
+    $match = [regex]::Match($Version, '\((\d+(?:\.\d+)+)\)')
+    if ($match.Success) { return $match.Groups[1].Value }
+    return ''
+  }
+  return [regex]::Match($Version, '\d+(?:\.\d+)+(?:-[a-zA-Z0-9.]+)?').Value
+}
+
+function Test-CatsNativeUpgrade {
+  param([string]$Provider, [string]$InstalledVersion, [AllowNull()][string]$LatestVersion = $null)
+  if (-not $PSBoundParameters.ContainsKey('LatestVersion')) { $LatestVersion = Get-CatsNativeLatestVersion $Provider }
+  $current = Get-CatsNativeVersionToken $Provider $InstalledVersion
+  $comparison = Compare-ToolVersion -Installed $current -Latest $LatestVersion
+  $known = $null -ne $comparison
+  $currentRelease = $known -and ($comparison -ge 0)
+  if ($Provider -eq 'cursor' -and $comparison -eq 0 -and $current -ne $LatestVersion) { $currentRelease = $false }
+  return [pscustomobject]@{ shouldInstall = -not $currentRelease; latestVersion = $LatestVersion; known = $known }
+}
+
+function Invoke-CatsRemoteInstaller {
+  param([Parameter(Mandatory)][string]$ScriptText, [switch]$RetrySharingViolation)
+  $temporary = Join-Path ([System.IO.Path]::GetTempPath()) ('cats-native-' + [guid]::NewGuid().ToString('N') + '.ps1')
+  try {
+    if ([string]::IsNullOrWhiteSpace($ScriptText)) { throw 'Vendor returned an empty installer.' }
+    $ast = [System.Management.Automation.Language.Parser]::ParseInput($ScriptText, [ref]$null, [ref]$null)
+    $offsets = @(0)
+    if ($ast.ParamBlock) { $offsets += $ast.ParamBlock.Extent.EndOffset }
+    foreach ($usingStatement in $ast.UsingStatements) { $offsets += $usingStatement.Extent.EndOffset }
+    $offset = ($offsets | Measure-Object -Maximum).Maximum
+    $prologue = '$env:PSModulePath = (@([System.Environment]::GetEnvironmentVariable(''PSModulePath'',''User''), [System.Environment]::GetEnvironmentVariable(''PSModulePath'',''Machine''), (Join-Path $PSHOME ''Modules'')) | Where-Object { $_ }) -join '';'''
+    $body = $ScriptText.Insert($offset, "`n$prologue`n")
+    if ($RetrySharingViolation) {
+      $encoded = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($body))
+      $body = @'
+$ErrorActionPreference = 'Stop'
+$installer = [scriptblock]::Create([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('__SOURCE__')))
+for ($attempt = 1; $attempt -le 3; $attempt++) {
+  try { & $installer; exit 0 }
+  catch {
+    $exception = $_.Exception
+    while ($exception.InnerException) { $exception = $exception.InnerException }
+    if ($attempt -eq 3 -or -not ($exception -is [IO.IOException]) -or ($exception.HResult -band 0xffff) -ne 32) { throw }
+    Start-Sleep -Seconds 5
+  }
+}
+'@
+      $body = $body.Replace('__SOURCE__', $encoded)
+    }
+    [IO.File]::WriteAllText($temporary, $body, [Text.UTF8Encoding]::new($true))
+    $hostExe = Join-Path $env:SystemRoot 'System32\WindowsPowerShell\v1.0\powershell.exe'
+    $result = Invoke-HiddenCommand -FileName $hostExe -ArgumentList @('-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', $temporary)
+    return [pscustomobject]@{ skipped = $false; success = $result.ExitCode -eq 0; exitCode = $result.ExitCode; stderr = $result.ErrorOutput; stdout = $result.Output }
+  } catch {
+    return [pscustomobject]@{ skipped = $false; success = $false; exitCode = -1; stderr = [string]$_.Exception.Message }
+  } finally {
+    # This is one uniquely-created file; never recursively remove a computed directory.
+    Remove-Item -LiteralPath $temporary -Force -ErrorAction SilentlyContinue
+  }
+}
+
+function Add-CatsNativeObservation {
+  param([pscustomobject]$Result, [AllowNull()]$Before, [bool]$Attempted, [bool]$Skipped)
+  if ($Result.mode -in @('check', 'uninstall') -or $null -eq $Before) { return }
+  $change = if ($Result.status -eq 'failed') { 'failed' }
+    elseif ($Skipped -or $Result.status -eq 'preview' -or -not $Attempted) { 'unchanged' }
+    elseif (-not $Result.installed) { 'failed' }
+    elseif (-not $Before.installed) { 'installed' }
+    elseif ($Before.detectedVersion -and $Result.detectedVersion -and $Before.detectedVersion -ne $Result.detectedVersion) {
+      $comparison = Compare-ToolVersion -Installed $Result.detectedVersion -Latest $Before.detectedVersion
+      if ($comparison -gt 0) { 'upgraded' } elseif ($comparison -lt 0) { 'downgraded' } else { 'version_changed' }
+    }
+    else { 'unchanged' }
+  if ($Result.mode -in @('upgrade', 'force') -and -not $Skipped -and $Result.status -ne 'preview' -and $change -ne 'failed' -and $Result.installed -and $Result.detectedVersion) {
+    $provider = $Result.helper -replace '^windows-', '' -replace '-native-installer$', ''
+    if ($provider -in @('cursor', 'devin', 'junie')) {
+      try { Remove-CatsStaleNativeVersions -Provider $provider -Version $Result.detectedVersion } catch { Write-Warning 'Old-version cleanup was skipped.' }
+    }
+  }
+  $Result | Add-Member -NotePropertyName observedChange -NotePropertyValue $change -Force
+  $Result | Add-Member -NotePropertyName previousVersion -NotePropertyValue $Before.detectedVersion -Force
+  $description = "$change"
+  if ($change -in @('upgraded', 'downgraded', 'version_changed')) { $description += ": $($Before.detectedVersion) -> $($Result.detectedVersion)" }
+  elseif ($Result.detectedVersion) { $description += ": $($Result.detectedVersion)" }
+  $Result | Add-Member -NotePropertyName summary -NotePropertyValue $description -Force
+  if ($change -in @('failed', 'unchanged')) { $Result.appliedChanges = @() }
+  else { $Result.appliedChanges = @("${change}_native_installation") }
+}
+
+function Write-CatsNativePreview {
+  param([string]$Helper, [string]$Mode, $Detected, [string[]]$Actions, [bool]$EmitJson)
+  $result = [pscustomobject]@{
+    helper = $Helper; mode = $Mode; status = 'preview'; installed = [bool]$Detected.installed
+    detectedVersion = $Detected.detectedVersion; commandPath = $Detected.commandPath
+    restartRequired = $false; plannedActions = @($Actions); appliedChanges = @()
+    warnings = @(); manualSteps = @(); interruptions = @(); observedChange = 'unchanged'
+  }
+  if ($EmitJson) { $result | ConvertTo-Json -Depth 10 } else { Write-Host "Preview: $($Actions -join ', ')" }
+  exit 0
+}
+
+function Get-CatsShimVersionText {
+  param([string]$Path)
+  if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) { return '' }
+  $literal = "'" + $Path.Replace("'", "''") + "'"
+  $script = "& $literal --version; exit " + '$LASTEXITCODE'
+  $encoded = [Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes($script))
+  $hostExe = Join-Path $env:SystemRoot 'System32\WindowsPowerShell\v1.0\powershell.exe'
+  $result = Invoke-HiddenCommand -FileName $hostExe -ArgumentList @('-NoProfile', '-NonInteractive', '-EncodedCommand', $encoded) -TimeoutMs 15000
+  if ($result.ExitCode -ne 0) { return '' }
+  return $result.Output.Trim()
+}
+
+function Remove-CatsStaleNativeVersions {
+  param([string]$Provider, [string]$Version)
+  $keep = Get-CatsNativeVersionToken $Provider $Version
+  if (-not $keep) { return }
+  $data = switch ($Provider) {
+    cursor { Join-Path $env:LOCALAPPDATA 'cursor-agent' }
+    devin { Join-Path $env:LOCALAPPDATA 'devin\cli' }
+    junie {
+      if ($env:JUNIE_DATA_DIR) { $env:JUNIE_DATA_DIR } else { Join-Path $env:USERPROFILE '.local\share\junie' }
+    }
+    default { return }
+  }
+  $versions = [IO.Path]::GetFullPath((Join-Path $data $(if ($Provider -eq 'devin') { '_versions' } else { 'versions' })))
+  if ($Provider -eq 'junie') {
+    if (Test-Path -LiteralPath (Join-Path $data 'updates\pending-update.json')) { return }
+    $currentFile = Join-Path $data 'current'
+    if (-not (Test-Path -LiteralPath $currentFile -PathType Leaf)) { return }
+    if ((Get-Content -LiteralPath $currentFile -Raw).Trim() -ne $keep) { return }
+  }
+  # Only known user roots; do not follow a junction in any ancestor or delete
+  # current/newer/pending builds. A custom directory outside those roots is kept.
+  if (-not (Test-PackagedProviderPathRemovable $versions)) { return }
+  $ancestor = Get-Item -LiteralPath $versions
+  while ($ancestor) {
+    if ($ancestor.Attributes -band [IO.FileAttributes]::ReparsePoint) { return }
+    $ancestor = $ancestor.Parent
+  }
+  foreach ($directory in (Get-ChildItem -LiteralPath $versions -Directory)) {
+    if ($directory.Attributes -band [IO.FileAttributes]::ReparsePoint) { continue }
+    if ($directory.Name -notmatch '^\d+(\.\d+)+(-[a-zA-Z0-9]+)?$') { continue }
+    if ((Compare-ToolVersion -Installed $directory.Name -Latest $keep) -ne -1) { continue }
+    $resolved = [IO.Path]::GetFullPath($directory.FullName)
+    if (-not $resolved.StartsWith($versions.TrimEnd('\') + '\', [StringComparison]::OrdinalIgnoreCase)) { continue }
+    if (Get-ChildItem -LiteralPath $resolved -Recurse -Force | Where-Object { $_.Attributes -band [IO.FileAttributes]::ReparsePoint } | Select-Object -First 1) { continue }
+    try { Remove-Item -LiteralPath $resolved -Recurse -Force -ErrorAction Stop } catch { Write-Warning "Could not remove old $Provider version $($directory.Name)." }
+  }
+}
+function ConvertTo-ComparableVersion {
+    param([string]$Version)
+
+    if ([string]::IsNullOrWhiteSpace($Version)) { return $null }
+
+    # 第一個版本樣式的 token；額外吃下 Git for Windows 的 .windows.N 尾段
+    $match = [regex]::Match($Version, '\d+(?:\.\d+)+(?:\.windows\.\d+)?')
+    if (-not $match.Success) { return $null }
+
+    $parts = ($match.Value -replace '\.windows\.', '.') -split '\.' |
+        Select-Object -First 4
+
+    while ($parts.Count -lt 4) { $parts += '0' }
+
+    try {
+        return [version]($parts -join '.')
+    } catch {
+        return $null
+    }
+}
+
+function Compare-ToolVersion {
+    param(
+        [string]$Installed,
+        [string]$Latest
+    )
+
+    $installedVersion = ConvertTo-ComparableVersion $Installed
+    $latestVersion    = ConvertTo-ComparableVersion $Latest
+
+    if (-not $installedVersion -or -not $latestVersion) { return $null }
+
+    return $installedVersion.CompareTo($latestVersion)
+}
+
+function Get-AntigravityLatestVersion {
+    param([string]$InstallerText)
+
+    $baseUrl = 'https://antigravity-cli-auto-updater-974169037036.us-central1.run.app'
+    if ($InstallerText) {
+        $m = [regex]::Match($InstallerText, '\$DOWNLOAD_BASE_URL\s*=\s*"(https://[^"]+)"')
+        if ($m.Success) { $baseUrl = $m.Groups[1].Value }
+    }
+
+    $arch = if ($env:PROCESSOR_ARCHITEW6432) { $env:PROCESSOR_ARCHITEW6432 } else { $env:PROCESSOR_ARCHITECTURE }
+    $platform = if ($arch -eq 'ARM64') { 'windows_arm64' } else { 'windows_amd64' }
+
+    try {
+        $manifest = Invoke-RestMethod -Uri "$baseUrl/manifests/$platform.json" -TimeoutSec 20 -UseBasicParsing -ErrorAction Stop
+        if (-not $manifest.version) { return $null }
+        return "$($manifest.version)"
+    } catch {
+        return $null
+    }
+}
+
+function Get-CursorAgentLatestVersion {
+    param(
+        [Parameter(Mandatory=$true)]
+        [string]$InstallerText
+    )
+
+    $m = [regex]::Match($InstallerText, "(?m)^\s*\`$version\s*=\s*'([^']+)'")
+    if (-not $m.Success) { return $null }
+    return $m.Groups[1].Value
+}
+
+function Get-JunieLatestBuild {
+    $archName = if ($env:PROCESSOR_ARCHITECTURE -eq 'ARM64' -or $env:PROCESSOR_ARCHITEW6432 -eq 'ARM64') { 'aarch64' } else { 'amd64' }
+    $platform = "windows-$archName"
+
+    try {
+        $jsonl = Invoke-RestMethod -Uri 'https://raw.githubusercontent.com/jetbrains-junie/junie/main/update-info.jsonl' `
+            -TimeoutSec 20 -UseBasicParsing -ErrorAction Stop
+    } catch {
+        return $null
+    }
+
+    $best = $null
+    foreach ($line in ("$jsonl" -split "`n")) {
+        if ($line -notmatch "`"platform`":`"$platform`"") { continue }
+        try { $entry = $line | ConvertFrom-Json } catch { continue }
+        if (-not $entry.version) { continue }
+        $candidate = ConvertTo-ComparableVersion "$($entry.version)"
+        if (-not $candidate) { continue }
+        if ($null -eq $best -or $candidate -gt $best.Comparable) {
+            $best = @{ Build = "$($entry.version)"; Comparable = $candidate }
+        }
+    }
+
+    if ($null -eq $best) { return $null }
+    return $best.Build
+}
+
+function Get-DevinLatestVersion {
+    try {
+        $manifest = Invoke-RestMethod -Uri 'https://static.devin.ai/cli/current/manifest.json' -TimeoutSec 20 -UseBasicParsing -ErrorAction Stop
+        if (-not $manifest.version) { return $null }
+        return "$($manifest.version)"
+    } catch {
+        return $null
+    }
+}
+
+function Get-GrokLatestVersion {
+    param([string]$Channel)
+
+    if (-not $Channel) {
+        $Channel = if ($env:GROK_CHANNEL) { $env:GROK_CHANNEL } else { 'stable' }
+    }
+
+    $urls = @(
+        "https://x.ai/cli/$Channel",
+        "https://storage.googleapis.com/grok-build-public-artifacts/cli/$Channel"
+    )
+    foreach ($url in $urls) {
+        try {
+            $text = Invoke-RestMethod -Uri $url -TimeoutSec 20 -UseBasicParsing -ErrorAction Stop
+        } catch {
+            continue
+        }
+        $line = @("$text" -split "`r?`n")[0]
+        if ($null -eq $line) { continue }
+        $line = $line.Trim()
+        if ($line -match '^\d+\.\d+\.\d+(-[A-Za-z0-9._]+)?$') { return $line }
+    }
+    return $null
+}

package/scripts/windows/_NpmCliInstaller.ps1

@@ -23,6 +23,8 @@
     can run it explicitly when needed.
 #>
 
+. (Join-Path $PSScriptRoot '_VerifiedNpmUpdate.ps1')
+
 function Test-NpmCliInstallerAdminGuard {
   param(
     [Parameter(Mandatory = $true)]
@@ -163,11 +165,16 @@ function Test-NpmCliPackageOutdated {
     [string]$PackageName
   )
 
-  $outdatedRaw = (& npm outdated -g --json $PackageName 2>$null) | Out-String
-  if ([string]::IsNullOrWhiteSpace($outdatedRaw)) {
-    return $false
-  }
-  return $outdatedRaw.Contains("`"$PackageName`"")
+  $latest = ((& npm view "$PackageName@latest" version --fetch-retries=0 --fetch-timeout=10000 --loglevel=error) | Out-String).Trim()
+  if ($LASTEXITCODE -ne 0 -or $latest -notmatch '^\d+\.\d+\.\d+(-[a-zA-Z0-9._-]+)?$') { throw 'Provider version query failed; update status is unknown.' }
+  $installed = Get-NpmCliPackageVersion -PackageName $PackageName
+  if (-not $installed) { return $true }
+  $currentBase = [version]($installed -split '-')[0]
+  $latestBase = [version]($latest -split '-')[0]
+  # Preserve a newer local/pre-release build. Equal numeric prerelease advances
+  # to the stable release; Repair remains the explicit reinstall action.
+  return $currentBase -lt $latestBase -or ($currentBase -eq $latestBase -and $installed.Contains('-') -and -not $latest.Contains('-'))
+
 }
 
 function Resolve-NpmCliCommandPath {
@@ -216,6 +223,7 @@ function Remove-SupersededNpmPackages {
 
     Write-Host "Removing superseded package $legacy (replaced by $PackageName)."
     & npm uninstall -g $legacy 2>$null | Out-Null
+    if ($LASTEXITCODE -ne 0) { throw "Could not remove superseded package $legacy." }
     if ($AppliedChanges) {
       $AppliedChanges.Add("${legacy}:removed-superseded") | Out-Null
     }
@@ -315,6 +323,12 @@ function Invoke-PackagedNpmCliInstall {
     $null
   }
   $commandPath = if ($installed) { Resolve-NpmCliCommandPath -CommandName $CommandName } else { $null }
+  if ($installed -and -not $detectedVersion -and -not $SkipNpmInvocation) {
+    foreach ($legacy in (Get-SupersededNpmPackages -PackageName $PackageName)) {
+      & npm list -g --depth=0 $legacy 2>$null | Out-Null
+      if ($LASTEXITCODE -eq 0) { $installed = $false; break }
+    }
+  }
 
   $plannedActions = [System.Collections.Generic.List[string]]::new()
   $appliedChanges = [System.Collections.Generic.List[string]]::new()
@@ -444,6 +458,17 @@ function Invoke-PackagedNpmCliInstall {
     exit 0
   }
 
+  if ($DryRun -and -not $CheckOnly) {
+    $preview = [pscustomobject]@{
+      helper = $HelperId; mode = $mode; status = 'preview'; installed = [bool]$installed
+      detectedVersion = $detectedVersion; commandPath = $commandPath; restartRequired = $false
+      plannedActions = @("${PackageName}:${mode}"); appliedChanges = @(); warnings = @(); manualSteps = @(); interruptions = @()
+    }
+    if ($Json) { $preview | ConvertTo-Json -Depth 10 } else { Write-Host "Preview: ${PackageName}:${mode}" }
+    exit 0
+  }
+  if ($Upgrade -and -not $CheckOnly -and -not $SkipNpmInvocation) { Update-CatsNpm }
+
   $isOutdated = if (-not $Upgrade -and -not $Force) {
     $false
   } else {
@@ -565,15 +590,9 @@ function Invoke-PackagedNpmCliInstall {
   # Without it, packages like @openai/codex skip their platform-specific
   # binaries (codex-win32-x64, codex-darwin-arm64, ...), leaving a shim that
   # silently exits when invoked. Pure-JS CLIs such as copilot don't notice.
-  $arguments = @('install', '-g', '--include=optional')
-  if ($plannedAction -eq 'upgrade') {
-    $arguments += "$PackageName@latest"
-  } else {
-    $arguments += $PackageName
-  }
-  if ($plannedAction -eq 'reinstall') {
-    $arguments += '--force'
-  }
+  $expectedVersion = ((& npm view "$PackageName@latest" version --fetch-retries=0 --fetch-timeout=10000 --loglevel=error) | Out-String).Trim()
+  if ($LASTEXITCODE -ne 0 -or $expectedVersion -notmatch '^\d+\.\d+\.\d+(-[a-zA-Z0-9._-]+)?$') { throw 'Could not resolve the provider version before installing.' }
+  $arguments = @('install', '-g', '--include=optional', '--engine-strict', '--fetch-retries=0', '--fetch-timeout=30000', "$PackageName@$expectedVersion")
 
   & npm @arguments | Out-Null
   if ($LASTEXITCODE -ne 0) {
@@ -585,6 +604,8 @@ function Invoke-PackagedNpmCliInstall {
   $finalCommandPath = if ($finalInstalled) { Resolve-NpmCliCommandPath -CommandName $CommandName } else { $null }
   $finalVersion = if ($finalInstalled) { Get-NpmCliPackageVersion -PackageName $PackageName } else { $null }
 
+  if (-not $finalInstalled -or -not $finalCommandPath -or $finalVersion -ne $expectedVersion) { throw 'Provider installation verification failed. Check npm prefix and command PATH.' }
+
   $result = [pscustomobject]@{
     helper = $HelperId
     mode = $mode

package/scripts/windows/_PackagedUninstall.ps1

@@ -24,7 +24,15 @@ if (-not (Get-Module -ListAvailable -Name Microsoft.PowerShell.Utility)) {
 function Test-PackagedProviderPathRemovable {
   param([string]$Path)
   if ([string]::IsNullOrWhiteSpace($Path)) { return $false }
-  return (Test-Path -LiteralPath $Path)
+  $fullPath = [IO.Path]::GetFullPath($Path).TrimEnd('\', '/')
+  $withinUserRoot = $false
+  foreach ($base in @($env:USERPROFILE, $env:LOCALAPPDATA)) {
+    if (-not $base) { continue }
+    $root = [IO.Path]::GetFullPath($base).TrimEnd('\', '/') + '\'
+    if ($fullPath.StartsWith($root, [StringComparison]::OrdinalIgnoreCase)) { $withinUserRoot = $true }
+  }
+  if (-not $withinUserRoot) { return $false }
+  return (Test-Path -LiteralPath $fullPath)
 }
 
 function Test-DetectedPathInPlannedRemovals {