mergedeep to slow so I made my options dict shallow

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

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

- Moved personal-environment specific scwrypts to wrynegade/dotwryn

.config/env.template

@@ -0,0 +1,29 @@
+#!/bin/zsh
+export AWS_ACCOUNT=
+export AWS_PROFILE=
+export AWS_REGION=
+export AWS__EFS__LOCAL_MOUNT_POINT=
+export DIRECTUS__API_TOKEN=
+export DIRECTUS__BASE_URL=
+export DISCORD__BOT_TOKEN=
+export DISCORD__CONTENT_FOOTER=
+export DISCORD__CONTENT_HEADER=
+export DISCORD__DEFAULT_AVATAR_URL=
+export DISCORD__DEFAULT_CHANNEL_ID=
+export DISCORD__DEFAULT_USERNAME=
+export DISCORD__DEFAULT_WEBHOOK=
+export I3__BORDER_PIXEL_SIZE=
+export I3__DMENU_FONT_SIZE=
+export I3__GLOBAL_FONT_SIZE=
+export I3__MODEL_CONFIG=
+export LINEAR__API_TOKEN=
+export MEDIA_SYNC__S3_BUCKET
+export MEDIA_SYNC__TARGETS
+export REDIS_AUTH=
+export REDIS_HOST=
+export REDIS_PORT=
+export TWILIO__ACCOUNT_SID=
+export TWILIO__API_KEY=
+export TWILIO__API_SECRET=
+export TWILIO__DEFAULT_PHONE_FROM=
+export TWILIO__DEFAULT_PHONE_TO=

.config/env.template.descriptions

@@ -0,0 +1,36 @@
+AWS_ACCOUNT  | standard AWS environment variables used by awscli and other tools
+AWS_PROFILE  |
+AWS_REGION   |
+
+AWS__EFS__LOCAL_MOUNT_POINT  | fully-qualified path to mount the EFS drive
+
+DIRECTUS__API_TOKEN | details for a directus instance
+DIRECTUS__BASE_URL  |
+
+DISCORD__BOT_TOKEN          | details for discord bot
+DISCORD__CONTENT_HEADER     |
+DISCORD__CONTENT_FOOTER     |
+DISCORD__DEFAULT_AVATAR_URL |
+DISCORD__DEFAULT_CHANNEL_ID |
+DISCORD__DEFAULT_USERNAME   |
+DISCORD__DEFAULT_WEBHOOK    |
+
+I3__BORDER_PIXEL_SIZE   | custom i3 configuration settings
+I3__DMENU_FONT_SIZE     |
+I3__GLOBAL_FONT_SIZE    |
+I3__MODEL_CONFIG        |
+
+LINEAR__API_TOKEN  | linear.app project management configuration
+
+MEDIA_SYNC__S3_BUCKET | s3 bucket name and filesystem targets for media backups
+MEDIA_SYNC__TARGETS   |
+
+REDIS_AUTH  | redis connection credentials
+REDIS_HOST  |
+REDIS_PORT  |
+
+TWILIO__ACCOUNT_SID        | twilio account / credentials
+TWILIO__API_KEY            | 
+TWILIO__API_SECRET         | 
+TWILIO__DEFAULT_PHONE_FROM | 
+TWILIO__DEFAULT_PHONE_TO   | 

.env.template

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

.github/workflows/update-semver.yaml

@@ -0,0 +1,16 @@
+---
+name: Update Semver
+
+on:  # yamllint disable-line rule:truthy
+  push:
+    branches-ignore:
+      - '**'
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  update-semver:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: rickstaa/action-update-semver@v1

README.md

@@ -6,6 +6,9 @@ In modern developer / dev-ops workflows, scripts require a complex configuration
 Without a better solution, the developer is cursed to copy lines-upon-lines of variables into terminals, create random text artifacts, or maybe even commit secure credentials into source.
 Scwrypts leverages ZSH to give hot-key access to run scripts in such environments.
 
+## Major Version Upgrade Notice
+
+Please refer to [Version 3 to Version 4 Upgrade Path](./docs/upgrade/v3-to-v4.md) when upgrading from scwrypts v3 to scwrypts v4!
 
 ## Dependencies
 Due to the wide variety of resources used by scripting libraries, the user is expected to manually resolve dependencies.
@@ -45,10 +48,11 @@ After determining which script to run, if no environment has been specified, Scw
 Set environment variable `CI=true` (and use the no install method) to run in an automated pipeline.
 There are a few notable changes to this runtime:
 - **The Scwrypts sandbox environment will not load.** All variables will be read from context.
-	- The underscore-prefixed `_AWS_(PROFILE|REGION|ACCOUNT)` variables will be read from the standard `AWS_` variables
 - User yes/no prompts will **always be YES**
 - Other user input will default to an empty string
 - Logs will not be captured
+- Setting the environment variable `SCWRYPTS_GROUP_LOADER__[a-z_]\+` will source the file indicated in the variable (this allows custom groups without needing to modify the `config.zsh` directly)
+	- In GitHub actions, `*.scwrypts.zsh` groups are detected automatically from the `$GITHUB_WORKSPACE`; set `SCWRYPTS_GITHUB_NO_AUTOLOAD=true` to disable
 
 
 ## Contributing

action.yaml

@@ -0,0 +1,68 @@
+---  # allow running scwrypts in Github Actions
+name: scwrypts
+author: yage
+description: check required dependencies and run a scwrypt
+
+inputs:
+  scwrypt:
+    description: "args / identifiers for scwrypts CLI (e.g. '--name <scwrypt-name> --group <group-name> --type <type-name>')"
+    required: true
+
+  args:
+    description: "arguments to pass to the scwrypt-to-be-run"
+    required: false
+
+  version:
+    description: "scwrypts version; defaults to latest (minimum v3.7.0)"
+    required: false
+
+  scwrypts-env:
+    description: "override value for SCWRYPTS_ENV"
+    required: false
+    default: "ci.github-actions"
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/checkout@v4
+      with:
+        repository: wrynegade/scwrypts
+        path: ./wrynegade/scwrypts
+        ref: ${{ inputs.version }}
+
+    - name: check dependencies
+      shell: bash
+      env:
+        CI: true
+        SCWRYPTS_PLUGIN_ENABLED__ci: 1
+      run: |
+        [ $CI_SCWRYPTS_READY ] && [[ $CI_SCWRYPTS_READY -eq 1 ]] && echo 'setup completed previously' && exit 0
+
+        echo "updating package dependencies"
+        {
+          sudo apt-get update
+          sudo apt-get install --yes zsh fzf ripgrep
+
+          for D in $($GITHUB_WORKSPACE/wrynegade/scwrypts/scwrypts -n --name check-all-dependencies --group ci --type zsh)
+          do
+            echo "--- installing $D ---"
+            ( sudo apt-get install --yes $D; exit 0; )
+          done
+        } > $HOME/.scwrypts.apt-get.log 2>&1
+
+        echo "updating virtual dependencies"
+        $GITHUB_WORKSPACE/wrynegade/scwrypts/scwrypts -n \
+          --name scwrypts/virtualenv/update-all \
+          --group scwrypts \
+          --type zsh \
+          > $HOME/.scwrypts.virtualenv.log 2>&1
+
+        echo "CI_SCWRYPTS_READY=1" >> $GITHUB_ENV
+        exit 0
+
+    - name: run scwrypt
+      shell: bash
+      env:
+        CI: true
+        SCWRYPTS_ENV: ${{ inputs.scwrypts-env }}
+      run: $GITHUB_WORKSPACE/wrynegade/scwrypts/scwrypts ${{inputs.scwrypt}} -- ${{inputs.args}} || exit 1

docs/upgrade/v3-to-v4.md

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

plugins/ci/.config/env.template

@@ -0,0 +1 @@
+#!/bin/zsh

plugins/ci/README.md

@@ -0,0 +1,10 @@
+# Kubernetes `kubectl` Helper Plugin
+
+Leverages a local `redis` application to quickly and easily set an alias `k` for `kubectl --context <some-context> --namespace <some-namespace>`.
+Much like scwrypts environments, `k` aliases are *only* shared amongst session with the same `SCWRYPTS_ENV` to prevent accidental cross-contamination.
+
+
+## Getting Started
+
+Enable the plugin in `~/.config/scwrypts/config.zsh` by adding `SCWRYPTS_PLUGIN_ENABLED__KUBECTL=1`.
+Use `k` as your new `kubectl` and checkout `k --help` and `k meta --help`.

plugins/ci/check-all-dependencies

@@ -0,0 +1,33 @@
+#!/bin/zsh
+#####################################################################
+MAIN() {
+	cd "$SCWRYPTS_ROOT__scwrypts/"
+
+	DEPENDENCIES+=()
+	for group in ${SCWRYPTS_GROUPS[@]}
+	do
+		[[ $group =~ ^ci$ ]] && continue
+
+		GROUP_HOME="$(eval 'echo $SCWRYPTS_ROOT__'$group)"
+		[ $GROUP_HOME ] && [ -d "$GROUP_HOME" ] || continue
+
+		STATUS "checking dependencies for $group"
+		DEPENDENCIES+=($(
+			for file in $(
+				{
+					cd "$GROUP_HOME"
+					rg -l '^DEPENDENCIES\+=\($'
+					rg -l '^DEPENDENCIES\+=\([^)]\+\)'
+				} | grep -v '\.md$' | grep -v 'check-all-dependencies$')
+			do
+				sed -z 's/.*DEPENDENCIES+=(\([^)]*\)).*/\1\n/; s/#.*\n//g; s/\s\+/\n/g' "$GROUP_HOME/$file"
+			done 
+		))
+	done
+
+	DEPENDENCIES=(zsh $(echo $DEPENDENCIES | sed 's/ /\n/g' | sort -u | grep '^[-_a-zA-Z]\+$'))
+
+	STATUS "discovered dependencies: ($DEPENDENCIES)"
+	echo $DEPENDENCIES | sed 's/ /\n/g'
+	CHECK_ENVIRONMENT && SUCCESS "all dependencies satisfied"
+}

plugins/ci/ci.scwrypts.zsh

@@ -0,0 +1,5 @@
+SCWRYPTS_GROUPS+=(ci)
+
+export SCWRYPTS_TYPE__ci=zsh
+export SCWRYPTS_ROOT__ci="$SCWRYPTS_ROOT__scwrypts/plugins/ci"
+export SCWRYPTS_COLOR__ci='\033[0m'

plugins/kubectl/.config/env.template

@@ -0,0 +1,2 @@
+#!/bin/zsh
+export SCWRYPTS_KUBECTL_REDIS=

plugins/kubectl/.config/env.template.descriptions

@@ -0,0 +1 @@
+SCWRYPTS_KUBECTL_REDIS | (currently only 'managed') 'managed' or 'custom' redis configuration

plugins/kubectl/.config/static/redis.zsh

@@ -0,0 +1,4 @@
+export SCWRYPTS_KUBECTL_REDIS_HOST__managed=127.0.0.1
+export SCWRYPTS_KUBECTL_REDIS_PORT__managed=26379
+export SCWRYPTS_KUBECTL_REDIS_AUTH__managed=
+export SCWRYPTS_KUBECTL_REDIS_KEY_PREFIX__managed=

plugins/kubectl/README.md

@@ -0,0 +1,10 @@
+# Kubernetes `kubectl` Helper Plugin
+
+Leverages a local `redis` application to quickly and easily set an alias `k` for `kubectl --context <some-context> --namespace <some-namespace>`.
+Much like scwrypts environments, `k` aliases are *only* shared amongst session with the same `SCWRYPTS_ENV` to prevent accidental cross-contamination.
+
+
+## Getting Started
+
+Enable the plugin in `~/.config/scwrypts/config.zsh` by adding `SCWRYPTS_PLUGIN_ENABLED__KUBECTL=1`.
+Use `k` as your new `kubectl` and checkout `k --help` and `k meta --help`.

plugins/kubectl/driver/kubectl.completion.zsh

@@ -0,0 +1,46 @@
+#####################################################################
+command -v compdef >/dev/null 2>&1 || return 0
+#####################################################################
+
+for CLI in kubectl helm flux
+do
+	eval "_${CLI[1]}() {
+		local SUBSESSION=0
+		echo \${words[2]} | grep -q '^[0-9]\\+$' && SUBSESSION=\${words[2]}
+
+		local PASSTHROUGH_WORDS=($CLI)
+		[[ \$CURRENT -gt 2 ]] && echo \${words[2]} | grep -qv '^[0-9]\\+$' && {
+			local KUBECONTEXT=\$(k \$SUBSESSION meta get context)
+			local NAMESPACE=\$(k \$SUBSESSION meta get namespace)
+
+			[ \$KUBECONTEXT ] \
+				&& PASSTHROUGH_WORDS+=($([[ $CLI =~ ^helm$ ]] && echo '--kube-context' || echo '--context') \$KUBECONTEXT) \
+				;
+			[ \$NAMESPACE   ] \
+				&& PASSTHROUGH_WORDS+=(--namespace \$NAMESPACE) \
+				;
+		}
+
+		local DELIMIT_COUNT=0
+		local WORD
+		for WORD in \${words[@]:1}
+		do
+			case \$WORD in
+				[0-9]* ) continue ;;
+				-- )
+					echo \$words | grep -q 'exec' && ((DELIMIT_COUNT+=1))
+					[[ \$DELIMIT_COUNT -eq 0 ]] && ((DELIMIT_COUNT+=1)) && continue
+					;;
+			esac
+			PASSTHROUGH_WORDS+=(\"\$WORD\")
+		done
+
+		echo \"\$words\" | grep -q '\\s\\+$' && PASSTHROUGH_WORDS+=(' ')
+
+		words=\"\$PASSTHROUGH_WORDS\"
+		_$CLI
+	}
+	"
+
+	compdef _${CLI[1]} ${CLI[1]}
+done

plugins/kubectl/driver/kubectl.driver.zsh

@@ -0,0 +1,199 @@
+[[ $SCWRYPTS_KUBECTL_DRIVER_READY -eq 1 ]] && return 0
+
+unalias k h >/dev/null 2>&1
+k() { _SCWRYPTS_KUBECTL_DRIVER kubectl $@; }
+h() { _SCWRYPTS_KUBECTL_DRIVER helm $@; }
+f() { _SCWRYPTS_KUBECTL_DRIVER flux $@; }
+
+
+_SCWRYPTS_KUBECTL_DRIVER() {
+	[ ! $SCWRYPTS_ENV ] && {
+		ERROR "must set SCWRYPTS_ENV in order to use '$(echo $CLI | head -c1)'"
+		return 1
+	}
+
+	which REDIS >/dev/null 2>&1 \
+		|| eval "$(scwrypts -n --name meta/get-static-redis-definition --type zsh --group kubectl)"
+
+	local CLI="$1"; shift 1
+
+	local SCWRYPTS_GROUP CUSTOM_COMMANDS=(meta)
+	for SCWRYPTS_GROUP in ${SCWRYPTS_GROUPS[@]}
+	do
+		CUSTOM_COMMANDS+=($(eval echo '$SCWRYPTS_KUBECTL_CUSTOM_COMMANDS__'$SCWRYPTS_GROUP))
+	done
+
+	##########################################
+
+	local USAGE="
+		usage: - [...args...] [...options...] -- [...$CLI options...]
+
+		args: -
+
+		options: -
+		  --subsession [0-9]   use indicated subsession (use for script clarity instead of positional arg)
+
+		  -h, --help      display this help dialogue
+		  -v, --verbose   output debugging information
+
+		description: -
+	"
+
+	local USAGE__usage=$(echo $CLI | head -c1) 
+
+	local USAGE__args="$(
+		{
+			echo "\\033[0;32m[0-9]\\033[0m^if the first argument is a number 0-9, uses or creates a subsession (default 0)"
+			echo " ^ "
+			for C in ${CUSTOM_COMMANDS[@]}
+			do
+				echo "\\033[0;32m$C\\033[0m^$(SCWRYPTS_KUBECTL_CUSTOM_COMMAND_DESCRIPTION__$C 2>/dev/null)"
+			done 
+		} | column -ts '^'
+	)"
+
+	local USAGE__options="
+		-n, --namespace   set the namespace
+		-k, --context     set the context
+	"
+
+	local USAGE__description="
+		Provides 'k' (kubectl), 'h' (helm), and 'f' (flux) shorthands to the respective
+		utility. These functions leverage redis and scwrypts environments to
+		allow quick selection of contexts and namespaces usable across all
+		active shell instances.
+		
+		The scwrypts group 'kubectl' has simple selection executables for
+		kubecontext and namespace, but also provides the library to enable
+		enriched, use-case-sensitive setup of kubernetes context.
+
+		All actions are scoped to the current SCWRYPTS_ENV
+		  currently : \\033[0;33m$SCWRYPTS_ENV\\033[0m
+		  
+		"
+
+	##########################################
+	
+	local USER_ARGS=()
+
+	local CUSTOM_COMMAND=0
+	local VERBOSE=0
+	local HELP=0
+	local ERRORS=0
+
+	local COMMAND_SWITCH_CASE="@($(echo $CUSTOM_COMMANDS | sed 's/ /|/g'))"
+
+	[ ! $SUBSESSION ] && local SUBSESSION=0
+	[[ $1 =~ ^[0-9]$ ]] && SUBSESSION=$1 && shift 1
+
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in
+			meta )
+				CUSTOM_COMMAND=$1
+				SCWRYPTS_KUBECTL_CUSTOM_COMMAND_PARSE__$1 ${@:2}
+				break
+				;;
+
+			-v | --verbose ) VERBOSE=1 ;;
+			-h | --help    ) HELP=1 ;;
+
+			--subsession ) SUBSESSION=$2; shift 1 ;;
+
+			-n | --namespace )
+				_SCWRYPTS_KUBECTL_DRIVER kubectl meta set namespace $2
+				shift 1
+				;;
+
+			-k | --context | --kube-context )
+				_SCWRYPTS_KUBECTL_DRIVER kubectl meta set context $2
+				shift 1
+				;;
+
+			-- )
+				echo $USER_ARGS | grep -q 'exec' && USER_ARGS+=(--)
+				shift 1
+				break
+				;;
+
+			* )
+				[ ! $CUSTOM_COMMAND ] && {
+					for C in ${CUSTOM_COMMANDS[@]}
+					do
+						[[ $1 =~ ^$C$ ]] && {
+							SCWRYPTS_KUBECTL_CUSTOM_COMMAND_PARSE__$1 ${@:2}
+							break
+						}
+					done
+				}
+				USER_ARGS+=($1)
+				;;
+		esac
+		shift 1
+	done
+
+	while [[ $# -gt 0 ]]; do USER_ARGS+=($1); shift 1; done
+
+
+	CHECK_ERRORS --no-fail || return 1
+
+	[[ $HELP -eq 1 ]] && { USAGE; return 0; }
+
+	#####################################################################
+
+	local STRICT=$(_SCWRYPTS_KUBECTL_SETTINGS get strict || echo 1)
+
+	case $CUSTOM_COMMAND in
+		0 )
+			local CLI_ARGS=()
+
+			local CONTEXT=$(k meta get context)
+			local NAMESPACE=$(k meta get namespace)
+
+			[ $CONTEXT ] && [[ $CLI =~ ^helm$    ]] && CLI_ARGS+=(--kube-context $CONTEXT)
+			[ $CONTEXT ] && [[ $CLI =~ ^kubectl$ ]] && CLI_ARGS+=(--context $CONTEXT)
+			[ $CONTEXT ] && [[ $CLI =~ ^flux$    ]] && CLI_ARGS+=(--context $CONTEXT)
+
+			[[ $STRICT -eq 1 ]] && {
+				[ $CONTEXT   ] || ERROR "missing kubectl 'context'"
+				[ $NAMESPACE ] || ERROR "missing kubectl 'namespace'"
+
+				CHECK_ERRORS --no-fail --no-usage || {
+					ERROR "with 'strict' settings enabled, context and namespace must be set!"
+					REMINDER "
+						these values can be set directly with
+							$(echo $CLI | head -c1) meta set (namespace|context)
+					"
+
+					return 2
+				}
+			}
+
+			[ $NAMESPACE ] && CLI_ARGS+=(--namespace $NAMESPACE)
+			[[ $VERBOSE -eq 1 ]] && {
+				INFO "
+					context '$CONTEXT'
+					namespace '$NAMESPACE'
+					environment '$SCWRYPTS_ENV'
+					subsession '$SUBSESSION'
+					"
+				STATUS "running $CLI ${CLI_ARGS[@]} ${USER_ARGS[@]}"
+			} || {
+				[[ $(_SCWRYPTS_KUBECTL_SETTINGS get context) =~ ^show$ ]] && {
+					INFO "$SCWRYPTS_ENV.$SUBSESSION : $CLI ${CLI_ARGS[@]} ${USER_ARGS[@]}"
+				}
+			}
+			$CLI ${CLI_ARGS[@]} ${USER_ARGS[@]}
+			;;
+		* ) SCWRYPTS_KUBECTL_CUSTOM_COMMAND__$CUSTOM_COMMAND ${USER_ARGS[@]} ;;
+	esac
+}
+
+_SCWRYPTS_KUBECTL_SETTINGS() {
+	# (get setting-name) or (set setting-name setting-value)
+	REDIS h$1 ${SCWRYPTS_ENV}:kubectl:settings ${@:2} | grep .
+}
+
+#####################################################################
+source ${0:a:h}/kubectl.completion.zsh
+source ${0:a:h}/meta.zsh

plugins/kubectl/driver/meta.zsh

@@ -0,0 +1,147 @@
+SCWRYPTS_KUBECTL_CUSTOM_COMMAND_PARSE__meta() {
+	USAGE__usage+=" meta"
+	USAGE__args="
+	- get     output value of meta variable
+	- set     interactively configure value of meta variable
+	- clear   clear current subsession variables
+
+	(settings args)
+	- show   output context for every command
+	- hide   (default) hide output context for every command
+
+	- strict   (default) require context *and* namespace to be set
+	- loose    do not require context and namespace to be set
+	"
+	USAGE__options=''
+	USAGE__description=$(SCWRYPTS_KUBECTL_CUSTOM_COMMAND_DESCRIPTION__meta)
+
+	META_SUBARGS="
+	- namespace
+	- context
+	"
+
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in
+			-h | --help ) HELP=1 ;;
+
+			set ) 
+				USAGE__usage+=" set"
+				USAGE__args="set (namespace|context)"
+				USAGE__description="interactively set a namespace or context for '$SCWRYPTS_ENV'"
+				case $2 in
+					namespace | context ) USER_ARGS+=($1 $2 $3); [ $3 ] && shift 1 ;;
+					-h | --help ) HELP=1 ;;
+					'' )
+						: \
+							&& SCWRYPTS_KUBECTL_CUSTOM_COMMAND__meta set context \
+							&& SCWRYPTS_KUBECTL_CUSTOM_COMMAND__meta set namespace \
+							;
+						return $?
+						;;
+
+					* ) ERROR "cannot set '$2'" ;;
+				esac
+				shift 1
+				;;
+
+			get )
+				USAGE__usage+=" get"
+				USAGE__args="get (namespace|context|all)"
+				USAGE__description="output the current namespace or context for '$SCWRYPTS_ENV'"
+				case $2 in
+					namespace | context | all ) USER_ARGS+=($1 $2) ;;
+
+					-h | --help ) HELP=1 ;;
+
+					* ) ERROR "cannot get '$2'" ;;
+				esac
+				shift 1
+				;;
+
+			copy )
+				USAGE__usage+=" copy"
+				USAGE__args+="copy [0-9]"
+				USAGE__description="copy current subsession ($SUBSESSION) to target subsession id"
+				case $2 in
+					[0-9] ) USER_ARGS+=($1 $2) ;;
+					-h | --help ) HELP=1 ;;
+					* ) ERROR "target session must be a number [0-9]" ;;
+				esac
+				shift 1
+				;;
+
+			clear | show | hide | strict | loose ) USER_ARGS+=($1) ;;
+
+			* ) ERROR "no meta command '$1'"
+		esac
+		shift 1
+	done
+}
+
+SCWRYPTS_KUBECTL_CUSTOM_COMMAND__meta() {
+	case $1 in
+		get )
+			[[ $2 =~ ^all$ ]] && {
+				local CONTEXT=$(REDIS get --prefix current:context | grep . || echo "\\033[1;31mnone set\\033[0m")
+				local NAMESPACE=$(REDIS get --prefix current:namespace | grep . || echo "\\033[1;31mnone set\\033[0m")
+				echo "
+					environment : $SCWRYPTS_ENV
+					context     : $CONTEXT
+					namespace   : $NAMESPACE
+
+					CLI settings
+					  command context : $(_SCWRYPTS_KUBECTL_SETTINGS get context)
+					      strict mode : $([[ $STRICT -eq 1 ]] && echo "on" || echo "\\033[1;31moff\\033[0m")
+					" | sed 's/^	\+//' >&2
+				return 0
+			}
+
+			REDIS get --prefix current:$2
+			;;
+
+		set )
+			scwrypts -n --name set-$2 --type zsh --group kubectl -- $3 --subsession $SUBSESSION >/dev/null \
+				&& SUCCESS "$2 set"
+			;;
+
+		copy )
+			: \
+				&& STATUS "copying $1 to $2" \
+				&& scwrypts -n --name set-context --type zsh --group kubectl -- --subsession $2 $(k meta get context | grep . || echo 'reset') \
+				&& scwrypts -n --name set-namespace --type zsh --group kubectl -- --subsession $2 $(k meta get namespace | grep . || echo 'reset') \
+				&& SUCCESS "subsession $1 copied to $2" \
+				;
+			;;
+
+		clear )
+			scwrypts -n --name set-context --type zsh --group kubectl -- --subsession $SUBSESSION reset >/dev/null \
+				&& SUCCESS "subsession $SUBSESSION reset to default"
+			;;
+
+		show )
+			_SCWRYPTS_KUBECTL_SETTINGS set context show >/dev/null \
+				&& SUCCESS "now showing full command context"
+			;;
+
+		hide )
+			_SCWRYPTS_KUBECTL_SETTINGS set context hide >/dev/null \
+				&& SUCCESS "now hiding command context"
+			;;
+
+		loose )
+			_SCWRYPTS_KUBECTL_SETTINGS set strict 0 >/dev/null \
+				&& WARNING "now running in 'loose' mode"
+			;;
+
+		strict )
+			_SCWRYPTS_KUBECTL_SETTINGS set strict 1 >/dev/null \
+				&& SUCCESS "now running in 'strict' mode"
+			;;
+	esac
+}
+
+SCWRYPTS_KUBECTL_CUSTOM_COMMAND_DESCRIPTION__meta() {
+	[ $CLI ] || CLI='kubectl'
+	echo "operations for $CLI session variables and other CLI settings"
+}

plugins/kubectl/get-context

@@ -0,0 +1,7 @@
+#!/bin/zsh
+use kubectl --group kubectl
+#####################################################################
+
+MAIN() {
+	KUBECTL__GET_CONTEXT
+}

plugins/kubectl/get-namespace

@@ -0,0 +1,7 @@
+#!/bin/zsh
+use kubectl --group kubectl
+#####################################################################
+
+MAIN() {
+	KUBECTL__GET_NAMESPACE
+}

plugins/kubectl/kubectl.scwrypts.zsh

@@ -0,0 +1,11 @@
+SCWRYPTS_GROUPS+=(kubectl)
+
+export SCWRYPTS_TYPE__kubectl=zsh
+export SCWRYPTS_ROOT__kubectl="$SCWRYPTS_ROOT__scwrypts/plugins/kubectl"
+export SCWRYPTS_COLOR__kubectl='\033[0;31m'
+
+SCWRYPTS_STATIC_CONFIG__kubectl+=(
+	"$SCWRYPTS_ROOT__kubectl/.config/static/redis.zsh"
+)
+
+source "$SCWRYPTS_ROOT__kubectl/driver/kubectl.driver.zsh"

plugins/kubectl/lib/kubectl.module.zsh

@@ -0,0 +1,158 @@
+#####################################################################
+
+DEPENDENCIES+=(
+	kubectl
+)
+
+REQUIRED_ENV+=()
+
+use redis --group kubectl
+
+#####################################################################
+
+KUBECTL() {
+	local NAMESPACE=$(REDIS get --prefix "current:namespace")
+	local CONTEXT=$(KUBECTL__GET_CONTEXT)
+
+	local KUBECTL_ARGS=()
+	[ $NAMESPACE ] && KUBECTL_ARGS+=(--namespace $NAMESPACE)
+	[ $CONTEXT   ] && KUBECTL_ARGS+=(--context $CONTEXT)
+
+	kubectl ${KUBECTL_ARGS[@]} $@
+}
+
+#####################################################################
+
+KUBECTL__GET_CONTEXT() { REDIS get --prefix "current:context"; }
+
+KUBECTL__SET_CONTEXT() {
+	local CONTEXT=$1
+	[ ! $CONTEXT ] && return 1
+
+	[[ $CONTEXT =~ reset ]] && {
+		: \
+			&& REDIS del --prefix "current:context" \
+			&& KUBECTL__SET_NAMESPACE reset \
+			;
+		return $?
+	}
+
+	: \
+		&& REDIS set --prefix "current:context" "$CONTEXT" \
+		&& KUBECTL__SET_NAMESPACE reset \
+		;
+}
+
+KUBECTL__SELECT_CONTEXT() {
+	KUBECTL__LIST_CONTEXTS | FZF 'select a context'
+}
+
+KUBECTL__LIST_CONTEXTS() {
+	echo reset
+	local ALL_CONTEXTS=$(KUBECTL config get-contexts -o name | sort)
+
+	echo $ALL_CONTEXTS | grep -v '^arn:aws:eks'
+
+	[[ $AWS_ACCOUNT ]] && {
+		echo $ALL_CONTEXTS | grep "^arn:aws:eks:.*:$AWS_ACCOUNT"
+		true
+	} || {
+		echo $ALL_CONTEXTS | grep '^arn:aws:eks'
+	}
+}
+
+#####################################################################
+
+KUBECTL__GET_NAMESPACE() { REDIS get --prefix "current:namespace"; }
+
+KUBECTL__SET_NAMESPACE() {
+	local NAMESPACE=$1
+	[ ! $NAMESPACE ] && return 1
+
+	[[ $NAMESPACE =~ reset ]] && {
+		REDIS del --prefix "current:namespace"
+		return $?
+	}
+
+	REDIS set --prefix "current:namespace" "$NAMESPACE"
+}
+
+KUBECTL__SELECT_NAMESPACE() {
+	KUBECTL__LIST_NAMESPACES | FZF 'select a namespace'
+}
+
+KUBECTL__LIST_NAMESPACES() {
+	echo reset
+	echo default
+	KUBECTL get namespaces -o name | sed 's/^namespace\///' | sort
+}
+
+#####################################################################
+
+KUBECTL__SERVE() {
+	[ $CONTEXT ] || local CONTEXT=$(KUBECTL__GET_CONTEXT)
+	[ $CONTEXT ] || ERROR 'must configure a context in which to serve'
+
+	[ $NAMESPACE ] || local NAMESPACE=$(KUBECTL__GET_NAMESPACE)
+	[ $NAMESPACE ] || ERROR 'must configure a namespace in which to serve'
+
+	CHECK_ERRORS --no-fail --no-usage || return 1
+
+	[ $SERVICE ] && SERVICE=$(KUBECTL__LIST_SERVICES | jq -c "select (.service == \"$SERVICE\")" || echo $SERVICE)
+	[ $SERVICE ] || local SERVICE=$(KUBECTL__SELECT_SERVICE)
+	[ $SERVICE ] || ERROR 'must provide or select a service'
+
+	KUBECTL__LIST_SERVICES | grep -q "^$SERVICE$"\
+		|| ERROR "no service '$SERVICE' in '$CONFIG/$NAMESPACE'"
+
+	CHECK_ERRORS --no-fail --no-usage || return 1
+
+	##########################################
+
+	SERVICE_PASSWORD="$(KUBECTL__GET_SERVICE_PASSWORD)"
+	KUBECTL__SERVICE_PARSE
+
+	INFO "attempting to serve ${NAMESPACE}/${SERVICE_NAME}:${SERVICE_PORT}"
+	[ $SERVICE_PASSWORD ] && INFO "password : $SERVICE_PASSWORD"
+
+	KUBECTL port-forward service/$SERVICE_NAME $SERVICE_PORT
+}
+
+KUBECTL__SELECT_SERVICE() {
+	[ $NAMESPACE ] || local NAMESPACE=$(KUBECTL__GET_NAMESPACE)
+	[ $NAMESPACE ] || return 1
+
+	local SERVICES=$(KUBECTL__LIST_SERVICES)
+	local SELECTED=$({
+		echo "namespace service port"
+		echo $SERVICES \
+			| jq -r '.service + " " + .port' \
+			| sed "s/^/$NAMESPACE /" \
+			;
+	} \
+		| column -t \
+		| FZF 'select a service' --header-lines=1 \
+		| awk '{print $2;}' \
+	)
+
+	echo $SERVICES | jq -c "select (.service == \"$SELECTED\")"
+}
+
+KUBECTL__LIST_SERVICES() {
+	KUBECTL get service --no-headers\
+		| awk '{print "{\"service\":\""$1"\",\"ip\":\""$3"\",\"port\":\""$5"\"}"}' \
+		| jq -c 'select (.ip != "None")' \
+		;
+}
+
+KUBECTL__GET_SERVICE_PASSWORD() {
+	[ $PASSWORD_SECRET ] && [ $PASSWORD_KEY ] || return 0
+
+	KUBECTL get secret $PASSWORD_SECRET -o jsonpath="{.data.$PASSWORD_KEY}" \
+		| base64 --decode
+}
+
+KUBECTL__SERVICE_PARSE() {
+	SERVICE_NAME=$(echo $SERVICE | jq -r .service)
+	SERVICE_PORT=$(echo $SERVICE | jq -r .port | sed 's|/.*$||')
+}

plugins/kubectl/lib/redis.module.zsh

@@ -0,0 +1,97 @@
+#####################################################################
+
+DEPENDENCIES+=(
+	redis-cli
+	docker
+)
+
+# TODO; allow custom redis configuration
+export SCWRYPTS_KUBECTL_REDIS=managed
+
+REQUIRED_ENV+=(
+	SCWRYPTS_KUBECTL_REDIS
+)
+
+#####################################################################
+
+REDIS() {
+	[ ! $USAGE ] && local USAGE="
+		usage: [...options...]
+
+		options:
+		  --subsession [0-9]   use a particular subsession
+
+		  -p, --prefix   apply dynamic prefix to the next command line argument
+
+		  --get-prefix              output key prefix for current session+subsession
+		  --get-static-definition   output the static ZSH function definition for REDIS
+
+		  additional arguments and options are passed through to 'redis-cli'
+	"
+
+	local REDIS_ARGS=() USER_ARGS=()
+
+	[ $SUBSESSION ] || local SUBSESSION=0
+
+	local REDIS_PREFIX=$(eval echo '$SCWRYPTS_KUBECTL_REDIS_KEY_PREFIX__'$SCWRYPTS_KUBECTL_REDIS)
+	[ $REDIS_PREFIX ] && REDIS_PREFIX+=':'
+
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in 
+			-p | --prefix ) USER_ARGS+=("${REDIS_PREFIX}${SCWRYPTS_ENV}:${SUBSESSION}:$2"); shift 1 ;;
+
+			--subsession            ) SUBSESSION=$2; shift 1 ;;
+
+			--get-prefix            ) echo $REDIS_PREFIX; return 0 ;;
+			--get-static-definition ) ECHO_STATIC_DEFINITION=1 ;;
+
+			* ) USER_ARGS+=($1) ;;
+		esac
+		shift 1
+	done
+
+	local REDIS_HOST=$(eval echo '$SCWRYPTS_KUBECTL_REDIS_HOST__'$SCWRYPTS_KUBECTL_REDIS)
+	local REDIS_PORT=$(eval echo '$SCWRYPTS_KUBECTL_REDIS_PORT__'$SCWRYPTS_KUBECTL_REDIS)
+	local REDIS_AUTH=$(eval echo '$SCWRYPTS_KUBECTL_REDIS_AUTH__'$SCWRYPTS_KUBECTL_REDIS)
+
+	[ $REDIS_HOST ] && REDIS_ARGS+=(-h $REDIS_HOST)
+	[ $REDIS_PORT ] && REDIS_ARGS+=(-p $REDIS_PORT)
+	[ $REDIS_AUTH ] && REDIS_ARGS+=(-a $REDIS_AUTH)
+
+	REDIS_ARGS+=(--raw)
+
+	[[ $ECHO_STATIC_DEFINITION -eq 1 ]] && {
+		echo "REDIS() {\
+			local USER_ARGS=(); \
+			[ ! \$SUBSESSION ] && local SUBSESSION=0 ;\
+			while [[ \$# -gt 0 ]]; \
+			do \
+				case \$1 in
+				-p | --prefix ) USER_ARGS+=(\"${REDIS_PREFIX}\${SCWRYPTS_ENV}:\${SUBSESSION}:\$2\"); shift 1 ;; \
+				* ) USER_ARGS+=(\$1) ;; \
+				esac; \
+				shift 1; \
+			done; \
+			redis-cli ${REDIS_ARGS[@]} \${USER_ARGS[@]}; \
+		}" | sed 's/\s\+/ /g'
+		return 0
+	}
+
+	redis-cli ${REDIS_ARGS[@]} ${USER_ARGS[@]}
+}
+
+REDIS ping | grep -qi pong || {
+	RPID=$(docker ps -a | grep scwrypts-kubectl-redis | awk '{print $1;}')
+	[ $RPID ] && STATUS 'refreshing redis instance' && docker rm -f $RPID
+	unset RPID
+
+	docker run \
+		--detach \
+		--name scwrypts-kubectl-redis \
+		--publish $SCWRYPTS_KUBECTL_REDIS_PORT__managed:6379 \
+		redis >/dev/null 2>&1
+
+	STATUS 'awaiting redis connection'
+	until REDIS ping 2>/dev/null | grep -qi pong; do sleep 0.5; done
+}

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

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

plugins/kubectl/serve

@@ -0,0 +1,49 @@
+#!/bin/zsh
+use kubectl --group kubectl
+#####################################################################
+
+MAIN() {
+	local USAGE="
+	usage: [service] [...options...]
+
+	args:
+	  service   (optional) name of the service to forward locally
+
+	options:
+	  --context      override context
+	  --namespace    override namespace
+	  --subsession   REDIS subsession (default 0)
+
+	  to show a required password on screen, use both:
+	  --password-secret   Secret resource
+	  --password-key      key within Secret's 'data'
+
+	  -h, --help   show this dialogue and exit
+	"
+	local CONTEXT NAMESPACE SERVICE
+	local SUBSESSION=0
+
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in
+			--context    ) CONTEXT=$2; shift 1 ;;
+			--namespace  ) NAMESPACE=$2; shift 1 ;;
+			--subsession ) SUBSESSION=$2; shift 1 ;;
+
+			--password-secret ) PASSWORD_SECRET=$2; shift 1 ;;
+			--password-key    ) PASSWORD_KEY=$2; shift 1 ;;
+
+			-h | --help ) USAGE; return 0 ;;
+
+			* )
+				[ $SERVICE ] && ERROR "unexpected argument '$2'"
+				SERVICE=$1
+				;;
+		esac
+		shift 1
+	done
+
+	CHECK_ERRORS
+
+	KUBECTL__SERVE 
+}

plugins/kubectl/set-context

@@ -0,0 +1,41 @@
+#!/bin/zsh
+use kubectl --group kubectl
+#####################################################################
+
+MAIN() {
+	local USAGE="
+	usage: [context] [...options...]
+
+	args:
+	  context   (optional) the full name of the kubeconfig context to set
+
+	options:
+	  --subsession   REDIS subsession (default 0)
+
+	  -h, --help   show this dialogue and exit
+	"
+	local CONTEXT
+	local SUBSESSION=0
+
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in
+			--subsession ) SUBSESSION=$2; shift 1 ;;
+
+			-h | --help ) USAGE; return 0 ;;
+
+			* )
+				[ $CONTEXT ] && ERROR "unexpected argument '$2'"
+				CONTEXT=$1
+				;;
+		esac
+		shift 1
+	done
+
+	[ $CONTEXT ] || CONTEXT=$(KUBECTL__SELECT_CONTEXT)
+	[ $CONTEXT ] || ERROR 'must provide or select a valid kube context'
+
+	CHECK_ERRORS
+
+	KUBECTL__SET_CONTEXT $CONTEXT
+}

plugins/kubectl/set-namespace

@@ -0,0 +1,41 @@
+#!/bin/zsh
+use kubectl --group kubectl
+#####################################################################
+
+MAIN() {
+	local USAGE="
+	usage: [namespace] [...options...]
+
+	args:
+	  namespace   (optional) the full name of the namespace context to set
+
+	options:
+	  --subsession   REDIS subsession (default 0)
+
+	  -h, --help   show this dialogue and exit
+	"
+	local NAMESPACE
+	local SUBSESSION=0
+
+	while [[ $# -gt 0 ]]
+	do
+		case $1 in
+			--subsession ) SUBSESSION=$2; shift 1 ;;
+
+			-h | --help ) USAGE; return 0 ;;
+
+			* )
+				[ $NAMESPACE ] && ERROR "unexpected argument '$2'"
+				NAMESPACE=$1
+				;;
+		esac
+		shift 1
+	done
+
+	[ $NAMESPACE ] || NAMESPACE=$(KUBECTL__SELECT_NAMESPACE)
+	[ $NAMESPACE ] || ERROR 'must provide or select a valid namespace'
+
+	CHECK_ERRORS
+
+	KUBECTL__SET_NAMESPACE $NAMESPACE
+}

py/data/convert/csv-to-json.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python
+from scwrypts import execute
+#####################################################################
+from scwrypts.data import convert
+
+
+description = 'convert csv into json'
+parse_args = []
+
+def main(_args, stream):
+    return convert(
+            input_stream = stream.input,
+            input_type   = 'csv',
+            output_stream = stream.output,
+            output_type   = 'json',
+            )
+
+#####################################################################
+if __name__ == '__main__':
+    execute(main, description, parse_args)

py/data/convert/csv-to-yaml.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python
+from scwrypts import execute
+#####################################################################
+from scwrypts.data import convert
+
+
+description = 'convert csv into yaml'
+parse_args = []
+
+def main(_args, stream):
+    return convert(
+            input_stream = stream.input,
+            input_type   = 'csv',
+            output_stream = stream.output,
+            output_type   = 'yaml',
+            )
+
+#####################################################################
+if __name__ == '__main__':
+    execute(main, description, parse_args)

py/data/convert/json-to-csv.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python
+from scwrypts import execute
+#####################################################################
+from scwrypts.data import convert
+
+
+description = 'convert json into csv'
+parse_args = []
+
+def main(_args, stream):
+    return convert(
+            input_stream = stream.input,
+            input_type   = 'json',
+            output_stream = stream.output,
+            output_type   = 'csv',
+            )
+
+#####################################################################
+if __name__ == '__main__':
+    execute(main, description, parse_args)

py/data/convert/json-to-yaml.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python
+from scwrypts import execute
+#####################################################################
+from scwrypts.data import convert
+
+
+description = 'convert json into yaml'
+parse_args = []
+
+def main(_args, stream):
+    return convert(
+            input_stream = stream.input,
+            input_type   = 'json',
+            output_stream = stream.output,
+            output_type   = 'yaml',
+            )
+
+#####################################################################
+if __name__ == '__main__':
+    execute(main, description, parse_args)

py/data/convert/yaml-to-csv.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python
+from scwrypts import execute
+#####################################################################
+from scwrypts.data import convert
+
+
+description = 'convert yaml into csv'
+parse_args = []
+
+def main(_args, stream):
+    return convert(
+            input_stream = stream.input,
+            input_type   = 'yaml',
+            output_stream = stream.output,
+            output_type   = 'csv',
+            )
+
+#####################################################################
+if __name__ == '__main__':
+    execute(main, description, parse_args)

py/data/convert/yaml-to-json.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python
+from scwrypts import execute
+#####################################################################
+from scwrypts.data import convert
+
+
+description = 'convert yaml into json'
+parse_args = []
+
+def main(_args, stream):
+    return convert(
+            input_stream = stream.input,
+            input_type   = 'yaml',
+            output_stream = stream.output,
+            output_type   = 'json',
+            )
+
+#####################################################################
+if __name__ == '__main__':
+    execute(main, description, parse_args)

py/directus/get-items.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python
+from scwrypts import execute
+#####################################################################
+from json import dumps
+
+from scwrypts.fzf import fzf, fzf_tail
+from scwrypts.http import directus
+
+
+description = 'interactive CLI to get data from directus'
+
+parse_args = [
+        ( ['-c', '--collection'], {
+            "dest"     : 'collection',
+            "default"  : None,
+            "help"     : 'the name of the collection',
+            "required" : False,
+            }),
+        ( ['-f', '--filters'], {
+            "dest"     : 'filters',
+            "default"  : None,
+            "help"     : 'as a URL-suffix, filters for the query',
+            "required" : False,
+            }),
+        ( ['-d', '--fields'], {
+            "dest"     : 'fields',
+            "default"  : None,
+            "help"     : 'comma-separated list of fields to include',
+            "required" : False,
+            }),
+        ( ['-p', '--interactive-prompt'], {
+            "action"   : 'store_true',
+            "dest"     : 'interactive',
+            "default"  : False,
+            "help"     : 'interactively generate filter prompts; implied if no flags are provided',
+            "required" : False,
+            }),
+        ( ['--prompt-filters'], {
+            "action"   : 'store_true',
+            "dest"     : 'generate_filters_prompt',
+            "default"  : False,
+            "help"     : '(superceded by -p) only generate filters interactively',
+            "required" : False,
+            }),
+        ( ['--prompt-fields'], {
+            "action"   : 'store_true',
+            "dest"     : 'generate_fields_prompt',
+            "default"  : False,
+            "help"     : '(superceded by -p) only generate filters interactively',
+            "required" : False,
+            }),
+        ]
+
+def main(args, stream):
+    if {None} == { args.collection, args.filters, args.fields }:
+        args.interactive = True
+
+    if args.interactive:
+        args.generate_filters_prompt = True
+        args.generate_fields_prompt = True
+
+    collection = _get_or_select_collection(args)
+    filters    = _get_or_select_filters(args, collection)
+    fields     = _get_or_select_fields(args, collection)
+
+    query = '&'.join([
+        param for param in [
+            fields,
+            filters,
+            ]
+        if param
+        ])
+
+    endpoint = f'items/{collection}?{query}'
+
+    response = directus.request('GET', endpoint)
+
+    stream.writeline(dumps({
+        **response.json(),
+        'scwrypts_metadata': {
+            'endpoint': endpoint,
+            'repeat_with': f'scwrypts -n py/directus/get-items -- -c {collection} -f \'{query}\'',
+            },
+        }))
+
+def _get_or_select_collection(args):
+    collection = args.collection
+
+    if collection is None:
+        collection = fzf(
+                prompt = 'select a collection',
+                choices = directus.get_collections(),
+                )
+
+    if not collection:
+        raise ValueError('collection required for query')
+
+    return collection
+
+def _get_or_select_filters(args, collection):
+    filters = args.filters or ''
+
+    if filters == '' and args.generate_filters_prompt:
+        filters = '&'.join([
+            f'filter[{filter}][' + (
+                operator := fzf(
+                    prompt = f'select operator for {filter}',
+                    choices = directus.FILTER_OPERATORS,
+                    )
+                ) + ']=' + fzf_tail(prompt = f'filter[{filter}][{operator}]')
+
+            for filter in fzf(
+                prompt = 'select filter(s) [C^c to skip]',
+                fzf_options = '--multi',
+                force_list = True,
+                choices = directus.get_fields(collection),
+                )
+            ])
+
+    return filters
+
+def _get_or_select_fields(args, collection):
+    fields = args.fields or ''
+
+    if fields == '' and args.generate_fields_prompt:
+        fields = ','.join(fzf(
+                prompt = 'select return field(s) [C^c to get all]',
+                fzf_options = '--multi',
+                choices = directus.get_fields(collection),
+                force_list = True,
+                ))
+
+    if fields:
+        fields = f'fields[]={fields}'
+
+    return fields
+
+#####################################################################
+if __name__ == '__main__':
+    execute(main, description, parse_args)

py/discord/post-message.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python
+from scwrypts import execute
+#####################################################################
+from json import dumps
+from sys import stderr
+
+from scwrypts.http import discord
+
+
+description = 'post a message to the indicated discord channel'
+parse_args = [
+        ( ['-b', '--body'], {
+            'dest'     : 'content',
+            'help'     : 'message body',
+            'required' : False,
+            }),
+        ( ['-c', '--channel-id'], {
+            'dest'     : 'channel_id',
+            'help'     : 'override default target channel id',
+            'required' : False,
+            }),
+        ( ['-w', '--webhook'], {
+            'dest'     : 'webhook',
+            'help'     : 'override default target webhook (takes precedence over -c)',
+            'required' : False,
+            }),
+        ( ['--avatar-url'], {
+            'dest'     : 'avatar_url',
+            'help'     : 'override default avatar_url',
+            'required' : False,
+            }),
+        ( ['--username'], {
+            'dest'     : 'username',
+            'help'     : 'override default username',
+            'required' : False,
+            }),
+        ]
+
+def main(args, stream):
+    if args.content is None:
+        print(f'reading input from {stream.input.name}', file=stderr)
+        args.content = ''.join(stream.readlines()).strip()
+
+    if len(args.content) == 0:
+        args.content = 'PING'
+
+    response = discord.send_message(**vars(args))
+
+    stream.writeline(dumps({
+        **(response.json() if response.text != '' else {'message': 'OK'}),
+        'scwrypts_metadata': {},
+        }))
+
+
+#####################################################################
+if __name__ == '__main__':
+    execute(main, description, parse_args)

py/hello-world.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python
+from scwrypts import execute
+#####################################################################
+
+description = 'a simple "Hello, World!" program'
+parse_args = [
+        ( ['-m', '--message'], {
+            'dest'     : 'message',
+            'default'  : 'HELLO WORLD',
+            'help'     : 'message to print',
+            'required' : False,
+            }),
+        ]
+
+def main(args, stream):
+    stream.writeline(args.message)
+
+
+#####################################################################
+if __name__ == '__main__':
+    execute(main, description, parse_args)

py/hello_world.py

@@ -1,7 +0,0 @@
-#!/usr/bin/env python
-
-def main():
-    print('HELLO WORLD')
-
-if __name__ == '__main__':
-    main()

py/lib/.gitignore

@@ -0,0 +1 @@
+dist/

py/lib/README.md

@@ -0,0 +1,3 @@
+# Python Scwrypts
+[![Generic Badge](https://img.shields.io/badge/python->=3.9-informational.svg)](https://python.org)
+<br>

py/lib/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = 'scwrypts'
+description = 'scwrypts library and invoker'
+license = 'GPL-3.0-or-later'
+
+readme = 'README.md'
+requires-python = '>=3.10'
+
+authors = [
+	{ name='yage', email='yage@yage.io' },
+]
+
+
+classifiers = [
+	'Programming Language :: Python :: 3',
+	'Programming Language :: Python :: 3.10',
+	'Programming Language :: Python :: 3.11',
+	'Programming Language :: Python :: 3.12',
+	'License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)',
+	]
+
+dynamic = ['version']
+
+dependencies = [
+	'bpython',
+	'pyfzf',
+	'pyyaml',
+	'redis',
+	'twilio',
+]
+
+[project.optional-dependencies]
+dev = [
+	'pylint',
+]
+
+test = [
+	'pytest',
+]
+
+[project.urls]
+homepage = 'https://github.com/wrynegade/scwrypts'
+issues = 'https://github.com/wrynegade/scwrypts/issues'
+
+[build-system]
+requires = [
+	'hatchling',
+	'versioningit',
+]
+build-backend = 'hatchling.build'
+
+[tool.hatch.version]
+source = 'versioningit'
+
+[tool.hatch.build.targets.wheel]
+packages = ['./']
+
+[tool.versioningit]
+match = ['v*']
+

py/lib/scwrypts/__init__.py

@@ -0,0 +1,9 @@
+'''
+scwrypts
+
+python library functions and invoker for scwrypts
+'''
+
+from .scwrypts.execute import execute
+from .scwrypts.interactive import interactive
+from .scwrypts.scwrypts import scwrypts

py/lib/scwrypts/data/__init__.py

@@ -0,0 +1 @@
+from .converter import convert

py/lib/scwrypts/data/converter.py

@@ -0,0 +1,70 @@
+import csv
+import json
+import yaml
+
+
+def convert(input_stream, input_type, output_stream, output_type):
+    data = convert_input(input_stream, input_type)
+    write_output(output_stream, output_type, data)
+
+
+def convert_input(stream, input_type):
+    supported_input_types  = {'csv', 'json', 'yaml'}
+
+    if input_type not in supported_input_types:
+        raise ValueError(f'input_type "{input_type}" not supported; must be one of {supported_input_types}')
+
+    return {
+            'csv':  _read_csv,
+            'json': _read_json,
+            'yaml': _read_yaml,
+            }[input_type](stream)
+
+
+def write_output(stream, output_type, data):
+    supported_output_types = {'csv', 'json', 'yaml'}
+
+    if output_type not in supported_output_types:
+        raise ValueError(f'output_type "{output_type}" not supported; must be one of {supported_output_types}')
+
+    return {
+            'csv':  _write_csv,
+            'json': _write_json,
+            'yaml': _write_yaml,
+            }[output_type](stream, data)
+
+
+#####################################################################
+
+def _read_csv(stream):
+    return [dict(line) for line in csv.DictReader(stream)]
+
+def _write_csv(stream, data):
+    writer = csv.DictWriter(stream, fieldnames=list({
+        key
+        for dictionary in data
+        for key in dictionary.keys()
+        }))
+
+    writer.writeheader()
+
+    for value in data:
+        writer.writerow(value)
+
+#####################################################################
+
+def _read_json(stream):
+    data = json.loads(stream.read())
+    return data if isinstance(data, list) else [data]
+
+def _write_json(stream, data):
+    stream.write(json.dumps(data))
+
+#####################################################################
+
+def _read_yaml(stream):
+    data = yaml.safe_load(stream)
+    return data if isinstance(data, list) else [data]
+
+def _write_yaml(stream, data):
+    yaml.dump(data, stream, default_flow_style=False)

py/lib/scwrypts/data/test_converter.py

@@ -0,0 +1,75 @@
+from io import StringIO
+#from string import ascii_letters, digits
+from unittest.mock import patch
+
+from pytest import raises
+
+from scwrypts.test import generate
+
+from .converter import convert
+
+GENERATE_OPTIONS = {
+        'depth': 1,
+        'minimum': -999999,
+        'maximum':  999999,
+        'dict_key_types': {str, int},
+        'csv_columns_minimum': 10,
+        'csv_columns_maximum': 64,
+        'csv_rows_minimum': 10,
+        'csv_rows_maximum': 64,
+        }
+
+INPUT_TYPES  = {'csv', 'json', 'yaml'}
+OUTPUT_TYPES = {'csv', 'json', 'yaml'}
+
+
+def test_convert_to_csv():
+    for input_type in INPUT_TYPES:
+        input_stream = generate(input_type, {
+            **GENERATE_OPTIONS,
+            'data_types': {bool,int,float,str},
+            })
+
+        if isinstance(input_stream, str):
+            input_stream = StringIO(input_stream)
+
+
+        convert(input_stream, input_type, StringIO(), 'csv')
+
+def test_convert_to_json():
+    for input_type in INPUT_TYPES:
+        input_stream = generate(input_type, GENERATE_OPTIONS)
+
+        if isinstance(input_stream, str):
+            input_stream = StringIO(input_stream)
+
+        convert(input_stream, input_type, StringIO(), 'json')
+
+def test_convert_to_yaml():
+    for input_type in INPUT_TYPES:
+        input_stream = generate(input_type, GENERATE_OPTIONS)
+
+        if isinstance(input_stream, str):
+            input_stream = StringIO(input_stream)
+
+        convert(input_stream, input_type, StringIO(), 'yaml')
+
+
+def test_convert_deep_json_to_yaml():
+    input_stream = StringIO(generate('json', {**GENERATE_OPTIONS, 'depth': 4}))
+    convert(input_stream, 'json', StringIO(), 'yaml')
+
+def test_convert_deep_yaml_to_json():
+    input_stream = generate('yaml', {**GENERATE_OPTIONS, 'depth': 4})
+    convert(input_stream, 'yaml', StringIO(), 'json')
+
+
+def test_convert_output_unsupported():
+    for input_type in list(INPUT_TYPES):
+        with raises(ValueError):
+            convert(StringIO(), input_type, StringIO(), generate(str))
+
+def test_convert_input_unsupported():
+    for output_type in list(OUTPUT_TYPES):
+        with raises(ValueError):
+            convert(StringIO(), generate(str), StringIO(), output_type)

py/lib/scwrypts/env.py

@@ -1,16 +1,15 @@
 from os import getenv as os_getenv
 
-from py.scwrypts.exceptions import MissingVariableError
-from py.scwrypts.run import run
+from .scwrypts.exceptions import MissingVariableError
 
 
 def getenv(name, required=True):
     value = os_getenv(name, None)
 
-    if value == None:
-        run('zsh/scwrypts/environment/stage-variables', name)
-
     if required and not value:
         raise MissingVariableError(name)
 
+    if value == '':
+        value = None
+
     return value

py/lib/scwrypts/fzf/__init__.py

@@ -0,0 +1 @@
+from .client import fzf, fzf_tail, fzf_head

py/lib/scwrypts/fzf/client.py

@@ -0,0 +1,61 @@
+from pyfzf.pyfzf import FzfPrompt
+
+FZF_PROMPT = None
+
+
+def fzf( # pylint: disable=too-many-arguments
+        choices=None,
+        prompt=None,
+        fzf_options='',
+        delimiter='\n',
+        return_type=str,
+        force_list=False,
+        ):
+    global FZF_PROMPT # pylint: disable=global-statement
+
+    if choices is None:
+        choices = []
+
+    if not isinstance(return_type, type):
+        raise ValueError(f'return_type must be a valid python type; "{return_type}" is not a type')
+
+    if FZF_PROMPT is None:
+        FZF_PROMPT = FzfPrompt()
+
+    options = ' '.join({
+        '-i',
+        '--layout=reverse',
+        '--ansi',
+        '--height=30%',
+        f'--prompt "{prompt} : "' if prompt is not None else '',
+        fzf_options,
+        })
+
+    selections = [
+            return_type(selection)
+            for selection in FZF_PROMPT.prompt(choices, options, delimiter)
+            ]
+
+    if not force_list:
+        if len(selections) == 0:
+            return None
+
+        if len(selections) == 1:
+            return selections[0]
+
+    return selections
+
+
+def fzf_tail(*args, **kwargs):
+    return _fzf_print(*args, **kwargs)[-1]
+
+def fzf_head(*args, **kwargs):
+    return _fzf_print(*args, **kwargs)[0]
+
+def _fzf_print(*args, fzf_options='', **kwargs):
+    return fzf(
+            *args,
+            **kwargs,
+            fzf_options = f'--print-query {fzf_options}',
+            force_list = True,
+            )

py/lib/scwrypts/http/__init__.py

@@ -0,0 +1 @@
+from .client import get_request_client

py/lib/scwrypts/http/client.py

@@ -0,0 +1,20 @@
+from requests import request
+
+
+def get_request_client(base_url, headers=None):
+    if headers is None:
+        headers = {}
+
+    return lambda method, endpoint, **kwargs: request(
+            method = method,
+            url = f'{base_url}/{endpoint}',
+            headers = {
+                **headers,
+                **kwargs.get('headers', {}),
+                },
+            **{
+                key: value
+                for key, value in kwargs.items()
+                if key != 'headers'
+                },
+            )

py/lib/scwrypts/http/directus/__init__.py

@@ -0,0 +1,27 @@
+from .client import *
+
+FILTER_OPERATORS = {
+        '_eq',
+        '_neq',
+        '_lt',
+        '_lte',
+        '_gt',
+        '_gte',
+        '_in',
+        '_nin',
+        '_null',
+        '_nnull',
+        '_contains',
+        '_ncontains',
+        '_starts_with',
+        '_ends_with',
+        '_nends_with',
+        '_between',
+        '_nbetween',
+        '_empty',
+        '_nempty',
+        '_intersects',
+        '_nintersects',
+        '_intersects_bbox',
+        '_nintersects_bbox',
+        }

py/lib/scwrypts/http/directus/client.py

@@ -0,0 +1,57 @@
+from scwrypts.env import getenv
+
+from .. import get_request_client
+
+
+REQUEST     = None
+COLLECTIONS = None
+FIELDS      = {}
+
+
+def request(method, endpoint, **kwargs):
+    global REQUEST # pylint: disable=global-statement
+
+    if REQUEST is None:
+        REQUEST = get_request_client(
+                base_url = getenv("DIRECTUS__BASE_URL"),
+                headers = {
+                    'Authorization': f'bearer {getenv("DIRECTUS__API_TOKEN")}',
+                    }
+                )
+
+    return REQUEST(method, endpoint, **kwargs)
+
+def graphql(query, system=False):
+    return request(
+            'POST',
+            'graphql' if system is True else 'graphql/system',
+            json={'query': query},
+            )
+
+
+def get_collections():
+    global COLLECTIONS # pylint: disable=global-statement
+
+    if COLLECTIONS is None:
+        COLLECTIONS = [
+            item['collection']
+            for item in request(
+                'GET',
+                'collections?limit=-1&fields[]=collection',
+                ).json()['data']
+            ]
+
+    return COLLECTIONS
+
+
+def get_fields(collection):
+    if FIELDS.get(collection) is None:
+        FIELDS[collection] = [
+                item['field']
+                for item in request(
+                    'GET',
+                    f'fields/{collection}?limit=-1&fields[]=field',
+                    ).json()['data']
+                ]
+
+    return FIELDS[collection]

py/lib/scwrypts/http/discord/__init__.py

@@ -0,0 +1,2 @@
+from .client import *
+from .send_message import *

py/lib/scwrypts/http/discord/client.py

@@ -0,0 +1,20 @@
+from scwrypts.env import getenv
+from scwrypts.http import get_request_client
+
+REQUEST = None
+
+def request(method, endpoint, **kwargs):
+    global REQUEST # pylint: disable=global-statement
+
+    if REQUEST is None:
+        headers = {}
+
+        if (token := getenv("DISCORD__BOT_TOKEN", required = False)) is not None:
+            headers['Authorization'] = f'Bot {token}'
+
+        REQUEST = get_request_client(
+                base_url = 'https://discord.com/api',
+                headers = headers,
+                )
+
+    return REQUEST(method, endpoint, **kwargs)

py/lib/scwrypts/http/discord/send_message.py

@@ -0,0 +1,48 @@
+from scwrypts.env import getenv
+from .client import request
+
+def send_message(content, channel_id=None, webhook=None, username=None, avatar_url=None, **kwargs):
+    if username is None:
+        username = getenv('DISCORD__DEFAULT_USERNAME', required=False)
+
+    if avatar_url is None:
+        avatar_url = getenv('DISCORD__DEFAULT_AVATAR_URL', required=False)
+
+    endpoint = None
+
+    if webhook is not None:
+        endpoint = f'webhooks/{webhook}'
+
+    elif channel_id is not None:
+        endpoint = f'channels/{channel_id}/messages'
+
+    elif (webhook := getenv('DISCORD__DEFAULT_WEBHOOK', required=False)) is not None:
+        endpoint = f'webhooks/{webhook}'
+
+    elif (channel_id := getenv('DISCORD__DEFAULT_CHANNEL_ID', required=False)) is not None:
+        endpoint = f'channels/{channel_id}/messages'
+
+    else:
+        raise ValueError('must provide target channel_id or webhook')
+
+    if (header := getenv('DISCORD__CONTENT_HEADER', required=False)) is not None:
+        content = f'{header}{content}'
+
+    if (footer := getenv('DISCORD__CONTENT_FOOTER', required=False)) is not None:
+        content = f'{content}{footer}'
+
+
+    return request(
+            method = 'POST',
+            endpoint = endpoint,
+            json = {
+                key: value
+                for key, value in {
+                    'content': content,
+                    'username': username,
+                    'avatar_url': avatar_url,
+                    **kwargs,
+                    }.items()
+                if value is not None
+                },
+            )

py/lib/scwrypts/http/linear/__init__.py

@@ -0,0 +1 @@
+from .client import *

py/lib/scwrypts/http/linear/client.py

@@ -0,0 +1,21 @@
+from scwrypts.env import getenv
+
+from .. import get_request_client
+
+REQUEST = None
+
+def request(method, endpoint, **kwargs):
+    global REQUEST # pylint: disable=global-statement
+
+    if REQUEST is None:
+        REQUEST = get_request_client(
+                base_url = 'https://api.linear.app',
+                headers = {
+                    'Authorization': f'bearer {getenv("LINEAR__API_TOKEN")}',
+                    }
+                )
+
+    return REQUEST(method, endpoint, **kwargs)
+
+def graphql(query):
+    return request('POST', 'graphql', json={'query': query})

py/lib/scwrypts/io/__init__.py

@@ -0,0 +1 @@
+from .combined_io_stream import get_combined_stream, add_io_arguments

py/lib/scwrypts/io/combined_io_stream.py

@@ -0,0 +1,86 @@
+from contextlib import contextmanager
+from pathlib import Path
+from sys import stdin, stdout, stderr
+
+from scwrypts.env import getenv
+
+
+@contextmanager
+def get_stream(filename=None, mode='r', encoding='utf-8', verbose=False, **kwargs):
+    allowed_modes = {'r', 'w', 'w+'}
+
+    if mode not in allowed_modes:
+        raise ValueError(f'mode "{mode}" not supported modes (must be one of {allowed_modes})')
+
+    is_read = mode == 'r'
+
+    if filename is not None:
+
+        if verbose:
+            print(f'opening file {filename} for {"read" if is_read else "write"}', file=stderr)
+
+        if filename[0] not in {'/', '~'}:
+            filename = Path(f'{getenv("EXECUTION_DIR")}/{filename}').resolve()
+        with open(filename, mode=mode, encoding=encoding, **kwargs) as stream:
+            yield stream
+
+    else:
+        if verbose:
+            print('using stdin for read' if is_read else 'using stdout for write', file=stderr)
+
+        yield stdin if is_read else stdout
+
+        if not is_read:
+            stdout.flush()
+
+
+def add_io_arguments(parser, allow_input=True, allow_output=True):
+    if allow_input:
+        parser.add_argument(
+                '-i', '--input-file',
+                dest     = 'input_file',
+                default  = None,
+                help     = 'path to input file; omit for stdin',
+                required = False,
+                )
+
+    if allow_output:
+        parser.add_argument(
+                '-o', '--output-file',
+                dest     = 'output_file',
+                default  = None,
+                help     = 'path to output file; omit for stdout',
+                required = False,
+                )
+
+
+@contextmanager
+def get_combined_stream(input_file=None, output_file=None):
+    with get_stream(input_file, 'r') as input_stream, get_stream(output_file, 'w+') as output_stream:
+        yield CombinedStream(input_stream, output_stream)
+
+
+class CombinedStream:
+    def __init__(self, input_stream, output_stream):
+        self.input = input_stream
+        self.output = output_stream
+
+    def read(self, *args, **kwargs):
+        return self.input.read(*args, **kwargs)
+
+    def readline(self, *args, **kwargs):
+        return self.input.readline(*args, **kwargs)
+
+    def readlines(self, *args, **kwargs):
+        return self.input.readlines(*args, **kwargs)
+
+    def write(self, *args, **kwargs):
+        return self.output.write(*args, **kwargs)
+
+    def writeline(self, line):
+        x = self.output.write(f'{line}\n')
+        self.output.flush()
+        return x
+
+    def writelines(self, *args, **kwargs):
+        return self.output.writelines(*args, **kwargs)

py/lib/scwrypts/redis/__init__.py

@@ -0,0 +1 @@
+from .client import get_client

py/lib/scwrypts/redis/client.py

@@ -0,0 +1,19 @@
+from redis import StrictRedis
+
+from scwrypts.env import getenv
+
+CLIENT = None
+
+def get_client():
+    global CLIENT # pylint: disable=global-statement
+
+    if CLIENT is None:
+        print('getting redis client')
+        CLIENT = StrictRedis(
+                host = getenv('REDIS_HOST'),
+                port = getenv('REDIS_PORT'),
+                password = getenv('REDIS_AUTH', required=False),
+                decode_responses = True,
+                )
+
+    return CLIENT

py/lib/scwrypts/scwrypts/exceptions.py

@@ -0,0 +1,16 @@
+from argparse import ArgumentError
+
+
+class MissingVariableError(EnvironmentError):
+    def init(self, name):
+        super().__init__(f'Missing required environment variable "{name}"')
+
+
+class MissingFlagAndEnvironmentVariableError(EnvironmentError, ArgumentError):
+    def __init__(self, flags, env_var):
+        super().__init__(f'must provide at least one of : {{ flags: {flags} OR {env_var} }}')
+
+
+class MissingScwryptsExecutableError(EnvironmentError):
+    def __init__(self):
+        super().__init__(f'scwrypts must be installed and available on your PATH')

py/lib/scwrypts/scwrypts/execute.py

@@ -0,0 +1,26 @@
+from argparse import ArgumentParser, ArgumentDefaultsHelpFormatter
+
+from scwrypts.io import get_combined_stream, add_io_arguments
+
+
+def execute(main, description=None, parse_args=None, allow_input=True, allow_output=True):
+    '''
+    API to initiate a python-based scwrypt
+    '''
+    if parse_args is None:
+        parse_args = []
+
+    parser = ArgumentParser(
+            description = description,
+            formatter_class = ArgumentDefaultsHelpFormatter,
+            )
+
+    add_io_arguments(parser, allow_input, allow_output)
+
+    for a in parse_args:
+        parser.add_argument(*a[0], **a[1])
+
+    args = parser.parse_args()
+
+    with get_combined_stream(args.input_file, args.output_file) as stream:
+        return main(args, stream)

py/lib/scwrypts/scwrypts/interactive.py

@@ -0,0 +1,25 @@
+from bpython import embed
+
+
+def interactive(variable_descriptions):
+    '''
+    main() decorator to drop to interactive python environment upon completion
+    '''
+    def outer(function):
+
+        def inner(*args, **kwargs):
+
+            print('\npreparing interactive environment...\n')
+
+            local_vars = function(*args, **kwargs)
+
+            print('\n\n'.join([
+                f'>>> {x}' for x in variable_descriptions
+                ]))
+            print('\nenvironment ready; user, GO! :)\n')
+
+            embed(local_vars)
+
+        return inner
+
+    return outer

py/lib/scwrypts/scwrypts/scwrypts.py

@@ -0,0 +1,30 @@
+from os import getenv
+from shutil import which
+from subprocess import run
+
+from .exceptions import MissingScwryptsExecutableError
+
+
+def scwrypts(name, group, _type, *args, log_level=None):
+    '''
+    invoke non-python scwrypts from python
+    '''
+    executable = which('scwrypts')
+    if executable is None:
+        raise MissingScwryptsExecutableError()
+
+    pre_args = ''
+
+    if log_level is not None:
+        pre_args += '--log-level {log_level}'
+
+    depth = getenv('SUBSCWRYPT', '')
+    if depth != '':
+        depth = int(depth) + 1
+
+    return run(
+        f'SUBSCWRYPT={depth} {executable} --name {name} --group {group} --type {_type} {pre_args} -- {" ".join(args)}',
+        shell=True,
+        executable='/bin/zsh',
+        check=False,
+        )

py/lib/scwrypts/test/__init__.py

@@ -0,0 +1 @@
+from .random_generator import generate

py/lib/scwrypts/test/exceptions.py

@@ -0,0 +1,10 @@
+class GeneratorError(Exception):
+    pass
+
+class NoDataTypeError(GeneratorError, ValueError):
+    def __init__(self):
+        super().__init__('must provide at least one data type (either "data_type" or "data_types")')
+
+class BadGeneratorTypeError(GeneratorError, ValueError):
+    def __init__(self, data_type):
+        super().__init__(f'no generator exists for data type "{data_type}"')

py/lib/scwrypts/test/random_generator.py

@@ -0,0 +1,240 @@
+from csv import writer, QUOTE_NONNUMERIC
+from io import StringIO
+from json import dumps
+from random import randint, uniform, choice
+from re import sub
+from string import printable
+from yaml import safe_dump
+
+from .exceptions import NoDataTypeError, BadGeneratorTypeError
+
+
+SUPPORTED_DATA_TYPES = None
+
+DEFAULT_OPTIONS = {
+        'data_types': None,
+        'minimum':  0,
+        'maximum': 64,
+        'depth': 1,
+        'character_set': None,
+        'bool_nullable': False,
+        'str_length': None,
+        'str_minimum_length': 0,
+        'str_maximum_length': 32,
+        'list_length': 8,
+        'set_length': 8,
+        'dict_length': 8,
+        'dict_key_types': {int, float, chr, str},
+        'csv_columns': None,
+        'csv_columns_minimum': 1,
+        'csv_columns_maximum': 16,
+        'csv_rows': None,
+        'csv_rows_minimum': 2,
+        'csv_rows_maximum': 16,
+        'json_initial_type': dict,
+        'yaml_initial_type': dict,
+        }
+
+def generate(data_type=None, options=None):
+    '''
+    generate random data with the call of a function
+        use data_type to generate a single value
+
+        use options to set generation options (key = type, value = kwargs)
+
+        use options.data_types and omit data_type to generate a random type
+    '''
+    if options is None:
+        options = {**DEFAULT_OPTIONS}
+    else:
+        options = DEFAULT_OPTIONS | options
+
+    if data_type is None and options['data_types'] is None:
+        raise NoDataTypeError()
+
+    if data_type is None and options['data_types'] is not None:
+        return generate(data_type=choice(list(options['data_types'])), options=options)
+
+    if not isinstance(data_type, str):
+        data_type = data_type.__name__
+
+    if data_type not in Generator.get_supported_data_types():
+        raise BadGeneratorTypeError(data_type)
+
+    return getattr(Generator, f'_{data_type}')(options)
+
+#####################################################################
+
+class Generator:
+
+    @classmethod
+    def get_supported_data_types(cls):
+        global SUPPORTED_DATA_TYPES  # pylint: disable=global-statement
+        if SUPPORTED_DATA_TYPES is None:
+            SUPPORTED_DATA_TYPES = {
+                    sub('^_', '', data_type)
+                    for data_type, method in Generator.__dict__.items()
+                    if isinstance(method, staticmethod)
+                    }
+
+        return SUPPORTED_DATA_TYPES
+
+
+
+    @staticmethod
+    def _bool(options):
+        return choice([True, False, None]) if options['bool_nullable'] else choice([True, False])
+
+
+    @staticmethod
+    def _int(options):
+        return randint(options['minimum'], options['maximum'])
+
+
+    @staticmethod
+    def _float(options):
+        return uniform(options['minimum'], options['maximum'])
+
+
+    @staticmethod
+    def _chr(options):
+        character_set = options['character_set']
+        return choice(character_set) if character_set is not None else chr(randint(0,65536))
+
+
+    @staticmethod
+    def _str(options):
+        length = options['str_length']
+        if length is None:
+            length = generate(int, {
+                'minimum': options['str_minimum_length'],
+                'maximum': options['str_maximum_length'],
+                })
+        return ''.join((generate(chr, options) for _ in range(length)))
+
+
+    @staticmethod
+    def _list(options):
+        if options['depth'] <= 0:
+            return []
+
+        options['depth'] -= 1
+
+        if options['data_types'] is None:
+            options['data_types'] = {bool, int, float, chr, str}
+
+        return [ generate(None, options) for _ in range(options['list_length']) ]
+
+
+    @staticmethod
+    def _set(options):
+        if options['depth'] <= 0:
+            return set()
+
+        options['depth'] -= 1
+
+        if options['data_types'] is None:
+            options['data_types'] = {bool, int, float, chr, str}
+
+        set_options = options | {'data_types': options['data_types'] - {list, dict, set}}
+
+        return { generate(None, set_options) for _ in range(options['set_length']) }
+
+
+    @staticmethod
+    def _dict(options):
+        if options['depth'] <= 0:
+            return {}
+
+        options['depth'] -= 1
+
+        if options['data_types'] is None:
+            options['data_types'] = {bool, int, float, chr, str, list, set, dict}
+
+        if len(options['data_types']) == 0:
+            return {}
+
+        key_options = options | {'data_types': options['dict_key_types']}
+        return {
+                generate(None, key_options): generate(None, options)
+                for _ in range(options['dict_length'])
+                }
+
+
+    @staticmethod
+    def _csv(options):
+        '''
+        creates a StringIO object containing csv data
+        '''
+        if options['data_types'] is None:
+            options['data_types'] = {int, float, str}
+
+        columns = options['csv_columns']
+        if columns is None:
+            columns = max(1, generate(int, {
+                'minimum': options['csv_columns_minimum'],
+                'maximum': options['csv_columns_maximum'],
+                }))
+
+        rows = options['csv_rows']
+        if rows is None:
+            rows = max(1, generate(int, {
+                'minimum': options['csv_rows_minimum'],
+                'maximum': options['csv_rows_maximum'],
+                }))
+
+        if options['character_set'] is None:
+            options['character_set'] = printable
+
+        csv = StringIO()
+        csv_writer = writer(csv, quoting=QUOTE_NONNUMERIC)
+
+        options['list_length'] = columns
+
+        for line in [ generate(list, options) for _ in range(rows) ]:
+            csv_writer.writerow(line)
+
+        csv.seek(0)
+        return csv
+
+
+    @staticmethod
+    def _json(options):
+        '''
+        creates a str containing json data
+        '''
+        if options['data_types'] is None:
+            options['data_types'] = {bool, int, float, str, list, dict}
+
+        if options['character_set'] is None:
+            options['character_set'] = printable
+
+        options['dict_key_types'] = { int, float, str }
+
+        data = generate(options['json_initial_type'], options)
+        return dumps(data)
+
+
+    @staticmethod
+    def _yaml(options):
+        '''
+        creates a StringIO object containing yaml data
+        '''
+        if options['data_types'] is None:
+            options['data_types'] = {bool, int, float, str, list, dict}
+
+        if options['character_set'] is None:
+            options['character_set'] = printable
+
+        options['dict_key_types'] = { int, float, str }
+
+        yaml = StringIO()
+        safe_dump(generate(options['yaml_initial_type'], options), yaml, default_flow_style=False)
+
+        yaml.seek(0)
+        return yaml
+
+
+#####################################################################
+if __name__ == '__main__':
+    print(generate('json', {'depth': 3}))

py/lib/scwrypts/test/test_random_generator.py

@@ -0,0 +1,44 @@
+from os import getenv
+from random import randint
+
+from .random_generator import generate, Generator
+
+
+ITERATIONS = int(getenv('PYTEST_ITERATIONS__scwrypts__test__random_generator', getenv('PYTEST_ITERATIONS', '999')))
+
+
+def test_generate():  # generators should be quick and "just work" (no Exceptions)
+    for data_type in Generator.get_supported_data_types():
+        for _ in range(ITERATIONS):
+            generate(data_type)
+
+
+def test_generate_depth_deep():
+    for data_type in Generator.get_supported_data_types():
+        generate(data_type, {'depth': 4})
+
+def test_generate_depth_shallow():
+    for data_type in Generator.get_supported_data_types():
+        generate(data_type, {'depth': randint(-999, 0)})
+
+
+def test_generate_range_all():
+    for data_type in Generator.get_supported_data_types():
+        generate(data_type, {'minimum': -99, 'maximum': 99})
+
+def test_generate_range_positive():
+    for data_type in Generator.get_supported_data_types():
+        generate(data_type, {'minimum':   1, 'maximum': 99})
+
+def test_generate_range_zero():
+    for data_type in Generator.get_supported_data_types():
+        generate(data_type, {'minimum':   3, 'maximum':  3})
+
+def test_generate_range_negative():
+    for data_type in Generator.get_supported_data_types():
+        generate(data_type, {'minimum': -99, 'maximum': -1})
+
+
+def test_generate_bool_nullable():
+    for data_type in Generator.get_supported_data_types():
+        generate(data_type, {'bool': {'nullable': True}})

py/lib/scwrypts/twilio/__init__.py

@@ -0,0 +1,2 @@
+from .client import get_client
+from .send_sms import send_sms

py/lib/scwrypts/twilio/client.py

@@ -0,0 +1,18 @@
+from twilio.rest import Client
+
+from scwrypts.env import getenv
+
+CLIENT = None
+
+def get_client():
+    global CLIENT # pylint: disable=global-statement
+
+    if CLIENT is None:
+        print('loading client')
+        CLIENT = Client(
+                username = getenv('TWILIO__API_KEY'),
+                password = getenv('TWILIO__API_SECRET'),
+                account_sid = getenv('TWILIO__ACCOUNT_SID'),
+                )
+
+    return CLIENT

py/lib/scwrypts/twilio/send_sms.py

@@ -0,0 +1,57 @@
+from json import dumps
+from time import sleep
+
+from .client import get_client
+
+
+def send_sms(to, from_, body, max_char_count=300, stream=None):
+    '''
+    abstraction for twilio.client.messages.create which will break
+    messages into multi-part SMS rather than throwing an error or
+    requiring the use of MMS data
+
+    @param to               messages.create parameter
+    @param from_            messages.create parameter
+    @param body             messages.create parameter
+    @param max_char_count   1 ≤ N ≤ 1500 (default 300)
+    @param stream           used to report success/failure (optional)
+
+    @return   a list of twilio MessageInstance objects
+    '''
+    client = get_client()
+    messages = []
+
+    max_char_count = max(1, min(max_char_count, 1500))
+
+    total_sms_parts = 1 + len(body) // max_char_count
+    contains_multiple_parts = total_sms_parts > 1
+
+    for i in range(0, len(body), max_char_count):
+        msg_body = body[i:i+max_char_count]
+        current_part = 1 + i // max_char_count
+
+        if contains_multiple_parts:
+            msg_body = f'{current_part}/{total_sms_parts}\n{msg_body}'
+
+        message = client.messages.create(
+                to = to,
+                from_ = from_,
+                body = msg_body,
+                )
+
+        messages.append(message)
+
+        if stream is not None:
+            stream.writeline(
+                    dumps({
+                        'sid': message.sid,
+                        'to': to,
+                        'from': from_,
+                        'body': msg_body,
+                        })
+                    )
+
+        if contains_multiple_parts:
+            sleep(2 if max_char_count <= 500 else 5)
+
+    return messages

py/linear/comment.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python
+from scwrypts import execute
+#####################################################################
+from scwrypts.http.linear import graphql
+
+
+description = 'comment on an issue in linear.app'
+parse_args = [
+        ( ['-d', '--issue-id'], {
+            'dest'     : 'issue_id',
+            'help'     : 'issue short-code (e.g. CLOUD-319)',
+            'required' : True,
+            }),
+        ( ['-m', '--message'], {
+            'dest'     : 'message',
+            'help'     : 'comment to post to the target issue',
+            'required' : True,
+            }),
+        ]
+
+
+def get_query(args):
+    body = f'"""from wrobot:\n```\n{args.message}\n```\n"""'
+    return f'''
+        mutation CommentCreate {{
+            commentCreate(
+                input: {{
+                    issueId: "{args.issue_id}"
+                    body:    {body}
+                }}
+            ) {{ success }}
+        }}'''
+
+def main(args, stream):
+    response = graphql(get_query(args))
+    stream.writeline(response)
+
+#####################################################################
+if __name__ == '__main__':
+    execute(main, description, parse_args)

py/redis/client.py

@@ -1,15 +0,0 @@
-from redis import StrictRedis
-
-from py.scwrypts import getenv
-
-
-class RedisClient(StrictRedis):
-    def __init__(self):
-        super().__init__(
-                host = getenv('REDIS_HOST'),
-                port = getenv('REDIS_PORT'),
-                password = getenv('REDIS_AUTH'),
-                decode_responses = True,
-                )
-
-Client = RedisClient()

py/redis/interactive.py

@@ -1,19 +1,23 @@
 #!/usr/bin/env python
-
-from py.redis.client import Client
-from py.scwrypts import interactive, getenv
+from scwrypts import execute
+#####################################################################
+from scwrypts import interactive
+from scwrypts.env import getenv
+from scwrypts.redis import get_client
 
 
-@interactive
-def main():
-    r = Client
-
-    print(f'''
->>> r = StrictRedis({getenv("REDIS_HOST")}:{getenv("REDIS_PORT")})
-    ''')
+description = 'establishes a redis client in an interactive python shell'
+parse_args = []
 
+@interactive([
+        f'r = StrictRedis(\'{getenv("REDIS_HOST")}:{getenv("REDIS_PORT")}\')',
+    ])
+def main(_args, _stream):
+    # pylint: disable=possibly-unused-variable
+    r = get_client()
     return locals()
 
 
+#####################################################################
 if __name__ == '__main__':
-    main()
+    execute(main, description, parse_args)

py/requirements.txt

@@ -1,2 +1 @@
-redis
-bpython
+./lib

py/scwrypts/__init__.py

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

py/scwrypts/exceptions.py

@@ -1,3 +0,0 @@
-class MissingVariableError(Exception):
-    def init(self, name):
-        super().__init__(f'Missing required environment variable "{name}"')

py/scwrypts/interactive.py

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

py/scwrypts/run.py

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

py/twilio/send-sms.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python
+from scwrypts import execute
+#####################################################################
+from sys import stderr
+
+from scwrypts.env import getenv
+from scwrypts.twilio import send_sms
+
+
+description = 'send a simple SMS through twilio'
+parse_args = [
+        ( ['-t', '--to'], {
+            'dest'     : 'to',
+            'help'     : 'phone number of the receipient',
+            'required' : False,
+            'default'  : getenv('TWILIO__DEFAULT_PHONE_TO', required=False),
+            }),
+        ( ['-f', '--from'], {
+            'dest'     : 'from_',
+            'help'     : 'phone number of the receipient',
+            'required' : False,
+            'default'  : getenv('TWILIO__DEFAULT_PHONE_FROM', required=False),
+            }),
+        ( ['-b', '--body'], {
+            'dest'     : 'body',
+            'help'     : 'message body',
+            'required' : False,
+            }),
+        ( ['--max-char-count'], {
+            'dest'     : 'max_char_count',
+            'help'     : 'separate message into parts by character count (1 < N <= 1500)',
+            'required' : False,
+            'default'  : 300,
+            }),
+        ]
+
+def main(args, stream):
+    if args.body is None:
+        print(f'reading input from {stream.input.name}', file=stderr)
+        args.body = ''.join(stream.readlines()).strip()
+
+    if len(args.body) == 0:
+        args.body = 'PING'
+
+    if args.from_ is None:
+        raise MissingFlagAndEnvironmentVariableError(['-f', '--from'], 'TWILIO__DEFAULT_PHONE_FROM')
+
+    if args.to is None:
+        raise MissingFlagAndEnvironmentVariableError(['-t', '--to'], 'TWILIO__DEFAULT_PHONE_TO')
+
+    send_sms(
+            to = args.to,
+            from_ = args.from_,
+            body = args.body,
+            max_char_count = args.max_char_count,
+            stream = stream,
+            )
+
+
+#####################################################################
+if __name__ == '__main__':
+    execute(main, description, parse_args)

run

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

scwrypts

@@ -1,211 +1,2 @@
 #!/bin/zsh
-SCWRYPTS_ROOT="${0:a:h}"
-source "$SCWRYPTS_ROOT/zsh/common.zsh" || exit 42
-#####################################################################
-
-__RUN() {
-	cd "$SCWRYPTS_ROOT"
-
-	local ENV_NAME="$SCWRYPTS_ENV"
-	local SEARCH_PATTERNS=()
-
-	while [[ $# -gt 0 ]]
-	do
-		case $1 in
-			-e|--env )
-				[ $ENV_NAME ] && __WARNING 'overwriting session environment'
-				ENV_NAME="$2"
-				__STATUS "using CLI environment '$ENV_NAME'"
-				shift 2
-				;;
-			-- )
-				shift 1
-				break # pass arguments after '--' to the scwrypt
-				;;
-			* )
-				SEARCH_PATTERNS+=$1
-				shift 1
-				;;
-		esac
-	done
-
-	##########################################
-
-	local SCRIPT=$(__SELECT_SCRIPT $SEARCH_PATTERNS)
-	[ ! $SCRIPT ] && exit 2
-
-	local ENV_REQUIRED=$(__CHECK_ENV_REQUIRED && echo 1 || echo 0)
-
-	[[ $ENV_REQUIRED -eq 1 ]] && {
-		[ ! $ENV_NAME ] && ENV_NAME=$(__SELECT_ENV)
-		local ENV_FILE=$(__GET_ENV_FILE $ENV_NAME)
-
-		[ -f "$ENV_FILE" ] && source "$ENV_FILE" \
-			|| __FAIL 5 "missing or invalid environment '$ENV_NAME'"
-
-		export ENV_NAME
-	}
-
-	[ ! $SUBSCWRYPT ] \
-		&& [[ $ENV_NAME =~ prod ]] \
-		&& { __VALIDATE_UPSTREAM_TIMELINE || __ABORT; }
-
-	local RUN_STRING=$(__GET_RUN_STRING $SCRIPT $ENV_NAME)
-	[ ! $RUN_STRING ] && exit 3
-
-	[ -f $_VIRTUALENV ] && source $_VIRTUALENV
-
-	##########################################
-
-	local LOGFILE=$(__GET_LOGFILE $SCRIPT)
-
-	local HEADER=$(
-		[ $SUBSCWRYPT ] && return 0
-		echo '====================================================================='
-		echo "script : $SCRIPT"
-		echo "run at : $(date)"
-		echo "config : $ENV_NAME"
-		[ ! $LOGFILE ] && echo '\033[1;33m------------------------------------------\033[0m'
-	)
-
-	[ ! $LOGFILE ] && {
-		[ $HEADER ] && echo $HEADER
-		eval $RUN_STRING $@ </dev/tty >/dev/tty 2>&1
-		exit $?
-	}
-
-	{
-		[ $HEADER ] && echo $HEADER
-		echo '\033[1;33m--- BEGIN OUTPUT -------------------------\033[0m'
-		eval $RUN_STRING $@
-		EXIT_CODE=$?
-		echo '\033[1;33m--- END OUTPUT ---------------------------\033[0m'
-
-		[[ $EXIT_CODE -eq 0 ]] && EXIT_COLOR='32m' || EXIT_COLOR='31m'
-
-		echo "terminated with\\033[1;$EXIT_COLOR code $EXIT_CODE\\033[0m"
-	} 2>&1 | tee --append "$LOGFILE"
-
-	exit $(\
-		sed -n 's/^terminated with.*code \([0-9]*\).*$/\1/p' $LOGFILE \
-			| tail -n1
-	)
-}
-
-#####################################################################
-
-__SELECT_SCRIPT() {
-	local SCRIPT
-	local SCRIPTS=$(__GET_AVAILABLE_SCRIPTS)
-	local SEARCH=($@)
-
-	[[ ${#SEARCH[@]} -eq 0 ]] && {
-		SCRIPT=$(echo $SCRIPTS | __FZF 'select a script')
-	}
-
-	[[ ${#SEARCH[@]} -eq 1 ]] && [ -f ./$SEARCH ] && {
-		SCRIPT=$SEARCH
-	}
-
-	[ ! $SCRIPT ] && [[ ${#SEARCH[@]} -gt 0 ]] && {
-		SCRIPT=$SCRIPTS
-		for PATTERN in $SEARCH
-		do
-			SCRIPT=$(echo $SCRIPT | grep $PATTERN)
-		done
-
-		[ ! $SCRIPT ] && __FAIL 2 "no script found by name '$@'"
-
-		[[ $(echo $SCRIPT | wc -l) -gt 1 ]] && {
-			__STATUS "more than one script matched '$@'"
-			SCRIPT=$(echo $SCRIPT | __FZF 'select a script')
-		}
-	}
-
-	echo $SCRIPT
-}
-
-__GET_RUN_STRING() {
-	local SCRIPT="$1"
-	local ENV_NAME="$2"
-	local TYPE=$(echo $SCRIPT | sed 's/\/.*$//')
-
-	local RUN_STRING
-
-	local _VIRTUALENV="$SCWRYPTS_VIRTUALENV_PATH/$TYPE/bin/activate"
-	[ -f $_VIRTUALENV ] && source $_VIRTUALENV
-
-	case $TYPE in
-		py ) __CHECK_DEPENDENCY python || return 1
-			RUN_STRING="python -m $(echo $SCRIPT | sed 's/\//./g; s/\.py$//; s/\.\.//')"
-
-			CURRENT_PYTHON_VERSION=$(python --version | sed 's/^[^0-9]*\(3\.[^.]*\).*$/\1/')
-
-			echo $__PREFERRED_PYTHON_VERSIONS | grep -q $CURRENT_PYTHON_VERSION || {
-				__WARNING "only tested on the following python versions: $(printf ', %s.x' ${__PREFERRED_PYTHON_VERSIONS[@]} | sed 's/^, //')"
-				__WARNING 'compatibility may vary'
-			}
-			;;
-
-		zsh ) __CHECK_DEPENDENCY zsh || return 1
-			RUN_STRING="./$SCRIPT"
-			;;
-
-		zx ) __CHECK_DEPENDENCY zx || return 1
-			RUN_STRING="FORCE_COLOR=3 ./$SCRIPT.mjs"
-			;;
-
-		* ) __ERROR "unsupported script type '$SCRIPT_TYPE'"
-			return 2
-			;;
-	esac
-
-	RUN_STRING="SCWRYPTS_ENV='$ENV_NAME' $RUN_STRING"
-	[ -f $_VIRTUALENV ] && RUN_STRING="source '$_VIRTUALENV'; $RUN_STRING"
-
-	echo $RUN_STRING
-}
-
-__CHECK_ENV_REQUIRED() {
-	[ $CI ] && return 1
-
-	echo $SCRIPT | grep -q 'zsh/scwrypts/logs' && return 1
-
-	return 0
-}
-
-__VALIDATE_UPSTREAM_TIMELINE() {
-	__STATUS "on '$ENV_NAME'; checking diff against origin/main"
-
-	git fetch --quiet origin main
-	local SYNC_STATUS=$?
-
-	git diff --exit-code origin/main -- . >&2
-	local DIFF_STATUS=$?
-
-	[[ $SYNC_STATUS -eq 0 ]] && [[ $DIFF_STATUS -eq 0 ]] && {
-		__SUCCESS 'up-to-date with origin/main'
-	} || {
-		__WARNING
-		[[ $SYNC_STATUS -ne 0 ]] && __WARNING 'unable to synchronize with origin/main'
-		[[ $DIFF_STATUS -ne 0 ]] && __WARNING 'your branch differs from origin/main (diff listed above)'
-		__WARNING
-
-		__yN 'continue?' || return 1
-	}
-}
-
-__GET_LOGFILE() {
-	local SCRIPT="$1"
-
-	[ $CI ] \
-		|| [ $SUBSCWRYPT ] \
-		|| [[ $SCRIPT =~ scwrypts/logs ]] \
-		|| [[ $SCRIPT =~ interactive ]] \
-		&& return 0
-
-	echo "$SCWRYPTS_LOG_PATH/$(echo $SCRIPT | sed 's/^\.\///; s/\//\%/g').log"
-}
-
-#####################################################################
-__RUN $@
+source "${0:a:h}/run" $@

scwrypts.plugin.zsh

@@ -1,26 +1,59 @@
-DONT_EXIT=1 source ${0:a:h}/zsh/common.zsh
+NO_EXPORT_CONFIG=1 source "${0:a:h}/zsh/lib/import.driver.zsh" || return 42
+
 #####################################################################
-__SCWRYPTS() {
-	local SCRIPT=$(__GET_AVAILABLE_SCRIPTS | __FZF 'select a script')
-	zle clear-command-line
-	[ ! $SCRIPT ] && { zle accept-line; return 0; }
+SCWRYPTS__ZSH_PLUGIN() {
+	local SCWRYPT_SELECTION=$(SCWRYPTS__GET_AVAILABLE_SCWRYPTS | FZF 'select a script' --header-lines 1)
+	local NAME
+	local TYPE
+	local GROUP
+	LBUFFER= RBUFFER=
+	[ ! $SCWRYPT_SELECTION ] && { zle accept-line; return 0; }
+
+	SCWRYPTS__SEPARATE_SCWRYPT_SELECTION $SCWRYPT_SELECTION
 
 	which scwrypts >/dev/null 2>&1\
 		&& RBUFFER="scwrypts" || RBUFFER="$SCWRYPTS_ROOT/scwrypts"
 
-	RBUFFER+=" $SCRIPT"
+	RBUFFER+=" --name $NAME --group $GROUP --type $TYPE"
 	zle accept-line
 }
 
-zle -N scwrypts __SCWRYPTS
+zle -N scwrypts SCWRYPTS__ZSH_PLUGIN
 bindkey $SCWRYPTS_SHORTCUT scwrypts
 
 #####################################################################
-__SCWRYPTS_ENV() {
+SCWRYPTS__ZSH_BUILDER_PLUGIN() {
+	local SCWRYPT_SELECTION=$(SCWRYPTS__GET_AVAILABLE_SCWRYPTS | FZF 'select a script' --header-lines 1)
+	local NAME
+	local TYPE
+	local GROUP
+	LBUFFER= RBUFFER=
+	[ ! $SCWRYPT_SELECTION ] && { zle accept-line; return 0; }
+
+	SCWRYPTS__SEPARATE_SCWRYPT_SELECTION $SCWRYPT_SELECTION
+
+	scwrypts --name $NAME --group $GROUP --type $TYPE -- --help >&2 || {
+		zle accept-line
+		return 0
+	}
+	echo
+
+	zle reset-prompt
+	which scwrypts >/dev/null 2>&1\
+		&& LBUFFER="scwrypts" || LBUFFER="$SCWRYPTS_ROOT/scwrypts"
+
+	LBUFFER+=" --name $NAME --group $GROUP --type $TYPE -- "
+}
+
+zle -N scwrypts-builder SCWRYPTS__ZSH_BUILDER_PLUGIN
+bindkey $SCWRYPTS_BUILDER_SHORTCUT scwrypts-builder
+
+#####################################################################
+SCWRYPTS__ZSH_PLUGIN_ENV() {
 	local RESET='reset'
 	local SELECTED=$(\
-		{ [ $SCWRYPTS_ENV ] && echo $RESET; __GET_ENV_NAMES; } \
-			| __FZF 'select an environment' \
+		{ [ $SCWRYPTS_ENV ] && echo $RESET; SCWRYPTS__GET_ENV_NAMES; } \
+			| FZF 'select an environment' \
 	)
 
 	zle clear-command-line
@@ -32,5 +65,5 @@ __SCWRYPTS_ENV() {
 	zle accept-line
 }
 
-zle -N scwrypts-setenv __SCWRYPTS_ENV
+zle -N scwrypts-setenv SCWRYPTS__ZSH_PLUGIN_ENV
 bindkey $SCWRYPTS_ENV_SHORTCUT scwrypts-setenv

zsh/aws/common.zsh

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

zsh/aws/ecr/common.zsh

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

zsh/aws/ecr/login

@@ -1,14 +0,0 @@
-#!/bin/zsh
-_DEPENDENCIES+=()
-_REQUIRED_ENV+=()
-source ${0:a:h}/common.zsh
-#####################################################################
-
-__STATUS "performing AWS ECR docker login"
-
-_AWS ecr get-login-password | docker login \
-	--username AWS \
-	--password-stdin \
-	"$_AWS_ACCOUNT.dkr.ecr.$_AWS_REGION.amazonaws.com" \
-	&& __SUCCESS "logged in to 'AWS:$_AWS_ACCOUNT:$_AWS_REGION'" \
-	|| __FAIL 1 "unable to login to '$_AWS_ACCOUNT' in '$_AWS_REGION'"

zsh/aws/efs/common.zsh

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

zsh/aws/efs/mount

@@ -1,65 +0,0 @@
-#!/bin/zsh
-_DEPENDENCIES+=()
-_REQUIRED_ENV+=()
-source ${0:a:h}/common.zsh
-#####################################################################
-
-_EFS_CONNECT() {
-	__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 FS_ID=$(\
-		_AWS efs describe-file-systems \
-		| jq -r '.[] | .[] | .FileSystemId' \
-		| __FZF 'select a filesystem to mount' \
-	)
-	[ ! $FS_ID ] && __ABORT
-
-	local MOUNT_POINT="$AWS__EFS__LOCAL_MOUNT_POINT/$FS_ID"
-	[ -d "$MOUNT_POINT" ] && {
-		__STATUS "$FS_ID is already mounted"
-		exit 0
-	}
-
-	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'\
-	)
-	[ ! $ZONE ] && __ABORT
-
-	local MOUNT_IP=$(\
-		echo $MOUNT_TARGETS \
-		| jq -r ".[] | .[] | select (.AvailabilityZoneName == \"$ZONE\") | .IpAddress" \
-		| head -n1 \
-	)
-
-	__SUCCESS 'ready to mount!'
-	__REMINDER 'your device must be connected to the appropriate VPN'
-
-	__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 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'" \
-		|| {
-		sudo rmdir $MOUNT_POINT >/dev/null 2>&1
-		__FAIL 2 "unable to mount '$FS_ID'"
-	}
-}
-
-#####################################################################
-_EFS_CONNECT

zsh/aws/efs/unmount

@@ -1,34 +0,0 @@
-#!/bin/zsh
-_DEPENDENCIES+=()
-_REQUIRED_ENV+=()
-source ${0:a:h}/common.zsh
-#####################################################################
-
-_EFS_DISCONNECT() {
-	[ ! -d "$AWS__EFS__LOCAL_MOUNT_POINT" ] && {
-		__STATUS 'no efs currently mounted'
-		exit 0
-	}
-
-	local MOUNTED=$(ls "$AWS__EFS__LOCAL_MOUNT_POINT")
-	[ ! $MOUNTED ] && {
-		__STATUS 'no efs currently mounted'
-		exit 0
-	}
-
-	__GETSUDO || exit 1
-
-
-	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'"
-}
-
-#####################################################################
-_EFS_DISCONNECT

zsh/aws/rds/common.zsh

@@ -1,22 +0,0 @@
-_DEPENDENCIES+=()
-_REQUIRED_ENV+=()
-source ${0:a:h}/../common.zsh
-#####################################################################
-
-__SELECT_CONNECTOR() {
-	local DB_TYPE="$1"
-
-	CLIENTS_postgresql=(pgcli psql)
-
-	local C CLIENT=none
-	for C in $(eval 'echo $CLIENTS_'$DB_TYPE)
-	do
-	__CHECK_DEPENDENCY $C >/dev/null 2>&1 && {
-		CLIENT=$C
-		__STATUS "detected '$CLIENT' for $DB_TYPE"
-		break
-	}
-	done
-
-	echo $CLIENT
-}

zsh/aws/rds/interactive-login

@@ -1,121 +0,0 @@
-#!/bin/zsh
-_DEPENDENCIES+=()
-_REQUIRED_ENV+=()
-source ${0:a:h}/common.zsh
-#####################################################################
-
-__CONNECT_TO_RDS() {
-	local DATABASE=$(__SELECT_DATABASE)
-	[ ! $DATABASE ] && __ABORT
-
-	local DB_HOST DB_USER DB_PORT DB_NAME DB_AUTH DB_TYPE
-
-	DB_HOST=$(echo $DATABASE | jq -r '.host')
-	DB_USER=$(echo $DATABASE | jq -r '.user')
-	DB_PORT=$(echo $DATABASE | jq -r '.port')
-	DB_TYPE=$(echo $DATABASE | jq -r '.type')
-
-	[[ $DB_PORT =~ null ]] && DB_PORT=5432
-	DB_NAME=postgres
-
-	local AUTH_METHODS=(iam secretsmanager user-input)
-	local AUTH_METHOD=$(\
-		echo $AUTH_METHODS | sed 's/\s\+/\n/g' \
-			| __FZF 'select an authentication method' \
-	)
-
-	[ ! $AUTH_METHOD ] && __ABORT
-
-	case $AUTH_METHOD in
-		iam )
-			DB_AUTH=$(\
-				_AWS rds generate-db-auth-token \
-					--hostname $DB_HOST \
-					--port $DB_PORT \
-					--username $DB_USER \
-			)
-			;;
-		secretsmanager )
-			CREDENTIALS=$(__GET_SECRETSMANAGER_CREDENTIALS)
-			echo $CREDENTIALS | jq -e '.pass' >/dev/null 2>&1 \
-				&& DB_AUTH=$(echo $CREDENTIALS | jq -r '.pass')
-
-			echo $CREDENTIALS | jq -e '.password' >/dev/null 2>&1 \
-				&& DB_AUTH=$(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')
-			;;
-		user-input )
-			;;
-	esac
-
-	__STATUS
-	__STATUS "host     : $DB_HOST"
-	__STATUS "type     : $DB_TYPE"
-	__STATUS "port     : $DB_PORT"
-	__STATUS "database : $DB_NAME"
-	__STATUS "username : $DB_USER"
-	__STATUS
-
-	__RUN_SCWRYPT 'zsh/db/interactive/postgres' -- \
-		--host $DB_HOST \
-		--port $DB_PORT \
-		--name $DB_NAME \
-		--user $DB_USER \
-		--pass $DB_AUTH \
-		;
-}
-
-__SELECT_DATABASE() {
-	local DATABASES=$(__GET_AVAILABLE_DATABASES)
-	[ ! $DATABASES ] && __FAIL 1 'no databases available'
-
-	local ID=$(\
-		echo $DATABASES | jq -r '.instance + " @ " + .cluster' \
-			| __FZF 'select a database (instance@cluster)' \
-	)
-	[ ! $ID ] && __ABORT
-
-	local INSTANCE=$(echo $ID | sed 's/ @ .*$//')
-	local CLUSTER=$(echo $ID  | sed 's/^.* @ //')
-
-	echo $DATABASES | jq "select (.instance == \"$INSTANCE\" and .cluster == \"$CLUSTER\")"
-}
-
-__GET_AVAILABLE_DATABASES() {
-	_AWS rds describe-db-instances \
-		| jq -r '.[] | .[] | {
-			instance: .DBInstanceIdentifier,
-			cluster:  .DBClusterIdentifier,
-			type:     .Engine,
-			host:     .Endpoint.Address,
-			port:     .Endpoint.Port,
-			user:     .MasterUsername,
-			database: .DBName
-		}'
-}
-
-__GET_SECRETSMANAGER_CREDENTIALS() {
-	local ID=$(\
-		_AWS secretsmanager list-secrets \
-			| jq -r '.[] | .[] | .Name' \
-			| __FZF 'select a secret' \
-	)
-	[ ! $ID ] && return 1
-
-	_AWS secretsmanager get-secret-value --secret-id "$ID" \
-		| jq -r '.SecretString' | jq
-}
-
-#####################################################################
-__CONNECT_TO_RDS