Replace Guardian disable_ap and enable_ap services with a switch (#75034)

* Starter buttons

* Ready to go

* Replace Guardian `disable_ap` and `enable_ap` services with a switch

* Clean up how actions are stored

* Make similar to buttons

* Remove service definitions

* Docstring

* Docstring

* flake8

* Add repairs item

* Add a repairs issue to notify of removed entity

* Add entity replacement strategy

* Fix repairs import

* Update deprecation version

* Remove breaking change

* Include future breaking change version

* Naming

homeassistant/components/guardian/util.py

@@ -2,7 +2,8 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Awaitable, Callable
+from collections.abc import Awaitable, Callable, Iterable
+from dataclasses import dataclass
 from datetime import timedelta
 from typing import Any, cast
 
@@ -11,16 +12,72 @@ from aioguardian.errors import GuardianError
 
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant, callback
+from homeassistant.helpers import entity_registry
 from homeassistant.helpers.dispatcher import async_dispatcher_connect
+from homeassistant.helpers.issue_registry import IssueSeverity, async_create_issue
 from homeassistant.helpers.update_coordinator import DataUpdateCoordinator, UpdateFailed
 
-from .const import LOGGER
+from .const import DOMAIN, LOGGER
 
 DEFAULT_UPDATE_INTERVAL = timedelta(seconds=30)
 
 SIGNAL_REBOOT_REQUESTED = "guardian_reboot_requested_{0}"
 
 
+@dataclass
+class EntityDomainReplacementStrategy:
+    """Define an entity replacement."""
+
+    old_domain: str
+    old_unique_id: str
+    replacement_entity_id: str
+    breaks_in_ha_version: str
+    remove_old_entity: bool = True
+
+
+@callback
+def async_finish_entity_domain_replacements(
+    hass: HomeAssistant,
+    entry: ConfigEntry,
+    entity_replacement_strategies: Iterable[EntityDomainReplacementStrategy],
+) -> None:
+    """Remove old entities and create a repairs issue with info on their replacement."""
+    ent_reg = entity_registry.async_get(hass)
+    for strategy in entity_replacement_strategies:
+        try:
+            [registry_entry] = [
+                registry_entry
+                for registry_entry in ent_reg.entities.values()
+                if registry_entry.config_entry_id == entry.entry_id
+                and registry_entry.domain == strategy.old_domain
+                and registry_entry.unique_id == strategy.old_unique_id
+            ]
+        except ValueError:
+            continue
+
+        old_entity_id = registry_entry.entity_id
+        translation_key = "replaced_old_entity"
+
+        async_create_issue(
+            hass,
+            DOMAIN,
+            f"{translation_key}_{old_entity_id}",
+            breaks_in_ha_version=strategy.breaks_in_ha_version,
+            is_fixable=True,
+            is_persistent=True,
+            severity=IssueSeverity.WARNING,
+            translation_key=translation_key,
+            translation_placeholders={
+                "old_entity_id": old_entity_id,
+                "replacement_entity_id": strategy.replacement_entity_id,
+            },
+        )
+
+        if strategy.remove_old_entity:
+            LOGGER.info('Removing old entity: "%s"', old_entity_id)
+            ent_reg.async_remove(old_entity_id)
+
+
 class GuardianDataUpdateCoordinator(DataUpdateCoordinator[dict]):
     """Define an extended DataUpdateCoordinator with some Guardian goodies."""