node-red-contrib-knx-ultimate 8.0.2 → 8.0.5

package/CHANGELOG.md

@@ -6,6 +6,22 @@
 
 # CHANGELOG
 
+**Version 8.0.5** - September 2026
+
+- Added the KNX Ultimate 7-to-8 migration video to the package README, migration guide and all localized documentation pages.
+
+**Version 8.0.4** - September 2026
+
+- Automatic migration now validates only the HUE, Matter and KNX Utility nodes it converts. Invalid nodes from unrelated packages no longer block the upgrade.
+- Unrelated invalid nodes are preserved unchanged while the converted flow is deployed and verified.
+- Added regression coverage for the reported Alarm Ultimate flow with unconfigured Alarm State and Alarm Siren nodes.
+
+**Version 8.0.3** - September 2026
+
+- Allows incomplete legacy HUE and Matter nodes that belong to the active migration plan to be converted without weakening validation for unrelated invalid nodes.
+- Adds an explicit **OK** button to persistent migration-error notifications so they can always be dismissed.
+- Adds an end-to-end regression fixture for direct migration of the Alarm Ultimate flow reported by a user.
+
 **Version 8.0.2** - September 2026
 
 - Published version 8 on the stable `latest` channel for installations that only need the current KNX nodes.

package/MIGRATION.md

@@ -2,6 +2,8 @@
 
 Version 8 contains the current KNX nodes and gateway. HUE and Matter are provided by `node-red-contrib-hue-ultimate` and `node-red-contrib-matter-ultimate`; the old dedicated KNX utility nodes are replaced by KNX Utility.
 
+> ▶️ [Watch the KNX Ultimate 7 → 8 migration video](https://youtu.be/fpNNi1jZZSc) *(Italian)*
+
 ## Recommended path from version 7
 
 Install KNX Ultimate 7.1.4 first, open any KNX Ultimate node and press **Upgrade to v8**. The guided operation backs up the flows, installs the required HUE/Matter packages, converts compatible nodes, performs and verifies a full Deploy, and installs version 8. Restart the Node-RED service when requested.

package/README.md

@@ -22,6 +22,8 @@ The palette contains KNX Device, KNX Utility, KNX Viewer, KNX IoT Bridge, KNX Mu
 >
 > If version 8 was installed directly from an older v7, restart Node-RED and open the editor: the built-in recovery bridge offers the same protected backup, package installation, conversion and Deploy. Legacy KNX AI nodes still require manual replacement or removal.
 >
+> ▶️ **[Watch the KNX Ultimate 7 → 8 migration video](https://youtu.be/fpNNi1jZZSc)** *(Italian)*
+>
 > **Follow the [upgrade steps](https://supergiovane.github.io/node-red-contrib-knx-ultimate/wiki/Migration-8) to keep your flows working.**
 
 ### Native seamless integrations

package/nodes/locales/de/knxUltimateUtility.json

@@ -34,6 +34,7 @@
       "cancel": "Abbrechen",
       "start": "Sichern und aktualisieren",
       "close": "Schließen",
+      "ok": "OK",
       "backup_failed": "Die Flow-Sicherung konnte nicht gestartet werden. Es wurde nichts geändert:",
       "progress_start": "Automatisches Update wird vorbereitet…",
       "progress_install_hue": "HUE Ultimate wird installiert…",

package/nodes/locales/en/knxUltimateUtility.json

@@ -34,6 +34,7 @@
       "cancel": "Cancel",
       "start": "Back up and upgrade",
       "close": "Close",
+      "ok": "OK",
       "backup_failed": "Flow backup could not be started. Nothing was changed:",
       "progress_start": "Preparing the automatic upgrade…",
       "progress_install_hue": "Installing HUE Ultimate…",

package/nodes/locales/es/knxUltimateUtility.json

@@ -34,6 +34,7 @@
       "cancel": "Cancelar",
       "start": "Copia y actualización",
       "close": "Cerrar",
+      "ok": "OK",
       "backup_failed": "No se pudo iniciar la copia de seguridad de los flujos. No se modificó nada:",
       "progress_start": "Preparando la actualización automática…",
       "progress_install_hue": "Instalando HUE Ultimate…",

package/nodes/locales/fr/knxUltimateUtility.json

@@ -34,6 +34,7 @@
       "cancel": "Annuler",
       "start": "Sauvegarder et mettre à jour",
       "close": "Fermer",
+      "ok": "OK",
       "backup_failed": "Impossible de démarrer la sauvegarde des flux. Rien n’a été modifié :",
       "progress_start": "Préparation de la mise à jour automatique…",
       "progress_install_hue": "Installation de HUE Ultimate…",

package/nodes/locales/it/knxUltimateUtility.json

@@ -34,6 +34,7 @@
       "cancel": "Annulla",
       "start": "Backup e aggiornamento",
       "close": "Chiudi",
+      "ok": "OK",
       "backup_failed": "Impossibile avviare il backup dei flow. Non è stato modificato nulla:",
       "progress_start": "Preparazione dell’aggiornamento automatico…",
       "progress_install_hue": "Installazione di HUE Ultimate…",

package/nodes/locales/zh-CN/knxUltimateUtility.json

@@ -34,6 +34,7 @@
       "cancel": "取消",
       "start": "备份并升级",
       "close": "关闭",
+      "ok": "OK",
       "backup_failed": "无法启动流程备份。未进行任何更改：",
       "progress_start": "正在准备自动升级…",
       "progress_install_hue": "正在安装 HUE Ultimate…",

package/nodes/plugins/knxUltimate-v8-migration-recovery-plugin.html

@@ -1,3 +1,4 @@
+<script type="text/javascript" src="resources/node-red-contrib-knx-ultimate/editorNotifications.js"></script>
 <script type="text/javascript" src="resources/node-red-contrib-knx-ultimate/flowMigrationBackup.js"></script>
 <script type="text/javascript" src="resources/node-red-contrib-knx-ultimate/hueControllerMigration.js"></script>
 <script type="text/javascript" src="resources/node-red-contrib-knx-ultimate/knxUtilityMigration.js"></script>

package/package.json

@@ -3,7 +3,7 @@
   "engines": {
     "node": ">=20.18.1"
   },
-  "version": "8.0.2",
+  "version": "8.0.5",
   "description": "KNX integration for Node-RED with KNX/IP and KNX Secure, ETS import, routing, diagnostics, automation utilities, MQTT and Modbus adapters. Optional Hue Ultimate and Matter Ultimate packages connect through the KNX gateway.",
   "files": [
     "nodes/",

package/resources/editorNotifications.js

@@ -0,0 +1,101 @@
+/* global RED */
+/* eslint-disable no-undef */
+
+;(function (root, factory) {
+  const api = factory()
+  if (typeof module === 'object' && module.exports) module.exports = api
+  if (root) root.UltimateEditorNotifications = api
+  try {
+    const editor = typeof RED !== 'undefined' ? RED : (root && root.RED)
+    if (editor) api.install(editor)
+  } catch (error) { /* Node-RED will call install when the resource loads again. */ }
+}(typeof globalThis !== 'undefined' ? globalThis : this, function () {
+  'use strict'
+
+  const PATCH_MARKER = '__ultimateCloseButtonPatched'
+  const CLOSE_BUTTON_CLASS = 'ultimate-notification-close'
+
+  const closeLabel = (RED) => {
+    const key = 'common.label.close'
+    try {
+      const translated = RED && typeof RED._ === 'function' ? RED._(key) : undefined
+      if (translated && translated !== key) return translated
+    } catch (error) { /* use the language-neutral fallback below */ }
+    return 'Close'
+  }
+
+  const normalizeOptions = (options, fixed, timeout) => {
+    if (options && typeof options === 'object') return { ...options }
+    const normalized = {}
+    if (options !== undefined && options !== null) normalized.type = options
+    if (fixed !== undefined) normalized.fixed = fixed
+    if (timeout !== undefined) normalized.timeout = timeout
+    return normalized
+  }
+
+  const closesNotification = (button) => {
+    if (!button || typeof button !== 'object') return false
+    if (String(button.class || '').split(/\s+/).includes(CLOSE_BUTTON_CLASS)) return true
+    if (typeof button.click !== 'function') return false
+
+    // Existing project buttons close either the notification directly or a
+    // named close/dismiss helper. Recognising them avoids duplicate buttons.
+    const source = Function.prototype.toString.call(button.click)
+    return /\.close\s*\(|\.dialog\s*\(\s*['"]close['"]|\b(?:close|dismiss)\w*\s*\(/i.test(source)
+  }
+
+  const withCloseButton = (RED, options, getNotification) => {
+    const normalized = { ...options }
+    const buttons = Array.isArray(normalized.buttons) ? normalized.buttons.slice() : []
+    if (!buttons.some(closesNotification)) {
+      buttons.push({
+        text: closeLabel(RED),
+        class: CLOSE_BUTTON_CLASS,
+        click: function () {
+          const notification = getNotification()
+          if (notification && typeof notification.close === 'function') notification.close()
+        }
+      })
+    }
+    normalized.buttons = buttons
+    return normalized
+  }
+
+  const install = (RED) => {
+    if (!RED || typeof RED.notify !== 'function') return false
+    if (RED.notify[PATCH_MARKER]) return true
+
+    const originalNotify = RED.notify
+    const notifyWithClose = function (message, options, fixed, timeout) {
+      const notificationRef = { current: null }
+      const normalized = withCloseButton(
+        RED,
+        normalizeOptions(options, fixed, timeout),
+        () => notificationRef.current
+      )
+      notificationRef.current = originalNotify.call(this, message, normalized)
+      const notification = notificationRef.current
+
+      if (notification && typeof notification.update === 'function' && !notification.update[PATCH_MARKER]) {
+        const originalUpdate = notification.update
+        const updateWithClose = function (updatedMessage, updatedOptions) {
+          const options = typeof updatedOptions === 'number'
+            ? { timeout: updatedOptions }
+            : normalizeOptions(updatedOptions)
+          return originalUpdate.call(this, updatedMessage, withCloseButton(RED, options, () => notification))
+        }
+        Object.defineProperty(updateWithClose, PATCH_MARKER, { value: true })
+        notification.update = updateWithClose
+      }
+
+      return notification
+    }
+
+    Object.defineProperty(notifyWithClose, PATCH_MARKER, { value: true })
+    Object.defineProperty(notifyWithClose, '__ultimateOriginalNotify', { value: originalNotify })
+    RED.notify = notifyWithClose
+    return true
+  }
+
+  return Object.freeze({ install })
+}))

package/resources/upgradeToV8.js

@@ -339,19 +339,23 @@
     if (remaining.length) throw new Error('Legacy node types remain after conversion: ' + remaining.map(node => node.type).join(', '))
   }
 
-  function validateDeployable (RED) {
-    const invalid = []
+  function validateDeployable (RED, plan) {
+    const migrating = new Set((plan && plan.entries ? plan.entries : []).map(entry => entry.node))
     const unknown = []
     collectAllNodes(RED).forEach(node => {
       if (node.type === 'unknown' || (node._def && node._def.category === 'unknown')) {
         unknown.push(node.id)
         return
       }
-      if (RED.editor && typeof RED.editor.validateNode === 'function') RED.editor.validateNode(node)
-      if (node.valid === false && node.d !== true) invalid.push(node.id)
+      if (migrating.has(node) && RED.editor && typeof RED.editor.validateNode === 'function') RED.editor.validateNode(node)
+      // A legacy node can be incomplete (for example, a placeholder without a
+      // HUE/Matter config reference). It must first be persisted with its new
+      // type before the user can open and complete it. Keep its invalid marker
+      // in the editor, but do not let it deadlock the migration. Nodes outside
+      // the migration plan are preserved verbatim and are deliberately not
+      // validated: their configuration is unrelated to this upgrade.
     })
     if (unknown.length) throw new Error('Unknown nodes must be resolved before the automatic upgrade: ' + unknown.join(', '))
-    if (invalid.length) throw new Error('Invalid nodes must be corrected before the automatic upgrade: ' + invalid.join(', '))
   }
 
   function validatePreflight (RED, plan) {
@@ -360,19 +364,14 @@
       ...((plan && plan.missingStandalone && plan.missingStandalone.hue) || []),
       ...((plan && plan.missingStandalone && plan.missingStandalone.matter) || [])
     ])
-    const invalid = []
     const unknown = []
     collectAllNodes(RED).forEach(node => {
       if (migrating.has(node) || expectedUnknown.has(node) || (plan && plan.ai && plan.ai.includes(node))) return
       if (node.type === 'unknown' || (node._def && node._def.category === 'unknown')) {
         unknown.push(node.id)
-        return
       }
-      if (RED.editor && typeof RED.editor.validateNode === 'function') RED.editor.validateNode(node)
-      if (node.valid === false && node.d !== true) invalid.push(node.id)
     })
     if (unknown.length) throw new Error('Unknown nodes must be resolved before the automatic upgrade: ' + unknown.join(', '))
-    if (invalid.length) throw new Error('Invalid nodes must be corrected before the automatic upgrade: ' + invalid.join(', '))
   }
 
   function requestError (xhr, fallback) {
@@ -877,7 +876,7 @@
     let deployed = false
     try {
       assertNoLegacyNodes(RED)
-      validateDeployable(RED)
+      validateDeployable(RED, plan)
       progress('deploy')
       await deployFlows(RED, {
         ...options,
@@ -1183,7 +1182,16 @@
                     ? t('recovery_failed', 'Automatic migration stopped safely:') + ' ' + error.message
                     : t('failed', 'Automatic upgrade stopped safely. KNX Ultimate 8 was not activated:') + ' ' + error.message
                 }
-                RED.notify(failureMessage, { type: 'error', fixed: true })
+                let failureNotice
+                failureNotice = RED.notify(failureMessage, {
+                  type: 'error',
+                  fixed: true,
+                  buttons: [{
+                    text: t('ok', 'OK'),
+                    class: 'primary',
+                    click: () => failureNotice.close()
+                  }]
+                })
                 if (!keepDeployBlocked) offerRecoveryRetry()
               })
               .finally(() => unlockEditor({ keepDeployBlocked }))