devsnap 0.1.1__py3-none-any.whl

devsnap/__init__.py

@@ -0,0 +1,13 @@
+"""devsnap — snapshot and diff your development environment."""
+
+from .core import Snapshot, collect_snapshot, diff_snapshots, render_diff, render_snapshot
+
+__version__ = "0.1.1"
+__all__ = [
+    "Snapshot",
+    "collect_snapshot",
+    "diff_snapshots",
+    "render_diff",
+    "render_snapshot",
+    "__version__",
+]

devsnap/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

devsnap/cli.py

@@ -0,0 +1,57 @@
+"""Command line interface: ``devsnap snap`` and ``devsnap diff``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .core import Snapshot, collect_snapshot, diff_snapshots, render_diff, render_snapshot
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="devsnap",
+        description="Snapshot and diff your development environment.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    snap = sub.add_parser("snap", help="take a snapshot of this machine")
+    snap.add_argument("-o", "--output", help="write JSON snapshot to this file")
+    snap.add_argument(
+        "--only",
+        help="comma-separated collectors to run (system, python, tools, env)",
+    )
+
+    diff = sub.add_parser("diff", help="compare two snapshot JSON files")
+    diff.add_argument("old", help="older snapshot JSON file")
+    diff.add_argument("new", help="newer snapshot JSON file")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if args.command == "snap":
+        only = [part.strip() for part in args.only.split(",")] if args.only else None
+        snapshot = collect_snapshot(only=only)
+        if args.output:
+            Path(args.output).write_text(snapshot.to_json(), encoding="utf-8")
+            print(f"Snapshot written to {args.output}")
+        else:
+            print(render_snapshot(snapshot), end="")
+        return 0
+
+    if args.command == "diff":
+        old = Snapshot.from_json(Path(args.old).read_text(encoding="utf-8"))
+        new = Snapshot.from_json(Path(args.new).read_text(encoding="utf-8"))
+        changes = diff_snapshots(old, new)
+        print(render_diff(changes), end="")
+        # Non-zero exit when environments differ, so CI can gate on it.
+        return 1 if changes else 0
+
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

devsnap/collectors/__init__.py

@@ -0,0 +1,16 @@
+"""All collectors, in snapshot display order."""
+
+from .base import Collector
+from .env import EnvCollector
+from .python import PythonCollector
+from .system import SystemCollector
+from .tools import ToolsCollector
+
+ALL_COLLECTORS: list[Collector] = [
+    SystemCollector(),
+    PythonCollector(),
+    ToolsCollector(),
+    EnvCollector(),
+]
+
+__all__ = ["ALL_COLLECTORS", "Collector"]

devsnap/collectors/base.py

@@ -0,0 +1,45 @@
+"""Base class for collectors.
+
+A collector inspects one slice of the development environment (Python,
+Git, Node, Docker, ...) and returns a flat ``{key: value}`` mapping of
+strings. Collectors must never raise: a missing tool is reported as
+``"not found"`` so a snapshot always succeeds on any machine.
+
+Want to add support for a new tool? Copy any existing collector, give it
+a unique ``name``, and register it in ``collectors/__init__.py``.
+See CONTRIBUTING.md — this is the easiest first contribution to devsnap.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+
+class Collector:
+    name: str = "base"
+
+    def collect(self) -> dict[str, str]:
+        raise NotImplementedError
+
+
+def run_version(argv: list[str], timeout: float = 5.0) -> str:
+    """Run a ``--version``-style command and return its first output line.
+
+    Returns ``"not found"`` when the executable is missing and
+    ``"unknown"`` when it exists but produces no usable output.
+    """
+    exe = shutil.which(argv[0])
+    if exe is None:
+        return "not found"
+    try:
+        proc = subprocess.run(
+            argv,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return "unknown"
+    output = (proc.stdout or proc.stderr).strip().splitlines()
+    return output[0].strip() if output else "unknown"

devsnap/collectors/env.py

@@ -0,0 +1,48 @@
+"""Selected environment variables, with secrets masked.
+
+Only a small allow-list of development-relevant variables is captured,
+and any variable whose name looks secret-bearing is masked. Snapshots
+are meant to be pasted into bug reports, so they must be safe to share.
+"""
+
+from __future__ import annotations
+
+import os
+
+from .base import Collector
+
+CAPTURED = [
+    "CI",
+    "EDITOR",
+    "HOME",
+    "LANG",
+    "PATH",
+    "PWD",
+    "SHELL",
+    "TERM",
+    "TZ",
+    "USER",
+    "VIRTUAL_ENV",
+    "CONDA_DEFAULT_ENV",
+    "NODE_ENV",
+    "PYTHONPATH",
+]
+
+SECRET_MARKERS = ("KEY", "TOKEN", "SECRET", "PASSWORD", "PASSWD", "CREDENTIAL")
+
+
+def mask_value(name: str, value: str) -> str:
+    if any(marker in name.upper() for marker in SECRET_MARKERS):
+        return "***masked***"
+    return value
+
+
+class EnvCollector(Collector):
+    name = "env"
+
+    def collect(self) -> dict[str, str]:
+        return {
+            name: mask_value(name, os.environ[name])
+            for name in CAPTURED
+            if name in os.environ
+        }

devsnap/collectors/python.py

@@ -0,0 +1,31 @@
+"""Python interpreter and installed packages."""
+
+from __future__ import annotations
+
+import importlib.metadata
+import platform
+import sys
+
+from .base import Collector
+
+
+class PythonCollector(Collector):
+    name = "python"
+
+    def collect(self) -> dict[str, str]:
+        data = {
+            "version": platform.python_version(),
+            "implementation": platform.python_implementation(),
+            "executable": sys.executable,
+        }
+        try:
+            packages = sorted(
+                f"{dist.metadata['Name']}=={dist.version}"
+                for dist in importlib.metadata.distributions()
+                if dist.metadata.get("Name")
+            )
+        except Exception:  # a snapshot must never fail on a broken env
+            packages = []
+        data["packages_count"] = str(len(packages))
+        data["packages"] = ", ".join(packages)
+        return data

devsnap/collectors/system.py

@@ -0,0 +1,26 @@
+"""Operating system and shell information."""
+
+from __future__ import annotations
+
+import os
+import platform
+
+from .base import Collector
+
+
+class SystemCollector(Collector):
+    name = "system"
+
+    def collect(self) -> dict[str, str]:
+        return {
+            "os": platform.system(),
+            "os_release": platform.release(),
+            "os_version": platform.version(),
+            "machine": platform.machine(),
+            "architecture": platform.architecture()[0] or "unknown",
+            "shell": os.environ.get("SHELL", "unknown"),
+            "terminal": os.environ.get("TERM", "unknown"),
+            "locale": os.environ.get("LANG", "unknown"),
+            "timezone": os.environ.get("TZ", "system default"),
+            "cpu_count": str(os.cpu_count() or "unknown"),
+        }

devsnap/collectors/tools.py

@@ -0,0 +1,35 @@
+"""Versions of common external development tools.
+
+Each tool is one line here. Adding a tool the community uses is a
+welcome contribution — please keep the list alphabetical.
+"""
+
+from __future__ import annotations
+
+from .base import Collector, run_version
+
+# tool name -> argv used to ask it for its version
+TOOLS: dict[str, list[str]] = {
+    "bun": ["bun", "--version"],
+    "cargo": ["cargo", "--version"],
+    "cmake": ["cmake", "--version"],
+    "deno": ["deno", "--version"],
+    "docker": ["docker", "--version"],
+    "git": ["git", "--version"],
+    "go": ["go", "version"],
+    "java": ["java", "--version"],
+    "kubectl": ["kubectl", "version", "--client"],
+    "node": ["node", "--version"],
+    "npm": ["npm", "--version"],
+    "pnpm": ["pnpm", "--version"],
+    "ruby": ["ruby", "--version"],
+    "rustc": ["rustc", "--version"],
+    "yarn": ["yarn", "--version"],
+}
+
+
+class ToolsCollector(Collector):
+    name = "tools"
+
+    def collect(self) -> dict[str, str]:
+        return {name: run_version(argv) for name, argv in sorted(TOOLS.items())}

devsnap/core.py

@@ -0,0 +1,98 @@
+"""Snapshot collection, serialisation and diffing."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+from .collectors import ALL_COLLECTORS
+
+FORMAT_VERSION = 1
+
+
+@dataclass
+class Snapshot:
+    created_at: str
+    sections: dict[str, dict[str, str]] = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return {
+            "format": FORMAT_VERSION,
+            "created_at": self.created_at,
+            "sections": self.sections,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Snapshot":
+        if data.get("format") != FORMAT_VERSION:
+            raise ValueError(f"unsupported snapshot format: {data.get('format')!r}")
+        return cls(created_at=data["created_at"], sections=data["sections"])
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), indent=2, ensure_ascii=False, sort_keys=True)
+
+    @classmethod
+    def from_json(cls, text: str) -> "Snapshot":
+        return cls.from_dict(json.loads(text))
+
+
+def collect_snapshot(only: list[str] | None = None) -> Snapshot:
+    sections: dict[str, dict[str, str]] = {}
+    for collector in ALL_COLLECTORS:
+        if only and collector.name not in only:
+            continue
+        try:
+            sections[collector.name] = collector.collect()
+        except Exception as exc:  # one bad collector must not lose the snapshot
+            sections[collector.name] = {"error": f"{type(exc).__name__}: {exc}"}
+    return Snapshot(
+        created_at=datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        sections=sections,
+    )
+
+
+def diff_snapshots(old: Snapshot, new: Snapshot) -> dict[str, dict[str, tuple[str | None, str | None]]]:
+    """Return ``{section: {key: (old_value, new_value)}}`` for changed keys only.
+
+    ``None`` marks a key that is absent on that side.
+    """
+    diff: dict[str, dict[str, tuple[str | None, str | None]]] = {}
+    for section in sorted(set(old.sections) | set(new.sections)):
+        old_items = old.sections.get(section, {})
+        new_items = new.sections.get(section, {})
+        changes = {}
+        for key in sorted(set(old_items) | set(new_items)):
+            before, after = old_items.get(key), new_items.get(key)
+            if before != after:
+                changes[key] = (before, after)
+        if changes:
+            diff[section] = changes
+    return diff
+
+
+def render_snapshot(snapshot: Snapshot) -> str:
+    lines = [f"devsnap snapshot — {snapshot.created_at}", ""]
+    for section, items in snapshot.sections.items():
+        lines.append(f"[{section}]")
+        for key in sorted(items):
+            lines.append(f"  {key} = {items[key]}")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render_diff(diff: dict) -> str:
+    if not diff:
+        return "No differences.\n"
+    lines = []
+    for section, changes in diff.items():
+        lines.append(f"[{section}]")
+        for key, (before, after) in changes.items():
+            if before is None:
+                lines.append(f"  + {key} = {after}")
+            elif after is None:
+                lines.append(f"  - {key} = {before}")
+            else:
+                lines.append(f"  ~ {key}: {before} -> {after}")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"

devsnap-0.1.1.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: devsnap
+Version: 0.1.1
+Summary: Snapshot and diff your development environment — end 'works on my machine' debugging.
+Author: gptfei
+License: MIT
+Project-URL: Homepage, https://github.com/gptfei/devsnap
+Project-URL: Repository, https://github.com/gptfei/devsnap
+Project-URL: Issues, https://github.com/gptfei/devsnap/issues
+Keywords: environment,snapshot,diff,debugging,devtools,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# devsnap
+
+**Snapshot and diff your development environment — end "works on my machine" debugging.**
+
+`devsnap` is a zero-dependency Python CLI that captures your OS, Python,
+tool versions (git, node, docker, go, rust, ...), installed packages and
+selected environment variables into one shareable JSON snapshot. Secrets
+are masked automatically, so a snapshot is safe to paste into a bug report.
+Diff two snapshots and see exactly what differs between two machines.
+
+## Install
+
+```bash
+pip install devsnap        # once published to PyPI
+# or from source:
+pip install git+https://github.com/gptfei/devsnap
+```
+
+Requires Python 3.9+. No third-party dependencies.
+
+## Usage
+
+```bash
+# Take a snapshot on machine A
+devsnap snap -o machine-a.json
+
+# Take one on machine B, then compare
+devsnap snap -o machine-b.json
+devsnap diff machine-a.json machine-b.json
+```
+
+Example diff output:
+
+```text
+[python]
+  ~ version: 3.11.4 -> 3.12.3
+
+[tools]
+  ~ git: git version 2.40.1 -> git version 2.43.0
+  + docker = Docker version 25.0.3
+```
+
+`devsnap diff` exits with code 1 when environments differ, so CI can gate
+on environment drift. Run `devsnap snap` without `-o` to print a readable
+report instead of JSON.
+
+As a library:
+
+```python
+from devsnap import collect_snapshot, diff_snapshots
+
+mine = collect_snapshot()
+print(mine.to_json())
+```
+
+## Why
+
+"It works on my machine" bugs burn hours because the difference between
+two environments is invisible. Existing answers are heavy (full system
+inventory tools) or manual (copying `pip freeze` output around). devsnap
+is the small middle ground: one command, one file, one diff.
+
+## Contributing
+
+Contributions are welcome — and designed to be easy:
+
+- **Add a tool** to `collectors/tools.py` (one line, alphabetical).
+- **Add a collector** for a stack we miss (Java, .NET, PHP, databases...).
+  Copy any collector in `src/devsnap/collectors/`, see `base.py`.
+- **Report** a machine where a snapshot comes out wrong.
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md), and look for issues labelled
+`good first issue`.
+
+## 中文简介
+
+`devsnap` 是一个零依赖的 Python 命令行工具：一键把操作系统、Python、
+常用工具版本、已装包和（自动打码后的）环境变量拍成一份 JSON 快照，
+可以安全地贴进 issue 里。两份快照一 diff，“在我机器上能跑”的差异
+立刻现形。
+
+## License
+
+MIT — see [LICENSE](LICENSE).

devsnap-0.1.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+devsnap/__init__.py,sha256=WdnkJOVhmkcC-vxSWnDrQRHrTXNZ39Bp1tog8rEKB0w,318
+devsnap/__main__.py,sha256=4JMK66Wj4uLZTKbF-sT3LAxOsr6buig77PmOkJCRRxw,83
+devsnap/cli.py,sha256=V-GP0UYVHDcT2UkepPDQFD0WouZfEbuw77ysseBWqwI,1945
+devsnap/core.py,sha256=oIuVDtgl4bt1r4sqUpgiWjBhYPea5OUyW_zecoSs_k0,3338
+devsnap/collectors/__init__.py,sha256=StU4CkiD_BotZvHRouce5_QEprx-mohMZ3p6QTvUmuk,384
+devsnap/collectors/base.py,sha256=La6FN40hIQKeZ5-ArokTDzBOcxEfYJ_tJul9VoZXJy0,1409
+devsnap/collectors/env.py,sha256=g_W4-Cy9kXrag9pUZ0oZO6nhrpy3Yf7e1vz83yzvS_I,1042
+devsnap/collectors/python.py,sha256=X3lGt7UR1abtv7SJ3i4gLw5mL4Ll2zb-YJ2Fcj4a9Vw,891
+devsnap/collectors/system.py,sha256=F-dL4JZmbPowuvQZWewKy3Y3SAs7GHvkr4Ed3tyRj6w,800
+devsnap/collectors/tools.py,sha256=epfPJtdfHmGZzl2W5zJPhzB2C2iDk8MdJ0Rh4GUncUQ,1061
+devsnap-0.1.1.dist-info/licenses/LICENSE,sha256=Cj0XVFIO6j89kpPNcfpffKbP5HMCbWcewAPMdY8yNVA,1063
+devsnap-0.1.1.dist-info/METADATA,sha256=wizS4uaeYoOTfFgyTuA5hpKrK6VN6zdH0iq6xwufo3U,3178
+devsnap-0.1.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+devsnap-0.1.1.dist-info/entry_points.txt,sha256=wFe1f1Si5xYvhnR3IIpMdjxPNabfEJE8kiORUlnxVgA,45
+devsnap-0.1.1.dist-info/top_level.txt,sha256=sp2eu36GSRXo5zTKAQXk912hvKZyQhqrQxH3eI9epQE,8
+devsnap-0.1.1.dist-info/RECORD,,

devsnap-0.1.1.dist-info/WHEEL

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

devsnap-0.1.1.dist-info/entry_points.txt

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

devsnap-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gptfei
+
+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.

devsnap-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+devsnap