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

package/installer/gap-lib.sh

@@ -0,0 +1,1203 @@
+# Shared by install.sh and gap (#1750, D27, D28). Sourced, never executed; the caller sets GAP_SRC to
+# the folder it runs from (the unzipped installer, or ~/.gap once installed).
+#
+# Written for bash 3.2 (macOS /bin/bash): no associative arrays, no mapfile, no ${var,,}.
+
+# Plain variables, not exported: a GAP_* variable in the user's shell must not change them.
+# D28: the installed instance (.env, docker-compose.yml, gap) lives in GAP_HOME, never in the
+# unzipped folder, so that moving or deleting that folder cannot lose the database password.
+GAP_HOME="${HOME:?HOME is not set}/.gap"
+LAUNCHER_DIR="$HOME/.local/bin"
+RC_MARKER="# gap installer"
+RC_EXPORT='export PATH="$HOME/.local/bin:$PATH"'
+# What install.sh may add after RC_MARKER, besides RC_EXPORT, when the user agrees to turn off a `gap`
+# alias or function (check_gap_resolution): one line for POSIX-like shells, two possible ones for fish.
+RC_UNSHADOW='unalias gap 2>/dev/null; unset -f gap 2>/dev/null'
+RC_UNSHADOW_FISH='functions -e gap'
+RC_UNSHADOW_FISH_ABBR='abbr -e gap'
+LAUNCHER_MARK="# gap launcher, written by the GAP installer"
+GAP_PROJECT=gap
+GAP_PORT_FIRST=8061
+GAP_PORT_LAST=8070
+GAP_UP_TIMEOUT=300   # D26: seconds to wait for the three services to become healthy
+
+ok()   { printf '[✓] %s\n' "$1"; }
+warn() { printf '[!] %s\n' "$1"; }
+
+# docker compose against this folder. GAP_* and COMPOSE_* variables from the user's shell are
+# dropped for the call so that only .env decides version, port and password (A4, E40).
+dc() {
+  local scrub=() v
+  # Two -e expressions, not `\(GAP\|COMPOSE\)`: the sed of macOS has no `\|`, matched nothing, and let a
+  # GAP_VERSION from the user's shell override .env.
+  while IFS= read -r v; do scrub+=(-u "$v"); done < <(env | sed -n -e 's/^\(GAP_[A-Za-z0-9_]*\)=.*/\1/p' -e 's/^\(COMPOSE_[A-Za-z0-9_]*\)=.*/\1/p')
+  env ${scrub[@]+"${scrub[@]}"} docker compose -p "$GAP_PROJECT" --project-directory "$GAP_HOME" \
+    -f "$GAP_HOME/docker-compose.yml" --env-file "$GAP_HOME/.env" "$@"
+}
+
+env_get() { sed -n "s/^$1=//p" "$GAP_HOME/.env" | head -n 1; }
+
+# image_ref 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).
+image_ref() { printf '%s%s:%s' "$1" "$2" "$3"; }
+
+# installed_prefix: 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. This is not "the prefix of the
+# channel running this script": an npm install over a machine that a ZIP installed rewrites .env, and a ZIP of
+# #1750 never knew the key. Use it to find what is installed (uninstall); what to pull is the channel's own matter.
+installed_prefix() { env_get 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 in ~/.gap, so both are the `zip` channel. This is a file, not
+# a variable, because `dc` drops every GAP_* variable of the shell (F3).
+NPM_IMAGE_PREFIX="ghcr.io/atomiton-gap/"
+
+channel() {
+  # -f first: a `< missing-file` fails in the shell, before any `2>/dev/null` of the same command takes effect.
+  if [ -f "$GAP_SRC/CHANNEL" ] && [ "$(tr -d '[:space:]' < "$GAP_SRC/CHANNEL")" = npm ]; then printf npm; else printf zip; fi
+}
+
+# channel_prefix / channel_pull_policy: 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 (F19). installed_prefix (above) is for finding what is installed.
+channel_prefix() { if [ "$(channel)" = npm ]; then printf '%s' "$NPM_IMAGE_PREFIX"; fi; }
+channel_pull_policy() { if [ "$(channel)" = npm ]; then printf missing; else printf never; fi; }
+
+# install_cmd: what the user types to install again, in the words of this channel.
+install_cmd() { if [ "$(channel)" = npm ]; then printf 'gap install'; else printf '%s/install.sh' "$GAP_SRC"; fi; }
+
+# install_name: the same command as install_cmd, short, for the sentence "... then run <it> again" of install.sh's own
+# error messages. The ZIP keeps the bare script name those messages always had; npm has no install.sh to name (it sits
+# inside node_modules), only `gap install`.
+install_name() { if [ "$(channel)" = npm ]; then printf 'gap install'; else printf 'install.sh'; fi; }
+
+# gap_script: the gap that works when `gap` itself does not. The npm package is the only copy of the scripts; a ZIP
+# install copies them into GAP_HOME.
+gap_script() { if [ "$(channel)" = npm ]; then printf '%s/gap' "$GAP_SRC"; else printf '%s/gap' "$GAP_HOME"; fi; }
+
+# classify_pull_error 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): `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
+# (the two cannot be 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 rather than guessed at.
+# Not matched on a bare "denied": `permission denied while trying to connect to the docker API` is not the registry.
+classify_pull_error() {
+  local t
+  t=$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')
+  case "$t" in
+    *'failed to do request'*)               printf network ;;
+    *'error from registry: unauthorized'*)  printf unauthorized ;;
+    *'error from registry: denied'*)        printf denied ;;
+    *': not found'*)                        printf notfound ;;
+    *)                                      printf other ;;
+  esac
+}
+
+# print_login_steps / print_denied_help: what to do about `unauthorized` and `denied` (the texts are measured, see
+# classify_pull_error). Shared by report_pull_failure (a pull that failed), doctor (access read with `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.
+print_login_steps() {
+  printf 'Action:\n'
+  printf '  1. Create a GitHub personal access token (classic) that has the read:packages permission:\n'
+  printf '       https://github.com/settings/tokens/new?scopes=read:packages\n'
+  printf '  2. Log in to the registry:  gap login\n'
+  printf '     and enter your GitHub username and the token when it asks.\n'
+}
+
+# LOGIN_JUST_DONE=1 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.
+print_denied_help() {
+  if [ "${LOGIN_JUST_DONE:-0}" = 1 ]; then
+    printf 'You are logged in, but your GitHub account has not been given access to GAP'"'"'s images.\n'
+    printf 'Ask the GAP administrator to add you to the team that can read them. If you were added just now,\n'
+    printf 'accept the invitation GitHub emailed you, then check again with: gap doctor\n'
+    return 0
+  fi
+  printf 'Either your token is no longer valid (expired or revoked), or your GitHub account has not been given\n'
+  printf 'access to GAP'"'"'s images. Ask the GAP administrator to add you to the team that can read them.\n'
+  printf 'If you were added, accept the invitation GitHub emailed you. If you are already on the team,\n'
+  printf 'create a new token with read:packages and log in again:\n'
+  printf '  gap login\n'
+}
+
+# classify_login_error TEXT: rejected | network | other, for what `docker login` printed when it failed. Measured with Docker 29
+# on ghcr.io (05/11/2026): 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 `... dial tcp: lookup <host>: no such host`. Network is tried
+# first (its texts carry the same `Get "<url>":` prefix). `rejected` needs the registry's own `": denied` / `": unauthorized`:
+# a bare "denied" is also what an unreadable ~/.docker/config.json says (`permission denied`), and that is not a bad token.
+classify_login_error() {
+  local t
+  t=$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')
+  case "$t" in
+    *'no such host'*|*'client.timeout'*|*'deadline exceeded'*|*'connection refused'*|*'i/o timeout'*|*'dial tcp'*|*'failed to do request'*) printf network ;;
+    *'": denied'*|*'": unauthorized'*) printf rejected ;;
+    *) printf other ;;
+  esac
+}
+
+# report_pull_failure 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.
+report_pull_failure() {
+  local image="$1" kind="$2" text="$3" retry="${4:-}" version
+  version=$(tr -d '[:space:]' < "$GAP_SRC/VERSION" 2>/dev/null)
+  case "$kind" in
+    unauthorized)
+      warn "GAP's images are private and this machine is not logged in to ghcr.io"
+      print_login_steps ;;
+    denied)
+      warn "ghcr.io refused access to $image"
+      print_denied_help ;;
+    notfound)
+      warn "$image was not found in the registry"
+      printf 'This GAP package is version %s. That version may not be published yet; check the version you were given.\n' "$version" ;;
+    network)
+      warn "Could not reach ghcr.io while pulling $image"
+      printf 'Check your internet connection (and proxy settings). Images and layers already downloaded are kept.\n' ;;
+    *)
+      warn "Pulling $image failed"
+      printf '%s\n' "$text" | tail -n 5 ;;
+  esac
+  if [ -n "$retry" ]; then
+    printf 'Nothing was changed.\n'
+    printf 'Then run: %s\n' "$retry"
+  else
+    printf 'Nothing was installed and no data was changed.\n'
+    printf 'Then run: %s\n' "$(install_cmd)"
+  fi
+}
+
+# pull_images VERSION [RETRY]: pull the images this version needs from the registry of the channel (npm), the ones that are
+# not on this machine yet. Returns 1 after report_pull_failure has said what to do. Runs before anything is written to
+# GAP_HOME, 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 when it is a kind we do not know).
+pull_images() {
+  local version="$1" retry="${2:-}" prefix ref out
+  prefix=$(channel_prefix)
+  for ref in "$(image_ref "$prefix" gap-kernel "$version")" "$(image_ref "$prefix" gap-admin-ui "$version")" \
+             "$(image_ref "$prefix" gap-postgres 16)"; do
+    docker image inspect "$ref" >/dev/null 2>&1 && continue
+    printf 'Pulling %s, this can take a few minutes...\n' "$ref"
+    if ! out=$(docker pull "$ref" 2>&1); then
+      report_pull_failure "$ref" "$(classify_pull_error "$out")" "$out" "$retry"
+      return 1
+    fi
+  done
+}
+
+# env_set 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). The file stays readable by its owner only.
+# VALUE may be empty but may not contain | & or \ : it goes into a sed expression, where they would be
+# read as the delimiter, the matched text and an escape. Such a value is refused (status 2) and nothing is
+# written, in the replace case and the add case alike.
+env_set() {
+  case "$2" in
+    *'|'*|*'&'*|*'\'*) printf 'env_set: the value of %s may not contain | & or \\\n' "$1" >&2; return 2 ;;
+  esac
+  # Never conjure up a .env that holds one key: "is there a .env?" is how the installers tell an installed
+  # machine from a fresh one, and a lost .env from a present one.
+  [ -f "$GAP_HOME/.env" ] || { printf 'env_set: %s/.env does not exist\n' "$GAP_HOME" >&2; return 1; }
+  ( umask 077
+    if grep -q "^$1=" "$GAP_HOME/.env"; then
+      sed "s|^$1=.*|$1=$2|" "$GAP_HOME/.env" > "$GAP_HOME/.env.tmp"
+    else
+      # The last line may have no newline; without this the new key would be glued to it.
+      { cat "$GAP_HOME/.env"; [ -z "$(tail -c 1 "$GAP_HOME/.env")" ] || printf '\n'; printf '%s=%s\n' "$1" "$2"; } > "$GAP_HOME/.env.tmp"
+    fi && mv "$GAP_HOME/.env.tmp" "$GAP_HOME/.env" )
+}
+
+ui_url() { printf 'http://127.0.0.1:%s' "$(env_get GAP_UI_PORT)"; }
+
+os_name() {
+  case "$(uname -s)" in
+    Darwin) printf 'macOS %s' "$(uname -m)" ;;
+    *)      printf '%s %s' "$(uname -s)" "$(uname -m)" ;;
+  esac
+}
+
+# Prints the failing step, then what to do about it. $1 = command to re-run afterwards; $2 = `up` when
+# the caller is going to start the stack, which also checks that Compose has `up --wait-timeout`.
+check_prereqs() {
+  local lines="[✓] OS: $(os_name)"$'\n' action="" info
+  if ! command -v docker >/dev/null 2>&1; then
+    lines+="[!] Docker CLI not found"
+    if [ "$(uname -s)" = Linux ]; then action="Install Docker Engine with the Compose plugin (https://docs.docker.com/engine/install/)"
+    else action="Install Docker Desktop (https://www.docker.com/products/docker-desktop/)"; fi
+  else
+    lines+="[✓] Docker CLI detected"$'\n'
+    if ! info=$(docker info 2>&1); then
+      if [ "$(uname -s)" = Darwin ]; then
+        lines+="[!] Docker daemon stopped"
+        action="Start Docker Desktop"
+      elif printf '%s' "$info" | grep -qi 'permission denied while trying to connect'; then
+        # The usual state of a fresh Docker Engine on Linux: the daemon runs, this user may not use its socket.
+        # Not just "permission denied": an unreadable ~/.docker/config.json (left by `sudo docker login`) also
+        # prints that, whatever the state of the daemon. Docker 24 to 28 say "... to the Docker daemon socket
+        # at", 29 says "... to the docker API at".
+        lines+="[!] No permission to use Docker"
+        action='Add your user to the docker group (sudo usermod -aG docker $USER), then log out and log in again'
+      else
+        lines+="[!] Docker daemon stopped"
+        action="Start the Docker service (for example: sudo systemctl start docker)"
+      fi
+    elif ! docker compose version >/dev/null 2>&1; then
+      lines+="[✓] Docker daemon running"$'\n'"[!] Docker Compose not found"
+      action="Install the Docker Compose plugin (v2) or update Docker Desktop"
+    elif [ "${2:-}" = up ] && ! docker compose up --help 2>/dev/null | grep -q -- '--wait-timeout'; then
+      # bring_up needs `up --wait --wait-timeout`; without this check an older Compose fails there
+      # with "unknown flag" and the user is told that a service is unhealthy.
+      lines+="[✓] Docker daemon running"$'\n'"[!] Docker Compose is too old"
+      action="Update the Docker Compose plugin (v2) or Docker Desktop"
+    elif ! command -v curl >/dev/null 2>&1; then
+      lines+="[✓] Docker daemon running"$'\n'"[✓] Docker Compose available"$'\n'"[!] curl not found"
+      action="Install curl"
+    fi
+  fi
+  [ -n "$action" ] || return 0
+  printf '%s\nAction: %s\nThen run: %s\n' "$lines" "$action" "$1"
+  return 1
+}
+
+# port_in_use P: something already accepts connections on 127.0.0.1:P.
+port_in_use() { (exec 3<>"/dev/tcp/127.0.0.1/$1") 2>/dev/null; }
+
+# port_owned_by_gap P: a container of this project publishes P.
+port_owned_by_gap() {
+  [ -n "$(docker ps -q --filter "label=com.docker.compose.project=$GAP_PROJECT" --filter "publish=$1" 2>/dev/null)" ]
+}
+
+# pick_port [STORED]: keep STORED when it is free or already ours, else the first free port of the
+# range (D9). Fails only when the whole range is taken.
+pick_port() {
+  local p
+  if [ -n "${1:-}" ] && { ! port_in_use "$1" || port_owned_by_gap "$1"; }; then
+    printf '%s' "$1"; return 0
+  fi
+  p=$GAP_PORT_FIRST
+  while [ "$p" -le "$GAP_PORT_LAST" ]; do
+    if ! port_in_use "$p"; then printf '%s' "$p"; return 0; fi
+    p=$((p + 1))
+  done
+  return 1
+}
+
+# svc_state SERVICE: Healthy | Starting | Unhealthy | Restarting | Running | Stopped
+svc_state() {
+  local id
+  id=$(dc ps -aq "$1" 2>/dev/null | head -n 1)
+  [ -n "$id" ] || { printf 'Stopped'; return; }
+  case "$(docker inspect --format '{{.State.Status}}/{{if .State.Health}}{{.State.Health.Status}}{{end}}' "$id" 2>/dev/null)" in
+    running/healthy)   printf 'Healthy' ;;
+    running/starting)  printf 'Starting' ;;
+    running/unhealthy) printf 'Unhealthy' ;;
+    running/)          printf 'Running' ;;
+    restarting/*)      printf 'Restarting' ;;
+    *)                 printf 'Stopped' ;;
+  esac
+}
+
+# http_ok PATH: HTTP 200 from the Admin UI (so through nginx, the path the user takes).
+http_ok() { curl -fsS -o /dev/null -m 5 "$(ui_url)$1" 2>/dev/null; }
+
+# kill_tree PID [SIGNAL]: PID and every process below it, children first (SIGNAL defaults to TERM). A
+# background function runs in a subshell, so killing only that subshell would leave `docker compose`
+# (and the compose plugin it starts) waiting on its own. Without pgrep only PID itself is killed.
+kill_tree() {
+  local child sig="${2:-TERM}"
+  for child in $(pgrep -P "$1" 2>/dev/null); do kill_tree "$child" "$sig"; done
+  kill -s "$sig" "$1" 2>/dev/null
+}
+
+# bring_up: 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.
+bring_up() {
+  local log pid s
+  log=$(mktemp)
+  dc up -d --wait --wait-timeout "$GAP_UP_TIMEOUT" >"$log" 2>&1 &
+  pid=$!
+  while kill -0 "$pid" 2>/dev/null; do
+    for s in postgres kernel admin-ui; do
+      if [ "$(svc_state "$s")" = Restarting ]; then
+        kill_tree "$pid"; wait "$pid" 2>/dev/null
+        warn "$s keeps restarting"
+        printf 'Run: gap logs %s\n' "$s"
+        [ "$s" = kernel ] && printf 'If .env was edited, the database password may no longer match the existing data (see: gap logs postgres).\n'
+        rm -f "$log"; return 1
+      fi
+    done
+    sleep 3
+  done
+  if ! wait "$pid"; then
+    warn "GAP did not start: a service is not healthy"
+    tail -n 5 "$log"
+    printf 'Run: gap logs kernel\n'
+    if [ "$(svc_state kernel)" != Healthy ] && [ "$(svc_state postgres)" = Healthy ]; then
+      printf 'If .env was edited, the database password may no longer match the existing data (see: gap logs postgres).\n'
+    fi
+    rm -f "$log"; return 1
+  fi
+  rm -f "$log"
+}
+
+# launcher_text: the ~/.local/bin/gap launcher. The path is single-quoted for /bin/sh (dash on
+# Debian/Ubuntu does not understand the $'...' that bash's printf %q can produce).
+launcher_text() {
+  local q
+  q=$(printf '%s' "$GAP_HOME/gap" | sed "s/'/'\\\\''/g")
+  printf "#!/bin/sh\n%s\nexec '%s' \"\$@\"\n" "$LAUNCHER_MARK" "$q"
+}
+
+# launcher_is_ours FILE: FILE is a launcher this installer wrote: a regular file (not a symlink) with
+# LAUNCHER_MARK, or the two-line launcher of the first version (78aafa6d), which had no mark:
+# `#!/bin/sh` then `exec <~/.gap/gap quoted by bash's printf %q> "$@"`. The second line is matched
+# against today's %q and, since another bash may quote differently, also against the plain path.
+# Anything else at that path belongs to the user and is never overwritten or removed; a file bigger
+# than a launcher is never read whole.
+launcher_is_ours() {
+  local line2
+  [ -f "$1" ] && [ ! -L "$1" ] || return 1
+  [ "$(($(wc -c < "$1")))" -le 1024 ] || return 1
+  grep -qxF "$LAUNCHER_MARK" "$1" 2>/dev/null && return 0
+  [ "$(($(wc -l < "$1")))" -eq 2 ] && [ "$(head -n 1 "$1")" = '#!/bin/sh' ] || return 1
+  line2=$(sed -n 2p "$1")
+  case "$line2" in 'exec '*' "$@"') ;; *) return 1 ;; esac
+  [ "$line2" = "exec $(printf '%q' "$GAP_HOME/gap") \"\$@\"" ] && return 0
+  case "$line2" in *"$GAP_HOME/gap"*) return 0 ;; esac
+  return 1
+}
+
+# Where a new terminal reads its PATH from, depending on the login shell (install adds the line here).
+# zsh and fish go through shell_startup_file, so that ZDOTDIR and fish's own config file count (fish
+# never reads ~/.profile; it does understand the `export PATH=...` line, checked with fish 4.0).
+rc_files() {
+  case "$(basename "${SHELL:-}")" in
+    zsh|fish) shell_startup_file "$(basename "$SHELL")"; printf '\n' ;;
+    bash) printf '%s\n' "$HOME/.bashrc"; [ "$(uname -s)" = Darwin ] && printf '%s\n' "$HOME/.bash_profile" ;;
+    *)    printf '%s\n' "$HOME/.profile" ;;
+  esac
+}
+
+# --- Does `gap` mean GAP in the user's own terminal? ---------------------------------------------
+# install.sh runs in a shell that never reads the user's startup files, so it cannot see an alias or
+# function called `gap` defined there (oh-my-zsh's git plugin has `alias gap='git apply'`). Such an
+# alias wins over the launcher on the PATH: `gap status` then runs something else and fails with a
+# message about patches. So the installer asks the user's own shell, started the way a terminal
+# window starts it, how it resolves the word `gap`. Like opening a terminal, that runs the user's
+# startup files.
+GAP_PROBE_TIMEOUT=10   # seconds a shell may take to start and answer
+# The same question for every POSIX-like shell (bash, zsh, ksh, dash): alias first, then `command -v`
+# (a path, nothing, or the bare word for a function or builtin). fish has no `command -v` for functions.
+GAP_PROBE_POSIX='if alias gap >/dev/null 2>&1; then printf "GAPPROBE:alias:%s\n" "$(alias gap)"; else r=$(command -v gap 2>/dev/null); case $r in "") printf "GAPPROBE:none:\n";; /*) printf "GAPPROBE:file:%s\n" "$r";; *) printf "GAPPROBE:function:\n";; esac; fi'
+GAP_PROBE_FISH='if functions -q gap; echo GAPPROBE:function:; else if abbr -q gap; echo GAPPROBE:abbr:; else if type -q gap; echo GAPPROBE:file:(type -p gap); else; echo GAPPROBE:none:; end'
+
+# probe_snippet SHELLNAME: the question for that shell. Fails for a shell this does not know.
+probe_snippet() {
+  case "$1" in
+    fish) printf '%s' "$GAP_PROBE_FISH" ;;
+    bash|zsh|ksh|ksh93|mksh|dash|ash|sh) printf '%s' "$GAP_PROBE_POSIX" ;;
+    *) return 1 ;;
+  esac
+}
+
+# probe_shell SHELL: how SHELL (a path) resolves `gap`. Prints alias:DEFINITION (as the shell shows
+# it: `gap='git apply'` in zsh, `alias gap='git apply'` in bash), function, abbr, none, or file:PATH. Prints nothing when it cannot say: a shell this does not know, or one that exits or hangs
+# while starting (killed after GAP_PROBE_TIMEOUT). The shell reads /dev/null and gets no terminal
+# (setsid, or perl where there is no setsid, as on macOS), so that it cannot take the installer's
+# terminal away from it. DISABLE_AUTO_UPDATE keeps an oh-my-zsh from updating itself in this run.
+probe_shell() {
+  local sh="$1" snippet flags=-i out pid dog nap answer
+  local detach=()
+  snippet=$(probe_snippet "$(basename "$sh")") || return 0
+  # A terminal window on macOS starts a login shell; on Linux it usually does not.
+  [ "$(uname -s)" = Darwin ] && flags="-l -i"
+  if command -v setsid >/dev/null 2>&1; then detach=(setsid)
+  elif command -v perl >/dev/null 2>&1; then detach=(perl -MPOSIX -e 'POSIX::setsid(); exec @ARGV' --)
+  else return 0   # an interactive shell on our terminal could keep it, so do not ask at all
+  fi
+  out=$(mktemp) || return 0
+  # $flags is two words on purpose.
+  # shellcheck disable=SC2086
+  ${detach[@]+"${detach[@]}"} env DISABLE_AUTO_UPDATE=true DISABLE_UPDATE_PROMPT=true \
+    "$sh" $flags -c "$snippet" </dev/null >"$out" 2>/dev/null &
+  pid=$!
+  # The shell leads its own session, so -PID is its whole process group, which also catches what
+  # a hung startup file started when there is no pgrep for kill_tree to find it with.
+  ( sleep "$GAP_PROBE_TIMEOUT"; kill_tree "$pid" KILL; kill -s KILL -- "-$pid" ) >/dev/null 2>&1 &
+  dog=$!
+  { wait "$pid"; } 2>/dev/null
+  # The watchdog before its sleep: the other way round it would wake up and still fire, at a probe
+  # that has already finished, at what its startup files left running, or at a reused PID.
+  nap=$(pgrep -P "$dog" 2>/dev/null)
+  kill -s KILL "$dog" 2>/dev/null
+  { wait "$dog"; } 2>/dev/null
+  # shellcheck disable=SC2086
+  [ -z "$nap" ] || kill -s KILL $nap 2>/dev/null
+  # Startup files may print before our line, even without ending theirs with a newline.
+  answer=$(sed -n 's/.*GAPPROBE:\([a-z]*\):\(.*\)$/\1:\2/p' "$out" | head -n 1)
+  rm -f "$out"
+  case "$answer" in
+    alias:*|function:*|abbr:*|none:*|file:?*) printf '%s\n' "${answer%:}" ;;
+  esac
+}
+
+# probe_candidates: the login shell, and the shell install.sh was started from when that is another one.
+probe_candidates() {
+  local login="${SHELL:-}" parent
+  [ -x "$login" ] && printf '%s\n' "$login"
+  parent=$(ps -o comm= -p "$PPID" 2>/dev/null | head -n 1)
+  parent=${parent#-}; parent=${parent##*/}
+  if [ -n "$parent" ] && [ "$parent" != "$(basename "$login")" ] && probe_snippet "$parent" >/dev/null; then
+    command -v "$parent" 2>/dev/null
+  fi
+  return 0
+}
+
+# shell_startup_file SHELLNAME: where a line has to go for a new terminal of that shell to run it.
+# bash on macOS starts as a login shell and reads only the first of ~/.bash_profile, ~/.bash_login and
+# ~/.profile that exists; creating ~/.bash_profile next to a ~/.profile would silence the latter.
+shell_startup_file() {
+  local f
+  case "$1" in
+    zsh)  printf '%s' "${ZDOTDIR:-$HOME}/.zshrc" ;;
+    bash)
+      if [ "$(uname -s)" != Darwin ]; then printf '%s' "$HOME/.bashrc"; return; fi
+      for f in .bash_profile .bash_login .profile; do
+        [ -f "$HOME/$f" ] && { printf '%s' "$HOME/$f"; return; }
+      done
+      printf '%s' "$HOME/.bash_profile" ;;
+    fish) printf '%s' "${XDG_CONFIG_HOME:-$HOME/.config}/fish/config.fish" ;;
+    *)    printf '%s' "$HOME/.profile" ;;
+  esac
+}
+
+# Set by check_gap_resolution, for the summary that install.sh prints after it:
+GAP_CHECK_CMD="gap status"   # what works in a new terminal: gap status, command gap status, or the full path
+GAP_FIX_ADDED=""             # startup files that got the unshadow line in this run
+GAP_NOTES=""                 # lines to print after the summary
+
+# can_ask: the user can answer a question (install.sh runs in a terminal, not from a script or pipe).
+can_ask() { [ -t 0 ]; }
+
+add_note() { GAP_NOTES="$GAP_NOTES$1"$'\n'; }
+
+# prefer_check_cmd CMD: keep the most cautious of GAP_CHECK_CMD and CMD (a full path works everywhere,
+# `command gap` gets past an alias or function, plain `gap` needs neither in the way).
+prefer_check_cmd() {
+  local rank_new rank_old
+  case "$1" in "gap status") rank_new=0 ;; "command gap status") rank_new=1 ;; *) rank_new=2 ;; esac
+  case "$GAP_CHECK_CMD" in "gap status") rank_old=0 ;; "command gap status") rank_old=1 ;; *) rank_old=2 ;; esac
+  [ "$rank_new" -le "$rank_old" ] || GAP_CHECK_CMD=$1
+}
+
+# tilde PATH: PATH with the home folder written as ~, quoted when it is somewhere else.
+tilde() {
+  case "$1" in "$HOME"/*) printf '~%s' "${1#"$HOME"}" ;; *) printf "'%s'" "$1" ;; esac
+}
+
+# unshadow_line SHELLNAME KIND: the line that turns `gap` back into GAP's launcher in that shell.
+unshadow_line() {
+  if [ "$1" != fish ]; then printf '%s' "$RC_UNSHADOW"
+  elif [ "$2" = abbr ]; then printf '%s' "$RC_UNSHADOW_FISH_ABBR"
+  else printf '%s' "$RC_UNSHADOW_FISH"
+  fi
+}
+
+# add_unshadow_line FILE LINE: append RC_MARKER and LINE to FILE, once. remove_rc_lines takes them out
+# again. Whether the line works is up to the caller to check: something read later may set gap again.
+add_unshadow_line() {
+  grep -qxF "$2" "$1" 2>/dev/null && return 0
+  mkdir -p "$(dirname "$1")" 2>/dev/null
+  # In braces: a 2>/dev/null after >> would come too late to hide the shell's own "Permission denied".
+  { printf '\n%s\n%s\n' "$RC_MARKER" "$2" >> "$1"; } 2>/dev/null
+}
+
+# note_answer SHELLNAME ANSWER: the notes for a `gap` that is a program, or that is not found.
+note_answer() {
+  local where="${2#*:}"
+  case "$2" in
+    file:*)
+      [ "$where" -ef "$LAUNCHER_DIR/gap" ] && return 0
+      # The npm channel: `npm install -g` makes <prefix>/bin/gap a symlink to <package>/bin/gap.js (F18, checked on
+      # macOS), and this script runs from <package>/installer.
+      if [ "$(channel)" = npm ] && [ "$where" -ef "$GAP_SRC/../bin/gap.js" ]; then return 0; fi
+      add_note "  Warning: in $1, \"gap\" runs $where (another program), not GAP."
+      if [ "$(channel)" = npm ]; then
+        add_note "  Run GAP with $(gap_script) status, or put npm's global bin folder first on your PATH."
+      else
+        add_note "  Run GAP with $(gap_script) status, or put $LAUNCHER_DIR first on your PATH."
+      fi
+      prefer_check_cmd "$(gap_script) status" ;;
+    none)
+      add_note "  Note: a new $1 terminal does not find \"gap\" on its PATH."
+      if [ "$(channel)" = npm ]; then
+        add_note "  Run GAP with $(gap_script) status, or add npm's global bin folder to your PATH (find it with: npm prefix -g)."
+      else
+        add_note "  Run GAP with $(gap_script) status, or add $LAUNCHER_DIR to your PATH."
+      fi
+      prefer_check_cmd "$(gap_script) status" ;;
+  esac
+}
+
+# offer_unshadow SHELL KIND DEFINITION: `gap` is an alias, function or (fish) abbreviation in SHELL.
+# Says so right away; in a terminal it asks to add the unshadow line to that shell's startup file
+# (Enter means yes), adds it, and asks the shell again to be sure it worked. Without a terminal, or
+# when the answer is no or the line does not help, the notes say how to do it by hand.
+offer_unshadow() {
+  local sh="$1" kind="$2" def="${3#alias }" name file shown line noun a value="" reply again
+  name=$(basename "$sh")
+  file=$(shell_startup_file "$name"); shown=$(tilde "$file")
+  line=$(unshadow_line "$name" "$kind")
+  case "$kind" in
+    alias)
+      noun=alias
+      # The command behind the alias, when it is plainly quoted: gap='git apply' or gap=ls.
+      case "$def" in gap=*) value=${def#gap=} ;; esac
+      case "$value" in \'*\') value=${value#\'}; value=${value%\'} ;; esac
+      case "$value" in *[\'\"\\]*) value="" ;; esac ;;
+    abbr) noun=abbreviation ;;
+    *)    noun="shell function" ;;
+  esac
+  case "$noun" in [aeiou]*) a=an ;; *) a=a ;; esac
+  if [ "$kind" = alias ] && [ -n "$def" ]; then
+    warn "In $name, \"gap\" is already an alias: $def"
+  else
+    warn "In $name, \"gap\" is already $a $noun."
+  fi
+  if [ -n "$value" ]; then printf '    So "gap status" would run "%s status", not GAP.\n' "$value"
+  else printf '    So "gap status" would not run GAP.\n'; fi
+  if can_ask; then
+    printf '    Turn that %s off by adding a line to %s?' "$noun" "$shown"
+    [ -z "$value" ] || printf ' "%s" itself keeps working.' "$value"
+    printf ' [Y/n] '
+    read -r reply || reply=n
+    case "$reply" in
+      ""|[Yy]|[Yy][Ee][Ss])
+        if add_unshadow_line "$file" "$line"; then
+          again=$(probe_shell "$sh")
+          case "$again" in
+            alias*|function|abbr)
+              # The line is in place but something read after it defines gap again (~/.zlogin, a
+              # plugin loaded later): writing it again would not help, so say where to look instead.
+              warn "Added the line to $shown, but a new $name terminal still has its own \"gap\""
+              prefer_check_cmd "command gap status"
+              add_note "  In $name, \"gap\" is defined again after the line in $shown (another startup file"
+              add_note "  or a plugin loaded later). Remove it there to use plain \"gap\"; until then: command gap status"
+              return 0 ;;
+            *)
+              case "$name:$kind" in
+                fish:*)     ok "Added \"$line\" to $shown" ;;
+                *:alias)    ok "Added \"unalias gap\" to $shown" ;;
+                *)          ok "Added \"unset -f gap\" to $shown" ;;
+              esac
+              GAP_FIX_ADDED="$GAP_FIX_ADDED $shown"
+              note_answer "$name" "$again"
+              return 0 ;;
+          esac
+        else
+          warn "Could not write to $shown"
+        fi ;;
+      *) printf '    %s was left unchanged.\n' "$shown" ;;
+    esac
+  fi
+  prefer_check_cmd "command gap status"
+  add_note "  To use plain \"gap\" in $name, run once, then open a new terminal:"
+  add_note "      echo '$line' >> $shown"
+}
+
+# check_gap_resolution: asks each shell of probe_candidates how it resolves `gap`, offers to fix an
+# alias or function in the way (offer_unshadow), and sets GAP_CHECK_CMD, GAP_FIX_ADDED and GAP_NOTES.
+# Returns 1 when no shell could be asked, so that the caller can fall back to what it knows without one.
+# Not to be run in $(...): it asks questions and sets those variables.
+check_gap_resolution() {
+  local sh name answer asked=1 seen=" "
+  # The shells come in on fd 3, so that stdin stays the terminal the questions are read from.
+  while IFS= read -r sh <&3; do
+    name=$(basename "$sh")
+    case "$seen" in *" $name "*) continue ;; esac
+    seen="$seen$name "
+    answer=$(probe_shell "$sh")
+    [ -n "$answer" ] || continue
+    asked=0
+    case "$answer" in
+      alias:*)  offer_unshadow "$sh" alias "${answer#alias:}" ;;
+      function) offer_unshadow "$sh" function "" ;;
+      abbr)     offer_unshadow "$sh" abbr "" ;;
+      *)        note_answer "$name" "$answer" ;;
+    esac
+  done 3< <(probe_candidates)
+  return $asked
+}
+
+# remove_rc_lines: undo what install.sh appended, in every rc file that could hold it (the login
+# shell may have changed since): the blank line, the marker line and the exact line after it (the
+# export line, or one of the RC_UNSHADOW lines).
+# A marker followed by anything else is left alone. The file is rewritten in place (cat >) so that a
+# symlinked dotfile keeps pointing where it did. Prints the files it changed.
+remove_rc_lines() {
+  local rc tmp
+  for rc in "$HOME/.zshrc" "${ZDOTDIR:-$HOME}/.zshrc" "$HOME/.bashrc" "$HOME/.bash_profile" "$HOME/.profile" \
+            "${XDG_CONFIG_HOME:-$HOME/.config}/fish/config.fish"; do
+    [ -f "$rc" ] && grep -qF "$RC_MARKER" "$rc" || continue
+    tmp=$(mktemp) || continue
+    awk -v m="$RC_MARKER" -v e="$RC_EXPORT" -v u1="$RC_UNSHADOW" -v u2="$RC_UNSHADOW_FISH" -v u3="$RC_UNSHADOW_FISH_ABBR" '
+      held  { held = 0; if ($0 == e || $0 == u1 || $0 == u2 || $0 == u3) next; if (hb) print ""; print m }
+      blank { blank = 0; if ($0 == m) { held = 1; hb = 1; next }; print "" }
+      $0 == "" { blank = 1; next }
+      $0 == m  { held = 1; hb = 0; next }
+      { print }
+      END { if (blank) print ""; if (held) { if (hb) print ""; print m } }' "$rc" > "$tmp"
+    if ! cmp -s "$rc" "$tmp"; then cat "$tmp" > "$rc"; printf ' %s' "$rc"; fi
+    rm -f "$tmp"
+  done
+}
+
+open_url() {
+  case "$(uname -s)" in
+    Darwin) open "$1" >/dev/null 2>&1 || true ;;
+    *) if command -v xdg-open >/dev/null 2>&1; then xdg-open "$1" >/dev/null 2>&1 & fi ;;
+  esac
+  return 0
+}
+
+# --- gap version and gap doctor (#1986, #2012) -----------------------------------------------------------------
+# Both only read. doctor never starts, stops or pulls anything, never writes .env, a launcher, a PATH or an rc file: of the
+# functions above it uses none of the ones that write (offer_unshadow, add_unshadow_line, install_launcher, env_set).
+# It does run the user's own shell the way a new terminal starts it (probe_shell), as install.sh does.
+GAP_MIN_NODE_MAJOR=18   # the same number as MIN_NODE_MAJOR in npm/lib/launcher.js, which refuses to start below it
+
+is_installed() { [ -f "$GAP_HOME/.env" ]; }
+
+# cli_version: 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, and the copy of gap in ~/.gap has none.
+cli_version() {
+  [ "$(channel)" = npm ] && [ -f "$GAP_SRC/VERSION" ] || return 0
+  tr -d '[:space:]' < "$GAP_SRC/VERSION"
+}
+
+# installed_version: GAP_VERSION of the install in GAP_HOME. Empty when GAP is not installed; `unknown` when there is an
+# .env that does not say (no number is guessed).
+installed_version() {
+  local v
+  is_installed || return 0
+  v=$(env_get GAP_VERSION)
+  printf '%s' "${v:-unknown}"
+}
+
+# classify_manifest_error TEXT: unauthorized | denied | notfound | network | other, for what `docker manifest inspect`
+# printed (it reads a manifest and downloads no layer). Measured on ghcr.io on 04/11/2026, with no credential at all:
+# `Get "<url>": unauthorized` is a private package, `Get "<url>": denied` is a package that does not exist (or that the
+# caller may not see), `manifest unknown` is a public package without that tag, and `failed to configure transport:
+# error pinging v2 registry: ...` is a registry that did not answer (no such host, connection refused, deadline).
+# With a credential: a token that is revoked or made up prints `Get "<url>": denied: denied`; a valid token that may not
+# read the package prints the single word `denied`, and nothing else; a valid token and a package that does not exist print
+# `manifest unknown`. Anything else falls under `other` and is shown as Docker gave it. The texts differ from the ones of
+# `docker pull` (classify_pull_error): they are not interchangeable. `denied` counts only as the WHOLE text: an unreadable
+# ~/.docker/config.json or the Docker socket also say `permission denied`, which is not the registry.
+classify_manifest_error() {
+  local t
+  t=$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')
+  case "$t" in
+    *'failed to configure transport'*|*'error pinging v2 registry'*|*'failed to do request'*) printf network ;;
+    *'": unauthorized'*)  printf unauthorized ;;
+    *'": denied'*)        printf denied ;;
+    denied)               printf denied ;;   # valid token without the right: the whole text is this word
+    *'manifest unknown'*) printf notfound ;;
+    *)                    printf other ;;
+  esac
+}
+
+DOCTOR_PROBLEMS=0   # `[!]` lines of this run
+DOCTOR_DOCKER=0     # 1 when Docker is ready: what needs it is skipped otherwise
+
+# doctor_problem MESSAGE: a `[!]` line, counted. doctor_unsure 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.
+doctor_problem() { warn "$1"; DOCTOR_PROBLEMS=$((DOCTOR_PROBLEMS + 1)); }
+doctor_unsure() { printf '[?] %s\n' "$1"; }
+
+# doctor_install_hint: the command that installs, in the words of this channel (the ZIP's install.sh is not in ~/.gap).
+doctor_install_hint() {
+  if [ "$(channel)" = npm ]; then printf 'gap install'
+  elif [ -f "$GAP_SRC/install.sh" ]; then printf '%s/install.sh' "$GAP_SRC"
+  else printf 'install.sh (in the GAP installer folder)'; fi
+}
+
+# doctor_node: the npm channel runs on Node, and the launcher has already refused a Node below the minimum, so this only
+# differs when the script is run without it. The ZIP channel does not use Node.
+doctor_node() {
+  local v major
+  if [ "$(channel)" != npm ]; then ok "Node.js is not needed for the ZIP installer"; return 0; fi
+  v=$(node -v 2>/dev/null) || v=""
+  major=${v#v}; major=${major%%.*}
+  case "$major" in
+    ''|*[!0-9]*)
+      doctor_problem "Node.js not found"
+      printf '    Action: install Node.js %s or newer from https://nodejs.org\n' "$GAP_MIN_NODE_MAJOR" ;;
+    *)
+      if [ "$major" -lt "$GAP_MIN_NODE_MAJOR" ]; then
+        doctor_problem "Node.js $v is too old: GAP's npm package needs Node $GAP_MIN_NODE_MAJOR or newer"
+        printf '    Action: install a current Node.js from https://nodejs.org\n'
+      else
+        ok "Node.js $v"
+      fi ;;
+  esac
+}
+
+# doctor_docker: check_prereqs as every command runs it (it prints the failing step and what to do, so it is not repeated
+# here), but a failure does not end doctor: what does not need Docker is still looked at.
+doctor_docker() {
+  if check_prereqs "gap doctor" up; then
+    DOCTOR_DOCKER=1
+    ok "OS: $(os_name)"
+    ok "Docker is ready (daemon running, Compose v2, curl found)"
+  else
+    DOCTOR_DOCKER=0
+    DOCTOR_PROBLEMS=$((DOCTOR_PROBLEMS + 1))
+    if [ "$(channel)" = npm ]; then
+      doctor_unsure "Access to GAP's images and the state of the GAP services were not checked: Docker is not ready"
+    else
+      doctor_unsure "The state of the GAP services was not checked: Docker is not ready"
+    fi
+  fi
+}
+
+# doctor_ports: what `gap install` and `gap start` would find: pick_port itself decides, so the two cannot disagree.
+doctor_ports() {
+  local stored="" port
+  is_installed && stored=$(env_get GAP_UI_PORT)
+  if ! port=$(pick_port "$stored"); then
+    doctor_problem "No free port for the Admin UI"
+    printf '    Action: free a port between %s and %s\n' "$GAP_PORT_FIRST" "$GAP_PORT_LAST"
+    return 0
+  fi
+  if [ -z "$stored" ]; then ok "Port $port is free for the Admin UI"
+  elif [ "$port" != "$stored" ]; then ok "The Admin UI port $stored is used by another program; the next gap start will use $port"
+  elif port_in_use "$stored"; then ok "The Admin UI port $stored is in use by GAP"
+  else ok "The Admin UI port $stored is free"
+  fi
+}
+
+# doctor_other_channel: the npm channel only. A launcher that a ZIP install made may run instead of the npm command. Only
+# reported (install.sh does the same); a ~/.local/bin/gap that is not ours is not our business.
+doctor_other_channel() {
+  [ "$(channel)" = npm ] || return 0
+  launcher_is_ours "$LAUNCHER_DIR/gap" || return 0
+  doctor_problem "$LAUNCHER_DIR/gap is a launcher from a ZIP install of GAP and may run instead of the npm command"
+  printf '    Use one channel per machine; the data is shared. To keep only the npm command: rm %s/gap\n' "$LAUNCHER_DIR"
+}
+
+# doctor_resolution NAME ANSWER: judge one answer of probe_shell about `gap` (alias:DEF, function, abbr, none, file:PATH) in
+# words, and change nothing. NAME is the shell, or "this terminal" when no shell could be asked.
+doctor_resolution() {
+  local name="$1" answer="$2" where="${2#*:}" ours=0 kind file shown line noun dir
+  case "$answer" in
+    file:*)
+      if [ "$(channel)" = npm ]; then
+        [ "$where" -ef "$GAP_SRC/../bin/gap.js" ] && ours=1
+        # A ZIP launcher in front is the one doctor_other_channel has reported already (a file there that is not ours is
+        # another program, judged below).
+        [ "$where" -ef "$LAUNCHER_DIR/gap" ] && launcher_is_ours "$LAUNCHER_DIR/gap" && return 0
+      else
+        [ "$where" -ef "$LAUNCHER_DIR/gap" ] && launcher_is_ours "$LAUNCHER_DIR/gap" && ours=1
+      fi
+      if [ "$ours" = 1 ]; then
+        ok "In $name, \"gap\" runs GAP"
+      else
+        doctor_problem "In $name, \"gap\" runs $where (another program), not GAP"
+        if [ "$(channel)" = npm ]; then printf '    Run GAP with %s status, or put npm'"'"'s global bin folder first on your PATH.\n' "$(gap_script)"
+        else printf '    Run GAP with %s status, or put %s first on your PATH.\n' "$(gap_script)" "$LAUNCHER_DIR"; fi
+      fi ;;
+    none)
+      doctor_problem "In $name, \"gap\" is not found: it is not on the PATH"
+      if [ "$(channel)" = npm ]; then
+        dir=$(npm prefix -g 2>/dev/null)
+        if [ -n "$dir" ]; then printf '    Action: add this folder to your PATH: %s/bin\n' "$dir"
+        else printf '    Action: add npm'"'"'s global bin folder to your PATH (find it with: npm prefix -g)\n'; fi
+      else
+        file=$(shell_startup_file "$(basename "${SHELL:-}")")
+        printf '    Action: add this line to %s:   %s\n' "$(tilde "$file")" "$RC_EXPORT"
+      fi
+      printf '    Until then, run GAP with: %s status\n' "$(gap_script)" ;;
+    alias:*|function|abbr)   # probe_shell prints function and abbr without a colon
+      kind=${answer%%:*}
+      case "$kind" in alias) noun="an alias: ${where#alias }" ;; abbr) noun="an abbreviation" ;; *) noun="a shell function" ;; esac
+      file=$(shell_startup_file "$name"); shown=$(tilde "$file"); line=$(unshadow_line "$name" "$kind")
+      doctor_problem "In $name, \"gap\" is $noun"
+      printf '    So "gap status" would not run GAP. To use plain "gap" in %s, run once, then open a new terminal:\n' "$name"
+      printf "        echo '%s' >> %s\n" "$line" "$shown"
+      printf '    Until then, run: command gap status\n' ;;
+  esac
+}
+
+# doctor_gap_command: does `gap` mean GAP in the user's terminal? Each shell of probe_candidates is asked as install.sh asks
+# it (a new terminal: its startup files run); only when none can be asked is the PATH of this process looked at. A ZIP that is
+# not installed yet is skipped: install.sh puts `gap` on the PATH, and "GAP is not installed" already says to run it.
+doctor_gap_command() {
+  local sh name answer found asked=1 seen=" "
+  [ "$(channel)" = npm ] || is_installed || return 0
+  doctor_other_channel
+  while IFS= read -r sh <&3; do
+    name=$(basename "$sh")
+    case "$seen" in *" $name "*) continue ;; esac
+    seen="$seen$name "
+    answer=$(probe_shell "$sh")
+    [ -n "$answer" ] || continue
+    asked=0
+    doctor_resolution "$name" "$answer"
+  done 3< <(probe_candidates)
+  if [ "$asked" != 0 ]; then
+    found=$(command -v gap 2>/dev/null)
+    case "$found" in /*) answer="file:$found" ;; "") answer=none ;; *) answer=function ;; esac
+    doctor_resolution "this terminal" "$answer"
+  fi
+}
+
+# doctor_join WORDS: the words of a space-separated list, comma-separated.
+doctor_join() { printf '%s' "${1# }" | sed 's/ /, /g'; }
+
+# doctor_registry: 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:
+# Docker stops waiting for an unreachable registry after 30 seconds by itself (measured), once, not three times over.
+# The prefix is the channel's, not .env's (an install by a ZIP left an empty one there).
+REGISTRY_READABLE=0   # set to 1 by doctor_registry when it could read all three images (`gap login` exits 0 only then)
+
+doctor_registry() {
+  local version prefix host tmp i ref kind err refs
+  REGISTRY_READABLE=0
+  local r_unauthorized="" r_denied="" r_notfound="" r_network="" r_other="" other_text=""
+  [ "$(channel)" = npm ] && [ "$DOCTOR_DOCKER" = 1 ] || return 0
+  version=$(cli_version)
+  if [ -z "$version" ]; then doctor_unsure "GAP's images were not checked: this package has no VERSION file"; return 0; fi
+  prefix=$(channel_prefix); host=${prefix%%/*}
+  refs=("$(image_ref "$prefix" gap-kernel "$version")" "$(image_ref "$prefix" gap-admin-ui "$version")" \
+        "$(image_ref "$prefix" gap-postgres 16)")
+  tmp=$(mktemp -d) || { doctor_unsure "GAP's images were not checked: no temporary folder"; return 0; }
+  printf 'Checking access to the image registry...\n'
+  for i in 0 1 2; do
+    ( docker manifest inspect "${refs[$i]}" >/dev/null 2>"$tmp/$i.err"; printf '%s' "$?" > "$tmp/$i.rc" ) &
+  done
+  wait
+  for i in 0 1 2; do
+    [ "$(cat "$tmp/$i.rc" 2>/dev/null)" = 0 ] && continue
+    ref=${refs[$i]}; err=$(cat "$tmp/$i.err" 2>/dev/null)
+    case "$(classify_manifest_error "$err")" in
+      unauthorized) r_unauthorized="$r_unauthorized $ref" ;;
+      denied)       r_denied="$r_denied $ref" ;;
+      notfound)     r_notfound="$r_notfound $ref" ;;
+      network)      r_network="$r_network $ref" ;;
+      *)            r_other="$r_other $ref"; [ -n "$other_text" ] || other_text=$err ;;
+    esac
+  done
+  rm -rf "$tmp"
+  if [ -z "$r_unauthorized$r_denied$r_notfound$r_network$r_other" ]; then
+    ok "You can read GAP's images in $host"
+    REGISTRY_READABLE=1
+    return 0
+  fi
+  if [ -n "$r_unauthorized" ]; then
+    doctor_problem "GAP's images are private and this machine is not logged in to $host"
+    print_login_steps
+  fi
+  if [ -n "$r_denied" ]; then
+    doctor_problem "$host refused access to $(doctor_join "$r_denied")"
+    print_denied_help
+  fi
+  if [ -n "$r_notfound" ]; then
+    doctor_problem "$(doctor_join "$r_notfound") was not found in the registry"
+    printf 'This GAP package is version %s. That version may not be published yet; check the version you were given.\n' "$version"
+  fi
+  if [ -n "$r_network" ]; then
+    doctor_unsure "Could not reach $host: access to $(doctor_join "$r_network") was not checked"
+    printf '    Check your internet connection (and proxy settings). Nothing is wrong with GAP itself.\n'
+  fi
+  if [ -n "$r_other" ]; then
+    doctor_unsure "Could not check access to $(doctor_join "$r_other")"
+    [ -z "$other_text" ] || printf '%s\n' "$other_text" | tail -n 2 | sed 's/^/    /'
+  fi
+}
+
+# doctor_services: the three services, as `gap status` reads them (svc_state), and the Admin UI through its own address.
+doctor_services() {
+  local pg kernel ui pair s state name
+  pg=$(svc_state postgres); kernel=$(svc_state kernel); ui=$(svc_state admin-ui)
+  if [ "$pg$kernel$ui" = StoppedStoppedStopped ]; then
+    doctor_problem "GAP is not running"
+    printf '    Run: gap start\n'
+    return 0
+  fi
+  for pair in "postgres:$pg" "kernel:$kernel" "admin-ui:$ui"; do
+    s=${pair%%:*}; state=${pair#*:}
+    case "$s" in postgres) name=PostgreSQL ;; kernel) name="GAP Kernel" ;; *) name="GAP Admin UI" ;; esac
+    case "$state" in
+      Healthy) ;;
+      Restarting)
+        doctor_problem "$s keeps restarting"
+        printf '    Run: gap logs %s\n' "$s"
+        [ "$s" = kernel ] && printf '    If .env was edited, the database password may no longer match the existing data (see: gap logs postgres).\n' ;;
+      Stopped)
+        doctor_problem "$name is stopped"
+        printf '    Run: gap start\n' ;;
+      Starting)
+        doctor_problem "$name is still starting"
+        printf '    Wait a minute, then run: gap doctor\n' ;;
+      *)
+        doctor_problem "$name is $(printf '%s' "$state" | tr '[:upper:]' '[:lower:]')"
+        printf '    Run: gap logs %s\n' "$s" ;;
+    esac
+  done
+  [ "$pg$kernel$ui" = HealthyHealthyHealthy ] || return 0
+  ok "PostgreSQL, GAP Kernel and GAP Admin UI are healthy"
+  if http_ok /system/health; then ok "The Admin UI answers at $(ui_url)"
+  else
+    doctor_problem "The Admin UI does not answer at $(ui_url)"
+    printf '    Run: gap logs kernel\n'
+  fi
+}
+
+# doctor_install: is GAP installed here, in the version this package expects, and running.
+doctor_install() {
+  local installed pkg
+  if ! is_installed; then
+    if [ "$DOCTOR_DOCKER" = 1 ] && docker volume inspect "${GAP_PROJECT}_pgdata" >/dev/null 2>&1; then
+      doctor_problem "GAP is not installed here, but data from an earlier install is in the Docker volume ${GAP_PROJECT}_pgdata"
+      printf '    Run: %s  (it keeps that data)\n' "$(doctor_install_hint)"
+    else
+      doctor_problem "GAP is not installed in $GAP_HOME"
+      printf '    Run: %s\n' "$(doctor_install_hint)"
+    fi
+    return 0
+  fi
+  installed=$(installed_version); pkg=$(cli_version)
+  if [ "$installed" = unknown ]; then
+    doctor_problem "GAP_VERSION is missing from $GAP_HOME/.env"
+    printf '    Run: %s\n' "$(doctor_install_hint)"
+  else
+    ok "GAP $installed is installed in $GAP_HOME"
+    if [ -n "$pkg" ] && [ "$pkg" != "$installed" ]; then
+      doctor_problem "The installed version ($installed) is not the version of this package ($pkg)"
+      if package_is_newer; then printf '    Run: gap update  (it backs up first)\n'
+      elif package_is_older; then printf '    Install the newer package: npm install -g @atomiton-dev/gap-cli@latest\n'
+      else printf '    Run: %s\n' "$(doctor_install_hint)"; fi
+    fi
+  fi
+  if [ ! -f "$GAP_HOME/docker-compose.yml" ]; then
+    doctor_problem "docker-compose.yml is missing in $GAP_HOME"
+    printf '    Run: %s again to put it back\n' "$(doctor_install_hint)"
+    return 0
+  fi
+  [ "$DOCTOR_DOCKER" = 1 ] || return 0
+  doctor_services
+}
+
+# --- gap update (#1986, #2014) ----------------------------------------------------------------------------------
+# `gap install` run again on a newer package already moves the version; `gap update` is that move with the guards of the
+# issue: npm channel only, versions compared as numbers, no step back, pull first, then a checked backup, then the stack.
+
+# put_file SRC DEST MODE: replace DEST in one rename, so that a `gap` that is running right now keeps reading its old
+# copy instead of a half-written one. (install.sh and `gap update`.)
+put_file() {
+  cp "$1" "$2.new" && chmod "$3" "$2.new" && mv -f "$2.new" "$2"
+}
+
+# health_checks: the Admin UI answers on /health, /system/health and / (the path the user will take), for up to ~30 seconds
+# each. Returns 1 after saying which one did not. (install.sh and `gap update`.)
+health_checks() {
+  local p tries
+  for p in /health /system/health /; do
+    tries=0
+    until http_ok "$p"; do
+      tries=$((tries + 1))
+      if [ "$tries" -ge 15 ]; then
+        warn "Health check failed: $(ui_url)$p"
+        printf 'Run: gap logs kernel\n'
+        return 1
+      fi
+      sleep 2
+    done
+  done
+}
+
+# version_cmp A B: prints -1, 0 or 1 (A older than, equal to, newer than B) and returns 0; prints nothing and returns 2 when it
+# cannot tell. Only `major.minor.patch` with an optional `-suffix` is read; the three numbers are compared as numbers (0.10.0
+# is newer than 0.9.0; a leading zero is not octal) and the suffix has to be the same on both sides (the repo has `-mvp`; a
+# comparison of `-mvp` with `-rc1` would be a guess). Numbers longer than nine digits are refused: shell arithmetic would wrap.
+VERSION_RE='^([0-9]{1,9})\.([0-9]{1,9})\.([0-9]{1,9})(-[[:alnum:]._-]+)?$'
+version_cmp() {
+  local a1 a2 a3 sa b1 b2 b3 sb x y i
+  [[ "$1" =~ $VERSION_RE ]] || return 2
+  a1=${BASH_REMATCH[1]}; a2=${BASH_REMATCH[2]}; a3=${BASH_REMATCH[3]}; sa=${BASH_REMATCH[4]}
+  [[ "$2" =~ $VERSION_RE ]] || return 2
+  b1=${BASH_REMATCH[1]}; b2=${BASH_REMATCH[2]}; b3=${BASH_REMATCH[3]}; sb=${BASH_REMATCH[4]}
+  [ "$sa" = "$sb" ] || return 2
+  for i in 1 2 3; do
+    eval "x=\$a$i y=\$b$i"
+    if [ $((10#$x)) -gt $((10#$y)) ]; then printf 1; return 0; fi
+    if [ $((10#$x)) -lt $((10#$y)) ]; then printf -- -1; return 0; fi
+  done
+  printf 0
+}
+
+# package_is_newer: the npm package that runs this script is newer than the installed GAP, by numbers. Says nothing and fails
+# when the versions are equal, the package is older, they cannot be compared, or this is the ZIP channel.
+package_is_newer() {
+  local pkg installed
+  [ "$(channel)" = npm ] || return 1
+  pkg=$(cli_version); installed=$(installed_version)
+  [ -n "$pkg" ] && [ -n "$installed" ] || return 1
+  [ "$(version_cmp "$installed" "$pkg" 2>/dev/null)" = -1 ]
+}
+
+# package_is_older: the mirror of package_is_newer (`gap install` and `gap update` refuse to go back to it).
+package_is_older() {
+  local pkg installed
+  [ "$(channel)" = npm ] || return 1
+  pkg=$(cli_version); installed=$(installed_version)
+  [ -n "$pkg" ] && [ -n "$installed" ] || return 1
+  [ "$(version_cmp "$installed" "$pkg" 2>/dev/null)" = 1 ]
+}
+
+# older_package_help: what to say to a user whose npm package is older than the installed GAP.
+older_package_help() {
+  printf '    gap does not go back: what a newer version did to the database cannot be undone.\n'
+  printf '    Install the newer package first: npm install -g @atomiton-dev/gap-cli@latest\n'
+}
+
+# newer_package_note: one line for `gap status` and `gap start`.
+newer_package_note() {
+  package_is_newer || return 0
+  printf 'A newer version (%s) is in the npm package. Run: gap update\n' "$(cli_version)"
+}
+
+# The backup of `gap update`. It is what spike S4 ran for real: `pg_dumpall` for every database (the Kernel creates one per
+# tenant), `tar` of the volume gap_data (the app files the user may have edited: src/, be/, fe/), both through the old images.
+# Plus the old .env and compose file, because the update replaces the compose file and a restore of the OLD version needs the
+# old one (and the old password and version). Nothing here is deleted afterwards.
+BACKUP_DIR=""
+PG_DUMP_END='-- PostgreSQL database cluster dump complete'
+BACKUP_SPACE_MARGIN_PERCENT=5
+
+# backup_fail MESSAGE [LINE...]: say what is wrong, remove what this backup wrote, return 1.
+backup_fail() {
+  warn "$1"; shift
+  local line
+  for line in "$@"; do [ -z "$line" ] || printf '%s\n' "$line"; done
+  [ -z "$BACKUP_DIR" ] || rm -rf "$BACKUP_DIR"
+  BACKUP_DIR=""
+  printf 'Nothing was changed in GAP: the version, .env and your data are as they were.\n'
+  return 1
+}
+
+# pg_size_kb / data_size_kb: kilobytes the database and the gap_data volume take (empty when they cannot be measured).
+pg_size_kb() {
+  dc exec -T postgres du -sk /var/lib/postgresql/data </dev/null 2>/dev/null | awk 'NR == 1 && $1 ~ /^[0-9]+$/ { print $1 }'
+}
+data_size_kb() {
+  dc run --rm --no-deps -T --entrypoint du kernel -sk /data </dev/null 2>/dev/null | awk 'END { if ($1 ~ /^[0-9]+$/) print $1 }'
+}
+free_kb() { df -Pk "$1" 2>/dev/null | awk 'NR == 2 && $4 ~ /^[0-9]+$/ { print $4 }'; }
+
+# dump_is_whole FILE: a readable gzip whose text ends with the line pg_dumpall writes last. An empty or cut dump fails here.
+dump_is_whole() {
+  [ -s "$1" ] && gzip -t "$1" 2>/dev/null && gzip -dc "$1" 2>/dev/null | tail -n 5 | grep -qxF -- "$PG_DUMP_END"
+}
+# archive_is_whole FILE: a readable gzip that tar lists with at least one entry. GNU tar says nothing and exits 0 for a gzip
+# that holds no tar at all (and for an empty one), so the exit status alone is not a check; a real backup of the app files
+# always has the entry "./", even when the volume is empty.
+archive_is_whole() {
+  local st
+  [ -s "$1" ] && gzip -t "$1" 2>/dev/null || return 1
+  tar -tzf "$1" 2>/dev/null | awk 'END { exit NR == 0 }'
+  st=("${PIPESTATUS[@]}")
+  [ "${st[0]}" = 0 ] && [ "${st[1]}" = 0 ]
+}
+
+# make_backup: sets BACKUP_DIR (<GAP_HOME>/backups/<UTC time>, 700, files 600) and returns 0, or returns 1 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
+# BACKUP_SPACE_MARGIN_PERCENT 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.
+make_backup() {
+  local root="$GAP_HOME/backups" dir final pg_kb data_kb need_kb free st err rc
+  if [ "$(svc_state postgres)" != Healthy ]; then
+    printf 'Starting the database for the backup...\n'
+    dc up -d --wait --wait-timeout 120 postgres >/dev/null 2>&1 \
+      || { backup_fail "The database did not start, so it cannot be backed up" "Run: gap logs postgres"; return 1; }
+  fi
+  [ -d "$root" ] || mkdir -m 700 "$root" 2>/dev/null || { backup_fail "Cannot create $root" "Check the permissions of $GAP_HOME."; return 1; }
+  chmod 700 "$root" 2>/dev/null
+  pg_kb=$(pg_size_kb); data_kb=$(data_size_kb); free=$(free_kb "$root")
+  if [ -n "$pg_kb" ] && [ -n "$data_kb" ] && [ -n "$free" ]; then
+    need_kb=$(( (pg_kb + data_kb) * (100 + BACKUP_SPACE_MARGIN_PERCENT) / 100 ))
+    if [ "$free" -lt "$need_kb" ]; then
+      backup_fail "Not enough free space for the backup" \
+        "About $(( (need_kb + 1023) / 1024 )) MB are needed (the database and the app files), $(( free / 1024 )) MB are free in $root." \
+        "Free some space, then run: gap update"
+      return 1
+    fi
+  else
+    printf '[?] The free space needed for the backup could not be measured; the backup is checked when it is done\n'
+  fi
+  # 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.
+  final="$root/$(date -u +%Y%m%dT%H%M%SZ)"
+  dir="$final.partial"
+  mkdir -m 700 "$dir" 2>/dev/null || { backup_fail "Cannot create $dir"; return 1; }
+  BACKUP_DIR="$dir"
+  printf 'Backing up the database...\n'
+  dc exec -T postgres pg_dumpall -U postgres </dev/null 2>"$dir/.err" | gzip > "$dir/db.sql.gz"
+  st=("${PIPESTATUS[@]}")
+  chmod 600 "$dir/db.sql.gz" 2>/dev/null
+  if [ "${st[0]}" != 0 ] || [ "${st[1]}" != 0 ]; then
+    err=$(tail -n 3 "$dir/.err" 2>/dev/null)
+    backup_fail "The backup of the database failed" "$err"; return 1
+  fi
+  dump_is_whole "$dir/db.sql.gz" || { backup_fail "The backup of the database is empty or cut short"; return 1; }
+  printf 'Backing up the app files (volume %s_data)...\n' "$GAP_PROJECT"
+  dc run --rm --no-deps -T --entrypoint tar kernel -czf - -C /data . </dev/null 2>"$dir/.err" > "$dir/data.tar.gz"
+  rc=$?
+  chmod 600 "$dir/data.tar.gz" 2>/dev/null
+  if [ "$rc" != 0 ]; then
+    err=$(tail -n 3 "$dir/.err" 2>/dev/null)
+    # tar says 1 when a file changed while it was read: the Kernel was writing. Nothing is wrong with the data.
+    backup_fail "The backup of the app files failed" "$err" "If GAP was busy, run: gap stop   and then: gap update"; return 1
+  fi
+  archive_is_whole "$dir/data.tar.gz" || { backup_fail "The backup of the app files is empty or unreadable"; return 1; }
+  cp "$GAP_HOME/.env" "$dir/.env" && cp "$GAP_HOME/docker-compose.yml" "$dir/docker-compose.yml" \
+    || { backup_fail "Could not copy .env and the compose file into the backup"; return 1; }
+  chmod 600 "$dir/.env" "$dir/docker-compose.yml"
+  rm -f "$dir/.err"
+  mv "$dir" "$final" || { backup_fail "Could not finish the backup folder $final"; return 1; }
+  BACKUP_DIR="$final"
+}
+
+# print_restore_help BACKUP_DIR OLD_VERSION: how to go back to OLD_VERSION with the data of the backup. These are the commands
+# that spike S4 ran for real (plus the copy of .env and the compose file of the backup, which the update had replaced).
+# Three things S4 found are said here: 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.
+# Nothing is run; the paths are written in full and quoted, so that the lines can be pasted in any shell.
+# print_files_back_help BACKUP_DIR: the two lines that put the old .env and compose file back (the first two of the restore).
+print_files_back_help() {
+  printf '  cp "%s/.env" "%s/.env"\n' "$1" "$GAP_HOME"
+  printf '  cp "%s/docker-compose.yml" "%s/docker-compose.yml"\n' "$1" "$GAP_HOME"
+}
+
+print_restore_help() {
+  local b="$1" h="$GAP_HOME" dcx
+  dcx="docker compose -p $GAP_PROJECT --project-directory \"$h\" -f \"$h/docker-compose.yml\" --env-file \"$h/.env\""
+  printf '\nTo go back to GAP %s with the data of the backup (this erases the current database and app files first, because\n' "$2"
+  printf 'the new version may already have changed them; a restore over existing data would duplicate rows):\n'
+  print_files_back_help "$b"
+  printf '  %s down -v\n' "$dcx"
+  printf '  %s up -d --wait postgres\n' "$dcx"
+  printf '  gunzip -c "%s/db.sql.gz" | %s exec -T postgres psql -U postgres -q\n' "$b" "$dcx"
+  printf '  cat "%s/data.tar.gz" | %s run --rm --no-deps -T --entrypoint tar kernel -xzf - -C /data\n' "$b" "$dcx"
+  printf '  gap start\n'
+  printf 'Do not add psql'"'"'s ON_ERROR_STOP: the restore prints exactly one error, `role "postgres" already exists`, and that is\n'
+  printf 'expected (and a few small `set_config` tables, which are normal). The images of %s are still on this machine.\n' "$2"
+}