moles-tools 0.0.1__tar.gz

moles_tools-0.0.1/.gitignore

@@ -0,0 +1,68 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# uv
+.python-version
+
+# Distribution / packaging
+dist/
+
+# Testing
+.pytest_cache/
+.coverage
+coverage.xml
+pytest-coverage.txt
+pytest.xml
+htmlcov/
+
+# Type checking
+.mypy_cache/
+
+# Linting
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Node.js
+node_modules/
+docs/node_modules/
+docs/.vitepress/dist/
+docs/.vitepress/cache/
+.env

moles_tools-0.0.1/LICENSE

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

moles_tools-0.0.1/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: moles-tools
+Version: 0.0.1
+Summary: A collection of Python tools from the underground
+Project-URL: Homepage, https://github.com/the78mole/moles-tools
+Project-URL: Documentation, https://the78mole.github.io/moles-tools
+Project-URL: Repository, https://github.com/the78mole/moles-tools
+Project-URL: Issues, https://github.com/the78mole/moles-tools/issues
+Project-URL: Changelog, https://github.com/the78mole/moles-tools/releases
+Author-email: the78mole <the78mole@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,env,tools,utilities
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# moles-tools
+
+[![CI/CD](https://github.com/the78mole/moles-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/the78mole/moles-tools/actions/workflows/ci.yml)
+[![Documentation](https://github.com/the78mole/moles-tools/actions/workflows/docs.yml/badge.svg)](https://the78mole.github.io/moles-tools)
+[![PyPI version](https://badge.fury.io/py/moles-tools.svg)](https://badge.fury.io/py/moles-tools)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A collection of Python tools from the underground. 🐾
+
+📖 **[Full Documentation](https://the78mole.github.io/moles-tools)**
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| [`env-updater`](https://the78mole.github.io/moles-tools/tools/env-updater) | Update ENV variables in a target file from a source file |
+
+## Quick Start
+
+```bash
+# Install from PyPI
+pip install moles-tools
+
+# Or with uv
+uv add moles-tools
+
+# Update .env from .env.production
+env-updater .env.production .env
+```
+
+## Development
+
+```bash
+# Install uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Clone and set up
+git clone https://github.com/the78mole/moles-tools.git
+cd moles-tools
+
+# Install all dependencies
+uv sync --all-extras
+
+# Install pre-commit hooks
+uv run pre-commit install
+
+# Run tests
+uv run pytest
+```
+
+## License
+
+[MIT](LICENSE)

moles_tools-0.0.1/README.md

@@ -0,0 +1,54 @@
+# moles-tools
+
+[![CI/CD](https://github.com/the78mole/moles-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/the78mole/moles-tools/actions/workflows/ci.yml)
+[![Documentation](https://github.com/the78mole/moles-tools/actions/workflows/docs.yml/badge.svg)](https://the78mole.github.io/moles-tools)
+[![PyPI version](https://badge.fury.io/py/moles-tools.svg)](https://badge.fury.io/py/moles-tools)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A collection of Python tools from the underground. 🐾
+
+📖 **[Full Documentation](https://the78mole.github.io/moles-tools)**
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| [`env-updater`](https://the78mole.github.io/moles-tools/tools/env-updater) | Update ENV variables in a target file from a source file |
+
+## Quick Start
+
+```bash
+# Install from PyPI
+pip install moles-tools
+
+# Or with uv
+uv add moles-tools
+
+# Update .env from .env.production
+env-updater .env.production .env
+```
+
+## Development
+
+```bash
+# Install uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Clone and set up
+git clone https://github.com/the78mole/moles-tools.git
+cd moles-tools
+
+# Install all dependencies
+uv sync --all-extras
+
+# Install pre-commit hooks
+uv run pre-commit install
+
+# Run tests
+uv run pytest
+```
+
+## License
+
+[MIT](LICENSE)

moles_tools-0.0.1/pyproject.toml

@@ -0,0 +1,99 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "moles-tools"
+version = "0.0.1"
+description = "A collection of Python tools from the underground"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "the78mole", email = "the78mole@users.noreply.github.com" }]
+keywords = ["tools", "env", "utilities", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "black>=24.0",
+    "ruff>=0.4.0",
+    "mypy>=1.10",
+    "pre-commit>=3.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/the78mole/moles-tools"
+Documentation = "https://the78mole.github.io/moles-tools"
+Repository = "https://github.com/the78mole/moles-tools"
+Issues = "https://github.com/the78mole/moles-tools/issues"
+Changelog = "https://github.com/the78mole/moles-tools/releases"
+
+[project.scripts]
+env-updater = "moles_tools.env_updater:main"
+moles-tools = "moles_tools.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/moles_tools"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/README.md", "/LICENSE"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "black>=24.0",
+    "ruff>=0.4.0",
+    "mypy>=1.10",
+    "pre-commit>=3.7",
+]
+
+[tool.black]
+line-length = 88
+target-version = ["py311", "py312"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "B", "UP"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["moles_tools"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --cov=moles_tools --cov-report=term-missing --cov-report=xml"
+
+[tool.coverage.run]
+source = ["src/moles_tools"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 80
+
+[tool.bandit]
+exclude_dirs = ["tests"]
+skips = []

moles_tools-0.0.1/src/moles_tools/__init__.py

@@ -0,0 +1,9 @@
+"""moles-tools: A collection of Python tools from the underground."""
+
+__version__ = "0.1.0"
+__author__ = "the78mole"
+__license__ = "MIT"
+
+from moles_tools.env_updater import update_env_file
+
+__all__ = ["update_env_file"]

moles_tools-0.0.1/src/moles_tools/__main__.py

@@ -0,0 +1,20 @@
+"""CLI entry point for moles-tools."""
+
+import sys
+
+
+def main() -> None:
+    """Show available tools when moles-tools is called directly."""
+    tools = {
+        "env-updater": "Update ENV variables in a target file from a source file",
+    }
+    print("moles-tools - A collection of Python tools from the underground\n")
+    print("Available tools:")
+    for name, description in tools.items():
+        print(f"  {name:<20} {description}")
+    print("\nRun 'env-updater --help' for usage information.")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

moles_tools-0.0.1/src/moles_tools/env_updater.py

@@ -0,0 +1,302 @@
+"""ENV File Updater: Updates ENV variables in a target file from a source file.
+
+This tool reads all ENV variables from a source file and updates the
+corresponding variables in a target file. Variables that exist in the source
+but not in the target are appended at the end of the target file. Comments
+and blank lines in the target file are preserved.
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+
+def parse_env_file(file_path: str | Path) -> dict[str, str]:
+    """Parse an ENV file and return a dict of key-value pairs.
+
+    Skips comments (lines starting with '#') and blank lines.
+    Handles values containing '=' characters correctly.
+
+    Args:
+        file_path: Path to the ENV file to parse.
+
+    Returns:
+        Dictionary mapping variable names to their values.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        ValueError: If a non-comment, non-blank line lacks an '=' separator.
+    """
+    variables: dict[str, str] = {}
+    path = Path(file_path)
+
+    with path.open("r", encoding="utf-8") as fh:
+        for lineno, raw_line in enumerate(fh, start=1):
+            line = raw_line.rstrip("\n")
+            stripped = line.strip()
+
+            # Skip blank lines and comment lines
+            if not stripped or stripped.startswith("#"):
+                continue
+
+            if "=" not in line:
+                raise ValueError(
+                    f"{file_path}:{lineno}: Line has no '=' separator: {line!r}"
+                )
+
+            key, _, value = line.partition("=")
+            variables[key.strip()] = value
+
+    return variables
+
+
+def update_env_file(
+    source_path: str | Path,
+    target_path: str | Path,
+    *,
+    create_target: bool = True,
+) -> tuple[int, int]:
+    """Update ENV variables in *target_path* with values from *source_path*.
+
+    For each KEY=VALUE entry in the source file:
+    - If KEY already exists in the target, its value is updated in place.
+    - If KEY does not exist in the target, it is appended at the end.
+    Comments and blank lines in the target are preserved unchanged.
+
+    Args:
+        source_path: Path to the source ENV file (read-only).
+        target_path: Path to the target ENV file to update.
+        create_target: If True and *target_path* does not exist, it is created.
+            If False and *target_path* does not exist, FileNotFoundError is
+            raised.
+
+    Returns:
+        A tuple ``(updated, added)`` with the count of variables that were
+        updated in place and the count of new variables appended.
+
+    Raises:
+        FileNotFoundError: If *source_path* does not exist, or if
+            *target_path* does not exist and *create_target* is False.
+    """
+    source = Path(source_path)
+    target = Path(target_path)
+
+    if not source.exists():
+        raise FileNotFoundError(f"Source file not found: {source}")
+
+    if not target.exists() and not create_target:
+        raise FileNotFoundError(f"Target file not found: {target}")
+
+    source_vars = parse_env_file(source)
+
+    # Read the existing target lines (if any) --------------------------------
+    target_lines: list[str] = []
+    if target.exists():
+        with target.open("r", encoding="utf-8") as fh:
+            target_lines = [line.rstrip("\n") for line in fh]
+
+    # Update existing keys in-place ------------------------------------------
+    updated = 0
+    found_keys: set[str] = set()
+
+    for idx, line in enumerate(target_lines):
+        stripped = line.strip()
+        if stripped.startswith("#") or not stripped or "=" not in line:
+            continue
+
+        key, _, _ = line.partition("=")
+        key = key.strip()
+        found_keys.add(key)
+
+        if key in source_vars:
+            new_line = f"{key}={source_vars[key]}"
+            if new_line != line:
+                target_lines[idx] = new_line
+                updated += 1
+
+    # Append new keys --------------------------------------------------------
+    added = 0
+    new_lines: list[str] = []
+    for key, value in source_vars.items():
+        if key not in found_keys:
+            new_lines.append(f"{key}={value}")
+            added += 1
+
+    if new_lines:
+        # Add a blank separator line if the target is non-empty and does not
+        # already end with a blank line.
+        if target_lines and target_lines[-1].strip():
+            target_lines.append("")
+        target_lines.extend(new_lines)
+
+    # Write the result -------------------------------------------------------
+    content = "\n".join(target_lines)
+    if content and not content.endswith("\n"):
+        content += "\n"
+
+    with target.open("w", encoding="utf-8") as fh:
+        fh.write(content)
+
+    return updated, added
+
+
+def find_example_env(cwd: Path) -> Path | None:
+    """Find `.env.example` or `env.example` in *cwd*.
+
+    Args:
+        cwd: Directory to search in.
+
+    Returns:
+        Path to the first found example file, or None if neither exists.
+    """
+    for name in (".env.example", "env.example"):
+        candidate = cwd / name
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="env-updater",
+        description=(
+            "Update ENV variables in TARGET from UPDATE.\n\n"
+            "When TARGET is omitted the tool auto-detects the target:\n"
+            "  1. .env exists            → update .env with UPDATE\n"
+            "  2. .env missing, .env.example/.env found → create .env from\n"
+            "     example, then apply UPDATE\n"
+            "  3. No UPDATE given, .env missing → copy .env.example / env.example\n"
+            "     to .env\n"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "update",
+        metavar="UPDATE",
+        nargs="?",
+        default=None,
+        help="ENV file whose values take precedence (optional).",
+    )
+    parser.add_argument(
+        "target",
+        metavar="TARGET",
+        nargs="?",
+        default=None,
+        help=(
+            "Target ENV file to update in-place. "
+            "Auto-detected from the current directory when omitted."
+        ),
+    )
+    parser.add_argument(
+        "--no-create",
+        dest="create_target",
+        action="store_false",
+        default=True,
+        help="Fail if TARGET does not exist instead of creating it.",
+    )
+    parser.add_argument(
+        "--quiet",
+        "-q",
+        action="store_true",
+        default=False,
+        help="Suppress informational output.",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point for the env-updater tool.
+
+    Args:
+        argv: Argument list (defaults to sys.argv[1:]).
+
+    Returns:
+        Exit code (0 on success, non-zero on error).
+    """
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    cwd = Path.cwd()
+    update_path: Path | None = Path(args.update) if args.update else None
+    target_path: Path
+    copied_example_name: str | None = None
+
+    if args.target is not None:
+        target_path = Path(args.target)
+    else:
+        # Auto-detect target in the current working directory
+        dot_env = cwd / ".env"
+        example = find_example_env(cwd)
+
+        if update_path is not None:
+            if dot_env.exists():
+                # Case 1: .env exists → update it
+                target_path = dot_env
+            elif example is not None:
+                # Case 2: no .env, but example → copy then apply update
+                shutil.copy2(example, dot_env)
+                copied_example_name = example.name
+                target_path = dot_env
+            else:
+                print(
+                    "Error: No .env, .env.example or env.example found "
+                    "in the current directory.",
+                    file=sys.stderr,
+                )
+                return 1
+        else:
+            # Case 3: no update file — just copy example → .env
+            if not dot_env.exists() and example is not None:
+                shutil.copy2(example, dot_env)
+                if not args.quiet:
+                    print(f"env-updater: Created .env from {example.name}")
+                return 0
+            elif dot_env.exists():
+                if not args.quiet:
+                    print("env-updater: .env already exists, nothing to do.")
+                return 0
+            else:
+                print(
+                    "Error: No .env, .env.example or env.example found "
+                    "in the current directory.",
+                    file=sys.stderr,
+                )
+                return 1
+
+    if update_path is None:
+        print("Error: No UPDATE file specified.", file=sys.stderr)
+        return 1
+
+    try:
+        updated, added = update_env_file(
+            update_path,
+            target_path,
+            create_target=args.create_target,
+        )
+    except FileNotFoundError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+    except ValueError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+    if not args.quiet:
+        if copied_example_name:
+            print(
+                f"env-updater: Created .env from {copied_example_name}, "
+                f"then {updated} variable(s) updated, {added} variable(s) added."
+            )
+        else:
+            print(
+                f"env-updater: {target_path.name} — "
+                f"{updated} variable(s) updated, {added} variable(s) added."
+            )
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

moles_tools-0.0.1/tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for moles_tools package."""

moles_tools-0.0.1/tests/files/env.example

@@ -0,0 +1,16 @@
+# Application settings
+APP_NAME=MyApp
+APP_ENV=production
+APP_DEBUG=false
+APP_PORT=443
+
+# Database
+DB_HOST=db.internal.example.com
+DB_PORT=5432
+DB_NAME=myapp_prod
+DB_USER=prod_user
+DB_PASSWORD=super_secret_prod_password
+
+# Secret keys
+SECRET_KEY=v3rY$tr0ngS3cr3t!
+API_KEY=prod-api-key-abc123xyz

moles_tools-0.0.1/tests/files/env.update

@@ -0,0 +1,5 @@
+# Application settings
+
+APP_PORT=8080
+
+JUST_A_NEW_KEY=DIDNOTEXIST

moles_tools-0.0.1/tests/test_env_updater.py

@@ -0,0 +1,423 @@
+"""Tests for the ENV File Updater tool."""
+
+from __future__ import annotations
+
+import textwrap
+from pathlib import Path
+
+import pytest
+
+from moles_tools.env_updater import (
+    find_example_env,
+    main,
+    parse_env_file,
+    update_env_file,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def write_env(path: Path, content: str) -> None:
+    """Write *content* (dedented) to *path*."""
+    path.write_text(textwrap.dedent(content), encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# parse_env_file
+# ---------------------------------------------------------------------------
+
+
+class TestParseEnvFile:
+    def test_basic_key_value(self, tmp_path: Path) -> None:
+        f = tmp_path / ".env"
+        write_env(f, "FOO=bar\nBAZ=qux\n")
+        result = parse_env_file(f)
+        assert result == {"FOO": "bar", "BAZ": "qux"}
+
+    def test_skips_comments(self, tmp_path: Path) -> None:
+        f = tmp_path / ".env"
+        write_env(f, "# This is a comment\nFOO=bar\n")
+        result = parse_env_file(f)
+        assert result == {"FOO": "bar"}
+        assert len(result) == 1
+
+    def test_skips_blank_lines(self, tmp_path: Path) -> None:
+        f = tmp_path / ".env"
+        write_env(f, "\nFOO=bar\n\nBAZ=qux\n")
+        result = parse_env_file(f)
+        assert result == {"FOO": "bar", "BAZ": "qux"}
+
+    def test_value_containing_equals(self, tmp_path: Path) -> None:
+        f = tmp_path / ".env"
+        write_env(f, "URL=http://example.com?a=1&b=2\n")
+        result = parse_env_file(f)
+        assert result == {"URL": "http://example.com?a=1&b=2"}
+
+    def test_empty_value(self, tmp_path: Path) -> None:
+        f = tmp_path / ".env"
+        write_env(f, "EMPTY=\n")
+        result = parse_env_file(f)
+        assert result == {"EMPTY": ""}
+
+    def test_file_not_found(self, tmp_path: Path) -> None:
+        with pytest.raises(FileNotFoundError):
+            parse_env_file(tmp_path / "nonexistent.env")
+
+    def test_line_without_equals_raises(self, tmp_path: Path) -> None:
+        f = tmp_path / ".env"
+        write_env(f, "NODIVIDER\n")
+        with pytest.raises(ValueError, match="no '=' separator"):
+            parse_env_file(f)
+
+    def test_empty_file(self, tmp_path: Path) -> None:
+        f = tmp_path / ".env"
+        f.write_text("", encoding="utf-8")
+        assert parse_env_file(f) == {}
+
+
+# ---------------------------------------------------------------------------
+# update_env_file — happy paths
+# ---------------------------------------------------------------------------
+
+
+class TestUpdateEnvFileUpdates:
+    def test_updates_existing_variable(self, tmp_path: Path) -> None:
+        source = tmp_path / "source.env"
+        target = tmp_path / "target.env"
+        write_env(source, "FOO=new_value\n")
+        write_env(target, "FOO=old_value\n")
+
+        updated, added = update_env_file(source, target)
+
+        assert updated == 1
+        assert added == 0
+        lines = target.read_text().splitlines()
+        assert "FOO=new_value" in lines
+
+    def test_adds_missing_variable(self, tmp_path: Path) -> None:
+        source = tmp_path / "source.env"
+        target = tmp_path / "target.env"
+        write_env(source, "NEW_VAR=hello\n")
+        write_env(target, "EXISTING=value\n")
+
+        updated, added = update_env_file(source, target)
+
+        assert updated == 0
+        assert added == 1
+        content = target.read_text()
+        assert "NEW_VAR=hello" in content
+        assert "EXISTING=value" in content
+
+    def test_updates_and_adds(self, tmp_path: Path) -> None:
+        source = tmp_path / "source.env"
+        target = tmp_path / "target.env"
+        write_env(source, "EXISTING=updated\nNEW=brand_new\n")
+        write_env(target, "EXISTING=old\n")
+
+        updated, added = update_env_file(source, target)
+
+        assert updated == 1
+        assert added == 1
+
+    def test_preserves_comments(self, tmp_path: Path) -> None:
+        source = tmp_path / "source.env"
+        target = tmp_path / "target.env"
+        write_env(source, "FOO=new\n")
+        write_env(target, "# My comment\nFOO=old\n")
+
+        update_env_file(source, target)
+
+        content = target.read_text()
+        assert "# My comment" in content
+        assert "FOO=new" in content
+
+    def test_preserves_blank_lines(self, tmp_path: Path) -> None:
+        source = tmp_path / "source.env"
+        target = tmp_path / "target.env"
+        write_env(source, "BAR=new\n")
+        write_env(target, "FOO=keep\n\nBAR=old\n")
+
+        update_env_file(source, target)
+
+        lines = target.read_text().splitlines()
+        assert "" in lines  # blank line preserved
+
+    def test_creates_target_when_missing(self, tmp_path: Path) -> None:
+        source = tmp_path / "source.env"
+        target = tmp_path / "new_target.env"
+        write_env(source, "A=1\nB=2\n")
+
+        assert not target.exists()
+        updated, added = update_env_file(source, target)
+
+        assert target.exists()
+        assert updated == 0
+        assert added == 2
+
+    def test_no_change_when_values_identical(self, tmp_path: Path) -> None:
+        source = tmp_path / "source.env"
+        target = tmp_path / "target.env"
+        write_env(source, "FOO=same\n")
+        write_env(target, "FOO=same\n")
+
+        updated, added = update_env_file(source, target)
+
+        assert updated == 0
+        assert added == 0
+
+    def test_value_with_equals(self, tmp_path: Path) -> None:
+        source = tmp_path / "source.env"
+        target = tmp_path / "target.env"
+        write_env(source, "URL=https://example.com?a=1&b=2\n")
+        write_env(target, "URL=old\n")
+
+        update_env_file(source, target)
+
+        lines = target.read_text().splitlines()
+        assert "URL=https://example.com?a=1&b=2" in lines
+
+    def test_empty_target_gets_all_source_vars(self, tmp_path: Path) -> None:
+        source = tmp_path / "source.env"
+        target = tmp_path / "target.env"
+        write_env(source, "A=1\nB=2\nC=3\n")
+        target.write_text("", encoding="utf-8")
+
+        updated, added = update_env_file(source, target)
+
+        assert updated == 0
+        assert added == 3
+
+
+# ---------------------------------------------------------------------------
+# update_env_file — error handling
+# ---------------------------------------------------------------------------
+
+
+class TestUpdateEnvFileErrors:
+    def test_source_not_found_raises(self, tmp_path: Path) -> None:
+        source = tmp_path / "missing.env"
+        target = tmp_path / "target.env"
+        target.write_text("", encoding="utf-8")
+
+        with pytest.raises(FileNotFoundError, match="Source file not found"):
+            update_env_file(source, target)
+
+    def test_no_create_raises_when_target_missing(self, tmp_path: Path) -> None:
+        source = tmp_path / "source.env"
+        source.write_text("A=1\n", encoding="utf-8")
+        target = tmp_path / "missing_target.env"
+
+        with pytest.raises(FileNotFoundError, match="Target file not found"):
+            update_env_file(source, target, create_target=False)
+
+
+# ---------------------------------------------------------------------------
+# CLI (main)
+# ---------------------------------------------------------------------------
+
+
+class TestMain:
+    def test_cli_basic(self, tmp_path: Path) -> None:
+        source = tmp_path / "source.env"
+        target = tmp_path / "target.env"
+        write_env(source, "FOO=new\nBAR=added\n")
+        write_env(target, "FOO=old\n")
+
+        rc = main([str(source), str(target)])
+
+        assert rc == 0
+        content = target.read_text()
+        assert "FOO=new" in content
+        assert "BAR=added" in content
+
+    def test_cli_missing_source(self, tmp_path: Path) -> None:
+        rc = main([str(tmp_path / "nope.env"), str(tmp_path / "target.env")])
+        assert rc == 1
+
+    def test_cli_no_create_fails(self, tmp_path: Path) -> None:
+        source = tmp_path / "source.env"
+        source.write_text("A=1\n", encoding="utf-8")
+        target = tmp_path / "nonexistent.env"
+
+        rc = main([str(source), str(target), "--no-create"])
+
+        assert rc == 1
+
+    def test_cli_quiet(
+        self, tmp_path: Path, capsys: pytest.CaptureFixture[str]
+    ) -> None:
+        source = tmp_path / "source.env"
+        target = tmp_path / "target.env"
+        write_env(source, "X=1\n")
+        write_env(target, "X=0\n")
+
+        rc = main([str(source), str(target), "--quiet"])
+
+        assert rc == 0
+        captured = capsys.readouterr()
+        assert captured.out == ""
+
+    def test_cli_creates_target(self, tmp_path: Path) -> None:
+        source = tmp_path / "source.env"
+        target = tmp_path / "new.env"
+        write_env(source, "KEY=val\n")
+
+        rc = main([str(source), str(target)])
+
+        assert rc == 0
+        assert target.exists()
+        assert "KEY=val" in target.read_text()
+
+
+# ---------------------------------------------------------------------------
+# find_example_env
+# ---------------------------------------------------------------------------
+
+
+class TestFindExampleEnv:
+    def test_finds_dot_env_example(self, tmp_path: Path) -> None:
+        (tmp_path / ".env.example").write_text("A=1\n", encoding="utf-8")
+        assert find_example_env(tmp_path) == tmp_path / ".env.example"
+
+    def test_finds_env_example(self, tmp_path: Path) -> None:
+        (tmp_path / "env.example").write_text("A=1\n", encoding="utf-8")
+        assert find_example_env(tmp_path) == tmp_path / "env.example"
+
+    def test_prefers_dot_env_example(self, tmp_path: Path) -> None:
+        (tmp_path / ".env.example").write_text("A=1\n", encoding="utf-8")
+        (tmp_path / "env.example").write_text("A=2\n", encoding="utf-8")
+        assert find_example_env(tmp_path) == tmp_path / ".env.example"
+
+    def test_returns_none_when_not_found(self, tmp_path: Path) -> None:
+        assert find_example_env(tmp_path) is None
+
+
+# ---------------------------------------------------------------------------
+# Auto-detect: main() without explicit TARGET
+# ---------------------------------------------------------------------------
+
+
+class TestAutoDetect:
+    """Tests for the auto-detection logic when TARGET is omitted."""
+
+    def test_case1_updates_existing_dot_env(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Case 1: .env exists → update it with UPDATE file."""
+        monkeypatch.chdir(tmp_path)
+        update = tmp_path / "update.env"
+        dot_env = tmp_path / ".env"
+        write_env(update, "FOO=new\nBAR=added\n")
+        write_env(dot_env, "FOO=old\n")
+
+        rc = main([str(update)])
+
+        assert rc == 0
+        content = dot_env.read_text()
+        assert "FOO=new" in content
+        assert "BAR=added" in content
+
+    def test_case2_creates_dot_env_from_example(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Case 2: no .env, .env.example exists → create .env from it, then apply UPDATE."""
+        monkeypatch.chdir(tmp_path)
+        update = tmp_path / "update.env"
+        example = tmp_path / ".env.example"
+        write_env(update, "SECRET=override\n")
+        write_env(example, "DB=postgres\nSECRET=changeme\n")
+
+        rc = main([str(update)])
+
+        assert rc == 0
+        dot_env = tmp_path / ".env"
+        assert dot_env.exists()
+        content = dot_env.read_text()
+        assert "DB=postgres" in content
+        assert "SECRET=override" in content
+
+    def test_case2_uses_env_example_fallback(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Case 2: env.example (no leading dot) is used as fallback."""
+        monkeypatch.chdir(tmp_path)
+        update = tmp_path / "update.env"
+        (tmp_path / "env.example").write_text("X=1\n", encoding="utf-8")
+        write_env(update, "X=2\n")
+
+        rc = main([str(update)])
+
+        assert rc == 0
+        content = (tmp_path / ".env").read_text()
+        assert "X=2" in content
+
+    def test_case2_no_example_returns_error(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Case 2 failure: no .env and no example → exit 1."""
+        monkeypatch.chdir(tmp_path)
+        update = tmp_path / "update.env"
+        write_env(update, "A=1\n")
+
+        rc = main([str(update)])
+
+        assert rc == 1
+
+    def test_case3_copies_example_to_dot_env(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Case 3: no UPDATE, no .env → copy .env.example to .env."""
+        monkeypatch.chdir(tmp_path)
+        example = tmp_path / ".env.example"
+        write_env(example, "HOST=localhost\nPORT=5432\n")
+
+        rc = main([])
+
+        assert rc == 0
+        dot_env = tmp_path / ".env"
+        assert dot_env.exists()
+        assert dot_env.read_text() == example.read_text()
+
+    def test_case3_dot_env_already_exists_noop(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        """Case 3: .env already exists, nothing to do."""
+        monkeypatch.chdir(tmp_path)
+        dot_env = tmp_path / ".env"
+        write_env(dot_env, "A=1\n")
+
+        rc = main([])
+
+        assert rc == 0
+        captured = capsys.readouterr()
+        assert "nothing to do" in captured.out
+
+    def test_case3_no_example_no_dot_env_returns_error(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Case 3 failure: no .env and no example → exit 1."""
+        monkeypatch.chdir(tmp_path)
+
+        rc = main([])
+
+        assert rc == 1
+
+    def test_case3_quiet_suppresses_output(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        """Case 3 with --quiet suppresses output."""
+        monkeypatch.chdir(tmp_path)
+        write_env(tmp_path / ".env.example", "A=1\n")
+
+        rc = main(["--quiet"])
+
+        assert rc == 0
+        assert capsys.readouterr().out == ""