ha-deploy-kit 0.1.0__py3-none-any.whl

ha_deploy_kit/ha/serving.py

@@ -0,0 +1,63 @@
+"""Optional hooks to serve a Lovelace card from a custom component.
+
+Each hook probes the installed Home Assistant for the supported API and uses it,
+rather than hard-coding a single call or swallowing unexpected errors blindly.
+Both the legacy and current HA signatures are handled:
+
+- static paths: legacy ``http.register_static_path`` or current
+  ``http.async_register_static_paths`` with ``StaticPathConfig``;
+- extra module URL: legacy ``frontend.add_extra_module_url`` or current
+  ``frontend.add_extra_js_url`` (``es5=False`` registers an ES module).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from homeassistant.core import HomeAssistant
+
+
+def register_card_serving(
+    hass: HomeAssistant,
+    domain: str,
+    lovelace_dir: str,
+    card_url: str,
+) -> None:
+    """Serve ``lovelace_dir`` at ``card_url`` and load it as a frontend module."""
+    _register_static_path(hass, lovelace_dir, card_url)
+    _register_extra_module_url(hass, card_url)
+
+
+def _register_static_path(
+    hass: HomeAssistant, lovelace_dir: str, card_url: str
+) -> None:
+    http = getattr(hass, "http", None)
+    if http is None:
+        return
+
+    register_static = getattr(http, "register_static_path", None)
+    if callable(register_static):
+        register_static(card_url, lovelace_dir, False)
+        return
+
+    async_register = getattr(http, "async_register_static_paths", None)
+    if callable(async_register):
+        from homeassistant.components.http import StaticPathConfig
+
+        hass.async_create_task(
+            async_register([StaticPathConfig(card_url, lovelace_dir, False)])
+        )
+
+
+def _register_extra_module_url(hass: HomeAssistant, card_url: str) -> None:
+    from homeassistant.components import frontend
+
+    add_module = getattr(frontend, "add_extra_module_url", None)
+    if callable(add_module):
+        add_module(hass, card_url)
+        return
+
+    add_js = getattr(frontend, "add_extra_js_url", None)
+    if callable(add_js):
+        add_js(hass, card_url)

ha_deploy_kit/inventory.py

@@ -0,0 +1,50 @@
+"""Local inventory: pure, side-effect-free hashing of a component tree.
+
+Keys are POSIX paths relative to ``component_dir`` (one namespace per
+deployment root), so an unchanged tree compares as a true no-op.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from ha_deploy_kit.settings import DeployError, DeploySettings
+
+
+def sha256_file(path: Path) -> str:
+    """Return the hex SHA-256 of a file, read in bounded chunks."""
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(65536), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def local_inventory(settings: DeploySettings) -> dict[str, str]:
+    """Map component-relative POSIX paths to SHA-256.
+
+    Skips files whose suffix is in ``settings.skip_suffixes`` and any path with
+    a part in ``settings.skip_dirs``. Raises ``DeployError`` when the component
+    dir is missing or the resulting inventory is empty.
+    """
+    component_dir = settings.component_dir
+    if not component_dir.is_dir():
+        raise DeployError(
+            f"component directory for domain '{settings.domain}' not found"
+        )
+
+    inventory: dict[str, str] = {}
+    for path in sorted(component_dir.rglob("*")):
+        if not path.is_file():
+            continue
+        rel = path.relative_to(component_dir)
+        if any(part in settings.skip_dirs for part in rel.parts):
+            continue
+        if path.suffix in settings.skip_suffixes:
+            continue
+        inventory[rel.as_posix()] = sha256_file(path)
+
+    if not inventory:
+        raise DeployError(f"no deployable files found for domain '{settings.domain}'")
+    return inventory

ha_deploy_kit/metadata/services.yaml.tmpl

@@ -0,0 +1,6 @@
+# Seed template for a consumer's custom_components/<domain>/services.yaml.
+# Replace {service_name} with your configured service name (default below).
+{service_name}:
+  name: Raise restart issue
+  description: Raise the restart-required repair issue for this integration.
+  fields: {}

ha_deploy_kit/metadata/strings.snippet.fixflow.json

@@ -0,0 +1,15 @@
+{
+  "issues": {
+    "restart_required": {
+      "title": "Restart required to finish updating",
+      "fix_flow": {
+        "step": {
+          "confirm_restart": {
+            "title": "Restart Home Assistant",
+            "description": "Restart Home Assistant now to load the newly deployed code?"
+          }
+        }
+      }
+    }
+  }
+}

ha_deploy_kit/metadata/strings.snippet.json

@@ -0,0 +1,14 @@
+{
+  "services": {
+    "raise_restart_issue": {
+      "name": "Raise restart issue",
+      "description": "Raise the restart-required repair issue for this integration."
+    }
+  },
+  "issues": {
+    "restart_required": {
+      "title": "Restart required to finish updating",
+      "description": "Newly deployed code is on disk. Restart Home Assistant to load it."
+    }
+  }
+}

ha_deploy_kit/notify.py

@@ -0,0 +1,150 @@
+"""Sanitized HTTP notification client.
+
+Posts to the HA service that raises the restart Repairs issue and classifies the
+outcome into a fixed, secret-free vocabulary. Never prints tokens, raw bodies, or
+secret-bearing exception text; never weakens TLS verification.
+"""
+
+from __future__ import annotations
+
+import ssl
+
+from ha_deploy_kit.settings import DeploySettings
+
+
+def _verifying_ssl_context() -> ssl.SSLContext:
+    """Return a strictly-verifying TLS context backed by a real CA store.
+
+    Python's default context has no usable CA store on some platforms (macOS /
+    python.org / fresh venvs), which misreports valid certs as ``tls-error``.
+    Prefer the OS trust store (``truststore``, matching ``curl``), then
+    ``certifi``, then the stdlib default. Every branch keeps verification strict
+    (``CERT_REQUIRED`` + ``check_hostname``); none ever disables it.
+    """
+    try:
+        import truststore
+
+        return truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    except ImportError:
+        pass
+    try:
+        import certifi
+
+        return ssl.create_default_context(cafile=certifi.where())
+    except ImportError:
+        pass
+    return ssl.create_default_context()
+
+
+def raise_restart_issue(
+    base_url: str, token: str | None, settings: DeploySettings
+) -> str:
+    """POST ``{}`` to the restart service; return a sanitized status string.
+
+    One of: ``no-token``, ``raised``, ``no-service``, ``http-<code>``,
+    ``tls-error``, ``connection-error``, ``invalid-config``, ``protocol-error``.
+    """
+    import http.client
+    import urllib.error
+    import urllib.request
+
+    if not base_url or not token:
+        return "no-token"
+
+    context = _verifying_ssl_context()
+
+    url = f"{base_url}/api/services/{settings.domain}/{settings.service_name}"
+    request = urllib.request.Request(
+        url,
+        data=b"{}",
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+        },
+        method="POST",
+    )
+
+    try:
+        with urllib.request.urlopen(
+            request, timeout=settings.http_timeout, context=context
+        ) as response:
+            response.read()
+        return "raised"
+    except urllib.error.HTTPError as err:
+        code = err.code
+        try:
+            err.read()
+        except Exception:  # noqa: BLE001 - draining; outcome does not matter
+            pass
+        finally:
+            err.close()
+        if code in (400, 404) and _restart_service_missing(
+            base_url, token, settings, context
+        ):
+            return "no-service"
+        return f"http-{code}"
+    except ssl.SSLCertVerificationError:
+        return "tls-error"
+    except urllib.error.URLError as err:
+        if isinstance(err.reason, ssl.SSLError):
+            return "tls-error"
+        return "connection-error"
+    except (ValueError, http.client.InvalidURL):
+        return "invalid-config"
+    except http.client.HTTPException:
+        return "protocol-error"
+    except OSError:
+        return "connection-error"
+
+
+def _restart_service_missing(
+    base_url: str, token: str, settings: DeploySettings, context: ssl.SSLContext
+) -> bool:
+    """Prove the service is absent via a bounded ``/api/services`` probe.
+
+    Returns ``True`` only when the response is a well-formed list and no item
+    declares ``settings.service_name`` under ``settings.domain``. Any malformed,
+    failed, or ambiguous probe returns ``False`` (keep the original HTTP error).
+    """
+    import http.client
+    import json
+    import urllib.error
+    import urllib.request
+
+    url = f"{base_url}/api/services"
+    request = urllib.request.Request(
+        url,
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/json",
+        },
+        method="GET",
+    )
+
+    try:
+        with urllib.request.urlopen(
+            request, timeout=settings.http_timeout, context=context
+        ) as response:
+            raw = response.read()
+        data = json.loads(raw)
+    except (
+        urllib.error.HTTPError,
+        http.client.HTTPException,
+        urllib.error.URLError,
+        OSError,
+        ValueError,
+    ):
+        return False
+
+    if not isinstance(data, list):
+        return False
+    for item in data:
+        if not isinstance(item, dict):
+            return False
+        domain = item.get("domain")
+        services = item.get("services")
+        if not isinstance(domain, str) or not isinstance(services, dict):
+            return False
+        if domain == settings.domain and settings.service_name in services:
+            return False
+    return True

ha_deploy_kit/settings.py

@@ -0,0 +1,56 @@
+"""Frozen settings types for ha_deploy_kit.
+
+All per-consumer state travels in a frozen ``DeploySettings`` passed by
+argument. No module globals, no ``os.environ`` mutation, and no imports of
+Home Assistant: one process can deploy several consumers without cross-talk.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class DeployError(Exception):
+    """Raised for any recoverable deployment error (sanitized messages)."""
+
+
+@dataclass(frozen=True)
+class FrontendAsset:
+    """An optional frontend card served separately from the backend tree.
+
+    ``source_rel`` is POSIX, relative to the component dir (e.g.
+    ``"lovelace/<name>-card.js"``); ``published_remote`` is the separately-served
+    copy relative to the remote HA config dir (e.g.
+    ``"www/<domain>/<name>-card.js"``).
+    """
+
+    source_rel: str
+    published_remote: str
+    serve_url: str | None = None
+
+
+@dataclass(frozen=True)
+class DeploySettings:
+    """All per-consumer deployment state. Paths derive from ``source_root``."""
+
+    domain: str
+    source_root: Path
+    remote_config: str = "/config"
+    service_name: str = "raise_restart_issue"
+    issue_id: str = "restart_required"
+    translation_key: str = "restart_required"
+    learn_more_url: str | None = None
+    frontend: FrontendAsset | None = None
+    ssh_timeout: int = 120
+    http_timeout: int = 30
+    skip_dirs: frozenset[str] = frozenset({"__pycache__"})
+    skip_suffixes: tuple[str, ...] = (".pyc",)
+
+    @property
+    def component_dir(self) -> Path:
+        return self.source_root / "custom_components" / self.domain
+
+    @property
+    def remote_component(self) -> str:
+        return f"{self.remote_config.rstrip('/')}/custom_components/{self.domain}"

ha_deploy_kit/transport.py

@@ -0,0 +1,117 @@
+"""SSH command transport and safe tar streaming.
+
+The transport never interpolates untrusted values into a shell string, never
+issues ``ha core restart``, and validates every archive member before a single
+byte is written.
+"""
+
+from __future__ import annotations
+
+import posixpath
+import subprocess
+import tarfile
+from io import BytesIO
+from typing import Protocol
+
+from ha_deploy_kit.settings import DeployError, DeploySettings
+
+
+def _shquote(value: str) -> str:
+    """Single-quote a value for safe embedding in a POSIX shell command."""
+    return "'" + value.replace("'", "'\\''") + "'"
+
+
+class SSHTransport(Protocol):
+    def __call__(self, command: str, stdin: bytes | None = None) -> bytes: ...
+
+
+class SubprocessSSH:
+    """Run remote commands over ``ssh`` via ``subprocess`` (no shell on our side)."""
+
+    def __init__(self, target: str, timeout: int = 120) -> None:
+        self.target = target
+        self.timeout = timeout
+
+    def __call__(self, command: str, stdin: bytes | None = None) -> bytes:
+        try:
+            result = subprocess.run(
+                ["ssh", self.target, command],
+                input=stdin,
+                capture_output=True,
+                timeout=self.timeout,
+            )
+        except (subprocess.TimeoutExpired, OSError) as exc:
+            raise DeployError(f"SSH to {self.target} failed") from exc
+        if result.returncode != 0:
+            raise DeployError(
+                f"SSH to {self.target} failed with exit code {result.returncode}"
+            )
+        return result.stdout
+
+
+def validate_members(settings: DeploySettings, rel_paths: list[str]) -> None:
+    """Reject unsafe archive members before any transfer.
+
+    Rejects absolute paths, ``..`` traversal, NUL/newline injection, and any
+    source path that is or traverses a symlink escaping ``component_dir``.
+    Messages are sanitized and never echo the raw (attacker-controlled) path.
+    """
+    base = settings.component_dir.resolve()
+    for index, rel in enumerate(rel_paths):
+        if "\x00" in rel or "\n" in rel or "\r" in rel:
+            raise DeployError(f"archive member #{index} contains an illegal character")
+        if rel.startswith("/") or posixpath.isabs(rel):
+            raise DeployError(f"archive member #{index} is an absolute path")
+        if ".." in rel.split("/"):
+            raise DeployError(f"archive member #{index} traverses outside the tree")
+        resolved = (settings.component_dir / rel).resolve()
+        try:
+            resolved.relative_to(base)
+        except ValueError as exc:
+            raise DeployError(
+                f"archive member #{index} escapes the component directory"
+            ) from exc
+
+
+def build_tar(settings: DeploySettings, rel_paths: list[str]) -> bytes:
+    """Build an uncompressed tar of the given members (owner-normalized)."""
+    validate_members(settings, rel_paths)
+
+    def _normalize(info: tarfile.TarInfo) -> tarfile.TarInfo:
+        info.uid = 0
+        info.gid = 0
+        info.uname = ""
+        info.gname = ""
+        return info
+
+    buffer = BytesIO()
+    with tarfile.open(fileobj=buffer, mode="w") as tar:
+        for rel in rel_paths:
+            tar.add(
+                settings.component_dir / rel,
+                arcname=rel,
+                recursive=False,
+                filter=_normalize,
+            )
+    return buffer.getvalue()
+
+
+def deploy_backend(
+    ssh: SSHTransport, settings: DeploySettings, rel_paths: list[str]
+) -> None:
+    """Create the remote dirs and stream the tar. No atomicity, no rollback."""
+    remote = settings.remote_component
+    dirs = [remote, f"{remote}/translations"]
+    if settings.frontend is not None:
+        published = (
+            settings.remote_config.rstrip("/")
+            + "/"
+            + settings.frontend.published_remote
+        )
+        dirs.append(posixpath.dirname(published))
+
+    mkdir = "mkdir -p " + " ".join(_shquote(d) for d in dirs)
+    ssh(mkdir)
+
+    blob = build_tar(settings, rel_paths)
+    ssh(f"tar -xf - -C {_shquote(remote)}", stdin=blob)

ha_deploy_kit-0.1.0.dist-info/METADATA

@@ -0,0 +1,199 @@
+Metadata-Version: 2.5
+Name: ha-deploy-kit
+Version: 0.1.0
+Summary: HA-free SSH deploy / compare / notify / optional-frontend toolkit for Home Assistant custom components
+Project-URL: Homepage, https://github.com/latrekc-meta/ha-deploy-kit
+Project-URL: Repository, https://github.com/latrekc-meta/ha-deploy-kit
+Project-URL: Issues, https://github.com/latrekc-meta/ha-deploy-kit/issues
+Author: latrekc-meta
+License: MIT License
+        
+        Copyright (c) 2026 latrekc-meta
+        
+        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.
+License-File: LICENSE
+Keywords: custom-component,deploy,home-assistant,homeassistant,lovelace,ssh
+Classifier: Development Status :: 4 - Beta
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Requires-Dist: certifi
+Requires-Dist: truststore>=0.9
+Provides-Extra: ha
+Requires-Dist: homeassistant; extra == 'ha'
+Description-Content-Type: text/markdown
+
+# ha-deploy-kit
+
+A small, reusable library for deploying a Home Assistant custom integration's
+code to a running HA host over SSH, and (optionally) wiring the HA-side restart
+notification. The core is Home-Assistant-free and standard-library only, so a
+deploy script can import it without pulling in Home Assistant; the HA adapter is
+a separate, explicitly-imported subpackage.
+
+One process can deploy several integrations without cross-talk: all per-consumer
+state lives in a frozen `DeploySettings` passed by argument — no module globals
+and no `os.environ` mutation.
+
+## What it does
+
+- Builds a content-hash inventory of your `custom_components/<domain>` tree and
+  compares it to the remote tree, deploying only the changed files.
+- Leaves remote-only files untouched (never deletes on the host).
+- Streams files over SSH with an uncompressed, path-validated tar — no backups,
+  no lock files, no rollback, no auto-restart.
+- Optionally publishes a separately-served Lovelace card.
+- Optionally raises a Home Assistant *Repairs* issue (via an HA service) telling
+  the user a restart is needed. The engine never restarts HA itself; restart is
+  opt-in and happens only when a user confirms a Repairs fix flow.
+
+## Install
+
+Published on PyPI. Pin an exact version.
+
+```sh
+pip install "ha-deploy-kit==0.1.0"
+```
+
+The HA adapter needs Home Assistant, which is an optional extra:
+
+```sh
+pip install "ha-deploy-kit[ha]==0.1.0"
+```
+
+- **Core** requires Python **3.10+** and only the standard library (plus a CA
+  trust store: `certifi`/`truststore`).
+- **The `ha` adapter** requires the Python version Home Assistant itself
+  requires; install it in the HA runtime, not in your deploy tooling.
+- **Home Assistant integrations** must pin a versioned PyPI requirement
+  (`"ha-deploy-kit==0.1.0"` in `manifest.json`), **never** a `git+…` VCS URL — HA
+  installs requirements in its own credential-less environment and treats URL
+  requirements as never-satisfied, retrying every startup.
+
+See [docs/install.md](docs/install.md) for `pyproject.toml`, HA `manifest.json`,
+and air-gapped host instructions, and [docs/releasing.md](docs/releasing.md) for
+how releases are published.
+
+## Public API
+
+| Symbol | Import | Purpose |
+| --- | --- | --- |
+| `DeploySettings` | `ha_deploy_kit` | Frozen per-consumer settings (domain, source root, remote config, optional frontend, timeouts). |
+| `FrontendAsset` | `ha_deploy_kit` | Optional served-card mapping (`source_rel`, `published_remote`). |
+| `DeployError` | `ha_deploy_kit` | Raised for recoverable, sanitized deployment errors. |
+| `run(settings, argv, ssh=None, environ=None)` | `ha_deploy_kit.cli` | Orchestrate end to end: compare, report, publish the changed card, deploy the changed backend, notify. Honors a `REMOTE_CONFIG` env override. |
+| `raise_restart_issue(base_url, token, settings)` | `ha_deploy_kit.notify` | POST to the HA restart service; returns a sanitized status string. |
+| `frontend_run(settings, plan, ssh, *, check)` | `ha_deploy_kit.frontend` | Deploy the card into the tree and/or publish the served copy. |
+| `ha.async_register_restart_service(hass, domain, ...)` | `ha_deploy_kit.ha` | Idempotently register the restart service (empty schema). Pass `fixable=True` for a one-click Repairs card (pair with the fix flow). |
+| `ha.async_raise_restart_issue(hass, domain, ...)` | `ha_deploy_kit.ha` | Raise the deduplicated, non-persistent restart Repairs issue. |
+| `ha.async_clear_restart_issue(hass, domain, ...)` | `ha_deploy_kit.ha` | Clear the restart issue. |
+| `ha.async_create_restart_fix_flow(hass, issue_id, ...)` | `ha_deploy_kit.ha` | Optional opt-in confirm-and-restart flow (restart only on submit). |
+| `ha.register_card_serving(hass, domain, lovelace_dir, card_url)` | `ha_deploy_kit.ha` | Serve the card and register it as a frontend module. |
+
+## CLI
+
+The package installs a `ha-deploy` console script. It deploys by default; pass
+`--check` (or its alias `--dry-run`) to preview without writing anything.
+
+```sh
+ha-deploy                 # deploy changed backend files, then notify
+ha-deploy --check         # compare and report only; no writes, no notify
+ha-deploy --root /path/to/your/repo
+```
+
+The source root is resolved from `--root`, then `HA_DEPLOY_SOURCE_ROOT`, then
+the current directory. The domain is read from `HA_DEPLOY_DOMAIN`, or inferred
+when the root has exactly one `custom_components/<domain>` subdirectory.
+
+### One-liner for your own deploy script
+
+`run` is fully frontend-aware, so a consumer's `deploy.py` is just settings + a
+call — no pipeline to copy. It publishes a changed card and deploys a changed
+backend; a frontend-only change publishes the card but never notifies a restart.
+
+```python
+import sys
+from pathlib import Path
+
+from ha_deploy_kit import DeploySettings, FrontendAsset
+from ha_deploy_kit.cli import run
+
+settings = DeploySettings(
+    domain="your_domain",
+    source_root=Path(__file__).resolve().parent,
+    frontend=FrontendAsset(  # omit entirely for backend-only
+        source_rel="lovelace/your-card.js",
+        published_remote="www/your_domain/your-card.js",
+    ),
+)
+raise SystemExit(run(settings, sys.argv[1:]))
+```
+
+`TARGET`/`HA_BASE_URL`/`HA_TOKEN` and an optional `REMOTE_CONFIG` override come
+from `.env` or the process environment; `run` applies `REMOTE_CONFIG` for you.
+
+See [docs/configuration.md](docs/configuration.md) for settings and `.env`, and
+[docs/adopting.md](docs/adopting.md) for a step-by-step adoption guide.
+
+## Design notes
+
+This library deliberately differs from typical hand-rolled HA deploy scripts.
+Each choice below is intentional:
+
+- **No positional target and no `--restart` / `--no-restart` / `--card-only`
+  flags.** The target comes from the environment; the engine never restarts HA,
+  so there is no restart flag to pass.
+- **The engine never executes a restart.** It can only raise a Repairs issue;
+  the actual restart is opt-in behind a user-confirmed fix flow.
+- **A frontend-only change never notifies a backend restart.** Backend and
+  frontend are separate concerns.
+- **Structured remote inventory.** The remote probe returns an explicit
+  four-field result (hashes, stale files, a missing-tree flag, published hash)
+  rather than guessing from text.
+- **Environment precedence is explicit.** Process environment overrides `.env`;
+  the library never mutates `os.environ`.
+- **Path validation.** Tar members are rejected if absolute, containing `..`,
+  NUL, or newlines, or escaping the component directory.
+- **No backups, lock files, rollback, or auto-restart**, and tokens, raw bodies,
+  and secret-bearing errors are never printed. TLS and SSH verification are
+  never weakened.
+- **Real CA trust store for the notification.** The HTTPS call to Home Assistant
+  verifies against the OS trust store via `truststore` (matching `curl`), falling
+  back to `certifi` then the stdlib default — all strictly verifying
+  (`CERT_REQUIRED` + hostname check). This avoids misreporting a valid cert as
+  `tls-error` on platforms whose default context has no usable CA store (macOS,
+  python.org, fresh venvs); `tls-error` is reserved for genuine failures.
+
+## Releases
+
+Releases are automated: every merge to `main` runs semantic-release, which picks
+the next version from the [Conventional Commit] messages (`fix:` → patch,
+`feat:` → minor, `feat!:`/`BREAKING CHANGE:` → major; `docs:`/`chore:`/`test:`
+publish nothing) and publishes to PyPI via Trusted Publishing. Write PR
+titles/commits in that form. See [docs/releasing.md](docs/releasing.md) for the
+one-time setup and the manual fallback.
+
+[Conventional Commit]: https://www.conventionalcommits.org/