envstack 0.9.6__tar.gz → 1.0.1__tar.gz

{envstack-0.9.6 → envstack-1.0.1}/LICENSE

@@ -1,6 +1,6 @@
 envstack
 
-Copyright (c) 2024-2025, Ryan Galloway (ryan@rsgalloway.com)
+Copyright (c) 2024-2026, Ryan Galloway (ryan@rsgalloway.com)
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

{envstack-0.9.6/lib/envstack.egg-info → envstack-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: envstack
-Version: 0.9.6
+Version: 1.0.1
 Summary: Environment variable composition layer for tools and processes.
 Author-email: Ryan Galloway <ryan@rsgalloway.com>
 License: BSD 3-Clause License
@@ -41,9 +41,22 @@ Environment variable composition and activation layer for tools and processes.
 - Shared, policy-driven environments
 - Inspectable and deterministic behavior
 
-envstack focuses on **configuration and activation**, not dependency resolution.
+envstack environments are layered hierarchically, with later layers inheriting
+from and overriding earlier ones.
 
-For the core concepts, see `docs/index.md`.
+```mermaid
+flowchart LR
+  default[default.env] --> prod[prod.env]
+  prod --> dev[dev.env]
+  prod --> test[test.env]
+```
+
+Later layers override earlier ones. Use envstack -t VAR to trace where a value
+comes from. envstack focuses on **configuration and activation**, not dependency
+resolution.
+
+For the core concepts, see
+[docs/index.md](https://github.com/rsgalloway/envstack/blob/master/docs/index.md).
 
 ## Installation
 
@@ -55,7 +68,9 @@ pip install -U envstack
 
 ## Quickstart
 
-Start by getting the latest `default.env` example file:
+Start by getting the latest
+[default.env](https://github.com/rsgalloway/envstack/blob/master/examples/default/default.env) 
+example file:
 
 ```bash
 curl -o \
@@ -79,7 +94,6 @@ $ envstack -u
 DEPLOY_ROOT=${ROOT}/${ENV}
 ENV=prod
 ENVPATH=${DEPLOY_ROOT}/env:${ENVPATH}
-HELLO=${HELLO:=world}
 LOG_LEVEL=${LOG_LEVEL:=INFO}
 PATH=${DEPLOY_ROOT}/bin:${PATH}
 PS1=\[\e[32m\](${ENV})\[\e[0m\] \w\$ 
@@ -138,10 +152,22 @@ $ envstack -- node index.js
 Hello prod
 ```
 
+## Secrets and encryption
+
+envstack supports optional encryption of environment values when writing
+environment files, allowing sensitive configuration to be safely stored,
+committed, or distributed.
+
+Encryption protects values **at rest** and integrates with environment stacks and
+includes. envstack does not attempt to be a full secret management system.
+
+See [docs/secrets.md](https://github.com/rsgalloway/envstack/blob/master/docs/secrets.md) for details.
+
 ## Documentation
 
-- Design & philosophy → `docs/design.md`
-- Examples & patterns → `docs/examples.md`
-- Tool comparisons → `docs/comparison.md`
-- FAQ & gotchas → `docs/faq.md`
-- API docs → `docs/api.md`
+- [Design & philosophy](https://github.com/rsgalloway/envstack/blob/master/docs/design.md)
+- [Examples & patterns](https://github.com/rsgalloway/envstack/blob/master/docs/examples.md)
+- [Tool comparisons](https://github.com/rsgalloway/envstack/blob/master/docs/comparison.md)
+- [Secrets and encryption](https://github.com/rsgalloway/envstack/blob/master/docs/secrets.md)
+- [FAQ & gotchas](https://github.com/rsgalloway/envstack/blob/master/docs/faq.md)
+- [API docs](https://github.com/rsgalloway/envstack/blob/master/docs/api.md)

{envstack-0.9.6 → envstack-1.0.1}/README.md

@@ -13,9 +13,22 @@ Environment variable composition and activation layer for tools and processes.
 - Shared, policy-driven environments
 - Inspectable and deterministic behavior
 
-envstack focuses on **configuration and activation**, not dependency resolution.
+envstack environments are layered hierarchically, with later layers inheriting
+from and overriding earlier ones.
+
+```mermaid
+flowchart LR
+  default[default.env] --> prod[prod.env]
+  prod --> dev[dev.env]
+  prod --> test[test.env]
+```
+
+Later layers override earlier ones. Use envstack -t VAR to trace where a value
+comes from. envstack focuses on **configuration and activation**, not dependency
+resolution.
 
-For the core concepts, see `docs/index.md`.
+For the core concepts, see
+[docs/index.md](https://github.com/rsgalloway/envstack/blob/master/docs/index.md).
 
 ## Installation
 
@@ -27,7 +40,9 @@ pip install -U envstack
 
 ## Quickstart
 
-Start by getting the latest `default.env` example file:
+Start by getting the latest
+[default.env](https://github.com/rsgalloway/envstack/blob/master/examples/default/default.env) 
+example file:
 
 ```bash
 curl -o \
@@ -51,7 +66,6 @@ $ envstack -u
 DEPLOY_ROOT=${ROOT}/${ENV}
 ENV=prod
 ENVPATH=${DEPLOY_ROOT}/env:${ENVPATH}
-HELLO=${HELLO:=world}
 LOG_LEVEL=${LOG_LEVEL:=INFO}
 PATH=${DEPLOY_ROOT}/bin:${PATH}
 PS1=\[\e[32m\](${ENV})\[\e[0m\] \w\$ 
@@ -110,10 +124,22 @@ $ envstack -- node index.js
 Hello prod
 ```
 
+## Secrets and encryption
+
+envstack supports optional encryption of environment values when writing
+environment files, allowing sensitive configuration to be safely stored,
+committed, or distributed.
+
+Encryption protects values **at rest** and integrates with environment stacks and
+includes. envstack does not attempt to be a full secret management system.
+
+See [docs/secrets.md](https://github.com/rsgalloway/envstack/blob/master/docs/secrets.md) for details.
+
 ## Documentation
 
-- Design & philosophy → `docs/design.md`
-- Examples & patterns → `docs/examples.md`
-- Tool comparisons → `docs/comparison.md`
-- FAQ & gotchas → `docs/faq.md`
-- API docs → `docs/api.md`
+- [Design & philosophy](https://github.com/rsgalloway/envstack/blob/master/docs/design.md)
+- [Examples & patterns](https://github.com/rsgalloway/envstack/blob/master/docs/examples.md)
+- [Tool comparisons](https://github.com/rsgalloway/envstack/blob/master/docs/comparison.md)
+- [Secrets and encryption](https://github.com/rsgalloway/envstack/blob/master/docs/secrets.md)
+- [FAQ & gotchas](https://github.com/rsgalloway/envstack/blob/master/docs/faq.md)
+- [API docs](https://github.com/rsgalloway/envstack/blob/master/docs/api.md)

{envstack-0.9.6 → envstack-1.0.1}/lib/envstack/__init__.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 #
-# Copyright (c) 2024-2025, Ryan Galloway (ryan@rsgalloway.com)
+# Copyright (c) 2024-2026, Ryan Galloway (ryan@rsgalloway.com)
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:
@@ -34,7 +34,7 @@ Stacked environment variable management system.
 """
 
 __prog__ = "envstack"
-__version__ = "0.9.6"
+__version__ = "1.0.1"
 
 from envstack.env import clear, init, revert, save  # noqa: F401
-from envstack.env import load_environ, resolve_environ  # noqa: F401
+from envstack.env import load_environ, resolve_environ  # noqa: F401

{envstack-0.9.6 → envstack-1.0.1}/lib/envstack/cli.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 #
-# Copyright (c) 2024-2025, Ryan Galloway (ryan@rsgalloway.com)
+# Copyright (c) 2024-2026, Ryan Galloway (ryan@rsgalloway.com)
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:

{envstack-0.9.6 → envstack-1.0.1}/lib/envstack/config.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 #
-# Copyright (c) 2024-2025, Ryan Galloway (ryan@rsgalloway.com)
+# Copyright (c) 2024-2026, Ryan Galloway (ryan@rsgalloway.com)
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:
@@ -57,12 +57,32 @@ def detect_shell():
             return "/usr/bin/bash"
 
 
+# debug mode
 DEBUG = os.getenv("DEBUG")
+
+# default namespace
 DEFAULT_NAMESPACE = os.getenv("DEFAULT_ENV_STACK", "default")
+
+# allow embedded commands
+ALLOW_COMMANDS = os.getenv("ALLOW_COMMANDS", "0") in ("1", "true", "True", "TRUE")
+
+# embedded command timeout in seconds
+try:
+    COMMAND_TIMEOUT = int(os.getenv("COMMAND_TIMEOUT", 5))
+except ValueError:
+    COMMAND_TIMEOUT = 5
+
+# default environment variables
 ENV = os.getenv("ENV", "prod")
 HOME = os.getenv("HOME")
-IGNORE_MISSING = bool(os.getenv("IGNORE_MISSING", 1))
+
+# Ignore missing stack files when resolving environments
+IGNORE_MISSING = os.getenv("IGNORE_MISSING", "1") in ("1", "true", "True", "TRUE")
+
+# logging level
 LOG_LEVEL = os.environ.get("LOG_LEVEL", "INFO")
+
+# platform and shell info
 ON_POSIX = "posix" in sys.builtin_module_names
 PLATFORM = platform.system().lower()
 PYTHON_VERSION = sys.version_info[0]

{envstack-0.9.6 → envstack-1.0.1}/lib/envstack/encrypt.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 #
-# Copyright (c) 2024-2025, Ryan Galloway (ryan@rsgalloway.com)
+# Copyright (c) 2024-2026, Ryan Galloway (ryan@rsgalloway.com)
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:

{envstack-0.9.6 → envstack-1.0.1}/lib/envstack/env.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 #
-# Copyright (c) 2024-2025, Ryan Galloway (ryan@rsgalloway.com)
+# Copyright (c) 2024-2026, Ryan Galloway (ryan@rsgalloway.com)
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:

{envstack-0.9.6 → envstack-1.0.1}/lib/envstack/envshell.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 #
-# Copyright (c) 2024-2025, Ryan Galloway (ryan@rsgalloway.com)
+# Copyright (c) 2024-2026, Ryan Galloway (ryan@rsgalloway.com)
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:
@@ -131,7 +131,7 @@ class EnvshellWrapper(Wrapper):
         if os.name == "nt":
             return ("PROMPT", "$E[32m(${ENV:=${STACK}})$E[0m $P$G ")
         else:
-            return ("PS1", "\[\e[32m\](${ENV:=${STACK}})\[\e[0m\] \w\$ ")
+            return ("PS1", r"\[\e[32m\](${ENV:=${STACK}})\[\e[0m\] \w\$ ")
 
     def get_subprocess_env(self):
         """

{envstack-0.9.6 → envstack-1.0.1}/lib/envstack/exceptions.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 #
-# Copyright (c) 2024-2025, Ryan Galloway (ryan@rsgalloway.com)
+# Copyright (c) 2024-2026, Ryan Galloway (ryan@rsgalloway.com)
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:

{envstack-0.9.6 → envstack-1.0.1}/lib/envstack/logger.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 #
-# Copyright (c) 2024-2025, Ryan Galloway (ryan@rsgalloway.com)
+# Copyright (c) 2024-2026, Ryan Galloway (ryan@rsgalloway.com)
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:

{envstack-0.9.6 → envstack-1.0.1}/lib/envstack/node.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 #
-# Copyright (c) 2024-2025, Ryan Galloway (ryan@rsgalloway.com)
+# Copyright (c) 2024-2026, Ryan Galloway (ryan@rsgalloway.com)
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:
@@ -250,30 +250,35 @@ class FernetNode(BaseNode):
 
 
 class CustomLoader(yaml.SafeLoader):
+    """Custom Loader class to preserve order of keys and ensure required
+    keys are first in the mapping."""
+
     required_keys = {"include", "all", "darwin", "linux", "windows"}
 
     def construct_mapping(self, node: yaml.Node, deep: bool = False):
-        mapping = super().construct_mapping(node, deep=deep)
-        for key, value in mapping.items():
+        """Construct a mapping from a YAML node, preserving the order of keys
+        and ensuring"""
+        # keep YAML merge keys (<<) working
+        self.flatten_mapping(node)
+
+        mapping = {}
+
+        for key_node, value_node in node.value:
+            # never implicit-resolve scalar KEYS (YES/NO/ON/OFF/null/date/etc)
+            if isinstance(key_node, yaml.ScalarNode):
+                key = key_node.value
+            else:
+                key = self.construct_object(key_node, deep=deep)
+
+            value = self.construct_object(value_node, deep=deep)
+            mapping[key] = value
+
+        # preserve order of keys and ensure required keys are first in the mapping
+        for key, value in list(mapping.items()):
             if key in self.required_keys:
                 continue
-            try:
-                if node.tag == Base64Node.yaml_tag:
-                    mapping[key] = Base64Node(value)
-                elif node.tag == EncryptedNode.yaml_tag:
-                    mapping[key] = EncryptedNode(value)
-                elif node.tag == AESGCMNode.yaml_tag:
-                    mapping[key] = AESGCMNode(value)
-                elif node.tag == FernetNode.yaml_tag:
-                    mapping[key] = FernetNode(value)
-                elif node.tag == MD5Node.yaml_tag:
-                    mapping[key] = MD5Node(value)
-                else:
-                    mapping[key] = Template(value)
-            except Exception as e:
-                raise yaml.constructor.ConstructorError(
-                    None, None, f"Error parsing template: {e}", node.start_mark
-                )
+            mapping[key] = value
+
         return mapping