hadsync 0.2.2__py3-none-any.whl

hadsync/config.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Optional, Union
+
+from pydantic import BaseModel, field_validator, ValidationError
+from ruamel.yaml import YAML
+
+CONFIG_FILENAME = ".hadsync.yaml"
+WORKSPACE_ENV_VAR = "HADSYNC_WORKSPACE"
+_ENV_RE = re.compile(r"^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$")
+
+
+class ConfigError(Exception):
+    pass
+
+
+class PullSettings(BaseModel):
+    refresh_entities: bool = True
+    dashboards: Union[str, list[str]] = "all"
+
+
+class PushSettings(BaseModel):
+    require_validation: bool = True
+    confirm: bool = True
+
+
+class ValidationSettings(BaseModel):
+    warn_on_unknown_entities: bool = True
+    entity_cache_max_age_days: int = 7
+    custom_card_types: list[str] = []  # prefixes treated as valid beyond custom:
+
+
+class Config(BaseModel):
+    ha_url: str
+    ha_token: str
+    workspace: Path = Path(".")
+    pull: PullSettings = PullSettings()
+    push: PushSettings = PushSettings()
+    validation: ValidationSettings = ValidationSettings()
+
+    @field_validator("ha_token", mode="before")
+    @classmethod
+    def resolve_token(cls, v: str) -> str:
+        m = _ENV_RE.match(str(v))
+        if m:
+            var_name = m.group(1)
+            token = os.environ.get(var_name)
+            if token is None:
+                raise ValueError(f"Environment variable '{var_name}' is not set")
+            return token
+        return v
+
+    @field_validator("ha_url")
+    @classmethod
+    def normalize_url(cls, v: str) -> str:
+        return v.rstrip("/")
+
+    def masked_token(self) -> str:
+        t = self.ha_token
+        if len(t) <= 8:
+            return "****"
+        return f"{t[:4]}...{t[-4:]}"
+
+
+_yaml = YAML()
+_yaml.preserve_quotes = True
+_yaml.default_flow_style = False
+
+
+def discover_config(start: Optional[Path] = None) -> Optional[Path]:
+    current = Path(start or Path.cwd()).resolve()
+    while True:
+        candidate = current / CONFIG_FILENAME
+        if candidate.exists():
+            return candidate
+        parent = current.parent
+        if parent == current:
+            break
+        current = parent
+    global_cfg = Path.home() / CONFIG_FILENAME
+    return global_cfg if global_cfg.exists() else None
+
+
+def load_config(path: Optional[Path] = None) -> tuple[Config, Path]:
+    config_path = path or discover_config()
+    if config_path is None:
+        raise ConfigError("No .hadsync.yaml found. Run 'hadsync init' to create one.")
+    if not config_path.exists():
+        raise ConfigError(f"Config file not found: {config_path}")
+    try:
+        data = _yaml.load(config_path)
+    except Exception as e:
+        raise ConfigError(f"Failed to parse {config_path}: {e}") from e
+    if not isinstance(data, dict):
+        raise ConfigError(f"{config_path} is not a valid YAML mapping.")
+    try:
+        cfg = Config.model_validate(data)
+    except ValidationError as e:
+        raise ConfigError(f"Invalid config in {config_path}:\n{e}") from e
+
+    # Workspace resolution priority:
+    #   1. HADSYNC_WORKSPACE env var
+    #   2. workspace in config (relative → resolved against config file's directory)
+    #   3. default (.) → resolves to CWD
+    env_ws = os.environ.get(WORKSPACE_ENV_VAR)
+    if env_ws:
+        workspace = Path(env_ws).expanduser().resolve()
+    elif not cfg.workspace.is_absolute():
+        workspace = (config_path.parent / cfg.workspace).resolve()
+    else:
+        workspace = cfg.workspace.resolve()
+
+    cfg = cfg.model_copy(update={"workspace": workspace})
+    return cfg, config_path
+
+
+def save_config(raw: dict, path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w") as f:
+        _yaml.dump(raw, f)

hadsync/converter.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import hashlib
+import json as _json
+from pathlib import Path
+
+from ruamel.yaml import YAML
+
+LOVELACE_FILENAME = "lovelace.yaml"
+
+_yaml = YAML()
+_yaml.default_flow_style = False
+_yaml.width = 4096          # prevent wrapping long strings (markdown cards etc.)
+_yaml.best_sequence_indent = 2
+_yaml.best_map_indent = 2
+
+
+def is_strategy_dashboard(config: dict) -> bool:
+    """True when the dashboard is auto-generated via a strategy (read-only in hadsync)."""
+    return "strategy" in config
+
+
+def count_cards(config: dict) -> tuple[int, int]:
+    """Return (view_count, card_count) for a dashboard config.
+
+    Handles both classic (cards) and sections-layout views.
+    """
+    views = config.get("views", [])
+    cards = 0
+    for view in views:
+        cards += len(view.get("cards", []))
+        for section in view.get("sections", []):
+            cards += len(section.get("cards", []))
+    return len(views), cards
+
+
+def config_to_yaml_file(config: dict, path: Path) -> None:
+    """Write a Lovelace config dict to a YAML file, creating parent dirs."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as f:
+        _yaml.dump(config, f)
+
+
+def yaml_file_to_config(path: Path) -> dict:
+    """Read a YAML file and return a Lovelace config dict."""
+    data = _yaml.load(path)
+    if not isinstance(data, dict):
+        raise ValueError(f"{path} does not contain a YAML mapping")
+    return data
+
+
+def config_hash(config: dict) -> str:
+    """Return a short stable hash of a normalized config dict.
+
+    Used to detect HA-side changes between pulls without storing the full config.
+    Sorting keys ensures the hash is independent of insertion order.
+    """
+    return hashlib.sha256(
+        _json.dumps(config, sort_keys=True, ensure_ascii=False).encode()
+    ).hexdigest()[:16]
+
+
+def normalize(obj: object) -> object:
+    """Recursively convert ruamel.yaml CommentedMap/Seq to plain dict/list.
+
+    Used to produce a clean JSON-serialisable dict for pushing to HA and for
+    equality comparisons between local YAML and the current HA state.
+    """
+    if isinstance(obj, dict):
+        return {k: normalize(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [normalize(v) for v in obj]
+    return obj

hadsync/entities.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+CACHE_FILENAME = ".ha-entities.json"
+
+
+def write_entity_cache(workspace: Path, states: list[dict]) -> int:
+    """Build and write the entity cache from a /api/states response list.
+
+    Returns the number of entities written.
+    """
+    entities: dict[str, dict] = {}
+    for state in states:
+        entity_id = state.get("entity_id")
+        if not entity_id:
+            continue
+        domain = entity_id.split(".")[0]
+        friendly_name = (state.get("attributes") or {}).get("friendly_name", "")
+        entities[entity_id] = {"friendly_name": friendly_name, "domain": domain}
+
+    cache = {
+        "refreshed_at": datetime.now(timezone.utc).isoformat(),
+        "entities": entities,
+    }
+    path = workspace / CACHE_FILENAME
+    path.write_text(json.dumps(cache, indent=2), encoding="utf-8")
+    return len(entities)
+
+
+def load_entity_cache(workspace: Path) -> dict:
+    """Return the raw cache dict, or an empty structure if not found."""
+    path = workspace / CACHE_FILENAME
+    if not path.exists():
+        return {"entities": {}, "refreshed_at": None}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {"entities": {}, "refreshed_at": None}
+
+
+def entity_id_exists(workspace: Path, entity_id: str) -> bool:
+    return entity_id in load_entity_cache(workspace).get("entities", {})
+
+
+def cache_age_days(workspace: Path) -> Optional[float]:
+    """Return the age of the entity cache in days, or None if cache is missing."""
+    refreshed_at = load_entity_cache(workspace).get("refreshed_at")
+    if not refreshed_at:
+        return None
+    try:
+        ts = datetime.fromisoformat(refreshed_at)
+        if ts.tzinfo is None:
+            ts = ts.replace(tzinfo=timezone.utc)
+        return (datetime.now(timezone.utc) - ts).total_seconds() / 86400
+    except Exception:
+        return None
+
+
+def search_entities(workspace: Path, filter_term: str = "") -> dict[str, dict]:
+    """Return entities whose entity_id or friendly_name contain filter_term."""
+    entities = load_entity_cache(workspace).get("entities", {})
+    if not filter_term:
+        return entities
+    term = filter_term.lower()
+    return {
+        eid: info for eid, info in entities.items()
+        if term in eid.lower() or term in (info.get("friendly_name") or "").lower()
+    }
+
+
+# ---------------------------------------------------------------------------
+# Entity ID extraction from Lovelace configs
+# ---------------------------------------------------------------------------
+
+def _get_line(container: object, key_or_idx: int | str) -> Optional[int]:
+    """Best-effort: return 1-based line number of a key/item from ruamel.yaml."""
+    try:
+        lc = getattr(container, "lc", None)
+        if lc is None:
+            return None
+        if isinstance(key_or_idx, int):
+            return lc.item(key_or_idx)[0] + 1
+        return lc.key(key_or_idx)[0] + 1
+    except Exception:
+        return None
+
+
+def _is_entity_id(value: object) -> bool:
+    return isinstance(value, str) and "." in value and not value.startswith("#")
+
+
+def _walk(obj: object, results: list[tuple[str, Optional[int]]]) -> None:
+    if isinstance(obj, dict):
+        # entity: light.lamp
+        if "entity" in obj:
+            v = obj["entity"]
+            if _is_entity_id(v):
+                results.append((v, _get_line(obj, "entity")))
+
+        # entities: ["light.lamp", {entity: sensor.temp}]
+        if "entities" in obj:
+            items = obj["entities"]
+            if isinstance(items, list):
+                for i, item in enumerate(items):
+                    if _is_entity_id(item):
+                        results.append((item, _get_line(items, i)))
+                    elif isinstance(item, dict) and "entity" in item:
+                        v = item["entity"]
+                        if _is_entity_id(v):
+                            results.append((v, _get_line(item, "entity")))
+
+        # Recurse into all other values (cards, sections, elements, card, conditions…)
+        for key, val in obj.items():
+            if key not in ("entity", "entities"):
+                _walk(val, results)
+
+    elif isinstance(obj, list):
+        for item in obj:
+            _walk(item, results)
+
+
+def extract_entity_ids(config: object) -> list[tuple[str, Optional[int]]]:
+    """Walk a Lovelace config (raw ruamel.yaml dict) and return (entity_id, line) pairs.
+
+    Handles entity/entities fields at any nesting depth (cards, sections, elements,
+    conditional conditions, stack cards, etc.).
+    """
+    results: list[tuple[str, Optional[int]]] = []
+    _walk(config, results)
+    return results

hadsync/ha_rest.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import httpx
+
+
+class HARestError(Exception):
+    pass
+
+
+def get_ha_info(ha_url: str, token: str, timeout: float = 10.0) -> dict:
+    """Fetch HA instance info from REST API. Returns dict with 'version', 'location_name', etc."""
+    try:
+        resp = httpx.get(
+            f"{ha_url}/api/config",
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=timeout,
+        )
+        resp.raise_for_status()
+        return resp.json()
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 401:
+            raise HARestError("Authentication failed — token is invalid or expired.") from e
+        raise HARestError(f"HA returned HTTP {e.response.status_code}") from e
+    except httpx.RequestError as e:
+        raise HARestError(f"Connection failed: {e}") from e
+
+
+def get_entity_states(ha_url: str, token: str, timeout: float = 30.0) -> list[dict]:
+    """Fetch all entity states from HA REST API for entity cache population."""
+    try:
+        resp = httpx.get(
+            f"{ha_url}/api/states",
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=timeout,
+        )
+        resp.raise_for_status()
+        return resp.json()
+    except httpx.HTTPStatusError as e:
+        raise HARestError(f"HA returned HTTP {e.response.status_code}") from e
+    except httpx.RequestError as e:
+        raise HARestError(f"Connection failed: {e}") from e

hadsync/ha_ws.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import asyncio
+import json
+
+from websockets.asyncio.client import connect
+from websockets.exceptions import WebSocketException
+
+
+class HAWebSocketError(Exception):
+    pass
+
+
+class HAAuthError(HAWebSocketError):
+    pass
+
+
+class HACommandError(HAWebSocketError):
+    def __init__(self, code: str, message: str) -> None:
+        self.code = code
+        super().__init__(f"{code}: {message}")
+
+
+def _ws_url(ha_url: str) -> str:
+    if ha_url.startswith("https://"):
+        return "wss://" + ha_url[8:] + "/api/websocket"
+    return "ws://" + ha_url[7:] + "/api/websocket"
+
+
+class HAWebSocketClient:
+    """Async context manager for the HA WebSocket API.
+
+    Correct commands for HA 2026.5+:
+      list dashboards  → get_panels (filter component_name=lovelace)
+      fetch config     → lovelace/config  with explicit url_path
+      save config      → lovelace/config/save  with explicit url_path
+    """
+
+    def __init__(self, ha_url: str, token: str, timeout: float = 15.0) -> None:
+        self._url = _ws_url(ha_url)
+        self._token = token
+        self._timeout = timeout
+        self._ws = None
+        self._msg_id = 0
+
+    async def __aenter__(self) -> HAWebSocketClient:
+        try:
+            self._ws = await connect(self._url, open_timeout=self._timeout)
+        except TimeoutError:
+            raise HAWebSocketError(
+                f"Connection timed out after {self._timeout:.0f}s — "
+                f"is HA reachable at {self._url}?"
+            )
+        except ConnectionRefusedError:
+            raise HAWebSocketError(
+                f"Connection refused at {self._url} — "
+                "check ha_url and port in .hadsync.yaml"
+            )
+        except OSError as e:
+            msg = str(e).lower()
+            if "nodename nor servname" in msg or "name or service not known" in msg:
+                raise HAWebSocketError(
+                    f"Cannot resolve hostname — check ha_url in .hadsync.yaml: {self._url}"
+                ) from e
+            raise HAWebSocketError(f"Cannot connect to {self._url}: {e}") from e
+        except WebSocketException as e:
+            raise HAWebSocketError(f"WebSocket error connecting to {self._url}: {e}") from e
+
+        async with asyncio.timeout(self._timeout):
+            try:
+                first = json.loads(await self._ws.recv())
+            except json.JSONDecodeError as e:
+                raise HAWebSocketError(f"HA sent malformed data during handshake: {e}") from e
+
+            if first.get("type") != "auth_required":
+                raise HAWebSocketError(
+                    f"Expected auth_required from HA, got: {first.get('type')!r}"
+                )
+
+            await self._ws.send(json.dumps({"type": "auth", "access_token": self._token}))
+
+            try:
+                auth_resp = json.loads(await self._ws.recv())
+            except json.JSONDecodeError as e:
+                raise HAWebSocketError(f"HA sent malformed auth response: {e}") from e
+
+        if auth_resp.get("type") == "auth_invalid":
+            raise HAAuthError(
+                "Authentication failed — check that HA_TOKEN is a valid long-lived access token. "
+                "Generate one in HA → Profile → Long-Lived Access Tokens."
+            )
+        if auth_resp.get("type") != "auth_ok":
+            raise HAWebSocketError(
+                f"Unexpected auth response from HA: {auth_resp.get('type')!r}"
+            )
+
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        if self._ws is not None:
+            await self._ws.close()
+            self._ws = None
+
+    def _next_id(self) -> int:
+        self._msg_id += 1
+        return self._msg_id
+
+    async def _command(self, **payload: object) -> object:
+        msg_id = self._next_id()
+        await self._ws.send(json.dumps({"id": msg_id, **payload}))
+        async with asyncio.timeout(self._timeout):
+            while True:
+                raw = await self._ws.recv()
+                try:
+                    msg = json.loads(raw)
+                except json.JSONDecodeError as e:
+                    raise HAWebSocketError(f"HA sent malformed JSON: {e}") from e
+                if msg.get("id") != msg_id:
+                    continue  # skip push messages or responses to other commands
+                if not msg.get("success"):
+                    err = msg.get("error", {})
+                    raise HACommandError(
+                        err.get("code", "unknown"),
+                        err.get("message", str(err)),
+                    )
+                return msg.get("result")
+
+    async def get_panels(self) -> dict[str, dict]:
+        """Return all Lovelace dashboard panels keyed by panel id."""
+        result = await self._command(type="get_panels")
+        return {
+            k: v
+            for k, v in (result or {}).items()
+            if isinstance(v, dict) and v.get("component_name") == "lovelace"
+        }
+
+    async def get_dashboard_config(self, url_path: str) -> dict:
+        """Fetch the full Lovelace config for a dashboard by its url_path."""
+        result = await self._command(type="lovelace/config", url_path=url_path)
+        return result or {}
+
+    async def save_dashboard_config(self, url_path: str, config: dict) -> None:
+        """Overwrite the Lovelace config for a dashboard by its url_path."""
+        await self._command(type="lovelace/config/save", url_path=url_path, config=config)

hadsync/output.py

@@ -0,0 +1,20 @@
+from rich.console import Console
+
+console = Console()
+_err_console = Console(stderr=True)
+
+
+def success(msg: str) -> None:
+    console.print(f"[green]✔[/green]  {msg}")
+
+
+def error(msg: str) -> None:
+    _err_console.print(f"[red]✗[/red]  {msg}")
+
+
+def warn(msg: str) -> None:
+    console.print(f"[yellow]⚠[/yellow]  {msg}")
+
+
+def info(msg: str) -> None:
+    console.print(f"[dim]ℹ[/dim]  {msg}")

hadsync/schema.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from typing import Iterator, Optional
+
+# ---------------------------------------------------------------------------
+# Known standard Lovelace card types → list of required field names.
+# An empty list means the card has no required fields beyond 'type'.
+# ---------------------------------------------------------------------------
+KNOWN_CARD_TYPES: dict[str, list[str]] = {
+    "alarm-panel":       ["entity"],
+    "attribute":         [],
+    "button":            [],
+    "calendar":          [],
+    "cast":              [],
+    "conditional":       ["conditions", "card"],
+    "divider":           [],
+    "entities":          ["entities"],
+    "entity":            ["entity"],
+    "entity-filter":     ["entities", "conditions"],
+    "gauge":             ["entity"],
+    "glance":            ["entities"],
+    "grid":              ["cards"],
+    "heading":           [],
+    "history-graph":     ["entities"],
+    "horizontal-stack":  ["cards"],
+    "humidifier":        ["entity"],
+    "iframe":            ["url"],
+    "light":             ["entity"],
+    "logbook":           [],
+    "map":               [],
+    "markdown":          ["content"],
+    "media-control":     ["entity"],
+    "picture":           [],
+    "picture-elements":  [],
+    "picture-entity":    ["entity"],
+    "picture-glance":    ["entities"],
+    "plant-status":      ["entity"],
+    "sensor":            ["entity"],
+    "shopping-list":     [],
+    "statistic":         ["entity", "stat_type"],
+    "statistics-graph":  ["entities"],
+    "thermostat":        ["entity"],
+    "tile":              ["entity"],
+    "todo-list":         [],
+    "vertical-stack":    ["cards"],
+    "weather-forecast":  ["entity"],
+    # HA 2024+
+    "area":              ["area"],
+    "energy-date-selection": [],
+    "input-button":      ["entity"],
+}
+
+
+def _walk_cards(obj: object) -> Iterator[dict]:
+    """Yield every card dict in a Lovelace config, at any nesting depth.
+
+    Descends into cards[], sections[].cards[], card (conditional),
+    and row (entity-filter template).
+    Views are iterated but view-level fields are not yielded as cards.
+    """
+    if isinstance(obj, dict):
+        for view in obj.get("views", []):
+            if isinstance(view, dict):
+                yield from _walk_cards(view)
+
+        for card in obj.get("cards", []):
+            if isinstance(card, dict):
+                yield card
+                yield from _walk_cards(card)
+
+        for section in obj.get("sections", []):
+            if isinstance(section, dict):
+                for card in section.get("cards", []):
+                    if isinstance(card, dict):
+                        yield card
+                        yield from _walk_cards(card)
+
+        if "card" in obj and isinstance(obj["card"], dict):
+            yield obj["card"]
+            yield from _walk_cards(obj["card"])
+
+        if "row" in obj and isinstance(obj["row"], dict):
+            yield obj["row"]
+            yield from _walk_cards(obj["row"])
+
+    elif isinstance(obj, list):
+        for item in obj:
+            yield from _walk_cards(item)
+
+
+def _get_line(container: object, key: str) -> Optional[int]:
+    try:
+        lc = getattr(container, "lc", None)
+        if lc is None:
+            return None
+        return lc.key(key)[0] + 1
+    except Exception:
+        return None
+
+
+def validate_cards(
+    config: object,
+    custom_card_types: list[str] | None = None,
+) -> list[tuple[str, str, Optional[int]]]:
+    """Walk all cards and return (severity, message, line) tuples.
+
+    Checks:
+      - Each card has a 'type' field
+      - Known card types have their required fields present
+      - Unknown card types (not custom:*) are flagged
+
+    custom_card_types: extra type prefixes to treat as valid beyond 'custom:'.
+    """
+    extra_prefixes = tuple(custom_card_types or [])
+    issues: list[tuple[str, str, Optional[int]]] = []
+
+    for card in _walk_cards(config):
+        card_type = card.get("type")
+
+        if card_type is None:
+            issues.append(("WARN", "Card is missing required 'type' field", _get_line(card, "type")))
+            continue
+
+        # custom:* and user-allowlisted prefixes — skip schema check
+        if card_type.startswith("custom:") or (extra_prefixes and card_type.startswith(extra_prefixes)):
+            continue
+
+        if card_type not in KNOWN_CARD_TYPES:
+            line = _get_line(card, "type")
+            issues.append(("WARN", f"Unknown card type: '{card_type}'", line))
+            continue
+
+        for required in KNOWN_CARD_TYPES[card_type]:
+            if required not in card:
+                line = _get_line(card, "type")
+                issues.append(("WARN", f"Card '{card_type}' is missing field '{required}'", line))
+
+    return issues