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

package/src/lib/call-site.js

@@ -0,0 +1,51 @@
+'use strict';
+/**
+ * Where in a script a registration came from: the first stack frame that lies in the script's own
+ * file. The sandbox APIs call this when a script registers a subscription, a schedule or a timer, so
+ * the editor's Runtime panel can jump to the line. Frames of the daemon (index.js, the sandbox
+ * modules, the timing library) are skipped — a `she.mqtt.timer()` call reports the script line that
+ * called it, not the stdlib line that subscribed on its behalf.
+ *
+ * Cost: one `new Error()` with its stack captured — tens of microseconds. Registrations happen at
+ * load and a few times a second at most; the timing helpers capture once when the helper is created,
+ * not on every re-arm.
+ */
+
+const FRAME_DEPTH = 30;
+
+/**
+ * @param {string} file the script's file name as given to `new vm.Script`
+ * @returns {{line: number, column: number}|null}
+ */
+function callerLine(file) {
+    if (!file) return null;
+    const limit = Error.stackTraceLimit;
+    Error.stackTraceLimit = FRAME_DEPTH;
+    const { stack } = new Error();
+    Error.stackTraceLimit = limit;
+    return parseStack(stack, file);
+}
+
+/**
+ * @param {string} stack an Error's stack
+ * @param {string} file
+ * @returns {{line: number, column: number}|null}
+ */
+function parseStack(stack, file) {
+    if (typeof stack !== 'string') return null;
+    const needle = file + ':';
+    for (const frame of stack.split('\n')) {
+        const i = frame.indexOf(needle);
+        if (i === -1) continue;
+        // the file name must start a location: "(file:l:c)" or "at file:l:c" — not be the tail of a
+        // longer path (".../otherdir/file")
+        const before = frame[i - 1];
+        if (before !== '(' && before !== ' ' && before !== undefined) continue;
+        const m = /^(\d+):(\d+)\)?\s*$/.exec(frame.slice(i + needle.length));
+        if (!m) continue;
+        return { line: Number(m[1]), column: Number(m[2]) };
+    }
+    return null;
+}
+
+module.exports = { callerLine, parseStack };

package/src/lib/command-topics.js

@@ -0,0 +1,162 @@
+'use strict';
+/**
+ * Topic conventions behind `she.mqtt.command`: where a command's effect shows up, how to tell a
+ * device is offline, and which topics a script should not publish to because an adapter owns them.
+ *
+ * Two conventions are known:
+ *
+ * - mqtt-smarthome: `<inst>/set/<path>` is answered on `<inst>/status/<path>` with `{ val, … }`;
+ *   `<inst>/connected` is 0 (gone), 1 (mqtt only) or 2 (device reachable).
+ * - zigbee2mqtt: `<base>/<device>/set` takes `{ state: "ON" }` and the device's state is published as
+ *   one JSON object on `<base>/<device>`; `<base>/<device>/availability` is `online`/`offline` (or
+ *   `{ state: "offline" }`); `<base>/<device>/set/<attribute>` sets one attribute.
+ *
+ * Everything else needs `opts.confirm` — the functions here say so by returning null.
+ */
+
+const SMARTHOME_SET = /^(.+?)\/set\/(.+)$/;
+const Z2M_SET = /^(.+)\/set$/;
+
+/**
+ * The topic (and JSON field) where the effect of a command shows up, and the value to expect.
+ * @param {string} topic the command topic (the `a//b` shorthand already expanded)
+ * @param {*} payload what is sent
+ * @param {object} [opts] `confirm` (topic), `path` (JSON field of the status payload)
+ * @param {(topic: string) => boolean} [has] whether the state store knows a topic — breaks the tie
+ *   between `<inst>/set/<dev>/<dp>` and zigbee2mqtt's `<base>/<dev>/set/<attr>`
+ * @returns {{ topic: string, field: string|null, expect: * }|null} null when nothing can be derived
+ */
+function deriveConfirm(topic, payload, opts = {}, has = () => false) {
+    const isObj = payload !== null && typeof payload === 'object' && !Array.isArray(payload);
+    const keys = isObj ? Object.keys(payload) : [];
+    const field = typeof opts.path === 'string' && opts.path ? opts.path : null;
+    const expectFor = (f) => {
+        if (isObj) {
+            if (f && f in payload) return payload[f];
+            if ('val' in payload) return payload.val;
+            if (keys.length === 1) return payload[keys[0]];
+            return payload;
+        }
+        return payload;
+    };
+    if (typeof opts.confirm === 'string' && opts.confirm) {
+        const f = field || (isObj && !('val' in payload) && keys.length === 1 ? keys[0] : null);
+        return { topic: opts.confirm, field: f, expect: expectFor(f) };
+    }
+    let m = Z2M_SET.exec(topic);
+    if (m) {
+        // zigbee2mqtt: the device's state object; the field is the payload's single key, or `state`
+        // for a bare "ON"/"OFF"
+        const f = field || (isObj && keys.length === 1 ? keys[0] : isObj ? null : 'state');
+        return { topic: m[1], field: f, expect: expectFor(f) };
+    }
+    m = SMARTHOME_SET.exec(topic);
+    if (m) {
+        const status = `${m[1]}/status/${m[2]}`;
+        // `<base>/<dev>/set/<attr>` of zigbee2mqtt: no status topic, but the device object exists
+        if (!has(status) && has(m[1])) {
+            const attr = m[2];
+            return { topic: m[1], field: field || attr, expect: expectFor(field || attr) };
+        }
+        return { topic: status, field, expect: expectFor(field) };
+    }
+    return null;
+}
+
+/**
+ * Whether the device behind a command topic is known to be offline.
+ * @param {string} topic the command topic
+ * @param {(topic: string) => *} get the state store's value of a topic (undefined when unknown)
+ * @returns {string|null} what says so (`hm/connected = 1`), or null
+ */
+function offlineReason(topic, get) {
+    const z = Z2M_SET.exec(topic);
+    if (z) {
+        const avail = get(`${z[1]}/availability`);
+        const state = avail !== null && typeof avail === 'object' ? avail.state : avail;
+        if (typeof state === 'string' && state.toLowerCase() === 'offline') return `${z[1]}/availability = offline`;
+        return null;
+    }
+    const inst = topic.split('/')[0];
+    if (!inst) return null;
+    const c = get(`${inst}/connected`);
+    if (c === undefined || c === null) return null;
+    const n = typeof c === 'object' ? Number(c.val) : Number(c);
+    if (Number.isFinite(n) && n < 2) return `${inst}/connected = ${n}`;
+    return null;
+}
+
+/** on/true → "1", off/false → "0", else the trimmed lower-case string */
+function norm(v) {
+    if (v === true) return '1';
+    if (v === false) return '0';
+    const s = String(v).trim().toLowerCase();
+    if (s === 'on' || s === 'true') return '1';
+    if (s === 'off' || s === 'false') return '0';
+    return s;
+}
+
+/**
+ * Does a status value confirm the command?
+ * @param {*} actual the value seen on the confirm topic (the field already picked)
+ * @param {*} expect a value, or fn(actual) → boolean
+ * @param {number} [tolerance=0] for numbers
+ */
+function confirms(actual, expect, tolerance = 0) {
+    if (typeof expect === 'function') return !!expect(actual);
+    if (actual === undefined) return false;
+    if (expect !== null && typeof expect === 'object') {
+        // an object payload (several fields): every field must match
+        if (actual === null || typeof actual !== 'object') return false;
+        return Object.keys(expect).every((k) => confirms(actual[k], expect[k], tolerance));
+    }
+    const a = typeof actual === 'string' ? actual.trim() : actual;
+    const na = Number(a);
+    const ne = Number(expect);
+    if (a !== '' && expect !== '' && typeof a !== 'boolean' && typeof expect !== 'boolean' && Number.isFinite(na) && Number.isFinite(ne)) {
+        return Math.abs(na - ne) <= tolerance;
+    }
+    return norm(actual) === norm(expect);
+}
+
+/**
+ * Why a script should not publish to a topic: an adapter writes it as status.
+ * @param {string} topic
+ * @param {(topic: string) => boolean} has whether the state store knows a topic
+ * @returns {string|null}
+ */
+function statusTopicWarning(topic, has = () => false) {
+    const parts = topic.split('/');
+    if (parts.length >= 3 && parts[1] === 'status') {
+        return `"${topic}" is a status topic — adapters publish there; a command goes to "${parts[0]}/set/${parts.slice(2).join('/')}"`;
+    }
+    if (parts.length >= 2 && parts[parts.length - 1] !== 'set' && parts[parts.length - 1] !== 'get' && !topic.includes('/set/')) {
+        const base = parts[0];
+        if (has(`${base}/bridge/info`) || has(`${base}/bridge/state`)) {
+            if (parts[1] === 'bridge') return null;
+            return `"${topic}" is published by zigbee2mqtt as the device's state; a command goes to "${topic}/set"`;
+        }
+    }
+    return null;
+}
+
+const PUBLISH_CALL = /\bshe\.(mqtt\.pub|mqttpub|setValue|mqtt\.command|mqttcommand)\(\s*(['"`])([^'"`$\\\n]+)\2/g;
+
+/**
+ * The literal topics a script publishes to — for the lint at load time.
+ * @param {string} source
+ * @returns {{ line: number, api: string, topic: string }[]}
+ */
+function scanPublishTopics(source) {
+    const out = [];
+    const text = String(source || '');
+    let m;
+    PUBLISH_CALL.lastIndex = 0;
+    while ((m = PUBLISH_CALL.exec(text)) !== null) {
+        const line = text.slice(0, m.index).split('\n').length;
+        out.push({ line, api: 'she.' + m[1], topic: m[3].replace(/^([^/]+)\/\/(.+)$/, '$1/set/$2') });
+    }
+    return out;
+}
+
+module.exports = { deriveConfirm, offlineReason, confirms, statusTopicWarning, scanPublishTopics };

package/src/lib/command.js

@@ -0,0 +1,188 @@
+'use strict';
+/**
+ * `she.mqtt.command(topic, payload, [opts])`: publish a command and wait for the device's status to
+ * confirm it — with a timeout per attempt, retries, a fast failure when the device is known to be
+ * offline, and a warning in the log when the command did not take.
+ *
+ * The commander is created per script with the script's primitives (publish, the state store, the
+ * tracked timers, the unload hook), so a pending command is a timer of the script: it shows in the
+ * timer list, is cancelled when the script is unloaded, and the editor can cancel it.
+ *
+ * `she.mqtt.pub` stays fire-and-forget; this is for the commands whose effect matters.
+ */
+
+const { deriveConfirm, offlineReason, confirms } = require('./command-topics');
+
+const DEFAULT_TIMEOUT_S = 5;
+
+class CommandError extends Error {
+    /**
+     * @param {'timeout'|'offline'|'superseded'|'unloaded'|'cancelled'} reason
+     * @param {object} info topic, payload (as sent), tries, detail
+     */
+    constructor(reason, info) {
+        const why = {
+            timeout: `no confirmation within ${info.timeoutS} s${info.tries > 1 ? ` (${info.tries} attempts)` : ''}`,
+            offline: `device offline (${info.detail})`,
+            superseded: 'superseded by a newer command to the same topic',
+            unloaded: 'script unloaded',
+            cancelled: 'cancelled from the editor',
+        }[reason];
+        super(`she.mqtt.command ${info.topic} ← ${info.payload}: ${why}`);
+        this.name = 'CommandError';
+        this.reason = reason;
+        this.topic = info.topic;
+        this.payload = info.payload;
+        this.tries = info.tries;
+        if (info.confirm) this.confirm = info.confirm;
+    }
+}
+
+/**
+ * @param {object} prim the script's primitives
+ * @param {(topic: string, payload: string) => void} prim.publish
+ * @param {(topic: string) => *} prim.get the state store's value of a topic
+ * @param {(topic: string) => boolean} prim.has
+ * @param {(topic: string, cb: (val: *) => void) => () => void} prim.watch called with every new value
+ *   stored for the topic, until the returned function is called
+ * @param {(fn: Function, ms: number, meta: object) => *} prim.setTimeout the script's tracked timer;
+ *   meta is { kind: 'command', name, extra, onCancel, actions }
+ * @param {(id: *) => void} prim.clearTimeout
+ * @param {(fn: Function) => () => void} [prim.onUnload]
+ * @param {(msg: string) => void} [prim.warn] the script's warning log
+ * @param {() => void} [prim.onFail] counts a failed command (timeout, offline)
+ * @param {() => number} [prim.now]
+ * @param {() => number|null} [prim.line] the script line of the call
+ * @returns {Function} command(topic, payload, [opts]) → Promise<{ val, ms, tries, already? }>
+ */
+function createCommander(prim) {
+    const now = prim.now || Date.now;
+    const onUnload = typeof prim.onUnload === 'function' ? prim.onUnload : () => () => {};
+    const warn = typeof prim.warn === 'function' ? prim.warn : () => {};
+    const onFail = typeof prim.onFail === 'function' ? prim.onFail : () => {};
+    const lineOf = typeof prim.line === 'function' ? prim.line : () => null;
+    /** topic → the running command's abort(reason) */
+    const active = new Map();
+
+    /**
+     * @param {string} topic the command topic (`a//b` is `a/set/b`)
+     * @param {*} payload a string, number, boolean or object (JSON)
+     * @param {object} [opts]
+     * @param {string} [opts.confirm] the status topic that shows the effect (derived when omitted)
+     * @param {string} [opts.path] the field of a JSON status payload to look at
+     * @param {*} [opts.expect] the value to expect (default: the payload), or fn(val) → boolean
+     * @param {number} [opts.tolerance=0] for numbers
+     * @param {number} [opts.timeout=5] seconds per attempt
+     * @param {number} [opts.retries=0] further attempts after a timeout
+     * @param {boolean} [opts.quiet=false] no warning in the log when the command fails
+     * @returns {Promise<{ val: *, ms: number, tries: number, already?: boolean }>}
+     */
+    function command(topic, payload, opts = {}) {
+        const api = 'she.mqtt.command(topic, payload, [opts])';
+        if (typeof topic !== 'string' || !topic) throw new TypeError(`${api}: topic must be a string (got ${typeof topic})`);
+        if (payload === undefined) throw new TypeError(`${api}: payload missing`);
+        if (opts === null || typeof opts !== 'object') throw new TypeError(`${api}: opts must be an object`);
+        topic = topic.replace(/^([^/]+)\/\/(.+)$/, '$1/set/$2');
+        const payloadStr = payload !== null && typeof payload === 'object' ? JSON.stringify(payload) : String(payload);
+        const confirm = deriveConfirm(topic, payload, opts, prim.has);
+        if (!confirm) throw new TypeError(`${api}: cannot derive the status topic of "${topic}" — pass opts.confirm`);
+        const expect = 'expect' in opts ? opts.expect : confirm.expect;
+        const tolerance = typeof opts.tolerance === 'number' && opts.tolerance >= 0 ? opts.tolerance : 0;
+        const timeoutS = typeof opts.timeout === 'number' && Number.isFinite(opts.timeout) && opts.timeout > 0 ? opts.timeout : DEFAULT_TIMEOUT_S;
+        const retries = Number.isInteger(opts.retries) && opts.retries >= 0 ? opts.retries : 0;
+        if (opts.timeout !== undefined && timeoutS !== opts.timeout) throw new TypeError(`${api}: opts.timeout must be a number of seconds > 0`);
+        if (opts.retries !== undefined && retries !== opts.retries) throw new TypeError(`${api}: opts.retries must be a whole number ≥ 0`);
+        const line = lineOf();
+        const pick = (val) => (confirm.field ? (val !== null && typeof val === 'object' ? val[confirm.field] : undefined) : val);
+
+        const promise = new Promise((resolve, reject) => {
+            const t0 = now();
+            let tries = 0;
+            let timer = null;
+            let offWatch = null;
+            let offUnload = null;
+            let settled = false;
+
+            const cleanup = () => {
+                settled = true;
+                if (timer !== null) prim.clearTimeout(timer);
+                timer = null;
+                if (offWatch) offWatch();
+                if (offUnload) offUnload();
+                if (active.get(topic) === abort) active.delete(topic);
+            };
+            const fail = (reason, detail) => {
+                if (settled) return;
+                cleanup();
+                const err = new CommandError(reason, { topic, payload: payloadStr, tries: Math.max(tries, 1), timeoutS, detail, confirm: confirm.topic });
+                if (reason === 'timeout' || reason === 'offline') {
+                    onFail();
+                    if (!opts.quiet) warn(err.message + (reason === 'timeout' ? ` — nothing matching on ${confirm.topic}${confirm.field ? ' .' + confirm.field : ''}` : ''));
+                }
+                reject(err);
+            };
+            const abort = (reason) => fail(reason);
+
+            // a newer command to the same topic replaces the running one
+            const previous = active.get(topic);
+            if (previous) previous('superseded');
+            active.set(topic, abort);
+
+            const offline = offlineReason(topic, prim.get);
+            if (offline) {
+                fail('offline', offline);
+                return;
+            }
+
+            const current = pick(prim.get(confirm.topic));
+            if (confirms(current, expect, tolerance)) {
+                // the status already shows the target: send anyway (the device may be out of sync
+                // with its last report) and do not wait for an echo many devices will not send
+                prim.publish(topic, payloadStr);
+                cleanup();
+                resolve({ val: current, ms: 0, tries: 1, already: true });
+                return;
+            }
+
+            offUnload = onUnload(() => fail('unloaded'));
+            offWatch = prim.watch(confirm.topic, (val) => {
+                if (settled) return;
+                const v = pick(val);
+                if (!confirms(v, expect, tolerance)) return;
+                cleanup();
+                resolve({ val: v, ms: now() - t0, tries });
+            });
+
+            const attempt = () => {
+                tries++;
+                prim.publish(topic, payloadStr);
+                timer = prim.setTimeout(
+                    () => {
+                        timer = null;
+                        if (settled) return;
+                        if (tries <= retries) attempt();
+                        else fail('timeout');
+                    },
+                    timeoutS * 1000,
+                    {
+                        kind: 'command',
+                        name: topic,
+                        line,
+                        extra: { topic, payload: payloadStr, tries, confirm: confirm.topic },
+                        actions: { run: false },
+                        onCancel: () => fail('cancelled'),
+                    },
+                );
+            };
+            attempt();
+        });
+        // a failure is reported in the log (unless quiet); a script that does not catch it must not
+        // produce an unhandled rejection on top
+        promise.catch(() => {});
+        return promise;
+    }
+
+    return command;
+}
+
+module.exports = { createCommander, CommandError, DEFAULT_TIMEOUT_S };

package/src/lib/holidays.js

@@ -0,0 +1,188 @@
+'use strict';
+/**
+ * Public holidays as a small rule table — fixed dates and days counted from Easter Sunday —
+ * for `she.time.isHoliday()`. Regions are an ISO 3166 country code, optionally with a
+ * subdivision (`DE`, `DE-BW`, `AT`); a subdivision inherits its country's rules.
+ *
+ * Deliberately small: no library, no calendar data files. What is not a public holiday
+ * everywhere in a region is left out (Mariä Himmelfahrt in Bavaria's catholic communities,
+ * the Augsburger Friedensfest) — a local day goes into the `holidaysExtra` config list.
+ */
+
+const DAY = 86400000;
+
+/** Easter Sunday of a Gregorian year as UTC ms (Meeus/Jones/Butcher). */
+function easterSunday(year) {
+    const a = year % 19;
+    const b = Math.floor(year / 100);
+    const c = year % 100;
+    const d = Math.floor(b / 4);
+    const e = b % 4;
+    const f = Math.floor((b + 8) / 25);
+    const g = Math.floor((b - f + 1) / 3);
+    const h = (19 * a + b - d - g + 15) % 30;
+    const i = Math.floor(c / 4);
+    const k = c % 4;
+    const l = (32 + 2 * e + 2 * i - h - k) % 7;
+    const m = Math.floor((a + 11 * h + 22 * l) / 451);
+    const month = Math.floor((h + l - 7 * m + 114) / 31);
+    const day = ((h + l - 7 * m + 114) % 31) + 1;
+    return Date.UTC(year, month - 1, day);
+}
+
+/** Buß- und Bettag: the Wednesday before November 23. */
+function penanceDay(year) {
+    let t = Date.UTC(year, 10, 22);
+    while (new Date(t).getUTCDay() !== 3) t -= DAY;
+    return t;
+}
+
+const fixed = (date, name) => ({ fixed: date, name });
+const easter = (offset, name) => ({ easter: offset, name });
+
+const DE_NATIONAL = [
+    fixed('01-01', 'Neujahr'),
+    easter(-2, 'Karfreitag'),
+    easter(1, 'Ostermontag'),
+    fixed('05-01', 'Tag der Arbeit'),
+    easter(39, 'Christi Himmelfahrt'),
+    easter(50, 'Pfingstmontag'),
+    fixed('10-03', 'Tag der Deutschen Einheit'),
+    fixed('12-25', '1. Weihnachtstag'),
+    fixed('12-26', '2. Weihnachtstag'),
+];
+
+const EPIPHANY = fixed('01-06', 'Heilige Drei Könige');
+const WOMENS_DAY = fixed('03-08', 'Internationaler Frauentag');
+const CORPUS_CHRISTI = easter(60, 'Fronleichnam');
+const ASSUMPTION = fixed('08-15', 'Mariä Himmelfahrt');
+const REFORMATION = fixed('10-31', 'Reformationstag');
+const ALL_SAINTS = fixed('11-01', 'Allerheiligen');
+const CHILDRENS_DAY = fixed('09-20', 'Weltkindertag');
+const PENANCE = { compute: penanceDay, name: 'Buß- und Bettag' };
+
+const REGIONS = {
+    'DE': { name: 'Deutschland (bundesweite Feiertage)', rules: DE_NATIONAL },
+    'DE-BW': { name: 'Baden-Württemberg', parent: 'DE', rules: [EPIPHANY, CORPUS_CHRISTI, ALL_SAINTS] },
+    'DE-BY': { name: 'Bayern', parent: 'DE', rules: [EPIPHANY, CORPUS_CHRISTI, ALL_SAINTS] },
+    'DE-BE': { name: 'Berlin', parent: 'DE', rules: [WOMENS_DAY] },
+    'DE-BB': { name: 'Brandenburg', parent: 'DE', rules: [easter(0, 'Ostersonntag'), easter(49, 'Pfingstsonntag'), REFORMATION] },
+    'DE-HB': { name: 'Bremen', parent: 'DE', rules: [REFORMATION] },
+    'DE-HH': { name: 'Hamburg', parent: 'DE', rules: [REFORMATION] },
+    'DE-HE': { name: 'Hessen', parent: 'DE', rules: [CORPUS_CHRISTI] },
+    'DE-MV': { name: 'Mecklenburg-Vorpommern', parent: 'DE', rules: [WOMENS_DAY, REFORMATION] },
+    'DE-NI': { name: 'Niedersachsen', parent: 'DE', rules: [REFORMATION] },
+    'DE-NW': { name: 'Nordrhein-Westfalen', parent: 'DE', rules: [CORPUS_CHRISTI, ALL_SAINTS] },
+    'DE-RP': { name: 'Rheinland-Pfalz', parent: 'DE', rules: [CORPUS_CHRISTI, ALL_SAINTS] },
+    'DE-SL': { name: 'Saarland', parent: 'DE', rules: [CORPUS_CHRISTI, ASSUMPTION, ALL_SAINTS] },
+    'DE-SN': { name: 'Sachsen', parent: 'DE', rules: [REFORMATION, PENANCE] },
+    'DE-ST': { name: 'Sachsen-Anhalt', parent: 'DE', rules: [EPIPHANY, REFORMATION] },
+    'DE-SH': { name: 'Schleswig-Holstein', parent: 'DE', rules: [REFORMATION] },
+    'DE-TH': { name: 'Thüringen', parent: 'DE', rules: [CHILDRENS_DAY, REFORMATION] },
+    'AT': {
+        name: 'Österreich',
+        rules: [
+            fixed('01-01', 'Neujahr'),
+            EPIPHANY,
+            easter(1, 'Ostermontag'),
+            fixed('05-01', 'Staatsfeiertag'),
+            easter(39, 'Christi Himmelfahrt'),
+            easter(50, 'Pfingstmontag'),
+            CORPUS_CHRISTI,
+            ASSUMPTION,
+            fixed('10-26', 'Nationalfeiertag'),
+            ALL_SAINTS,
+            fixed('12-08', 'Mariä Empfängnis'),
+            fixed('12-25', 'Christtag'),
+            fixed('12-26', 'Stefanitag'),
+        ],
+    },
+};
+
+function normalizeRegion(code) {
+    return typeof code === 'string' ? code.trim().toUpperCase() : '';
+}
+
+function isRegion(code) {
+    return Object.prototype.hasOwnProperty.call(REGIONS, normalizeRegion(code));
+}
+
+/** @returns {Array<{code: string, name: string}>} */
+function listRegions() {
+    return Object.keys(REGIONS).map((code) => ({ code, name: REGIONS[code].name }));
+}
+
+const pad2 = (n) => String(n).padStart(2, '0');
+const mmdd = (utcMs) => {
+    const d = new Date(utcMs);
+    return `${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())}`;
+};
+
+function rulesOf(code) {
+    const region = REGIONS[normalizeRegion(code)];
+    if (!region) return [];
+    return region.parent ? [...rulesOf(region.parent), ...region.rules] : region.rules;
+}
+
+const _cache = new Map();
+
+/**
+ * The holidays of a region in one year.
+ * @param {string} code region, e.g. 'DE-BW'
+ * @param {number} year
+ * @returns {Map<string, string>} 'MM-DD' → name, in calendar order; empty for an unknown region
+ */
+function holidaysOfYear(code, year) {
+    const key = `${normalizeRegion(code)}|${year}`;
+    const hit = _cache.get(key);
+    if (hit) return hit;
+    const es = easterSunday(year);
+    const days = rulesOf(code).map((rule) => {
+        if (rule.fixed) return [rule.fixed, rule.name];
+        if (typeof rule.easter === 'number') return [mmdd(es + rule.easter * DAY), rule.name];
+        return [mmdd(rule.compute(year)), rule.name];
+    });
+    days.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+    const map = new Map(days);
+    if (_cache.size > 200) _cache.clear();
+    _cache.set(key, map);
+    return map;
+}
+
+/**
+ * Parse the `holidaysExtra` config list: strings `MM-DD` or `YYYY-MM-DD`, optionally followed
+ * by a name (`"05-08 Tag der Befreiung"`), or objects `{ date, name }`.
+ * @param {unknown} list
+ * @returns {{ entries: Array<{date: string, name: string}>, errors: string[] }} date is 'MM-DD' or 'YYYY-MM-DD'
+ */
+function parseExtra(list) {
+    const entries = [];
+    const errors = [];
+    if (list === undefined || list === null || list === '') return { entries, errors };
+    if (!Array.isArray(list)) return { entries, errors: ['holidaysExtra must be a list'] };
+    for (const item of list) {
+        let date, name;
+        if (typeof item === 'string') {
+            const m = /^\s*(\d{4}-\d{2}-\d{2}|\d{2}-\d{2})(?:\s+(.*?))?\s*$/.exec(item);
+            if (m) [, date, name] = m;
+        } else if (item && typeof item === 'object' && typeof item.date === 'string') {
+            if (/^(\d{4}-\d{2}-\d{2}|\d{2}-\d{2})$/.test(item.date)) {
+                date = item.date;
+                name = typeof item.name === 'string' ? item.name : undefined;
+            }
+        }
+        if (!date) {
+            errors.push(`holidaysExtra: "${typeof item === 'string' ? item : JSON.stringify(item)}" is not "MM-DD" or "YYYY-MM-DD" (optionally followed by a name)`);
+            continue;
+        }
+        const [mo, d] = date.slice(-5).split('-').map(Number);
+        if (mo < 1 || mo > 12 || d < 1 || d > 31) {
+            errors.push(`holidaysExtra: "${date}" is not a calendar date`);
+            continue;
+        }
+        entries.push({ date, name: name || date });
+    }
+    return { entries, errors };
+}
+
+module.exports = { REGIONS, easterSunday, isRegion, listRegions, holidaysOfYear, normalizeRegion, parseExtra };

package/src/lib/publish-changed.js

@@ -0,0 +1,45 @@
+'use strict';
+/**
+ * `she.mqtt.pub(topic, payload, { changed: true })`: publish only when the payload
+ * differs from what this script last sent to the topic. Before the first publish of a run, the
+ * comparison falls back to the topic's current value in the state store — for a command topic
+ * (`<prefix>/set/<name>`) to its `status` sibling, which is where a variable's or an adapter's
+ * state lives. The last payloads are kept per script, so a hot reload starts over with the store.
+ */
+
+const parsePayload = require('./parse-payload');
+
+const CAP = 200; // topics remembered per script, like the publish record
+
+/**
+ * @param {Map<string,string>} last topic → the payload this script last published
+ * @param {string} topic
+ * @param {string} payload the stringified payload
+ * @param {Function} lookup (topic) → the state object { val, ts, lc } or undefined
+ * @returns {boolean} true when the publish would repeat the last one
+ */
+function isRepeat(last, topic, payload, lookup) {
+    if (last.has(topic)) return last.get(topic) === payload;
+    let state = lookup(topic);
+    if (state === undefined) {
+        const parts = topic.split('/');
+        if (parts.length > 2 && parts[1] === 'set') {
+            parts[1] = 'status';
+            state = lookup(parts.join('/'));
+        }
+    }
+    if (state === undefined || state === null) return false;
+    return JSON.stringify(parsePayload(payload).val) === JSON.stringify(state.val);
+}
+
+/**
+ * Remember what was published; at most CAP topics per script.
+ * @param {Map<string,string>} last
+ * @param {string} topic
+ * @param {string} payload
+ */
+function remember(last, topic, payload) {
+    if (last.size < CAP || last.has(topic)) last.set(topic, payload);
+}
+
+module.exports = { isRepeat, remember, CAP };