evm-cli 2.4.0__py3-none-any.whl

evm/__init__.py

@@ -0,0 +1,55 @@
+"""
+EVM - Environment Variable Manager
+A command-line tool for managing environment variables.
+"""
+
+__version__ = "2.4.0"
+__author__ = "EVM Tool"
+
+from .exceptions import (
+    BackupError,
+    CommandNotFoundError,
+    CorruptedStorageError,
+    DecryptionError,
+    EditorError,
+    EVMError,
+    ExportError,
+    GroupNotFoundError,
+    GroupOperationError,
+    ImportFailedError,
+    KeyAlreadyExistsError,
+    KeyNotFoundError,
+    LockTimeoutError,
+    OperationCancelledError,
+    SchemaError,
+    StorageError,
+    StoragePermissionError,
+    ValidationError,
+)
+from .manager import EnvironmentManager
+
+__all__ = [
+    '__version__',
+    '__author__',
+    # Core API
+    'EnvironmentManager',
+    # Exceptions
+    'EVMError',
+    'KeyNotFoundError',
+    'KeyAlreadyExistsError',
+    'StorageError',
+    'CorruptedStorageError',
+    'StoragePermissionError',
+    'LockTimeoutError',
+    'ExportError',
+    'ImportFailedError',
+    'CommandNotFoundError',
+    'GroupNotFoundError',
+    'GroupOperationError',
+    'BackupError',
+    'EditorError',
+    'DecryptionError',
+    'ValidationError',
+    'SchemaError',
+    'OperationCancelledError',
+]

evm/__main__.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+"""
+Entry point for running EVM as a module: python -m evm
+"""
+
+from evm.cli import main
+
+if __name__ == '__main__':
+    raise SystemExit(main())

evm/_completion.py

@@ -0,0 +1,253 @@
+#!/usr/bin/env python3
+"""
+EVM Shell 补全脚本生成
+
+支持 bash, zsh, fish。
+M3: 为 get/delete/edit/expand/validate/rename/copy 等命令
+提供动态变量名补全（通过 evm list --json --quiet 获取 key 列表）。
+"""
+
+
+def generate_bash_completion(commands: list) -> str:
+    """生成 bash 补全脚本（含动态变量名补全）"""
+    cmds = ' '.join(commands)
+    # 需要变量名补全的命令
+    key_cmds = ' '.join([
+        'get', 'delete', 'edit', 'expand', 'validate',
+        'rename', 'copy', 'setg', 'getg', 'deleteg', 'listg',
+    ])
+    return f'''# EVM bash completion
+# L3: 仅在 evm 命令可用时注册补全
+if ! command -v evm &>/dev/null; then
+    return 2>/dev/null || exit
+fi
+
+_evm_completions() {{
+    local cur prev opts
+    COMPREPLY=()
+    cur="${{COMP_WORDS[COMP_CWORD]}}"
+    prev="${{COMP_WORDS[COMP_CWORD-1]}}"
+
+    # Top-level commands
+    local commands="{cmds}"
+    local global_opts="--help --version --verbose --env-file --json --quiet --dry-run --force"
+    local key_cmds="{key_cmds}"
+
+    # 动态获取变量名列表
+    _evm_keys() {{
+        evm list --json --quiet 2>/dev/null | \\
+            python3 -c "import sys,json; d=json.load(sys.stdin); print(' '.join(d.get('data',{{}}).keys()))" 2>/dev/null
+    }}
+
+    case "${{prev}}" in
+        evm)
+            COMPREPLY=( $(compgen -W "${{commands}} ${{global_opts}}" -- "${{cur}}") )
+            return 0
+            ;;
+        --env-file)
+            COMPREPLY=( $(compgen -f -- "${{cur}}") )
+            return 0
+            ;;
+        --format|-f)
+            COMPREPLY=( $(compgen -W "json env sh backup" -- "${{cur}}") )
+            return 0
+            ;;
+        set)
+            COMPREPLY=( $(compgen -W "--secret --help" -- "${{cur}}") )
+            return 0
+            ;;
+        get|delete|edit|expand|validate|rename|copy)
+            COMPREPLY=( $(compgen -W "$(_evm_keys) --secret --help" -- "${{cur}}") )
+            return 0
+            ;;
+        setg|getg|deleteg|listg)
+            # 分组名补全（从现有 key 中提取分组前缀）
+            local groups
+            groups=$(evm groups --json --quiet 2>/dev/null | \\
+                python3 -c "import sys,json; d=json.load(sys.stdin); print(' '.join(d.get('data',{{}}).get('groups',{{}}).keys()))" 2>/dev/null)
+            COMPREPLY=( $(compgen -W "${{groups}} --help" -- "${{cur}}") )
+            return 0
+            ;;
+        export)
+            COMPREPLY=( $(compgen -W "--format --output --group --help" -- "${{cur}}") )
+            return 0
+            ;;
+        load)
+            COMPREPLY=( $(compgen -W "--format --replace --group --nest --help" -- "${{cur}}") )
+            return 0
+            ;;
+        completion)
+            COMPREPLY=( $(compgen -W "bash zsh fish" -- "${{cur}}") )
+            return 0
+            ;;
+    esac
+
+    # 如果前一个词是需要 key 补全的命令，尝试补全变量名
+    for kc in ${{key_cmds}}; do
+        if [[ "${{COMP_WORDS[1]}}" == "$kc" ]]; then
+            COMPREPLY=( $(compgen -W "$(_evm_keys)" -- "${{cur}}") )
+            return 0
+        fi
+    done
+
+    COMPREPLY=( $(compgen -W "${{commands}} ${{global_opts}}" -- "${{cur}}") )
+}}
+complete -F _evm_completions evm
+'''
+
+
+def generate_zsh_completion(commands: list) -> str:
+    """生成 zsh 补全脚本（含动态变量名补全）"""
+    return f'''#compdef evm
+
+# L3: 仅在 evm 命令可用时注册补全
+if (( ! $+commands[evm] )); then
+    return
+fi
+
+_evm() {{
+    local -a commands
+    commands=(
+        {chr(10).join(f"        '{c}:{c} command'" for c in commands)}
+    )
+
+    # 动态获取变量名列表
+    _evm_keys() {{
+        local keys
+        keys=(${{(f)"$(evm list --json --quiet 2>/dev/null | \\
+            python3 -c "import sys,json; d=json.load(sys.stdin); print('\\n'.join(d.get('data',{{}}).keys()))" 2>/dev/null)"}})
+        _describe 'variable' keys
+    }}
+
+    # 动态获取分组名列表
+    _evm_groups() {{
+        local groups
+        groups=(${{(f)"$(evm groups --json --quiet 2>/dev/null | \\
+            python3 -c "import sys,json; d=json.load(sys.stdin); print('\\n'.join(d.get('data',{{}}).get('groups',{{}}).keys()))" 2>/dev/null)"}})
+        _describe 'group' groups
+    }}
+
+    _arguments -C \\
+        '--help[Show help]' \\
+        '--version[Show version]' \\
+        '(-v --verbose)'{{-v,--verbose}}'[Show detailed info]' \\
+        '--env-file[Storage file path]:file:_files' \\
+        '--json[Output structured JSON]' \\
+        '--quiet[Suppress output]' \\
+        '--dry-run[Preview changes]' \\
+        '--force[Skip confirmation]' \\
+        '1: :->command' \\
+        '*:: :->args'
+
+    case $state in
+        command)
+            _describe 'command' commands
+            ;;
+        args)
+            case $words[1] in
+                get|delete|edit|expand|validate)
+                    _evm_keys
+                    ;;
+                rename|copy)
+                    _evm_keys
+                    ;;
+                setg|getg|deleteg|listg)
+                    _evm_groups
+                    ;;
+                completion)
+                    _values 'shell' bash zsh fish
+                    ;;
+                export)
+                    _arguments \\
+                        '(-f --format)'{{-f,--format}}'[Format]:format:(json env sh)' \\
+                        '(-o --output)'{{-o,--output}}'[Output file]:file:_files' \\
+                        '(-g --group)'{{-g,--group}}'[Group name]:group'
+                    ;;
+            esac
+            ;;
+    esac
+}}
+
+_evm "$@"
+'''
+
+
+def generate_fish_completion(commands: list) -> str:
+    """生成 fish 补全脚本（含动态变量名补全）"""
+    lines = ['# EVM fish completion', '']
+
+    # L3: 仅在 evm 命令可用时注册补全
+    lines.append('# Guard: only register if evm is in PATH')
+    lines.append('if not command -q evm')
+    lines.append('    exit')
+    lines.append('end')
+    lines.append('')
+
+    # Disable file completion by default
+    lines.append('complete -c evm -f')
+    lines.append('')
+
+    # Global options
+    lines.append('# Global options')
+    lines.append("complete -c evm -l help -d 'Show help'")
+    lines.append("complete -c evm -l version -d 'Show version'")
+    lines.append("complete -c evm -s v -l verbose -d 'Show detailed info'")
+    lines.append("complete -c evm -l env-file -d 'Storage file path' -r -F")
+    lines.append("complete -c evm -l json -d 'Output structured JSON'")
+    lines.append("complete -c evm -l quiet -s q -d 'Suppress output'")
+    lines.append("complete -c evm -l dry-run -d 'Preview changes'")
+    lines.append("complete -c evm -l force -d 'Skip confirmation'")
+    lines.append('')
+
+    # Commands
+    lines.append('# Commands')
+    for cmd in commands:
+        lines.append(f"complete -c evm -n '__fish_use_subcommand' -a '{cmd}' -d '{cmd}'")
+    lines.append('')
+
+    # Dynamic variable name completion helper
+    lines.append('# Dynamic variable name completion')
+    lines.append('function __evm_keys')
+    lines.append('    evm list --json --quiet 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); [print(k) for k in d.get(\'data\',{})]" 2>/dev/null')
+    lines.append('end')
+    lines.append('')
+
+    # Dynamic group name completion helper
+    lines.append('function __evm_groups')
+    lines.append('    evm groups --json --quiet 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); [print(k) for k in d.get(\'data\',{}).get(\'groups\',{})]" 2>/dev/null')
+    lines.append('end')
+    lines.append('')
+
+    # Sub-options
+    lines.append('# Sub-options')
+    lines.append("complete -c evm -n '__fish_seen_subcommand_from set' -l secret -d 'Encrypt value'")
+    lines.append("complete -c evm -n '__fish_seen_subcommand_from get' -l secret -d 'Decrypt value'")
+    lines.append("complete -c evm -n '__fish_seen_subcommand_from export' -s f -l format -d 'Format' -xa 'json env sh'")
+    lines.append("complete -c evm -n '__fish_seen_subcommand_from export' -s o -l output -d 'Output file' -r -F")
+    lines.append("complete -c evm -n '__fish_seen_subcommand_from load' -s f -l format -d 'Format' -xa 'json env backup'")
+    lines.append("complete -c evm -n '__fish_seen_subcommand_from load' -s r -l replace -d 'Replace mode'")
+    lines.append("complete -c evm -n '__fish_seen_subcommand_from load' -s n -l nest -d 'Nested JSON'")
+    lines.append("complete -c evm -n '__fish_seen_subcommand_from completion' -xa 'bash zsh fish'")
+    lines.append("complete -c evm -n '__fish_seen_subcommand_from history' -s n -l limit -d 'Number of entries' -x")
+    lines.append("complete -c evm -n '__fish_seen_subcommand_from schema' -xa 'set get delete validate list'")
+    lines.append('')
+
+    # Variable name completion for relevant commands
+    lines.append('# Variable name completion')
+    for cmd in ['get', 'delete', 'edit', 'expand', 'validate', 'rename', 'copy']:
+        lines.append(f"complete -c evm -n '__fish_seen_subcommand_from {cmd}' -a '(__evm_keys)'")
+    lines.append('')
+
+    # Group name completion
+    lines.append('# Group name completion')
+    for cmd in ['setg', 'getg', 'deleteg', 'listg']:
+        lines.append(f"complete -c evm -n '__fish_seen_subcommand_from {cmd}' -a '(__evm_groups)'")
+
+    return '\n'.join(lines) + '\n'
+
+
+SHELL_GENERATORS = {
+    'bash': generate_bash_completion,
+    'zsh': generate_zsh_completion,
+    'fish': generate_fish_completion,
+}

evm/_crypto.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""
+EVM 加密模块
+
+提供安全的加密/解密功能：
+- HKDF-Expand: 密钥分离（加密密钥 + MAC 密钥）
+- HMAC-CTR: 基于 HMAC 的 CTR 模式流密码
+- HMAC-SHA256: 认证加密（Encrypt-then-MAC）
+
+格式: ENCv3:<salt_b64>:<iv_b64>:<mac_b64>:<ciphertext_b64>
+"""
+
+import base64
+import hashlib
+import hmac
+import os
+import struct
+
+from .exceptions import DecryptionError
+
+# SHA-256 输出长度（字节），用于 HKDF-Expand 计算
+HKDF_HASH_LEN = 32
+
+
+def hkdf_expand(prk: bytes, info: bytes, length: int = 32) -> bytes:
+    """HKDF-Expand (RFC 5869)
+
+    从伪随机密钥 (PRK) 派生指定长度的输出密钥材料。
+
+    Args:
+        prk: 伪随机密钥（至少 HKDF_HASH_LEN 字节）
+        info: 上下文和用途信息
+        length: 输出密钥材料长度（字节）
+
+    Returns:
+        派生的密钥材料
+    """
+    n = (length + HKDF_HASH_LEN - 1) // HKDF_HASH_LEN
+    okm = b''
+    t = b''
+    for i in range(1, n + 1):
+        t = hmac.new(
+            prk, t + info + bytes([i]), hashlib.sha256
+        ).digest()
+        okm += t
+    return okm[:length]
+
+
+def derive_subkeys(master_key: bytes, salt: bytes) -> tuple:
+    """从主密钥派生独立的加密和 MAC 子密钥
+
+    使用 HKDF-Expand 和不同的 info 字符串确保密钥分离。
+
+    Args:
+        master_key: PBKDF2 输出的主密钥
+        salt: 用于 HKDF info 的随机盐
+
+    Returns:
+        (enc_key, mac_key) 各 32 字节
+    """
+    enc_key = hkdf_expand(master_key, salt + b'evm-encryption', 32)
+    mac_key = hkdf_expand(master_key, salt + b'evm-authentication', 32)
+    return enc_key, mac_key
+
+
+def hmac_ctr_keystream(key: bytes, iv: bytes, length: int) -> bytes:
+    """生成 HMAC-CTR 模式密钥流
+
+    keystream = HMAC(key, IV || 0) || HMAC(key, IV || 1) || ...
+
+    Args:
+        key: 加密密钥
+        iv: 随机初始化向量（计数器起始值）
+        length: 需要的密钥流长度（字节）
+
+    Returns:
+        指定长度的密钥流
+    """
+    stream = b''
+    counter = 0
+    while len(stream) < length:
+        block = hmac.new(
+            key, iv + struct.pack('>I', counter), hashlib.sha256
+        ).digest()
+        stream += block
+        counter += 1
+    return stream[:length]
+
+
+def encrypt_v3(plaintext: str, derive_key_fn) -> str:
+    """v3 加密: HKDF 密钥分离 + HMAC-CTR + Encrypt-then-MAC
+
+    Args:
+        plaintext: 明文
+        derive_key_fn: 密钥派生函数 (salt) -> master_key
+
+    Returns:
+        ENCv3:<salt_b64>:<iv_b64>:<mac_b64>:<ciphertext_b64>
+    """
+    salt = os.urandom(16)
+    iv = os.urandom(16)
+    master_key = derive_key_fn(salt)
+    enc_key, mac_key = derive_subkeys(master_key, salt)
+
+    data_bytes = plaintext.encode('utf-8')
+
+    # HMAC-CTR 加密
+    keystream = hmac_ctr_keystream(enc_key, iv, len(data_bytes))
+    ciphertext = bytes(a ^ b for a, b in zip(data_bytes, keystream))
+
+    # Encrypt-then-MAC: HMAC 覆盖 salt + iv + ciphertext
+    mac = hmac.new(
+        mac_key, salt + iv + ciphertext, hashlib.sha256
+    ).digest()
+
+    salt_b64 = base64.b64encode(salt).decode('ascii')
+    iv_b64 = base64.b64encode(iv).decode('ascii')
+    mac_b64 = base64.b64encode(mac).decode('ascii')
+    ct_b64 = base64.b64encode(ciphertext).decode('ascii')
+
+    return f"ENCv3:{salt_b64}:{iv_b64}:{mac_b64}:{ct_b64}"
+
+
+def decrypt_v3(encoded: str, derive_key_fn) -> str:
+    """v3 解密: 验证 MAC + HMAC-CTR 解密
+
+    Args:
+        encoded: salt_b64:iv_b64:mac_b64:ciphertext_b64
+        derive_key_fn: 密钥派生函数 (salt) -> master_key
+
+    Returns:
+        解密后的明文
+
+    Raises:
+        DecryptionError: 格式错误或完整性校验失败
+    """
+    parts = encoded.split(':')
+    if len(parts) != 4:
+        raise DecryptionError("Invalid v3 encrypted data format")
+
+    try:
+        salt = base64.b64decode(parts[0])
+        iv = base64.b64decode(parts[1])
+        stored_mac = base64.b64decode(parts[2])
+        ciphertext = base64.b64decode(parts[3])
+    except Exception as e:
+        raise DecryptionError(f"Failed to decode v3 data: {e}")
+
+    master_key = derive_key_fn(salt)
+    enc_key, mac_key = derive_subkeys(master_key, salt)
+
+    # 验证 MAC（常量时间比较）
+    computed_mac = hmac.new(
+        mac_key, salt + iv + ciphertext, hashlib.sha256
+    ).digest()
+    if not hmac.compare_digest(stored_mac, computed_mac):
+        raise DecryptionError(
+            "Data integrity check failed — data may be corrupted or tampered"
+        )
+
+    # HMAC-CTR 解密
+    keystream = hmac_ctr_keystream(enc_key, iv, len(ciphertext))
+    plaintext = bytes(a ^ b for a, b in zip(ciphertext, keystream))
+
+    try:
+        return plaintext.decode('utf-8')
+    except UnicodeDecodeError as e:
+        raise DecryptionError(f"Decrypted data is not valid UTF-8: {e}")
+
+
+__all__ = [
+    'hkdf_expand',
+    'derive_subkeys',
+    'hmac_ctr_keystream',
+    'encrypt_v3',
+    'decrypt_v3',
+]

evm/_groups.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""
+EVM 分组操作 Mixin
+
+从 manager.py 中提取的分组管理功能。
+"""
+
+
+from ._typing import EnvironmentManagerProtocol
+from .exceptions import (
+    GroupNotFoundError,
+    GroupOperationError,
+    KeyAlreadyExistsError,
+    KeyNotFoundError,
+)
+
+
+class GroupMixin(EnvironmentManagerProtocol):
+    """分组操作 mixin — 提供 setg/getg/deleteg/groups 等功能"""
+
+    def set_grouped(
+        self, group: str, key: str, value: str, dry_run: bool = False
+    ) -> str:
+        """设置分组变量"""
+        full_key = f"{group}:{key}" if group else key
+        if dry_run:
+            return f"[DRY-RUN] Would set: [{group}]{key} = {value}"
+        self._env_vars[full_key] = value
+        self._save_env_vars()
+        return f"Set: [{group}]{key} = {value}"
+
+    def get_grouped(self, group: str, key: str) -> str:
+        """获取分组变量
+
+        Raises:
+            KeyNotFoundError: 变量不存在
+        """
+        full_key = f"{group}:{key}" if group else key
+        value = self._env_vars.get(full_key)
+        if value is None and group:
+            value = self._env_vars.get(key)
+        if value is None:
+            raise KeyNotFoundError(full_key)
+        return value
+
+    def delete_grouped(
+        self, group: str, key: str, dry_run: bool = False
+    ) -> str:
+        """删除分组变量
+
+        Raises:
+            KeyNotFoundError: 变量不存在
+        """
+        full_key = f"{group}:{key}" if group else key
+        if full_key not in self._env_vars:
+            raise KeyNotFoundError(full_key)
+        if dry_run:
+            return f"[DRY-RUN] Would delete: [{group}]{key}"
+        del self._env_vars[full_key]
+        self._save_env_vars()
+        return f"Deleted: [{group}]{key}"
+
+    def list_groups(self) -> dict[str, int]:
+        """列出所有分组
+
+        Returns:
+            {group_name: variable_count} 字典
+        """
+        groups: dict[str, int] = {}
+        for key in self._env_vars:
+            if ':' in key:
+                group = key.split(':', 1)[0]
+                groups[group] = groups.get(group, 0) + 1
+        return groups
+
+    def delete_group(self, group: str, dry_run: bool = False) -> str:
+        """删除整个分组
+
+        Raises:
+            GroupOperationError: 尝试删除 default 组
+            GroupNotFoundError: 分组不存在
+        """
+        if group == 'default':
+            raise GroupOperationError(
+                "Cannot delete default namespace. Use 'clear' to remove all variables."
+            )
+
+        prefix = f"{group}:"
+        to_delete = [k for k in self._env_vars if k.startswith(prefix)]
+
+        if not to_delete:
+            raise GroupNotFoundError(group)
+
+        if dry_run:
+            return (
+                f"[DRY-RUN] Would delete group '{group}' "
+                f"and {len(to_delete)} variables"
+            )
+
+        for key in to_delete:
+            del self._env_vars[key]
+        self._save_env_vars()
+        return f"Deleted group '{group}' and all its variables ({len(to_delete)} total)"
+
+    def move_to_group(
+        self, key: str, new_group: str, dry_run: bool = False
+    ) -> str:
+        """移动变量到另一个分组
+
+        Raises:
+            KeyNotFoundError: 变量不存在
+            KeyAlreadyExistsError: 目标分组中已有同名 key
+        """
+        if key not in self._env_vars:
+            raise KeyNotFoundError(key)
+
+        new_key = f"{new_group}:{key}"
+        if new_key in self._env_vars and new_key != key:
+            raise KeyAlreadyExistsError(new_key)
+
+        if dry_run:
+            return f"[DRY-RUN] Would move: {key} -> {new_key}"
+
+        value = self._env_vars.pop(key)
+        self._env_vars[new_key] = value
+        self._save_env_vars()
+        return f"Moved: {key} -> {new_key}"