plugins/ci migration from v3 to v4

README.md

@@ -6,6 +6,9 @@ In modern developer / dev-ops workflows, scripts require a complex configuration
 Without a better solution, the developer is cursed to copy lines-upon-lines of variables into terminals, create random text artifacts, or maybe even commit secure credentials into source.
 Scwrypts leverages ZSH to give hot-key access to run scripts in such environments.
 
+## Major Version Upgrade Notice
+
+Please refer to [Version 3 to Version 4 Upgrade Path](./docs/upgrade/v3-to-v4.md) when upgrading from scwrypts v3 to scwrypts v4!
 
 ## Dependencies
 Due to the wide variety of resources used by scripting libraries, the user is expected to manually resolve dependencies.

docs/upgrade/v3-to-v4.md

@@ -0,0 +1,254 @@
+# Scwrypts Upgrade v3 to v4 Notes
+
+Scwrypts v4 brings a big update to the *runstring for `zsh`-type scwrypts*.
+I've found some of the boilerplate required by each individual script to be confusing and terse, and the goal here is to make it easier and safer to write and run scwrypts in this critical format.
+
+Jump to [Technical Bits](#technical-bits) if you just want to get started with migration steps.
+The actual migration _should take less than a minute per script_.
+This document is deliberately verbose for future reference when I don't remember how any of this works.
+
+## Ideology and History
+
+Originally (scwrypts v2 and below) wanted to preserve the direct-use of individual scwrypts.
+In those versions, executable files could be executed directly (outside of the `scwrypts` function) and still operate with minimal, unwanted consequences.
+This resulted in a rigid structure which made code-sharing difficult at small scales and untenable in many non-trivial cases.
+
+Scwrypts v3, begrudgingly introduced a pseudo-import syntax with `use`.
+This sought to combat the issues of code-sharing and open up the structure of executable scwrypts to the scwrypts-writer.
+Beyond just clarity, this allowed external libraries to be written and cross-referenced.
+Although "importing" is an odd (anti?)feature to shell scripting, the way libraries could be written and reused was too helpful and I succumbed to write the `import.driver.zsh` module.
+
+
+Throughout v3, I tried to maintain the "executability" of individual scwrypts.
+It's ugly though.
+Every individual scwrypt relies on `import.driver.zsh` and the context set up by the `scwrypts` executable.
+While you _could_ run the executable file directly, it would misbehave at-best and fail pretty reliably.
+
+So... here's v4!
+Scwrypts v4 accepts the reality that, although `zsh` scwrypts are zsh, they do not stand alone without the proper context setup provided by `scwrypts`.
+To improve usability, I've abstracted much of the boilerplate so you never have to see it.
+I've injected safety mechanisms like `--help` arguments and utility mechanisms like flag separation (`-abc` is really `-a -b -c`) into all v4 zsh scwrypts.
+
+You don't have to worry about checking the context, v4 does that for you!
+
+You don't have to worry about execution, v4 does that for you!
+
+So!
+
+Are you coupling your zsh scripts to `scwrypts` when you write them? Yes.
+Is that a bad thing? I don't think so.
+Shell-scripting is such a critical coupler to real-life systems.
+High-risk-high-impact to SLAs means we cannot allow context mistakes by sysadmins and users.
+Reusability between local machine, cloud runtime, and CI pipelines is a must.
+And if you have a need to reign all that in to single, isolated executable files...
+
+...then good luck <3
+
+## Technical Bits
+
+Big idea: let's get rid of v3 boilerplate and make things easy.
+
+### Your executable must be in a MAIN function
+
+A main function in shell scripts?
+Weird!
+Don't worry, it's easy.
+
+Take your original scwrypt, and slap the executable stuff into a function called `MAIN` (yes, it must be _exactly_, all-caps `MAIN`):
+
+```diff
+#!/bin/zsh
+#####################################################################
+DEPENDENCIES+=(dep-function-a dep-function-b)
+REQUIRED_ENV+=()
+
+use do/awesome/stuff --group my-custom-library
+
+CHECK_ENVIRONMENT
+#####################################################################
+
+- echo "do some stuff here"
+- # ... etc ...
+- SUCCESS "completed the stuff"
++ MAIN() {
++     echo "do some stuff here"
++     # ... etc ...
++     SUCCESS "completed the stuff
++ }
+```
+
+**Don't invoke the function!**
+Scwrypts will now do that on your behalf.
+I've already written many scwrypts which _almost_ used this syntax.
+All I had to do in this case was delete the function invocation at the end:
+
+```diff
+# ... top boilerplate ...
+MAIN() {
+    SUCCESS "look at me I'm so cool I already wrote this in a main function"
+}
+-
+- #####################################################################
+- MAIN $@
+```
+
+Again, **do not invoke the function**. Just name it `MAIN` and you're good-to-go!
+
+### Great news!
+
+Great news!
+We have finished with *all of the necessary steps* to migrate to v4!
+Easy!
+
+While you're here, let's do a couple more things to cleanup your scwrypts (I promise they are also easy and will take less than a few seconds for each)!
+
+### Remove the boilerplate
+
+Were you confused by all that garbage at the top?
+Awesome!
+Just get rid of any of it you don't use.
+
+While you _probably_ will still need whatever dependencies you already defined, feel free to get rid of empty config lists like `DEPENDENCIES+=()`.
+For non-empty lists, the syntax remains the same (use the `+=` and make sure it's an array-type `()` just like before!)
+
+Also you can ditch the `CHECK_ENVIRONMENT`.
+While it won't hurt, v4 already does this, so just get rid of it.
+Here's my recommended formatting:
+```diff
+#!/bin/zsh
+- #####################################################################
+DEPENDENCIES+=(dep-function-a dep-function-b)
+- REQUIRED_ENV+=()
+
+use do/awesome/stuff --group my-custom-library
+- 
+- CHECK_ENVIRONMENT
+#####################################################################
+
+MAIN() {
+    echo "do some stuff here"
+    # ... etc ...
+    SUCCESS "completed the stuff
+}
+```
+
+
+### Get rid of `--help` argument processing
+
+Scwrypts v4 injects the `--help` argument into every zsh scwrypt.
+So there's no need to process it manually anymore!
+
+We can now eliminate the help case from any MAIN body or library function:
+
+```diff
+MAIN() {
+    while [[ $# -gt 0 ]]
+    do
+        case $1 in
+            # ... a bunch of cases ...
+-            -h | --help ) USAGE; return 0 ;;
+            # ... a bunch of cases ...
+        esac
+        shift 1
+    done
+}
+```
+
+While you probably weren't doing this, you can also do the same for any logic which splits arguments input like `-abc` which should be read as `-a -b -c`.
+If you know how to do this, you know how to get rid of it.
+
+### Write some help docs
+
+Okay this one might take a little bit of time if you haven't done it already (but this is the last recommended step! hang in there and make your stuff better!).
+If you _have_ done it already, typically by writing a variable called "USAGE" in your code, maybe consider the _new and improved_ way to write your help strings.
+
+Returning to our original `MAIN()` example, I'll add some options parsing so we should now look something like this:
+```sh
+#!/bin/zsh
+DEPENDENCIES+=(dep-function-a dep-function-b)
+
+use do/awesome/stuff --group my-custom-library
+#####################################################################
+
+MAIN() {
+    local A
+    local B=false
+    local ARGS=()
+
+    while [[ $# -gt 0 ]]
+    do
+        case $1 in
+            -a | --option-a ) A=$2; shift 1 ;;
+
+            -b | --allow-b ) B=true ;;
+
+            * ) ARGS+=($1) ;;
+        esac
+        shift 1
+    done
+
+    echo "A : $A\nB : $B\nARGS : $ARGS"
+}
+```
+
+All we have to do is add some usage variables and we're done!
+I want to call out a few specific ones:
+- `USAGE__options` provides descriptions for CLI flags like `-a` `--some-flag` and `-a <some value>` (reminder, you *don't* need '-h, --help' anymore!)
+- `USAGE__args` provides descriptions for non-flag CLI arguments, where order matters (e.g. `cat file-a file-b ... etc`)
+- `USAGE__description` provides the human-readable description of what your function does
+- `USAGE__usage` you probably don't need to adjust this one, but it will be everything after the `--` in the usage-line. Defaults to include `[...options...]`, but I suppose you might want to write `USAGE__usage+=' [...args...]` if you 1) have args and 2) are really specific about your help strings.
+
+Just add another section to define these values before declaring `MAIN`:
+```sh
+#!/bin/zsh
+DEPENDENCIES+=(dep-function-a dep-function-b)
+
+use do/awesome/stuff --group my-custom-library
+#####################################################################
+
+USAGE__options='
+  -a, --option-a <string>   sets the value of the A variable
+  -b, --allow-b             enables the B option
+'
+
+# remember there's no specific formatting here, just write it nice
+USAGE__args='
+  N-args   All remaining args are inserted into the ARGS variable
+'
+
+USAGE__description="
+    This is my cool example function. It's really neato, but does
+    very little.
+"
+
+#####################################################################
+
+MAIN() {
+    # ... etc ...
+}
+
+```
+
+Now, when we run `scwrypts my sample -- --help`, we get:
+```txt
+usage: scwrypts my sample -- [...options...]
+
+args:
+  N-args   All remaining args are inserted into the ARGS variable
+
+options:
+  -a, --option-a <string>   sets the value of the A variable
+  -b, --allow-b             enables the B option
+
+  -h, --help   display this message and exit
+
+This is my cool example function. It's really neato, but does
+very little.
+```
+
+### All done
+
+No more recommendations at this time.
+Someday I'll have an auto-formatter and a language server to help with go-to-definition, but that's still for the future.
+
+Thanks for your time and welcome to v4!

plugins/ci/check-all-dependencies

@@ -1,9 +1,5 @@
 #!/bin/zsh
 #####################################################################
-DEPENDENCIES+=()
-REQUIRED_ENV+=()
-#####################################################################
-
 MAIN() {
 	cd "$SCWRYPTS_ROOT__scwrypts/"
 
@@ -35,6 +31,3 @@ MAIN() {
 	echo $DEPENDENCIES | sed 's/ /\n/g'
 	CHECK_ENVIRONMENT && SUCCESS "all dependencies satisfied"
 }
-
-#####################################################################
-MAIN $@

plugins/kubectl/get-context

@@ -1,16 +1,7 @@
 #!/bin/zsh
-#####################################################################
-DEPENDENCIES+=()
-REQUIRED_ENV+=()
-
 use kubectl --group kubectl
-
-CHECK_ENVIRONMENT
 #####################################################################
 
 MAIN() {
 	KUBECTL__GET_CONTEXT
 }
-
-#####################################################################
-MAIN $@

plugins/kubectl/get-namespace

@@ -1,16 +1,7 @@
 #!/bin/zsh
-#####################################################################
-DEPENDENCIES+=()
-REQUIRED_ENV+=()
-
 use kubectl --group kubectl
-
-CHECK_ENVIRONMENT
 #####################################################################
 
 MAIN() {
 	KUBECTL__GET_NAMESPACE
 }
-
-#####################################################################
-MAIN $@

plugins/kubectl/meta/get-static-redis-definition

@@ -1,11 +1,7 @@
 #!/bin/zsh
-#####################################################################
-DEPENDENCIES+=()
-REQUIRED_ENV+=()
-
 use redis --group kubectl
-
-CHECK_ENVIRONMENT
 #####################################################################
 
-echo $(REDIS --get-static-definition)
+MAIN() {
+	echo $(REDIS --get-static-definition)
+}

plugins/kubectl/serve

@@ -1,11 +1,5 @@
 #!/bin/zsh
-#####################################################################
-DEPENDENCIES+=()
-REQUIRED_ENV+=()
-
 use kubectl --group kubectl
-
-CHECK_ENVIRONMENT
 #####################################################################
 
 MAIN() {
@@ -53,6 +47,3 @@ MAIN() {
 
 	KUBECTL__SERVE 
 }
-
-#####################################################################
-MAIN $@

plugins/kubectl/set-context

@@ -1,11 +1,5 @@
 #!/bin/zsh
-#####################################################################
-DEPENDENCIES+=()
-REQUIRED_ENV+=()
-
 use kubectl --group kubectl
-
-CHECK_ENVIRONMENT
 #####################################################################
 
 MAIN() {
@@ -45,6 +39,3 @@ MAIN() {
 
 	KUBECTL__SET_CONTEXT $CONTEXT
 }
-
-#####################################################################
-MAIN $@

plugins/kubectl/set-namespace

@@ -1,11 +1,5 @@
 #!/bin/zsh
-#####################################################################
-DEPENDENCIES+=()
-REQUIRED_ENV+=()
-
 use kubectl --group kubectl
-
-CHECK_ENVIRONMENT
 #####################################################################
 
 MAIN() {
@@ -45,6 +39,3 @@ MAIN() {
 
 	KUBECTL__SET_NAMESPACE $NAMESPACE
 }
-
-#####################################################################
-MAIN $@

run

@@ -1,12 +1,13 @@
 #!/bin/zsh
 export EXECUTION_DIR=$(pwd)
 source "${0:a:h}/zsh/lib/import.driver.zsh" || exit 42
-
 #####################################################################
-
-__RUN() {
+() {
+	cd "$SCWRYPTS_ROOT__scwrypts"
+	GIT_SCWRYPTS() { git -C "$SCWRYPTS_ROOT__scwrypts" $@; }
+	local ERRORS=0
 	local USAGE='
-		usage: scwrypts [... options ...] [patterns] -- [...script options...]
+		usage: scwrypts [...options...] [...patterns...] -- [...script options...]
 
 		options:
 		  selection
@@ -18,9 +19,13 @@ __RUN() {
 		  runtime
 		    -y, --yes              auto-accept all [yn] prompts through current scwrypt
 		    -e, --env <env-name>   set environment; overwrites SCWRYPTS_ENV
-		    -q, --quiet            run in quiet mode
-		    -n, --no-log           skip the log file and run in quiet mode
-		    -v, --verbose          override quiet mode settings and print all debug dialogue
+		    -n                     shorthand for "--verbosity 0"
+		    -v, --verbosity [0-4]  set scwrypts log level to one of the following:
+			                         0 : only command output and critical failures; skips logfile
+			                         1 : add success / failure messages
+			                         2 : (default) include status update messages
+			                         3 : include warning messages
+			                         4 : include debug messages
 
 		  alternate commands
 		    -h, --help        display this message and exit
@@ -28,27 +33,28 @@ __RUN() {
 		        --list-envs   print out environment list and exit
 		        --update      update scwrypts library to latest version
 		        --version     print out scwrypts version and exit
-		
+
 		patterns:
 		  - a list of glob patterns to loose-match a scwrypt by name
 
 		script options:
 		  - everything after "--" is forwarded to the scwrypt you run
-		    (usually "-- --help" will provide more information)
+		    ("-- --help" will provide more information)
 	'
-	cd "$SCWRYPTS_ROOT"
+
+	#####################################################################
+	### cli argument parsing and global configuration ###################
+	#####################################################################
 
 	local ENV_NAME="$SCWRYPTS_ENV"
 	local SEARCH_PATTERNS=()
 
 	local VARSPLIT SEARCH_GROUP SEARCH_TYPE SEARCH_NAME
 
-	local ALLOW_LOGFILE=1
-	local VERBOSE=1
-
-	[ $CI ] && [ ! $SCWRYPTS_CI_FORCE_NON_VERBOSE ] && VERBOSE=2
-
-	local ERROR=0
+	[ ! $SCWRYPTS_LOG_LEVEL ] && {
+		local SCWRYPTS_LOG_LEVEL
+		[ $CI ] && SCWRYPTS_LOG_LEVEL=3 || SCWRYPTS_LOG_LEVEL=2
+	}
 
 	while [[ $# -gt 0 ]]
 	do
@@ -58,30 +64,44 @@ __RUN() {
 				set -- $(echo " $VARSPLIT ") ${@:2}
 				;;
 
-			-h | --help ) USAGE; return 0 ;;
-			-l | --list ) SCWRYPTS__GET_AVAILABLE_SCWRYPTS; return 0 ;;
-			--list-envs ) SCWRYPTS__GET_ENV_NAMES; return 0 ;;
+			### alternate commands ###################
+
+			-h | --help )
+				USAGE
+				return 0
+				;;
+
+			-l | --list )
+				SCWRYPTS__GET_AVAILABLE_SCWRYPTS
+				return 0
+				;;
+
+			--list-envs )
+				SCWRYPTS__GET_ENV_NAMES
+				return 0
+				;;
+
 			--version )
-				echo scwrypts $(git -C "$SCWRYPTS__ROOT__scwrypts" describe --tags)
+				echo scwrypts $(GIT_SCWRYPTS describe --tags)
 				return 0
 				;;
 
 			--update )
-				cd "$SCWRYPTS__ROOT__scwrypts"
-				git fetch --quiet origin main
-				git fetch --quiet origin main --tags
+				GIT_SCWRYPTS fetch --quiet origin main
+				GIT_SCWRYPTS fetch --quiet origin main --tags
 				local SYNC_STATUS=$?
 
-				git diff --exit-code origin/main -- . >&2
+				GIT_SCWRYPTS diff --exit-code origin/main -- . >/dev/null 2>&1
 				local DIFF_STATUS=$?
 
 				[[ $SYNC_STATUS -eq 0 ]] && [[ $DIFF_STATUS -eq 0 ]] && {
 					SUCCESS 'already up-to-date with origin/main'
 				} || {
-					git rebase --autostash origin/main \
+					GIT_SCWRYPTS rebase --autostash origin/main \
 						&& SUCCESS 'up-to-date with origin/main' \
+						&& GIT_SCWRYPTS log -n1 \
 						|| {
-							git rebase --abort
+							GIT_SCWRYPTS rebase --abort
 							ERROR 'unable to update scwrypts; please try manual upgrade'
 							REMINDER "installation in '$(pwd)'"
 						}
@@ -89,41 +109,52 @@ __RUN() {
 				return 0
 				;;
 
+			### scwrypts filters #####################
+
 			-m | --name )
-				[ ! $2 ] && ERROR "missing value for argument $1" && break
+				[ $2 ] || { ERROR "missing value for argument $1"; break; }
 				SEARCH_NAME=$2
 				shift 1
 				;;
 
 			-g | --group )
-				[ ! $2 ] && ERROR "missing value for argument $1" && break
+				[ $2 ] || { ERROR "missing value for argument $1"; break; }
 				SEARCH_GROUP=$2
 				shift 1
 				;;
 
 			-t | --type )
-				[ ! $2 ] && ERROR "missing value for argument $1" && break
+				[ $2 ] || { ERROR "missing value for argument $1"; break; }
 				SEARCH_TYPE=$2
 				shift 1
 				;;
 
-			-y | --yes     ) export __SCWRYPTS_YES=1 ;;
-			-q | --quiet   ) VERBOSE=0 ;;
-			-n | --no-log  ) VERBOSE=0 ; [ ! $SUBSCWRYPT ] && SUBSCWRYPT=0 ;;
-			-v | --verbose ) VERBOSE=2 ;;
+			### runtime settings #####################
+
+			-y | --yes ) export __SCWRYPTS_YES=1 ;;
+
+			-n | --no-log )
+				SCWRYPTS_LOG_LEVEL=0
+				[[ $1 =~ ^--no-log$ ]] && WARNING 'the --no-log flag is deprecated and will be removed in scwrypts v4.2'
+				;;
+
+			-v | --verbosity )
+				[[ $2 =~ ^[0-4]$ ]] || ERROR "invalid setting for verbosity '$2'"
+				SCWRYPTS_LOG_LEVEL=$2
+				shift 1
+				;;
 
 			-e | --env )
-				[ ! $2 ] && ERROR "missing value for argument $1" && break
-				[ ! $SUBSCWRYPTS ] \
-					&& [ $ENV_NAME ] \
-					&& WARNING 'overwriting session environment' \
-					;
+				[ $2 ] || { ERROR "missing value for argument $1"; break; }
+
+				[ $ENV_NAME ] && DEBUG 'overwriting session environment'
 
 				ENV_NAME="$2"
 				STATUS "using CLI environment '$ENV_NAME'"
 				shift 1
 				;;
 
+			##########################################
 
 			--  ) shift 1; break ;; # pass arguments after '--' to the scwrypt
 			--* ) ERROR "unrecognized argument '$1'" ;;
@@ -139,26 +170,20 @@ __RUN() {
 
 	CHECK_ERRORS
 
-	##########################################
+	#####################################################################
+	### scwrypts selection / filtering ##################################
+	#####################################################################
 
 	local SCWRYPTS_AVAILABLE
-	local POTENTIAL_ERROR="no such scwrypt exists:"
-
 	SCWRYPTS_AVAILABLE=$(SCWRYPTS__GET_AVAILABLE_SCWRYPTS)
 
-	[ $SEARCH_NAME ] && {
-		POTENTIAL_ERROR+="\n   NAME     : '$SEARCH_NAME'"
-		POTENTIAL_ERROR+="\n   TYPE     : '$SEARCH_TYPE'"
-		POTENTIAL_ERROR+="\n   GROUP    : '$SEARCH_GROUP'"
-		SCWRYPTS_AVAILABLE=$({
-			echo $SCWRYPTS_AVAILABLE | head -n1
-			echo $SCWRYPTS_AVAILABLE | sed -e 's/\x1b\[[0-9;]*m//g' | grep "^$SEARCH_NAME *$SEARCH_TYPE *$SEARCH_GROUP\$"
-		})
-	}
+	##########################################
 
-	[ ! $SEARCH_NAME ] && {
+	[ $SEARCH_NAME ] && SCWRYPTS_AVAILABLE=$({
+		echo $SCWRYPTS_AVAILABLE | head -n1
+		echo $SCWRYPTS_AVAILABLE | sed -e 's/\x1b\[[0-9;]*m//g' | grep "^$SEARCH_NAME *$SEARCH_TYPE *$SEARCH_GROUP\$"
+	}) || {
 		[ $SEARCH_TYPE ] && {
-			POTENTIAL_ERROR+="\n   TYPE     : '$SEARCH_TYPE'"
 			SCWRYPTS_AVAILABLE=$(\
 				{
 					echo $SCWRYPTS_AVAILABLE | head -n1
@@ -171,7 +196,6 @@ __RUN() {
 		}
 
 		[ $SEARCH_GROUP ] && {
-			POTENTIAL_ERROR+="\n   GROUP    : '$SEARCH_GROUP'"
 			SCWRYPTS_AVAILABLE=$(
 				{
 					echo $SCWRYPTS_AVAILABLE | head -n1
@@ -198,41 +222,47 @@ __RUN() {
 		}
 	}
 
-	[[ $(echo $SCWRYPTS_AVAILABLE | wc -l) -lt 2 ]] && ERROR "$POTENTIAL_ERROR"
-
-	CHECK_ERRORS
+	[[ $(echo $SCWRYPTS_AVAILABLE | wc -l) -lt 2 ]] && {
+		FAIL 1 "$(echo "
+		no such scwrypt exists
+		  NAME     : '$SEARCH_NAME'
+		  TYPE     : '$SEARCH_TYPE'
+		  GROUP    : '$SEARCH_GROUP'
+		  PATTERNS : '$SEARCH_PATTERNS'
+		" | sed "1d; \$d; /''$/d")"
+	}
 
 	##########################################
 
-	local NAME="$SEARCH_NAME"
-	local TYPE="$SEARCH_TYPE"
-	local GROUP="$SEARCH_GROUP"
+	[[ $(echo $SCWRYPTS_AVAILABLE | wc -l) -eq 2 ]] \
+		&& SCWRYPT_SELECTION=$(echo $SCWRYPTS_AVAILABLE | tail -n1) \
+		|| SCWRYPT_SELECTION=$(echo $SCWRYPTS_AVAILABLE | FZF "select a script to run" --header-lines 1) \
+		;
 
-	[[ $(echo $SCWRYPTS_AVAILABLE | wc -l) -eq 2 ]] && {
-		SCWRYPT_SELECTION=$(echo $SCWRYPTS_AVAILABLE | tail -n1)
-		[[ $VERBOSE -eq 2 ]] || VERBOSE=0
-	} || {
-		SCWRYPT_SELECTION=$(echo $SCWRYPTS_AVAILABLE | FZF "select a script to run" --header-lines 1)
-	}
 	[ $SCWRYPT_SELECTION ] || exit 2
 
+	##########################################
+
+	local NAME TYPE GROUP
 	SCWRYPTS__SEPARATE_SCWRYPT_SELECTION $SCWRYPT_SELECTION
 
 	export SCWRYPT_NAME=$NAME
 	export SCWRYPT_TYPE=$TYPE
 	export SCWRYPT_GROUP=$GROUP
 
-	##########################################
+	#####################################################################
+	### environment variables and configuration validation ##############
+	#####################################################################
+
+	local ENV_REQUIRED=true \
+		&& [ ! $CI ] \
+		&& [[ ! $SCWRYPT_NAME =~ scwrypts/logs ]] \
+		&& [[ ! $SCWRYPT_NAME =~ scwrypts/environment ]] \
+		|| ENV_REQUIRED=false
 
-	local ENV_REQUIRED=$(__CHECK_ENV_REQUIRED && echo 1 || echo 0)
 	local REQUIRED_ENVIRONMENT_REGEX=$(eval echo '$SCWRYPTS_REQUIRED_ENVIRONMENT_REGEX__'$SCWRYPT_GROUP)
 
-	[ $REQUIRED_ENVIRONMENT_REGEX ] && {
-		[[ $ENV_NAME =~ $REQUIRED_ENVIRONMENT_REGEX ]] \
-			|| FAIL 5 "group '$SCWRYPT_GROUP' requires current environment to match '$REQUIRED_ENVIRONMENT_REGEX' (currently $ENV_NAME)"
-	}
-
-	[[ $ENV_REQUIRED -eq 1 ]] && {
+	[[ $ENV_REQUIRED =~ true ]] && {
 		[ ! $ENV_NAME ] && ENV_NAME=$(SCWRYPTS__SELECT_ENV)
 
 		for GROUP in ${SCWRYPTS_GROUPS[@]}
@@ -249,105 +279,97 @@ __RUN() {
 		export ENV_NAME
 	}
 
+	##########################################
+
 	[ $REQUIRED_ENVIRONMENT_REGEX ] && {
 		[[ $ENV_NAME =~ $REQUIRED_ENVIRONMENT_REGEX ]] \
-			|| FAIL 5 "group '$SCWRYPT_GROUP' requires current environment to match '$REQUIRED_ENVIRONMENT_REGEX' (currently $ENV_NAME)"
+			|| FAIL 5 "group '$SCWRYPT_GROUP' requires current environment name to match '$REQUIRED_ENVIRONMENT_REGEX' (currently $ENV_NAME)"
 	}
 
 	##########################################
 
-	: \
-		&& [ ! $SUBSCWRYPT ] \
-		&& [[ $ENV_NAME =~ prod ]] \
-		&& { __VALIDATE_UPSTREAM_TIMELINE || ABORT; }
+	[ ! $SUBSCWRYPT ] && [[ $ENV_NAME =~ prod ]] && {
+		STATUS "on '$ENV_NAME'; checking diff against origin/main"
+
+		GIT_SCWRYPTS fetch --quiet origin main
+		local SYNC_STATUS=$?
+
+		GIT_SCWRYPTS diff --exit-code origin/main -- . >&2
+		local DIFF_STATUS=$?
+
+		[[ $SYNC_STATUS -eq 0 ]] && [[ $DIFF_STATUS -eq 0 ]] && {
+			SUCCESS 'up-to-date with origin/main'
+		} || {
+			SCWRYPTS_LOG_LEVEL=3 WARNING "you are trying to run in ${__BRIGHT_RED}production${__YELLOW} but $([[ $SYNC_STATUS -ne 0 ]] && echo 'I am unable to verify your scwrypts version')$([[ $DIFF_STATUS -ne 0 ]] && echo 'your scwrypts is out-of-date (diff listed above)')"
+
+			yN 'continue?' || {
+				REMINDER "you can use 'scwrypts --update' to quickly update scwrypts to latest"
+				ABORT
+			}
+		}
+	}
 
 	##########################################
 
 	local RUN_STRING=$(SCWRYPTS__GET_RUNSTRING $SCWRYPT_NAME $SCWRYPT_TYPE $SCWRYPT_GROUP)
-	[ ! $RUN_STRING ] && exit 3
+	[ "$RUN_STRING" ] || return 42
 
-	##########################################
+	#####################################################################
+	### logging and pretty header/footer setup ##########################
+	#####################################################################
 
-	local LOGFILE=$(__GET_LOGFILE)
+	local LOGFILE \
+		&& [[ $SCWRYPTS_LOG_LEVEL -gt 0 ]] \
+		&& [ ! $SUBSCWRYPT ] \
+		&& [[ ! $SCWRYPT_NAME =~ scwrypts/logs ]] \
+		&& [[ ! $SCWRYPT_NAME =~ interactive ]] \
+		&& LOGFILE="$SCWRYPTS_LOG_PATH/$(echo $GROUP/$TYPE/$NAME | sed 's/^\.\///; s/\//\%/g').log" \
+		|| LOGFILE='/dev/null' \
+		;
 
-	local HEADER=$(
-		[[ $VERBOSE -gt 0 ]] || return 0
-		[ $SUBSCWRYPT ] && return 0
-		echo '====================================================================='
-		echo "script : $SCWRYPT_GROUP $SCWRYPT_TYPE $SCWRYPT_NAME"
-		echo "run at : $(date)"
-		echo "config : $ENV_NAME"
-		[ ! $LOGFILE ] && echo '\033[1;33m------------------------------------------\033[0m'
-	)
+	local HEADER FOOTER
 
-	[ ! $LOGFILE ] && {
-		[ $HEADER ] && echo $HEADER
-		[ $SUBSCWRYPT ] && {
-			eval "$RUN_STRING $(printf "%q " "$@")"
-			exit $?
-		} || {
-			eval "$RUN_STRING $(printf "%q " "$@")" </dev/tty >/dev/tty 2>&1
-			exit $?
-		}
+	[[ $SCWRYPTS_LOG_LEVEL -ge 2 ]] && {
+		HEADER=$(
+			echo "
+				=====================================================================
+				script    : $SCWRYPT_GROUP $SCWRYPT_TYPE $SCWRYPT_NAME
+				run at    : $(date)
+				config    : $ENV_NAME
+				verbosity : $SCWRYPTS_LOG_LEVEL
+				\\033[1;33m--- SCWRYPT BEGIN ---------------------------------------------------\\033[0m
+			" | sed 's/^\s\+//; 1d'
+		)
+
+		FOOTER="\\033[1;33m--- SCWRYPT END   ---------------------------------------------------\\033[0m"
 	}
 
+	[ $SUBSCWRYPT ] && {
+		HEADER="\\033[0;33m--- ($SUBSCWRYPT) BEGIN $SCWRYPT_GROUP $SCWRYPT_TYPE $SCWRYPT_NAME ---"
+		FOOTER="\\033[0;33m--- ($SUBSCWRYPT) END   $SCWRYPT_GROUP $SCWRYPT_TYPE $SCWRYPT_NAME ---"
+	}
+
+	#####################################################################
+	### run the scwrypt #################################################
+	#####################################################################
+
+	set -o pipefail
 	{
 		[ $HEADER ] && echo $HEADER
-		[[ $VERBOSE -gt 0 ]] && echo '\033[1;33m--- BEGIN OUTPUT -------------------------\033[0m'
-		(eval "$RUN_STRING $(printf "%q " "$@")")
-		EXIT_CODE=$?
-		[[ $VERBOSE -gt 0 ]] && echo '\033[1;33m--- END OUTPUT ---------------------------\033[0m'
-
+		[[ $LOGFILE =~ ^/dev/null$ ]] && {
+			eval "$RUN_STRING $(printf "%q " "$@")" </dev/tty >/dev/tty 2>&1
+			EXIT_CODE=$?
+		} || {
+			(eval "$RUN_STRING $(printf "%q " "$@")")
+			EXIT_CODE=$?
+		}
+		[ $FOOTER ] && echo $FOOTER
 		[[ $EXIT_CODE -eq 0 ]] && EXIT_COLOR='32m' || EXIT_COLOR='31m'
 
-		[[ $VERBOSE -gt 0 ]] && echo "terminated with\\033[1;$EXIT_COLOR code $EXIT_CODE\\033[0m"
+		[[ $SCWRYPTS_LOG_LEVEL -ge 2 ]] && [ ! $SUBSCWRYPT ] \
+			&& echo "terminated with\\033[1;$EXIT_COLOR code $EXIT_CODE\\033[0m"
+
+		return $EXIT_CODE
 	} 2>&1 | tee --append "$LOGFILE"
 
-	exit $(\
-		sed -n 's/^terminated with.*code \([0-9]*\).*$/\1/p' $LOGFILE \
-			| tail -n1
-	)
-}
-
-#####################################################################
-
-__CHECK_ENV_REQUIRED() {
-	[ $CI ] && return 1
-
-	echo $SCWRYPT_NAME | grep -q 'scwrypts/logs/' && return 1
-	echo $SCWRYPT_NAME | grep -q 'scwrypts/environment/' && return 1
-
-	return 0
-}
-
-__VALIDATE_UPSTREAM_TIMELINE() {
-	STATUS "on '$ENV_NAME'; checking diff against origin/main"
-
-	git fetch --quiet origin main
-	local SYNC_STATUS=$?
-
-	git diff --exit-code origin/main -- . >&2
-	local DIFF_STATUS=$?
-
-	[[ $SYNC_STATUS -eq 0 ]] && [[ $DIFF_STATUS -eq 0 ]] && {
-		SUCCESS 'up-to-date with origin/main'
-	} || {
-		WARNING
-		[[ $SYNC_STATUS -ne 0 ]] && WARNING 'unable to synchronize with origin/main'
-		[[ $DIFF_STATUS -ne 0 ]] && WARNING 'your branch differs from origin/main (diff listed above)'
-		WARNING
-
-		yN 'continue?' || return 1
-	}
-}
-
-__GET_LOGFILE() {
-	[ $SUBSCWRYPT ] && return 0
-	[[ $SCWRYPT_NAME =~ scwrypts/logs ]] && return 0
-	[[ $SCWRYPT_NAME =~ interactive ]] && return 0
-
-	echo "$SCWRYPTS_LOG_PATH/$(echo $GROUP/$TYPE/$NAME | sed 's/^\.\///; s/\//\%/g').log"
-}
-
-#####################################################################
-__RUN $@
+} $@

scwrypts.plugin.zsh

@@ -14,7 +14,7 @@ SCWRYPTS__ZSH_PLUGIN() {
 	which scwrypts >/dev/null 2>&1\
 		&& RBUFFER="scwrypts" || RBUFFER="$SCWRYPTS_ROOT/scwrypts"
 
-	RBUFFER+=" --name $NAME --group $GROUP --type $TYPE --verbose"
+	RBUFFER+=" --name $NAME --group $GROUP --type $TYPE"
 	zle accept-line
 }
 

zsh/hello-world

@@ -1,4 +1,6 @@
 #!/bin/zsh
+#####################################################################
+
 MAIN() {
-	SUCCESS 'hello world!'
+	SUCCESS 'Hello, World!'
 }

zsh/lib/cloud/aws/rds.module.zsh

@@ -86,7 +86,7 @@ RDS__GET_DATABASE_CREDENTIALS() {
 		user-input     ) _RDS_AUTH__userinput ;;
 	esac
 
-	[[ $PRINT_PASSWORD -eq 1 ]] && INFO "password : $DB_PASS"
+	[[ $PRINT_PASSWORD -eq 1 ]] && DEBUG "password : $DB_PASS"
 
 	return 0
 }

zsh/lib/misc/tally.module.zsh

@@ -99,8 +99,8 @@ TALLY() {
 		true  ) printf "$NEW_VALUE" ;;
 		false )
 			case $TALLY_NAME in
-				default ) INFO "current tally : $NEW_VALUE" ;;
-				*       ) INFO "$TALLY_NAME : $NEW_VALUE" ;;
+				default ) SUCCESS "current tally : $NEW_VALUE" ;;
+				*       ) SUCCESS "$TALLY_NAME : $NEW_VALUE" ;;
 			esac
 	esac
 }

zsh/lib/scwrypts/environment-files.module.zsh

@@ -12,7 +12,7 @@ SCWRYPTS__SELECT_ENV() {
 }
 
 SCWRYPTS__SELECT_OR_CREATE_ENV() {
-	SCWRYPTS__GET_ENV_NAMES | FZF_TAIL 'select / create an environment'
+	SCWRYPTS__GET_ENV_NAMES | FZF_USER_INPUT 'select / create an environment'
 }
 
 SCWRYPTS__GET_ENV_FILES() {

zsh/lib/scwrypts/meta.module.zsh

@@ -8,15 +8,13 @@ use scwrypts/run
 
 #####################################################################
 
-SCWRYPTS__RUN() {
+SCWRYPTS__RUN() {  # context wrapper to run scwrypts within scwrypts
 	local EXIT_CODE=0
 	((SUBSCWRYPT+=1))
 
-	echo "--- START SUBSCWRYPT=$SUBSCWRYPT $@"
 	SUBSCWRYPT=$SUBSCWRYPT $SCWRYPTS_ROOT/run $@
 	EXIT_CODE=$?
 
 	((SUBSCWRYPT-=1))
 	return $EXIT_CODE
-	echo "--- END SUBSCWRYPT=$SUBSCWRYPT $@"
 }

zsh/lib/scwrypts/run.module.zsh

@@ -119,12 +119,49 @@ SCWRYPTS__GET_RUNSTRING__zsh() {
 		|| SCWRYPT_FILENAME="$GROUP_PATH/$SCWRYPT_TYPE/$SCWRYPT_NAME" \
 		;
 
-	echo "source '$SCWRYPT_FILENAME'; CHECK_ENVIRONMENT; MAIN"
+	printf "
+		source '$SCWRYPT_FILENAME'
+		CHECK_ENVIRONMENT
+		ERRORS=0
+
+		export USAGE=\"
+			usage: -
+
+			args: -
+
+			options: -
+			  -h, --help      display this message and exit
+
+			description: -
+		\"
+
+		[ ! \$USAGE__usage ] && export USAGE__usage='[...options...]'
+
+		() {
+			local MAIN_ARGS=()
+			local VARSPLIT
+			while [[ \$# -gt 0 ]]
+			do
+				case \$1 in
+					-[a-z][a-z]* )
+						VARSPLIT=\$(echo \"\$1 \" | sed 's/^\\\\(-.\\\\)\\\\(.*\\\\) /\\\\1 -\\\\2/')
+						set -- throw-away \$(echo \" \$VARSPLIT \") \${@:2}
+						;;
+					-h | --help    ) USAGE; exit 0 ;;
+					* ) MAIN_ARGS+=(\$1) ;;
+				esac
+				shift 1
+			done
+			MAIN \${MAIN_ARGS[@]}
+		} "
+
 
 	return 0
 }
 
-SCWRYPTS__GET_RUNSTRING__zsh_v3_compatibility() {
+SCWRYPTS__GET_RUNSTRING__zsh_v3() {
+	WARNING "scwrypts zsh/v3 runstrings are now deprecated; please update to scwrypts v4 format"
+
 	__CHECK_DEPENDENCY zsh || return 1
 
 	[ $(eval echo '$SCWRYPTS_TYPE__'$SCWRYPT_GROUP) ] \
@@ -132,8 +169,6 @@ SCWRYPTS__GET_RUNSTRING__zsh_v3_compatibility() {
 		|| echo "source $GROUP_PATH/$SCWRYPT_TYPE/$SCWRYPT_NAME" \
 		;
 
-	WARNING "scwrypts zsh/v3 runstrings are now deprecated; please update to scwrypts v4 format"
-
 	return 0
 }
 

zsh/lib/utils/colors.zsh

@@ -2,22 +2,22 @@ __BLACK='\033[0;30m'
 __DARK_GRAY='\033[1;30m'
 
 __RED='\033[0;31m'
-__LIGHT_RED='\033[1;31m'
+__BRIGHT_RED='\033[1;31m'
 
 __GREEN='\033[0;32m'
-__LIGHT_GREEN='\033[1;32m'
+__BRIGHT_GREEN='\033[1;32m'
 
-__ORANGE='\033[0;33m'
-__YELLOW='\033[1;33m'
+__YELLOW='\033[0;33m'
+__BRIGHT_YELLOW='\033[1;33m'
 
-__BLUE='\033[1;34m'
-__DARK_BLUE='\033[0;34m'
+__BLUE='\033[0;34m'
+__BRIGHT_BLUE='\033[1;34m'
 
-__PURPLE='\033[1;35m'
-__DARK_PURPLE='\033[0;35m'
+__MAGENTA='\033[0;35m'
+__BRIGHT_MAGENTA='\033[1;35m'
 
-__CYAN='\033[1;36m'
-__DARK_CYAN='\033[0;36m'
+__CYAN='\033[0;36m'
+__BRIGHT_CYAN='\033[1;36m'
 
 __WHITE='\033[1;37m'
 __LIGHT_GRAY='\033[0;37m'
@@ -27,17 +27,17 @@ __COLOR_RESET='\033[0m'
 __GET_RANDOM_COLOR() {
 	local COLORS=(
 		$__RED
-		$__LIGHT_RED
+		$__BRIGHT_RED
 		$__GREEN
-		$__LIGHT_GREEN
-		$__ORANGE
+		$__BRIGHT_GREEN
 		$__YELLOW
+		$__BRIGHT_YELLOW
 		$__BLUE
-		$__DARK_BLUE
-		$__PURPLE
-		$__DARK_PURPLE
+		$__BRIGHT_BLUE
+		$__MAGENTA
+		$__BRIGHT_MAGENTA
 		$__CYAN
-		$__DARK_CYAN
+		$__BRIGHT_CYAN
 		$__WHITE
 	)
 	print "$__COLOR_RESET${COLORS[$(shuf -i 1-${#COLORS[@]} -n 1)]}"

zsh/lib/utils/dependencies.zsh

@@ -1,13 +1,14 @@
 __CHECK_DEPENDENCIES() {
-	local DEP ERROR=0
+	local DEP ERRORS=0
+	local SCWRYPTS_LOG_LEVEL=1
 	[ ! $E ] && E=ERROR
 
 	DEPENDENCIES=($(echo $DEPENDENCIES | sed 's/ \+/\n/g' | sort -u))
 
-	for DEP in ${DEPENDENCIES[@]}; do __CHECK_DEPENDENCY $DEP || ((ERROR+=1)); done
-	__CHECK_COREUTILS || ((ERROR+=$?))
+	for DEP in ${DEPENDENCIES[@]}; do __CHECK_DEPENDENCY $DEP || ((ERRORS+=1)); done
+	__CHECK_COREUTILS || ((ERRORS+=$?))
 
-	return $ERROR
+	return $ERRORS
 }
 
 __CHECK_DEPENDENCY() {

zsh/lib/utils/environment.zsh

@@ -1,4 +1,5 @@
 __CHECK_REQUIRED_ENV() {
+	local SCWRYPTS_LOG_LEVEL=1
 	local VAR ERROR=0
 	REQUIRED_ENV=($(echo $REQUIRED_ENV | sed 's/\s\+/\n/g' | sort -u))
 	for VAR in ${REQUIRED_ENV[@]}; do __CHECK_ENV_VAR $VAR || ((ERROR+=1)); done

zsh/lib/utils/io.fzf.zsh

@@ -0,0 +1,57 @@
+FZF() {
+	[ $CI ] && FAIL 1 'currently in CI, but FZF requires user input'
+
+	local FZF_ARGS=()
+
+	FZF_ARGS+=(-i)
+	FZF_ARGS+=(--ansi)
+	FZF_ARGS+=(--bind=ctrl-c:cancel)
+	FZF_ARGS+=(--height=50%)
+	FZF_ARGS+=(--layout=reverse)
+
+	local SELECTION=$(fzf ${FZF_ARGS[@]} --prompt "$1 : " ${@:2})
+	PROMPT "$1"
+
+	[ $BE_QUIET ] || {
+		[[ $SCWRYPTS_LOG_LEVEL -ge 1 ]] && echo $SELECTION >&2
+	}
+	echo $SELECTION
+	[ $SELECTION ]
+}
+
+FZF_USER_INPUT() { # allow user to type custom answers; reconfirm if ambiguous with select
+	local FZF_OUTPUT=$(BE_QUIET=1 FZF $@ --print-query | sed '/^$/d' | sort -u)
+	[[ $SCWRYPTS_LOG_LEVEL -ge 1 ]] && echo $FZF_OUTPUT | head -n1 >&2
+	[ ! $FZF_OUTPUT ] && return 1
+
+	[[ $(echo "$FZF_OUTPUT" | wc -l) -eq 1 ]] \
+		&& { echo "$FZF_OUTPUT"; return 0; }
+
+	local FZF_OUTPUT=$(
+		echo "$FZF_OUTPUT" \
+			| sed "1s/\$/^$(printf "$__LIGHT_GRAY\\033[3m")<- what you typed$(printf $__COLOR_RESET)/" \
+			| sed "2s/\$/^$(printf "$__LIGHT_GRAY\\033[3m")<- what you selected$(printf $__COLOR_RESET)/" \
+			| column -ts '^' \
+			| BE_QUIET=1 FZF "$@ (clarify)" \
+		)
+
+	[[ $SCWRYPTS_LOG_LEVEL -ge 1 ]] && echo $FZF_OUTPUT >&2
+	FZF_OUTPUT=$(echo $FZF_OUTPUT | sed 's/\s\+<- what you .*$//')
+	echo $FZF_OUTPUT
+	[ $FZF_OUTPUT ]
+}
+
+#####################################################################
+### vvv DEPRECATED vvv ##############################################
+#####################################################################
+
+FZF_HEAD() {  # prefer user input over selected
+	WARNING 'FZF_HEAD is deprecated and will be unavailable in v4.2; please switch to FZF_USER_INPUT (drop-in fix!)'
+	FZF $@ --print-query | sed '/^$/d' | head -n1;
+}
+FZF_TAIL() {  # prefer selected over user input
+	WARNING 'FZF_TAIL is deprecated and will be unavailable in v4.2; please switch to FZF_USER_INPUT (drop-in fix!)'
+	FZF $@ --print-query | sed '/^$/d' | tail -n1;
+}
+
+#####################################################################

zsh/lib/utils/io.print.zsh

@@ -0,0 +1,38 @@
+PRINT() {
+	local MESSAGE
+	local LAST_LINE_END='\n'
+	local STDERR=1
+	local STDOUT=0
+
+	local LTRIM=1
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in
+			-n | --no-trim-tabs ) LTRIM=0 ;;
+			-x | --no-line-end  ) LAST_LINE_END='' ;;
+			-o | --use-stdout   ) STDOUT=1; STDERR=0 ;;
+			* ) MESSAGE+="$(echo $1) " ;;
+		esac
+		shift 1
+	done
+
+	MESSAGE="$(echo "$MESSAGE" | sed 's/%/%%/g')"
+
+	local STYLED_MESSAGE="$({
+		printf "${COLOR}"
+		while IFS='' read line
+		do
+			[[ $PREFIX =~ ^[[:space:]]\+$ ]] && printf '\n'
+
+			printf "${PREFIX} : $(echo "$line" | sed 's/^	\+//; s/ \+$//')"
+
+			PREFIX=$(echo $PREFIX | sed 's/./ /g')
+		done <<< $MESSAGE
+	})"
+	STYLED_MESSAGE="${COLOR}$(echo "$STYLED_MESSAGE" | sed 's/%/%%/g')${__COLOR_RESET}${LAST_LINE_END}"
+
+	[[ $STDERR -eq 1 ]] && printf $STYLED_MESSAGE >&2
+	[[ $STDOUT -eq 1 ]] && printf $STYLED_MESSAGE
+
+	return 0
+}

zsh/lib/utils/io.usage.zsh

@@ -0,0 +1,65 @@
+USAGE() { # formatter for USAGE variable
+	[ ! $USAGE ] && return 0
+	local USAGE_LINE=$(echo $USAGE | grep -i '^[	]*usage *:' | sed 's/^[		]*//')
+
+	[ $USAGE__usage ] && echo $USAGE_LINE | grep -q 'usage: -' \
+		&& USAGE_LINE=$(echo $USAGE_LINE | sed "s/usage: -/usage: $USAGE__usage/")
+
+	[ $__SCWRYPT ] \
+		&& USAGE_LINE=$(
+			echo $USAGE_LINE \
+				| sed "s;^[^:]*:;& scwrypts $SCWRYPT_NAME --;" \
+				| sed 's/ \{2,\}/ /g; s/scwrypts -- scwrypts/scwrypts/' \
+			)
+
+	local THE_REST=$(echo $USAGE | grep -vi '^[		]*usage *:' )
+
+	local DYNAMIC_USAGE_ELEMENT
+	#
+	# create dynamic usage elements (like 'args') by defining USAGE__<element>
+	# then using the syntax "<element>: -" in your USAGE variable
+	#
+	# e.g.
+	#
+	# USAGE__args="
+	#	subcommand arg 1   arg 1 description
+	#   subcommand arg 2   some other description
+	# "
+	#
+	# USAGE="
+	# usage: some-command [...args...]
+	#
+	# args: -
+	#   -h, --help   some arguments are applicable everywhere
+	# "
+	#
+	for DYNAMIC_USAGE_ELEMENT in $(echo $THE_REST | sed -n 's/^\([^:]*\): -$/\1/p')
+	do
+		DYNAMIC_USAGE_ELEMENT_TEXT=$(eval echo '$USAGE__'$DYNAMIC_USAGE_ELEMENT)
+		#[ $DYNAMIC_USAGE_ELEMENT_TEXT ] || continue
+
+
+		case $DYNAMIC_USAGE_ELEMENT in
+			description )
+				DYNAMIC_USAGE_ELEMENT_TEXT=$(echo "$DYNAMIC_USAGE_ELEMENT_TEXT" | perl -p0e 's/^[\n\s]+//')
+			DYNAMIC_USAGE_ELEMENT_TEXT="$__YELLOW\\033[03m$DYNAMIC_USAGE_ELEMENT_TEXT\\033[0m"
+				;;
+			* )
+			DYNAMIC_USAGE_ELEMENT_TEXT=$(echo $DYNAMIC_USAGE_ELEMENT_TEXT | sed 's/[^	]/  &/')
+				;;
+		esac
+
+		THE_REST=$(echo $THE_REST | perl -pe "s$DYNAMIC_USAGE_ELEMENT: -$DYNAMIC_USAGE_ELEMENT:\n$DYNAMIC_USAGE_ELEMENT_TEXT\n\n")
+	done
+
+	# allow for dynamic 'description: -' but delete the 'description:' header line
+	THE_REST=$(echo $THE_REST | sed '/^[		]*description:$/d')
+
+	echo "$__BLUE$USAGE_LINE$__COLOR_RESET\n\n$THE_REST" \
+		| sed "s/^\t\+//; s/\s\+$//; s/^\\s*$//;" \
+		| sed '/./,$!d; :a; /^\n*$/{$d;N;ba;};' \
+		| perl -p0e 's/\n{2,}/\n\n/g' \
+		| perl -p0e 's/:\n{2,}/:\n/g' \
+		| perl -p0e 's/([a-z]+:)\n([a-z]+:)/\2/g' \
+		>&2
+}

zsh/lib/utils/io.zsh

@@ -1,218 +1,104 @@
-PRINT() {
-	local MESSAGE
-	local LAST_LINE_END='\n'
-	local STDERR=1
-	local STDOUT=0
-
-	local LTRIM=1
-	while [[ $# -gt 0 ]]
-	do
-		case $1 in
-			-n | --no-trim-tabs ) LTRIM=0 ;;
-			-x | --no-line-end  ) LAST_LINE_END='' ;;
-			-o | --use-stdout   ) STDOUT=1; STDERR=0 ;;
-			* ) MESSAGE+="$(echo $1) " ;;
-		esac
-		shift 1
-	done
-
-	MESSAGE="$(echo "$MESSAGE" | sed 's/%/%%/g')"
-
-	local STYLED_MESSAGE="$({
-		printf "${COLOR}"
-		while IFS='' read line
-		do
-			[[ $PREFIX =~ ^[[:space:]]\+$ ]] && printf '\n'
-
-			printf "${PREFIX} : $(echo "$line" | sed 's/^	\+//; s/ \+$//')"
-
-			PREFIX=$(echo $PREFIX | sed 's/./ /g')
-		done <<< $MESSAGE
-	})"
-	STYLED_MESSAGE="${COLOR}$(echo "$STYLED_MESSAGE" | sed 's/%/%%/g')${__COLOR_RESET}${LAST_LINE_END}"
-
-	[[ $STDERR -eq 1 ]] && printf $STYLED_MESSAGE >&2
-	[[ $STDOUT -eq 1 ]] && printf $STYLED_MESSAGE
-
-	return 0
-}
+#####################################################################
+### basic colorized print messages ##################################
+#####################################################################
 
+source "${0:a:h}/io.print.zsh"
 [ ! $ERRORS ] && ERRORS=0
-ERROR()    { PREFIX="ERROR    ✖" COLOR=$__RED    PRINT "$@"; ((ERRORS+=1)); }
-SUCCESS()  { PREFIX="SUCCESS  ✔" COLOR=$__GREEN  PRINT "$@"; }
-WARNING()  { PREFIX="WARNING  " COLOR=$__ORANGE PRINT "$@"; }
-STATUS()   { PREFIX="STATUS    " COLOR=$__BLUE   PRINT "$@"; }
-REMINDER() { PREFIX="REMINDER " COLOR=$__PURPLE PRINT "$@"; }
-INFO()     { PREFIX="INFO     ℹ" COLOR=$__WHITE  PRINT "$@"; }
-
-PROMPT() {
-	PREFIX="PROMPT   " COLOR=$__CYAN PRINT "$@"
-	PREFIX="USER     ⌨" COLOR=$__CYAN PRINT '' --no-line-end
-}
-
-FAIL()  { ERROR "${@:2}"; exit $1; }
-ABORT() { FAIL 69 'user abort'; }
-
-CHECK_ERRORS() {
-	local FAIL_OUT=1
-	local DISPLAY_USAGE=1
-
-	while [[ $# -gt 0 ]]
-	do
-		case $1 in
-			--no-fail  ) FAIL_OUT=0 ;;
-			--no-usage ) DISPLAY_USAGE=0 ;;
-		esac
-		shift 1
-	done
-
-	[ ! $ERRORS ] && ERRORS=0
-	[[ $ERRORS -eq 0 ]] && return 0
-
-	[[ $DISPLAY_USAGE -eq 1 ]] && USAGE
-
-	[[ $FAIL_OUT -eq 1 ]] && exit $ERRORS
 
+ERROR() {  # command encountered an error
+	[[ $SCWRYPTS_LOG_LEVEL -ge 1 ]] \
+		&& PREFIX="ERROR    ✖" COLOR=$__RED            PRINT "$@"
+	((ERRORS+=1))
 	return $ERRORS
 }
 
-USAGE() { # formatter for USAGE variable
-	[ ! $USAGE ] && return 0
-	local USAGE_LINE=$(echo $USAGE | grep -i '^[	]*usage *:' | sed 's/^[		]*//')
-
-	[ $USAGE__usage ] && echo $USAGE_LINE | grep -q 'usage: -' \
-		&& USAGE_LINE=$(echo $USAGE_LINE | sed "s/usage: -/usage: $USAGE__usage/")
-
-	[ $__SCWRYPT ] \
-		&& USAGE_LINE=$(
-			echo $USAGE_LINE \
-				| sed "s;^[^:]*:;& scwrypts $SCWRYPT_NAME --;" \
-				| sed 's/ \{2,\}/ /g; s/scwrypts -- scwrypts/scwrypts/' \
-			)
-
-	local THE_REST=$(echo $USAGE | grep -vi '^[		]*usage *:' )
-
-	local DYNAMIC_USAGE_ELEMENT
-	#
-	# create dynamic usage elements (like 'args') by defining USAGE__<element>
-	# then using the syntax "<element>: -" in your USAGE variable
-	#
-	# e.g.
-	#
-	# USAGE__args="
-	#	subcommand arg 1   arg 1 description
-	#   subcommand arg 2   some other description
-	# "
-	#
-	# USAGE="
-	# usage: some-command [...args...]
-	#
-	# args: -
-	#   -h, --help   some arguments are applicable everywhere
-	# "
-	#
-	for DYNAMIC_USAGE_ELEMENT in $(echo $THE_REST | sed -n 's/^\([^:]*\): -$/\1/p')
-	do
-		DYNAMIC_USAGE_ELEMENT_TEXT=$(eval echo '$USAGE__'$DYNAMIC_USAGE_ELEMENT)
-
-		[[ ! $DYNAMIC_USAGE_ELEMENT =~ ^description$ ]] \
-			&& DYNAMIC_USAGE_ELEMENT_TEXT=$(echo $DYNAMIC_USAGE_ELEMENT_TEXT | sed 's/[^	]/  &/')
-
-		THE_REST=$(echo $THE_REST | perl -pe "s/$DYNAMIC_USAGE_ELEMENT: -/$DYNAMIC_USAGE_ELEMENT:\n$DYNAMIC_USAGE_ELEMENT_TEXT\n\n/")
-	done
-
-	# allow for dynamic 'description: -' but delete the 'description:' header line
-	THE_REST=$(echo $THE_REST | sed '/^[		]*description:$/d')
-
-	echo "$__DARK_BLUE$USAGE_LINE$__COLOR_RESET\n\n$THE_REST" \
-		| sed "s/^\t\+//; s/\s\+$//; s/^\\s*$//;" \
-		| sed '/./,$!d; :a; /^\n*$/{$d;N;ba;};' \
-		| perl -p0e 's/\n{2,}/\n\n/g' \
-		| perl -p0e 's/:\n{2,}/:\n/g' \
-		>&2
+SUCCESS() {  # command completed successfully
+	[[ $SCWRYPTS_LOG_LEVEL -ge 1 ]] \
+		&& PREFIX="SUCCESS  ✔" COLOR=$__GREEN          PRINT "$@"
 }
 
-INPUT() {
+REMINDER() {  # include sysadmin reminder or other important notice to users
+	[[ $SCWRYPTS_LOG_LEVEL -ge 1 ]] \
+		&& PREFIX="REMINDER " COLOR=$__BRIGHT_MAGENTA PRINT "$@"
+}
+
+STATUS() {  # general status updates (prefer this to generic 'echo')
+	[[ $SCWRYPTS_LOG_LEVEL -ge 2 ]] \
+		&& PREFIX="STATUS    " COLOR=$__BLUE           PRINT "$@"
+}
+
+WARNING() {  # warning-level messages; not errors
+	[[ $SCWRYPTS_LOG_LEVEL -ge 3 ]] \
+		&& PREFIX="WARNING  " COLOR=$__YELLOW         PRINT "$@"
+}
+
+DEBUG() {  # helpful during development or (sparingly) to help others' development
+	[[ $SCWRYPTS_LOG_LEVEL -ge 4 ]] \
+		&& PREFIX="DEBUG    ℹ" COLOR=$__WHITE          PRINT "$@"
+}
+
+PROMPT() {  # you probably want to use yN or INPUT from below
+	[[ $SCWRYPTS_LOG_LEVEL -ge 1 ]] \
+		&& PREFIX="PROMPT   " COLOR=$__CYAN PRINT "$@" \
+		&& PREFIX="USER     ⌨" COLOR=$__BRIGHT_CYAN PRINT '' --no-line-end \
+		;
+}
+
+FAIL()  { SCWRYPTS_LOG_LEVEL=1 ERROR "${@:2}"; exit $1; }
+ABORT() { FAIL 69 'user abort'; }
+
+#####################################################################
+### check for reported errors and format USAGE contents #############
+#####################################################################
+
+CHECK_ERRORS() {
+	local FAIL_OUT=true
+	local DISPLAY_USAGE=true
+
+	[ ! $ERRORS ] && ERRORS=0
+
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in
+			--fail    ) FAIL_OUT=true  ;;
+			--no-fail ) FAIL_OUT=false ;;
+
+			--usage    ) DISPLAY_USAGE=true  ;;
+			--no-usage ) DISPLAY_USAGE=false ;;
+		esac
+		shift 1
+	done
+
+	[[ $ERRORS -eq 0 ]] && return 0
+
+	[[ $DISPLAY_USAGE =~ true ]] && USAGE
+
+	[[ $FAIL_OUT =~ true ]] && exit $ERRORS || return $ERRORS
+}
+
+source "${0:a:h}/io.usage.zsh"
+
+#####################################################################
+### facilitate user prompt and input ################################
+#####################################################################
+
+# yes/no prompts   && = yes (exit code 0)
+#                  || = no  (exit code 1)
+Yn() { [[ ! $(READ_YN $@ '[Yn]') =~ [nN] ]]; }  # default 'yes'
+yN() { [[   $(READ_YN $@ '[yN]') =~ [yY] ]]; }  # default 'no'
+
+INPUT() {  # read a single line of user input
 	PROMPT "${@:2}"
 	READ $1
 	local VALUE=$(eval echo '$'$1)
 	[ $VALUE ]
 }
 
-Yn() {
-	PROMPT "$@ [Yn]"
-	[ $CI ] && { echo y; return 0; }
-	[ $__SCWRYPTS_YES ] && [[ $__SCWRYPTS_YES -eq 1 ]] && { echo y; return 0; }
+source "${0:a:h}/io.fzf.zsh"  # allow user to select from a list of inputs
 
-	local Yn; READ -k Yn; echo >&2
-	[[ $Yn =~ [nN] ]] && return 1 || return 0
-}
-
-yN() {
-	PROMPT "$@ [yN]"
-	[ $CI ] && { echo y; return 0; }
-	[ $__SCWRYPTS_YES ] && [[ $__SCWRYPTS_YES -eq 1 ]] && { echo y; return 0; }
-
-	local yN; READ -k yN; echo >&2
-	[[ $yN =~ [yY] ]] && return 0 || return 1
-}
-
-CAPTURE() {
-	[ ! $USAGE ] && USAGE="
-	usage: stdout-varname stderr-varname [...cmd and args...]
-
-	captures stdout and stderr on separate variables for a command
-	"
-	{
-		IFS=$'\n' read -r -d '' $2;
-		IFS=$'\n' read -r -d '' $1;
-	} < <((printf '\0%s\0' "$(${@:3})" 1>&2) 2>&1)
-}
-
-#####################################################################
-
-GETSUDO() {
-	echo "\\033[1;36mPROMPT    : checking sudo password...\\033[0m" >&2
-	sudo echo hi >/dev/null 2>&1 </dev/tty \
-		&& SUCCESS '...authenticated!' \
-		|| { ERROR 'failed :c'; return 1; }
-}
-
-LESS() { less -R $@ </dev/tty >/dev/tty; }
-
-FZF()      {
+EDIT() {  # edit a file in user's preferred editor
 	[ $CI ] && {
-		ERROR 'currently in CI, but FZF requires user input'
-		exit 1
-	}
-
-	local FZF_ARGS=()
-
-	FZF_ARGS+=(-i)
-	FZF_ARGS+=(--ansi)
-	FZF_ARGS+=(--bind=ctrl-c:cancel)
-	FZF_ARGS+=(--height=50%)
-	FZF_ARGS+=(--layout=reverse)
-
-	local SELECTION=$(fzf ${FZF_ARGS[@]} --layout=reverse --prompt "$1 : " ${@:2})
-	PROMPT "$1"
-	echo $SELECTION >&2
-	echo $SELECTION
-}
-FZF_HEAD() { FZF $@ --print-query | sed '/^$/d' | head -n1; } # prefer user input over selected
-FZF_TAIL() { FZF $@ --print-query | sed '/^$/d' | tail -n1; } # prefer selected over user input
-
-READ()  {
-	[ $CI ] && {
-		INFO 'currently in CI, skipping READ'
-		return 0
-	}
-	read $@ </dev/tty
-}
-
-EDIT() {
-	[ $CI ] && {
-		INFO 'currently in CI, skipping EDIT'
+		WARNING 'currently in CI, skipping EDIT'
 		return 0
 	}
 
@@ -221,6 +107,12 @@ EDIT() {
 	SUCCESS "finished editing '$1'!"
 }
 
+#####################################################################
+### basic commands with tricky states or default requirements #######
+#####################################################################
+
+LESS() { less -R $@ </dev/tty >/dev/tty; }
+
 YQ() {
 	yq --version | grep -q mikefarah || {
 		yq $@
@@ -229,3 +121,110 @@ YQ() {
 
 	yq eval '... comments=""' | yq $@
 }
+
+#####################################################################
+### other i/o utilities #############################################
+#####################################################################
+
+CAPTURE() {
+	[ ! $USAGE ] && USAGE="
+		usage: stdout-varname stderr-varname [...cmd and args...]
+
+		captures stdout and stderr on separate variables for a command
+	"
+	{
+		IFS=$'\n' read -r -d '' $2;
+		IFS=$'\n' read -r -d '' $1;
+	} < <((printf '\0%s\0' "$(${@:3})" 1>&2) 2>&1)
+}
+
+
+GETSUDO() {
+	echo "\\033[1;36mPROMPT    : checking sudo password...\\033[0m" >&2
+	sudo echo hi >/dev/null 2>&1 </dev/tty \
+		&& SUCCESS '...authenticated!' \
+		|| { ERROR 'failed :c'; return 1; }
+}
+
+READ()  {
+	[ $CI ] && [ -t 0 ] \
+		&& FAIL 42 'currently in CI, but attempting interactive read; aborting'
+
+	local FORCE_USER_INPUT=false
+	local ARGS=()
+
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in
+			--force-user-input ) FORCE_USER_INPUT=true ;;
+			-k )
+				ARGS+=($1)
+				;;
+			* ) ARGS+=($1) ;;
+		esac
+		shift 1
+	done
+
+	while read -k -t 0; do :; done;  # flush user stdin
+
+	case $FORCE_USER_INPUT in
+		true  )
+			read ${PREARGS[@]} ${ARGS[@]} $@ </dev/tty
+			;;
+		false )
+			[ -t 0 ] || ARGS=(-u 0 ${ARGS[@]})
+			read ${ARGS[@]} $@
+			;;
+	esac
+}
+
+READ_YN() {  # yes/no read is suprisingly tricky
+	local FORCE_USER_INPUT=false
+	local USERPROMPT=()
+	local READ_ARGS=()
+
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in
+			--force-user-input )
+				# overrides 'scwrypts -y' and stdin pipe but not CI
+				FORCE_USER_INPUT=true
+				READ_ARGS+=($1)
+				;;
+			* ) USERPROMPT+=($1) ;;
+		esac
+		shift 1
+	done
+
+	##########################################
+
+	local SKIP_USER_INPUT=false
+
+	[ $CI ] \
+		&& SKIP_USER_INPUT=true
+
+	[ $__SCWRYPTS_YES ] && [[ $__SCWRYPTS_YES -eq 1 ]] && [[ $FORCE_USER_INPUT =~ false ]] \
+		&& SKIP_USER_INPUT=true
+
+	##########################################
+
+	local yn
+	PROMPT "${USERPROMPT[@]}"
+
+	case $SKIP_USER_INPUT in
+		true ) yn=y ;;
+		false )
+			[[ $FORCE_USER_INPUT =~ true ]] && [[ $SCWRYPTS_LOG_LEVEL -lt 1 ]] \
+				&& echo -n "${USERPROMPT[@]} : " >&2
+
+			READ ${READ_ARGS[@]} -s -k yn
+
+			[[ $FORCE_USER_INPUT =~ true ]] && [[ $SCWRYPTS_LOG_LEVEL -lt 1 ]] \
+				&& echo $yn >&2
+			;;
+	esac
+
+	[[ $SCWRYPTS_LOG_LEVEL -ge 1 ]] && echo $yn >&2
+
+	echo $yn
+}

zsh/media/youtube/download

@@ -5,7 +5,7 @@ use media/youtube
 MAIN() {
 	local URLS=($@)
 
-	[[ ${#URLS[@]} -eq 0 ]] && URLS=($(echo '' | FZF_HEAD 'enter URL'))
+	[[ ${#URLS[@]} -eq 0 ]] && URLS=($(echo '' | FZF_USER_INPUT 'enter URL'))
 	[[ ${#URLS[@]} -eq 0 ]] && ABORT
 
 	local FILENAME=$(YT__GET_FILENAME $URLS)

zsh/media/youtube/get-audio-clip

@@ -5,7 +5,7 @@ use media/youtube
 MAIN() {
 	local URLS=($@)
 
-	[[ ${#URLS[@]} -eq 0 ]] && URLS=($(echo '' | FZF_HEAD 'enter URL'))
+	[[ ${#URLS[@]} -eq 0 ]] && URLS=($(echo '' | FZF_USER_INPUT 'enter URL'))
 	[[ ${#URLS[@]} -eq 0 ]] && ABORT
 
 	local FILENAME=$(YT__GET_FILENAME $URLS)
@@ -21,9 +21,9 @@ MAIN() {
 
 	LENGTH=$(GET_VIDEO_LENGTH "$INPUT_FILE")
 	[ ! $LENGTH ] && { ERROR "unable to determine video length for '$INPUT_FILE'"; return 2; }
-	START_TIME=$(echo 0 | FZF_HEAD "enter start time (0 ≤ t < $LENGTH)")
+	START_TIME=$(echo 0 | FZF_USER_INPUT "enter start time (0 ≤ t < $LENGTH)")
 	[ ! $START_TIME ] && ABORT
-	END_TIME=$(echo $LENGTH | FZF_HEAD "enter end time ($START_TIME > t ≥ $LENGTH)")
+	END_TIME=$(echo $LENGTH | FZF_USER_INPUT "enter end time ($START_TIME > t ≥ $LENGTH)")
 	[ ! $END_TIME ] && ABORT
 
 	STATUS
@@ -32,7 +32,7 @@ MAIN() {
 	STATUS "end time   : $END_TIME"
 	STATUS
 	OUTPUT_FILE=$(echo '' \
-		| FZF_HEAD 'what should I call this clip? (.mp3)' \
+		| FZF_USER_INPUT 'what should I call this clip? (.mp3)' \
 		| sed 's/\.mp3$//' \
 	)
 	[ ! $OUTPUT_FILE ] && ABORT

zsh/office/memo/open

@@ -3,7 +3,7 @@ use office/memo
 #####################################################################
 
 MAIN() {
-	local MEMO_NAME=$(MEMO__LIST_ALL | FZF_TAIL 'select/create a memo')
+	local MEMO_NAME=$(MEMO__LIST_ALL | FZF_USER_INPUT 'select/create a memo')
 	[ ! "$MEMO_NAME" ] && ABORT
 
 	MEMO_FILE="$MEMO__DIR/$MEMO_NAME.$MEMO__FILETYPE"

zsh/sanity-check

@@ -0,0 +1,52 @@
+#!/bin/zsh
+#####################################################################
+
+USAGE__options='
+	-e, --exit-code         desired exit code of the function (default "0")
+	-f, --output-function   one of the zsh/utils output functions (default "SUCCESS")
+	-m, --message           a message to display (default "Hello, World!")
+'
+
+USAGE__description='
+	a simple hello-world-style script which allows specific scwrypts
+	conditions to be quickly emulated
+'
+
+#####################################################################
+
+MAIN() {
+	local OUTPUT_FUNCTION=SUCCESS
+	local EXIT_CODE=0
+	local MESSAGE='Hello, world!'
+
+	ARGUMENT_REQUIRED() { ERROR "'$1' requires an argument"; }
+
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in
+			-e | --exit-code )
+				EXIT_CODE="$2"
+				[ $2 ] && shift 1 || ARGUMENT_REQUIRED
+				;;
+			-f | --output-function )
+				OUTPUT_FUNCTION="$2"
+				[ $2 ] && shift 1 || ARGUMENT_REQUIRED
+				;;
+			-m | --message )
+				MESSAGE="$2"
+				[ $2 ] && shift 1 || ARGUMENT_REQUIRED
+				;;
+			* ) ERROR "unknown argument '$1'" ;;
+		esac
+		shift 1
+	done
+
+	CHECK_ERRORS
+
+	##########################################
+
+	[[ $OUTPUT_FUNCTION =~ ^FAIL$ ]] && FAIL $EXIT_CODE "$MESSAGE"
+
+	$OUTPUT_FUNCTION "$MESSAGE"
+	return $EXIT_CODE
+}

zsh/scwrypts/environment/copy

@@ -10,7 +10,7 @@ MAIN() {
 	STATUS "selected '$TEMPLATE_ENV_NAME'"
 	
 	PROMPT 'enter new environment name'
-	ENV_NAME=$(echo '' | FZF_HEAD 'new environment')
+	ENV_NAME=$(echo '' | FZF_USER_INPUT 'new environment')
 	[ ! $ENV_NAME ] && ABORT
 	SCWRYPTS__GET_ENV_NAMES | grep -q $ENV_NAME && FAIL 1 "'$ENV_NAME' already exists"
 	

zsh/system/config/symlinks

@@ -18,7 +18,7 @@ SETUP_SYMLINK() {
 	local TARGET_CONFIG="$HOME/.config/$2"
 
 	[ ! -f "$SOURCE_CONFIG" ] && [ ! -d "$SOURCE_CONFIG" ] && [ -f "$TARGET_CONFIG" ] && {
-		INFO 'SOURCE_CONFIG is not tracked; copying from TARGET_CONFIG'
+		DEBUG 'SOURCE_CONFIG is not tracked; copying from TARGET_CONFIG'
 		mkdir -p "$(dirname "$SOURCE_CONFIG")"
 		cp "$TARGET_CONFIG" "$SOURCE_CONFIG"
 	}

zsh/system/packages/install

@@ -66,7 +66,7 @@ MAIN() {
 
 	[ ! $NAME ] && {
 		NAME=$(echo $TARGET | sed 's/.*\///; s/\.git$//')
-		INFO "using default name '$NAME'"
+		DEBUG "using default name '$NAME'"
 	}
 
 	[ -d "$PACKAGE_INSTALL_DIR/$NAME" ] && [[ $SKIP_PULL -eq 0 ]] && {