envtidy 0.2.0__py3-none-any.whl

envtidy/__init__.py

@@ -0,0 +1,3 @@
+"""envtidy — keep your .env files honest."""
+
+__version__ = "0.2.0"

envtidy/cli.py

@@ -0,0 +1,350 @@
+"""envtidy — keep your .env files honest.
+
+Zero-dependency CLI that catches .env drift, generates sanitized
+.env.example files, and finds env files at risk of being committed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+from . import __version__
+
+# ---------------------------------------------------------------------------
+# Terminal colors (respects NO_COLOR and non-tty output)
+# ---------------------------------------------------------------------------
+
+
+def _use_color() -> bool:
+    if os.environ.get("NO_COLOR") is not None:
+        return False
+    if os.environ.get("FORCE_COLOR") is not None:
+        return True
+    return sys.stdout.isatty()
+
+
+class C:
+    enabled = _use_color()
+
+    @classmethod
+    def _wrap(cls, code: str, text: str) -> str:
+        return f"\033[{code}m{text}\033[0m" if cls.enabled else text
+
+    @classmethod
+    def red(cls, t: str) -> str:
+        return cls._wrap("31", t)
+
+    @classmethod
+    def green(cls, t: str) -> str:
+        return cls._wrap("32", t)
+
+    @classmethod
+    def yellow(cls, t: str) -> str:
+        return cls._wrap("33", t)
+
+    @classmethod
+    def cyan(cls, t: str) -> str:
+        return cls._wrap("36", t)
+
+    @classmethod
+    def dim(cls, t: str) -> str:
+        return cls._wrap("2", t)
+
+    @classmethod
+    def bold(cls, t: str) -> str:
+        return cls._wrap("1", t)
+
+
+# ---------------------------------------------------------------------------
+# Dotenv parsing
+# ---------------------------------------------------------------------------
+
+# KEY=VALUE with optional `export ` prefix; permissive on key charset
+_LINE_RE = re.compile(
+    r"""^\s*(?:export\s+)?(?P<key>[A-Za-z_][A-Za-z0-9_.-]*)\s*=\s*(?P<value>.*)$"""
+)
+
+
+def parse_env(path: Path) -> dict[str, str]:
+    """Parse a dotenv file into an ordered {key: raw_value} dict."""
+    entries: dict[str, str] = {}
+    for raw in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        m = _LINE_RE.match(raw)
+        if not m:
+            continue
+        value = m.group("value").strip()
+        # Strip surrounding quotes and trailing unquoted comments
+        if value[:1] in ("'", '"') and value[-1:] == value[:1] and len(value) >= 2:
+            value = value[1:-1]
+        else:
+            value = value.split(" #", 1)[0].rstrip()
+        entries[m.group("key")] = value
+    return entries
+
+
+# ---------------------------------------------------------------------------
+# check — compare .env against .env.example
+# ---------------------------------------------------------------------------
+
+EXAMPLE_SUFFIXES = (".example", ".sample", ".template", ".dist")
+
+
+def find_example(env_path: Path) -> Path | None:
+    for suffix in EXAMPLE_SUFFIXES:
+        candidate = env_path.with_name(env_path.name + suffix)
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    env_path = Path(args.env)
+    if not env_path.is_file():
+        print(f"{C.red('error:')} {env_path} not found", file=sys.stderr)
+        return 2
+
+    example_path = Path(args.example) if args.example else find_example(env_path)
+    if example_path is None or not example_path.is_file():
+        print(
+            f"{C.red('error:')} no example file found next to {env_path} "
+            f"(tried {', '.join(env_path.name + s for s in EXAMPLE_SUFFIXES)})",
+            file=sys.stderr,
+        )
+        return 2
+
+    env = parse_env(env_path)
+    example = parse_env(example_path)
+
+    missing = [k for k in example if k not in env]
+    extra = [k for k in env if k not in example]
+    empty = [k for k, v in env.items() if v == "" and k in example]
+
+    print(C.bold(f"envtidy check  {C.dim(f'{env_path} vs {example_path}')}"))
+    issues = 0
+    for key in missing:
+        issues += 1
+        print(f"  {C.red('missing')}  {key}  {C.dim('(in example, not in env)')}")
+    for key in extra:
+        issues += 1
+        print(f"  {C.yellow('extra')}    {key}  {C.dim('(in env, not in example)')}")
+    for key in empty:
+        issues += 1
+        print(f"  {C.yellow('empty')}    {key}  {C.dim('(declared but has no value)')}")
+
+    if issues == 0:
+        print(f"  {C.green('ok')}       {len(env)} keys in sync")
+        return 0
+    print(
+        f"\n{C.bold(str(issues))} issue{'s' if issues != 1 else ''} found "
+        f"({len(missing)} missing, {len(extra)} extra, {len(empty)} empty)"
+    )
+    if extra and not args.no_hint:
+        print(C.dim("hint: run `envtidy sync` to update the example file"))
+    return 1
+
+
+# ---------------------------------------------------------------------------
+# sync — generate/update a sanitized .env.example from .env
+# ---------------------------------------------------------------------------
+
+
+def sanitize_lines(env_path: Path) -> list[str]:
+    """Rewrite dotenv content with values stripped, preserving structure."""
+    out: list[str] = []
+    for raw in env_path.read_text(encoding="utf-8", errors="replace").splitlines():
+        stripped = raw.strip()
+        if not stripped or stripped.startswith("#"):
+            out.append(raw)
+            continue
+        m = _LINE_RE.match(raw)
+        if m:
+            prefix = "export " if raw.lstrip().startswith("export ") else ""
+            out.append(f"{prefix}{m.group('key')}=")
+        else:
+            out.append(raw)
+    return out
+
+
+def cmd_sync(args: argparse.Namespace) -> int:
+    env_path = Path(args.env)
+    if not env_path.is_file():
+        print(f"{C.red('error:')} {env_path} not found", file=sys.stderr)
+        return 2
+
+    example_path = (
+        Path(args.example)
+        if args.example
+        else (find_example(env_path) or env_path.with_name(env_path.name + ".example"))
+    )
+    content = "\n".join(sanitize_lines(env_path)) + "\n"
+
+    if args.dry_run:
+        sys.stdout.write(content)
+        return 0
+
+    existed = example_path.exists()
+    example_path.write_text(content, encoding="utf-8")
+    verb = "updated" if existed else "created"
+    n_keys = len(parse_env(env_path))
+    print(f"{C.green(verb)} {example_path} ({n_keys} keys, values stripped)")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# scan — find env files at risk of being committed
+# ---------------------------------------------------------------------------
+
+SKIP_DIRS = {
+    ".git", "node_modules", ".venv", "venv", "__pycache__",
+    ".tox", ".mypy_cache", "dist", "build", ".next", "target",
+}
+
+_ENV_NAME_RE = re.compile(r"^\.env(\..+)?$|^.+\.env$")
+
+
+def is_env_file(name: str) -> bool:
+    if any(name.endswith(s) for s in EXAMPLE_SUFFIXES):
+        return False
+    return bool(_ENV_NAME_RE.match(name))
+
+
+def _git(root: Path, *argv: str) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["git", "-C", str(root), *argv],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def env_files_in_history(root: Path) -> set[str]:
+    """Paths (relative to scan root) of env files ever added to git history."""
+    prefix = _git(root, "rev-parse", "--show-prefix").stdout.strip()
+    log = _git(
+        root, "log", "--all", "--diff-filter=A", "--name-only", "--pretty=format:"
+    )
+    if log.returncode != 0:
+        return set()
+    hits: set[str] = set()
+    for line in log.stdout.splitlines():
+        line = line.strip()
+        if not line or not is_env_file(os.path.basename(line)):
+            continue
+        # git log paths are relative to the repo top level; keep only those
+        # under the scan root and re-relativize them to it
+        if prefix:
+            if not line.startswith(prefix):
+                continue
+            line = line[len(prefix):]
+        hits.add(line)
+    return hits
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    root = Path(args.dir).resolve()
+    if not root.is_dir():
+        print(f"{C.red('error:')} {root} is not a directory", file=sys.stderr)
+        return 2
+
+    env_files: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        for name in filenames:
+            if is_env_file(name):
+                env_files.append(Path(dirpath) / name)
+
+    print(C.bold(f"envtidy scan  {C.dim(str(root))}"))
+    in_git = _git(root, "rev-parse", "--is-inside-work-tree").returncode == 0
+    history = env_files_in_history(root) if in_git else set()
+
+    if not env_files and not history:
+        print(f"  {C.green('ok')}       no env files found")
+        return 0
+
+    issues = 0
+    seen: set[str] = set()
+    for path in sorted(env_files):
+        rel = str(path.relative_to(root))
+        seen.add(rel)
+        if not in_git:
+            print(f"  {C.cyan('found')}    {rel}  {C.dim('(not a git repo)')}")
+            continue
+        tracked = _git(root, "ls-files", "--error-unmatch", rel).returncode == 0
+        if tracked:
+            issues += 1
+            print(f"  {C.red('TRACKED')}  {rel}  {C.dim('(committed to git — rotate these secrets)')}")
+            continue
+        if rel in history:
+            issues += 1
+            print(f"  {C.red('HISTORY')}  {rel}  {C.dim('(untracked now, but still in git history — rotate + scrub)')}")
+            continue
+        ignored = _git(root, "check-ignore", "-q", rel).returncode == 0
+        if ignored:
+            print(f"  {C.green('ignored')}  {rel}")
+        else:
+            issues += 1
+            print(f"  {C.yellow('exposed')}  {rel}  {C.dim('(not in .gitignore — one `git add .` from leaking)')}")
+
+    # env files deleted from the working tree but still recoverable from history
+    for rel in sorted(history - seen):
+        if _git(root, "ls-files", "--error-unmatch", rel).returncode == 0:
+            continue  # currently tracked under a path outside the walk (skipped dir)
+        issues += 1
+        print(f"  {C.red('HISTORY')}  {rel}  {C.dim('(deleted, but still in git history — rotate + scrub)')}")
+
+    if issues:
+        print(f"\n{C.bold(str(issues))} file{'s' if issues != 1 else ''} at risk")
+        if any(rel in history for rel in seen) or history - seen:
+            print(C.dim("hint: scrub history with `git filter-repo --sensitive-data-removal --invert-paths --path <file>`"))
+        return 1
+    print(f"\n{C.green('all clear')} — every env file is gitignored and absent from git history")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# entry point
+# ---------------------------------------------------------------------------
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="envtidy",
+        description="Keep your .env files honest: catch drift, sync examples, find leaks.",
+    )
+    parser.add_argument("--version", action="version", version=f"envtidy {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_check = sub.add_parser("check", help="compare .env against .env.example")
+    p_check.add_argument("env", nargs="?", default=".env", help="env file (default: .env)")
+    p_check.add_argument("--example", help="example file (default: auto-detect)")
+    p_check.add_argument("--no-hint", action="store_true", help=argparse.SUPPRESS)
+    p_check.set_defaults(func=cmd_check)
+
+    p_sync = sub.add_parser("sync", help="generate .env.example from .env (values stripped)")
+    p_sync.add_argument("env", nargs="?", default=".env", help="env file (default: .env)")
+    p_sync.add_argument("--example", help="output file (default: <env>.example)")
+    p_sync.add_argument("--dry-run", action="store_true", help="print result instead of writing")
+    p_sync.set_defaults(func=cmd_sync)
+
+    p_scan = sub.add_parser("scan", help="find env files at risk of being committed")
+    p_scan.add_argument("dir", nargs="?", default=".", help="directory to scan (default: .)")
+    p_scan.set_defaults(func=cmd_scan)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

envtidy-0.2.0.dist-info/METADATA

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: envtidy
+Version: 0.2.0
+Summary: Keep your .env files honest: catch drift, sync examples, find leaks. Zero dependencies.
+Author: Nidhi Sebastian
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nidhisebastian008/envtidy
+Project-URL: Issues, https://github.com/nidhisebastian008/envtidy/issues
+Keywords: dotenv,env,environment-variables,cli,devtools,secrets
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# envtidy
+
+> Keep your `.env` files honest — catch drift, sync examples, find leaks.
+
+![zero dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen)
+![python](https://img.shields.io/badge/python-3.9%2B-blue)
+![license](https://img.shields.io/badge/license-MIT-lightgrey)
+
+Every team has lived this bug: someone adds `REDIS_URL` to their local `.env`, forgets to update `.env.example`, and the next person to clone the repo burns an hour debugging a crash that was really just a missing variable. Or worse — someone's `staging.env` was never gitignored and ships to GitHub with live credentials inside.
+
+**envtidy** is a tiny CLI that catches both. Pure Python stdlib, zero dependencies, single-purpose.
+
+![envtidy demo](demo.svg)
+
+## Install
+
+```bash
+pipx install git+https://github.com/nidhisebastian008/envtidy
+# or
+pip install git+https://github.com/nidhisebastian008/envtidy
+```
+
+## Usage
+
+### `envtidy check` — catch drift
+
+Compares `.env` against `.env.example` (also auto-detects `.sample`, `.template`, `.dist`):
+
+```
+$ envtidy check
+envtidy check  .env vs .env.example
+  missing  REDIS_URL  (in example, not in env)
+  extra    DEBUG  (in env, not in example)
+  empty    SMTP_HOST  (declared but has no value)
+
+3 issues found (1 missing, 1 extra, 1 empty)
+```
+
+Exits `1` when drift is found, `0` when clean — drop it straight into CI or a pre-commit hook:
+
+```yaml
+# .pre-commit-config.yaml
+- repo: local
+  hooks:
+    - id: envtidy
+      name: envtidy check
+      entry: envtidy check
+      language: system
+      pass_filenames: false
+```
+
+### `envtidy sync` — regenerate the example file
+
+Rewrites `.env.example` from your real `.env`, stripping every value but preserving comments, blank lines, and key order:
+
+```
+$ envtidy sync
+created .env.example (4 keys, values stripped)
+```
+
+Use `--dry-run` to preview without writing.
+
+### `envtidy scan` — find files that leaked (or are about to)
+
+Walks a directory tree, finds every env file, and checks each one against git — **including the full git history**. Deleting a committed `.env` doesn't remove it; anyone with a clone can still recover it. `scan` catches that:
+
+```
+$ envtidy scan
+envtidy scan  ~/code/myapp
+  ignored  .env
+  exposed  staging.env  (not in .gitignore — one `git add .` from leaking)
+  TRACKED  api/.env.production  (committed to git — rotate these secrets)
+  HISTORY  old/.env.local  (deleted, but still in git history — rotate + scrub)
+
+3 files at risk
+hint: scrub history with `git filter-repo --sensitive-data-removal --invert-paths --path <file>`
+```
+
+- **ignored** — safely gitignored, never committed ✅
+- **exposed** — exists but *not* gitignored; one `git add .` away from a leak
+- **TRACKED** — committed right now; treat those secrets as compromised and rotate them
+- **HISTORY** — not in the working tree or index anymore, but recoverable from git history; rotate the secrets *and* scrub the history
+
+## Alternatives
+
+Prior art exists — pick the right tool for your job:
+
+- [dotenv-linter](https://github.com/dotenv-linter/dotenv-linter) — fast Rust linter for `.env` *style* (duplicate keys, ordering, quoting), with a `compare` command for key diffs. No git awareness, no example generation.
+- [sync-dotenv](https://github.com/luqmanoop/sync-dotenv) — Node tool doing what `envtidy sync` does.
+- [gitleaks](https://github.com/gitleaks/gitleaks) / trufflehog / detect-secrets — heavyweight *content-level* secret scanners with rules and entropy checks. Use them for full audits; use `envtidy scan` for the quick file-level answer to "are my env files safe in this repo?"
+
+envtidy's niche: all three jobs (drift check, example sync, git-aware leak scan) in one zero-dependency CLI with no config.
+
+## Details
+
+- Understands `export KEY=value`, quoted values, inline `# comments`
+- Respects [`NO_COLOR`](https://no-color.org/); colors auto-disable when piped
+- Skips `node_modules`, `.venv`, `.git`, build dirs while scanning
+- Exit codes: `0` clean · `1` issues found · `2` usage error
+
+## License
+
+MIT

envtidy-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+envtidy/__init__.py,sha256=j6UBI8eB36OxpRknwzIoC_PMcRDmRG0K1Y7r0mh6Poc,70
+envtidy/cli.py,sha256=wUlxpWuBGWhNrg1k0CvaCII3mkQlMLMpK6ZpLB3jmNg,12281
+envtidy-0.2.0.dist-info/licenses/LICENSE,sha256=BOTIWnyCicrtFp_VI25capTgqjUC8Dup_4kztoeVtHU,1073
+envtidy-0.2.0.dist-info/METADATA,sha256=Pf-idGEhCDEpOVRtFJbW14U1PRE8IUOgIHbEImgaubQ,4826
+envtidy-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+envtidy-0.2.0.dist-info/entry_points.txt,sha256=N4SQkg7wT7m8YPeOQMDkiP0cVk2NB5ayV0GXyz2qfWQ,45
+envtidy-0.2.0.dist-info/top_level.txt,sha256=CHWVGL56RU3gyZKsoqkXWxZWyx9BWX-2wOud-0aBjv4,8
+envtidy-0.2.0.dist-info/RECORD,,

envtidy-0.2.0.dist-info/WHEEL

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

envtidy-0.2.0.dist-info/entry_points.txt

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

envtidy-0.2.0.dist-info/licenses/LICENSE

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

envtidy-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+envtidy