feat: entry.runtime_data ShieldConnectionManager lifecycle — passive when ADB unavailable, close on HA stop + unload; adb_session adapter docstring

custom_components/nvidia_shield/__init__.py

@@ -1,23 +1,87 @@
-"""The Nvidia Shield integration."""
+"""The Nvidia Shield integration.
+
+Phase 1 architecture (docs/MVP_PLAN.md §2): the entry owns a single
+ShieldConnectionManager stored in ``entry.runtime_data`` — the persistent ADB
+socket and all ADB-derived state live there, not on the entities. Entities are
+thin callback-views over the manager's StateStore.
+
+ADB is optional: a failed/absent ADB connection never blocks setup (no
+ConfigEntryNotReady) — the manager retries in the background, or stays
+passive until the user pairs via the Pair ADB button.
+"""
 
 import logging
+import os
 
 from homeassistant.config_entries import ConfigEntry
-from homeassistant.const import Platform
+from homeassistant.const import EVENT_HOMEASSISTANT_STOP, Platform
 from homeassistant.core import HomeAssistant
 
-from .const import DOMAIN
+from .adb_session import AdbMediaSessionPoller
+from .connection import ShieldConnectionManager
+from .const import CONF_ADB_ENABLED, DOMAIN
+from .helpers import resolve_adb_config
 
 _LOGGER = logging.getLogger(__name__)
 
 PLATFORMS = [Platform.MEDIA_PLAYER, Platform.SENSOR, Platform.BUTTON]
 
 
+def _build_poller_factory(hass: HomeAssistant, entry: ConfigEntry):
+    """Poller factory when ADB is configured AND usable today, else None.
+
+    Returning None leaves the manager passive: the entry still sets up, the
+    entities simply see no ADB state. The Pair ADB button / reconfigure
+    triggers a reload that re-evaluates this.
+    """
+    if not entry.options.get(CONF_ADB_ENABLED, False):
+        return None
+
+    adb = resolve_adb_config(hass, entry)
+    if adb is None:
+        _LOGGER.warning(
+            "ADB enabled but no host resolvable for entry %s — continuing "
+            "without ADB state.",
+            entry.title,
+        )
+        return None
+
+    # Only auto-connect when a key already exists — an ADB handshake against
+    # an unpaired device is pointless noise (pairing happens via the Pair ADB
+    # button / config flow, untouched).
+    key_path_ready = await hass.async_add_executor_job(
+        os.path.exists, adb.key_path
+    )
+    if not key_path_ready:
+        _LOGGER.info(
+            "ADB key not found for entry %s — skipping auto-connect. "
+            "Use the Pair ADB button or reconfigure the integration.",
+            entry.title,
+        )
+        return None
+
+    return lambda: AdbMediaSessionPoller(adb.host, adb.port, adb.key_path)
+
+
 async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     """Set up Nvidia Shield from a config entry."""
     hass.data.setdefault(DOMAIN, {})
     hass.data[DOMAIN][entry.entry_id] = entry
 
+    manager = ShieldConnectionManager(
+        hass, entry, poller_factory=_build_poller_factory(hass, entry)
+    )
+    entry.runtime_data = manager
+    await manager.async_start()
+
+    # Close the persistent socket on Home Assistant stop as well as unload.
+    async def _close_on_hass_stop(_event) -> None:
+        await manager.async_stop()
+
+    entry.async_on_unload(
+        hass.bus.async_listen_once(EVENT_HOMEASSISTANT_STOP, _close_on_hass_stop)
+    )
+
     await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
 
     entry.async_on_unload(entry.add_update_listener(_async_update_listener))
@@ -30,6 +94,10 @@ async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     unload_ok = await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
 
     if unload_ok:
+        manager = getattr(entry, "runtime_data", None)
+        if manager is not None:
+            await manager.async_stop()
+            entry.runtime_data = None
         hass.data[DOMAIN].pop(entry.entry_id)
 
     return unload_ok

custom_components/nvidia_shield/adb_session.py

@@ -1,7 +1,12 @@
-"""ADB media session reader for NVIDIA Shield.
+"""ADB session adapter for NVIDIA Shield.
 
-Thin wrapper around ha_adb_common.AdbClientBase — adds the Shield-specific
-`poll()` method that calls wake check + media session in sequence.
+Since Phase 1 this module is a thin adapter on top of ha_adb_common:
+
+- ``ensure_adb_key`` (re-exported here for the config flow / Pair ADB button)
+  does the one-time key-material setup — the pairing flow stays untouched.
+- ``AdbMediaSessionPoller`` remains the protocol-level ADB client used by the
+  ShieldConnectionManager (connection.py) and one-shot pairing connects. The
+  polling loop itself lives in the connection manager, not here.
 
 Re-exports MediaSessionInfo and ensure_adb_key for existing importers.
 """

custom_components/nvidia_shield/connection.py

@@ -115,6 +115,21 @@ class ShieldConnectionManager:
         self._failures = 0
         self._down_since = False  # listeners already told the connection is down
 
+    # ── One-shot connection test (pairing UX) ──
+
+    @staticmethod
+    async def test_connect(host: str, port: int, key_path: str) -> bool:
+        """Single-shot ADB connect used by the config-flow pairing step.
+
+        Throws away the poller immediately — the config flow runs before any
+        entry exists, so it must never touch an entry's persistent socket.
+        """
+        poller = AdbMediaSessionPoller(host, port, key_path)
+        try:
+            return await poller.connect()
+        finally:
+            await poller.disconnect()
+
     # ── Introspection (thin views for entities) ──
 
     @property