feat: Automatically surface component updates in HACS after a server update (#2166)

* feat: Automatically surface component updates in HACS after a server update

HACS refreshes a custom repository's release data only about every 48
hours, so the component update paired with each server release stayed
invisible unless the user ran the HACS UI's "Update information" by
hand. The existing component-side nudge (hacs_nudge.py) only covers the
embedded server.

Server side: on startup, when the server version changed since the last
recorded nudge or a newer release is pending, send hacs/repository/refresh
for every installed candidate repository entry (dedicated mirror and
legacy main-repo path), over the existing admin WebSocket. Advisory
only: failures degrade to debug logs, a marker file in the data dir
throttles repeat passes, embedded installs are skipped (hacs_nudge
covers them), and HA_MCP_DISABLE_UPDATE_CHECK opts out.

Component side: the nudge now refreshes ALL installed candidate
repositories instead of the first match, so a legacy-path install is
refreshed even when the mirror entry is also present.

* fix: Address review findings on the startup HACS nudge

- An all-candidates-failed refresh pass now reports undetermined instead
  of complete, so the retry schedule and next startup still run.
- unknown_command is retried through the whole schedule before HACS is
  recorded absent: a still-booting HA returns the same reply before HACS
  registers its WebSocket handlers.
- HomeAssistantCommandTimeout joins the retry classification (it is a
  sibling of HomeAssistantCommandError, not a subclass).
- Per-user OAuth mode is skipped: it holds no server-level HA credential
  for the nudge to use.
- The marker records the HA URL, so servers sharing a data dir but
  targeting different instances cannot suppress each other's nudge.
- Drift-guard test pins CANDIDATE_REPO_FULL_NAMES to the component's
  constants.

* fix: Per-target refresh markers and websocket-closure retries

- One marker file per Home Assistant target (URL-hashed filename):
  server configs sharing a data dir but pointing at different instances
  no longer invalidate each other's marker on alternating spawns. The
  scalar ha_url marker field and its _nudge_due check are gone — the
  scoping lives in the path.
- Raw websocket exceptions join the retry classification: send_command
  deliberately re-raises the original exception on a mid-send closure,
  which previously escaped the retry loop to the outer advisory catch.

* docs(internal): Correct the both-installed comment on the refresh loops

Two candidate entries read installed only when the mirror was downloaded
without removing the legacy record — HACS blocks adding the same
repository twice but has no same-domain guard. A legacy-to-mirror
migration leaves the mirror added but not downloaded, which is one
installed candidate, so calling that state 'mid migration' was wrong on
both loops.

---------

Co-authored-by: kingpanther13 <kingpanther13@users.noreply.github.com>

Author: kingpanther13

custom_components/ha_mcp_tools/hacs_nudge.py

@@ -26,7 +26,7 @@
 from __future__ import annotations
 
 import logging
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from .const import (
     DOMAIN,
@@ -113,14 +113,15 @@ async def async_nudge_hacs_refresh(hass: HomeAssistant, target_version: str) ->
 
 
 async def _async_force_hacs_repo_refresh(hass: HomeAssistant) -> bool:
-    """Run HACS's "Update information" force-refresh for this component's repo.
-
-    Returns True when a tracked repository was found and its refresh completed,
-    False when there is nothing to refresh (no HACS, or no INSTALLED repository
-    under either candidate name). Reaches into HACS internals —
-    the top-level lookups are ``getattr``-guarded so a wholly different HACS
-    shape returns False cleanly; anything deeper that changes shape raises and is
-    swallowed by :func:`async_nudge_hacs_refresh`.
+    """Run HACS's "Update information" force-refresh for this component's repos.
+
+    Returns True when at least one INSTALLED tracked repository completed its
+    refresh, False when there was nothing to refresh (no HACS, or no installed
+    repository under either candidate name) or every candidate's refresh
+    failed. Reaches into HACS internals — the top-level lookups are
+    ``getattr``-guarded so a wholly different HACS shape returns False cleanly;
+    anything deeper that changes shape raises and is swallowed by
+    :func:`async_nudge_hacs_refresh`.
     """
     hacs = hass.data.get("hacs")
     if hacs is None:
@@ -133,7 +134,7 @@ async def _async_force_hacs_repo_refresh(hass: HomeAssistant) -> bool:
     if get_by_full_name is None:
         return False
 
-    repository = None
+    installed_candidates: list[Any] = []
     for full_name in _CANDIDATE_REPO_FULL_NAMES:
         candidate = get_by_full_name(full_name)
         if candidate is None:
@@ -146,20 +147,41 @@ async def _async_force_hacs_repo_refresh(hass: HomeAssistant) -> bool:
         # only an installed candidate counts (review finding).
         if not getattr(getattr(candidate, "data", None), "installed", False):
             continue
-        repository = candidate
-        break
-    if repository is None:
+        installed_candidates.append(candidate)
+    if not installed_candidates:
         return False
 
-    # The repository's "Update information" menu action: re-fetch its release
-    # data ignoring cached state, then push the fresh data to HACS's own update
-    # entity so Home Assistant advertises the component update immediately.
-    await repository.update_repository(ignore_issues=True, force=True)
-    # The refresh is complete at this point; the listener push below only
-    # re-publishes the fresh data to HACS's update entity sooner. Guarded
-    # separately so a HACS shape change here cannot void the completed
-    # refresh's throttle and re-run the network fetch every pass (review
-    # finding).
+    # Every installed candidate, not just the first. Two entries read
+    # installed when the mirror was downloaded without removing the legacy
+    # record — HACS blocks adding the same repository twice but not two
+    # repositories sharing a domain — and each carries its own update entity,
+    # so refreshing only the first left the other stale.
+    refreshed_any = False
+    for repository in installed_candidates:
+        # The repository's "Update information" menu action: re-fetch its
+        # release data ignoring cached state.
+        try:
+            await repository.update_repository(ignore_issues=True, force=True)
+        except Exception:
+            # One candidate's failure must not skip the other's refresh.
+            _LOGGER.debug(
+                "HA-MCP: HACS refresh failed for one candidate repository",
+                exc_info=True,
+            )
+            continue
+        refreshed_any = True
+        _poke_hacs_update_entity(hacs, repository)
+    return refreshed_any
+
+
+def _poke_hacs_update_entity(hacs: Any, repository: Any) -> None:
+    """Push the freshly fetched data to HACS's own update entity.
+
+    The refresh is already complete when this runs; the push only makes Home
+    Assistant advertise the component update sooner. Guarded separately so a
+    HACS shape change here cannot void the completed refresh's throttle and
+    re-run the network fetch every pass (review finding).
+    """
     try:
         coordinators = getattr(hacs, "coordinators", None) or {}
         category = getattr(getattr(repository, "data", None), "category", None)
@@ -171,4 +193,3 @@ async def _async_force_hacs_repo_refresh(hass: HomeAssistant) -> bool:
             "HA-MCP: HACS listener push after the repository refresh failed",
             exc_info=True,
         )
-    return True

src/ha_mcp/__main__.py

@@ -666,6 +666,13 @@ async def _run_with_shutdown(server_coro: Coroutine[Any, Any, Any]) -> None:
     server_task = asyncio.create_task(server_coro)
     shutdown_task = asyncio.create_task(_shutdown_event.wait())
 
+    # Fire-and-forget: ask HACS to surface a paired component update after a
+    # server update (advisory; see hacs_auto_refresh). Not in the wait set —
+    # its completion must not stop the server.
+    from ha_mcp.hacs_auto_refresh import maybe_refresh_hacs_after_update
+
+    hacs_refresh_task = asyncio.create_task(maybe_refresh_hacs_after_update())
+
     try:
         done, pending = await asyncio.wait(
             [server_task, shutdown_task],
@@ -725,7 +732,7 @@ async def _run_with_shutdown(server_coro: Coroutine[Any, Any, Any]) -> None:
             logger.warning("Resource cleanup timed out")
 
         try:
-            await _cancel_tasks(server_task, shutdown_task)
+            await _cancel_tasks(server_task, shutdown_task, hacs_refresh_task)
         except Exception as e:
             # Teardown must never mask the exception being propagated from the
             # try block (Python drops the original if finally raises).

src/ha_mcp/hacs_auto_refresh.py

@@ -0,0 +1,252 @@
+"""Ask HACS to surface the paired component update after a server update.
+
+HACS refreshes a *custom* repository's release data from GitHub only about
+every 48 hours, and the ha_mcp_tools component ships in lockstep with each
+server release — so a freshly updated server can sit for two days next to a
+component update HACS has not noticed yet. The component's own nudge
+(``custom_components/ha_mcp_tools/hacs_nudge.py``) closes that gap only for the
+embedded server, which is where it runs; add-on, Docker, pip and stdio installs
+had no trigger at all. This module is that trigger, server-side.
+
+On startup, when the server version changed since the last recorded nudge (the
+just-updated case) or a newer release is pending, it sends HACS's "Update
+information" refresh (``hacs/repository/refresh``) over the existing admin
+WebSocket for every INSTALLED candidate repository entry.
+
+Fully advisory: every failure degrades to a debug log and nothing here can
+fault startup. A marker file in the data dir records the state the last
+completed pass ran against, so the common case — a per-conversation stdio
+spawn on an unchanged version — costs one file read and no WebSocket traffic.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from ._vendor import websockets
+from ._version import get_version, is_embedded
+from .client.rest_client import (
+    HomeAssistantCommandError,
+    HomeAssistantCommandTimeout,
+    HomeAssistantConnectionError,
+)
+from .config import OAUTH_MODE_TOKEN, get_global_settings
+from .update_check import UpdateInfo, get_update_info, is_update_check_disabled
+from .utils.data_paths import get_data_dir
+
+logger = logging.getLogger(__name__)
+
+# The repository full_names HACS may track the ha_mcp_tools component under —
+# the dedicated mirror first, the legacy main-repo path second. Values are
+# duplicated from custom_components/ha_mcp_tools/const.py (HACS_MIRROR_ /
+# HACS_LEGACY_REPO_FULL_NAME): the server package cannot import the component.
+CANDIDATE_REPO_FULL_NAMES = (
+    "homeassistant-ai/ha-mcp-integration",
+    "homeassistant-ai/ha-mcp",
+)
+
+# Marker file (in the ha-mcp data dir) recording the state the last completed
+# nudge ran against. Written only on a completed pass, so a failed pass (HA
+# still booting, HACS not loaded yet) is retried on the next startup. One file
+# PER Home Assistant target: server configs sharing a data dir but pointing at
+# different instances must neither suppress each other's nudge nor invalidate
+# each other's marker on every alternating spawn (review finding).
+MARKER_FILENAME_PREFIX = "hacs_refresh_marker"
+
+# The add-on can start before HA Core finishes booting (and before HACS is
+# loaded), so the first attempts may fail; spread retries over ~8 minutes,
+# then give up until the next startup (the unwritten marker retries then).
+RETRY_DELAYS = (30.0, 60.0, 120.0, 300.0)
+
+
+def _marker_path(ha_url: str) -> Path:
+    digest = hashlib.sha256(ha_url.rstrip("/").encode()).hexdigest()[:12]
+    return get_data_dir() / f"{MARKER_FILENAME_PREFIX}_{digest}.json"
+
+
+def _read_marker(ha_url: str) -> dict[str, Any] | None:
+    """Return the last completed pass's marker, or None when there isn't one."""
+    path = _marker_path(ha_url)
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return None
+    except (OSError, ValueError) as err:
+        logger.debug("Ignoring unreadable HACS refresh marker %s: %s", path, err)
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def _write_marker(ha_url: str, marker: dict[str, Any]) -> None:
+    """Record the state this pass ran against; an unwritable dir just retries."""
+    path = _marker_path(ha_url)
+    try:
+        path.write_text(json.dumps(marker), encoding="utf-8")
+    except OSError as err:
+        logger.debug("Could not write HACS refresh marker %s: %s", path, err)
+
+
+def _nudge_due(
+    current_version: str,
+    info: UpdateInfo | None,
+    marker: dict[str, Any] | None,
+) -> bool:
+    """Decide whether this startup should ask HACS for a refresh.
+
+    Instance scoping lives in the marker PATH (one file per HA target), so a
+    marker handed in here always describes the current instance.
+    """
+    if marker is None:
+        # First run ever, or no pass has ever completed for this HA target.
+        return True
+    if marker.get("server_version") != current_version:
+        # The server was just updated, and the paired component release is
+        # exactly what HACS needs to surface.
+        return True
+    # A release appeared while this build sat idle — surface its component side.
+    return bool(
+        info is not None
+        and info.update_available
+        and marker.get("latest") != info.latest
+    )
+
+
+async def _refresh_installed_candidates() -> dict[str, Any] | None:
+    """Refresh every installed candidate repository; one attempt, no retries.
+
+    Returns the pass result (``hacs`` presence plus the full_names refreshed),
+    or None when the outcome could not be determined.
+    """
+    from .client.websocket_client import get_websocket_client
+    from .tools.hacs_registration import send_hacs_repository_refresh
+
+    ws_client = await get_websocket_client()
+    try:
+        response = await ws_client.send_command("hacs/repositories/list")
+    except HomeAssistantCommandError as err:
+        # HACS not installed at all — HA rejects its commands as unknown. Same
+        # detection as ``_assert_hacs_available`` in tools/tools_hacs.py. Any
+        # other command failure is a real error: let the retry loop see it.
+        if err.code == "unknown_command" or "unknown command" in str(err).lower():
+            return {"hacs": "absent", "refreshed": []}
+        raise
+
+    wanted = {name.lower() for name in CANDIDATE_REPO_FULL_NAMES}
+    refreshed: list[str] = []
+    attempted = 0
+    for repo in response.get("result", []):
+        full_name = (repo.get("full_name") or "").lower()
+        # HACS keeps a record for every ADDED repo but only creates an update
+        # entity for downloaded ones, so refreshing an uninstalled record
+        # lights up nothing.
+        if full_name not in wanted or not repo.get("installed"):
+            continue
+        attempted += 1
+        try:
+            await send_hacs_repository_refresh(ws_client, str(repo["id"]))
+        except Exception as err:
+            # Both entries read installed only when someone downloaded the
+            # mirror without removing the legacy record — HACS guards against
+            # adding the same repository twice but not against two
+            # repositories sharing a domain. Rare, but one failing must not
+            # cost the other its refresh.
+            logger.debug("HACS refresh failed for %s: %s", full_name, err)
+            continue
+        refreshed.append(full_name)
+    if attempted and not refreshed:
+        # Every attempted refresh failed — the pass is undetermined, not
+        # complete. Returning a result here would write the marker and cancel
+        # the retry schedule and the next startup's pass (review finding).
+        return None
+    return {"hacs": "present", "refreshed": refreshed}
+
+
+async def _refresh_with_retries() -> dict[str, Any] | None:
+    """Run the refresh pass, retrying transport failures over ``RETRY_DELAYS``."""
+    absent_result: dict[str, Any] | None = None
+    for delay in (0.0, *RETRY_DELAYS):
+        if delay:
+            await asyncio.sleep(delay)
+        try:
+            result = await _refresh_installed_candidates()
+        except (
+            HomeAssistantConnectionError,
+            HomeAssistantCommandError,
+            HomeAssistantCommandTimeout,
+            # send_command deliberately re-raises the ORIGINAL exception when
+            # the socket closes mid-send (ambiguous-write contract), so raw
+            # websocket closures reach this loop unwrapped (review finding).
+            websockets.exceptions.WebSocketException,
+            OSError,
+        ) as err:
+            logger.debug("HACS repository refresh attempt failed: %s", err)
+            continue
+        if result is None:
+            continue
+        if result["hacs"] == "absent":
+            # ``unknown_command`` also happens while HA is still booting,
+            # before HACS registers its WS handlers — indistinguishable from
+            # no HACS at all. Keep retrying; record absence only once the
+            # schedule is exhausted (review finding).
+            absent_result = result
+            continue
+        return result
+    return absent_result
+
+
+async def maybe_refresh_hacs_after_update() -> None:
+    """Nudge HACS once per startup when the update picture changed."""
+    try:
+        if is_embedded():
+            # The component's own hacs_nudge already covers embedded installs;
+            # running both would double HACS's GitHub fetches.
+            return
+        if is_update_check_disabled():
+            return
+
+        settings = get_global_settings()
+        if settings.homeassistant_token == OAUTH_MODE_TOKEN:
+            # Per-user OAuth mode holds no server-level HA credential — the
+            # nudge would only burn its retry schedule on auth failures.
+            return
+        ha_url = settings.homeassistant_url
+
+        current = get_version()
+        # Normally a cache hit — the startup banner warms the lru_cache — but
+        # offloaded anyway so a cold call can never touch the event loop.
+        info = await asyncio.to_thread(get_update_info)
+        marker = await asyncio.to_thread(_read_marker, ha_url)
+        if not _nudge_due(current, info, marker):
+            return
+
+        result = await _refresh_with_retries()
+        if result is None:
+            logger.debug(
+                "Could not reach HACS to refresh the component repository; "
+                "giving up until next startup"
+            )
+            return
+
+        await asyncio.to_thread(
+            _write_marker,
+            ha_url,
+            {
+                "server_version": current,
+                "latest": info.latest if info else None,
+                "hacs": result["hacs"],
+            },
+        )
+        if result["refreshed"]:
+            logger.info(
+                "Asked HACS to refresh component repository info: %s",
+                ", ".join(result["refreshed"]),
+            )
+    except asyncio.CancelledError:
+        raise
+    except Exception:
+        logger.debug("HACS auto-refresh nudge skipped", exc_info=True)

src/ha_mcp/update_check.py

@@ -79,6 +79,16 @@ def _is_disabled() -> bool:
     return os.environ.get(DISABLE_ENV, "").strip().lower() in _TRUTHY
 
 
+def is_update_check_disabled() -> bool:
+    """Public accessor for the HA_MCP_DISABLE_UPDATE_CHECK opt-out.
+
+    The HACS auto-refresh nudge gates on the same switch: an operator who
+    opted out of update phone-home should not get update-driven side
+    effects either.
+    """
+    return _is_disabled()
+
+
 def _is_newer(latest: str, current: str) -> bool:
     """Return True only when ``latest`` is a strictly higher PEP 440 release.