envlock-cli 1.1.0__py3-none-any.whl

envlock/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "1.1.0"
+
+from .cli import main  # noqa: E402  (after __version__: cli imports it)
+
+__all__ = ["main", "__version__"]

envlock/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

envlock/cli.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""
+envlock — freeze a project's Python/Node/system environment and detect drift.
+
+Exit codes:  0 no drift (at or above --fail-on)   1 drift detected   2 usage or I/O error
+"""
+import argparse
+import sys
+from pathlib import Path
+
+from shellcolorize import Color
+
+from . import __version__
+from .diff import diff_snapshots
+from .renderer import render_json, render_markdown, render_terminal
+from .snapshot import DEFAULT_PATH, EnvSnapshot, take_snapshot
+
+EXIT_OK, EXIT_DRIFT, EXIT_ERROR = 0, 1, 2
+FAIL_LEVELS = {'info': 'INFO', 'warning': 'WARNING', 'critical': 'CRITICAL'}
+
+
+# Progress and errors go to stderr so stdout only carries the report (safe to pipe into jq).
+def _ok(msg):   print(f"  {Color.GREEN}✔{Color.RESET}  {msg}", file=sys.stderr)
+def _step(msg): print(f"  {Color.CYAN}▶{Color.RESET}  {msg}", file=sys.stderr)
+def _err(msg):  print(f"  {Color.RED}✖{Color.RESET}  {msg}", file=sys.stderr)
+
+
+# ── snapshot ──────────────────────────────────────────────────────────────────
+
+def cmd_snapshot(args: argparse.Namespace) -> int:
+    output = Path(args.output) if args.output else DEFAULT_PATH
+    path = Path(args.path)
+    if not path.is_dir():
+        _err(f'Not a directory: {path}')
+        return EXIT_ERROR
+
+    print(f"\n  {Color.CYAN}{Color.BOLD}envlock  ·  snapshot{Color.RESET}\n", file=sys.stderr)
+    _step(f'Scanning environment at {path.resolve()}...')
+    snap = take_snapshot(path=str(path))
+
+    try:
+        snap.save(output)
+    except OSError as e:
+        _err(f'Cannot write {output}: {e.strerror}')
+        return EXIT_ERROR
+
+    py, nd, system = snap.python, snap.node, snap.system
+    n_pkgs = len(py.get('packages', {}).get('pip_installed', {}))
+    print()
+    _ok(f'Baseline saved: {output}')
+    print(f"  Python   : {py.get('python_version') or 'not found'}  "
+          f"({n_pkgs} packages, {py.get('interpreter') or 'no interpreter'})")
+    print(f"  Node     : {nd.get('node_version') or 'not found'}  "
+          f"(files: {', '.join(nd.get('lockfiles', [])) or 'none'})")
+    print(f"  OS       : {system.get('os') or '?'}  [{system.get('arch') or '?'}]")
+    print(f"  Runtimes : {', '.join(system.get('runtimes', {})) or 'none detected'}")
+    print()
+    return EXIT_OK
+
+# ── check / diff ──────────────────────────────────────────────────────────────
+
+def _load(path: Path):
+    try:
+        return EnvSnapshot.load(path)
+    except FileNotFoundError:
+        _err(f'Snapshot not found: {path}')
+    except (OSError, ValueError) as e:
+        _err(f'Cannot read snapshot {path}: {e}')
+    return None
+
+
+def _report(report, args: argparse.Namespace) -> int:
+    fmt = args.format
+    if fmt == 'terminal' and args.output:
+        fmt = 'markdown' if str(args.output).endswith('.md') else 'json'
+
+    if fmt == 'terminal':
+        render_terminal(report)
+    else:
+        text = render_json(report) if fmt == 'json' else render_markdown(report)
+        if args.output:
+            try:
+                Path(args.output).write_text(text + '\n', encoding='utf-8')
+            except OSError as e:
+                _err(f'Cannot write {args.output}: {e.strerror}')
+                return EXIT_ERROR
+            _ok(f'Report saved to {args.output}')
+        else:
+            print(text)
+
+    if args.fail_on == 'never':
+        return EXIT_OK
+    return EXIT_DRIFT if report.has_at_least(FAIL_LEVELS[args.fail_on]) else EXIT_OK
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    baseline_path = Path(args.baseline) if args.baseline else DEFAULT_PATH
+    if not baseline_path.exists():
+        _err(f'Baseline not found: {baseline_path}')
+        _err("Run 'envlock snapshot' first to create one.")
+        return EXIT_ERROR
+    baseline = _load(baseline_path)
+    if baseline is None:
+        return EXIT_ERROR
+
+    _step('Collecting current environment...')
+    current = take_snapshot(path=args.path)
+    return _report(diff_snapshots(baseline, current), args)
+
+
+def cmd_diff(args: argparse.Namespace) -> int:
+    snap_a, snap_b = _load(Path(args.snapshot_a)), _load(Path(args.snapshot_b))
+    if snap_a is None or snap_b is None:
+        return EXIT_ERROR
+    return _report(diff_snapshots(snap_a, snap_b), args)
+
+# ── main ──────────────────────────────────────────────────────────────────────
+
+def _add_report_options(p: argparse.ArgumentParser) -> None:
+    p.add_argument('--format', '-f', choices=['terminal', 'json', 'markdown'], default='terminal',
+                   help='Report format (default: terminal)')
+    p.add_argument('--output', '-o', metavar='FILE',
+                   help='Write the report to FILE (json or markdown; inferred from .md/.json if needed)')
+    p.add_argument('--fail-on', choices=['info', 'warning', 'critical', 'never'], default='info',
+                   help='Lowest severity that makes the exit code 1 (default: info = any change)')
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog='envlock',
+        description='Freeze Python, Node and system environments — detect drift before it breaks your builds.',
+        epilog='exit codes: 0 no drift · 1 drift detected · 2 error',
+    )
+    parser.add_argument('-v', '--version', action='version', version=f'envlock {__version__}')
+    sub = parser.add_subparsers(dest='command', metavar='COMMAND')
+
+    p_snap = sub.add_parser('snapshot', help='Capture the current environment as baseline')
+    p_snap.add_argument('--path', '-p', metavar='DIR', default='.',
+                        help='Project directory to scan (default: current dir)')
+    p_snap.add_argument('--output', '-o', metavar='FILE',
+                        help=f'Output path (default: {DEFAULT_PATH})')
+
+    p_check = sub.add_parser('check', help='Compare the current environment against the baseline')
+    p_check.add_argument('--baseline', '-b', metavar='FILE',
+                         help=f'Baseline to compare against (default: {DEFAULT_PATH})')
+    p_check.add_argument('--path', '-p', metavar='DIR', default='.',
+                         help='Project directory to scan (default: current dir)')
+    _add_report_options(p_check)
+
+    p_diff = sub.add_parser('diff', help='Compare two snapshot files')
+    p_diff.add_argument('snapshot_a', metavar='BASELINE')
+    p_diff.add_argument('snapshot_b', metavar='CURRENT')
+    _add_report_options(p_diff)
+    return parser
+
+
+def main(argv=None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    Color.auto()
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(EXIT_OK)
+
+    dispatch = {'snapshot': cmd_snapshot, 'check': cmd_check, 'diff': cmd_diff}
+    try:
+        sys.exit(dispatch[args.command](args))
+    except KeyboardInterrupt:
+        _err('Interrupted')
+        sys.exit(130)
+
+
+if __name__ == '__main__':
+    main()

envlock/collectors.py

@@ -0,0 +1,221 @@
+"""
+Environment collectors — Python, Node, and system-level dependencies.
+Each collector returns a plain dict ready for JSON serialisation.
+"""
+import json
+import os
+import re
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Dict, Optional
+
+
+def _run(cmd: list, cwd: Optional[str] = None, timeout: int = 60, stderr: bool = False) -> str:
+    """Run a command and return its stdout ('' on any failure). With stderr=True, include stderr."""
+    try:
+        r = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, cwd=cwd)
+    except (OSError, subprocess.TimeoutExpired):
+        return ''
+    return (r.stdout + r.stderr) if stderr else r.stdout
+
+
+def normalize_name(name: str) -> str:
+    """PEP 503 normalisation: 'PyYAML', 'pyyaml', 'py_yaml' → 'pyyaml' / 'py-yaml'."""
+    return re.sub(r'[-_.]+', '-', name).lower()
+
+
+_REQ_RE = re.compile(r'^([A-Za-z0-9][A-Za-z0-9._-]*)\s*(\[[^\]]*\])?\s*([^;]*)')
+
+
+def parse_requirement(line: str) -> Optional[tuple]:
+    """
+    Parse one requirement ('requests[socks]>=2.31 ; python_version>"3.8"  # note')
+    into (normalized_name, spec). Returns None for blank lines, comments and options.
+    """
+    line = line.split(' #', 1)[0].strip()
+    if not line or line.startswith(('#', '-')) or '://' in line:
+        return None
+    m = _REQ_RE.match(line)
+    if not m:
+        return None
+    return normalize_name(m.group(1)), m.group(3).strip()
+
+# ── Python ────────────────────────────────────────────────────────────────────
+
+def find_python(path: str = '.') -> Optional[str]:
+    """
+    The interpreter whose packages describe the project:
+    a virtualenv inside the project, then the active $VIRTUAL_ENV, then python3 on PATH.
+    """
+    candidates = [Path(path) / d / 'bin' / 'python' for d in ('.venv', 'venv', 'env')]
+    if os.environ.get('VIRTUAL_ENV'):
+        candidates.append(Path(os.environ['VIRTUAL_ENV']) / 'bin' / 'python')
+    for c in candidates:
+        if c.is_file() and os.access(c, os.X_OK):
+            return str(c)
+    return shutil.which('python3') or shutil.which('python')
+
+
+def collect_python(path: str = '.') -> Dict:
+    """
+    Python environment of the project at `path`:
+    interpreter + version, installed packages (pip), requirements.txt and pyproject.toml deps.
+    """
+    result: Dict = {'python_version': None, 'interpreter': None, 'venv': None,
+                    'packages': {}, 'lockfiles': []}
+
+    python = find_python(path)
+    if python:
+        result['interpreter'] = python
+        venv = Path(python).parent.parent
+        if (venv / 'pyvenv.cfg').is_file():
+            result['venv'] = str(venv)
+        ver = _run([python, '--version'], stderr=True).strip()
+        if ver:
+            result['python_version'] = ver.split()[-1]
+        out = _run([python, '-m', 'pip', 'list', '--format=json', '--disable-pip-version-check'])
+        try:
+            result['packages']['pip_installed'] = {
+                normalize_name(p['name']): p['version'] for p in json.loads(out)
+            }
+        except (json.JSONDecodeError, KeyError, TypeError):
+            pass
+
+    req = Path(path) / 'requirements.txt'
+    if req.is_file():
+        result['lockfiles'].append('requirements.txt')
+        pkgs = dict(filter(None, (parse_requirement(line)
+                                  for line in req.read_text(errors='replace').splitlines())))
+        if pkgs:
+            result['packages']['requirements_txt'] = pkgs
+
+    ppt = Path(path) / 'pyproject.toml'
+    if ppt.is_file():
+        result['lockfiles'].append('pyproject.toml')
+        try:
+            import tomllib  # Python 3.11+
+        except ImportError:
+            try:
+                import tomli as tomllib
+            except ImportError:
+                tomllib = None
+        if tomllib:
+            try:
+                data = tomllib.loads(ppt.read_text())
+            except (tomllib.TOMLDecodeError, UnicodeDecodeError):
+                data = {}
+            deps = data.get('project', {}).get('dependencies', [])
+            pkgs = dict(filter(None, (parse_requirement(d) for d in deps)))
+            if pkgs:
+                result['packages']['pyproject_deps'] = pkgs
+
+    return result
+
+# ── Node / npm ────────────────────────────────────────────────────────────────
+
+def collect_node(path: str = '.') -> Dict:
+    """
+    Node.js environment: node/npm versions, package.json deps + devDeps,
+    package-lock.json resolved versions and yarn.lock presence.
+    """
+    result: Dict = {'node_version': None, 'npm_version': None, 'packages': {}, 'lockfiles': []}
+
+    ver = _run(['node', '--version']).strip()
+    if ver:
+        result['node_version'] = ver.lstrip('v')
+    ver = _run(['npm', '--version']).strip()
+    if ver:
+        result['npm_version'] = ver
+
+    pkg_json = Path(path) / 'package.json'
+    if pkg_json.is_file():
+        result['lockfiles'].append('package.json')
+        try:
+            data = json.loads(pkg_json.read_text())
+            for key in ('dependencies', 'devDependencies'):
+                if isinstance(data.get(key), dict):
+                    result['packages'][key] = data[key]
+        except json.JSONDecodeError:
+            pass
+
+    lock = Path(path) / 'package-lock.json'
+    if lock.is_file():
+        result['lockfiles'].append('package-lock.json')
+        try:
+            data = json.loads(lock.read_text())
+            locked = {}
+            # lockfileVersion 2/3: "packages" keyed by "node_modules/<name>"
+            for name, info in data.get('packages', {}).items():
+                if name.startswith('node_modules/') and '/node_modules/' not in name:
+                    locked[name[len('node_modules/'):]] = info.get('version', '?')
+            # lockfileVersion 1: nested "dependencies"
+            if not locked:
+                for name, info in data.get('dependencies', {}).items():
+                    locked[name] = info.get('version', '?')
+            if locked:
+                result['packages']['locked'] = locked
+        except json.JSONDecodeError:
+            pass
+
+    if (Path(path) / 'yarn.lock').is_file():
+        result['lockfiles'].append('yarn.lock')
+
+    return result
+
+# ── System ────────────────────────────────────────────────────────────────────
+
+_RUNTIMES = [
+    ('python', ['python3', '--version']),
+    ('node',   ['node', '--version']),
+    ('ruby',   ['ruby', '--version']),
+    ('go',     ['go', 'version']),
+    ('java',   ['java', '-version']),     # prints to stderr
+    ('rustc',  ['rustc', '--version']),
+]
+
+_ENV_KEYS = [
+    'VIRTUAL_ENV', 'CONDA_DEFAULT_ENV', 'NVM_DIR', 'NODE_ENV',
+    'PYTHONPATH', 'GOPATH', 'JAVA_HOME', 'PATH',
+]
+
+
+def collect_system() -> Dict:
+    """OS, architecture, language runtimes and environment variables relevant to reproducibility."""
+    result: Dict = {'os': None, 'arch': None, 'env_vars': {}, 'runtimes': {}}
+
+    try:
+        info = {}
+        for line in Path('/etc/os-release').read_text().splitlines():
+            if '=' in line:
+                k, v = line.split('=', 1)
+                info[k] = v.strip().strip('"')
+        result['os'] = f"{info.get('NAME', '?')} {info.get('VERSION_ID', '')}".strip()
+    except OSError:
+        import platform
+        result['os'] = f"{platform.system()} {platform.release()}".strip() or None
+
+    arch = _run(['uname', '-m']).strip()
+    if arch:
+        result['arch'] = arch
+
+    for name, cmd in _RUNTIMES:
+        out = _run(cmd, stderr=True).strip()
+        if out:
+            result['runtimes'][name] = out.splitlines()[0]
+
+    for k in _ENV_KEYS:
+        v = os.environ.get(k)
+        if v:
+            result['env_vars'][k] = v
+
+    return result
+
+# ── Unified snapshot ──────────────────────────────────────────────────────────
+
+def collect_all(path: str = '.') -> Dict:
+    return {
+        'python': collect_python(path),
+        'node':   collect_node(path),
+        'system': collect_system(),
+    }

envlock/diff.py

@@ -0,0 +1,167 @@
+"""
+Diff two EnvSnapshots and produce a structured drift report.
+
+Severity rules:
+  CRITICAL  Python/Node major.minor change, OS or architecture change
+  WARNING   package removed or downgraded, declared constraint changed,
+            runtime patch change, lockfile removed, env var removed/changed
+  INFO      package added or upgraded, lockfile or env var added
+"""
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from .versions import compare_versions, same_minor
+
+SEVERITIES = ('CRITICAL', 'WARNING', 'INFO')
+
+
+@dataclass
+class Change:
+    section:     str
+    kind:        str       # added | removed | changed
+    severity:    str       # CRITICAL | WARNING | INFO
+    description: str
+    detail:      Optional[str] = None
+
+
+@dataclass
+class EnvDriftReport:
+    baseline_meta: dict
+    current_meta:  dict
+    changes:       List[Change] = field(default_factory=list)
+
+    @property
+    def is_clean(self) -> bool:
+        return not self.changes
+
+    @property
+    def critical(self) -> List[Change]:
+        return [c for c in self.changes if c.severity == 'CRITICAL']
+
+    @property
+    def warnings(self) -> List[Change]:
+        return [c for c in self.changes if c.severity == 'WARNING']
+
+    @property
+    def info(self) -> List[Change]:
+        return [c for c in self.changes if c.severity == 'INFO']
+
+    def has_at_least(self, severity: str) -> bool:
+        """True if any change is as severe as `severity` or more."""
+        rank = SEVERITIES.index(severity)
+        return any(SEVERITIES.index(c.severity) <= rank for c in self.changes)
+
+# ── Per-section diffing ───────────────────────────────────────────────────────
+
+def _diff_runtime(label: str, section: str, a: Optional[str], b: Optional[str],
+                  critical_on_minor: bool) -> List[Change]:
+    if a == b or (not a and not b):
+        return []
+    if a and b:
+        if critical_on_minor and not same_minor(a, b):
+            severity = 'CRITICAL'
+        elif section == 'system.os':
+            severity = 'CRITICAL'
+        else:
+            severity = 'WARNING'
+        return [Change(section, 'changed', severity, f'{label} version changed', f'{a} → {b}')]
+    if b:
+        return [Change(section, 'added', 'INFO', f'{label} detected', b)]
+    return [Change(section, 'removed', 'WARNING', f'{label} no longer detected', f'was {a}')]
+
+
+def _diff_versions(section: str, label: str, a: dict, b: dict) -> List[Change]:
+    """Resolved versions (pip list, package-lock): upgrades are INFO, downgrades WARNING."""
+    changes = []
+    for k in sorted(b.keys() - a.keys()):
+        changes.append(Change(section, 'added', 'INFO', f'{label}: {k} added', b[k] or None))
+    for k in sorted(a.keys() - b.keys()):
+        changes.append(Change(section, 'removed', 'WARNING', f'{label}: {k} removed',
+                              f'was {a[k]}' if a[k] else None))
+    for k in sorted(a.keys() & b.keys()):
+        if a[k] == b[k]:
+            continue
+        order = compare_versions(str(a[k]), str(b[k]))
+        if order is not None and order < 0:
+            changes.append(Change(section, 'changed', 'INFO', f'{label}: {k} upgraded', f'{a[k]} → {b[k]}'))
+        elif order is not None and order > 0:
+            changes.append(Change(section, 'changed', 'WARNING', f'{label}: {k} downgraded', f'{a[k]} → {b[k]}'))
+        else:
+            changes.append(Change(section, 'changed', 'WARNING', f'{label}: {k} version changed',
+                                  f'{a[k]} → {b[k]}'))
+    return changes
+
+
+def _diff_declared(section: str, label: str, a: dict, b: dict) -> List[Change]:
+    """Declared constraints (requirements.txt, pyproject, package.json): any change is a WARNING."""
+    changes = []
+    for k in sorted(b.keys() - a.keys()):
+        changes.append(Change(section, 'added', 'INFO', f'{label}: {k} added', b[k] or None))
+    for k in sorted(a.keys() - b.keys()):
+        changes.append(Change(section, 'removed', 'WARNING', f'{label}: {k} removed',
+                              f'was {a[k]}' if a[k] else None))
+    for k in sorted(a.keys() & b.keys()):
+        if a[k] != b[k]:
+            changes.append(Change(section, 'changed', 'WARNING', f'{label}: {k} constraint changed',
+                                  f'{a[k] or "(any)"} → {b[k] or "(any)"}'))
+    return changes
+
+
+def _diff_list(section: str, label: str, a: list, b: list) -> List[Change]:
+    changes = [Change(section, 'added', 'INFO', f'{label}: {x} added') for x in sorted(set(b) - set(a))]
+    changes += [Change(section, 'removed', 'WARNING', f'{label}: {x} removed') for x in sorted(set(a) - set(b))]
+    return changes
+
+
+def _diff_env_vars(a: dict, b: dict) -> List[Change]:
+    skip = {'PATH'}   # too noisy / session-specific
+    a = {k: v for k, v in a.items() if k not in skip}
+    b = {k: v for k, v in b.items() if k not in skip}
+    changes = [Change('env_vars', 'added', 'INFO', f'Env var added: {k}', b[k]) for k in sorted(b.keys() - a.keys())]
+    changes += [Change('env_vars', 'removed', 'WARNING', f'Env var removed: {k}') for k in sorted(a.keys() - b.keys())]
+    changes += [Change('env_vars', 'changed', 'WARNING', f'Env var changed: {k}', f'{a[k][:60]} → {b[k][:60]}')
+                for k in sorted(a.keys() & b.keys()) if a[k] != b[k]]
+    return changes
+
+# ── Entry point ───────────────────────────────────────────────────────────────
+
+def diff_snapshots(snap_a, snap_b) -> EnvDriftReport:
+    report = EnvDriftReport(baseline_meta=snap_a.meta, current_meta=snap_b.meta)
+    ch = report.changes
+    py_a, py_b = snap_a.python, snap_b.python
+    nd_a, nd_b = snap_a.node, snap_b.node
+    sy_a, sy_b = snap_a.system, snap_b.system
+
+    def pkgs(env: dict, key: str) -> dict:
+        return env.get('packages', {}).get(key, {}) or {}
+
+    # Python
+    ch += _diff_runtime('Python', 'python.runtime', py_a.get('python_version'),
+                        py_b.get('python_version'), critical_on_minor=True)
+    ch += _diff_versions('python.packages', 'pip', pkgs(py_a, 'pip_installed'), pkgs(py_b, 'pip_installed'))
+    ch += _diff_declared('python.packages', 'requirements.txt',
+                         pkgs(py_a, 'requirements_txt'), pkgs(py_b, 'requirements_txt'))
+    ch += _diff_declared('python.packages', 'pyproject',
+                         pkgs(py_a, 'pyproject_deps'), pkgs(py_b, 'pyproject_deps'))
+    ch += _diff_list('lockfiles', 'Python lockfile', py_a.get('lockfiles', []), py_b.get('lockfiles', []))
+
+    # Node
+    ch += _diff_runtime('Node.js', 'node.runtime', nd_a.get('node_version'),
+                        nd_b.get('node_version'), critical_on_minor=True)
+    ch += _diff_declared('node.packages', 'npm dep', pkgs(nd_a, 'dependencies'), pkgs(nd_b, 'dependencies'))
+    ch += _diff_declared('node.packages', 'npm devDep',
+                         pkgs(nd_a, 'devDependencies'), pkgs(nd_b, 'devDependencies'))
+    ch += _diff_versions('node.packages', 'npm locked', pkgs(nd_a, 'locked'), pkgs(nd_b, 'locked'))
+    ch += _diff_list('lockfiles', 'Node lockfile', nd_a.get('lockfiles', []), nd_b.get('lockfiles', []))
+
+    # System (python/node runtimes are already covered above)
+    rt_a, rt_b = sy_a.get('runtimes', {}), sy_b.get('runtimes', {})
+    for name in sorted((rt_a.keys() | rt_b.keys()) - {'python', 'node'}):
+        ch += _diff_runtime(name.capitalize(), 'system.runtime', rt_a.get(name), rt_b.get(name),
+                            critical_on_minor=False)
+    ch += _diff_runtime('OS', 'system.os', sy_a.get('os'), sy_b.get('os'), critical_on_minor=False)
+    ch += _diff_runtime('Architecture', 'system.os', sy_a.get('arch'), sy_b.get('arch'),
+                        critical_on_minor=False)
+    ch += _diff_env_vars(sy_a.get('env_vars', {}), sy_b.get('env_vars', {}))
+
+    return report

envlock/renderer.py

@@ -0,0 +1,180 @@
+"""
+Render an EnvDriftReport to terminal, Markdown, or JSON.
+"""
+import json
+from datetime import datetime
+from shellcolorize import Color
+from .diff import EnvDriftReport, Change
+
+# Attribute names, resolved at render time so Color.auto()/disable() are respected.
+_SEV_COLOR = {
+    'CRITICAL': 'RED',
+    'WARNING':  'YELLOW',
+    'INFO':     'CYAN',
+}
+
+_SEV_ICON = {
+    'CRITICAL': '⛔',
+    'WARNING':  '⚠ ',
+    'INFO':     '·',
+}
+
+_KIND_SYM = {
+    'added':   '+',
+    'removed': '-',
+    'changed': '~',
+}
+
+_SECTIONS = [
+    'python.runtime', 'python.packages',
+    'node.runtime',   'node.packages',
+    'system.os', 'system.runtime', 'lockfiles', 'env_vars',
+]
+
+_SEC_LABEL = {
+    'python.runtime':  'Python Runtime',
+    'python.packages': 'Python Packages',
+    'node.runtime':    'Node.js Runtime',
+    'node.packages':   'Node.js Packages',
+    'system.os':       'Operating System',
+    'system.runtime':  'Other Runtimes',
+    'lockfiles':       'Lockfiles',
+    'env_vars':        'Environment Variables',
+}
+
+
+def _header() -> None:
+    title = 'envlock  ·  environment drift report'
+    w = len(title) + 4
+    print()
+    print(f"  {Color.CYAN}╔{'═' * w}╗{Color.RESET}")
+    print(f"  {Color.CYAN}║{Color.RESET}  {Color.BOLD}{Color.CYAN}{title}{Color.RESET}  {Color.CYAN}║{Color.RESET}")
+    print(f"  {Color.CYAN}╚{'═' * w}╝{Color.RESET}")
+    print()
+
+
+def _meta_line(label: str, meta: dict) -> None:
+    ts   = meta.get('captured_at', '?')
+    host = meta.get('hostname', '?')
+    proj = meta.get('project_path', '?')
+    print(f"  {Color.DIM}{label:<10}{Color.RESET} {ts}  ({host})  {Color.DIM}{proj}{Color.RESET}")
+
+
+def _section(label: str) -> None:
+    print()
+    print(f"  {Color.CYAN}── {label} {'─' * max(0, 42 - len(label))}{Color.RESET}")
+
+
+def _change_line(c: Change) -> None:
+    color  = getattr(Color, _SEV_COLOR.get(c.severity, ''), '')
+    icon   = _SEV_ICON.get(c.severity, ' ')
+    sym    = _KIND_SYM.get(c.kind, ' ')
+    detail = f"  {Color.DIM}{c.detail}{Color.RESET}" if c.detail else ''
+    print(f"  {color}{icon} {sym}  {c.description}{Color.RESET}{detail}")
+
+
+def render_terminal(report: EnvDriftReport) -> None:
+    _header()
+    _meta_line('Baseline', report.baseline_meta)
+    _meta_line('Current',  report.current_meta)
+    print()
+
+    if report.is_clean:
+        print(f"  {Color.GREEN}✔  No drift detected — environment matches baseline.{Color.RESET}")
+        print()
+        return
+
+    by_sec = {}
+    for c in report.changes:
+        by_sec.setdefault(c.section, []).append(c)
+
+    for sec in _SECTIONS:
+        changes = by_sec.get(sec, [])
+        if not changes:
+            continue
+        _section(_SEC_LABEL.get(sec, sec))
+        for c in changes:
+            _change_line(c)
+
+    print()
+    print(f"  {'─' * 44}")
+    total = len(report.changes)
+    crit  = len(report.critical)
+    warn  = len(report.warnings)
+    info  = len(report.info)
+    parts = []
+    if crit: parts.append(f"{Color.RED}{crit} critical{Color.RESET}")
+    if warn: parts.append(f"{Color.YELLOW}{warn} warning{'s' if warn > 1 else ''}{Color.RESET}")
+    if info: parts.append(f"{Color.CYAN}{info} info{Color.RESET}")
+    print(f"  {Color.BOLD}{total} change{'s' if total != 1 else ''} detected{Color.RESET}"
+          + (f"  ({', '.join(parts)})" if parts else ''))
+    print()
+
+
+def render_markdown(report: EnvDriftReport) -> str:
+    lines = []
+    ts_now = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+
+    lines += [
+        "# envlock — Environment Drift Report",
+        "",
+        "| | |",
+        "|---|---|",
+        f"| **Baseline** | {report.baseline_meta.get('captured_at','?')}  ({report.baseline_meta.get('hostname','?')}) |",
+        f"| **Current**  | {report.current_meta.get('captured_at','?')}  ({report.current_meta.get('hostname','?')}) |",
+        f"| **Project**  | {report.current_meta.get('project_path','?')} |",
+        f"| **Generated** | {ts_now} |",
+        f"| **Changes** | {len(report.changes)} ({len(report.critical)} critical, {len(report.warnings)} warnings, {len(report.info)} info) |",
+        "",
+        "---",
+        "",
+    ]
+
+    if report.is_clean:
+        lines += ["## ✅ No drift detected", "", "Environment matches baseline.", ""]
+        return '\n'.join(lines)
+
+    by_sec = {}
+    for c in report.changes:
+        by_sec.setdefault(c.section, []).append(c)
+
+    _icons = {'CRITICAL': '⛔', 'WARNING': '⚠️', 'INFO': 'ℹ️'}
+    _syms  = {'added': '+', 'removed': '−', 'changed': '~'}
+
+    for sec in _SECTIONS:
+        changes = by_sec.get(sec, [])
+        if not changes:
+            continue
+        lines += [f"## {_SEC_LABEL.get(sec, sec)}", ""]
+        for c in changes:
+            icon   = _icons.get(c.severity, '')
+            sym    = _syms.get(c.kind, ' ')
+            detail = f" _{c.detail}_" if c.detail else ''
+            lines.append(f"- {icon} `{sym}` {c.description}{detail}")
+        lines.append("")
+
+    lines += ["---", "", f"*Generated by [envlock](https://github.com/serber1990/envlock) at {ts_now}*"]
+    return '\n'.join(lines)
+
+
+def render_json(report: EnvDriftReport) -> str:
+    return json.dumps({
+        'baseline_meta': report.baseline_meta,
+        'current_meta':  report.current_meta,
+        'summary': {
+            'total':    len(report.changes),
+            'critical': len(report.critical),
+            'warnings': len(report.warnings),
+            'info':     len(report.info),
+        },
+        'changes': [
+            {
+                'section':     c.section,
+                'kind':        c.kind,
+                'severity':    c.severity,
+                'description': c.description,
+                'detail':      c.detail,
+            }
+            for c in report.changes
+        ],
+    }, indent=2)

envlock/snapshot.py

@@ -0,0 +1,58 @@
+"""
+EnvSnapshot — captures, saves, and loads an environment state.
+"""
+import json
+import socket
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import __version__
+from .collectors import collect_all
+
+DEFAULT_PATH = Path('.envlock.json')
+
+
+class EnvSnapshot:
+    def __init__(self, data: dict):
+        if not isinstance(data, dict):
+            raise ValueError('not an envlock snapshot (expected a JSON object)')
+        self._data = data
+
+    @property
+    def meta(self) -> dict:
+        return self._data.get('meta', {})
+
+    @property
+    def python(self) -> dict:
+        return self._data.get('python', {})
+
+    @property
+    def node(self) -> dict:
+        return self._data.get('node', {})
+
+    @property
+    def system(self) -> dict:
+        return self._data.get('system', {})
+
+    def to_dict(self) -> dict:
+        return self._data
+
+    def save(self, path: Path) -> None:
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(self._data, indent=2) + '\n', encoding='utf-8')
+
+    @classmethod
+    def load(cls, path: Path) -> 'EnvSnapshot':
+        return cls(json.loads(Path(path).read_text(encoding='utf-8')))
+
+
+def take_snapshot(path: str = '.') -> EnvSnapshot:
+    env = collect_all(path)
+    env['meta'] = {
+        'captured_at': datetime.now(timezone.utc).isoformat(timespec='seconds'),
+        'hostname': socket.gethostname(),
+        'project_path': str(Path(path).resolve()),
+        'envlock_version': __version__,
+    }
+    return EnvSnapshot(env)

envlock/versions.py

@@ -0,0 +1,49 @@
+"""
+Dependency-free version comparison, good enough for drift reports.
+
+Handles PEP 440-ish ("2.0.0rc1"), semver ("1.2.3-beta.1") and Debian-style
+epochs ("1:2.3-4"). Returns None when a version cannot be interpreted.
+"""
+import re
+from typing import Optional, Tuple
+
+_EPOCH = re.compile(r'^(\d+):')
+_RELEASE = re.compile(r'^[vV]?(\d+(?:\.\d+)*)')
+_PRE = re.compile(r'(?:a|alpha|b|beta|c|rc|pre|preview|dev)\.?\d*$|-(?:alpha|beta|rc|pre|dev)', re.I)
+
+
+def _parse(v: str) -> Optional[Tuple[int, Tuple[int, ...], bool]]:
+    v = v.strip()
+    epoch = 0
+    m = _EPOCH.match(v)
+    if m:
+        epoch, v = int(m.group(1)), v[m.end():]
+    m = _RELEASE.match(v)
+    if not m:
+        return None
+    release = tuple(int(x) for x in m.group(1).split('.'))
+    rest = v[m.end():]
+    return epoch, release, bool(_PRE.search(rest))
+
+
+def compare_versions(a: str, b: str) -> Optional[int]:
+    """-1 if a < b, 0 if equal, 1 if a > b, None if either is not a version."""
+    pa, pb = _parse(a), _parse(b)
+    if pa is None or pb is None:
+        return None
+    (ea, ra, pre_a), (eb, rb, pre_b) = pa, pb
+    width = max(len(ra), len(rb))
+    ra, rb = ra + (0,) * (width - len(ra)), rb + (0,) * (width - len(rb))
+    # A pre-release sorts before its final release: 2.0.0rc1 < 2.0.0.
+    key_a, key_b = (ea, ra, not pre_a), (eb, rb, not pre_b)
+    if key_a == key_b:
+        return 0
+    return 1 if key_a > key_b else -1
+
+
+def same_minor(a: str, b: str) -> bool:
+    """True when both versions share major.minor (3.12.1 vs 3.12.4)."""
+    pa, pb = _parse(a), _parse(b)
+    if pa is None or pb is None:
+        return False
+    return pa[0] == pb[0] and pa[1][:2] == pb[1][:2]

envlock_cli-1.1.0.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: envlock-cli
+Version: 1.1.0
+Summary: Freeze and compare Python, Node, and system environments — detect dependency drift before it breaks your builds.
+Author-email: Serber1990 <serber1990@pm.me>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/serber1990/envlock
+Project-URL: Repository, https://github.com/serber1990/envlock
+Project-URL: Issues, https://github.com/serber1990/envlock/issues
+Project-URL: Changelog, https://github.com/serber1990/envlock/blob/main/CHANGELOG.md
+Keywords: environment,dependencies,drift,reproducibility,devops,ci,python,node
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: shellcolorize>=1.1.0
+Requires-Dist: tomli>=1.1; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# envlock
+
+[![CI](https://github.com/serber1990/envlock/actions/workflows/ci.yml/badge.svg)](https://github.com/serber1990/envlock/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/envlock-cli.svg)](https://badge.fury.io/py/envlock-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Freeze your environment. Detect when it drifts.
+
+**envlock** snapshots a project's Python packages, Node.js dependencies and system runtimes, then tells you
+exactly what changed — so "works on my machine" stops being an excuse. Use it locally, in CI, or to compare
+staging with production.
+
+---
+
+## ✨ What it tracks
+
+| Layer | What's captured |
+|-------|----------------|
+| **Python** | Interpreter and version (the project's `.venv` / `venv` / `env`, or the active virtualenv), installed packages, `requirements.txt`, `pyproject.toml` dependencies |
+| **Node.js** | Node and npm versions, `package.json` dependencies + devDependencies, `package-lock.json` resolved versions, `yarn.lock` presence |
+| **System** | OS, architecture, Go / Ruby / Java / Rust versions, relevant env vars (`VIRTUAL_ENV`, `NODE_ENV`, `JAVA_HOME`…) |
+
+### Severity levels
+
+| Severity | Examples |
+|----------|----------|
+| ⛔ **CRITICAL** | Python/Node major or minor version changed (3.12 → 3.13), OS or architecture changed |
+| ⚠️ **WARNING** | Package removed or downgraded, declared constraint changed, runtime patch release, lockfile or env var removed |
+| ℹ️ **INFO** | Package added or upgraded, new lockfile or env var |
+
+---
+
+## 📥 Installation
+
+```bash
+pip install envlock-cli     # the command is `envlock`
+```
+
+---
+
+## 🛠 Usage
+
+### 1 — Take a baseline snapshot
+
+```bash
+envlock snapshot                          # saves .envlock.json in the current directory
+envlock snapshot --path /srv/myapp        # scan another project
+envlock snapshot --output locks/prod.json # custom location
+```
+
+### 2 — Check for drift
+
+```bash
+envlock check                                        # terminal report
+envlock check --format json | jq .summary            # JSON on stdout (progress goes to stderr)
+envlock check --format markdown -o drift-report.md      # Markdown report file
+envlock check --baseline locks/prod.json --fail-on critical
+```
+
+### 3 — Diff any two snapshots
+
+```bash
+envlock diff staging.json production.json
+envlock diff before.json after.json --format markdown -o drift.md
+```
+
+---
+
+## 📄 Example output
+
+```
+  ╔════════════════════════════════════════╗
+  ║  envlock  ·  environment drift report  ║
+  ╚════════════════════════════════════════╝
+
+  Baseline   2026-05-10T09:00:00+00:00  (dev-laptop)  /srv/app
+  Current    2026-05-12T14:22:18+00:00  (dev-laptop)  /srv/app
+
+
+  ── Python Runtime ────────────────────────────
+  ⛔ ~  Python version changed  3.12.1 → 3.13.0
+
+  ── Python Packages ───────────────────────────
+  · +  pip: httpx added  0.27.0
+  · ~  pip: requests upgraded  2.31.0 → 2.32.3
+  ⚠  ~  pip: urllib3 downgraded  2.0.7 → 1.26.18
+
+  ── Node.js Packages ──────────────────────────
+  · +  npm dep: express added  ^4.19.2
+
+  ────────────────────────────────────────────
+  5 changes detected  (1 critical, 1 warning, 3 info)
+```
+
+---
+
+## 🔁 Use in CI
+
+The exit code tells your pipeline what happened:
+
+| Exit code | Meaning |
+|-----------|---------|
+| `0` | No drift at or above `--fail-on` |
+| `1` | Drift detected |
+| `2` | Error (missing or invalid baseline, unreadable path) |
+
+```yaml
+# GitHub Actions — fail only on critical drift, keep the report as an artifact
+- name: Check environment drift
+  run: envlock check --baseline .envlock.json --fail-on critical --format markdown -o drift-report.md
+- uses: actions/upload-artifact@v4
+  if: always()
+  with:
+    name: drift-report
+    path: drift-report.md
+```
+
+---
+
+## 📋 Options
+
+### `envlock snapshot`
+| Option | Description |
+|--------|-------------|
+| `-p`, `--path DIR` | Project directory to scan (default: `.`) |
+| `-o`, `--output FILE` | Where to save the baseline (default: `.envlock.json`) |
+
+### `envlock check` / `envlock diff BASELINE CURRENT`
+| Option | Description |
+|--------|-------------|
+| `-b`, `--baseline FILE` | *(check)* Baseline to compare against (default: `.envlock.json`) |
+| `-p`, `--path DIR` | *(check)* Project directory to scan (default: `.`) |
+| `-f`, `--format` | `terminal` (default), `json` or `markdown` |
+| `-o`, `--output FILE` | Write the report to a file (JSON or Markdown) |
+| `--fail-on LEVEL` | `info` (default: any change), `warning`, `critical` or `never` |
+
+---
+
+## 🧪 Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+pytest
+```
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes.
+
+---
+
+## 📝 License
+
+MIT — see [LICENSE](LICENSE).
+
+## 🌐 Connect
+
+[![GitHub](https://img.shields.io/badge/GitHub-@serber1990-181717?style=flat-square&logo=github)](https://github.com/serber1990)

envlock_cli-1.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+envlock/__init__.py,sha256=Pufh-jUt1mxJjrQgISobG7cxRKcwXV8xiI7mB_5FcbE,131
+envlock/__main__.py,sha256=bYt9eEaoRQWdejEHFD8REx9jxVEdZptECFsV7F49Ink,30
+envlock/cli.py,sha256=gRkh3IkRFebQkz3Q4mv4DSpRHyTfb7A6sto_ZEcBohQ,7223
+envlock/collectors.py,sha256=Xr1PYyMhgxAF89LXjdPQEEM06nQc4_k-EZyMb5TLP6E,8451
+envlock/diff.py,sha256=Um_ewf8uhk6V8qzXiueb5OW2-0b7jmJ77Fza78QXauk,8011
+envlock/renderer.py,sha256=JordXij8pa0qFIytekUElmpiYGh4v3d9pCRPXfoNhHA,5794
+envlock/snapshot.py,sha256=Fmx_IviwGZue5DIFBF3-RFedL22OxBMWCrp_84Qpliw,1565
+envlock/versions.py,sha256=lJjzaNVt_MjXtJW3J9P38vaAqXCbA4CVMoaAxQBksrU,1667
+envlock_cli-1.1.0.dist-info/licenses/LICENSE,sha256=rOAaRlMktc-uI4u5mxNvBLTLqUvsyujBQMivrLv2olo,1067
+envlock_cli-1.1.0.dist-info/METADATA,sha256=l5LElDH37PatGBJ-sV5zGyJ3SpZE8sNVqA9V7h277PU,6532
+envlock_cli-1.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+envlock_cli-1.1.0.dist-info/entry_points.txt,sha256=P1oKpwy_78znwOZMnF-KeQjC84byhnpOisTFGf8F2Bs,45
+envlock_cli-1.1.0.dist-info/top_level.txt,sha256=0WkvYcSrDn5BGereto7gPP50GErBODo6H6ncBxyA5Ek,8
+envlock_cli-1.1.0.dist-info/RECORD,,

envlock_cli-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

envlock_cli-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+envlock = envlock.cli:main

envlock_cli-1.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Serber1990
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

envlock_cli-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+envlock