abra-bash/abra

#!/usr/bin/env bash

GIT_URL="https://git.autonomic.zone/coop-cloud/"
ABRA_DIR="${ABRA_DIR:-$HOME/.abra}"
ABRA_VERSION="0.5.0"
ABRA_BACKUP_DIR="${ABRA_BACKUP_DIR:-$ABRA_DIR/backups}"

#######################################
# Global help
#######################################

DOC="
The cooperative cloud utility belt 🎩🐇

Usage:
  abra [options] app (list|ls) [--status] [--server=<server>]
  abra [options] app new [--server=<server>] [--domain=<domain>] [--app-name=<app_name>] [--pass] [--secrets] <type>
  abra [options] app <app> backup (<service>|--all)
  abra [options] app <app> deploy [--update]
  abra [options] app <app> check
  abra [options] app <app> config
  abra [options] app <app> cp <src> <dst>
  abra [options] app <app> logs [<service>]
  abra [options] app <app> ps
  abra [options] app <app> restore (<service>|--all)
  abra [options] app <app> (rm|delete) [--force]
  abra [options] app <app> restore <service> [<backup file>]
  abra [options] app <app> run [--no-tty] [--user=<user>] <service> <args>...
  abra [options] app <app> secret generate (<secret> <version>|--all) [<cmd>] [--pass]
  abra [options] app <app> secret insert <secret> <version> <data> [--pass]
  abra [options] app <app> secret (rm|delete) (<secret>|--all) [--pass] [--force]
  abra [options] app <app> undeploy
  abra [options] app <app> <command> [<args>...]
  abra [options] server add <host> [<user>] [<port>]
  abra [options] server (list|ls)
  abra [options] server <host> rm
  abra [options] server <host> init
  abra [options] server <host> apps [--status]
  abra [options] upgrade
  abra [options] version
  abra [options] help [<subcommands>...]
  abra [options]

Options:
  -e, --env=<path>     Environment variables to load
  -h, --help           Show this message and exit
  -s, --stack=<stack>  Name of the target stack
  -C, --skip-check     Don't verify app variables
  -U, --skip-update    Don't pull latest app definitions
  -v, --verbose        Show INFO messages
  -d, --debug          Show DEBUG messages

See 'abra help <subcommands>...' to read about a specific subcommand.
"

# docopt parser below, refresh this parser with `docopt.sh abra`
# shellcheck disable=2016,1075,2154
docopt() { parse() { if ${DOCOPT_DOC_CHECK:-true}; then local doc_hash
if doc_hash=$(printf "%s" "$DOC" | (sha256sum 2>/dev/null || shasum -a 256)); then
if [[ ${doc_hash:0:5} != "$digest" ]]; then
stderr "The current usage doc (${doc_hash:0:5}) does not match \
what the parser was generated with (${digest})
Run \`docopt.sh\` to refresh the parser."; _return 70; fi; fi; fi
local root_idx=$1; shift; argv=("$@"); parsed_params=(); parsed_values=()
left=(); testdepth=0; local arg; while [[ ${#argv[@]} -gt 0 ]]; do
if [[ ${argv[0]} = "--" ]]; then for arg in "${argv[@]}"; do
parsed_params+=('a'); parsed_values+=("$arg"); done; break
elif [[ ${argv[0]} = --* ]]; then parse_long
elif [[ ${argv[0]} = -* && ${argv[0]} != "-" ]]; then parse_shorts
elif ${DOCOPT_OPTIONS_FIRST:-false}; then for arg in "${argv[@]}"; do
parsed_params+=('a'); parsed_values+=("$arg"); done; break; else
parsed_params+=('a'); parsed_values+=("${argv[0]}"); argv=("${argv[@]:1}"); fi
done; local idx; if ${DOCOPT_ADD_HELP:-true}; then
for idx in "${parsed_params[@]}"; do [[ $idx = 'a' ]] && continue
if [[ ${shorts[$idx]} = "-h" || ${longs[$idx]} = "--help" ]]; then
stdout "$trimmed_doc"; _return 0; fi; done; fi
if [[ ${DOCOPT_PROGRAM_VERSION:-false} != 'false' ]]; then
for idx in "${parsed_params[@]}"; do [[ $idx = 'a' ]] && continue
if [[ ${longs[$idx]} = "--version" ]]; then stdout "$DOCOPT_PROGRAM_VERSION"
_return 0; fi; done; fi; local i=0; while [[ $i -lt ${#parsed_params[@]} ]]; do
left+=("$i"); ((i++)) || true; done
if ! required "$root_idx" || [ ${#left[@]} -gt 0 ]; then error; fi; return 0; }
parse_shorts() { local token=${argv[0]}; local value; argv=("${argv[@]:1}")
[[ $token = -* && $token != --* ]] || _return 88; local remaining=${token#-}
while [[ -n $remaining ]]; do local short="-${remaining:0:1}"
remaining="${remaining:1}"; local i=0; local similar=(); local match=false
for o in "${shorts[@]}"; do if [[ $o = "$short" ]]; then similar+=("$short")
[[ $match = false ]] && match=$i; fi; ((i++)) || true; done
if [[ ${#similar[@]} -gt 1 ]]; then
error "${short} is specified ambiguously ${#similar[@]} times"
elif [[ ${#similar[@]} -lt 1 ]]; then match=${#shorts[@]}; value=true
shorts+=("$short"); longs+=(''); argcounts+=(0); else value=false
if [[ ${argcounts[$match]} -ne 0 ]]; then if [[ $remaining = '' ]]; then
if [[ ${#argv[@]} -eq 0 || ${argv[0]} = '--' ]]; then
error "${short} requires argument"; fi; value=${argv[0]}; argv=("${argv[@]:1}")
else value=$remaining; remaining=''; fi; fi; if [[ $value = false ]]; then
value=true; fi; fi; parsed_params+=("$match"); parsed_values+=("$value"); done
}; parse_long() { local token=${argv[0]}; local long=${token%%=*}
local value=${token#*=}; local argcount; argv=("${argv[@]:1}")
[[ $token = --* ]] || _return 88; if [[ $token = *=* ]]; then eq='='; else eq=''
value=false; fi; local i=0; local similar=(); local match=false
for o in "${longs[@]}"; do if [[ $o = "$long" ]]; then similar+=("$long")
[[ $match = false ]] && match=$i; fi; ((i++)) || true; done
if [[ $match = false ]]; then i=0; for o in "${longs[@]}"; do
if [[ $o = $long* ]]; then similar+=("$long"); [[ $match = false ]] && match=$i
fi; ((i++)) || true; done; fi; if [[ ${#similar[@]} -gt 1 ]]; then
error "${long} is not a unique prefix: ${similar[*]}?"
elif [[ ${#similar[@]} -lt 1 ]]; then
[[ $eq = '=' ]] && argcount=1 || argcount=0; match=${#shorts[@]}
[[ $argcount -eq 0 ]] && value=true; shorts+=(''); longs+=("$long")
argcounts+=("$argcount"); else if [[ ${argcounts[$match]} -eq 0 ]]; then
if [[ $value != false ]]; then
error "${longs[$match]} must not have an argument"; fi
elif [[ $value = false ]]; then
if [[ ${#argv[@]} -eq 0 || ${argv[0]} = '--' ]]; then
error "${long} requires argument"; fi; value=${argv[0]}; argv=("${argv[@]:1}")
fi; if [[ $value = false ]]; then value=true; fi; fi; parsed_params+=("$match")
parsed_values+=("$value"); }; required() { local initial_left=("${left[@]}")
local node_idx; ((testdepth++)) || true; for node_idx in "$@"; do
if ! "node_$node_idx"; then left=("${initial_left[@]}"); ((testdepth--)) || true
return 1; fi; done; if [[ $((--testdepth)) -eq 0 ]]; then
left=("${initial_left[@]}"); for node_idx in "$@"; do "node_$node_idx"; done; fi
return 0; }; either() { local initial_left=("${left[@]}"); local best_match_idx
local match_count; local node_idx; ((testdepth++)) || true
for node_idx in "$@"; do if "node_$node_idx"; then
if [[ -z $match_count || ${#left[@]} -lt $match_count ]]; then
best_match_idx=$node_idx; match_count=${#left[@]}; fi; fi
left=("${initial_left[@]}"); done; ((testdepth--)) || true
if [[ -n $best_match_idx ]]; then "node_$best_match_idx"; return 0; fi
left=("${initial_left[@]}"); return 1; }; optional() { local node_idx
for node_idx in "$@"; do "node_$node_idx"; done; return 0; }; oneormore() {
local i=0; local prev=${#left[@]}; while "node_$1"; do ((i++)) || true
[[ $prev -eq ${#left[@]} ]] && break; prev=${#left[@]}; done
if [[ $i -ge 1 ]]; then return 0; fi; return 1; }; _command() { local i
local name=${2:-$1}; for i in "${!left[@]}"; do local l=${left[$i]}
if [[ ${parsed_params[$l]} = 'a' ]]; then
if [[ ${parsed_values[$l]} != "$name" ]]; then return 1; fi
left=("${left[@]:0:$i}" "${left[@]:((i+1))}")
[[ $testdepth -gt 0 ]] && return 0; if [[ $3 = true ]]; then
eval "((var_$1++)) || true"; else eval "var_$1=true"; fi; return 0; fi; done
return 1; }; switch() { local i; for i in "${!left[@]}"; do local l=${left[$i]}
if [[ ${parsed_params[$l]} = "$2" ]]; then
left=("${left[@]:0:$i}" "${left[@]:((i+1))}")
[[ $testdepth -gt 0 ]] && return 0; if [[ $3 = true ]]; then
eval "((var_$1++))" || true; else eval "var_$1=true"; fi; return 0; fi; done
return 1; }; value() { local i; for i in "${!left[@]}"; do local l=${left[$i]}
if [[ ${parsed_params[$l]} = "$2" ]]; then
left=("${left[@]:0:$i}" "${left[@]:((i+1))}")
[[ $testdepth -gt 0 ]] && return 0; local value
value=$(printf -- "%q" "${parsed_values[$l]}"); if [[ $3 = true ]]; then
eval "var_$1+=($value)"; else eval "var_$1=$value"; fi; return 0; fi; done
return 1; }; stdout() { printf -- "cat <<'EOM'\n%s\nEOM\n" "$1"; }; stderr() {
printf -- "cat <<'EOM' >&2\n%s\nEOM\n" "$1"; }; error() {
[[ -n $1 ]] && stderr "$1"; stderr "$usage"; _return 1; }; _return() {
printf -- "exit %d\n" "$1"; exit "$1"; }; set -e; trimmed_doc=${DOC:1:1811}
usage=${DOC:40:1348}; digest=4fa25
shorts=(-v -s -C -U -h -e -d '' '' '' '' '' '' '' '' '' '' '')
longs=(--verbose --stack --skip-check --skip-update --help --env --debug --status --server --domain --app-name --pass --secrets --all --update --force --no-tty --user)
argcounts=(0 1 0 0 0 1 0 0 1 1 1 0 0 0 0 0 0 1); node_0(){ switch __verbose 0; }
node_1(){ value __stack 1; }; node_2(){ switch __skip_check 2; }; node_3(){
switch __skip_update 3; }; node_4(){ switch __help 4; }; node_5(){ value __env 5
}; node_6(){ switch __debug 6; }; node_7(){ switch __status 7; }; node_8(){
value __server 8; }; node_9(){ value __domain 9; }; node_10(){
value __app_name 10; }; node_11(){ switch __pass 11; }; node_12(){
switch __secrets 12; }; node_13(){ switch __all 13; }; node_14(){
switch __update 14; }; node_15(){ switch __force 15; }; node_16(){
switch __no_tty 16; }; node_17(){ value __user 17; }; node_18(){ value _type_ a
}; node_19(){ value _app_ a; }; node_20(){ value _service_ a; }; node_21(){
value _src_ a; }; node_22(){ value _dst_ a; }; node_23(){ value _backup_file_ a
}; node_24(){ value _args_ a true; }; node_25(){ value _secret_ a; }; node_26(){
value _version_ a; }; node_27(){ value _cmd_ a; }; node_28(){ value _data_ a; }
node_29(){ value _command_ a; }; node_30(){ value _host_ a; }; node_31(){
value _user_ a; }; node_32(){ value _port_ a; }; node_33(){
value _subcommands_ a true; }; node_34(){ _command app; }; node_35(){
_command list; }; node_36(){ _command ls; }; node_37(){ _command new; }
node_38(){ _command backup; }; node_39(){ _command deploy; }; node_40(){
_command check; }; node_41(){ _command config; }; node_42(){ _command cp; }
node_43(){ _command logs; }; node_44(){ _command ps; }; node_45(){
_command restore; }; node_46(){ _command rm; }; node_47(){ _command delete; }
node_48(){ _command run; }; node_49(){ _command secret; }; node_50(){
_command generate; }; node_51(){ _command insert; }; node_52(){
_command undeploy; }; node_53(){ _command server; }; node_54(){ _command add; }
node_55(){ _command init; }; node_56(){ _command apps; }; node_57(){
_command upgrade; }; node_58(){ _command version; }; node_59(){ _command help; }
node_60(){ optional 0 1 2 3 4 5 6; }; node_61(){ optional 60; }; node_62(){
either 35 36; }; node_63(){ required 62; }; node_64(){ optional 7; }; node_65(){
optional 8; }; node_66(){ required 61 34 63 64 65; }; node_67(){ optional 9; }
node_68(){ optional 10; }; node_69(){ optional 11; }; node_70(){ optional 12; }
node_71(){ required 61 34 37 65 67 68 69 70 18; }; node_72(){ either 20 13; }
node_73(){ required 72; }; node_74(){ required 61 34 19 38 73; }; node_75(){
optional 14; }; node_76(){ required 61 34 19 39 75; }; node_77(){
required 61 34 19 40; }; node_78(){ required 61 34 19 41; }; node_79(){
required 61 34 19 42 21 22; }; node_80(){ optional 20; }; node_81(){
required 61 34 19 43 80; }; node_82(){ required 61 34 19 44; }; node_83(){
required 61 34 19 45 73; }; node_84(){ either 46 47; }; node_85(){ required 84
}; node_86(){ optional 15; }; node_87(){ required 61 34 19 85 86; }; node_88(){
optional 23; }; node_89(){ required 61 34 19 45 20 88; }; node_90(){ optional 16
}; node_91(){ optional 17; }; node_92(){ oneormore 24; }; node_93(){
required 61 34 19 48 90 91 20 92; }; node_94(){ required 25 26; }; node_95(){
either 94 13; }; node_96(){ required 95; }; node_97(){ optional 27; }
node_98(){ required 61 34 19 49 50 96 97 69; }; node_99(){
required 61 34 19 49 51 25 26 28 69; }; node_100(){ either 25 13; }; node_101(){
required 100; }; node_102(){ required 61 34 19 49 85 101 69 86; }; node_103(){
required 61 34 19 52; }; node_104(){ optional 92; }; node_105(){
required 61 34 19 29 104; }; node_106(){ optional 31; }; node_107(){ optional 32
}; node_108(){ required 61 53 54 30 106 107; }; node_109(){ required 61 53 63; }
node_110(){ required 61 53 30 46; }; node_111(){ required 61 53 30 55; }
node_112(){ required 61 53 30 56 64; }; node_113(){ required 61 57; }
node_114(){ required 61 58; }; node_115(){ oneormore 33; }; node_116(){
optional 115; }; node_117(){ required 61 59 116; }; node_118(){ required 61; }
node_119(){
either 66 71 74 76 77 78 79 81 82 83 87 89 93 98 99 102 103 105 108 109 110 111 112 113 114 117 118
}; node_120(){ required 119; }; cat <<<' docopt_exit() {
[[ -n $1 ]] && printf "%s\n" "$1" >&2; printf "%s\n" "${DOC:40:1348}" >&2
exit 1; }'; unset var___verbose var___stack var___skip_check var___skip_update \
var___help var___env var___debug var___status var___server var___domain \
var___app_name var___pass var___secrets var___all var___update var___force \
var___no_tty var___user var__type_ var__app_ var__service_ var__src_ var__dst_ \
var__backup_file_ var__args_ var__secret_ var__version_ var__cmd_ var__data_ \
var__command_ var__host_ var__user_ var__port_ var__subcommands_ var_app \
var_list var_ls var_new var_backup var_deploy var_check var_config var_cp \
var_logs var_ps var_restore var_rm var_delete var_run var_secret var_generate \
var_insert var_undeploy var_server var_add var_init var_apps var_upgrade \
var_version var_help; parse 120 "$@"; local prefix=${DOCOPT_PREFIX:-''}
unset "${prefix}__verbose" "${prefix}__stack" "${prefix}__skip_check" \
"${prefix}__skip_update" "${prefix}__help" "${prefix}__env" "${prefix}__debug" \
"${prefix}__status" "${prefix}__server" "${prefix}__domain" \
"${prefix}__app_name" "${prefix}__pass" "${prefix}__secrets" "${prefix}__all" \
"${prefix}__update" "${prefix}__force" "${prefix}__no_tty" "${prefix}__user" \
"${prefix}_type_" "${prefix}_app_" "${prefix}_service_" "${prefix}_src_" \
"${prefix}_dst_" "${prefix}_backup_file_" "${prefix}_args_" \
"${prefix}_secret_" "${prefix}_version_" "${prefix}_cmd_" "${prefix}_data_" \
"${prefix}_command_" "${prefix}_host_" "${prefix}_user_" "${prefix}_port_" \
"${prefix}_subcommands_" "${prefix}app" "${prefix}list" "${prefix}ls" \
"${prefix}new" "${prefix}backup" "${prefix}deploy" "${prefix}check" \
"${prefix}config" "${prefix}cp" "${prefix}logs" "${prefix}ps" \
"${prefix}restore" "${prefix}rm" "${prefix}delete" "${prefix}run" \
"${prefix}secret" "${prefix}generate" "${prefix}insert" "${prefix}undeploy" \
"${prefix}server" "${prefix}add" "${prefix}init" "${prefix}apps" \
"${prefix}upgrade" "${prefix}version" "${prefix}help"
eval "${prefix}"'__verbose=${var___verbose:-false}'
eval "${prefix}"'__stack=${var___stack:-}'
eval "${prefix}"'__skip_check=${var___skip_check:-false}'
eval "${prefix}"'__skip_update=${var___skip_update:-false}'
eval "${prefix}"'__help=${var___help:-false}'
eval "${prefix}"'__env=${var___env:-}'
eval "${prefix}"'__debug=${var___debug:-false}'
eval "${prefix}"'__status=${var___status:-false}'
eval "${prefix}"'__server=${var___server:-}'
eval "${prefix}"'__domain=${var___domain:-}'
eval "${prefix}"'__app_name=${var___app_name:-}'
eval "${prefix}"'__pass=${var___pass:-false}'
eval "${prefix}"'__secrets=${var___secrets:-false}'
eval "${prefix}"'__all=${var___all:-false}'
eval "${prefix}"'__update=${var___update:-false}'
eval "${prefix}"'__force=${var___force:-false}'
eval "${prefix}"'__no_tty=${var___no_tty:-false}'
eval "${prefix}"'__user=${var___user:-}'
eval "${prefix}"'_type_=${var__type_:-}'; eval "${prefix}"'_app_=${var__app_:-}'
eval "${prefix}"'_service_=${var__service_:-}'
eval "${prefix}"'_src_=${var__src_:-}'; eval "${prefix}"'_dst_=${var__dst_:-}'
eval "${prefix}"'_backup_file_=${var__backup_file_:-}'
if declare -p var__args_ >/dev/null 2>&1; then
eval "${prefix}"'_args_=("${var__args_[@]}")'; else eval "${prefix}"'_args_=()'
fi; eval "${prefix}"'_secret_=${var__secret_:-}'
eval "${prefix}"'_version_=${var__version_:-}'
eval "${prefix}"'_cmd_=${var__cmd_:-}'; eval "${prefix}"'_data_=${var__data_:-}'
eval "${prefix}"'_command_=${var__command_:-}'
eval "${prefix}"'_host_=${var__host_:-}'
eval "${prefix}"'_user_=${var__user_:-}'
eval "${prefix}"'_port_=${var__port_:-}'
if declare -p var__subcommands_ >/dev/null 2>&1; then
eval "${prefix}"'_subcommands_=("${var__subcommands_[@]}")'; else
eval "${prefix}"'_subcommands_=()'; fi; eval "${prefix}"'app=${var_app:-false}'
eval "${prefix}"'list=${var_list:-false}'; eval "${prefix}"'ls=${var_ls:-false}'
eval "${prefix}"'new=${var_new:-false}'
eval "${prefix}"'backup=${var_backup:-false}'
eval "${prefix}"'deploy=${var_deploy:-false}'
eval "${prefix}"'check=${var_check:-false}'
eval "${prefix}"'config=${var_config:-false}'
eval "${prefix}"'cp=${var_cp:-false}'; eval "${prefix}"'logs=${var_logs:-false}'
eval "${prefix}"'ps=${var_ps:-false}'
eval "${prefix}"'restore=${var_restore:-false}'
eval "${prefix}"'rm=${var_rm:-false}'
eval "${prefix}"'delete=${var_delete:-false}'
eval "${prefix}"'run=${var_run:-false}'
eval "${prefix}"'secret=${var_secret:-false}'
eval "${prefix}"'generate=${var_generate:-false}'
eval "${prefix}"'insert=${var_insert:-false}'
eval "${prefix}"'undeploy=${var_undeploy:-false}'
eval "${prefix}"'server=${var_server:-false}'
eval "${prefix}"'add=${var_add:-false}'
eval "${prefix}"'init=${var_init:-false}'
eval "${prefix}"'apps=${var_apps:-false}'
eval "${prefix}"'upgrade=${var_upgrade:-false}'
eval "${prefix}"'version=${var_version:-false}'
eval "${prefix}"'help=${var_help:-false}'; local docopt_i=1
[[ $BASH_VERSION =~ ^4.3 ]] && docopt_i=2; for ((;docopt_i>0;docopt_i--)); do
declare -p "${prefix}__verbose" "${prefix}__stack" "${prefix}__skip_check" \
"${prefix}__skip_update" "${prefix}__help" "${prefix}__env" "${prefix}__debug" \
"${prefix}__status" "${prefix}__server" "${prefix}__domain" \
"${prefix}__app_name" "${prefix}__pass" "${prefix}__secrets" "${prefix}__all" \
"${prefix}__update" "${prefix}__force" "${prefix}__no_tty" "${prefix}__user" \
"${prefix}_type_" "${prefix}_app_" "${prefix}_service_" "${prefix}_src_" \
"${prefix}_dst_" "${prefix}_backup_file_" "${prefix}_args_" \
"${prefix}_secret_" "${prefix}_version_" "${prefix}_cmd_" "${prefix}_data_" \
"${prefix}_command_" "${prefix}_host_" "${prefix}_user_" "${prefix}_port_" \
"${prefix}_subcommands_" "${prefix}app" "${prefix}list" "${prefix}ls" \
"${prefix}new" "${prefix}backup" "${prefix}deploy" "${prefix}check" \
"${prefix}config" "${prefix}cp" "${prefix}logs" "${prefix}ps" \
"${prefix}restore" "${prefix}rm" "${prefix}delete" "${prefix}run" \
"${prefix}secret" "${prefix}generate" "${prefix}insert" "${prefix}undeploy" \
"${prefix}server" "${prefix}add" "${prefix}init" "${prefix}apps" \
"${prefix}upgrade" "${prefix}version" "${prefix}help"; done; }
# docopt parser above, complete command for generating this parser is `docopt.sh abra`

PROGRAM_NAME=$(basename "$0")

#######################################
# Helpers
#######################################

###### Utility functions

error() {
  echo "$(tput setaf 1)ERROR: $*$(tput sgr0)"
  exit 1
}

warning() {
  echo "$(tput setaf 3)WARNING: $*$(tput sgr0)"
}

success() {
  echo "$(tput setaf 2)SUCCESS: $*$(tput sgr0)"
}

info() {
  if [ "$abra___verbose" = "false" ] && [ "$abra___debug" = "false" ]; then
    return
  fi
  echo "$(tput setaf 4)INFO: $*$(tput sgr0)"
}

debug() {
  if [ "$abra___debug" = "false" ]; then
    return
  fi
  echo "$(tput setaf 13)DEBUG: $*$(tput sgr0)"
}

# 3wc: temporarily disable debug and verbose

silence() {
  # FIXME 3wc: required otherwise we get debug output in the password
  _abra___debug="$abra___debug"
  _abra___verbose="$abra___verbose"
  abra___verbose="false"
  abra___debug="false"
}

unsilence() {
  # FIXME 3wc: required otherwise we get debug output in the password
  abra___verbose="$_abra___verbose"
  abra___debug="$_abra___debug"
}

###### Default settings

if [ -z "$COMPOSE_FILE" ]; then
  COMPOSE_FILE="compose.yml"
fi

###### Safety checks

require_pwqgen() {
  if ! type pwqgen > /dev/null 2>&1; then
    error "pwqgen program is not installed"
  fi
}

require_pwgen() {
  if ! type pwgen > /dev/null 2>&1; then
    error "pwgen program is not installed"
  fi
}

require_abra_dir() {
  mkdir -p "$ABRA_DIR"
}

require_stack() {
  if [ -z "$STACK_NAME" ]; then
    error "no stack_name, export \$STACK_NAME=my_cool_app"
  fi
}

require_app_latest() {
  APP="$1"
  APP_DIR="$ABRA_DIR/apps/$APP"

  debug "Checking for type '$APP'"

  if [ ! -d "$APP_DIR" ]; then
    warning "The app type '$APP' was not found, fetching via Git"
    if ! git clone "$GIT_URL/$APP.git" "$ABRA_DIR/apps/$APP" > /dev/null 2>&1 ; then
      error "Could not retrieve app type '$APP', this app type doesn't exist?"
    fi
    success "Fetched app configuration via Git"
  fi

  debug "Using $APP_DIR"

  if [ "$abra___skip_update" = "false" ]; then
    (cd "$APP_DIR" && git pull > /dev/null 2>&1)
  fi
}

# FIXME 3wc: update or remove
if [ -z "$ABRA_ENV" ] && [ -f .env ] && type direnv > /dev/null 2>&1 && ! direnv status | grep -q 'Found RC allowed true'; then
  error "direnv is blocked, run direnv allow"
fi

require_consent_for_update (){
  if [ "$CONSENT_TO_UPDATE" = "false" ] && \
     [ -n "$deployed_version" ] && \
     [ "$ABRA_TYPE_VERSION" != "$deployed_version" ]; then
    error "This deployment will be an app update from version ${deployed_version} -> ${ABRA_TYPE_VERSION}
       Please pass the --update option to the deploy to deploy the update"
  fi

  if [ "$CONSENT_TO_UPDATE" = "false" ] && \
     [ "$ABRA_TYPE_VERSION" = "$deployed_version" ] && \
     [ "$ABRA_TYPE_DIGEST" != "$deployed_digest" ]; then
    error "The app version is the same but the image digest has changed from ${deployed_digest} -> ${ABRA_TYPE_DIGEST}
       This should not happen! This may mean that the upstream app developers are overwriting their image tags
       Get in touch and let's make the builds stable together: https://docs.cloud.autonomic.zone/contact/
       Please pass the --update option to deploy the update anyway"
  fi
}

###### Run-time loading

load_abra_sh() {
  if [ -f abra.sh ]; then
    # shellcheck disable=SC1091
    source abra.sh
    info "Loading abra.sh"
  fi

  if [ -n "$abra__app_" ]; then
    load_instance
    load_instance_env
    require_app_latest "$TYPE"
  fi

  if [ -f "$APP_DIR/abra.sh" ]; then
    info "Loading $APP_DIR/abra.sh"
    # shellcheck disable=SC1090,SC1091
    source "$APP_DIR/abra.sh"
  fi
}

###### FIXME 3wc: name this section

get_servers() {
  shopt -s nullglob dotglob
  # shellcheck disable=SC2206
  SERVERS=($ABRA_DIR/servers/*)
  shopt -u nullglob dotglob
}

get_app_secrets() {
  # FIXME 3wc: requires bash 4, use for loop instead
  mapfile -t PASSWORDS < <(grep "SECRET.*VERSION.*" "$ENV_FILE")
}

load_instance() {
  APP="$abra__app_"

  # load all files matching "$APP.env" into ENV_FILES array
  mapfile -t ENV_FILES < <(find -L "$ABRA_DIR" -name "$APP.env")
  # FIXME 3wc: requires bash 4, use for loop instead

  case "${#ENV_FILES[@]}" in
    1 ) ;;
    0 ) error "Can't find app '$APP'"; return;;
    * ) error "Found $APP in multiple servers: ${ENV_FILES[*]}"; return;;
  esac

  ENV_FILE="${ENV_FILES[0]}"
  debug "Selected ENV_FILE $ENV_FILE"

  if [ ! -f "$ENV_FILE" ]; then
    error "Can't open ENV_FILE '$ENV_FILE'"
  fi

  # split up the path by "/"
  IFS='/' read -r -a PARTS <<< "$ENV_FILE"

  SERVER="${PARTS[-2]}"
  export STACK_NAME="${APP//./_}"
}

load_instance_env() {
  # 3wc: using set -a means we don't need `export` in the env files
  set -a
  # shellcheck disable=SC1090
  source "$ENV_FILE"
  set +a

  debug "Loaded variables from $ENV_FILE"

  if [ -z "$TYPE" ]; then
    error "TYPE not set, maybe $ENV_FILE is using an old format?"
  fi

  APP_DIR="$ABRA_DIR/apps/$TYPE"
  export DOCKER_CONTEXT="$SERVER"
  info "Setting DOCKER_CONTEXT=$DOCKER_CONTEXT"

  export DOMAIN
}

load_context() {
  # Load current context from env or Docker
  if [ -z "$DOCKER_CONTEXT" ]; then
    warning "\$DOCKER_CONTEXT not set, (slowly) looking it up"
    # shellcheck disable=SC2063
    DOCKER_CONTEXT=$(docker context ls | grep '*' | cut -d' ' -f1)
    # make sure grep doesn't parse this, we want a literal '*'
  fi
}

prompt_confirm() {
  read -rp "Continue? (y/[n])? " choice

  case "$choice" in
    y|Y ) return ;;
    * ) exit;;
  esac
}

parse_secret() {
  SECRET="$1"

  if [[ "$SECRET" == *"length"* ]]; then
    # shellcheck disable=SC2001
    abra__length_="$(echo "$SECRET" | sed -e 's/.*[^0-9]\([0-9]\+\)[^0-9]*$/\1/')"
  else
    # Note(decentral1se): unset this so that a length value from another secret
    # definition does not get passed on to another secret generation flow
    unset abra__length_
  fi

  abra__secret_="${SECRET%_VERSION=*}"  # strip _VERSION=v1
  abra__secret_="${abra__secret_#SECRET_}"  # strip SECRET_
  abra__secret_="${abra__secret_,,}"  # lowercase

  abra__version_="$(echo "$SECRET" | sed -n 's/.*\(v[0-9]\).*/\1/p')"

  if [[ -n "$abra__length_" ]]; then
    echo "Generating $abra__secret_, version: $abra__version_, length: $abra__length_"
  else
    echo "Generating $abra__secret_, version: $abra__version_"
  fi

  sub_app_secret_generate
}

stack_logs (){
  # Note(decentral1se): see https://github.com/moby/moby/issues/31458#issuecomment-617871046
  STACK="$1"

  services=$(docker stack services "${STACK}" --format "{{.ID}}")

  # shellcheck disable=SC2154
  trap 'jobs=$(jobs -p) && test -n "$jobs" && kill $jobs' EXIT

  for item in ${services//\\n/$'\n'}; do
      docker service logs -f -t --tail 10 "$item" &
  done

  sleep infinity
}

auto_gen_secrets (){
  get_app_secrets

  if [ "${#PASSWORDS[@]}" -eq 0 ]; then
    error "No secrets found in $ENV_FILE"
  fi

  for PASSWORD in "${PASSWORDS[@]}"; do
    parse_secret "$PASSWORD"
  done
}

#######################################
# abra app ..
#######################################

###### .. app ls

help_app_ls (){
  help_app_list
}

sub_app_ls (){
  sub_app_list
}

help_app_list (){
  echo "abra [options] app (list|ls) [--status] [--server=<server>]

List your exciting apps.

OPTIONS
  --status           Show whether apps are deployed (warning! slow!)
  --server=<server>  Filter to a specific server

POWERED BY (for --status)
  docker stack ls"
}

sub_app_list (){
  SERVER="$abra___server"
  if [ -z "$SERVER" ]; then
    SERVER='*'
  fi

  shopt -s nullglob dotglob
  # shellcheck disable=SC2206
  ENV_FILES=($ABRA_DIR/servers/$SERVER/*.env)
  shopt -u nullglob dotglob

  STATUS="$( [[ $abra___status == "true" ]] && echo "Y" )"

  if [ -n "$STATUS" ]; then
    if [ "$SERVER" = "*" ]; then
      get_servers
    else
      SERVERS=( "$SERVER" )
    fi

    local -a DEPLOYED_APPS  # array

    warning "Loading status from ${#SERVERS[@]} server(s), patience advised.."

    for SERVER in "${SERVERS[@]}"; do
      SERVER="${SERVER##*/}"  # basename
      mapfile -t SERVER_APPS < <(DOCKER_CONTEXT="$SERVER" docker stack ls --format '{{ .Name }}')
      # add $SERVER~ to the start of each DEPLOYED_APPS
      DEPLOYED_APPS+=("${SERVER_APPS[@]/#/$SERVER~}")
    done
  fi

  printf "%s lovely apps:\n\n" "${#ENV_FILES[@]}"

  for i in "${!ENV_FILES[@]}"; do
    # Output header inside the loop, so it's included in the pipe to `column`
    if [ "$i" == 0 ]; then
      printf "  DOMAIN\tTYPE\tSERVER%s%s\n" "${STATUS:+	}" "${STATUS:+STATUS}"
      printf "  --\t--\t--%s\n" "${STATUS:+	--}"
    fi

    local ENV_FILE="${ENV_FILES[$i]}" APP_STACK_NAME

    IFS='/' read -r -a PARTS <<< "$ENV_FILE"

    FILE="${PARTS[-1]}"
    SERVER="${PARTS[-2]}"
    DOMAIN="${FILE%.env}"

    set -a
    # shellcheck disable=SC1090
    TYPE="$(source "$ENV_FILE" && echo "$TYPE")"
    # shellcheck disable=SC1090
    APP_STACK_NAME="$(source "$ENV_FILE" && echo "$STACK_NAME")"
    set +a

    if [ -z "$APP_STACK_NAME" ]; then
      APP_STACK_NAME="${DOMAIN//./_}"
    fi
    if [ -n "$STATUS" ]; then
      APP_STATUS=$( printf '%s\n' "${DEPLOYED_APPS[@]}" | grep -qP "^${SERVER}~${APP_STACK_NAME}$" && echo "deployed" || echo "inactive")
    fi
    printf "  %s\t%s\t%s%s\n" "$DOMAIN" "$TYPE" "$SERVER" "${STATUS:+	}${APP_STATUS}"
  done | column -s'	' -t
  # Align table `-t` based on tab characters -s`^V<Tab>`
}

###### .. app new
help_app_new (){
  echo "abra [options] app new [--server=<server>] [--domain=<domain>] [--pass] [--auto] <type>

Create a new app of <type> (e.g. wordpress or custom-html).

OPTIONS
  --server=<server>  Specify which server to use (default: prompt)
  --domain=<domain>  Set the domain name (default: prompt)
  --auto             Auto-generate secrets (default: no)
  --pass             Store generated secrets in pass (default: no)"
}

sub_app_new (){
  require_abra_dir
  get_servers

  # Note(decentral1se): we are overloading the use of the word "app" on this
  # the interface and therefore try to use the word "type" to refer to "a type
  # of app" vs. "an instance of an app"
  TYPE=$abra__type_

  SERVER=$abra___server
  DOMAIN=$abra___domain
  APP_NAME=$abra___app_name

  require_app_latest "$TYPE"

  if [ -z "$SERVER" ]; then
    echo "Where would you like to put $TYPE?"

    select SERVER_ITEM in "${SERVERS[@]##*/}"; do
      if [ 1 -le "$REPLY" ] && [ "$REPLY" -le ${#SERVERS[@]} ]; then
        SERVER="$SERVER_ITEM"
        success "Selected server ${SERVER}"
        break
      fi
    done
  fi
  SERVER="$ABRA_DIR/servers/$SERVER"

  if [ ! -d "$SERVER" ]; then
    error "Server '$SERVER' not found"
  fi

  APP_DIR="$ABRA_DIR/apps/$TYPE"

  if [ -z "$DOMAIN" ]; then
    read -rp "Domain name: " DOMAIN
  fi

  if [ -z "$APP_NAME" ]; then
    DEFAULT_NAME="${TYPE/-/}_${DOMAIN//./_}"
    read -rp "App name [$DEFAULT_NAME]: " APP_NAME
    if [ -z "$APP_NAME" ]; then
      APP_NAME="$DEFAULT_NAME"
    fi
  fi

  ENV_FILE="$SERVER/$APP_NAME.env"

  if [ -f "$ENV_FILE" ]; then
    error "$ENV_FILE already exists"
    # FIXME 3wc: offer to user $STACK_$DOMAIN.env name instead
  fi

  cp "$APP_DIR/.env.sample" "$ENV_FILE"
  sed -i "s/$TYPE\.example\.com/$DOMAIN/g" "$ENV_FILE"
  sed -i "s/example\.com/$DOMAIN/g" "$ENV_FILE"

  abra__app_="$APP_NAME"

  get_app_secrets

  if [ "$abra___secrets" == "true" ]; then
    if [ "${#PASSWORDS[@]}" -eq 0 ]; then
      warning "--secrets provided but no secrets found"
    fi
    auto_gen_secrets
  fi

  echo "$(tput setaf 4)Your new '$TYPE' is ready for action:$(tput sgr0)"
  echo "  $(tput setaf 3)Customise the configuration:"
  echo "    abra app $APP_NAME config$(tput sgr0)"
  echo "  $(tput setaf 2)Deploy it:"
  echo "    abra app $APP_NAME deploy$(tput sgr0)"
}

###### .. app backup
sub_app_backup (){
  load_instance
  load_instance_env

  require_app_latest "$TYPE"

  # Add _<service> if it's defined
  FUNCTION="abra_backup${abra__service_:+_}$abra__service_"

  if ! type "$FUNCTION" > /dev/null 2>&1; then
    error "'$TYPE' doesn't know how to do ${abra__service_}${abra__service_:+ }backups."\
      "See $GIT_URL$TYPE/issues/"
  fi

  mkdir -p "$ABRA_DIR/backups"

  $FUNCTION
}

###### .. app restore
sub_app_restore (){
  load_instance
  load_instance_env

  require_app_latest "$TYPE"

  FUNCTION="abra_restore_$abra__service_"

  if ! type "$FUNCTION" > /dev/null 2>&1; then
    error "'$TYPE' doesn't know how to restore '${abra__service_}' backups."\
      "See $GIT_URL$TYPE/issues/"
  fi

  $FUNCTION "$abra__backup_file_"
}

###### backup utility functions

# Usage: _abra_backup_dir service:/path/to/src
_abra_backup_dir() {
  {
    abra__src_="$1"
    abra__dst_="-"
  }

  # shellcheck disable=SC2154
  FILENAME="$ABRA_BACKUP_DIR/${abra__app_}_$(basename "$1")_$(date +%F).tar.gz"

  debug "Copying '$1' to '$FILENAME'"

  silence
  sub_app_cp | gzip > "$FILENAME"
  success "Backed up '$1' to $FILENAME"
  unsilence
}

_abra_backup_db_prep() {
  # shellcheck disable=SC2034
  abra__service_="$1"
  # 3wc: necessary because $abra__service_ won't be set if we're coming from
  # `abra_backup`, i.e. `abra app ... backup --all`

  # What's the name of the Docker secret? Default to db_root_password
  DB_PASSWORD_NAME=${4:-db_root_password}

  debug "Looking up secret '$DB_PASSWORD_NAME'"
  silence
  DB_PASSWORD="$(sub_app_run cat "/run/secrets/$DB_PASSWORD_NAME")"
  unsilence

  # 3wc: strip newline \r from variable
  DB_PASSWORD="${DB_PASSWORD//$'\015'}"

  # shellcheck disable=SC2154
  FILENAME="$ABRA_BACKUP_DIR/${abra__app_}_$(date +%F).sql.gz"
}

# usage: _abra_backup_postgres <service> <database> [<user> <secret name>]
_abra_backup_postgres() {
  _abra_backup_db_prep "$@"

  debug "Running pg_dump to '$FILENAME'"

  silence
  # shellcheck disable=SC2034
  PGPASSWORD="$DB_PASSWORD"
  sub_app_run pg_dump -U "${3:-postgres}" "$2" | gzip > "$FILENAME"
  unsilence

  success "Backed up '$abra__service_:$2' to '$FILENAME'"
}

_abra_backup_mysql() {
  _abra_backup_db_prep "$@"

  silence
  # shellcheck disable=SC2086
  sub_app_run mysqldump -u root -p"${DB_PASSWORD}" "$2" | gzip > "$FILENAME"
  unsilence

  success "Backed up '$abra__service_:$2' to $FILENAME"
}

###### .. app deploy
help_app_deploy (){
  echo "abra [options] app <app> deploy [--update] [--skip-check]

  Deploy app <app> to the configured server.

  POWERED BY
  docker stack deploy -c compose.yml <app>"
}

sub_app_deploy (){
  load_instance
  load_instance_env

  require_app_latest "$TYPE"

  CONSENT_TO_UPDATE=$abra___update

  deployed_version_digest=$(docker service inspect \
    -f "{{index .Spec.Labels \"coop-cloud.${STACK_NAME}.version\" }}" "${STACK_NAME}_app" > /dev/null 2>&1)
  deployed_version=$(echo "$deployed_version_digest" | cut -d- -f1)
  deployed_digest=$(echo "$deployed_version_digest" | cut -d- -f2)

  about_to_deploy_msg="About to deploy:"
  version_msg="  Version: $(tput setaf 2)${ABRA_TYPE_VERSION} (digest: ${ABRA_TYPE_DIGEST})$(tput sgr0)"

  if [ -n "$deployed_version" ] && [ -n "$deployed_digest" ]; then
    require_consent_for_update

    if [ "$ABRA_TYPE_VERSION" != "$deployed_version" ]; then
      about_to_deploy_msg="About to deploy (NEW VERSION):"
    fi

    if [ "$ABRA_TYPE_VERSION" != "$deployed_version" ]; then
      version_msg="  Version: $(tput setaf 2)$deployed_version -> ${ABRA_TYPE_VERSION} (digest: $deployed_digest -> ${ABRA_TYPE_DIGEST})$(tput sgr0)"
    fi
  fi

  echo "$about_to_deploy_msg"
  echo "  Server: $(tput setaf 4)${SERVER}$(tput sgr0)"

  if [ "${COMPOSE_FILE/:/}" == "${COMPOSE_FILE}" ]; then
    echo "  Compose: $(tput setaf 3)${APP_DIR}/${COMPOSE_FILE}$(tput sgr0)"
  else
    echo "  Compose: $(tput setaf 3)${APP_DIR}/"
    IFS=':' read -ra COMPOSE_FILES <<< "$COMPOSE_FILE"
    for COMPOSE in "${COMPOSE_FILES[@]}"; do
      echo "   - ${COMPOSE}"
    done
    tput sgr0
  fi

  if [ -n "$DOMAIN" ]; then
    echo "  Domain: $(tput setaf 2)${DOMAIN}$(tput sgr0)"
  fi

  if [ -n "$ABRA_TYPE_VERSION" ] && [ -n "$ABRA_TYPE_DIGEST" ]; then
    echo "$version_msg"
  fi

  echo "  Stack: $(tput setaf 1)${STACK_NAME}$(tput sgr0)"

  prompt_confirm

  APP=$(basename "$APP_DIR")

  (
    (cd "$APP_DIR" || error "\$APP_DIR '$APP_DIR' not found")
    # shellcheck disable=SC2086
    if (cd "$APP_DIR" && docker stack deploy -c ${COMPOSE_FILE//:/ -c } "$STACK_NAME"); then
      if [ -n "$DOMAIN" ]; then
        success "Yay! App should be available at https://${DOMAIN}"
      else
        success "Yay! That worked. No \$DOMAIN defined, check status by running \"abra app ${STACK_NAME} ps\""
      fi
    else
      error "Oh no! Something went wrong 😕 Check errors above"
    fi
  )
}

###### .. app <app> undeploy
help_app_undeploy (){
  echo "abra [options] app <app> undeploy

Opposite of \`app <app> deploy\`; deactivate an app without deleting anything.

POWERED BY
  docker stack rm <app>"
}

sub_app_undeploy (){
  load_instance
  load_instance_env

  warning "About to un-deploy $STACK_NAME from $SERVER"
  prompt_confirm

  docker stack rm "$STACK_NAME"
}

###### .. app config
help_app_config (){
  echo "abra [options] app <app> config

Open the app configuration in \$EDITOR."
}

sub_app_config (){
  load_instance

  if [ -z "$EDITOR" ]; then
    warning "\$EDITOR not set; which text editor would you like to use?"

    EDITORS_ALL=(vi vim nano pico emacs)
    declare -a EDITORS_AVAILABLE

    for EDITOR in "${EDITORS_ALL[@]}"; do
      if type "$EDITOR" > /dev/null 2>&1; then
        EDITORS_AVAILABLE+=("$EDITOR")
      fi
    done

    if [ ${#EDITORS_AVAILABLE[@]} = 0 ]; then
      error "No text editors found! Are you using a magnetised needle? 🤪"
    fi

    select EDITOR in "${EDITORS_AVAILABLE[@]}"; do
      if [ 1 -le "$REPLY" ] && [ "$REPLY" -le ${#EDITORS_AVAILABLE[@]} ]; then
        SERVER="$EDITOR"
        success "Using '${EDITOR}'; Add 'export EDITOR=${EDITOR}' to your ~/.bashrc to set as default"
        break
      fi
    done
  fi

  $EDITOR "$ENV_FILE"
}

###### .. app check
help_app_check (){
  echo "abra [options] app <app> check

Make sure that all an app's required variables are set."
}

sub_app_check (){
  if [ "$abra___skip_check" = "true" ]; then
    return 0
  fi

  load_instance
  load_instance_env

  APP_ENV=$(grep -v '^#' "$ENV_FILE" | cut -d' ' -f2 | cut -d'=' -f1 | sort -u)
  STACK_ENV=$(grep -v '^#' "$APP_DIR/.env.sample" | cut -d' ' -f2 | cut -d'=' -f1 | sort -u)

  debug "APP_ENV: $APP_ENV"

  debug "STACK_ENV: $STACK_ENV"

  # Only show "1", items in STACK_ENV which aren't in APP_ENV
  MISSING_VARS=$(comm -23 <(echo "$STACK_ENV") <(echo "$APP_ENV"))

  if [ -z "$MISSING_VARS" ]; then
    success "Yay! All the necessary basic variables are defined"
    return 0
  fi

  error "Found missing variables: $MISSING_VARS"
}

###### .. app ps
help_app_ps (){
  echo "abra [options] app <app> ps

Show <app>'s running containers.

POWERED BY
  docker stack ps <app>"
}

sub_app_ps (){
  load_instance
  load_instance_env

  docker stack ps "$STACK_NAME"
}

###### .. app delete
help_app_rm (){
  help_app_delete
}

sub_app_rm (){
  sub_app_delete
}

help_app_delete (){
  echo "abra [options] app <app> (rm|delete) [--force]

Delete local configuration for <app>.

OPTIONS
  --force   Live dangerously; skip prompt for confirmation"
}

sub_app_delete (){
  load_instance
  load_instance_env

  if [ "$abra___force" != "true" ]; then
    warning "About to delete $ENV_FILE"
    prompt_confirm
  fi

  rm "$ENV_FILE"
}

###### .. app secret insert
help_app_secret_insert (){
  echo "abra [options] app <app> secret insert <secret> <version> <data> [--pass]

Store <data> as a Docker secret called <secret>_<version>.

OPTIONS
  --pass     Save the secret in \`pass\` as well"
}
sub_app_secret_insert() {
  load_instance
  load_instance_env

  SECRET="$abra__secret_"
  VERSION="$abra__version_"
  PW="$abra__data_"
  STORE_WITH_PASS="$abra___pass"

  if [ -z "$SECRET" ] || [ -z "$VERSION" ] || [ -z "$PW" ]; then
    error "Required arguments missing"
  fi

  # shellcheck disable=SC2059
  printf "$PW" | docker secret create "${STACK_NAME}_${SECRET}_${VERSION}" - > /dev/null

  if [ "$STORE_WITH_PASS" == "true" ] && type pass > /dev/null 2>&1; then
    echo "$PW" | pass insert "hosts/$DOCKER_CONTEXT/${STACK_NAME}/${SECRET}" -m > /dev/null
    success "pass: hosts/$DOCKER_CONTEXT/${STACK_NAME}/${SECRET}"
  fi
}

###### .. app secret delete
help_app_secret_rm (){
  help_app_secret_delete
}

sub_app_secret_rm(){
  sub_app_secret_delete
}

help_app_secret_delete (){
  echo "abra [options] app <app> secret (delete|rm) (<secret>|--all) [--pass] [--force]

Remove <app>'s Docker secret <secret>.

OPTIONS
  --pass     Remove secret(s) from \`pass\` as well
  --all      Delete all secrets for <app>
  --force   Live dangerously; skip prompt for confirmation"
}

sub_app_secret_delete(){
  load_instance
  load_instance_env

  # if --all is provided then $abra__secret_ will be blank and this will work
  # auto-magically
  NAMES=$(docker secret ls --filter "name=${STACK_NAME}_${abra__secret_}" --format "{{.Name}}")

  if [ -z "$NAMES" ]; then
    error "Could not find any secrets under ${STACK_NAME}_${abra__secret_}"
  fi

  if [ "$abra___force" != "true" ]; then
    warning "About to delete $(echo "$NAMES" | paste -d "")"
    prompt_confirm
  fi

  for NAME in ${NAMES}; do
    docker secret rm "$NAME" > /dev/null

    # as above, no need to test for --all, cos if abra__secret_ is blank it'll
    # Just Work anyway
    if [ "$abra___pass" == "true" ] && type pass > /dev/null 2>&1; then
      pass rm -r "hosts/$DOCKER_CONTEXT/${STACK_NAME}/${abra__secret_}" > /dev/null \
        && success "pass rm'd: hosts/$DOCKER_CONTEXT/${STACK_NAME}/${abra__secret_}"
    fi
  done
}

###### .. app secret generate
help_app_secret_generate (){
  echo "abra [options] app <app> secret generate (<secret> <version>|--all) [<cmd>] [--pass]

Generate <secret>_<version> for <app> and store as a Docker secret.

OPTIONS
  <secret>  Generate a single secret
  <version> Specify secret version (for single secret)
  --all     Auto-generate all secrets
  <cmd>     Run <cmd> to generate secret (default: pwqgen)
  --pass    Save generated secrets in \`pass\`"
}

sub_app_secret_generate(){
  load_instance
  load_instance_env

  SECRET="$abra__secret_"
  VERSION="$abra__version_"
  LENGTH="$abra__length_"

  if [ "$abra___all" == "true" ]; then
    # Note(decentral1se): we need to reset the flag here to avoid the infinite
    # recursion of auto_gen_secrets which calls this function itself
    abra___all="false"

    auto_gen_secrets
    return
  fi

  if [[ -n "$LENGTH" ]]; then
    require_pwgen
    PWGEN=${abra__cmd_:-pwgen -s "$LENGTH" 1}
  else
    require_pwqgen
    PWGEN="${abra__cmd_:-pwqgen}"
  fi

  echo "SECRET: $SECRET, VERSION $VERSION, PW $PW, ALL $abra___all"

  if [ -z "$SECRET" ] || [ -z "$VERSION" ] && [ "$abra___all" == "false" ]; then
    error "Required arguments missing"
  fi

  PW=$($PWGEN|tr -d "\n")

  success "Password: $PW"

  # TODO 3wc: this is a little janky, might be better to make a
  # util_secret_insert function which this and sub_secret_insert can call
  abra__data_="$PW"

  sub_app_secret_insert

  warning "These generated secrets are now stored as encrypted data on your server"
  warning "Please take a moment to make sure you have saved a copy of the passwords"
  warning "Abra is not able to show the password values in plain text again"
  warning "See https://docs.docker.com/engine/swarm/secrets/ for more on secrets"
}

###### .. app run
help_app_run (){
  echo "abra [options] app <app> run [--no-tty] [--user=<user>] <service> <args>...

Run <args>... (often something like 'bash' or 'sh') in <app>'s <service>
container.

OPTIONS
  --no-tty        Don't allocate a TTY; sometimes running \`mysql\` enjoys this
  --user=<user>   Run as the UNIX user <user>, e.g. for running Wordpress-CLI
                  as www-data

EXAMPLES
  abra wordpress_foo_bar run app bash

POWERED BY
  CONTAINER_ID=\$(docker container ls -f ...)
  docker exec \$CONTAINER_ID ..."
}

sub_app_run(){
  load_instance
  load_instance_env

  if [ -n "$abra___user" ]; then
    RUN_USER="-u $abra___user"
  fi

  if [ "$abra___no_tty" = "true" ]; then
    ARGS="-i"
  else
    ARGS="-it"
  fi

  CONTAINER=$(docker container ls --format "table {{.ID}},{{.Names}}" \
    | grep "${STACK_NAME}_${abra__service_}" | head -n1 | cut -d',' -f1)

  if [ -z "$CONTAINER" ]; then
    error "Can't find a container for ${STACK_NAME}_${abra__service_}"
    exit
  fi

  debug "Using Container ID ${CONTAINER}"

  # 3wc: we want the "splitting" that shellcheck warns us about, so that -u and
  # $RUN_USER aren't treated as a single argument:
  # shellcheck disable=SC2086
  docker exec $RUN_USER $ARGS "$CONTAINER" "$@"

  return
}

###### .. app logs
help_app_logs (){
  echo "abra [options] app <app> logs [<service>]

Show logs for <app>.

OPTIONS
  <service>   Only show logs for a specific service (default: combine all
              services)

EXAMPLES
  abra wordpress_foo_bar logs app

POWERED BY
  docker service logs"
}

sub_app_logs (){
  load_instance
  load_instance_env

  SERVICE="${abra__service_}"

  if [ -z "$SERVICE" ]; then
    stack_logs "${STACK_NAME}"
    return
  fi

  shift

  if [ $# -eq 0 ]; then
    LOGS_ARGS="\
    --follow \
    --tail 20 \
    --no-trunc \
    --details \
    --timestamps"
  else
    # shellcheck disable=SC2124
    LOGS_ARGS=$@
  fi

  # shellcheck disable=SC2086
  docker service logs "${STACK_NAME}_${SERVICE}" $LOGS_ARGS
}

###### .. app cp
help_app_cp (){
  echo "abra [options] app <app> cp <src> <dst>

Copy files to or from a running container.

One of <src> or <dst> must have the format <service>:<path>.

Copying multiple files is possible using \`tar\`, see EXAMPLES.

If <dst> is a file then it will be over-written, if it is a folder then <src>
will be copied into it.

EXAMPLES
  abra customhtml_foo_bar_com cp index.html app:/usr/share/nginx/html/
  tar cf - wp-content | abra wordpress_bar_bat_com cp - app:/var/www/html/

POWERED BY
  CONTAINER_ID=\$(docker container ls -f ...)
  docker cp \$CONTAINER_ID:<src> <dst>
  docker cp \$CONTAINER_ID:<dst> <src>"
}

sub_app_cp() {
  load_instance
  load_instance_env

  SOURCE="${abra__src_}"
  DEST="${abra__dst_}"

  # Get the service name from either SOURCE or DEST
  SERVICE=$(echo "$SOURCE" | grep -o '^[^:]\+:' || echo "$DEST" | grep -o '^[^:]\+:')
  SERVICE=$(echo "$SERVICE" | tr -d ':')

  if [ -z "$SERVICE" ]; then
    echo "Usage: $PROGRAM_NAME cp SERVICE:SRC_PATH DEST_PATH"
    echo "       $PROGRAM_NAME cp SRC_PATH SERVICE:DEST_PATH"
    echo ""
    error "Can't find SERVICE in either SRC or DEST"
  fi

  CONTAINER=$(docker container ls --format "table {{.ID}},{{.Names}}" \
    | grep "${STACK_NAME}_${SERVICE}" | cut -d',' -f1)

  if [ -z "$CONTAINER" ]; then
    error "Can't find a container for ${STACK_NAME}_${SERVICE}"
    exit
  fi

  debug "Using Container ID ${CONTAINER}"

  # Replace $SERVICE with $CONTAINER in the original args
  CP_ARGS=$(echo "$SOURCE $DEST" | sed "s/$SERVICE:/$CONTAINER:/")
  # FIXME 3wc: this might cause problems for filenames with spaces..

  # shellcheck disable=SC2086
  docker cp ${CP_ARGS}
}

#######################################
# abra server ..
#######################################

###### .. server ls
help_server_ls (){
  help_server_list
}

sub_server_ls() {
  sub_server_list
}

help_server_list (){
  echo "abra [options] server (list|ls)

List locally-defined servers."
}

sub_server_list() {
  get_servers
  printf "%s servers:\n\n" "${#SERVERS[@]}"
  for SERVER in "${SERVERS[@]}"; do
    echo "  ${SERVER##*/}"
  done
}

###### .. server init
help_server_init (){
  echo "abra [options] server init

Set up a server for Docker swarm joy.

POWERED BY
  docker swarm init
  docker network create ..."
}

sub_server_init() {
  export DOCKER_CONTEXT="${abra__host_}"

  load_context

  docker swarm init || true
  docker network create --driver=overlay proxy --scope swarm || true
}

###### .. server add
help_server_add (){
  echo "abra [options] server add <host> [<user>] [<port>]

Add a server, reachable on <host>.

OPTIONS
  <user>, <port>    SSH connection details

POWERED BY
  docker context create ..."
}

sub_server_add() {
  require_abra_dir

  HOST="$abra__host_"
  USERNAME="$abra__user_"
  PORT="$abra__port_"

  if [ -n "$PORT" ]; then
    PORT=":$PORT"
  fi

  if [ -n "$USERNAME" ]; then
    USERNAME="$USERNAME@"
  fi

  docker context create "$HOST" \
    --docker "host=ssh://$USERNAME$HOST$PORT" \
    || true

  mkdir -p "$ABRA_DIR/servers/$HOST"
}

###### .. server <host> delete
help_server_rm (){
  help_server_delete
}

sub_server_rm() {
  sub_server_delete
}

help_server_delete (){
  echo "abra [options] server <host> delete

Remove server <host>

POWERED BY
  docker context rm ..."
}

sub_server_delete() {
  docker context rm  "$abra__host_"
}

###### .. server <host> apps
help_server_apps (){
  echo "abra [options] server <host> apps [--status]

Alias for \`abra app ls --server=<host>.

OPTIONS
  --status           Show whether apps are deployed (warning! slow!)

POWERED BY (for --status)
  docker stack ls"
}

sub_server_apps() {
  abra___server="$abra__host_"
  sub_app_list
}

#######################################
# Misc commands
#######################################

###### .. upgrade
help_upgrade (){
  echo "abra [options] upgrade

Upgrade abra itself, using the online installer script."
}

sub_upgrade() {
  curl https://install.abra.autonomic.zone | bash
}

###### .. version
help_version (){
  echo "abra [options] version

Show the installed version of abra (currently $ABRA_VERSION)."
}

sub_version() {
  echo "$ABRA_VERSION"
}

###### .. help
help_help (){
  echo "HEEEEEELP! 😱"
}

sub_help() {
  SUBCOMMAND=$(IFS="_"; echo "${abra__subcommands_[*]}")
  if [ -z "$SUBCOMMAND" ]; then
    printf "%s" "$DOC"
    exit
  fi
  HELP_CMD="help_${SUBCOMMAND}"
  if type "$HELP_CMD" > /dev/null 2>&1; then
    "$HELP_CMD"
  else
    HELP_COMMANDS=$(declare -Ff | grep 'help_' | cut -d' ' -f3 | sed 's/_/ /g')
    error "No help found for '$abra__subcommands_'

Try one of these:
${HELP_COMMANDS//help /}"
  fi
}

#######################################
# cheeky docker aliases
#######################################

###### .. stack <args>...
sub_stack() {
  # shellcheck disable=SC2068
  docker stack $@
}

###### .. volume <args>...
sub_volume() {
  # shellcheck disable=SC2068
  docker volume $@
}

###### .. network <args>...
sub_network() {
  # shellcheck disable=SC2068
  docker network $@
}

#######################################
# Main
#######################################

abra() {
  # TODO (3wc): we either need to do this, or add 'shellcheck disable' all over
  # the place to handle the dynamically-defined vars
  declare abra___stack abra___env abra__command_ abra__args_ \
    abra__secret_ abra__version_ abra__data_ abra___user abra__host_ \
    abra__type_ abra__port_ abra__user_ abra__service_ abra__src_ abra__dst_ \
    abra___server abra___domain abra___force abra___pass \
    abra___secrets abra___status abra___no_tty abra___app_name \
    abra__subcommands_ abra___skip_update abra___skip_check \
    abra__backup_file_ abra___verbose abra___debug abra___help \
    abra___update

  if ! type tput > /dev/null 2>&1; then
    tput() {
      echo -n
    }
  fi

  DOCOPT_PREFIX=abra_
  DOCOPT_ADD_HELP=false
  eval "$(docopt "$@")"

  # --stack <stack>
  STACK_NAME=$abra___stack

  # --env <env>
  if [ -n "$abra___env" ]; then
    set -a
    # shellcheck disable=SC1090
    source "$abra___env" || error "Unable to load env from '$abra___env'"
    set +a
  fi

  load_abra_sh

  # Search for sub_* functions, and check if any of them matches enabled
  # arguments (i.e. is a command and is specified)
  for SUBCOMMAND in $(declare -Ff | grep 'sub_' | cut -d' ' -f3 | sort -r); do
    IFS='_' read -r -a PARTS <<< "$SUBCOMMAND"
    for PART in "${PARTS[@]:1}"; do
      # TODO 3wc: probably a better way to check if a variable is defined..
      VAR=$(eval "echo \$abra_$PART")
      if [ ! "$VAR" == "true" ]; then
        continue 2
      fi
    done
    abra__command_=$(IFS="_"; echo "${PARTS[*]:1}")
    break
  done

  if [ "$abra___help" = "true" ]; then
    if [ -z "$abra__command_" ]; then
      # shellcheck disable=SC2059
      printf "$DOC"
      exit
    elif type "help_${abra__command_}" > /dev/null 2>&1; then
      "help_${abra__command_}"
      exit
    else
      error "No help for '$abra__command_'"
    fi
  fi

  # Use abra__command_ in case `command` is provided (i.e. `volume` or `stack`)
  CMD="sub_${abra__command_}"
  if type "$CMD" > /dev/null 2>&1; then
    # shellcheck disable=SC2086
    "$CMD" ${abra__args_[*]}
  else
    docopt_exit
  fi
}

abra "$@"