v5.0.0

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

Excited to bring V5 to life. This includes some BREAKING CHANGES to
several aspects of ZSH-type scwrypts. Please refer to the readme
for upgrade details (specifically docs/upgrade/v4-to-v5.md)

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

- ZSH testing library with basic mock capabilities

- new scwrypts environment file format includes metadata and more
  advanced features like optional parent env overrides, selection
  inheritence, and improved structurual flexibility

- speedup cache for non-CI runs of ZSH-type scwrypts

- ${scwryptsmodule} syntax now allows a consistent unique-naming
  scheme for functions in ZSH-type scwrypts while providing better
  insight into origin of API calls in other modules

- reusable, case-statement-driven argument parsers in ZSH-type scwrypts

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

- several utility function renames in ZSH-type scwrypts to improve
  consistency

- documentation comments included in ZSH libraries

- ZSH-type scwrypts now allow library modules to live alongside
  executables
  (zsh/lib still supported; autodetection determines default)

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

- hardened environment checking for REQUIRED_ENV variables; this removes
  the ability to overwrite variables in local function contexts

zsh/README.md

@@ -1,21 +1,113 @@
 # ZSH Scwrypts
 [![Generic Badge](https://img.shields.io/badge/1password-op-informational.svg)](https://1password.com/downloads/command-line)
 [![Generic Badge](https://img.shields.io/badge/BurntSushi-rg-informational.svg)](https://github.com/BurntSushi/ripgrep)
+[![Generic Badge](https://img.shields.io/badge/dbcli-pgcli-informational.svg)](https://github.com/dbcli/pgcli)
 [![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.
+Since they emulate direct user interaction, shell scripts are a (commonly dreaded) go-to for automation.
 
-## Basic Utilities
+Although the malleability of shell scripts can make integrations quickly, the ZSH-type scwrypt provides a structure to promote extendability and clean code while performing a lot of the heavy lifting to ensure consistent execution across different runtimes.
 
-One of my biggest pet-peeves with scripting is when every line of a *(insert-language-here)* program is escaped to shell.
-This kind of program, which doesn't use language features, should be a shell script.
-While there are definitely unavoidable limitations to shell scripting, we can minimize a variety of problems with a modern shell and shared utilities library.
+## The Basic Framework
 
-Loaded by `common.zsh`, the [`utils/` library](./utils) provides:
-- common function wrappers to unify flags and context
-- lazy dependency and environment variable validation
-- consistent (and pretty) user input / output
+Take a look at the simplest ZSH-type scwrypt: [hello-world](./hello-world).
+The bare minimum API for ZSH-type scwrypts is to:
+
+1. include the shebang `#!/usr/bin/env zsh` on the first line of the file
+2. wrap your zsh in a function called `MAIN()`
+3. make the file executable (e.g. `chmod +x hello-world`)
+
+Once this is complete, you are free to simply _write valid zsh_ then execute the scwrypt with `scwrypts hello world zsh`!
+
+## Basics+
+
+While it would be perfectly fine to use the `echo` function in our scwrypt, you'll notice that the `hello-world` scwrypt instead uses `echo.success` which is _not_ valid ZSH by default.
+This is a helper function provided by the scwrypts ZSH library, and it does a lot more work than you'd expect.
+
+Although this function defaults to print user messages in color, notice what happens when you run `scwrypts --output json hello world zsh`:
+
+```json
+{"timestamp":1745674060,"runtime":"c62737da-481e-4013-a370-4dedc76bf4d2","scwrypt":"start of hello-world scwrypts zsh","logLevel":"3","subscwrypt":0}
+{"timestamp":1745674060,"runtime":"c62737da-481e-4013-a370-4dedc76bf4d2","status":"SUCCESS","message":"\"Hello, World!\""}
+{"timestamp":1745674060,"runtime":"c62737da-481e-4013-a370-4dedc76bf4d2","status":"SUCCESS","message":"\"terminated with code 0\""}
+```
+
+We get a LOT more information.
+
+It's 100% possible for you to include your own take on printing messages, but it is highly recommended to use the tools provided here.
+
+### What is loaded by default?
+
+By default, every ZSH-type scwrypt will load [the basic utilities suite](./utils), which is a little different from scwrypts ZSH modules, and a little bit complex.
+Although it's totally worth a deep-dive, here are the fundamentals you should ALWAYS use:
+
+#### Printing User Messages or Logs
+
+Whenever you want to print a message to the user or logs, rather than using `echo`, use the following:
+<!------------------------------------------------------------------------>
+| function name   | minimum log level | description                       |
+| --------------- | ----------------- | --------------------------------- |
+| `echo.success`  |                 1 | indicate successful completion    |
+| `echo.error`    |                 1 | indicate an error has occurred    |
+| `echo.reminder` |                 1 | an important, information message |
+| `echo.status`   |                 2 | a regular, information message    |
+| `echo.warning`  |                 3 | a non-critical warning            |
+| `echo.debug`    |                 4 | a message for scwrypt developers  |
+<!------------------------------------------------------------------------>
+
+Of the `echo` family, there are two unique functions:
+
+- `echo.error` will **increment the `ERRORS` variable** then return an error code of `$ERRORS` (this makes it easy to chain with command failure by using `||`)
+- `echo.debug` will inject state information like the timestamp and current function stack
+
+
+#### Yes / No Prompts
+
+The two helpers `utils.Yn` and `utils.yN` take a user-friendly yes/no question as an argument.
+
+- when the user responds "yes", the command returns 0 / success / `&&`
+- when the user responds "no", the command returns 1 / error / `||`
+- when the user responds with _nothing_ (e.g. just presses enter), the _default_ is used
+
+The two commands work identically; however, the capitalization denotes the default:
+- `utils.Yn` = default "yes"
+- `utils.yN` = default "no"
+
+#### Select from a List Prompt
+
+When you want the user to select an item from a list, scwrypts typically use `fzf`.
+There are a LOT of options to `fzf`, so there are two provided helpers.
+
+The basic selector, `utils.fzf` (most of the time, you want to use this one) which outputs:
+- _the selection_ if the user made a choice
+- _nothing / empty string_ if the user cancelled or made an invalid choice
+
+The user-input selector, `utils.fzf.user-input` which outputs:
+- _the selection_ if the user made a choice
+- _the text typed by the user_ if the user typed something other than the listed choices
+- _nothing / empty string_ if the user cancelled
+- _a secondary `utils.fzf` prompt_ if the user's choice was ambiguous
+
+### Imports
+
+Don't use `source` in ZSH-type scwrypts (I mean, if you're pretty clever you can get it to work, but DON'T THOUGH).
+Instead, use `use`!
+
+The `use` command, rather than specifying file directories, you reference the path to `*.module.zsh`.
+This means you don't have to know the exact path to any given file.
+For example, if I wanted to import the safety tool for `aws` CLI commands, I can do the following:
+
+```zsh
+#!/usr/bin/env zsh
+
+use cloud/aws
+
+#####################################################################
+
+MAIN() {
+    cloud.aws sts get-caller-identity
+}
+```

zsh/cloud/aws/aws.module.zsh

@@ -0,0 +1,13 @@
+#
+# provides utilities for interacting with Amazon Web Services (AWS)
+#
+
+# context wrapper for AWS CLI v2
+use cloud/aws/cli
+eval "${scwryptsmodule}() { ${scwryptsmodule}.cli \$@; }"
+
+# simplify context commands for kubectl on EKS
+use cloud/aws/eks
+
+# context wrapper for eksctl
+use cloud/aws/eksctl

zsh/cloud/aws/aws.test.zsh

@@ -0,0 +1,28 @@
+#####################################################################
+
+use unittest
+testmodule=cloud.aws
+
+#####################################################################
+
+beforeall() {
+	use cloud/aws
+}
+
+#####################################################################
+
+test.provides-aws-cli() {
+	unittest.test.provides ${testmodule}.cli
+}
+
+test.provides-aws-cli-alias() {
+	unittest.test.provides ${testmodule}
+}
+
+test.provides-eks() {
+	unittest.test.provides ${testmodule}.eks
+}
+
+test.provides-eksctl() {
+	unittest.test.provides ${testmodule}.eksctl
+}

zsh/cloud/aws/cli.module.zsh

@@ -0,0 +1,36 @@
+#####################################################################
+
+DEPENDENCIES+=(aws)
+
+use cloud/aws/zshparse
+
+#####################################################################
+
+${scwryptsmodule}() {
+	local PARSERS=(cloud.aws.zshparse.overrides)
+	local ARGS=()
+	local DESCRIPTION="
+		Safe context wrapper for aws cli commands; prevents accidental local environment
+		bleed-through, but otherwise works exactly like 'aws'. For help with awscli, try
+		'AWS [command] help' (no -h or --help)
+
+		This wrapper should be used in place of _all_ 'aws' usages within scwrypts.
+		"
+
+	eval "$(utils.parse.autosetup)"
+
+	##########################################
+
+	echo.debug "invoking '$(echo "$AWS_EVAL_PREFIX" | sed 's/AWS_\(ACCESS_KEY_ID\|SECRET_ACCESS_KEY\)=[^ ]\+ //g')aws ${AWS_CONTEXT_ARGS[@]} ${ARGS[@]}'"
+	eval "${AWS_EVAL_PREFIX}aws ${AWS_CONTEXT_ARGS[@]} ${ARGS[@]}"
+}
+
+#####################################################################
+
+${scwryptsmodule}.parse() {
+	return 0  # uses default args parser
+}
+
+${scwryptsmodule}.parse.usage() {
+	USAGE__args+='\$@   arguments forwarded to the AWS CLI'
+}

zsh/cloud/aws/cli.test.zsh

@@ -0,0 +1,65 @@
+#####################################################################
+
+use unittest
+testmodule=cloud.aws.cli
+
+#####################################################################
+
+beforeall() {
+	use cloud/aws/cli
+}
+
+beforeeach() {
+	unittest.mock aws
+	unittest.mock echo.debug
+
+	_ARGS=($(uuidgen) $(uuidgen) $(uuidgen))
+
+	_AWS_REGION=$(uuidgen)
+	_AWS_PROFILE=$(uuidgen)
+
+	unittest.mock.env AWS_ACCOUNT --value $(uuidgen)
+	unittest.mock.env AWS_PROFILE --value ${_AWS_PROFILE}
+	unittest.mock.env AWS_REGION  --value ${_AWS_REGION}
+}
+
+aftereach() {
+	unset _AWS_REGION
+	unset _AWS_PROFILE
+}
+
+#####################################################################
+
+test.forwards-arguments() {
+	${testmodule} ${_ARGS[@]}
+
+	aws.assert.callstack \
+		--output json \
+		--region ${_AWS_REGION} \
+		--profile ${_AWS_PROFILE} \
+		${_ARGS[@]} \
+		;
+}
+
+test.overrides-region() {
+	local OVERRIDE_REGION=$(uuidgen)
+
+	${testmodule} --region ${OVERRIDE_REGION} ${_ARGS[@]}
+
+	aws.assert.callstack \
+		--output json \
+		--region ${OVERRIDE_REGION} \
+		--profile ${_AWS_PROFILE} \
+		${_ARGS[@]} \
+		;
+}
+
+test.overrides-account() {
+	local OVERRIDE_ACCOUNT=$(uuidgen)
+
+	${testmodule} --account ${OVERRIDE_ACCOUNT} ${_ARGS[@]}
+
+	echo.debug.assert.callstackincludes \
+		AWS_ACCOUNT=${OVERRIDE_ACCOUNT} \
+		;
+}

zsh/cloud/aws/ecr/ecr.module.zsh

@@ -0,0 +1,6 @@
+#
+# common operations for AWS Elastic Container Registry (ECR)
+#
+
+# that obnoxious command which pushes the AWS temporary credentials to 'docker login'
+use cloud/aws/ecr/login

zsh/cloud/aws/ecr/ecr.test.zsh

@@ -0,0 +1,16 @@
+#####################################################################
+
+use unittest
+testmodule=cloud.aws.ecr
+
+#####################################################################
+
+beforeall() {
+	use cloud/aws/ecr
+}
+
+#####################################################################
+
+test.provides-ecr-login() {
+	unittest.test.provides ${testmodule}.login
+}

zsh/cloud/aws/ecr/login

@@ -1,7 +1,17 @@
-#!/bin/zsh
-use cloud/aws/ecr
+#!/usr/bin/env zsh
 #####################################################################
 
-MAIN() {
-	ECR_LOGIN $@
-}
+use cloud/aws/ecr/login
+use cloud/aws/zshparse
+
+#####################################################################
+
+USAGE__description='
+	interactively setup temporary credentials for ECR in the given region
+'
+
+cloud.aws.zshparse.overrides.usage
+
+#####################################################################
+
+MAIN() { cloud.aws.ecr.login $@; }

zsh/cloud/aws/ecr/login.module.zsh

@@ -0,0 +1,30 @@
+#####################################################################
+
+use cloud/aws/cli
+use cloud/aws/zshparse
+
+DEPENDENCIES+=(docker)
+
+#####################################################################
+
+${scwryptsmodule}() {
+	local DESCRIPTION="
+		Performs the appropriate 'docker login' command with temporary
+		credentials from AWS.
+	"
+
+	local PARSERS=(cloud.aws.zshparse.overrides)
+
+	eval "$(utils.parse.autosetup)"
+
+	##########################################
+
+	${AWS} ecr get-login-password \
+		| docker login "${ACCOUNT}.dkr.ecr.${REGION}.amazonaws.com" \
+			--username AWS \
+			--password-stdin \
+			&>/dev/null \
+		&& echo.success "authenticated docker for '${ACCOUNT}' in '${REGION}'" \
+		|| echo.error "unable to authenticate docker for '${ACCOUNT}' in '${REGION}'" \
+		;
+}

zsh/cloud/aws/ecr/login.test.zsh

@@ -0,0 +1,47 @@
+#####################################################################
+
+use unittest
+testmodule=cloud.aws.ecr.login
+
+#####################################################################
+
+beforeall() {
+	use cloud/aws/ecr/login
+}
+
+beforeeach() {
+	unittest.mock cloud.aws.cli
+	unittest.mock docker
+
+	_AWS_ACCOUNT=$(uuidgen)
+	_AWS_PROFILE=$(uuidgen)
+	_AWS_REGION=$(uuidgen)
+
+	unittest.mock.env AWS_ACCOUNT --value ${_AWS_ACCOUNT}
+	unittest.mock.env AWS_PROFILE --value ${_AWS_PROFILE}
+	unittest.mock.env AWS_REGION  --value ${_AWS_REGION}
+
+	_EXPECTED_AWS_ARGS=(
+		--account ${_AWS_ACCOUNT}
+		--region  ${_AWS_REGION}
+	)
+}
+
+aftereach() {
+	unset \
+		_AWS_ACCOUNT _AWS_PROFILE _AWS_REGION \
+		_EXPECTED_AWS_ARGS \
+		;
+}
+
+#####################################################################
+
+test.login-forwards-credentials-to-docker() {
+	${testmodule}
+
+	docker.assert.callstack \
+		login "${_AWS_ACCOUNT}.dkr.ecr.${_AWS_REGION}.amazonaws.com" \
+			--username AWS \
+			--password-stdin \
+			;
+}

zsh/cloud/aws/efs/mount

@@ -1,64 +1,82 @@
-#!/bin/zsh
-DEPENDENCIES+=(jq)
-REQUIRED_ENV+=(AWS__EFS__LOCAL_MOUNT_POINT)
+#!/usr/bin/env zsh
+#####################################################################
 
 use cloud/aws/cli
+use cloud/aws/zshparse/overrides
+
+DEPENDENCIES+=(jq mount sort sudo)
+REQUIRED_ENV+=(AWS__EFS__LOCAL_MOUNT_POINT)
+
+#####################################################################
+
+USAGE__description='
+	interactively mount an AWS EFS volume to the local filesystem
+'
+
 #####################################################################
 
 MAIN() {
-	GETSUDO || exit 1
-	[ ! -d $AWS__EFS__LOCAL_MOUNT_POINT ] && {
-		sudo mkdir $AWS__EFS__LOCAL_MOUNT_POINT \
-			&& STATUS "created local mount point '$AWS__EFS__LOCAL_MOUNT_POINT'"
-	}
+	local PARSERS=(cloud.aws.zshparse.overrides)
+	eval "$(utils.parse.autosetup)"
+	utils.io.getsudo || return 1
+	##########################################
+
+	{
+		mkdir -p -- "${AWS__EFS__LOCAL_MOUNT_POINT}" \
+			|| sudo mkdir -p -- "${AWS__EFS__LOCAL_MOUNT_POINT}"
+	} &>/dev/null
+
+	[ -d "${AWS__EFS__LOCAL_MOUNT_POINT}" ] \
+		|| echo.error "unable to create local mount point '${AWS__EFS__LOCAL_MOUNT_POINT}'" \
+		|| return
 
 	local FS_ID=$(\
-		AWS efs describe-file-systems \
-		| jq -r '.[] | .[] | .FileSystemId' \
-		| FZF 'select a filesystem to mount' \
+		$AWS efs describe-file-systems \
+			| jq -r '.[] | .[] | .FileSystemId' \
+			| utils.fzf 'select a filesystem to mount' \
 	)
-	[ ! $FS_ID ] && ABORT
+	[ ! ${FS_ID} ] && utils.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
+	local MOUNT_POINT="${AWS__EFS__LOCAL_MOUNT_POINT}/${FS_ID}"
+	[ -d "${MOUNT_POINT}" ] && sudo rmdir "${MOUNT_POINT}" &>/dev/null
+	[ -d "${MOUNT_POINT}" ] && {
+		echo.status "${FS_ID} is already mounted"
+		return 0
 	}
 
-	local MOUNT_TARGETS=$(AWS efs describe-mount-targets --file-system-id $FS_ID)
+	local MOUNT_TARGETS=$($AWS efs describe-mount-targets --file-system-id ${FS_ID})
 	local ZONE=$(\
-		echo $MOUNT_TARGETS \
-		| jq -r '.[] | .[] | .AvailabilityZoneName' \
-		| sort -u | FZF 'select availability zone'\
+		echo ${MOUNT_TARGETS} \
+			| jq -r '.[] | .[] | .AvailabilityZoneName' \
+			| sort -u | utils.fzf 'select availability zone'\
 	)
-	[ ! $ZONE ] && ABORT
+	[ ! "${ZONE}" ] && utils.abort
 
 	local MOUNT_IP=$(\
-		echo $MOUNT_TARGETS \
-		| jq -r ".[] | .[] | select (.AvailabilityZoneName == \"$ZONE\") | .IpAddress" \
-		| head -n1 \
+		echo ${MOUNT_TARGETS} \
+			| jq -r ".[] | .[] | select (.AvailabilityZoneName == \"${ZONE}\") | .IpAddress" \
+			| head -n1 \
 	)
 
-	SUCCESS 'ready to mount!'
-	REMINDER 'for private file-systems, you must be connected to the appropriate VPN'
+	echo.success  'ready to mount!'
+	echo.status "
+		file system id    : ${FS_ID}
+		availability zone : ${ZONE}
+		file system ip    : ${MOUNT_IP}
+		local mount point : ${MOUNT_POINT}
+	 "
+	echo.reminder 'for private file-systems, you must be connected to the appropriate VPN'
+	Yn 'proceed?' || utils.abort
 
-	STATUS "file system id    : $FS_ID"
-	STATUS "availability zone : $ZONE"
-	STATUS "file system ip    : $MOUNT_IP"
-	STATUS "local mount point : $MOUNT_POINT"
-
-	Yn 'proceed?' || ABORT
-
-	sudo mkdir $MOUNT_POINT \
+	sudo mkdir -- "${MOUNT_POINT}" \
 		&& sudo mount \
 			-t nfs4 \
 			-o nfsvers=4.1,rsize=1048576,wsize=1048576,hard,timeo=600,retrans=2,noresvport \
-			$MOUNT_IP:/ \
-			"$MOUNT_POINT" \
-		&& SUCCESS "mounted at '$MOUNT_POINT'" \
+			"${MOUNT_IP}:/" \
+			"${MOUNT_POINT}" \
+		&& echo.success "mounted at '${MOUNT_POINT}'" \
 		|| {
-		sudo rmdir $MOUNT_POINT >/dev/null 2>&1
-		FAIL 2 "unable to mount '$FS_ID'"
-	}
+			sudo rmdir -- "${MOUNT_POINT}" &>/dev/null
+			echo.error "unable to mount '${FS_ID}'"
+		}
 }

zsh/cloud/aws/efs/unmount

@@ -1,32 +1,39 @@
-#!/bin/zsh
-DEPENDENCIES+=(jq)
-REQUIRED_ENV+=(AWS__EFS__LOCAL_MOUNT_POINT)
-
-use cloud/aws/cli
+#!/usr/bin/env zsh
 #####################################################################
 
+DEPENDENCIES+=(jq umount sudo)
+REQUIRED_ENV+=(AWS__EFS__LOCAL_MOUNT_POINT)
+
+#####################################################################
+
+USAGE__description='
+	interactively unmount an AWS EFS volume to the local filesystem
+'
+
 MAIN() {
-	[ ! -d "$AWS__EFS__LOCAL_MOUNT_POINT" ] && {
-		STATUS 'no efs currently mounted'
-		exit 0
+	eval "$(utils.parse.autosetup)"
+	##########################################
+
+	[ ! -d "${AWS__EFS__LOCAL_MOUNT_POINT}" ] && {
+		echo.status 'no efs currently mounted'
+		return 0
 	}
 
-	local MOUNTED=$(ls "$AWS__EFS__LOCAL_MOUNT_POINT")
-	[ ! $MOUNTED ] && {
-		STATUS 'no efs currently mounted'
-		exit 0
+	local MOUNTED=$(cd -- "${AWS__EFS__LOCAL_MOUNT_POINT}" | find . -type -f | sed 's|^\./.||')
+	[ "${MOUNTED}" ] && {
+		echo.status 'no efs currently mounted'
+		return 0
 	}
 
-	GETSUDO || exit 1
+	utils.io.getsudo || return 1
 
+	local SELECTED=$(echo ${MOUNTED} | utils.fzf 'select a file system to unmount')
+	[ "${SELECTED}" ] || user.abort
 
-	local SELECTED=$(echo $MOUNTED | FZF 'select a file system to unmount')
-	[ ! $SELECTED ] && ABORT
-
-	local EFS="$AWS__EFS__LOCAL_MOUNT_POINT/$SELECTED"
-	STATUS "unmounting '$SELECTED'"
-	sudo umount $EFS >/dev/null 2>&1
-	sudo rmdir $EFS \
-		&& SUCCESS "done" \
-		|| FAIL 2 "failed to unmount '$EFS'"
+	local EFS="${AWS__EFS__LOCAL_MOUNT_POINT}/${SELECTED}"
+	echo.status "unmounting '${SELECTED}'"
+	sudo umount "${EFS}" >/dev/null 2>&1
+	sudo rmdir -- "${EFS}" \
+		&& echo.success "done" \
+		|| utils.fail 2 "failed to unmount '${EFS}'"
 }

zsh/cloud/aws/eks/cli.module.zsh

@@ -0,0 +1,86 @@
+#####################################################################
+
+use cloud/aws/eks/cluster-login
+
+use cloud/aws/zshparse
+use cloud/aws/eks/zshparse
+
+#####################################################################
+
+${scwryptsmodule}() {
+	local DESCRIPTION="
+		Context wrapper for kubernetes CLI commands on AWS EKS. This
+		will automatically attempt login for first-time connections,
+		and ensures the correct kubecontext is used for the expected
+		command.
+
+			EKS --cluster-name my-cluster kubectl get pods
+			EKS --cluster-name my-cluster helm history my-deployment
+			... etc ...
+		"
+	local ARGS=() PARSERS=(
+		cloud.aws.zshparse.overrides
+		cloud.aws.eks.zshparse.cluster-name
+	)
+
+	eval "$(utils.parse.autosetup)"
+
+	##########################################
+
+	local CONTEXT="arn:aws:eks:${REGION}:${ACCOUNT}:cluster/${CLUSTER_NAME}"
+
+	local ALREADY_LOGGED_IN
+	kubectl config get-contexts --output=name | grep -q "^${CONTEXT}$" \
+		&& ALREADY_LOGGED_IN=true \
+		|| ALREADY_LOGGED_IN=false \
+		;
+
+	case ${ALREADY_LOGGED_IN} in
+		( true ) ;;
+		( false )
+			cloud.aws.eks.cluster-login \
+					${AWS_PASSTHROUGH[@]} \
+					--cluster-name ${CLUSTER_NAME} \
+					>/dev/null \
+				|| echo.error "unable to login to cluster '${CLUSTER_NAME}'" \
+				|| return 1
+			;;
+	esac
+
+	local CONTEXT_ARGS=()
+	case ${KUBECLI} in
+		( helm )
+			CONTEXT_ARGS+=(--kube-context ${CONTEXT})  # *rolls eyes* THANKS, helm
+			;;
+		( * )
+			CONTEXT_ARGS+=(--context ${CONTEXT})
+			;;
+	esac
+
+	${KUBECLI} ${CONTEXT_ARGS[@]} ${ARGS[@]}
+}
+
+#####################################################################
+
+${scwryptsmodule}.parse() { return 0; }
+
+${scwryptsmodule}.parse.locals() {
+	local KUBECLI   # extracted from default ARGS parser
+}
+
+${scwryptsmodule}.parse.usage() {
+	USAGE__usage+=' kubecli [...kubecli-args...]'
+
+	USAGE__args+='
+		kubecli        cli which uses kubernetes context arguments (e.g. kubectl, helm, flux)
+		kubecli-args   arguments forwarded to the kubectl-style CLI
+	'
+}
+
+${scwryptsmodule}.parse.validate() {
+	KUBECLI="${ARGS[1]}"
+	ARGS=(${ARGS[@]:1})
+
+	[ ${KUBECLI} ] \
+		|| echo.error "missing argument for 'kubecli'"
+}

zsh/cloud/aws/eks/cli.test.zsh

@@ -0,0 +1,105 @@
+#####################################################################
+
+use unittest
+
+testmodule=cloud.aws.eks.cli
+
+#####################################################################
+
+beforeall() {
+	use cloud/aws/eks/cli
+	use cloud/aws/eks/cluster-login
+}
+
+beforeeach() {
+	unittest.mock cloud.aws.eks.cluster-login
+
+	_CLUSTER_NAME=$(uuidgen)
+
+	_AWS_ACCOUNT=$(uuidgen)
+	_AWS_PROFILE=$(uuidgen)
+	_AWS_REGION=$(uuidgen)
+
+	_KUBECLI=$(uuidgen)
+	_KUBECLI_ARGS=($(uuidgen) $(uuidgen) $(uuidgen))
+
+	unittest.mock.env AWS_ACCOUNT --value ${_AWS_ACCOUNT}
+	unittest.mock.env AWS_PROFILE --value ${_AWS_PROFILE}
+	unittest.mock.env AWS_REGION  --value ${_AWS_REGION}
+
+	_EXPECTED_KUBECONTEXT="arn:aws:eks:${_AWS_REGION}:${_AWS_ACCOUNT}:cluster/${_CLUSTER_NAME}"
+	_KUBECTL_KUBECONTEXTS="$(uuidgen)\n${_EXPECTED_KUBECONTEXT}\n$(uuidgen)"
+
+	_EXPECTED_AWS_ARGS=(
+		--account ${_AWS_ACCOUNT}
+		--region  ${_AWS_REGION}
+	)
+}
+
+aftereach() {
+	unset \
+		_CLUSTER_NAME \
+		_AWS_ACCOUNT _AWS_PROFILE _AWS_REGION \
+		_EXPECTED_AWS_ARGS \
+		;
+}
+
+mock.kubectl() {
+	unittest.mock kubectl --stdout "${_KUBECTL_KUBECONTEXTS}"
+}
+
+mock.kubecli() {
+	command -v ${_KUBECLI} &>/dev/null || ${_KUBECLI}() { true; }
+	unittest.mock ${_KUBECLI}
+}
+
+#####################################################################
+
+test.uses-correct-kubecli-args() {
+	mock.kubectl
+	mock.kubecli
+
+	${testmodule} --cluster-name ${_CLUSTER_NAME} ${_KUBECLI} ${_KUBECLI_ARGS[@]}
+
+	${_KUBECLI}.assert.callstack \
+		--context ${_EXPECTED_KUBECONTEXT} \
+		${_KUBECLI_ARGS[@]}
+		;
+}
+
+test.uses-correct-helm-args() {
+	_KUBECLI=helm
+
+	mock.kubectl
+	mock.kubecli
+
+	${testmodule} --cluster-name ${_CLUSTER_NAME} ${_KUBECLI} ${_KUBECLI_ARGS[@]}
+
+	${_KUBECLI}.assert.callstack \
+		--kube-context ${_EXPECTED_KUBECONTEXT} \
+		${_KUBECLI_ARGS[@]}
+		;
+}
+
+test.performs-login() {
+	_KUBECTL_KUBECONTEXTS="$(uuidgen)\n$(uuidgen)"
+
+	mock.kubectl
+	mock.kubecli
+
+	${testmodule} --cluster-name ${_CLUSTER_NAME} ${_KUBECLI} ${_KUBECLI_ARGS[@]}
+
+	cloud.aws.eks.cluster-login.assert.callstack \
+		${_EXPECTED_AWS_ARGS[@]} \
+		--cluster-name ${_CLUSTER_NAME} \
+		;
+}
+
+test.does-not-perform-login-if-already-logged-in() {
+	mock.kubectl
+	mock.kubecli
+
+	${testmodule} --cluster-name ${_CLUSTER_NAME} ${_KUBECLI} ${_KUBECLI_ARGS[@]}
+
+	cloud.aws.eks.cluster-login.assert.not.called
+}

zsh/cloud/aws/eks/cluster-login.module.zsh

@@ -0,0 +1,43 @@
+#####################################################################
+
+use cloud/aws/cli
+
+use cloud/aws/zshparse
+use cloud/aws/eks/zshparse
+
+#####################################################################
+
+${scwryptsmodule}() {
+	local DESCRIPTION='
+		Interactively sets the default kubeconfig to match the selected
+		cluster in EKS. Also creates the kubeconfig entry if it does not
+		already exist.
+	'
+	local PARSERS=(
+		cloud.aws.zshparse.overrides
+		cloud.aws.eks.zshparse.cluster-name
+	)
+
+	local EKS_CLUSTER_NAME_INTERACTIVE=allowed
+
+	eval "$(utils.parse.autosetup)"
+
+	#####################################################################
+
+	[ ${CLUSTER_NAME} ] || CLUSTER_NAME=$(\
+		${AWS} eks list-clusters \
+			| jq -r '.[] | .[]' \
+			| utils.fzf "select an eks cluster (${ACCOUNT}/${REGION})"
+	)
+
+	[ ${CLUSTER_NAME} ] || echo.error 'must select a valid cluster or use --cluster-name'
+
+	utils.check-errors || return $?
+
+	##########################################
+
+	echo.status 'updating kubeconfig for EKS cluster '${CLUSTER_NAME}''
+	${AWS} eks update-kubeconfig --name ${CLUSTER_NAME} \
+		&& echo.success "kubeconfig updated with '${CLUSTER_NAME}'" \
+		|| echo.error "failed to update kubeconfig; do you have permission to access '${CLUSTER_NAME}'?"
+}

zsh/cloud/aws/eks/cluster-login.test.zsh

@@ -0,0 +1,66 @@
+#####################################################################
+
+use unittest
+testmodule=cloud.aws.eks.cluster-login
+
+#####################################################################
+
+beforeall() {
+	use cloud/aws/eks/cluster-login
+}
+
+beforeeach() {
+	unittest.mock cloud.aws.cli
+
+	_CLUSTER_NAME=$(uuidgen)
+
+	_AWS_ACCOUNT=$(uuidgen)
+	_AWS_PROFILE=$(uuidgen)
+	_AWS_REGION=$(uuidgen)
+
+	unittest.mock.env AWS_ACCOUNT --value ${_AWS_ACCOUNT}
+	unittest.mock.env AWS_PROFILE --value ${_AWS_PROFILE}
+	unittest.mock.env AWS_REGION  --value ${_AWS_REGION}
+
+	_EXPECTED_AWS_ARGS=(
+		--account ${_AWS_ACCOUNT}
+		--region  ${_AWS_REGION}
+	)
+}
+
+aftereach() {
+	unset \
+		_CLUSTER_NAME \
+		_AWS_ACCOUNT _AWS_PROFILE _AWS_REGION \
+		_EXPECTED_AWS_ARGS \
+		;
+}
+
+#####################################################################
+
+test.login-to-correct-cluster() {
+	${testmodule} --cluster-name ${_CLUSTER_NAME}
+
+	cloud.aws.cli.assert.callstack \
+		${_EXPECTED_AWS_ARGS[@]} \
+		eks update-kubeconfig \
+		--name ${_CLUSTER_NAME} \
+		;
+}
+
+test.interactive-login-ignored-on-ci() {
+	${testmodule}
+	cloud.aws.cli.assert.not.called
+}
+
+test.interactive-login-to-correct-cluster() {
+	unittest.mock utils.fzf --stdout ${_CLUSTER_NAME}
+
+	${testmodule}
+
+	cloud.aws.cli.assert.callstack \
+		${_EXPECTED_AWS_ARGS[@]} \
+		eks update-kubeconfig \
+		--name ${_CLUSTER_NAME} \
+		;
+}

zsh/cloud/aws/eks/eks.module.zsh

@@ -0,0 +1,10 @@
+#
+# run kubectl/helm/etc commands on AWS Elastic Kubernetes Service (EKS)
+#
+
+# provides an EKS connection wrapper for any kubectl-like cli
+use cloud/aws/eks/cli
+eval "${scwryptsmodule}() { ${scwryptsmodule}.cli $@; }"
+
+# sets up kubeconfig to connect to EKS
+use cloud/aws/eks/cluster-login

zsh/cloud/aws/eks/eks.test.zsh

@@ -0,0 +1,24 @@
+#####################################################################
+
+use unittest
+testmodule=cloud.aws.eks
+
+#####################################################################
+
+beforeall() {
+	use cloud/aws
+}
+
+#####################################################################
+
+test.provides-eks-cli() {
+	unittest.test.provides ${testmodule}.cli
+}
+
+test.provides-eks-cli-alias() {
+	unittest.test.provides ${testmodule}
+}
+
+test.provides-cluster-login() {
+	unittest.test.provides ${testmodule}.cluster-login
+}

zsh/cloud/aws/eks/login

@@ -1,4 +1,4 @@
-#!/bin/zsh
+#!/usr/bin/env zsh
 use cloud/aws/eks
 #####################################################################
 

zsh/cloud/aws/eks/zshparse/cluster-name.module.zsh

@@ -0,0 +1,44 @@
+${scwryptsmodule}.locals() {
+	local CLUSTER_NAME
+
+	# set to 'allowed' to enable interactive cluster select
+	# by default, the '--cluster-name' flag is required
+	local EKS_CLUSTER_NAME_INTERACTIVE
+}
+
+${scwryptsmodule}() {
+	local PARSED=0
+
+	case $1 in
+		( -c | --cluster-name )
+			CLUSTER_NAME="$2"
+			((PARSED+=2))
+			;;
+	esac
+
+	return $PARSED
+}
+
+${scwryptsmodule}.usage() {
+	[[ "$USAGE__usage" =~ '\[...options...\]' ]] || USAGE__usage+=' [...options...]'
+
+	USAGE__options+="\n
+		-c, --cluster-name <string>   EKS cluster name identifier string
+	"
+}
+
+${scwryptsmodule}.validate() {
+	[ $CLUSTER_NAME ] && return 0
+
+	[[ $EKS_CLUSTER_NAME_INTERACTIVE =~ allowed ]] \
+		|| echo.error 'missing cluster name' \
+		|| return
+
+	CLUSTER_NAME=$(\
+		$AWS eks list-clusters \
+			| jq -r '.[] | .[]' \
+			| utils.fzf "select an eks cluster ($ACCOUNT/$REGION)" \
+	)
+
+	[ $CLUSTER_NAME ] || echo.error 'must select a valid cluster or use --cluster-name'
+}

zsh/cloud/aws/eks/zshparse/zshparse.module.zsh

@@ -0,0 +1,6 @@
+#
+# argument parsers for common EKS arguments
+#
+
+# get the EKS "ClusterName" identifier
+use cloud/aws/eks/zshparse/cluster-name

zsh/cloud/aws/eksctl/cli.module.zsh

@@ -0,0 +1,40 @@
+#####################################################################
+
+use cloud/aws/zshparse/overrides
+
+DEPENDENCIES+=(eksctl)
+
+#####################################################################
+
+${scwryptsmodule}() {
+	local PARSERS=(cloud.aws.zshparse.overrides)
+	local DESCRIPTION="
+		Context wrapper for eksctl commands; prevents accidental local environment
+		bleed-through, but otherwise works exactly like 'eksctl'.
+
+		This wrapper should be used in place of _all_ 'eksctl' usages within scwrypts.
+	"
+
+	eval "$(utils.parse.autosetup)"
+
+	##########################################
+
+	echo.debug "invoking '$(echo "$AWS_EVAL_PREFIX" | sed 's/AWS_\(ACCESS_KEY_ID\|SECRET_ACCESS_KEY\)=[^ ]\+ //g')eksctl ${ARGS[@]}'"
+	eval "${AWS_EVAL_PREFIX}eksctl ${ARGS[@]}"
+}
+
+#####################################################################
+
+${scwryptsmodule}.parse() {
+	return 0
+}
+
+${scwryptsmodule}.parse.locals() {
+	local ARGS=()
+}
+
+${scwryptsmodule}.parse.usage() {
+	USAGE__args+='
+		args   all remaining arguments are forwarded to eksctl
+	'
+}

zsh/cloud/aws/eksctl/cli.test.zsh

@@ -0,0 +1,72 @@
+#####################################################################
+
+use unittest
+testmodule=cloud.aws.eksctl.cli
+
+#####################################################################
+
+beforeall() {
+	use cloud/aws/eksctl/cli
+}
+
+beforeeach() {
+	unittest.mock eksctl
+	unittest.mock echo.debug
+
+	_ARGS=($(uuidgen) $(uuidgen) $(uuidgen))
+
+	_AWS_REGION=$(uuidgen)
+	_AWS_PROFILE=$(uuidgen)
+
+	unittest.mock.env AWS_ACCOUNT --value $(uuidgen)
+	unittest.mock.env AWS_PROFILE --value ${_AWS_PROFILE}
+	unittest.mock.env AWS_REGION  --value ${_AWS_REGION}
+}
+
+aftereach() {
+	unset _AWS_REGION
+	unset _AWS_PROFILE
+}
+
+#####################################################################
+
+test.forwards-arguments() {
+	${testmodule} ${_ARGS[@]}
+
+	eksctl.assert.callstack \
+		${_ARGS[@]} \
+		;
+}
+
+test.forwards-profile() {
+	#
+	# --profile is an invalid argument for eksctl, so it
+	# MUST be forwarded as AWS_PROFILE to prevent environment
+	# bleeding
+	#
+	${testmodule} ${_ARGS[@]}
+
+	echo.debug.assert.callstackincludes \
+		AWS_PROFILE=${OVERRIDE_REGION} \
+		;
+}
+
+test.overrides-region() {
+	local OVERRIDE_REGION=$(uuidgen)
+
+	${testmodule} --region ${OVERRIDE_REGION} ${_ARGS[@]}
+
+	echo.debug.assert.callstackincludes \
+		AWS_REGION=${OVERRIDE_REGION} \
+		;
+}
+
+test.overrides-account() {
+	local OVERRIDE_ACCOUNT=$(uuidgen)
+
+	${testmodule} --account ${OVERRIDE_ACCOUNT} ${_ARGS[@]}
+
+	echo.debug.assert.callstackincludes \
+		AWS_ACCOUNT=${OVERRIDE_ACCOUNT} \
+		;
+}

zsh/cloud/aws/eksctl/eksctl.module.zsh

@@ -0,0 +1,10 @@
+#
+# module for eksctl actions
+#
+
+# context wrapper for direct use of eksctl
+use cloud/aws/eksctl/cli
+eval "${scwryptsmodule}() { ${scwryptsmodule}.cli \$@; }"
+
+# argument helper for creating a standard iamserviceaccount
+use cloud/aws/eksctl/iamserviceaccount

zsh/cloud/aws/eksctl/eksctl.test.zsh

@@ -0,0 +1,20 @@
+#####################################################################
+
+use unittest
+testmodule=cloud.aws.eksctl
+
+#####################################################################
+
+beforeall() {
+	use cloud/aws/eksctl
+}
+
+#####################################################################
+
+test.provides-eksctl-cli() {
+	unittest.test.provides ${testmodule}.cli
+}
+
+test.provides-eksctl-alias() {
+	unittest.test.provides ${testmodule}
+}

zsh/cloud/aws/eksctl/iamserviceaccount/check-exists.module.zsh

@@ -0,0 +1,57 @@
+#####################################################################
+
+use cloud/aws/eks/cli
+
+use cloud/aws/eksctl/iamserviceaccount/zshparse
+use cloud/aws/zshparse/overrides
+
+DEPENDENCIES+=(kubectl yq)
+
+#####################################################################
+
+${scwryptsmodule}() {
+	local DESCRIPTION="
+		determine whether the target iamserviceaccount already
+		exists on Kubernetes
+
+		OK:
+		  exit code   0 : the serviceaccount exists on kubernetes
+		  exit code 100 : the serviceaccount does not exist on kubernetes
+
+		ERROR:
+		  exit code 200 : the serviceaccount exists on kubernetes, but does not match the target role
+	"
+
+	local PARSERS=(
+		cloud.aws.eksctl.iamserviceaccount.zshparse
+		cloud.aws.zshparse.overrides
+	)
+
+	eval "$(utils.parse.autosetup)"
+
+	##########################################
+
+	echo.status "checking for existing role-arn"
+	local CURRENT_ROLE_ARN=$(
+		cloud.aws.eks.cli kubectl ${AWS_PASSTHROUGH_ARGS[@]} --namespace "${NAMESPACE}" get serviceaccount "${SERVICEACCOUNT}" -o yaml \
+			| utils.yq -r '.metadata.annotations["eks.amazonaws.com/role-arn"]' \
+			| grep -v '^null$' \
+	)
+
+	[ "${CURRENT_ROLE_ARN}" ] || {
+		echo.status "serviceaccount does not exist or has no configured role"
+		return 100
+	}
+
+	[[ ${CURRENT_ROLE_ARN} =~ "${ROLE_NAME}$" ]] || {
+		echo.status "\
+			serviceaccount current role does not match desired role:
+			  CURRENT : ${CURRENT_ROLE_ARN}
+			  DESIRED : arn:aws:iam::${AWS_ACCOUNT}:role/${ROLE_NAME}
+		"
+		return 200
+	}
+
+	echo.status "serviceaccount current role matches desired role"
+	return 0
+}

zsh/cloud/aws/eksctl/iamserviceaccount/check-exists.test.zsh

@@ -0,0 +1,63 @@
+#####################################################################
+
+use unittest
+testmodule=cloud.aws.eksctl.iamserviceaccount.check-exists
+
+#####################################################################
+
+beforeall() {
+	use cloud/aws/eksctl/iamserviceaccount/check-exists
+	use cloud/aws/eks/cli
+}
+
+beforeeach() {
+	_SERVICEACCOUNT=$(uuidgen)
+	_NAMEPACE=$(uuidgen)
+	_ROLE_NAME=$(uuidgen)
+	_ROLE_ARN="$(uuidgen)/${_ROLE_NAME}"
+
+	unittest.mock.env AWS_ACCOUNT --value $(uuidgen)
+	unittest.mock.env AWS_PROFILE --value $(uuidgen)
+	unittest.mock.env AWS_REGION  --value $(uuidgen)
+
+	_ARGS=(
+		--serviceaccount ${_SERVICEACCOUNT}
+		--namespace ${_NAMEPACE}
+		--role-name ${_ROLE_NAME}
+	)
+}
+
+aftereach() {
+	unset _SERVICEACCOUNT _NAMESPACE _ROLE_NAME _ARGS
+}
+
+#####################################################################
+
+test.detects-exists() {
+	unittest.mock cloud.aws.eks.cli \
+		--stdout '{"metadata":{"annotations":{"eks.amazonaws.com/role-arn":"'$_ROLE_ARN'"}}}' \
+		;
+
+	${testmodule} ${_ARGS[@]}
+
+	[[ $? -eq 0 ]]
+}
+
+test.detects-not-exists() {
+	unittest.mock cloud.aws.eks.cli \
+		--stdout '{}'
+
+	${testmodule} ${_ARGS[@]}
+
+	[[ $? -eq 100 ]]
+}
+
+test.detects-exists-but-does-not-match() {
+	unittest.mock cloud.aws.eks.cli \
+		--stdout '{"metadata":{"annotations":{"eks.amazonaws.com/role-arn":"'$(uuidgen)'"}}}' \
+		;
+
+	${testmodule} ${_ARGS[@]}
+
+	[[ $? -eq 200 ]]
+}

zsh/cloud/aws/eksctl/iamserviceaccount/create.module.zsh

@@ -0,0 +1,93 @@
+#####################################################################
+
+use cloud/aws/eksctl/cli
+use cloud/aws/eksctl/iamserviceaccount/check-exists
+
+use cloud/aws/eksctl/iamserviceaccount/zshparse
+use cloud/aws/zshparse/overrides
+use cloud/aws/eks/zshparse/cluster-name
+
+#####################################################################
+
+${scwryptsmodule}() {
+	local DESCRIPTION="
+		creates an 'iamserviceaccount' which provides a Kubernetes
+		serviceaccount with AWS role identity and access control
+	"
+
+	local PARSERS=(
+		cloud.aws.eksctl.iamserviceaccount.zshparse
+		cloud.aws.zshparse.overrides
+		cloud.aws.eks.zshparse.cluster-name
+	)
+
+	eval "$(utils.parse.autosetup)"
+
+	##########################################
+
+	case ${FORCE} in
+		( true ) ;;
+		( false )
+			cloud.aws.eksctl.iamserviceaccount.check-exists \
+				--serviceaccount "${SERVICEACCOUNT}" \
+				--namespace      "${NAMESPACE}" \
+				--role-name      "${ROLE_NAME}" \
+				${AWS_PASSTHROUGH[@]} \
+				;
+			case $? in
+				(   0 ) echo.success "'${NAMESPACE}/${SERVICEACCOUNT}' already configured with '${ROLE_NAME}'"
+					return 0
+					;;
+				( 100 ) # role does not exist yet; continue with rollout
+					;;
+				( 200 ) echo.error "'${NAMESPACE}/${SERVICEACCOUNT}' has been configured with a different role than '${ROLE_NAME}'"
+					echo.reminder "must use --force flag to overwrite"
+					return 2
+					;;
+			esac
+			;;
+	esac
+
+	echo.status "creating iamserviceaccount" \
+		&& cloud.aws.eksctl.cli ${AWS_PASSTHROUGH_ARGS[@]} create iamserviceaccount \
+			--cluster   "${CLUSTER_NAME}" \
+			--namespace "${NAMESPACE}" \
+			--name      "${SERVICEACCOUNT}" \
+			--role-name "${ROLE_NAME}" \
+			--override-existing-serviceaccounts \
+			--approve \
+			${ARGS[@]} \
+		&& echo.success "successfully configured '${NAMESPACE}/${SERVICEACCOUNT}' with IAM role '${ROLE_NAME}'" \
+		|| echo.error   "unable to configure '${NAMESPACE}/${SERVICEACCOUNT}' with IAM role '${ROLE_NAME}'\n(check cloudformation dashboard for details)" \
+		;
+}
+
+#####################################################################
+
+${scwryptsmodule}.parse.locals() {
+	local FORCE=false   # whether or not to force a new eksctl deployment
+	local ARGS=()
+}
+
+${scwryptsmodule}.parse() {
+	local PARSED=0
+
+	case $1 in
+		--force ) PARSED=1; FORCE=true ;;
+	esac
+
+	return ${PARSED}
+}
+
+${scwryptsmodule}.parse.usage() {
+	USAGE__options+="
+		--force   don't check for existing serviceaccount and override any existing configuration
+	"
+
+	USAGE__args+="
+		args   all remaining arguments are forwarded to 'eksctl create iamserviceaccount'
+
+		eksctl create iamserviceaccount args:
+		$(eksctl create iamserviceaccount --help 2>&1 | grep -v -- '--name' | grep -v -- '--namespace' | grep -v -- '--role-name' | sed 's/^/  /')
+	"
+}

zsh/cloud/aws/eksctl/iamserviceaccount/create.test.zsh

@@ -0,0 +1,150 @@
+#####################################################################
+
+use unittest
+testmodule=cloud.aws.eksctl.iamserviceaccount.create
+
+#####################################################################
+
+beforeall() {
+	use cloud/aws/eksctl/iamserviceaccount/create
+}
+
+beforeeach() {
+	unittest.mock cloud.aws.eksctl.cli
+
+	_SERVICEACCOUNT=$(uuidgen)
+	_NAMESPACE=$(uuidgen)
+	_ROLE_NAME=$(uuidgen)
+	_ROLE_ARN="$(uuidgen)/${_ROLE_NAME}"
+
+	_CLUSTER_NAME=$(uuidgen)
+
+	_AWS_ACCOUNT=$(uuidgen)
+	_AWS_REGION=$(uuidgen)
+
+	unittest.mock.env AWS_ACCOUNT --value ${_AWS_ACCOUNT}
+	unittest.mock.env AWS_PROFILE --value $(uuidgen)
+	unittest.mock.env AWS_REGION  --value ${_AWS_REGION}
+
+	_IAMSERVICEACCOUNT_ARGS=(
+		--serviceaccount ${_SERVICEACCOUNT}
+		--namespace ${_NAMESPACE}
+		--role-name ${_ROLE_NAME}
+	)
+
+	_EXTRA_ARGS=($(uuidgen) $(uuidgen) $(uuidgen))
+
+	_ARGS=(
+		--cluster-name ${_CLUSTER_NAME}
+		${_IAMSERVICEACCOUNT_ARGS[@]}
+		--
+		${_EXTRA_ARGS[@]}
+	)
+
+	_EXPECTED_AWS_PASSTHROUGH=(
+		--account ${_AWS_ACCOUNT}
+		--region  ${_AWS_REGION}
+	)
+}
+
+aftereach() {
+	unset \
+		_SERVICEACCOUNT _NAMESPACE _ROLE_NAME \
+		_CLUSTER_NAME \
+		_AWS_ACCOUNT _AWS_REGION \
+		_ARGS _EXPECTED_AWS_PASSTHROUGH_ARGS \
+		;
+}
+
+#####################################################################
+
+test.performs-check-exists() {
+	unittest.mock cloud.aws.eksctl.iamserviceaccount.check-exists \
+		--exit-code 0 \
+		;
+
+	${testmodule} ${_ARGS[@]}
+
+	cloud.aws.eksctl.iamserviceaccount.check-exists.assert.callstack \
+		${_IAMSERVICEACCOUNT_ARGS[@]} \
+		${_EXPECTED_AWS_PASSTHROUGH[@]} \
+		;
+}
+
+test.ignores-check-exist-on-force() {
+	unittest.mock cloud.aws.eksctl.iamserviceaccount.check-exists \
+		--exit-code 0 \
+		;
+
+	${testmodule} ${_ARGS[@]} --force
+
+	cloud.aws.eksctl.iamserviceaccount.check-exists.assert.not.called
+}
+
+test.does-not-create-if-exists() {
+	unittest.mock cloud.aws.eksctl.iamserviceaccount.check-exists \
+		--exit-code 0 \
+		;
+
+	${testmodule} ${_ARGS[@]}
+
+	cloud.aws.eksctl.cli.assert.not.called
+}
+
+test.creates-role() {
+	unittest.mock cloud.aws.eksctl.iamserviceaccount.check-exists \
+		--exit-code 100 \
+		;
+
+	${testmodule} ${_ARGS[@]}
+
+	cloud.aws.eksctl.cli.assert.callstack \
+		create iamserviceaccount \
+		--cluster   ${_CLUSTER_NAME} \
+		--namespace ${_NAMESPACE} \
+		--name      ${_SERVICEACCOUNT} \
+		--role-name ${_ROLE_NAME} \
+		--override-existing-serviceaccounts \
+		--approve \
+		${_EXTRA_ARGS[@]} \
+		;
+}
+
+test.creates-role-on-force() {
+	unittest.mock cloud.aws.eksctl.iamserviceaccount.check-exists \
+		--exit-code 0 \
+		;
+
+	${testmodule} ${_ARGS[@]} --force
+
+	cloud.aws.eksctl.cli.assert.callstack \
+		create iamserviceaccount \
+		--cluster   ${_CLUSTER_NAME} \
+		--namespace ${_NAMESPACE} \
+		--name      ${_SERVICEACCOUNT} \
+		--role-name ${_ROLE_NAME} \
+		--override-existing-serviceaccounts \
+		--approve \
+		${_EXTRA_ARGS[@]} \
+		;
+}
+
+test.does-not-create-if-mismatched-role() {
+	unittest.mock cloud.aws.eksctl.iamserviceaccount.check-exists \
+		--exit-code 200 \
+		;
+
+	${testmodule} ${_ARGS[@]}
+
+	cloud.aws.eksctl.cli.assert.not.called
+}
+
+test.returns-correct-error-if-mismatched-role() {
+	unittest.mock cloud.aws.eksctl.iamserviceaccount.check-exists \
+		--exit-code 200 \
+		;
+
+	${testmodule} ${_ARGS[@]}
+
+	[[ $? -eq 2 ]]
+}

zsh/cloud/aws/eksctl/iamserviceaccount/iamserviceaccount.module.zsh

@@ -0,0 +1,9 @@
+#
+# build 'iamserviceaccount' to enable IAM identity / access control
+#
+
+# create the iamserviceaccount
+use cloud/aws/eksctl/iamserviceaccount/create
+
+# check whether the iamserviceaccount exists in kubernetes
+use cloud/aws/eksctl/iamserviceaccount/check-exists

zsh/cloud/aws/eksctl/iamserviceaccount/iamserviceaccount.test.zsh

@@ -0,0 +1,20 @@
+#####################################################################
+
+use unittest
+testmodule=cloud.aws.eksctl.iamserviceaccount
+
+#####################################################################
+
+beforeall() {
+	use cloud/aws/eksctl/iamserviceaccount
+}
+
+#####################################################################
+
+test.provides-create() {
+	unittest.test.provides ${testmodule}.create
+}
+
+test.provides-check-exists() {
+	unittest.test.provides ${testmodule}.check-exists
+}

zsh/cloud/aws/eksctl/iamserviceaccount/zshparse.module.zsh

@@ -0,0 +1,35 @@
+#####################################################################
+
+${scwryptsmodule}.locals() {
+	local SERVICEACCOUNT
+	local NAMESPACE
+	local ROLE_NAME
+}
+
+${scwryptsmodule}() {
+	local PARSED=0
+
+	case $1 in
+		( --serviceaccount ) PARSED=2; SERVICEACCOUNT=$2 ;;
+		( --namespace      ) PARSED=2; NAMESPACE=$2 ;;
+		( --role-name      ) PARSED=2; ROLE_NAME=$2 ;;
+	esac
+
+	return ${PARSED}
+}
+
+${scwryptsmodule}.usage() {
+	USAGE__options+="
+		--serviceaccount   (required) target k8s:ServiceAccount
+		--namespace        (required) target k8s:Namespace
+		--role-name        (required) name of the IAM role to assign
+	"
+}
+
+${scwryptsmodule}.validate() {
+	[ "${SERVICEACCOUNT}" ] || echo.error "--serviceaccount is required"
+	[ "${NAMESPACE}"      ] || echo.error "--namespace is required"
+	[ "${ROLE_NAME}"      ] || echo.error "--role-name is required"
+}
+
+#####################################################################

zsh/cloud/aws/rds/create-backup

@@ -1,4 +1,4 @@
-#!/bin/zsh
+#!/usr/bin/env zsh
 use cloud/aws/rds
 use db/postgres
 #####################################################################

zsh/cloud/aws/rds/interactive-login

@@ -1,4 +1,4 @@
-#!/bin/zsh
+#!/usr/bin/env zsh
 use cloud/aws/rds
 use db/postgres
 #####################################################################

zsh/cloud/aws/rds/load-backup

@@ -1,4 +1,4 @@
-#!/bin/zsh
+#!/usr/bin/env zsh
 use cloud/aws/rds
 use db/postgres
 #####################################################################

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

@@ -1,13 +1,7 @@
 #####################################################################
 
-DEPENDENCIES+=(
-	docker
-)
-
-REQUIRED_ENV+=(
-	AWS_ACCOUNT
-	AWS_REGION
-)
+DEPENDENCIES+=(docker)
+REQUIRED_ENV+=(AWS_ACCOUNT AWS_REGION)
 
 use cloud/aws/cli
 
@@ -15,13 +9,13 @@ use cloud/aws/cli
 
 RDS__SELECT_DATABASE() {
 	local DATABASES=$(_RDS__GET_AVAILABLE_DATABASES)
-	[ ! $DATABASES ] && FAIL 1 'no databases available'
+	[ ! $DATABASES ] && utils.fail 1 'no databases available'
 
 	local ID=$(\
 		echo $DATABASES | jq -r '.instance + " @ " + .cluster' \
-			| FZF 'select a database (instance@cluster)' \
+			| utils.fzf 'select a database (instance@cluster)' \
 	)
-	[ ! $ID ] && ABORT
+	[ ! $ID ] && user.abort
 
 	local INSTANCE=$(echo $ID | sed 's/ @ .*$//')
 	local CLUSTER=$(echo $ID  | sed 's/^.* @ //')
@@ -49,24 +43,24 @@ RDS__GET_DATABASE_CREDENTIALS() {
 	while [[ $# -gt 0 ]]
 	do
 		case $1 in
-			--print-password ) PRINT_PASSWORD=1 ;;
-			* )
-				WARNING "unrecognized argument $1"
+			( --print-password ) PRINT_PASSWORD=1 ;;
+			( * )
+				echo.warning "unrecognized argument $1"
 				ERRORS+=1
 				;;
 		esac
 		shift 1
 	done
 
-	CHECK_ERRORS
+	utils.check-errors --fail
 
 	##########################################
 
 	local DATABASE=$(RDS__SELECT_DATABASE)
-	[ ! $DATABASE ] && ABORT
+	[ ! $DATABASE ] && user.abort
 
 	DB_HOST="$(echo $DATABASE | jq -r '.host')"
-	[ ! $DB_HOST ] && { ERROR 'unable to find host'; return 2; }
+	[ ! $DB_HOST ] && { echo.error 'unable to find host'; return 2; }
 
 	DB_PORT="$(echo $DATABASE | jq -r '.port')"
 	[ ! $DB_PORT ] && DB_PORT=5432
@@ -76,17 +70,17 @@ RDS__GET_DATABASE_CREDENTIALS() {
 
 	local AUTH_METHOD=$(\
 		echo "iam\nsecretsmanager\nuser-input" \
-			| FZF 'select an authentication method' \
+			| utils.fzf 'select an authentication method' \
 	)
-	[ ! $AUTH_METHOD ] && ABORT
+	[ ! $AUTH_METHOD ] && user.abort
 
 	case $AUTH_METHOD in
-		iam            ) _RDS_AUTH__iam ;;
-		secretsmanager ) _RDS_AUTH__secretsmanager ;;
-		user-input     ) _RDS_AUTH__userinput ;;
+		( iam            ) _RDS_AUTH__iam ;;
+		( secretsmanager ) _RDS_AUTH__secretsmanager ;;
+		( user-input     ) _RDS_AUTH__userinput ;;
 	esac
 
-	[[ $PRINT_PASSWORD -eq 1 ]] && DEBUG "password : $DB_PASS"
+	[[ $PRINT_PASSWORD -eq 1 ]] && echo.debug "password : $DB_PASS"
 
 	return 0
 }
@@ -104,19 +98,19 @@ _RDS_AUTH__secretsmanager() {
 	local CREDENTIALS=$(_RDS__GET_SECRETSMANAGER_CREDENTIALS)
 	echo $CREDENTIALS | jq -e '.pass' >/dev/null 2>&1 \
 		&& DB_PASS="$(echo $CREDENTIALS | jq -r '.pass')"
-	
+
 	echo $CREDENTIALS | jq -e '.password' >/dev/null 2>&1 \
 		&& DB_PASS="$(echo $CREDENTIALS | jq -r '.password')"
-	
+
 	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')
 }
@@ -125,7 +119,7 @@ _RDS__GET_SECRETSMANAGER_CREDENTIALS() {
 	local ID=$(\
 		AWS secretsmanager list-secrets \
 			| jq -r '.[] | .[] | .Name' \
-			| FZF 'select a secret' \
+			| utils.fzf 'select a secret' \
 	)
 	[ ! $ID ] && return 1
 

zsh/cloud/aws/route53/backup

@@ -1,33 +1,30 @@
-#!/bin/zsh
+#!/usr/bin/env zsh
 DEPENDENCIES+=(cli53)
-REQUIRED_ENV+=(AWS_PROFILE)
+REQUIRED_ENV+=(AWS_PROFILE AWS_ACCOUNT)
 #####################################################################
 
+utils.cli53() {
+	AWS_ACCOUNT=${AWS_ACCOUNT} \
+		cli53 --profile ${AWS_PROFILE} $@;
+}
+
 MAIN() {
-	local BACKUP_PATH="$SCWRYPTS_OUTPUT_PATH/$ENV_NAME/aws-dns-backup/$(date '+%Y-%m-%d')"
-	mkdir -p $BACKUP_PATH >/dev/null 2>&1
+	local BACKUP_BASE_PATH="${SCWRYPTS_DATA_PATH}/route53-backup/${SCWRYPTS_ENV}"
 
 	local DOMAIN
 	local JOBS=()
-	for DOMAIN in $(ROUTE53_GET_DOMAINS)
+	for DOMAIN in $(utils.cli53 list | awk '{print $2;}' | sed '1d; s/\.$//')
 	do
-		( STATUS "creating '$BACKUP_PATH/$DOMAIN.txt'" \
-			&& cli53 export --profile $AWS_PROFILE $DOMAIN > "$BACKUP_PATH/$DOMAIN.txt" \
-			&& SUCCESS "backed up '$DOMAIN'" \
-			|| ERROR "failed to back up '$DOMAIN'" \
+		(
+			utils.cli53 export ${DOMAIN} > "${BACKUP_BASE_PATH}/${DOMAIN}/$(date '+%Y-%m-%d_%H%M').cli53.txt" \
+				&& echo.success "backed up '${DOMAIN}'" \
+				|| echo.error "failed to back up '${DOMAIN}'" \
 		) &
 		JOBS+=$!
 	done
 
 	local P
-	for P in ${JOBS[@]}; do wait $P >/dev/null 2>&1; done
-}
+	for P in ${JOBS[@]}; do wait ${P} &>/dev/null; done
 
-#####################################################################
-
-ROUTE53_GET_DOMAINS() {
-	cli53 list --profile $AWS_PROFILE \
-		| awk '{print $2;}' \
-		| sed '1d; s/\.$//'\
-		;
+	echo.reminder "successful backups can be found in '${BACKUP_BASE_PATH}'"
 }

zsh/cloud/aws/zshparse/overrides.module.zsh

@@ -0,0 +1,79 @@
+${scwryptsmodule}.locals() {
+	local ACCOUNT   # parsed/configured AWS_ACCOUNT (use this instead of the env var!)
+	local REGION    # parsed/configured AWS_REGION (use this instead of the env var!)
+
+	local AWS_PASSTHROUGH=()   # used to forward parsed overrides to cloud.aws.cli calls (e.g. 'cloud.aws.cli ${AWS_PASSTHROUGH[@]} your command')
+	local AWS=()               # used to forward parsed overrides to cloud.aws.cli calls (e.g. '$AWS your command')
+
+	# should only be used by cloud/aws/cli
+	local AWS_EVAL_PREFIX
+	local AWS_CONTEXT_ARGS=()
+}
+
+${scwryptsmodule}() {
+	local PARSED=0
+
+	case $1 in
+		( --account ) PARSED+=2; ACCOUNT=$2 ;;
+		( --region  ) PARSED+=2; REGION=$2  ;;
+	esac
+
+	return $PARSED
+}
+
+${scwryptsmodule}.usage() {
+	[[ "$USAGE__usage" =~ ' \[...options...\]' ]] || USAGE__usage+=' [...options...]'
+
+	USAGE__options+="\n
+		--account   overrides required AWS_ACCOUNT scwrypts env value
+		--region    overrides required AWS_REGION  scwrypts env value
+	"
+}
+
+
+${scwryptsmodule}.validate() {
+	AWS_CONTEXT_ARGS=(--output json)
+
+	[ $ACCOUNT ] || { utils.environment.check AWS_ACCOUNT &>/dev/null && ACCOUNT=$AWS_ACCOUNT; }
+	[ $ACCOUNT ] \
+		&& AWS_EVAL_PREFIX+="AWS_ACCOUNT=$ACCOUNT " \
+		&& AWS_PASSTHROUGH+=(--account $ACCOUNT) \
+		|| echo.error "missing either --account or AWS_ACCOUNT" \
+		;
+
+	[ $REGION ] || { utils.environment.check AWS_REGION &>/dev/null && REGION=$AWS_REGION; }
+	[ $REGION ] \
+		&& AWS_EVAL_PREFIX+="AWS_REGION=$REGION AWS_DEFAULT_REGION=$REGION " \
+		&& AWS_CONTEXT_ARGS+=(--region $REGION) \
+		&& AWS_PASSTHROUGH+=(--region $REGION) \
+		|| echo.error "missing either --region  or AWS_REGION" \
+		;
+
+	utils.environment.check AWS_PROFILE &>/dev/null
+	[ $AWS_PROFILE ] \
+		&& AWS_EVAL_PREFIX+="AWS_PROFILE=$AWS_PROFILE " \
+		&& AWS_CONTEXT_ARGS+=(--profile $AWS_PROFILE) \
+		;
+
+	AWS=(cloud.aws.cli ${AWS_PASSTHROUGH[@]})
+
+	[ ! $CI ] && {
+		# non-CI must use PROFILE authentication
+		[ $AWS_PROFILE ] || echo.error "missing either --profile or AWS_PROFILE";
+
+		[[ $AWS_PROFILE =~ ^default$ ]] \
+			&& echo.warning "it is HIGHLY recommended to NOT use the 'default' profile for aws operations\nconsider using '$USER.$SCWRYPTS_ENV' instead"
+	}
+
+	[ $CI ] && {
+		# CI can use 'profile' or envvar 'access key' authentication
+		[ $AWS_PROFILE ] && return 0  # 'profile' preferred
+
+		[ $AWS_ACCESS_KEY_ID ] && [ $AWS_SECRET_ACCESS_KEY ] \
+			&& AWS_EVAL_PREFIX+="AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID " \
+			&& AWS_EVAL_PREFIX+="AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY " \
+			&& return 0
+
+		echo.error "running in CI, but missing both profile and access-key configuration\n(one AWS authentication method *must* be used)"
+	}
+}

zsh/cloud/aws/zshparse/zshparse.module.zsh

@@ -0,0 +1,6 @@
+#
+# argument parsers for common AWS-CLI arguments
+#
+
+# load/override AWS_* variables
+use cloud/aws/zshparse/overrides

zsh/cloud/media-sync/pull

@@ -1,7 +0,0 @@
-#!/bin/zsh
-use cloud/media-sync
-#####################################################################
-
-MAIN() {
-	MEDIA_SYNC__PULL $@
-}

zsh/cloud/media-sync/push

@@ -1,7 +0,0 @@
-#!/bin/zsh
-use cloud/media-sync
-#####################################################################
-
-MAIN() {
-	MEDIA_SYNC__PUSH $@
-}

zsh/config.global.zsh

@@ -0,0 +1,9 @@
+scwrypts.config() {
+	[ $1 ] || return 1
+
+	case $1 in
+		( python.versions ) echo "3.13\n3.12\n3.11\n3.10" ;;
+		( nodejs.version  ) echo "22.0.0" ;;
+		( * ) return 1 ;;
+	esac
+}

zsh/config.zsh

@@ -0,0 +1,183 @@
+#####################################################################
+### preflight config validation #####################################
+#####################################################################
+
+[[ ${__SCWRYPT} -eq 1 ]] && return 0  # avoid config reload if already active
+
+# Apparently MacOS puts ALL of the homebrew stuff inside of a top level git repository
+# with bizarre git ignores; so:
+#  - USE the git root if it's a manual install...
+#  - UNLESS that git root is just the $(brew --prefix)
+__SCWRYPTS_ROOT="$(cd -- "${0:a:h}"; git rev-parse --show-toplevel 2>/dev/null | grep -v "^$(brew --prefix 2>/dev/null)$")"
+
+[ ${__SCWRYPTS_ROOT} ] && [ -d "${__SCWRYPTS_ROOT}" ] \
+	|| __SCWRYPTS_ROOT="$(echo "${0:a:h}" | sed -n 's|\(share/scwrypts\).*$|\1|p')"
+
+[ ${__SCWRYPTS_ROOT} ] && [ -d "${__SCWRYPTS_ROOT}" ] || {
+	echo "cannot determine scwrypts root path for current installation; aborting"
+	exit 1
+}
+
+[ -f "${__SCWRYPTS_ROOT}/MANAGED_BY" ] \
+	&& readonly SCWRYPTS_INSTALLATION_TYPE=$(cat "${__SCWRYPTS_ROOT}/MANAGED_BY") \
+	|| readonly SCWRYPTS_INSTALLATION_TYPE=manual \
+	;
+
+#####################################################################
+
+#
+# this is like a manual "use" invocation, but the import driver relies
+# on this file, so here we go ahead and do it by hand once
+#
+# equivalent to "use utils"
+# (which is unnecessary since utils are ALWAYS loaded with import.driver.zsh)
+#
+# normally more logic is necessary for "use", but utils.module.zsh is a
+# special module which supports direct-sourcing from any zsh environment
+#
+source "${__SCWRYPTS_ROOT}/zsh/utils/utils.module.zsh"
+SCWRYPTS_LIBRARY_LOADED__scwrypts__utils=true
+
+#####################################################################
+### scwrypts global configuration ###################################
+#####################################################################
+
+readonly SCWRYPTS_CONFIG_PATH="${XDG_CONFIG_HOME:-${HOME}/.config}/scwrypts"
+readonly SCWRYPTS_ENV_PATH="${SCWRYPTS_CONFIG_PATH}/environments"
+
+readonly SCWRYPTS_DATA_PATH="${XDG_DATA_HOME:-${HOME}/.local/share}/scwrypts"
+
+readonly SCWRYPTS_STATE_PATH="${XDG_STATE_HOME:-${HOME}/.local/state}/scwrypts"
+readonly SCWRYPTS_LOG_PATH="${SCWRYPTS_STATE_PATH}/logs"
+
+[ -d /tmp ] \
+	&& readonly SCWRYPTS_TEMP_PATH="/tmp/scwrypts/${SCWRYPTS_RUNTIME_ID}" \
+	|| readonly SCWRYPTS_TEMP_PATH="${XDG_RUNTIME_DIR:-/run/user/${UID}}/scwrypts/${SCWRYPTS_RUNTIME_ID}" \
+	;
+
+mkdir -p \
+	"${SCWRYPTS_ENV_PATH}" \
+	"${SCWRYPTS_LOG_PATH}" \
+	"${SCWRYPTS_TEMP_PATH}" \
+	;
+
+DEFAULT_CONFIG="${__SCWRYPTS_ROOT}/zsh/config.user.zsh"
+source "${DEFAULT_CONFIG}"
+
+USER_CONFIG_OVERRIDES="${SCWRYPTS_CONFIG_PATH}/config.zsh"
+
+[ ! -f "${USER_CONFIG_OVERRIDES}" ] && {
+	mkdir -p $(dirname "${USER_CONFIG_OVERRIDES}")
+	cp "${DEFAULT_CONFIG}" "${USER_CONFIG_OVERRIDES}"
+}
+
+source "${USER_CONFIG_OVERRIDES}"
+source "${__SCWRYPTS_ROOT}/zsh/config.global.zsh"
+
+#####################################################################
+### load groups and plugins #########################################
+#####################################################################
+
+SCWRYPTS_GROUPS=()
+
+command -v echo.warning &>/dev/null || WARNING() { echo "echo.warning : $@" >&2; }
+command -v echo.error   &>/dev/null || ERROR()   { echo "echo.error   : $@" >&2; return 1; }
+command -v utils.fail    &>/dev/null || FAIL()    { echo.error "${@:2}"; exit $1; }
+
+__SCWRYPTS_GROUP_LOADERS=(
+	"${__SCWRYPTS_ROOT}/scwrypts.scwrypts.zsh"
+)
+
+[ "${GITHUB_WORKSPACE}" ] && [ ! "${SCWRYPTS_GITHUB_NO_AUTOLOAD}" ] && {
+	SCWRYPTS_GROUP_DIRS+=("${GITHUB_WORKSPACE}")
+}
+
+for __SCWRYPTS_GROUP_DIR in ${SCWRYPTS_GROUP_DIRS[@]}
+do
+	[ -d "${__SCWRYPTS_GROUP_DIR}" ] || continue
+	for __SCWRYPTS_GROUP_LOADER in $(find "${__SCWRYPTS_GROUP_DIR}" -type f -name \*scwrypts.zsh)
+	do
+		__SCWRYPTS_GROUP_LOADERS+=("${__SCWRYPTS_GROUP_LOADER}")
+	done
+done
+
+scwrypts.config.group() {
+	local GROUP_NAME="$1"
+	local CONFIG_KEY="$2"
+
+	[ "$GROUP_NAME" ] && [ "$CONFIG_KEY" ] \
+		|| return 1
+
+	echo ${(P)$(echo SCWRYPTS_GROUP_CONFIGURATION__${GROUP_NAME}__${CONFIG_KEY})}
+}
+
+for __SCWRYPTS_GROUP_LOADER in ${__SCWRYPTS_GROUP_LOADERS}
+do
+	__SCWRYPTS_GROUP_LOADER_REALPATH="$(readlink -f -- "${__SCWRYPTS_GROUP_LOADER}")"
+
+	[ -f "${__SCWRYPTS_GROUP_LOADER_REALPATH}" ] || {
+		echo.warning "error loading group '${__SCWRYPTS_GROUP_LOADER}': cannot read file"
+		continue
+	}
+
+	__SCWRYPTS_GROUP_NAME="$(\
+		basename -- "${__SCWRYPTS_GROUP_LOADER_REALPATH}" \
+			| sed -n 's/^\([a-z][a-z0-9_]*[a-z0-9]\).scwrypts.zsh$/\1/p' \
+	)"
+
+	[ "$__SCWRYPTS_GROUP_NAME" ] || {
+		echo.warning "unable to load group '${__SCWRYPTS_GROUP_LOADER_REALPATH}': invalid group name" >&2
+		continue
+	}
+
+	[[ $(scwrypts.config.group "$__SCWRYPTS_GROUP_NAME" loaded) =~ true ]] && {
+		echo.warning "unable to load group '${__SCWRYPTS_GROUP_NAME}': duplicate name"
+		continue
+	}
+
+	scwryptsgroup="SCWRYPTS_GROUP_CONFIGURATION__${__SCWRYPTS_GROUP_NAME}"
+	scwryptsgrouproot="$(dirname -- "${__SCWRYPTS_GROUP_LOADER_REALPATH}")"
+
+	: \
+		&& readonly ${scwryptsgroup}__root="${scwryptsgrouproot}" \
+		&& source "${__SCWRYPTS_GROUP_LOADER_REALPATH}" \
+		&& SCWRYPTS_GROUPS+=(${__SCWRYPTS_GROUP_NAME}) \
+		&& readonly ${scwryptsgroup}__loaded=true \
+		|| echo.warning "error encountered when loading group '${__SCWRYPTS_GROUP_NAME}'" \
+		;
+
+	[[ ! ${__SCWRYPTS_GROUP_NAME} =~ ^scwrypts$ ]] && [ ! "$(scwrypts.config.group ${__SCWRYPTS_GROUP_NAME} zshlibrary)" ] && {
+		case $(scwrypts.config.group ${__SCWRYPTS_GROUP_NAME} type) in
+			( zsh )
+				[ -d "${scwryptsgrouproot}/lib" ] \
+					&& readonly ${scwryptsgroup}__zshlibrary="${scwryptsgrouproot}/lib" \
+					|| readonly ${scwryptsgroup}__zshlibrary="${scwryptsgrouproot}" \
+					;
+				;;
+			( '' )
+				[ -d "${scwryptsgrouproot}/zsh/lib" ] \
+					&& readonly ${scwryptsgroup}__zshlibrary="${scwryptsgrouproot}/zsh/lib" \
+					|| readonly ${scwryptsgroup}__zshlibrary="${scwryptsgrouproot}/zsh" \
+					;
+				;;
+		esac
+	}
+done
+
+[[ ${SCWRYPTS_GROUPS[1]} =~ ^scwrypts$ ]] \
+	|| utils.fail 69 "encountered error when loading essential group 'scwrypts'; aborting"
+
+#####################################################################
+### cleanup #########################################################
+#####################################################################
+
+unset __SCWRYPTS_ROOT  # you should now use '$(scwrypts.config.group scwrypts root)'
+
+unset \
+	__SCWRYPTS_GROUP_LOADER __SCWRYPTS_GROUP_LOADERS __SCWRYPTS_GROUP_LOADER_REALPATH \
+	__SCWRYPTS_GROUP_DIR SCWRYPTS_GROUP_DIRS \
+	__SCWRYPTS_GROUP_NAME \
+	scwryptsgroup scwryptsgrouproot \
+	;
+
+__SCWRYPT=1  # arbitrary; indicates currently inside a scwrypt

zsh/db/postgres/interactive-pgcli

@@ -1,4 +1,4 @@
-#!/bin/zsh
+#!/usr/bin/env zsh
 use db/postgres
 #####################################################################
 

zsh/db/postgres/pg_dump

@@ -1,4 +1,4 @@
-#!/bin/zsh
+#!/usr/bin/env zsh
 use db/postgres
 #####################################################################
 

zsh/db/postgres/pg_restore

@@ -1,4 +1,4 @@
-#!/bin/zsh
+#!/usr/bin/env zsh
 use db/postgres
 #####################################################################
 

zsh/db/postgres/postgres.module.zsh

@@ -25,7 +25,7 @@ PG_DUMP() {
 
 
 
-	STATUS "
+	echo.status "
 	making backup of : $DB_USER@$DB_HOST:$DB_PORT/$DB_NAME
 
 	    (compressed) : '$OUTPUT_FILE.dump'
@@ -34,21 +34,21 @@ PG_DUMP() {
 	"
 
 	: \
-		&& STATUS "creating compressed backup..." \
+		&& echo.status "creating compressed backup..." \
 		&& eval PGPASSWORD=$(printf '%q ' "$DB_PASS") psql ${PSQL_ARGS[@]} \
 			--format custom \
 			--file "$OUTPUT_FILE.dump" \
 			--verbose \
-		&& SUCCESS "completed compressed backup" \
-		&& STATUS "creating raw backup..." \
+		&& echo.success "completed compressed backup" \
+		&& echo.status "creating raw backup..." \
 		&& pg_restore -f "$OUTPUT_FILE.raw.sql" "$OUTPUT_FILE.dump" \
-		&& SUCCESS "completed raw backup" \
-		&& STATUS "creating single-transaction raw backup..." \
+		&& echo.success "completed raw backup" \
+		&& echo.status "creating single-transaction raw backup..." \
 		&& { echo "BEGIN;\n"; cat "$OUTPUT_FILE.raw.sql"; echo "\nEND;" } > "$OUTPUT_FILE.sql" \
-		&& SUCCESS "completed single-transaction raw backup" \
-		|| { ERROR "error creating backup for '$DB_HOST/$DB_NAME' (see above)"; return 1; }
+		&& echo.success "completed single-transaction raw backup" \
+		|| { echo.error "error creating backup for '$DB_HOST/$DB_NAME' (see above)"; return 1; }
 
-	SUCCESS "
+	echo.success "
 	completed backup : $DB_USER@$DB_HOST:$DB_PORT/$DB_NAME
 
 	    (compressed) : '$OUTPUT_FILE.dump'
@@ -64,11 +64,11 @@ PG_RESTORE() {
 	local FILE
 	POSTGRES__SET_LOGIN_ARGS $@
 
-	local INPUT_FILE=$(find "$DATA_DIR"/backup.* -type f | FZF 'select database file to restore')
+	local INPUT_FILE=$(find "$DATA_DIR"/backup.* -type f | utils.fzf 'select database file to restore')
 
 	[ $INPUT_FILE ] && [ -f "$INPUT_FILE" ] || {
-		ERROR 'no file selected or missing backup file; aborting'
-		REMINDER "
+		echo.error 'no file selected or missing backup file; aborting'
+		echo.reminder "
 			backups must be *.sql or *.dump files starting with the prefix 'backup.'
 			in the following directory:
 
@@ -80,7 +80,7 @@ PG_RESTORE() {
 	local RAW=1
 	[[ $INPUT_FILE =~ \\.dump$ ]] && RAW=0
 
-	STATUS "
+	echo.status "
 	loading backup for : $DB_USER@$DB_HOST:$DB_PORT/$DB_NAME
 
 	              file : '$INPUT_FILE'
@@ -88,13 +88,13 @@ PG_RESTORE() {
 
 	local EXIT_CODE
 	[[ $RAW -eq 1 ]] && {
-		REMINDER "
+		echo.reminder "
 			loading a backup from a raw sql dump may result in data loss
 
 			make sure your database is ready to accept the database file!
 		"
 
-		yN 'continue?' || ABORT
+		yN 'continue?' || user.abort
 
 		PSQL < "$INPUT_FILE"
 		EXIT_CODE=$?
@@ -110,8 +110,8 @@ PG_RESTORE() {
 	}
 
 	[[ $EXIT_CODE -eq 0 ]] \
-		&& SUCCESS "finished restoring backup for '$DB_HOST/$DB_NAME'" \
-		|| ERROR "error restoring backup for '$DB_HOST/$DB_NAME' (see above)" \
+		&& echo.success "finished restoring backup for '$DB_HOST/$DB_NAME'" \
+		|| echo.error "error restoring backup for '$DB_HOST/$DB_NAME' (see above)" \
 		;
 
 	return $EXIT_CODE
@@ -120,14 +120,14 @@ PG_RESTORE() {
 #####################################################################
 
 POSTGRES__LOGIN_INTERACTIVE() {
-	DEPENDENCIES=(pgcli) CHECK_ENVIRONMENT --optional \
+	utils.dependencies.check pgcli --optional \
 		&& COMMAND=pgcli || COMMAND=psql
 
-	[[ $COMMAND =~ psql ]] && WARNING "using 'psql' instead"
+	[[ $COMMAND =~ psql ]] && echo.warning "using 'psql' instead"
 
 	POSTGRES__SET_LOGIN_ARGS $@
 
-	STATUS "
+	echo.status "
 	performing login  : $DB_USER@$DB_HOST:$DB_PORT/$DB_NAME
 	working directory : $DATA_DIR
 	 "
@@ -146,25 +146,25 @@ POSTGRES__SET_LOGIN_ARGS() {
 	while [[ $# -gt 0 ]]
 	do
 		case $1 in
-			-h | --host ) DB_HOST="$2"; shift 1 ;;
-			-p | --port ) DB_PORT="$2"; shift 1 ;;
-			-d | --name ) DB_NAME="$2"; shift 1 ;;
-			-U | --user ) DB_USER="$2"; shift 1 ;;
-			-P | --pass ) DB_PASS="$2"; shift 1 ;;
+			( -h | --host ) DB_HOST="$2"; shift 1 ;;
+			( -p | --port ) DB_PORT="$2"; shift 1 ;;
+			( -d | --name ) DB_NAME="$2"; shift 1 ;;
+			( -U | --user ) DB_USER="$2"; shift 1 ;;
+			( -P | --pass ) DB_PASS="$2"; shift 1 ;;
 
-			--file  ) PSQL_FILE="$2";  shift 1 ;;
+			( --file  ) PSQL_FILE="$2";  shift 1 ;;
 
-			--data-dir-prefix ) DATA_DIR_PREFIX="$2"; shift 1 ;;
+			( --data-dir-prefix ) DATA_DIR_PREFIX="$2"; shift 1 ;;
 
-			* ) PSQL_ARGS+=($1) ;;
+			( * ) PSQL_ARGS+=($1) ;;
 		esac
 		shift 1
 	done
 
 	[ $PSQL_FILE ] && [ ! -f "$PSQL_FILE" ] \
-		&& ERROR "no such file available:\n'$PSQL_FILE'"
+		&& echo.error "no such file available:\n'$PSQL_FILE'"
 
-	CHECK_ERRORS
+	utils.check-errors --fail
 
 	##########################################
 

zsh/db/postgres/run-sql

@@ -1,9 +1,9 @@
-#!/bin/zsh
+#!/usr/bin/env zsh
 use db/postgres
 #####################################################################
 
 MAIN() {
-	WARNING " \nthis function is in a beta state\n "
+	echo.warning " \nthis function is in a beta state\n "
 	local _PASS _ARGS=()
 	POSTGRES__SET_LOGIN_ARGS $@
 
@@ -15,27 +15,27 @@ MAIN() {
 	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/'"
+		echo.error "you haven't made any SQL commands yet"
+		echo.reminder "add '.sql' files here: '$SQL_DIR/'"
 		return 1
 	}
 
-	[ ! $INPUT_FILE ] && INPUT_FILE=$(FZF 'select a sql file to run')
-	[ ! $INPUT_FILE ] && ABORT
+	[ ! $INPUT_FILE ] && INPUT_FILE=$(utils.fzf 'select a sql file to run')
+	[ ! $INPUT_FILE ] && user.abort
 
-	[ ! -f "$INPUT_FILE" ] && FAIL 2 "no such sql file '$SQL_DIR/$INPUT_FILE'"
+	[ ! -f "$INPUT_FILE" ] && utils.fail 2 "no such sql file '$SQL_DIR/$INPUT_FILE'"
 
-	STATUS "loading '$INPUT_FILE' preview..."
+	echo.status "loading '$INPUT_FILE' preview..."
 	LESS "$INPUT_FILE"
 
-	STATUS "login   : $_USER@$_HOST:$_PORT/$_NAME"
-	STATUS "command : '$INPUT_FILE'"
+	echo.status "login   : $_USER@$_HOST:$_PORT/$_NAME"
+	echo.status "command : '$INPUT_FILE'"
 
-	yN 'run this command?' || ABORT
+	yN 'run this command?' || user.abort
 
-	STATUS "running '$INPUT_FILE'"
+	echo.status "running '$INPUT_FILE'"
 
 	PSQL < $INPUT_FILE \
-		&& SUCCESS "finished running '$INPUT_FILE'" \
-		|| FAIL 3 "something went wrong running '$INPUT_FILE' (see above)"
+		&& echo.success "finished running '$INPUT_FILE'" \
+		|| utils.fail 3 "something went wrong running '$INPUT_FILE' (see above)"
 }

zsh/docker/cleanup

@@ -1,13 +1,29 @@
-#!/bin/zsh
+#!/usr/bin/env zsh
 DEPENDENCIES+=(docker)
 #####################################################################
 
 MAIN() {
-	WARNING 'this will prune all docker resources from the current machine'
-	WARNING 'pruned resources are PERMANENTLY DELETED'
-	yN 'continue?' || return 1
+	local RESOURCES=(
+		container
+		image
+		volume
+		system
+		)
 
-	SUCCESS "CONTAINER : $(docker container prune -f 2>/dev/null | tail -n 1)"
-	SUCCESS "IMAGE     : $(docker image prune -f 2>/dev/null | tail -n 1)"
-	SUCCESS "VOLUME    : $(docker volume prune -f 2>/dev/null | tail -n 1)"
+	echo.warning "
+		this will prune the following docker resources from the
+		current machine:
+		   (${RESOURCES[@]})
+
+		pruned resources are PERMANENTLY DELETED
+	 "
+
+	utils.yN 'continue?' || utils.abort
+
+	echo.success "$(
+		for RESOURCE in ${RESOURCES[@]}
+		do
+			echo "${RESOURCE}^:^$(docker ${RESOURCE} prune -f 2>/dev/null | tail -n 1)"
+		done | column -ts '^'
+	)"
 }

zsh/hello-world

@@ -1,6 +1,6 @@
-#!/bin/zsh
+#!/usr/bin/env zsh
 #####################################################################
 
 MAIN() {
-	SUCCESS 'Hello, World!'
+	echo.success 'Hello, World!'
 }

zsh/helm/get-template

@@ -1,9 +1,13 @@
-#!/bin/zsh
-use helm
-use scwrypts
+#!/usr/bin/env zsh
 #####################################################################
 
-MAIN() {
-	unset USAGE
-	HELM__TEMPLATE__GET $@
-}
+use helm
+
+#####################################################################
+
+helm.zshparse.usage
+helm.get-template.parse.usage
+
+#####################################################################
+
+MAIN() { helm.get-template $@; }

zsh/helm/get-template.module.zsh

@@ -0,0 +1,135 @@
+#####################################################################
+
+use scwrypts/get-realpath
+
+use helm/zshparse
+
+DEPENDENCIES+=(helm)
+
+#####################################################################
+
+${scwryptsmodule}() {
+	local PARSERS=(helm.zshparse)
+	eval "$(utils.parse.autosetup)"
+
+	##########################################
+
+	local HELM_LINT_ARGS=(${HELM_ARGS[@]})
+
+	[[ ${USE_CHART_ROOT} =~ false ]] \
+		&& HELM_ARGS+=(--show-only "$(echo "${TEMPLATE_FILENAME}" | sed "s|^${CHART_ROOT}/||")")
+
+	local TEMPLATE_OUTPUT DEBUG_OUTPUT
+	utils.io.capture TEMPLATE_OUTPUT DEBUG_OUTPUT \
+		helm template "${CHART_ROOT}" ${HELM_ARGS[@]} --debug \
+		;
+
+	local EXIT_CODE
+	[ "${TEMPLATE_OUTPUT}" ] && EXIT_CODE=0 || EXIT_CODE=1
+
+	case ${OUTPUT_MODE} in
+		( raw )
+			[[ ${EXIT_CODE} -eq 0 ]] \
+				&& echo "${TEMPLATE_OUTPUT}" | grep -v '^# Source:.*$' \
+				|| echo "${DEBUG_OUTPUT}" >&2 \
+				;
+			;;
+
+		( color )
+			[[ ${EXIT_CODE} -eq 0 ]] \
+				&& echo "${TEMPLATE_OUTPUT}" | bat --language yaml --color always \
+				|| echo "${DEBUG_OUTPUT}" >&2 \
+				;
+			;;
+
+		( debug )
+			[[ ${EXIT_CODE} -eq 0 ]] \
+				&& KUBEVAL_RAW=$(
+					echo "${TEMPLATE_OUTPUT}" \
+						| kubeval --schema-location https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master \
+					) \
+				|| KUBEVAL_RAW='no template output; kubeval skipped'
+
+			echo "
+				${TEMPLATE_OUTPUT}
+				---
+				debug: |\n$(echo ${DEBUG_OUTPUT} | sed 's/^/  /g')
+
+				kubeval: |\n$(echo ${KUBEVAL_RAW} | sed 's/^/  /g')
+
+				lint: |\n$(helm lint "${CHART_ROOT}" ${HELM_LINT_ARGS[@]} 2>&1 | sed 's/^/  /g')
+				" | sed 's/^	\+//; 1d; $d'
+			;;
+	esac
+
+	return ${EXIT_CODE}
+}
+
+#####################################################################
+
+${scwryptsmodule}.parse() {
+	local PARSED=0
+
+	case $1 in
+		( --colorize ) PARSED=1; OUTPUT_MODE=color ;;
+		( --raw      ) PARSED=1; OUTPUT_MODE=raw ;;
+		( --debug    ) PARSED=1; OUTPUT_MODE=debug ;;
+
+		( --update   ) PARSED=1; UPDATE_DEPENDENCIES=true ;;
+	esac
+
+	return ${PARSED}
+}
+
+${scwryptsmodule}.parse.locals() {
+	local OUTPUT_MODE=default
+	local UPDATE_DEPENDENCIES=false
+}
+
+${scwryptsmodule}.parse.usage() {
+	USAGE__description="
+		Smart helm-template generator which auto-detects the chart
+		and sample values for testing and developing helm charts.
+	"
+
+	local DEFAULT
+	utils.dependencies.check bat &>/dev/null \
+		&& DEFAULT=color || DEFAULT=raw
+
+	USAGE__options+="
+		--colorize   $([[ ${DEFAULT} =~ color ]] && printf '(default) ')use 'bat' to colorize output
+		--raw        $([[ ${DEFAULT} =~ raw   ]] && printf '(default) ')remove scwrypts-added fluff and only output helm template details
+		--debug      debug template with kubeval and helm-lint
+
+		--update   update dependencies before generating template output
+	"
+}
+
+${scwryptsmodule}.parse.validate() {
+	case ${OUTPUT_MODE} in
+		( default )
+			utils.dependencies.check bat &>/dev/null \
+				&& OUTPUT_MODE=color \
+				|| OUTPUT_MODE=raw \
+				;
+			;;
+
+		( color )
+			utils.dependencies.check bat || ((ERRORS+=1))
+			;;
+
+		( debug )
+			utils.dependencies.check kubeval \
+				|| echo.error 'kubeval is required for --debug'
+			;;
+	esac
+
+	case ${UPDATE_DEPENDENCIES} in
+		( false ) ;;
+		( true )
+			use helm/update-dependencies
+			helm.update-dependencies --template-filename "${TEMPLATE_FILENAME}" &>/dev/null \
+				|| echo.error 'failed to update dependencies'
+			;;
+	esac
+}

zsh/helm/helm.module.zsh

@@ -0,0 +1,15 @@
+#
+# helm template testing and generation helpers
+#
+
+
+# ensures default values are injected from local Chart dependencies
+use helm/update-dependencies
+
+
+# template generation
+use helm/get-template
+
+
+# shared argument parser
+use helm/zshparse

zsh/helm/update-dependencies

@@ -1,9 +1,13 @@
-#!/bin/zsh
-use helm
-use scwrypts
+#!/usr/bin/env zsh
 #####################################################################
 
-MAIN() {
-	unset USAGE
-	HELM__DEPENDENCY__UPDATE $@
-}
+use helm
+
+#####################################################################
+
+helm.zshparse.usage
+helm.update-dependencies.parse.usage
+
+#####################################################################
+
+MAIN() { helm.update-dependencies $@; }

zsh/helm/update-dependencies.module.zsh

@@ -0,0 +1,31 @@
+#####################################################################
+
+use helm/zshparse
+
+DEPENDENCIES+=(helm)
+
+#####################################################################
+
+${scwryptsmodule}() {
+	local PARSERS=(helm.zshparse)
+
+	eval "$(utils.parse.autosetup)"
+
+	##########################################
+
+	echo.status "updating helm dependencies for '${CHART_ROOT}'" \
+
+	helm dependency update "${CHART_ROOT}" \
+		&& echo.success "helm chart dependencies updated" \
+		|| echo.error   "unable to update helm chart dependencies (see above)" \
+		|| return 1
+}
+
+#####################################################################
+
+${scwryptsmodule}.parse() { return 0; }
+${scwryptsmodule}.parse.usage() {
+	USAGE__description='
+		Auto-detect chart and build dependencies for any file within a helm chart.
+	'
+}

zsh/helm/validate.module.zsh

@@ -0,0 +1,119 @@
+#####################################################################
+
+DEPENDENCIES+=(yq)
+REQUIRED_ENV+=()
+
+#####################################################################
+
+${scwryptsmodule}() {
+	local USAGE="
+		Smart helm-detection / validator which determines the helm
+		chart root and other details given a particular filename.
+
+		You must set TEMPLATE_FILENAME, and this function will verify
+		the template is part of a helm chart and set up the following
+		variables:
+
+		  - CHART_ROOT : the fully qualified path to the directory
+		                 containing Chart.yaml
+
+		  - CHART_NAME : Chart.yaml > .name
+
+		  - USE_CHART_ROOT (true/false)
+		         true  : operations should use/output the entire chart
+			     false : operations should use/output a single template
+
+		  - HELM_ARGS  : an array of arguments which apply to any 'helm'
+		                 command
+	"
+
+	[ "${TEMPLATE_FILENAME}" ] && [ -f "${TEMPLATE_FILENAME}" ] \
+		|| echo.error 'must provide a template filename' \
+		|| return 1
+
+	##########################################
+
+	CHART_ROOT="$(helm.validate.get-chart-root)"
+	[ ${CHART_ROOT} ] && [ -d "${CHART_ROOT}" ] \
+		|| echo.error 'unable to determine helm root; is this a helm template file?' \
+		|| return 1
+
+	##########################################
+
+	CHART_NAME=$(utils.yq -r .name "${CHART_ROOT}/Chart.yaml")
+
+	##########################################
+
+	USE_CHART_ROOT=false
+
+	case "${TEMPLATE_FILENAME}" in
+		( *values.*.yaml | *tests/*.yaml )
+			HELM_ARGS+=(--values ${TEMPLATE_FILENAME})
+			USE_CHART_ROOT=true
+			;;
+
+		( *.tpl )
+			USE_CHART_ROOT=true
+			;;
+	esac
+
+	[[ $(dirname -- "${TEMPLATE_FILENAME}") =~ ^${CHART_ROOT}$ ]] \
+		&& USE_CHART_ROOT=true
+
+	##########################################
+
+	HELM_ARGS=($(helm.validate.get-default-values-args) ${HELM_ARGS[@]})
+
+	##########################################
+
+	return 0
+}
+
+${scwryptsmodule}.get-chart-root() {
+	local SEARCH_DIR=$(dirname -- "${TEMPLATE_FILENAME}")
+	while [[ ! ${SEARCH_DIR} =~ ^/$ ]]
+	do
+		[ -f "${SEARCH_DIR}/Chart.yaml" ] \
+			&& echo "${SEARCH_DIR}" \
+			&& return 0 \
+			;
+
+		SEARCH_DIR="$(dirname -- "${SEARCH_DIR}")"
+	done
+	return 1
+}
+
+${scwryptsmodule}.get-default-values-args() {
+	local F
+	local VALUES_FILES_ORDER=(
+		values.yaml         # the default values of the chart
+		tests/default.yaml  # a template test which provides any required values not included in the default values
+	)
+
+	local LOCAL_DEPENDENCY_CHART LOCAL_CHART_ROOT
+	for LOCAL_DEPENDENCY_CHART in $(\
+		cat "${CHART_ROOT}/Chart.yaml" \
+			| utils.yq -r '.dependencies[] | .repository' \
+			| grep '^file://' \
+			| sed 's|file://||' \
+		)
+	do
+		[[ "${LOCAL_DEPENDENCY_CHART}" =~ ^[/~] ]] \
+			&& LOCAL_CHART_ROOT="${LOCAL_DEPENDENCY_CHART}" \
+			|| LOCAL_CHART_ROOT=$(readlink -f -- "${CHART_ROOT}/${LOCAL_DEPENDENCY_CHART}") \
+			;
+
+		for F in ${VALUES_FILES_ORDER[@]}
+		do
+			[ -f "${LOCAL_CHART_ROOT}/${F}" ] \
+				&& echo --values "${LOCAL_CHART_ROOT}/${F}"
+		done
+	done
+
+	local HELM_VALUES_ARGS=()
+	for F in ${VALUES_FILES_ORDER[@]}
+	do
+		[ -f "${CHART_ROOT}/${F}" ] \
+			&& echo --values "${CHART_ROOT}/${F}"
+	done
+}

zsh/helm/zshparse.module.zsh

@@ -0,0 +1,54 @@
+#####################################################################
+
+use helm/validate
+use scwrypts/get-realpath
+
+#####################################################################
+
+${scwryptsmodule}() {
+	local PARSED=0
+
+	case $1 in
+		( -t | --template-filename )
+			PARSED=2
+			TEMPLATE_FILENAME="$(scwrypts.get-realpath "$2")"
+			;;
+	esac
+
+	return ${PARSED}
+}
+
+${scwryptsmodule}.locals() {
+	local TEMPLATE_FILENAME
+	local ARGS=()
+
+	# configured by helm.validate
+	local CHART_NAME
+	local CHART_ROOT
+	local HELM_ARGS=()
+}
+
+${scwryptsmodule}.usage() {
+	USAGE__options+='
+		-t, --template-filename   path to a template/*.yaml file of a helm chart
+	'
+
+	USAGE__args+='
+		\$@   additional args are forwarded to helm
+	'
+}
+
+${scwryptsmodule}.validate() {
+	helm.validate || return 1
+
+	HELM_ARGS+=(${ARGS[@]})
+
+	echo.debug "
+		template filename : ${TEMPLATE_FILENAME}
+		chart name        : ${CHART_NAME}
+		chart root        : ${CHART_ROOT}
+		helm args         : ${HELM_ARGS[@]}
+	"
+}
+
+#####################################################################

zsh/import.driver.zsh

@@ -0,0 +1,340 @@
+command -v use use.is-loaded use.get-library-root &>/dev/null && return 0
+
+ ###################################################################
+#                                                                   #
+# usage: use [OPTIONS ...] zsh/module/path                          #
+#                                                                   #
+ ###################################################################
+#                                                                   #
+# OPTIONS:                                                          #
+#                                                                   #
+#   -g, --group          lookup library root from friendly group    #
+#                        name (requires configuration)              #
+#                        (default: scwrypts)                        #
+#                                                                   #
+#   -r, --library-root   fully qualified path to a library root     #
+#                                                                   #
+#   --check-environment  check environment immediately rather than  #
+#                        wait for downstream call to                #
+#                                          utils.check-environment  #
+#                                                                   #
+#                                                                   #
+# ZSHIMPORT_USE_CACHE (true|false; default: true)                   #
+#    setting this to false will always require direct, source files #
+#                                                                   #
+# Allows for import-style library loading in zsh. No matter what    #
+# scwrypt is run, this function (and required helpers) are *also*   #
+# loaded, ensuring that 'use' is always available in scwrypts       #
+# context.                                                          #
+#                                                                   #
+#                                                                   #
+# Friendly group-names can be configured by setting the variable    #
+# 'SCWRYPTS_GROUP_CONFIGRUATION__<group-name>__root' to the fully   #
+# qualified path to the root directory of the modules library.      #
+#                                                                   #
+#                                                                   #
+ ###################################################################
+
+
+# I have no idea why, but CircleCI obliterates this env var in particular
+# every time. Just going to force it like this for now
+[ $CIRCLECI ] && export ZSHIMPORT_USE_CACHE=false
+
+[ ${ZSHIMPORT_USE_CACHE} ] || export ZSHIMPORT_USE_CACHE=true
+
+[[ ${ZSHIMPORT_USE_CACHE} =~ true ]] && {
+	command -v jo jq sha1sum &>/dev/null || {
+		echo.warning "missing utilities prevents import cache"
+		export ZSHIMPORT_USE_CACHE=false
+	}
+}
+
+[ ${ZSHIMPORT_CACHE_DIR} ] || export ZSHIMPORT_CACHE_DIR="${XDG_CACHE_HOME:-${HOME}/.cache}/zshimport"
+
+source "${0:a:h}/config.zsh"
+
+use() {
+	local SCWRYPTS_LIBRARY SCWRYPTS_LIBRARY_ROOT SCWRYPTS_LIBRARY_GROUP
+	local DEFER_ENVIRONMENT_CHECK=true
+
+	local ONLY_OUTPUT_METADATA=false
+	local ONLY_GENERATE_CACHE=false
+
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in
+			( -g | --group )
+				[ "${SCWRYPTS_LIBRARY_ROOT}" ] && echo.error 'specify only one of {(-g), (-r)}'
+				SCWRYPTS_LIBRARY_GROUP=$2
+				shift 1
+				;;
+
+			( -r | --library-root )
+				[ "${SCWRYPTS_LIBRARY_GROUP}" ] && echo.error 'specify only one of {(-g), (-r)}'
+				SCWRYPTS_LIBRARY_ROOT=$2
+				shift 1
+				;;
+
+			( -c | --check-environment )
+				DEFER_ENVIRONMENT_CHECK=false
+				;;
+
+			( --meta )
+				ONLY_OUTPUT_METADATA=true
+				;;
+
+			( --generate-cache )
+				ONLY_GENERATE_CACHE=true
+				;;
+
+			( * )
+				[ ! "${SCWRYPTS_LIBRARY}" ] \
+					&& SCWRYPTS_LIBRARY=$1 \
+					|| echo.error 'too many arguments; expected exactly 1 argument' \
+
+				;;
+		esac
+		shift 1
+	done
+
+	[ ! "${SCWRYPTS_LIBRARY}" ] && echo.error 'no library specified for import'
+
+	: \
+		&& [ ! "${SCWRYPTS_LIBRARY_GROUP}" ] \
+		&& [ ! "${SCWRYPTS_LIBRARY_ROOT}"  ] \
+		&& SCWRYPTS_LIBRARY_GROUP=scwrypts
+
+	# bail ASAP, check errors later
+	use.is-loaded && [[ ${ONLY_OUTPUT_METADATA} =~ false ]] && [[ ${ONLY_GENERATE_CACHE} =~ false ]] && return 0
+
+	[ ! "${SCWRYPTS_LIBRARY_ROOT}" ] && SCWRYPTS_LIBRARY_ROOT="$(use.get-scwrypts-library-root)"
+	[ ! "${SCWRYPTS_LIBRARY_ROOT}" ] && echo.error "unable to determine library root from group name '${SCWRYPTS_LIBRARY_GROUP}'"
+
+	#####################################################################
+
+	local LIBRARY_FILE LIBRARY_FILE_TEMP CACHE_FILE
+
+	[ ! "${LIBRARY_FILE}" ] && {
+		LIBRARY_FILE_TEMP="${SCWRYPTS_LIBRARY_ROOT}/${SCWRYPTS_LIBRARY}.module.zsh"
+		[ -f "${LIBRARY_FILE_TEMP}" ] && {
+			LIBRARY_FILE="${LIBRARY_FILE_TEMP}"
+			CACHE_FILE="${SCWRYPTS_LIBRARY}.module.zsh"
+		}
+	}
+
+	[ ! "${LIBRARY_FILE}" ] && {  # "group" library reference
+		LIBRARY_FILE_TEMP="${SCWRYPTS_LIBRARY_ROOT}/${SCWRYPTS_LIBRARY}/$(basename -- "${SCWRYPTS_LIBRARY}").module.zsh"
+		[ -f "${LIBRARY_FILE_TEMP}" ] && {
+			LIBRARY_FILE="${LIBRARY_FILE_TEMP}"
+			CACHE_FILE="${SCWRYPTS_LIBRARY}/$(basename -- "${SCWRYPTS_LIBRARY}").module.zsh"
+		}
+	}
+
+	[ "${LIBRARY_FILE}" ] \
+		|| echo.error "no such library '${SCWRYPTS_LIBRARY_GROUP}/${SCWRYPTS_LIBRARY}'"
+
+	#####################################################################
+
+	local LIBRARY_HASH LIBRARY_CACHE_DIR LIBRARY_CACHE_FILE
+
+	#####################################################################
+
+	utils.check-errors || {
+		((IMPORT_ERRORS+=1))
+		return 1
+	}
+
+	#####################################################################
+
+	local SCWRYPTS_MODULE_BEFORE=${scwryptsmodule}
+	[[ ${SCWRYPTS_LIBRARY_GROUP} =~ ^scwrypts$ ]] \
+		&& export scwryptsmodule="$(echo "${SCWRYPTS_LIBRARY}" | sed 's|/|.|g')" \
+		|| export scwryptsmodule="${SCWRYPTS_LIBRARY_GROUP}.$(echo "${SCWRYPTS_LIBRARY}" | sed 's|/|.|g')" \
+		;
+
+	[[ ${ONLY_OUTPUT_METADATA} =~ true ]] && {
+		use.get-metadata
+		return 0
+	}
+
+	case "${ZSHIMPORT_USE_CACHE}" in
+		( false ) ;;
+		( true )
+			LIBRARY_HASH="$(use.compute-scwrypts-library-hash)"
+			LIBRARY_CACHE_DIR="${ZSHIMPORT_CACHE_DIR}/${SCWRYPTS_LIBRARY_GROUP}-${LIBRARY_HASH}"
+			LIBRARY_CACHE_FILE="${LIBRARY_CACHE_DIR}/${CACHE_FILE}"
+
+			[ "${LIBRARY_HASH}" ] && [ "${LIBRARY_CACHE_DIR}" ] && [ "${LIBRARY_CACHE_FILE}" ] \
+				|| echo.error "error when computing library hash for ${SCWRYPTS_LIBRARY_GROUP}/${SCWRYPTS_LIBRARY}"
+
+			use.generate-cache \
+				|| echo.error "error generating cache for ${SCWRYPTS_LIBRARY_GROUP}/${SCWRYPTS_LIBRARY}" \
+				|| return 1
+			;;
+	esac
+
+	[[ ${ONLY_GENERATE_CACHE} =~ true ]] && {
+		cat "${LIBRARY_CACHE_FILE}" | grep .
+		return $?
+	}
+
+	case ${ZSHIMPORT_USE_CACHE} in
+		( true )
+			source "${LIBRARY_CACHE_FILE}" || {
+				((IMPORT_ERRORS+=1))
+				echo.error "import error for '${SCWRYPTS_LIBRARY_GROUP}/${SCWRYPTS_LIBRARY}'"
+				echo.debug "cache : '${LIBRARY_CACHE_FILE}'"
+				return 1
+			}
+			;;
+
+		( false )
+
+			source "${LIBRARY_FILE}" || {
+				((IMPORT_ERRORS+=1))
+				echo.error "import error for '${SCWRYPTS_LIBRARY_GROUP}/${SCWRYPTS_LIBRARY}'"
+				export scwryptsmodule=${SCWRYPTS_MODULE_BEFORE}
+				return 1
+			}
+
+			[[ ${DEFER_ENVIRONMENT_CHECK} =~ false ]] && {
+				utils.check-environment || {
+					((IMPORT_ERRORS+=1))
+					echo.error "import error for '${SCWRYPTS_LIBRARY_GROUP}/${SCWRYPTS_LIBRARY}'"
+					return 1
+				}
+			}
+
+			use.is-loaded --set
+			[[ ${SCWRYPTS_MODULE_BEFORE} ]] \
+				&& export scwryptsmodule=${SCWRYPTS_MODULE_BEFORE} \
+				|| unset scwryptsmodule \
+				;
+			;;
+	esac
+
+	return 0
+}
+
+use.get-scwrypts-library-root() {
+	local VARIABLE_NAME="SCWRYPTS_LIBRARY_ROOT__${SCWRYPTS_LIBRARY_GROUP}"
+	echo "${(P)VARIABLE_NAME}" | grep . && return 0
+
+	##########################################
+
+	local ROOT
+
+	ROOT="$(scwrypts.config.group "${SCWRYPTS_LIBRARY_GROUP}" zshlibrary)"
+	[ "${ROOT}" ] && eval ${VARIABLE_NAME}="${ROOT}" && echo "${ROOT}" && return 0
+
+	##########################################
+
+	local GROUP_ROOT="$(scwrypts.config.group "${SCWRYPTS_LIBRARY_GROUP}" root)"
+	local GROUP_TYPE="$(scwrypts.config.group "${SCWRYPTS_LIBRARY_GROUP}" type)"
+
+	[[ ${GROUP_TYPE} =~ zsh ]] \
+		&& ROOT="${GROUP_ROOT}/lib" \
+		|| ROOT="${GROUP_ROOT}/zsh/lib" \
+		;
+
+	[ -d "${ROOT}" ] || ROOT="$(dirname -- "${ROOT}")"
+
+	[ "${ROOT}" ] && [ -d "${ROOT}" ] \
+		|| echo.error "unable to determine library root" \
+		|| return 1
+
+	eval ${VARIABLE_NAME}="${ROOT}"
+	echo "${ROOT}"
+}
+
+use.compute-scwrypts-library-hash() {
+	LC_ALL=POSIX find "${SCWRYPTS_LIBRARY_ROOT}" -type f -name \*.module.zsh -print0 \
+		| sort -z \
+		| xargs -0 sha1sum \
+		| sha1sum \
+		| awk '{print $1;}' \
+		;
+}
+
+use.is-loaded() {
+	local VARIABLE_NAME="SCWRYPTS_LIBRARY_LOADED__${SCWRYPTS_LIBRARY_GROUP}__$(echo ${SCWRYPTS_LIBRARY} | sed 's|[/-]|_|g')"
+
+	[[ $1 =~ ^--set$ ]] && eval ${VARIABLE_NAME}=true
+
+	[[ ${(P)VARIABLE_NAME} =~ true ]]
+}
+
+use.get-metadata() {
+	jo \
+		LIBRARY_FILE="${LIBRARY_FILE}" \
+		SCWRYPTS_LIBRARY_GROUP="${SCWRYPTS_LIBRARY_GROUP}" \
+		SCWRYPTS_LIBRARY="${SCWRYPTS_LIBRARY}" \
+		scwryptsmodule="${scwryptsmodule}" \
+		;
+}
+
+#####################################################################
+
+use.generate-cache() {
+	[ "${LIBRARY_CACHE_FILE}" ] || return 1
+
+	[ -f "${LIBRARY_CACHE_FILE}" ] && return 0
+
+	##########################################
+
+	mkdir -p -- "$(dirname -- "${LIBRARY_CACHE_FILE}")"
+
+	local IMPORTS=":${LIBRARY_FILE}:"
+
+	use.generate-cache.create-import $(use.get-metadata) > "${LIBRARY_CACHE_FILE}"
+
+	local METADATA SUBFILE SUBMODULE
+	while $(grep -q '^use\s' "${LIBRARY_CACHE_FILE}")
+	do
+		NEXT_IMPORT=$(grep '^use\s' ${LIBRARY_CACHE_FILE} | head -n1)
+		METADATA="$(eval "${NEXT_IMPORT} --meta")"
+
+		[ "${METADATA}" ] \
+			|| echo.error "error getting metadata for '${NEXT_IMPORT}'" \
+			|| return 1
+
+		SUBFILE="$(echo "${METADATA}" | jq -r .LIBRARY_FILE)"
+		[[ "${IMPORTS}" =~ ":${SUBFILE}:" ]] && {
+			grep -v "^${NEXT_IMPORT}$" "${LIBRARY_CACHE_FILE}" > "${LIBRARY_CACHE_FILE}.tmp"
+			mv "${LIBRARY_CACHE_FILE}.tmp" "${LIBRARY_CACHE_FILE}"
+			continue
+		}
+
+		IMPORTS+="${SUBFILE}:"
+
+		SUBMODULE="$(echo "${METADATA}" | jq -r .scwryptsmodule)"
+		use.generate-cache.create-import "${METADATA}" > "${LIBRARY_CACHE_FILE}.subfile"
+
+		{
+			sed -n '0,/^use\s/p' ${LIBRARY_CACHE_FILE} | sed '$d'
+			echo '() {'
+			cat "${LIBRARY_CACHE_FILE}.subfile"
+			echo '}'
+			sed -n '/^use\s/,$p' ${LIBRARY_CACHE_FILE} | sed '1d'
+		} > "${LIBRARY_CACHE_FILE}.tmp"
+		mv "${LIBRARY_CACHE_FILE}.tmp" "${LIBRARY_CACHE_FILE}"
+		rm "${LIBRARY_CACHE_FILE}.subfile"
+	done
+}
+
+use.generate-cache.create-import() {
+	local METADATA="$1"
+
+	local FILENAME="$(echo "${METADATA}" | jq -r .LIBRARY_FILE)"
+	local SCWRYPTSMODULE="$(echo "${METADATA}" | jq -r .scwryptsmodule)"
+	local GROUP="$(echo "${METADATA}" | jq -r .SCWRYPTS_LIBRARY_GROUP)"
+	local LIBRARY="$(echo "${METADATA}" | jq -r .SCWRYPTS_LIBRARY | sed 's|[/-]|_|g')"
+
+	local IS_LOADED_VARIABLE="SCWRYPTS_LIBRARY_LOADED__${GROUP}__${LIBRARY}"
+
+	echo "[[ \$${IS_LOADED_VARIABLE} =~ true ]] && return 0"
+	echo "export scwryptsmodule=${SCWRYPTSMODULE}"
+	sed "/^use\\s/aexport scwryptsmodule=${SCWRYPTSMODULE}" "${FILENAME}"
+	echo "${IS_LOADED_VARIABLE}=true"
+	echo "unset scwryptsmodule"
+}

zsh/lib/cloud/aws/cli.module.zsh

@@ -1,23 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=(
-	aws
-)
-
-REQUIRED_ENV+=()
-
-#####################################################################
-
-AWS() {
-	local ARGS=()
-
-	ARGS+=(--output json)
-
-	[ ! $CI ] && {
-		REQUIRED_ENV=(AWS_REGION AWS_ACCOUNT AWS_PROFILE) CHECK_ENVIRONMENT || return 1
-		ARGS+=(--profile $AWS_PROFILE)
-		ARGS+=(--region $AWS_REGION)
-		}
-
-	aws ${ARGS[@]} $@
-}

zsh/lib/cloud/aws/ecr.module.zsh

@@ -1,27 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=(
-	docker
-)
-
-REQUIRED_ENV+=()
-
-use cloud/aws/cli
-
-#####################################################################
-
-ECR_LOGIN() {
-	REQUIRED_ENV=(AWS_REGION AWS_ACCOUNT) CHECK_ENVIRONMENT || return 1
-
-	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 "authenticated docker for '$AWS_ACCOUNT' in '$AWS_REGION'" \
-		|| {
-			ERROR "unable to authenticate docker for '$AWS_ACCOUNT' in '$AWS_REGION'"
-			return 1
-		}
-}

zsh/lib/cloud/aws/eks.module.zsh

@@ -1,90 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=(kubectl yq)
-REQUIRED_ENV+=()
-
-use cloud/aws/cli
-
-#####################################################################
-
-EKS__KUBECTL() { EKS kubectl $@; }
-EKS__FLUX()    { EKS flux $@; }
-
-#####################################################################
-
-EKS() {
-	local USAGE="
-		usage: cli [...kubectl args...]
-
-		args:
-		  cli   a kubectl-style CLI (e.g. kubectl, helm, flux, etc)
-
-		Allows access to kubernetes CLI commands by configuring environment
-		to point to a specific cluster.
-	"
-
-	REQUIRED_ENV=(AWS_REGION AWS_ACCOUNT CLUSTER_NAME) DEPENDENCIES=(kubectl $1) CHECK_ENVIRONMENT || return 1
-
-	local CONTEXT="arn:aws:eks:${AWS_REGION}:${AWS_ACCOUNT}:cluster/${CLUSTER_NAME}"
-
-	kubectl config get-contexts | grep -q $CONTEXT \
-		|| EKS__CLUSTER_LOGIN -c $CLUSTER_NAME >/dev/null
-
-	local CONTEXT_ARGS=()
-	case $1 in
-		helm ) CONTEXT_ARGS+=(--kube-context $CONTEXT) ;;
-		* ) CONTEXT_ARGS+=(--context $CONTEXT) ;;
-	esac
-
-	$1 ${CONTEXT_ARGS[@]} ${@:2}
-}
-
-#####################################################################
-
-EKS__CLUSTER_LOGIN() {
-	local USAGE="
-		usage:  [...options...]
-
-		options
-		  -c, --cluster-name <string>   (optional) login a specific cluster
-
-
-		Interactively sets the default kubeconfig to match the selected
-		cluster in EKS. Also creates the kubeconfig entry if it does not
-		already exist.
-	"
-	REQUIRED_ENV=(AWS_ACCOUNT AWS_REGION) CHECK_ENVIRONMENT || return 1
-
-
-	local CLUSTER_NAME
-
-	while [[ $# -gt 0 ]]
-	do
-		case $1 in 
-			-c | --cluster-name ) CLUSTER_NAME="$2"; shift 1 ;;
-
-			* ) [ ! $APPLICATION  ] && APPLICATION="$1" \
-					|| ERROR "extra positional argument '$1'"
-				;;
-		esac
-		shift 1
-	done
-
-	[ ! $CLUSTER_NAME ] && CLUSTER_NAME=$(\
-		AWS eks list-clusters \
-			| jq -r '.[] | .[]' \
-			| FZF 'select a cluster'
-	)
-
-	[ ! $CLUSTER_NAME ] && ERROR 'must select a valid cluster or use -c flag'
-
-	CHECK_ERRORS
-
-	##########################################
-
-	STATUS 'creating / updating kubeconfig for EKS cluster'
-	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/lib/cloud/aws/eksctl.module.zsh

@@ -1,116 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=(eksctl)
-REQUIRED_ENV+=()
-
-use cloud/aws/eks
-
-#####################################################################
-
-EKSCTL() {
-	REQUIRED_ENV=(AWS_PROFILE AWS_REGION) CHECK_ENVIRONMENT || return 1
-
-	AWS_PROFILE=$AWS_PROFILE AWS_REGION=$AWS_REGION \
-		eksctl $@
-}
-
-EKSCTL__CREATE_IAMSERVICEACCOUNT() {
-	local USAGE="
-		usage: serviceaccount-name namespace [...options...] -- [...'eksctl create iamserviceaccount' args...]
-
-		options:
-		  --serviceaccount   (required) target k8s:ServiceAccount
-		  --namespace        (required) target k8s:Namespace
-		  --role-name        (required) name of the IAM role to assign
-
-		  --force   don't check for existing serviceaccount and override any existing configuration
-
-		eksctl create iamserviceaccount args:
-		$(eksctl create iamserviceaccount --help 2>&1 | grep -v -- '--name' | grep -v -- '--namespace' | grep -v -- '--role-name' | sed 's/^/  /')
-	"
-	REQUIRED_ENV=(AWS_REGION AWS_ACCOUNT CLUSTER_NAME) CHECK_ENVIRONMENT || return 1
-
-	local SERVICEACCOUNT NAMESPACE ROLE_NAME
-	local FORCE=0
-	local EKSCTL_ARGS=()
-
-	while [[ $# -gt 0 ]]
-	do
-		case $1 in
-			--serviceaccount ) SERVICEACCOUNT=$2; shift 1 ;;
-			--namespace      ) NAMESPACE=$2; shift 1 ;;
-			--role-name      ) ROLE_NAME=$2; shift 1 ;;
-
-			--force ) FORCE=1 ;; 
-
-			-- ) shift 1; break ;;
-
-			* ) ERROR "unknown argument '$1'" ;;
-		esac
-		shift 1
-	done
-
-	while [[ $# -gt 0 ]]; do EKSCTL_ARGS+=($1); shift 1; done
-
-	[ $SERVICEACCOUNT ] || ERROR "--serviceaccount is required"
-	[ $NAMESPACE      ] || ERROR "--namespace is required"
-	[ $ROLE_NAME      ] || ERROR "--role-name is required"
-
-	CHECK_ERRORS --no-fail || return 1
-
-	##########################################
-	
-	[[ $FORCE -eq 0 ]] && {
-		_EKS__CHECK_IAMSERVICEACCOUNT_EXISTS
-		local EXISTS_STATUS=$?
-		case $EXISTS_STATUS in
-			0 )
-				SUCCESS "'$NAMESPACE/$SERVICEACCOUNT' already configured with '$ROLE_NAME'"
-				return 0
-				;;
-			1 ) ;; # role does not exist yet; continue with rollout
-			2 )
-				ERROR "'$NAMESPACE/$SERVICEACCOUNT' has been configured with a different role than '$ROLE_NAME'"
-				REMINDER "must use --force flag to overwrite"
-				return 2
-				;;
-		esac
-	}
-
-	STATUS "creating iamserviceaccount" \
-		&& EKSCTL create iamserviceaccount \
-			--cluster $CLUSTER_NAME \
-			--namespace $NAMESPACE \
-			--name $SERVICEACCOUNT \
-			--role-name $ROLE_NAME \
-			--override-existing-serviceaccounts \
-			--approve \
-			${EKSCTL_ARGS[@]} \
-		&& SUCCESS "successfully configured '$NAMESPACE/$SERVICEACCOUNT' with IAM role '$ROLE_NAME'" \
-		|| { ERROR "unable to configure '$NAMESPACE/$SERVICEACCOUNT' with IAM role '$ROLE_NAME' (check cloudformation dashboard for details)"; return 3; }
-}
-
-_EKS__CHECK_IAMSERVICEACCOUNT_EXISTS() {
-	STATUS "checking for existing role-arn"
-	local CURRENT_ROLE_ARN=$(
-		EKS__KUBECTL --namespace $NAMESPACE get serviceaccount $SERVICEACCOUNT -o yaml \
-			| YQ -r '.metadata.annotations["eks.amazonaws.com/role-arn"]' \
-			| grep -v '^null$' \
-	)
-
-	[ $CURRENT_ROLE_ARN ] || {
-		STATUS "serviceaccount does not exist or has no configured role"
-		return 1
-	}
-
-	[[ $CURRENT_ROLE_ARN =~ "$ROLE_NAME$" ]] || {
-		STATUS "serviceaccount current role does not match desired role:
-			  CURRENT : $CURRENT_ROLE_ARN
-			  DESIRED : arn:aws:iam::${AWS_ACCOUNT}:role/$ROLE_NAME
-			  "
-		return 2
-	}
-
-	STATUS "serviceaccount current role matches desired role"
-	return 0
-}

zsh/lib/cloud/media-sync.module.zsh

@@ -1,69 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=()
-
-REQUIRED_ENV+=(
-	MEDIA_SYNC__TARGETS
-	MEDIA_SYNC__S3_BUCKET
-)
-
-use cloud/aws/cli
-
-#####################################################################
-
-MEDIA_SYNC__PUSH() {
-	local FLAGS=($@)
-	local FAILED_COUNT=0
-
-	STATUS 'starting media upload to s3'
-
-	local TARGET
-	for TARGET in ${MEDIA_SYNC__TARGETS[@]}
-	do
-		_MEDIA_SYNC push $TARGET $FLAGS || ((FAILED_COUNT+=1))
-	done
-
-	[[ $FAILED_COUNT -eq 0 ]] \
-		&& SUCCESS 's3 media files now up-to-date' \
-		|| FAIL $FAILED_COUNT 'unable to upload one or more targets' \
-		;
-}
-
-MEDIA_SYNC__PULL() {
-	local FLAGS=($@)
-	local FAILED_COUNT=0
-
-	STATUS 'starting media download from s3'
-
-	local TARGET
-	for TARGET in ${MEDIA_SYNC__TARGETS[@]}
-	do
-		_MEDIA_SYNC pull $TARGET $FLAGS || ((FAILED_COUNT+=1))
-	done
-
-	[[ $FAILED_COUNT -eq 0 ]] \
-		&& SUCCESS 'local media files now up-to-date' \
-		|| FAIL $FAILED_COUNT 'unable to download one or more targets' \
-		;
-}
-
-_MEDIA_SYNC() {
-	local ACTION="$1"
-	local REMOTE_TARGET="s3://$MEDIA_SYNC__S3_BUCKET/$2"
-	local LOCAL_TARGET="$HOME/$2"
-
-	local A B
-	case $ACTION in
-		push ) A="$LOCAL_TARGET";  B="$REMOTE_TARGET" ;;
-		pull ) A="$REMOTE_TARGET"; B="$LOCAL_TARGET"  ;;
-
-		* ) ERROR "unknown action '$1'"; return 1 ;;
-	esac
-
-	local FLAGS=(${@:3})
-
-	STATUS "${ACTION}ing $2"
-	AWS s3 sync $A $B $FLAGS \
-		&& SUCCESS "$2 up-to-date" \
-		|| { ERROR "unable to sync $2 (see above)"; return 1; }
-}

zsh/lib/config.zsh

@@ -1,95 +0,0 @@
-[[ $__SCWRYPT -eq 1 ]] && return 0
-#####################################################################
-
-# Apparently MacOS puts ALL of the homebrew stuff inside of a top level git repository
-# with bizarre git ignores; so:
-#  - USE the git root if it's a manual install...
-#  - UNLESS that git root is just the $(brew --prefix)
-SCWRYPTS_ROOT="$(cd -- ${0:a:h}; git rev-parse --show-toplevel 2>/dev/null | grep -v "^$(brew --prefix 2>/dev/null)$")"
-
-[ $SCWRYPTS_ROOT ] && [ -d "$SCWRYPTS_ROOT" ] \
-	|| SCWRYPTS_ROOT="$(echo "${0:a:h}" | sed -n 's|\(share/scwrypts\).*$|\1|p')"
-
-[ $SCWRYPTS_ROOT ] && [ -d "$SCWRYPTS_ROOT" ] || {
-	echo "cannot determine scwrypts root path for current installation; aborting"
-	exit 1
-}
-
-export SCWRYPTS_ROOT__scwrypts="$SCWRYPTS_ROOT"
-
-[ -f "$SCWRYPTS_ROOT__scwrypts/MANAGED_BY" ] \
-	&& export SCWRYPTS_INSTALLATION_TYPE=$(cat "$SCWRYPTS_ROOT__scwrypts/MANAGED_BY") \
-	|| export SCWRYPTS_INSTALLATION_TYPE=manual \
-	;
-
-
-#####################################################################
-
-DEFAULT_CONFIG="$SCWRYPTS_ROOT__scwrypts/zsh/lib/config.user.zsh"
-source "$DEFAULT_CONFIG"
-
-USER_CONFIG_OVERRIDES="$SCWRYPTS_CONFIG_PATH/config.zsh"
-[ ! -f "$USER_CONFIG_OVERRIDES" ] && {
-	mkdir -p $(dirname "$USER_CONFIG_OVERRIDES")
-	cp "$DEFAULT_CONFIG" "$USER_CONFIG_OVERRIDES"
-}
-source "$USER_CONFIG_OVERRIDES"
-
-mkdir -p \
-	"$SCWRYPTS_CONFIG_PATH" \
-	"$SCWRYPTS_DATA_PATH" \
-	"$SCWRYPTS_ENV_PATH" \
-	"$SCWRYPTS_LOG_PATH" \
-	"$SCWRYPTS_OUTPUT_PATH" \
-	;
-
-export \
-	SCWRYPTS_GROUPS \
-	SCWRYPTS_CONFIG_PATH \
-	SCWRYPTS_DATA_PATH \
-	SCWRYPTS_SHORTCUT \
-	SCWRYPTS_ENV_SHORTCUT \
-	SCWRYPTS_LOG_PATH \
-	SCWRYPTS_OUTPUT_PATH \
-	;
-
-source "$SCWRYPTS_ROOT/scwrypts.scwrypts.zsh" \
-	|| FAIL 69 'failed to set up scwrypts group; aborting'
-
-
-#####################################################################
-
-for plugin in $(ls $SCWRYPTS_ROOT__scwrypts/plugins)
-do
-	[[ $(eval 'echo $SCWRYPTS_PLUGIN_ENABLED__'$plugin) -eq 1 ]] && {
-		source "$SCWRYPTS_ROOT/plugins/$plugin/$plugin.scwrypts.zsh"
-	}
-done
-
-#####################################################################
-
-for GROUP_LOADER in $(env | sed -n 's/^SCWRYPTS_GROUP_LOADER__[a-z_]\+=//p')
-do
-	[ -f "$GROUP_LOADER" ] && source "$GROUP_LOADER"
-done
-
-: \
-	&& [ ! "$SCWRYPTS_AUTODETECT_GROUP_BASEDIR" ] \
-	&& [ $GITHUB_WORKSPACE ] \
-	&& [ ! $SCWRYPTS_GITHUB_NO_AUTOLOAD ] \
-	&& SCWRYPTS_AUTODETECT_GROUP_BASEDIR="$GITHUB_WORKSPACE" \
-	;
-
-[ "$SCWRYPTS_AUTODETECT_GROUP_BASEDIR" ] && [ -d "$SCWRYPTS_AUTODETECT_GROUP_BASEDIR" ] && {
-	for GROUP_LOADER in $(find "$SCWRYPTS_AUTODETECT_GROUP_BASEDIR" -type f -name \*scwrypts.zsh)
-	do
-		[ -f "$GROUP_LOADER" ] && source "$GROUP_LOADER"
-	done
-}
-
-#####################################################################
-
-SCWRYPTS_GROUPS=(scwrypts $(echo $SCWRYPTS_GROUPS | sed 's/\s\+/\n/g' | sort -u | grep -v '^scwrypts$'))
-
-#####################################################################
-__SCWRYPT=1 # arbitrary; indicates currently inside a scwrypt

zsh/lib/helm/dependency.module.zsh

@@ -1,42 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=(helm kubeval)
-REQUIRED_ENV+=()
-
-use helm/validate
-
-#####################################################################
-
-HELM__DEPENDENCY__UPDATE() {
-	[ ! $USAGE ] && local USAGE="
-		usage: [...options...]
-
-		options
-		  -t, --template-filename   path to a template/*.yaml file of a helm chart
-
-		Auto-detect chart and build dependencies for any file within a helm chart.
-	"
-	local TEMPLATE_FILENAME CHART_ROOT VALUES_FILES=()
-	local COLORIZE=0 RAW=0 DEBUG=0
-
-	while [[ $# -gt 0 ]]
-	do
-		case $1 in 
-			-t | --template-filename ) TEMPLATE_FILENAME="$(SCWRYPTS__GET_REALPATH "$2")"; shift 1 ;;
-
-			* ) ERROR "unexpected argument '$1'" ;;
-		esac
-		shift 1
-	done
-
-	HELM__VALIDATE
-	CHECK_ERRORS || return 1
-
-	##########################################
-
-	STATUS "updating helm dependencies for '$CHART_ROOT'" \
-		&& cd $CHART_ROOT  \
-		&& helm dependency update \
-		&& SUCCESS "helm chart dependencies updated" \
-		|| { ERROR "unable to update helm chart dependencies (see above)"; return 1; }
-}

zsh/lib/helm/helm.module.zsh

@@ -1,9 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=()
-REQUIRED_ENV+=()
-
-use helm/dependency
-use helm/template
-
-#####################################################################

zsh/lib/helm/template.module.zsh

@@ -1,111 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=(helm kubeval)
-REQUIRED_ENV+=()
-
-use helm/validate
-use scwrypts
-
-#####################################################################
-
-HELM__TEMPLATE__GET() {
-	[ ! $USAGE ] && local USAGE="
-		usage: [...options...] (--) [...helm args...]
-
-		options
-		  -t, --template-filename   path to a template/*.yaml file of a helm chart
-
-		  --colorize   use 'bat' to colorize output
-		  --raw        remove scwrypts-added fluff and only output helm template details
-
-		  -h, --help   show this help dialogue
-
-		Smart helm-template generator which auto-detects the chart
-		and sample values for testing and developing helm charts.
-	"
-	local HELM_ARGS=()
-	local TEMPLATE_FILENAME TEMPLATE_NAME CHART_ROOT CHART_NAME VALUES_FILES=()
-	local COLORIZE=0 RAW=0 DEBUG=0
-
-	while [[ $# -gt 0 ]]
-	do
-		case $1 in 
-			-t | --template-filename ) TEMPLATE_FILENAME="$(SCWRYPTS__GET_REALPATH "$2")"; shift 1 ;;
-
-			--colorize )
-				DEPENDENCIES=(bat) CHECK_ENVIRONMENT || return 1
-				COLORIZE=1
-				;;
-
-			--raw ) RAW=1 ;;
-
-			-h | --help ) USAGE; return 0 ;;
-			-- ) shift 1; break ;;
-
-
-			* ) HELM_ARGS+=($1) ;;
-		esac
-		shift 1
-	done
-
-	while [[ $# -gt 0 ]]; do HELM_ARGS+=($1); shift 1; done
-
-	HELM__VALIDATE
-	CHECK_ERRORS || return 1
-
-	##########################################
-
-	local EXIT_CODE=0
-	local TEMPLATE_OUTPUT DEBUG_OUTPUT
-	[ $USE_CHART_ROOT ] && [[ $USE_CHART_ROOT -eq 1 ]] && {
-		CAPTURE TEMPLATE_OUTPUT DEBUG_OUTPUT helm template "$CHART_ROOT" ${HELM_ARGS[@]} --debug
-		true
-	} || {
-		CAPTURE TEMPLATE_OUTPUT DEBUG_OUTPUT helm template "$CHART_ROOT" ${HELM_ARGS[@]} --debug --show-only "$(echo $TEMPLATE_FILENAME | sed "s|^$CHART_ROOT/||")"
-	}
-		
-	[ ! $TEMPLATE_OUTPUT ] && EXIT_CODE=1
-
-
-	[[ $RAW -eq 1 ]] && {
-		[ $USE_CHART_ROOT ] && [[ $USE_CHART_ROOT -eq 1 ]] || HELM_ARGS+=(--show-only $(echo $TEMPLATE_FILENAME | sed "s|^$CHART_ROOT/||"))
-		[[ $COLORIZE -eq 1 ]] \
-			&& helm template "$CHART_ROOT" ${HELM_ARGS[@]} 2>&1 | bat --language yaml --color always \
-			|| helm template "$CHART_ROOT" ${HELM_ARGS[@]} | grep -v '^# Source:.*$' \
-			;
-
-		return $EXIT_CODE
-	}
-
-	[ $TEMPLATE_OUTPUT ] && {
-		KUBEVAL_RAW=$(echo $TEMPLATE_OUTPUT | kubeval --schema-location https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master)
-		true
-	} || {
-		TEMPLATE_OUTPUT="---\nerror: chart or '$(basename $(dirname $TEMPLATE_FILENAME))/$(basename $TEMPLATE_FILENAME)' invalid"
-		KUBEVAL_RAW="no template output; kubeval skipped"
-
-		[ $USE_CHART_ROOT ] && [[ $USE_CHART_ROOT -eq 1 ]] || {
-			DEBUG_OUTPUT="$(helm template "$CHART_ROOT" ${HELM_ARGS[@]} --debug 2>&1 >/dev/null)"
-		}
-	}
-
-	TEMPLATE_OUTPUT="$TEMPLATE_OUTPUT
----
-debug: |
-$(echo $DEBUG_OUTPUT | sed 's/^/  /g')
-
-kubeval: |
-$(echo $KUBEVAL_RAW | sed 's/^/  /g')
-
-lint: |
-$(helm lint $CHART_ROOT ${HELM_ARGS[@]} 2>&1 | sed 's/^/  /g')
-"
-
-	[[ $COLORIZE -eq 1 ]] && {
-		echo $TEMPLATE_OUTPUT | bat --language yaml --color always
-	} || {
-		echo $TEMPLATE_OUTPUT
-	}
-
-	return $EXIT_CODE
-}

zsh/lib/helm/validate.module.zsh

@@ -1,95 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=(yq)
-REQUIRED_ENV+=()
-
-#####################################################################
-
-HELM__VALIDATE() {
-	[ ! $USAGE ] && USAGE="
-		usage:
-
-		environment
-		  TEMPLATE_FILENAME   target template filename
-
-		Smart helm-detection / validator which determines the helm
-		chart root and other details given a particular filename.
-	"
-
-	[ $TEMPLATE_FILENAME ] && [ -f "$TEMPLATE_FILENAME" ] || {
-		ERROR 'must provide a template filename'
-		return 1
-	}
-
-	_HELM__GET_CHART_ROOT
-	[ $CHART_ROOT ] && [ -d "$CHART_ROOT" ] || {
-		ERROR 'unable to determine helm root; is this a helm template file?'
-		return 1
-	}
-
-	CHART_NAME=$(YQ -r .name "$CHART_ROOT/Chart.yaml")
-
-	[[ $TEMPLATE_FILENAME =~ values.*.yaml$ ]] && {
-		HELM_ARGS+=(--values $TEMPLATE_FILENAME)
-		USE_CHART_ROOT=1
-	}
-
-	[[ $TEMPLATE_FILENAME =~ tests/.*.yaml$ ]] && {
-		HELM_ARGS+=(--values $TEMPLATE_FILENAME)
-		USE_CHART_ROOT=1
-	}
-	[[ $TEMPLATE_FILENAME =~ .tpl$ ]] \
-		&& USE_CHART_ROOT=1
-
-	[[ $(dirname $TEMPLATE_FILENAME) =~ ^$CHART_ROOT$ ]] \
-		&& USE_CHART_ROOT=1
-	
-	_HELM__GET_DEFAULT_VALUES_ARGS
-
-	return 0
-}
-
-_HELM__GET_CHART_ROOT() {
-	local SEARCH_DIR=$(dirname "$TEMPLATE_FILENAME")
-	while [ ! $CHART_ROOT ] && [[ ! $SEARCH_DIR =~ ^/$ ]]
-	do
-		[ -f "$SEARCH_DIR/Chart.yaml" ] && CHART_ROOT="$SEARCH_DIR" && return 0
-		SEARCH_DIR="$(dirname "$SEARCH_DIR")"
-	done
-
-	return 1
-}
-
-_HELM__GET_DEFAULT_VALUES_ARGS() {
-	for F in \
-		"$CHART_ROOT/tests/default.yaml" \
-		"$CHART_ROOT/values.test.yaml" \
-		"$CHART_ROOT/values.yaml" \
-		;
-	do
-		[ -f "$F" ] && HELM_ARGS=(--values "$F" $HELM_ARGS)
-	done
-
-	for LOCAL_REPOSITORY in $(\
-		cat "$CHART_ROOT/Chart.yaml" \
-			| YQ -r '.dependencies[] | .repository' \
-			| grep '^file://' \
-			| sed 's|file://||' \
-		)
-	do
-		[[ $LOCAL_REPOSITORY =~ ^[/~] ]] \
-			&& LOCAL_REPOSITORY_ROOT="$LOCAL_REPOSITORY" \
-			|| LOCAL_REPOSITORY_ROOT="$CHART_ROOT/$LOCAL_REPOSITORY" \
-			;
-
-		for F in \
-			"$LOCAL_REPOSITORY_ROOT/tests/default.yaml" \
-			"$LOCAL_REPOSITORY_ROOT/values.test.yaml" \
-			"$LOCAL_REPOSITORY_ROOT/values.yaml" \
-			;
-		do
-			[ -f "$F" ] && HELM_ARGS=(--values "$F" $HELM_ARGS)
-		done
-	done
-}
-

zsh/lib/import.driver.zsh

@@ -1,156 +0,0 @@
-[[ $SCWRYPTS_IMPORT_DRIVER_READY -eq 1 ]] && return 0
- ###################################################################
-#                                                                   #
-# usage: use [OPTIONS ...] zsh/module/path                          #
-#                                                                   #
- ###################################################################
-#                                                                   #
-# OPTIONS:                                                          #
-#                                                                   #
-#   -g, --group          lookup library root from friendly group    #
-#                        name (requires configuration)              #
-#                        (default: scwrypts)                        #
-#                                                                   #
-#   -r, --library-root   fully qualified path to a library root     #
-#                                                                   #
-#   --check-environment  check environment immediately rather than  #
-#                        wait for downstream CHECK_ENVIRONMENT call #
-#                                                                   #
-#                                                                   #
-# Allows for import-style library loading in zsh. No matter what    #
-# scwrypt is run, this function (and required helpers) are *also*   #
-# loaded, ensuring that 'use' is always available in scwrypts       #
-# context.                                                          #
-#                                                                   #
-#                                                                   #
-# Friendly group-names can be configured by setting the variable    #
-# 'SCWRYPTS_LIBRARY_ROOT__<group-name>' to the fully qualified path #
-# to the root directory of the modules library.                     #
-#                                                                   #
-#                                                                   #
- ###################################################################
-
-source "${0:a:h}/config.zsh"
-
-use() {
-	local SCWRYPTS_LIBRARY SCWRYPTS_LIBRARY_ROOT SCWRYPTS_LIBRARY_GROUP
-	local DEFER_ENVIRONMENT_CHECK=true
-
-	while [[ $# -gt 0 ]]
-	do
-		case $1 in
-			-g | --group )
-				[ $SCWRYPTS_LIBRARY_ROOT ] && ERROR 'specify only one of {(-g), (-r)}'
-				SCWRYPTS_LIBRARY_GROUP=$2
-				shift 1
-				;;
-			-r | --library-root )
-				[ $SCWRYPTS_LIBRARY_GROUP ] && ERROR 'specify only one of {(-g), (-r)}'
-				SCWRYPTS_LIBRARY_ROOT=$2
-				shift 1
-				;;
-			-c | --check-environment )
-				DEFER_ENVIRONMENT_CHECK=false
-				;;
-			* )
-				[ ! $SCWRYPTS_LIBRARY ] \
-					&& SCWRYPTS_LIBRARY=$1 \
-					|| ERROR 'too many arguments; expected exactly 1 argument' \
-
-				;;
-		esac
-		shift 1
-	done
-
-	[ ! $SCWRYPTS_LIBRARY ] && ERROR 'no library specified for import'
-
-	: \
-		&& [ ! $SCWRYPTS_LIBRARY_GROUP ] \
-		&& [ ! $SCWRYPTS_LIBRARY_ROOT  ] \
-		&& SCWRYPTS_LIBRARY_GROUP=scwrypts
-
-	[ ! $SCWRYPTS_LIBRARY_ROOT ] && SCWRYPTS_LIBRARY_ROOT=$(GET_SCWRYPTS_LIBRARY_ROOT)
-	[ ! $SCWRYPTS_LIBRARY_ROOT ] && ERROR "unable to determine library root from group name '$SCWRYPTS_LIBRARY_GROUP'"
-
-	#####################################################################
-
-	local LIBRARY_FILE LIBRARY_FILE_TEMP
-
-	[ ! $LIBRARY_FILE ] \
-		&& LIBRARY_FILE_TEMP="$SCWRYPTS_LIBRARY_ROOT/$SCWRYPTS_LIBRARY.module.zsh" \
-		&& [ -f "$LIBRARY_FILE_TEMP" ] \
-		&& LIBRARY_FILE="$LIBRARY_FILE_TEMP"
-
-	[ ! $LIBRARY_FILE ] \
-		&& LIBRARY_FILE_TEMP="$SCWRYPTS_LIBRARY_ROOT/$SCWRYPTS_LIBRARY/$(echo $SCWRYPTS_LIBRARY | sed 's/.*\///').module.zsh" \
-		&& [ -f "$LIBRARY_FILE_TEMP" ] \
-		&& LIBRARY_FILE="$LIBRARY_FILE_TEMP" \
-
-	[ ! $LIBRARY_FILE ] \
-		&& ERROR "no such library '$SCWRYPTS_LIBRARY_GROUP/$SCWRYPTS_LIBRARY'"
-
-	#####################################################################
-
-	CHECK_ERRORS --no-fail || {
-		((IMPORT_ERRORS+=1))
-		return 1
-	}
-
-	#####################################################################
-
-	IS_LOADED && return 0
-
-	source "$LIBRARY_FILE" || {
-		((IMPORT_ERRORS+=1))
-		ERROR "import error for '$SCWRYPTS_LIBRARY_GROUP/$SCWRYPTS_LIBRARY'"
-		return 1
-	}
-
-	[[ $DEFER_ENVIRONMENT_CHECK =~ false ]] && {
-		CHECK_ENVIRONMENT || {
-			((IMPORT_ERRORS+=1))
-			ERROR "import error for '$SCWRYPTS_LIBRARY_GROUP/$SCWRYPTS_LIBRARY'"
-			return 1
-		}
-	}
-
-	IS_LOADED --set
-}
-
-GET_SCWRYPTS_LIBRARY_ROOT() {
-	local ROOT
-
-	ROOT=$(eval echo '$SCWRYPTS_LIBRARY_ROOT__'$SCWRYPTS_LIBRARY_GROUP)
-	[ $ROOT ] && echo $ROOT && return 0
-
-	[[ $(eval echo '$SCWRYPTS_TYPE__'$SCWRYPTS_LIBRARY_GROUP) =~ zsh ]] \
-		&& ROOT=$(eval echo '$SCWRYPTS_ROOT__'$SCWRYPTS_LIBRARY_GROUP/lib) \
-		|| ROOT=$(eval echo '$SCWRYPTS_ROOT__'$SCWRYPTS_LIBRARY_GROUP/zsh/lib) \
-		;
-	[ $ROOT ] && echo $ROOT && return 0
-}
-
-IS_LOADED() {
-	local VARIABLE_NAME="SCWRYPTS_LIBRARY_LOADED__${SCWRYPTS_LIBRARY_GROUP}__$(echo $SCWRYPTS_LIBRARY | sed 's|[/-]|_|g')"
-
-	[[ $1 =~ ^--set$ ]] \
-		&& eval $VARIABLE_NAME=1 \
-
-	[[ $(eval echo '$'$VARIABLE_NAME || echo 0) -eq 1 ]]
-}
-
-
-# temporary definitions for first load
-CHECK_ERRORS()      { return 0; unset -f CHECK_ERRORS; }
-CHECK_ENVIRONMENT() { return 0; unset -f CHECK_ENVIRONMENT; }
-ERROR()             { echo $@ >&2; exit 1; }
-
-#####################################################################
-
-# ensures that zsh/utils and zsh/scwrypts/meta are always present!
-
-use utils
-use scwrypts/meta
-
-#####################################################################
-SCWRYPTS_IMPORT_DRIVER_READY=1

zsh/lib/media/youtube.module.zsh

@@ -1,48 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=(
-	ffmpeg
-	youtube-dl
-)
-
-REQUIRED_ENV+=()
-
-#####################################################################
-
-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/lib/misc/k8s-helper.plugin.zsh

@@ -1,26 +0,0 @@
-K8s_HELPER__NAMESPACE_KEY='k8s-helper'
-K8s_HELPER__REDIS_HOST=127.0.0.1
-K8s_HELPER__REDIS_PORT=6379
-K8s_HELPER__REDIS_AUTH=
-
-REDIS_CLI() {
-	local ARGS=()
-	[ $K8s_HELPER__REDIS_HOST ] && ARGS+=(-h $K8s_HELPER__REDIS_HOST)
-	[ $K8s_HELPER__REDIS_PORT ] && ARGS+=(-p $K8s_HELPER__REDIS_PORT)
-	[ $K8s_HELPER__REDIS_AUTH ] && ARGS+=(-a $K8s_HELPER__REDIS_AUTH --no-auth-warning)
-	redis-cli ${ARGS[@|} $@
-}
-
-K8s_HELPER__SET_NAMESPACE() {
-	REDIS_CLI hset $K8s_HELPER__NAMESPACE_KEY namespace $@
-}
-
-K8s_HELPER__GET_NAMESPACE() {
-	REDIS_CLI hget $K8s_HELPER__NAMESPACE_KEY namespace
-}
-
-K8s_HELPER__KUBECTL() {
-	kubectl -n $(K8s_HELPER__GET_NAMESPACE) $@
-}
-
-alias k='K8s_HELPER__PREFIX '

zsh/lib/misc/tally.module.zsh

@@ -1,106 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=()
-REQUIRED_ENV+=()
-
-#####################################################################
-
-TALLY_USE_REDIS=false  # maybe someday
-TALLY_PATH="$SCWRYPTS_DATA_PATH/tally"
-
-#####################################################################
-
-TALLY() {
-	local USAGE="
-		usage: [...options...]
-
-		options:
-		  -c, --increment-count   increment the tally by this much (default 1)
-		  -n, --tally-name        name of tally system (default 'default')
-
-		  -g, --get     only output the current value
-		  -s, --set     set the tally to a specific value
-		  -r, --reset   set the tally back to zero
-
-		  --raw   only output the tally value
-
-		  -h, --help   print this dialogue and exit
-
-		Simple tally mark system; keep track of a count.
-	"
-
-	local INCREMENT_COUNT=1
-	local TALLY_NAME=default
-	local RAW=false
-
-	local SET_VALUE=
-
-	while [[ $# -gt 0 ]]
-	do
-		case $1 in
-			-c | --increment-count ) INCREMENT_COUNT=$2; shift 1 ;;
-			-n | --tally-name      ) TALLY_NAME=$2; shift 1 ;;
-
-			-g | --get   ) INCREMENT_COUNT=0 ;;
-
-			-s | --set   ) SET_VALUE=$2; shift 1 ;;
-			-r | --reset ) SET_VALUE=0 ;;
-
-			--raw ) RAW=true ;;
-
-			-h | --help ) USAGE; return 0 ;;
-
-			* ) ERROR "unknown argument '$1'" ;;
-		esac
-		shift 1
-	done
-
-	[ $TALLY_NAME ] && echo "$TALLY_NAME" | grep -qv '/' \
-		|| ERROR "invalid tally name '$TALLY_NAME'"
-
-	local TALLY_FILENAME="$TALLY_PATH/$TALLY_NAME.txt"
-
-	CHECK_ERRORS --no-fail || return 1
-
-	##########################################
-
-	local NEW_VALUE CURRENT_VALUE=0
-	[ $SET_VALUE ] && NEW_VALUE=$SET_VALUE || {
-		[ -f "$TALLY_FILENAME" ] && {
-			CURRENT_VALUE=$(cat "$TALLY_FILENAME" | tail -n1 | grep '^[0-9]\+')
-		}
-		
-		[ $CURRENT_VALUE ] || {
-			ERROR "malformed tally file '$TALLY_FILENAME'; aborting"
-			return 1
-		}
-
-		NEW_VALUE=$(($CURRENT_VALUE + $INCREMENT_COUNT))
-	}
-
-	##########################################
-
-	local TALLY_DIR="$(dirname "$TALLY_FILENAME")"
-
-	[ -d "$TALLY_DIR" ] || mkdir -p "$TALLY_DIR"
-	[ -d "$TALLY_DIR" ] || {
-		ERROR "unable to write to '$TALLY_DIR'; aborting"
-		return 1
-	}
-
-	echo "# autogenerated tally file; avoid direct modification\n$NEW_VALUE" > "$TALLY_FILENAME" || {
-		ERROR "failed to write to '$TALLY_FILENAME': aborting"
-		return 1
-	}
-
-	##########################################
-	
-	case $RAW in
-		true  ) printf "$NEW_VALUE" ;;
-		false )
-			case $TALLY_NAME in
-				default ) SUCCESS "current tally : $NEW_VALUE" ;;
-				*       ) SUCCESS "$TALLY_NAME : $NEW_VALUE" ;;
-			esac
-	esac
-}

zsh/lib/office/latex.module.zsh

@@ -1,44 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=(
-	rg
-	pdflatex
-)
-
-REQUIRED_ENV+=()
-
-#####################################################################
-
-LATEX__GET_MAIN_FILENAME() {
-	local FILENAME=$(SCWRYPTS__GET_REALPATH "$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"
-}
-
-LATEX__CHECK_IS_MAIN_FILE() {
-	[ ! $FILENAME ] && return 1
-	grep -q 'documentclass' $FILENAME 2>/dev/null && echo $FILENAME || return 3
-}
-
-LATEX__GET_PDF() {
-	local FILENAME=$(LATEX__GET_MAIN_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
-}

zsh/lib/office/memo.module.zsh

@@ -1,15 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=()
-REQUIRED_ENV+=()
-
-#####################################################################
-
-set +o noglob
-
-MEMO__FILETYPE=md
-MEMO__DIR="$SCWRYPTS_DATA_PATH/memo"
-
-[ ! -d $MEMO__DIR ] && mkdir -p $MEMO__DIR
-
-MEMO__LIST_ALL() { ls $MEMO__DIR | sed "s/\.$MEMO__FILETYPE$//" | sort; }

zsh/lib/redis/redis.module.zsh

@@ -1,43 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=(
-	redis-cli
-)
-
-REQUIRED_ENV+=()
-
-#####################################################################
-
-REDIS() {
-	[[ ${#ARGS[@]} -eq 0 ]] && REDIS__SET_LOGIN_ARGS $@
-
-	redis-cli ${#ARGS[@]}
-}
-
-
-REDIS__SET_LOGIN_ARGS() {
-	while [[ $# -gt 0 ]]
-	do
-		case $1 in
-			--host ) _ARGS+=(-h $2); _HOST="$2"; shift 1 ;;
-			--port ) _ARGS+=(-p $2); _PORT="$2"; shift 1 ;;
-			--pass ) _ARGS+=(-a $2); _PASS="$2"; shift 1 ;;
-
-			--file ) _FILE="$2"; shift 1 ;;
-
-			* ) _ARGS+=($1) ;;
-		esac
-		shift 1
-	done
-
-	[ $_FILE ] && [ ! -f "$_FILE" ] && {
-		ERROR "no such file '$_FILE'"
-		exit 1
-	}
-
-	return 0
-}
-
-REDIS__ENABLED() {
-	REDIS ping 2>&1 | grep -qi pong
-}

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

@@ -1,126 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=()
-REQUIRED_ENV+=()
-
-use utils
-
-#####################################################################
-
-SCWRYPTS__SELECT_ENV() {
-	SCWRYPTS__GET_ENV_NAMES | FZF 'select an environment'
-}
-
-SCWRYPTS__SELECT_OR_CREATE_ENV() {
-	SCWRYPTS__GET_ENV_NAMES | FZF_USER_INPUT 'select / create an environment'
-}
-
-SCWRYPTS__GET_ENV_FILES() {
-	local NAME="$1"
-
-	local FILENAMES=$(
-	for GROUP in ${SCWRYPTS_GROUPS[@]}
-	do
-		echo "$SCWRYPTS_ENV_PATH/$GROUP/$NAME"
-	done
-	)
-
-	echo $FILENAMES | grep 'environments/scwrypts/'
-	echo $FILENAMES | grep -v 'environments/scwrypts/' | sort
-
-	SCWRYPTS__GET_ENV_NAMES | grep -q $NAME \
-		|| { ERROR "no environment '$NAME' exists"; return 1; }
-}
-
-SCWRYPTS__GET_ENV_FILE() {
-	local NAME="$1"
-	local GROUP="$2"
-
-	[ ! $GROUP ] && { ERROR 'must provide group'; return 1; }
-
-	echo "$SCWRYPTS_ENV_PATH/$GROUP/$NAME"
-
-	SCWRYPTS__GET_ENV_NAMES | grep -q $NAME \
-		|| { ERROR "no environment '$NAME' exists"; return 1; }
-
-	[ -f "$SCWRYPTS_ENV_PATH/$GROUP/$NAME" ] || {
-		mkdir -p "$SCWRYPTS_ENV_PATH/$GROUP"
-		touch "$SCWRYPTS_ENV_PATH/$GROUP/$NAME"
-	}
-	[ -f "$SCWRYPTS_ENV_PATH/$GROUP/$NAME" ] \
-		|| { ERROR "missing environment file for '$GROUP/$NAME'"; return 2; }
-}
-
-SCWRYPTS__GET_ENV_TEMPLATE_FILES() {
-	local GROUP
-	for GROUP in ${SCWRYPTS_GROUPS[@]}
-	do
-		eval echo '$SCWRYPTS_ROOT__'$GROUP/.config/env.template
-	done
-}
-
-SCWRYPTS__GET_ENV_NAMES() {
-	SCWRYPTS__INIT_ENVIRONMENTS || {
-		ERROR 'environment initialization error'
-		return 1
-	}
-	[ $REQUIRED_ENVIRONMENT_REGEX ] && {
-		ls "$SCWRYPTS_ENV_PATH/scwrypts" | grep "$REQUIRED_ENVIRONMENT_REGEX" | sort -r
-	} || {
-		ls "$SCWRYPTS_ENV_PATH/scwrypts" | sort -r
-	}
-}
-
-SCWRYPTS__INIT_ENVIRONMENTS() {
-	[ ! -d "$SCWRYPTS_ENV_PATH" ] && mkdir -p "$SCWRYPTS_ENV_PATH"
-	[[ $(ls "$SCWRYPTS_ENV_PATH" | wc -l) -gt 0 ]] && return 0
-
-	STATUS "initializing environments for scwrypts"
-
-	local BASIC_ENV
-	for BASIC_ENV in local dev prod
-	do
-		for GROUP in ${SCWRYPTS_GROUPS[@]}
-		do
-			mkdir -p "$SCWRYPTS_ENV_PATH/$GROUP"
-			GENERATE_TEMPLATE > "$SCWRYPTS_ENV_PATH/$GROUP/$BASIC_ENV"
-		done
-	done
-}
-
-#####################################################################
-
-_SED() { sed --follow-symlinks $@; }
-
-GENERATE_TEMPLATE() {
-    [ ! $GROUP ] && { ERROR 'must provide GROUP'; return 1; }
-    DIVIDER='#####################################################################'
-    HEADER='### scwrypts runtime configuration '
-    [[ GROUP =~ ^scwrypts$ ]] || HEADER="${HEADER}(group '$GROUP') "
-    printf "#!/bin/zsh\n$DIVIDER\n$HEADER%s\n$DIVIDER\n" "${DIVIDER:${#$(echo "$HEADER")}}"
-
-    local FILE CONTENT
-    local VARIABLE DESCRIPTION
-    FILE=$(eval echo '$SCWRYPTS_ROOT__'$GROUP/.config/env.template)
-
-    CONTENT=$(GET_VARIABLE_NAMES "$FILE" | sed 's/^/export /; s/$/=/')
-
-    while read DESCRIPTION_LINE
-    do
-        VARIABLE=$(echo $DESCRIPTION_LINE | sed 's/ \+| .*$//')
-        DESCRIPTION=$(echo $DESCRIPTION_LINE | sed 's/^.* | //')
-        [ ! $DESCRIPTION ] && continue
-
-        CONTENT=$(echo "$CONTENT" | sed "/^export $VARIABLE=/i #" | sed "/^export $VARIABLE=/i # $DESCRIPTION")
-    done < <(_SED -n '/^[^ ]\+ \+| /p' "$FILE.descriptions")
-
-    echo "$CONTENT" | sed 's/^#$//'
-}
-
-GET_VARIABLE_NAMES() {
-	local FILE="$1"
-	grep '^export' "$FILE" \
-		| sed 's/^export //; s/=.*//' \
-		| grep -v '__[a-z]\+$' \
-		;
-}

zsh/lib/scwrypts/meta.module.zsh

@@ -1,23 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=()
-REQUIRED_ENV+=()
-
-use scwrypts/environment-files
-use scwrypts/run
-
-#####################################################################
-
-SCWRYPTS__RUN() {  # context wrapper to run scwrypts within scwrypts
-	local EXIT_CODE=0
-	((SUBSCWRYPT+=1))
-
-	SCWRYPTS_LOG_LEVEL=$SCWRYPTS_LOG_LEVEL \
-	SUBSCWRYPT=$SUBSCWRYPT \
-		$SCWRYPTS_ROOT__scwrypts/scwrypts $@
-
-	EXIT_CODE=$?
-
-	((SUBSCWRYPT-=1))
-	return $EXIT_CODE
-}

zsh/lib/scwrypts/run.module.zsh

@@ -1,195 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=()
-REQUIRED_ENV+=()
-
-use scwrypts/environment-files
-
-#####################################################################
-
-SCWRYPTS__GET_AVAILABLE_SCWRYPTS() {
-	local TYPE_COLOR='\033[0;37m'
-	local GROUP GROUP_PATH GROUP_COLOR LOOKUP_PIDS=()
-	{
-	echo 'NAME^TYPE^GROUP'
-	for GROUP in ${SCWRYPTS_GROUPS[@]}
-	do
-		GROUP_PATH=$(eval echo '$SCWRYPTS_ROOT__'$GROUP)
-		GROUP_COLOR=$(eval echo '$SCWRYPTS_COLOR__'$GROUP)
-
-		GROUP_TYPE=$(eval echo '$SCWRYPTS_TYPE__'$GROUP)
-		[ $GROUP_TYPE ] && MINDEPTH=1 && GROUP_TYPE="$GROUP_TYPE\\/" || MINDEPTH=2
-
-		command -v SCWRYPTS__LIST_AVAILABLE_SCWRYPTS__$GROUP >/dev/null 2>&1 \
-			&& LOOKUP=SCWRYPTS__LIST_AVAILABLE_SCWRYPTS__$GROUP \
-			|| LOOKUP=SCWRYPTS__LIST_AVAILABLE_SCWRYPTS__scwrypts \
-			;
-
-		{
-		$LOOKUP \
-			| sed "s|\\([^/]*\\)/\(.*\)$|$(printf $__COLOR_RESET)\\2^$(printf $TYPE_COLOR)\\1^$(printf $GROUP_COLOR)$GROUP$(printf $__COLOR_RESET)|" \
-		} &
-		LOOKUP_PIDS+=($!)
-	done
-	for p in ${LOOKUP_PIDS[@]}; do wait $p; done
-	} | column -t -s '^'
-}
-
-SCWRYPTS__SEPARATE_SCWRYPT_SELECTION() {
-	set -- $(echo $@ | sed -e 's/\x1b\[[0-9;]*m//g')
-	while [[ $# -gt 0 ]]
-	do
-		[ ! $NAME  ] && NAME=$1  && shift 1 && continue
-		[ ! $TYPE  ] && TYPE=$1  && shift 1 && continue
-		[ ! $GROUP ] && GROUP=$1 && shift 1 && continue
-		shift 1
-	done
-}
-
-SCWRYPTS__LIST_AVAILABLE_SCWRYPTS__scwrypts() {
-	# implementation should output lines of the following format:
-	# "${SCWRYPT_TYPE}/${SCWRYPT_NAME}"
-	cd "$GROUP_PATH"
-	find . -mindepth $MINDEPTH -type f -executable \
-		| grep -v '\.git' \
-		| grep -v 'node_modules' \
-		| sed "s/^\\.\\///; s/\\.[^.]*$//; s/^/$GROUP_TYPE/" \
-		| grep -v '^plugins/' \
-		;
-}
-
-SCWRYPTS__GET_RUNSTRING() {
-	local GROUP_PATH=$(eval echo '$SCWRYPTS_ROOT__'$SCWRYPT_GROUP)
-	local RUNSTRING
-
-	[ $SCWRYPT_NAME ] && [ $SCWRYPT_TYPE ] && [ $SCWRYPT_GROUP ] || {
-		ERROR 'missing required information to get runstring'
-		return 1
-	}
-
-	[ $ENV_REQUIRED ] && [[ $ENV_REQUIRED -eq 1 ]] && [ ! $ENV_NAME ] && {
-		ERROR 'missing required information to get runstring'
-		return 1
-	}
-
-	[ ! $RUNSTRING ] && typeset -f SCWRYPTS__GET_RUNSTRING__${SCWRYPT_GROUP}__${SCWRYPT_TYPE} >/dev/null 2>&1 && {
-		RUNSTRING=$(SCWRYPTS__GET_RUNSTRING__${SCWRYPT_GROUP}__${SCWRYPT_TYPE})
-		[ ! $RUNSTRING ] && {
-			ERROR "SCWRYPTS__GET_RUNSTRING__${SCWRYPT_GROUP}__${SCWRYPT_TYPE} error"
-			return 2
-		}
-	}
-
-	[ ! $RUNSTRING ] && typeset -f SCWRYPTS__GET_RUNSTRING__${SCWRYPT_TYPE} >/dev/null 2>&1 && {
-		RUNSTRING=$(SCWRYPTS__GET_RUNSTRING__${SCWRYPT_TYPE})
-		[ ! $RUNSTRING ] && {
-			ERROR "SCWRYPTS__GET_RUNSTRING__${SCWRYPT_TYPE} error"
-			return 3
-		}
-	}
-
-	[ ! $RUNSTRING ] && {
-		ERROR "type ${SCWRYPT_TYPE} (group ${SCWRYPT_GROUP}) has no supported runstring generator"
-		return 4
-	}
-
-	RUNSTRING="SCWRYPTS_ENV=$ENV_NAME; $RUNSTRING"
-	RUNSTRING="source $SCWRYPTS_ROOT__scwrypts/zsh/lib/import.driver.zsh; $RUNSTRING"
-
-	local _VIRTUALENV=$(eval echo '$SCWRYPTS_VIRTUALENV_PATH__'$SCWRYPT_GROUP'/$SCWRYPT_TYPE/bin/activate')
-	[ -f $_VIRTUALENV ] && RUNSTRING="source $_VIRTUALENV; $RUNSTRING"
-
-	local G SCWRYPTSENV
-	for G in ${SCWRYPTS__GROUPS[@]}
-	do
-		SCWRYPTSENV="$SCWRYPTS_ENV_PATH/$G/$ENV_NAME"
-		[ -f $SCWRYPTSENV ] && RUNSTRING="source $SCWRYPTSENV; $RUNSTRING"
-	done
-
-	echo "$RUNSTRING"
-}
-
-SCWRYPTS__GET_RUNSTRING__zsh() {
-	__CHECK_DEPENDENCY zsh || return 1
-
-	local SCWRYPT_FILENAME
-
-	[ $(eval echo '$SCWRYPTS_TYPE__'$SCWRYPT_GROUP) ] \
-		&& SCWRYPT_FILENAME="$GROUP_PATH/$SCWRYPT_NAME" \
-		|| SCWRYPT_FILENAME="$GROUP_PATH/$SCWRYPT_TYPE/$SCWRYPT_NAME" \
-		;
-
-	SCWRYPTS__GET_RUNSTRING__zsh__generic "$SCWRYPT_FILENAME"
-	return 0
-}
-
-SCWRYPTS__GET_RUNSTRING__zsh__generic() {
-	# boilerplate to allow
-	#    - multiflag splitting (e.g. -abc = -a -b -c)
-	#    - help flag injection (e.g. -h | --help)
-	#    - default USAGE definition (allows USAGE__options style usage definition)
-	#    - required MAIN() function wrapping
-	#
-	# this is available automatically in SCWRYPTS_GROUP declaration contexts
-	# (e.g. my-group.scwrypts.zsh)
-	local ZSH_FILENAME="$1"
-	[ $ZSH_FILENAME ] || {
-		ERROR '
-			to use SCWRYPTS__GET_RUNSTRING__zsh__generic, you must provide a
-			ZSH_FILENAME (arg $1) where the MAIN function is defined
-			'
-		return 1
-	}
-	printf "
-		source '$SCWRYPT_FILENAME'
-		CHECK_ENVIRONMENT
-		ERRORS=0
-
-		export USAGE=\"
-			usage: -
-
-			args: -
-
-			options: -
-			  -h, --help      display this message and exit
-
-			description: -
-		\"
-
-		[ ! \$USAGE__usage ] && export USAGE__usage='[...options...]'
-
-		() {
-			local MAIN_ARGS=()
-			local VARSPLIT
-			while [[ \$# -gt 0 ]]
-			do
-				case \$1 in
-					-[a-z][a-z]* )
-						VARSPLIT=\$(echo \"\$1 \" | sed 's/^\\\\(-.\\\\)\\\\(.*\\\\) /\\\\1 -\\\\2/')
-						set -- throw-away \$(echo \" \$VARSPLIT \") \${@:2}
-						;;
-					-h | --help    ) USAGE; exit 0 ;;
-					* ) MAIN_ARGS+=(\$1) ;;
-				esac
-				shift 1
-			done
-			MAIN \${MAIN_ARGS[@]}
-		} "
-}
-
-SCWRYPTS__GET_RUNSTRING__py() {
-	__CHECK_DEPENDENCY python || return 1
-	CURRENT_PYTHON_VERSION=$(python --version | sed 's/^[^0-9]*\(3\.[^.]*\).*$/\1/')
-	echo $SCWRYPTS_PREFERRED_PYTHON_VERSIONS__scwrypts | grep -q $CURRENT_PYTHON_VERSION || {
-		WARNING "only tested on the following python versions: $(printf ', %s.x' ${SCWRYPTS_PREFERRED_PYTHON_VERSIONS__scwrypts[@]} | sed 's/^, //')"
-		WARNING 'compatibility may vary'
-	}
-
-	echo "cd $GROUP_PATH; python -m $(echo $SCWRYPT_TYPE/$SCWRYPT_NAME | sed 's/\//./g; s/\.py$//; s/\.\.//')"
-}
-
-SCWRYPTS__GET_RUNSTRING__zx() {
-	__CHECK_DEPENDENCY zx || return 1
-
-	echo "export FORCE_COLOR=3; cd $GROUP_PATH; ./$SCWRYPT_TYPE/$SCWRYPT_NAME.js"
-}

zsh/lib/scwrypts/scwrypts.module.zsh

@@ -1,15 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=()
-REQUIRED_ENV+=()
-
-#####################################################################
-
-SCWRYPTS__GET_REALPATH() {
-	[[ ! $1 =~ ^[/~] ]] \
-		&& echo $(readlink -f "$EXECUTION_DIR/$1") \
-		|| echo "$1" \
-		;
-
-	return 0
-}

zsh/lib/scwrypts/virtualenv.module.zsh

@@ -1,173 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=()
-REQUIRED_ENV+=()
-
-use utils
-
-#####################################################################
-
-AVAILABLE_VIRTUALENVS=(py zx)
-
-REFRESH_VIRTUALENV() {
-	local GROUP="$1"
-	local TYPE="$2"
-	local VIRTUALENV_PATH="$(_VIRTUALENV__GET_PATH)"
-
-	[ ! $TYPE ] && { ERROR 'no virtualenv type specified'; return 1; }
-
-	STATUS "refreshing $GROUP/$TYPE virtualenv"
-	DELETE_VIRTUALENV $GROUP $TYPE \
-		&& UPDATE_VIRTUALENV $GROUP $TYPE \
-		&& SUCCESS 'successfully refreshed virtualenv' \
-		|| { ERROR 'something went wrong during refresh (see above)'; return 1; } \
-		;
-}
-
-UPDATE_VIRTUALENV() {
-	local GROUP="$1"
-	local TYPE="$2"
-	local VIRTUALENV_PATH="$(_VIRTUALENV__GET_PATH)"
-
-	[ ! $TYPE ] && { ERROR 'no virtualenv type specified'; return 1; }
-
-	: \
-		&& which CREATE_VIRTUALENV__${GROUP}__${TYPE} >/dev/null 2>&1 \
-		&& which ACTIVATE_VIRTUALENV__${GROUP}__${TYPE} >/dev/null 2>&1 \
-		&& which UPDATE_VIRTUALENV__${GROUP}__${TYPE} >/dev/null 2>&1 \
-		&& which DEACTIVATE_VIRTUALENV__${GROUP}__${TYPE} >/dev/null 2>&1 \
-		|| { STATUS "no virtualenv available for $GROUP/$TYPE; skipping"; return 0; }
-
-	STATUS "updating $GROUP/$TYPE virtualenv" \
-		&& CREATE_VIRTUALENV__${GROUP}__${TYPE} \
-		&& ACTIVATE_VIRTUALENV__${GROUP}__${TYPE} \
-		&& UPDATE_VIRTUALENV__${GROUP}__${TYPE} \
-		&& DEACTIVATE_VIRTUALENV__${GROUP}__${TYPE} \
-		&& SUCCESS "$GROUP/$TYPE virtualenv up-to-date" \
-		|| { ERROR "failed to update $GROUP/$TYPE virtualenv (see errors above)"; return 2; }
-}
-
-DELETE_VIRTUALENV() {
-	[ $CI ] && return 0
-
-	local GROUP="$1"
-	local TYPE="$2"
-	local VIRTUALENV_PATH="$(_VIRTUALENV__GET_PATH)"
-
-	[ ! $TYPE ] && { ERROR 'no virtualenv type specified'; return 1; }
-
-	STATUS "dropping $GROUP/$TYPE virtualenv artifacts"
-
-	[ ! -d $VIRTUALENV_PATH ] && {
-		SUCCESS "no $GROUP/$TYPE environment detected"
-		return 0
-	}
-
-	rm -rf $VIRTUALENV_PATH \
-		&& SUCCESS "succesfully cleaned up $GROUP/$TYPE virtualenv" \
-		|| { ERROR "unabled to remove '$VIRTUALENV_PATH'"; return 1; }
-}
-
-#####################################################################
-
-_VIRTUALENV__GET_PATH() {
-	local ENV_PATH="$(eval echo '$SCWRYPTS_VIRTUALENV_PATH__'$GROUP 2>/dev/null)"
-	[ ! $ENV_PATH ] && ENV_PATH="$SCWRYPTS_VIRTUALENV_PATH__scwrypts"
-
-	mkdir -p "$ENV_PATH/$TYPE" &>/dev/null
-
-	echo $ENV_PATH/$TYPE
-}
-
-#####################################################################
-
-CREATE_VIRTUALENV__scwrypts__py() {
-	[ $CI ] && return 0
-	[ -d $VIRTUALENV_PATH ] && return 0
-
-	DEPENDENCIES=(virtualenv) CHECK_ENVIRONMENT || return 1
-
-	STATUS 'creating python virtualenv'
-	local PY PYTHON
-	for PY in $(echo $SCWRYPTS_PREFERRED_PYTHON_VERSIONS__scwrypts)
-	do
-		which python$PY >/dev/null 2>&1 && {
-			PYTHON=$(which python$PY)
-			break
-		}
-	done
-	[ ! $PYTHON ] && {
-		ERROR 'python>=3.10 not available; skipping python env'
-		return 1
-	}
-
-	STATUS 'setting up virtualenv'
-	virtualenv $VIRTUALENV_PATH --python="$PYTHON" \
-		&& SUCCESS 'python virtualenv created' \
-		|| {
-			ERROR "unable to create '$VIRTUALENV_PATH' with '$PYTHON'"
-			return 2
-		}
-}
-
-ACTIVATE_VIRTUALENV__scwrypts__py() {
-	[ $CI ] && return 0
-	source $VIRTUALENV_PATH/bin/activate || {
-		ERROR "failed to activate virtualenv $GROUP/$TYPE; did create fail?"
-		return 1
-	}
-}
-
-UPDATE_VIRTUALENV__scwrypts__py() {
-	local PIP_INSTALL_ARGS=()
-
-	PIP_INSTALL_ARGS+=(--no-cache-dir)
-	PIP_INSTALL_ARGS+=(-r requirements.txt)
-
-	cd "$SCWRYPTS_ROOT__scwrypts/py"
-	pip install ${PIP_INSTALL_ARGS[@]}
-}
-
-DEACTIVATE_VIRTUALENV__scwrypts__py() {
-	deactivate >/dev/null 2>&1
-	return 0
-}
-
-##########################################
-
-CREATE_VIRTUALENV__scwrypts__zx() {
-	[ $CI ] && return 0
-	[ -d $VIRTUALENV_PATH ] && return 0
-
-	DEPENDENCIES=(nodeenv) CHECK_ENVIRONMENT || return 1
-
-	STATUS 'setting up nodeenv'
-	nodeenv $VIRTUALENV_PATH --node=$SCWRYPTS_NODE_VERSION__scwrypts \
-		&& SUCCESS 'node virtualenv created' \
-		|| {
-			ERROR "unable to create '$VIRTUALENV_PATH' with '$SCWRYPTS_NODE_VERSION__scwrypts'"
-			return 2
-		}
-}
-
-ACTIVATE_VIRTUALENV__scwrypts__zx() {
-	[ $CI ] && return 0
-	source $VIRTUALENV_PATH/bin/activate || {
-		ERROR "failed to activate virtualenv $GROUP/$TYPE; did create fail?"
-		return 1
-	}
-}
-
-UPDATE_VIRTUALENV__scwrypts__zx() {
-	local NPM_INSTALL_ARGS=()
-
-	[ $CI ] && NPM_INSTALL_ARGS+=(--ignore-scripts)
-
-	cd "$SCWRYPTS_ROOT__scwrypts/zx"
-	npm install ${NPM_INSTALL_ARGS[@]}
-}
-
-DEACTIVATE_VIRTUALENV__scwrypts__zx() {
-	deactivate_node >/dev/null 2>&1
-	return 0
-}

zsh/lib/system/config/config.module.zsh

@@ -1,18 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=()
-REQUIRED_ENV+=()
-
-#####################################################################
-
-DEFAULT_CONFIG="${0:a:h}/default.conf.zsh"
-
-SAFE_SYMLINKS=1
-
-# in case dotfiles.zsh is sourced; allows users 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/lib/system/config/default.conf.zsh

@@ -1,19 +0,0 @@
-#
-# 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/lib/system/desktop/notify.module.zsh

@@ -1,16 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=(
-	notify-send
-)
-
-REQUIRED_ENV+=()
-
-#####################################################################
-
-NOTIFY() {
-	local D=$DISPLAY
-	[ ! $D ] && D=:0
-
-	DISPLAY=$D notify-send "SCWRYPTS $SCWRYPT_NAME" $@
-}

zsh/lib/system/packages/git.module.zsh

@@ -1,78 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=(
-	git
-	make
-)
-
-REQUIRED_ENV+=()
-
-#####################################################################
-
-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/lib/system/vim/vim.module.zsh

@@ -1,11 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=(
-	vim
-)
-
-REQUIRED_ENV+=()
-
-#####################################################################
-
-VIM() { vim $@ </dev/tty >/dev/tty; }

zsh/lib/system/vim/vundle.module.zsh

@@ -1,53 +0,0 @@
-#####################################################################
-
-DEPENDENCIES+=()
-REQUIRED_ENV+=()
-
-use system/vim
-
-#####################################################################
-
-VUNDLE__PLUGIN_DIR="$HOME/.vim/bundle"
-VUNDLE__BUILD_DEFINITIONS="$SCWRYPTS_CONFIG_PATH/vundle.zsh"
-
-[ ! -f $VUNDLE__BUILD_DEFINITIONS ] && {
-	{
-		echo -e "#\n# Scwrypts Build Definitions\n#\n"
-	} > $VUNDLE__BUILD_DEFINITIONS
-}
-
-VUNDLE__PLUGIN_LIST=$(ls $VUNDLE__PLUGIN_DIR | grep -v 'Vundle.vim' | grep -v 'build.zsh')
-source $VUNDLE__BUILD_DEFINITIONS
-for PLUGIN in $(echo $VUNDLE__PLUGIN_LIST)
-do
-	which VUNDLE__BUILD__$PLUGIN >/dev/null 2>/dev/null || {
-		echo -e "\nVUNDLE__BUILD__$PLUGIN() {\n	# ... build steps from $HOME/.vim/$PLUGIN \n}" \
-			>> $VUNDLE__BUILD_DEFINITIONS
-		VUNDLE__BUILD__$PLUGIN() {}
-	}
-done
-
-#####################################################################
-
-VUNDLE__PLUGIN_INSTALL() {
-	VIM +PluginInstall +qall \
-		&& SUCCESS 'successfully installed Vundle.vim plugins' \
-		|| FAIL 1 'failed to install Vundle.vim plugins'
-}
-
-VUNDLE__REBUILD_PLUGINS() {
-	local ERRORS=0
-
-	local PLUGIN
-	for PLUGIN in $(echo $VUNDLE__PLUGIN_LIST)
-	do
-		cd "$VUNDLE__PLUGIN_DIR/$PLUGIN"
-		STATUS "building '$PLUGIN'"
-		VUNDLE__BUILD__$PLUGIN \
-			&& SUCCESS "finished building '$PLUGIN'" \
-			|| ERROR "failed to build '$PLUGIN' (see above)" \
-			;
-	done
-
-	return $ERRORS
-}

zsh/lib/utils/colors.zsh

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

zsh/lib/utils/credits.zsh

@@ -1,11 +0,0 @@
-__CREDITS() {
-	# scwrypts exclusive ("credits" pulled from README files)
-	[ ! $SCWRYPTS_ROOT ] && return 0
-
-	local COMMAND="$1"
-	[[ $COMMAND =~ - ]] && COMMAND=$(echo $COMMAND | sed 's/-/--/g')
-	cd $SCWRYPTS_ROOT
-	cat ./**/README.md \
-		| grep 'Generic Badge' \
-		| sed -n "s/.*Generic Badge.*-$COMMAND-.*(/(/p"
-}

zsh/lib/utils/dependencies.zsh

@@ -1,52 +0,0 @@
-__CHECK_DEPENDENCIES() {
-	local DEP ERRORS=0
-	local SCWRYPTS_LOG_LEVEL=1
-	[ ! $E ] && E=ERROR
-
-	DEPENDENCIES=($(echo $DEPENDENCIES | sed 's/ \+/\n/g' | sort -u))
-
-	for DEP in ${DEPENDENCIES[@]}; do __CHECK_DEPENDENCY $DEP || ((ERRORS+=1)); done
-	__CHECK_COREUTILS || ((ERRORS+=$?))
-
-	return $ERRORS
-}
-
-__CHECK_DEPENDENCY() {
-	local DEPENDENCY="$1"
-	[ ! $DEPENDENCY ] && return 1
-	command -v $DEPENDENCY >/dev/null 2>&1 || {
-		$E "application '$1' "$([[ $OPTIONAL -eq 1 ]] && echo preferred || echo required)" but not available on PATH $(__CREDITS $1)"
-		return 1
-	}
-
-	[[ $DEPENDENCY =~ ^yq$ ]] && {
-		yq --version | grep -q mikefarah \
-			|| WARNING 'detected kislyuk/yq but mikefarah/yq is preferred (compatibility may vary)'
-	}
-
-	return 0
-}
-
-__CHECK_COREUTILS() {
-	local COREUTILS=(awk find grep sed readlink)
-	local MISSING_DEPENDENCY_COUNT=0
-	local NON_GNU_DEPENDENCY_COUNT=0
-
-	local UTIL
-	for UTIL in $(echo $COREUTILS)
-	do
-		__CHECK_DEPENDENCY $UTIL || { ((MISSING_DEPENDENCY_COUNT+=1)); continue; }
-
-		$UTIL --version 2>&1 | grep 'GNU' | grep -qv 'BSD' || {
-			WARNING "non-GNU version of $UTIL detected"
-			((NON_GNU_DEPENDENCY_COUNT+=1))
-		}
-	done
-
-	[[ $NON_GNU_DEPENDENCY_COUNT -gt 0 ]] && {
-		WARNING 'scripts rely on GNU coreutils; compatibility may vary'
-		IS_MACOS && REMINDER 'GNU coreutils can be installed and linked through Homebrew'
-	}
-
-	return $MISSING_DEPENDENCY_COUNT
-}

zsh/lib/utils/environment.zsh

@@ -1,39 +0,0 @@
-__CHECK_REQUIRED_ENV() {
-	local SCWRYPTS_LOG_LEVEL=1
-	local VAR ERROR=0
-	REQUIRED_ENV=($(echo $REQUIRED_ENV | sed 's/\s\+/\n/g' | sort -u))
-	for VAR in ${REQUIRED_ENV[@]}; do __CHECK_ENV_VAR $VAR || ((ERROR+=1)); done
-	return $ERROR
-}
-
-__CHECK_ENV_VAR() {
-	local NAME="$1"
-	[ ! $NAME ] && return 1
-
-	local OVERRIDE_VALUE=$(eval echo '$'$NAME'__override')
-	[ $OVERRIDE_VALUE ] && export $NAME=$OVERRIDE_VALUE && return 0
-
-	local OPTIONAL="$2"
-	local DEFAULT_VALUE="$3"
-
-	local VALUE=$(eval echo '$'$NAME)
-	[ $VALUE ] && return 0
-
-	local SELECTION_VALUES=$(eval echo '$'$NAME'__select' | sed 's/,/\n/g; s/ /\n/g')
-	[[ $ERROR -eq 0 ]] && [[ ${#SELECTION_VALUES[@]} -gt 0 ]] && {
-		local SELECTION=$(echo $SELECTION_VALUES | FZF "select a value for '$NAME'")
-		[ $SELECTION ] && {
-			export $NAME=$SELECTION
-			return 0
-		}
-	}
-	[ $VALUE ] && return 0
-
-	[ $OPTIONAL ] && {
-		[ $DEFAULT_VALUE ] && $NAME="$DEFAULT_VALUE"
-		return 0
-	} || {
-		ERROR "variable '$NAME' required"
-		return 1
-	}
-}

zsh/lib/utils/io.fzf.zsh

@@ -1,45 +0,0 @@
-FZF() {
-	[ $CI ] && {
-		DEBUG "invoked FZF with $@"
-		FAIL 1 'currently in CI, but FZF requires user input'
-	}
-
-	local FZF_ARGS=()
-
-	FZF_ARGS+=(-i)
-	FZF_ARGS+=(--ansi)
-	FZF_ARGS+=(--bind=ctrl-c:cancel)
-	FZF_ARGS+=(--height=50%)
-	FZF_ARGS+=(--layout=reverse)
-
-	local SELECTION=$(fzf ${FZF_ARGS[@]} --prompt "$1 : " ${@:2} 2>/dev/tty)
-	PROMPT "$1"
-
-	[ $BE_QUIET ] || {
-		[[ $SCWRYPTS_LOG_LEVEL -ge 1 ]] && echo $SELECTION >&2
-	}
-	echo $SELECTION
-	[ $SELECTION ]
-}
-
-FZF_USER_INPUT() { # allow user to type custom answers; reconfirm if ambiguous with select
-	local FZF_OUTPUT=$(BE_QUIET=1 FZF $@ --print-query | sed '/^$/d' | sort -u)
-	[[ $SCWRYPTS_LOG_LEVEL -ge 1 ]] && echo $FZF_OUTPUT | head -n1 >&2
-	[ ! $FZF_OUTPUT ] && return 1
-
-	[[ $(echo "$FZF_OUTPUT" | wc -l) -eq 1 ]] \
-		&& { echo "$FZF_OUTPUT"; return 0; }
-
-	local FZF_OUTPUT=$(
-		echo "$FZF_OUTPUT" \
-			| sed "1s/\$/^$(printf "$__LIGHT_GRAY\\033[3m")<- what you typed$(printf $__COLOR_RESET)/" \
-			| sed "2s/\$/^$(printf "$__LIGHT_GRAY\\033[3m")<- what you selected$(printf $__COLOR_RESET)/" \
-			| column -ts '^' \
-			| BE_QUIET=1 FZF "$@ (clarify)" \
-		)
-
-	[[ $SCWRYPTS_LOG_LEVEL -ge 1 ]] && echo $FZF_OUTPUT >&2
-	FZF_OUTPUT=$(echo $FZF_OUTPUT | sed 's/\s\+<- what you .*$//')
-	echo $FZF_OUTPUT
-	[ $FZF_OUTPUT ]
-}

zsh/lib/utils/io.print.zsh

@@ -1,65 +0,0 @@
-PRINT() {
-	local MESSAGE
-	local LAST_LINE_END='\n'
-	local STDERR=1
-	local STDOUT=0
-
-	local LTRIM=1
-	local FORMAT=$SCWRYPTS_OUTPUT_FORMAT
-	local _S
-	while [[ $# -gt 0 ]]
-	do
-		_S=1
-		case $1 in
-			-n | --no-trim-tabs ) LTRIM=0 ;;
-			-x | --no-line-end  ) LAST_LINE_END='' ;;
-			-o | --use-stdout   ) STDOUT=1; STDERR=0 ;;
-
-			-f | --format ) ((_S+=1)); FORMAT=$2 ;;
-
-			* ) MESSAGE+="$(echo $1) " ;;
-		esac
-		shift $_S
-	done
-
-	[ $FORMAT ] || FORMAT=pretty
-	local STYLED_MESSAGE
-	case $FORMAT in
-		pretty )
-			STYLED_MESSAGE="$(echo "$MESSAGE" | sed 's/%/%%/g')"
-			STYLED_MESSAGE="$({
-				printf "${COLOR}"
-				while IFS='' read line
-				do
-					[[ $PREFIX =~ ^[[:space:]]\+$ ]] && printf '\n'
-
-					printf "${PREFIX} : $(echo "$line" | sed 's/^	\+//; s/ \+$//')"
-
-					PREFIX=$(echo $PREFIX | sed 's/./ /g')
-				done <<< $MESSAGE
-			})"
-			STYLED_MESSAGE="${COLOR}$(echo "$STYLED_MESSAGE" | sed 's/%/%%/g')${__COLOR_RESET}${LAST_LINE_END}"
-			;;
-		json )
-			STYLED_MESSAGE="$(
-				echo '{}' | jq -c ".
-					| .timestamp = \"$(date +%s)\"
-					| .runtime   = \"$SCWRYPTS_RUNTIME_ID\"
-					| .status    = \"$(echo "$PREFIX" | sed 's/ .*//')\"
-					| .message   = $(echo $MESSAGE | sed 's/^\t\+//' | jq -Rs)
-					" | sed 's/\\/\\\\/g'
-			)\n"
-			;;
-		* )
-			echo "ERROR : unsupported format '$FORMAT'" >&2
-			return 1
-			;;
-	esac
-
-
-
-	[[ $STDERR -eq 1 ]] && printf -- "$STYLED_MESSAGE" >&2
-	[[ $STDOUT -eq 1 ]] && printf -- "$STYLED_MESSAGE"
-
-	return 0
-}

zsh/lib/utils/io.usage.zsh

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

zsh/lib/utils/io.zsh

@@ -1,249 +0,0 @@
-#####################################################################
-### basic colorized print messages ##################################
-#####################################################################
-
-source "${0:a:h}/io.print.zsh"
-[ ! $ERRORS ] && ERRORS=0
-
-ERROR() {  # command encountered an error
-	[ ! $SCWRYPTS_LOG_LEVEL ] && local SCWRYPTS_LOG_LEVEL=4
-	[[ $SCWRYPTS_LOG_LEVEL -ge 1 ]] \
-		&& PREFIX="ERROR    ✖" COLOR=$__RED            PRINT "$@"
-	((ERRORS+=1))
-	return $ERRORS
-}
-
-SUCCESS() {  # command completed successfully
-	[ ! $SCWRYPTS_LOG_LEVEL ] && local SCWRYPTS_LOG_LEVEL=4
-	[[ $SCWRYPTS_LOG_LEVEL -ge 1 ]] \
-		&& PREFIX="SUCCESS  ✔" COLOR=$__GREEN          PRINT "$@"
-	return 0
-}
-
-REMINDER() {  # include sysadmin reminder or other important notice to users
-	[ ! $SCWRYPTS_LOG_LEVEL ] && local SCWRYPTS_LOG_LEVEL=4
-	[[ $SCWRYPTS_LOG_LEVEL -ge 1 ]] \
-		&& PREFIX="REMINDER " COLOR=$__BRIGHT_MAGENTA PRINT "$@"
-	return 0
-}
-
-STATUS() {  # general status updates (prefer this to generic 'echo')
-	[ ! $SCWRYPTS_LOG_LEVEL ] && local SCWRYPTS_LOG_LEVEL=4
-	[[ $SCWRYPTS_LOG_LEVEL -ge 2 ]] \
-		&& PREFIX="STATUS    " COLOR=$__BLUE           PRINT "$@"
-	return 0
-}
-
-WARNING() {  # warning-level messages; not errors
-	[ ! $SCWRYPTS_LOG_LEVEL ] && local SCWRYPTS_LOG_LEVEL=4
-	[[ $SCWRYPTS_LOG_LEVEL -ge 3 ]] \
-		&& PREFIX="WARNING  " COLOR=$__YELLOW         PRINT "$@"
-	return 0
-}
-
-DEBUG() {  # helpful during development or (sparingly) to help others' development
-	[ ! $SCWRYPTS_LOG_LEVEL ] && local SCWRYPTS_LOG_LEVEL=4
-	[[ $SCWRYPTS_LOG_LEVEL -ge 4 ]] \
-		&& PREFIX="DEBUG    ℹ" COLOR=$__WHITE          PRINT "$@"
-	return 0
-}
-
-PROMPT() {  # you probably want to use yN or INPUT from below
-	[ ! $SCWRYPTS_LOG_LEVEL ] && local SCWRYPTS_LOG_LEVEL=4
-	[[ $SCWRYPTS_LOG_LEVEL -ge 1 ]] \
-		&& PREFIX="PROMPT   " COLOR=$__CYAN PRINT "$@" \
-		&& PREFIX="USER     ⌨" COLOR=$__BRIGHT_CYAN PRINT '' --no-line-end \
-		;
-	return 0
-}
-
-FAIL()  { SCWRYPTS_LOG_LEVEL=1 ERROR "${@:2}"; exit $1; }
-ABORT() { FAIL 69 'user abort'; }
-
-#####################################################################
-### check for reported errors and format USAGE contents #############
-#####################################################################
-
-CHECK_ERRORS() {
-	local FAIL_OUT=true
-	local DISPLAY_USAGE=true
-
-	[ ! $ERRORS ] && ERRORS=0
-
-	while [[ $# -gt 0 ]]
-	do
-		case $1 in
-			--fail    ) FAIL_OUT=true  ;;
-			--no-fail ) FAIL_OUT=false ;;
-
-			--usage    ) DISPLAY_USAGE=true  ;;
-			--no-usage ) DISPLAY_USAGE=false ;;
-		esac
-		shift 1
-	done
-
-	[[ $ERRORS -eq 0 ]] && return 0
-
-	[[ $DISPLAY_USAGE =~ true ]] && USAGE
-
-	[[ $FAIL_OUT =~ true ]] && exit $ERRORS || return $ERRORS
-}
-
-source "${0:a:h}/io.usage.zsh"
-
-#####################################################################
-### facilitate user prompt and input ################################
-#####################################################################
-
-# yes/no prompts   && = yes (exit code 0)
-#                  || = no  (exit code 1)
-Yn() { [[ ! $(READ_YN $@ '[Yn]') =~ [nN] ]]; }  # default 'yes'
-yN() { [[   $(READ_YN $@ '[yN]') =~ [yY] ]]; }  # default 'no'
-
-INPUT() {  # read a single line of user input
-	PROMPT "${@:2}"
-	READ $1
-	local VALUE=$(eval echo '$'$1)
-	[ $VALUE ]
-}
-
-source "${0:a:h}/io.fzf.zsh"  # allow user to select from a list of inputs
-
-EDIT() {  # edit a file in user's preferred editor
-	[ $CI ] && {
-		WARNING 'currently in CI, skipping EDIT'
-		return 0
-	}
-
-	STATUS "opening '$1' for editing"
-	$EDITOR $@ </dev/tty >/dev/tty
-	SUCCESS "finished editing '$1'!"
-}
-
-#####################################################################
-### basic commands with tricky states or default requirements #######
-#####################################################################
-
-LESS() { less -R $@ </dev/tty >/dev/tty; }
-
-YQ() {
-	yq --version | grep -q mikefarah || {
-		yq $@
-		return $?
-	}
-
-	yq eval '... comments=""' | yq $@
-}
-
-#####################################################################
-### other i/o utilities #############################################
-#####################################################################
-
-CAPTURE() {
-	[ ! $USAGE ] && USAGE="
-		usage: stdout-varname stderr-varname [...cmd and args...]
-
-		captures stdout and stderr on separate variables for a command
-	"
-	{
-		IFS=$'\n' read -r -d '' $2;
-		IFS=$'\n' read -r -d '' $1;
-	} < <((printf '\0%s\0' "$(${@:3})" 1>&2) 2>&1)
-}
-
-
-GETSUDO() {
-	echo "\\033[1;36mPROMPT    : checking sudo password...\\033[0m" >&2
-	sudo echo hi >/dev/null 2>&1 </dev/tty \
-		&& SUCCESS '...authenticated!' \
-		|| { ERROR 'failed :c'; return 1; }
-}
-
-READ()  {
-	[ $CI ] && [ -t 0 ] \
-		&& FAIL 42 'currently in CI, but attempting interactive read; aborting'
-
-	local FORCE_USER_INPUT=false
-	local ARGS=()
-
-	while [[ $# -gt 0 ]]
-	do
-		case $1 in
-			--force-user-input ) FORCE_USER_INPUT=true ;;
-			-k )
-				ARGS+=($1)
-				;;
-			* ) ARGS+=($1) ;;
-		esac
-		shift 1
-	done
-
-	while read -k -t 0; do :; done;  # flush user stdin
-
-	case $FORCE_USER_INPUT in
-		true  )
-			read ${PREARGS[@]} ${ARGS[@]} $@ </dev/tty
-			;;
-		false )
-			[ -t 0 ] || ARGS=(-u 0 ${ARGS[@]})
-			read ${ARGS[@]} $@
-			;;
-	esac
-}
-
-READ_YN() {  # yes/no read is suprisingly tricky
-	local FORCE_USER_INPUT=false
-	local USERPROMPT=()
-	local READ_ARGS=()
-
-	while [[ $# -gt 0 ]]
-	do
-		case $1 in
-			--force-user-input )
-				# overrides 'scwrypts -y' and stdin pipe but not CI
-				FORCE_USER_INPUT=true
-				READ_ARGS+=($1)
-				;;
-			* ) USERPROMPT+=($1) ;;
-		esac
-		shift 1
-	done
-
-	##########################################
-
-	local SKIP_USER_INPUT=false
-
-	[ $CI ] \
-		&& SKIP_USER_INPUT=true
-
-	[ $__SCWRYPTS_YES ] && [[ $__SCWRYPTS_YES -eq 1 ]] && [[ $FORCE_USER_INPUT =~ false ]] \
-		&& SKIP_USER_INPUT=true
-
-	##########################################
-
-	local yn
-	PROMPT "${USERPROMPT[@]}"
-
-	local PERFORM_FAKE_PROMPT=false
-	case $SKIP_USER_INPUT in
-		true ) yn=y ;;
-		false )
-			[[ $SCWRYPTS_LOG_LEVEL -lt 1 ]] && {
-				[[ $FORCE_USER_INPUT =~ false ]] && [ ! -t 0 ] \
-					|| PERFORM_FAKE_PROMPT=true
-			}
-
-			[[ $PERFORM_FAKE_PROMPT =~ true ]] \
-				&& echo -n "${USERPROMPT[@]} : " >&2
-
-			READ ${READ_ARGS[@]} -s -k yn
-
-			[[ $PERFORM_FAKE_PROMPT =~ true ]] \
-				&& echo $yn >&2
-			;;
-	esac
-
-	[[ $SCWRYPTS_LOG_LEVEL -ge 1 ]] && echo $yn >&2
-
-	echo $yn
-}

zsh/lib/utils/os.zsh

@@ -1,12 +0,0 @@
-IS_MACOS() { uname -s | grep -q 'Darwin'; }
-
-OPEN() {
-	local OPEN=''
-	{
-		command -v xdg-open && OPEN=xdg-open
-		command -v open     && OPEN=open
-	} >/dev/null 2>&1
-
-	[ ! $OPEN ] && { ERROR 'unable to detect default open command (e.g. xdg-open)'; return 1 }
-	$OPEN $@
-}

zsh/lib/utils/utils.module.zsh

@@ -1,89 +0,0 @@
-#####################################################################
-
-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
-
-#####################################################################
-
-source ${0:a:h}/dependencies.zsh
-source ${0:a:h}/environment.zsh
-
-#####################################################################
-
-CHECK_ENVIRONMENT() {
-	local OPTIONAL=0
-
-	while [[ $# -gt 0 ]]
-	do
-		case $1 in
-			--optional ) OPTIONAL=1 ;;
-		esac
-		shift 1
-	done
-
-	[[ $OPTIONAL -eq 1 ]] && E=WARNING || E=ERROR
-
-	local ENVIRONMENT_STATUS=0
-
-	__CHECK_DEPENDENCIES $DEPENDENCIES
-	local MISSING_DEPENDENCIES=$?
-
-	__CHECK_REQUIRED_ENV $REQUIRED_ENV
-	local MISSING_ENVIRONMENT_VARIABLES=$?
-
-	##########################################
-
-	local ERROR_MESSAGE=""
-	[[ $MISSING_DEPENDENCIES -ne 0 ]] && {
-		((ENVIRONMENT_STATUS+=1))
-		ERROR_MESSAGE+="\n$MISSING_DEPENDENCIES missing "
-
-		[[ $MISSING_DEPENDENCIES -eq 1 ]] \
-			&& ERROR_MESSAGE+='dependency' \
-			|| ERROR_MESSAGE+='dependencies' \
-			;
-	}
-
-	[[ $MISSING_ENVIRONMENT_VARIABLES -ne 0 ]] && {
-		((ENVIRONMENT_STATUS+=2))
-		ERROR_MESSAGE+="\n$MISSING_ENVIRONMENT_VARIABLES missing environment variable"
-
-		[[ $MISSING_ENVIRONMENT_VARIABLES -gt 1 ]] && ERROR_MESSAGE+=s
-	}
-
-	[ $IMPORT_ERRORS ] && [[ $IMPORT_ERRORS -ne 0 ]] && {
-		((ENVIRONMENT_STATUS+=4))
-		ERROR_MESSAGE+="\n$IMPORT_ERRORS import error"
-
-		[[ $IMPORT_ERRORS -gt 1 ]] && ERROR_MESSAGE+=s
-	}
-
-	##########################################
-
-	[[ ENVIRONMENT_STATUS -ne 0 ]] && [[ $OPTIONAL -eq 0 ]] && {
-		ERROR_MESSAGE=$(echo $ERROR_MESSAGE | sed '1d; s/^/   /')
-		$E "environment errors found (see above)\n$ERROR_MESSAGE"
-	}
-
-	[[ $MISSING_ENVIRONMENT_VARIABLES -ne 0 ]] && [[ $__SCWRYPT ]] && {
-		REMINDER "
-			to quickly update missing environment variables, run:
-			'scwrypts zsh/scwrypts/environment/edit'
-		"
-	}
-
-	[[ $ENVIRONMENT_STATUS -ne 0 ]] && [[ $NO_EXIT -ne 1 ]] && [[ $OPTIONAL -eq 0 ]] && {
-		exit $ENVIRONMENT_STATUS
-	}
-
-	return $ENVIRONMENT_STATUS
-}
-
-CHECK_ENVIRONMENT

zsh/media/youtube/README.md

@@ -1,5 +0,0 @@
-# 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/media/youtube/download

@@ -1,20 +0,0 @@
-#!/bin/zsh
-use media/youtube
-#####################################################################
-
-MAIN() {
-	local URLS=($@)
-
-	[[ ${#URLS[@]} -eq 0 ]] && URLS=($(echo '' | FZF_USER_INPUT '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; }
-}