smart-home-engine 1.20.2 → 1.20.4

package/dist/web/assets/{tsMode-wYM5jYsY.js → tsMode-Bd9DcRmS.js}

@@ -1,4 +1,4 @@
-import{m as O}from"./monaco-langs-Dt8a9eeo.js";import{t as I}from"./index-C31bVgVn.js";/*!-----------------------------------------------------------------------------
+import{m as O}from"./monaco-langs-Dt8a9eeo.js";import{t as I}from"./index-xX-8bkDA.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-C31bVgVn.js"></script>
+      <script type="module" crossorigin src="/assets/index-xX-8bkDA.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-CjRDTePT.css">
+      <link rel="stylesheet" crossorigin href="/assets/index-B4M4MeEk.css">
     </head>
     <body>
         <div id="app"></div>

package/package.json

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

package/src/matter/controller.js

@@ -326,6 +326,11 @@ async function _commissionInner(options) {
     if (!addr) throw new Error('Commission succeeded but node has no peerAddress');
     const nodeId = _nodeIdStr(addr.nodeId);
     _subscribeNodeLifecycle(clientNode, nodeId);
+    // A freshly commissioned node is already online, so the lifecycle 'online'
+    // event (the other place this is wired) will not fire again — attach the
+    // attribute watchers now or the node stays without live updates until the
+    // next daemon restart.
+    _broadcastNodeAttributes(clientNode, nodeId);
     _broadcast?.({ type: 'matter:deviceList', devices: listPaired() });
     return nodeId;
 }
@@ -394,11 +399,115 @@ async function getAttribute(nodeId, endpointId, clusterName, attrName) {
     return clusterState[attrName];
 }
 
+/**
+ * Write a single attribute value (a remote write for client nodes — the
+ * attribute must be writable per the device's Matter data model).
+ *
+ * Uses the interaction-level write rather than Endpoint.set(): set() requires
+ * a synthesized client behavior, which matter.js does not create for every
+ * cluster (e.g. basicInformation on the root endpoint reports
+ * "Behavior ... is not present on this endpoint" although the cluster and its
+ * state are there). The interaction write goes over the same wire path that
+ * commands use and needs no behavior instance.
+ *
+ * @param {string}  nodeId
+ * @param {number}  endpointId
+ * @param {string}  clusterName  camelCase cluster name, e.g. "basicInformation"
+ * @param {string}  attrName     camelCase attribute name, e.g. "nodeLabel"
+ * @param {*}       value
+ * @returns {Promise<void>}
+ */
+async function setAttribute(nodeId, endpointId, clusterName, attrName, value) {
+    const node = _findClientNode(nodeId);
+    const { Write, WriteResult } = require('@matter/protocol');
+    const clusters = require('@matter/main/clusters');
+    const clusterDef = clusters[clusterName.charAt(0).toUpperCase() + clusterName.slice(1)]?.Complete;
+    if (!clusterDef) throw new Error(`Unknown cluster "${clusterName}"`);
+    if (!clusterDef.attributes?.[attrName]) throw new Error(`Unknown attribute "${clusterName}.${attrName}"`);
+    const request = Write(Write.Attribute({ endpoint: Number(endpointId), cluster: clusterDef, attributes: attrName, value }));
+    const result = await node.interaction.write(request);
+    WriteResult.assertSuccess(result);
+}
+
+/**
+ * Rename a device by writing basicInformation.nodeLabel on the root endpoint —
+ * the Matter-standard writable user label (max 32 chars), persisted on the
+ * device itself. she prefers nodeLabel over productName wherever names are
+ * shown or matched, so the new name is immediately usable in scripts.
+ *
+ * @param {string} nodeId
+ * @param {string} name
+ * @returns {Promise<void>}
+ */
+async function rename(nodeId, name) {
+    await setAttribute(nodeId, 0, 'basicInformation', 'nodeLabel', String(name));
+    _log?.info(`matter: renamed node ${nodeId} to "${name}"`);
+    _broadcast?.({ type: 'matter:deviceList', devices: listPaired() });
+}
+
 // ── Commands ──────────────────────────────────────────────────────────────────
 
+/** Lowercase the first character (PascalCase model names → camelCase). */
+function _camelize(s) {
+    return s.charAt(0).toLowerCase() + s.slice(1);
+}
+
+/**
+ * Best-effort: list the mandatory field names (camelCase) of a command's
+ * request schema. Resolution mirrors matter.js's own command lookup:
+ *   1. the behavior's cluster definition (unwrapping a `.cluster`-wrapped
+ *      specifier like @matter/protocol Specifier.clusterFor does), commands as
+ *      a TLV Command (requestSchema/fieldDefinitions) or a model-based command
+ *      ({ schema: CommandModel });
+ *   2. fallback: the behavior's ClusterModel schema — request-direction
+ *      CommandModel children matched by camelized name (the shape generated
+ *      for discovered client clusters).
+ * Returns [] when unresolvable.
+ * @param {object} behavior     the cluster behavior (agent[clusterName])
+ * @param {string} commandName
+ * @returns {string[]}
+ */
+function _mandatoryCommandFields(behavior, commandName) {
+    try {
+        let cluster = behavior?.cluster;
+        if (cluster && typeof cluster === 'object' && 'cluster' in cluster) cluster = cluster.cluster;
+        let cmd = cluster?.commands?.[commandName];
+        if (!cmd) {
+            // Discovered client clusters: command models live on the ClusterModel schema
+            const schemaModel = behavior?.schema ?? behavior?.constructor?.schema;
+            if (schemaModel?.children) {
+                for (const c of schemaModel.children) {
+                    if (c.tag === 'command' && c.name && _camelize(c.name) === commandName && c.direction !== 'response') {
+                        cmd = { schema: c };
+                        break;
+                    }
+                }
+            }
+        }
+        const schema = cmd?.schema ?? cmd?.requestSchema;
+        if (schema?.fieldDefinitions) {
+            return Object.entries(schema.fieldDefinitions)
+                .filter(([, def]) => !def?.optional)
+                .map(([name]) => name);
+        }
+        if (schema?.children) {
+            return [...schema.children].filter((c) => c.effectiveConformance?.isMandatory !== false).map((c) => _camelize(c.name));
+        }
+    } catch {
+        /* best-effort — fall through */
+    }
+    return [];
+}
+
 /**
  * Invoke a cluster command.
  *
+ * Mandatory boilerplate fields that scripts rarely care about are filled with
+ * neutral defaults when omitted: optionsMask/optionsOverride → {} (bitmap 0,
+ * "obey the device's options") and transitionTime → 0 (instant). So
+ * she.matter.send('x', 1, 'levelControl', 'moveToLevel', { level: 128 }) works
+ * without spelling out the full Matter command schema.
+ *
  * @param {string}  nodeId
  * @param {number}  endpointId
  * @param {string}  clusterName  camelCase cluster name, e.g. "onOff"
@@ -416,10 +525,27 @@ async function sendCommand(nodeId, endpointId, clusterName, commandName, args) {
         if (!clusterAgent) throw new Error(`Cluster "${clusterName}" not found on endpoint ${endpointId}`);
         const cmd = clusterAgent[commandName];
         if (typeof cmd !== 'function') throw new Error(`Command "${commandName}" not found in cluster "${clusterName}"`);
-        // Only pass args when the caller actually provided non-empty args.
+        // Fill neutral defaults for mandatory boilerplate fields the caller omitted.
+        const merged = args !== undefined && args !== null && typeof args === 'object' ? { ...args } : {};
+        let mandatoryFields = _mandatoryCommandFields(clusterAgent, commandName);
+        if (mandatoryFields.length === 0) {
+            _log?.debug(`matter: could not resolve request fields for ${clusterName}.${commandName}`);
+            // Last resort: every LevelControl/ColorControl command carries the two
+            // options bitmaps (and the TLV encoder ignores unknown fields), so
+            // injecting them is safe even for the few commands without them.
+            if (_clusterName(clusterName) === 'levelControl' || _clusterName(clusterName) === 'colorControl') {
+                mandatoryFields = ['optionsMask', 'optionsOverride'];
+            }
+        }
+        for (const field of mandatoryFields) {
+            if (merged[field] !== undefined) continue;
+            if (field === 'optionsMask' || field === 'optionsOverride') merged[field] = {};
+            else if (field === 'transitionTime') merged[field] = 0;
+        }
+        // Only pass args when there is actually a payload.
         // Void commands (e.g. onOff.off) fail TLV validation if passed an empty object.
-        const hasArgs = args !== undefined && args !== null && Object.keys(args).length > 0;
-        return hasArgs ? cmd.call(clusterAgent, args) : cmd.call(clusterAgent);
+        const hasArgs = Object.keys(merged).length > 0;
+        return hasArgs ? cmd.call(clusterAgent, merged) : cmd.call(clusterAgent);
     });
 }
 
@@ -467,7 +593,14 @@ function _broadcastNodeAttributes(node, nodeId) {
                 }
             }
         }
-        _log?.info(`matter: watching ${count} attribute(s) on node ${nodeId}`);
+        if (count === 0) {
+            // Endpoint structure not populated yet (e.g. right after commissioning)
+            // — drop the guard so the next lifecycle 'online' event retries.
+            _attrBroadcastNodes.delete(nodeId);
+            _log?.debug(`matter: no watchable attributes on node ${nodeId} yet, will retry on next online event`);
+        } else {
+            _log?.info(`matter: watching ${count} attribute(s) on node ${nodeId}`);
+        }
     } catch (err) {
         _attrBroadcastNodes.delete(nodeId); // allow retry
         _log?.warn(`matter: attribute broadcast setup failed for ${nodeId}: ${err.message}`);
@@ -586,6 +719,8 @@ module.exports = {
     getEndpoints,
     getDeviceSubtitle,
     getAttribute,
+    setAttribute,
+    rename,
     sendCommand,
     subscribeAttribute,
     unsubscribe,

package/src/web/matter-api.js

@@ -58,6 +58,25 @@ router.post('/commission', async (req, res) => {
     }
 });
 
+// POST /she/matter/devices/:nodeId/rename — { name } → writes basicInformation.nodeLabel
+router.post('/devices/:nodeId/rename', async (req, res) => {
+    if (!isReady()) return notReady(res);
+    const name = req.body?.name;
+    if (typeof name !== 'string' || !name.trim()) {
+        return res.status(400).json({ error: 'body must contain a non-empty name' });
+    }
+    if (name.trim().length > 32) {
+        return res.status(400).json({ error: 'name must be at most 32 characters (Matter nodeLabel limit)' });
+    }
+    try {
+        await getController().rename(req.params.nodeId, name.trim());
+        res.json({ ok: true });
+    } catch (err) {
+        if (err.message.includes('not found')) return res.status(404).json({ error: err.message });
+        res.status(500).json({ error: err.message });
+    }
+});
+
 // GET /she/matter/devices/:nodeId — node detail
 router.get('/devices/:nodeId', (req, res) => {
     if (!isReady()) return notReady(res);