v2.1.0

=====================================================================

--- New Scripts --------------------------

zsh )
  database backup/restore
   - db/postgres/pg_dump
   - db/postgres/pg_restore
   - aws/rds/create-backup
   - aws/rds/load-backup

  redis-cached curl commands
   - redis/curl

  youtube download
   - youtube/download
   - youtube/get-audio-clip

--- Changes ------------------------------

- 'scwrypts' executable now reloads upon execution to prevent staleness
- added various options to improve api/cli; see 'scwrypts --help' for more

--- Bug Fixes ----------------------------

- fixed an issue with .config settings' visibility to non-zsh scripts
- fixed an issue with command arguments globbing too early

.gitattributes

@@ -0,0 +1,2 @@
+*.zsh diff
+.config diff

README.md

@@ -28,12 +28,9 @@ Check out [Meta Scwrypts](./zsh/scwrypts) to quickly set up environments and adj
 ### No Install / API Usage
 Alternatively, the `scwrypts` API can be used directly:
 ```zsh
-./scwrypts (environment-name) (...script-patterns)
+./scwrypts [--env environment-name] (...script-name-patterns...) [-- ...passthrough arguments... ]
 ```
 
-If not already set with `$SCWRYPTS_ENV`, Scwrypts will try to load `$1` as an environment.
-If no environment with the name `$1` is found, `$1` is assumed to be a script pattern.
-
 Given one or more script patterns, Scwrypts will filter the commands by pattern conjunction.
 If only one command is found which matches the pattern(s), it will immediately begin execution.
 If multiple commands match, the user will be prompted to select from the filtered list.
@@ -44,6 +41,16 @@ Given no script patterns, Scwrypts becomes an interactive CLI, prompting the use
 After determining which script to run, if no environment has been specified, Scwrypts prompts the user to choose one.
 
 
+### Using in CI/CD or Automated Workflows
+Set environment variable `CI=true` (and use the no install method) to run in an automated pipeline.
+There are a few notable changes to this runtime:
+- **The Scwrypts sandbox environment will not load.** All variables will be read from context.
+	- The underscore-prefixed `_AWS_(PROFILE|REGION|ACCOUNT)` variables will be read from the standard `AWS_` variables
+- User yes/no prompts will **always be YES**
+- Other user input will default to an empty string
+- Logs will not be captured
+
+
 ## Contributing
 
 Before contributing an issue, idea, or pull request, check out the [super-brief contributing guide](./docs/CONTRIBUTING.md)

py/.gitignore

@@ -1,4 +1,3 @@
 __pycache__/
 *.py[cod]
 *.so
-.env/

py/redis/interactive.py

@@ -1,16 +1,15 @@
 #!/usr/bin/env python
-from os import getenv
 
 from py.redis.client import Client
-from py.scwrypts import interactive
+from py.scwrypts import interactive, getenv
 
 
 @interactive
 def main():
     r = Client
 
-    print('''
+    print(f'''
-    r = StrictRedis("{getenv("REDIS_HOST")}")
+>>> r = StrictRedis({getenv("REDIS_HOST")}:{getenv("REDIS_PORT")})
     ''')
 
     return locals()

py/scwrypts/__init__.py

@@ -1,2 +1,3 @@
 from py.scwrypts.getenv import getenv
 from py.scwrypts.interactive import interactive
+from py.scwrypts.run import run

py/scwrypts/getenv.py

@@ -1,23 +1,16 @@
 from os import getenv as os_getenv
-from pathlib import Path
-from subprocess import run
 
 from py.scwrypts.exceptions import MissingVariableError
+from py.scwrypts.run import run
 
 
 def getenv(name, required=True):
     value = os_getenv(name, None)
 
     if value == None:
-        ZSH_COMMAND = Path(__file__).parents[2] / 'zsh/scwrypts/environment/stage-variables'
+        run('zsh/scwrypts/environment/stage-variables', name)
 
-        run(
+    if required and not value:
-            f'{ZSH_COMMAND} {name}',
+        raise MissingVariableError(name)
-            shell=True,
-            executable='/bin/zsh',
-            )
-
-        if required:
-            raise MissingVariableError(name)
 
     return value

py/scwrypts/interactive.py

@@ -3,7 +3,9 @@ from bpython import embed
 
 def interactive(function):
     def main(*args, **kwargs):
+        print('preparing interactive environment...')
         local_vars = function(*args, **kwargs)
+        print('environment ready; user, GO! :)')
         embed(local_vars)
 
     return main

py/scwrypts/run.py

@@ -0,0 +1,17 @@
+from os import getenv
+from pathlib import Path
+from subprocess import run as subprocess_run
+
+
+def run(scwrypt_name, *args):
+    DEPTH = int(getenv('SUBSCWRYPT', '0'))
+    DEPTH += 1
+
+    print(f'\n {"--"*DEPTH} ({DEPTH}) BEGIN SUBSCWRYPT : {Path(scwrypt_name).name}')
+    subprocess_run(
+        f'SUBSCWRYPT={DEPTH} {Path(__file__).parents[2] / "scwrypts"} {scwrypt_name} -- {" ".join([str(x) for x in args])}',
+        shell=True,
+        executable='/bin/zsh',
+        )
+
+    print(f' {"--"*DEPTH} ({DEPTH}) END SUBSCWRYPT   : {Path(scwrypt_name).name}\n')

run

@@ -0,0 +1,271 @@
+#!/bin/zsh
+SCWRYPTS_ROOT="${0:a:h}"
+source "$SCWRYPTS_ROOT/zsh/common.zsh" || exit 42
+#####################################################################
+
+__RUN() {
+	local USAGE='
+Usage : scwrypts [OPTIONS ...] SCRIPT -- [SCRIPT OPTIONS ...]
+
+OPTIONS
+  -e, --env <env-name>   set environment; overwrites SCWRYPTS_ENV
+  -n, --no-log           skip logging (useful when calling scwrypts as an api)
+  -l, --list             print out command list and exit
+
+  -h, --help             display this message and exit
+'
+
+	cd "$SCWRYPTS_ROOT"
+
+	local ENV_NAME="$SCWRYPTS_ENV"
+	local SEARCH_PATTERNS=()
+
+	local ARGS_ERROR=0
+
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in
+			-h | --help )
+				echo $USAGE
+				return 0
+				;;
+			-n | --no-log )
+				[ ! $SUBSCWRYPT ] && SUBSCWRYPT=0
+				shift 1
+				;;
+			-e | --env )
+				[ $ENV_NAME ] && __WARNING 'overwriting session environment'
+				ENV_NAME="$2"
+				__STATUS "using CLI environment '$ENV_NAME'"
+				shift 2
+				;;
+			-l | --list )
+				__OUTPUT_COMMAND_LIST
+				return 0
+				;;
+			-- )
+				shift 1
+				break # pass arguments after '--' to the scwrypt
+				;;
+			-* )
+				__ERROR "unrecognized argument '$1'"
+				((ARGS_ERROR+=1))
+				shift 1
+				;;
+			* )
+				SEARCH_PATTERNS+=$1
+				shift 1
+				;;
+		esac
+	done
+
+	[[ $ARGS_ERROR -gt 0 ]] && {
+		echo $USAGE
+		return 1
+	}
+
+	##########################################
+
+	local SCRIPT=$(__SELECT_SCRIPT $SEARCH_PATTERNS)
+	[ ! $SCRIPT ] && exit 2
+
+	local ENV_REQUIRED=$(__CHECK_ENV_REQUIRED && echo 1 || echo 0)
+
+	[[ $ENV_REQUIRED -eq 1 ]] && {
+		[ ! $ENV_NAME ] && ENV_NAME=$(__SELECT_ENV)
+		local ENV_FILE=$(__GET_ENV_FILE $ENV_NAME)
+
+		[ -f "$ENV_FILE" ] && source "$ENV_FILE" \
+			|| __FAIL 5 "missing or invalid environment '$ENV_NAME'"
+
+		export ENV_NAME
+	}
+
+	[ ! $SUBSCWRYPT ] \
+		&& [[ $ENV_NAME =~ prod ]] \
+		&& { __VALIDATE_UPSTREAM_TIMELINE || __ABORT; }
+
+	local RUN_STRING=$(__GET_RUN_STRING $SCRIPT $ENV_NAME)
+	[ ! $RUN_STRING ] && exit 3
+
+	##########################################
+
+	local LOGFILE=$(__GET_LOGFILE $SCRIPT)
+
+	local HEADER=$(
+		[ $SUBSCWRYPT ] && return 0
+		echo '====================================================================='
+		echo "script : $SCRIPT"
+		echo "run at : $(date)"
+		echo "config : $ENV_NAME"
+		[ ! $LOGFILE ] && echo '\033[1;33m------------------------------------------\033[0m'
+	)
+
+	[ ! $LOGFILE ] && {
+		[ $HEADER ] && echo $HEADER
+		[[ $SUBSCWRYPT -eq 0 ]] && {
+			eval $RUN_STRING $@
+			exit $?
+		} || {
+			eval $RUN_STRING $@ </dev/tty >/dev/tty 2>&1
+			exit $?
+		}
+	}
+
+	{
+		[ $HEADER ] && echo $HEADER
+		echo '\033[1;33m--- BEGIN OUTPUT -------------------------\033[0m'
+		eval $RUN_STRING $@
+		EXIT_CODE=$?
+		echo '\033[1;33m--- END OUTPUT ---------------------------\033[0m'
+
+		[[ $EXIT_CODE -eq 0 ]] && EXIT_COLOR='32m' || EXIT_COLOR='31m'
+
+		echo "terminated with\\033[1;$EXIT_COLOR code $EXIT_CODE\\033[0m"
+	} 2>&1 | tee --append "$LOGFILE"
+
+	exit $(\
+		sed -n 's/^terminated with.*code \([0-9]*\).*$/\1/p' $LOGFILE \
+			| tail -n1
+	)
+}
+
+#####################################################################
+
+__OUTPUT_COMMAND_LIST() {
+	local LAST_TYPE LAST_SUBSET
+	for SCRIPT in $(__GET_AVAILABLE_SCRIPTS)
+	do
+		TYPE=$(echo $SCRIPT | sed 's/\/.*//')
+		SUBSET=$(echo $SCRIPT | sed 's/.*\/\(.*\)\/[^\/]*$/\1/')
+		[[ ! $LAST_TYPE =~ $TYPE ]] && {
+			echo >&2
+			echo "\\033[1;32m$TYPE scwrypts\\033[0m" >&2
+			LAST_SUBSET=''
+		}
+		[ $LAST_SUBSET ] && [[ ! $LAST_SUBSET =~ $SUBSET ]] && {
+			echo >&2
+		}
+		printf '  - ' >&2
+		echo $SCRIPT
+		LAST_TYPE=$TYPE
+		LAST_SUBSET=$SUBSET
+	done
+}
+
+#####################################################################
+
+__SELECT_SCRIPT() {
+	local SCRIPT
+	local SCRIPTS=$(__GET_AVAILABLE_SCRIPTS)
+	local SEARCH=($@)
+
+	[[ ${#SEARCH[@]} -eq 0 ]] && {
+		SCRIPT=$(echo $SCRIPTS | __FZF 'select a script')
+	}
+
+	[[ ${#SEARCH[@]} -eq 1 ]] && [ -f ./$SEARCH ] && {
+		SCRIPT=$SEARCH
+	}
+
+	[ ! $SCRIPT ] && [[ ${#SEARCH[@]} -gt 0 ]] && {
+		SCRIPT=$SCRIPTS
+		for PATTERN in $SEARCH
+		do
+			SCRIPT=$(echo $SCRIPT | grep $PATTERN)
+		done
+
+		[ ! $SCRIPT ] && __FAIL 2 "no script found by name '$@'"
+
+		[[ $(echo $SCRIPT | wc -l) -gt 1 ]] && {
+			__STATUS "more than one script matched '$@'"
+			SCRIPT=$(echo $SCRIPT | __FZF 'select a script')
+		}
+	}
+
+	echo $SCRIPT
+}
+
+__GET_RUN_STRING() {
+	local SCRIPT="$1"
+	local ENV_NAME="$2"
+	local TYPE=$(echo $SCRIPT | sed 's/\/.*$//')
+
+	local RUN_STRING
+
+	local _VIRTUALENV="$SCWRYPTS_VIRTUALENV_PATH/$TYPE/bin/activate"
+	[ -f $_VIRTUALENV ] && source $_VIRTUALENV
+
+	case $TYPE in
+		py ) __CHECK_DEPENDENCY python || return 1
+			RUN_STRING="python -m $(echo $SCRIPT | sed 's/\//./g; s/\.py$//; s/\.\.//')"
+
+			CURRENT_PYTHON_VERSION=$(python --version | sed 's/^[^0-9]*\(3\.[^.]*\).*$/\1/')
+
+			echo $__PREFERRED_PYTHON_VERSIONS | grep -q $CURRENT_PYTHON_VERSION || {
+				__WARNING "only tested on the following python versions: $(printf ', %s.x' ${__PREFERRED_PYTHON_VERSIONS[@]} | sed 's/^, //')"
+				__WARNING 'compatibility may vary'
+			}
+			;;
+
+		zsh ) __CHECK_DEPENDENCY zsh || return 1
+			RUN_STRING="noglob ./$SCRIPT"
+			;;
+
+		zx ) __CHECK_DEPENDENCY zx || return 1
+			RUN_STRING="FORCE_COLOR=3 ./$SCRIPT.mjs"
+			;;
+
+		* ) __ERROR "unsupported script type '$SCRIPT_TYPE'"
+			return 2
+			;;
+	esac
+
+	RUN_STRING="SCWRYPTS_ENV='$ENV_NAME' $RUN_STRING"
+	[ -f $_VIRTUALENV ] && RUN_STRING="source '$_VIRTUALENV'; $RUN_STRING"
+
+	echo $RUN_STRING
+}
+
+__CHECK_ENV_REQUIRED() {
+	[ $CI ] && return 1
+
+	echo $SCRIPT | grep -q 'zsh/scwrypts/logs' && 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() {
+	local SCRIPT="$1"
+
+	[ $SUBSCWRYPT ] \
+		|| [[ $SCRIPT =~ scwrypts/logs ]] \
+		|| [[ $SCRIPT =~ interactive ]] \
+		&& return 0
+
+	echo "$SCWRYPTS_LOG_PATH/$(echo $SCRIPT | sed 's/^\.\///; s/\//\%/g').log"
+}
+
+#####################################################################
+__RUN $@

scwrypts

@@ -1,151 +1,2 @@
 #!/bin/zsh
-SCWRYPTS_ROOT="${0:a:h}"
+source "${0:a:h}/run"
-
-source "$SCWRYPTS_ROOT/zsh/common.zsh"
-
-__CHECK_DEPENDENCIES \
-	fzf \
-	;
-
-__CHECK_IMPORTS
-
-#####################################################################
-
-__RUN() {
-	cd "$SCWRYPTS_ROOT"
-
-	##########################################
-	### parse arguments ######################
-	##########################################
-
-	local ENV_NAME
-	[ $SCWRYPTS_ENV ] && ENV_NAME="$SCWRYPTS_ENV" || {
-		[ $1 ] && [ -f $(__GET_ENV_FILE $1) ] && {
-			ENV_NAME="$1"
-			shift 1
-		}
-	}
-
-	local SCRIPT
-	local SCRIPTS=$(__GET_AVAILABLE_SCRIPTS)
-
-	[ $1 ] && {
-		for PATTERN in $*
-		do
-			shift 1
-			[[ $PATTERN =~ ^--$ ]] && break
-			SCRIPT=$(echo $SCRIPTS | grep $PATTERN)
-		done
-
-		[ ! $SCRIPT ] && __FAIL 2 "no script found by name '$@'"
-
-		[[ $(echo $SCRIPT | wc -l) -gt 1 ]] && {
-			__STATUS "more than one script matched '$@'"
-			SCRIPT=$(echo $SCRIPT | __FZF 'select a script')
-		}
-		true
-	} || SCRIPT=$(echo $SCRIPTS | __FZF 'select a script')
-
-	[ ! $SCRIPT ] && exit 2
-
-	##########################################
-	### check type and min dependencies ######
-	##########################################
-
-	local ENV_REQUIRED=1
-	local RUN_STRING="./$SCRIPT"
-	local TYPE=$(echo $SCRIPT | sed 's/\/.*$//')
-
-	local VIRTUALENV="$SCWRYPTS_ROOT/$TYPE/.env/bin/activate"
-	[ -f $VIRTUALENV ] && source $VIRTUALENV
-
-	case $TYPE in
-		py ) __CHECK_DEPENDENCY python || exit 3
-
-			python --version | grep -q '3.[91]' || {
-				__WARNING 'only tested on python>=3.9'
-				__WARNING 'compatibility may vary'
-			}
-
-			RUN_STRING="python -m $(echo $SCRIPT | sed 's/\//./g; s/\.py$//; s/\.\.//')"
-			;;
-
-		zsh ) __CHECK_DEPENDENCY zsh || exit 3
-			echo $SCRIPT | grep -q 'scwrypts' && ENV_REQUIRED=0
-
-			RUN_STRING="./$SCRIPT"
-			;;
-
-		zx ) __CHECK_DEPENDENCY zx || exit 3
-
-			RUN_STRING="FORCE_COLOR=3 ./$SCRIPT.mjs"
-			;;
-
-		* ) __FAIL 4 "unsupported script type '$SCRIPT_TYPE'" ;;
-	esac
-
-	##########################################
-	### load scwrypts env and virtualenv #####
-	##########################################
-
-	[[ $ENV_REQUIRED -eq 1 ]] && {
-		[ ! $ENV_NAME ] && ENV_NAME=$(__SELECT_ENV)
-		[ ! $ENV_NAME ] && __ABORT
-
-		local ENV_FILE=$(__GET_ENV_FILE $ENV_NAME)
-
-		[ -f "$ENV_FILE" ] \
-			&& source "$ENV_FILE" \
-			&& export ENV_NAME \
-			|| __FAIL 5 "missing or invalid environment '$ENV_NAME'"
-
-		[[ $ENV_NAME =~ prod ]] && {
-			__STATUS "on '$ENV_NAME'; checking diff against origin/main"
-
-			git fetch --quiet origin main \
-				&& git diff --exit-code origin/main -- . >&2 \
-				&& __SUCCESS 'up-to-date with main!' \
-				|| {
-					__WARNING
-					__WARNING 'your branch differs from origin/main'
-					__WARNING 'in '$ENV_NAME', being out-of-sync with main may have BAD CONSEQUENCES'
-					__WARNING
-					__yN 'continue?' || __ABORT
-			}
-		}
-	}
-
-	##########################################
-	### run the scwrypt ######################
-	##########################################
-
-	local HEADER=$(
-		echo '====================================================================='
-		echo "script : $SCRIPT"
-		echo "run at : $(date)"
-		echo "config : $ENV_NAME"
-		echo '------------------------------------------'
-	)
-
-	echo $SCRIPT | grep -q 'interactive' && {
-		echo $HEADER
-		eval $RUN_STRING $@ </dev/tty >/dev/tty 2>&1; exit $?
-	}
-
-	local LOGFILE="$SCWRYPTS_LOG_PATH/$(echo $SCRIPT | sed 's/^\.\///; s/\//\%/g').log"
-	[[ $SCRIPT =~ scwrypts/logs ]] && LOGFILE=/dev/null
-	{
-		echo $HEADER
-		echo '--- BEGIN OUTPUT--------------------------'
-		eval $RUN_STRING $@; local EXIT_CODE="$?"
-		echo '--- END OUTPUT ---------------------------'
-
-		local C
-		[[ $EXIT_CODE -eq 0 ]] && C='32m' || C='31m';
-
-		echo "terminated with\\033[1;$C code $EXIT_CODE\\033[0m"
-	} 2>&1 | tee --append "$LOGFILE"
-}
-
-#####################################################################
-__RUN $@

scwrypts.plugin.zsh

@@ -1,9 +1,6 @@
-source ${0:a:h}/zsh/common.zsh
+DONT_EXIT=1 source ${0:a:h}/zsh/common.zsh
 #####################################################################
-[ ! $SCWRYPTS_SHORTCUT ] && return 0
-
 __SCWRYPTS() {
-
 	local SCRIPT=$(__GET_AVAILABLE_SCRIPTS | __FZF 'select a script')
 	zle clear-command-line
 	[ ! $SCRIPT ] && { zle accept-line; return 0; }
@@ -14,12 +11,11 @@ __SCWRYPTS() {
 	RBUFFER+=" $SCRIPT"
 	zle accept-line
 }
+
 zle -N scwrypts __SCWRYPTS
 bindkey $SCWRYPTS_SHORTCUT scwrypts
 
 #####################################################################
-[ ! $SCWRYPTS_ENV_SHORTCUT ] && return 0
-
 __SCWRYPTS_ENV() {
 	local RESET='reset'
 	local SELECTED=$(\
@@ -31,9 +27,10 @@ __SCWRYPTS_ENV() {
 	[ $SELECTED ] && {
 		[[ $SELECTED =~ ^$RESET$ ]] \
 			&& RBUFFER='unset SCWRYPTS_ENV' \
-			|| RBUFFER="export SCWRYPTS_ENV=$SELECTED'"
+			|| RBUFFER="export SCWRYPTS_ENV=$SELECTED"
 	}
 	zle accept-line
 }
+
 zle -N scwrypts-setenv __SCWRYPTS_ENV
 bindkey $SCWRYPTS_ENV_SHORTCUT scwrypts-setenv

zsh/README.md

@@ -4,6 +4,7 @@
 [![Generic Badge](https://img.shields.io/badge/junegunn-fzf-informational.svg)](https://github.com/junegunn/fzf)
 [![Generic Badge](https://img.shields.io/badge/mikefarah-yq-informational.svg)](https://github.com/mikefarah/yq)
 [![Generic Badge](https://img.shields.io/badge/stedolan-jq-informational.svg)](https://github.com/stedolan/jq)
+[![Generic Badge](https://img.shields.io/badge/dbcli-pgcli-informational.svg)](https://github.com/dbcli/pgcli)
 <br>
 
 Since they emulate direct user interaction, shell scripts are often the straightforward choice for task automation.

zsh/aws/common.zsh

@@ -1,16 +1,13 @@
+_DEPENDENCIES+=(
+	aws
+	jq
+)
+_REQUIRED_ENV+=(
+	_AWS_ACCOUNT
+	_AWS_PROFILE
+	_AWS_REGION
+)
 source ${0:a:h}/../common.zsh
-
-__CHECK_DEPENDENCIES \
-	aws \
-	jq \
-	;
-
-__CHECK_ENV_VARS \
-	_AWS_ACCOUNT \
-	_AWS_PROFILE \
-	_AWS_REGION \
-	;
-
 #####################################################################
 
 _AWS() { aws --profile $_AWS_PROFILE --region $_AWS_REGION --output json $@; }

zsh/aws/ecr/common.zsh

@@ -1,10 +1,6 @@
+_DEPENDENCIES+=(
+	docker
+)
+_REQUIRED_ENV+=()
 source ${0:a:h}/../common.zsh
-
-__CHECK_DEPENDENCIES \
-	docker \
-	;
-
-__CHECK_ENV_VARS \
-	;
-
 #####################################################################

zsh/aws/ecr/login

@@ -1,6 +1,7 @@
 #!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/common.zsh
-__CHECK_IMPORTS
 #####################################################################
 
 __STATUS "performing AWS ECR docker login"

zsh/aws/efs/common.zsh

@@ -1,10 +1,6 @@
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=(
+	AWS__EFS__LOCAL_MOUNT_POINT
+)
 source ${0:a:h}/../common.zsh
-
-__CHECK_DEPENDENCIES \
-	;
-
-__CHECK_ENV_VARS \
-	AWS__EFS__LOCAL_MOUNT_POINT \
-	;
-
 #####################################################################

zsh/aws/efs/mount

@@ -1,6 +1,7 @@
 #!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/common.zsh
-__CHECK_IMPORTS
 #####################################################################
 
 _EFS_CONNECT() {
@@ -18,6 +19,7 @@ _EFS_CONNECT() {
 	[ ! $FS_ID ] && __ABORT
 
 	local MOUNT_POINT="$AWS__EFS__LOCAL_MOUNT_POINT/$FS_ID"
+	[ -d "$MOUNT_POINT" ] && sudo rmdir "$MOUNT_POINT" >/dev/null 2>&1
 	[ -d "$MOUNT_POINT" ] && {
 		__STATUS "$FS_ID is already mounted"
 		exit 0

zsh/aws/efs/unmount

@@ -1,6 +1,7 @@
 #!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/common.zsh
-__CHECK_IMPORTS
 #####################################################################
 
 _EFS_DISCONNECT() {

zsh/aws/rds/common.zsh

@@ -0,0 +1,129 @@
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/../common.zsh
+#####################################################################
+
+GET_DATABASE_CREDENTIALS() {
+	local PRINT_PASSWORD=0
+	local ARGS_ERRORS=0
+
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in
+			--print-password ) PRINT_PASSWORD=1 ;;
+			* )
+				__WARNING "unrecognized argument $1"
+				ARGS_ERRORS+=1
+				;;
+		esac
+		shift 1
+	done
+	[[ $ARGS_ERRORS -ne 0 ]] && return 1
+
+	##########################################
+
+	local DATABASE=$(SELECT_DATABASE)
+	[ ! $DATABASE ] && __ABORT
+
+	DB_HOST="$(echo $DATABASE | jq -r '.host')"
+	[ ! $DB_HOST ] && { __ERROR 'unable to find host'; return 2; }
+
+	DB_PORT="$(echo $DATABASE | jq -r '.port')"
+	[ ! $DB_PORT ] && DB_PORT=5432
+	[[ $DB_PORT =~ ^null$ ]] && DB_PORT=5432
+
+	##########################################
+
+	local AUTH_METHOD=$(\
+		echo "iam\nsecretsmanager\nuser-input" \
+			| __FZF 'select an authentication method' \
+	)
+	[ ! $AUTH_METHOD ] && __ABORT
+
+	case $AUTH_METHOD in
+		iam            ) GET_AUTH__IAM ;;
+		secretsmanager ) GET_AUTH__SECRETSMANAGER ;;
+		user-input     ) GET_AUTH__USER_INPUT ;;
+	esac
+
+	__STATUS
+	__STATUS "host     : $DB_HOST"
+	__STATUS "type     : $DB_TYPE"
+	__STATUS "port     : $DB_PORT"
+	__STATUS "database : $DB_NAME"
+	__STATUS "username : $DB_USER"
+	[[ $PRINT_PASSWORD -eq 1 ]] && __STATUS "password : $DB_PASS"
+	__STATUS
+}
+
+GET_AUTH__IAM() {
+	DB_PASS=$(\
+		_AWS rds generate-db-auth-token \
+		--hostname $DB_HOST \
+		--port $DB_PORT \
+		--username $DB_USER \
+	)
+}
+
+GET_AUTH__SECRETSMANAGER() {
+	local CREDENTIALS=$(GET_SECRETSMANAGER_CREDENTIALS)
+	echo $CREDENTIALS | jq -e '.pass' >/dev/null 2>&1 \
+		&& DB_PASS="'$(echo $CREDENTIALS | jq -r '.pass' | sed "s/'/'\"'\"'/g")'"
+	
+	echo $CREDENTIALS | jq -e '.password' >/dev/null 2>&1 \
+		&& DB_PASS="'$(echo $CREDENTIALS | jq -r '.password' | sed "s/'/'\"'\"'/g")'"
+	
+	echo $CREDENTIALS | jq -e '.user' >/dev/null 2>&1 \
+		&& DB_USER=$(echo $CREDENTIALS | jq -r '.user')
+	
+	echo $CREDENTIALS | jq -e '.username' >/dev/null 2>&1 \
+		&& DB_USER=$(echo $CREDENTIALS | jq -r '.username')
+	
+	echo $CREDENTIALS | jq -e '.name' >/dev/null 2>&1 \
+		&& DB_NAME=$(echo $CREDENTIALS | jq -r '.name')
+	
+	echo $CREDENTIALS | jq -e '.dbname' >/dev/null 2>&1 \
+		&& DB_NAME=$(echo $CREDENTIALS | jq -r '.dbname')
+}
+
+GET_SECRETSMANAGER_CREDENTIALS() {
+	local ID=$(\
+		_AWS secretsmanager list-secrets \
+			| jq -r '.[] | .[] | .Name' \
+			| __FZF 'select a secret' \
+	)
+	[ ! $ID ] && return 1
+
+	_AWS secretsmanager get-secret-value --secret-id "$ID" \
+		| jq -r '.SecretString' | jq
+}
+
+SELECT_DATABASE() {
+	local DATABASES=$(GET_AVAILABLE_DATABASES)
+	[ ! $DATABASES ] && __FAIL 1 'no databases available'
+
+	local ID=$(\
+		echo $DATABASES | jq -r '.instance + " @ " + .cluster' \
+			| __FZF 'select a database (instance@cluster)' \
+	)
+	[ ! $ID ] && __ABORT
+
+	local INSTANCE=$(echo $ID | sed 's/ @ .*$//')
+	local CLUSTER=$(echo $ID  | sed 's/^.* @ //')
+
+	echo $DATABASES | jq "select (.instance == \"$INSTANCE\" and .cluster == \"$CLUSTER\")"
+}
+
+GET_AVAILABLE_DATABASES() {
+	_AWS rds describe-db-instances \
+		| jq -r '.[] | .[] | {
+			instance: .DBInstanceIdentifier,
+			cluster:  .DBClusterIdentifier,
+			type:     .Engine,
+			host:     .Endpoint.Address,
+			port:     .Endpoint.Port,
+			user:     .MasterUsername,
+			database: .DBName
+		}'
+}
+

zsh/aws/rds/create-backup

@@ -0,0 +1,22 @@
+#!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+RDS_INTERACTIVE_LOGIN() {
+	local DB_HOST DB_PORT DB_NAME DB_USER DB_PASS
+	GET_DATABASE_CREDENTIALS $@ || return 1
+
+	__RUN_SCWRYPT 'zsh/db/postgres/pg_dump' -- \
+		--host $DB_HOST \
+		--port $DB_PORT \
+		--name $DB_NAME \
+		--user $DB_USER \
+		--pass $DB_PASS \
+		;
+}
+
+
+#####################################################################
+RDS_INTERACTIVE_LOGIN $@

zsh/aws/rds/interactive-login

@@ -0,0 +1,22 @@
+#!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+RDS_INTERACTIVE_LOGIN() {
+	local DB_HOST DB_PORT DB_NAME DB_USER DB_PASS
+	GET_DATABASE_CREDENTIALS $@ || return 1
+
+	__RUN_SCWRYPT 'zsh/db/interactive/postgres' -- \
+		--host $DB_HOST \
+		--port $DB_PORT \
+		--name $DB_NAME \
+		--user $DB_USER \
+		--pass $DB_PASS \
+		;
+}
+
+
+#####################################################################
+RDS_INTERACTIVE_LOGIN $@

zsh/aws/rds/load-backup

@@ -0,0 +1,22 @@
+#!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+RDS_INTERACTIVE_LOGIN() {
+	local DB_HOST DB_PORT DB_NAME DB_USER DB_PASS
+	GET_DATABASE_CREDENTIALS $@ || return 1
+
+	__RUN_SCWRYPT 'zsh/db/postgres/pg_restore' -- \
+		--host $DB_HOST \
+		--port $DB_PORT \
+		--name $DB_NAME \
+		--user $DB_USER \
+		--pass $DB_PASS \
+		;
+}
+
+
+#####################################################################
+RDS_INTERACTIVE_LOGIN $@

zsh/aws/route53/backup

@@ -1,6 +1,7 @@
 #!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/common.zsh
-__CHECK_IMPORTS
 #####################################################################
 
 _ROUTE53_BACKUP() {

zsh/aws/route53/common.zsh

@@ -1,10 +1,6 @@
+_DEPENDENCIES+=(
+	cli53
+)
+_REQUIRED_ENV+=()
 source ${0:a:h}/../common.zsh
-
-__CHECK_DEPENDENCIES \
-	cli53 \
-	;
-
-__CHECK_ENV_VARS \
-	;
-
 #####################################################################

zsh/aws/s3/common.zsh

@@ -1,9 +1,4 @@
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/../common.zsh
-
-__CHECK_DEPENDENCIES \
-	;
-
-__CHECK_ENV_VARS \
-	;
-
 #####################################################################

zsh/aws/s3/media-sync/common.zsh

@@ -1,17 +1,13 @@
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=(
+	AWS__S3__MEDIA_TARGETS
+	AWS__S3__MEDIA_BUCKET
+)
 source ${0:a:h}/../common.zsh
-
+#####################################################################
-__CHECK_DEPENDENCIES \
-	;
-
-__CHECK_ENV_VARS \
-	AWS__S3__MEDIA_TARGETS \
-	AWS__S3__MEDIA_BUCKET \
-	;
 
 AWS__S3__MEDIA_TARGETS=($(echo $AWS__S3__MEDIA_TARGETS | sed 's/,/\n/g'))
 
-#####################################################################
-
 __SYNC_MEDIA() {
 	local ACTION="$1"
 	local REMOTE_TARGET="s3://$AWS__S3__MEDIA_BUCKET/$2"

zsh/aws/s3/media-sync/pull

@@ -1,6 +1,7 @@
 #!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/common.zsh
-__CHECK_IMPORTS
 #####################################################################
 
 __PULL_ALL_MEDIA() {

zsh/aws/s3/media-sync/push

@@ -1,6 +1,7 @@
 #!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/common.zsh
-__CHECK_IMPORTS
 #####################################################################
 
 __PUSH_ALL_MEDIA() {

zsh/common.zsh

@@ -1,40 +1,21 @@
+#####################################################################
+
 [ ! $SCWRYPTS_ROOT ] && SCWRYPTS_ROOT="$(dirname ${0:a:h})"
 
-source $SCWRYPTS_ROOT/.config
-[ -f $SCWRYPTS_CONFIG_PATH/config ] && source $SCWRYPTS_CONFIG_PATH/config
-
-[ ! -d $SCWRYPTS_CONFIG_PATH ] && mkdir -p $SCWRYPTS_CONFIG_PATH
-[ ! -d $SCWRYPTS_ENV_PATH    ] && mkdir -p $SCWRYPTS_ENV_PATH
-[ ! -d $SCWRYPTS_LOG_PATH    ] && mkdir -p $SCWRYPTS_LOG_PATH
-
 __PREFERRED_PYTHON_VERSIONS=(3.10 3.9)
 __NODE_VERSION=18.0.0
+__ENV_TEMPLATE=$SCWRYPTS_ROOT/.env.template
 
-#####################################################################
+__SCWRYPT=1
 
-__DEPENDENCY_ERROR=0
+source $SCWRYPTS_ROOT/.config
-__ENVIRONMENT_ERROR=0
+source ${0:a:h}/utils/utils.module.zsh || {
-
+	[ $DONT_EXIT ] && return 1 || exit 1
-source ${0:a:h}/utils/io.zsh
-source ${0:a:h}/utils/os.zsh
-source ${0:a:h}/utils/credits.zsh
-source ${0:a:h}/utils/dependencies.zsh
-source ${0:a:h}/utils/environment.zsh
-
-#####################################################################
-
-__CHECK_IMPORTS() {
-	[[ $__DEPENDENCY_ERROR -eq 0 ]] \
-		&& [[ $__ENVIRONMENT_ERROR -eq 0 ]] \
-		|| __FAIL 1 'import error (see output above)' \
-		;
 }
 
 #####################################################################
 
-__ENV_TEMPLATE=$SCWRYPTS_ROOT/.template.env
+__GET_ENV_FILES() { find $SCWRYPTS_CONFIG_PATH/env -maxdepth 1 -type f | sort -r }
-
-__GET_ENV_FILES() { find $SCWRYPTS_CONFIG_PATH/env -maxdepth 1 -type f; }
 [ ! "$(__GET_ENV_FILES)" ] && {
 	cp $__ENV_TEMPLATE "$SCWRYPTS_CONFIG_PATH/env/dev"
 	cp $__ENV_TEMPLATE "$SCWRYPTS_CONFIG_PATH/env/local"
@@ -56,3 +37,22 @@ __GET_AVAILABLE_SCRIPTS() {
 		| sed 's/^\.\///; s/\.[^.]*$//' \
 		;
 }
+
+#####################################################################
+
+__RUN_SCWRYPT() {
+	# run a scwrypt inside a scwrypt w/stack-depth indicators
+	((SUBSCWRYPT+=1))
+	printf ' '; printf '--%.0s' {1..$SUBSCWRYPT}; printf " ($SUBSCWRYPT) "
+	echo "  BEGIN SUBSCWRYPT : $(basename $1)"
+
+	SUBSCWRYPT=$SUBSCWRYPT SCWRYPTS_ENV=$ENV_NAME \
+		"$SCWRYPTS_ROOT/scwrypts" $@
+	EXIT_CODE=$?
+
+	printf ' '; printf '--%.0s' {1..$SUBSCWRYPT}; printf " ($SUBSCWRYPT) "
+	echo "  END SUBSCWRYPT   : $(basename $1)"
+	((SUBSCWRYPT-=1))
+
+	return $EXIT_CODE
+}

zsh/db/common.zsh

@@ -0,0 +1,24 @@
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/../common.zsh
+#####################################################################
+
+
+GET_POSTGRES_LOGIN_ARGS() {
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in
+			--host | -h ) _HOST="$2"; shift 2 ;;
+			--name | -d ) _NAME="$2"; shift 2 ;;
+			--pass | -w ) _PASS="$2"; shift 2 ;;
+			--port | -p ) _PORT="$2"; shift 2 ;;
+			--user | -U ) _USER="$2"; shift 2 ;;
+			* ) shift 1 ;;
+		esac
+	done
+
+	[ ! $_HOST ] && _HOST=127.0.0.1
+	[ ! $_NAME ] && _NAME=postgres
+	[ ! $_PORT ] && _PORT=5432
+	[ ! $_USER ] && _USER=postgres
+}

zsh/db/interactive/common.zsh

@@ -0,0 +1,4 @@
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/../common.zsh
+#####################################################################

zsh/db/interactive/postgres

@@ -0,0 +1,29 @@
+#!/bin/zsh
+_DEPENDENCIES+=(
+	pgcli
+)
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+_LOGIN_POSTGRES() {
+	local _HOST _NAME _PASS _PORT _USER
+	GET_POSTGRES_LOGIN_ARGS $@
+
+	local DATA_DIR="$SCWRYPTS_DATA_PATH/db/$_HOST"
+	[ ! -d $DATA_DIR ] && mkdir -p $DATA_DIR
+	cd $DATA_DIR
+
+	__STATUS "performing login  : $_USER@$_HOST:$_PORT/$_NAME"
+	__STATUS "working directory : $DATA_DIR"
+
+	PGPASSWORD="$_PASS" pgcli \
+		--host $_HOST \
+		--port $_PORT \
+		--user $_USER \
+		--dbname $_NAME \
+		;
+}
+
+#####################################################################
+_LOGIN_POSTGRES $@

zsh/db/postgres/common.zsh

@@ -0,0 +1,4 @@
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/../common.zsh
+#####################################################################

zsh/db/postgres/pg_dump

@@ -0,0 +1,44 @@
+#!/bin/zsh
+_DEPENDENCIES+=(
+	pg_dump
+)
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+BACKUP_POSTGRES() {
+	local _HOST _NAME _PASS _PORT _USER
+	GET_POSTGRES_LOGIN_ARGS $@
+
+	local DATA_DIR="$SCWRYPTS_DATA_PATH/db/$_HOST/$_NAME/pg_dump"
+	[ ! -d $DATA_DIR ] && mkdir -p $DATA_DIR
+	cd $DATA_DIR
+
+	local OUTPUT_FILE="$DATA_DIR/$_NAME.dump"
+	[ -f $OUTPUT_FILE ] && {
+		local BACKUP_COUNT=$(ls "$DATA_DIR/$_NAME."*".dump" | wc -l)
+		ls "$DATA_DIR/$_NAME."*".dump"
+
+		__INFO "discovered previous dump for '$_HOST/$_NAME'"
+		__INFO "backing up previous dump to '$_NAME.$BACKUP_COUNT.dump'"
+
+		mv "$OUTPUT_FILE" "$DATA_DIR/$_NAME.$BACKUP_COUNT.dump"
+	}
+
+	__STATUS "making backup of  : $_USER@$_HOST:$_PORT/$_NAME"
+	__STATUS "output file       : $OUTPUT_FILE"
+
+	PGPASSWORD="$_PASS" pg_dump \
+		--verbose \
+		--format custom \
+		--host "$_HOST" \
+		--port "$_PORT" \
+		--username "$_USER" \
+		--dbname "$_NAME" \
+		--file "$OUTPUT_FILE" \
+		&& { __SUCCESS "finished backup of '$_HOST/$_NAME'"; __SUCCESS "saved to '$OUTPUT_FILE'"; } \
+		|| { __ERROR "error creating backup for '$_HOST/$_NAME' (see above)"; return 1; }
+}
+
+#####################################################################
+BACKUP_POSTGRES $@

zsh/db/postgres/pg_restore

@@ -0,0 +1,55 @@
+#!/bin/zsh
+_DEPENDENCIES+=(
+	pg_dump
+)
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+BACKUP_POSTGRES() {
+	local _HOST _NAME _PASS _PORT _USER
+	GET_POSTGRES_LOGIN_ARGS $@
+
+	local DATA_DIR="$SCWRYPTS_DATA_PATH/db/$_HOST/$_NAME/pg_restore"
+	[ ! -d $DATA_DIR ] && mkdir -p $DATA_DIR
+	cd $DATA_DIR
+
+	local INPUT_FILE="$DATA_DIR/$_NAME.dump"
+
+	[ ! -f $INPUT_FILE ] && {
+		local DUMP="$(dirname $DATA_DIR)/pg_dump/$_NAME.dump"
+		__STATUS $DUMP
+		ls $DUMP
+
+		[ -f "$DUMP" ] && {
+			__SUCCESS "discovered previous scwrypts dump"
+			__SUCCESS "$DUMP"
+			__Yn 'restore from this backup?' && INPUT_FILE="$DUMP"
+		}
+
+		[ ! -f "$INPUT_FILE" ] && {
+			__STATUS 'place backup in the following location:'
+			__STATUS "$INPUT_FILE"
+		}
+
+		while [ ! -f $INPUT_FILE ]; do sleep 1; done
+	}
+
+	__STATUS "backup file : $DATA_DIR"
+	__STATUS "database    : $_USER@$_HOST:$_PORT/$_NAME"
+
+	PGPASSWORD="$_PASS" pg_restore \
+		--verbose \
+		--single-transaction \
+		--format custom \
+		--host "$_HOST" \
+		--port "$_PORT" \
+		--username "$_USER" \
+		--dbname "$_NAME" \
+		"$INPUT_FILE" \
+		&& { __SUCCESS "finished restoring backup for '$_HOST/$_NAME'"; } \
+		|| { __ERROR "error restoring backup for '$_HOST/$_NAME' (see above)"; return 1; }
+}
+
+#####################################################################
+BACKUP_POSTGRES $@

zsh/hello-world

@@ -1,6 +1,7 @@
 #!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/common.zsh
-__CHECK_IMPORTS
 #####################################################################
 
 __SUCCESS 'hello world!'

zsh/redis/common.zsh

@@ -0,0 +1,22 @@
+_DEPENDENCIES+=(
+	redis-cli
+)
+_REQUIRED_ENV+=()
+source ${0:a:h}/../common.zsh
+
+[ ! $SCWRYPTS_CACHE_HOST ] && SCWRYPTS_CACHE_HOST=localhost
+[ ! $SCWRYPTS_CACHE_PORT ] && SCWRYPTS_CACHE_PORT=6379
+#####################################################################
+
+_REDIS() {
+	local ARGS=()
+
+	ARGS+=(-h $SCWRYPTS_CACHE_HOST)
+	ARGS+=(-p $SCWRYPTS_CACHE_PORT)
+
+	[ $SCWRYPTS_CACHE_AUTH ] && ARGS+=(-a $SCWRYPTS_CACHE_AUTH)
+
+	redis-cli ${ARGS[@]} $@
+}
+
+CACHE_ENABLED=$(_REDIS ping 2>&1 | grep -qi pong && echo 1 || echo 0)

zsh/redis/curl

@@ -0,0 +1,48 @@
+#!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+CURL_WITH_CACHE() {
+	[ ! $TTL ] && TTL=10
+	[[ $CACHE_ENABLED -eq 0 ]] && {
+		curl $@
+		return $?
+	}
+
+	local ARGS=()
+	local URL
+
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in
+			--   ) shift 1 ;;
+			--*= ) ARGS+=($1); shift 1 ;;
+			--*  ) ARGS+=($1 $2); shift 2 ;;
+			-*   ) ARGS+=($1); shift 1 ;;
+			* ) URL=$1; break ;;
+		esac
+	done
+
+	local KEY=$(GET_URL_KEY $URL)
+	local OUTPUT=$(_REDIS get $KEY 2>&1)
+	[ $OUTPUT ] && {
+		[[ ${#ARGS[@]} -gt 0 ]] && __WARN "cache hit found; ignoring arguments ($ARGS)"
+		echo $OUTPUT
+		return
+	}
+
+	local OUTPUT=$(curl -s $@)
+	[ ! $OUTPUT ] && return 1
+
+	_REDIS set $KEY "$OUTPUT" >/dev/null
+	_REDIS expire $KEY $TTL >/dev/null
+
+	echo $OUTPUT
+}
+
+GET_URL_KEY() { echo "scwrypts:curl:$1" | sed 's/\s\+/+/g'; }
+
+#####################################################################
+CURL_WITH_CACHE $@

zsh/scwrypts/README.md

@@ -15,12 +15,21 @@ This will immediately open your custom configuration file and reload any necessa
 If you use Scwrypts, **you should use these commands all the time**.
 This is your gateway to managing scwrypts sandboxed environments.
 
-Command       | Description
+Command           | Description
-------------- | ---------------------------------------------------------------------------------------
+----------------- | ---------------------------------------------------------------------------------------
-`edit`        | edit an existing environment; synchronizes environments if new variables are added
+`edit`            | edit an existing environment
-`copy`        | copy an existing environment to a new one
+`copy`            | create and edit a new environment from an existing one
-`delete`      | permanently delete an environment by name
+`delete`          | permanently delete an environment by name
-`synchronize` | uses [template](../../.template.env) to add missing and remove extemporaneous variables
+`stage-variables` | stage missing variables; [helpful for non-ZSH scwrypts](../../py/scwrypts/getenv.py)
+`synchronize`     | uses [template](../../.env.template) to add missing and remove extemporaneous variables
+
+### Environment Inheritance
+You can make a child environment by naming an environment `<parent-name>.<child-name>`.
+Children inherit all parent-set values, and **parent-set values overwrite child-set values**.
+Remember that synchronize runs *every time you edit an environment*, so changes propagate to children immediately.
+Inherited values are denoted by `# inherited from <parent-name>` in the environment file.
+
+Nested children will inherit values from all parents.
 
 ## Logs
 Quickly view or clear Scwrypts logs.

zsh/scwrypts/common.zsh

@@ -1,9 +1,4 @@
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/../common.zsh
-
-__CHECK_DEPENDENCIES \
-	;
-
-__CHECK_ENV_VARS \
-	;
-
 #####################################################################

zsh/scwrypts/configure

@@ -1,16 +1,25 @@
 #!/bin/zsh               
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/common.zsh
-__CHECK_IMPORTS
 #####################################################################
 
 [ ! -f $SCWRYPTS_CONFIG_PATH/config ] && {
 	__STATUS 'first-time setup detected; creating local configuration override...'
-	cp $SCWRYPTS_ROOT/.config $SCWRYPTS_CONFIG_PATH/config \
+	touch $SCWRYPTS_CONFIG_PATH/config \
 		&& __SUCCESS 'created!' \
 		|| __FAIL 1 "unable to create config at '$SCWRYPTS_CONFIG_PATH/config'"
+	{
+		echo '#'
+		echo '# configuration for scwrypts'
+		echo '#'
+		sed -n '1d; /^###/q; p' $SCWRYPTS_ROOT/.config | sed '$d'
+	} > $SCWRYPTS_CONFIG_PATH/config
+
+	__EDIT $SCWRYPTS_CONFIG_PATH/config
 
 	__STATUS 'attempting to build virtual environments'
-	$SCWRYPTS_ROOT/zsh/scwrypts/virutalenv/update-all \
+	__RUN_SCWRYPT zsh/scwrypts/virtualenv/update-all \
 		&& __SUCCESS 'finished updating virtualenvs' \
 		|| __WARNING 'unable to create one or more virtualenv (see above)' \
 		;
@@ -19,16 +28,12 @@ __CHECK_IMPORTS
 	__REMINDER 'use "zsh/scwrypts/virtualenv/update-all" to update environments'
 	__REMINDER '(equivalent to "npm install" or "pip install -r requirements.txt")'
 	__REMINDER
+} || {
+	__STATUS 'opening local config for editing'
+	__EDIT $SCWRYPTS_CONFIG_PATH/config
+	__STATUS 'finished editing!'
 }
 
-__STATUS 'opening local config for editing'
-__EDIT $SCWRYPTS_CONFIG_PATH/config
-__STATUS 'finished editing!'
-
-which __SCWRYPTS >/dev/null 2>&1 && {
-	__STATUS 'reloading configuration for current session'
-	source $SCWRYPTS_ROOT/zsh/common.zsh \
-		|| __FAIL 2 'unable to reload configuration :c'
-}
 
 __SUCCESS 'saved new configuration'
+__REMINDER 'changes which affect the hot-key plugin will require a ZSHRC reload'

zsh/scwrypts/environment/common.zsh

@@ -1,9 +1,11 @@
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/../common.zsh
-
-__CHECK_DEPENDENCIES \
-	;
-
-__CHECK_ENV_VARS \
-	;
-
 #####################################################################
+
+_SORT_ENV() {
+	local ENV_FILE="$1"
+
+	sed -i "s/^[A-Z]/export &/; s/^[^#=]\\+$/&=/" "$ENV_FILE"
+	LC_COLLATE=C sort -uo "$ENV_FILE" "$ENV_FILE"
+}

zsh/scwrypts/environment/copy

@@ -1,6 +1,7 @@
 #!/bin/zsh               
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/common.zsh
-__CHECK_IMPORTS
 #####################################################################
 
 __PROMPT 'choose an environment to copy'
@@ -10,7 +11,7 @@ TEMPLATE_ENV_NAME=$(__SELECT_ENV)
 __STATUS "selected '$TEMPLATE_ENV_NAME'"
 
 __PROMPT 'enter new environment name'
-ENV_NAME=$(__FZF_HEAD 'new environment')
+ENV_NAME=$(echo '' | __FZF_HEAD 'new environment')
 [ ! $ENV_NAME ] && __ABORT
 
 TEMPLATE_ENV_FILE=$(__GET_ENV_FILE $TEMPLATE_ENV_NAME)
@@ -18,7 +19,19 @@ ENV_FILE=$(__GET_ENV_FILE $ENV_NAME)
 
 [ -f "$ENV_FILE" ] && __FAIL 2 "'$ENV_NAME' already exists"
 
-__STATUS "creating environment"
+__STATUS "creating environment '$ENV_NAME'"
 cp "$TEMPLATE_ENV_FILE" "$ENV_FILE" \
 	&& __SUCCESS "created '$ENV_NAME'" \
 	|| __FAIL 3 "unable to create '$ENV_NAME'"
+
+__STATUS 'stripping inherited values'
+sed -i 's/ # inherited from.*$//' "$ENV_FILE" 2>/dev/null
+
+__RUN_SCWRYPT zsh/scwrypts/environment/synchronize -- --no-prompt \
+	|| __FAIL 4 'failed to run environment sync'
+
+__RUN_SCWRYPT zsh/scwrypts/environment/edit -- $ENV_NAME \
+	|| __FAIL 4 'failed to edit new environment'
+	;
+
+__SUCCESS "finished copy environment '$TEMPLATE_ENV_NAME > $ENV_NAME'"

zsh/scwrypts/environment/delete

@@ -1,6 +1,7 @@
 #!/bin/zsh               
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/common.zsh
-__CHECK_IMPORTS
 #####################################################################
 
 __PROMPT 'choose an environment to delete'

zsh/scwrypts/environment/edit

@@ -1,11 +1,16 @@
 #!/bin/zsh               
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/common.zsh
-__CHECK_IMPORTS
 #####################################################################
 
-[ $SCWRYPTS_ENV ] \
+[ $1 ] && ENV_NAME="$1"
-	&& ENV_NAME=$SCWRYPTS_ENV \
+
-	|| ENV_NAME=$(__SELECT_OR_CREATE_ENV)
+[ ! $1 ] && {
+	[ $SCWRYPTS_ENV ] \
+		&& ENV_NAME=$SCWRYPTS_ENV \
+		|| ENV_NAME=$(__SELECT_OR_CREATE_ENV)
+}
 [ ! $ENV_NAME ] && __ABORT
 
 ENV_FILE=$(__GET_ENV_FILE $ENV_NAME)
@@ -32,18 +37,8 @@ do
 	}
 done < $ENV_FILE
 
-[ $NEW_VAR ] && {
+__RUN_SCWRYPT zsh/scwrypts/environment/synchronize -- --no-prompt \
-	LC_COLLATE=C sort -uo $__ENV_TEMPLATE $__ENV_TEMPLATE
+	|| __FAIL 4 'failed to run environment sync' \
-	NOPROMPT=1 ${0:a:h}/synchronize
+	;
-	git add $__ENV_TEMPLATE \
-		&& __SUCCESS "auto-staged the $(basename $__ENV_TEMPLATE) changes" \
-		|| {
-			__WARNING "unable to stage $(basename $__ENV_TEMPLATE) changes"
-			__REMINDER "don't forget to commit changes to $(basename $__ENV_TEMPLATE)"
-		}
-	true
-} || {
-	__STATUS 'no new environment variables'
-}
 
 __SUCCESS "environment '$ENV_NAME' successfully modified"

zsh/scwrypts/environment/stage-variables

@@ -1,6 +1,7 @@
 #!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/common.zsh
-__CHECK_IMPORTS
 #####################################################################
 
-__CHECK_ENV_VARS $@ || NOPROMPT=1 $SCWRYPTS_ROOT/zsh/scwrypts/environment/synchronize
+__CHECK_REQUIRED_ENV $@

zsh/scwrypts/environment/synchronize

@@ -1,46 +1,130 @@
-#!/bin/zsh               
+#!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/common.zsh
-__CHECK_IMPORTS
 #####################################################################
 
-[ ! $NOPROMPT ] && {
+_SYNCHRONIZE() {
-	__yN 'change the template before sync?' && __EDIT $__ENV_TEMPLATE
+	while [[ $# -gt 0 ]]
-	sed -i "s/^[A-Z]/export &/; s/^[^#=]\\+$/&=/; s/=.*$/=/" $__ENV_TEMPLATE
+	do
-	LC_COLLATE=C sort -uo $__ENV_TEMPLATE $__ENV_TEMPLATE
+		case $1 in
-	git add $__ENV_TEMPLATE >/dev/null 2>&1
+			--no-prompt ) SLIENT=1; shift 1 ;;
+
+			* ) __WARNING "argument '$1' not recognized"
+				shift 1 ;;
+		esac
+	done
+
+	[ ! $SLIENT ] && {
+		__yN 'change the template before sync?' && __EDIT $__ENV_TEMPLATE
+		_SORT_ENV "$__ENV_TEMPLATE"
+		git add $__ENV_TEMPLATE >/dev/null 2>&1
+	}
+
+	ENVIRONMENTS=$(__GET_ENV_NAMES | sort -r)
+
+	_CLEAR_INHERITED_VARIABLES
+	_INSERT_NEW_VARIABLES
+	_REMOVE_OLD_VARIABLES
+	_SORT_AND_CASCADE
+
+	__SUCCESS 'finished sync!'
 }
 
-ENVIRONMENTS=$(__GET_ENV_FILES)
+#####################################################################
 
-__STATUS 'inserting new environment variables...'
+_CLEAR_INHERITED_VARIABLES() {
-while read line
+	for ENV_NAME in $(echo $ENVIRONMENTS)
-do
+	do
-	for ENV_FILE in $(echo $ENVIRONMENTS)
+		ENV_FILE=$(__GET_ENV_FILE $ENV_NAME)
-    do
+		sed -i 's/ # inherited from.*//' "$ENV_FILE"
-        grep -q "^$line" $ENV_FILE || {
+	done
-            echo $line >> $ENV_FILE && __STATUS "added '$line' to '$ENV_FILE'"
+}
-        }
-    done
-done < <(sed -n '/^./p' $__ENV_TEMPLATE)
 
-__STATUS 'removing old environment variables...'
+_INSERT_NEW_VARIABLES() {
-for ENV_FILE in $(echo $ENVIRONMENTS)
+	__STATUS 'inserting new environment variables...'
-do
-    while read line
-    do
-        ENV_VAR=$(echo "$line" | sed 's/=.*/=/')
-        grep -q "$ENV_VAR" $__ENV_TEMPLATE || {
-            sed -i "\\%$ENV_VAR%d" $ENV_FILE
-            __WARNING "removed unwanted '$ENV_VAR' from '$ENV_FILE'"
-        }
-    done < $ENV_FILE
-done
 
-for ENV_FILE in $(echo $ENVIRONMENTS)
+	local ENV_NAME ENV_FILE line
-do
+	while read line
-	sed -i "s/^[A-Z]/export &/; s/^[^#=]\\+$/&=/" $ENV_FILE
+	do
-	LC_COLLATE=C sort -uo $ENV_FILE $ENV_FILE
+		for ENV_NAME in $(echo $ENVIRONMENTS)
-done
+	    do
-LC_COLLATE=C sort -uo $__ENV_TEMPLATE $__ENV_TEMPLATE
+			ENV_FILE=$(__GET_ENV_FILE $ENV_NAME)
+	        grep -q "$line" $ENV_FILE || {
+	            echo $line >> $ENV_FILE && __STATUS "added '$line' to '$ENV_NAME'"
+	        }
+	    done
+	done < <(sed -n '/^./p' "$__ENV_TEMPLATE")
+}
 
-__SUCCESS 'finished sync!'
+_REMOVE_OLD_VARIABLES() {
+	__STATUS 'removing old environment variables...'
+
+	local ENV_NAME ENV_FILE line
+	for ENV_NAME in $(echo $ENVIRONMENTS)
+	do
+		ENV_FILE=$(__GET_ENV_FILE $ENV_NAME)
+	    while read line
+	    do
+	        ENV_VAR=$(echo "$line" | sed 's/=.*/=/')
+	        grep -q "$ENV_VAR" "$__ENV_TEMPLATE" || {
+	            sed -i "\\%$ENV_VAR%d" "$ENV_FILE"
+	            echo "$ENV_VAR" | grep -qv '^#' \
+					&& __WARNING "removed unwanted '$ENV_VAR' from '$ENV_NAME'"
+	        }
+	    done < $ENV_FILE
+	done
+}
+
+_SORT_AND_CASCADE() {
+	local ENV_NAM ENV_FILE
+
+	for ENV_NAME in $(echo $ENVIRONMENTS)
+	do
+		ENV_FILE=$(__GET_ENV_FILE $ENV_NAME)
+		_CASCADE_ENVIRONMENT $ENV_NAME
+	done
+
+	for ENV_NAME in $(echo $ENVIRONMENTS)
+	do
+		ENV_FILE=$(__GET_ENV_FILE $ENV_NAME)
+		_SORT_ENV "$ENV_FILE"
+	done
+}
+
+_CASCADE_ENVIRONMENT() {
+	local PARENT_NAME="$1"
+	local PARENT_FILE=$(__GET_ENV_FILE $PARENT_NAME)
+
+	local CHILD_NAMES=$(echo $ENVIRONMENTS | grep "^$PARENT_NAME\\.")
+	[ ! $CHILD_NAMES ] && return 0
+
+	__STATUS "cascading '$PARENT_NAME' to children"
+	for CHILD_NAME in $(echo $CHILD_NAMES)
+	do
+		__SUCCESS "detected child '$CHILD_NAME'"
+	done
+
+	local PARENT_VAR VAR_PATTERN CHILD_NAME CHILD_FILE
+
+	while read PARENT_VAR
+	do
+		VAR_PATTERN=$(echo "$PARENT_VAR" | sed 's/=.*/=/; s/\//\/\//g')
+		__STATUS "propagating '$(echo $VAR_PATTERN | sed 's/^export \([^=]*\)=/\1/')' to children"
+
+		PARENT_VAR+=" # inherited from $PARENT_NAME"
+
+		for CHILD_NAME in $(echo $CHILD_NAMES)
+		do
+			CHILD_FILE=$(__GET_ENV_FILE $CHILD_NAME)
+
+			sed -i "/^$VAR_PATTERN/d" "$CHILD_FILE"
+			echo $PARENT_VAR >> "$CHILD_FILE"
+		done
+	done < <(sed -n '/^[^#][^=]*=[^#]\+$/p' "$PARENT_FILE")
+
+	__SUCCESS "finished '$PARENT_NAME' propagation"
+}
+
+#####################################################################
+_SYNCHRONIZE $@

zsh/scwrypts/logs/clear

@@ -1,6 +1,7 @@
 #!/bin/zsh               
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/common.zsh
-__CHECK_IMPORTS
 #####################################################################
 
 cd $SCWRYPTS_ROOT

zsh/scwrypts/logs/common.zsh

@@ -1,9 +1,4 @@
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/../common.zsh
-
-__CHECK_DEPENDENCIES \
-	;
-
-__CHECK_ENV_VARS \
-	;
-
 #####################################################################

zsh/scwrypts/logs/view

@@ -1,11 +1,12 @@
 #!/bin/zsh               
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/common.zsh
-__CHECK_IMPORTS
 #####################################################################
 
 cd $SCWRYPTS_ROOT
 __PROMPT 'select a script log'
-LOG_FILE=$(ls $SCWRYPTS_LOG_PATH | __FZF 'logfile')
+LOG_FILE=$(ls -t $SCWRYPTS_LOG_PATH | __FZF 'logfile')
 [ ! $LOG_FILE ] && { __ERROR 'user abort'; exit 1; }
 
 __STATUS 'opening logfile'

zsh/scwrypts/virtualenv/common.zsh

@@ -1,13 +1,9 @@
+_DEPENDENCIES+=(
+	virtualenv
+	nodeenv
+)
+_REQUIRED_ENV+=()
 source ${0:a:h}/../common.zsh
-
-__CHECK_DEPENDENCIES \
-	virtualenv \
-	nodeenv \
-	;
-
-__CHECK_ENV_VARS \
-	;
-
 #####################################################################
 
 __AVAILABLE_VIRTUALENVS=(python node)
@@ -46,11 +42,11 @@ __UPDATE_VIRTUALENV() {
 		return 1
 	}
 
-	cd $VIRTUALENV_PATH/../
+	cd $SCWRYPTS_ROOT
 	local UPDATE_CODE=0
 	case $TYPE in
-		python ) pip install -r requirements.txt; UPDATE_CODE=$? ;;
+		python ) cd py; pip install -r requirements.txt; UPDATE_CODE=$? ;;
-		node   ) npm install ;
+		node   ) cd zx; npm install ;;
 	esac
 	UPDATE_CODE=$?
 	[[ $UPDATE_CODE -eq 0 ]] \
@@ -82,8 +78,8 @@ __DELETE_VIRTUALENV() {
 __GET_VIRTUALENV_PATH() {
 	local TYPE="$1"
 	case $TYPE in
-		python ) echo "$SCWRYPTS_ROOT/py/.env" ;;
+		python ) echo "$SCWRYPTS_VIRTUALENV_PATH/py" ;;
-		node   ) echo "$SCWRYPTS_ROOT/zx/.env" ;;
+		node   ) echo "$SCWRYPTS_VIRTUALENV_PATH/zx" ;;
 	esac
 }
 

zsh/scwrypts/virtualenv/refresh

@@ -1,6 +1,7 @@
 #!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/common.zsh
-__CHECK_IMPORTS
 #####################################################################
 
 ENV_TYPE=$(echo $__AVAILABLE_VIRTUALENVS | sed 's/ \+/\n/' | __FZF 'select an environment to refresh')

zsh/scwrypts/virtualenv/update-all

@@ -1,6 +1,7 @@
 #!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/common.zsh
-__CHECK_IMPORTS
 #####################################################################
 
 __STATUS 'beginning update for all environments'

zsh/utils/README.md

@@ -0,0 +1,57 @@
+# ZSH Utilities
+
+A shell-scripting utilities module made for ZSH.
+This module is definitely a major component of Scwrypts, but is also standalone and can be sourced by any ZSH script to utilize (almost) all of the features.
+
+## Usage
+Import `utils.module.zsh` to activate all of the features.
+Doing so will *also* check for path dependencies and required environment variables (see [Dependencies](#dependencies) and [Environment](#environment) below).
+
+
+```shell
+#!/bin/zsh
+source ./path/to/utils.plugin.zsh
+__SUCCESS 'ZSH utilities online!'
+```
+
+Checkout [io](./io.zsh) and [os](./os.zsh) for available simple functions.
+
+### Dependencies
+Ensures dependent programs are available for execution.
+Specify a simple name to check the current `PATH`, or give a fully-qualified path for arbitrary dependency inclusion.
+
+Include a dependency by adding to the `_DEPENDENCIES` array.
+*Always using `+=` makes your dependencies extensible to other scripts :)*
+
+If any dependencies are missing, `source utils.module.zsh` will return an error code and count the number of missing dependencies in the variable `DEP_ERROR_COUNT`.
+
+```shell
+#!/bin/zsh
+_DEPENDENCIES+=(
+	path-executable-1
+	path-executable-2
+	/path/to/arbitrary/program
+)
+source ./path/to/utils.plugin.zsh
+echo "missing $DEP_ERROR required dependencies"
+```
+
+### Environment
+Similar to [Dependencies](#dependencies), `environment.zsh` ensures a list of environment variables are *set to non-empty values*.
+
+Include an environment variable by adding to the `_REQUIRED_ENV` array.
+*Something something use `+=` here too ;)*
+
+If any environment variables are missing, `source utils.module.zsh` will return an error code and count the number of missing variables in `ENV_ERROR_COUNT`.
+
+Missing environment variables will be added to the environment template (*exclusive to Scwrypts*).
+
+```shell
+#!/bin/zsh
+_REQUIRED_ENV+=(
+	AWS_PROFILE
+	AWS_REGION
+)
+source ./path/to/utils.plugin.zsh
+echo "missing $ENV_ERROR_COUNT required environment variables"
+```

zsh/utils/colors.zsh

@@ -0,0 +1,25 @@
+__BLACK='\033[0;30m'
+__DARK_GRAY='\033[1;30m'
+
+__RED='\033[0;31m'
+__LIGHT_RED='\033[1;31m'
+
+__GREEN='\033[0;32m'
+__LIGHT_GREEN='\033[1;32m'
+
+__ORANGE='\033[0;33m'
+__YELLOW='\033[1;33m'
+
+__BLUE='\033[1;34m'
+__DARK_BLUE='\033[0;34m'
+
+__PURPLE='\033[1;35m'
+__DARK_PURPLE='\033[0;35m'
+
+__CYAN='\033[1;36m'
+__DARK_CYAN='\033[0;36m'
+
+__WHITE='\033[1;37m'
+__LIGHT_GRAY='\033[0;37m'
+
+__COLOR_RESET='\033[0m'

zsh/utils/credits.zsh

@@ -1,4 +1,7 @@
 __CREDITS() {
+	# scwrypts exclusive ("credits" pulled from README files)
+	[ ! $SCWRYPTS_ROOT ] && return 0
+
 	local COMMAND="$1"
 	cd $SCWRYPTS_ROOT
 	cat ./**/README.md \

zsh/utils/dependencies.zsh

@@ -1,19 +1,15 @@
 __CHECK_DEPENDENCIES() {
-	local DEPENDENCY
+	local DEP ERROR=0
-	for DEPENDENCY in $*
-	do
-		__CHECK_DEPENDENCY $DEPENDENCY || ((__DEPENDENCY_ERROR+=1))
-	done
 
-	__CHECK_COREUTILS || ((__DEPENDENCY_ERROR+=$?))
+	for DEP in $*; do __CHECK_DEPENDENCY $DEP || ((ERROR+=1)); done
+	__CHECK_COREUTILS || ((ERROR+=$?))
 
-	return $__DEPENDENCY_ERROR
+	return $ERROR
 }
 
 __CHECK_DEPENDENCY() {
 	local DEPENDENCY="$1"
 	[ ! $DEPENDENCY ] && return 1
-
 	command -v $DEPENDENCY >/dev/null 2>&1 || {
 		__ERROR "'$1' required but not installed. $(__CREDITS $1)"
 		return 1

zsh/utils/environment.zsh

@@ -1,45 +1,37 @@
-__CHECK_ENV_VARS() {
+__CHECK_REQUIRED_ENV() {
-	local OPTIONAL=0
+	local VAR ERROR=0
-	[[ $1 =~ ^--optional$ ]] && { shift 1; OPTIONAL=1; }
+	for VAR in $*; do __CHECK_ENV_VAR $VAR || ((ERROR+=1)); done
-
+	return $ERROR
-	local VAR_NAME
-	for VAR_NAME in $*
-	do
-		__CHECK_ENV_VAR $VAR_NAME $OPTIONAL || ((__ENVIRONMENT_ERROR+=1))
-	done
-
-	return $__ENVIRONMENT_ERROR
 }
 
 __CHECK_ENV_VAR() {
 	local NAME="$1"
+	[ ! $NAME ] && return 1
+
 	local OPTIONAL="$2"
 	local DEFAULT_VALUE="$3"
 
 	local VALUE=$(eval echo '$'$NAME)
 	[ $VALUE ] && return 0
 
-	local LINE="export $NAME="
-	local TEMPLATE="$SCWRYPTS_ROOT/.template.env"
 
-	grep -q -- "^$LINE" "$TEMPLATE" || {
+	[ $__SCWRYPT ] && {
-		__STATUS 'staging new variable in template'
+		# scwrypts exclusive (missing vars staged in env.template)
+		local LINE="export $NAME="
 
-		echo "$LINE" >> "$TEMPLATE" \
+		grep -q -- "^$LINE" "$__ENV_TEMPLATE" || {
-			&& NOPROMPT=1 $SCWRYPTS_ROOT/zsh/scwrypts/environment/synchronize \
+			__STATUS 'staging new variable in template'
-			&& git add $TEMPLATE >/dev/null 2>&1 \
+
-			&& __SUCCESS "staged '$NAME'" \
+			echo "$LINE" >> "$__ENV_TEMPLATE" \
-			|| {
+				&& __RUN_SCWRYPT zsh/scwrypts/environment/synchronize -- --no-prompt
-				__WARNING  "failed to stage '$NAME'"
+		}
-				__REMINDER "add/commit '$NAME' to template manually"
-			}
 	}
 
 	[ $OPTIONAL ] && {
-		 __ERROR "'$NAME' required"
-		return 1
-	} || {
 		[ $DEFAULT_VALUE ] && $NAME="$DEFAULT_VALUE"
 		return 0
+	} || {
+		 __ERROR "'$NAME' required"
+		return 1
 	}
 }

zsh/utils/io.zsh

@@ -1,29 +1,44 @@
-__ERROR()    { echo "\\033[1;31mERROR    ✖ : $@\\033[0m" >&2; }
+__PRINT() {
-__SUCCESS()  { echo "\\033[1;32mSUCCESS  ✔ : $@\\033[0m" >&2; }
+	local COLOR="$1"
-__WARNING()  { echo "\\033[1;33mWARNING   : $@\\033[0m" >&2; }
+	local MESSAGE="$2"
-__STATUS()   { echo "\\033[1;34mSTATUS     : $@\\033[0m" >&2; }
+
-__REMINDER() { echo "\\033[1;35mREMINDER  : $@\\033[0m" >&2; }
+	local LINE_END
-__PROMPT() {
+	[ $3 ] && LINE_END='' || LINE_END='\n'
-	echo   "\\033[1;36mPROMPT    : $@\\033[0m" >&2
+
-	printf "\\033[1;36mUSER      : \\033[0m" >&2
+	printf "${COLOR}${MESSAGE}${__COLOR_RESET}${LINE_END}"
 }
 
+__ERROR()    { __PRINT $__RED    "ERROR    ✖ : $@" >&2; }
+__SUCCESS()  { __PRINT $__GREEN  "SUCCESS  ✔ : $@" >&2; }
+__WARNING()  { __PRINT $__ORANGE "WARNING   : $@" >&2; }
+__STATUS()   { __PRINT $__BLUE   "STATUS     : $@" >&2; }
+__REMINDER() { __PRINT $__PURPLE "REMINDER  : $@" >&2; }
+__INFO()     { __PRINT $__WHITE  "INFO      : $@" >&2; }
+
+__PROMPT() {
+	__PRINT $__CYAN "PROMPT    : $@" >&2
+	__PRINT $__CYAN "USER      : " --no-end >&2
+}
+
+__FAIL()  { __ERROR "${@:2}"; exit $1; }
+__ABORT() { __FAIL 69 'user abort'; }
+
 __Yn() {
 	__PROMPT "$@ [Yn]"
+	[ $CI ] && { echo y; return 0; }
+
 	local Yn; __READ -k Yn; echo
 	[[ $Yn =~ [nN] ]] && return 1 || return 0
 }
 
 __yN() {
 	__PROMPT "$@ [yN]"
+	[ $CI ] && { echo y; return 0; }
+
 	local yN; __READ -k yN; echo
 	[[ $yN =~ [yY] ]] && return 0 || return 1
 }
 
-__FAIL()  { __ERROR "${@:2}"; exit $1; }
-
-__ABORT() { __FAIL 69 'user abort'; }
-
 #####################################################################
 
 __GETSUDO() {
@@ -35,10 +50,29 @@ __GETSUDO() {
 
 __LESS() { less -R $@ </dev/tty >/dev/tty; }
 
-__FZF()      { fzf -i --height=30% --layout=reverse --prompt "$@ : "; }
+__FZF()      {
-__FZF_HEAD() { fzf -i --height=30% --layout=reverse --print-query --prompt "$@ : " | head -n1; }
+	[ $CI ] && {
-__FZF_TAIL() { fzf -i --height=30% --layout=reverse --print-query --prompt "$@ : " | tail -n1; }
+		__ERROR 'currently in CI, but __FZF requires user input'
+		exit 1
+	}
 
-__READ()  { read $@ </dev/tty; }
+	fzf -i --height=30% --layout=reverse --prompt "$1 : " ${@:2}
+}
+__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
 
-__EDIT() { $EDITOR $@ </dev/tty >/dev/tty; }
+__READ()  {
+	[ $CI ] && {
+		__ERROR 'currently in CI, but __READ explicitly requires terminal input'
+		return 1
+	}
+	read $@ </dev/tty
+}
+
+__EDIT() {
+	[ $CI ] && {
+		__ERROR 'currently in CI, but __EDIT explicitly requires terminal input'
+		return 1
+	}
+	$EDITOR $@ </dev/tty >/dev/tty
+}

zsh/utils/utils.module.zsh

@@ -0,0 +1,46 @@
+#####################################################################
+
+_DEPENDENCIES+=(fzf) # (extensible) list of PATH dependencies
+_REQUIRED_ENV+=()    # (extensible) list of required environment variables
+
+#####################################################################
+
+source ${0:a:h}/colors.zsh
+source ${0:a:h}/io.zsh
+source ${0:a:h}/os.zsh
+source ${0:a:h}/credits.zsh
+
+#####################################################################
+
+IMPORT_ERROR=0
+
+[ $CI ] && {
+	export _AWS_PROFILE="$AWS_PROFILE"
+	export _AWS_ACCOUNT="$AWS_ACCOUNT"
+	export _AWS_REGION="$AWS_REGION"
+}
+
+source ${0:a:h}/dependencies.zsh
+_DEP_ERROR=0
+_DEPENDENCIES=($(echo $_DEPENDENCIES | sort -u))
+__CHECK_DEPENDENCIES $_DEPENDENCIES || _DEP_ERROR=$?
+
+source ${0:a:h}/environment.zsh
+_ENV_ERROR=0
+_REQUIRED_ENV=($(echo $_REQUIRED_ENV | sort -u))
+__CHECK_REQUIRED_ENV $_REQUIRED_ENV || _ENV_ERROR=$?
+
+[[ $_ENV_ERROR -ne 0 ]] && {
+	__REMINDER 'to update missing environment variables, run:'
+	__REMINDER "'scwrypts zsh/scwrypts/environment/edit'"
+}
+
+((IMPORT_ERROR+=$_DEP_ERROR))
+((IMPORT_ERROR+=$_ENV_ERROR))
+
+[[ $IMPORT_ERROR -ne 0 ]] && {
+	__ERROR "encountered $IMPORT_ERROR import error(s)"
+}
+
+#####################################################################
+[[ $IMPORT_ERROR -eq 0 ]]

zsh/youtube/README.md

@@ -0,0 +1,5 @@
+# ZSH Scwrypts
+[![Generic Badge](https://img.shields.io/badge/ytdl--org-youtube--dl-informational.svg)](https://github.com/ytdl-org/youtube-dl)
+<br>
+
+Quick wrappers for downloading and trimming YouTube videos.

zsh/youtube/common.zsh

@@ -0,0 +1,45 @@
+_DEPENDENCIES+=(
+	youtube-dl
+	ffmpeg
+)
+_REQUIRED_ENV+=()
+source ${0:a:h}/../common.zsh
+#####################################################################
+
+YT__GLOBAL_ARGS=(
+	--no-call-home
+	--restrict-filenames
+	)
+
+YT__OUTPUT_DIR="$SCWRYPTS_DATA_PATH/youtube"
+
+YT__GET_INFO() {
+	youtube-dl --dump-json ${YT__GLOBAL_ARGS[@]} $@
+}
+
+YT__GET_FILENAME() {
+	YT__GET_INFO $@ \
+		| jq -r '._filename' \
+		| sed 's/\.[^.]*$/\.mp4/' \
+		;
+}
+
+YT__DOWNLOAD() {
+	local OUTPUT_DIR="$SCWRYPTS_DATA_PATH/youtube"
+	[ ! -d $YT__OUTPUT_DIR ] && mkdir -p $YT__OUTPUT_DIR
+	cd "$YT__OUTPUT_DIR"
+	youtube-dl ${YT__GLOBAL_ARGS[@]} $@ \
+		--format 'bestvideo[ext=mp4]+bestaudio[ext=m4a]/mp4' \
+		;
+}
+
+GET_VIDEO_LENGTH() {
+	local FILENAME="$1"
+
+	ffprobe \
+		-v quiet \
+		-show_entries format=duration \
+		-of default=noprint_wrappers=1:nokey=1 \
+		-i $FILENAME \
+		;
+}

zsh/youtube/download

@@ -0,0 +1,25 @@
+#!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+DOWNLOAD_VIDEO() {
+	local URLS=($@)
+
+	[[ ${#URLS[@]} -eq 0 ]] && URLS=($(echo '' | __FZF_HEAD 'enter URL'))
+	[[ ${#URLS[@]} -eq 0 ]] && __ABORT
+
+	local FILENAME=$(YT__GET_FILENAME $URLS)
+	[ ! $FILENAME ] && __ERROR "unable to download '$URLS'"
+
+	__SUCCESS "Found '$FILENAME'"
+	__Yn "Proceed with download?" || return 1
+
+	YT__DOWNLOAD $URLS \
+		&& __SUCCESS "downloaded to '$YT__OUTPUT_DIR/$FILENAME'" \
+		|| { __ERROR "failed to download '$FILENAME'"; return 2; }
+}
+
+#####################################################################
+DOWNLOAD_VIDEO $@

zsh/youtube/get-audio-clip

@@ -0,0 +1,51 @@
+#!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+GET_AUDIO_CLIP() {
+	local URLS=($@)
+
+	[[ ${#URLS[@]} -eq 0 ]] && URLS=($(echo '' | __FZF_HEAD 'enter URL'))
+	[[ ${#URLS[@]} -eq 0 ]] && __ABORT
+
+	local FILENAME=$(YT__GET_FILENAME $URLS)
+	[ ! $FILENAME ] && __ERROR "unable to download '$URLS'"
+
+	INPUT_FILE="$YT__OUTPUT_DIR/$FILENAME"
+
+	[ ! -f "$INPUT_FILE" ] && {
+		__RUN_SCWRYPT youtube/download -- $URLS || return 1
+	}
+
+	__SUCCESS "video download '$FILENAME' detected!"
+
+	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 ] && __ABORT
+	END_TIME=$(echo $LENGTH | __FZF_HEAD "enter end time ($START_TIME > t ≥ $LENGTH)")
+	[ ! $END_TIME ] && __ABORT
+
+	__STATUS
+	__STATUS "video      : $FILENAME"
+	__STATUS "start time : $START_TIME"
+	__STATUS "end time   : $END_TIME"
+	__STATUS
+	OUTPUT_FILE=$(echo '' \
+		| __FZF_HEAD 'what should I call this clip? (.mp3)' \
+		| sed 's/\.mp3$//' \
+	)
+	[ ! $OUTPUT_FILE ] && __ABORT
+	OUTPUT_FILE="$YT__OUTPUT_DIR/$OUTPUT_FILE.mp3"
+
+	ffmpeg -i "$INPUT_FILE" -q:a 0 -map a \
+		-ss $START_TIME -t $(($END_TIME - $START_TIME))\
+		"$OUTPUT_FILE" \
+		&& __SUCCESS "created clip '$OUTPUT_FILE'" \
+		|| { __ERROR "error creating clip '$(basename $OUTPUT_FILE)' (see above)"; return 3; }
+}
+
+#####################################################################
+GET_AUDIO_CLIP $@

zx/.gitignore

@@ -1,2 +1 @@
 node_modules/
-.env/