feat: Add hardened error handling and retries (#2451)

- Closes #1830
 - Closes #2099

tests/card-controller/config/config-manager.test.ts

@@ -75,12 +75,12 @@ describe('ConfigManager', () => {
   });
 
   describe('should handle error when', () => {
-    it('no input', () => {
+    it('should handle no input', () => {
       const manager = new ConfigManager(createCardAPI());
       expect(() => manager.setConfig()).toThrowError(/Invalid configuration/);
     });
 
-    it('invalid configuration', () => {
+    it('should handle invalid configuration', () => {
       const schemaForMock: z.ZodType = advancedCameraCardConfigSchema;
       const spy = vi
         .spyOn(schemaForMock, 'safeParse')
@@ -94,14 +94,14 @@ describe('ConfigManager', () => {
       spy.mockRestore();
     });
 
-    it('invalid configuration with hint', () => {
+    it('should handle invalid configuration with hint', () => {
       const manager = new ConfigManager(createCardAPI());
       expect(() => manager.setConfig({})).toThrowError(
         'Invalid configuration: [\n "type"\n]',
       );
     });
 
-    it('upgradeable', () => {
+    it('should handle upgradeable config', () => {
       const manager = new ConfigManager(createCardAPI());
       expect(() =>
         manager.setConfig({
@@ -150,9 +150,9 @@ describe('ConfigManager', () => {
       displayMode: undefined,
       camera: undefined,
     });
+    expect(api.getIssueManager().reset).toBeCalledWith('config_error');
     expect(api.getMediaLoadedInfoManager().clear).toBeCalled();
     expect(api.getViewManager().reset).toBeCalled();
-    expect(api.getMessageManager().reset).toBeCalled();
     expect(api.getAutomationsManager().addAutomations).toBeCalled();
     expect(api.getStyleManager().updateFromConfig).toBeCalled();
     expect(api.getCardElementManager().update).toBeCalled();
@@ -327,13 +327,14 @@ describe('ConfigManager', () => {
 
       stateManager.setState({ fullscreen: true });
       expect(manager.getConfig()).not.toBeNull();
-      expect(api.getMessageManager().setErrorIfHigherPriority).toBeCalledWith(
-        expect.objectContaining({ message: 'Invalid override configuration' }),
+      expect(api.getIssueManager().trigger).toBeCalledWith(
+        'config_error',
+        expect.objectContaining({ error: expect.any(Error) }),
       );
     });
 
     describe('should uninitialize on override', () => {
-      it('cameras', () => {
+      it('should uninitialize cameras', () => {
         const api = createCardAPI();
         const stateManager = new ConditionStateManager();
         vi.mocked(api.getConditionStateManager).mockReturnValue(stateManager);
@@ -365,7 +366,7 @@ describe('ConfigManager', () => {
         );
       });
 
-      it('cameras_global', () => {
+      it('should uninitialize cameras_global', () => {
         const api = createCardAPI();
         const stateManager = new ConditionStateManager();
         vi.mocked(api.getConditionStateManager).mockReturnValue(stateManager);
@@ -397,7 +398,7 @@ describe('ConfigManager', () => {
         );
       });
 
-      it('live.microphone.always_connected', () => {
+      it('should uninitialize live.microphone.always_connected', () => {
         const api = createCardAPI();
         const stateManager = new ConditionStateManager();
         vi.mocked(api.getConditionStateManager).mockReturnValue(stateManager);

tests/card-controller/config/load-folders.test.ts

@@ -39,6 +39,8 @@ describe('setFoldersFromConfig', () => {
 
     setFoldersFromConfig(api);
 
-    expect(api.getMessageManager().setErrorIfHigherPriority).toBeCalledWith(error);
+    expect(api.getIssueManager().trigger).toBeCalledWith('config_error', {
+      error,
+    });
   });
 });

tests/card-controller/config/overrides-manager.test.ts

@@ -1,6 +1,8 @@
-import { describe, expect, it, vi } from 'vitest';
+import { assert, describe, expect, it, vi } from 'vitest';
 import { OverridesManager } from '../../../src/card-controller/config/overrides-manager';
+import { AdvancedCameraCardConfig } from '../../../src/config/schema/types';
 import { ConditionStateManager } from '../../../src/conditions/state-manager';
+import { AdvancedCameraCardError } from '../../../src/types';
 import { createConfig } from '../../test-utils';
 
 describe('OverridesManager', () => {
@@ -316,30 +318,93 @@ describe('OverridesManager', () => {
     });
   });
 
-  it('should throw on invalid schema', () => {
-    const config = createConfig({
-      overrides: [
-        {
-          conditions: [
-            {
-              condition: 'fullscreen' as const,
-              fullscreen: true,
-            },
-          ],
-        },
-      ],
+  describe('should throw on invalid schema', () => {
+    const runInvalidOverride = (
+      mutate: (config: AdvancedCameraCardConfig) => void,
+    ): AdvancedCameraCardError => {
+      const config = createConfig({
+        overrides: [
+          {
+            conditions: [
+              {
+                condition: 'fullscreen' as const,
+                fullscreen: true,
+              },
+            ],
+          },
+        ],
+      });
+      mutate(config);
+
+      const stateManager = new ConditionStateManager();
+      stateManager.setState({ fullscreen: true });
+
+      const manager = new OverridesManager(vi.fn());
+      manager.set(stateManager, config.overrides);
+
+      let thrown: unknown = null;
+      try {
+        manager.getConfig(config);
+      } catch (e) {
+        thrown = e;
+      }
+      assert(thrown instanceof AdvancedCameraCardError);
+      return thrown;
+    };
+
+    it('with `invalid_type` surfacing the attempted value', () => {
+      const error = runInvalidOverride((config) => {
+        assert(config.overrides);
+        // @ts-expect-error — intentionally invalid runtime value to trigger
+        // Zod's `invalid_type` issue code.
+        config.overrides[0].merge = 6;
+      });
+
+      expect(error.message).toMatch(/Invalid override configuration/);
+      expect(error.context).toMatchObject({
+        failures: expect.arrayContaining([
+          expect.objectContaining({
+            path: expect.any(String),
+            expected: expect.anything(),
+          }),
+        ]),
+      });
     });
-    config.overrides![0].merge = 6 as unknown as Record<string, unknown>;
 
-    const stateManager = new ConditionStateManager();
-    stateManager.setState({ fullscreen: true });
+    it('with `invalid_value` surfacing the allowed enum values', () => {
+      const error = runInvalidOverride((config) => {
+        assert(config.overrides);
+        config.overrides[0].set = { 'view.default': 'not_a_real_view' };
+      });
 
-    const manager = new OverridesManager(vi.fn());
-    manager.set(stateManager, config.overrides);
+      expect(error.context).toMatchObject({
+        failures: expect.arrayContaining([
+          expect.objectContaining({
+            path: 'view.default',
+            received: 'not_a_real_view',
+            expected: expect.arrayContaining(['live']),
+          }),
+        ]),
+      });
+    });
 
-    expect(() => manager.getConfig(config)).toThrowError(
-      /Invalid override configuration/,
-    );
+    it('with a fallback to the issue message for unhandled codes', () => {
+      // Hits the ternary's fallback branch: `too_small` is neither
+      // invalid_value nor invalid_type, so we surface `issue.message`.
+      const error = runInvalidOverride((config) => {
+        assert(config.overrides);
+        config.overrides[0].set = { 'status_bar.height': -1 };
+      });
+
+      expect(error.context).toMatchObject({
+        failures: expect.arrayContaining([
+          expect.objectContaining({
+            path: 'status_bar.height',
+            expected: expect.any(String),
+          }),
+        ]),
+      });
+    });
   });
 
   // See: https://github.com/dermotduffy/advanced-camera-card/issues/1954