envlock-cli 1.1.0__tar.gz

envlock_cli-1.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,157 @@
+# 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/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_cli-1.1.0/envlock/__main__.py

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

envlock_cli-1.1.0/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()