@danolez/docker-util 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fatunmbi Daniel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# docker-util
+
+Small interactive helpers for people who run a lot of Docker Compose stacks
+on one machine. You pick projects from a list instead of typing names, and
+anything that is still running is left alone.
+
+```
+docker-list    Show compose projects and containers outside compose
+docker-stop    Pick running compose projects to stop, then pick which to delete
+docker-prune   Clean stopped containers, unused images, volumes and build cache
+docker-help    Show the command list
+```
+
+## Install
+
+Run it once without installing:
+
+```sh
+npx @danolez/docker-util list
+npx @danolez/docker-util stop
+npx @danolez/docker-util prune --dry-run
+```
+
+Or install it so the `docker-*` commands are on your PATH:
+
+```sh
+npm install -g @danolez/docker-util
+```
+
+Straight from GitHub works too, no registry needed:
+
+```sh
+npx github:danolez1/docker-util help
+```
+
+Works on macOS and Linux. It needs `bash` (the 3.2 that ships with macOS is
+fine) and the `docker` CLI. Node is only used to install it.
+
+## Picking things
+
+Every choice is a menu. Nothing asks you to type a name or a number.
+
+The tool uses [fzf](https://github.com/junegunn/fzf) if it is installed, then
+[gum](https://github.com/charmbracelet/gum), and otherwise falls back to its
+own arrow-key menu:
+
+| key | action |
+| --- | --- |
+| up / down (or k / j) | move |
+| space | mark or unmark (multi-select menus) |
+| enter | confirm |
+| q or esc | abort, nothing is changed |
+
+In fzf and gum, multi-select menus start with a `(none)` row. Confirm on it
+to pick nothing. Yes/No questions default to No.
+
+Force a picker with `DOCKER_UTIL_PICKER=fzf|gum|builtin`.
+
+## docker-stop
+
+1. Lists every compose project with at least one running container. Mark the
+   ones to stop.
+2. Stops them, then lists the same projects again so you can mark which ones
+   to delete. Deleting removes their containers and networks.
+3. If you deleted anything, asks whether to keep or delete the project
+   volumes. Keeping them is the first option.
+
+`docker-stop --dry-run` shows the commands without running them.
+
+## docker-prune
+
+Removes stopped containers, unused images, anonymous volumes and dangling
+build cache. Compose projects with a running container are always kept, and
+so are the images they use.
+
+Before removing anything it asks:
+
+- which stopped compose projects to keep,
+- which unused named volumes to delete (none by default, since fixed-name
+  volumes often hold data you care about),
+- whether to go ahead with the plan it prints.
+
+```
+-n, --dry-run            Show what would be removed, remove nothing
+-y, --yes                Skip prompts: remove all stopped projects, keep all named volumes
+    --keep-image REGEX   Never remove images whose repo:tag matches REGEX (repeatable)
+    --cache-cap SIZE     Build cache to keep, e.g. 10GB (default 20GB)
+    --tmp-prefix PREFIX  Also delete $TMPDIR/PREFIX* dirs older than 24h (repeatable)
+    --no-mole            Do not offer 'mo clean' afterwards
+```
+
+If [Mole](https://github.com/tw93/Mole) is installed, it offers to run
+`mo clean` at the end.
+
+### Config
+
+Defaults can live in `~/.config/docker-util/config` (or `$DOCKER_UTIL_CONFIG`).
+It is plain shell:
+
+```sh
+# Images you can't pull again, e.g. mirrors of deleted upstream tags
+KEEP_IMAGE_PATTERN='^(registry\.example\.com/|myorg/)'
+CACHE_CAP=20GB
+# Scratch dirs your test suites leave in $TMPDIR
+TMP_PREFIXES="myapp-test- e2e-run-"
+TMP_MAX_AGE_MIN=1440
+```
+
+`DOCKER_UTIL_KEEP_IMAGES`, `DOCKER_UTIL_CACHE_CAP` and
+`DOCKER_UTIL_TMP_PREFIXES` override the file, and flags override both.
+
+## Development
+
+```sh
+npm test       # runs test/run.sh against a stub docker, no daemon needed
+npm run lint   # shellcheck
+```
+
+## License
+
+MIT

package/bin/docker-help

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+self="$0"
+while [ -L "$self" ]; do
+  link=$(readlink "$self")
+  case "$link" in /*) self="$link" ;; *) self="$(dirname "$self")/$link" ;; esac
+done
+# shellcheck source=../lib/common.sh
+. "$(dirname "$self")/../lib/common.sh"
+
+case "${1:-}" in -v|--version) echo "$DOCKER_UTIL_VERSION"; exit 0 ;; esac
+
+cat <<EOF
+docker-util $DOCKER_UTIL_VERSION
+
+  docker-list    Show compose projects and containers outside compose
+  docker-stop    Pick running compose projects to stop, then pick which to delete
+  docker-prune   Clean stopped containers, unused images, volumes and build cache
+                 (running compose projects are never touched)
+  docker-help    Show this list
+
+Each command also runs as 'docker-util <list|stop|prune|help>'.
+Add --help to any command for its options. --dry-run works on stop and prune.
+
+Picker in use: $(picker) (fzf, then gum, then a built-in arrow-key menu)
+EOF

package/bin/docker-list

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Compose projects and loose containers at a glance.
+set -uo pipefail
+
+self="$0"
+while [ -L "$self" ]; do
+  link=$(readlink "$self")
+  case "$link" in /*) self="$link" ;; *) self="$(dirname "$self")/$link" ;; esac
+done
+# shellcheck source=../lib/common.sh
+. "$(dirname "$self")/../lib/common.sh"
+
+case "${1:-}" in
+  "") ;;
+  -h|--help)
+    cat <<EOF
+docker-list $DOCKER_UTIL_VERSION
+Show compose projects (running, stopped, partial) and containers outside compose.
+
+Usage: docker-list
+EOF
+    exit 0 ;;
+  -v|--version) echo "$DOCKER_UTIL_VERSION"; exit 0 ;;
+  *) echo "docker-list: unknown option '$1'" >&2; exit 2 ;;
+esac
+
+require_docker
+
+rows=$(docker ps -a --format '{{.Label "com.docker.compose.project"}}	{{.State}}	{{.Names}}	{{.Image}}	{{.Status}}')
+
+bold "Compose projects"
+printf '%s\n' "$rows" | awk -F'\t' '
+  $1 != "" {
+    total[$1]++
+    if ($2 == "running") up[$1]++
+  }
+  END {
+    n = 0
+    for (p in total) {
+      if (up[p] == total[p]) state = "running"
+      else if (up[p] > 0) state = "partial"
+      else state = "stopped"
+      printf "  %-32s %-8s %d/%d up\n", p, state, up[p], total[p]
+      n++
+    }
+    if (n == 0) print "  none"
+  }' | sort
+
+echo
+bold "Containers outside compose"
+printf '%s\n' "$rows" | awk -F'\t' '
+  $1 == "" && $3 != "" { printf "  %-32s %-8s %-30s %s\n", $3, $2, $4, $5; n++ }
+  END { if (n == 0) print "  none" }'

package/bin/docker-prune

@@ -0,0 +1,188 @@
+#!/usr/bin/env bash
+# Interactive Docker cleanup that never touches running compose stacks.
+set -uo pipefail
+
+self="$0"
+while [ -L "$self" ]; do
+  link=$(readlink "$self")
+  case "$link" in /*) self="$link" ;; *) self="$(dirname "$self")/$link" ;; esac
+done
+# shellcheck source=../lib/common.sh
+. "$(dirname "$self")/../lib/common.sh"
+
+CONFIG_FILE="${DOCKER_UTIL_CONFIG:-${XDG_CONFIG_HOME:-$HOME/.config}/docker-util/config}"
+KEEP_IMAGE_PATTERN=""
+CACHE_CAP="20GB"
+TMP_PREFIXES=""
+TMP_MAX_AGE_MIN=1440
+MOLE=1
+
+# shellcheck source=/dev/null
+[ -f "$CONFIG_FILE" ] && . "$CONFIG_FILE"
+KEEP_IMAGE_PATTERN="${DOCKER_UTIL_KEEP_IMAGES:-$KEEP_IMAGE_PATTERN}"
+CACHE_CAP="${DOCKER_UTIL_CACHE_CAP:-$CACHE_CAP}"
+TMP_PREFIXES="${DOCKER_UTIL_TMP_PREFIXES:-$TMP_PREFIXES}"
+
+usage() {
+  cat <<EOF
+docker-prune $DOCKER_UTIL_VERSION
+Clean up stopped containers, unused images, volumes and build cache
+without touching running compose projects.
+
+Usage: docker-prune [options]
+
+Options:
+  -n, --dry-run            Show what would be removed, remove nothing
+  -y, --yes                Skip prompts: remove all stopped projects, keep all named volumes
+      --keep-image REGEX   Never remove images whose repo:tag matches REGEX (repeatable)
+      --cache-cap SIZE     Build cache to keep, e.g. 10GB (default: $CACHE_CAP)
+      --tmp-prefix PREFIX  Also delete \$TMPDIR/PREFIX* dirs older than 24h (repeatable)
+      --no-mole            Do not offer 'mo clean' afterwards
+  -h, --help               Show this help
+  -v, --version            Show version
+
+Config file: $CONFIG_FILE
+EOF
+}
+
+add_pattern() { KEEP_IMAGE_PATTERN="${KEEP_IMAGE_PATTERN:+$KEEP_IMAGE_PATTERN|}$1"; }
+need_arg() { [ -n "${2:-}" ] || { echo "docker-prune: $1 needs a value" >&2; exit 2; }; }
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -n|--dry-run) DRY_RUN=1 ;;
+    -y|--yes) ASSUME_YES=1 ;;
+    --keep-image) need_arg "$1" "${2:-}"; add_pattern "$2"; shift ;;
+    --keep-image=*) add_pattern "${1#*=}" ;;
+    --cache-cap) need_arg "$1" "${2:-}"; CACHE_CAP="$2"; shift ;;
+    --cache-cap=*) CACHE_CAP="${1#*=}" ;;
+    --tmp-prefix) need_arg "$1" "${2:-}"; TMP_PREFIXES="$TMP_PREFIXES $2"; shift ;;
+    --tmp-prefix=*) TMP_PREFIXES="$TMP_PREFIXES ${1#*=}" ;;
+    --no-mole) MOLE=0 ;;
+    -h|--help) usage; exit 0 ;;
+    -v|--version) echo "$DOCKER_UTIL_VERSION"; exit 0 ;;
+    *) echo "docker-prune: unknown option '$1'" >&2; usage >&2; exit 2 ;;
+  esac
+  shift
+done
+
+aborted() { echo "Aborted, nothing removed." >&2; exit 130; }
+
+require_docker
+
+bold "Docker usage before"
+docker system df
+
+running_projects=$(compose_projects)
+all_projects=$(compose_projects -a)
+stopped_projects=$(comm -23 <(printf '%s\n' "$all_projects") <(printf '%s\n' "$running_projects"))
+
+echo
+bold "Running compose projects (always kept)"
+# shellcheck disable=SC2086
+printf '  %s\n' ${running_projects:-none}
+
+kept_projects=""
+if [ -n "$stopped_projects" ]; then
+  echo
+  kept_projects=$(pick_many "Stopped compose projects to KEEP" "$stopped_projects") || aborted
+fi
+protected_projects=$(printf '%s\n%s\n' "$running_projects" "$kept_projects" | sed '/^$/d' | sort -u)
+doomed_projects=$(comm -23 <(printf '%s\n' "$stopped_projects" | sed '/^$/d') <(printf '%s\n' "$protected_projects"))
+
+doomed_containers=""
+while IFS=$'\t' read -r id name project; do
+  [ -z "$id" ] && continue
+  [ -n "$project" ] && in_list "$project" "$protected_projects" && continue
+  doomed_containers+="$id	$name	${project:-(no compose project)}"$'\n'
+done < <(docker ps -a --filter status=exited --filter status=created --filter status=dead \
+  --format '{{.ID}}\t{{.Names}}\t{{.Label "com.docker.compose.project"}}')
+
+container_ids=$(printf '%s' "$doomed_containers" | cut -f1 | sed '/^$/d')
+# Named volumes are only deleted when picked; fixed-name ones can hold backups.
+unused_volumes=""
+while IFS= read -r vol; do
+  [ -z "$vol" ] && continue
+  # Anonymous volumes are handled by `volume prune` below.
+  [[ "$vol" =~ ^[0-9a-f]{64}$ ]] && continue
+  users=$(docker ps -aq --filter volume="$vol" | grep -vxF -f <(printf '%s\n' "$container_ids"))
+  [ -z "$users" ] && unused_volumes+="$vol"$'\n'
+done < <(docker volume ls --format '{{.Name}}')
+unused_volumes=$(printf '%s' "$unused_volumes" | sed '/^$/d')
+
+doomed_volumes=""
+if [ -n "$unused_volumes" ]; then
+  echo
+  doomed_volumes=$(pick_many "Unused named volumes to DELETE (may be backups)" "$unused_volumes") || aborted
+fi
+
+echo
+bold "Plan"
+echo "Stopped projects to remove:"
+# shellcheck disable=SC2086
+printf '  %s\n' ${doomed_projects:-none}
+echo "Stopped containers to remove:"
+printf '%s' "${doomed_containers:-  none
+}" | awk -F'\t' 'NF>1 {printf "  %s (%s)\n", $2, $3} NF<=1 {print}'
+echo "Named volumes to remove:"
+# shellcheck disable=SC2086
+printf '  %s\n' ${doomed_volumes:-none}
+echo "Also: anonymous unused volumes, dangling images, unused images"
+echo "      (except images of kept projects${KEEP_IMAGE_PATTERN:+ and $KEEP_IMAGE_PATTERN}),"
+echo "      build cache trimmed to $CACHE_CAP."
+[ -n "${TMP_PREFIXES// /}" ] && echo "      \$TMPDIR dirs older than ${TMP_MAX_AGE_MIN}m matching:$TMP_PREFIXES"
+
+if [ "$DRY_RUN" = 0 ] && ! confirm "Proceed?"; then
+  echo "Nothing removed."
+  exit 0
+fi
+
+echo
+bold "Removing"
+# shellcheck disable=SC2086
+[ -n "$container_ids" ] && run docker rm -v $container_ids >/dev/null
+for vol in $doomed_volumes; do
+  run docker volume rm "$vol" >/dev/null
+done
+run docker volume prune -f
+
+# Containers pending removal are excluded so a dry run lists the same images a real run removes.
+used_images=$(docker ps -aq | grep -vxF -f <(printf '%s\n' "$container_ids") |
+  xargs docker inspect 2>/dev/null --format '{{.Image}}' | sort -u)
+while IFS=$'\t' read -r id ref; do
+  [ -z "$id" ] && continue
+  in_list "$id" "$used_images" && continue
+  # An empty regex matches everything, so it must mean "keep nothing extra".
+  [ -n "$KEEP_IMAGE_PATTERN" ] && [[ "$ref" =~ $KEEP_IMAGE_PATTERN ]] && continue
+  [ "$ref" = "<none>:<none>" ] && continue
+  # Digest-pinned pulls have no tag, so only their ID addresses them.
+  [[ "$ref" == *:"<none>" ]] && ref="$id"
+  run docker image rm "$ref" >/dev/null 2>&1
+done < <(docker image ls --no-trunc --format '{{.ID}}\t{{.Repository}}:{{.Tag}}')
+run docker image prune -f >/dev/null
+
+# --keep-storage was renamed to --max-used-space in newer buildx.
+if docker builder prune --help 2>&1 | grep -q -- --max-used-space; then
+  run docker builder prune -af --max-used-space "$CACHE_CAP"
+else
+  run docker builder prune -af --keep-storage "$CACHE_CAP"
+fi
+
+tmp_root="${TMPDIR:-/tmp}"
+for prefix in $TMP_PREFIXES; do
+  find "$tmp_root" -maxdepth 1 -type d -name "${prefix}*" -mmin +"$TMP_MAX_AGE_MIN" -print0 2>/dev/null |
+    while IFS= read -r -d '' dir; do run rm -rf "$dir"; done
+done
+
+echo
+bold "Docker usage after"
+docker system df
+
+if [ "$MOLE" = 1 ] && command -v mo >/dev/null 2>&1; then
+  echo
+  if [ "$DRY_RUN" = 1 ]; then
+    dim "  would offer: mo clean (macOS caches, logs, temp)"
+  elif [ "$ASSUME_YES" = 0 ] && confirm "Also clean macOS caches and temp with Mole (mo clean)?"; then
+    mo clean
+  fi
+fi

package/bin/docker-stop

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# Stop running compose projects picked from a list, then optionally delete them.
+set -uo pipefail
+
+self="$0"
+while [ -L "$self" ]; do
+  link=$(readlink "$self")
+  case "$link" in /*) self="$link" ;; *) self="$(dirname "$self")/$link" ;; esac
+done
+# shellcheck source=../lib/common.sh
+. "$(dirname "$self")/../lib/common.sh"
+
+usage() {
+  cat <<EOF
+docker-stop $DOCKER_UTIL_VERSION
+Pick running compose projects to stop, then pick which of those to delete.
+
+Usage: docker-stop [options]
+
+Options:
+  -n, --dry-run   Show what would happen, change nothing
+  -h, --help      Show this help
+  -v, --version   Show version
+EOF
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -n|--dry-run) DRY_RUN=1 ;;
+    -h|--help) usage; exit 0 ;;
+    -v|--version) echo "$DOCKER_UTIL_VERSION"; exit 0 ;;
+    *) echo "docker-stop: unknown option '$1'" >&2; usage >&2; exit 2 ;;
+  esac
+  shift
+done
+
+aborted() { echo "Aborted, nothing $1." >&2; exit 130; }
+by_project() { printf 'label=com.docker.compose.project=%s' "$1"; }
+
+require_docker
+
+running=$(compose_projects)
+if [ -z "$running" ]; then
+  echo "No running compose projects."
+  exit 0
+fi
+
+chosen=$(pick_many "Compose projects to STOP" "$running") || aborted "stopped"
+if [ -z "$chosen" ]; then
+  echo "Nothing stopped."
+  exit 0
+fi
+
+bold "Stopping"
+for project in $chosen; do
+  echo "  $project"
+  # shellcheck disable=SC2046
+  run docker stop $(docker ps -q --filter "$(by_project "$project")") >/dev/null
+done
+
+echo
+doomed=$(pick_many "Stopped projects to also DELETE (containers and networks)" "$chosen") || aborted "deleted"
+if [ -z "$doomed" ]; then
+  echo "Stopped, nothing deleted."
+  exit 0
+fi
+
+# Volumes hold the data, so wiping them is a separate, explicit choice.
+volumes=$(pick_one "Volumes of deleted projects" "Keep volumes" "Delete volumes too") || aborted "deleted"
+
+echo
+bold "Deleting"
+for project in $doomed; do
+  echo "  $project"
+  filter=$(by_project "$project")
+  ids=$(docker ps -aq --filter "$filter")
+  # shellcheck disable=SC2086
+  [ -n "$ids" ] && run docker rm -v $ids >/dev/null
+  nets=$(docker network ls -q --filter "$filter")
+  # shellcheck disable=SC2086
+  [ -n "$nets" ] && run docker network rm $nets >/dev/null
+  if [ "$volumes" = "Delete volumes too" ]; then
+    vols=$(docker volume ls -q --filter "$filter")
+    # shellcheck disable=SC2086
+    [ -n "$vols" ] && run docker volume rm $vols >/dev/null
+  fi
+done
+echo "Done."

package/bin/docker-util

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Single entry point so `npx @danolez/docker-util <cmd>` reaches every command.
+set -uo pipefail
+
+self="$0"
+while [ -L "$self" ]; do
+  link=$(readlink "$self")
+  case "$link" in /*) self="$link" ;; *) self="$(dirname "$self")/$link" ;; esac
+done
+dir="$(dirname "$self")"
+
+cmd="${1:-help}"
+[ $# -gt 0 ] && shift
+case "$cmd" in
+  list|stop|prune|help) exec "$dir/docker-$cmd" "$@" ;;
+  -h|--help) exec "$dir/docker-help" ;;
+  -v|--version) exec "$dir/docker-help" --version ;;
+  *) echo "docker-util: unknown command '$cmd'" >&2; "$dir/docker-help" >&2; exit 2 ;;
+esac

package/lib/common.sh

@@ -0,0 +1,128 @@
+# shellcheck shell=bash
+# Shared by every docker-util command so they all pick things the same way.
+
+# shellcheck disable=SC2034
+DOCKER_UTIL_VERSION="1.0.0"
+NONE="(none)"
+DRY_RUN="${DRY_RUN:-0}"
+ASSUME_YES="${ASSUME_YES:-0}"
+
+bold() { printf '\033[1m%s\033[0m\n' "$*"; }
+dim() { printf '\033[2m%s\033[0m\n' "$*"; }
+# fd 3 keeps dry-run output visible past callers that silence the real command.
+exec 3>&1
+run() {
+  if [ "$DRY_RUN" = 1 ]; then dim "  would run: $*" >&3; else "$@"; fi
+}
+
+in_list() { printf '%s\n' "$2" | grep -qxF -- "$1"; }
+
+require_docker() {
+  command -v docker >/dev/null 2>&1 || { echo "docker not found on PATH." >&2; exit 1; }
+  docker info >/dev/null 2>&1 || { echo "Docker daemon not reachable." >&2; exit 1; }
+}
+
+# Opened once so every menu in a run shares one read offset (lets tests script keystrokes).
+{ exec 4<"${DOCKER_UTIL_TTY:-/dev/tty}"; } 2>/dev/null || true
+
+picker() {
+  local want="${DOCKER_UTIL_PICKER:-auto}"
+  if [ "$want" = auto ]; then
+    if command -v fzf >/dev/null 2>&1; then want=fzf
+    elif command -v gum >/dev/null 2>&1; then want=gum
+    else want=builtin; fi
+  fi
+  echo "$want"
+}
+
+# Arrow-key menu for machines without fzf or gum. Args: multi(0|1) prompt items...
+_menu() {
+  local multi="$1" prompt="$2"; shift 2
+  local opts=("$@") n=$# cur=0 i key rest mark ptr hint drawn=0
+  local sel=()
+  [ "$n" -eq 0 ] && return 0
+  # Runs in a $() subshell, so this only restores the cursor for this menu.
+  trap 'printf "\033[?25h" >&2' EXIT
+  for ((i = 0; i < n; i++)); do sel[i]=0; done
+  hint="up/down move, enter select, q abort"
+  [ "$multi" = 1 ] && hint="up/down move, space mark, enter confirm, q abort"
+  printf '\033[?25l\033[1m%s\033[0m  \033[2m%s\033[0m\n' "$prompt" "$hint" >&2
+  while :; do
+    [ "$drawn" = 1 ] && printf '\033[%dA' "$n" >&2
+    for ((i = 0; i < n; i++)); do
+      ptr="  "; [ "$i" = "$cur" ] && ptr="> "
+      mark=""
+      if [ "$multi" = 1 ]; then mark="[ ] "; [ "${sel[i]}" = 1 ] && mark="[x] "; fi
+      printf '\033[2K%s%s%s\n' "$ptr" "$mark" "${opts[i]}" >&2
+    done
+    drawn=1
+    IFS= read -rsn1 key 2>/dev/null <&4 || key=q
+    if [ "$key" = $'\033' ]; then
+      rest=""
+      IFS= read -rsn2 -t 1 rest 2>/dev/null <&4
+      case "$rest" in "[A") key=k ;; "[B") key=j ;; *) key=q ;; esac
+    fi
+    case "$key" in
+      k) cur=$(((cur - 1 + n) % n)) ;;
+      j) cur=$(((cur + 1) % n)) ;;
+      " ") [ "$multi" = 1 ] && sel[cur]=$((1 - sel[cur])) ;;
+      "") break ;;
+      q) printf '\033[?25h' >&2; return 130 ;;
+    esac
+  done
+  printf '\033[?25h' >&2
+  if [ "$multi" = 1 ]; then
+    for ((i = 0; i < n; i++)); do [ "${sel[i]}" = 1 ] && printf '%s\n' "${opts[i]}"; done
+  else
+    printf '%s\n' "${opts[cur]}"
+  fi
+  return 0
+}
+
+# Newline-separated items in, picked items out. Non-zero only on abort.
+pick_many() {
+  local prompt="$1" items="$2" picked rc line
+  local arr=()
+  [ -z "$items" ] && return 0
+  [ "$ASSUME_YES" = 1 ] && return 0
+  case "$(picker)" in
+    # fzf and gum return the highlighted row on a bare ENTER, so (none) is the only way to pick nothing.
+    fzf)
+      picked=$(printf '%s\n%s\n' "$NONE" "$items" | fzf --multi --prompt="$prompt> " \
+        --height=40% --reverse --header="TAB to mark, ENTER to confirm, ESC to abort")
+      rc=$? ;;
+    gum)
+      picked=$(printf '%s\n%s\n' "$NONE" "$items" | gum choose --no-limit --header="$prompt")
+      rc=$? ;;
+    *)
+      while IFS= read -r line; do [ -n "$line" ] && arr+=("$line"); done <<<"$items"
+      [ ${#arr[@]} -eq 0 ] && return 0
+      picked=$(_menu 1 "$prompt" "${arr[@]}")
+      rc=$? ;;
+  esac
+  [ "$rc" -ne 0 ] && return 130
+  printf '%s\n' "$picked" | grep -vxF -- "$NONE" | sed '/^$/d'
+  return 0
+}
+
+# Items as arguments, one picked item out. Non-zero only on abort.
+pick_one() {
+  local prompt="$1"; shift
+  case "$(picker)" in
+    fzf) printf '%s\n' "$@" | fzf --prompt="$prompt> " --height=40% --reverse \
+      --header="ENTER to select, ESC to abort" ;;
+    gum) gum choose --header="$prompt" "$@" ;;
+    *) _menu 0 "$prompt" "$@" ;;
+  esac
+}
+
+confirm() {
+  local answer
+  [ "$ASSUME_YES" = 1 ] && return 0
+  answer=$(pick_one "$1" No Yes) || return 1
+  [ "$answer" = Yes ]
+}
+
+compose_projects() {
+  docker ps "$@" --format '{{.Label "com.docker.compose.project"}}' | sed '/^$/d' | sort -u
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@danolez/docker-util",
+  "version": "1.0.0",
+  "description": "Interactive Docker helpers: list, stop and prune compose projects without typing names",
+  "bin": {
+    "docker-util": "bin/docker-util",
+    "docker-list": "bin/docker-list",
+    "docker-stop": "bin/docker-stop",
+    "docker-prune": "bin/docker-prune",
+    "docker-help": "bin/docker-help"
+  },
+  "files": [
+    "bin/",
+    "lib/"
+  ],
+  "scripts": {
+    "test": "bash test/run.sh",
+    "lint": "shellcheck bin/* lib/common.sh test/run.sh test/stub/docker"
+  },
+  "keywords": [
+    "docker",
+    "compose",
+    "prune",
+    "stop",
+    "cleanup",
+    "cli",
+    "fzf"
+  ],
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danolez1/docker-util.git"
+  },
+  "homepage": "https://github.com/danolez1/docker-util#readme",
+  "bugs": "https://github.com/danolez1/docker-util/issues",
+  "author": "Fatunmbi Daniel",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}