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

ha_deploy_kit/__init__.py

@@ -0,0 +1,9 @@
+"""ha_deploy_kit: HA-free SSH deploy / compare / notify toolkit.
+
+The core package never imports Home Assistant. The HA-side adapter lives in
+``ha_deploy_kit.ha`` and must be imported explicitly.
+"""
+
+from ha_deploy_kit.settings import DeployError, DeploySettings, FrontendAsset
+
+__all__ = ["DeployError", "DeploySettings", "FrontendAsset"]

ha_deploy_kit/cli.py

@@ -0,0 +1,144 @@
+"""CLI orchestration and sanitized reporting.
+
+``run`` is the testable entrypoint: resolve env, build the local inventory, probe
+the remote, compare, report, and — only when the backend changed — deploy the
+changed subset and attempt the restart notification. A frontend-only change does
+no backend deploy/mkdir/notify (the frontend profile handles the card). The
+engine never restarts; it only ever prints a manual-restart line as guidance.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from collections.abc import Mapping
+from dataclasses import replace
+from pathlib import Path
+
+from ha_deploy_kit.comparison import ComparisonPlan, compare, fetch_remote_inventory
+from ha_deploy_kit.config import api_base, env_value, resolve_env
+from ha_deploy_kit.frontend import frontend_run
+from ha_deploy_kit.inventory import local_inventory
+from ha_deploy_kit.notify import raise_restart_issue
+from ha_deploy_kit.settings import DeployError, DeploySettings
+from ha_deploy_kit.transport import SSHTransport, SubprocessSSH, deploy_backend
+
+_STATUS_MESSAGES = {
+    "raised": "Restart notification raised.",
+    "no-token": "No API token configured; notification skipped.",
+    "no-service": "Restart service not registered on Home Assistant.",
+    "tls-error": "Could not reach Home Assistant: TLS verification failed.",
+    "connection-error": "Could not reach Home Assistant: connection failed.",
+    "invalid-config": "Invalid Home Assistant URL configuration.",
+    "protocol-error": "Unexpected protocol error contacting Home Assistant.",
+}
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(prog="ha-deploy")
+    parser.add_argument("--check", action="store_true", dest="check")
+    parser.add_argument("--dry-run", action="store_true", dest="check")
+    parser.add_argument("--root", default=None)
+    return parser.parse_args(argv)
+
+
+def _notify_message(status: str, target: str) -> str:
+    base = _STATUS_MESSAGES.get(status)
+    if base is None:
+        base = f"Home Assistant returned {status}."
+    manual = f"Restart manually: ssh {target} 'ha core restart'"
+    return f"{base} {manual}"
+
+
+def report(settings: DeploySettings, plan: ComparisonPlan, target: str) -> None:
+    print(f"Target: {target}  (domain: {settings.domain})")
+    if plan.in_sync:
+        print("Backend: in sync.")
+    elif plan.changed_backend:
+        print(f"Backend: {len(plan.changed_backend)} file(s) to deploy.")
+    else:
+        print("Backend: no changes.")
+    if plan.stale_remote:
+        print(f"Remote-only files (left untouched): {len(plan.stale_remote)}.")
+    if settings.frontend is not None:
+        if plan.frontend_changed:
+            print("Frontend: card changes pending.")
+        else:
+            print("Frontend: in sync.")
+
+
+def run(
+    settings: DeploySettings,
+    argv: list[str],
+    ssh: SSHTransport | None = None,
+    environ: Mapping[str, str] | None = None,
+) -> int:
+    args = parse_args(argv)
+    environ = os.environ if environ is None else environ
+
+    resolved = resolve_env(settings.source_root / ".env", environ)
+    base = api_base(resolved)
+    token = env_value(resolved, "HA_TOKEN")
+    target = env_value(resolved, "TARGET")
+
+    remote_config = env_value(resolved, "REMOTE_CONFIG")
+    if remote_config:
+        settings = replace(settings, remote_config=remote_config)
+
+    if ssh is None:
+        ssh = SubprocessSSH(target, settings.ssh_timeout)
+
+    local = local_inventory(settings)
+    rel_paths = sorted(local)
+    remote = fetch_remote_inventory(ssh, settings, rel_paths)
+    plan = compare(local, remote, settings)
+    report(settings, plan, target)
+
+    if plan.in_sync:
+        print("Already in sync; nothing to do.")
+        return 0
+
+    # Publish the card (or preview on --check). No-op when frontend is None or
+    # unchanged; a frontend-only change publishes but never notifies a restart.
+    for note in frontend_run(settings, plan, ssh, check=args.check):
+        print(note)
+
+    if args.check:
+        print("Check only: no changes applied.")
+        return 0
+
+    if plan.changed_backend:
+        try:
+            deploy_backend(ssh, settings, plan.changed_backend)
+        except DeployError as exc:
+            print(f"Deployment failed: {exc}")
+            return 1
+        status = raise_restart_issue(base, token, settings)
+        print(_notify_message(status, target))
+
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    root = args.root or os.environ.get("HA_DEPLOY_SOURCE_ROOT") or os.getcwd()
+    source_root = Path(root)
+
+    domain = os.environ.get("HA_DEPLOY_DOMAIN")
+    if not domain:
+        components = source_root / "custom_components"
+        candidates = (
+            [p.name for p in sorted(components.iterdir()) if p.is_dir()]
+            if components.is_dir()
+            else []
+        )
+        if len(candidates) != 1:
+            print(
+                "Set HA_DEPLOY_DOMAIN: could not infer a single component under "
+                f"{components}"
+            )
+            return 2
+        domain = candidates[0]
+
+    settings = DeploySettings(domain=domain, source_root=source_root)
+    return run(settings, argv or [])

ha_deploy_kit/comparison.py

@@ -0,0 +1,202 @@
+"""Remote inventory wire format and comparison planning (pure).
+
+The remote probe is a single one-shot shell script whose output is parsed into a
+structured ``RemoteInventory`` with an explicit ``missing_tree`` flag. ``compare``
+diffs that against the local inventory and produces a ``ComparisonPlan``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from ha_deploy_kit.settings import DeployError, DeploySettings
+
+if TYPE_CHECKING:
+    from ha_deploy_kit.transport import SSHTransport
+
+
+def _shquote(value: str) -> str:
+    """Single-quote a value for safe embedding in a POSIX shell script."""
+    return "'" + value.replace("'", "'\\''") + "'"
+
+
+@dataclass(frozen=True)
+class RemoteInventory:
+    """Parsed result of the remote probe.
+
+    ``missing_tree`` is explicit (corrects the reference 3-vs-4 return mismatch):
+    an absent component dir is a distinct state from an empty hash map.
+    """
+
+    hashes: dict[str, str]
+    stale: list[str] = field(default_factory=list)
+    missing_tree: bool = False
+    published_hash: str | None = None
+
+
+@dataclass(frozen=True)
+class ComparisonPlan:
+    changed_backend: list[str]
+    stale_remote: list[str]
+    frontend_tree_changed: bool = False
+    frontend_published_changed: bool = False
+
+    @property
+    def frontend_changed(self) -> bool:
+        return self.frontend_tree_changed or self.frontend_published_changed
+
+    @property
+    def in_sync(self) -> bool:
+        return not self.changed_backend and not self.frontend_changed
+
+
+def build_inventory_script(settings: DeploySettings, rel_paths: list[str]) -> str:
+    """Build the one-shot remote probe script.
+
+    Reads requested relative paths from stdin; emits ``sha256sum``/``MISSING <f>``
+    per requested path, ``REMOTE_ONLY <p>`` for every remote file (caches
+    excluded), ``NO_REMOTE_TREE`` when the component dir is absent, and
+    ``WWW:card``/``MISSING WWW:card`` for a configured frontend published copy.
+    """
+    remote = _shquote(settings.remote_component)
+    parts = [
+        "set -u",
+        f"DIR={remote}",
+        'if [ ! -d "$DIR" ]; then',
+        "  echo NO_REMOTE_TREE",
+        "else",
+        "  while IFS= read -r f; do",
+        '    [ -z "$f" ] && continue',
+        '    if [ -f "$DIR/$f" ]; then',
+        '      (cd "$DIR" && sha256sum "$f")',
+        "    else",
+        '      echo "MISSING $f"',
+        "    fi",
+        "  done",
+        (
+            '  find "$DIR" -type f ! -path "*/__pycache__/*" '
+            '! -name "*.pyc" 2>/dev/null \\'
+        ),
+        '    | sed "s#^$DIR/##" | sort | while IFS= read -r p; do',
+        '      echo "REMOTE_ONLY $p"',
+        "    done",
+        "fi",
+    ]
+    if settings.frontend is not None:
+        published = (
+            settings.remote_config.rstrip("/")
+            + "/"
+            + settings.frontend.published_remote
+        )
+        card = _shquote(published)
+        parts += [
+            f"CARD={card}",
+            'if [ -f "$CARD" ]; then',
+            '  echo "$(sha256sum "$CARD" | cut -d\' \' -f1) WWW:card"',
+            "else",
+            "  echo MISSING WWW:card",
+            "fi",
+        ]
+    return "\n".join(parts) + "\n"
+
+
+def parse_inventory(
+    output: str, rel_paths: list[str], settings: DeploySettings
+) -> RemoteInventory:
+    """Parse the remote probe output into a ``RemoteInventory``.
+
+    ``REMOTE_ONLY`` entries that correspond to a requested (local) path are not
+    stale. Raises ``DeployError`` on empty output.
+    """
+    if not output.strip():
+        raise DeployError("empty remote inventory output")
+
+    requested = set(rel_paths)
+    hashes: dict[str, str] = {}
+    stale: list[str] = []
+    missing_tree = False
+    published_hash: str | None = None
+
+    for raw in output.splitlines():
+        line = raw.strip()
+        if not line:
+            continue
+        if line == "NO_REMOTE_TREE":
+            missing_tree = True
+        elif line == "MISSING WWW:card":
+            published_hash = None
+        elif line.endswith("WWW:card"):
+            published_hash = line.split()[0]
+        elif line.startswith("MISSING "):
+            hashes[line[len("MISSING ") :]] = ""
+        elif line.startswith("REMOTE_ONLY "):
+            path = line[len("REMOTE_ONLY ") :]
+            if path not in requested:
+                stale.append(path)
+        else:
+            parts = line.split()
+            if len(parts) >= 2 and len(parts[0]) == 64:
+                hashes[parts[-1]] = parts[0]
+            # anything else is noise and ignored
+
+    return RemoteInventory(
+        hashes=hashes,
+        stale=stale,
+        missing_tree=missing_tree,
+        published_hash=published_hash,
+    )
+
+
+def fetch_remote_inventory(
+    ssh: SSHTransport, settings: DeploySettings, rel_paths: list[str]
+) -> RemoteInventory:
+    """Bridge transport to pure parsing: send the probe, parse the result."""
+    script = build_inventory_script(settings, rel_paths)
+    stdin = ("\n".join(rel_paths) + "\n").encode()
+    output = ssh(script, stdin=stdin)
+    return parse_inventory(output.decode(), rel_paths, settings)
+
+
+def compare(
+    local: dict[str, str], remote: RemoteInventory, settings: DeploySettings
+) -> ComparisonPlan:
+    """Diff local vs remote into a ``ComparisonPlan``.
+
+    The frontend ``source_rel`` is excluded from ``changed_backend`` and tracked
+    separately. A configured-but-missing local card raises ``DeployError`` before
+    any write; an absent optional asset never raises.
+    """
+    frontend = settings.frontend
+    source_rel = frontend.source_rel if frontend is not None else None
+
+    if source_rel is not None and source_rel not in local:
+        raise DeployError(
+            f"configured frontend source '{source_rel}' not found in local tree"
+        )
+
+    backend_local = {k: v for k, v in local.items() if k != source_rel}
+
+    if remote.missing_tree:
+        changed_backend = sorted(backend_local)
+    else:
+        changed_backend = [
+            k for k in sorted(backend_local) if remote.hashes.get(k) != backend_local[k]
+        ]
+
+    frontend_tree_changed = False
+    frontend_published_changed = False
+    if source_rel is not None:
+        local_card = local[source_rel]
+        if remote.missing_tree:
+            frontend_tree_changed = True
+        else:
+            frontend_tree_changed = remote.hashes.get(source_rel) != local_card
+        frontend_published_changed = remote.published_hash != local_card
+
+    return ComparisonPlan(
+        changed_backend=changed_backend,
+        stale_remote=list(remote.stale),
+        frontend_tree_changed=frontend_tree_changed,
+        frontend_published_changed=frontend_published_changed,
+    )

ha_deploy_kit/config.py

@@ -0,0 +1,63 @@
+"""Configuration loading without global mutation.
+
+``load_dotenv`` returns the parsed values and never touches ``os.environ`` (the
+reference scripts mutated it, which leaks between two consumers in one process).
+``resolve_env`` merges with process env taking precedence over the file.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from pathlib import Path
+
+_KEY_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+_API_BASE_KEY = "HA_BASE_URL"
+
+
+def load_dotenv(path: Path) -> dict[str, str]:
+    """Parse a ``KEY=VALUE`` file into a dict without mutating ``os.environ``.
+
+    Ignores blanks and ``#`` comments, strips a leading ``export``, strips one
+    layer of matching single/double quotes, keeps empty values, accepts only
+    ``[A-Za-z_][A-Za-z0-9_]*`` keys, ignores malformed lines, and performs no
+    shell evaluation. A missing file yields ``{}``.
+    """
+    if not path.is_file():
+        return {}
+
+    result: dict[str, str] = {}
+    for raw in path.read_text().splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export ") :].lstrip()
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        if not _KEY_RE.fullmatch(key):
+            continue
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
+            value = value[1:-1]
+        result[key] = value
+    return result
+
+
+def resolve_env(path: Path, environ: Mapping[str, str]) -> dict[str, str]:
+    """Merge file values with process env, where process env wins."""
+    resolved = load_dotenv(path)
+    resolved.update(environ)
+    return resolved
+
+
+def env_value(resolved: Mapping[str, str], key: str) -> str:
+    """Return a stripped value for ``key`` (empty string when absent)."""
+    return resolved.get(key, "").strip()
+
+
+def api_base(resolved: Mapping[str, str]) -> str:
+    """Return the HA base URL, stripped and without a trailing slash."""
+    return env_value(resolved, _API_BASE_KEY).rstrip("/")

ha_deploy_kit/frontend.py

@@ -0,0 +1,87 @@
+"""Optional frontend profile: publish a served card copy and run frontend steps.
+
+Frontend copying never triggers a backend restart notification and never adds a
+JS build system. It only streams the card file via the same validated tar path.
+"""
+
+from __future__ import annotations
+
+import posixpath
+import tarfile
+from io import BytesIO
+
+from ha_deploy_kit.comparison import ComparisonPlan
+from ha_deploy_kit.settings import DeploySettings
+from ha_deploy_kit.transport import (
+    SSHTransport,
+    _shquote,
+    deploy_backend,
+    validate_members,
+)
+
+
+def publish_frontend(ssh: SSHTransport, settings: DeploySettings) -> None:
+    """Stream the card to its separately-served published location."""
+    frontend = settings.frontend
+    if frontend is None:
+        return
+
+    validate_members(settings, [frontend.source_rel])
+    published = settings.remote_config.rstrip("/") + "/" + frontend.published_remote
+    published_dir = posixpath.dirname(published)
+    arcname = posixpath.basename(published)
+
+    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:
+        tar.add(
+            settings.component_dir / frontend.source_rel,
+            arcname=arcname,
+            recursive=False,
+            filter=_normalize,
+        )
+
+    ssh("mkdir -p " + _shquote(published_dir))
+    ssh(f"tar -xf - -C {_shquote(published_dir)}", stdin=buffer.getvalue())
+
+
+def frontend_run(
+    settings: DeploySettings,
+    plan: ComparisonPlan,
+    ssh: SSHTransport,
+    *,
+    check: bool,
+) -> list[str]:
+    """Deploy the tree card and/or published copy per the plan.
+
+    No restart side effects.
+    """
+    notes: list[str] = []
+    frontend = settings.frontend
+    if frontend is None or not plan.frontend_changed:
+        return notes
+
+    if check:
+        if plan.frontend_tree_changed:
+            notes.append("Would deploy the card into the component tree.")
+        if plan.frontend_published_changed:
+            notes.append("Would publish the served card copy.")
+        return notes
+
+    if plan.frontend_tree_changed:
+        deploy_backend(ssh, settings, [frontend.source_rel])
+        notes.append("Deployed the card into the component tree.")
+    if plan.frontend_published_changed:
+        publish_frontend(ssh, settings)
+        notes.append(
+            "Published the served card copy; hard-refresh the browser "
+            "(Ctrl/Cmd+Shift+R) to pick it up."
+        )
+
+    return notes

ha_deploy_kit/ha/__init__.py

@@ -0,0 +1,20 @@
+"""Home Assistant adapter for ha_deploy_kit.
+
+Importing this subpackage imports Home Assistant; the core never does.
+"""
+
+from ha_deploy_kit.ha.repairs_flow import async_create_restart_fix_flow
+from ha_deploy_kit.ha.repairs_issue import (
+    async_clear_restart_issue,
+    async_raise_restart_issue,
+)
+from ha_deploy_kit.ha.service import async_register_restart_service
+from ha_deploy_kit.ha.serving import register_card_serving
+
+__all__ = [
+    "async_clear_restart_issue",
+    "async_create_restart_fix_flow",
+    "async_raise_restart_issue",
+    "async_register_restart_service",
+    "register_card_serving",
+]

ha_deploy_kit/ha/repairs_flow.py

@@ -0,0 +1,48 @@
+"""Optional opt-in confirm-and-restart Repairs flow.
+
+The restart happens ONLY on an explicit form submit. No executable restart lives
+in the core engine; this flow is the single opt-in place a consumer may wire it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import voluptuous as vol
+from homeassistant.components.repairs import RepairsFlow
+
+if TYPE_CHECKING:
+    from homeassistant.core import HomeAssistant
+    from homeassistant.data_entry_flow import FlowResult
+
+
+class _RestartRequiredFixFlow(RepairsFlow):
+    """Shows a confirmation form, then restarts only when the user submits it."""
+
+    async def async_step_init(
+        self, user_input: dict[str, Any] | None = None
+    ) -> FlowResult:
+        return await self.async_step_confirm_restart(user_input)
+
+    async def async_step_confirm_restart(
+        self, user_input: dict[str, Any] | None = None
+    ) -> FlowResult:
+        if user_input is None:
+            return self.async_show_form(
+                step_id="confirm_restart", data_schema=vol.Schema({})
+            )
+        await self.hass.services.async_call("homeassistant", "restart", blocking=False)
+        return self.async_create_entry(title="", data={})
+
+
+def async_create_restart_fix_flow(
+    hass: HomeAssistant,
+    issue_id: str,
+    data: dict[str, Any] | None = None,
+    *,
+    expected_issue_id: str = "restart_required",
+) -> RepairsFlow | None:
+    """Return the opt-in restart fix flow, or ``None`` for other issue ids."""
+    if issue_id != expected_issue_id:
+        return None
+    return _RestartRequiredFixFlow()

ha_deploy_kit/ha/repairs_issue.py

@@ -0,0 +1,46 @@
+"""Repairs issue helpers for the restart-required notification."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from homeassistant.helpers import issue_registry as ir
+
+if TYPE_CHECKING:
+    from homeassistant.core import HomeAssistant
+
+
+def async_raise_restart_issue(
+    hass: HomeAssistant,
+    domain: str,
+    issue_id: str = "restart_required",
+    *,
+    translation_key: str = "restart_required",
+    is_fixable: bool = False,
+    is_persistent: bool = False,
+    learn_more_url: str | None = None,
+) -> None:
+    """Create a deduplicated restart issue scoped to ``domain``+``issue_id``.
+
+    Defaults to a non-persistent, notification-only warning. Keyed by
+    ``(domain, issue_id)``, so it never overwrites another domain's issue.
+    """
+    ir.async_create_issue(
+        hass,
+        domain,
+        issue_id,
+        is_fixable=is_fixable,
+        is_persistent=is_persistent,
+        severity=ir.IssueSeverity.WARNING,
+        translation_key=translation_key,
+        learn_more_url=learn_more_url,
+    )
+
+
+def async_clear_restart_issue(
+    hass: HomeAssistant,
+    domain: str,
+    issue_id: str = "restart_required",
+) -> None:
+    """Remove the restart issue for ``domain``+``issue_id`` if present."""
+    ir.async_delete_issue(hass, domain, issue_id)

ha_deploy_kit/ha/service.py

@@ -0,0 +1,52 @@
+"""Home Assistant service registration for the restart-required issue.
+
+Imports Home Assistant; must be imported explicitly as ``ha_deploy_kit.ha``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import voluptuous as vol
+
+from ha_deploy_kit.ha.repairs_issue import async_raise_restart_issue
+
+if TYPE_CHECKING:
+    from homeassistant.core import HomeAssistant, ServiceCall
+
+
+def async_register_restart_service(
+    hass: HomeAssistant,
+    domain: str,
+    *,
+    service_name: str = "raise_restart_issue",
+    issue_id: str = "restart_required",
+    translation_key: str = "restart_required",
+    learn_more_url: str | None = None,
+    persistent: bool = False,
+    fixable: bool = False,
+) -> None:
+    """Idempotently register the service that raises the restart issue.
+
+    Registers with an empty ``vol.Schema({})`` (rejects any payload) and works
+    from global ``async_setup`` before any config entry loads.
+
+    Set ``fixable=True`` to raise a one-click (fixable) Repairs issue; Home
+    Assistant only runs a fix flow for a fixable issue, so pair this with a
+    wired ``async_create_restart_fix_flow``. The default stays notification-only.
+    """
+    if hass.services.has_service(domain, service_name):
+        return
+
+    async def _handle(call: ServiceCall) -> None:
+        async_raise_restart_issue(
+            hass,
+            domain,
+            issue_id,
+            translation_key=translation_key,
+            is_fixable=fixable,
+            is_persistent=persistent,
+            learn_more_url=learn_more_url,
+        )
+
+    hass.services.async_register(domain, service_name, _handle, schema=vol.Schema({}))