v2.8.0

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

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

- python library functions moved to `py/lib`
- python scwrypts renamed in kebob-case to help prevent import
- __name__ == '__main__' enforced on all python scwrypts

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

- `__override` variables now allow values to be force-overwritten
- py.lib.http.client provides a slim `requests.request` wrapper

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

py/data/convert )
  quick data converters
   - csv-to-json
   - csv-to-yaml
   - json-to-csv
   - json-to-yaml
   - yaml-to-csv
   - yaml-to-json

py/linear )
  uses the linear.app graphql API for PM tasks
   - comment

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

- `scwrypts` handles arguments with quotes and special characters

.env.template

@@ -5,6 +5,11 @@ export AWS_REGION=
 export AWS__EFS__LOCAL_MOUNT_POINT=
 export AWS__S3__MEDIA_BUCKET=
 export AWS__S3__MEDIA_TARGETS=
+export I3__BORDER_PIXEL_SIZE=
+export I3__DMENU_FONT_SIZE=
+export I3__GLOBAL_FONT_SIZE=
+export I3__MODEL_CONFIG=
+export LINEAR__API_TOKEN=
 export REDIS_AUTH=
 export REDIS_HOST=
 export REDIS_PORT=

.env.template.descriptions

@@ -7,6 +7,13 @@ AWS__EFS__LOCAL_MOUNT_POINT  | fully-qualified path to mount the EFS drive
 AWS__S3__MEDIA_BUCKET   | s3 bucket name and filesystem targets for media backups
 AWS__S3__MEDIA_TARGETS  |
 
+I3__BORDER_PIXEL_SIZE   | custom i3 configuration settings
+I3__DMENU_FONT_SIZE     |
+I3__GLOBAL_FONT_SIZE    |
+I3__MODEL_CONFIG        |
+
+LINEAR__API_TOKEN  | linear.app project management configuration
+
 REDIS_AUTH  | redis connection credentials
 REDIS_HOST  |
 REDIS_PORT  |

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

@@ -0,0 +1,21 @@
+#!/usr/bin/env python
+from argparse import ArgumentParser
+
+from py.lib.data.io import add_io_arguments
+from py.lib.data.converter import convert
+
+if __name__ != '__main__':
+    raise Exception('executable only; must run through scwrypts')
+
+
+parser = ArgumentParser(description = 'converts csv into json')
+add_io_arguments(parser)
+
+args = parser.parse_args()
+
+convert(
+        input_file  = args.input_file,
+        input_type  = 'csv',
+        output_file = args.output_file,
+        output_type = 'json',
+        )

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

@@ -0,0 +1,21 @@
+#!/usr/bin/env python
+from argparse import ArgumentParser
+
+from py.lib.data.io import add_io_arguments
+from py.lib.data.converter import convert
+
+if __name__ != '__main__':
+    raise Exception('executable only; must run through scwrypts')
+
+
+parser = ArgumentParser(description = 'converts csv into yaml')
+add_io_arguments(parser)
+
+args = parser.parse_args()
+
+convert(
+        input_file  = args.input_file,
+        input_type  = 'csv',
+        output_file = args.output_file,
+        output_type = 'yaml',
+        )

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

@@ -0,0 +1,21 @@
+#!/usr/bin/env python
+from argparse import ArgumentParser
+
+from py.lib.data.io import add_io_arguments
+from py.lib.data.converter import convert
+
+if __name__ != '__main__':
+    raise Exception('executable only; must run through scwrypts')
+
+
+parser = ArgumentParser(description = 'converts csv into json')
+add_io_arguments(parser)
+
+args = parser.parse_args()
+
+convert(
+        input_file  = args.input_file,
+        input_type  = 'json',
+        output_file = args.output_file,
+        output_type = 'csv',
+        )

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

@@ -0,0 +1,21 @@
+#!/usr/bin/env python
+from argparse import ArgumentParser
+
+from py.lib.data.io import add_io_arguments
+from py.lib.data.converter import convert
+
+if __name__ != '__main__':
+    raise Exception('executable only; must run through scwrypts')
+
+
+parser = ArgumentParser(description = 'converts json into yaml')
+add_io_arguments(parser)
+
+args = parser.parse_args()
+
+convert(
+        input_file  = args.input_file,
+        input_type  = 'json',
+        output_file = args.output_file,
+        output_type = 'yaml',
+        )

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

@@ -0,0 +1,21 @@
+#!/usr/bin/env python
+from argparse import ArgumentParser
+
+from py.lib.data.io import add_io_arguments
+from py.lib.data.converter import convert
+
+if __name__ != '__main__':
+    raise Exception('executable only; must run through scwrypts')
+
+
+parser = ArgumentParser(description = 'converts yaml into csv')
+add_io_arguments(parser)
+
+args = parser.parse_args()
+
+convert(
+        input_file  = args.input_file,
+        input_type  = 'yaml',
+        output_file = args.output_file,
+        output_type = 'csv',
+        )

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

@@ -0,0 +1,21 @@
+#!/usr/bin/env python
+from argparse import ArgumentParser
+
+from py.lib.data.io import add_io_arguments
+from py.lib.data.converter import convert
+
+if __name__ != '__main__':
+    raise Exception('executable only; must run through scwrypts')
+
+
+parser = ArgumentParser(description = 'converts yaml into json')
+add_io_arguments(parser)
+
+args = parser.parse_args()
+
+convert(
+        input_file  = args.input_file,
+        input_type  = 'yaml',
+        output_file = args.output_file,
+        output_type = 'json',
+        )

py/hello-world.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python
+from argparse import ArgumentParser
+
+if __name__ != '__main__':
+    raise Exception('executable only; must run through scwrypts')
+
+
+parser = ArgumentParser(description = 'a simple "Hello, World!" program')
+parser.add_argument(
+        '-m', '--message',
+        dest     = 'message',
+        default  = 'HELLO WORLD',
+        help     = 'message to print to stdout',
+        required = False,
+        )
+
+args = parser.parse_args()
+
+print(args.message)

py/hello_world.py

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

py/lib/data/converter.py

@@ -0,0 +1,76 @@
+import csv
+import json
+import yaml
+
+from py.lib.data.io import get_stream
+
+
+def convert(input_file, input_type, output_file, output_type):
+    if input_type == output_type:
+        raise ValueError('input type and output type are the same')
+
+    with get_stream(input_file) as input_stream:
+        data = convert_input(input_stream, input_type)
+
+    with get_stream(output_file, 'w+') as output_stream:
+        _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/data/io.py

@@ -0,0 +1,51 @@
+from contextlib import contextmanager
+from pathlib import Path
+from sys import stdin, stdout, stderr
+
+from py.lib.scwrypts.getenv 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
+
+
+def add_io_arguments(parser, toggle_input=True, toggle_output=True):
+    if toggle_input:
+        parser.add_argument(
+                '-i', '--input-file',
+                dest     = 'input_file',
+                default  = None,
+                help     = 'path to input file; omit for stdin',
+                required = False,
+                )
+
+    if toggle_output:
+        parser.add_argument(
+                '-o', '--output-file',
+                dest     = 'output_file',
+                default  = None,
+                help     = 'path to output file; omit for stdout',
+                required = False,
+                )

py/lib/http/__init__.py

@@ -0,0 +1 @@
+from py.lib.http.client import get_request_client

py/lib/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/linear/__init__.py

@@ -0,0 +1 @@
+from py.lib.linear.client import request, graphql

py/lib/linear/client.py

@@ -0,0 +1,13 @@
+from py.lib.http import get_request_client
+from py.lib.scwrypts import getenv
+
+
+request = get_request_client(
+        base_url = 'https://api.linear.app',
+        headers = {
+            'Authorization': f'bearer {getenv("LINEAR__API_TOKEN")}',
+            }
+        )
+
+def graphql(query):
+    return request('POST', 'graphql', json={'query': query})

py/lib/redis/__init__.py

@@ -0,0 +1 @@
+

py/lib/redis/client.py

@@ -1,6 +1,6 @@
 from redis import StrictRedis
 
-from py.scwrypts import getenv
+from py.lib.scwrypts import getenv
 
 
 class RedisClient(StrictRedis):

py/lib/scwrypts/__init__.py

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

py/lib/scwrypts/getenv.py

@@ -1,7 +1,7 @@
 from os import getenv as os_getenv
 
-from py.scwrypts.exceptions import MissingVariableError
+from py.lib.scwrypts.exceptions import MissingVariableError
-from py.scwrypts.run import run
+from py.lib.scwrypts.run import run
 
 
 def getenv(name, required=True):

py/lib/scwrypts/run.py

@@ -7,11 +7,15 @@ def run(scwrypt_name, *args):
     DEPTH = int(getenv('SUBSCWRYPT', '0'))
     DEPTH += 1
 
+    SCWRYPTS_EXE = Path(__file__).parents[2] / 'scwrypts'
+    ARGS = ' '.join([str(x) for x in args])
+
     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])}',
+        f'SUBSCWRYPT={DEPTH} {SCWRYPTS_EXE} {scwrypt_name} -- {ARGS}',
         shell=True,
         executable='/bin/zsh',
+        check=False,
         )
 
     print(f' {"--"*DEPTH} ({DEPTH}) END SUBSCWRYPT   : {Path(scwrypt_name).name}\n')

py/linear/comment.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python
+from argparse import ArgumentParser
+
+from py.lib.data.io import get_stream, add_io_arguments
+from py.lib.linear import graphql
+
+if __name__ != '__main__':
+    raise Exception('executable only; must run through scwrypts')
+
+
+parser = ArgumentParser(description = 'comment on an issue in linear.app')
+
+parser.add_argument(
+        '-i', '--issue',
+        dest     = 'issue_id',
+        help     = 'issue short-code (e.g. CLOUD-319)',
+        required = True,
+        )
+
+parser.add_argument(
+        '-m', '--message',
+        dest     = 'message',
+        help     = 'comment to post to the target issue',
+        required = True,
+        )
+
+add_io_arguments(parser, toggle_input=False)
+
+args = parser.parse_args()
+
+query = f'''
+mutation CommentCreate {{
+    commentCreate(
+        input: {{
+            issueId: "{args.issue_id}"
+            body:    """from wrobot:
+```
+{args.message.strip()}
+```"""
+        }}
+    ) {{ success }}
+}}
+'''
+
+response = graphql(query)
+with get_stream(args.output_file, 'w+') as output:
+    output.write(response.text)

py/redis/interactive.py

@@ -1,11 +1,19 @@
 #!/usr/bin/env python
+from argparse import ArgumentParser
 
-from py.redis.client import Client
+from py.lib.redis.client import Client
-from py.scwrypts import interactive, getenv
+from py.lib.scwrypts import interactive, getenv
 
+if __name__ != '__main__':
+    raise Exception('executable only; must run through scwrypts')
+
+
+parser = ArgumentParser(description = 'establishes a redis client in an interactive python shell')
+args = parser.parse_args()
 
 @interactive
 def main():
+    # pylint: disable=possibly-unused-variable
     r = Client
 
     print(f'''
@@ -14,6 +22,4 @@ def main():
 
     return locals()
 
-
-if __name__ == '__main__':
 main()

py/requirements.txt

@@ -1,2 +1,3 @@
 redis
 bpython
+pyyaml

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

run

@@ -102,10 +102,10 @@ __RUN() {
 	[ ! $LOGFILE ] && {
 		[ $HEADER ] && echo $HEADER
 		[ $SUBSCWRYPT ] && {
-			eval $RUN_STRING $@
+			eval "$RUN_STRING $(printf "%q " "$@")"
 			exit $?
 		} || {
-			eval $RUN_STRING $@ </dev/tty >/dev/tty 2>&1
+			eval "$RUN_STRING $(printf "%q " "$@")" </dev/tty >/dev/tty 2>&1
 			exit $?
 		}
 	}
@@ -113,7 +113,7 @@ __RUN() {
 	{
 		[ $HEADER ] && echo $HEADER
 		echo '\033[1;33m--- BEGIN OUTPUT -------------------------\033[0m'
-		eval $RUN_STRING $@
+		eval "$RUN_STRING $(printf "%q " "$@")"
 		EXIT_CODE=$?
 		echo '\033[1;33m--- END OUTPUT ---------------------------\033[0m'
 

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

@@ -24,7 +24,7 @@ __SYNC_MEDIA() {
 	local FLAGS=(${@:3})
 
 	__STATUS "${ACTION}ing $2"
-	_AWS s3 sync $REMOTE_TARGET $LOCAL_TARGET $FLAGS \
+	_AWS s3 sync $A $B $FLAGS \
 		&& __SUCCESS "$2 up-to-date" \
 		|| { __ERROR "unable to sync $2 (see above)"; return 1; }
 }

zsh/common.zsh

@@ -6,7 +6,7 @@ source ${0:a:h}/utils/utils.module.zsh \
 
 #####################################################################
 
-__GET_ENV_FILES() { find $SCWRYPTS_CONFIG_PATH/env -maxdepth 1 -type f | sort -r }
+__GET_ENV_FILES() { ls $SCWRYPTS_CONFIG_PATH/env | sort -r }
 [ ! "$(__GET_ENV_FILES)" ] && {
 	cp $__ENV_TEMPLATE "$SCWRYPTS_CONFIG_PATH/env/dev"
 	cp $__ENV_TEMPLATE "$SCWRYPTS_CONFIG_PATH/env/local"

zsh/config/common.zsh

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

zsh/config/symlinks

@@ -15,16 +15,16 @@ SETUP_SYMLINK() {
 	[ ! $2 ] && __FAIL 1 'must provide SOURCE_CONFIG and TARGET_CONFIG'
 
 	local SOURCE_CONFIG="$1"
-	[ ! -f "$SOURCE_CONFIG" ] && __FAIL 2 "no such file '$SOURCE_CONFIG'"
+	[ ! -f "$SOURCE_CONFIG" ] && [ ! -d "$SOURCE_CONFIG" ] && __FAIL 2 "no such file or directory '$SOURCE_CONFIG'"
 
 	local TARGET_CONFIG="$HOME/.config/$2"
 
 	[ ! -d $(dirname "$TARGET_CONFIG") ] && mkdir -p $(dirname "$TARGET_CONFIG")
 
-	[ -f "$TARGET_CONFIG" ] && {
+	[[ $SAFE_SYMLINKS -eq 1 ]] \
-		[[ $SAFE_SYMLINKS -eq 1 ]] && mv "$TARGET_CONFIG" "$TARGET_CONFIG.bak"
+		&& mv "$TARGET_CONFIG" "$TARGET_CONFIG.bak" >/dev/null 2>&1
-		[[ $SAFE_SYMLINKS -eq 0 ]] && rm "$TARGET_CONFIG"
+
-	}
+	rm "$TARGET_CONFIG" >/dev/null 2>&1
 
 	ln -s "$SOURCE_CONFIG" "$TARGET_CONFIG" \
 		&& __SUCCESS "successfully linked '$(basename $(dirname $TARGET_CONFIG))/$(basename $TARGET_CONFIG)'" \

zsh/i3/common.zsh

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

zsh/i3/create-local-font-override

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

zsh/i3/launch-or-show

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

zsh/scwrypts/README.md

@@ -31,6 +31,34 @@ Inherited values are denoted by `# inherited from <parent-name>` in the environm
 
 Nested children will inherit values from all parents.
 
+### Special Environment Variable Syntax
+
+All environment variables which end in `__[a-z_]+` are ignored by the template file.
+These environment variables *will propagate to children*, but will not be removed nor staged into the `.env.template`.
+
+#### `__select` Environment Variables
+Omit any variable, but provide a comma-separated list with the `__select` suffix, and the user will be prompted to select a value from the provided options.
+
+In the following configuration, the user will be prompted to select an `AWS_REGION` once at the beginning of scwrypt execution:
+
+```zsh
+export AWS_REGION=
+export AWS_REGION__select=us-east-1,us-east-2,us-west-1,us-west-2
+```
+
+Setting the `AWS_REGION` variable will cause scwrypts to ignore the `__select` syntax.
+
+CI will fail on select, because CI fails on any FZF prompt.
+
+#### `__override` Environment Variables
+Override any variable with the indicated value.
+This will take precedence over existing values *and* any other special environment variable types.
+
+Examples of use:
+- temporarily changing a single value in your current session (e.g. `export VARIABLE__override=value`)
+- overriding a variable for a one-time command (e.g. `VARIABLE__override=value scwrypts ...`)
+
+
 ## Logs
 Quickly view or clear Scwrypts logs.
 

zsh/scwrypts/environment/common.zsh

@@ -6,7 +6,9 @@ source ${0:a:h}/../common.zsh
 _SORT_ENV() {
 	local ENV_FILE="$1"
 
-	sed -i "/^# /d; /^$/d" "$ENV_FILE"
+	_SED -i "/^# /d; /^$/d" "$ENV_FILE"
-	sed -i "s/^[A-Z]/export &/; s/^[^#=]\\+$/&=/" "$ENV_FILE"
+	_SED -i "s/^[A-Z]/export &/; s/^[^#=]\\+$/&=/" "$ENV_FILE"
 	LC_COLLATE=C sort -uo "$ENV_FILE" "$ENV_FILE"
 }
+
+_SED() { sed --follow-symlinks $@; }

zsh/scwrypts/environment/copy

@@ -25,7 +25,7 @@ cp "$TEMPLATE_ENV_FILE" "$ENV_FILE" \
 	|| __FAIL 3 "unable to create '$ENV_NAME'"
 
 __STATUS 'stripping inherited values'
-sed -i 's/ # inherited from.*$//' "$ENV_FILE" 2>/dev/null
+_SED -i 's/ # inherited from.*$//' "$ENV_FILE" 2>/dev/null
 
 __RUN_SCWRYPT zsh/scwrypts/environment/synchronize -- --no-prompt \
 	|| __FAIL 4 'failed to run environment sync'

zsh/scwrypts/environment/edit

@@ -27,7 +27,7 @@ _SORT_ENV $ENV_FILE
 
 while read line
 do
-	ENV_VAR=$(echo "$line" | sed 's/=.*$//; s/^export //')
+	ENV_VAR=$(echo "$line" | _SED 's/=.*$//; s/^export //')
 	grep -q "$ENV_VAR" $__ENV_TEMPLATE || {
 		((NEW_VAR+=1))
 		echo "export $ENV_VAR=" >> $__ENV_TEMPLATE

zsh/scwrypts/environment/synchronize

@@ -17,10 +17,12 @@ _SYNCHRONIZE() {
 
 	[ ! $SLIENT ] && {
 		__yN 'change the template before sync?' && __EDIT $__ENV_TEMPLATE
-		_SORT_ENV "$__ENV_TEMPLATE"
-		git add $__ENV_TEMPLATE >/dev/null 2>&1
 	}
 
+	_SORT_ENV "$__ENV_TEMPLATE"
+	_SED -i '/__[a-z_]\+=$/d' "$__ENV_TEMPLATE"
+	git add $__ENV_TEMPLATE >/dev/null 2>&1
+
 	ENVIRONMENTS=$(__GET_ENV_NAMES | sort -r)
 
 	_CLEAR_INHERITED_VARIABLES
@@ -38,7 +40,7 @@ _CLEAR_INHERITED_VARIABLES() {
 	for ENV_NAME in $(echo $ENVIRONMENTS)
 	do
 		ENV_FILE=$(__GET_ENV_FILE $ENV_NAME)
-		sed -i 's/ # inherited from.*//' "$ENV_FILE"
+		_SED -i 's/ # inherited from.*//' "$ENV_FILE"
 	done
 }
 
@@ -55,7 +57,7 @@ _INSERT_NEW_VARIABLES() {
 	            echo $line >> $ENV_FILE && __STATUS "added '$line' to '$ENV_NAME'"
 	        }
 	    done
-	done < <(sed -n '/^./p' "$__ENV_TEMPLATE")
+	done < <(_SED -n '/^./p' "$__ENV_TEMPLATE")
 }
 
 _REMOVE_OLD_VARIABLES() {
@@ -67,9 +69,11 @@ _REMOVE_OLD_VARIABLES() {
 		ENV_FILE=$(__GET_ENV_FILE $ENV_NAME)
 	    while read line
 	    do
-	        ENV_VAR=$(echo "$line" | sed 's/=.*/=/')
+	        ENV_VAR=$(echo "$line" | _SED 's/=.*/=/')
+			echo $ENV_VAR | grep -q '__[a-z_]\+=' && continue
+
 	        grep -q "$ENV_VAR" "$__ENV_TEMPLATE" || {
-	            sed -i "\\%$ENV_VAR%d" "$ENV_FILE"
+	            _SED -i "\\%$ENV_VAR%d" "$ENV_FILE"
 	            echo "$ENV_VAR" | grep -qv '^#' \
 					&& __WARNING "removed unwanted '$ENV_VAR' from '$ENV_NAME'"
 	        }
@@ -110,8 +114,8 @@ _CASCADE_ENVIRONMENT() {
 
 	while read PARENT_VAR
 	do
-		VAR_PATTERN=$(echo "$PARENT_VAR" | sed 's/=.*/=/; s/\//\/\//g')
+		VAR_PATTERN=$(echo "$PARENT_VAR" | _SED 's/=.*/=/; s/\//\/\//g')
-		__STATUS "propagating '$(echo $VAR_PATTERN | sed 's/^export \([^=]*\)=/\1/')' to children"
+		__STATUS "propagating '$(echo $VAR_PATTERN | _SED 's/^export \([^=]*\)=/\1/')' to children"
 
 		PARENT_VAR+=" # inherited from $PARENT_NAME"
 
@@ -119,10 +123,10 @@ _CASCADE_ENVIRONMENT() {
 		do
 			CHILD_FILE=$(__GET_ENV_FILE $CHILD_NAME)
 
-			sed -i "/^$VAR_PATTERN/d" "$CHILD_FILE"
+			_SED -i "/^$VAR_PATTERN/d" "$CHILD_FILE"
 			echo $PARENT_VAR >> "$CHILD_FILE"
 		done
-	done < <(sed -n '/^[^#][^=]*=[^#]\+$/p' "$PARENT_FILE")
+	done < <(_SED -n '/^[^#][^=]*=[^#]\+$/p' "$PARENT_FILE")
 
 	__SUCCESS "finished '$PARENT_NAME' propagation"
 }
@@ -131,22 +135,19 @@ _ADD_DESCRIPTIONS() {
 	__STATUS 'updating descriptions'
 	while read DESCRIPTION_LINE
 	do
-		ENV_VAR=$(echo $DESCRIPTION_LINE | sed 's/ \+| .*$//')
+		ENV_VAR=$(echo $DESCRIPTION_LINE | _SED 's/ \+| .*$//')
-		DESCRIPTION=$(echo $DESCRIPTION_LINE | sed 's/^.* | //')
+		DESCRIPTION=$(echo $DESCRIPTION_LINE | _SED 's/^.* | //')
 		for ENV_NAME in $(echo $ENVIRONMENTS)
 		do
-			sed -i "/^export $ENV_VAR=/i # $DESCRIPTION" "$(__GET_ENV_FILE $ENV_NAME)"
+			_SED -i "/^export $ENV_VAR=/i # $DESCRIPTION" "$(__GET_ENV_FILE $ENV_NAME)"
 		done
-	done < <(sed -n '/^[^ ]\+ \+| /p' "$__ENV_TEMPLATE.descriptions")
+	done < <(_SED -n '/^[^ ]\+ \+| /p' "$__ENV_TEMPLATE.descriptions")
 
-	while read ENV_VAR
-	do
 	for ENV_NAME in $(echo $ENVIRONMENTS)
 	do
-			sed -i "/^export $ENV_VAR=/a \ " "$(__GET_ENV_FILE $ENV_NAME)"
+		_SED -i "/^# /i \ " "$(__GET_ENV_FILE $ENV_NAME)"
-			sed -i "s/^ $//" "$(__GET_ENV_FILE $ENV_NAME)"
+		_SED -i "s/^ $//" "$(__GET_ENV_FILE $ENV_NAME)"
 	done
-	done < <(grep -B1 '^$' "$__ENV_TEMPLATE.descriptions" | grep '|' | awk '{print $1;}')
 }
 
 #####################################################################

zsh/utils/environment.zsh

@@ -8,12 +8,24 @@ __CHECK_ENV_VAR() {
 	local NAME="$1"
 	[ ! $NAME ] && return 1
 
+	local OVERRIDE_VALUE=$(eval echo '$'$NAME'__override')
+	[ $OVERRIDE_VALUE ] && export $NAME=$OVERRIDE_VALUE && return 0
+
 	local OPTIONAL="$2"
 	local DEFAULT_VALUE="$3"
 
 	local VALUE=$(eval echo '$'$NAME)
 	[ $VALUE ] && return 0
 
+	local SELECTION_VALUES=$(eval echo '$'$NAME'__select' | sed 's/,/\n/g')
+	[ $SELECTION_VALUES ] && {
+		local SELECTION=$(echo $SELECTION_VALUES | __FZF "select a value for '$NAME'")
+		[ $SELECTION ] && {
+			export $NAME=$SELECTION
+			return 0
+		}
+	}
+	[ $VALUE ] && return 0
 
 	[ $__SCWRYPT ] && {
 		# scwrypts exclusive (missing vars staged in env.template)

zsh/utils/io.zsh

@@ -8,6 +8,7 @@ __PRINT() {
 	printf "${COLOR}${MESSAGE}${__COLOR_RESET}${LINE_END}"
 }
 
+[ ! $ERRORS ] && export ERRORS=0
 __ERROR()    { __PRINT $__RED    "ERROR    ✖ : $@" >&2; ((ERRORS+=1)); }
 __SUCCESS()  { __PRINT $__GREEN  "SUCCESS  ✔ : $@" >&2; }
 __WARNING()  { __PRINT $__ORANGE "WARNING   : $@" >&2; }
@@ -37,7 +38,7 @@ __USAGE() {
 	local USAGE_LINE=$(\
 		echo $USAGE \
 			| grep -i '^ *usage *:' \
-			| sed "s;^[^:]*:;& scwrypts -- $SCWRYPT_NAME;" \
+			| sed "s;^[^:]*:;& scwrypts $SCWRYPT_NAME --;" \
 			| sed 's/ \{2,\}/ /g; s/scwrypts -- scwrypts/scwrypts/' \
 		)
 	local THE_REST=$(echo $USAGE | grep -vi '^ *usage *:' | sed 'N;/^\n$/D;P;D;')
@@ -85,7 +86,10 @@ __FZF()      {
 		exit 1
 	}
 
-	fzf -i --height=30% --layout=reverse --prompt "$1 : " ${@:2}
+	local SELECTION=$(fzf -i --height=30% --layout=reverse --prompt "$1 : " ${@:2})
+	__PROMPT "$1"
+	echo $SELECTION >&2
+	echo $SELECTION
 }
 __FZF_HEAD() { __FZF $@ --print-query | sed '/^$/d' | head -n1; } # prefer user input over selected
 __FZF_TAIL() { __FZF $@ --print-query | sed '/^$/d' | tail -n1; } # prefer selected over user input

zsh/vim/vundle/common.zsh

@@ -4,7 +4,7 @@ source ${0:a:h}/../common.zsh
 #####################################################################
 
 VUNDLE_PLUGIN_DIR="$HOME/.vim/bundle"
-VUNDLE_BUILD_DEFINITIONS="$VUNDLE_PLUGIN_DIR/build.zsh"
+VUNDLE_BUILD_DEFINITIONS="$SCWRYPTS_CONFIG_PATH/vundle.zsh"
 
 [ ! -f $VUNDLE_BUILD_DEFINITIONS ] && {
 	{