✨ Add a few cli commands, better output

Fix: #19
Fix: #8

README.md

@@ -119,6 +119,16 @@ should), but you don’t want your devs waiting 15 minutes to see if their
 commit passed. Instead, you want them to wait a few seconds for all that to
 run locally, maybe in parallel.
 
+You may argue that all these checks should be done automatically by editors
+with on-save hooks. But there are a few reasons that often doesn't happen:
+
+- not all developers know how or bother
+- some types of checks are difficult to run automatically, or editors don't
+  have packages to run such checks
+- some checks may be a bit too slow to run frequently in an editor
+
+So in this regard, Captain takes the onus off all the developers’ editors.
+
 ### Captain’s key features
 
 Specifically, here are some of **Captain's features** you don't want to have
@@ -141,7 +151,7 @@ to invent, write, and/or wrap around every tool you run:
 You can think of Captain as like moving your fancy CI setup into everyone’s
 local control. The output is reminiscent of Github Actions, but way easier to
 set up, runs automatically whenever you use git, and delivers the red and
-green a kajillion times faster.
+green a kajillion times faster (aim for not more than a couple seconds).
 
 ## Why Captain instead of another hook manager?
 
@@ -170,10 +180,8 @@ Captain also has most of the features of other managers:
 
 ## Installation
 
-### Sneaking it in
-
 It’s worth noting that no one needs to know you’ve enlisted the Captain. You
-can do all the following and put `capt` to work for just yourself to start out
+can do the following steps to put `capt` to work for just yourself to start out
 with. You’ll commit a `.capt/` dir with some innocuous tiny files and point
 your own `git` config to use the Captain’s hooks instead of the pedestrian
 hooks you may have in `.git/hooks`.
@@ -276,6 +284,12 @@ a script (or at least a doc) for getting all the tooling installed. It might
 be just a bunch of dnf/apt-get/pacman/brew commands, or it could even be an
 ansible file.
 
+## Usage
+
+The `capt` CLI has a few built-in commands, such as `help`, `edit` (open
+editor on control files), `list` (see active hooks), and more. Use `help` to
+see them all and their documentation.
+
 ## Control File Spec
 
 Now onto the simple `.capt/share.sh` control file at the root of your repo

bin/capt

@@ -68,10 +68,10 @@ typeset -A builtin_helps=(
 )
 
 typeset -A command_helps=(
-    help 'show help with descriptions of built-in triggers'
-    list 'list the active hooks'
-    edit 'open the share.sh control file'
-    editlocal 'open the local.sh personal control file'
+    help    'show help with descriptions of built-in triggers'
+    list    'list the active hooks'
+    edit    'open the share.sh (and local.sh if exists) control file'
+    scripts 'list available scripts'
 )
 
 if [[ $@[1] == 'help' ]]; then
@@ -89,11 +89,45 @@ if [[ $@[1] == 'help' ]]; then
     # print $builtin_helps
     # print ${builtin_helps[kondo]}
     print "\nBuilt-in available triggers:"
-    for b in ${(k)builtin_helps}; do printf '  %-16s%s\n' $b ${builtin_helps[$b]} ; done
+    for b in ${(k)builtin_helps}; do printf '  %-26s%s\n' "${bold_color}$b$reset_color" ${builtin_helps[$b]} ; done
     print '\nCommands:'
-    print "  ${bold_color}list$reset_color   list of all active hooks"
-    print "  ${bold_color}edit$reset_color   see all active triggers in EDITOR"
-    print "  ${bold_color}setup$reset_color  initialize captain files into project (idempotent)"
+    for b in ${(k)command_helps}; do printf '  %-20s%s\n' "${bold_color}$b$reset_color" ${command_helps[$b]} ; done
+    # print "  ${bold_color}list$reset_color     list of all active hooks"
+    # print "  ${bold_color}edit$reset_color     see all active triggers in EDITOR"
+    # print "  ${bold_color}scripts$reset_color  initialize captain files into project (idempotent)"
+    # print "  ${bold_color}setup$reset_color    initialize captain files into project (idempotent)"
+    exit
+fi
+
+list_available_hooks() {
+    controller=$1
+    for h in $( grep -e '^[a-z_]\+=(' $controller | sed -e 's/_/-/g' -e 's/=(//' ); do
+        print "## $h"
+        local gf=$captdir/hooks/$h
+        if [[ -f $gf ]]; then cat $gf; else print '<custom hook/command>'; fi
+        print
+    done
+}
+if [[ $@[1] == 'list' ]]; then
+    aye "Active hooks in $captfile: (CAPT_FILE)"
+    list_available_hooks $captfile
+    aye "Active hooks in $captfilelocal: (CAPT_LOCALFILE)"
+    list_available_hooks $captfilelocal
+    print -- '----'
+    print "HINT: To see/edit triggers: ${bold_color}capt edit$reset_color"
+    print "HINT: To see your scripts:  ${bold_color}capt scripts$reset_color"
+    exit
+fi
+
+if [[ $@[1] == 'edit' ]]; then
+    aye "Opening EDITOR on $captfile $captfilelocal"
+    $EDITOR $captfile $captfilelocal &
+    exit
+fi
+
+if [[ $@[1] == 'scripts' ]]; then
+    aye "Available scripts in $scriptsdir: (CAPT_SCRIPTSDIR)"
+    ls -1 $scriptsdir
     exit
 fi
 
@@ -403,13 +437,13 @@ run_scripts () {
         else aye "$fg[red]WARNING: Skippin on yer $print_name; $cmd0 and $script be lost at sea.$reset_color"
         fi
         es=$?
-        [[ -n $CAPT_VERBOSE ]] && print -- "$output"
+        [[ -n $CAPT_VERBOSE && -n $output ]] && print -- "$output"
         wait # don't process until background scripts are finished
         tfinal=$(( $(sdate +%s%3N) - $t0 )) units=ms units_color=white
         if (( 1000 < $tfinal )); then tfinal=$(( $tfinal / 1000 )); units=s; units_color=red; fi
         # Bail out on whole run if any script not successful
         if [[ $es -ne 0 && ! -v failok ]]; then
-            print
+            [[ -z $CAPT_VERBOSE ]] && print "\nFAIL: $output"
             # print "$fg[red]    ⠀⠀⠀⠀⠀⠀⠀⠀⣀⣤⣤⣤⣤⣀⡀⠀⠀⠀⠀⠀⠀⠀"
             # print "$fg[red]    ⠀⠀⠀⠀⠀⢀⣴⣿⣿⣿⡿⢿⣿⣿⣿⣷⣄⠀⠀⠀⠀⠀"
             # print "$fg[red]    ⠀⣠⣤⣶⣶⣿⣿⣿⣿⣯⠀⠀⣽⣿⣿⣿⣿⣷⣶⣤⣄⠀"
@@ -423,7 +457,7 @@ run_scripts () {
             # print "$fg[red]    ⠀⠀⠀⠀⢻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠀⠀⠀⠀Status: $es"
             # print "$fg[red]    ⠀⠀⠀⠀⠈⠻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠁⠀⠀⠀⠀"
             # print "$fg[red]    ⠀⠀⠀⠀⠀⠀⠀⠈⠉⠛⠛⠛⠛⠋⠉⠀⠀⠀⠀⠀⠀⠀"
-            print "$fg[red]         "'\\\\'
+            print "\n$fg[red]         "'\\\\'
             print "$fg[red]         (o>     Down to Davey Jones’ locker!"
             print "$fg[red]      ___(()___  Status $es"
             print "$fg[red]         ||"