feat: add Home Assistant Event entity for command errors

Closes #272. When a command to the vehicle fails, a JSON event is now
published to the command/error topic so Home Assistant users can build
automations around command failures.

Changes:
- Add _publish_event() to HA discovery base for MQTT Event entities
- Register a "Command error" diagnostic event entity in discovery
- Publish error events from all failure paths in VehicleCommandHandler
- Wrap error event publishing in try-except to prevent masking original errors
- Cover the "no handler found" path with error events too

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: nanomad

src/handlers/vehicle_command.py

@@ -2,7 +2,7 @@
 
 from dataclasses import dataclass
 import logging
-from typing import TYPE_CHECKING, Final
+from typing import TYPE_CHECKING, Any, Final
 
 from saic_ismart_client_ng.exceptions import SaicApiException, SaicLogoutException
 
@@ -57,13 +57,30 @@ def __init__(
     def publisher(self) -> Publisher:
         return self.vehicle_state.publisher
 
+    def __publish_command_error(self, command: str, detail: str) -> None:
+        try:
+            error_topic = self.vehicle_state.get_topic(mqtt_topics.COMMAND_ERROR)
+            event_payload: dict[str, Any] = {
+                "event_type": "command_error",
+                "command": command,
+                "detail": detail,
+            }
+            self.publisher.publish_json(error_topic, event_payload)
+        except Exception:
+            LOG.warning(
+                "Failed to publish command error event for command %s",
+                command,
+                exc_info=True,
+            )
+
     async def handle_mqtt_command(self, *, topic: str, payload: str) -> None:
         analyzed_topic = self.__get_command_topics(topic)
         handler = self.__command_handlers.get(analyzed_topic.command_no_vin)
         if not handler:
             msg = f"No handler found for command topic {analyzed_topic.command_no_vin}"
             self.publisher.publish_str(analyzed_topic.response_no_global, msg)
             LOG.error(msg)
+            self.__publish_command_error(analyzed_topic.command_no_vin, msg)
         else:
             await self.__execute_mqtt_command_handler(
                 handler=handler, payload=payload, analyzed_topic=analyzed_topic
@@ -92,17 +109,20 @@ async def __execute_mqtt_command_handler(
         except MqttGatewayException as e:
             self.publisher.publish_str(result_topic, f"Failed: {e.message}")
             LOG.exception(e.message, exc_info=e)
+            self.__publish_command_error(topic, e.message)
         except SaicLogoutException:
             LOG.warning(
                 "API Client was logged out, attempting immediate relogin and retry"
             )
             try:
                 await self.relogin_handler.force_login()
             except Exception as login_err:
+                detail = f"relogin failed ({login_err})"
                 self.publisher.publish_str(
-                    result_topic, f"Failed: relogin failed ({login_err})"
+                    result_topic, f"Failed: {detail}"
                 )
                 LOG.error("Immediate relogin failed", exc_info=login_err)
+                self.__publish_command_error(topic, detail)
                 return
             try:
                 execution_result = await handler.handle(payload)
@@ -115,20 +135,24 @@ async def __execute_mqtt_command_handler(
                 if execution_result.clear_command:
                     self.publisher.clear_topic(topic_no_global)
             except Exception as retry_err:
+                detail = str(retry_err)
                 self.publisher.publish_str(
-                    result_topic, f"Failed: {retry_err}"
+                    result_topic, f"Failed: {detail}"
                 )
                 LOG.error(
                     "Command retry after relogin failed", exc_info=retry_err
                 )
+                self.__publish_command_error(topic, detail)
         except SaicApiException as se:
             self.publisher.publish_str(result_topic, f"Failed: {se.message}")
             LOG.exception(se.message, exc_info=se)
+            self.__publish_command_error(topic, se.message)
         except Exception as se:
             self.publisher.publish_str(result_topic, "Failed unexpectedly")
             LOG.exception(
                 "handle_mqtt_command failed with an unexpected exception", exc_info=se
             )
+            self.__publish_command_error(topic, str(se))
 
     def __get_command_topics(self, topic: str) -> _MqttCommandTopic:
         global_topic_removed = topic.removeprefix(self.global_mqtt_topic).removeprefix(

src/integrations/home_assistant/base.py

@@ -230,6 +230,34 @@ def _publish_lock(
             "lock", name, payload, custom_availability
         )
 
+    def _publish_event(
+        self,
+        topic: str,
+        name: str,
+        event_types: list[str],
+        *,
+        enabled: bool = True,
+        entity_category: str | None = None,
+        device_class: str | None = None,
+        icon: str | None = None,
+        custom_availability: HaCustomAvailabilityConfig | None = None,
+    ) -> str:
+        payload: dict[str, Any] = {
+            "state_topic": self._get_state_topic(topic),
+            "event_types": event_types,
+            "enabled_by_default": enabled,
+        }
+        if entity_category is not None:
+            payload["entity_category"] = entity_category
+        if device_class is not None:
+            payload["device_class"] = device_class
+        if icon is not None:
+            payload["icon"] = icon
+
+        return self._publish_ha_discovery_message(
+            "event", name, payload, custom_availability
+        )
+
     def _publish_sensor(
         self,
         topic: str,

src/integrations/home_assistant/discovery.py

@@ -327,6 +327,15 @@ def __publish_ha_discovery_messages_real(self) -> None:
         )
         self.__publish_lights_sensors()
 
+        # Command error event
+        self._publish_event(
+            mqtt_topics.COMMAND_ERROR,
+            "Command error",
+            ["command_error"],
+            entity_category="diagnostic",
+            icon="mdi:alert-circle",
+        )
+
         LOG.debug("Completed publishing Home Assistant discovery messages")
 
     def __publish_drivetrain_charging_sensors(self) -> None:

src/mqtt_topics.py

@@ -179,4 +179,7 @@
 TYRES_REAR_LEFT_PRESSURE = TYRES + "/rearLeftPressure"
 TYRES_REAR_RIGHT_PRESSURE = TYRES + "/rearRightPressure"
 
+COMMAND = "command"
+COMMAND_ERROR = COMMAND + "/error"
+
 VEHICLES = "vehicles"