v2.6.0

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

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

- i3 window manager scrypts (see --help for more info)
   - zsh/i3/create-local-font-override
   - zsh/i3/launch-or-show

--- New Features -------------------------

Now support `__select` syntax in environment files!
(see zsh/scwrypts/README.md for more detail)

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

- moved some rogue configuration files under the scwrypts config
   - ~/.vim/bundle/build.zsh >> ~/.config/scwrypts/vundle.zsh
   - ~/.config/scwrypts/config.dotfile.zsh >> ~/.config/scwrypts/dotfiles.zsh

- __FZF, __FZF_TAIL, and __FZF_HEAD now create prompt+response logs

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

- zsh/config/symlinks
   - don't fail when trying to symlink a directory
   - no longer fails when trying to replace a broken symlink

- scwrypts now detects environments which are symlinked

- USAGE syntax now correctly shows the position of the '--' argument
  delimiter

support __select in env files; ignore __lower_case suffix in env files; put blank line before comments in env files

added i3 scripts

.config

@@ -1,14 +0,0 @@
-#
-# scwrypts config
-#
-
-# resource paths
-SCWRYPTS_CONFIG_PATH="$HOME/.config/scwrypts"
-SCWRYPTS_ENV_PATH="$SCWRYPTS_CONFIG_PATH/env"
-SCWRYPTS_LOG_PATH="$SCWRYPTS_CONFIG_PATH/logs"
-
-SCWRYPTS_OUTPUT_PATH="$HOME/SCWRYPTS"
-
-# ZLE hotkeys
-SCWRYPTS_SHORTCUT=''     # CTRL + W
-SCWRYPTS_ENV_SHORTCUT='' # CTRL + /

.env.template

@@ -0,0 +1,14 @@
+#!/bin/zsh
+export AWS_ACCOUNT=
+export AWS_PROFILE=
+export AWS_REGION=
+export AWS__EFS__LOCAL_MOUNT_POINT=
+export AWS__S3__MEDIA_BUCKET=
+export AWS__S3__MEDIA_TARGETS=
+export I3__BORDER_PIXEL_SIZE=
+export I3__DMENU_FONT_SIZE=
+export I3__GLOBAL_FONT_SIZE=
+export I3__MODEL_CONFIG=
+export REDIS_AUTH=
+export REDIS_HOST=
+export REDIS_PORT=

.env.template.descriptions

@@ -0,0 +1,17 @@
+AWS_ACCOUNT  | standard AWS environment variables used by awscli and other tools
+AWS_PROFILE  |
+AWS_REGION   |
+
+AWS__EFS__LOCAL_MOUNT_POINT  | fully-qualified path to mount the EFS drive
+
+AWS__S3__MEDIA_BUCKET   | s3 bucket name and filesystem targets for media backups
+AWS__S3__MEDIA_TARGETS  |
+
+I3__BORDER_PIXEL_SIZE   | custom i3 configuration settings
+I3__DMENU_FONT_SIZE     |
+I3__GLOBAL_FONT_SIZE    |
+I3__MODEL_CONFIG        |
+
+REDIS_AUTH  | redis connection credentials
+REDIS_HOST  |
+REDIS_PORT  |

.gitattributes

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

.template.env

@@ -1,10 +0,0 @@
-#!/bin/zsh
-export AWS__EFS__LOCAL_MOUNT_POINT=
-export AWS__S3__MEDIA_BUCKET=
-export AWS__S3__MEDIA_TARGETS=
-export REDIS_AUTH=
-export REDIS_HOST=
-export REDIS_PORT=
-export _AWS_ACCOUNT=
-export _AWS_PROFILE=
-export _AWS_REGION=

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,15 @@ 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.
+- 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)

global/common.zsh

@@ -0,0 +1,42 @@
+#####################################################################
+
+[ ! $SCWRYPTS_ROOT ] && SCWRYPTS_ROOT="$(dirname ${0:a:h})"
+
+source "${0:a:h}/config.zsh"
+
+#####################################################################
+
+__SCWRYPT=1 # arbitrary; indicates scwrypts exists
+
+__PREFERRED_PYTHON_VERSIONS=(3.10 3.9)
+__NODE_VERSION=18.0.0
+
+__ENV_TEMPLATE=$SCWRYPTS_ROOT/.env.template
+
+#####################################################################
+
+__GET_PATH_TO_RELATIVE_ARGUMENT() {
+	[[ $1 =~ ^[.] ]] \
+		&& echo $(readlink -f "$EXECUTION_DIR/$1") \
+		|| echo "$1" \
+		;
+	true
+}
+
+#####################################################################
+
+__RUN_SCWRYPT() {
+	((SUBSCWRYPT+=1))
+	{ printf ' '; printf '--%.0s' {1..$SUBSCWRYPT}; printf " ($SUBSCWRYPT) "; } >&2
+	echo "  BEGIN SUBSCWRYPT : $@" >&2
+
+	SUBSCWRYPT=$SUBSCWRYPT SCWRYPTS_ENV=$ENV_NAME \
+		"$SCWRYPTS_ROOT/scwrypts" $@
+	EXIT_CODE=$?
+
+	{ printf ' '; printf '--%.0s' {1..$SUBSCWRYPT}; printf " ($SUBSCWRYPT) "; } >&2
+	echo "  END SUBSCWRYPT   : $1" >&2
+	((SUBSCWRYPT-=1))
+
+	return $EXIT_CODE
+}

py/.gitignore

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

py/redis/client.py

@@ -8,7 +8,7 @@ class RedisClient(StrictRedis):
         super().__init__(
                 host = getenv('REDIS_HOST'),
                 port = getenv('REDIS_PORT'),
-                password = getenv('REDIS_AUTH'),
+                password = getenv('REDIS_AUTH', required=False),
                 decode_responses = True,
                 )
 

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('''
-    r = StrictRedis("{getenv("REDIS_HOST")}")
+    print(f'''
+>>> 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(
-            f'{ZSH_COMMAND} {name}',
-            shell=True,
-            executable='/bin/zsh',
-            )
-
-        if required:
-            raise MissingVariableError(name)
+    if required and not value:
+        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,269 @@
+#!/bin/zsh
+export EXECUTION_DIR=$(pwd)
+
+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 ERROR=0
+
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in
+			-h | --help )
+				__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'"
+				shift 1
+				;;
+			* )
+				SEARCH_PATTERNS+=$1
+				shift 1
+				;;
+		esac
+	done
+
+	__ERROR_CHECK
+
+	##########################################
+
+	local SCRIPT=$(__SELECT_SCRIPT $SEARCH_PATTERNS)
+	[ ! $SCRIPT ] && exit 2
+	export SCWRYPT_NAME=$SCRIPT
+
+	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 ] && {
+			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 "$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 $@
+source "${0:a:h}/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 $@; }
+_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"
@@ -8,6 +9,6 @@ __STATUS "performing AWS ECR docker login"
 _AWS ecr get-login-password | docker login \
 	--username AWS \
 	--password-stdin \
-	"$_AWS_ACCOUNT.dkr.ecr.$_AWS_REGION.amazonaws.com" \
-	&& __SUCCESS "logged in to 'AWS:$_AWS_ACCOUNT:$_AWS_REGION'" \
-	|| __FAIL 1 "unable to login to '$_AWS_ACCOUNT' in '$_AWS_REGION'"
+	"$AWS_ACCOUNT.dkr.ecr.$AWS_REGION.amazonaws.com" \
+	&& __SUCCESS "logged in to 'AWS:$AWS_ACCOUNT:$AWS_REGION'" \
+	|| __FAIL 1 "unable to login to '$AWS_ACCOUNT' in '$AWS_REGION'"

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/eks/common.zsh

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

zsh/aws/eks/login

@@ -0,0 +1,19 @@
+#!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+__STATUS "performing AWS ECR docker login"
+
+CLUSTER_NAME=$(\
+	_AWS eks list-clusters \
+		| jq -r '.[] | .[]' \
+		| __FZF 'select a cluster'
+)
+[ ! $CLUSTER_NAME ] && __ABORT
+
+__STATUS "updating kubeconfig for '$CLUSTER_NAME'"
+_AWS eks update-kubeconfig --name $CLUSTER_NAME \
+	&& __SUCCESS "kubeconfig updated with '$CLUSTER_NAME'" \
+	|| __ERROR "failed to update kubeconfig; do you have permissions to access '$CLUSTER_NAME'?"

zsh/aws/rds/common.zsh

@@ -0,0 +1,130 @@
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/../common.zsh
+#####################################################################
+
+GET_DATABASE_CREDENTIALS() {
+	local PRINT_PASSWORD=0
+	local ERRORS=0
+
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in
+			--print-password ) PRINT_PASSWORD=1 ;;
+			* )
+				__WARNING "unrecognized argument $1"
+				ERRORS+=1
+				;;
+		esac
+		shift 1
+	done
+
+	__ERROR_CHECK
+
+	##########################################
+
+	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() {
@@ -12,7 +13,7 @@ _ROUTE53_BACKUP() {
 	for DOMAIN in $(_ROUTE53_GET_DOMAINS)
 	do
 		( __STATUS "creating '$BACKUP_PATH/$DOMAIN.txt'" \
-			&& cli53 export --profile $_AWS_PROFILE $DOMAIN > "$BACKUP_PATH/$DOMAIN.txt" \
+			&& cli53 export --profile $AWS_PROFILE $DOMAIN > "$BACKUP_PATH/$DOMAIN.txt" \
 			&& __SUCCESS "backed up '$DOMAIN'" \
 			|| __ERROR "failed to back up '$DOMAIN'" \
 		) &
@@ -24,7 +25,7 @@ _ROUTE53_BACKUP() {
 }
 
 _ROUTE53_GET_DOMAINS() {
-	cli53 list --profile $_AWS_PROFILE \
+	cli53 list --profile $AWS_PROFILE \
 		| awk '{print $2;}' \
 		| sed '1d; s/\.$//'\
 		;

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,12 @@
-[ ! $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
+source ${0:a:h}/../global/common.zsh
+source ${0:a:h}/utils/utils.module.zsh \
+	|| { [ $DONT_EXIT ] && return 1 || exit 1; }
 
 #####################################################################
 
-__DEPENDENCY_ERROR=0
-__ENVIRONMENT_ERROR=0
-
-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; }
+__GET_ENV_FILES() { ls $SCWRYPTS_CONFIG_PATH/env | sort -r }
 [ ! "$(__GET_ENV_FILES)" ] && {
 	cp $__ENV_TEMPLATE "$SCWRYPTS_CONFIG_PATH/env/dev"
 	cp $__ENV_TEMPLATE "$SCWRYPTS_CONFIG_PATH/env/local"
@@ -45,13 +17,14 @@ __GET_ENV_NAMES() { __GET_ENV_FILES | sed 's/.*\///'; }
 __GET_ENV_FILE()  { echo "$SCWRYPTS_CONFIG_PATH/env/$1"; }
 
 __SELECT_OR_CREATE_ENV() { __GET_ENV_NAMES | __FZF_TAIL 'select/create an environment'; }
-__SELECT_ENV()           { __GET_ENV_NAMES | __FZF 'select an environment'; }
+__SELECT_ENV()           { __GET_ENV_NAMES | __FZF      'select an environment'; }
+
+#####################################################################
 
 __GET_AVAILABLE_SCRIPTS() {
 	cd $SCWRYPTS_ROOT;
 	find . -mindepth 2 -type f -executable \
 		| grep -v '\.git' \
-		| grep -v '\.env' \
 		| grep -v 'node_modules' \
 		| sed 's/^\.\///; s/\.[^.]*$//' \
 		;

zsh/config/common.zsh

@@ -0,0 +1,14 @@
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+DEFAULT_CONFIG="${0:a:h}/default.conf.zsh"
+source ${0:a:h}/../common.zsh
+#####################################################################
+
+SAFE_SYMLINKS=1
+
+# in case dotfiles.zsh is sourced... allow user to provide initial config ;)
+[ ! $CONFIG__USER_SETTINGS ] \
+	&& CONFIG__USER_SETTINGS="$SCWRYPTS_CONFIG_PATH/dotfiles.zsh"
+
+[ ! -f "$CONFIG__USER_SETTINGS" ] && cp "$DEFAULT_CONFIG" "$CONFIG__USER_SETTINGS"
+source $CONFIG__USER_SETTINGS

zsh/config/default.conf.zsh

@@ -0,0 +1,19 @@
+#
+# scwrypts dot-files config
+#
+
+#TERMINFO_PATH=/path/to/sourced/terminfo/files
+
+#
+# SAFE_SYMLINKS=1, makes a backup of config files that already exist
+# SAFE_SYMLINKS=0, deletes existing config file
+#
+#SAFE_SYMLINKS=1
+
+
+# lines which begin with '#' are ignored
+SYMLINKS="
+# fully qualified path       ~/.config/THE-REST
+# ---------------------------------------------
+# /path/to/your/kitty.conf   kitty/kitty.conf
+"

zsh/config/settings

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

zsh/config/symlinks

@@ -0,0 +1,36 @@
+#!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+SETUP_SYMLINKS() {
+	while read SYMLINK
+	do
+		SETUP_SYMLINK $(echo $SYMLINK | awk '{print $1;}') $(echo $SYMLINK | awk '{print $2}')
+	done < <(echo $SYMLINKS | sed -n '/^[^#]/p')
+}
+
+SETUP_SYMLINK() {
+	[ ! $2 ] && __FAIL 1 'must provide SOURCE_CONFIG and TARGET_CONFIG'
+
+	local SOURCE_CONFIG="$1"
+	[ ! -f "$SOURCE_CONFIG" ] && [ ! -d "$SOURCE_CONFIG" ] && __FAIL 2 "no such file or directory '$SOURCE_CONFIG'"
+
+	local TARGET_CONFIG="$HOME/.config/$2"
+
+	[ ! -d $(dirname "$TARGET_CONFIG") ] && mkdir -p $(dirname "$TARGET_CONFIG")
+
+	[[ $SAFE_SYMLINKS -eq 1 ]] \
+		&& mv "$TARGET_CONFIG" "$TARGET_CONFIG.bak" >/dev/null 2>&1
+
+	rm "$TARGET_CONFIG" >/dev/null 2>&1
+
+	ln -s "$SOURCE_CONFIG" "$TARGET_CONFIG" \
+		&& __SUCCESS "successfully linked '$(basename $(dirname $TARGET_CONFIG))/$(basename $TARGET_CONFIG)'" \
+		|| __FAIL 3 "failed to create link '$TARGET_CONFIG'" \
+		;
+}
+
+#####################################################################
+SETUP_SYMLINKS $@

zsh/config/terminfo

@@ -0,0 +1,26 @@
+#!/bin/zsh
+_DEPENDENCIES+=(
+	tic
+)
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+SETUP_TERMINFO() {
+	[ ! $TERMINFO_PATH ] && return 0
+	[ ! -d $TERMINFO_PATH ] && __FAIL 1 "TERMINFO_PATH='$TERMINFO_PATH' does not exist"
+
+	local ERRORS=0
+	for TERMINFO in $(find $TERMINFO_PATH -type f)
+	do
+		tic -x $TERMINFO >/dev/null 2>&1 \
+			&& __SUCCESS "added '$(basename $TERMINFO)'" \
+			|| __ERROR "failed to add '$(basename $TERMINFO)'" \
+			;
+	done
+
+	__ERROR_CHECK
+}
+
+#####################################################################
+SETUP_TERMINFO $@

zsh/config/update

@@ -0,0 +1,10 @@
+#!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+__STATUS 'updating all config files and links'
+__RUN_SCWRYPT zsh/config/symlinks || exit 1
+__RUN_SCWRYPT zsh/config/terminfo || exit 2
+__SUCCESS 'finished updating config files and links'

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/db/run-sql/common.zsh

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

zsh/db/run-sql/postgres

@@ -0,0 +1,72 @@
+#!/bin/zsh
+_DEPENDENCIES+=(
+	psql
+)
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+_RUN_SQL_POSTGRES() {
+	local _HOST _NAME _PASS _PORT _USER INPUT_FILE
+
+	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 ;;
+			--file | -i ) INPUT_FILE="$2"; shift 2 ;;
+			* ) shift 1 ;;
+		esac
+	done
+
+	[ ! $_HOST ] && _HOST=127.0.0.1
+	[ ! $_NAME ] && _NAME=postgres
+	[ ! $_PORT ] && _PORT=5432
+	[ ! $_USER ] && _USER=postgres
+
+	local SQL_DIR="$SCWRYPTS_DATA_PATH/sql"
+	[ ! -d $SQL_DIR ] && mkdir -p $SQL_DIR
+	cd $SQL_DIR
+
+	[[ $(ls "*.sql" 2>&1 | wc -l) -eq 0 ]] && {
+		__ERROR "you haven't made any SQL commands yet"
+		__REMINDER "add '.sql' files here: '$SQL_DIR/'"
+		exit 1
+	}
+
+	[ ! $INPUT_FILE ] && INPUT_FILE=$(\
+		__FZF 'select a sql file to run'
+	)
+	[ ! $INPUT_FILE ] && __ABORT
+
+	[ ! -f $INPUT_FILE ] && {
+		__FAIL 2 "no such sql file '$SQL_DIR/$INPUT_FILE'"
+	}
+
+	__STATUS "loading $INPUT_FILE preview..."
+	_LESS $INPUT_FILE
+
+	__STATUS "login   : $_USER@$_HOST:$_PORT/$_NAME"
+	__STATUS "command : ./$INPUT_FILE"
+
+	__yN 'run this command?' || __ABORT
+
+	__STATUS "running './$INPUT_FILE'"
+	PGPASSWORD="$_PASS" psql \
+		-h $_HOST \
+		-p $_PORT \
+		-U $_USER \
+		-d $_NAME \
+		< $INPUT_FILE \
+		&& __SUCCESS "finished running './$INPUT_FILE'" \
+		|| __FAIL 3 "something went wrong running './$INPUT_FILE' (see above)"
+}
+
+#####################################################################
+__WARNING
+__WARNING 'this function is in a beta state'
+__WARNING
+_RUN_SQL_POSTGRES $@

zsh/git/common.zsh

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

zsh/git/package/build

@@ -0,0 +1,6 @@
+#!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+__RUN_SCWRYPT zsh/git/package/install -- --only-build $@

zsh/git/package/common.zsh

@@ -0,0 +1,74 @@
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/../common.zsh
+#####################################################################
+
+PACKAGE_INSTALL_DIR="$HOME/.local/share/source-packages"
+[ ! -d "$PACKAGE_INSTALL_DIR" ] && mkdir -p "$PACKAGE_INSTALL_DIR"
+
+#####################################################################
+
+CLONE() {
+	cd "$PACKAGE_INSTALL_DIR"
+	__STATUS "downloading $NAME"
+	git clone "$TARGET" "$NAME" \
+		&& __SUCCESS "successfully downloaded '$NAME'" \
+		|| __FAIL 1 "failed to download '$NAME'" \
+		;
+}
+
+PULL() {
+	__STATUS "updating '$NAME'"
+	cd "$PACKAGE_INSTALL_DIR/$NAME"
+	git pull origin $(git rev-parse --abbrev-ref HEAD) \
+		&& __SUCCESS "successfully updated '$NAME'" \
+		|| __FAIL 1 "failed to update '$NAME'" \
+		;
+}
+
+#####################################################################
+
+BUILD() {
+	cd "$PACKAGE_INSTALL_DIR/$NAME"
+
+	CHECK_MAKE    && { MAKE    && return 0 || return 1; }
+	CHECK_MAKEPKG && { MAKEPKG && return 0 || return 2; }
+
+	__WARNING 'could not detect supported installation method'
+
+	__REMINDER 'complete manual installation in the directory below:'
+	__REMINDER "$PACKAGE_INSTALL_DIR/$NAME"
+}
+
+CHECK_MAKE()    { [ -f ./Makefile ]; }
+CHECK_MAKEPKG() { [ -f ./PKGBUILD ]; }
+
+MAKE() {
+	[[ $CLEAN -eq 1 ]] && {
+		__STATUS "cleaning '$NAME'"
+		make clean
+	}
+
+	__STATUS "building '$NAME'"
+	make \
+		&& __SUCCESS "finished building '$NAME'" \
+		|| __FAIL 1 "build failed for '$NAME' (see above)"\
+		;
+
+	__STATUS "installing '$NAME'"
+	__GETSUDO
+	sudo make install \
+		&& __SUCCESS "succesfully installed '$NAME'" \
+		|| __FAIL 2 "failed to install '$NAME' (see above)"\
+		;
+}
+
+MAKEPKG() {
+	__STATUS "installing '$NAME'"
+	yes | makepkg -si \
+		&& __SUCCESS "succesfully installed '$NAME'" \
+		|| __FAIL 1 "failed to install '$NAME' (see above)"\
+		;
+}
+
+#####################################################################

zsh/git/package/download

@@ -0,0 +1,6 @@
+#!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+__RUN_SCWRYPT zsh/git/package/install -- --only-pull $@

zsh/git/package/install

@@ -0,0 +1,88 @@
+#!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+INSTALL() {
+	local USAGE="
+		usage: [...options...]
+
+		options
+		  -t, --target-url <string>   target URL; required for first-time download
+		  -n, --local-name <string>   local name for package (optional)
+
+		  -u, --update                if package exists, update without prompt
+		  -b, --only-build            if package exists, skip update step and only build
+		  -p, --only-pull             skip the automated build step
+		  -c, --clean                 for make, run make clean before build
+
+		  -h, --help                  print this message and exit
+	"
+	local NAME
+	local TARGET
+
+	local SKIP_BUILD=0
+	local SKIP_PULL=0
+	local UPDATE=0
+	local CLEAN=0
+
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in
+			-t | --target-url ) TARGET="$2"; shift 1 ;;
+			-n | --local-name ) NAME="$2"; shift 1 ;;
+
+			-u | --update     ) UPDATE=1 ;;
+			-b | --only-build ) SKIP_PULL=1 ;;
+			-p | --only-pull  ) SKIP_BUILD=1 ;;
+			-c | --clean      ) CLEAN=1 ;;
+
+			-h | --help ) __USAGE; exit 0 ;;
+
+			-* ) __ERROR "unknown argument '$1'" ;;
+
+			* ) [ ! $TARGET ] && TARGET="$1" \
+					|| __ERROR "extra positional argument '$1'" \
+					;
+				;;
+		esac
+		shift 1
+	done
+
+	[[ $SKIP_PULL -eq 1 ]] && [[ $SKIP_BUILD -eq 1 ]] && __ERROR 'only one of [-b | -p] can be specified'
+
+	[ ! $TARGET ] && [ ! $NAME ] && {
+		[[ $SKIP_BUILD -eq 1 ]] && {
+			__ERROR 'cannot skip build without specifying package local-name'
+		} || {
+			UPDATE=1
+			NAME=$(ls "$PACKAGE_INSTALL_DIR" | __FZF 'select a package to update')
+			[ ! $NAME ] && __ERROR 'target-url required'
+		}
+	}
+
+	__ERROR_CHECK
+
+	####################################################
+
+	[ ! $NAME ] && {
+		NAME=$(echo $TARGET | sed 's/.*\///; s/\.git$//')
+		__INFO "using default name '$NAME'"
+	}
+
+	[ -d "$PACKAGE_INSTALL_DIR/$NAME" ] && [[ $SKIP_PULL -eq 0 ]] && {
+		[[ $UPDATE -eq 0 ]] && __Yn "package '$NAME' already exists; update now?" && UPDATE=1
+		[[ $UPDATE -eq 1 ]] && PULL || return 1
+	}
+
+	[ ! -d "$PACKAGE_INSTALL_DIR/$NAME" ] && {
+		CLONE || return 2
+	}
+
+	[[ $SKIP_BUILD -eq 1 ]] && return 0
+	BUILD
+}
+
+#####################################################################
+INSTALL $@

zsh/git/package/update

@@ -0,0 +1,6 @@
+#!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+__RUN_SCWRYPT zsh/git/package/install -- --update $@

zsh/hello-world

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

zsh/i3/common.zsh

@@ -0,0 +1,14 @@
+_DEPENDENCIES+=(
+	i3
+	i3-msg
+)
+_REQUIRED_ENV+=()
+source ${0:a:h}/../common.zsh
+#####################################################################
+
+[ ! $DISPLAY ] && export DISPLAY=:0
+
+_NOTIFY() {
+	__CHECK_DEPENDENCY notify-send || return 0
+	notify-send "SCWRYPTS $SCWRYPT_NAME" $@
+}

zsh/i3/create-local-font-override

@@ -0,0 +1,105 @@
+#!/bin/zsh
+_DEPENDENCIES+=(
+	diff
+)
+_REQUIRED_ENV+=(
+	I3__MODEL_CONFIG
+)
+source ${0:a:h}/common.zsh
+
+__CHECK_ENV_VAR I3__GLOBAL_FONT_SIZE  --optional
+__CHECK_ENV_VAR I3__DMENU_FONT_SIZE   --optional
+__CHECK_ENV_VAR I3__BORDER_PIXEL_SIZE --optional
+#####################################################################
+
+REGEX_FONT='^\(font [^0-9]*\)\(.*\)'
+REGEX_DMENU="^\\(.*dmenu_run .*-fn '[^0-9]*\\)\\([0-9]*\\)'"
+REGEX_BORDER='^\(for_window.*border pixel \)\(.*\)'
+
+INSTALL() {
+	local USAGE="
+		usage: [...options...]
+
+		options
+		  -f, --force             force replacement of existing i3config
+		  -n, --no-link           if output config and template are the same, don't create link
+
+		  -h, --help              print this message and exit
+
+		environment
+		  I3__MODEL_CONFIG        fully-qualified path to sourced i3config
+		  I3__GLOBAL_FONT_SIZE    global font size
+		  I3__DMENU_FONT_SIZE     (optional) font size for 'dmenu' command
+		  I3__BORDER_PIXEL_SIZE   (optional) pixel-width of window borders
+
+		I3 provides no way to include dynamic variables in your config.
+		The main difference I want between my i3 configurations is font-size
+		to match the current monitor. Since i3-msg provides no way to change
+		font size, I run this command to update those variables on a local
+		copy of my sourced config
+	"
+	local FORCE=0
+	local AUTOLINK=1
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in 
+			-f | --force ) FORCE=1 ;;
+			-n | --no-link ) AUTOLINK=0 ;;
+			-h | --help ) __USAGE; exit 0 ;;
+		esac
+		shift 1
+	done
+
+	__STATUS 'reading local i3config'
+	[[ ^$I3__MODEL_CONFIG$ =~ ^$HOME/.config/i3/config$ ]] && {
+		__STATUS "model configuration is default configuration"
+		I3__MODEL_CONFIG="$I3__MODEL_CONFIG.template"
+		[ ! -f "$I3__MODEL_CONFIG" ] && {
+			__STATUS "creating template"
+			cp "$HOME/.config/i3/config" "$I3__MODEL_CONFIG.template"
+		}
+		__STATUS "referring to '$I3__MODEL_CONFIG'"
+	}
+	local CONFIG=$(cat "$I3__MODEL_CONFIG")
+	[ ! $CONFIG ] && __FAIL 1 "failed to read config at '$I3__MODEL_CONFIG'"
+
+	local CONFIG_FILE="$HOME/.config/i3/config"
+	[ ! -d $(dirname "$CONFIG_FILE") ] && mkdir -p "$(dirname "$CONFIG_FILE")"
+
+	[ -f "$CONFIG_FILE" ] && mv "$CONFIG_FILE" "$CONFIG_FILE.bak"
+
+	[ $I3__GLOBAL_FONT_SIZE ] && {
+		__STATUS "setting global font size to '$I3__DMENU_FONT_SIZE'"
+		CONFIG=$(echo $CONFIG | sed "s/$REGEX_FONT/\\1$I3__GLOBAL_FONT_SIZE/")
+	}
+
+	[ $I3__DMENU_FONT_SIZE ] && {
+		__STATUS "setting dmenu font size to '$I3__DMENU_FONT_SIZE'"
+		CONFIG=$(echo $CONFIG | sed "s/$REGEX_DMENU/\\1$I3__DMENU_FONT_SIZE/")
+	}
+
+	[ $I3__BORDER_PIXEL_SIZE ] && {
+		__STATUS "setting border pixel size to '$I3__BORDER_PIXEL_SIZE'"
+		CONFIG=$(echo $CONFIG | sed "s/$REGEX_BORDER/\\1$I3__BORDER_PIXEL_SIZE/")
+	}
+
+	echo $CONFIG > "$CONFIG_FILE"
+	[ -f "$CONFIG_FILE.bak" ] \
+		&& diff "$CONFIG_FILE" "$CONFIG_FILE.bak" -q >/dev/null \
+		&& mv "$CONFIG_FILE.bak" "$CONFIG_FILE" \
+		&& __INFO "no changes were made" \
+		;
+
+	[[ $AUTOLINK -eq 1 ]] \
+		&& diff "$CONFIG_FILE" "$I3__MODEL_CONFIG" -q >/dev/null \
+		&& rm "$CONFIG_FILE" \
+		&& ln -s "$I3__MODEL_CONFIG" "$CONFIG_FILE" \
+		&& __INFO "output is the same as model, i3config has been linked to model" \
+		;
+
+	[[ $FORCE -eq 1 ]] && rm "$CONFIG.bak" >/dev/null 2>&1
+	return 0
+}
+
+#####################################################################
+INSTALL $@

zsh/i3/launch-or-show

@@ -0,0 +1,113 @@
+#!/bin/zsh
+_DEPENDENCIES+=(
+	xdotool
+	xrandr
+	i3-msg
+)
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+LAUNCH_OR_SHOW() {
+	local USAGE="
+		usage: <path-executable> [client-class] [...options...]
+
+		options
+		  -c, --client <string>   if different from the executable name, xprop CLIENT_CLASS
+
+		  -s, --scale <value>     (default: 0.8 or 0.5 if screen width >3000px)
+		  -x, --x-offset <value>  (default: 0.0)
+		  -y, --y-offset <value>  (default: 0.0)
+
+		  -a, --always-launch     invoke executable even if client-class exists
+		  -n, --no-resize         don't resize the window (ignores -sxy flags)
+
+		  -h, --help              print this message and exit
+
+		Makes it easy to bind appications to key shortcuts without having to
+		spin up redundant instances or cycle through the scratchpad queue.
+
+		Depending on state, performs one of three useful functions
+		  1) starts application
+		  2) adds application window to the scratchpad
+		  3) pulls applciation from scratchpad to foreground on active screen
+	"
+	local APPLICATION CLIENT_CLASS
+
+	local XFFSET=0.0
+	local YFFSET=0.0
+	local SCALE=0.8
+	[[ $(xrandr | grep primary | awk '{print $4;}' | sed 's/x.*//') -gt 3000 ]] \
+		&& SCALE=0.5
+
+	local ALWAYS_LAUNCH=0
+	local RESIZE=1
+
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in 
+			-c | --client   ) CLIENT_CLASS="$2"; shift 1 ;;
+			-x | --x-offset ) XFFSET=$2; shift 1 ;;
+			-y | --y-offset ) YFFSET=$2; shift 1 ;;
+			-s | --scale    ) SCALE=$2;  shift 1 ;;
+
+			-a | --always-launch ) ALWAYS_LAUNCH=1 ;;
+			-n | --no-resize     ) RESIZE=0 ;;
+
+			-h | --help ) __USAGE; exit 0 ;;
+
+			* )
+				[ ! $APPLICATION  ] && APPLICATION="$1" \
+					|| __ERROR "extra positional argument '$1'"
+		esac
+		shift 1
+	done
+
+	[ ! $APPLICATION  ] && __ERROR 'path-executable required'
+	[ ! $CLIENT_CLASS ] && CLIENT_CLASS=$APPLICATION
+
+	[ $APPLICATION ] && {
+		__CHECK_DEPENDENCY $APPLICATION || {
+			__ERROR "$APPLICATION is not installed"
+			_NOTIFY "ERROR: $APPLICATION not found"
+		}
+	}
+
+	__ERROR_CHECK
+
+	local LAUNCH_APP=$ALWAYS_LAUNCH
+	__STATUS "looking for window process ids"
+	xdotool search --class $CLIENT_CLASS || LAUNCH_APP=1
+
+	[[ $LAUNCH_APP -eq 1 ]] && {
+		__STATUS 'launching application'
+		i3-msg "exec --no-startup-id $APPLICATION;"
+		sleep .5
+	}
+
+	__STATUS 'getting target window size'
+	WINDOW_SIZE=$(\
+		xrandr \
+			| grep 'connected primary' \
+			| sed 's/.*connected primary \([^x]*\)x\([^+]*\).*/\1 \2/' \
+			| awk -v f=$SCALE -v x=$XFFSET -v y=$YFFSET \
+				'{print int($1*f+x)," ",int($2*f+y);}'\
+	)
+	__INFO "window size: $WINDOW_SIZE"
+
+	__STATUS 'moving window to scratchpad'
+	i3-msg "[class=$CLIENT_CLASS] move scratchpad"
+
+	[[ $RESIZE -eq 1 ]] \
+		&& __STATUS 'resizing window' \
+		&& i3-msg "[class=$CLIENT_CLASS] resize set $WINDOW_SIZE"
+
+	__STATUS 'pulling window from scratchpad to foreground'
+	i3-msg "[class=$CLIENT_CLASS] scratchpad show"
+
+	__STATUS 'moving window to center of current screen'
+	i3-msg "[class=$CLIENT_CLASS] move position center"
+}
+
+#####################################################################
+LAUNCH_OR_SHOW $@

zsh/latex/build-pdf

@@ -0,0 +1,31 @@
+#!/bin/zsh
+_DEPENDENCIES+=(
+	pdflatex
+	rg
+)
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+PDFLATEX() {
+	[ ! $1 ] && __FAIL 1 'must provide filename'
+	local FILENAME=$(GET_MAIN_LATEX_FILENAME "$1")
+
+	local ARGS=(-interaction=nonstopmode)
+	ARGS+=("$FILENAME")
+
+	cd "$(dirname $FILENAME)"
+
+	__STATUS 'running compile (1/2)'
+	pdflatex ${ARGS[@]} \
+		|| __FAIL 2 'first compile failed (see above)'
+
+	__STATUS 'running compile (2/2)'
+	pdflatex ${ARGS[@]} >/dev/null 2>&1 \
+		|| __FAIL 3 'second compile failed :c'
+
+	__SUCCESS "created '$(echo $FILENAME | sed 's/\.[^.]*$/.pdf/')'"
+}
+
+#####################################################################
+PDFLATEX $@

zsh/latex/cleanup

@@ -0,0 +1,20 @@
+#!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+CLEAN_LATEX_LOGFILES() {
+	local DIRECTORY=$(__GET_PATH_TO_RELATIVE_ARGUMENT ".")
+	[ $1 ] && DIRECTORY="$(dirname "$(GET_MAIN_LATEX_FILENAME "$1")")"
+	[ $DIRECTORY ] && [ -d $DIRECTORY ] \
+		|| __FAIL 1 'unable to parse valid directory'
+
+	cd $DIRECTORY
+	rm $(ls | grep '\.\(aux\)\|\(log\)\|\(pdf\)\|\(out\)\|\(dvi\)$')
+
+	__SUCCESS "cleaned up latex artifacts in '$DIRECTORY'"
+}
+
+#####################################################################
+CLEAN_LATEX_LOGFILES $@

zsh/latex/common.zsh

@@ -0,0 +1,34 @@
+_DEPENDENCIES+=(
+	rg
+)
+_REQUIRED_ENV+=()
+source ${0:a:h}/../common.zsh
+#####################################################################
+
+GET_MAIN_LATEX_FILENAME() {
+	local FILENAME=$(__GET_PATH_TO_RELATIVE_ARGUMENT "$1")
+	local DIRNAME="$FILENAME"
+
+	for _ in {1..3}
+	do
+		CHECK_IS_MAIN_LATEX_FILE && return 0
+		DIRNAME="$(dirname "$FILENAME")"
+		__STATUS "checking '$DIRNAME'"
+		[[ $DIRNAME =~ ^$HOME$ ]] && break
+		FILENAME=$(
+			rg -l --max-depth 1 'documentclass' "$DIRNAME/" \
+				| grep '\.tex$' \
+				| head -n1 \
+		)
+		__STATUS "here is '$FILENAME'"
+	done
+
+	__WARNING 'unable to find documentclass; pdflatex will probably fail'
+	echo "$1"
+}
+
+CHECK_IS_MAIN_LATEX_FILE() {
+	[ ! $FILENAME ] && return 1
+	grep -q 'documentclass' $FILENAME 2>/dev/null && echo $FILENAME || return 3
+}
+

zsh/latex/create-new

@@ -0,0 +1,63 @@
+#!/bin/zsh
+_DEPENDENCIES+=(
+	pdflatex
+	rg
+)
+_REQUIRED_ENV+=()
+
+TEMPLATE_DIR="${0:a:h}/templates"
+
+source ${0:a:h}/common.zsh
+#####################################################################
+
+CREATE_NEW_LATEX_DOCUMENT_FROM_TEMPLATE() {
+	local DOCUMENT_DIR="$EXECUTION_DIR"
+	local TEMPLATE=$(GET_TEMPLATES | __FZF 'select a template')
+	[ ! $TEMPLATE ] && __ABORT
+	__SUCCESS "selected template '$TEMPLATE'"
+
+	__INPUT DOC_TITLE 'document title' || __ABORT
+
+	local DOCUMENT_FILE="$DOCUMENT_DIR/$(SLUGIFY_TITLE).tex"
+	[ -f "$DOCUMENT_FILE" ] && __FAIL 1 "'$(basename $DOCUMENT_FILE)' already exists"
+
+	__INPUT DOC_ID    'document id/subtitle'
+	__INPUT AUTHOR    'author name'
+	__INPUT AUTHOR_ID 'author id/title'
+
+	{
+		PRINT_TITLE_INFO 
+		cat "$TEMPLATE_DIR/$TEMPLATE/template.tex"
+	} > "$DOCUMENT_FILE"
+	cp "$TEMPLATE_DIR/gitignore" "$DOCUMENT_DIR/.gitignore"
+	for FILE in $(find "$TEMPLATE_DIR/$TEMPLATE" -type f | grep -v '/template.tex$')
+	do
+		cp "$FILE" "$DOCUMENT_DIR/" || return 2
+	done
+	[[ ! $TEMPLATE =~ ^basic$ ]] \
+		&& mkdir "$DOCUMENT_DIR/sections" "$DOCUMENT_DIR/graphics"
+
+	__SUCCESS "finished generating '$(basename $DOCUMENT_FILE)' from '$TEMPLATE'"
+}
+
+GET_TEMPLATES() {
+	find "$TEMPLATE_DIR" -type d | sed "s^$TEMPLATE_DIR/*^^; /^$/d"
+}
+
+PRINT_TITLE_INFO() {
+	local DATESTRING=$(date '+%B %_d, %Y' | sed 's/ \{1,\}/ /g')
+	sed "
+		s^LATEX-DOC-TITLE^$DOC_TITLE^
+		s^LATEX-DOC-DATE^$DATESTRING^
+		s^LATEX-DOC-ID^$DOC_ID^
+		s^LATEX-AUTHOR-NAME^$AUTHOR^
+		s^LATEX-AUTHOR-ID^$AUTHOR_ID^
+	" "$TEMPLATE_DIR/main.tex"
+}
+
+SLUGIFY_TITLE() {
+	echo $DOC_TITLE | sed "s^['\"\\/,\!@#\$%^&*()]*^^g; s^\s\+^-^g;"
+}
+
+#####################################################################
+CREATE_NEW_LATEX_DOCUMENT_FROM_TEMPLATE $@

zsh/latex/get-pdf

@@ -0,0 +1,15 @@
+#!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+GET_PDF() {
+	local FILENAME=$(GET_MAIN_LATEX_FILENAME "$1" | sed 's/\.[^.]*$/.pdf/')
+	[ $FILENAME ] && [ -f $FILENAME ] || __FAIL 1 "no compiled pdf found for '$1'; have you run 'build-pdf'?"
+	__SUCCESS 'found main pdf'
+	echo $FILENAME
+}
+
+#####################################################################
+GET_PDF $@

zsh/latex/open-pdf

@@ -0,0 +1,15 @@
+#!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+OPEN_PDF() {
+	local PDF=$(__RUN_SCWRYPT latex/get-pdf -n -- $1)
+	[ ! $PDF ] && return 1
+
+	__OPEN "$PDF"
+}
+
+#####################################################################
+OPEN_PDF $@

zsh/latex/templates/basic/template.tex

@@ -0,0 +1,37 @@
+\usepackage[margin=.75in,bottom=0.5in,top=1.0in]{geometry}
+
+\usepackage{enumitem}
+\usepackage{fancyhdr}
+\usepackage{hyperref}
+\usepackage{lastpage}
+
+\newcommand{\headerL}     {\documentTitle: \documentDate}
+\newcommand{\headerC}     {\documentId}
+\newcommand{\headerR}     {\authorName\ (\authorId)}
+\newcommand{\pageOfTotal} {\thepage\ of~\pageref{LastPage}}
+
+\pagestyle{fancy}
+\fancypagestyle{plain}{%
+	\fancyhf{}
+	\fancyhead[L]{\headerL}\fancyhead[R]{\headerR}\fancyhead[C]{\headerC}
+	\fancyfoot[C]{\pageOfTotal}
+}
+
+\renewcommand{\baselinestretch}{1}
+\setlength{\parskip}{0em}
+\hyphenpenalty=5000%
+
+\fancyhf{}
+\fancyhead[L]{\headerL}\fancyhead[R]{\headerR}\fancyhead[C]{\headerC}
+\fancyfoot[C]{\pageOfTotal}
+
+\title{\documentTitle}
+\author{\authorName\ \\ \authorId}
+\date{\documentDate}
+
+\begin{document}
+\maketitle%
+% ---------------------------------------------------------------------
+
+% ---------------------------------------------------------------------
+\end{document}

zsh/latex/templates/gitignore

@@ -0,0 +1,5 @@
+*.aux
+*.log
+*.out
+*.pdf
+*.dvi

zsh/latex/templates/main.tex

@@ -0,0 +1,9 @@
+\documentclass[letterpaper]{article}
+
+\newcommand{\documentTitle} {LATEX-DOC-TITLE}
+\newcommand{\documentDate}  {LATEX-DOC-DATE}
+\newcommand{\documentId}    {LATEX-DOC-ID}
+
+\newcommand{\authorName}    {LATEX-AUTHOR-NAME}
+\newcommand{\authorId}      {LATEX-AUTHOR-ID}
+

zsh/latex/templates/math/code.sty

@@ -0,0 +1,11 @@
+\ProvidesPackage{code}
+% ---------------------------------------------------------------------
+
+\newcommand{\clispsnippet}[2]{%
+	\lstinputlisting[%
+		caption=#1,
+		language=Lisp,
+		showstringspaces=false,
+		numbers=left,
+	]{#2}
+}

zsh/latex/templates/math/formatting.sty

@@ -0,0 +1,46 @@
+\ProvidesPackage{formatting}
+% ---------------------------------------------------------------------
+
+\newcommand{\headerLeft}   {\documentTitle: \documentDate}
+\newcommand{\headerCenter} {\documentId}
+\newcommand{\headerRight}  {\authorName\ (\authorId)}
+\newcommand{\pageOfTotal}  {\thepage\ of~\pageref{LastPage}}
+
+\newtheorem{theorem}{Theorem}[section]
+\newtheorem{lemma}[theorem]{Lemma}
+\newtheorem{corollary}{Corollary}[theorem]
+
+\RequirePackage[margin=1in,bottom=.5in,includefoot]{geometry}
+\RequirePackage{lastpage}
+\RequirePackage{fancyhdr}
+
+% ---------------------------------------------------------------------
+% Page 1
+
+\pagestyle{fancy}
+\fancypagestyle{plain}{%
+	\fancyhf{}
+	\fancyhead[L]{\headerLeft}
+	\fancyhead[R]{\headerRight}
+	\fancyhead[C]{\headerCenter}
+	\fancyfoot[C]{\pageOfTotal}
+}
+
+\renewcommand{\baselinestretch}{1}
+\setlength{\parskip}{0em}
+\setlength{\parindent}{0em}
+
+% ---------------------------------------------------------------------
+% Pages 2+
+
+\fancyhf{}
+\fancyhead[L]{\headerLeft}
+\fancyhead[R]{\headerRight}
+\fancyhead[C]{\headerCenter}
+\fancyfoot[C]{\pageOfTotal}
+
+% ---------------------------------------------------------------------
+
+\title{\documentTitle}
+\author{\authorName\ \\ \authorId}
+\date{\documentDate}

zsh/latex/templates/math/imports.sty

@@ -0,0 +1,16 @@
+\ProvidesPackage{imports}
+% ---------------------------------------------------------------------
+
+\RequirePackage{amssymb} % "bold" math letters (e.g. set of integers ℤ)
+\RequirePackage{amsmath} % advanced math symbols
+
+\RequirePackage{listings} % code snippet styling block
+
+\RequirePackage{tikz} % graphic drawing / generation
+\usetikzlibrary{arrows,automata}
+\usetikzlibrary{trees}
+
+\RequirePackage{graphicx} % include images
+\graphicspath{{./graphics/}}
+
+\RequirePackage[english]{babel} % -- English compilation rules

zsh/latex/templates/math/shorthand.sty

@@ -0,0 +1,13 @@
+\ProvidesPackage{shorthand}
+% ---------------------------------------------------------------------
+
+\newcommand{\egfcoefficient}{\ensuremath{\left[\frac{x^n}{n!}\right]}}
+\newcommand{\ogfcoefficient}{\ensuremath{\left[x^n\right]}}
+\newcommand{\falling}[1]{^{\underline{#1}}}
+\newcommand{\divides}{\ensuremath{\;\backslash\;}}
+
+\newcommand{\sumgz}{\ensuremath{\sum_{n\geq 0}}}
+\newcommand{\sumdiv}{\ensuremath{\sum_{d\divides n}}}
+
+\newcommand{\union}{\ensuremath{\cup}}
+\newcommand{\intersect}{\ensuremath{\cap}}

zsh/latex/templates/math/template.tex

@@ -0,0 +1,12 @@
+\usepackage{imports}
+\usepackage{formatting}
+\usepackage{shorthand}
+\usepackage{code}
+
+\begin{document}
+\maketitle
+% ---------------------------------------------------------------------
+% \input{sections/01.introduction.tex}
+% \includegraphic{graphics/diagram-a.png}
+% ---------------------------------------------------------------------
+\end{document}

zsh/latex/templates/times-new-roman-12/custom-headers.sty

@@ -0,0 +1,7 @@
+\ProvidesPackage{custom-headers}
+% ---------------------------------------------------------------------
+
+\newcommand{\firstH}[1]  {\begin{large}\textbf{#1}\end{large}\par}
+\newcommand{\secondH}[1] {\textbf{#1}\par}
+\newcommand{\thirdH}[1]  {\textbf{#1}. }
+\newcommand{\fourthH}[1] {\textbf{\textit{#1}}. }

zsh/latex/templates/times-new-roman-12/formatting.sty

@@ -0,0 +1,31 @@
+\ProvidesPackage{formatting}
+% ---------------------------------------------------------------------
+
+\newcommand{\horizontalHeader} {%
+	\authorName\hfill
+	\authorId\hfill
+	\documentId\hfill
+	\documentDate%
+}
+
+\RequirePackage[margin=1in]{geometry}
+\RequirePackage{fancyhdr}
+
+% ---------------------------------------------------------------------
+
+\pagestyle{fancy}
+\renewcommand{\headrulewidth}{0pt}
+\fancyhead[C]{\horizontalHeader}
+\fancyfoot[C]{\thepage}
+
+\renewcommand{\baselinestretch}{1}
+\setlength{\parskip}{1em}
+\setlength{\parindent}{0em}
+\raggedright%
+
+% ---------------------------------------------------------------------
+
+\newcommand{\insertTitle} {%
+	\centerline{\begin{large}\textbf{\documentTitle}\end{large}}
+}
+

zsh/latex/templates/times-new-roman-12/imports.sty

@@ -0,0 +1,11 @@
+\ProvidesPackage{imports}
+% ---------------------------------------------------------------------
+
+\RequirePackage{times} % "Times New Roman" font
+
+\RequirePackage{kantlipsum} % generate Kantian lorem ipsum
+
+\RequirePackage{graphicx} % include images
+\graphicspath{{./graphics/}}
+
+\RequirePackage[english]{babel} % -- English compilation rules

zsh/latex/templates/times-new-roman-12/template.tex

@@ -0,0 +1,15 @@
+\usepackage{imports}
+\usepackage{formatting}
+\usepackage{custom-headers}
+
+\begin{document}
+\insertTitle%
+% ---------------------------------------------------------------------
+
+% \input{sections/abstract.tex}
+% \includgraphics{graphics/table-a.png}
+\firstH{First-level Header}
+\kant%
+
+% ---------------------------------------------------------------------
+\end{document}

zsh/memo/common.zsh

@@ -0,0 +1,19 @@
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/../common.zsh
+#####################################################################
+
+set +o noglob
+MEMO__FILETYPE=md
+MEMO__DIR="$SCWRYPTS_DATA_PATH/memo"
+[ ! -d $MEMO__DIR ] && mkdir -p $MEMO__DIR
+
+LIST_MEMOS() { ls $MEMO__DIR | sed "s/\.$MEMO__FILETYPE$//" | sort; }
+
+# TODO : remove deprecated migration
+[ -d $HOME/.memos ] && {
+	__Yn 'detected legacy memos folder; upgrade now?' && {
+		mv $HOME/.memos/* $MEMO__DIR
+		rmdir "$HOME/.memos"
+	}
+}

zsh/memo/open

@@ -0,0 +1,30 @@
+#!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+OPEN_MEMO() {
+	local MEMO_NAME=$(LIST_MEMOS | __FZF_TAIL 'select/create a memo')
+	[ ! "$MEMO_NAME" ] && __ABORT
+
+	MEMO_FILE="$MEMO__DIR/$MEMO_NAME.$MEMO__FILETYPE"
+
+	[ ! -f $MEMO_FILE ] && {
+		__STATUS "creating memo '$MEMO_NAME'"
+		echo "# $MEMO_NAME" > "$MEMO_FILE" \
+			&& __SUCCESS "created memo '$MEMO_NAME'" \
+			|| __FAIL 1 "failed to create '$MEMO_FILE'" \
+			;
+	}
+
+	DATESTRING="## $(date '+%A, %B %-d, %Y')"
+	grep -q "$DATESTRING" "$MEMO_FILE" || echo "$DATESTRING" >> "$MEMO_FILE"
+
+	__EDIT "$MEMO_FILE"
+}
+
+
+
+#####################################################################
+OPEN_MEMO $@

zsh/memo/remove

@@ -0,0 +1,32 @@
+#!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
+source ${0:a:h}/common.zsh
+#####################################################################
+
+OPEN_MEMO() {
+	local MEMO_NAME=$(LIST_MEMOS | __FZF 'select a memo to delete')
+	local MEMO_FILE="$MEMO__DIR/$MEMO_NAME.$MEMO__FILETYPE"
+	[ "$MEMO_NAME" ] && [ -f "$MEMO_FILE" ] || __ABORT
+
+	__STATUS "--- START OF MEMO ---------------------------------------------------"
+	cat "$MEMO_FILE"
+	__STATUS "--- END OF MEMO -----------------------------------------------------"
+
+	__WARNING
+	__WARNING 'memos are not backed up by default; deletion is permanent!'
+	__WARNING
+
+	__yN 'are you sure you want to delete this memo?' || __ABORT
+
+	__STATUS "deleting memo '$MEMO_FILE'"
+	rm "$MEMO_FILE" \
+		&& __SUCCESS "removed memo '$MEMO_NAME'" \
+		|| __FAIL 1 "failed to remove memo '$MEMO_NAME'" \
+		;
+}
+
+
+
+#####################################################################
+OPEN_MEMO $@

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,41 @@ 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
-------------- | ---------------------------------------------------------------------------------------
-`edit`        | edit an existing environment; synchronizes environments if new variables are added
-`copy`        | copy an existing environment to a new one
-`delete`      | permanently delete an environment by name
-`synchronize` | uses [template](../../.template.env) to add missing and remove extemporaneous variables
+Command           | Description
+----------------- | ---------------------------------------------------------------------------------------
+`edit`            | edit an existing environment
+`copy`            | create and edit a new environment from an existing one
+`delete`          | permanently delete an environment by name
+`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.
+
+### Special Environment Variable Syntax
+
+All environment variables which end in `__[a-z_]+` are ignored by the template file.
+These environment variables *will propagate to children*, but will not be removed nor staged into the `.env.template`.
+
+#### `__select` Environment Variables
+Omit any variable, but provide a comma-separated list with the `__select` suffix, and the user will be prompted to select a value from the provided options.
+
+In the following configuration, the user will be prompted to select an `AWS_REGION` once at the beginning of scwrypt execution:
+
+```zsh
+export AWS_REGION=
+export AWS_REGION__select=us-east-1,us-east-2,us-west-1,us-west-2
+```
+
+Setting the `AWS_REGION` variable will cause scwrypts to ignore the `__select` syntax.
+
+CI will fail on select, because CI fails on any FZF prompt.
+
 
 ## 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/global/config.zsh | 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,10 @@ __CHECK_IMPORTS
 	__REMINDER 'use "zsh/scwrypts/virtualenv/update-all" to update environments'
 	__REMINDER '(equivalent to "npm install" or "pip install -r requirements.txt")'
 	__REMINDER
+} || {
+	__EDIT $SCWRYPTS_CONFIG_PATH/config
 }
 
-__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,12 @@
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/../common.zsh
-
-__CHECK_DEPENDENCIES \
-	;
-
-__CHECK_ENV_VARS \
-	;
-
 #####################################################################
+
+_SORT_ENV() {
+	local ENV_FILE="$1"
+
+	sed -i "/^# /d; /^$/d" "$ENV_FILE"
+	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,27 +1,30 @@
 #!/bin/zsh               
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/common.zsh
-__CHECK_IMPORTS
 #####################################################################
 
-[ $SCWRYPTS_ENV ] \
-	&& ENV_NAME=$SCWRYPTS_ENV \
-	|| ENV_NAME=$(__SELECT_OR_CREATE_ENV)
+[ $1 ] && ENV_NAME="$1"
+
+[ ! $1 ] && {
+	[ $SCWRYPTS_ENV ] \
+		&& ENV_NAME=$SCWRYPTS_ENV \
+		|| ENV_NAME=$(__SELECT_OR_CREATE_ENV)
+}
 [ ! $ENV_NAME ] && __ABORT
 
 ENV_FILE=$(__GET_ENV_FILE $ENV_NAME)
 [ ! -f $ENV_FILE ] && {
 	__STATUS "Creating '$ENV_NAME'..." \
 		&& cp $__ENV_TEMPLATE $ENV_FILE \
-		&& __SUCCESS 'created!' \
+		&& __RUN_SCWRYPT zsh/scwrypts/environment/synchronize -- --no-prompt \
+		&& __SUCCESS "created '$ENV_NAME'" \
 		|| { __ERROR "failed to create '$ENV_FILE'"; exit 1; }
 }
 
-__STATUS "opening '$ENV_NAME' for editing..."
 __EDIT $ENV_FILE
-sed -i "s/^[A-Z]/export &/; s/^[^#=]\\+$/&=/" $ENV_FILE
-LC_COLLATE=C sort -uo $ENV_FILE $ENV_FILE
+_SORT_ENV $ENV_FILE
 
-__STATUS "finished editing; looking for new environment variables"
 while read line
 do
 	ENV_VAR=$(echo "$line" | sed 's/=.*$//; s/^export //')
@@ -32,18 +35,8 @@ do
 	}
 done < $ENV_FILE
 
-[ $NEW_VAR ] && {
-	LC_COLLATE=C sort -uo $__ENV_TEMPLATE $__ENV_TEMPLATE
-	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'
-}
+__RUN_SCWRYPT zsh/scwrypts/environment/synchronize -- --no-prompt \
+	|| __FAIL 4 'failed to run environment sync' \
+	;
 
 __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,154 @@
-#!/bin/zsh               
+#!/bin/zsh
+_DEPENDENCIES+=()
+_REQUIRED_ENV+=()
 source ${0:a:h}/common.zsh
-__CHECK_IMPORTS
 #####################################################################
 
-[ ! $NOPROMPT ] && {
-	__yN 'change the template before sync?' && __EDIT $__ENV_TEMPLATE
-	sed -i "s/^[A-Z]/export &/; s/^[^#=]\\+$/&=/; s/=.*$/=/" $__ENV_TEMPLATE
-	LC_COLLATE=C sort -uo $__ENV_TEMPLATE $__ENV_TEMPLATE
+_SYNCHRONIZE() {
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in
+			--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"
+	sed -i '/__[a-z_]\+=$/d' "$__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
+	_ADD_DESCRIPTIONS
+
+	__SUCCESS 'finished sync!'
 }
 
-ENVIRONMENTS=$(__GET_ENV_FILES)
+#####################################################################
 
-__STATUS 'inserting new environment variables...'
-while read line
-do
-	for ENV_FILE in $(echo $ENVIRONMENTS)
-    do
-        grep -q "^$line" $ENV_FILE || {
-            echo $line >> $ENV_FILE && __STATUS "added '$line' to '$ENV_FILE'"
-        }
-    done
-done < <(sed -n '/^./p' $__ENV_TEMPLATE)
+_CLEAR_INHERITED_VARIABLES() {
+	for ENV_NAME in $(echo $ENVIRONMENTS)
+	do
+		ENV_FILE=$(__GET_ENV_FILE $ENV_NAME)
+		sed -i 's/ # inherited from.*//' "$ENV_FILE"
+	done
+}
 
-__STATUS 'removing old environment variables...'
-for ENV_FILE in $(echo $ENVIRONMENTS)
-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
+_INSERT_NEW_VARIABLES() {
+	__STATUS 'inserting new environment variables...'
 
-for ENV_FILE in $(echo $ENVIRONMENTS)
-do
-	sed -i "s/^[A-Z]/export &/; s/^[^#=]\\+$/&=/" $ENV_FILE
-	LC_COLLATE=C sort -uo $ENV_FILE $ENV_FILE
-done
-LC_COLLATE=C sort -uo $__ENV_TEMPLATE $__ENV_TEMPLATE
+	local ENV_NAME ENV_FILE line
+	while read line
+	do
+		for ENV_NAME in $(echo $ENVIRONMENTS)
+	    do
+			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/=.*/=/')
+			echo $ENV_VAR | grep -q '__[a-z_]\+=' && continue
+
+	        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"
+}
+
+_ADD_DESCRIPTIONS() {
+	__STATUS 'updating descriptions'
+	while read DESCRIPTION_LINE
+	do
+		ENV_VAR=$(echo $DESCRIPTION_LINE | sed 's/ \+| .*$//')
+		DESCRIPTION=$(echo $DESCRIPTION_LINE | sed 's/^.* | //')
+		for ENV_NAME in $(echo $ENVIRONMENTS)
+		do
+			sed -i "/^export $ENV_VAR=/i # $DESCRIPTION" "$(__GET_ENV_FILE $ENV_NAME)"
+		done
+	done < <(sed -n '/^[^ ]\+ \+| /p' "$__ENV_TEMPLATE.descriptions")
+
+	for ENV_NAME in $(echo $ENVIRONMENTS)
+	do
+		sed -i "/^# /i \ " "$(__GET_ENV_FILE $ENV_NAME)"
+		sed -i "s/^ $//" "$(__GET_ENV_FILE $ENV_NAME)"
+	done
+}
+
+#####################################################################
+_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=$? ;;
-		node   ) npm install ;
+		python ) cd py; pip install -r requirements.txt; UPDATE_CODE=$? ;;
+		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" ;;
-		node   ) echo "$SCWRYPTS_ROOT/zx/.env" ;;
+		python ) echo "$SCWRYPTS_VIRTUALENV_PATH/py" ;;
+		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')