@atomiton-dev/gap-cli 0.0.0-stage → 0.9.0-mvp

package/installer/gap-lib.ps1

@@ -0,0 +1,1248 @@
+# Shared by install.ps1 and gap.ps1 (#1750, D27, D28). Dot-sourced, never run; the caller sets
+# $GapSource to the folder it runs from (the unzipped installer, or ~\.gap once installed).
+#
+# Written for Windows PowerShell 5.1 (the one every Windows 10/11 has): no ??, no ternary, no &&.
+# ASCII only, because 5.1 reads a script that has no BOM as ANSI.
+
+$ErrorActionPreference = 'Continue'   # native commands write progress to stderr; check $LASTEXITCODE instead
+
+# Plain script variables, not environment variables: a GAP_* variable in the user's shell must not
+# change them.
+# D28: the installed instance (.env, docker-compose.yml, gap.ps1) lives in $GapHome, never in the
+# unzipped folder, so that moving or deleting that folder cannot lose the database password.
+$GapHome = Join-Path $HOME '.gap'
+$LauncherDir = Join-Path $GapHome 'bin'
+$GapProject = 'gap'
+$GapPortFirst = 8061
+$GapPortLast = 8070
+$GapUpTimeout = 300   # D26: seconds to wait for the three services to become healthy
+# Windows PowerShell 5.1 has no $IsWindows; PowerShell 7 does. False only when these scripts are
+# exercised with pwsh on macOS or Linux, where there is no user PATH in a registry to change.
+$OnWindows = ($PSVersionTable.PSVersion.Major -lt 6) -or $IsWindows
+
+# Only .env decides version, port and password (A4, E40): drop GAP_* and COMPOSE_* from this process.
+Get-ChildItem Env: | Where-Object { $_.Name -match '^(GAP|COMPOSE)_' } | ForEach-Object { Remove-Item -LiteralPath "Env:$($_.Name)" }
+
+# Windows Terminal and PowerShell 7 draw the check mark; the old console font may not.
+$Tick = if ($env:WT_SESSION -or $PSVersionTable.PSVersion.Major -ge 7) { [string][char]0x2713 } else { 'OK' }
+
+function Write-Ok($message)   { Write-Host "[$Tick] $message" }
+function Write-Warn($message) { Write-Host "[!] $message" }
+
+function Get-EnvPath { Join-Path $GapHome '.env' }
+
+# docker compose against this folder.
+function Invoke-Dc {
+  & docker compose -p $GapProject --project-directory $GapHome -f (Join-Path $GapHome 'docker-compose.yml') --env-file (Get-EnvPath) @args
+}
+
+# .env is read by Compose: UTF-8 without a BOM (a BOM would glue itself to the first key) and LF.
+function Write-EnvFile($text) {
+  [IO.File]::WriteAllText((Get-EnvPath), $text, (New-Object Text.UTF8Encoding($false)))
+}
+
+function Get-EnvValue($key) {
+  foreach ($line in [IO.File]::ReadAllLines((Get-EnvPath))) {
+    if ($line.StartsWith("$key=")) { return $line.Substring($key.Length + 1) }
+  }
+  return ''
+}
+
+# Get-ImageRef PREFIX NAME TAG: the name Docker knows an image by. PREFIX is the registry part with its trailing
+# slash (the npm channel: ghcr.io/atomiton-gap/) or empty (the ZIP channel: the local name, as `docker load` made
+# it). -f, not "$prefix$name:$tag": PowerShell would read `$name:` as a variable in a scope called name.
+function Get-ImageRef($prefix, $name, $tag) { '{0}{1}:{2}' -f $prefix, $name, $tag }
+
+# Get-InstalledPrefix: the PREFIX of the images that are on this machine, as the .env written by the install says
+# (#1986). Empty when .env has no such key (an install by a ZIP of #1750) or has it empty. Not "the prefix of the
+# channel running this script": an npm install over a machine that a ZIP installed rewrites .env. Use it to find
+# what is installed (uninstall); what to pull is the channel's own matter.
+function Get-InstalledPrefix { Get-EnvValue 'GAP_IMAGE_PREFIX' }
+
+# --- Which installer channel runs this script (#1986, #2011) ----------------------------------------------
+# The npm package carries a CHANNEL file that says `npm`, next to the scripts (installer\build-npm-package.sh). A ZIP
+# has no such file, and neither has the copy of gap.ps1 in ~\.gap, so both are the `zip` channel.
+$NpmImagePrefix = 'ghcr.io/atomiton-gap/'
+
+function Get-Channel {
+  $file = Join-Path $GapSource 'CHANNEL'
+  if ((Test-Path -LiteralPath $file) -and (([IO.File]::ReadAllText($file)).Trim() -eq 'npm')) { return 'npm' }
+  return 'zip'
+}
+
+# Get-ChannelPrefix / Get-ChannelPullPolicy: what the channel being run pulls from, and how Compose treats a missing
+# image. Never read from .env: an npm install over a machine that a ZIP installed finds an empty prefix there, and would
+# pull a gap-kernel:<V> that no registry has. Get-InstalledPrefix (above) is for finding what is installed.
+function Get-ChannelPrefix { if ((Get-Channel) -eq 'npm') { $NpmImagePrefix } else { '' } }
+function Get-ChannelPullPolicy { if ((Get-Channel) -eq 'npm') { 'missing' } else { 'never' } }
+
+# Get-InstallCommand: what the user types to install again, in the words of this channel.
+# Get-InstallName: the same command as Get-InstallCommand, short, for the sentence "... then run <it> again" of install.ps1's
+# own error messages. The ZIP keeps the bare script name those messages always had; npm has no install.ps1 to name (it
+# sits inside node_modules), only `gap install`.
+function Get-InstallName { if ((Get-Channel) -eq 'npm') { 'gap install' } else { 'install.ps1' } }
+
+function Get-InstallCommand {
+  if ((Get-Channel) -eq 'npm') { return 'gap install' }
+  return "powershell -ExecutionPolicy Bypass -File `"$(Join-Path $GapSource 'install.ps1')`""
+}
+
+# Get-PullErrorKind TEXT: unauthorized | denied | notfound | network | other, for what `docker pull` printed. The texts
+# are the ones measured on ghcr.io (03/11/2026, spike S6, on macOS: the text comes from the Docker daemon, which is
+# the same on Windows, but this has not been measured there): `error from registry: unauthorized` is no credential at
+# all, `error from registry: denied` is a credential that was refused or has no right to the package (not told apart by
+# text), `<ref>: not found` is a missing tag or package, `failed to do request` is a network that did not answer.
+# Anything else is `other`: its text is shown as Docker gave it.
+function Get-PullErrorKind($text) {
+  $t = "$text".ToLower()
+  if ($t.Contains('failed to do request')) { return 'network' }
+  if ($t.Contains('error from registry: unauthorized')) { return 'unauthorized' }
+  if ($t.Contains('error from registry: denied')) { return 'denied' }
+  if ($t.Contains(': not found')) { return 'notfound' }
+  return 'other'
+}
+
+# Write-LoginSteps / Write-DeniedHelp: what to do about `unauthorized` and `denied`. Shared by Write-PullFailure (a pull that
+# failed), doctor (access read with `docker manifest inspect`) and `gap login` (the same check, right after the login). None
+# of them prints or asks for a token here: `gap login` asks for it and hands it to Docker on stdin.
+function Write-LoginSteps {
+  Write-Host 'Action:'
+  Write-Host '  1. Create a GitHub personal access token (classic) that has the read:packages permission:'
+  Write-Host '       https://github.com/settings/tokens/new?scopes=read:packages'
+  Write-Host '  2. Log in to the registry:  gap login'
+  Write-Host '     and enter your GitHub username and the token when it asks.'
+}
+
+# $script:LoginJustDone is set by `gap login` before it checks the images: the token was accepted a second ago, so an expired
+# or revoked token is not what the refusal means, and saying so would send the user to make a second token for nothing.
+$script:LoginJustDone = $false
+
+function Write-DeniedHelp {
+  if ($script:LoginJustDone) {
+    Write-Host "You are logged in, but your GitHub account has not been given access to GAP's images."
+    Write-Host 'Ask the GAP administrator to add you to the team that can read them. If you were added just now,'
+    Write-Host 'accept the invitation GitHub emailed you, then check again with: gap doctor'
+    return
+  }
+  Write-Host 'Either your token is no longer valid (expired or revoked), or your GitHub account has not been given'
+  Write-Host "access to GAP's images. Ask the GAP administrator to add you to the team that can read them."
+  Write-Host 'If you were added, accept the invitation GitHub emailed you. If you are already on the team,'
+  Write-Host 'create a new token with read:packages and log in again:'
+  Write-Host '  gap login'
+}
+
+# Get-LoginErrorKind TEXT: rejected | network | other, for what `docker login` printed when it failed (the same words, and the
+# same order, as classify_login_error in gap-lib.sh). Measured with Docker 29 on ghcr.io (05/11/2026), on macOS: a made-up
+# token ends with `Error response from daemon: Get "https://ghcr.io/v2/": denied: denied`; an unreachable registry with
+# `... Client.Timeout exceeded ...` or `... no such host`. A bare "denied" is not enough for `rejected`: an unreadable Docker
+# config says `permission denied` too, and that is not a bad token.
+function Get-LoginErrorKind($text) {
+  $t = "$text".ToLowerInvariant()
+  foreach ($marker in 'no such host', 'client.timeout', 'deadline exceeded', 'connection refused', 'i/o timeout', 'dial tcp', 'failed to do request') {
+    if ($t.Contains($marker)) { return 'network' }
+  }
+  if ($t.Contains('": denied') -or $t.Contains('": unauthorized')) { return 'rejected' }
+  return 'other'
+}
+
+# Write-PullFailure IMAGE KIND TEXT [RETRY]: say what to do about a pull that failed. Nothing was written yet when this runs,
+# which the message says. RETRY is the command to run again when it is not the installer's own: `gap update` names itself, so
+# that the way on is not `gap install`, which would move the version with no backup and no guard.
+function Write-PullFailure($image, $kind, $text, $retry = '') {
+  $version = ([IO.File]::ReadAllText((Join-Path $GapSource 'VERSION'))).Trim()
+  switch ($kind) {
+    'unauthorized' {
+      Write-Warn "GAP's images are private and this machine is not logged in to ghcr.io"
+      Write-LoginSteps
+    }
+    'denied' {
+      Write-Warn "ghcr.io refused access to $image"
+      Write-DeniedHelp
+    }
+    'notfound' {
+      Write-Warn "$image was not found in the registry"
+      Write-Host "This GAP package is version $version. That version may not be published yet; check the version you were given."
+    }
+    'network' {
+      Write-Warn "Could not reach ghcr.io while pulling $image"
+      Write-Host 'Check your internet connection (and proxy settings). Images and layers already downloaded are kept.'
+    }
+    default {
+      Write-Warn "Pulling $image failed"
+      @("$text" -split "`r?`n" | Where-Object { $_ }) | Select-Object -Last 5 | ForEach-Object { Write-Host $_ }
+    }
+  }
+  if ($retry) {
+    Write-Host 'Nothing was changed.'
+    Write-Host "Then run: $retry"
+  } else {
+    Write-Host 'Nothing was installed and no data was changed.'
+    Write-Host "Then run: $(Get-InstallCommand)"
+  }
+}
+
+# Invoke-PullImages VERSION: pull the images this version needs from the registry of the channel (npm), the ones that are
+# not on this machine yet. Returns $false after Write-PullFailure has said what to do. Runs before anything is written to
+# GapHome, so a user who may not pull is left with nothing half installed. Docker's own output is not shown: a failure
+# is explained in our words (the text is shown only for a kind we do not know). RETRY: see Write-PullFailure.
+function Invoke-PullImages($version, $retry = '') {
+  $prefix = Get-ChannelPrefix
+  foreach ($image in (Get-ImageRef $prefix 'gap-kernel' $version), (Get-ImageRef $prefix 'gap-admin-ui' $version), (Get-ImageRef $prefix 'gap-postgres' '16')) {
+    & docker image inspect $image *> $null
+    if ($LASTEXITCODE -eq 0) { continue }
+    Write-Host "Pulling $image, this can take a few minutes..."
+    $out = & docker pull $image 2>&1
+    if ($LASTEXITCODE -ne 0) {
+      $text = @($out) -join "`n"
+      Write-PullFailure $image (Get-PullErrorKind $text) $text $retry
+      return $false
+    }
+  }
+  return $true
+}
+
+# Set-EnvValue KEY VALUE: set one line of .env, keep the others (and their secrets) untouched. A KEY
+# that is not in the file yet is added at the end (#1986: an .env written before a key existed, such as
+# the GAP_IMAGE_PREFIX of the npm channel, must be able to receive it).
+function Set-EnvValue($key, $value) {
+  $found = $false
+  # An explicit list, not `$x = foreach (...)`: that gives $null for an empty file and a bare string for
+  # a one-line file, and `@($null)` would put an empty first line in front of the new key.
+  $out = New-Object 'System.Collections.Generic.List[string]'
+  foreach ($line in [IO.File]::ReadAllLines((Get-EnvPath))) {
+    if ($line.StartsWith("$key=")) { $found = $true; $out.Add("$key=$value") } else { $out.Add($line) }
+  }
+  if (-not $found) { $out.Add("$key=$value") }
+  Write-EnvFile (($out -join "`n") + "`n")
+}
+
+function Get-UiUrl { "http://127.0.0.1:$(Get-EnvValue 'GAP_UI_PORT')" }
+
+function Get-OsName {
+  $arch = [Runtime.InteropServices.RuntimeInformation]::OSArchitecture.ToString().ToLower()
+  "Windows $arch"
+}
+
+# Prints the failing step, then what to do about it. $rerun = command to run again afterwards;
+# $needsUp = the caller is going to start the stack, which also checks that Compose has
+# `up --wait-timeout`. Returns $true when everything is in place.
+function Test-Prereqs($rerun, $needsUp) {
+  $lines = @("[$Tick] OS: $(Get-OsName)")
+  $action = ''
+  if (-not (Get-Command docker -ErrorAction SilentlyContinue)) {
+    $lines += '[!] Docker CLI not found'
+    $action = 'Install Docker Desktop (https://www.docker.com/products/docker-desktop/), then open a new terminal'
+  } else {
+    $lines += "[$Tick] Docker CLI detected"
+    $osType = & docker info --format '{{.OSType}}' 2>$null
+    if ($LASTEXITCODE -ne 0) {
+      $lines += '[!] Docker daemon stopped'
+      $action = 'Start Docker Desktop and wait until it says it is running'
+    } elseif ("$osType".Trim() -ne 'linux') {
+      $lines += "[$Tick] Docker daemon running"
+      $lines += '[!] Docker is set to Windows containers'
+      $action = 'Switch Docker Desktop to Linux containers (tray icon, then Switch to Linux containers)'
+    } else {
+      & docker compose version *> $null
+      if ($LASTEXITCODE -ne 0) {
+        $lines += "[$Tick] Docker daemon running"
+        $lines += '[!] Docker Compose not found'
+        $action = 'Update Docker Desktop (it includes Compose v2)'
+      } elseif ($needsUp -and ((& docker compose up --help 2>$null | Out-String) -notmatch '--wait-timeout')) {
+        # Start-GapStack needs `up --wait --wait-timeout`; an older Compose would fail there with
+        # "unknown flag" and the user would be told that a service is unhealthy.
+        $lines += "[$Tick] Docker daemon running"
+        $lines += '[!] Docker Compose is too old'
+        $action = 'Update Docker Desktop (it includes Compose v2)'
+      }
+    }
+  }
+  if (-not $action) { return $true }
+  $lines | ForEach-Object { Write-Host $_ }
+  Write-Host "Action: $action"
+  Write-Host "Then run: $rerun"
+  return $false
+}
+
+# Test-PortInUse P: something accepts connections on 127.0.0.1:P, or Windows will not let us bind
+# it (Hyper-V and WSL reserve some ranges; Docker then fails with "forbidden by its access
+# permissions" even though nothing listens).
+function Test-PortInUse($port) {
+  $client = New-Object Net.Sockets.TcpClient
+  try {
+    $pending = $client.BeginConnect('127.0.0.1', $port, $null, $null)
+    if ($pending.AsyncWaitHandle.WaitOne(500) -and $client.Connected) { return $true }
+  } catch {
+  } finally {
+    $client.Close()
+  }
+  $listener = New-Object Net.Sockets.TcpListener([Net.IPAddress]::Loopback, $port)
+  try {
+    $listener.Start()
+    return $false
+  } catch {
+    return $true
+  } finally {
+    try { $listener.Stop() } catch { }
+  }
+}
+
+# Test-PortOwnedByGap P: a container of this project publishes P.
+function Test-PortOwnedByGap($port) {
+  $id = & docker ps -q --filter "label=com.docker.compose.project=$GapProject" --filter "publish=$port" 2>$null
+  return [bool]$id
+}
+
+# Select-Port [STORED]: keep STORED when it is free or already ours, else the first free port of the
+# range (D9). Returns $null only when the whole range is taken.
+function Select-Port($stored) {
+  if ($stored -and ((-not (Test-PortInUse $stored)) -or (Test-PortOwnedByGap $stored))) { return [int]$stored }
+  foreach ($port in $GapPortFirst..$GapPortLast) {
+    if (-not (Test-PortInUse $port)) { return $port }
+  }
+  return $null
+}
+
+# Get-SvcState SERVICE: Healthy | Starting | Unhealthy | Restarting | Running | Stopped
+function Get-SvcState($service) {
+  $id = Invoke-Dc ps -aq $service 2>$null | Select-Object -First 1
+  if (-not $id) { return 'Stopped' }
+  $state = & docker inspect --format '{{.State.Status}}/{{if .State.Health}}{{.State.Health.Status}}{{end}}' $id 2>$null
+  switch -Wildcard ("$state".Trim()) {
+    'running/healthy'   { return 'Healthy' }
+    'running/starting'  { return 'Starting' }
+    'running/unhealthy' { return 'Unhealthy' }
+    'running/'          { return 'Running' }
+    'restarting/*'      { return 'Restarting' }
+    default             { return 'Stopped' }
+  }
+}
+
+# Test-HttpOk PATH: HTTP 200 from the Admin UI (so through nginx, the path the user takes). No proxy:
+# a corporate proxy setting must not intercept 127.0.0.1.
+function Test-HttpOk($path) {
+  try {
+    $request = [Net.WebRequest]::Create("$(Get-UiUrl)$path")
+    $request.Proxy = $null
+    $request.Timeout = 5000
+    $response = $request.GetResponse()
+    try { return ([int]$response.StatusCode -eq 200) } finally { $response.Close() }
+  } catch {
+    return $false
+  }
+}
+
+function Format-Arg($value) { '"' + $value + '"' }
+
+# Get-DescendantIds ID: every process below ID, deepest first (pwsh on macOS or Linux only).
+function Get-DescendantIds($id) {
+  foreach ($child in @(& pgrep -P $id 2>$null)) {
+    if ($child) {
+      Get-DescendantIds $child
+      $child
+    }
+  }
+}
+
+# Stop-ProcessTree PROC: the process and everything it started. docker.exe runs Compose as a separate
+# docker-compose.exe (a grandchild of this script), which Kill() alone would leave waiting on its own.
+function Stop-ProcessTree($proc) {
+  if ($OnWindows) {
+    & taskkill /PID $proc.Id /T /F *> $null
+    return
+  }
+  foreach ($id in @(Get-DescendantIds $proc.Id)) { & kill -TERM $id *> $null }
+  try { $proc.Kill() } catch { }
+}
+
+# The user PATH is read and written in the registry directly, not with
+# [Environment]::SetEnvironmentVariable: that would store it as REG_SZ with every %VAR% already
+# expanded, freezing entries such as %USERPROFILE%\AppData\Local\Microsoft\WindowsApps.
+function Get-UserPathRaw {
+  $key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment')
+  if (-not $key) { return '' }
+  try {
+    return [string]$key.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
+  } finally {
+    $key.Close()
+  }
+}
+
+function Set-UserPathRaw($value) {
+  $key = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey('Environment')
+  try {
+    if ($value) { $key.SetValue('Path', $value, [Microsoft.Win32.RegistryValueKind]::ExpandString) }
+    else { $key.DeleteValue('Path', $false) }
+  } finally {
+    $key.Close()
+  }
+  # Removing a user variable that does not exist changes nothing, but .NET then broadcasts
+  # WM_SETTINGCHANGE, so Explorer and the terminals it starts from now on see the new PATH.
+  [Environment]::SetEnvironmentVariable('GAP_INSTALLER_PATH_REFRESH', $null, 'User')
+}
+
+# Test-LauncherEntry ENTRY: a PATH entry that is the launcher folder (also when written with %VAR%).
+function Test-LauncherEntry($entry) {
+  [Environment]::ExpandEnvironmentVariables($entry).TrimEnd('\') -ieq $LauncherDir
+}
+
+# --- Does `gap` mean GAP in the user's own PowerShell? --------------------------------------------
+# install.cmd runs install.ps1 with -NoProfile, so it cannot see an alias or function called `gap`
+# that the user's profile defines, and PowerShell prefers those to gap.cmd on the PATH. So each
+# PowerShell the user may open (Windows PowerShell, PowerShell 7) is started the way a terminal
+# window starts it, with its profile, and asked how it resolves `gap`. Like opening a terminal,
+# that runs the profile, under the machine's own execution policy (see Get-GapResolution).
+$GapProbeTimeoutMs = 10000
+
+# Get-GapResolution EXE: how EXE resolves `gap`, as @{ Kind = CommandType or 'None'; Source = path }.
+# $null when it cannot say: a profile that exits, or hangs (killed after $GapProbeTimeoutMs).
+# - The question goes in -EncodedCommand: Windows PowerShell 5.1 mangles inner double quotes in arguments.
+# - The answer goes to a UTF-8 file, not to stdout: 5.1 writes redirected output in the console's
+#   code page, which turns a user folder such as C:\Users\Nguyen-with-accents into question marks.
+# - `-ExecutionPolicy Bypass` (install.cmd) is kept in $env:PSExecutionPolicyPreference and would be
+#   inherited, loading a profile that the user's own windows refuse to run; it is left out here.
+function Get-GapResolution($exe) {
+  $answerFile = [IO.Path]::GetTempFileName()
+  $out = [IO.Path]::GetTempFileName()
+  $err = [IO.Path]::GetTempFileName()
+  $target = "'" + $answerFile.Replace("'", "''") + "'"
+  $question = '$c = Get-Command gap -ErrorAction SilentlyContinue | Select-Object -First 1; ' +
+    '$a = if ($c) { "$($c.CommandType)|$($c.Source)" } else { ''None|'' }; ' +
+    "[IO.File]::WriteAllText($target, `$a, (New-Object Text.UTF8Encoding(`$false)))"
+  $encoded = [Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes($question))
+  $policy = $env:PSExecutionPolicyPreference
+  try {
+    Remove-Item Env:PSExecutionPolicyPreference -ErrorAction SilentlyContinue
+    try {
+      $proc = Start-Process -FilePath $exe -ArgumentList @('-NoLogo', '-NonInteractive', '-EncodedCommand', $encoded) `
+        -NoNewWindow -PassThru -RedirectStandardOutput $out -RedirectStandardError $err
+    } finally {
+      if ($policy) { $env:PSExecutionPolicyPreference = $policy }
+    }
+    $null = $proc.Handle   # keeps the handle so the process can be waited on and killed
+    if (-not $proc.WaitForExit($GapProbeTimeoutMs)) { Stop-ProcessTree $proc; return $null }
+    $answer = [IO.File]::ReadAllText($answerFile, [Text.Encoding]::UTF8)
+    $bar = $answer.IndexOf('|')
+    if ($bar -lt 1) { return $null }
+    return @{ Kind = $answer.Substring(0, $bar); Source = $answer.Substring($bar + 1) }
+  } catch {
+    return $null
+  } finally {
+    Remove-Item -LiteralPath $answerFile, $out, $err -Force -ErrorAction SilentlyContinue
+  }
+}
+
+# Get-ProbeShells: the PowerShells found on this machine, as @{ Name; Path }.
+function Get-ProbeShells {
+  foreach ($candidate in @(@{ Exe = 'powershell'; Name = 'Windows PowerShell' }, @{ Exe = 'pwsh'; Name = 'PowerShell 7' })) {
+    $found = Get-Command $candidate.Exe -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1
+    if ($found) { @{ Name = $candidate.Name; Path = $found.Source } }
+  }
+}
+
+# Test-NpmShim SOURCE: SOURCE is the command `npm install -g` made for this package. On Windows npm puts a shim (gap.cmd,
+# gap.ps1) in its global folder, next to node_modules\@atomiton-dev\gap-cli, and this script runs from the installer
+# folder inside that package. Compared by place, not by what the shim says. Not checked on Windows: the layout is
+# npm's documented one, it has not been looked at there.
+function Test-NpmShim($source) {
+  if ((Get-Channel) -ne 'npm') { return $false }
+  $package = [IO.Path]::GetFullPath((Split-Path -Parent $GapSource)).TrimEnd('\')
+  $shimDir = [IO.Path]::GetDirectoryName($source)
+  $expected = [IO.Path]::GetFullPath((Join-Path $shimDir 'node_modules\@atomiton-dev\gap-cli')).TrimEnd('\')
+  return ($expected -ieq $package)
+}
+
+# Get-GapResolutionReport: asks each PowerShell (Get-ProbeShells) and returns @{ Asked; Shadowed; NotFound; Lines }:
+# Lines say what to do where `gap` is not gap.cmd, and are empty where it is; Shadowed says there was
+# such a place. Asked is $false when no PowerShell could be asked, so that the caller can fall back
+# to what it knows without one.
+# Nothing is printed here: a profile may clear the console, so the caller asks before its summary.
+function Get-GapResolutionReport {
+  $asked = $false
+  $shadowed = $false
+  $notFound = $false
+  $lines = @()
+  $launcher = Join-Path $LauncherDir 'gap.cmd'
+  # What works when `gap` does not: the ZIP's launcher, or (npm) the script the package provides, which needs the
+  # flags that gap.cmd carries itself.
+  $fallback = if ((Get-Channel) -eq 'npm') { "powershell -NoProfile -ExecutionPolicy Bypass -File `"$(Join-Path $GapSource 'gap.ps1')`"" } else { $launcher }
+  $fallbackHint = if ((Get-Channel) -eq 'npm') { "powershell -NoProfile -ExecutionPolicy Bypass -File `"$(Join-Path $GapSource 'gap.ps1')`" status" } else { '& "$HOME\.gap\bin\gap.cmd" status' }
+  foreach ($shell in @(Get-ProbeShells)) {
+    $found = Get-GapResolution $shell.Path
+    if (-not $found) { continue }
+    $asked = $true
+    $kind = $found.Kind
+    # The install does not mind: this folder is not on the PATH of a window opened before, and the PATH note covers it.
+    # doctor does (NotFound): it says `gap` is not found.
+    if ($kind -eq 'None') { $notFound = $true; continue }
+    if ($kind -eq 'Application' -or $kind -eq 'ExternalScript') {
+      if ([IO.Path]::GetDirectoryName($found.Source) -ieq $LauncherDir) { continue }
+      if (Test-NpmShim $found.Source) { continue }
+      $shadowed = $true
+      $lines += "  Warning: in $($shell.Name), `"gap`" runs $($found.Source) (another program), not GAP."
+      if ((Get-Channel) -eq 'npm') { $lines += "  Run GAP with $fallback status, or put npm's global folder first on your PATH." }
+      else { $lines += "  Run GAP with $launcher status, or put $LauncherDir first on your PATH." }
+      continue
+    }
+    $shadowed = $true
+    $what = if ($kind -eq 'Alias') { 'an alias' } elseif ($kind -eq 'Function') { 'a function' } else { "a PowerShell command ($kind)" }
+    $lines += "  Warning: in $($shell.Name), `"gap`" is $what that runs something else, so `"gap status`" does not run GAP there."
+    if ($kind -eq 'Alias' -or $kind -eq 'Function') {
+      # The profile folder may not exist yet (the alias can come from another profile), and an alias
+      # made with -Option ReadOnly only goes with -Force.
+      $lines += '  To fix that for good, run this once in that window, then open a new one:'
+      $lines += "      New-Item -Force -ItemType Directory (Split-Path `$PROFILE) | Out-Null; Add-Content `$PROFILE 'Remove-Item -Force Alias:gap, Function:gap -ErrorAction SilentlyContinue'"
+    }
+    $lines += "  Until then, run GAP with: $fallbackHint"
+  }
+  return @{ Asked = $asked; Shadowed = $shadowed; NotFound = $notFound; Lines = $lines }
+}
+
+# Start-GapStack: docker compose up -d --wait, bounded (D26). A bare `up -d` hangs forever when the
+# Kernel crash-loops (A4.11), and --wait alone would sit out the whole timeout, so a Restarting
+# service stops the wait early. Returns $true when all three services are healthy.
+function Start-GapStack {
+  $out = [IO.Path]::GetTempFileName()
+  $err = [IO.Path]::GetTempFileName()
+  try {
+    $composeArgs = @('compose', '-p', $GapProject,
+      '--project-directory', (Format-Arg $GapHome),
+      '-f', (Format-Arg (Join-Path $GapHome 'docker-compose.yml')),
+      '--env-file', (Format-Arg (Get-EnvPath)),
+      'up', '-d', '--wait', '--wait-timeout', "$GapUpTimeout")
+    $proc = Start-Process -FilePath 'docker' -ArgumentList $composeArgs -NoNewWindow -PassThru `
+      -RedirectStandardOutput $out -RedirectStandardError $err
+    $null = $proc.Handle   # keeps the handle so ExitCode is readable after the process ends
+    while (-not $proc.HasExited) {
+      foreach ($service in 'postgres', 'kernel', 'admin-ui') {
+        if ((Get-SvcState $service) -eq 'Restarting') {
+          Stop-ProcessTree $proc
+          Write-Warn "$service keeps restarting"
+          Write-Host "Run: gap logs $service"
+          if ($service -eq 'kernel') {
+            Write-Host 'If .env was edited, the database password may no longer match the existing data (see: gap logs postgres).'
+          }
+          return $false
+        }
+      }
+      Start-Sleep -Seconds 3
+    }
+    $proc.WaitForExit()
+    if ($proc.ExitCode -ne 0) {
+      Write-Warn 'GAP did not start: a service is not healthy'
+      (@(Get-Content -LiteralPath $out) + @(Get-Content -LiteralPath $err)) | Select-Object -Last 5 | ForEach-Object { Write-Host $_ }
+      Write-Host 'Run: gap logs kernel'
+      if ((Get-SvcState 'kernel') -ne 'Healthy' -and (Get-SvcState 'postgres') -eq 'Healthy') {
+        Write-Host 'If .env was edited, the database password may no longer match the existing data (see: gap logs postgres).'
+      }
+      return $false
+    }
+    return $true
+  } finally {
+    Remove-Item -LiteralPath $out, $err -Force -ErrorAction SilentlyContinue
+  }
+}
+
+function Open-Url($url) {
+  try { Start-Process $url } catch { }
+}
+
+# --- gap version and gap doctor (#1986, #2012) -------------------------------------------------------------
+# Both only read. doctor never starts, stops or pulls anything, never writes .env, a launcher or the user PATH. It does
+# run the user's own PowerShell the way a new window starts it (Get-GapResolutionReport), as install.ps1 does.
+# NOT RUN: there is no Windows (and no pwsh) on the machine this was written on; see the notes at the places that rest on
+# something that was not looked at.
+$GapMinNodeMajor = 18   # the same number as MIN_NODE_MAJOR in npm\lib\launcher.js, which refuses to start below it
+
+function Test-Installed { Test-Path -LiteralPath (Get-EnvPath) }
+
+# Get-CliVersion: the version of the npm package that runs this script. Empty on the ZIP channel (the VERSION file of an
+# unzipped folder is the ZIP's own, not a package).
+function Get-CliVersion {
+  if ((Get-Channel) -ne 'npm') { return '' }
+  $file = Join-Path $GapSource 'VERSION'
+  if (-not (Test-Path -LiteralPath $file)) { return '' }
+  return ([IO.File]::ReadAllText($file)).Trim()
+}
+
+# Get-InstalledVersion: GAP_VERSION of the install in $GapHome. Empty when GAP is not installed; 'unknown' when there is an
+# .env that does not say (no number is guessed).
+function Get-InstalledVersion {
+  if (-not (Test-Installed)) { return '' }
+  $v = Get-EnvValue 'GAP_VERSION'
+  if ($v) { return $v }
+  return 'unknown'
+}
+
+# Compare-GapVersion A B: -1, 0 or 1 (A older than, equal to, newer than B); $null when it cannot tell. The same reading as
+# version_cmp in gap-lib.sh: major.minor.patch with an optional -suffix, the numbers compared as numbers, the suffix the same
+# (compared exactly, case too: -ceq, not -eq), nine digits at most. Callers compare the result with -eq, never as a boolean.
+$script:VersionPattern = '^([0-9]{1,9})\.([0-9]{1,9})\.([0-9]{1,9})(-[A-Za-z0-9._-]+)?$'
+function Compare-GapVersion($a, $b) {
+  $ma = [regex]::Match("$a", $script:VersionPattern)
+  $mb = [regex]::Match("$b", $script:VersionPattern)
+  if (-not $ma.Success -or -not $mb.Success) { return $null }
+  if ($ma.Groups[4].Value -cne $mb.Groups[4].Value) { return $null }
+  foreach ($i in 1, 2, 3) {
+    $x = [int64]$ma.Groups[$i].Value
+    $y = [int64]$mb.Groups[$i].Value
+    if ($x -gt $y) { return 1 }
+    if ($x -lt $y) { return -1 }
+  }
+  return 0
+}
+
+# Test-PackageOlder: the npm package that runs this script is older than the installed GAP, by numbers (false when equal,
+# newer, not comparable, or on the ZIP channel). `gap install` refuses to go back to it.
+function Test-PackageOlder {
+  if ((Get-Channel) -ne 'npm') { return $false }
+  $pkg = Get-CliVersion
+  $installed = Get-InstalledVersion
+  if (-not $pkg -or -not $installed) { return $false }
+  return ((Compare-GapVersion $installed $pkg) -eq 1)
+}
+
+# Test-PackageNewer: the mirror of Test-PackageOlder: the npm package that runs this script is newer than the installed GAP, by
+# numbers (`gap update` moves to it). False when equal, older, not comparable, or on the ZIP channel.
+function Test-PackageNewer {
+  if ((Get-Channel) -ne 'npm') { return $false }
+  $pkg = Get-CliVersion
+  $installed = Get-InstalledVersion
+  if (-not $pkg -or -not $installed) { return $false }
+  return ((Compare-GapVersion $installed $pkg) -eq -1)
+}
+
+# Write-NewerPackageNote: one line for `gap status` and `gap start`.
+function Write-NewerPackageNote {
+  if (Test-PackageNewer) { Write-Host "A newer version ($(Get-CliVersion)) is in the npm package. Run: gap update" }
+}
+
+function Write-OlderPackageHelp {
+  Write-Host '    gap does not go back: what a newer version did to the database cannot be undone.'
+  Write-Host '    Install the newer package first: npm install -g @atomiton-dev/gap-cli@latest'
+}
+
+# Get-ManifestErrorKind TEXT: unauthorized | denied | notfound | network | other, for what `docker manifest inspect` printed.
+# The same texts as classify_manifest_error in gap-lib.sh, measured on ghcr.io on macOS (04/11/2026); `docker manifest
+# inspect` is part of the Docker CLI, which is the same code on Windows, but this has not been measured there. A valid token
+# that may not read the package prints the single word `denied`; it counts only as the WHOLE text, because `permission denied`
+# (config file, Docker socket) is not the registry.
+function Get-ManifestErrorKind($text) {
+  $t = "$text".ToLower()
+  if ($t.Contains('failed to configure transport') -or $t.Contains('error pinging v2 registry') -or $t.Contains('failed to do request')) { return 'network' }
+  if ($t.Contains('": unauthorized')) { return 'unauthorized' }
+  if ($t.Contains('": denied')) { return 'denied' }
+  if ($t.Trim() -eq 'denied') { return 'denied' }
+  if ($t.Contains('manifest unknown')) { return 'notfound' }
+  return 'other'
+}
+
+$script:DoctorProblems = 0   # `[!]` lines of this run
+$script:DoctorDocker = $false   # $true when Docker is ready: what needs it is skipped otherwise
+
+# Add-DoctorProblem MESSAGE: a `[!]` line, counted. Write-DoctorUnsure MESSAGE: something that could not be checked; it says
+# nothing is wrong, so it is not counted. The lines that say what to do come after them, indented.
+function Add-DoctorProblem($message) { Write-Warn $message; $script:DoctorProblems++ }
+function Write-DoctorUnsure($message) { Write-Host "[?] $message" }
+
+# Get-DoctorInstallHint: the command that installs, in the words of this channel.
+function Get-DoctorInstallHint {
+  if ((Get-Channel) -eq 'npm') { return 'gap install' }
+  $ps1 = Join-Path $GapSource 'install.ps1'
+  if (Test-Path -LiteralPath $ps1) { return "powershell -ExecutionPolicy Bypass -File `"$ps1`"" }
+  return 'install.ps1 (in the GAP installer folder)'
+}
+
+function Test-DoctorNode {
+  if ((Get-Channel) -ne 'npm') { Write-Ok 'Node.js is not needed for the ZIP installer'; return }
+  $v = ''
+  if (Get-Command node -ErrorAction SilentlyContinue) { $v = "$(& node -v 2>$null)".Trim() }
+  $major = 0
+  if ($v -match '^v(\d+)\.') { $major = [int]$Matches[1] }
+  if ($major -eq 0) {
+    Add-DoctorProblem 'Node.js not found'
+    Write-Host "    Action: install Node.js $GapMinNodeMajor or newer from https://nodejs.org"
+  } elseif ($major -lt $GapMinNodeMajor) {
+    Add-DoctorProblem "Node.js $v is too old: GAP's npm package needs Node $GapMinNodeMajor or newer"
+    Write-Host '    Action: install a current Node.js from https://nodejs.org'
+  } else {
+    Write-Ok "Node.js $v"
+  }
+}
+
+# Test-DoctorDocker: Test-Prereqs as every command runs it (it prints the failing step and what to do), but a failure does not
+# end doctor: what does not need Docker is still looked at. (Test-Prereqs does not look for curl on Windows.)
+function Test-DoctorDocker {
+  if (Test-Prereqs 'gap doctor' $true) {
+    $script:DoctorDocker = $true
+    Write-Ok "OS: $(Get-OsName)"
+    Write-Ok 'Docker is ready (daemon running, Linux containers, Compose v2)'
+  } else {
+    $script:DoctorDocker = $false
+    $script:DoctorProblems++
+    if ((Get-Channel) -eq 'npm') {
+      Write-DoctorUnsure "Access to GAP's images and the state of the GAP services were not checked: Docker is not ready"
+    } else {
+      Write-DoctorUnsure 'The state of the GAP services was not checked: Docker is not ready'
+    }
+  }
+}
+
+# Test-DoctorPorts: what `gap install` and `gap start` would find: Select-Port itself decides, so the two cannot disagree.
+function Test-DoctorPorts {
+  $stored = ''
+  if (Test-Installed) { $stored = Get-EnvValue 'GAP_UI_PORT' }
+  $port = Select-Port $stored
+  if (-not $port) {
+    Add-DoctorProblem 'No free port for the Admin UI'
+    Write-Host "    Action: free a port between $GapPortFirst and $GapPortLast"
+  } elseif (-not $stored) {
+    Write-Ok "Port $port is free for the Admin UI"
+  } elseif ("$port" -ne "$stored") {
+    Write-Ok "The Admin UI port $stored is used by another program; the next gap start will use $port"
+  } elseif (Test-PortInUse $port) {
+    Write-Ok "The Admin UI port $stored is in use by GAP"
+  } else {
+    Write-Ok "The Admin UI port $stored is free"
+  }
+}
+
+# Test-DoctorGapCommand: does `gap` mean GAP in the user's own PowerShell? Each PowerShell is asked as install.ps1 asks it (a
+# new window: its profile runs); only when none can be asked is this process's own view used. The npm channel's global
+# folder is `npm prefix -g` itself on Windows (npm puts gap.cmd there), not a bin subfolder: NOT looked at on Windows.
+function Test-DoctorGapCommand {
+  $npm = ((Get-Channel) -eq 'npm')
+  # A ZIP that is not installed yet: install.ps1 puts `gap` on the PATH, and "GAP is not installed" already says to run it.
+  if (-not $npm -and -not (Test-Installed)) { return }
+  $zipLauncher = Join-Path $LauncherDir 'gap.cmd'
+  if ($npm -and (Test-Path -LiteralPath $zipLauncher)) {
+    Add-DoctorProblem "$zipLauncher is a launcher from a ZIP install of GAP and may run instead of the npm command"
+    Write-Host '    Use one channel per machine; the data is shared. To keep only the npm command, delete that file.'
+  }
+  $report = Get-GapResolutionReport
+  $found = $null
+  if (-not $report.Asked) {
+    $c = Get-Command gap -ErrorAction SilentlyContinue | Select-Object -First 1
+    if (-not $c) {
+      $report.NotFound = $true
+    } else {
+      $found = $c
+      if ($c.CommandType -eq 'Application' -or $c.CommandType -eq 'ExternalScript') {
+        $isLauncher = ([IO.Path]::GetDirectoryName($c.Source) -ieq $LauncherDir)
+        $ours = if ($npm) { Test-NpmShim $c.Source } else { $isLauncher }
+        # The ZIP launcher in front of the npm command is the one reported above, not a second problem.
+        if (-not $ours -and -not ($npm -and $isLauncher)) { $report.Shadowed = $true }
+      } else {
+        $report.Shadowed = $true   # an alias or a function
+      }
+    }
+  }
+  if ($report.Shadowed) {
+    Add-DoctorProblem 'In your PowerShell, "gap" does not run GAP'
+    if ($report.Asked) { $report.Lines | ForEach-Object { Write-Host $_ } }
+    else { Write-Host "    It runs $($found.Source). Run GAP with: powershell -NoProfile -ExecutionPolicy Bypass -File `"$(Join-Path $GapSource 'gap.ps1')`" status" }
+  }
+  # Both can be true: one PowerShell has its own `gap`, another has none (the bash side reports each shell as well).
+  if ($report.NotFound) {
+    Add-DoctorProblem '"gap" is not found: it is not on the PATH'
+    if ($npm) {
+      $prefix = ''
+      if (Get-Command npm -ErrorAction SilentlyContinue) { $prefix = "$(& npm prefix -g 2>$null)".Trim() }
+      if ($prefix) { Write-Host "    Action: add this folder to your PATH: $prefix" }
+      else { Write-Host "    Action: add npm's global folder to your PATH (find it with: npm prefix -g)" }
+    } else {
+      Write-Host "    Action: add this folder to your user PATH: $LauncherDir"
+    }
+    Write-Host "    Until then, run GAP with: powershell -NoProfile -ExecutionPolicy Bypass -File `"$(Join-Path $GapSource 'gap.ps1')`" status"
+  }
+  if (-not $report.Shadowed -and -not $report.NotFound) {
+    Write-Ok '"gap" runs GAP in your PowerShell'
+  }
+}
+
+# Join-DoctorRefs REFS: the references, comma-separated.
+function Join-DoctorRefs($refs) { (@($refs) -join ', ') }
+
+# Test-DoctorRegistry: the npm channel pulls from a private registry, so say whether this machine may read the three images.
+# `docker manifest inspect` reads a manifest and downloads no layer (it is not `docker pull`). The three run side by side, as
+# in gap-lib.sh: Docker stops waiting for an unreachable registry after 30 seconds by itself (measured on macOS), once, not
+# three times over. The prefix is the channel's, not .env's.
+$script:RegistryReadable = $false   # $true when Test-DoctorRegistry could read all three images (`gap login` exits 0 only then)
+
+function Test-DoctorRegistry {
+  $script:RegistryReadable = $false
+  if ((Get-Channel) -ne 'npm' -or -not $script:DoctorDocker) { return }
+  $version = Get-CliVersion
+  if (-not $version) { Write-DoctorUnsure "GAP's images were not checked: this package has no VERSION file"; return }
+  $prefix = Get-ChannelPrefix
+  $registryHost = $prefix.Split('/')[0]
+  $refs = @((Get-ImageRef $prefix 'gap-kernel' $version), (Get-ImageRef $prefix 'gap-admin-ui' $version), (Get-ImageRef $prefix 'gap-postgres' '16'))
+  Write-Host 'Checking access to the image registry...'
+  $jobs = @()
+  try {
+    foreach ($ref in $refs) {
+      $out = [IO.Path]::GetTempFileName()
+      $err = [IO.Path]::GetTempFileName()
+      $proc = Start-Process -FilePath 'docker' -ArgumentList @('manifest', 'inspect', $ref) -NoNewWindow -PassThru `
+        -RedirectStandardOutput $out -RedirectStandardError $err
+      $null = $proc.Handle   # keeps the handle so ExitCode is readable after the process ends
+      $jobs += @{ Ref = $ref; Proc = $proc; Out = $out; Err = $err }
+    }
+    $unauthorized = @(); $denied = @(); $notFound = @(); $network = @(); $other = @(); $otherText = ''
+    foreach ($job in $jobs) {
+      $job.Proc.WaitForExit()
+      if ($job.Proc.ExitCode -eq 0) { continue }
+      $text = (@(Get-Content -LiteralPath $job.Err) -join "`n")
+      switch (Get-ManifestErrorKind $text) {
+        'unauthorized' { $unauthorized += $job.Ref }
+        'denied'       { $denied += $job.Ref }
+        'notfound'     { $notFound += $job.Ref }
+        'network'      { $network += $job.Ref }
+        default        { $other += $job.Ref; $otherText = $text }
+      }
+    }
+  } finally {
+    foreach ($job in $jobs) { Remove-Item -LiteralPath $job.Out, $job.Err -Force -ErrorAction SilentlyContinue }
+  }
+  if (($unauthorized.Count + $denied.Count + $notFound.Count + $network.Count + $other.Count) -eq 0) {
+    Write-Ok "You can read GAP's images in $registryHost"
+    $script:RegistryReadable = $true
+    return
+  }
+  if ($unauthorized.Count -gt 0) {
+    Add-DoctorProblem "GAP's images are private and this machine is not logged in to $registryHost"
+    Write-LoginSteps
+  }
+  if ($denied.Count -gt 0) {
+    Add-DoctorProblem "$registryHost refused access to $(Join-DoctorRefs $denied)"
+    Write-DeniedHelp
+  }
+  if ($notFound.Count -gt 0) {
+    Add-DoctorProblem "$(Join-DoctorRefs $notFound) was not found in the registry"
+    Write-Host "This GAP package is version $version. That version may not be published yet; check the version you were given."
+  }
+  if ($network.Count -gt 0) {
+    Write-DoctorUnsure "Could not reach ${registryHost}: access to $(Join-DoctorRefs $network) was not checked"
+    Write-Host '    Check your internet connection (and proxy settings). Nothing is wrong with GAP itself.'
+  }
+  if ($other.Count -gt 0) {
+    Write-DoctorUnsure "Could not check access to $(Join-DoctorRefs $other)"
+    @("$otherText" -split "`r?`n" | Where-Object { $_ }) | Select-Object -Last 2 | ForEach-Object { Write-Host "    $_" }
+  }
+}
+
+# Test-DoctorServices: the three services, as `gap status` reads them (Get-SvcState), and the Admin UI through its own address.
+function Test-DoctorServices {
+  $pg = Get-SvcState 'postgres'
+  $kernel = Get-SvcState 'kernel'
+  $ui = Get-SvcState 'admin-ui'
+  if ($pg -eq 'Stopped' -and $kernel -eq 'Stopped' -and $ui -eq 'Stopped') {
+    Add-DoctorProblem 'GAP is not running'
+    Write-Host '    Run: gap start'
+    return
+  }
+  foreach ($item in @(@('postgres', 'PostgreSQL', $pg), @('kernel', 'GAP Kernel', $kernel), @('admin-ui', 'GAP Admin UI', $ui))) {
+    $service = $item[0]; $name = $item[1]; $state = $item[2]
+    switch ($state) {
+      'Healthy' { }
+      'Restarting' {
+        Add-DoctorProblem "$service keeps restarting"
+        Write-Host "    Run: gap logs $service"
+        if ($service -eq 'kernel') {
+          Write-Host '    If .env was edited, the database password may no longer match the existing data (see: gap logs postgres).'
+        }
+      }
+      'Stopped' { Add-DoctorProblem "$name is stopped"; Write-Host '    Run: gap start' }
+      'Starting' { Add-DoctorProblem "$name is still starting"; Write-Host '    Wait a minute, then run: gap doctor' }
+      default { Add-DoctorProblem "$name is $($state.ToLower())"; Write-Host "    Run: gap logs $service" }
+    }
+  }
+  if (-not ($pg -eq 'Healthy' -and $kernel -eq 'Healthy' -and $ui -eq 'Healthy')) { return }
+  Write-Ok 'PostgreSQL, GAP Kernel and GAP Admin UI are healthy'
+  if (Test-HttpOk '/system/health') {
+    Write-Ok "The Admin UI answers at $(Get-UiUrl)"
+  } else {
+    Add-DoctorProblem "The Admin UI does not answer at $(Get-UiUrl)"
+    Write-Host '    Run: gap logs kernel'
+  }
+}
+
+# Test-DoctorInstall: is GAP installed here, in the version this package expects, and running.
+function Test-DoctorInstall {
+  if (-not (Test-Installed)) {
+    $hasData = $false
+    if ($script:DoctorDocker) {
+      & docker volume inspect "${GapProject}_pgdata" *> $null
+      $hasData = ($LASTEXITCODE -eq 0)
+    }
+    if ($hasData) {
+      Add-DoctorProblem "GAP is not installed here, but data from an earlier install is in the Docker volume ${GapProject}_pgdata"
+      Write-Host "    Run: $(Get-DoctorInstallHint)  (it keeps that data)"
+    } else {
+      Add-DoctorProblem "GAP is not installed in $GapHome"
+      Write-Host "    Run: $(Get-DoctorInstallHint)"
+    }
+    return
+  }
+  $installed = Get-InstalledVersion
+  $pkg = Get-CliVersion
+  if ($installed -eq 'unknown') {
+    Add-DoctorProblem "GAP_VERSION is missing from $(Get-EnvPath)"
+    Write-Host "    Run: $(Get-DoctorInstallHint)"
+  } else {
+    Write-Ok "GAP $installed is installed in $GapHome"
+    if ($pkg -and $pkg -ne $installed) {
+      Add-DoctorProblem "The installed version ($installed) is not the version of this package ($pkg)"
+      if (Test-PackageNewer) { Write-Host '    Run: gap update  (it backs up first)' }
+      elseif (Test-PackageOlder) { Write-Host '    Install the newer package: npm install -g @atomiton-dev/gap-cli@latest' }
+      else { Write-Host "    Run: $(Get-DoctorInstallHint)" }
+    }
+  }
+  if (-not (Test-Path -LiteralPath (Join-Path $GapHome 'docker-compose.yml'))) {
+    Add-DoctorProblem "docker-compose.yml is missing in $GapHome"
+    Write-Host "    Run: $(Get-DoctorInstallHint) again to put it back"
+    return
+  }
+  if ($script:DoctorDocker) { Test-DoctorServices }
+}
+
+# --- gap update (#1986, #2014) -------------------------------------------------------------------------------------
+# The same command as `gap update` of the bash gap (gap-lib.sh, gap), in the same order: npm channel only, the versions compared
+# as numbers, no step back, the new images pulled first, then a checked backup, then the new compose file and version, then the
+# stack. Nothing is rolled back and nothing is deleted.
+# What is not the same, on purpose:
+#  - Windows PowerShell 5.1 turns what a native command writes into text, which would corrupt a dump or a tar archive. So the
+#    backup never uses a PowerShell pipeline, `>` or Out-File for docker's output: .NET starts docker, and copies its output
+#    stream byte for byte into the file (gzip by .NET for the dump; tar gzips inside the container). The checks of the backup
+#    are .NET too.
+#  - the commands that go back to the old version are written for PowerShell (Copy-Item, docker cp, a bind mount), because
+#    `gunzip -c file | docker ...` and `cat file | docker ...` of the bash text are pipelines of a binary file.
+#  - the backup folder is not chmod-ed: on Windows it inherits the permissions of the user's folder (~\.gap is under it).
+# NOT RUN on Windows or on Windows PowerShell 5.1: what rests on them is the lookup of docker.exe by Process.Start, the free
+# space of a drive (DriveInfo), and the way `C:\...` paths are given to `docker cp` and `-v`. The rest was run with pwsh 7 on
+# Linux against a fake docker (test_installer_update_powershell.py) and against a real Docker.
+
+$script:BackupDir = ''
+$script:PgDumpEnd = '-- PostgreSQL database cluster dump complete'
+$script:BackupSpaceMarginPercent = 5
+
+# Get-DcArgs: the start of every `docker compose` call of the backup (the same project, folder, files as Invoke-Dc), as an
+# array of arguments for Invoke-DockerStream; a path with a space is quoted.
+function Get-DcArgs {
+  @('compose', '-p', $GapProject,
+    '--project-directory', (Format-Arg $GapHome),
+    '-f', (Format-Arg (Join-Path $GapHome 'docker-compose.yml')),
+    '--env-file', (Format-Arg (Get-EnvPath)))
+}
+
+# Invoke-DockerStream ARGS STREAM: run docker with the arguments, standard input closed (what `-T </dev/null` does in bash),
+# and copy its standard output byte for byte into STREAM. Returns an object with ExitCode and Error (what it wrote to standard
+# error, as text). Never throws: a docker that cannot be started is ExitCode 127 and says why.
+function Invoke-DockerStream($dockerArgs, $outStream) {
+  $proc = $null
+  try {
+    $psi = New-Object Diagnostics.ProcessStartInfo
+    $psi.FileName = 'docker'
+    $psi.Arguments = (@($dockerArgs) -join ' ')
+    $psi.UseShellExecute = $false
+    $psi.CreateNoWindow = $true
+    $psi.RedirectStandardInput = $true
+    $psi.RedirectStandardOutput = $true
+    $psi.RedirectStandardError = $true
+    $proc = [Diagnostics.Process]::Start($psi)
+    $proc.StandardInput.Close()
+    $errTask = $proc.StandardError.ReadToEndAsync()   # read at the same time: a full error pipe would stop docker
+    $proc.StandardOutput.BaseStream.CopyTo($outStream)
+    $proc.WaitForExit()
+    return [pscustomobject]@{ ExitCode = $proc.ExitCode; Error = $errTask.Result }
+  } catch {
+    return [pscustomobject]@{ ExitCode = 127; Error = "$($_.Exception.Message)" }
+  } finally {
+    if ($proc) { $proc.Dispose() }
+  }
+}
+
+# Get-DockerText ARGS: the standard output of docker as text, or $null when it did not exit 0.
+function Get-DockerText($dockerArgs) {
+  $mem = New-Object IO.MemoryStream
+  try {
+    $result = Invoke-DockerStream $dockerArgs $mem
+    if ($result.ExitCode -ne 0) { return $null }
+    return [Text.Encoding]::UTF8.GetString($mem.ToArray())
+  } finally {
+    $mem.Dispose()
+  }
+}
+
+# Get-LineKb TEXT WHICH: the number in front of the first (First) or last (Last) line of `du -sk`, or $null.
+function Get-LineKb($text, $which) {
+  if ($null -eq $text) { return $null }
+  $lines = @("$text" -split "`r?`n" | Where-Object { $_ -match '^[0-9]+\b' })
+  if ($lines.Count -eq 0) { return $null }
+  $line = if ($which -eq 'First') { $lines[0] } else { $lines[$lines.Count - 1] }
+  return [int64](($line -split '\s+')[0])
+}
+
+# Get-FreeKb PATH: kilobytes free on the drive that holds PATH, or $null when that cannot be read.
+function Get-FreeKb($path) {
+  try {
+    $name = if ($OnWindows) { [IO.Path]::GetPathRoot($path) } else { $path }
+    $drive = New-Object IO.DriveInfo($name)
+    return [int64]($drive.AvailableFreeSpace / 1024)
+  } catch {
+    return $null
+  }
+}
+
+# Read-GzipEnds FILE KEEP: decompress the whole file and return its first 512 bytes (Head), its last KEEP bytes (Tail) and its
+# decompressed length (Length); $null when it is not a readable gzip. Reading all of it is what checks the gzip (its CRC).
+function Read-GzipEnds($file, $keep) {
+  $fs = $null
+  $gz = $null
+  try {
+    $fs = [IO.File]::OpenRead($file)
+    $gz = New-Object IO.Compression.GZipStream($fs, [IO.Compression.CompressionMode]::Decompress)
+    $buffer = New-Object byte[] 1048576
+    $head = New-Object byte[] 512
+    $headLen = 0
+    $tail = New-Object byte[] 0
+    $total = [int64]0
+    while ($true) {
+      $n = $gz.Read($buffer, 0, $buffer.Length)
+      if ($n -le 0) { break }
+      if ($headLen -lt 512) {
+        $take = [Math]::Min(512 - $headLen, $n)
+        [Array]::Copy($buffer, 0, $head, $headLen, $take)
+        $headLen += $take
+      }
+      $total += $n
+      $all = New-Object byte[] ($tail.Length + $n)
+      [Array]::Copy($tail, 0, $all, 0, $tail.Length)
+      [Array]::Copy($buffer, 0, $all, $tail.Length, $n)
+      if ($all.Length -gt $keep) {
+        $tail = New-Object byte[] $keep
+        [Array]::Copy($all, $all.Length - $keep, $tail, 0, $keep)
+      } else {
+        $tail = $all
+      }
+    }
+    return [pscustomobject]@{ Head = $head; Tail = $tail; Length = $total }
+  } catch {
+    return $null
+  } finally {
+    if ($gz) { $gz.Dispose() }
+    if ($fs) { $fs.Dispose() }
+  }
+}
+
+# Test-DumpWhole FILE: a readable gzip whose text ends with the line pg_dumpall writes last. An empty or cut dump fails here.
+function Test-DumpWhole($file) {
+  $ends = Read-GzipEnds $file 4096
+  if (-not $ends -or $ends.Length -eq 0) { return $false }
+  $lines = @([Text.Encoding]::UTF8.GetString($ends.Tail) -split "`n" | Select-Object -Last 6)
+  foreach ($line in $lines) {
+    if ($line.TrimEnd("`r") -ceq $script:PgDumpEnd) { return $true }
+  }
+  return $false
+}
+
+# Test-ArchiveWhole FILE: a readable gzip that holds a whole tar archive: a first header with a name and a checksum that is
+# right, a length of whole 512-byte blocks, and the two empty blocks that end every archive. A gzip of something else, or of
+# half an archive, fails here (the exit status of tar alone proves nothing: GNU tar says nothing about a gzip that is no tar).
+# A real backup of the app files has at least the entry "./", even when the volume is empty.
+function Test-ArchiveWhole($file) {
+  $ends = Read-GzipEnds $file 1024
+  if (-not $ends -or $ends.Length -lt 1536 -or ($ends.Length % 512) -ne 0) { return $false }
+  foreach ($b in $ends.Tail) { if ($b -ne 0) { return $false } }
+  $head = $ends.Head
+  if ($head[0] -eq 0) { return $false }
+  $field = [Text.Encoding]::ASCII.GetString($head, 148, 8).Trim([char]0, ' ')
+  try { $stored = [Convert]::ToInt64($field, 8) } catch { return $false }
+  $sum = [int64]0
+  for ($i = 0; $i -lt 512; $i++) {
+    if ($i -ge 148 -and $i -lt 156) { $sum += 32 } else { $sum += $head[$i] }
+  }
+  return ($sum -eq $stored)
+}
+
+# Stop-Backup MESSAGE LINES: say what is wrong, remove what this backup wrote, return $false.
+function Stop-Backup($message, $lines = @()) {
+  Write-Warn $message
+  foreach ($line in @($lines)) { if ($line) { Write-Host $line } }
+  if ($script:BackupDir -and (Test-Path -LiteralPath $script:BackupDir)) {
+    Remove-Item -LiteralPath $script:BackupDir -Recurse -Force -ErrorAction SilentlyContinue
+  }
+  $script:BackupDir = ''
+  Write-Host 'Nothing was changed in GAP: the version, .env and your data are as they were.'
+  return $false
+}
+
+function Get-LastLines($text, $count) {
+  (@("$text" -split "`r?`n" | Where-Object { $_ } | Select-Object -Last $count)) -join "`n"
+}
+
+# New-GapBackup: sets $script:BackupDir (<GapHome>\backups\<UTC time>) and returns $true, or returns $false after saying why and
+# leaving nothing behind. Starts only Postgres if it is not running (the dump goes through it); the Kernel is not needed, the
+# app files are read with a throw-away container of the old Kernel image.
+# Room: the backup is at most as big as what is on disk (gzip of a dump, tar of files that are often zips already), so the free
+# space of the backup folder has to cover the size of the database plus the size of gap_data, plus
+# $script:BackupSpaceMarginPercent for tar and gzip overhead. A size that cannot be measured is said and does not stop the
+# backup, which is checked when it is done.
+function New-GapBackup {
+  $root = Join-Path $GapHome 'backups'
+  if ((Get-SvcState 'postgres') -ne 'Healthy') {
+    Write-Host 'Starting the database for the backup...'
+    Invoke-Dc up -d --wait --wait-timeout 120 postgres *> $null
+    if ($LASTEXITCODE -ne 0) {
+      return (Stop-Backup 'The database did not start, so it cannot be backed up' @('Run: gap logs postgres'))
+    }
+  }
+  if (-not (Test-Path -LiteralPath $root)) {
+    try { $null = New-Item -ItemType Directory -Path $root -ErrorAction Stop } catch {
+      return (Stop-Backup "Cannot create $root" @("Check the permissions of $GapHome."))
+    }
+  }
+  $pgKb = Get-LineKb (Get-DockerText ((Get-DcArgs) + @('exec', '-T', 'postgres', 'du', '-sk', '/var/lib/postgresql/data'))) 'First'
+  $dataKb = Get-LineKb (Get-DockerText ((Get-DcArgs) + @('run', '--rm', '--no-deps', '-T', '--entrypoint', 'du', 'kernel', '-sk', '/data'))) 'Last'
+  $freeKb = Get-FreeKb $root
+  if ($null -ne $pgKb -and $null -ne $dataKb -and $null -ne $freeKb) {
+    $needKb = [int64](($pgKb + $dataKb) * (100 + $script:BackupSpaceMarginPercent) / 100)
+    if ($freeKb -lt $needKb) {
+      $needMb = [int64][Math]::Floor(($needKb + 1023) / 1024)
+      $freeMb = [int64][Math]::Floor($freeKb / 1024)
+      return (Stop-Backup 'Not enough free space for the backup' @(
+        "About $needMb MB are needed (the database and the app files), $freeMb MB are free in $root.",
+        'Free some space, then run: gap update'))
+    }
+  } else {
+    Write-Host '[?] The free space needed for the backup could not be measured; the backup is checked when it is done'
+  }
+  # Written under a ".partial" name and renamed only when everything has been checked: a Ctrl-C or a crash must not leave a
+  # half written folder that looks like a backup.
+  $stamp = (Get-Date).ToUniversalTime().ToString("yyyyMMdd'T'HHmmss'Z'", [Globalization.CultureInfo]::InvariantCulture)
+  $final = Join-Path $root $stamp
+  $dir = "$final.partial"
+  try { $null = New-Item -ItemType Directory -Path $dir -ErrorAction Stop } catch {
+    return (Stop-Backup "Cannot create $dir")
+  }
+  $script:BackupDir = $dir
+
+  Write-Host 'Backing up the database...'
+  $dumpFile = Join-Path $dir 'db.sql.gz'
+  $result = $null
+  $fs = [IO.File]::Create($dumpFile)
+  try {
+    $gz = New-Object IO.Compression.GZipStream($fs, [IO.Compression.CompressionMode]::Compress)
+    try { $result = Invoke-DockerStream ((Get-DcArgs) + @('exec', '-T', 'postgres', 'pg_dumpall', '-U', 'postgres')) $gz }
+    finally { $gz.Dispose() }
+  } finally {
+    $fs.Dispose()
+  }
+  if ($result.ExitCode -ne 0) {
+    return (Stop-Backup 'The backup of the database failed' @((Get-LastLines $result.Error 3)))
+  }
+  if (-not (Test-DumpWhole $dumpFile)) { return (Stop-Backup 'The backup of the database is empty or cut short') }
+
+  Write-Host "Backing up the app files (volume ${GapProject}_data)..."
+  $dataFile = Join-Path $dir 'data.tar.gz'
+  $fs = [IO.File]::Create($dataFile)
+  try {
+    $result = Invoke-DockerStream ((Get-DcArgs) + @('run', '--rm', '--no-deps', '-T', '--entrypoint', 'tar', 'kernel', '-czf', '-', '-C', '/data', '.')) $fs
+  } finally {
+    $fs.Dispose()
+  }
+  if ($result.ExitCode -ne 0) {
+    # tar says 1 when a file changed while it was read: the Kernel was writing. Nothing is wrong with the data.
+    return (Stop-Backup 'The backup of the app files failed' @((Get-LastLines $result.Error 3), 'If GAP was busy, run: gap stop   and then: gap update'))
+  }
+  if (-not (Test-ArchiveWhole $dataFile)) { return (Stop-Backup 'The backup of the app files is empty or unreadable') }
+
+  try {
+    [IO.File]::Copy((Get-EnvPath), (Join-Path $dir '.env'), $true)
+    [IO.File]::Copy((Join-Path $GapHome 'docker-compose.yml'), (Join-Path $dir 'docker-compose.yml'), $true)
+  } catch {
+    return (Stop-Backup 'Could not copy .env and the compose file into the backup')
+  }
+  try { [IO.Directory]::Move($dir, $final) } catch {
+    return (Stop-Backup "Could not finish the backup folder $final")
+  }
+  $script:BackupDir = $final
+  return $true
+}
+
+# Copy-FileReplacing SRC DEST: replace DEST in one step, so that nothing reads half a file. Throws when it cannot.
+function Copy-FileReplacing($src, $dest) {
+  $temp = "$dest.new"
+  [IO.File]::Copy($src, $temp, $true)
+  # [NullString]::Value, not $null: PowerShell hands a $null to a .NET string parameter as an empty string, which Replace refuses
+  if (Test-Path -LiteralPath $dest) { [IO.File]::Replace($temp, $dest, [NullString]::Value) } else { [IO.File]::Move($temp, $dest) }
+}
+
+# Test-GapHealth [TRIES] [PAUSE]: the Admin UI answers on /health, /system/health and / (the path the user will take), for up
+# to TRIES x PAUSE seconds each (15 x 2: about 30 seconds). Returns $false after saying which one did not. (install.ps1 does
+# the same inline; this is `gap update`'s.)
+function Test-GapHealth($tries = 15, $pause = 2) {
+  foreach ($path in '/health', '/system/health', '/') {
+    $n = 0
+    while (-not (Test-HttpOk $path)) {
+      $n++
+      if ($n -ge $tries) {
+        Write-Warn "Health check failed: $(Get-UiUrl)$path"
+        Write-Host 'Run: gap logs kernel'
+        return $false
+      }
+      Start-Sleep -Seconds $pause
+    }
+  }
+  return $true
+}
+
+# Write-FilesBackHelp BACKUP: the two lines that put the old .env and compose file back (the first two of the restore).
+function Write-FilesBackHelp($backup) {
+  Write-Host ('  Copy-Item "{0}" "{1}"' -f (Join-Path $backup '.env'), (Get-EnvPath))
+  Write-Host ('  Copy-Item "{0}" "{1}"' -f (Join-Path $backup 'docker-compose.yml'), (Join-Path $GapHome 'docker-compose.yml'))
+}
+
+# Write-RestoreHelp BACKUP OLDVERSION: how to go back to OLDVERSION with the data of the backup. The same order as the bash text
+# (spike S4 ran it for real): no ON_ERROR_STOP (psql would stop on the one error that is expected), restore only into an empty
+# database volume with only Postgres running (a restore over data doubles the rows of tables without a primary key), and the
+# password after the restore is the one of the backup, which is the one in the backup's .env. In PowerShell: the dump goes into
+# the container with `docker cp` and is unzipped there (no pipe of a binary file), and the app files are read from the backup
+# folder, mounted into a throw-away Kernel container. Nothing is run; the paths are written in full and quoted.
+function Write-RestoreHelp($backup, $oldVersion) {
+  $dcx = 'docker compose -p {0} --project-directory "{1}" -f "{2}" --env-file "{3}"' -f $GapProject, $GapHome, (Join-Path $GapHome 'docker-compose.yml'), (Get-EnvPath)
+  Write-Host ''
+  Write-Host "To go back to GAP $oldVersion with the data of the backup (this erases the current database and app files first, because"
+  Write-Host 'the new version may already have changed them; a restore over existing data would duplicate rows). In PowerShell:'
+  Write-FilesBackHelp $backup
+  Write-Host "  $dcx down -v"
+  Write-Host "  $dcx up -d --wait postgres"
+  Write-Host "  `$pg = $dcx ps -q postgres"
+  Write-Host ('  docker cp "{0}" "${{pg}}:/tmp/db.sql.gz"' -f (Join-Path $backup 'db.sql.gz'))
+  Write-Host "  $dcx exec -T postgres sh -c `"gunzip -c /tmp/db.sql.gz | psql -U postgres -q`""
+  Write-Host ('  {0} run --rm --no-deps -T -v "{1}:/backup:ro" --entrypoint tar kernel -xzf /backup/data.tar.gz -C /data' -f $dcx, $backup)
+  Write-Host '  gap start'
+  Write-Host "Do not add psql's ON_ERROR_STOP: the restore prints exactly one error, role `"postgres`" already exists, and that is"
+  Write-Host "expected (and a few small set_config tables, which are normal). The images of $oldVersion are still on this machine."
+}
+
+# Write-UpdateFailed OLD NEW BACKUP: the new version did not come up. Nothing is rolled back (the Kernel may already have
+# migrated the database, and a migration is not undone): say where the backup is, what .env says now, and how to go back.
+function Write-UpdateFailed($old, $new, $backup) {
+  Write-Warn "The update to GAP $new did not finish, and GAP $old was not restored automatically"
+  Write-Host "    The backup made before the update: $backup"
+  Write-Host "    .env now says GAP_VERSION=$(Get-EnvValue 'GAP_VERSION'). Nothing was rolled back and nothing was deleted."
+  Write-Host '    First look at what the new version says: gap logs kernel'
+  Write-RestoreHelp $backup $old
+}
+
+# Write-UpdateNotApplied OLD NEW BACKUP [REASON]: the new .env or compose file could not be written. The stack was not touched (the old
+# version still runs as before); .env and the compose file may be half moved, and the backup holds the old ones.
+function Write-UpdateNotApplied($old, $new, $backup, $reason = '') {
+  Write-Warn "The update to GAP $new could not be applied: the files in $GapHome could not be written"
+  if ($reason) { Write-Host "    $reason" }
+  Write-Host "    The running stack was not touched; GAP $old runs as before. The backup made before: $backup"
+  Write-Host "    .env now says GAP_VERSION=$(Get-EnvValue 'GAP_VERSION'). To put the old .env and compose file back:"
+  Write-FilesBackHelp $backup
+  Write-Host "    Check the permissions of $GapHome, then run: gap update"
+}