Use WebSocket entity registry for stable unique_id matching (#50)

Replace regex-based entity discovery with HA's WebSocket API to fetch
entity/device registries, matching by translation_key for stability
across entity renames and HA language changes.

- Discover printers/AMS/trays via WS entity+device registries
- Store spool assignments by unique_id instead of entity_id
- Add fallback matching for pre-migration spools using entity_id
- Add entity_id→unique_id resolver in webhook and spool routes
- Add automations stale warning on dashboard when entities change
- Fix external mode automation registration to use per-printer format
  matching embedded mode (enables stale detection for external users)
- Add Jinja2 null guards for trigger.from_state/to_state in automations
- Remove entity-patterns.ts (no longer needed with WS discovery)

Author: gibz104

app/package-lock.json

@@ -31,14 +31,16 @@
     "react-dom": "^19.2.3",
     "recharts": "^3.7.0",
     "sonner": "^2.0.7",
-    "tailwind-merge": "^3.4.0"
+    "tailwind-merge": "^3.4.0",
+    "ws": "^8.19.0"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/react-dom": "^19",
+    "@types/ws": "^8.18.1",
     "eslint": "^9",
     "eslint-config-next": "16.1.1",
     "prisma": "^7.2.0",

app/package.json

@@ -3,7 +3,6 @@ import prisma from '@/lib/db';
 import { HomeAssistantClient, isEmbeddedMode, isAddonMode } from '@/lib/api/homeassistant';
 import { generateHAConfig, mergeConfiguration, mergeAutomations } from '@/lib/ha-config-generator';
 import { createActivityLog } from '@/lib/activity-log';
-import { extractPrinterPrefix } from '@/lib/entity-patterns';
 import { getHiddenPrinters } from '@/app/api/printers/setup/route';
 import * as fs from 'fs/promises';
 
@@ -65,41 +64,76 @@ export async function POST(request: NextRequest) {
       // Use the same config generator as embedded mode for consistency
       const config = generateHAConfig(printers, webhookUrl, webhookUrl);
 
+      // Return printer registration data so the frontend can register
+      // automations in the same per-printer format as auto-configure
+      const printerRegistrations = printers.map(p => ({
+        prefix: p.prefix,
+        name: p.name,
+        trayIds: [
+          ...p.ams_units.flatMap(ams => ams.trays.map(t => t.entity_id)),
+          ...p.external_spools.map(es => es.entity_id),
+        ],
+      }));
+
       return NextResponse.json({
         trayCount: config.trayCount,
         printerCount: config.printerCount,
         automationsYaml: config.automationsYaml,
         configurationYaml: config.configurationAdditions,
+        printerRegistrations,
       });
     }
 
     if (action === 'register') {
       // Register automations in our database (after user applies to HA)
-      const { trayIds } = body;
+      // Uses same per-printer format as auto-configure for consistent stale detection
+      const { printerRegistrations } = body;
 
-      for (const trayId of trayIds) {
-        const automationId = `spoolmansync_${trayId.replace(/\./g, '_')}`;
+      const currentAutomationIds: string[] = [];
+      for (const reg of printerRegistrations) {
+        const automationId = `spoolmansync_update_spool_${reg.prefix}`;
+        currentAutomationIds.push(automationId);
 
         await prisma.automation.upsert({
           where: { haAutomationId: automationId },
           create: {
             haAutomationId: automationId,
-            trayId,
-            printerId: trayId.split('_')[0], // Extract printer prefix
+            trayId: reg.trayIds.join(','),
+            printerId: reg.name,
           },
           update: {
-            trayId,
+            trayId: reg.trayIds.join(','),
+            printerId: reg.name,
           },
         });
       }
 
+      // Clean up stale automation records for printers no longer present
+      const staleRecords = await prisma.automation.findMany({
+        where: {
+          haAutomationId: { startsWith: 'spoolmansync_update_spool_' },
+          NOT: { haAutomationId: { in: currentAutomationIds } },
+        },
+      });
+      if (staleRecords.length > 0) {
+        await prisma.automation.deleteMany({
+          where: { id: { in: staleRecords.map(r => r.id) } },
+        });
+      }
+
+      // Also clean up any legacy external-mode-configured records
+      await prisma.automation.deleteMany({
+        where: { haAutomationId: 'spoolmansync_external-mode-configured' },
+      });
+
+      const totalTrays = printerRegistrations.reduce((sum: number, r: { trayIds: string[] }) => sum + r.trayIds.length, 0);
       await createActivityLog({
         type: 'automation_created',
-        message: `Registered ${trayIds.length} automations`,
-        details: { trayIds },
+        message: `Registered ${printerRegistrations.length} printer(s), ${totalTrays} tray(s)`,
+        details: { printerRegistrations },
       });
 
-      return NextResponse.json({ success: true, count: trayIds.length });
+      return NextResponse.json({ success: true, count: printerRegistrations.length });
     }
 
     if (action === 'auto-configure') {
@@ -193,7 +227,7 @@ export async function POST(request: NextRequest) {
         // Register one automation record per printer
         const currentAutomationIds: string[] = [];
         for (const printer of printers) {
-          const prefix = extractPrinterPrefix(printer.entity_id);
+          const prefix = printer.prefix;
           const printerTrayIds: string[] = [];
           for (const ams of printer.ams_units) {
             for (const tray of ams.trays) {

app/src/app/api/automations/route.ts

@@ -118,33 +118,97 @@ export async function GET() {
       const spoolmanClient = new SpoolmanClient(spoolmanConnection.url);
       const spools = await spoolmanClient.getSpools();
 
-      // Create a map of tray ID to spool
+      // Build entity_id → unique_id map from discovered trays for migration.
+      // This map includes CURRENT entity_ids only. For renamed entities,
+      // the old entity_id won't be in this map — we handle that with
+      // a fallback unique_id-suffix match below.
+      const entityIdToUniqueId = new Map<string, string>();
+      // Also build a set of all known unique_ids for fallback matching
+      const allUniqueIds = new Set<string>();
+      for (const printer of printers) {
+        for (const ams of printer.ams_units) {
+          for (const tray of ams.trays) {
+            if (tray.unique_id) {
+              entityIdToUniqueId.set(tray.entity_id, tray.unique_id);
+              allUniqueIds.add(tray.unique_id);
+            }
+          }
+        }
+        for (const ext of printer.external_spools) {
+          if (ext.unique_id) {
+            entityIdToUniqueId.set(ext.entity_id, ext.unique_id);
+            allUniqueIds.add(ext.unique_id);
+          }
+        }
+      }
+
+      // Set up resolver so any SpoolmanClient writes also sanitize
+      spoolmanClient.setEntityIdResolver(async (entityId: string) => {
+        return entityIdToUniqueId.get(entityId) || entityId;
+      });
+
+      // Build tray-spool map and migrate entity_id → unique_id in one pass.
+      // On upgrade, existing spools have entity_ids stored in active_tray.
+      // Convert them to stable unique_ids so assignments survive entity renames.
+      // After the first run, all values are already unique_ids, so the
+      // startsWith('sensor.') check short-circuits and no API calls are made.
       const traySpoolMap = new Map<string, typeof spools[0]>();
       for (const spool of spools) {
-        const trayId = spool.extra?.['active_tray'];
-        // Skip empty, null, or missing active_tray values
-        // Values are JSON-encoded, so empty string is '""', null is 'null'
-        if (trayId && trayId !== '' && trayId !== 'null' && trayId !== '""' && trayId !== '\"\"') {
-          // Remove JSON quotes from tray ID
-          const cleanTrayId = trayId.replace(/^"|"$/g, '');
-          if (cleanTrayId) {
-            traySpoolMap.set(cleanTrayId, spool);
+        const raw = spool.extra?.['active_tray'];
+        if (!raw || raw === '' || raw === 'null' || raw === '""' || raw === '\"\"') continue;
+        let cleanId = raw.replace(/^"|"$/g, '');
+        if (!cleanId) continue;
+
+        // Migrate: if it's an entity_id, convert to unique_id
+        if (cleanId.startsWith('sensor.')) {
+          // Try exact match first (entity hasn't been renamed)
+          let uniqueId = entityIdToUniqueId.get(cleanId);
+
+          // Fallback: if the entity was renamed, the old entity_id won't be in
+          // the map. Try to match by finding a unique_id whose tray suffix
+          // matches the entity_id's suffix (e.g., both end with "_tray_1").
+          if (!uniqueId) {
+            const trayMatch = cleanId.match(/_(tray_\d+|external_spool\d*)$/);
+            if (trayMatch) {
+              const suffix = trayMatch[0]; // e.g., "_tray_1"
+              for (const uid of allUniqueIds) {
+                if (uid.endsWith(suffix)) {
+                  uniqueId = uid;
+                  break;
+                }
+              }
+            }
+          }
+
+          if (uniqueId) {
+            const newExtra: Record<string, string> = {};
+            if (spool.extra) {
+              for (const [key, value] of Object.entries(spool.extra)) {
+                newExtra[key] = value;
+              }
+            }
+            newExtra['active_tray'] = JSON.stringify(uniqueId);
+            await spoolmanClient.updateSpool(spool.id, { extra: newExtra });
+            spool.extra!['active_tray'] = JSON.stringify(uniqueId);
+            cleanId = uniqueId;
+            console.log(`[Migration] Spool #${spool.id}: active_tray converted from entity_id to unique_id`);
           }
         }
+
+        traySpoolMap.set(cleanId, spool);
       }
 
       // Enrich printer data with spool info and mismatch detection
+      // Match by unique_id (stable across entity renames)
       for (const printer of printers) {
         for (const ams of printer.ams_units) {
           for (const tray of ams.trays) {
-            const assignedSpool = traySpoolMap.get(tray.entity_id);
+            const assignedSpool = tray.unique_id ? traySpoolMap.get(tray.unique_id) : traySpoolMap.get(tray.entity_id);
             const trayRecord = tray as unknown as Record<string, unknown>;
 
             if (assignedSpool) {
               trayRecord.assigned_spool = assignedSpool;
 
-              // Mismatch detection: compare printer's RFID data with assigned spool
-              // Only meaningful for Bambu spools with RFID tags
               const mismatch = detectTrayMismatch(tray, assignedSpool);
               if (mismatch) {
                 trayRecord.mismatch = mismatch;
@@ -153,18 +217,67 @@ export async function GET() {
           }
         }
         for (const extSpool of printer.external_spools) {
-          const assignedSpool = traySpoolMap.get(extSpool.entity_id);
+          const assignedSpool = extSpool.unique_id ? traySpoolMap.get(extSpool.unique_id) : traySpoolMap.get(extSpool.entity_id);
           if (assignedSpool) {
             const extRecord = extSpool as unknown as Record<string, unknown>;
             extRecord.assigned_spool = assignedSpool;
+          }
+        }
+      }
+    }
+
+    // Check if automations are stale (entity_ids changed or new trays added)
+    // Only check printers that are in-scope (not hidden) AND have automation records
+    let automationsStale = false;
+    try {
+      const automations = await prisma.automation.findMany();
+      if (automations.length > 0) {
+        // Build a map of printer prefix → configured tray entity_ids
+        // Automation haAutomationId format: spoolmansync_update_spool_{prefix}
+        const configuredByPrefix = new Map<string, Set<string>>();
+        for (const automation of automations) {
+          const prefix = automation.haAutomationId.replace('spoolmansync_update_spool_', '');
+          const ids = new Set<string>();
+          for (const id of automation.trayId.split(',')) {
+            if (id.trim()) ids.add(id.trim());
+          }
+          configuredByPrefix.set(prefix, ids);
+        }
+
+        // For each in-scope printer that has an automation record, compare entity_ids
+        for (const printer of printers) {
+          const configuredIds = configuredByPrefix.get(printer.prefix);
+          if (!configuredIds) continue; // No automation record for this printer — skip
+
+          // Collect current tray entity_ids for this printer
+          const currentIds = new Set<string>();
+          for (const ams of printer.ams_units) {
+            for (const tray of ams.trays) {
+              currentIds.add(tray.entity_id);
+            }
+          }
+          for (const ext of printer.external_spools) {
+            currentIds.add(ext.entity_id);
+          }
+
+          // Stale: a configured entity_id no longer exists (renamed or removed)
+          for (const id of configuredIds) {
+            if (!currentIds.has(id)) { automationsStale = true; break; }
+          }
+          if (automationsStale) break;
 
-            // External spool doesn't have RFID reader, so no mismatch detection
+          // Missing: a current entity_id isn't covered by automations (new AMS/tray)
+          for (const id of currentIds) {
+            if (!configuredIds.has(id)) { automationsStale = true; break; }
           }
+          if (automationsStale) break;
         }
       }
+    } catch {
+      // Non-critical check, don't block the response
     }
 
-    return NextResponse.json({ printers });
+    return NextResponse.json({ printers, automationsStale });
   } catch (error) {
     console.error('Error fetching printers:', error);
     return NextResponse.json({ error: 'Failed to fetch printers' }, { status: 500 });