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

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# @atomiton-dev/gap-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Installs and runs the GAP platform on your own machine with Docker. Your data is kept when you run
+the installer again.
+
+## What you need
+
+- Node.js 18 or newer.
+- Docker, installed **and running**: Docker Desktop on macOS and Windows; Docker Engine with the Compose
+  plugin (v2) on Linux. On Linux your user must be able to run `docker` without `sudo`, and `curl` must be
+  installed.
+- On macOS and Linux, `bash`. On Windows, Windows PowerShell 5.1.
+- Access to GAP's images (see "Get access to the images" below). They are private.
+
+## Install the command
+
+```
+npm install -g @atomiton-dev/gap-cli
+```
+
+This puts the `gap` command on your computer. It does not download GAP yet.
+
+If you use oh-my-zsh, the install also adds one small file, `~/.oh-my-zsh/custom/atomiton-gap.zsh`, so that a new
+terminal runs `gap` and not oh-my-zsh's `alias gap='git apply'` (which would answer "can't open patch"). It turns
+off only that one alias, only while this package is installed (with several Node versions it follows every copy
+that is still installed), and changes nothing else; delete the file to undo it. It holds a path on this machine, so do
+not copy it to another one. Open a new terminal (or run `exec zsh`) after the install. This step writes nothing else
+outside the package.
+
+## Get access to the images
+
+GAP's images are stored in a private registry (ghcr.io). You need a GitHub account that has been given access.
+
+1. Ask your contact at Atomiton to add your GitHub account to the GAP customers group. GitHub emails you an
+   invitation; accept it.
+2. Create a personal access token (classic) that has the `read:packages` permission. This link selects the
+   permission for you: <https://github.com/settings/tokens/new?scopes=read:packages>. Nobody else can create the
+   token for you.
+3. Log in to the registry:
+
+   ```
+   gap login
+   ```
+
+   It asks for your GitHub username and the token (the token is hidden as you type), logs Docker in to ghcr.io, and then
+   checks that your account can read GAP's images. It needs a terminal, and it exits with status 0 only when you are logged
+   in and can read the images. `gap` does not store the token anywhere: Docker keeps the login, in the system's credential
+   store when it has one (for example the macOS keychain). Where it has none, as on many Linux
+   machines, Docker stores it in `~/.docker/config.json` and says so. If you prefer Docker's own command,
+   `docker login ghcr.io -u <your GitHub username>` does the same login (paste the token when it asks for the password);
+   `gap doctor` then checks the access. (If `gap` still runs another program, see "If something goes wrong"; `command gap login` works meanwhile.)
+
+You do this once per machine. When the token expires, create a new one and run `gap login` again.
+
+## Install GAP
+
+```
+gap install
+```
+
+`gap install` pulls the images, starts GAP and prints the address of the Admin UI
+(`http://127.0.0.1:<port>`, a port between 8061 and 8070) and the sign-in details. It is safe to run again at
+any time: your data and password are kept. If it cannot pull the images it stops before changing anything on
+your machine and tells you what to do.
+
+## Update
+
+```
+npm install -g @atomiton-dev/gap-cli@latest
+gap update
+```
+
+`gap update` moves GAP to the version of the package you just installed. In this
+order: it pulls the new images, makes a backup of your database and your app files in
+`~/.gap/backups/<date and time>` (readable by you only; on Windows it has the permissions of your user folder), and only then starts the new version. If pulling or the backup fails,
+it stops and nothing has changed. It does not go back to an older version, and it does nothing when you are already on
+the version of the package. If the new version does not start, it undoes nothing by itself: it prints where the backup
+is and the commands to go back to your old version with your data. It never deletes a backup.
+`gap install` does not go back to an older version either: it stops and says so. `gap uninstall` keeps the `backups` folder
+(`gap uninstall --purge` erases it with everything else).
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `gap login` | asks for your GitHub username and token, logs in to the image registry, and checks that you can read the images |
+| `gap install` | installs, or installs again |
+| `gap update` | moves GAP to the version of this package, after a backup |
+| `gap status` | shows whether GAP is running and healthy |
+| `gap start` | starts GAP again (after `gap stop` or a reboot) |
+| `gap stop` | stops GAP; your data is kept |
+| `gap logs [service] [-f]` | shows logs (`kernel`, `postgres` or `admin-ui`) |
+| `gap version` | shows which GAP version is installed, and the version of this package |
+| `gap doctor` | checks this machine and the install, and says what to do about each problem; it changes nothing |
+| `gap uninstall [--purge] [--yes]` | removes GAP from this machine; your data is kept unless you add `--purge` (it asks you to type `delete`) |
+
+`gap help` prints the list.
+
+## One way of installing per machine
+
+Use either this package or the ZIP package of GAP on a machine, not both. They share the same data. If you
+used the ZIP before, run `gap install`. On macOS and Linux it reports a leftover `~/.local/bin/gap` launcher
+from the ZIP, which may run instead of the npm command; remove it with `rm ~/.local/bin/gap`.
+
+## Your data
+
+Your data lives in two Docker volumes, `gap_pgdata` and `gap_data`. Do not run `docker volume prune` or
+`docker system prune --volumes`: they can erase it.
+
+## If something goes wrong
+
+Run `gap doctor` first. It checks Node.js, Docker, the Admin UI port, the `gap` command, your access to the images and
+the state of GAP, and says what to do about each problem. It exits with status 1 when it finds one, and it changes
+nothing.
+
+- **`gap: command not found`** after installing: npm's global command folder is not on your `PATH`. Run
+  `npm prefix -g`; add that folder's `bin` subfolder (on Windows, the folder itself) to your `PATH`, then open a
+  new terminal.
+- **`gap` fails with "can't open patch 'login'" (or another word), or runs another program:** your terminal has
+  its own command named `gap`. With oh-my-zsh it is `alias gap='git apply'`; the install turns it off for new
+  terminals, so open a new terminal (or run `exec zsh`). If it still happens, the install could not do it (for
+  example it ran with `--ignore-scripts`, under `sudo`, or with yarn or pnpm, which may not run it; or your
+  `ZSH_CUSTOM` is set only in `~/.zshrc`; or you use another framework such as prezto). Add
+  `unalias gap 2>/dev/null` at the end of `~/.zshrc`, or run `command gap login` each time.
+  `gap install` also finds this and offers to turn it off.
+- **"GAP's images are private and this machine is not logged in to ghcr.io"** (`unauthorized`): follow steps 2
+  and 3 of "Get access to the images": create a token, then run `gap login`.
+- **"ghcr.io refused access to ..."** (`denied`): either your token has expired or been revoked, or your GitHub
+  account has not been given access yet. Create a new token and run `gap login` again; if it still fails, accept the
+  invitation GitHub emailed you and ask your contact at Atomiton to check that you are in the GAP customers group.
+- **"Docker daemon stopped":** start Docker Desktop (or the Docker service on Linux), wait until it is running,
+  then run `gap install` again.
+- **Something does not start:** `gap logs kernel` (or `postgres`, `admin-ui`) shows why.

package/bin/gap.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+'use strict';
+// `gap`: a thin Node shell over the installer scripts (#1986, #2010, D2). It runs bash (macOS, Linux) or
+// PowerShell (Windows) with the same arguments and exits with the script's exit code. ES5 only: on an old
+// Node this file must still get as far as printing why it cannot go on.
+var path = require('path');
+var childProcess = require('child_process');
+var launcher = require('../lib/launcher.js');
+
+
+function die(message) {
+  process.stderr.write(message + '\n');
+  process.exit(1);
+}
+
+if (!launcher.nodeSupported(process.versions.node)) {
+  die('Node ' + launcher.MIN_NODE_MAJOR + ' or newer is required (found ' + process.versions.node + '). ' +
+    'Install a current Node.js from https://nodejs.org and run the command again.');
+}
+
+var SIGNALS = require('os').constants.signals;
+var win = process.platform === 'win32';
+var command = launcher.buildCommand({
+  platform: process.platform,
+  pkgRoot: path.resolve(__dirname, '..'),
+  args: process.argv.slice(2)
+});
+
+var child = childProcess.spawn(command.cmd, command.args, { stdio: 'inherit' });
+
+child.on('error', function (err) {
+  if (err && err.code === 'ENOENT') {
+    die(win
+      ? 'powershell is required but was not found on PATH. Use Windows PowerShell 5.1 or newer.'
+      : 'bash is required but was not found on PATH. Install bash and run the command again.');
+  }
+  die('Could not start ' + command.cmd + ': ' + (err && err.message ? err.message : err));
+});
+
+['SIGINT', 'SIGTERM', 'SIGHUP'].forEach(function (sig) {
+  process.on(sig, function () { child.kill(sig); });
+});
+
+child.on('exit', function (code, signal) {
+  if (signal) process.exit(128 + (SIGNALS[signal] || 1));
+  process.exit(code === null ? 1 : code);
+});

package/installer/CHANNEL

@@ -0,0 +1 @@
+npm

package/installer/VERSION

@@ -0,0 +1 @@
+0.9.0-mvp

package/installer/docker-compose.yml

@@ -0,0 +1,86 @@
+# GAP local installer stack: postgres + kernel + admin-ui.
+#
+# Ships in the installer zip next to env.template, images.tar.gz and install.sh / install.ps1; the
+# installer copies it to ~/.gap, where .env is written and where it runs from (D28)
+# (#1750, plan .claude/plan/issue-1750/03-compose-and-config.md). Always run with `-p gap`:
+# COMPOSE_PROJECT_NAME in the user's shell overrides the `name:` key below.
+#
+# Two channels share this file, told apart only by two keys of .env (#1986):
+#   ZIP (default, offline): the images are loaded from images.tar.gz (`docker load`) under their
+#     local names and never pulled: GAP_IMAGE_PREFIX is empty and GAP_PULL_POLICY is `never`, so a
+#     missing image fails with a clear error instead of reaching for Docker Hub.
+#   npm (online): the images are pulled from a registry: GAP_IMAGE_PREFIX is
+#     `ghcr.io/atomiton-gap/` and GAP_PULL_POLICY is `missing`.
+# An .env without either key (every ZIP installed before #1986) behaves exactly as the ZIP channel.
+# Required variables use `${VAR:?...}` so Compose stops with a message instead of running with an
+# empty value.
+name: gap
+
+services:
+  postgres:
+    # Hard-coded on purpose: changing the major version breaks an existing volume. The official
+    # postgres:16, packaged under a GAP name so that `docker load` never moves the user's own
+    # postgres:16 tag (build-package.sh).
+    image: ${GAP_IMAGE_PREFIX:-}gap-postgres:16
+    pull_policy: ${GAP_PULL_POLICY:-never}
+    environment:
+      POSTGRES_USER: postgres
+      # Only read when the data volume is still empty (first start).
+      POSTGRES_PASSWORD: ${GAP_DB_PASSWORD:?GAP_DB_PASSWORD missing, re-run the installer}
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      # -h 127.0.0.1: without it pg_isready reaches the temporary socket-only server that the
+      # image runs during first-time initialisation and reports ready too early.
+      test: ["CMD", "pg_isready", "-h", "127.0.0.1", "-U", "postgres"]
+      interval: 5s
+      timeout: 3s
+      retries: 30
+    restart: unless-stopped
+    # No `ports`: the database is reachable only from the other services.
+
+  kernel:
+    image: ${GAP_IMAGE_PREFIX:-}gap-kernel:${GAP_VERSION:?GAP_VERSION missing, re-run the installer}
+    pull_policy: ${GAP_PULL_POLICY:-never}
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      ENVIRONMENT: dev
+      DEBUG: "false"
+      # Required: without it the App UI endpoints answer 500 (main.py warns at start).
+      GAP_DATA_ROOT: /data/gap-data
+      DB_HOST: postgres
+      DB_PORT: "5432"
+      DB_USER: postgres
+      DB_PASSWORD: ${GAP_DB_PASSWORD:?GAP_DB_PASSWORD missing, re-run the installer}
+      DB_ADMIN_USER: postgres
+      DB_ADMIN_PASSWORD: ${GAP_DB_PASSWORD:?GAP_DB_PASSWORD missing, re-run the installer}
+      # Explicit: the Kernel default follows the CPU count of the machine.
+      OFFLOAD_MAX_WORKERS: "2"
+      # JWT_SECRET and APP_CREDENTIAL_ENCRYPTION_KEY are left to the Kernel defaults (D7); that is
+      # only acceptable while nothing but 127.0.0.1 can reach the Admin UI (D9).
+    volumes:
+      - data:/data
+    # The default 10 s equals worker_drain_timeout_seconds, which leaves no time for the rest
+    # of the shutdown.
+    stop_grace_period: 30s
+    restart: unless-stopped
+    # No `ports`: every API call goes through the Admin UI (nginx).
+
+  admin-ui:
+    image: ${GAP_IMAGE_PREFIX:-}gap-admin-ui:${GAP_VERSION:?GAP_VERSION missing, re-run the installer}
+    pull_policy: ${GAP_PULL_POLICY:-never}
+    depends_on:
+      kernel:
+        condition: service_healthy
+    ports:
+      # Loopback only: the seeded admin account and the default JWT secret are acceptable only
+      # because of this binding (D6, D7, D9). Never bind 0.0.0.0 without revisiting those.
+      - "127.0.0.1:${GAP_UI_PORT:?GAP_UI_PORT missing, re-run the installer}:8080"
+    restart: unless-stopped
+
+# Real names on Docker are gap_pgdata and gap_data (project name + key).
+volumes:
+  pgdata:
+  data:

package/installer/env.template

@@ -0,0 +1,13 @@
+# Written by the installer on first install, as .env in ~/.gap (not in the unzipped folder, D28);
+# do not commit a filled-in copy. The installer owns these values and reads them back on later runs.
+GAP_VERSION=@GAP_VERSION@
+GAP_UI_PORT=@GAP_UI_PORT@
+# Random, generated once. Postgres keeps the password it was first started with, so editing it by
+# hand makes the Kernel fail to authenticate. If this file is lost, install.sh / install.ps1
+# generates a new password and sets it inside Postgres, so the data is kept (D28).
+GAP_DB_PASSWORD=@GAP_DB_PASSWORD@
+# Which channel the images come from (#1986). The ZIP installer keeps these two as they are: images
+# loaded from the zip under their local names, never pulled. The npm installer sets the registry
+# prefix (ghcr.io/atomiton-gap/) and `missing`. docker-compose.yml reads them.
+GAP_IMAGE_PREFIX=
+GAP_PULL_POLICY=never

package/installer/gap

@@ -0,0 +1,365 @@
+#!/usr/bin/env bash
+# gap: status / start / stop / logs / uninstall / version / doctor (and update, npm channel) for the local GAP stack (#1750, D27, D28). In the npm package
+# (#1986) `gap install` is the other script, install.sh, which the Node launcher (bin/gap.js) runs.
+# install.sh copies this file to ~/.gap and puts a launcher for it on the PATH, so `gap status`
+# works in any terminal. It always works on the instance in ~/.gap (GAP_HOME, from gap-lib.sh),
+# also when run from the unzipped installer folder.
+set -u
+
+GAP_SRC=$(cd "$(dirname "$0")" && pwd -P)
+# shellcheck source=gap-lib.sh
+. "$GAP_SRC/gap-lib.sh"
+
+usage() {
+  printf 'Usage: gap <command>\n\n'
+  # `install` and `update` are commands of the npm package only: the ZIP's gap has none, its installer is install.sh /
+  # install.ps1 (and a ZIP updates by running the new one).
+  if [ "$(channel)" = npm ]; then
+    printf '  install         install GAP on this machine (pulls the images; run it again any time)\n'
+    printf '  login           log in to the registry that holds the images (asks for your GitHub username and token)\n'
+    printf '  update          move GAP to the version of the installed npm package, after a backup\n'
+  fi
+  cat <<'EOF'
+  status          show whether GAP is running and healthy
+  version         show the installed GAP version
+  doctor          check this machine and the install for problems; changes nothing
+  start           start GAP again (after `gap stop` or a reboot)
+  stop            stop GAP; your data is kept
+  logs [service] [-f]
+                  show logs (service: kernel, postgres or admin-ui)
+  uninstall [--purge] [--yes]
+                  remove GAP from this machine; your data is kept
+                  unless you add --purge (it asks you to type "delete")
+EOF
+}
+
+need_install() {
+  [ -f "$GAP_HOME/.env" ] && return 0
+  warn "GAP is not installed in $GAP_HOME"
+  if [ "$(channel)" = npm ]; then printf 'Run: gap install\n'
+  elif [ -f "$GAP_SRC/install.sh" ]; then printf 'Run: %s/install.sh\n' "$GAP_SRC"
+  else printf 'Run install.sh from the GAP installer folder.\n'; fi
+  return 1
+}
+
+cmd_status() {
+  local pg kernel ui runtime overall=READY port
+  check_prereqs "gap status" || return 1
+  pg=$(svc_state postgres); kernel=$(svc_state kernel); ui=$(svc_state 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" = Healthy ] && [ "$ui" = Healthy ] && http_ok /system/health; then runtime=Healthy
+  elif [ "$kernel" = Stopped ]; then runtime=Stopped
+  else runtime=Unreachable; fi
+  for s in "$pg" "$kernel" "$runtime" "$ui"; do [ "$s" = Healthy ] || overall="NOT READY"; done
+  port=$(env_get GAP_UI_PORT)
+  printf '%-15s %s\n' "PostgreSQL" "$pg" "GAP Kernel" "$kernel" "GAP Runtime" "$runtime" "GAP Admin UI" "$ui"
+  printf 'Version: %s\n' "$(env_get GAP_VERSION)"
+  newer_package_note
+  [ "$overall" = READY ] && printf 'URL: http://127.0.0.1:%s\n' "$port"
+  printf 'Overall: %s\n' "$overall"
+  [ "$overall" = READY ]
+}
+
+# version and doctor work before GAP is installed: doctor is what to run when the install did not work.
+cmd_version() {
+  local installed pkg
+  installed=$(installed_version); pkg=$(cli_version)
+  printf 'Installed:    %s\n' "${installed:-not installed}"
+  [ -z "$pkg" ] || printf 'CLI package:  %s\n' "$pkg"
+  if [ -n "$pkg" ] && [ -n "$installed" ] && [ "$installed" != unknown ] && [ "$installed" != "$pkg" ]; then
+    if package_is_newer; then printf 'The installed version differs from this package. Run: gap update\n'
+    elif package_is_older; then
+      printf 'The installed version is newer than this package. Install the newer package: npm install -g @atomiton-dev/gap-cli@latest\n'
+    else printf 'The installed version differs from this package. Run: gap install\n'; fi
+  fi
+}
+
+# doctor_* are in gap-lib.sh (where the tests reach them). Exits 0 when no check found a problem, 1 otherwise.
+cmd_doctor() {
+  DOCTOR_PROBLEMS=0
+  doctor_docker
+  doctor_node
+  doctor_ports
+  doctor_gap_command
+  doctor_registry
+  doctor_install
+  case "$DOCTOR_PROBLEMS" in
+    0) printf 'Overall: OK\n' ;;
+    1) printf 'Overall: 1 problem\n' ;;
+    *) printf 'Overall: %s problems\n' "$DOCTOR_PROBLEMS" ;;
+  esac
+  [ "$DOCTOR_PROBLEMS" = 0 ]
+}
+
+# cannot_hide_token: what `gap login` says when the terminal cannot be told to stop echoing (see cmd_login). Uses `host` of the caller.
+cannot_hide_token() {
+  warn "Cannot hide the token on this terminal, so gap login did not ask for it"
+  printf 'Log in with Docker instead (it asks for the token itself): docker login %s -u <your GitHub username>\n' "${host:-ghcr.io}"
+}
+
+# `gap login` (#1986): npm channel only (the ZIP carries its images). The way in to the private registry that holds them, in
+# GAP's own words: 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, so that "logged in" and "can
+# read GAP's images" are not mistaken for each other: a valid token of an account that was never given access logs in fine.
+# Needs a terminal (the token is typed hidden); without one it says how to do it by hand. Docker keeps the credential, in its
+# own store (the macOS keychain, Windows' credential manager, ...); gap writes it nowhere.
+cmd_login() {
+  local host user token out rc saved traced=0
+  if [ "$(channel)" != npm ]; then
+    warn "The ZIP has no \`gap login\`"
+    printf 'Its images are inside the ZIP, so there is no registry to log in to.\n'
+    return 1
+  fi
+  host=$(channel_prefix); host=${host%%/*}
+  if [ ! -t 0 ]; then
+    warn "gap login asks for your GitHub username and token, so it needs a terminal"
+    printf 'Without one, log in with Docker and pipe the token into it:\n'
+    printf '  docker login %s -u <your GitHub username> --password-stdin\n' "$host"
+    return 1
+  fi
+  check_prereqs "gap login" || return 1
+  # The questions go to stderr, as `read -p` does: with `gap login > log` they are still on the screen.
+  {
+    printf 'GAP'"'"'s images are in %s, a private registry. You need a GitHub personal access token (classic)\n' "$host"
+    printf 'with the read:packages permission. Create one here if you have none:\n'
+    printf '  https://github.com/settings/tokens/new?scopes=read:packages\n\n'
+    printf 'GitHub username: '
+  } >&2
+  # `read` (IFS at its default) drops the blanks a paste brings in front of and behind the text.
+  read -r user || { printf '\n' >&2; user=""; }
+  if [ -z "$user" ]; then warn "No username was given"; return 1; fi
+  # The echo is turned off BEFORE the prompt is printed, not by `read -s` after it: a token pasted right after the prompt
+  # appears (or typed ahead together with the username) would be echoed in the meantime. A Ctrl-C used to leave the echo off
+  # (measured on bash 3.2), so that what the user typed next was invisible: put the terminal back as it was, whichever way this
+  # ends.
+  # If the terminal cannot be asked how it is set, or cannot be told to stop echoing, the token would be shown while the prompt says
+  # it is hidden (a missing or broken stty): then nothing is asked, rather than a lie.
+  saved=$(stty -g 2>/dev/null)
+  if [ -z "$saved" ]; then cannot_hide_token; return 1; fi
+  trap 'stty "$saved" 2>/dev/null; printf "\n" >&2; exit 130' INT TERM HUP QUIT
+  # A job that was stopped (Ctrl-Z) and resumed (fg) gets the terminal back as the shell saved it, echo on: hide the token again.
+  trap 'stty -echo 2>/dev/null' CONT
+  if ! stty -echo 2>/dev/null; then
+    trap - INT TERM HUP QUIT CONT; stty "$saved" 2>/dev/null
+    cannot_hide_token; return 1
+  fi
+  printf 'Token (hidden as you type): ' >&2
+  # From here the token is in a variable: no shell trace (`bash -x`, SHELLOPTS=xtrace) may print it, so it is switched off
+  # until the token has gone to Docker, and back on afterwards if it was on.
+  case $- in *x*) traced=1 ;; esac
+  { set +x; } 2>/dev/null
+  read -r token || token=""
+  trap - INT TERM HUP QUIT CONT
+  stty "$saved" 2>/dev/null
+  printf '\n' >&2
+  if [ -z "$token" ]; then [ "$traced" = 0 ] || set -x; warn "No token was given"; return 1; fi
+  out=$(printf '%s' "$token" | docker login "$host" -u "$user" --password-stdin 2>&1); rc=$?
+  out=${out//"$token"/***}   # Docker does not print the password; if a text ever carried it, it would not reach the screen
+  token=""
+  [ "$traced" = 0 ] || set -x
+  if [ "$rc" != 0 ]; then
+    case "$(classify_login_error "$out")" in
+      rejected)
+        # ghcr.io ignores the username of a valid token (measured: a made-up name logs in), so only the token is blamed.
+        warn "$host did not accept that token"
+        printf '    - Paste the personal access token (classic) itself, not your GitHub password.\n'
+        printf '    - It needs the read:packages permission and must not be expired or revoked.\n'
+        printf '    Nothing was changed. Run gap login to try again.\n' ;;
+      network)
+        warn "Could not reach $host"
+        printf '    Check your internet connection (and proxy settings), then run gap login again.\n' ;;
+      *)
+        warn "docker login failed"
+        printf '%s\n' "$out" | tail -n 3 | sed 's/^/    /' ;;
+    esac
+    return 1
+  fi
+  ok "Logged in to $host as $user"
+  # What Docker said besides "Login Succeeded" is worth reading (it warns when the credential is kept unencrypted).
+  printf '%s\n' "$out" | grep -v '^Login Succeeded$' | sed -e '/^$/d' -e 's/^/    /'
+  LOGIN_JUST_DONE=1; DOCTOR_PROBLEMS=0; DOCTOR_DOCKER=1
+  doctor_registry
+  [ "$DOCTOR_PROBLEMS" = 0 ] || return 1
+  # Exit 0 means logged in AND able to read the images. When the check could not be made (no network for it, no VERSION file, a
+  # text Docker gave that is not known) neither is claimed: it is said, the status is 1, and no "Next:" is offered.
+  if [ "$REGISTRY_READABLE" != 1 ]; then
+    printf 'Logged in, but whether your account can read the images could not be checked. Run gap doctor when that is possible.\n'
+    return 1
+  fi
+  is_installed || printf 'Next: gap install\n'
+  return 0
+}
+
+# update_failed OLD NEW: 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 (print_restore_help).
+update_failed() {
+  warn "The update to GAP $2 did not finish, and GAP $1 was not restored automatically"
+  printf '    The backup made before the update: %s\n' "$BACKUP_DIR"
+  printf '    .env now says GAP_VERSION=%s. Nothing was rolled back and nothing was deleted.\n' "$(env_get GAP_VERSION)"
+  printf '    First look at what the new version says: gap logs kernel\n'
+  print_restore_help "$BACKUP_DIR" "$1"
+}
+
+# update_not_applied OLD NEW: 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.
+update_not_applied() {
+  warn "The update to GAP $2 could not be applied: the files in $GAP_HOME could not be written"
+  printf '    The running stack was not touched; GAP %s runs as before. The backup made before: %s\n' "$1" "$BACKUP_DIR"
+  printf '    .env now says GAP_VERSION=%s. To put the old .env and compose file back:\n' "$(env_get GAP_VERSION)"
+  print_files_back_help "$BACKUP_DIR"
+  printf '    Check the permissions of %s, then run: gap update\n' "$GAP_HOME"
+}
+
+# D-update (#2014): npm channel only. Order matters: nothing of the old stack is touched until the images are here AND the
+# backup was made and checked. Equal versions are "nothing to do"; an older package or a version it cannot compare is refused.
+cmd_update() {
+  local installed pkg cmp
+  if [ "$(channel)" != npm ]; then
+    warn "The ZIP has no \`gap update\`"
+    printf 'To update: unzip the new installer and run its install.sh. It keeps your data and your secrets.\n'
+    return 1
+  fi
+  need_install || return 1
+  installed=$(installed_version); pkg=$(cli_version)
+  if [ -z "$pkg" ]; then
+    warn "This package has no VERSION file, so it cannot tell which version it brings"
+    return 1
+  fi
+  if ! cmp=$(version_cmp "$installed" "$pkg"); then
+    warn "Cannot compare the installed version ($installed) with the version of this package ($pkg)"
+    printf '    gap update only moves between versions it can compare (major.minor.patch, with the same -suffix).\n'
+    printf '    Nothing was changed.\n'
+    return 1
+  fi
+  if [ "$cmp" = 0 ]; then
+    printf 'GAP %s is already the version of this package. Nothing to do.\n' "$installed"
+    return 0
+  fi
+  if [ "$cmp" = 1 ]; then
+    warn "This package ($pkg) is older than the installed GAP ($installed)"
+    older_package_help
+    printf '    Nothing was changed.\n'
+    return 1
+  fi
+  printf 'Updating GAP %s -> %s\n\n' "$installed" "$pkg"
+  check_prereqs "gap update" up || return 1
+  pull_images "$pkg" "gap update" || return 1   # has said what to do; the old stack is untouched
+  ok "Images ready"
+  make_backup || return 1          # has said what is wrong; nothing was changed
+  ok "Backup saved in $BACKUP_DIR"
+  # The files first: if they cannot be written the running stack has not been touched, and the way back is two `cp` lines, not
+  # the restore (which starts with `down -v` and would erase a healthy stack).
+  if ! { put_file "$GAP_SRC/docker-compose.yml" "$GAP_HOME/docker-compose.yml" 644 \
+         && env_set GAP_VERSION "$pkg" && env_set GAP_IMAGE_PREFIX "$(channel_prefix)" \
+         && env_set GAP_PULL_POLICY "$(channel_pull_policy)"; }; then
+    update_not_applied "$installed" "$pkg"
+    return 1
+  fi
+  if ! { bring_up && health_checks; }; then
+    update_failed "$installed" "$pkg"
+    return 1
+  fi
+  printf '\nGAP updated: %s -> %s\n' "$installed" "$pkg"
+  printf '  Backup of GAP %s: %s\n' "$installed" "$BACKUP_DIR"
+  printf '  It is kept; delete it when you no longer need it. Check GAP with: gap status\n'
+}
+
+cmd_start() {
+  local stored port
+  check_prereqs "gap start" up || return 1
+  stored=$(env_get GAP_UI_PORT)
+  port=$(pick_port "$stored") || { warn "No free port for the Admin UI"; printf 'Action: free a port between %s and %s\n' "$GAP_PORT_FIRST" "$GAP_PORT_LAST"; return 1; }
+  if [ "$port" != "$stored" ]; then
+    warn "Port $stored is in use, using $port instead"
+    env_set GAP_UI_PORT "$port"
+  fi
+  bring_up || return 1
+  ok "GAP is running"
+  printf 'Admin UI: %s\n' "$(ui_url)"
+  newer_package_note
+  open_url "$(ui_url)"
+}
+
+cmd_stop() {
+  check_prereqs "gap stop" || return 1
+  dc stop || return 1
+  printf 'GAP stopped. Your data is kept. Run: gap start\n'
+}
+
+cmd_logs() {
+  check_prereqs "gap logs" || return 1
+  dc logs "$@"
+}
+
+# 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 usage()
+# and the READMEs. It removes ~/.gap, the launcher and the rc lines the installer added, and nothing else: the
+# unzipped installer folder (ZIP) and the package folder (npm) are never touched, and `npm uninstall -g` is the
+# user's separate, later step.
+cmd_uninstall() {
+  local purge=0 yes=0 arg answer version prefix removed had_backups=0
+  for arg in "$@"; do
+    case "$arg" in
+      --purge) purge=1 ;;
+      --yes)   yes=1 ;;
+      *)       usage >&2; return 2 ;;
+    esac
+  done
+  check_prereqs "gap uninstall" || return 1
+  version=$(env_get GAP_VERSION)
+  [ ! -d "$GAP_HOME/backups" ] || had_backups=1
+  if [ "$purge" = 1 ] && [ "$yes" = 0 ]; then
+    if [ ! -t 0 ]; then
+      warn "--purge erases all GAP data; run it in a terminal, or add --yes to confirm"
+      return 1
+    fi
+    if [ "$had_backups" = 1 ]; then
+      printf 'This erases ALL GAP data (database and files), the GAP images and the backups in %s/backups. Type "delete" to continue: ' "$GAP_HOME"
+    else
+      printf 'This erases ALL GAP data (database and files) and the GAP images. Type "delete" to continue: '
+    fi
+    read -r answer
+    [ "$answer" = delete ] || { printf 'Cancelled. Nothing was changed.\n'; return 1; }
+  fi
+  if [ "$purge" = 1 ]; then dc down -v || return 1; else dc down || return 1; fi
+  if [ "$purge" = 1 ]; then
+    prefix=$(installed_prefix)
+    docker rmi "$(image_ref "$prefix" gap-kernel "$version")" "$(image_ref "$prefix" gap-admin-ui "$version")" \
+      "$(image_ref "$prefix" gap-postgres 16)" >/dev/null 2>&1 || true
+  fi
+  # The launcher only if it is ours: a `gap` of another program, or a symlink, stays.
+  if launcher_is_ours "$LAUNCHER_DIR/gap"; then rm -f "$LAUNCHER_DIR/gap"; fi
+  removed=$(remove_rc_lines)
+  # The backups of `gap update` are data: without --purge they stay, everything else of ~/.gap goes (they hold the database
+  # and the old password, so nothing here makes them readable by others: the folder is 700).
+  if [ "$purge" = 0 ] && [ "$had_backups" = 1 ]; then
+    find "$GAP_HOME" -mindepth 1 -maxdepth 1 ! -name backups -exec rm -rf {} +
+  else
+    rm -rf "$GAP_HOME"
+  fi
+  ok "GAP removed"
+  [ -z "$removed" ] || printf 'Removed the lines the installer added to:%s\n' "$removed"
+  if [ "$purge" = 1 ]; then
+    printf 'All GAP data was erased.\n'
+    [ "$had_backups" = 0 ] || printf 'The backups in %s/backups were erased too.\n' "$GAP_HOME"
+  else
+    [ "$had_backups" = 0 ] || printf 'The backups of gap update are kept in %s/backups (delete that folder when you no longer need them).\n' "$GAP_HOME"
+    printf 'Your data is kept in the Docker volumes %s_pgdata and %s_data; installing again brings it back.\n' "$GAP_PROJECT" "$GAP_PROJECT"
+    printf 'To erase it for good, install again and run: gap uninstall --purge\n'
+  fi
+}
+
+cmd=${1:-}
+[ $# -gt 0 ] && shift
+case "$cmd" in
+  version|doctor|update|login)  [ $# -eq 0 ] || { usage >&2; exit 2; }; "cmd_$cmd" ;;
+  status|start|stop|logs|uninstall) need_install || exit 1; "cmd_$cmd" "$@" ;;
+  help|-h|--help)         usage ;;
+  *)                      usage >&2; exit 2 ;;
+esac