@cats-inc/cats-platform 0.1.7 → 0.1.9

package/scripts/windows/Install-Grok.ps1

@@ -0,0 +1,355 @@
+<#
+.SYNOPSIS
+    Install or verify the native Windows Grok CLI for Cats.
+
+.DESCRIPTION
+    Cats-owned packaged setup wrapper for xAI's Grok CLI. The official
+    installer places grok.exe and an agent.exe alias in
+    %USERPROFILE%\.grok\bin. Detection intentionally uses only grok; uninstall
+    removes only those two fixed installer-owned paths and never resolves a
+    generic agent command from PATH.
+#>
+param(
+  [switch]$CheckOnly,
+  [switch]$Apply,
+  [switch]$Upgrade,
+  [switch]$Force,
+  [switch]$Uninstall,
+  [switch]$DryRun,
+  [switch]$Json,
+  [switch]$AllowAdmin,
+  [ValidateSet('auto', 'installed', 'missing')]
+  [string]$InstallState = 'auto',
+  [string]$DetectedVersion = '',
+  [switch]$SkipInstaller
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+. (Join-Path $PSScriptRoot '_HiddenProcess.ps1')
+. (Join-Path $PSScriptRoot '_PackagedUninstall.ps1')
+
+function Write-StructuredResult {
+  param(
+    [pscustomobject]$Result,
+    [int]$ExitCode
+  )
+
+  if ($Json) {
+    $Result | ConvertTo-Json -Depth 10
+  } else {
+    Write-Host "Mode: $($Result.mode)"
+    Write-Host "Status: $($Result.status)"
+    Write-Host "Installed: $($Result.installed)"
+    if ($Result.detectedVersion) { Write-Host "Version: $($Result.detectedVersion)" }
+    foreach ($action in $Result.plannedActions) { Write-Host "Planned action: $action" }
+    foreach ($warning in $Result.warnings) { Write-Host "Warning: $warning" }
+    foreach ($step in $Result.manualSteps) { Write-Host "Manual step: $step" }
+  }
+
+  exit $ExitCode
+}
+
+function Resolve-GrokInstallDir {
+  return Join-Path $env:USERPROFILE '.grok\bin'
+}
+
+function Resolve-GrokExecutablePath {
+  return Join-Path (Resolve-GrokInstallDir) 'grok.exe'
+}
+
+function Resolve-GrokInstallerAliasPath {
+  return Join-Path (Resolve-GrokInstallDir) 'agent.exe'
+}
+
+function Refresh-UserPath {
+  $env:Path = [System.Environment]::GetEnvironmentVariable('Path', 'User') + ';' +
+    [System.Environment]::GetEnvironmentVariable('Path', 'Machine')
+}
+
+function Detect-GrokInstall {
+  $exePath = Resolve-GrokExecutablePath
+
+  if ($InstallState -eq 'installed') {
+    return [pscustomobject]@{
+      installed = $true
+      commandPath = $exePath
+      detectedVersion = $DetectedVersion
+    }
+  }
+  if ($InstallState -eq 'missing') {
+    return [pscustomobject]@{
+      installed = $false
+      commandPath = $exePath
+      detectedVersion = $DetectedVersion
+    }
+  }
+
+  Refresh-UserPath
+  $command = Get-Command grok -ErrorAction SilentlyContinue
+  $installed = $null -ne $command -or (Test-Path -LiteralPath $exePath -PathType Leaf)
+  $commandPath = if ($null -ne $command) { $command.Source } else { $exePath }
+  $commandSource = if ($null -ne $command) { $command.Source } else { '' }
+  $version = $DetectedVersion
+  $versionProbePath = Resolve-HiddenVersionProbePath `
+    -PreferredPath $commandSource `
+    -FallbackPath $exePath
+
+  if ($installed -and [string]::IsNullOrWhiteSpace($version) -and $versionProbePath) {
+    try {
+      $version = Get-HiddenCommandText -FileName $versionProbePath -ArgumentList @('--version')
+    } catch {
+      $version = ''
+    }
+  }
+
+  return [pscustomobject]@{
+    installed = $installed
+    commandPath = $commandPath
+    detectedVersion = $version
+  }
+}
+
+function Add-GrokToUserPath {
+  $installDir = Resolve-GrokInstallDir
+  $userPath = [System.Environment]::GetEnvironmentVariable('Path', 'User')
+  if ([string]::IsNullOrWhiteSpace($userPath)) {
+    [System.Environment]::SetEnvironmentVariable('Path', $installDir, 'User')
+  } elseif ($userPath -notlike "*$installDir*") {
+    [System.Environment]::SetEnvironmentVariable('Path', "$installDir;$userPath", 'User')
+  }
+  Refresh-UserPath
+}
+
+function Invoke-GrokInstaller {
+  if ($SkipInstaller) {
+    return [pscustomobject]@{ skipped = $true; success = $true; exitCode = 0; stderr = '' }
+  }
+
+  $tempScript = [System.IO.Path]::Combine(
+    [System.IO.Path]::GetTempPath(),
+    "cats-grok-install-$([System.Guid]::NewGuid().ToString('N')).ps1"
+  )
+  $stdoutPath = "$tempScript.stdout"
+  $stderrPath = "$tempScript.stderr"
+  $bootstrap = @'
+& {
+  $previousErrorActionPreference = $ErrorActionPreference
+  try {
+    Invoke-RestMethod 'https://x.ai/cli/install.ps1' | Invoke-Expression
+  } finally {
+    $ErrorActionPreference = $previousErrorActionPreference
+  }
+}
+'@
+
+  try {
+    [System.IO.File]::WriteAllText(
+      $tempScript,
+      $bootstrap,
+      [System.Text.UTF8Encoding]::new($false)
+    )
+    $powerShellExe = if (Get-Command pwsh.exe -ErrorAction SilentlyContinue) {
+      'pwsh.exe'
+    } else {
+      'powershell.exe'
+    }
+    $process = Start-Process -FilePath $powerShellExe `
+      -ArgumentList @('-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', $tempScript) `
+      -Wait -PassThru -NoNewWindow `
+      -RedirectStandardOutput $stdoutPath `
+      -RedirectStandardError $stderrPath
+    $stderrRaw = if (Test-Path -LiteralPath $stderrPath -PathType Leaf) {
+      Get-Content -LiteralPath $stderrPath -Raw -ErrorAction SilentlyContinue
+    } else { $null }
+
+    return [pscustomobject]@{
+      skipped = $false
+      success = ($process.ExitCode -eq 0)
+      exitCode = $process.ExitCode
+      stderr = if ($null -eq $stderrRaw) { '' } else { [string]$stderrRaw }
+    }
+  } catch {
+    return [pscustomobject]@{
+      skipped = $false
+      success = $false
+      exitCode = -1
+      stderr = "Failed to invoke Grok installer: $($_.Exception.Message)"
+    }
+  } finally {
+    foreach ($path in @($tempScript, $stdoutPath, $stderrPath)) {
+      if (Test-Path -LiteralPath $path -PathType Leaf) {
+        Remove-Item -LiteralPath $path -Force -ErrorAction SilentlyContinue
+      }
+    }
+  }
+}
+
+if (-not $CheckOnly -and -not $Apply -and -not $Upgrade -and -not $Force -and -not $Uninstall) {
+  $CheckOnly = $true
+}
+
+$mutationCount = @($Apply, $Upgrade, $Force | Where-Object { $_ }).Count
+if ($Uninstall -and ($CheckOnly -or $mutationCount -gt 0)) {
+  throw 'Install-Grok.ps1 -Uninstall is mutually exclusive with other modes.'
+}
+if ($CheckOnly -and $mutationCount -gt 0) {
+  throw 'Install-Grok.ps1 accepts either -CheckOnly or one mutation mode.'
+}
+if ($mutationCount -gt 1) {
+  throw 'Install-Grok.ps1 accepts at most one of -Apply / -Upgrade / -Force.'
+}
+
+$executionMode = if ($Uninstall) {
+  'uninstall'
+} elseif ($CheckOnly) {
+  'check'
+} elseif ($Force) {
+  'force'
+} elseif ($Upgrade) {
+  'upgrade'
+} else {
+  'apply'
+}
+
+if ($Uninstall) {
+  Invoke-PackagedProviderUninstall `
+    -HelperId 'windows-grok-native-installer' `
+    -UserBinaryPath (Resolve-GrokExecutablePath) `
+    -ExtraUserOwnedPaths @((Resolve-GrokInstallerAliasPath)) `
+    -RedetectCommand { Detect-GrokInstall } `
+    -EmitJson:$Json `
+    -DryRun:$DryRun
+}
+
+$isAdmin = ([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).
+  IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
+if ($isAdmin -and -not $AllowAdmin) {
+  Write-StructuredResult -Result ([pscustomobject]@{
+      helper = 'windows-grok-native-installer'
+      mode = $executionMode
+      status = 'failed'
+      installed = $false
+      detectedVersion = $null
+      commandPath = Resolve-GrokExecutablePath
+      restartRequired = $false
+      plannedActions = @()
+      warnings = @('Refusing to run under an elevated shell without -AllowAdmin because Grok CLI is intended for user-scoped installation.')
+      appliedChanges = @()
+      manualSteps = @()
+      interruptions = @()
+    }) -ExitCode 1
+}
+
+$detected = Detect-GrokInstall
+$plannedActions = [System.Collections.Generic.List[string]]::new()
+$appliedChanges = [System.Collections.Generic.List[string]]::new()
+$warnings = [System.Collections.Generic.List[string]]::new()
+$manualSteps = [System.Collections.Generic.List[string]]::new()
+
+if ($Force) {
+  $plannedActions.Add('reinstall_grok_native')
+} elseif ($Upgrade -and $detected.installed) {
+  $plannedActions.Add('upgrade_grok_native')
+} elseif (-not $detected.installed) {
+  $plannedActions.Add('install_grok_native')
+}
+
+if ($CheckOnly) {
+  Write-StructuredResult -Result ([pscustomobject]@{
+      helper = 'windows-grok-native-installer'
+      mode = 'check'
+      status = if ($detected.installed) { 'ready' } else { 'not_installed' }
+      installed = [bool]$detected.installed
+      detectedVersion = if ($detected.detectedVersion) { $detected.detectedVersion } else { $null }
+      commandPath = $detected.commandPath
+      restartRequired = $false
+      plannedActions = $plannedActions.ToArray()
+      warnings = @()
+      appliedChanges = @()
+      manualSteps = @()
+      interruptions = @()
+    }) -ExitCode 0
+}
+
+$shouldInstall = $Force -or $Upgrade -or -not $detected.installed
+$installFailed = $false
+$installSkipped = $false
+if ($shouldInstall) {
+  if ($DryRun) {
+    $warnings.Add('Dry-run requested; Grok installer invocation was skipped.')
+    $installSkipped = $true
+  } else {
+    $installResult = Invoke-GrokInstaller
+    $installSkipped = [bool]$installResult.skipped
+    $installFailed = (-not $installSkipped) -and (-not $installResult.success)
+    if ($installSkipped) {
+      $warnings.Add('Installer invocation was skipped by request.')
+    } elseif ($installFailed) {
+      $stderrSnippet = if ([string]::IsNullOrWhiteSpace($installResult.stderr)) {
+        'no stderr captured'
+      } else {
+        ($installResult.stderr.Trim() -split "`r?`n" |
+          Where-Object { -not [string]::IsNullOrWhiteSpace($_) } |
+          Select-Object -Last 8) -join ' | '
+      }
+      $warnings.Add("Grok installer exited $($installResult.exitCode): $stderrSnippet")
+    }
+
+    Start-Sleep -Seconds 2
+    Add-GrokToUserPath
+    $detected = Detect-GrokInstall
+    if (-not $detected.installed -and -not $installSkipped -and -not $installFailed) {
+      $warnings.Add('Grok installation completed but grok.exe was not detected at the expected path.')
+      $installFailed = $true
+    }
+  }
+
+  if (-not $installFailed -and -not ($DryRun -and $shouldInstall)) {
+    if ($Force) {
+      $appliedChanges.Add('reinstall_grok_native')
+    } elseif ($Upgrade) {
+      $appliedChanges.Add('upgrade_grok_native')
+    } else {
+      $appliedChanges.Add('install_grok_native')
+    }
+  }
+}
+
+$manualSteps.Add('Run `grok login` or set XAI_API_KEY before first use.')
+$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 Grok install step, then rerun the packaged setup check.'
+      resumable = $true
+      requiresRestart = $false
+      requiresElevation = $false
+    })
+}
+
+$status = if ($installFailed) {
+  'failed'
+} elseif ($DryRun -and $shouldInstall) {
+  'preview'
+} elseif ($interruptions.Count -gt 0) {
+  [string]$interruptions[0].kind
+} else {
+  'ready'
+}
+
+Write-StructuredResult -Result ([pscustomobject]@{
+    helper = 'windows-grok-native-installer'
+    mode = $executionMode
+    status = $status
+    installed = [bool]$detected.installed
+    detectedVersion = if ($detected.detectedVersion) { $detected.detectedVersion } else { $null }
+    commandPath = $detected.commandPath
+    restartRequired = $false
+    plannedActions = $plannedActions.ToArray()
+    warnings = $warnings.ToArray()
+    appliedChanges = $appliedChanges.ToArray()
+    manualSteps = $manualSteps.ToArray()
+    interruptions = $interruptions.ToArray()
+  }) -ExitCode $(if ($installFailed) { 1 } else { 0 })

package/scripts/windows/Install-Pi.ps1

@@ -22,7 +22,7 @@ $ErrorActionPreference = 'Stop'
 
 Invoke-PackagedNpmCliInstall `
   -HelperId 'windows-pi-native-installer' `
-  -PackageName '@mariozechner/pi-coding-agent' `
+  -PackageName '@earendil-works/pi-coding-agent' `
   -CommandName 'pi' `
   -DisplayName 'Pi Coding Agent' `
   -CheckOnly:$CheckOnly `

package/scripts/windows/Test-WindowsInstallerSmoke.ps1

@@ -195,6 +195,7 @@ $requiredFiles = @(
   @{ Path = (Join-Path $resourcesRoot 'desktop\setup-assets\windows\_NpmCliInstaller.ps1'); Label = 'bundled Windows shared npm CLI installer helper' },
   @{ Path = (Join-Path $resourcesRoot 'desktop\setup-assets\windows\Install-Codex.ps1'); Label = 'bundled Windows native OpenAI Codex installer helper' },
   @{ Path = (Join-Path $resourcesRoot 'desktop\setup-assets\windows\Install-Antigravity.ps1'); Label = 'bundled Windows native Antigravity installer helper' },
+  @{ Path = (Join-Path $resourcesRoot 'desktop\setup-assets\windows\Install-Grok.ps1'); Label = 'bundled Windows native Grok installer helper' },
   @{ Path = (Join-Path $resourcesRoot 'desktop\setup-assets\windows\Install-Copilot.ps1'); Label = 'bundled Windows native GitHub Copilot installer helper' },
   @{ Path = (Join-Path $resourcesRoot 'desktop\setup-assets\windows\Install-OpenCode.ps1'); Label = 'bundled Windows native OpenCode installer helper' },
   @{ Path = (Join-Path $resourcesRoot 'desktop\setup-assets\windows\Install-KiloCli.ps1'); Label = 'bundled Windows native Kilo Code installer helper' },
@@ -216,6 +217,26 @@ foreach ($requiredFile in $requiredFiles) {
   Assert-FileExists -Path $requiredFile.Path -Label $requiredFile.Label
 }
 
+$grokHelperPath = Join-Path $resourcesRoot 'desktop\setup-assets\windows\Install-Grok.ps1'
+$grokCheck = & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $grokHelperPath `
+  -CheckOnly -Json -AllowAdmin | ConvertFrom-Json
+Assert-True ($grokCheck.helper -eq 'windows-grok-native-installer') `
+  'bundled Windows Grok helper check mode completed'
+$grokPreview = & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $grokHelperPath `
+  -Force -DryRun -Json -AllowAdmin | ConvertFrom-Json
+Assert-True ($grokPreview.status -eq 'preview') `
+  'bundled Windows Grok helper dry-run mode completed'
+
+$clineHelperPath = Join-Path $resourcesRoot 'desktop\setup-assets\windows\Install-Cline.ps1'
+$clineCheck = & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $clineHelperPath `
+  -CheckOnly -Json -AllowAdmin | ConvertFrom-Json
+Assert-True ($clineCheck.helper -eq 'windows-cline-native-installer') `
+  'bundled Windows Cline helper check mode completed'
+$clinePreview = & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $clineHelperPath `
+  -Force -DryRun -Json -AllowAdmin -SkipNpmInvocation | ConvertFrom-Json
+Assert-True ($clinePreview.status -eq 'preview') `
+  'bundled Windows Cline helper dry-run mode completed'
+
 $packagingPlan = Read-JsonFile -Path $packagingPlanPath
 Assert-True ($packagingPlan.strategy -eq 'electron-sidecar-bundle') 'installer packaging strategy is electron-sidecar-bundle'
 Assert-True ($packagingPlan.selfHostedNpmCompatible -eq $true) 'installer keeps self-hosted npm compatibility'
@@ -232,6 +253,7 @@ Assert-True (($windowsTarget.artifacts | Where-Object { $_.id -eq 'windows-githu
 Assert-True (($windowsTarget.artifacts | Where-Object { $_.id -eq 'windows-npm-prefix-helper-script' }).Count -ge 1) 'Windows target includes the bundled npm prefix setup asset'
 Assert-True (($windowsTarget.artifacts | Where-Object { $_.id -eq 'windows-codex-native-installer-script' }).Count -ge 1) 'Windows target includes the bundled native OpenAI Codex installer asset'
 Assert-True (($windowsTarget.artifacts | Where-Object { $_.id -eq 'windows-antigravity-native-installer-script' }).Count -ge 1) 'Windows target includes the bundled native Antigravity installer asset'
+Assert-True (($windowsTarget.artifacts | Where-Object { $_.id -eq 'windows-grok-native-installer-script' }).Count -ge 1) 'Windows target includes the bundled native Grok installer asset'
 Assert-True (($windowsTarget.artifacts | Where-Object { $_.id -eq 'windows-copilot-native-installer-script' }).Count -ge 1) 'Windows target includes the bundled native GitHub Copilot installer asset'
 Assert-True (($windowsTarget.artifacts | Where-Object { $_.id -eq 'windows-opencode-native-installer-script' }).Count -ge 1) 'Windows target includes the bundled native OpenCode installer asset'
 Assert-True (($windowsTarget.artifacts | Where-Object { $_.id -eq 'windows-kilo-native-installer-script' }).Count -ge 1) 'Windows target includes the bundled native Kilo installer asset'
@@ -246,6 +268,7 @@ Assert-True (($windowsTarget.artifacts | Where-Object { $_.id -eq 'windows-ollam
 Assert-True (($windowsTarget.artifacts | Where-Object { $_.id -eq 'windows-setup-readiness-audit-script' }).Count -ge 1) 'Windows target includes the bundled setup readiness audit asset'
 Assert-True (($packagingPlan.installer.providerSetup.localProviders | Where-Object { $_.id -eq 'opencode' -and $_.bundledInCurrentInstaller -eq $true }).Count -ge 1) 'installer contract keeps OpenCode in the bundled local-provider rollout'
 Assert-True (($packagingPlan.installer.providerSetup.localProviders | Where-Object { $_.id -eq 'kilo' -and $_.bundledInCurrentInstaller -eq $true }).Count -ge 1) 'installer contract keeps Kilo in the bundled local-provider rollout'
+Assert-True (($packagingPlan.installer.providerSetup.localProviders | Where-Object { $_.id -eq 'grok' -and $_.bundledInCurrentInstaller -eq $true }).Count -ge 1) 'installer contract keeps Grok in the bundled local-provider rollout'
 Assert-True (($packagingPlan.installer.providerSetup.localProviders | Where-Object { $_.id -eq 'ollama' -and $_.bundledInCurrentInstaller -eq $true }).Count -ge 1) 'installer contract keeps Ollama in the bundled local-provider rollout'
 Assert-True (($packagingPlan.installer.providerSetup.helperCatalog | Where-Object { $_.id -eq 'windows-ollama-local-model-installer' }).Count -ge 1) 'installer contract includes the bundled Ollama helper metadata'
 

package/scripts/windows/_NpmCliInstaller.ps1

@@ -183,6 +183,45 @@ function Resolve-NpmCliCommandPath {
   return $null
 }
 
+function Get-SupersededNpmPackages {
+  <#
+    Packages whose npm name changed upstream. npm resolves an abandoned name to
+    its final published version and reports it as current forever, so
+    `npm outdated -g` never flags it and every upgrade path silently skips it.
+    Two packages shipping the same bin also fight over the shim, which resolves
+    to whichever installed last. The superseded package is therefore removed
+    before its replacement is installed, matching environment-bootstrap cfe7785.
+  #>
+  param(
+    [Parameter(Mandatory = $true)]
+    [string]$PackageName
+  )
+
+  switch ($PackageName) {
+    '@earendil-works/pi-coding-agent' { @('@mariozechner/pi-coding-agent') }
+    default { @() }
+  }
+}
+
+function Remove-SupersededNpmPackages {
+  param(
+    [Parameter(Mandatory = $true)]
+    [string]$PackageName,
+    [System.Collections.ArrayList]$AppliedChanges
+  )
+
+  foreach ($legacy in (Get-SupersededNpmPackages -PackageName $PackageName)) {
+    & npm list -g --depth=0 $legacy 2>$null | Out-Null
+    if ($LASTEXITCODE -ne 0) { continue }
+
+    Write-Host "Removing superseded package $legacy (replaced by $PackageName)."
+    & npm uninstall -g $legacy 2>$null | Out-Null
+    if ($AppliedChanges) {
+      $AppliedChanges.Add("${legacy}:removed-superseded") | Out-Null
+    }
+  }
+}
+
 function Invoke-PackagedNpmCliInstall {
   param(
     [Parameter(Mandatory = $true)]
@@ -520,6 +559,8 @@ function Invoke-PackagedNpmCliInstall {
     exit 0
   }
 
+  Remove-SupersededNpmPackages -PackageName $PackageName -AppliedChanges $appliedChanges
+
   # --include=optional defends against user-level `omit=optional` in npmrc.
   # Without it, packages like @openai/codex skip their platform-specific
   # binaries (codex-win32-x64, codex-darwin-arm64, ...), leaving a shim that