smart-home-engine 1.36.1 → 1.38.0

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

@@ -1,4 +1,4 @@
-import{m as O}from"./monaco-langs-DKJI_o9J.js";import{t as I}from"./index-Crt_IAIl.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-Crt_IAIl.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-hiXQxo8M.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.36.1",
+    "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/config.js

@@ -44,22 +44,97 @@ const config = require('yargs')
     })
     .default('config', path.join(DATA_ROOT, 'config', 'config.json'))
     .hide('config')
-    // Sensible defaults for values not present in config.json
-    .default({
-        latitude: 48.7408,
-        longitude: 9.1778,
-        name: 'she',
-        variablePrefix: 'var',
-        verbosity: 'info',
-        disableVariables: false,
-        disableWatch: false,
-        dbRetain: false,
-        dbPrefix: 'she/db/',
-        auth: 'none',
-        proxyHeader: 'X-Remote-User',
-        bindAddress: '0.0.0.0',
-        timezone: '',
-        mqttVersion: '',
+    // Sensible defaults for values not present in config.json. Declared as typed options
+    // rather than bare defaults: without a type, a value arriving from the environment
+    // stays a string, and `SHE_DISABLE_WATCH=false` would be truthy.
+    .option('url', {
+        describe: 'MQTT broker URL, e.g. mqtt://localhost — MQTT is disabled when omitted',
+        type: 'string',
+    })
+    .option('name', {
+        describe: 'instance name — MQTT client id and prefix of the connected topic',
+        default: 'she',
+        type: 'string',
+    })
+    .option('verbosity', {
+        describe: 'log level: error, warn, info, debug',
+        default: 'info',
+        type: 'string',
+    })
+    .option('latitude', {
+        describe: 'latitude for solar-event scheduling',
+        default: 48.7408,
+        type: 'number',
+    })
+    .option('longitude', {
+        describe: 'longitude for solar-event scheduling',
+        default: 9.1778,
+        type: 'number',
+    })
+    .option('timezone', {
+        describe: 'IANA timezone for schedules (default: the system timezone)',
+        default: '',
+        type: 'string',
+    })
+    .option('variable-prefix', {
+        describe: 'topic prefix for the variable system',
+        default: 'var',
+        type: 'string',
+    })
+    .option('disable-variables', {
+        describe: 'disable the variable feedback loop — set on all but one instance sharing a broker',
+        default: false,
+        type: 'boolean',
+    })
+    .option('disable-watch', {
+        describe: 'disable file watching: scripts are not reloaded when they change',
+        default: false,
+        type: 'boolean',
+    })
+    .option('db-retain', {
+        describe: 'publish sheDB document changes as retained MQTT messages',
+        default: false,
+        type: 'boolean',
+    })
+    .option('db-prefix', {
+        describe: 'topic prefix for sheDB publications',
+        default: 'she/db/',
+        type: 'string',
+    })
+    .option('auth', {
+        describe: 'authentication mode: none, password, proxy',
+        default: 'none',
+        type: 'string',
+    })
+    .option('proxy-header', {
+        describe: 'HTTP header carrying the authenticated user in proxy mode',
+        default: 'X-Remote-User',
+        type: 'string',
+    })
+    .option('bind-address', {
+        describe: 'interface the HTTP server binds to — 127.0.0.1 when behind a reverse proxy',
+        default: '0.0.0.0',
+        type: 'string',
+    })
+    .option('mqtt-version', {
+        describe: 'MQTT protocol version to force (3, 4 or 5; default: negotiated)',
+        default: '',
+        type: 'string',
+    })
+    .option('safe-mode', {
+        describe: 'start without loading any user script (recovery mode — see safeModeAutoDetect)',
+        default: false,
+        type: 'boolean',
+    })
+    .option('safe-mode-auto-detect', {
+        describe: 'enter safe mode automatically after an unclean shutdown (default: true)',
+        default: true,
+        type: 'boolean',
+    })
+    .option('script-timeout', {
+        describe: "ms a script's synchronous top-level code may run before it is terminated, 0 = no limit (default: 5000)",
+        default: 5000,
+        type: 'number',
     })
     .option('sentinel-timeout', {
         describe: 'ms to wait for the retained-state sentinel after connecting to MQTT (default: 5000)',
@@ -70,8 +145,19 @@ const config = require('yargs')
         describe: 'create system user and install systemd service, then exit (run as root)',
         type: 'boolean',
     })
+    // Every option is also settable as SHE_<OPTION> (SCREAMING_SNAKE_CASE), e.g. SHE_PORT,
+    // SHE_BIND_ADDRESS, SHE_SAFE_MODE_AUTO_DETECT. Precedence: CLI > env > config file >
+    // default. The trailing underscore in the prefix matters — yargs matches the prefix as
+    // a plain string, so 'SHE' alone would also swallow SHELL (SHE + LL → config.ll).
+    .env('SHE_')
     .version()
     .help('help')
     .parseSync();
 
+// SHE_SECRETS_KEY is not an option: lib/secrets.js reads it straight from the environment.
+// The prefix match picks it up anyway, and the config object is debug-logged at startup —
+// so drop the master key here rather than print it.
+delete config.secretsKey;
+delete config['secrets-key'];
+
 module.exports = config;

package/src/index.js

@@ -121,6 +121,62 @@ const log = {
 }
 const pkg = require('../package.json');
 
+// ---------------------------------------------------------------------------
+// Safe mode (roadmap S4): start the daemon without executing any user script.
+// Entered explicitly with --safe-mode, or automatically when the previous run
+// did not shut down cleanly — a script blocking the event loop forever leaves
+// the sentinel behind because neither the exit handler nor SIGTERM ever runs.
+// ---------------------------------------------------------------------------
+const _sentinelFile = _path.join(require('./lib/storage').STORAGE_ROOT, '.she-running');
+
+/**
+ * Who left the marker behind: `null` nobody (clean start), `'live'` a second instance
+ * sharing this data directory (documented setup — see cli.md "Multiple instances"),
+ * `'stale'` a run that was killed. Only 'stale' means safe mode; a PID reused by an
+ * unrelated process after a reboot is the one case this misses, which is the harmless
+ * direction to be wrong in.
+ */
+function _sentinelState() {
+    let pid;
+    try {
+        pid = parseInt(_fs.readFileSync(_sentinelFile, 'utf8').trim(), 10);
+    } catch {
+        return null; // no marker
+    }
+    if (!pid) return 'stale';
+    try {
+        process.kill(pid, 0);
+        return 'live';
+    } catch (e) {
+        return e.code === 'EPERM' ? 'live' : 'stale'; // EPERM: alive, just not ours
+    }
+}
+const _sentinelBefore = _sentinelState();
+const SAFE_MODE = config.safeMode === true || (config.safeModeAutoDetect !== false && _sentinelBefore === 'stale');
+let _sentinelWritten = false;
+function _clearSentinel() {
+    if (!_sentinelWritten) return;
+    _sentinelWritten = false;
+    try {
+        _fs.unlinkSync(_sentinelFile);
+    } catch {
+        /* already gone */
+    }
+}
+if (_sentinelBefore !== 'live') {
+    try {
+        _fs.writeFileSync(_sentinelFile, String(process.pid));
+        _sentinelWritten = true;
+    } catch (e) {
+        // not fatal — auto-detect simply never triggers when the file cannot be written
+        console.error('could not write ' + _sentinelFile + ': ' + e.message);
+    }
+}
+// Runs on exit(0) from the restart endpoint and on a normal end of the event loop.
+process.on('exit', _clearSentinel);
+// Wall-clock budget for a script's synchronous top-level code (0 = no limit).
+const SCRIPT_TIMEOUT_MS = typeof config.scriptTimeout === 'number' && config.scriptTimeout >= 0 ? config.scriptTimeout : 5000;
+
 /**
  * Build a short log label for a script file.
  * Uses the path relative to the configured script dir(s) when possible,
@@ -147,6 +203,14 @@ process.on('unhandledRejection', (reason) => {
 });
 
 log.info('she ' + pkg.version + ' starting');
+if (_sentinelBefore === 'live') log.info(`another she instance already uses ${require('./lib/storage').STORAGE_ROOT} — leaving its ${_path.basename(_sentinelFile)} marker alone`);
+if (SAFE_MODE) {
+    if (config.safeMode === true) log.warn('SAFE MODE (--safe-mode): user scripts are not loaded. Restart without the flag to run them.');
+    else
+        log.warn(
+            `SAFE MODE: ${_sentinelFile} was left behind, so the previous run was killed rather than stopped — a script may be blocking the event loop. User scripts are not loaded; fix the script and restart. Set "safeModeAutoDetect": false to disable this detection.`,
+        );
+}
 log.debug('loaded config: ', config);
 
 if (typeof config.port !== 'undefined') {
@@ -465,14 +529,26 @@ require('./web/server').setStatsProvider(() => {
         eluPercent: Math.round(eluDelta.utilization * 100),
         elMeanMs,
         elMaxMs,
+        safeMode: SAFE_MODE,
     };
 });
 
+// Health probe for GET /she/health (roadmap A1) — cheap, no counting, no allocation.
+require('./web/server').setHealthProvider(() => ({
+    started: _started,
+    mqttConfigured: !!config.url,
+    mqttConnected: connected,
+    scripts: Object.keys(scripts).length,
+    safeMode: SAFE_MODE,
+}));
+
 // Push current script:running state so the UI green dots survive a browser reload.
 setWelcomeProvider(() => Object.keys(scripts).map((f) => ({ type: 'script:running', path: makeLabel(f).slice(0, -1), running: true })));
 
 if (!config.url) {
-    log.warn('no MQTT broker URL configured — set "url" in ' + path.join(require('os').homedir(), '.she', 'config.json'));
+    // config.config is the file actually in use — hardcoding ~/.she misleads anyone
+    // running with --data-dir / SHE_DATA_DIR or --config.
+    log.warn('no MQTT broker URL configured — set "url" in ' + config.config + ' (or pass --url / SHE_URL)');
 }
 
 if (config.url) {
@@ -1255,8 +1331,16 @@ function runScript(script, name, _origin) {
     scriptDomain.run(() => {
         log.debug(logLabel, 'running');
         try {
-            script.runInContext(context);
+            // The timeout only covers synchronous top-level code — a callback registered
+            // here can still block the loop later (that is what the heartbeat reports).
+            script.runInContext(context, SCRIPT_TIMEOUT_MS > 0 ? { timeout: SCRIPT_TIMEOUT_MS } : undefined);
         } catch (e) {
+            if (e && e.code === 'ERR_SCRIPT_EXECUTION_TIMEOUT') {
+                // Killing the script mid-run leaves whatever it registered before the
+                // timeout in place; loading continues with the remaining scripts.
+                log.error(logLabel, `top-level code did not finish within ${SCRIPT_TIMEOUT_MS} ms and was terminated ("scriptTimeout", 0 disables this)`);
+                return;
+            }
             // Contain top-level script errors: without this, the exception
             // unwinds through the caller (e.g. the watcher batch loading many
             // scripts in one tick) and aborts loading of subsequent scripts.
@@ -1621,6 +1705,10 @@ function loadDir(dir) {
     }
 }
 function start() {
+    if (SAFE_MODE) {
+        log.warn('safe mode: no script is loaded and the script directory is not watched. Edit or delete the offending script in the web UI, then restart the daemon.');
+        return;
+    }
     if (config.heartbeat?.enabled) {
         const _hbInterval = typeof config.heartbeat.interval === 'number' ? config.heartbeat.interval : 50;
         const _hbThreshold = typeof config.heartbeat.threshold === 'number' ? config.heartbeat.threshold : 300;
@@ -1669,6 +1757,9 @@ function start() {
 }
 
 async function gracefulShutdown(signal) {
+    // First thing, synchronously: the async cleanup below may outlive systemd's
+    // TimeoutStopSec, and a SIGKILL after that must not look like a crash.
+    _clearSentinel();
     log.info(`got ${signal}. exiting.`);
     if (config.matterStorage) {
         try {

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/server.js

@@ -32,7 +32,10 @@ app.use('/she/auth', authRouter);
 // /api/* is intentionally excluded — user scripts control their own auth.
 // The remote-host bootstrap script and its callback are fetched by curl on the target host: no
 // session, but useless without the one-time token they carry (services-api validates it).
-const OPEN_SHE_PATHS = new Set(['/she/auth/mode', '/she/auth/login', '/she/auth/logout', '/she/services/setup.sh', '/she/services/setup/done']);
+// /she/health is public on purpose: Docker HEALTHCHECK, nginx upstream probes and monitoring
+// agents cannot present a session. It answers with a status only — the version is added for
+// authenticated callers, the rest of the payload is counters that give nothing away.
+const OPEN_SHE_PATHS = new Set(['/she/auth/mode', '/she/auth/login', '/she/auth/logout', '/she/services/setup.sh', '/she/services/setup/done', '/she/health']);
 app.use('/she', (req, res, next) => {
     if (OPEN_SHE_PATHS.has(req.originalUrl.split('?')[0])) return next();
     authMiddleware(req, res, next);
@@ -124,6 +127,32 @@ let _getStats = null;
 function setStatsProvider(fn) {
     _getStats = fn;
 }
+
+// Health check (roadmap A1) — 200 while the daemon can do its job, 503 otherwise.
+// Not healthy: still starting up (waiting for retained MQTT state or the Matter
+// controller), or a broker is configured but not connected. Safe mode stays 200:
+// it is a deliberate state the user has to reach the web UI to get out of, so a
+// probe that takes the daemon out of an upstream pool would be counterproductive.
+let _getHealth = null;
+function setHealthProvider(fn) {
+    _getHealth = fn;
+}
+app.get('/she/health', (req, res) => {
+    const h = _getHealth ? _getHealth() : null;
+    const mqtt = !h ? 'unknown' : h.mqttConfigured ? (h.mqttConnected ? 'connected' : 'disconnected') : 'disabled';
+    const ok = !!h && h.started && mqtt !== 'disconnected';
+    const body = {
+        status: ok ? 'ok' : 'degraded',
+        uptime: Math.round((Date.now() - SERVER_START_TIME) / 1000),
+        started: !!h?.started,
+        mqtt,
+        scripts: h?.scripts ?? 0,
+    };
+    if (h?.safeMode) body.safeMode = true;
+    if (checkAuth(req)) body.version = pkg.version;
+    res.set('Cache-Control', 'no-store');
+    res.status(ok ? 200 : 503).json(body);
+});
 const _isDocker = require('fs').existsSync('/.dockerenv');
 app.get('/she/status', (req, res) => {
     const s = _getStats ? _getStats() : { scripts: 0, topics: 0 };
@@ -290,4 +319,4 @@ function stopServer() {
     });
 }
 
-module.exports = { app, registerRoute, unregisterRoutesByScript, setStatsProvider, startServer, stopServer };
+module.exports = { app, registerRoute, unregisterRoutesByScript, setStatsProvider, setHealthProvider, startServer, stopServer };