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

package/resources/legacyMigrationNotice.js

@@ -1,3 +1,5 @@
+// Compatibility with the version 7 plugin cached by a running Node-RED process.
+// Version 8 does not register that plugin. Keep this URL until the process restarts.
 (function (root, factory) {
   const api = factory()
   if (typeof module === 'object' && module.exports) module.exports = api
@@ -5,133 +7,43 @@
 }(typeof globalThis !== 'undefined' ? globalThis : this, function () {
   'use strict'
 
-  const I18N_PREFIX = 'node-red-contrib-knx-ultimate/knxUltimateUtility:knxUltimateUtility.startup_migration.'
   const installations = new WeakMap()
+  const messages = {
+    en: 'KNX Ultimate 8 has been installed. Restart the Node-RED service, then reload this page to finish the upgrade. Do this before editing or deploying flows; reloading the browser alone is not enough.',
+    it: 'KNX Ultimate 8 è stato installato. Riavvia il servizio Node-RED, poi ricarica questa pagina per completare l’aggiornamento. Fallo prima di modificare i flow o fare Deploy: ricaricare soltanto il browser non basta.',
+    de: 'KNX Ultimate 8 wurde installiert. Starten Sie den Node-RED-Dienst neu und laden Sie danach diese Seite neu, um das Update abzuschließen. Tun Sie dies vor dem Bearbeiten oder Deployen von Flows; das Neuladen des Browsers allein reicht nicht aus.',
+    fr: 'KNX Ultimate 8 a été installé. Redémarrez le service Node-RED, puis rechargez cette page pour terminer la mise à jour. Faites-le avant de modifier ou de déployer des flows ; recharger uniquement le navigateur ne suffit pas.',
+    es: 'KNX Ultimate 8 se ha instalado. Reinicia el servicio Node-RED y después recarga esta página para completar la actualización. Hazlo antes de editar o desplegar flows; recargar solo el navegador no es suficiente.',
+    zh: 'KNX Ultimate 8 已安装。请重启 Node-RED 服务，然后重新加载此页面以完成升级。请先完成这些操作，再编辑或部署流程；仅刷新浏览器是不够的。'
+  }
 
   function install (RED, options = {}) {
     if (installations.has(RED)) return installations.get(RED)
     const environment = options.environment || globalThis
-    const $ = options.$ || environment.jQuery
-    const documentObject = environment.document
     let notification
     let timer
-    let dismissed = false
     let disposed = false
-    let migrating = false
-    let closeMigration
-    let lastCounts = ''
-
-    function translate (key, fallback, values = {}) {
-      const qualifiedKey = I18N_PREFIX + key
-      let result
-      try { result = RED._(qualifiedKey, values) } catch (error) { /* use fallback */ }
-      result = result && result !== qualifiedKey ? result : fallback
-      return result.replace(/{{\s*(\w+)\s*}}/g, (match, name) => values[name] === undefined ? match : String(values[name]))
-    }
-
-    function closeNotice () {
-      if (notification) notification.close()
-      notification = undefined
-      lastCounts = ''
-    }
 
-    // Defer scans until the current import, undo or conversion batch finishes.
-    // Node events also cover initial loading in Node-RED's safe mode.
-    function schedule () {
+    function dispose () {
       if (disposed) return
-      if (timer !== undefined) environment.clearTimeout(timer)
-      timer = environment.setTimeout(refresh, 150)
-    }
-
-    function migrationClosed () {
-      migrating = false
-      closeMigration = undefined
-      schedule()
-    }
-
-    function openMigration (kind) {
-      if (disposed || migrating) return
-      closeNotice()
-      migrating = true
-      try {
-        if (kind === 'hue') {
-          closeMigration = environment.KNXUltimateHueControllerMigrationDialog.open({
-            RED, $, windowObject: environment, documentObject, onClose: migrationClosed
-          })
-        } else {
-          closeMigration = environment.KNXUltimateUtilityMigration.migrate(RED, {
-            environment, $, onClose: migrationClosed
-          })
-        }
-      } catch (error) {
-        migrationClosed()
-        RED.notify(translate('unavailable', 'The migration tool is unavailable. Reload the editor after restarting Node-RED.'), 'error')
-      }
-    }
-
-    function refresh () {
-      timer = undefined
-      if (disposed || dismissed || migrating) return
-      const hueApi = environment.KNXUltimateHueControllerMigration
-      const knxApi = environment.KNXUltimateUtilityMigration
-      if (!hueApi || !knxApi) return
-      const hue = hueApi.collectLegacyHueNodes(RED).length
-      const knx = knxApi.collectLegacyUtilityNodes(RED).length
-      if (!hue && !knx) {
-        closeNotice()
-        return
-      }
-      const counts = `${hue}:${knx}`
-      if (notification && counts === lastCounts) return
-      lastCounts = counts
-
-      const message = $('<div></div>')
-      $('<p></p>').append($('<strong></strong>').text(translate('title', 'Legacy KNX Ultimate nodes'))).appendTo(message)
-      $('<p></p>').text(translate('message', 'Legacy nodes found in your flows and subflows: HUE: {{hue}}; KNX utility: {{knx}}. These nodes still work, but are hidden from the palette. Migrate them to HUE Controller and KNX Utility. Each migration downloads a flow backup; review the result before deploying.', { hue, knx })).appendTo(message)
-      const buttons = []
-      if (hue) buttons.push({
-        text: translate('hue_button', 'Migrate HUE ({{count}})', { count: hue }),
-        click: () => openMigration('hue')
-      })
-      if (knx) buttons.push({
-        text: translate('knx_button', 'Migrate KNX ({{count}})', { count: knx }),
-        click: () => openMigration('knx')
-      })
-      buttons.push({
-        text: translate('later', 'Later'),
-        click () {
-          dismissed = true
-          closeNotice()
-        }
-      })
-      const settings = { type: 'warning', fixed: true, modal: false, buttons, silent: true }
-      if (notification) notification.update(message, settings)
-      else notification = RED.notify(message, settings)
-    }
-
-    function reset () {
-      dismissed = false
-      closeNotice()
-      if (closeMigration) closeMigration()
-      migrating = false
-      schedule()
-    }
-
-    const events = ['nodes:add', 'nodes:remove', 'nodes:change', 'workspace:dirty', 'deploy']
-    events.forEach(event => RED.events.on(event, schedule))
-    RED.events.on('workspace:clear', reset)
-    const dispose = () => {
       disposed = true
       if (timer !== undefined) environment.clearTimeout(timer)
-      events.forEach(event => RED.events.off(event, schedule))
-      RED.events.off('workspace:clear', reset)
-      if (closeMigration) closeMigration()
-      closeNotice()
+      if (notification && typeof notification.close === 'function') notification.close()
       installations.delete(RED)
     }
+
     const installation = { dispose }
     installations.set(RED, installation)
-    schedule()
+    // Let plugin registration finish before showing the non-modal notification.
+    timer = environment.setTimeout(function () {
+      timer = undefined
+      if (disposed || typeof RED.notify !== 'function') return
+      const language = typeof RED.i18n?.lang === 'function'
+        ? RED.i18n.lang()
+        : environment.navigator?.language
+      const message = messages[String(language || 'en').toLowerCase().split(/[-_]/)[0]] || messages.en
+      notification = RED.notify(message, { type: 'warning', fixed: true, modal: false })
+    }, 0)
     return installation
   }
 

package/resources/matterQrScanner.js

@@ -1,98 +1,2 @@
-(function (root, factory) {
-  const api = factory()
-  if (typeof module === 'object' && module.exports) module.exports = api
-  if (root) root.KNXUltimateMatterQrScanner = api
-}(typeof globalThis !== 'undefined' ? globalThis : this, function () {
-  'use strict'
-
-  function normalizeMatterQrPayload (rawValue) {
-    const value = typeof rawValue === 'string' ? rawValue.trim() : ''
-    if (!/^MT:[0-9A-Z.-]+$/.test(value)) return null
-    return value
-  }
-
-  function getResultText (result) {
-    if (result && typeof result.getText === 'function') return result.getText()
-    if (result && typeof result.text === 'string') return result.text
-    return ''
-  }
-
-  function getCameraStatus (browserWindow, browserNavigator) {
-    if (!browserWindow || browserWindow.isSecureContext !== true) {
-      return { available: false, reason: 'insecure' }
-    }
-    if (!browserNavigator || !browserNavigator.mediaDevices || typeof browserNavigator.mediaDevices.getUserMedia !== 'function') {
-      return { available: false, reason: 'unsupported' }
-    }
-    return { available: true, reason: null }
-  }
-
-  function stopVideo (videoElement) {
-    if (!videoElement) return
-    const stream = videoElement.srcObject
-    if (stream && typeof stream.getTracks === 'function') {
-      stream.getTracks().forEach(function (track) {
-        try {
-          track.stop()
-        } catch (error) { /* empty */ }
-      })
-    }
-    try {
-      videoElement.pause()
-    } catch (error) { /* empty */ }
-    try {
-      videoElement.srcObject = null
-    } catch (error) { /* empty */ }
-  }
-
-  function isCameraPermissionError (error) {
-    return Boolean(error && (error.name === 'NotAllowedError' || error.name === 'SecurityError'))
-  }
-
-  function invertCanvasPixels (canvas) {
-    if (!canvas || typeof canvas.getContext !== 'function') throw new Error('Canvas is not available')
-    let context
-    try {
-      context = canvas.getContext('2d', { willReadFrequently: true })
-    } catch (error) {
-      context = canvas.getContext('2d')
-    }
-    if (!context) throw new Error('Canvas 2D context is not available')
-    const imageData = context.getImageData(0, 0, canvas.width, canvas.height)
-    for (let index = 0; index < imageData.data.length; index += 4) {
-      imageData.data[index] = 255 - imageData.data[index]
-      imageData.data[index + 1] = 255 - imageData.data[index + 1]
-      imageData.data[index + 2] = 255 - imageData.data[index + 2]
-    }
-    context.putImageData(imageData, 0, 0)
-    return canvas
-  }
-
-  function enableInvertedQrFallback (reader) {
-    if (!reader || typeof reader.decodeFromCanvas !== 'function') throw new Error('QR reader is not available')
-    const decodeFromCanvas = reader.decodeFromCanvas.bind(reader)
-    reader.decodeFromCanvas = function (canvas) {
-      try {
-        return decodeFromCanvas(canvas)
-      } catch (normalError) {
-        try {
-          invertCanvasPixels(canvas)
-          return decodeFromCanvas(canvas)
-        } catch (invertedError) {
-          throw normalError
-        }
-      }
-    }
-    return reader
-  }
-
-  return {
-    enableInvertedQrFallback,
-    getCameraStatus,
-    getResultText,
-    invertCanvasPixels,
-    isCameraPermissionError,
-    normalizeMatterQrPayload,
-    stopVideo
-  }
-}))
+// Inert compatibility resource for the version 7 Matter editor cached before restart.
+// Matter pairing and QR scanning now belong to node-red-contrib-matter-ultimate.

package/resources/upgradeToV8.js

@@ -41,8 +41,8 @@
     'matterbridge-config': 'matter-ultimate-bridge-config',
     knxUltimateMatterControllerDevice: 'matterUltimateController',
     knxUltimateMatterBridge: 'matterUltimateBridge',
-    // This short-lived beta type is still blocked by the version 8 install
-    // guard. Its saved contract is compatible with the standalone Controller.
+    // This short-lived beta type has a saved contract compatible with the
+    // standalone Controller.
     knxUltimateMatterLight: 'matterUltimateController'
   })
   const AI_TYPES = Object.freeze(new Set(['knxUltimateAI', 'knxUltimateAIHomeAssistant']))
@@ -51,6 +51,7 @@
   const I18N_PREFIX = 'node-red-contrib-knx-ultimate/knxUltimateUtility:knxUltimateUtility.v8_upgrade.'
   const EVENT_NAMESPACE = '.knxUltimateV8Upgrade'
   const installations = new WeakMap()
+  const inertInstallations = new WeakMap()
   const blockedUpgrades = new WeakSet()
 
   function translate (RED, key, fallback, values = {}) {
@@ -895,8 +896,10 @@
     try {
       progress('verify')
       await verifySavedFlows({ ...options, environment }, plan)
-      progress('install_v8')
-      await installKnxV8({ ...options, environment })
+      if (!options.recoveryMode) {
+        progress('install_v8')
+        await installKnxV8({ ...options, environment })
+      }
     } catch (error) {
       error.flowsPersisted = true
       throw error
@@ -1013,44 +1016,60 @@
   function open (RED, options = {}) {
     const environment = options.environment || root || {}
     const $ = options.$ || environment.jQuery
+    const recoveryMode = options.recoveryMode === true
+    const offerRecoveryRetry = function () {
+      if (recoveryMode && typeof options.onRecoveryRetry === 'function') options.onRecoveryRetry()
+    }
     if (!$ || typeof RED.notify !== 'function') throw new Error('The Node-RED editor notification API is unavailable')
     const t = (key, fallback, values) => translate(RED, key, fallback, values)
     if (blockedUpgrades.has(RED)) {
-      return RED.notify(t('upgrade_locked', 'An upgrade is already running or Node-RED must be restarted/reloaded before it can be tried again.'), { type: 'warning', fixed: true })
+      RED.notify(t('upgrade_locked', 'An upgrade is already running or Node-RED must be restarted/reloaded before it can be tried again.'), { type: 'warning', fixed: true })
+      return false
     }
     let plan
     try {
       plan = createMigrationPlan(RED, { ...options, environment })
     } catch (error) {
       RED.notify(t('preflight_failed', 'Upgrade preflight failed:') + ' ' + error.message, { type: 'error', fixed: true })
-      return
+      return false
     }
 
     if (plan.ai.length) {
-      const message = makeMessage($, t('title', 'Upgrade to KNX Ultimate 8'), [
+      const message = makeMessage($, recoveryMode
+        ? t('recovery_title', 'Complete KNX Ultimate 8 migration')
+        : t('title', 'Upgrade to KNX Ultimate 8'), [
         t('ai_blocked', 'Found {{count}} legacy KNX AI nodes. The automatic upgrade stopped before making changes. Replace or remove those nodes first; their configuration cannot be converted safely to Cerebrum Ultimate.', { count: plan.ai.length })
       ])
-      return RED.notify(message, { type: 'error', fixed: true, modal: true })
+      RED.notify(message, { type: 'error', fixed: true, modal: true })
+      return false
     }
     try {
       validatePreflight(RED, plan)
     } catch (error) {
       RED.notify(t('preflight_failed', 'Upgrade preflight failed:') + ' ' + error.message, { type: 'error', fixed: true })
-      return
+      return false
     }
     const needsModuleInspection = plan.needsHue || plan.needsMatter
     if (RED.user && typeof RED.user.hasPermission === 'function' &&
         (!RED.user.hasPermission('flows.read') || !RED.user.hasPermission('flows.write') ||
          (needsModuleInspection && !RED.user.hasPermission('nodes.read')))) {
-      return RED.notify(t('permission_denied', 'Your Node-RED account cannot install nodes or deploy flows.'), { type: 'error', fixed: true })
+      RED.notify(t('permission_denied', 'Your Node-RED account cannot install nodes or deploy flows.'), { type: 'error', fixed: true })
+      return false
     }
 
     const values = plan.counts
-    const message = makeMessage($, t('title', 'Upgrade to KNX Ultimate 8'), [
-      t('summary', 'Ready to upgrade. Nodes/configurations to convert: KNX Utility {{utility}}, HUE {{hue}}, Matter {{matter}}.', values),
-      t('confirm', 'A JSON backup of all flows will download first. The required HUE/Matter packages will then be installed, all current editor changes deployed, and KNX Ultimate 8 installed. IDs, wiring, configuration references, credentials and Matter storage are preserved. The current node editor will close and discard edits not yet saved in this form.', values),
-      t('restart_note', 'When the process finishes, you must restart the Node-RED service and reload the editor.', values)
-    ])
+    const message = makeMessage($, recoveryMode
+      ? t('recovery_title', 'Complete KNX Ultimate 8 migration')
+      : t('title', 'Upgrade to KNX Ultimate 8'), recoveryMode
+      ? [
+          t('recovery_summary', 'Legacy nodes were found after KNX Ultimate 8 was installed. Nodes/configurations to convert: KNX Utility {{utility}}, HUE {{hue}}, Matter {{matter}}.', values),
+          t('recovery_confirm', 'A JSON backup of all flows will download first. The required HUE/Matter packages will then be installed and all current editor changes deployed. KNX Ultimate itself will not be reinstalled. IDs, wiring, configuration references, credentials and Matter storage are preserved. The current node editor will close and discard edits not yet saved in this form.', values)
+        ]
+      : [
+          t('summary', 'Ready to upgrade. Nodes/configurations to convert: KNX Utility {{utility}}, HUE {{hue}}, Matter {{matter}}.', values),
+          t('confirm', 'A JSON backup of all flows will download first. The required HUE/Matter packages will then be installed, all current editor changes deployed, and KNX Ultimate 8 installed. IDs, wiring, configuration references, credentials and Matter storage are preserved. The current node editor will close and discard edits not yet saved in this form.', values),
+          t('restart_note', 'When the process finishes, you must restart the Node-RED service and reload the editor.', values)
+        ])
     let notification
     let running = false
     notification = RED.notify(message, {
@@ -1058,9 +1077,17 @@
       fixed: true,
       modal: true,
       buttons: [
-        { text: t('cancel', 'Cancel'), click: () => notification.close() },
         {
-          text: t('start', 'Back up and upgrade'),
+          text: t('cancel', 'Cancel'),
+          click: () => {
+            notification.close()
+            offerRecoveryRetry()
+          }
+        },
+        {
+          text: recoveryMode
+            ? t('recovery_start', 'Back up and complete migration')
+            : t('start', 'Back up and upgrade'),
           class: 'primary',
           click: function () {
             if (running) return
@@ -1086,24 +1113,40 @@
               progressNotice = RED.notify(progressMessage, { type: 'info', fixed: true, modal: true })
             } catch (error) {
               if (unlockEditor) unlockEditor()
-              RED.notify(t('failed', 'Automatic upgrade stopped safely. KNX Ultimate 8 was not activated:') + ' ' + error.message, { type: 'error', fixed: true })
+              RED.notify(recoveryMode
+                ? t('recovery_failed', 'Automatic migration stopped safely:') + ' ' + error.message
+                : t('failed', 'Automatic upgrade stopped safely. KNX Ultimate 8 was not activated:') + ' ' + error.message, { type: 'error', fixed: true })
+              offerRecoveryRetry()
               return
             }
             const onProgress = stage => progressText.text(t('progress_' + stage, stage))
             let keepDeployBlocked = false
             Promise.resolve().then(() => runUpgrade(RED, plan, { ...options, environment, $, onProgress }))
               .then(counts => {
+                // Unknown config nodes are converted in place. The full Deploy
+                // is correct, but a browser reload is required to rebuild their
+                // editor indexes and user references from the converted flow.
                 keepDeployBlocked = true
                 if (progressNotice && typeof progressNotice.close === 'function') progressNotice.close()
-                const done = makeMessage($, t('complete_title', 'KNX Ultimate 8 installed'), [
-                  t('complete', 'Converted {{total}} nodes/configurations and installed KNX Ultimate 8. Restart the Node-RED service now, then reload this page. Do not edit or deploy flows before restarting.', counts)
+                const done = makeMessage($, recoveryMode
+                  ? t('recovery_complete_title', 'KNX Ultimate 8 migration completed')
+                  : t('complete_title', 'KNX Ultimate 8 installed'), [
+                  recoveryMode
+                    ? t('recovery_complete', 'Converted {{total}} legacy nodes/configurations. The saved flows are now compatible with KNX Ultimate 8. Reload the editor before making further changes.', counts)
+                    : t('complete', 'Converted {{total}} nodes/configurations and installed KNX Ultimate 8. Restart the Node-RED service now, then reload this page. Do not edit or deploy flows before restarting.', counts)
                 ])
                 let doneNotice
                 doneNotice = RED.notify(done, {
                   type: 'success',
                   fixed: true,
                   modal: true,
-                  buttons: [{ text: t('close', 'Close'), click: () => doneNotice.close() }]
+                  buttons: [{
+                    text: recoveryMode ? t('recovery_reload', 'Reload editor') : t('close', 'Close'),
+                    click: () => {
+                      doneNotice.close()
+                      if (recoveryMode && environment.location && typeof environment.location.reload === 'function') environment.location.reload()
+                    }
+                  }]
                 })
               })
               .catch(error => {
@@ -1111,13 +1154,19 @@
                 let failureMessage
                 if (error.code === 'standalone_restart_required') {
                   keepDeployBlocked = true
-                  failureMessage = t('standalone_restart_required', 'A HUE/Matter package update is ready. Restart the Node-RED service, reload the editor, then press the upgrade button again. No flows were changed.')
+                  failureMessage = recoveryMode
+                    ? t('recovery_standalone_restart_required', 'A HUE/Matter package update is ready. Restart the Node-RED service, reload the editor, then start the migration recovery again. No flows were changed.')
+                    : t('standalone_restart_required', 'A HUE/Matter package update is ready. Restart the Node-RED service, reload the editor, then press the upgrade button again. No flows were changed.')
                 } else if (error.moduleInstallUncertain) {
                   keepDeployBlocked = true
-                  failureMessage = t('module_install_uncertain', 'A package operation may still be running. Restart the Node-RED service, reload the editor and press the upgrade button again. Do not deploy flows before restarting.')
+                  failureMessage = recoveryMode
+                    ? t('recovery_module_install_uncertain', 'A package operation may still be running. Restart the Node-RED service, reload the editor and start the migration recovery again. Do not deploy flows before restarting.')
+                    : t('module_install_uncertain', 'A package operation may still be running. Restart the Node-RED service, reload the editor and press the upgrade button again. Do not deploy flows before restarting.')
                 } else if (error.restartRequired) {
                   keepDeployBlocked = true
-                  failureMessage = t('standalone_restart_required', 'A HUE/Matter package update is ready. Restart the Node-RED service, reload the editor, then press the upgrade button again. No flows were changed.') + ' ' + error.message
+                  failureMessage = (recoveryMode
+                    ? t('recovery_standalone_restart_required', 'A HUE/Matter package update is ready. Restart the Node-RED service, reload the editor, then start the migration recovery again. No flows were changed.')
+                    : t('standalone_restart_required', 'A HUE/Matter package update is ready. Restart the Node-RED service, reload the editor, then press the upgrade button again. No flows were changed.')) + ' ' + error.message
                 } else if (error.flowConflict) {
                   keepDeployBlocked = true
                   failureMessage = t('flow_conflict', 'Another editor changed the flow revision. The automatic conversion was rolled back locally. Review or export any pre-existing local changes, then reload the editor before trying again.')
@@ -1126,11 +1175,16 @@
                   failureMessage = t('persistence_uncertain', 'Node-RED did not confirm the flow save. No automatic rollback was applied. Reload the editor and review the saved flows before trying again.')
                 } else if (error.flowsPersisted) {
                   keepDeployBlocked = true
-                  failureMessage = t('flows_persisted', 'The converted flows were saved, but KNX Ultimate 8 was not installed. Do not deploy more changes. Resolve the reported error, reload the editor and press the upgrade button again:') + ' ' + error.message
+                  failureMessage = recoveryMode
+                    ? t('recovery_flows_persisted', 'The converted flows were saved, but verification did not complete. Do not deploy more changes. Reload the editor and review the saved flows before starting migration recovery again:') + ' ' + error.message
+                    : t('flows_persisted', 'The converted flows were saved, but KNX Ultimate 8 was not installed. Do not deploy more changes. Resolve the reported error, reload the editor and press the upgrade button again:') + ' ' + error.message
                 } else {
-                  failureMessage = t('failed', 'Automatic upgrade stopped safely. KNX Ultimate 8 was not activated:') + ' ' + error.message
+                  failureMessage = recoveryMode
+                    ? 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 })
+                if (!keepDeployBlocked) offerRecoveryRetry()
               })
               .finally(() => unlockEditor({ keepDeployBlocked }))
           }
@@ -1141,6 +1195,20 @@
   }
 
   function install (RED, options = {}) {
+    // A running Node-RED 7 process can keep the old plugin HTML in memory while
+    // npm has already replaced the package files with version 8. In that state
+    // the cached plugin still requests this resource. Do not let it start a
+    // second upgrade path: only the plugin shipped and registered by version 8
+    // is allowed to opt in to recovery mode.
+    if (options.recoveryMode !== true) {
+      if (inertInstallations.has(RED)) return inertInstallations.get(RED)
+      const inertInstallation = {
+        open: function () {},
+        dispose: function () { inertInstallations.delete(RED) }
+      }
+      inertInstallations.set(RED, inertInstallation)
+      return inertInstallation
+    }
     if (installations.has(RED)) return installations.get(RED)
     const environment = options.environment || root || {}
     const $ = options.$ || environment.jQuery

package/scripts/check-legacy-flows.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+'use strict'
+
+// Best-effort npm lifecycle diagnostic only. Dependency lifecycle scripts may
+// be skipped by the installer, and this hook has no access to Node-RED's live
+// storage API or editor state. Never mutate flows or install other packages.
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const LEGACY_TYPES = new Set([
+  'knxUltimateAlerter', 'knxUltimateAutoResponder', 'knxUltimateDateTime',
+  'knxUltimateWatchDog', 'knxUltimateGlobalContext', 'knxUltimateLogger',
+  'knxUltimateStaircase', 'knxUltimateGarage', 'knxUltimateSceneController',
+  'knxUltimateLoadControl', 'knxUltimateHATranslator',
+  'hue-config', 'matter-config', 'matterbridge-config',
+  'knxUltimateHueController', 'knxUltimateHueLight', 'knxUltimateHuePlug',
+  'knxUltimateHueButton', 'knxUltimateHueTapDial', 'knxUltimateHueMotion',
+  'knxUltimateHueAreaMotion', 'knxUltimateHueCameraMotion', 'knxUltimateHueContactSensor',
+  'knxUltimateHueLightSensor', 'knxUltimateHueTemperatureSensor', 'knxUltimateHueHumiditySensor',
+  'knxUltimateHueScene', 'knxUltimateHueBattery', 'knxUltimateHueZigbeeConnectivity',
+  'knxUltimateHuedevice_software_update', 'knxUltimateMatterControllerDevice',
+  'knxUltimateMatterBridge', 'knxUltimateMatterLight',
+  'knxUltimateAI', 'knxUltimateAIHomeAssistant'
+])
+
+function check (options = {}) {
+  const env = options.env || process.env
+  const cwd = options.cwd || process.cwd()
+  const home = options.home || os.homedir()
+  const packageDir = options.packageDir || path.resolve(__dirname, '..')
+  const version = options.version || require('../package.json').version
+  const result = { files: [], legacy: [], errors: [], warnings: [] }
+  if (!/^8\./.test(version)) return result
+  const candidates = new Map()
+  const visited = new Set()
+  const add = (file, required = false) => {
+    file = path.resolve(file)
+    candidates.set(file, required || /^flows(?:[_.-]|\.json$)/.test(path.basename(file)) || candidates.get(file) || false)
+  }
+  const json = file => JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, ''))
+  const scanDirectory = dir => {
+    if (!fs.existsSync(dir)) return
+    try {
+      const realDir = fs.realpathSync(dir)
+      if (visited.has(realDir)) return
+      visited.add(realDir)
+      // Restrict discovery to this directory. Never traverse backups, libraries,
+      // node_modules, examples or persistent device storage.
+      for (const file of fs.readdirSync(dir)) {
+        if (/\.json$/i.test(file) && !file.startsWith('.') && !/(?:_cred|credentials|backup|\.bak)(?:[._-]|$)/i.test(file) && !['package.json', 'package-lock.json'].includes(file)) add(path.join(dir, file))
+      }
+      const settings = path.join(dir, 'settings.js')
+      if (fs.existsSync(settings)) {
+        // Strip comments while retaining string literals; do not run user code.
+        const text = fs.readFileSync(settings, 'utf8').replace(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\/\*[\s\S]*?\*\/|\/\/[^\r\n]*/g, token => token.startsWith('/') ? '' : token)
+        const match = /\bflowFile\s*:\s*(['"])([^\r\n]*?)\1\s*[,}]/.exec(text)
+        if (match && !match[2].includes('\\')) add(path.resolve(dir, match[2]), true)
+        else if (/\bflowFile\s*:/.test(text)) result.warnings.push('Dynamic flowFile setting: use KNXULTIMATE_FLOW_FILE to check its resolved path.')
+      }
+      const projectConfig = path.join(dir, '.config.projects.json')
+      if (fs.existsSync(projectConfig)) {
+        const config = json(projectConfig)
+        const active = config.activeProject || (config.projects && config.projects.activeProject)
+        if (typeof active === 'string' && active && path.basename(active) === active) {
+          const projectDir = path.join(dir, 'projects', active)
+          scanDirectory(projectDir)
+          const manifest = json(path.join(projectDir, 'package.json'))
+          const flowFile = manifest['node-red']?.settings?.flowFile
+          if (typeof flowFile === 'string') add(path.resolve(projectDir, flowFile), true)
+        }
+      }
+    } catch (error) { result.errors.push(`${dir}: unable to inspect flow files (${error.code || 'invalid JSON'}).`) }
+  }
+  if (env.KNXULTIMATE_FLOW_FILE) {
+    add(path.resolve(env.INIT_CWD || cwd, env.KNXULTIMATE_FLOW_FILE), true)
+  } else if (env.KNXULTIMATE_NODE_RED_USER_DIR) {
+    const dir = path.resolve(env.INIT_CWD || cwd, env.KNXULTIMATE_NODE_RED_USER_DIR)
+    if (!fs.existsSync(dir)) result.errors.push(`${dir}: Node-RED user directory does not exist.`)
+    else scanDirectory(dir)
+  } else {
+    const dirs = new Set([env.INIT_CWD, env.npm_config_local_prefix, cwd].filter(Boolean).map(p => path.resolve(p)))
+    // npm lifecycle cwd is the installed package, not the Node-RED userDir.
+    for (let dir = packageDir; path.dirname(dir) !== dir; dir = path.dirname(dir)) {
+      if (path.basename(dir) === 'node_modules') dirs.add(path.dirname(dir))
+    }
+    for (const dir of dirs) if (dir !== packageDir) scanDirectory(dir)
+  }
+  const inspected = new Set()
+  const inspectCandidates = () => {
+    for (const [file, required] of candidates) {
+      if (inspected.has(file)) continue
+      inspected.add(file)
+      try {
+        const data = json(file)
+        const flow = Array.isArray(data) ? data : (data && Array.isArray(data.flows) ? data.flows : null)
+        if (!flow) {
+          if (required) result.errors.push(`${file}: expected a Node-RED flow array.`)
+          continue
+        }
+        if (flow.some(node => !node || typeof node.id !== 'string' || typeof node.type !== 'string')) {
+          if (required || flow.some(node => node && LEGACY_TYPES.has(node.type))) result.errors.push(`${file}: invalid Node-RED flow entries.`)
+          else continue
+        }
+        result.files.push(file)
+        const counts = new Map()
+        for (const node of flow) if (node && LEGACY_TYPES.has(node.type)) counts.set(node.type, (counts.get(node.type) || 0) + 1)
+        for (const [type, count] of counts) result.legacy.push({ file, type, count })
+      } catch (error) {
+        // Report broken conventional/explicit flow files when this diagnostic
+        // is allowed to run; the version 8 editor bridge remains authoritative.
+        if (required || /^flows(?:[_.-]|\.json$)/.test(path.basename(file)) || error.code === 'EACCES') result.errors.push(`${file}: unable to read flow (${error.code || 'invalid JSON'}).`)
+      }
+    }
+  }
+  inspectCandidates()
+  // A random JSON file beside npm's launch directory is not evidence that the
+  // actual Node-RED flow has been checked. Fall back after inspecting candidates.
+  if (!env.KNXULTIMATE_FLOW_FILE && !env.KNXULTIMATE_NODE_RED_USER_DIR && !result.files.length && !result.errors.length) {
+    scanDirectory(path.join(home, '.node-red'))
+    inspectCandidates()
+  }
+  if (!result.files.length) result.warnings.push('No saved flow could be checked. For custom storage/paths, verify migration manually or set KNXULTIMATE_FLOW_FILE.')
+  return result
+}
+
+function run (options) {
+  const result = check(options)
+  if (result.legacy.length > 0) {
+    console.error('\nKNX Ultimate 8 migration required / Migrazione necessaria.')
+    for (const item of result.legacy) console.error(`  ${item.file}: ${item.type} (${item.count})`)
+    console.error('Installation will continue. Restart the Node-RED service, open the editor and follow the KNX Ultimate migration prompt before editing or deploying flows. The editor will back up and convert supported nodes and install HUE/Matter packages when required. Legacy KNX AI nodes still require manual replacement or removal. Do not delete Matter storage.')
+  }
+  if (result.errors.length > 0) {
+    console.error('\nKNX Ultimate could not inspect every saved flow. Installation will continue, but you must open the Node-RED editor after restart and complete any offered migration before deploying.')
+    for (const error of result.errors) console.error(`  ${error}`)
+  }
+  for (const warning of result.warnings) console.error(`[KNX Ultimate migration check] ${warning}`)
+  return 0
+}
+
+module.exports = { check, run, LEGACY_TYPES }
+if (require.main === module) process.exitCode = run()