smart-home-engine 1.20.8 → 1.21.0

package/dist/web/assets/{tsMode-4yeSlBtg.js → tsMode-BsFm8afo.js}

@@ -1,4 +1,4 @@
-import{m as O}from"./monaco-langs-Dt8a9eeo.js";import{t as I}from"./index-t_EkMUG4.js";/*!-----------------------------------------------------------------------------
+import{m as O}from"./monaco-langs-Dt8a9eeo.js";import{t as I}from"./index-AcVonavW.js";/*!-----------------------------------------------------------------------------
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Version: 0.52.2(404545bded1df6ffa41ea0af4e8ddb219018c6c1)
  * Released under the MIT license

package/dist/web/index.html

@@ -172,10 +172,10 @@
                 }
             })();
         </script>
-      <script type="module" crossorigin src="/assets/index-t_EkMUG4.js"></script>
+      <script type="module" crossorigin src="/assets/index-AcVonavW.js"></script>
       <link rel="modulepreload" crossorigin href="/assets/monaco-langs-Dt8a9eeo.js">
       <link rel="stylesheet" crossorigin href="/assets/monaco-langs-DyX1CsEw.css">
-      <link rel="stylesheet" crossorigin href="/assets/index-C3njyEHY.css">
+      <link rel="stylesheet" crossorigin href="/assets/index-BAau5K4k.css">
     </head>
     <body>
         <div id="app"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "smart-home-engine",
-    "version": "1.20.8",
+    "version": "1.21.0",
     "description": "Node.js based script runner for use in MQTT based Smart Home environments",
     "main": "src/index.js",
     "scripts": {

package/src/index.js

@@ -196,13 +196,30 @@ const _global = {};
 let _blockingScript = null;
 let _blockingScriptTs = 0; // timestamp when the last _dispatch() call finished
 
-/** Wrap a user callback dispatch so the heartbeat can identify the active script. */
+/**
+ * Wrap a user callback dispatch so the heartbeat can identify the active
+ * script — and so async callback errors are caught close to their source with
+ * script attribution (S1): when the callback returns a Promise, a rejection is
+ * logged with the script's label. The global unhandledRejection handler stays
+ * as a last resort but cannot name the script; label-prefixed errors also show
+ * up in the script's log panel in the Scripts tab.
+ */
 function _dispatch(label, fn) {
     _blockingScript = label;
-    fn();
-    // Record end-time synchronously — no setImmediate, which would race with the
-    // heartbeat timer when blocking occurs inside a poll-phase (I/O) callback.
-    _blockingScriptTs = Date.now();
+    let result;
+    try {
+        result = fn();
+    } finally {
+        // Record end-time synchronously — no setImmediate, which would race with the
+        // heartbeat timer when blocking occurs inside a poll-phase (I/O) callback.
+        _blockingScriptTs = Date.now();
+    }
+    if (result && typeof result.then === 'function' && typeof result.catch === 'function') {
+        result.catch((err) => {
+            const msg = err instanceof Error ? (err.stack ?? err.message) : String(err);
+            log.error(makeLabel(label) + ' async callback error: ' + msg);
+        });
+    }
 }
 
 // Sun scheduling
@@ -867,11 +884,11 @@ function runScript(script, name, _origin) {
                 subscriptions.push({ topic, options, callback: typeof callback === 'function' && scriptDomain.bind(callback), _script: name });
 
                 if (options.retain && store.has('mqtt::' + topic) && typeof callback === 'function') {
-                    callback(topic, store.get('mqtt::' + topic), store.getObject('mqtt::' + topic));
+                    _dispatch(name, () => callback(topic, store.get('mqtt::' + topic), store.getObject('mqtt::' + topic)));
                 } else if (options.retain && (/\/\+\//.test(topic) || /\+$/.test(topic) || /\+/.test(topic) || topic.endsWith('#')) && typeof callback === 'function') {
                     for (const [t, obj] of store.mqttEntries()) {
                         if (mqttWildcards(t, topic)) {
-                            callback(t, obj.val, obj);
+                            _dispatch(name, () => callback(t, obj.val, obj));
                         }
                     }
                 }

package/src/lib/ha-discovery.js

@@ -0,0 +1,349 @@
+'use strict';
+
+/**
+ * Home Assistant MQTT discovery analysis (roadmap M10).
+ *
+ * Pure functions over the daemon's state store: parse every retained
+ * `<prefix>/<component>/[<node_id>/]<object_id>/config` announcement, group
+ * the entities by the device they belong to and derive, per device,
+ *
+ *   - the config topics that announce it,
+ *   - the state / command / availability topics the announcements reference,
+ *   - the retained topics that can safely be wiped along with the device
+ *     ("state topics": referenced topics plus everything below the device's
+ *     own topic prefix(es), never anything shared with another device),
+ *   - an *orphaned* flag (none of the referenced topics exist any more) and a
+ *     *duplicate* flag (another device with the same name exists).
+ *
+ * Both the classic per-entity format and the device-level format (HA 2024.4+,
+ * `<prefix>/device/<id>/config` with a `cmps` map) are supported, including
+ * the abbreviated key names and the `~` base-topic shorthand.
+ */
+
+const DEFAULT_PREFIX = 'homeassistant';
+
+/** Abbreviation → full key (subset of HA's ABBREVIATIONS relevant here). */
+const ABBR = {
+    dev: 'device',
+    ids: 'identifiers',
+    mf: 'manufacturer',
+    mdl: 'model',
+    sw: 'sw_version',
+    hw: 'hw_version',
+    cns: 'connections',
+    cmps: 'components',
+    uniq_id: 'unique_id',
+    p: 'platform',
+    stat_t: 'state_topic',
+    cmd_t: 'command_topic',
+    avty: 'availability',
+    avty_t: 'availability_topic',
+    json_attr_t: 'json_attributes_topic',
+    t: 'topic',
+};
+
+const TOPIC_KEY_RE = /(^|_)(topic|t)$/;
+
+/**
+ * Normalise abbreviated keys (recursively) so the rest of the module only
+ * deals with long names.
+ * @param {*} v
+ * @returns {*}
+ */
+function expandKeys(v) {
+    if (Array.isArray(v)) return v.map(expandKeys);
+    if (!v || typeof v !== 'object') return v;
+    const out = {};
+    for (const [k, val] of Object.entries(v)) {
+        out[ABBR[k] || k] = expandKeys(val);
+    }
+    return out;
+}
+
+/**
+ * Apply the `~` base-topic shorthand to a topic value.
+ * @param {string} t
+ * @param {string} base
+ */
+function applyBase(t, base) {
+    if (!base || typeof t !== 'string') return t;
+    if (t.startsWith('~')) return base + t.slice(1);
+    if (t.endsWith('~')) return t.slice(0, -1) + base;
+    return t;
+}
+
+/**
+ * Collect every topic string referenced by a (key-expanded) entity config,
+ * split into *state* topics (`state_topic`, `command_topic`, `*_topic`, …)
+ * and *availability* topics (`availability_topic`, `availability[].topic`).
+ * Availability topics are frequently shared infrastructure (a bridge's
+ * `…/bridge/state`), so they are kept apart: they neither derive a device's
+ * topic prefix nor decide whether a device is still alive.
+ * @param {object} cfg
+ * @param {string} base
+ * @returns {{state: string[], availability: string[]}}
+ */
+function collectTopics(cfg, base) {
+    const state = new Set();
+    const availability = new Set();
+    for (const [k, v] of Object.entries(cfg)) {
+        if (k === 'device' || k === 'components') continue;
+        if (k === 'availability_topic') {
+            if (typeof v === 'string' && v) availability.add(applyBase(v, base));
+        } else if (k === 'availability') {
+            const list = Array.isArray(v) ? v : [v];
+            for (const a of list) {
+                if (a && typeof a === 'object' && typeof a.topic === 'string' && a.topic) availability.add(applyBase(a.topic, base));
+                else if (typeof a === 'string' && a) availability.add(applyBase(a, base));
+            }
+        } else if (TOPIC_KEY_RE.test(k) && typeof v === 'string' && v) {
+            state.add(applyBase(v, base));
+        }
+    }
+    return { state: [...state], availability: [...availability] };
+}
+
+/** Merge two collectTopics() results. */
+function mergeTopics(a, b) {
+    return {
+        state: [...new Set([...a.state, ...b.state])],
+        availability: [...new Set([...a.availability, ...b.availability])],
+    };
+}
+
+/**
+ * Turn HA's `identifiers` (string | (string|string[])[]) into a stable key.
+ * @param {*} ids
+ * @returns {string|null}
+ */
+function identifierKey(ids) {
+    if (typeof ids === 'string') return ids || null;
+    if (Array.isArray(ids) && ids.length) {
+        const first = ids[0];
+        if (Array.isArray(first)) return first.map(String).join(':');
+        if (first !== null && first !== undefined && first !== '') return String(first);
+    }
+    return null;
+}
+
+/**
+ * Parse a discovery config topic.
+ * @param {string} topic
+ * @param {string} prefix
+ * @returns {{component:string,nodeId:string|null,objectId:string}|null}
+ */
+function parseConfigTopic(topic, prefix) {
+    if (!topic.startsWith(prefix + '/')) return null;
+    const parts = topic.slice(prefix.length + 1).split('/');
+    if (parts[parts.length - 1] !== 'config') return null;
+    if (parts.length === 3) return { component: parts[0], nodeId: null, objectId: parts[1] };
+    if (parts.length === 4) return { component: parts[0], nodeId: parts[1], objectId: parts[2] };
+    return null;
+}
+
+/**
+ * Longest path prefix of a topic (all segments but the last).
+ * @param {string} t
+ */
+function dirname(t) {
+    const i = t.lastIndexOf('/');
+    return i > 0 ? t.slice(0, i) : '';
+}
+
+function segCount(t) {
+    return t ? t.split('/').length : 0;
+}
+
+/**
+ * Analyse the retained state for HA discovery announcements.
+ *
+ * @param {Iterable<[string, {val:*, ts?:number}]>} entries  [topic, stateObj] pairs (store.mqttEntries())
+ * @param {{prefix?: string}} [opts]
+ * @returns {{prefix:string, devices:object[], entityCount:number}}
+ */
+function analyzeDiscovery(entries, opts = {}) {
+    const prefix = (opts.prefix || DEFAULT_PREFIX).replace(/\/+$/, '');
+    const all = new Map(); // topic → {val, ts}
+    for (const [topic, obj] of entries) all.set(topic, obj);
+
+    /** @type {Map<string, object>} deviceKey → device */
+    const devices = new Map();
+    let entityCount = 0;
+
+    const getDevice = (key, info, fallbackName) => {
+        let d = devices.get(key);
+        if (!d) {
+            d = {
+                id: key,
+                name: null,
+                manufacturer: null,
+                model: null,
+                identifiers: [],
+                entities: [],
+                configTopics: [],
+                refTopics: new Set(),
+                _stateRefs: new Set(),
+                _candidatePrefixes: new Set(),
+            };
+            devices.set(key, d);
+        }
+        if (info) {
+            if (!d.name && typeof info.name === 'string') d.name = info.name;
+            if (!d.manufacturer && typeof info.manufacturer === 'string') d.manufacturer = info.manufacturer;
+            if (!d.model && typeof info.model === 'string') d.model = info.model;
+            if (!d.identifiers.length && info.identifiers !== undefined) {
+                d.identifiers = (Array.isArray(info.identifiers) ? info.identifiers : [info.identifiers]).map((x) => (Array.isArray(x) ? x.join(':') : String(x)));
+            }
+        }
+        if (!d.name && fallbackName) d.name = fallbackName;
+        return d;
+    };
+
+    const addEntity = (d, entity, refs) => {
+        entity.topics = [...new Set([...refs.state, ...refs.availability])].sort();
+        d.entities.push(entity);
+        entityCount++;
+        for (const t of entity.topics) {
+            if (t.startsWith(prefix + '/')) continue; // never treat discovery topics as state
+            d.refTopics.add(t);
+        }
+        for (const t of refs.state) {
+            if (t.startsWith(prefix + '/')) continue;
+            d._stateRefs.add(t);
+            const dir = dirname(t);
+            if (segCount(dir) >= 2) d._candidatePrefixes.add(dir);
+        }
+    };
+
+    for (const [topic, obj] of all) {
+        const parsed = parseConfigTopic(topic, prefix);
+        if (!parsed) continue;
+        const raw = obj && obj.val;
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) continue;
+        const cfg = expandKeys(raw);
+        const base = typeof cfg['~'] === 'string' ? cfg['~'] : '';
+        const devInfo = cfg.device && typeof cfg.device === 'object' ? cfg.device : null;
+        const ts = obj.ts || 0;
+
+        if (parsed.component === 'device' && cfg.components && typeof cfg.components === 'object') {
+            // Device-level discovery: one payload announces all components
+            const key = identifierKey(devInfo && devInfo.identifiers) || (devInfo && devInfo.name) || 'device:' + parsed.objectId;
+            const d = getDevice(key, devInfo, parsed.objectId);
+            d.configTopics.push(topic);
+            const shared = collectTopics(cfg, base);
+            for (const [cid, comp] of Object.entries(cfg.components)) {
+                if (!comp || typeof comp !== 'object') continue;
+                addEntity(
+                    d,
+                    {
+                        component: typeof comp.platform === 'string' ? comp.platform : 'unknown',
+                        objectId: cid,
+                        name: typeof comp.name === 'string' ? comp.name : cid,
+                        uniqueId: typeof comp.unique_id === 'string' ? comp.unique_id : null,
+                        configTopic: topic,
+                        ts,
+                    },
+                    mergeTopics(shared, collectTopics(comp, base)),
+                );
+            }
+            continue;
+        }
+
+        const key =
+            identifierKey(devInfo && devInfo.identifiers) ||
+            (devInfo && typeof devInfo.name === 'string' && devInfo.name) ||
+            (parsed.nodeId ? 'node:' + parsed.nodeId : 'entity:' + parsed.component + '/' + parsed.objectId);
+        const d = getDevice(key, devInfo, parsed.nodeId || parsed.objectId);
+        d.configTopics.push(topic);
+        addEntity(
+            d,
+            {
+                component: parsed.component,
+                objectId: parsed.objectId,
+                name: typeof cfg.name === 'string' ? cfg.name : parsed.objectId,
+                uniqueId: typeof cfg.unique_id === 'string' ? cfg.unique_id : null,
+                configTopic: topic,
+                ts,
+            },
+            collectTopics(cfg, base),
+        );
+    }
+
+    // Topics / prefixes referenced by more than one device are shared
+    // infrastructure (e.g. `zigbee2mqtt/bridge/state`) and must never be wiped.
+    const refOwners = new Map();
+    const prefixOwners = new Map();
+    for (const d of devices.values()) {
+        for (const t of d._stateRefs) refOwners.set(t, (refOwners.get(t) || 0) + 1);
+        for (const p of d._candidatePrefixes) prefixOwners.set(p, (prefixOwners.get(p) || 0) + 1);
+    }
+    const isSharedPrefix = (p) => {
+        // shared if the prefix itself, or any ancestor of it, is claimed by another device
+        for (const [q, n] of prefixOwners) {
+            if (n > 1 && (q === p || p.startsWith(q + '/'))) return true;
+        }
+        return false;
+    };
+
+    const nameCount = new Map();
+    for (const d of devices.values()) {
+        if (d.name) {
+            const k = d.name.trim().toLowerCase();
+            nameCount.set(k, (nameCount.get(k) || 0) + 1);
+        }
+    }
+
+    const allTopics = [...all.keys()];
+    const result = [];
+    for (const d of devices.values()) {
+        // Only state/command topics that no other device references count as
+        // "owned"; they drive both the liveness check and the wipe list.
+        const ownRefs = [...d._stateRefs].filter((t) => refOwners.get(t) === 1);
+        const prefixes = [...d._candidatePrefixes].filter((p) => !isSharedPrefix(p));
+        // Drop prefixes nested inside another kept prefix of the same device
+        const statePrefixes = prefixes.filter((p) => !prefixes.some((q) => q !== p && p.startsWith(q + '/'))).sort();
+
+        const stateSet = new Set();
+        for (const t of ownRefs) if (all.has(t)) stateSet.add(t);
+        for (const p of statePrefixes) {
+            for (const t of allTopics) {
+                if ((t === p || t.startsWith(p + '/')) && !t.startsWith(prefix + '/')) stateSet.add(t);
+            }
+        }
+        for (const t of d.configTopics) stateSet.delete(t);
+        const stateTopics = [...stateSet].sort();
+
+        let lastSeen = null;
+        let alive = 0;
+        for (const t of ownRefs) {
+            const o = all.get(t);
+            if (o) {
+                alive++;
+                if (o.ts && (lastSeen === null || o.ts > lastSeen)) lastSeen = o.ts;
+            }
+        }
+        const configTs = Math.max(0, ...d.entities.map((e) => e.ts || 0));
+
+        result.push({
+            id: d.id,
+            name: d.name,
+            manufacturer: d.manufacturer,
+            model: d.model,
+            identifiers: d.identifiers,
+            entities: d.entities.sort((a, b) => a.configTopic.localeCompare(b.configTopic)),
+            configTopics: [...new Set(d.configTopics)].sort(),
+            refTopics: [...d.refTopics].sort(),
+            statePrefixes,
+            stateTopics,
+            orphaned: ownRefs.length > 0 && alive === 0,
+            duplicate: Boolean(d.name && nameCount.get(d.name.trim().toLowerCase()) > 1),
+            lastSeen,
+            configTs: configTs || null,
+        });
+    }
+
+    result.sort((a, b) => (a.name || a.id).localeCompare(b.name || b.id));
+    return { prefix, devices: result, entityCount };
+}
+
+module.exports = { analyzeDiscovery, DEFAULT_PREFIX, parseConfigTopic, expandKeys, collectTopics, identifierKey };

package/src/matter/controller.js

@@ -722,13 +722,18 @@ function subscribeAttribute(scriptFile, nodeId, endpointId, clusterName, attrNam
     if (!changeEvent) throw new Error(`Attribute "${attrName}" on cluster "${clusterName}" has no change event`);
 
     const listenerId = _nextListenerId++;
-    const cancel = changeEvent.on((value, oldValue) => {
+    const observer = (value, oldValue) => {
         try {
             callback(value, oldValue);
         } catch (err) {
             _log?.error(`matter subscriber error in ${scriptFile}:`, err.message);
         }
-    });
+    };
+    // Observable.on() returns void — detaching needs off() with the same
+    // observer reference. (A cancel based on on()'s return value silently did
+    // nothing, leaking one listener per hot-reload.)
+    changeEvent.on(observer);
+    const cancel = () => changeEvent.off(observer);
 
     if (!_listeners.has(scriptFile)) _listeners.set(scriptFile, new Map());
     _listeners.get(scriptFile).set(listenerId, { cancel });
@@ -756,13 +761,18 @@ function unsubscribe(scriptFile, listenerId) {
 function cleanup(scriptFile) {
     const scriptListeners = _listeners.get(scriptFile);
     if (!scriptListeners) return;
+    let cancelled = 0;
     for (const { cancel } of scriptListeners.values()) {
         try {
             cancel();
-        } catch {
-            // ignore
+            cancelled++;
+        } catch (err) {
+            // Don't swallow silently — a broken cancel means a leaked listener
+            // (this hid the on()-returns-void bug above for a long time).
+            _log?.warn(`matter: failed to cancel a subscription of ${scriptFile}: ${err.message}`);
         }
     }
+    if (cancelled > 0) _log?.debug(`matter: cancelled ${cancelled} subscription(s) of ${scriptFile}`);
     _listeners.delete(scriptFile);
 }
 

package/src/sandbox/matter-sandbox.js

@@ -42,8 +42,21 @@ module.exports = function (she, { scriptDomain, scriptName, scriptFile }) {
          * @returns {number}  listenerId
          */
         sub(nodeId, endpointId, clusterName, attrName, callback) {
+            // Wrap so callback errors (sync and async) are logged with the
+            // script's label — she.error carries the label, which also routes
+            // the line into the script's log panel in the Scripts tab (S1).
+            const wrapped = (value, oldValue) => {
+                try {
+                    const result = callback(value, oldValue);
+                    if (result && typeof result.then === 'function' && typeof result.catch === 'function') {
+                        result.catch((err) => she.error('async callback error:', err instanceof Error ? (err.stack ?? err.message) : String(err)));
+                    }
+                } catch (err) {
+                    she.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
+                }
+            };
             try {
-                return controller.subscribeAttribute(trackingKey, nodeId, endpointId, clusterName, attrName, callback);
+                return controller.subscribeAttribute(trackingKey, nodeId, endpointId, clusterName, attrName, wrapped);
             } catch (err) {
                 scriptDomain.emit('error', err);
             }

package/src/web/mqtt-api.js

@@ -6,6 +6,8 @@
  * Routes:
  *   GET  /she/mqtt/state    → snapshot of all retained MQTT topic values
  *   POST /she/mqtt/publish  → publish a message to a topic
+ *   GET  /she/mqtt/ha-discovery?prefix= → Home Assistant discovery devices (grouped announcements)
+ *   DELETE /she/mqtt/ha-discovery { topics } → clear retained messages on the given topics
  *
  * Call init(store, getMqttClient) once after the state store is created.
  * The getMqttClient callback is a zero-arg function returning the live mqtt client
@@ -18,6 +20,7 @@
 
 const express = require('express');
 const { broadcast, broadcastBrokerLog } = require('./log-ws');
+const { analyzeDiscovery, DEFAULT_PREFIX } = require('../lib/ha-discovery');
 
 const BROKER_LOG_TOPICS = new Set(['D', 'I', 'N', 'W', 'E'].map((l) => `$SYS/broker/log/${l}`));
 
@@ -75,4 +78,34 @@ router.post('/publish', (req, res) => {
     });
 });
 
+// GET /she/mqtt/ha-discovery?prefix=homeassistant — devices announced via HA MQTT discovery
+router.get('/ha-discovery', (req, res) => {
+    if (!_store) return res.json({ prefix: DEFAULT_PREFIX, devices: [], entityCount: 0 });
+    const prefix = typeof req.query.prefix === 'string' && req.query.prefix.trim() ? req.query.prefix.trim() : DEFAULT_PREFIX;
+    if (/[+#]/.test(prefix)) return res.status(400).json({ error: 'prefix must not contain wildcards' });
+    res.json(analyzeDiscovery(_store.mqttEntries(), { prefix }));
+});
+
+// DELETE /she/mqtt/ha-discovery — { topics: string[] } → clear the retained message on each topic
+router.delete('/ha-discovery', async (req, res) => {
+    const mqtt = _getMqtt();
+    if (!mqtt) return res.status(503).json({ error: 'MQTT not connected' });
+    const topics = req.body && req.body.topics;
+    if (!Array.isArray(topics) || topics.length === 0) return res.status(400).json({ error: 'topics[] required' });
+    const bad = topics.find((t) => typeof t !== 'string' || !t || /[+#]/.test(t));
+    if (bad !== undefined) return res.status(400).json({ error: 'invalid topic: ' + String(bad) });
+
+    const unique = [...new Set(topics)];
+    const errors = [];
+    for (const t of unique) {
+        await new Promise((resolve) => {
+            mqtt.publish(t, '', { retain: true, qos: 0 }, (err) => {
+                if (err) errors.push({ topic: t, error: err.message });
+                resolve();
+            });
+        });
+    }
+    res.json({ ok: errors.length === 0, cleared: unique.length - errors.length, errors });
+});
+
 module.exports = { router, init };