From 1a649c56cbaaaa9394915a4b6790e3f6e02086e3 Mon Sep 17 00:00:00 2001
From: 3wc <3wc.git@doesthisthing.work>
Date: Sun, 14 Mar 2021 03:33:22 +0200
Subject: [PATCH] Docs & comments

---
 abra | 58 ++++++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 40 insertions(+), 18 deletions(-)

diff --git a/abra b/abra
index e501177..6b412cb 100755
--- a/abra
+++ b/abra
@@ -611,13 +611,14 @@ sub_app_ls (){
 }
 
 help_app_list (){
-  echo "abra [options] app (list|ls) [--status] [--server=<server>]
+  echo "abra [options] app (list|ls) [--status] [--server=<server>] [--type=<type>]
 
 List your exciting apps.
 
 OPTIONS
   --status           Show whether apps are deployed (warning! slow!)
-  --server=<server>  Filter to a specific server
+  --server=<server>  Only show apps on a specific server
+  --type=<type>      Only show apps of the given type
 
 POWERED BY (for --status)
   docker stack ls"
@@ -697,15 +698,16 @@ sub_app_list (){
 
 ###### .. app new
 help_app_new (){
-  echo "abra [options] app new [--server=<server>] [--domain=<domain>] [--pass] [--auto] <type>
+  echo "abra [options] app new [--app-name=<app_name>] [--server=<server>] [--domain=<domain>] [--pass] [--secrets] <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)"
+  --server=<server>       Specify which server to use (default: prompt)
+  --domain=<domain>       Set the domain name (default: prompt)
+  --app-name=<app-name>   Set the app name (default: prompt)
+  --secrets               Auto-generate secrets (default: no)
+  --pass                  Store generated secrets in pass (default: no)"
 }
 
 sub_app_new (){
@@ -714,9 +716,9 @@ sub_app_new (){
   require_abra_dir
   get_servers
 
-  # Note(decentral1se): we are overloading the use of the word "app" on the
-  # interface and therefore try to use the word "type" to refer to "a type of
-  # app" vs. "an instance of an app"
+  # decentral1se: we are overloading the use of the word "app" in the
+  # command-line interface to mean two things -- in the code, we differentiate
+  # between them as $APP ("an instance of an app") and $TYPE ("a kind of app")
   TYPE=$abra__type_
 
   SERVER=$abra___server
@@ -749,6 +751,9 @@ sub_app_new (){
   fi
 
   if [ -z "$APP_NAME" ]; then
+    # e.g.:
+    #   TYPE=custom-html, DOMAIN=foo.bar-baz.com
+    #   -> custom_html_foo_bar_baz_com
     DEFAULT_NAME="${TYPE/-/_}_${DOMAIN//+([.-])/_}"
     read -rp "App name [$DEFAULT_NAME]: " APP_NAME
     if [ -z "$APP_NAME" ]; then
@@ -757,6 +762,8 @@ sub_app_new (){
   fi
 
   if [ ${#APP_NAME} -gt 45 ]; then
+    # 3wc: Docker won't create secret names > 64 characters -- setting a
+    # 45-character limit here is enough for all our secrets so far.
     error "$APP_NAME cannot be longer than 45 characters in length"
   fi
 
@@ -764,7 +771,6 @@ sub_app_new (){
 
   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"
@@ -1058,7 +1064,12 @@ volumes and secrets can be removed with this command.
 OPTIONS
   --force    Live dangerously; skip prompt for confirmation
   --volumes  Delete all storage volumes
-  --secrets  Delete all secrets"
+  --secrets  Delete all secrets
+
+POWERED BY
+  docker volume ls / docker volume rm
+  docker secret ls / docker secret rm
+"
 }
 
 sub_app_delete (){
@@ -1104,7 +1115,10 @@ help_app_secret_insert (){
 Store <data> as a Docker secret called <secret>_<version>.
 
 OPTIONS
-  --pass     Save the secret in \`pass\` as well"
+  --pass     Save the secret in \`pass\` as well
+
+POWERED BY
+  docker secret insert"
 }
 sub_app_secret_insert() {
   SECRET="$abra__secret_"
@@ -1142,7 +1156,11 @@ 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"
+  --force   Live dangerously; skip prompt for confirmation
+
+POWERED BY
+  docker secret rm
+  docker secret ls (for --all)"
 }
 
 sub_app_secret_delete(){
@@ -1182,7 +1200,10 @@ OPTIONS
   <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\`"
+  --pass    Save generated secrets in \`pass\`
+
+POWERED BY
+  docker secret insert"
 }
 
 sub_app_secret_generate(){
@@ -1288,6 +1309,7 @@ EXAMPLES
   abra app wordpress rollback app
 
 POWERED BY
+  CONTAINER_ID=\$(docker container ls -f ...)
   docker service rollback \$CONTAINER_ID ..."
 }
 
@@ -1354,8 +1376,8 @@ 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/
+  abra app customhtml_foo_bar_com cp index.html app:/usr/share/nginx/html/
+  tar cf - wp-content | abra app wordpress_bar_bat_com cp - app:/var/www/html/
 
 POWERED BY
   CONTAINER_ID=\$(docker container ls -f ...)
@@ -1519,7 +1541,7 @@ sub_server_new() {
   source "$ABRA_DIR/plugins/abra-$PROVIDER/abra-$PROVIDER"
 }
 
-##host> delete
+###### .. server delete
 help_server_rm (){
   help_server_delete
 }