Merge pull request #74 from rsgalloway/v0.9.1

Version 0.9.1

Author: rsgalloway

.gitignore

@@ -16,4 +16,5 @@ venv*/
 .vscode/
 keys.env
 encrypted.env
-baketest.env
+baketest.env
+out.env

README.md

@@ -12,23 +12,6 @@ Environment variable management system.
 [Python API](#python-api) |
 [Running Commands](#running-commands)
 
-
-| Feature | Description |
-|---------|-------------|
-| Namespaced environments | Environments in envstack are namespaced, allowing you to organize and manage variables based on different contexts or projects. Each environment stack can have its own set of variables, providing a clean separation and avoiding conflicts between different environments. |
-| Environment stacks | Allows you to manage environment variables using .env files called environment stacks. These stacks provide a hierarchical and contextual approach to managing variables. |
-| Encryption support | Secure encryption, including AES-GCM, Fernet, and Base64. This allows you to securely encrypt and decrypt sensitive environment variables. |
-| Hierarchical structure | Stacks can be combined and have a defined order of priority. Variables defined in higher scope stacks flow from higher scope to lower scope, left to right. |
-| Variable expansion modifiers | Supports bash-like variable expansion modifiers, allowing you to set default values for variables and override them in the environment or by higher scope stacks. |
-| Platform-specific variables | Stacks can have platform-specific variables and values. This allows you to define different values for variables based on the platform. |
-| Variable references | Variables can reference other variables, allowing for more flexibility and dynamic value assignment. |
-| Multi-line values | Supports variables with multi-line values. |
-| Includes | Stack files can include other stacks, making it easy to reuse and combine different stacks. |
-| Python API | Provides a Python API that allows you to initialize and work with environment stacks programmatically. Easily initialize pre-defined environments with Python scripts, tools, and wrappers. |
-| Running commands | Allows you to run command line executables inside an environment stack, providing a convenient way to execute commands with a pre-defined environment. |
-| Wrappers | Supports wrappers, which are command line executable scripts that automatically run a given command in the environment stack. This allows for easy customization and management of environments. |
-| Shell integration | Provides instructions for sourcing the environment stack in your current shell, allowing you to set and clear the environment easily. |
-
 ## Installation
 
 The easiest way to install:
@@ -70,15 +53,13 @@ $ curl -o default.env https://raw.githubusercontent.com/rsgalloway/envstack/mast
 Alternatively, set `${ENVPATH}` to the directory containing your environment
 stack files:
 
-#### bash
 ```bash
 $ export ENVPATH=/path/to/env/files
 ```
 
 Define as many paths as you want, and envstack will search for stack files in
 order from left to right, for example:
 
-#### bash
 ```bash
 $ export ENVPATH=/mnt/pipe/dev/env:/mnt/pipe/prod/env
 ```
@@ -209,50 +190,34 @@ $ envstack -s HELLO=world -o hello.env
 You can convert existing `.env` files to envstack by piping them into envstack:
 
 ```bash
-$ cat .env | envstack --set -o dev.env
+$ cat .env | envstack --set -o out.env
 ```
 
-## Creating Stacks
+## Creating Environments
 
 Several example or starter stacks are available in the [env folder of the
 envstack repo](https://github.com/rsgalloway/envstack/tree/master/env).
 
-To create a new environment stack, create an envstack file and declare some
-variables.
+To create a new environment file, use `--set` to declare some variables:
 
 ```bash
-$ envstack foobar -o foobar.env
-```
-
-Add the `${FOO}` and `${BAR}` env vars to the foobar.env environment stack file:
-
-```yaml
-#!/usr/bin/env envstack
-all: &all
-  FOO: bar
-  BAR: ${FOO}
-darwin:
-  <<: *all
-linux:
-  <<: *all
-windows:
-  <<: *all
+$ envstack -s FOO=bar BAR=\${FOO} -o out.env
 ```
 
-Or using Python:
+Using Python:
 
 ```python
 >>> env = Env({"FOO": "bar", "BAR": "${FOO}"})
->>> env.write("foobar.env")
+>>> env.write("out.env")
 ```
 
-Get the resolved environment for the `foobar` stack:
+Get the resolved values back:
 
 ```bash
-$ ./foobar.env -r
+$ ./out.env -r
 BAR=bar
 FOO=bar
-STACK=foobar
+STACK=out
 ```
 
 #### More Details
@@ -330,7 +295,7 @@ nodes look for keys in the following order, favoring AES-GCM over Fernet:
 | Fernet | ${ENVSTACK_FERNET_KEY} |
 
 If no encryption keys are found in the environment, envstack will default to
-using Base64 encryption:
+using Base64 encoding:
 
 ```bash
 $ envstack --encrypt
@@ -357,7 +322,7 @@ $ source <(envstack --keygen --export)
 Once the keys are in the environment, you can encrypt the env stack:
 
 ```bash
-$ envstack --encrypt -o encrypted.env
+$ envstack -o encrypted.env --encrypt
 ```
 
 Encrypted variables will resolve as long as the key is in the environment:
@@ -369,17 +334,17 @@ HELLO=world
 
 #### Storing Keys
 
-Keys can be stored in other environment stacks, e.g. a `keys.env` file. To
-generate keys and store them in a `keys.env` env stack file:
+Keys can be stored in other environment stacks, e.g. a `keys.env` file
+(keys are automatically base64 encoded):
 
 ```bash
 $ envstack --keygen -o keys.env
 ```
 
-Then use the `keys.env` env stack to encrypt any other env stack:
+Then use `keys.env` to encrypt any other environment files:
 
 ```bash
-$ envstack keys -- envstack --encrypt -o encrypted.env
+$ ./keys.env -- envstack -eo encrypted.env
 ```
 
 To decrypt, add `keys` to the env stack:
@@ -389,7 +354,14 @@ $ envstack keys encrypted -r HELLO
 HELLO=world
 ```
 
-Or add the `keys` env stack to `include` to automatically decrypt:
+Or run the command inside the `keys` environment like this:
+
+```bash
+$ ./keys.env -- envsatck encrypted -r HELLO
+HELLO=world
+```
+
+Or include `keys` in environments to automatically decrypt:
 
 ```yaml
 include: [keys]

lib/envstack/__init__.py

@@ -34,6 +34,6 @@
 """
 
 __prog__ = "envstack"
-__version__ = "0.9.0"
+__version__ = "0.9.1"
 
 from envstack.env import clear, init, revert, save  # noqa: F401

lib/envstack/cli.py

@@ -205,8 +205,14 @@ def parse_args():
         "--set",
         nargs="*",
         action=StoreOnce,
-        metavar="VAR=VALUE",
-        help="convert KEY=VALUE pairs to envstack environment variables",
+        metavar="KEY=VALUE",
+        help="overlay KEY=VALUE pairs to envstack environments",
+    )
+    parser.add_argument(
+        "-b",
+        "--bare",
+        action="store_true",
+        help="create a bare environment",
     )
     parser.add_argument(
         "--scope",
@@ -234,6 +240,12 @@ def parse_args():
         action="store_true",
         help="list the env stack file sources",
     )
+    export_group.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        help="print values only",
+    )
 
     args = parser.parse_args(args_before_dash)
 
@@ -278,6 +290,13 @@ def main():
         elif args.set is not None:
             force_stdin = args.set == [] or args.set == ["-"]
             using_pipe = args.set == [] and not sys.stdin.isatty()
+
+            # load the environment if not in bare mode
+            if args.bare:
+                env = Env()
+            else:
+                env = load_environ(args.namespace, platform=args.platform)
+
             # interactive mode
             if force_stdin and sys.stdin.isatty():
                 print(
@@ -302,15 +321,27 @@ def main():
             else:
                 data = _parse_keyvals(args.set)
 
+            # encrypt the new data only
             if args.encrypt:
-                data = encrypt_environ(data, encrypt=(not args.out))
+                data = encrypt_environ(data)
+
+            # update the environment with the new data
+            env.update(data)
+
             if args.export:
-                print(export_env_to_shell(data))
+                print(export_env_to_shell(env))
             elif args.out:
-                Env(data).write(args.out)
+                Env(env).write(args.out)
             else:
-                for key, value in data.items():
-                    print(f"{key}={value}")
+                for key, val in env.items():
+                    if args.quiet:
+                        if len(env) > 1:
+                            print("error: --quiet requires exactly one KEY")
+                            return 2
+                        else:
+                            print(val)
+                    else:
+                        print(f"{key}={val}")
 
         elif args.out:
             bake_environ(
@@ -327,14 +358,30 @@ def main():
             keys = args.resolve or resolved.keys()
             for key in sorted(str(k) for k in keys):
                 val = resolved.get(key)
-                print(f"{key}={val}")
+                if key in resolved:
+                    if args.quiet:
+                        if len(keys) > 1:
+                            print("error: --quiet requires exactly one KEY")
+                            return 2
+                        else:
+                            print(val)
+                    else:
+                        print(f"{key}={val}")
 
         elif args.trace is not None:
             if len(args.trace) == 0:
                 args.trace = load_environ(args.namespace).keys()
             for trace in args.trace:
                 path = trace_var(*args.namespace, var=trace)
-                print("{0}: {1}".format(trace, path))
+                if path:
+                    if args.quiet:
+                        if len(args.trace) > 1:
+                            print("error: --quiet requires exactly one KEY")
+                            return 2
+                        else:
+                            print(path)
+                    else:
+                        print("{0}={1}".format(trace, path))
 
         elif args.sources:
             env = load_environ(args.namespace, platform=args.platform)

lib/envstack/encrypt.py

@@ -313,10 +313,12 @@ def generate_keys():
 
     :returns: Dictionary containing Fernet and AES-GCM keys.
     """
+    from envstack.node import Base64Node
+
     symmetric_key = AESGCMEncryptor.generate_key()
     fernet_key = FernetEncryptor.generate_key()
 
     return {
-        AESGCMEncryptor.KEY_VAR_NAME: symmetric_key,
-        FernetEncryptor.KEY_VAR_NAME: fernet_key,
+        AESGCMEncryptor.KEY_VAR_NAME: Base64Node(symmetric_key),
+        FernetEncryptor.KEY_VAR_NAME: Base64Node(fernet_key),
     }

lib/envstack/env.py

@@ -344,7 +344,10 @@ def get_node_class(value):
 
         # write the baked environment to the file
         if filename:
-            baked.write()
+            try:
+                baked.write()
+            except Exception as err:
+                raise WriteError(f"Failed to write {filename}", err)
 
         # create the baked environment from the baked source
         baked_env = Env()
@@ -791,6 +794,7 @@ def encrypt_environ(
             node = node_class(v)
             if encrypt:
                 node.value = node.encryptor(env=resolved_env).encrypt(str(v))
+                node.original_value = node.value
             encrypted_env[k] = node
         else:
             encrypted_env[k] = v

lib/envstack/exceptions.py

@@ -74,3 +74,9 @@ class TemplateNotFound(Exception):
     """Custom exception class for missing Templates."""
 
     pass
+
+
+class WriteError(Exception):
+    """Custom exception class for errors during export operations."""
+
+    pass

setup.py

@@ -40,7 +40,7 @@
 
 setup(
     name="envstack",
-    version="0.9.0",
+    version="0.9.1",
     description="Stacked environment variable management system",
     long_description=long_description,
     long_description_content_type="text/markdown",