hadsync 0.2.2__py3-none-any.whl

hadsync/state.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+STATE_FILENAME = ".hadsync-state.json"
+
+
+def _load(workspace: Path) -> dict:
+    path = workspace / STATE_FILENAME
+    if not path.exists():
+        return {"dashboards": {}}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {"dashboards": {}}
+
+
+def _save(workspace: Path, state: dict) -> None:
+    path = workspace / STATE_FILENAME
+    path.write_text(json.dumps(state, indent=2), encoding="utf-8")
+
+
+def record_pull(
+    workspace: Path,
+    url_path: str,
+    ha_config_hash: str | None = None,
+) -> None:
+    state = _load(workspace)
+    existing = state["dashboards"].get(url_path, {})
+    entry: dict = {
+        **existing,
+        "last_pull": datetime.now(timezone.utc).isoformat(),
+    }
+    if ha_config_hash is not None:
+        entry["ha_config_hash"] = ha_config_hash
+    state["dashboards"][url_path] = entry
+    _save(workspace, state)
+
+
+def record_push(workspace: Path, url_path: str) -> None:
+    state = _load(workspace)
+    existing = state["dashboards"].get(url_path, {})
+    state["dashboards"][url_path] = {
+        **existing,
+        "last_push": datetime.now(timezone.utc).isoformat(),
+    }
+    _save(workspace, state)
+
+
+def get_dashboard_state(workspace: Path, url_path: str) -> dict:
+    return _load(workspace)["dashboards"].get(url_path, {})
+
+
+def get_all_states(workspace: Path) -> dict[str, dict]:
+    return _load(workspace).get("dashboards", {})

hadsync/validator.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+
+class Severity(str, Enum):
+    ERROR = "ERROR"
+    WARN = "WARN"
+
+
+@dataclass
+class ValidationIssue:
+    severity: Severity
+    message: str
+    line: Optional[int] = None
+
+    def __str__(self) -> str:
+        loc = f" (line {self.line})" if self.line else ""
+        return f"[{self.severity.value}] {self.message}{loc}"
+
+
+# ---------------------------------------------------------------------------
+# Phase 1 — YAML syntax + structural checks
+# ---------------------------------------------------------------------------
+
+def validate(path: Path) -> list[ValidationIssue]:
+    """Phase 1: YAML syntax + structural checks. No HA connection required."""
+    if not path.exists():
+        return [ValidationIssue(Severity.ERROR, f"File not found: {path}")]
+
+    from ruamel.yaml import YAML
+    _yaml = YAML()
+    try:
+        config = _yaml.load(path)
+    except Exception as e:
+        mark = getattr(getattr(e, "problem_mark", None), "line", None)
+        line = mark + 1 if mark is not None else None
+        problem = getattr(e, "problem", str(e))
+        return [ValidationIssue(Severity.ERROR, f"YAML syntax error: {problem}", line)]
+
+    if config is None:
+        return [ValidationIssue(Severity.ERROR, "File is empty")]
+
+    if not isinstance(config, dict):
+        return [ValidationIssue(Severity.ERROR, "Config must be a YAML mapping, not a list or scalar")]
+
+    issues: list[ValidationIssue] = []
+
+    if "views" not in config:
+        issues.append(ValidationIssue(Severity.ERROR, "Missing required key: 'views'"))
+        return issues
+
+    views = config["views"]
+    if not isinstance(views, list):
+        issues.append(ValidationIssue(Severity.ERROR, "'views' must be a list"))
+        return issues
+
+    if len(views) == 0:
+        issues.append(ValidationIssue(
+            Severity.WARN,
+            "Dashboard has 0 views — pushing will wipe all content from this dashboard in HA",
+        ))
+
+    for i, view in enumerate(views):
+        if not isinstance(view, dict):
+            issues.append(ValidationIssue(Severity.ERROR, f"views[{i}] must be a mapping"))
+
+    return issues
+
+
+# ---------------------------------------------------------------------------
+# Phase 2 — Entity ID existence checks against local cache
+# ---------------------------------------------------------------------------
+
+def validate_entities(
+    path: Path,
+    workspace: Path,
+    warn_on_unknown: bool = True,
+    max_age_days: int = 7,
+) -> list[ValidationIssue]:
+    """Phase 2: check entity_id references in a lovelace.yaml against the cache.
+
+    Returns an empty list if the entity cache does not exist (Phase 2 silently
+    skipped — user must run 'hadsync entities refresh' to enable this check).
+    """
+    from hadsync.entities import (
+        cache_age_days, entity_id_exists, extract_entity_ids, load_entity_cache,
+    )
+
+    issues: list[ValidationIssue] = []
+
+    # Require an existing cache — skip silently if absent (not an error)
+    cache = load_entity_cache(workspace)
+    if not cache.get("entities"):
+        return []
+
+    age = cache_age_days(workspace)
+    if age is not None and age > max_age_days:
+        issues.append(ValidationIssue(
+            Severity.WARN,
+            f"Entity cache is {age:.0f} day(s) old (limit: {max_age_days}) — "
+            "run 'hadsync entities refresh'",
+        ))
+
+    # Load raw YAML to keep ruamel.yaml line info for reporting
+    from ruamel.yaml import YAML
+    _yaml = YAML()
+    try:
+        config = _yaml.load(path)
+    except Exception:
+        return issues  # syntax errors are caught by Phase 1 validate()
+
+    if not isinstance(config, dict):
+        return issues
+
+    seen: set[str] = set()
+    severity = Severity.WARN if warn_on_unknown else Severity.ERROR
+
+    for entity_id, line in extract_entity_ids(config):
+        if entity_id in seen:
+            continue
+        seen.add(entity_id)
+        if not entity_id_exists(workspace, entity_id):
+            issues.append(ValidationIssue(
+                severity,
+                f"Unknown entity: {entity_id}",
+                line,
+            ))
+
+    return issues
+
+
+# ---------------------------------------------------------------------------
+# Phase 3 — Card type and required-field schema checks
+# ---------------------------------------------------------------------------
+
+def validate_schema(
+    path: Path,
+    custom_card_types: list[str] | None = None,
+) -> list[ValidationIssue]:
+    """Phase 3: check card types and required fields against the bundled schema.
+
+    custom:* prefixed types are always allowed. Additional prefixes can be
+    passed via custom_card_types (mirrors validation.custom_card_types config).
+    """
+    from ruamel.yaml import YAML
+    from hadsync.schema import validate_cards
+
+    _yaml = YAML()
+    try:
+        config = _yaml.load(path)
+    except Exception:
+        return []  # syntax errors caught by Phase 1
+
+    if not isinstance(config, dict):
+        return []
+
+    return [
+        ValidationIssue(Severity[sev], msg, line)
+        for sev, msg, line in validate_cards(config, custom_card_types)
+    ]
+
+
+def has_errors(issues: list[ValidationIssue]) -> bool:
+    return any(i.severity == Severity.ERROR for i in issues)

hadsync/watcher.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from watchdog.events import FileSystemEventHandler
+from watchdog.observers import Observer
+
+import hadsync.output as output
+from hadsync.config import Config
+from hadsync.converter import LOVELACE_FILENAME, count_cards, normalize, yaml_file_to_config
+from hadsync.validator import Severity, has_errors, validate, validate_entities, validate_schema
+
+
+class _DashboardHandler(FileSystemEventHandler):
+    def __init__(
+        self,
+        cfg: Config,
+        auto_push: bool,
+        filter_id: Optional[str],
+    ) -> None:
+        self._cfg = cfg
+        self._auto_push = auto_push
+        self._filter_id = filter_id
+        self._last: dict[str, float] = {}
+        self._debounce = 1.5  # seconds — absorbs rapid consecutive save events
+
+    def on_modified(self, event) -> None:  # type: ignore[override]
+        if event.is_directory:
+            return
+        path = Path(event.src_path)
+        if path.name != LOVELACE_FILENAME:
+            return
+
+        url_path = path.parent.name
+        if self._filter_id and url_path != self._filter_id:
+            return
+
+        now = time.monotonic()
+        key = str(path)
+        if now - self._last.get(key, 0) < self._debounce:
+            return
+        self._last[key] = now
+
+        self._handle(path, url_path)
+
+    def _handle(self, yaml_path: Path, url_path: str) -> None:
+        ts = datetime.now().strftime("%H:%M:%S")
+        output.console.print(f"\n[dim]{ts}[/dim]  [bold cyan]{url_path}[/bold cyan]  saved")
+
+        try:
+            self._validate_and_push(yaml_path, url_path)
+        except Exception as e:
+            # Catch unexpected errors so the watchdog observer thread keeps running.
+            # A crash here would silently stop all future watch events.
+            output.error(f"  Watch handler crashed unexpectedly: {e}")
+
+    def _validate_and_push(self, yaml_path: Path, url_path: str) -> None:
+        cfg = self._cfg
+        issues = validate(yaml_path)
+        issues += validate_entities(
+            yaml_path, cfg.workspace,
+            warn_on_unknown=cfg.validation.warn_on_unknown_entities,
+            max_age_days=cfg.validation.entity_cache_max_age_days,
+        )
+        issues += validate_schema(yaml_path, cfg.validation.custom_card_types)
+
+        if not issues:
+            output.success("  Validation passed")
+        else:
+            for issue in issues:
+                fn = output.error if issue.severity == Severity.ERROR else output.warn
+                fn(f"  {issue}")
+
+        if self._auto_push and not has_errors(issues):
+            try:
+                asyncio.run(self._push(yaml_path, url_path))
+            except Exception as e:
+                output.error(f"  Auto-push failed: {e}")
+
+    async def _push(self, yaml_path: Path, url_path: str) -> None:
+        from hadsync.ha_ws import HAWebSocketClient
+        from hadsync.state import record_push
+
+        local_config = normalize(yaml_file_to_config(yaml_path))
+        async with HAWebSocketClient(self._cfg.ha_url, self._cfg.ha_token) as client:
+            ha_config = normalize(await client.get_dashboard_config(url_path))
+            if local_config == ha_config:
+                output.info("  Already up to date — nothing pushed")
+                return
+            await client.save_dashboard_config(url_path, local_config)
+            record_push(self._cfg.workspace, url_path)
+            n_views, n_cards = count_cards(local_config)
+            output.success(f"  Auto-pushed ({n_views} views, {n_cards} cards)")
+
+
+def run_watch(cfg: Config, auto_push: bool, filter_id: Optional[str]) -> None:
+    """Start the filesystem watcher. Blocks until Ctrl-C."""
+    handler = _DashboardHandler(cfg, auto_push, filter_id)
+    observer = Observer()
+    observer.schedule(handler, str(cfg.workspace), recursive=True)
+    observer.start()
+
+    mode = "validate + auto-push" if auto_push else "validate on save"
+    output.success(f"Watching {cfg.workspace}  [{mode}]")
+    output.info("Press Ctrl-C to stop.")
+
+    try:
+        while True:
+            time.sleep(0.5)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        observer.stop()
+        observer.join()
+        output.console.print("\n[dim]Watch stopped.[/dim]")