@cats-inc/cats-platform 0.1.21 → 0.3.4

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 {

package/scripts/windows/_VerifiedNpmUpdate.ps1

@@ -0,0 +1,25 @@
+<#
+.SYNOPSIS
+    Update npm in its current prefix with bounded queries and post-install verification.
+.DESCRIPTION
+    Dot-source and invoke Update-CatsNpm only for an explicit upgrade action.
+    Adapted from environment-bootstrap 4690075. Never changes prefix or bypasses engines.
+.EXAMPLE
+    Update-CatsNpm
+#>
+function Update-CatsNpm {
+  $current = ((& npm --version) | Out-String).Trim()
+  if ($LASTEXITCODE -ne 0) { throw 'Could not read npm version.' }
+  $latest = ((& npm view npm@latest version --fetch-retries=0 --fetch-timeout=10000 --loglevel=error) | Out-String).Trim()
+  if ($LASTEXITCODE -ne 0 -or $latest -notmatch '^\d+\.\d+\.\d+$') { throw 'npm version query failed or returned an invalid version.' }
+  if ($current -eq $latest) { return }
+  if ([version]$current -gt [version]$latest) { return }
+  & npm install -g "npm@$latest" --engine-strict --fetch-retries=0 --fetch-timeout=30000 | Out-Null
+  if ($LASTEXITCODE -ne 0) { throw 'npm update failed. Check network, permissions and Node.js compatibility.' }
+  $installed = ((& npm --version) | Out-String).Trim()
+  if ($LASTEXITCODE -ne 0 -or $installed -ne $latest) { throw 'npm command version verification failed. Check PATH and prefix.' }
+  $root = ((& npm root -g) | Out-String).Trim()
+  if ($LASTEXITCODE -ne 0 -or -not $root) { throw 'Could not verify the npm installation prefix.' }
+  $package = Get-Content -LiteralPath (Join-Path $root 'npm/package.json') -Raw -Encoding UTF8 | ConvertFrom-Json
+  if ($package.version -ne $latest) { throw 'npm package version does not match its active command.' }
+}

package/build/desktop/updateNotifications.d.ts

@@ -1,64 +0,0 @@
-import type { DesktopUpdateErrorCode, DesktopUpdateSnapshot } from './contracts.js';
-import { type DesktopTrayLocale } from './trayMenu.js';
-/**
- * Native update notifications.
- *
- * SPEC-111 section 5 requires a check started outside Settings to report its
- * result somewhere the user is actually looking. This module owns that policy;
- * `main.ts` only constructs the native notification the policy asks for, so the
- * rules stay testable without Electron.
- */
-/** Where the check that produced the result came from. */
-export declare const DESKTOP_UPDATE_NOTIFICATION_ORIGINS: readonly ["tray", "settings", "startup"];
-export type DesktopUpdateNotificationOrigin = typeof DESKTOP_UPDATE_NOTIFICATION_ORIGINS[number];
-export declare const DESKTOP_UPDATE_SETTINGS_PATH = "/settings/desktop";
-export interface DesktopUpdateNotification {
-    title: string;
-    body: string;
-    /** Where activating the notification shall land the user. */
-    navigatePath: typeof DESKTOP_UPDATE_SETTINGS_PATH;
-}
-export interface DesktopUpdateAnnouncement {
-    notification: DesktopUpdateNotification | null;
-    /**
-     * Where to open the main window when no notification reaches the user —
-     * either because the platform has none or because showing it failed.
-     *
-     * Null when the result does not justify pulling a window forward. Set
-     * independently of `notification` so the caller never has to re-derive the
-     * policy after a failed `show()`.
-     */
-    fallbackNavigatePath: typeof DESKTOP_UPDATE_SETTINGS_PATH | null;
-}
-/**
- * Error copy for notifications, in the same two locales the tray uses.
- *
- * These strings are duplicated from the renderer i18n catalogs because the
- * main process has no translator. `settings-desktop-update-labels.test.tsx`
- * asserts they stay identical to the catalog entries, so the duplication cannot
- * drift silently.
- */
-export declare const DESKTOP_UPDATE_NOTIFICATION_ERROR_COPY: Record<DesktopTrayLocale, Record<DesktopUpdateErrorCode, string>>;
-export interface ResolveDesktopUpdateAnnouncementInput {
-    origin: DesktopUpdateNotificationOrigin;
-    snapshot: DesktopUpdateSnapshot;
-    locale?: string | null;
-    /** `Notification.isSupported()`, resolved by the caller. */
-    notificationsSupported: boolean;
-}
-/**
- * Decides what a finished check should tell the user, and how.
- *
- * A result is announced only when the user cannot already see it:
- *
- * - `settings` never announces. The section shows the state directly and
- *   routes manual results through the shared toast system, so a native
- *   notification would report the same check twice.
- * - `tray` announces up-to-date, available, and failed. The menu closes on
- *   click, so without this the command looks like it did nothing.
- * - `startup` announces only an available update. The user did not ask for
- *   that check, so an up-to-date or offline result has nothing to say and
- *   would nag on every launch.
- */
-export declare function resolveDesktopUpdateAnnouncement(input: ResolveDesktopUpdateAnnouncementInput): DesktopUpdateAnnouncement;
-//# sourceMappingURL=updateNotifications.d.ts.map

package/build/desktop/updateNotifications.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"updateNotifications.d.ts","sourceRoot":"","sources":["../../desktop/host/updateNotifications.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AAIxB,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AAEvB;;;;;;;GAOG;AAEH,0DAA0D;AAC1D,eAAO,MAAM,mCAAmC,0CAA2C,CAAC;AAC5F,MAAM,MAAM,+BAA+B,GACzC,OAAO,mCAAmC,CAAC,MAAM,CAAC,CAAC;AAErD,eAAO,MAAM,4BAA4B,sBAAsB,CAAC;AAEhE,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,YAAY,EAAE,OAAO,4BAA4B,CAAC;CACnD;AAED,MAAM,WAAW,yBAAyB;IACxC,YAAY,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAC/C;;;;;;;OAOG;IACH,oBAAoB,EAAE,OAAO,4BAA4B,GAAG,IAAI,CAAC;CAClE;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sCAAsC,EAAE,MAAM,CACzD,iBAAiB,EACjB,MAAM,CAAC,sBAAsB,EAAE,MAAM,CAAC,CA0BvC,CAAC;AAmCF,MAAM,WAAW,qCAAqC;IACpD,MAAM,EAAE,+BAA+B,CAAC;IACxC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,4DAA4D;IAC5D,sBAAsB,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,qCAAqC,GAC3C,yBAAyB,CA2B3B"}

package/build/desktop/updateNotifications.js

@@ -1,143 +0,0 @@
-// Locale normalization is shared with the tray rather than duplicated. The
-// main process has no i18n runtime, so both surfaces resolve their own copy
-// from the same two-locale rule.
-import { normalizeDesktopTrayLocale, } from './trayMenu.js';
-/**
- * Native update notifications.
- *
- * SPEC-111 section 5 requires a check started outside Settings to report its
- * result somewhere the user is actually looking. This module owns that policy;
- * `main.ts` only constructs the native notification the policy asks for, so the
- * rules stay testable without Electron.
- */
-/** Where the check that produced the result came from. */
-export const DESKTOP_UPDATE_NOTIFICATION_ORIGINS = ['tray', 'settings', 'startup'];
-export const DESKTOP_UPDATE_SETTINGS_PATH = '/settings/desktop';
-/**
- * Error copy for notifications, in the same two locales the tray uses.
- *
- * These strings are duplicated from the renderer i18n catalogs because the
- * main process has no translator. `settings-desktop-update-labels.test.tsx`
- * asserts they stay identical to the catalog entries, so the duplication cannot
- * drift silently.
- */
-export const DESKTOP_UPDATE_NOTIFICATION_ERROR_COPY = {
-    en: {
-        offline: 'Cats could not reach the update service.',
-        timeout: 'The update service did not respond in time.',
-        provider_rejected: 'The update service rejected the request.',
-        metadata_invalid: 'The update information could not be read.',
-        checksum_mismatch: 'The downloaded update failed its integrity check.',
-        signature_rejected: 'The downloaded update failed its signature check.',
-        unsupported_package: 'This installation cannot update itself.',
-        download_cancelled: 'The update download was cancelled.',
-        install_handoff_failed: 'Cats could not open the installer.',
-        unknown: 'The update could not be completed.',
-    },
-    'zh-TW': {
-        offline: 'Cats 無法連線到更新服務。',
-        timeout: '更新服務未在時限內回應。',
-        provider_rejected: '更新服務拒絕了這次請求。',
-        metadata_invalid: '無法讀取更新資訊。',
-        checksum_mismatch: '下載的更新未通過完整性檢查。',
-        signature_rejected: '下載的更新未通過簽章檢查。',
-        unsupported_package: '這個安裝方式無法自我更新。',
-        download_cancelled: '更新下載已取消。',
-        install_handoff_failed: 'Cats 無法開啟安裝程式。',
-        unknown: '更新無法完成。',
-    },
-};
-const NOTIFICATION_COPY = {
-    en: {
-        upToDateTitle: 'Cats is up to date',
-        upToDateBody: (version) => `Cats ${version} is the latest version.`,
-        availableTitle: 'Update available',
-        availableBody: (version) => `Cats ${version} is available to download.`,
-        failedTitle: 'Update check failed',
-        previewSuffix: ' (preview)',
-    },
-    'zh-TW': {
-        upToDateTitle: 'Cats 已是最新版本',
-        upToDateBody: (version) => `Cats ${version} 已是最新版本。`,
-        availableTitle: '有可用更新',
-        availableBody: (version) => `Cats ${version} 已可下載。`,
-        failedTitle: '更新檢查失敗',
-        previewSuffix: '（預覽）',
-    },
-};
-const NOTHING_TO_ANNOUNCE = {
-    notification: null,
-    fallbackNavigatePath: null,
-};
-/**
- * Decides what a finished check should tell the user, and how.
- *
- * A result is announced only when the user cannot already see it:
- *
- * - `settings` never announces. The section shows the state directly and
- *   routes manual results through the shared toast system, so a native
- *   notification would report the same check twice.
- * - `tray` announces up-to-date, available, and failed. The menu closes on
- *   click, so without this the command looks like it did nothing.
- * - `startup` announces only an available update. The user did not ask for
- *   that check, so an up-to-date or offline result has nothing to say and
- *   would nag on every launch.
- */
-export function resolveDesktopUpdateAnnouncement(input) {
-    const { origin, snapshot, notificationsSupported } = input;
-    if (origin === 'settings') {
-        return NOTHING_TO_ANNOUNCE;
-    }
-    // A build that cannot check cannot have produced a result worth reporting,
-    // and must never imply that an update path exists.
-    if (!snapshot.capability.canCheck) {
-        return NOTHING_TO_ANNOUNCE;
-    }
-    const locale = normalizeDesktopTrayLocale(input.locale);
-    const notification = resolveNotification(origin, snapshot, locale);
-    if (notification === null) {
-        return NOTHING_TO_ANNOUNCE;
-    }
-    // SPEC-111 section 5.5: a tray-originated result always becomes visible, so
-    // it falls back to opening Settings. A startup check was never requested, so
-    // pulling a window forward unasked would be worse than staying quiet.
-    const fallbackNavigatePath = origin === 'tray' ? DESKTOP_UPDATE_SETTINGS_PATH : null;
-    return {
-        notification: notificationsSupported ? notification : null,
-        fallbackNavigatePath,
-    };
-}
-function resolveNotification(origin, snapshot, locale) {
-    const copy = NOTIFICATION_COPY[locale];
-    // A preview self-updates from an unsigned prerelease feed. A tester who
-    // cannot tell that apart from a supported release cannot report usefully.
-    const suffix = snapshot.capability.distribution === 'preview_packaged'
-        ? copy.previewSuffix
-        : '';
-    const announce = (title, body) => ({
-        title: `${title}${suffix}`,
-        body,
-        navigatePath: DESKTOP_UPDATE_SETTINGS_PATH,
-    });
-    switch (snapshot.status) {
-        case 'up_to_date':
-            return origin === 'tray'
-                ? announce(copy.upToDateTitle, copy.upToDateBody(snapshot.currentVersion))
-                : null;
-        case 'update_available':
-            // The manager rejects an available update without a version, so this
-            // guard is only here to keep a version-less body unreachable.
-            return snapshot.availableVersion === null
-                ? null
-                : announce(copy.availableTitle, copy.availableBody(snapshot.availableVersion));
-        case 'failed':
-            return origin === 'tray' && snapshot.error !== null
-                ? announce(copy.failedTitle, DESKTOP_UPDATE_NOTIFICATION_ERROR_COPY[locale][snapshot.error.code])
-                : null;
-        default:
-            // Every other status is either in flight or the result of an action the
-            // user took in Settings, where the surface already reports it.
-            return null;
-    }
-}
-//# sourceMappingURL=updateNotifications.js.map