smart-home-engine 1.36.1 → 1.37.0

package/dist/web/assets/{tsMode-eTXPyDTL.js → tsMode-CLQ49mna.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-CHsE05wI.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-CHsE05wI.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-BWan5OPE.css">
     </head>
     <body>
         <div id="app"></div>

package/package.json

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

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/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 };