smart-home-engine 2.0.1 → 3.0.0-beta.0

package/src/web/log-ws.js

@@ -19,6 +19,34 @@ function sendOrDrop(ws, str) {
     ws.send(str);
 }
 const _welcomeProviders = [];
+const _clientHandlers = new Map(); // message type → (ws, msg)
+const _closeHandlers = new Set(); // (ws) when a client goes away
+
+/**
+ * Handle a message a client sends: `{ type, ... }`. One handler per type.
+ * @param {string} type
+ * @param {(ws: import('ws').WebSocket, msg: object) => void} fn
+ */
+function onClientMessage(type, fn) {
+    _clientHandlers.set(type, fn);
+}
+
+/**
+ * Called with the socket when a client disconnects — to drop what it subscribed to.
+ * @param {(ws: import('ws').WebSocket) => void} fn
+ */
+function onClientClose(fn) {
+    _closeHandlers.add(fn);
+}
+
+/**
+ * Send a JSON message to one client (dropped when it is gone or not reading).
+ * @param {import('ws').WebSocket} ws
+ * @param {object} msg
+ */
+function sendWs(ws, msg) {
+    sendOrDrop(ws, JSON.stringify(msg));
+}
 
 /**
  * Register a function that returns a welcome message (or array of messages)
@@ -54,8 +82,24 @@ function attachWss(httpServer, authCheck = () => true) {
             return;
         }
         _clients.add(ws);
-        ws.on('close', () => _clients.delete(ws));
-        ws.on('error', () => _clients.delete(ws));
+        const gone = () => {
+            if (!_clients.delete(ws)) return;
+            for (const fn of _closeHandlers) fn(ws);
+        };
+        ws.on('close', gone);
+        ws.on('error', gone);
+        // A client may ask for something — a page subscribing to the runtime snapshot: { type, ... }
+        ws.on('message', (data) => {
+            let msg;
+            try {
+                msg = JSON.parse(data.toString());
+            } catch {
+                return;
+            }
+            if (!msg || typeof msg.type !== 'string') return;
+            const handler = _clientHandlers.get(msg.type);
+            if (handler) handler(ws, msg);
+        });
         // Send current state to this new client immediately
         for (const provider of _welcomeProviders) {
             const msgs = provider();
@@ -153,5 +197,8 @@ module.exports = {
     getBrokerLogBuffer,
     getLogBuffer,
     setWelcomeProvider,
+    onClientMessage,
+    onClientClose,
+    sendWs,
     _internal: { clients: _clients, MAX_BACKLOG },
 };

package/src/web/prompts/api-ref-compact.md

@@ -1,16 +1,19 @@
 ## she sandbox API (the common part)
 Scripts start with `/* global she */` and `'use strict';`. `require()` works for installed npm packages.
 ```
-she.mqtt.sub(topic, [opts], cb)     cb(topic, val, obj)   opts: { change: true } fires on changes only; wildcards + and #
-she.mqtt.pub(topic, payload)        publish (commands: no retain)
+she.mqtt.sub(topic, [opts], cb)     cb(topic, val, obj)   opts: { change: true } fires on changes only; { debounce: 5, maxWait: 15 } (SECONDS) bundles events; wildcards + and #
+she.mqtt.pub(topic, payload, [opts]) publish (commands: no retain); { changed: true } publishes only when the payload differs from the last one
 she.mqtt.get(topic)                 last known value
 she.mqtt.age(topic)                 seconds since the value last changed
 she.mqtt.timer(src, ms, target)     publish 1 when src turns truthy, 0 after ms
+she.mqtt.command(topic, payload, [{ timeout: 5, retries: 0, confirm }])  → Promise<{ val, ms, tries }>; waits for the status topic to confirm; rejects with reason timeout | offline | superseded
 she.mqtt.or(srcs[], target) / and   publish 1 when any / all sources are truthy, else 0
 she.schedule('0 7 * * *', cb)       cron string, Date, or 'sunrise' / 'sunset' with { shift: seconds }
 she.http.fetch(url, [opts])         → Promise<{ body, code, headers }>
 she.debug / info / warn / error     logging
-setTimeout / setInterval            available
+setTimeout / setInterval            available; she.timeout(ms, cb) → handle.restart()/cancel() is a restartable timer (motion light)
+she.debounce(fn, ms, [{ maxWait }]) / she.throttle(fn, ms) / she.retry(fn, { tries, delay, onFail })   MILLISECONDS; cleared on reload
+she.time.between('22:00', '06:00') / at('06:00') / isWorkday() / format(ts, 'dd HH:mm') / iso(ts) / duration(a, b) / humanize(ms)   the daemon's zone, DST-safe; not getHours()
 ```
 Variables: read `var/status/<name>`, write `she.mqtt.pub('var/set/<name>', value)`.
 For anything else ask with the tool she_api_doc or say that you are not sure.

package/src/web/prompts/api-ref.md

@@ -8,15 +8,41 @@ she.mqtt.sub(topic, [opts], cb)        Subscribe; topic may be a string or an ar
     opts.retain     also fire for the retained value present on connect and script start
     opts.shift      delay the callback by N seconds; opts.random adds up to N random seconds
     opts.condition  fn(val) or a one-line JS string over val/obj/objPrev; the callback runs only when truthy
-    cb(topic, val, obj, objPrev, msg)   obj and objPrev are { val, ts, lc }
-she.mqtt.pub(topic, payload, [opts])   Publish; objects are JSON-stringified; opts { qos, retain }
+    opts.debounce   SECONDS: bundle events, one callback once nothing came in for N s; opts.maxWait (seconds) runs it at the latest then
+    opts.throttle   SECONDS: the first event at once, then at most one callback per N s (with the last event)
+    opts.perTopic   with debounce/throttle on an array or wildcard: one bundle per topic; opts.name names it in the timer list
+    opts.flushOnUnload  with debounce: run a pending callback once on unload/reload (default: dropped)
+    cb(topic, val, obj, objPrev, msg)   obj and objPrev are { val, ts, lc }; debounced: the last event, objPrev from before the first bundled one
+she.mqtt.pub(topic, payload, [opts])   Publish; objects are JSON-stringified; opts { qos, retain, changed }
+    opts.changed    publish only when the payload differs from this script's last publish to the topic (before that: from the topic's state, set→status)
 she.mqtt.get(topic)                    Last known value (undefined when never seen); an empty payload removes a topic
 she.mqtt.getProp(topic, 'val'|'ts'|'lc')  One property of the state; without a property the whole { val, ts, lc }
 she.mqtt.age(topic, ['message'])       Seconds since the last change, or since the last message with 'message'; NaN when never seen
 she.mqtt.link(src, target, [fn])       Forward src changes to target, optionally transformed
 she.mqtt.or / and / max / min(srcs[], topicOrCb)   Combine sources; publish 1/0 or the extreme value; re-evaluated on every change
-she.mqtt.timer(src, ms, topicOrCb)     Publish 1 when src turns truthy, 0 after ms; restarted when src fires again
+she.mqtt.timer(src, ms, topicOrCb)     Publish 1 when src turns truthy, 0 after ms (a number — swapped arguments throw at load); restarted when src fires again
                                         topicOrCb: a topic string or cb(topic, val)
+she.mqtt.command(topic, payload, [opts])  → Promise<{ val, ms, tries, already? }>: publish a command and wait for the device's status to confirm it (3.0.0-beta.0)
+    confirm topic derived: <inst>/set/<path> → <inst>/status/<path> (val); zigbee2mqtt <base>/<dev>/set → <base>/<dev> (field = the payload's key, or opts.path); else opts.confirm is required (TypeError)
+    opts { confirm, path, expect (value or fn(val); default the payload), tolerance (numbers), timeout = 5 SECONDS per attempt, retries = 0, quiet }
+    status already at the target → sent anyway, resolves at once with already: true; device offline (<inst>/connected < 2, <dev>/availability offline) → rejects at once
+    rejects with Error { reason: 'timeout' | 'offline' | 'superseded' | 'unloaded', topic, payload, tries }; timeout/offline are logged as a warning with the script name (unless quiet)
+    and counted in get_health; a rejection nobody catches is NOT an unhandled rejection. A new command to the same topic supersedes the running one. Pending commands are listed by list_timers.
+    Use it for commands whose effect matters (heating, gates, switching off); she.mqtt.pub stays fire-and-forget. Callbacks that await it become async: wrap in try/catch.
+    Lint: a pub/command to <inst>/status/… or to a zigbee2mqtt device topic is warned about at load (with the line) — commands go to the set topic.
+```
+
+### Timing helpers (MILLISECONDS, like setTimeout; cleared on unload/reload; pending runs listed by list_timers with kind and name)
+```
+she.timeout(ms, cb, [{ name }])         A restartable timer, created idle → handle.restart([ms]) arms or starts over, cancel(), pending(), remaining()
+                                        the motion-light pattern: off.restart() on every motion, off.cancel() when the state changes
+she.debounce(fn, wait, [opts])          Bundle calls: fn runs with the LAST call's args after `wait` ms of quiet; opts { maxWait, leading=false, trailing=true, flushOnUnload, name }
+                                        → wrapped(...args) with cancel(), flush(), pending(); maxWait keeps a never-resting source from starving fn
+she.throttle(fn, wait, [opts])          Rate-limit: first call at once, then at most once per `wait` ms; opts { leading=true, trailing=true, name }; trailing:false = fire, then block
+she.debounce.keyed / she.throttle.keyed(fn, wait, [opts])   One state per key (the first argument, or opts.key(...args)); cancel(key)/flush(key)/pending(key), without key: all
+she.retry(fn, [opts])                   → Promise; fn(attempt) may be async; opts { tries=3, delay=1000, backoff=1, onFail(err, tries), name }
+                                        resolves with fn's result; after the last failure: onFail's return value, or rejects without onFail; an unload stops it
+she.setTimeout / she.clearTimeout       The sandbox's setTimeout/clearTimeout under she (official aliases); a non-number delay is logged with the script name
 ```
 
 ### Scheduling
@@ -24,7 +50,22 @@ she.mqtt.timer(src, ms, topicOrCb)     Publish 1 when src turns truthy, 0 after
 she.schedule(pattern, [opts], cb)      pattern: cron string | Date | 'sunrise' 'sunset' 'dawn' 'dusk' 'nauticalDawn' 'nauticalDusk' 'solarNoon' 'night'
     opts.shift    seconds offset (-1800 = 30 min before);  opts.random  up to N random seconds later
 she.now()                              Milliseconds since the epoch
-setTimeout / setInterval               Available; cleared automatically when the script is unloaded
+setTimeout / setInterval               Available; cleared automatically when the script is unloaded; a bad delay is logged with the script name
+```
+
+### Time (she.time — the daemon's zone, DST-safe; ts = ms | Date | ISO string, default now)
+```
+she.time.between(from, to, [ts])       In the window? from/to: 'HH:mm' or a sun event with offset ('sunset-30m', 'dawn+1h', 'sunrise+90s'); from inclusive, to exclusive
+                                        to before from crosses midnight: she.time.between('22:00', '06:00') is the whole night in one call
+she.time.at(time, [ts])                ms of 'HH:mm' or a sun event on the day of ts; '24:00' = next midnight; NaN when the sun event does not occur
+she.time.startOfDay / endOfDay([ts])   ms of midnight / of the day's last ms;  she.time.addDays(ts, n)  the same wall clock n days later (DST-safe, not +86400000)
+she.time.parts([ts])                   { year, month 1-12, day, hour, minute, second, millisecond, weekday 0=Sunday, offset (min), zone } — instead of getHours()/getDay()
+she.time.isWeekend / isHoliday / isWorkday([ts])   holidays from the config (holidays: 'DE-BW', holidaysExtra: [...]); she.time.holiday([ts]) → name or null
+she.time.format(ts, [pattern])         tokens YYYY YY M MM MMM MMMM D DD H HH m mm s ss SSS dd (So) ddd (Sonntag) Z (+01:00) [literal]; default 'YYYY-MM-DD HH:mm:ss'
+she.time.iso([ts])                     '2026-10-25T02:41:00+02:00' — ISO 8601 WITH offset: sortable even in the autumn double hour
+she.time.duration(a, b)                b - a in ms, the real difference;  she.time.humanize(ms, [{ parts: 2, long }]) → '2 h 40 min' / '2 Stunden 40 Minuten'
+    DST rules: a time in the spring gap (02:30) resolves to 03:30; one in the autumn double hour to its first occurrence; windows and durations compare instants
+    Prefer she.time over new Date().getHours()/getDay()/toLocale*/padStart: those use the process zone and break around the DST change
 ```
 
 ### sheDB (documents, ids like topics: devices/lamp1)

package/src/web/runtime-api.js

@@ -0,0 +1,66 @@
+'use strict';
+
+/**
+ * The runtime model over HTTP: what every script has registered, with statistics and pending timers
+ * (`GET /she/runtime`, optionally one script), the hour's gauge history (`GET /she/runtime/history`),
+ * and the editor's actions on a timer or handler (`POST /she/runtime/action`). The live view goes
+ * over the WebSocket (`runtime:subscribe`); these endpoints serve a one-off read and the actions.
+ */
+
+const express = require('express');
+const { NotFoundError } = require('../lib/runtime');
+
+const router = express.Router();
+
+let _ctx = null;
+
+/**
+ * @param {object} ctx
+ * @param {import('../lib/runtime').Runtime} ctx.runtime
+ * @param {(label?: string) => object} ctx.snapshot the model, or one script's part by its label
+ * @param {() => {intervalMs: number, samples: object[]}} ctx.history
+ * @param {(file: string, msg: string) => void} ctx.log writes into a script's log
+ */
+function init(ctx) {
+    _ctx = ctx;
+}
+
+router.get('/', (req, res) => {
+    if (!_ctx) return res.status(503).json({ error: 'runtime not ready' });
+    const label = typeof req.query.script === 'string' ? req.query.script : undefined;
+    res.set('Cache-Control', 'no-store');
+    res.json(_ctx.snapshot(label));
+});
+
+router.get('/history', (req, res) => {
+    if (!_ctx) return res.status(503).json({ error: 'runtime not ready' });
+    res.set('Cache-Control', 'no-store');
+    res.json(_ctx.history());
+});
+
+/**
+ * An action from the editor's Runtime panel. Body: `{ id, action }` with action `cancel` or `run`.
+ * `cancel` removes a pending timer (or an interval) without running it; `run` fires a pending timer
+ * now (a debounce: its flush), runs an interval once, or runs a schedule or sun event once — the
+ * schedule stays. Every action is written into the script's log.
+ */
+router.post('/action', (req, res) => {
+    if (!_ctx) return res.status(503).json({ error: 'runtime not ready' });
+    const { id, action } = req.body || {};
+    if (typeof id !== 'string' || (action !== 'cancel' && action !== 'run')) {
+        return res.status(400).json({ error: 'expected { id, action: "cancel" | "run" }' });
+    }
+    let result;
+    try {
+        result = _ctx.runtime.action(id, action);
+    } catch (err) {
+        if (err instanceof NotFoundError) return res.status(404).json({ error: err.message });
+        if (err instanceof TypeError) return res.status(400).json({ error: err.message });
+        return res.status(500).json({ error: err.message });
+    }
+    const what = `${result.kind}${result.name ? ` "${result.name}"` : ''}`;
+    _ctx.log(result.script, `${what} ${action === 'cancel' ? 'cancelled' : 'run now'} from the editor`);
+    res.json({ ok: true, ...result });
+});
+
+module.exports = { router, init };

package/src/web/server.js

@@ -3,9 +3,9 @@
 const express = require('express');
 const path = require('path');
 const { spawn } = require('child_process');
-const semverCompare = require('semantic-compare');
 const pkg = require('../../package.json');
-const { router: configRouter } = require('./config-api');
+const { router: configRouter, DEFAULT_CONFIG_PATH } = require('./config-api');
+const updateChannel = require('../lib/update-channel');
 const { router: scriptsRouter } = require('./scripts-api');
 const { router: shedbRouter } = require('./shedb-api');
 const { router: matterRouter } = require('./matter-api');
@@ -76,6 +76,9 @@ app.use('/she/services', servicesRouter);
 // Secrets (roadmap A5): write-only, values never leave the daemon
 app.use('/she/secrets', secretsRouter);
 
+// The runtime model: handlers, timers, statistics, gauge history, the editor's timer actions
+app.use('/she/runtime', require('./runtime-api').router);
+
 // Graceful daemon restart
 // When running under systemd, delegate to `sudo systemctl restart` so the
 // service actually comes back up. Otherwise fall back to exit(0) and let
@@ -93,33 +96,61 @@ app.post('/she/restart', (req, res) => {
     setTimeout(_systemdRestart, 200);
 });
 
-// npm version check — poll once on startup and every 24 hours
-let _latestNpmVersion = null;
-async function _checkNpmVersion() {
+// Update check — the GitHub releases of she, by channel: `stable` offers the newest release,
+// `beta` also the pre-releases. Polled once at start and every 24 hours, and on the UI's button.
+const _isDocker = require('fs').existsSync('/.dockerenv');
+let _update = null; // the last check's result (update-channel.checkUpdate)
+let _startupChannel = 'stable';
+
+// The channel is read from the config file at every check, so a change on the Config page
+// takes effect without a restart; the CLI/env value is the fallback when the file has none.
+function currentChannel() {
     try {
-        const res = await fetch('https://registry.npmjs.org/smart-home-engine/latest');
-        const data = await res.json();
-        _latestNpmVersion = data.version && semverCompare(pkg.version, data.version) < 0 ? data.version : null;
+        const file = JSON.parse(require('fs').readFileSync(app.locals.configPath || DEFAULT_CONFIG_PATH, 'utf8'));
+        if (updateChannel.CHANNELS.includes(file.updateChannel)) return file.updateChannel;
     } catch {
-        /* best-effort */
+        /* no file, or not ours to parse */
     }
+    return _startupChannel;
+}
+
+async function _checkUpdate() {
+    _update = await updateChannel.checkUpdate({ installed: pkg.version, channel: currentChannel(), docker: _isDocker });
+    return _update;
+}
+
+function _updateFields() {
+    const f = { updateChannel: _update ? _update.channel : currentChannel() };
+    if (_update && _update.latest) {
+        f.latestVersion = _update.latest;
+        if (_update.latestIsPrerelease) f.latestPrerelease = true;
+    }
+    if (_update && _update.stable) f.latestStable = _update.stable;
+    if (_update && _update.prerelease) f.latestBeta = _update.prerelease;
+    if (_update && _update.error) f.updateError = _update.error;
+    return f;
 }
-_checkNpmVersion();
-setInterval(_checkNpmVersion, 24 * 60 * 60 * 1000);
 
 // Trigger an immediate version check (called by the UI refresh button)
 app.post('/she/check-update', async (req, res) => {
-    await _checkNpmVersion();
-    res.json({ latestVersion: _latestNpmVersion });
+    const r = await _checkUpdate();
+    res.json({ latestVersion: r.latest, ..._updateFields() });
 });
 
-// Update — install latest npm package, then restart
+// Update — install the offered version exactly, then restart. Without a known version there is
+// nothing to install: `npm install -g smart-home-engine` would take npm's `latest`, which can be
+// older than a running pre-release.
 app.post('/she/update', (req, res) => {
-    res.json({ ok: true });
+    const version = _update && _update.latest;
+    if (!version || _isDocker) {
+        res.status(409).json({ ok: false, error: _isDocker ? 'a Docker container is updated by pulling a new image' : 'no update known — check for updates first' });
+        return;
+    }
+    res.json({ ok: true, version });
     setTimeout(() => {
         // Use async spawn so the HTTP server (and event loop) remain responsive
         // while npm runs. spawnSync would block all HTTP polling from the UI.
-        const child = spawn('sudo', ['npm', 'install', '-g', 'smart-home-engine'], { stdio: 'inherit' });
+        const child = spawn('sudo', ['npm', 'install', '-g', `${updateChannel.PACKAGE}@${version}`], { stdio: 'inherit' });
         child.on('close', () => _systemdRestart());
     }, 200);
 });
@@ -158,10 +189,8 @@ app.get('/she/health', (req, res) => {
     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 };
-    if (_latestNpmVersion) s.latestVersion = _latestNpmVersion;
+    const s = Object.assign(_getStats ? _getStats() : { scripts: 0, topics: 0 }, _updateFields());
     s.dataDir = require('../lib/storage').STORAGE_ROOT;
     s.user = require('os').userInfo().username; // the OS user the daemon runs as (default SSH user for managed hosts)
     s.startedAt = SERVER_START_TIME;
@@ -297,6 +326,9 @@ function startServer(port, options = {}) {
     if (options.scriptDir) {
         app.locals.scriptDir = options.scriptDir;
     }
+    _startupChannel = updateChannel.normalizeChannel(options.updateChannel);
+    _checkUpdate();
+    setInterval(_checkUpdate, 24 * 60 * 60 * 1000).unref();
     const host = options.bindAddress || '0.0.0.0';
     return new Promise((resolve, reject) => {
         httpServer = app.listen(port, host, () => {