smart-home-engine 1.37.0 → 1.38.0

package/dist/web/assets/{tsMode-CLQ49mna.js → tsMode-BQh1DHEC.js}

@@ -1,4 +1,4 @@
-import{m as O}from"./monaco-langs-DKJI_o9J.js";import{t as I}from"./index-CHsE05wI.js";/*!-----------------------------------------------------------------------------
+import{m as O}from"./monaco-langs-DKJI_o9J.js";import{t as I}from"./index-5np-MgKm.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-CHsE05wI.js"></script>
+      <script type="module" crossorigin src="/assets/index-5np-MgKm.js"></script>
       <link rel="modulepreload" crossorigin href="/assets/monaco-langs-DKJI_o9J.js">
       <link rel="stylesheet" crossorigin href="/assets/monaco-langs-DyX1CsEw.css">
-      <link rel="stylesheet" crossorigin href="/assets/index-BWan5OPE.css">
+      <link rel="stylesheet" crossorigin href="/assets/index-Ggp8nXi_.css">
     </head>
     <body>
         <div id="app"></div>

package/package.json

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

package/service/she-servicectl

@@ -23,6 +23,7 @@
 #   she-servicectl env    <adapter> <instance> read|write        (write: file on stdin)
 #   she-servicectl broker-env read|write                          (write: file on stdin)
 #   she-servicectl schema <adapter>
+#   she-servicectl discover <adapter> [--timeout <s>] [--address <addr-or-cidr>]...   scan for devices, JSON on stdout
 #   she-servicectl install   <adapter> <instance>                 (options as KEY=VALUE lines on stdin)
 #   she-servicectl uninstall <adapter> <instance>
 #   she-servicectl npm    <adapter> version|origin|install|update|uninstall [--purge]   (uninstall: package, template unit; --purge also /etc and /var/lib)
@@ -41,7 +42,7 @@
 
 set -eu
 
-VERSION=10
+VERSION=11
 BROKER_ENV=/etc/mqtt-interfaces/broker.env
 UNIT_DIR=/etc/systemd/system
 
@@ -417,6 +418,35 @@ cmd_schema() {
     exec "$cmd" --config-schema
 }
 
+# The adapter's own --discover (core 0.9+): it owns the hint, the protocols and the rate limiting.
+# Runs on this host on purpose — broadcast, multicast, ARP and /dev only reach the network and the
+# usb bus of the machine the scan runs on, which is this one, not necessarily she's.
+cmd_discover() {
+    [ $# -ge 1 ] || die "usage: discover <adapter> [--timeout <s>] [--address <addr>]..."
+    need_adapter "$1"
+    cmd=$(adapter_cmd "$1") || die "adapter not installed: $1"
+    shift
+    set -- --discover --discover-json "$@"
+    args=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --discover|--discover-json) args="$args $1"; shift ;;
+            --timeout)
+                [ $# -ge 2 ] || die "--timeout needs a value"
+                case "$2" in ''|*[!0-9]*) die "invalid timeout: $2" ;; esac
+                args="$args --discover-timeout $2"; shift 2 ;;
+            --address)
+                [ $# -ge 2 ] || die "--address needs a value"
+                # an address or a cidr range, nothing that could become a second argument
+                case "$2" in *[!0-9A-Za-z.:/_-]*|'') die "invalid address: $2" ;; esac
+                args="$args --discover-address $2"; shift 2 ;;
+            *) die "unknown discover option: $1" ;;
+        esac
+    done
+    # shellcheck disable=SC2086  # args is built from validated tokens above
+    exec "$cmd" $args
+}
+
 cmd_install() {
     [ $# -eq 2 ] || die "usage: install <adapter> <instance>  (KEY=VALUE lines on stdin)"
     need_adapter "$1"; need_instance "$2"
@@ -646,6 +676,7 @@ case "$c" in
     env) cmd_env "$@" ;;
     broker-env) cmd_broker_env "$@" ;;
     schema) cmd_schema "$@" ;;
+    discover) cmd_discover "$@" ;;
     install) cmd_install "$@" ;;
     uninstall) cmd_uninstall "$@" ;;
     npm) cmd_npm "$@" ;;

package/src/lib/device-discovery.js

@@ -0,0 +1,194 @@
+'use strict';
+
+/**
+ * Device discovery (roadmap I13): shaping what an adapter's `--discover --discover-json` printed
+ * into what the Add-instance UI needs.
+ *
+ * The adapter owns the scanning (mqtt-interfaces-core 0.9 `lib/discovery.js`: SSDP, mDNS/DNS-SD,
+ * UDP probes, port probes, subnet sweeps, ARP/OUI, USB serial ports). This module never scans —
+ * it validates the JSON that came back over the helper, decides what goes into the config, and
+ * proposes an instance name.
+ *
+ * Everything here treats its input as hostile: it was printed by a device on the network that
+ * answered a broadcast, and it ends up in a config file, a systemd unit name and an MQTT topic.
+ */
+
+/** Fields of a core discovery entry we pass on, with the maximum length we keep of each. */
+const STRING_FIELDS = {
+    address: 128,
+    fqdn: 253,
+    hostname: 63,
+    name: 120,
+    model: 120,
+    type: 120,
+    serial: 120,
+    version: 60,
+    id: 253, // serial: the /dev/serial/by-id name
+    device: 253, // serial: the /dev/tty* the by-id name points at
+    udn: 120,
+};
+
+/** Instance names are topic prefixes, systemd instances and file names all at once. */
+const INSTANCE_RE = /^[A-Za-z0-9_.-]+$/;
+const MAX_NAME = 32;
+
+/** German first, then whatever else NFKD can strip an accent off. */
+const TRANSLITERATE = [
+    [/ä/g, 'ae'],
+    [/ö/g, 'oe'],
+    [/ü/g, 'ue'],
+    [/Ä/g, 'Ae'],
+    [/Ö/g, 'Oe'],
+    [/Ü/g, 'Ue'],
+    [/ß/g, 'ss'],
+];
+
+function cleanString(value, max) {
+    if (typeof value !== 'string') return null;
+    // control characters would break the log line and the terminal of whoever cats the env file
+    // eslint-disable-next-line no-control-regex
+    const stripped = value.replace(/[\u0000-\u001f\u007f]/g, '').trim();
+    return stripped ? stripped.slice(0, max) : null;
+}
+
+/**
+ * Turn a device's own name into something usable as an instance name.
+ * "Küche Oben" → "kueche-oben". Returns null when nothing usable is left.
+ * @param {string} value the name the device answers with
+ * @returns {string|null}
+ */
+function slugName(value) {
+    const cleaned = cleanString(value, 200);
+    if (!cleaned) return null;
+    let out = cleaned;
+    for (const [re, replacement] of TRANSLITERATE) out = out.replace(re, replacement);
+    out = out
+        .normalize('NFKD')
+        .replace(/[\u0300-\u036f]/g, '') // the accents NFKD just split off
+        .toLowerCase()
+        .replace(/[^a-z0-9_.-]+/g, '-')
+        .replace(/-{2,}/g, '-')
+        .replace(/^[-._]+|[-._]+$/g, '')
+        .slice(0, MAX_NAME)
+        .replace(/[-._]+$/, ''); // the slice may have ended on a separator
+    // all digits would be a uuid or a serial rather than a name, and reads like an index
+    if (!out || !INSTANCE_RE.test(out) || /^[0-9]+$/.test(out)) return null;
+    return out;
+}
+
+/**
+ * A name not taken yet, suffixed `-2`, `-3`, … Instance names are MQTT topic prefixes, so the
+ * set to avoid is every instance she knows of — any adapter, any host — not just this adapter's.
+ * @param {string} base
+ * @param {Set<string>} taken lower-cased names already in use
+ * @returns {string}
+ */
+function uniqueName(base, taken) {
+    if (!taken.has(base)) return base;
+    for (let n = 2; n < 100; n++) {
+        const stem = base.slice(0, MAX_NAME - String(n).length - 1).replace(/[-._]+$/, '');
+        const candidate = `${stem}-${n}`;
+        if (!taken.has(candidate)) return candidate;
+    }
+    return base;
+}
+
+/**
+ * The value that goes into the config: the qualified name when DNS knows the device, its address
+ * otherwise — the same choice `--<option> auto` makes in the core, and for the same reason, a
+ * name outlives a DHCP lease. The short hostname is deliberately not used: it only resolves
+ * through the search list of whoever asks. For a serial port the address *is* the by-id path.
+ * @param {object} entry
+ * @returns {string|null}
+ */
+function configValue(entry) {
+    const fqdn = cleanString(entry.fqdn, STRING_FIELDS.fqdn);
+    const address = cleanString(entry.address, STRING_FIELDS.address);
+    return fqdn || address;
+}
+
+/**
+ * Validate and shape the entries of `--discover-json`.
+ *
+ * @param {unknown} raw parsed JSON from the adapter
+ * @param {object} [options]
+ * @param {Set<string>|string[]} [options.taken] instance names already in use (any adapter, any host)
+ * @param {Map<string,string>|object} [options.usedBy] configured value → instance using it
+ * @param {string} [options.fallbackName] instance name to build on when a device has no name of its own
+ * @param {number} [options.max] maximum number of devices returned (default 50)
+ * @returns {Array<object>} devices, each `{value, suggestName, usedBy, sources, services, …}`
+ */
+function shapeDevices(raw, options = {}) {
+    if (!Array.isArray(raw)) return [];
+    const taken = new Set([...(options.taken ?? [])].map((n) => String(n).toLowerCase()));
+    const usedBy = options.usedBy instanceof Map ? options.usedBy : new Map(Object.entries(options.usedBy ?? {}));
+    const max = Number.isFinite(options.max) ? options.max : 50;
+    const out = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+        const value = configValue(entry);
+        if (!value) continue; // an entry we cannot configure anything with is of no use here
+        const device = { value };
+        for (const [field, maxLen] of Object.entries(STRING_FIELDS)) {
+            const clean = cleanString(entry[field], maxLen);
+            if (clean) device[field] = clean;
+        }
+        device.sources = Array.isArray(entry.sources)
+            ? entry.sources
+                  .map((s) => cleanString(s, 20))
+                  .filter(Boolean)
+                  .slice(0, 8)
+            : [];
+        device.services = {};
+        if (entry.services && typeof entry.services === 'object' && !Array.isArray(entry.services)) {
+            for (const [label, open] of Object.entries(entry.services).slice(0, 24)) {
+                const clean = cleanString(label, 40);
+                if (clean) device.services[clean] = open === true;
+            }
+        }
+        // The name the *user* gave the device (core convention: `name`), not what it is
+        // (`model`/`type`) — an instance name built from a model would repeat per device.
+        const slug = slugName(entry.name) ?? (options.fallbackName ? slugName(options.fallbackName) : null);
+        if (slug) {
+            const unique = uniqueName(slug, taken);
+            device.suggestName = unique;
+            taken.add(unique); // two speakers both called "Küche" must not both propose kueche
+        }
+        // An instance may have been configured with any of the identifiers this device answers
+        // to: the raw /dev/ttyACM0 rather than the by-id path, or the address before dns knew a
+        // name for it. Matching only `value` would offer a stick that is already in use.
+        device.usedBy = null;
+        for (const identifier of [value, device.address, device.fqdn, device.hostname, device.device, device.id]) {
+            if (identifier && usedBy.has(identifier)) {
+                device.usedBy = usedBy.get(identifier);
+                break;
+            }
+        }
+        out.push(device);
+        if (out.length >= max) break;
+    }
+    return out;
+}
+
+/**
+ * The discovery kinds a schema asks for, from the `x-discover` marker the core sets on the one
+ * property that takes what a scan finds (`ccu-address`, `serialport`, …).
+ *
+ * @param {object|null} schema a `--config-schema` document
+ * @returns {{key: string, envName: string, kinds: string[]}|null} null when not discovery-capable
+ */
+function discoverTarget(schema) {
+    const properties = schema && typeof schema === 'object' ? schema.properties : null;
+    if (!properties || typeof properties !== 'object') return null;
+    for (const [key, prop] of Object.entries(properties)) {
+        if (!prop || typeof prop !== 'object' || prop['x-discover'] === undefined) continue;
+        const raw = prop['x-discover'];
+        // 'network' | 'serial' | both; `true` from a future core is treated as a network scan
+        const kinds = (Array.isArray(raw) ? raw : [raw]).map((k) => (k === true ? 'network' : k)).filter((k) => k === 'network' || k === 'serial');
+        if (kinds.length === 0) continue;
+        return { key, envName: typeof prop['x-env'] === 'string' ? prop['x-env'] : null, kinds };
+    }
+    return null;
+}
+
+module.exports = { shapeDevices, slugName, uniqueName, configValue, discoverTarget, INSTANCE_RE, MAX_NAME };

package/src/lib/services-host.js

@@ -26,7 +26,7 @@ const { execFile, spawn } = require('child_process');
 const sshDeploy = require('./ssh-deploy');
 
 const HELPER = '/usr/local/bin/she-servicectl';
-const HELPER_VERSION = 10; // must match VERSION in service/she-servicectl
+const HELPER_VERSION = 11; // must match VERSION in service/she-servicectl
 /** Default identity for services.hosts[].ssh — one key for all managed hosts (I5). */
 const DEFAULT_SERVICES_IDENTITY = '~/.she/ssh/services_id_ed25519';
 /** The helper as shipped with this she version (copied to remote hosts by the deploy route). */

package/src/web/services-api.js

@@ -52,6 +52,7 @@ const fs = require('fs');
 const crypto = require('crypto');
 const dns = require('dns');
 const { analyzeServices, wipeTopics, LOG_LEVELS } = require('../lib/services-inventory');
+const { shapeDevices, discoverTarget } = require('../lib/device-discovery');
 const npmRegistry = require('../lib/npm-registry');
 const catalog = require('../lib/services-catalog');
 const os = require('os');
@@ -602,9 +603,10 @@ async function listHosts(req) {
     );
 }
 
-// every mutating host route changes what the listing would show
+// every mutating host route changes what the listing would show — a scan does not, and
+// re-listing every host (ssh round trips included) after each one would be pure waste
 router.use((req, res, next) => {
-    if (req.method !== 'GET') {
+    if (req.method !== 'GET' && !req.path.endsWith('/discover')) {
         res.on('finish', () => {
             if (req.path.startsWith('/hosts/')) invalidateHosts();
         });
@@ -803,6 +805,130 @@ router.get('/hosts/:host/adapters/:adapter/schema', async (req, res) => {
     }
 });
 
+// POST /she/services/hosts/:host/adapters/:adapter/discover { timeout?, address? }
+/**
+ * Scan for devices with the adapter's own `--discover` on the target host (roadmap I13).
+ *
+ * The scan has to run *there*: broadcast, multicast, ARP and /dev/serial only reach the network
+ * and the usb bus of the machine running the scan, and that is the adapter's host, not
+ * necessarily she's. The adapter owns the protocols; she shapes the answer and adds what only it
+ * knows — which devices an instance already uses, and a free instance name.
+ */
+router.post('/hosts/:host/adapters/:adapter/discover', async (req, res) => {
+    const entry = resolve(req, res, { adapter: true });
+    if (!entry) return;
+    const adapter = req.params.adapter;
+    const body = req.body || {};
+    const args = ['discover', adapter];
+    if (body.timeout !== undefined) {
+        const timeout = Number(body.timeout);
+        if (!Number.isInteger(timeout) || timeout < 1 || timeout > 120) return res.status(400).json({ error: 'timeout must be 1-120 seconds' });
+        args.push('--timeout', String(timeout));
+    }
+    const addresses = body.address === undefined ? [] : Array.isArray(body.address) ? body.address : [body.address];
+    if (addresses.length > 8) return res.status(400).json({ error: 'at most 8 addresses' });
+    for (const address of addresses) {
+        // an ipv4 address, a hostname or a cidr range — the helper validates again
+        if (typeof address !== 'string' || !/^[A-Za-z0-9.:_-]+(\/[0-9]{1,3})?$/.test(address) || address.length > 64) {
+            return res.status(400).json({ error: 'invalid address: ' + String(address).slice(0, 40) });
+        }
+        args.push('--address', address);
+    }
+    let schema;
+    try {
+        // not swallowed: an unreachable host or a missing helper must say so, rather than come
+        // out as "this adapter cannot be discovered", which sends the user after the wrong thing
+        schema = await loadSchema(entry.driver, adapter);
+    } catch (err) {
+        return hostError(res, err);
+    }
+    const target = discoverTarget(schema);
+    if (!target) return res.status(400).json({ error: adapter + ' does not support discovery', code: 'NO_DISCOVERY' });
+    try {
+        // one listing serves both the free-name check and the "already configured" markers
+        let listing = null;
+        try {
+            listing = parseList((await entry.driver.exec(['list'], { timeout: 30000 })).stdout);
+        } catch {
+            /* the scan is still worth running without it */
+        }
+        // the adapter listens per method for the timeout, and a --discover-address sweep of a /24
+        // adds a minute of tcp connects on top: give the helper room rather than killing a scan
+        const seconds = body.timeout === undefined ? 5 : Number(body.timeout);
+        const { stdout } = await entry.driver.exec(args, { timeout: (seconds + 20) * 1000 + addresses.length * 60000 });
+        let raw;
+        try {
+            raw = JSON.parse(stdout);
+        } catch {
+            throw new HostError('EXEC_FAILED', adapter + ' did not print discovery JSON');
+        }
+        res.json({
+            devices: shapeDevices(raw, {
+                taken: await knownInstanceNames(listing),
+                usedBy: await configuredValues(entry, adapter, target.envName, listing),
+                fallbackName: typeof schema?.properties?.name?.default === 'string' ? schema.properties.name.default : null,
+            }),
+            property: target.key,
+            envName: target.envName,
+            kinds: target.kinds,
+        });
+    } catch (err) {
+        hostError(res, err);
+    }
+});
+
+/**
+ * Every instance name she knows of: the retained MQTT inventory (every instance that ever
+ * connected, whatever host it runs on), the cached listing of all hosts when it is warm, and the
+ * listing of the host being installed on. An instance name is an MQTT topic prefix, so a name
+ * taken by another adapter on another host is taken all the same.
+ * @param {{instances?: Array<{instance: string}>}|null} listing the target host's listing
+ * @returns {Promise<Set<string>>}
+ */
+async function knownInstanceNames(listing) {
+    const names = new Set();
+    const add = (name) => {
+        if (typeof name === 'string' && name) names.add(name.toLowerCase());
+    };
+    if (_store) {
+        for (const inst of analyzeServices(_store.mqttEntries()).instances) add(inst.instance);
+    }
+    if (_hostsCache) {
+        try {
+            for (const host of await _hostsCache.promise) {
+                for (const unit of host.instances ?? []) add(unit.instance);
+            }
+        } catch {
+            /* a host that cannot be listed contributes no names */
+        }
+    }
+    for (const unit of listing?.instances ?? []) add(unit.instance);
+    return names;
+}
+
+/**
+ * What the adapter's instances on this host are already pointed at: `<value> → <instance>`, read
+ * from their env files. Best effort — an unreadable env file only means one missing marker.
+ * @returns {Promise<Map<string,string>>}
+ */
+async function configuredValues(entry, adapter, envName, listing) {
+    const used = new Map();
+    if (!envName || !listing) return used;
+    const instances = (listing.instances ?? []).filter((i) => i.adapter === adapter);
+    await Promise.all(
+        instances.map(async (unit) => {
+            try {
+                const { stdout } = await entry.driver.exec(['env', adapter, unit.instance, 'read'], { timeout: 15000 });
+                const value = parseEnvFile(stdout)[envName];
+                if (typeof value === 'string' && value.trim()) used.set(value.trim(), unit.instance);
+            } catch {
+                /* not readable: this instance simply does not mark a device */
+            }
+        }),
+    );
+    return used;
+}
+
 // POST /she/services/hosts/:host/adapters/:adapter/install { instance, env }
 router.post('/hosts/:host/adapters/:adapter/install', async (req, res) => {
     const entry = resolve(req, res, { adapter: true });