@cats-inc/cats-platform 0.1.0

package/scripts/windows/Setup-CliReadiness.ps1

@@ -0,0 +1,339 @@
+<#
+.SYNOPSIS
+    Prepare a clean Windows host so user-launched CLIs work in PowerShell.
+
+.DESCRIPTION
+    After Cats's bridge installs CLIs (claude, codex, kiro-cli, cursor-agent, ...),
+    the user still needs two things to invoke them from their own PowerShell or
+    cmd terminal (e.g. for first-time `claude auth login`):
+
+      1. ExecutionPolicy unblocked. A clean Windows install defaults to
+         Restricted, which blocks .ps1 / .psm1 shims that several CLIs ship as.
+
+      2. User PATH updated. Some installers drop binaries under per-user
+         directories (~/.local/bin, %LOCALAPPDATA%/Kiro-Cli, etc.) that are not
+         on the default PATH, so a fresh terminal cannot find the executables.
+
+    This helper is idempotent and user-scoped. It never touches the Machine
+    policy or Machine PATH and never elevates without -AllowAdmin.
+
+.PARAMETER CheckOnly
+    Report the current state without mutating policy or PATH.
+
+.PARAMETER Apply
+    Set ExecutionPolicy to RemoteSigned (CurrentUser scope) and append any
+    missing CLI directories to the user PATH.
+
+.PARAMETER Json
+    Emit a structured JSON result instead of human-readable console output.
+
+.PARAMETER AllowAdmin
+    Allow execution under an elevated shell. Defaults to refusing because the
+    helper is intended to keep changes user-scoped.
+
+.PARAMETER UserHome
+    Override the user home directory (defaults to $env:USERPROFILE).
+
+.PARAMETER LocalAppData
+    Override the LOCALAPPDATA directory (defaults to $env:LOCALAPPDATA).
+
+.PARAMETER CurrentUserPath
+    Override the current user PATH for deterministic check-mode tests.
+
+.PARAMETER CurrentExecutionPolicy
+    Override the current ExecutionPolicy reading for deterministic tests.
+#>
+param(
+  [switch]$CheckOnly,
+  [switch]$Apply,
+  [switch]$Json,
+  [switch]$AllowAdmin,
+  [string]$UserHome = $env:USERPROFILE,
+  [string]$LocalAppData = $env:LOCALAPPDATA,
+  [string]$CurrentUserPath = '',
+  [string]$CurrentExecutionPolicy = ''
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$HelperId = 'windows-cli-readiness-helper'
+$DesiredPolicy = 'RemoteSigned'
+$AcceptablePolicies = @('RemoteSigned', 'Unrestricted', 'Bypass')
+$ExecutionPolicyRegistrySubKey = 'Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell'
+
+function Read-CurrentUserExecutionPolicy {
+  # Read the registry directly instead of calling Get-ExecutionPolicy. When the
+  # bridge spawns powershell.exe with redirected I/O and an inherited PSModulePath
+  # that points at PowerShell 7's modules, Microsoft.PowerShell.Security fails to
+  # autoload — taking Get-ExecutionPolicy / Set-ExecutionPolicy down with it.
+  try {
+    $key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey($ExecutionPolicyRegistrySubKey)
+    if ($null -eq $key) {
+      return 'Undefined'
+    }
+    try {
+      $value = $key.GetValue('ExecutionPolicy')
+    } finally {
+      $key.Dispose()
+    }
+    if ($null -eq $value -or [string]::IsNullOrWhiteSpace([string]$value)) {
+      return 'Undefined'
+    }
+    return [string]$value
+  } catch {
+    return 'Undefined'
+  }
+}
+
+function Set-CurrentUserExecutionPolicyRegistry {
+  param([string]$Policy)
+
+  $key = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey($ExecutionPolicyRegistrySubKey)
+  if ($null -eq $key) {
+    throw "Failed to open or create HKCU:\$ExecutionPolicyRegistrySubKey"
+  }
+  try {
+    $key.SetValue('ExecutionPolicy', $Policy, [Microsoft.Win32.RegistryValueKind]::String)
+  } finally {
+    $key.Dispose()
+  }
+}
+
+function Normalize-PathValue {
+  param(
+    [AllowNull()]
+    [string]$Path
+  )
+
+  if ([string]::IsNullOrWhiteSpace($Path)) {
+    return ''
+  }
+
+  return $Path.Trim().TrimEnd('\')
+}
+
+function Get-PathEntries {
+  param(
+    [AllowNull()]
+    [string]$PathValue
+  )
+
+  if ([string]::IsNullOrWhiteSpace($PathValue)) {
+    return @()
+  }
+
+  return $PathValue.Split(';', [System.StringSplitOptions]::RemoveEmptyEntries)
+}
+
+function Test-PathEntryPresent {
+  param(
+    [string[]]$Entries,
+    [string]$Expected
+  )
+
+  $normalizedExpected = (Normalize-PathValue -Path $Expected).ToLowerInvariant()
+  foreach ($entry in $Entries) {
+    if ((Normalize-PathValue -Path $entry).ToLowerInvariant() -eq $normalizedExpected) {
+      return $true
+    }
+  }
+
+  return $false
+}
+
+function Get-CandidatePathEntries {
+  param(
+    [string]$HomeDir,
+    [string]$LocalApp
+  )
+
+  $candidates = [System.Collections.Generic.List[string]]::new()
+
+  if (-not [string]::IsNullOrWhiteSpace($HomeDir)) {
+    [void]$candidates.Add((Join-Path $HomeDir '.local\bin'))
+  }
+  if (-not [string]::IsNullOrWhiteSpace($LocalApp)) {
+    [void]$candidates.Add((Join-Path $LocalApp 'Kiro-Cli'))
+    [void]$candidates.Add((Join-Path $LocalApp 'cursor-agent'))
+  }
+
+  return $candidates.ToArray()
+}
+
+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 "Current policy: $($Result.currentExecutionPolicy)"
+    Write-Host "Desired policy: $($Result.desiredExecutionPolicy)"
+    Write-Host "Restart required: $($Result.restartRequired)"
+    foreach ($warning in $Result.warnings) {
+      Write-Warning $warning
+    }
+    foreach ($change in $Result.plannedChanges) {
+      Write-Host "Planned change: $change"
+    }
+    foreach ($change in $Result.appliedChanges) {
+      Write-Host "Applied change: $change"
+    }
+  }
+
+  exit $ExitCode
+}
+
+if (-not $CheckOnly -and -not $Apply) {
+  $CheckOnly = $true
+}
+
+if ($CheckOnly -and $Apply) {
+  throw 'Setup-CliReadiness.ps1 accepts either -CheckOnly or -Apply, not both.'
+}
+
+$isAdmin = ([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).
+  IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
+
+$executionMode = if ($Apply) { 'apply' } else { 'check' }
+
+if ($isAdmin -and -not $AllowAdmin) {
+  $result = [pscustomobject]@{
+    helper = $HelperId
+    mode = $executionMode
+    status = 'failed'
+    currentExecutionPolicy = ''
+    desiredExecutionPolicy = $DesiredPolicy
+    currentUserPath = ''
+    candidatePathEntries = @()
+    missingPathEntries = @()
+    restartRequired = $false
+    plannedChanges = @()
+    appliedChanges = @()
+    warnings = @(
+      'Refusing to run under an elevated shell without -AllowAdmin because this helper is intended for user-scoped setup.'
+    )
+  }
+  Write-StructuredResult -Result $result -ExitCode 1
+}
+
+$currentPolicy = if ($PSBoundParameters.ContainsKey('CurrentExecutionPolicy')) {
+  $CurrentExecutionPolicy
+} else {
+  Read-CurrentUserExecutionPolicy
+}
+
+$pathProbe = if ($PSBoundParameters.ContainsKey('CurrentUserPath')) {
+  $CurrentUserPath
+} else {
+  [System.Environment]::GetEnvironmentVariable('Path', 'User')
+}
+$pathEntries = Get-PathEntries -PathValue $pathProbe
+$candidatePathEntries = Get-CandidatePathEntries -HomeDir $UserHome -LocalApp $LocalAppData
+
+$policyNeedsUpdate = -not ($AcceptablePolicies -contains $currentPolicy)
+$missingPathEntries = [System.Collections.Generic.List[string]]::new()
+foreach ($candidate in $candidatePathEntries) {
+  if (Test-PathEntryPresent -Entries $pathEntries -Expected $candidate) {
+    continue
+  }
+  # Add unconditionally so users can run this helper before installing the
+  # native CLIs. Windows' PATH lookup silently ignores entries pointing at
+  # non-existent directories, so seeding ahead of install has no side effect
+  # but lets the next fresh terminal see the binaries the moment they appear.
+  [void]$missingPathEntries.Add($candidate)
+}
+
+$plannedChanges = [System.Collections.Generic.List[string]]::new()
+if ($policyNeedsUpdate) {
+  [void]$plannedChanges.Add("Set CurrentUser ExecutionPolicy to $DesiredPolicy (currently '$currentPolicy')")
+}
+foreach ($entry in $missingPathEntries) {
+  [void]$plannedChanges.Add("Add $entry to user PATH")
+}
+
+if ($CheckOnly) {
+  $checkStatus = if ($plannedChanges.Count -gt 0) { 'changes_required' } else { 'ready' }
+  $checkRestartRequired = $missingPathEntries.Count -gt 0
+  $result = [pscustomobject]@{
+    helper = $HelperId
+    mode = 'check'
+    status = $checkStatus
+    currentExecutionPolicy = $currentPolicy
+    desiredExecutionPolicy = $DesiredPolicy
+    currentUserPath = $pathProbe
+    candidatePathEntries = $candidatePathEntries
+    missingPathEntries = $missingPathEntries.ToArray()
+    restartRequired = $checkRestartRequired
+    plannedChanges = $plannedChanges.ToArray()
+    appliedChanges = @()
+    warnings = @()
+  }
+  Write-StructuredResult -Result $result -ExitCode 0
+}
+
+$appliedChanges = [System.Collections.Generic.List[string]]::new()
+$warnings = [System.Collections.Generic.List[string]]::new()
+
+if ($policyNeedsUpdate) {
+  try {
+    Set-CurrentUserExecutionPolicyRegistry -Policy $DesiredPolicy
+    [void]$appliedChanges.Add("Set CurrentUser ExecutionPolicy to $DesiredPolicy")
+    $currentPolicy = $DesiredPolicy
+  } catch {
+    [void]$warnings.Add("Failed to set ExecutionPolicy: $($_.Exception.Message)")
+  }
+}
+
+if ($missingPathEntries.Count -gt 0) {
+  $existingPath = [System.Environment]::GetEnvironmentVariable('Path', 'User')
+  $existingEntries = Get-PathEntries -PathValue $existingPath
+  $combinedEntries = [System.Collections.Generic.List[string]]::new()
+  foreach ($entry in $missingPathEntries) {
+    [void]$combinedEntries.Add($entry)
+  }
+  foreach ($entry in $existingEntries) {
+    [void]$combinedEntries.Add($entry)
+  }
+  $updatedPath = ($combinedEntries -join ';')
+  try {
+    [System.Environment]::SetEnvironmentVariable('Path', $updatedPath, 'User')
+    $env:Path = $updatedPath + ';' + [System.Environment]::GetEnvironmentVariable('Path', 'Machine')
+    foreach ($entry in $missingPathEntries) {
+      [void]$appliedChanges.Add("Added $entry to user PATH")
+    }
+    $pathProbe = $updatedPath
+  } catch {
+    [void]$warnings.Add("Failed to update user PATH: $($_.Exception.Message)")
+  }
+}
+
+$restartRequired = $missingPathEntries.Count -gt 0
+$finalStatus = if ($warnings.Count -gt 0) {
+  'partial'
+} elseif ($restartRequired) {
+  'restart_required'
+} else {
+  'ready'
+}
+
+$result = [pscustomobject]@{
+  helper = $HelperId
+  mode = 'apply'
+  status = $finalStatus
+  currentExecutionPolicy = $currentPolicy
+  desiredExecutionPolicy = $DesiredPolicy
+  currentUserPath = $pathProbe
+  candidatePathEntries = $candidatePathEntries
+  missingPathEntries = @()
+  restartRequired = $restartRequired
+  plannedChanges = @()
+  appliedChanges = $appliedChanges.ToArray()
+  warnings = $warnings.ToArray()
+}
+Write-StructuredResult -Result $result -ExitCode 0

package/scripts/windows/Setup-NgrokTunnel.ps1

@@ -0,0 +1,369 @@
+<#
+.SYNOPSIS
+    Configure cats + ngrok auto-start on Windows.
+
+.DESCRIPTION
+    Builds cats, creates a user-level runner script, and registers a Windows
+    Startup shortcut so login will start the built cats server and ensure an
+    ngrok tunnel is available. Webhook registration remains owned by the Cats
+    UI/API.
+
+.PARAMETER Install
+    Build cats, create the runner script, register Windows Startup, and run
+    the runner once immediately.
+
+.PARAMETER Remove
+    Remove Windows Startup registration and stop the managed cats/ngrok
+    processes tracked by this helper.
+
+.PARAMETER Verify
+    Show runner, Startup, local server, and ngrok status.
+
+.PARAMETER Force
+    Recreate the runner and Startup shortcut even if they already exist.
+#>
+
+[CmdletBinding()]
+param(
+  [switch]$Install,
+  [switch]$Remove,
+  [switch]$Verify,
+  [switch]$Force
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Get-ProjectRoot {
+  return Split-Path -Parent (Split-Path -Parent $PSScriptRoot)
+}
+
+function Read-EnvValue {
+  param(
+    [string]$Path,
+    [string]$Name
+  )
+
+  if (-not (Test-Path $Path)) {
+    return $null
+  }
+
+  $line = Get-Content $Path | Select-String -Pattern ("^\s*{0}\s*=" -f [regex]::Escape($Name)) | Select-Object -First 1
+  if (-not $line) {
+    return $null
+  }
+
+  return ($line.Line -split '=', 2)[1].Trim()
+}
+
+function Resolve-EnvFile {
+  param([string]$ProjectRoot)
+
+  $envFile = Join-Path $ProjectRoot '.env'
+  if (Test-Path $envFile) {
+    return $envFile
+  }
+
+  $envExample = Join-Path $ProjectRoot '.env.example'
+  if (Test-Path $envExample) {
+    Copy-Item $envExample $envFile
+    return $envFile
+  }
+
+  throw 'Neither .env nor .env.example was found.'
+}
+
+function Get-CatsPort {
+  param([string]$EnvFile)
+
+  $port = Read-EnvValue -Path $EnvFile -Name 'CATS_PORT'
+  if ([string]::IsNullOrWhiteSpace($port)) {
+    $port = Read-EnvValue -Path $EnvFile -Name 'CATS_INC_PORT'
+  }
+  if ([string]::IsNullOrWhiteSpace($port)) {
+    return '8181'
+  }
+  return $port
+}
+
+function Get-HelperPaths {
+  $userScriptsDir = Join-Path $env:USERPROFILE 'Scripts'
+  $startupFolder = [Environment]::GetFolderPath('Startup')
+  return @{
+    UserScriptsDir = $userScriptsDir
+    RunnerScript = Join-Path $userScriptsDir 'Start-CatsNgrokTunnel.ps1'
+    RunnerLog = Join-Path $userScriptsDir 'cats-ngrok-tunnel.log'
+    ServerOutLog = Join-Path $userScriptsDir 'cats-server.out.log'
+    ServerErrLog = Join-Path $userScriptsDir 'cats-server.err.log'
+    ServerPidFile = Join-Path $userScriptsDir 'cats-server.pid'
+    NgrokOutLog = Join-Path $userScriptsDir 'cats-ngrok.out.log'
+    NgrokErrLog = Join-Path $userScriptsDir 'cats-ngrok.err.log'
+    NgrokPidFile = Join-Path $userScriptsDir 'cats-ngrok.pid'
+    StartupShortcut = Join-Path $startupFolder 'Start-CatsNgrokTunnel.lnk'
+  }
+}
+
+function Assert-NgrokReady {
+  if (-not (Get-Command ngrok -ErrorAction SilentlyContinue)) {
+    throw 'ngrok command not found. Install ngrok first.'
+  }
+}
+
+function Assert-NodeReady {
+  if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
+    throw 'node command not found. Install Node.js first.'
+  }
+  if (-not (Get-Command npm -ErrorAction SilentlyContinue)) {
+    throw 'npm command not found.'
+  }
+}
+
+function Ensure-Build {
+  param([string]$ProjectRoot)
+
+  Push-Location $ProjectRoot
+  try {
+    if (-not (Test-Path (Join-Path $ProjectRoot 'node_modules'))) {
+      npm install
+    }
+    npm run build
+  } finally {
+    Pop-Location
+  }
+}
+
+function Query-NgrokApi {
+  try {
+    return Invoke-RestMethod -Uri 'http://127.0.0.1:4040/api/tunnels' -TimeoutSec 3 -ErrorAction Stop
+  } catch {
+    return $null
+  }
+}
+
+function Show-IngressProbeHint {
+  param([string]$BaseUrl)
+
+  if ([string]::IsNullOrWhiteSpace($BaseUrl)) {
+    return
+  }
+
+  Write-Host 'Probe same-origin runtime ingress with:' -ForegroundColor Gray
+  Write-Host "  npm run ingress:smoke -- --base-url $BaseUrl" -ForegroundColor Gray
+}
+
+function New-RunnerScript {
+  param(
+    [string]$ProjectRoot,
+    [string]$EnvFile,
+    [hashtable]$Paths
+  )
+
+  if (-not (Test-Path $Paths.UserScriptsDir)) {
+    New-Item -ItemType Directory -Path $Paths.UserScriptsDir -Force | Out-Null
+  }
+
+  $content = @"
+`$ErrorActionPreference = 'Stop'
+`$projectRoot = '$($ProjectRoot -replace "'", "''")'
+`$envFile = '$($EnvFile -replace "'", "''")'
+`$runnerLog = '$($Paths.RunnerLog -replace "'", "''")'
+`$serverOutLog = '$($Paths.ServerOutLog -replace "'", "''")'
+`$serverErrLog = '$($Paths.ServerErrLog -replace "'", "''")'
+`$serverPidFile = '$($Paths.ServerPidFile -replace "'", "''")'
+`$ngrokOutLog = '$($Paths.NgrokOutLog -replace "'", "''")'
+`$ngrokErrLog = '$($Paths.NgrokErrLog -replace "'", "''")'
+`$ngrokPidFile = '$($Paths.NgrokPidFile -replace "'", "''")'
+
+function Import-EnvFile {
+  param([string]`$Path)
+
+  if (-not (Test-Path `$Path)) {
+    return
+  }
+
+  foreach (`$line in Get-Content `$Path) {
+    if ([string]::IsNullOrWhiteSpace(`$line) -or `$line.TrimStart().StartsWith('#')) {
+      continue
+    }
+    `$parts = `$line -split '=', 2
+    if (`$parts.Count -ne 2) {
+      continue
+    }
+    `$name = `$parts[0].Trim()
+    `$value = `$parts[1].Trim()
+    if (`$name) {
+      [Environment]::SetEnvironmentVariable(`$name, `$value, 'Process')
+    }
+  }
+}
+
+Import-EnvFile `$envFile
+
+`$port = `$env:CATS_PORT
+if ([string]::IsNullOrWhiteSpace(`$port)) {
+  `$port = `$env:CATS_INC_PORT
+}
+if ([string]::IsNullOrWhiteSpace(`$port)) {
+  `$port = '8181'
+}
+
+`$authToken = if (-not [string]::IsNullOrWhiteSpace(`$env:CATS_NGROK_AUTHTOKEN)) { `$env:CATS_NGROK_AUTHTOKEN } else { `$env:NGROK_AUTHTOKEN }
+`$domain = if (-not [string]::IsNullOrWhiteSpace(`$env:CATS_NGROK_DOMAIN)) { `$env:CATS_NGROK_DOMAIN } else { `$env:NGROK_DOMAIN }
+`$healthUrl = "http://127.0.0.1:`$port/health"
+Add-Content -Path `$runnerLog -Value ""
+`$timestamp = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
+Add-Content -Path `$runnerLog -Value "=== [`$timestamp] Starting cats + ngrok ==="
+
+`$serverHealthy = `$false
+try {
+  `$response = Invoke-WebRequest -Uri `$healthUrl -TimeoutSec 3 -UseBasicParsing -ErrorAction Stop
+  `$serverHealthy = `$response.StatusCode -eq 200
+} catch {
+  `$serverHealthy = `$false
+}
+
+if (-not `$serverHealthy) {
+  `$serverProcess = Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'npm start' -WorkingDirectory `$projectRoot -WindowStyle Hidden -RedirectStandardOutput `$serverOutLog -RedirectStandardError `$serverErrLog -PassThru
+  Set-Content -Path `$serverPidFile -Value `$serverProcess.Id
+  Start-Sleep -Seconds 5
+}
+
+if (Get-Command ngrok -ErrorAction SilentlyContinue) {
+  `$existingTunnel = `$false
+  try {
+    `$tunnels = Invoke-RestMethod -Uri 'http://127.0.0.1:4040/api/tunnels' -TimeoutSec 3 -ErrorAction Stop
+    foreach (`$tunnel in `$tunnels.tunnels) {
+      if (`$tunnel.config.addr -match "127\.0\.0\.1:`$port|localhost:`$port|http://127\.0\.0\.1:`$port") {
+        `$existingTunnel = `$true
+      }
+    }
+  } catch {
+    `$existingTunnel = `$false
+  }
+
+  if (-not `$existingTunnel) {
+    `$args = @('http', "http://127.0.0.1:`$port", '--log=stdout', '--log-format=logfmt', '--log-level=info')
+    if (-not [string]::IsNullOrWhiteSpace(`$authToken)) {
+      `$args += "--authtoken=`$authToken"
+    }
+    if (-not [string]::IsNullOrWhiteSpace(`$domain)) {
+      `$args += "--domain=`$domain"
+    }
+    `$ngrokProcess = Start-Process -FilePath 'ngrok' -ArgumentList `$args -WindowStyle Hidden -RedirectStandardOutput `$ngrokOutLog -RedirectStandardError `$ngrokErrLog -PassThru
+    Set-Content -Path `$ngrokPidFile -Value `$ngrokProcess.Id
+  }
+}
+"@
+
+  Set-Content -Path $Paths.RunnerScript -Value $content -Encoding UTF8
+}
+
+function New-StartupShortcut {
+  param([string]$RunnerScript, [string]$WorkingDirectory, [string]$ShortcutPath)
+
+  $shell = New-Object -ComObject WScript.Shell
+  $shortcut = $shell.CreateShortcut($ShortcutPath)
+  $targetPath = if (Test-Path 'C:\Program Files\PowerShell\7\pwsh.exe') { 'C:\Program Files\PowerShell\7\pwsh.exe' } else { 'powershell.exe' }
+  $shortcut.TargetPath = $targetPath
+  $shortcut.Arguments = "-WindowStyle Hidden -ExecutionPolicy Bypass -File `"$RunnerScript`""
+  $shortcut.WorkingDirectory = $WorkingDirectory
+  $shortcut.WindowStyle = 7
+  $shortcut.Description = 'Start cats and ensure ngrok is available'
+  $shortcut.Save()
+}
+
+function Stop-ManagedProcess {
+  param([string]$PidFile)
+
+  if (-not (Test-Path $PidFile)) {
+    return
+  }
+
+  $pidValue = Get-Content $PidFile -Raw
+  if ($pidValue -match '^\d+$') {
+    Stop-Process -Id ([int]$pidValue) -ErrorAction SilentlyContinue
+  }
+  Remove-Item $PidFile -ErrorAction SilentlyContinue
+}
+
+function Show-VerifySummary {
+  param(
+    [string]$Port,
+    [hashtable]$Paths
+  )
+
+  Write-Host '--- cats ngrok auto-start helper ---' -ForegroundColor Cyan
+  Write-Host "Runner script: $($Paths.RunnerScript)" -ForegroundColor Gray
+  Write-Host "Startup shortcut: $($Paths.StartupShortcut)" -ForegroundColor Gray
+
+  if (Test-Path $Paths.RunnerScript) {
+    Write-Host 'Runner script exists.' -ForegroundColor Green
+  } else {
+    Write-Host 'Runner script is missing.' -ForegroundColor Yellow
+  }
+
+  if (Test-Path $Paths.StartupShortcut) {
+    Write-Host 'Startup shortcut exists.' -ForegroundColor Green
+  } else {
+    Write-Host 'Startup shortcut is missing.' -ForegroundColor Yellow
+  }
+
+  $api = Query-NgrokApi
+  if ($api) {
+    Write-Host 'ngrok API is responding on http://127.0.0.1:4040/api/tunnels.' -ForegroundColor Green
+    foreach ($tunnel in $api.tunnels) {
+      Write-Host "Tunnel: $($tunnel.public_url) -> $($tunnel.config.addr)" -ForegroundColor Gray
+      Show-IngressProbeHint -BaseUrl $tunnel.public_url
+    }
+  } else {
+    Write-Host 'ngrok API is not responding.' -ForegroundColor Yellow
+  }
+
+  try {
+    $response = Invoke-WebRequest -Uri "http://127.0.0.1:$Port/health" -TimeoutSec 3 -UseBasicParsing -ErrorAction Stop
+    Write-Host "Local cats server health responded with HTTP $($response.StatusCode)." -ForegroundColor Green
+    Show-IngressProbeHint -BaseUrl "http://127.0.0.1:$Port"
+  } catch {
+    Write-Host "Local cats server is not responding on http://127.0.0.1:$Port/health yet." -ForegroundColor DarkYellow
+  }
+}
+
+$operationCount = @($Install, $Remove, $Verify).Where({ $_ }).Count
+if ($operationCount -ne 1) {
+  throw 'Choose exactly one operation: -Install, -Verify, or -Remove.'
+}
+
+$projectRoot = Get-ProjectRoot
+$envFile = Resolve-EnvFile -ProjectRoot $projectRoot
+$port = Get-CatsPort -EnvFile $envFile
+$paths = Get-HelperPaths
+
+if ($Verify) {
+  Assert-NgrokReady
+  Show-VerifySummary -Port $port -Paths $paths
+  exit 0
+}
+
+if ($Remove) {
+  Stop-ManagedProcess -PidFile $paths.NgrokPidFile
+  Stop-ManagedProcess -PidFile $paths.ServerPidFile
+  Remove-Item $paths.RunnerScript, $paths.RunnerLog, $paths.ServerOutLog, $paths.ServerErrLog, $paths.NgrokOutLog, $paths.NgrokErrLog, $paths.StartupShortcut -ErrorAction SilentlyContinue
+  Write-Host 'Removed cats ngrok auto-start configuration.' -ForegroundColor Green
+  exit 0
+}
+
+Assert-NgrokReady
+Assert-NodeReady
+Ensure-Build -ProjectRoot $projectRoot
+
+if (((Test-Path $paths.RunnerScript) -or (Test-Path $paths.StartupShortcut)) -and -not $Force) {
+  Write-Host 'Auto-start configuration already exists. Use -Force to recreate it.' -ForegroundColor Yellow
+  exit 0
+}
+
+New-RunnerScript -ProjectRoot $projectRoot -EnvFile $envFile -Paths $paths
+New-StartupShortcut -RunnerScript $paths.RunnerScript -WorkingDirectory $projectRoot -ShortcutPath $paths.StartupShortcut
+& $paths.RunnerScript
+
+Write-Host 'Installed cats ngrok auto-start configuration.' -ForegroundColor Green
+Write-Host "Runner script: $($paths.RunnerScript)" -ForegroundColor Gray
+Write-Host "Startup shortcut: $($paths.StartupShortcut)" -ForegroundColor Gray