smart-home-engine 0.0.1 → 0.10.4

package/src/lib/shedb-worker.js

@@ -0,0 +1,126 @@
+'use strict';
+
+/**
+ * SheDB view worker — runs in a worker_threads Worker.
+ * Executes map/reduce view scripts for all named queries against
+ * a snapshot of the document store received from the main thread.
+ *
+ * Message protocol:
+ *   Main → Worker:
+ *     { type: 'db',       docs: {...} }              full docs snapshot
+ *     { type: 'query',    id, payload: {filter?,map,reduce?} }
+ *     { type: 'delQuery', id }
+ *
+ *   Worker → Main:
+ *     { type: 'view', id, result: [...] }            successful result
+ *     { type: 'view', id, error: string }            runtime/compile error
+ *     { type: 'view', id, deleted: true }            query was removed
+ */
+
+const { parentPort, workerData } = require('worker_threads');
+const vm = require('vm');
+const mqttWildcard = require('./mqtt-wildcards');
+
+const TIMEOUT = (workerData && workerData.scriptTimeout) || 5000;
+
+let docs = {};
+const queries = {};
+let queue = [];
+let running = false;
+
+// ---------------------------------------------------------------------------
+// Helpers (inlined — worker has no access to main-thread closures)
+// ---------------------------------------------------------------------------
+
+function getProp(obj, propPath) {
+    if (obj == null || !propPath) return undefined;
+    return propPath.split('.').reduce((cur, k) => (cur != null ? cur[k] : undefined), obj);
+}
+
+// ---------------------------------------------------------------------------
+// View queue
+// ---------------------------------------------------------------------------
+
+function enqueue(id) {
+    if (!queue.includes(id)) queue.push(id);
+    if (!running) scheduleNext();
+}
+
+function scheduleNext() {
+    if (queue.length === 0) {
+        running = false;
+        return;
+    }
+    running = true;
+    const id = queue.shift();
+    setImmediate(() => buildAndRun(id));
+}
+
+function buildAndRun(id) {
+    const q = queries[id];
+    if (!q) {
+        scheduleNext();
+        return;
+    }
+
+    const { filter, map, reduce } = q;
+
+    // Build script source — same structure as the original in-process approach
+    let src = `api.map = function() {\n${map}\n};\napi._result = [];\n`;
+    if (filter) {
+        src += `api.forEachDocument(docId => { if (api.mqttWildcard(docId, ${JSON.stringify(filter)})) api.map.apply(api.getDocument(docId)); });\n`;
+    } else {
+        src += `api.forEachDocument(docId => { api.map.apply(api.getDocument(docId)); });\n`;
+    }
+    if (reduce) {
+        src += `api.reduce = function(result) {\n${reduce}\n};\napi._result = api.reduce(api._result);\n`;
+    }
+
+    // Sandbox — uses the local docs snapshot
+    const sandbox = {
+        api: {
+            forEachDocument: (cb) => Object.keys(docs).forEach(cb),
+            getDocument: (docId) => docs[docId],
+            getProp,
+            mqttWildcard,
+            _result: [],
+        },
+    };
+    sandbox.emit = (item) => sandbox.api._result.push(item);
+
+    try {
+        const script = new vm.Script(src, { filename: 'shedb-view-' + id });
+        const ctx = vm.createContext(sandbox);
+        script.runInContext(ctx, { timeout: TIMEOUT });
+        parentPort.postMessage({ type: 'view', id, result: Array.from(ctx.api._result) });
+    } catch (err) {
+        parentPort.postMessage({ type: 'view', id, error: 'runtime: ' + err.message });
+    }
+
+    scheduleNext();
+}
+
+// ---------------------------------------------------------------------------
+// Message handler
+// ---------------------------------------------------------------------------
+
+parentPort.on('message', (msg) => {
+    switch (msg.type) {
+        case 'db':
+            docs = msg.docs;
+            // Re-run all registered views with the new docs snapshot
+            for (const id of Object.keys(queries)) enqueue(id);
+            break;
+
+        case 'query':
+            queries[msg.id] = msg.payload;
+            enqueue(msg.id);
+            break;
+
+        case 'delQuery':
+            delete queries[msg.id];
+            queue = queue.filter((id) => id !== msg.id);
+            parentPort.postMessage({ type: 'view', id: msg.id, deleted: true });
+            break;
+    }
+});

package/src/lib/state-store.js

@@ -0,0 +1,97 @@
+'use strict';
+
+/**
+ * Unified in-memory state store for all interfaces (MQTT, Matter, variables).
+ *
+ * Keys are namespaced with a double-colon separator:
+ *   mqtt::home/sensor/temp
+ *   matter::1/1/LevelControl/currentLevel
+ *   var::myVariable
+ *
+ * Events:
+ *   'change' (key, val, obj, prevObj)
+ */
+
+const { EventEmitter } = require('events');
+
+class StateStore extends EventEmitter {
+    constructor() {
+        super();
+        this._map = new Map();
+    }
+
+    /**
+     * Store a value, auto-computing { val, ts, lc } timestamps.
+     * Emits 'change' on every call.
+     * @param {string} key  Namespaced key, e.g. 'mqtt::home/sensor/temp'
+     * @param {*}      val
+     */
+    set(key, val) {
+        const now = Date.now();
+        const prev = this._map.get(key);
+        const lc = !prev || prev.val !== val ? now : prev.lc;
+        const obj = { val, ts: now, lc };
+        this._map.set(key, obj);
+        this.emit('change', key, val, obj, prev);
+    }
+
+    /**
+     * Store a pre-constructed state object { val, ts, lc }.
+     * Use when the caller has already built the state (e.g. MQTT parse-payload).
+     * @param {string} key
+     * @param {{ val:*, ts:number, lc:number }} obj
+     */
+    setObject(key, obj) {
+        const prev = this._map.get(key);
+        this._map.set(key, obj);
+        this.emit('change', key, obj.val, obj, prev);
+    }
+
+    /**
+     * @param {string} key
+     * @returns {*} the val of the stored state, or undefined
+     */
+    get(key) {
+        const obj = this._map.get(key);
+        return obj !== undefined ? obj.val : undefined;
+    }
+
+    /**
+     * @param {string} key
+     * @returns {{ val:*, ts:number, lc:number } | undefined}
+     */
+    getObject(key) {
+        return this._map.get(key);
+    }
+
+    /** @returns {boolean} */
+    has(key) {
+        return this._map.has(key);
+    }
+
+    /**
+     * Return all keys, optionally filtered to those starting with nsPrefix.
+     * @param {string} [nsPrefix]
+     * @returns {string[]}
+     */
+    keys(nsPrefix) {
+        const all = Array.from(this._map.keys());
+        return nsPrefix ? all.filter((k) => k.startsWith(nsPrefix)) : all;
+    }
+
+    /**
+     * Iterate [rawTopic, obj] pairs for all mqtt:: keys, stripping the prefix.
+     * Used for wildcard retain-replay in subscribe().
+     * @yields {[string, {val:*, ts:number, lc:number}]}
+     */
+    *mqttEntries() {
+        const prefix = 'mqtt::';
+        for (const [key, obj] of this._map) {
+            if (key.startsWith(prefix)) {
+                yield [key.slice(prefix.length), obj];
+            }
+        }
+    }
+}
+
+module.exports = StateStore;

package/src/lib/storage.js

@@ -0,0 +1,74 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const STORAGE_ROOT = path.join(os.homedir(), '.she');
+const CONFIG_ROOT = path.join(STORAGE_ROOT, 'config');
+const SCRIPTS_ROOT = path.join(STORAGE_ROOT, 'scripts');
+const DB_ROOT = path.join(STORAGE_ROOT, 'db');
+
+/**
+ * Return the absolute path for a named sub-directory of ~/.she/.
+ * The directory is NOT created here — call ensureStorageDir() for that.
+ */
+function getStoragePath(name) {
+    return path.join(STORAGE_ROOT, name);
+}
+
+/**
+ * Return the path to the shared config file: ~/.she/config/config.json.
+ */
+function getConfigPath() {
+    return path.join(CONFIG_ROOT, 'config.json');
+}
+
+/**
+ * Create ~/.she/<name>/ if it does not already exist.
+ * Returns the resolved path.
+ */
+function ensureStorageDir(name) {
+    const dir = path.join(STORAGE_ROOT, name);
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
+
+/**
+ * Create ~/.she/ and its standard subdirectories if they don't already exist.
+ * Called once at daemon startup before anything else runs.
+ */
+function ensureRoot() {
+    fs.mkdirSync(STORAGE_ROOT, { recursive: true });
+    fs.mkdirSync(CONFIG_ROOT, { recursive: true });
+    fs.mkdirSync(SCRIPTS_ROOT, { recursive: true });
+    fs.mkdirSync(DB_ROOT, { recursive: true });
+}
+
+/**
+ * Ensure ~/.she/package.json exists so npm can install packages there.
+ * Creates a minimal private package.json if missing.
+ */
+function ensureUserPackageJson() {
+    const pkgPath = path.join(STORAGE_ROOT, 'package.json');
+    if (!fs.existsSync(pkgPath)) {
+        fs.writeFileSync(
+            pkgPath,
+            JSON.stringify(
+                {
+                    name: 'she-user-scripts',
+                    version: '1.0.0',
+                    private: true,
+                    description: 'User-installed npm packages for she scripts',
+                    dependencies: {},
+                },
+                null,
+                2,
+            ) + '\n',
+            'utf8',
+        );
+    }
+    return pkgPath;
+}
+
+module.exports = { STORAGE_ROOT, CONFIG_ROOT, SCRIPTS_ROOT, DB_ROOT, getStoragePath, getConfigPath, ensureStorageDir, ensureRoot, ensureUserPackageJson };

package/src/matter/controller.js

@@ -0,0 +1,307 @@
+'use strict';
+
+/**
+ * Matter controller — wraps @matter/main ServerNode + Peers API.
+ *
+ * Call init() once at daemon startup (only when --matter-storage is set).
+ * Call close() on daemon shutdown.
+ *
+ * All nodeIds are exposed as decimal strings (BigInt serialization boundary).
+ */
+
+const { Environment, ServerNode } = require('@matter/main');
+
+/** @type {import('@matter/main').ServerNode | null} */
+let _server = null;
+let _log = null;
+/** @type {((msg: object) => void) | null} */
+let _broadcast = null;
+
+// ── Attribute / event listeners registered by sandbox scripts ───────────────
+// Map<scriptFile, Map<listenerId, { cancel: () => void }>>
+const _listeners = new Map();
+let _nextListenerId = 1;
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function _bigintNodeId(nodeId) {
+    return BigInt(nodeId);
+}
+
+function _nodeIdStr(nodeId) {
+    return nodeId.toString();
+}
+
+function _findClientNode(nodeIdStr) {
+    if (!_server) throw new Error('Matter controller not started');
+    for (const node of _server.peers) {
+        const addr = node.peerAddress;
+        if (addr && _nodeIdStr(addr.nodeId) === nodeIdStr) return node;
+    }
+    throw new Error(`Matter node not found: ${nodeIdStr}`);
+}
+
+/** Resolve a cluster name (camelCase) from a cluster ID number or string. */
+function _clusterName(clusterId) {
+    // matter.js cluster state keys are camelCase cluster names.
+    // For generic access we accept either the camelCase name directly or skip resolution.
+    // The caller must pass the camelCase cluster name (e.g. "onOff", "levelControl").
+    return clusterId;
+}
+
+// ── Lifecycle ─────────────────────────────────────────────────────────────────
+
+/**
+ * Initialise the Matter controller.
+ * Must be called before any other method.
+ *
+ * @param {string} storagePath  Absolute path to the matter storage directory (~/.she/matter)
+ * @param {{ info: Function, warn: Function, error: Function }} log  Daemon logger
+ * @param {((msg: object) => void) | null} [broadcastFn]  WebSocket broadcast function from log-ws.js
+ */
+async function init(storagePath, log, broadcastFn) {
+    _broadcast = broadcastFn ?? null;
+    if (_server) throw new Error('Matter controller already started');
+    _log = log;
+
+    // Configure storage before anything else touches StorageService
+    Environment.default.vars.set('storage.path', storagePath);
+
+    // Disable matter.js built-in CLI arg and env-var parsing so it doesn't
+    // interfere with the daemon's own yargs config.
+    Environment.default.vars.set('environment.disableInteraction', true);
+
+    _server = await ServerNode.create({
+        id: 'she-matter-controller',
+    });
+
+    await _server.start();
+    _log.info('matter controller started, storage:', storagePath);
+}
+
+async function close() {
+    if (!_server) return;
+    try {
+        await _server.close();
+    } catch (err) {
+        _log?.error('matter controller close error:', err.message);
+    } finally {
+        _server = null;
+    }
+}
+
+// ── Device management ─────────────────────────────────────────────────────────
+
+/**
+ * List all paired nodes.
+ * @returns {{ nodeId: string, online: boolean }[]}
+ */
+function listPaired() {
+    if (!_server) return [];
+    const result = [];
+    for (const node of _server.peers) {
+        const addr = node.peerAddress;
+        if (!addr) continue; // not commissioned yet (in discovery)
+        result.push({
+            nodeId: _nodeIdStr(addr.nodeId),
+            online: node.lifecycle?.isOnline ?? false,
+        });
+    }
+    return result;
+}
+
+/**
+ * Commission a new device.
+ *
+ * @param {{ passcode: number, discriminator?: number } | { pairingCode: string }} options
+ * @returns {Promise<string>}  nodeId of the newly commissioned device
+ */
+async function commission(options) {
+    if (!_server) throw new Error('Matter controller not started');
+    const clientNode = await _server.peers.commission(options);
+    const addr = clientNode.peerAddress;
+    if (!addr) throw new Error('Commission succeeded but node has no peerAddress');
+    const nodeId = _nodeIdStr(addr.nodeId);
+    _subscribeNodeLifecycle(clientNode, nodeId);
+    _broadcast?.({ type: 'matter:deviceList', devices: listPaired() });
+    return nodeId;
+}
+
+/**
+ * Decommission and locally delete a paired node.
+ * Tries graceful decommission first; falls back to force-delete.
+ *
+ * @param {string} nodeId
+ */
+async function unpair(nodeId) {
+    const node = _findClientNode(nodeId);
+    try {
+        await node.decommission();
+    } catch (err) {
+        _log?.warn(`matter: decommission of ${nodeId} failed (${err.message}), force-deleting`);
+        await node.delete();
+    }
+    _broadcast?.({ type: 'matter:deviceList', devices: listPaired() });
+}
+
+/**
+ * Return the endpoint structure of a paired node.
+ * Each endpoint entry carries the list of available cluster names.
+ *
+ * @param {string} nodeId
+ * @returns {{ endpointId: number, clusters: string[] }[]}
+ */
+function getEndpoints(nodeId) {
+    const node = _findClientNode(nodeId);
+    const result = [];
+    for (const endpoint of node.endpoints) {
+        const clusters = endpoint.state ? Object.keys(endpoint.state) : [];
+        result.push({ endpointId: endpoint.number ?? 0, clusters });
+    }
+    return result;
+}
+
+// ── Attribute access ──────────────────────────────────────────────────────────
+
+/**
+ * Read a single attribute value.
+ *
+ * @param {string}          nodeId
+ * @param {number}          endpointId
+ * @param {string}          clusterName  camelCase cluster name, e.g. "onOff"
+ * @param {string}          attrName     camelCase attribute name, e.g. "onOff"
+ * @returns {Promise<unknown>}
+ */
+async function getAttribute(nodeId, endpointId, clusterName, attrName) {
+    const node = _findClientNode(nodeId);
+    const endpoint = node.endpoints.for(endpointId);
+    const clusterState = endpoint.state?.[_clusterName(clusterName)];
+    if (!clusterState) throw new Error(`Cluster "${clusterName}" not found on endpoint ${endpointId}`);
+    return clusterState[attrName];
+}
+
+// ── Commands ──────────────────────────────────────────────────────────────────
+
+/**
+ * Invoke a cluster command.
+ *
+ * @param {string}  nodeId
+ * @param {number}  endpointId
+ * @param {string}  clusterName  camelCase cluster name, e.g. "onOff"
+ * @param {string}  commandName  camelCase command name, e.g. "on"
+ * @param {object}  [args={}]
+ * @returns {Promise<unknown>}
+ */
+async function sendCommand(nodeId, endpointId, clusterName, commandName, args) {
+    const node = _findClientNode(nodeId);
+    return node.act(`she.matter.send(${nodeId}, ${endpointId}, ${clusterName}.${commandName})`, async (agent) => {
+        const rootParts = agent.parts;
+        // Navigate to the target endpoint
+        const ep = rootParts ? rootParts.get(endpointId) : null;
+        if (!ep) throw new Error(`Endpoint ${endpointId} not found on node ${nodeId}`);
+        const clusterAgent = ep[_clusterName(clusterName)];
+        if (!clusterAgent) throw new Error(`Cluster "${clusterName}" not found`);
+        const cmd = clusterAgent[commandName];
+        if (typeof cmd !== 'function') throw new Error(`Command "${commandName}" not found in cluster "${clusterName}"`);
+        return cmd.call(clusterAgent, args ?? {});
+    });
+}
+
+// ── Node lifecycle events (online / offline) ────────────────────────────────
+
+/**
+ * Subscribe to online/offline lifecycle changes for a node and broadcast them.
+ * @param {object} node ClientNode
+ * @param {string} nodeId decimal string
+ */
+function _subscribeNodeLifecycle(node, nodeId) {
+    const lc = node.lifecycle;
+    if (!lc) return;
+    lc.online?.on?.(() => {
+        _broadcast?.({ type: 'matter:deviceStatus', nodeId, online: true });
+    });
+    lc.offline?.on?.(() => {
+        _broadcast?.({ type: 'matter:deviceStatus', nodeId, online: false });
+    });
+}
+
+// ── Subscriptions (for sandbox) ───────────────────────────────────────────────
+
+/**
+ * Subscribe to attribute changes on a specific cluster attribute.
+ * Returns a listenerId that can be passed to unsubscribe().
+ *
+ * @param {string}   scriptFile   For cleanup tracking
+ * @param {string}   nodeId
+ * @param {number}   endpointId
+ * @param {string}   clusterName  camelCase cluster name
+ * @param {string}   attrName     camelCase attribute name
+ * @param {Function} callback     (value, oldValue) => void
+ * @returns {number}  listenerId
+ */
+function subscribeAttribute(scriptFile, nodeId, endpointId, clusterName, attrName, callback) {
+    const node = _findClientNode(nodeId);
+    const endpoint = node.endpoints.for(endpointId);
+    const events = endpoint.events?.[_clusterName(clusterName)];
+    if (!events) throw new Error(`Cluster "${clusterName}" not found on endpoint ${endpointId}`);
+    const changeEvent = events[`${attrName}$Changed`];
+    if (!changeEvent) throw new Error(`Attribute "${attrName}" on cluster "${clusterName}" has no change event`);
+
+    const listenerId = _nextListenerId++;
+    const cancel = changeEvent.on((value, oldValue) => {
+        try {
+            callback(value, oldValue);
+        } catch (err) {
+            _log?.error(`matter subscriber error in ${scriptFile}:`, err.message);
+        }
+    });
+
+    if (!_listeners.has(scriptFile)) _listeners.set(scriptFile, new Map());
+    _listeners.get(scriptFile).set(listenerId, { cancel });
+    return listenerId;
+}
+
+/**
+ * Remove a specific subscription by listenerId.
+ */
+function unsubscribe(scriptFile, listenerId) {
+    const scriptListeners = _listeners.get(scriptFile);
+    if (!scriptListeners) return;
+    const entry = scriptListeners.get(listenerId);
+    if (entry) {
+        entry.cancel();
+        scriptListeners.delete(listenerId);
+    }
+}
+
+/**
+ * Remove all subscriptions registered by a script (called on hot-reload).
+ *
+ * @param {string} scriptFile
+ */
+function cleanup(scriptFile) {
+    const scriptListeners = _listeners.get(scriptFile);
+    if (!scriptListeners) return;
+    for (const { cancel } of scriptListeners.values()) {
+        try {
+            cancel();
+        } catch {
+            // ignore
+        }
+    }
+    _listeners.delete(scriptFile);
+}
+
+module.exports = {
+    init,
+    close,
+    listPaired,
+    commission,
+    unpair,
+    getEndpoints,
+    getAttribute,
+    sendCommand,
+    subscribeAttribute,
+    unsubscribe,
+    cleanup,
+};

package/src/sandbox/api.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const { registerRoute } = require('../web/server');
+
+/**
+ * Sandbox module — adds she.api.{get,post,put,delete} to every script.
+ *
+ * Routes are registered under /api/<scriptName><routePath>, e.g.
+ *   she.api.get('/hello', () => ({ ok: true }))
+ *   → GET /api/myscript/hello
+ *
+ * Throws if the same method+path is registered more than once.
+ *
+ * @param {object} she        - per-script sandbox she object
+ * @param {object} ctx
+ * @param {string} ctx.scriptName - basename of the script file without extension
+ */
+module.exports = function (she, { scriptName }) {
+    /**
+     * Build the Express route handler that calls the user-supplied function.
+     * - GET / DELETE: handler(req) → value | Promise
+     * - POST / PUT:   handler(req, body) → value | Promise
+     * req = { params, query, headers }
+     */
+    function makeExpressHandler(userHandler, hasBody) {
+        return function (req, res) {
+            let result;
+            try {
+                result = hasBody
+                    ? userHandler({ params: req.params, query: req.query, headers: req.headers }, req.body)
+                    : userHandler({ params: req.params, query: req.query, headers: req.headers });
+            } catch (err) {
+                res.status(500).json({ error: err.message });
+                return;
+            }
+            Promise.resolve(result)
+                .then((val) => res.json(val !== undefined ? val : null))
+                .catch((err) => res.status(500).json({ error: err.message }));
+        };
+    }
+
+    function apiMethod(method, hasBody) {
+        return function (routePath, handler) {
+            if (typeof routePath !== 'string') throw new TypeError('path must be a string');
+            if (typeof handler !== 'function') throw new TypeError('handler must be a function');
+            const fullPath = '/api/' + scriptName + routePath;
+            registerRoute(method, fullPath, makeExpressHandler(handler, hasBody));
+        };
+    }
+
+    she.api = {
+        get: apiMethod('get', false),
+        post: apiMethod('post', true),
+        put: apiMethod('put', true),
+        delete: apiMethod('delete', false),
+    };
+};