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

package/installer/gap.ps1

@@ -0,0 +1,361 @@
+# gap: status / start / stop / logs / uninstall / version / doctor (and update, npm channel) for the local GAP stack (#1750, D27, D28).
+# install.ps1 copies this file to ~\.gap and puts a launcher (gap.cmd) for it on the PATH, so
+# `gap status` works in any terminal. It always works on the instance in ~\.gap ($GapHome, from
+# gap-lib.ps1), also when run from the unzipped installer folder. Reads its arguments from $args
+# (no param block) so that `gap logs kernel -f` reaches docker untouched.
+$GapSource = $PSScriptRoot
+. (Join-Path $GapSource 'gap-lib.ps1')
+
+function Show-Usage {
+  # `install` is a command of the npm package only: the ZIP's gap has none, its installer is install.cmd / install.ps1.
+  $lines = @('Usage: gap <command>', '')
+  if ((Get-Channel) -eq 'npm') {
+    $lines += '  install         install GAP on this machine (pulls the images; run it again any time)'
+    $lines += '  login           log in to the registry that holds the images (asks for your GitHub username and token)'
+    $lines += '  update          move GAP to the version of the installed npm package, after a backup'
+  }
+  $lines += '  status          show whether GAP is running and healthy'
+  $lines += '  version         show the installed GAP version'
+  $lines += '  doctor          check this machine and the install for problems; changes nothing'
+  $lines += '  start           start GAP again (after `gap stop` or a reboot)'
+  $lines += '  stop            stop GAP; your data is kept'
+  $lines += '  logs [service] [-f]'
+  $lines += '                  show logs (service: kernel, postgres or admin-ui)'
+  $lines += '  uninstall [--purge] [--yes]'
+  $lines += '                  remove GAP from this machine; your data is kept'
+  $lines += '                  unless you add --purge (it asks you to type "delete")'
+  $lines
+}
+
+function Assert-Installed {
+  if (Test-Path -LiteralPath (Get-EnvPath)) { return }
+  Write-Warn "GAP is not installed in $GapHome"
+  if ((Get-Channel) -eq 'npm') {
+    Write-Host 'Run: gap install'
+  } elseif (Test-Path -LiteralPath (Join-Path $GapSource 'install.ps1')) {
+    Write-Host "Run: powershell -ExecutionPolicy Bypass -File `"$(Join-Path $GapSource 'install.ps1')`""
+  } else {
+    Write-Host 'Run install.ps1 from the GAP installer folder.'
+  }
+  exit 1
+}
+
+function Invoke-Status {
+  if (-not (Test-Prereqs 'gap status')) { exit 1 }
+  $pg = Get-SvcState 'postgres'
+  $kernel = Get-SvcState 'kernel'
+  $ui = Get-SvcState 'admin-ui'
+  # D19: the Runtime lives inside the Kernel; /system/health answering 200 proves the database
+  # session and the app manager are up. The `status` field is not read: it says "error" on a
+  # fresh install that has no app worker yet.
+  if ($kernel -eq 'Healthy' -and $ui -eq 'Healthy' -and (Test-HttpOk '/system/health')) { $runtime = 'Healthy' }
+  elseif ($kernel -eq 'Stopped') { $runtime = 'Stopped' }
+  else { $runtime = 'Unreachable' }
+  $overall = 'READY'
+  foreach ($state in $pg, $kernel, $runtime, $ui) {
+    if ($state -ne 'Healthy') { $overall = 'NOT READY' }
+  }
+  Write-Host ('{0,-15} {1}' -f 'PostgreSQL', $pg)
+  Write-Host ('{0,-15} {1}' -f 'GAP Kernel', $kernel)
+  Write-Host ('{0,-15} {1}' -f 'GAP Runtime', $runtime)
+  Write-Host ('{0,-15} {1}' -f 'GAP Admin UI', $ui)
+  Write-Host "Version: $(Get-EnvValue 'GAP_VERSION')"
+  Write-NewerPackageNote
+  if ($overall -eq 'READY') { Write-Host "URL: $(Get-UiUrl)" }
+  Write-Host "Overall: $overall"
+  if ($overall -ne 'READY') { exit 1 }
+}
+
+# version and doctor work before GAP is installed: doctor is what to run when the install did not work.
+function Invoke-Version {
+  $installed = Get-InstalledVersion
+  $pkg = Get-CliVersion
+  $shown = if ($installed) { $installed } else { 'not installed' }
+  Write-Host "Installed:    $shown"
+  if ($pkg) { Write-Host "CLI package:  $pkg" }
+  if ($pkg -and $installed -and $installed -ne 'unknown' -and $installed -ne $pkg) {
+    if (Test-PackageNewer) { Write-Host 'The installed version differs from this package. Run: gap update' }
+    elseif (Test-PackageOlder) { Write-Host 'The installed version is newer than this package. Install the newer package: npm install -g @atomiton-dev/gap-cli@latest' }
+    else { Write-Host 'The installed version differs from this package. Run: gap install' }
+  }
+}
+
+# Test-Doctor* are in gap-lib.ps1. Exits 0 when no check found a problem, 1 otherwise.
+function Invoke-Doctor {
+  $script:DoctorProblems = 0
+  Test-DoctorDocker
+  Test-DoctorNode
+  Test-DoctorPorts
+  Test-DoctorGapCommand
+  Test-DoctorRegistry
+  Test-DoctorInstall
+  if ($script:DoctorProblems -eq 0) { Write-Host 'Overall: OK' }
+  elseif ($script:DoctorProblems -eq 1) { Write-Host 'Overall: 1 problem' }
+  else { Write-Host "Overall: $($script:DoctorProblems) problems" }
+  if ($script:DoctorProblems -ne 0) { exit 1 }
+}
+
+function Invoke-Start {
+  if (-not (Test-Prereqs 'gap start' $true)) { exit 1 }
+  $stored = Get-EnvValue 'GAP_UI_PORT'
+  $port = Select-Port $stored
+  if (-not $port) {
+    Write-Warn 'No free port for the Admin UI'
+    Write-Host "Action: free a port between $GapPortFirst and $GapPortLast"
+    exit 1
+  }
+  if ("$port" -ne $stored) {
+    Write-Warn "Port $stored is in use, using $port instead"
+    Set-EnvValue 'GAP_UI_PORT' $port
+  }
+  if (-not (Start-GapStack)) { exit 1 }
+  Write-Ok 'GAP is running'
+  Write-Host "Admin UI: $(Get-UiUrl)"
+  Write-NewerPackageNote
+  Open-Url (Get-UiUrl)
+}
+
+function Invoke-Stop {
+  if (-not (Test-Prereqs 'gap stop')) { exit 1 }
+  Invoke-Dc stop
+  if ($LASTEXITCODE -ne 0) { exit 1 }
+  Write-Host 'GAP stopped. Your data is kept. Run: gap start'
+}
+
+function Invoke-Logs($logArgs) {
+  if (-not (Test-Prereqs 'gap logs')) { exit 1 }
+  Invoke-Dc logs @logArgs
+  exit $LASTEXITCODE
+}
+
+# Remove-LauncherFromPath: take ~\.gap\bin out of the user PATH again. Returns $true when it was there.
+function Remove-LauncherFromPath {
+  if (-not $OnWindows) { return $false }
+  $entries = @((Get-UserPathRaw) -split ';' | Where-Object { $_ })
+  $kept = @($entries | Where-Object { -not (Test-LauncherEntry $_) })
+  if ($kept.Count -eq $entries.Count) { return $false }
+  Set-UserPathRaw ($kept -join ';')
+  return $true
+}
+
+# D28: stop the stack and remove everything the installer put on this machine. Without --purge the
+# Docker volumes (gap_pgdata, gap_data) stay, and a later install finds and reuses them. With
+# --purge the volumes and this version's GAP images go too (gap-kernel, gap-admin-ui and gap-postgres:16,
+# under the names the install gave them: the registry prefix of .env, empty for a ZIP; the user's own
+# postgres:16, if any, is a different name and is never touched). Nothing is removed until the stack has
+# been taken down. Public since #1986 (#2015): it was hidden in #1750 (Scott, 21/10) and is now in Show-Usage
+# and the READMEs. It removes ~\.gap, the launcher and the PATH entry the installer added, and nothing else: the
+# extracted installer folder (ZIP) and the package folder (npm) are never touched, and `npm uninstall -g` is the
+# user's separate, later step.
+function Invoke-Uninstall($uninstallArgs) {
+  $purge = $false
+  $yes = $false
+  foreach ($arg in $uninstallArgs) {
+    switch ("$arg") {
+      '--purge' { $purge = $true }
+      '--yes'   { $yes = $true }
+      default   { [Console]::Error.WriteLine((Show-Usage | Out-String).TrimEnd()); exit 2 }
+    }
+  }
+  if (-not (Test-Prereqs 'gap uninstall')) { exit 1 }
+  $version = Get-EnvValue 'GAP_VERSION'
+  if ($purge -and -not $yes) {
+    if ([Console]::IsInputRedirected) {
+      Write-Warn '--purge erases all GAP data; run it in a terminal, or add --yes to confirm'
+      exit 1
+    }
+    $answer = Read-Host 'This erases ALL GAP data (database and files) and the GAP images. Type "delete" to continue'
+    if ($answer -ne 'delete') { Write-Host 'Cancelled. Nothing was changed.'; exit 1 }
+  }
+  if ($purge) { Invoke-Dc down -v } else { Invoke-Dc down }
+  if ($LASTEXITCODE -ne 0) { exit 1 }
+  if ($purge) {
+    $prefix = Get-InstalledPrefix
+    & docker rmi (Get-ImageRef $prefix 'gap-kernel' $version) (Get-ImageRef $prefix 'gap-admin-ui' $version) `
+      (Get-ImageRef $prefix 'gap-postgres' '16') *> $null
+  }
+  $pathRemoved = Remove-LauncherFromPath
+  # The running chain is gap.cmd (cmd.exe re-reads a batch file after each command, so deleting it
+  # now would end in "The batch file cannot be found") -> gap.ps1. Everything else goes now; the
+  # folder that still holds gap.cmd is removed by a separate cmd.exe a moment after this one exits.
+  # Anything that is still locked now is caught by that second pass.
+  if ($OnWindows) {
+    Get-ChildItem -LiteralPath $GapHome -Force | Where-Object { $_.Name -ne 'bin' } |
+      Remove-Item -Recurse -Force -ErrorAction SilentlyContinue
+    Start-Process -FilePath 'cmd.exe' -WindowStyle Hidden `
+      -ArgumentList '/c', "ping -n 3 127.0.0.1 >nul & rmdir /s /q `"$GapHome`""
+  } else {
+    Remove-Item -LiteralPath $GapHome -Recurse -Force
+  }
+  Write-Ok 'GAP removed'
+  if ($pathRemoved) { Write-Host "Removed $LauncherDir from your user PATH." }
+  if ($purge) {
+    Write-Host 'All GAP data was erased.'
+  } else {
+    Write-Host "Your data is kept in the Docker volumes ${GapProject}_pgdata and ${GapProject}_data; installing again brings it back."
+    Write-Host 'To erase it for good, install again and run: gap uninstall --purge'
+  }
+}
+
+# `gap login` (#1986): npm channel only (the ZIP carries its images). The same flow as the bash one (see cmd_login in gap): it asks
+# for a GitHub username and a token, hands the token to `docker login --password-stdin` (on stdin, so it is in no argument list and
+# no log), and then reads the three images the way `gap doctor` does. Needs a terminal. NOT run on Windows PowerShell 5.1 yet.
+function Invoke-Login {
+  if ((Get-Channel) -ne 'npm') {
+    Write-Warn 'The ZIP has no `gap login`'
+    Write-Host 'Its images are inside the ZIP, so there is no registry to log in to.'
+    exit 1
+  }
+  $registryHost = (Get-ChannelPrefix).Split('/')[0]
+  if ([Console]::IsInputRedirected) {
+    Write-Warn 'gap login asks for your GitHub username and token, so it needs a terminal'
+    Write-Host 'Without one, log in with Docker and pipe the token into it:'
+    Write-Host "  docker login $registryHost -u <your GitHub username> --password-stdin"
+    exit 1
+  }
+  if (-not (Test-Prereqs 'gap login')) { exit 1 }
+  Write-Host "GAP's images are in $registryHost, a private registry. You need a GitHub personal access token (classic)"
+  Write-Host 'with the read:packages permission. Create one here if you have none:'
+  Write-Host '  https://github.com/settings/tokens/new?scopes=read:packages'
+  Write-Host ''
+  # Trim() drops the blanks a paste brings at either end, as `read` does in the bash version (nothing is removed inside the text).
+  $user = "$(Read-Host 'GitHub username')".Trim()
+  if (-not $user) { Write-Warn 'No username was given'; exit 1 }
+  $secure = Read-Host 'Token (hidden as you type)' -AsSecureString
+  $token = ''
+  $bstr = [IntPtr]::Zero
+  try {
+    $bstr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure)
+    $token = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($bstr).Trim()
+  } finally {
+    if ($bstr -ne [IntPtr]::Zero) { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr) }
+  }
+  if (-not $token) { Write-Warn 'No token was given'; exit 1 }
+  $out = $token | & docker login $registryHost -u $user --password-stdin 2>&1
+  $rc = $LASTEXITCODE
+  # Docker does not print the password; if a text ever carried it, it would not reach the screen.
+  $text = (@($out | ForEach-Object { "$_" }) -join "`n").Replace($token, '***')
+  $token = ''
+  if ($rc -ne 0) {
+    switch (Get-LoginErrorKind $text) {
+      'rejected' {
+        # ghcr.io ignores the username of a valid token (measured: a made-up name logs in), so only the token is blamed.
+        Write-Warn "$registryHost did not accept that token"
+        Write-Host '    - Paste the personal access token (classic) itself, not your GitHub password.'
+        Write-Host '    - It needs the read:packages permission and must not be expired or revoked.'
+        Write-Host '    Nothing was changed. Run gap login to try again.'
+      }
+      'network' {
+        Write-Warn "Could not reach $registryHost"
+        Write-Host '    Check your internet connection (and proxy settings), then run gap login again.'
+      }
+      default {
+        Write-Warn 'docker login failed'
+        @($text -split "`r?`n" | Where-Object { $_ }) | Select-Object -Last 3 | ForEach-Object { Write-Host "    $_" }
+      }
+    }
+    exit 1
+  }
+  Write-Ok "Logged in to $registryHost as $user"
+  # What Docker said besides "Login Succeeded" is worth reading (it warns when the credential is kept unencrypted).
+  @($text -split "`r?`n" | Where-Object { $_ -and $_ -ne 'Login Succeeded' }) | ForEach-Object { Write-Host "    $_" }
+  $script:LoginJustDone = $true
+  $script:DoctorProblems = 0
+  $script:DoctorDocker = $true
+  Test-DoctorRegistry
+  if ($script:DoctorProblems -gt 0) { exit 1 }
+  # Exit 0 means logged in AND able to read the images. When the check could not be made neither is claimed: it is said, the
+  # status is 1, and no "Next:" is offered.
+  if (-not $script:RegistryReadable) {
+    Write-Host 'Logged in, but whether your account can read the images could not be checked. Run gap doctor when that is possible.'
+    exit 1
+  }
+  if (-not (Test-Installed)) { Write-Host 'Next: gap install' }
+}
+
+# `gap update` (#1986, #2014): the same command as the bash gap's cmd_update, in the same order (see "gap update" in gap-lib.ps1):
+# 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. If the new version does not
+# come up it says where the backup is and how to go back to the old version with its data (Write-UpdateFailed).
+function Invoke-Update {
+  if ((Get-Channel) -ne 'npm') {
+    Write-Warn 'The ZIP has no `gap update`'
+    Write-Host 'To update: unzip the new installer and run its install.ps1. It keeps your data and your secrets.'
+    exit 1
+  }
+  Assert-Installed
+  $installed = Get-InstalledVersion
+  $pkg = Get-CliVersion
+  if (-not $pkg) {
+    Write-Warn 'This package has no VERSION file, so it cannot tell which version it brings'
+    exit 1
+  }
+  $cmp = Compare-GapVersion $installed $pkg
+  if ($null -eq $cmp) {
+    Write-Warn "Cannot compare the installed version ($installed) with the version of this package ($pkg)"
+    Write-Host '    gap update only moves between versions it can compare (major.minor.patch, with the same -suffix).'
+    Write-Host '    Nothing was changed.'
+    exit 1
+  }
+  if ($cmp -eq 0) {
+    Write-Host "GAP $installed is already the version of this package. Nothing to do."
+    return
+  }
+  if ($cmp -eq 1) {
+    Write-Warn "This package ($pkg) is older than the installed GAP ($installed)"
+    Write-OlderPackageHelp
+    Write-Host '    Nothing was changed.'
+    exit 1
+  }
+  Write-Host "Updating GAP $installed -> $pkg"
+  Write-Host ''
+  if (-not (Test-Prereqs 'gap update' $true)) { exit 1 }
+  if (-not (Invoke-PullImages $pkg 'gap update')) { exit 1 }   # has said what to do; the old stack is untouched
+  Write-Ok 'Images ready'
+  if (-not (New-GapBackup)) { exit 1 }                          # has said what is wrong; nothing was changed
+  $backup = $script:BackupDir
+  Write-Ok "Backup saved in $backup"
+  # The files first: if they cannot be written the running stack has not been touched, and the way back is two Copy-Item lines,
+  # not the restore (which starts with `down -v` and would erase a healthy stack).
+  $written = $true
+  try {
+    Copy-FileReplacing (Join-Path $GapSource 'docker-compose.yml') (Join-Path $GapHome 'docker-compose.yml')
+    Set-EnvValue 'GAP_VERSION' $pkg
+    Set-EnvValue 'GAP_IMAGE_PREFIX' (Get-ChannelPrefix)
+    Set-EnvValue 'GAP_PULL_POLICY' (Get-ChannelPullPolicy)
+  } catch {
+    $written = $false
+    $reason = "$($_.Exception.Message)"
+  }
+  if (-not $written) {
+    Write-UpdateNotApplied $installed $pkg $backup $reason
+    exit 1
+  }
+  if (-not ((Start-GapStack) -and (Test-GapHealth))) {
+    Write-UpdateFailed $installed $pkg $backup
+    exit 1
+  }
+  Write-Host ''
+  Write-Host "GAP updated: $installed -> $pkg"
+  Write-Host "  Backup of GAP ${installed}: $backup"
+  Write-Host '  It is kept; delete it when you no longer need it. Check GAP with: gap status'
+}
+
+$command = ''
+$rest = @()
+if ($args.Count -gt 0) { $command = "$($args[0])" }
+if ($args.Count -gt 1) { $rest = @($args[1..($args.Count - 1)]) }
+
+switch ($command) {
+  'version' { if ($rest.Count -gt 0) { [Console]::Error.WriteLine((Show-Usage | Out-String).TrimEnd()); exit 2 }; Invoke-Version }
+  'doctor' { if ($rest.Count -gt 0) { [Console]::Error.WriteLine((Show-Usage | Out-String).TrimEnd()); exit 2 }; Invoke-Doctor }
+  'update' { if ($rest.Count -gt 0) { [Console]::Error.WriteLine((Show-Usage | Out-String).TrimEnd()); exit 2 }; Invoke-Update }
+  'login' { if ($rest.Count -gt 0) { [Console]::Error.WriteLine((Show-Usage | Out-String).TrimEnd()); exit 2 }; Invoke-Login }
+  'status' { Assert-Installed; Invoke-Status }
+  'start'  { Assert-Installed; Invoke-Start }
+  'stop'   { Assert-Installed; Invoke-Stop }
+  'logs'   { Assert-Installed; Invoke-Logs $rest }
+  'uninstall' { Assert-Installed; Invoke-Uninstall $rest }
+  { $_ -in 'help', '-h', '--help' } { Show-Usage }
+  default  { [Console]::Error.WriteLine((Show-Usage | Out-String).TrimEnd()); exit 2 }
+}

package/installer/install.ps1

@@ -0,0 +1,262 @@
+# Installs the local GAP stack from this folder (Windows). Safe to run again: secrets stay.
+# Folder contents (#1750, D27): docker-compose.yml, env.template, VERSION, images.tar.gz,
+# install.cmd, install.ps1, gap.ps1, gap-lib.ps1, README.TXT, BUILD-INFO.txt.
+#
+# D28: the installed instance lives in ~\.gap (docker-compose.yml, .env, gap.ps1, gap-lib.ps1). This
+# folder is only the installer: after a successful run it can be moved or deleted.
+#
+# #1986 (#2011): the same script is the installer of the npm package `@atomiton-dev/gap-cli` (`gap install`), told
+# apart by the CHANNEL file next to it (gap-lib.ps1: Get-Channel). There the images are pulled from ghcr.io instead of
+# loaded, no launcher and no PATH entry is made (npm put `gap` on the PATH), and only docker-compose.yml is copied
+# into ~\.gap, because this folder is the package that provides `gap` and must stay.
+#
+# Double-click install.cmd, or in a terminal run:
+#   powershell -ExecutionPolicy Bypass -File .\install.ps1
+# (a plain .\install.ps1 is refused by the default execution policy of Windows 10/11, and files
+# from a downloaded zip also carry the "from the Internet" mark)
+$GapSource = $PSScriptRoot
+. (Join-Path $GapSource 'gap-lib.ps1')
+
+function Stop-Install($headline, $details) {
+  Write-Warn $headline
+  foreach ($line in $details) { Write-Host $line }
+  exit 1
+}
+
+# Copy-IntoHome NAME: replace GapHome\NAME in one move, so that a gap.ps1 that is
+# running right now is never half overwritten.
+function Copy-IntoHome($name) {
+  $target = Join-Path $GapHome $name
+  Copy-Item -LiteralPath (Join-Path $GapSource $name) -Destination "$target.new" -Force -ErrorAction Stop
+  Move-Item -LiteralPath "$target.new" -Destination $target -Force -ErrorAction Stop
+}
+
+# Sync-Files: copy what the installed instance needs into GapHome (D28). A newer installer replaces
+# the older compose file and scripts; .env is never touched here.
+function Sync-Files {
+  New-Item -ItemType Directory -Force -Path $GapHome -ErrorAction Stop | Out-Null
+  $src = [IO.Path]::GetFullPath($GapSource).TrimEnd('\')
+  $dst = [IO.Path]::GetFullPath($GapHome).TrimEnd('\')
+  if ($src -ieq $dst) { return }   # running from GapHome itself
+  # npm: `Invoke-Dc` needs the compose file here; the scripts stay in the package.
+  $names = if ((Get-Channel) -eq 'npm') { @('docker-compose.yml') } else { @('docker-compose.yml', 'gap-lib.ps1', 'gap.ps1') }
+  foreach ($name in $names) { Copy-IntoHome $name }
+}
+
+# Reset-DbPassword: set the Postgres password to the one in .env (D28, replaces the stop of D24).
+# Postgres keeps the password it was first started with, so a lost .env would lock the Kernel out of
+# its own data. The official image trusts connections made on the local socket inside the container
+# (pg_hba.conf: `local all all trust`), so the password can be set without knowing the old one.
+# Starts only postgres. The result is checked over the container's own IP, which (unlike 127.0.0.1)
+# is not trusted, so a wrong password fails there. Returns $null on success, else the reason.
+function Reset-DbPassword {
+  $password = Get-EnvValue 'GAP_DB_PASSWORD'
+  $out = Invoke-Dc up -d --wait --wait-timeout 120 postgres 2>&1
+  if ($LASTEXITCODE -ne 0) { return "postgres did not start: $((@($out) | Select-Object -Last 2) -join ' ')" }
+  $id = Invoke-Dc ps -q postgres | Select-Object -First 1
+  if (-not $id) { return 'postgres container not found' }
+  $out = "ALTER USER postgres PASSWORD '$password';" | & docker exec -i $id psql -U postgres -v ON_ERROR_STOP=1 -q 2>&1
+  if ($LASTEXITCODE -ne 0) { return "setting the password failed: $(@($out) -join ' ')" }
+  # No `sh -c "..."` here: Windows PowerShell 5.1 passes an argument with inner double quotes to
+  # docker.exe without escaping them, which split that command into pieces and made this check
+  # always fail. The IP is read first, and every argument below is free of double quotes.
+  $ip = "$(& docker exec $id hostname -i 2>$null)".Trim().Split(' ')[0]
+  if (-not $ip) { return "could not read the postgres container's IP" }
+  $out = & docker exec -e "PGPASSWORD=$password" $id psql -h $ip -U postgres -tAc 'select 1' 2>&1
+  if ($LASTEXITCODE -ne 0) { return "the new password was not accepted: $(@($out) -join ' ')" }
+  return $null
+}
+
+# Makes `gap` runnable from any terminal: gap.cmd in ~\.gap\bin (cmd.exe cannot run a .ps1 by
+# name, and the execution policy would block one anyway), and that folder on the user PATH.
+# Needs no administrator rights. Returns $true when it had to add the folder to the PATH.
+function Install-Launcher {
+  New-Item -ItemType Directory -Force -Path $LauncherDir | Out-Null
+  $cmd = "@echo off`r`npowershell -NoProfile -ExecutionPolicy Bypass -File `"$(Join-Path $GapHome 'gap.ps1')`" %*`r`nexit /b %ERRORLEVEL%`r`n"
+  [IO.File]::WriteAllText((Join-Path $LauncherDir 'gap.cmd'), $cmd, (New-Object Text.UTF8Encoding($false)))
+  if (-not $OnWindows) { return $false }
+  $entries = @((Get-UserPathRaw) -split ';' | Where-Object { $_ })
+  if ($entries | Where-Object { Test-LauncherEntry $_ }) { return $false }
+  Set-UserPathRaw ((@($entries) + $LauncherDir) -join ';')
+  return $true
+}
+
+Write-Host "Installing GAP from $GapSource"
+Write-Host ''
+
+# 1. Prerequisites
+if (-not (Test-Prereqs (Get-InstallCommand) $true)) { exit 1 }
+Write-Ok 'Prerequisites passed'
+
+foreach ($name in 'VERSION', 'docker-compose.yml', 'env.template', 'gap.ps1', 'gap-lib.ps1') {
+  if (-not (Test-Path -LiteralPath (Join-Path $GapSource $name))) {
+    Stop-Install "$name is missing in $GapSource" @('Download the installer again.')
+  }
+}
+$version = ([IO.File]::ReadAllText((Join-Path $GapSource 'VERSION'))).Trim()
+
+# npm channel: never go back (the same guard as install.sh). An older package over a newer GAP would start an old Kernel on a
+# database a newer one has migrated. Only a comparison that can be made refuses; anything else runs as it always did.
+if ((Get-Channel) -eq 'npm' -and (Test-Installed) -and ((Compare-GapVersion (Get-InstalledVersion) $version) -eq 1)) {
+  Write-Warn "This package ($version) is older than the installed GAP ($(Get-InstalledVersion))"
+  Write-OlderPackageHelp
+  Write-Host '    Nothing was changed.'
+  exit 1
+}
+
+# 2. Images. npm channel: pulled from the registry, the missing ones only, before anything is written (the user may
+# not be logged in or allowed, and must then be left with nothing half installed). ZIP channel: from the archive in
+# this folder (no network needed). Postgres is packaged as
+# gap-postgres:16, so loading never moves the user's own postgres:16 tag. The archive is loaded when
+# an image is missing, and also when this package differs from the one loaded last time (its
+# BUILD-INFO.txt is recorded in ~\.gap), so a rebuilt package with the same VERSION still replaces
+# the images. Only missing images make images.tar.gz mandatory.
+$pkgId = ''
+$needLoad = $false
+$loadedFile = Join-Path $GapHome 'images.loaded'
+if ((Get-Channel) -eq 'npm') {
+  if (-not (Invoke-PullImages $version)) { exit 1 }   # has said what to do
+  Write-Ok 'Images ready'
+} else {
+  $buildInfo = Join-Path $GapSource 'BUILD-INFO.txt'
+  if (Test-Path -LiteralPath $buildInfo) { $pkgId = (Get-FileHash -LiteralPath $buildInfo -Algorithm SHA256).Hash }
+  foreach ($image in "gap-kernel:$version", "gap-admin-ui:$version", 'gap-postgres:16') {
+    & docker image inspect $image *> $null
+    if ($LASTEXITCODE -ne 0) { $needLoad = $true }
+  }
+  if (-not $needLoad -and $pkgId -and (Test-Path -LiteralPath (Join-Path $GapSource 'images.tar.gz'))) {
+    $loaded = ''
+    if (Test-Path -LiteralPath $loadedFile) { $loaded = ([IO.File]::ReadAllText($loadedFile)).Trim() }
+    if ($loaded -ne $pkgId) { $needLoad = $true }
+  }
+  if ($needLoad) {
+    $archive = Join-Path $GapSource 'images.tar.gz'
+    if (-not (Test-Path -LiteralPath $archive)) {
+      Stop-Install 'images.tar.gz is missing and the images are not on this machine' @('Download the installer again.')
+    }
+    Write-Host 'Loading images, this can take a minute...'
+    $loadOut = & docker load -i $archive 2>&1
+    if ($LASTEXITCODE -ne 0) { Stop-Install 'Loading images failed' @("$($loadOut -join "`n")") }
+  }
+  Write-Ok 'Images loaded'
+}
+
+# 3. The installed instance (D28)
+try { Sync-Files } catch {
+  Stop-Install "Could not write to $GapHome" @("$($_.Exception.Message)", "Check the permissions of that folder, then run $(Get-InstallName) again.")
+}
+if ($needLoad -and $pkgId) { [IO.File]::WriteAllText($loadedFile, "$pkgId`n") }
+
+# 4. Configuration. First run creates .env with fresh secrets; later runs only update version and
+# port (D23, D9) and keep the password, which Postgres has already stored in its volume.
+& docker volume inspect "${GapProject}_pgdata" *> $null
+$hadVolume = ($LASTEXITCODE -eq 0)
+if (Test-Path -LiteralPath (Get-EnvPath)) {
+  $storedPort = Get-EnvValue 'GAP_UI_PORT'
+  Set-EnvValue 'GAP_VERSION' $version
+} else {
+  $storedPort = ''
+  $bytes = New-Object byte[] 24
+  $rng = [Security.Cryptography.RandomNumberGenerator]::Create()
+  $rng.GetBytes($bytes)
+  $rng.Dispose()
+  $password = ($bytes | ForEach-Object { $_.ToString('x2') }) -join ''
+  $template = [IO.File]::ReadAllText((Join-Path $GapSource 'env.template')).Replace("`r`n", "`n")
+  Write-EnvFile $template.Replace('@GAP_VERSION@', $version).Replace('@GAP_UI_PORT@', '0').Replace('@GAP_DB_PASSWORD@', $password)
+  # D28: data from an earlier install is still in the volume but its password is gone with the old
+  # .env (the install folder was moved or deleted). Set the new password inside Postgres.
+  if ($hadVolume) {
+    $reason = Reset-DbPassword
+    if ($reason) {
+      Remove-Item -LiteralPath (Get-EnvPath) -Force   # back to "no .env", so the next run starts from the same place
+      Stop-Install 'GAP data from an earlier install exists, but its database password could not be reset' @(
+        $reason,
+        "Either: put the old .env back into $GapHome and run $(Get-InstallName) again,",
+        'or: erase the old data (it is lost for good) with',
+        "    docker compose -p $GapProject down -v",
+        "and run $(Get-InstallName) again.")
+    }
+    Write-Ok 'GAP data from an earlier install was found; its lost .env was rebuilt and the data is kept'
+  }
+}
+# Where this channel gets its images from (#1986): the ZIP's own, loaded above under their local names and never
+# pulled (empty prefix, `never`); the npm channel's, pulled above from the registry (its prefix, `missing`). The
+# channel's value, not .env's: written on every run, not only on the first, so that a machine that used another
+# channel (or an older package that did not know these keys) takes this channel's names from now on.
+Set-EnvValue 'GAP_IMAGE_PREFIX' (Get-ChannelPrefix)
+Set-EnvValue 'GAP_PULL_POLICY' (Get-ChannelPullPolicy)
+$port = Select-Port $storedPort
+if (-not $port) {
+  Stop-Install 'No free port for the Admin UI' @("Action: free a port between $GapPortFirst and $GapPortLast, then run $(Get-InstallName) again.")
+}
+if ($storedPort -and "$port" -ne $storedPort) { Write-Warn "Port $storedPort is in use, using $port instead" }
+Set-EnvValue 'GAP_UI_PORT' $port
+
+# 5. Start. Both lines are true once the Kernel is healthy: it depends on a healthy Postgres, and
+# its entrypoint finishes the schema before the server that answers /health starts (D16).
+if (-not (Start-GapStack)) { exit 1 }
+Write-Ok 'Database initialized'
+Write-Ok 'Migrations completed'
+
+# 6. Health checks through the Admin UI port, the path the user will take.
+foreach ($path in '/health', '/system/health', '/') {
+  $tries = 0
+  while (-not (Test-HttpOk $path)) {
+    $tries++
+    if ($tries -ge 15) { Stop-Install "Health check failed: $(Get-UiUrl)$path" @('Run: gap logs kernel') }
+    Start-Sleep -Seconds 2
+  }
+}
+Write-Ok 'Health checks passed'
+
+# 7. The gap command
+$other = Get-Command gap -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1
+$onNpm = ((Get-Channel) -eq 'npm')
+$pathAdded = $false
+$zipLauncherLeft = $false
+if ($onNpm) {
+  # npm put `gap` on the PATH: no launcher, no PATH entry. A gap.cmd left by a ZIP install is only reported (D6);
+  # npm never makes this one.
+  $zipLauncherLeft = Test-Path -LiteralPath (Join-Path $LauncherDir 'gap.cmd')
+} else {
+  $pathAdded = Install-Launcher
+}
+# Does `gap` mean GAP in the user's own PowerShell? An alias or function of that name from the profile
+# is invisible to this script (install.cmd runs it with -NoProfile), so each PowerShell is asked
+# (gap-lib.ps1). Asked before the summary below, so that the summary stays the last thing on the screen.
+Write-Host 'Checking the gap command in your terminal...'
+$shadow = Get-GapResolutionReport
+Write-Host ''
+Write-Host 'GAP Platform is ready!'
+Write-Host ''
+Write-Host "  Admin UI:  $(Get-UiUrl)"
+Write-Host '  Login:     admin@example.com / changeme'
+Write-Host ''
+# Where `gap` is taken (see below), the name gap.cmd still reaches GAP, in PowerShell and in cmd.exe.
+if ($shadow.Shadowed) {
+  Write-Host '  Check it any time with:  gap.cmd status   (also: gap.cmd start, gap.cmd stop, gap.cmd logs)'
+} else {
+  Write-Host '  Check it any time with:  gap status   (also: gap start, gap stop, gap logs)'
+}
+if ($onNpm) {
+  # $GapSource is the package that provides `gap`: deleting it would remove the command.
+  Write-Host "  GAP now runs from $GapHome. Keep the npm package: it is the gap command."
+  if ($zipLauncherLeft) {
+    Write-Host "  Warning: $(Join-Path $LauncherDir 'gap.cmd') 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.'
+  }
+} else {
+  Write-Host "  GAP now runs from $GapHome; you can delete the installer folder $GapSource"
+}
+if ($pathAdded) {
+  Write-Host "  Added $LauncherDir to your user PATH."
+  Write-Host "  Open a new terminal for that to take effect, or run: $(Join-Path $LauncherDir 'gap.cmd') status"
+}
+$shadow.Lines | ForEach-Object { Write-Host $_ }
+# Only when no PowerShell could be asked, fall back to a gap on this script's own PATH.
+if (-not $shadow.Asked -and $other -and -not "$($other.Source)".StartsWith($LauncherDir)) {
+  Write-Host "  Note: another `"gap`" is already on your PATH ($($other.Source)) and may run instead; use $(Join-Path $LauncherDir 'gap.cmd')"
+}
+
+# 8. Open the browser
+Open-Url (Get-UiUrl)