v5.0.0

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

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

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

- ZSH testing library with basic mock capabilities

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

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

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

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

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

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

- documentation comments included in ZSH libraries

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

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

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

docs/upgrade/v3-to-v4.md

@@ -57,7 +57,7 @@ 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
+#!/usr/bin/env zsh
 #####################################################################
 DEPENDENCIES+=(dep-function-a dep-function-b)
 REQUIRED_ENV+=()
@@ -69,11 +69,11 @@ CHECK_ENVIRONMENT
 
 - echo "do some stuff here"
 - # ... etc ...
-- SUCCESS "completed the stuff"
+- echo.success "completed the stuff"
 + MAIN() {
 +     echo "do some stuff here"
 +     # ... etc ...
-+     SUCCESS "completed the stuff
++     echo.success "completed the stuff
 + }
 ```
 
@@ -85,7 +85,7 @@ 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"
+    echo.success "look at me I'm so cool I already wrote this in a main function"
 }
 -
 - #####################################################################
@@ -115,20 +115,20 @@ 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
+#!/usr/bin/env 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
+    echo.success "completed the stuff
 }
 ```
 
@@ -164,7 +164,7 @@ If you _have_ done it already, typically by writing a variable called "USAGE" in
 
 Returning to our original `MAIN()` example, I'll add some options parsing so we should now look something like this:
 ```sh
-#!/bin/zsh
+#!/usr/bin/env zsh
 DEPENDENCIES+=(dep-function-a dep-function-b)
 
 use do/awesome/stuff --group my-custom-library
@@ -200,7 +200,7 @@ I want to call out a few specific ones:
 
 Just add another section to define these values before declaring `MAIN`:
 ```sh
-#!/bin/zsh
+#!/usr/bin/env zsh
 DEPENDENCIES+=(dep-function-a dep-function-b)
 
 use do/awesome/stuff --group my-custom-library

docs/upgrade/v4-to-v5.md

@@ -0,0 +1,136 @@
+# Scwrypts Upgrade v4 to v5 Notes
+
+Although scwrypts v4 brings a number of new features, most functionality is backwards-compatible.
+
+## Lots of renames!
+
+Nearly every module received a rename.
+This was a decision made to improve both style-consistency and import transparency, but has resulted in a substantial number of breaking changes to `zsh-type scwrypts modules`.
+
+### `zsh/utils` Functions
+
+The functions in the underlying library have all been renamed, but otherwise maintain the same functionality.
+For a full reference, check out the [zsh/utils](../../zsh/utils/utils.module.zsh), but some critical renames are:
+```bash
+FZF            >> utils.fzf
+FZF_USER_INPUT >> utils.fzf.user-input
+LESS           >> utils.less
+YQ             >> utils.yq
+
+SUCCESS  >> echo.success
+ERROR    >> echo.error
+REMINDER >> echo.reminder
+STATUS   >> echo.status
+WARNING  >> echo.warning
+DEBUG    >> echo.debug
+FAIL     >> utils.fail
+ABORT    >> utils.abort
+
+CHECK_ERRORS >> utils.check-errors
+
+Yn >> utils.Yn
+yN >> utils.yN
+
+EDIT >> utils.io.edit
+
+CHECK_ENVIRONMENT >> utils.check-environment
+```
+
+### `zsh/utils` Color Functions
+
+Rather than storing ANSI colors as a variable, colors are now stored as a function which prints the color code.
+Doing this has proven more versatile than trying to extract the value of the variable in several contexts.
+Rename looks like this for all named ANSI colors:
+
+```bash
+$__GREEN      >> utils.colors.green
+$__BRIGHT_RED >> utils.colors.bright-red
+```
+
+The most common use case of colors is indirectly through the `echo.*` commands, so a new function now provides _the color used by the associated `echo.*` command_:
+
+```bash
+# instead of
+STATUS "Hello there, ${_BRIGHT_GREEN}bobby${_YELLOW}. How are you?"
+
+# use
+echo.status "Hello there, $(utils.colors.bright-green)bobby$(echo.status.color). How are you?
+```
+
+### ZSH Scwrypts Module Naming
+
+**This is the biggest point of refactor.**
+
+You will notice that modules now declare their functions using a `${scwryptsmodule}` notation.
+This notation provides a dot-notated name which is intended to provide a consistent, unique naming system in ZSH (remember, everything loaded into the same shell script must have a globally-unique name).
+Consider the new naming method for the following:
+
+```bash
+# v4: zsh/lib/helm/template.module.zsh
+
+HELM__TEMPLATE__GET() {
+    # ...
+}
+
+# v5: zsh/helm/get-template.module.zsh
+${scwryptsmodule}() {
+    # ...
+}
+```
+
+Although the import syntax is generally the same, now we reference the full name of the module instead of the arbitrarily defined `HELM__TEMPLATE__GET`:
+
+```
+# in some other scwrypt
+use helm/get-template
+
+helm.get-template --raw ./my-helm-chart
+```
+
+The name `${scwryptsmodule}` is depended on the scwrypts library path.
+Since there is not an easy way to provide an exhaustive list, go through all the places where you `use` something from the scwrypts core library, and check to see where it is now.
+One of the critical call-outs is the AWS CLI, which no longer follows the "just use ALL CAPS for function names," but instead is a proper module.
+
+Both of the following are valid ways to use the scwrypts-safe aws-cli (`AWS` in v4):
+
+```bash
+# to import _only_ AWS cli
+use cloud.aws.cli
+
+cloud.aws.cli sts get-caller-identity
+
+# importing the full AWS module also provides an alias
+use cloud.aws
+
+cloud.aws sts get-caller-identity
+```
+
+### Great news!
+
+Great news!
+We have finished with **all of the necessary steps** to migrate to v5!
+
+If you still have the energy, take some time to make these _recommended_ adjustments too.
+
+
+### Use the new `${scwryptsmodule}` syntax
+
+The `${scwryptsmodule}` name is now automatically available in any module.
+The one change from the `${scwryptsmodule}` in scwrypts core is that **your scwrypts group name is the first dot**.
+
+If I'm building the scwrypts group called `my-cool-stuff` and open the file `my-cool-stuff/zsh/module-a.module.zsh`, then `${scwryptsmodule}` will refer to `my-cool-stuff.module-a`.
+
+### Update your `*.scwrypts.zsh` declaration file
+
+In v4 and earlier, it was tricky to create your own scwrypts group, since you had to create a particular folder structure, and write a `group-name.scwrypts.zsh` file with some somewhat arbitrary requirements.
+In v5, you can now make any folder a scwrypts group by simply _creating the `*.scwrypts.zsh` file_.
+
+```bash
+# this will turn the current folder into the root of a scwrypts group called `my-cool-stuff`
+touch 'my-cool-stuff.scwrypts.zsh'
+    ├── zsh
+    ├── zx
+    └── py
+```
+
+Advanced options for scwrypts are now [documented in the example](../../scwrypts.scwrypts.zsh), so please refer to it for any additional changes you may need for existing scwrypts modules.