smart-home-engine 0.0.1 → 0.11.0

package/src/web/scripts-api.js

@@ -0,0 +1,192 @@
+'use strict';
+
+const express = require('express');
+const fs = require('fs');
+const path = require('path');
+
+const router = express.Router();
+
+/**
+ * Resolve a safe absolute path within the script root.
+ * Returns null if the resolved path escapes the root (traversal attempt).
+ * @param {string} root - absolute script directory
+ * @param {string} relPath - client-supplied relative path
+ * @returns {string|null}
+ */
+function safePath(root, relPath) {
+    const abs = path.resolve(root, relPath.replace(/^\/+/, ''));
+    if (!abs.startsWith(root + path.sep) && abs !== root) return null;
+    return abs;
+}
+
+function getRoot(req) {
+    return req.app.locals.scriptDir || null;
+}
+
+/** True if the directory itself contains a .shelib marker. */
+function hasShelibMarker(absDir) {
+    return fs.existsSync(path.join(absDir, '.shelib'));
+}
+
+/** Flat list of all .js files with metadata and lib flag. */
+function walk(dir, base, parentIsLib) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    const lib = parentIsLib || (base !== '' && hasShelibMarker(dir));
+    const results = [];
+    for (const entry of entries) {
+        if (entry.name === '.shelib') continue;
+        const rel = base ? `${base}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            results.push(...walk(path.join(dir, entry.name), rel, lib));
+        } else if (entry.name.endsWith('.js')) {
+            const stat = fs.statSync(path.join(dir, entry.name));
+            results.push({ path: rel, size: stat.size, mtime: stat.mtimeMs, lib });
+        }
+    }
+    return results;
+}
+
+/**
+ * Nested tree of all .js files and subdirectories.
+ * Each node: { type:'file'|'dir', name, path, lib, size?, mtime?, children? }
+ */
+function buildTree(dir, base, parentIsLib) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    const selfIsLib = base !== '' && hasShelibMarker(dir);
+    const lib = parentIsLib || selfIsLib;
+    const result = [];
+    for (const entry of entries) {
+        if (entry.name === '.shelib') continue;
+        const rel = base ? `${base}/${entry.name}` : entry.name;
+        const abs = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            const childIsLib = lib || hasShelibMarker(abs);
+            const children = buildTree(abs, rel, childIsLib);
+            result.push({ type: 'dir', name: entry.name, path: rel, lib: childIsLib, children });
+        } else if (entry.name.endsWith('.js')) {
+            const stat = fs.statSync(abs);
+            result.push({ type: 'file', name: entry.name, path: rel, lib, size: stat.size, mtime: stat.mtimeMs });
+        }
+    }
+    result.sort((a, b) => {
+        if (a.type !== b.type) return a.type === 'dir' ? -1 : 1;
+        return a.name.localeCompare(b.name);
+    });
+    return result;
+}
+
+// All routes dispatched via router.use to avoid path-to-regexp v8 wildcard issues.
+router.use((req, res) => {
+    const root = getRoot(req);
+    if (!root) return res.status(503).json({ error: 'scriptDir not configured' });
+
+    const method = req.method.toUpperCase();
+    const filePath = req.path.replace(/^\/+/, '');
+
+    // GET /she/scripts  — flat list of all .js files with metadata
+    if (method === 'GET' && !filePath) {
+        return res.json(walk(root, '', false));
+    }
+
+    // GET /she/scripts/tree  — nested tree structure
+    if (method === 'GET' && filePath === 'tree') {
+        return res.json(buildTree(root, '', false));
+    }
+
+    // GET /she/scripts/<path>  — read file content
+    if (method === 'GET') {
+        const abs = safePath(root, filePath);
+        if (!abs) return res.status(400).json({ error: 'Invalid path' });
+        try {
+            const content = fs.readFileSync(abs, 'utf8');
+            return res.json({ path: filePath, content });
+        } catch (err) {
+            if (err.code === 'ENOENT') return res.status(404).json({ error: 'Not found' });
+            return res.status(500).json({ error: err.message });
+        }
+    }
+
+    // PUT /she/scripts/<path>  — create or overwrite file
+    if (method === 'PUT') {
+        const abs = safePath(root, filePath);
+        if (!abs) return res.status(400).json({ error: 'Invalid path' });
+        const basename = path.basename(abs);
+        if (!basename.endsWith('.js') && basename !== '.shelib') {
+            return res.status(400).json({ error: 'Only .js and .shelib files are allowed' });
+        }
+        const content = typeof req.body?.content === 'string' ? req.body.content : null;
+        if (content === null) return res.status(400).json({ error: 'Missing body.content string' });
+        try {
+            fs.mkdirSync(path.dirname(abs), { recursive: true });
+            fs.writeFileSync(abs, content, 'utf8');
+            const stat = fs.statSync(abs);
+            return res.json({ ok: true, path: filePath, size: stat.size, mtime: stat.mtimeMs });
+        } catch (err) {
+            return res.status(500).json({ error: err.message });
+        }
+    }
+
+    // DELETE /she/scripts/<path>  — delete file
+    if (method === 'DELETE') {
+        const abs = safePath(root, filePath);
+        if (!abs) return res.status(400).json({ error: 'Invalid path' });
+        try {
+            fs.unlinkSync(abs);
+            return res.json({ ok: true });
+        } catch (err) {
+            if (err.code === 'ENOENT') return res.status(404).json({ error: 'Not found' });
+            return res.status(500).json({ error: err.message });
+        }
+    }
+
+    // POST /she/scripts/mkdir  — create a directory
+    if (method === 'POST' && filePath === 'mkdir') {
+        const dirPath = typeof req.body?.path === 'string' ? req.body.path : null;
+        if (!dirPath) return res.status(400).json({ error: 'Missing body.path string' });
+        const abs = safePath(root, dirPath);
+        if (!abs) return res.status(400).json({ error: 'Invalid path' });
+        try {
+            fs.mkdirSync(abs, { recursive: true });
+            return res.json({ ok: true, path: dirPath });
+        } catch (err) {
+            return res.status(500).json({ error: err.message });
+        }
+    }
+
+    // POST /she/scripts/<path>/rename  — rename / move file
+    if (method === 'POST') {
+        if (!filePath.endsWith('/rename')) return res.status(404).json({ error: 'Not found' });
+        const srcPath = filePath.slice(0, -'/rename'.length);
+        const abs = safePath(root, srcPath);
+        if (!abs) return res.status(400).json({ error: 'Invalid path' });
+        const newName = req.body?.newPath;
+        if (typeof newName !== 'string' || !newName) {
+            return res.status(400).json({ error: 'Missing body.newPath string' });
+        }
+        const absNew = safePath(root, newName);
+        if (!absNew) return res.status(400).json({ error: 'Invalid newPath' });
+        if (!absNew.endsWith('.js')) return res.status(400).json({ error: 'Only .js files are allowed' });
+        try {
+            fs.mkdirSync(path.dirname(absNew), { recursive: true });
+            fs.renameSync(abs, absNew);
+            return res.json({ ok: true, path: newName });
+        } catch (err) {
+            if (err.code === 'ENOENT') return res.status(404).json({ error: 'Not found' });
+            return res.status(500).json({ error: err.message });
+        }
+    }
+
+    res.status(405).json({ error: 'Method not allowed' });
+});
+
+module.exports = { router };

package/src/web/server.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const express = require('express');
+const path = require('path');
+const { router: configRouter } = require('./config-api');
+const { router: scriptsRouter } = require('./scripts-api');
+const { router: shedbRouter } = require('./shedb-api');
+const { router: matterRouter } = require('./matter-api');
+const { router: mqttRouter } = require('./mqtt-api');
+const { router: depsRouter } = require('./deps-api');
+const { router: gitRouter } = require('./git-api');
+const { router: aiRouter } = require('./ai-api');
+const { attachWss, closeWss } = require('./log-ws');
+const { init: initAuth, authMiddleware, checkAuth, router: authRouter } = require('./auth');
+
+const app = express();
+app.use(express.json());
+
+// Public auth routes — always accessible regardless of auth mode.
+// Must be mounted BEFORE the auth middleware.
+app.use('/she/auth', authRouter);
+
+// Auth middleware for all /she/* routes except the public auth endpoints above.
+// /api/* is intentionally excluded — user scripts control their own auth.
+const OPEN_SHE_PATHS = new Set(['/she/auth/mode', '/she/auth/login', '/she/auth/logout']);
+app.use('/she', (req, res, next) => {
+    if (OPEN_SHE_PATHS.has(req.originalUrl.split('?')[0])) return next();
+    authMiddleware(req, res, next);
+});
+
+// Config REST endpoints: GET /she/config and PUT /she/config
+app.use('/she/config', configRouter);
+
+// Scripts file CRUD: GET/PUT/DELETE /she/scripts/*
+app.use('/she/scripts', scriptsRouter);
+
+// sheDB document store REST API: /she/db/*
+app.use('/she/db', shedbRouter);
+
+// Matter controller REST API: /she/matter/*
+app.use('/she/matter', matterRouter);
+
+// MQTT state snapshot and publish: /she/mqtt/*
+app.use('/she/mqtt', mqttRouter);
+
+// npm package management: /she/deps/*
+app.use('/she/deps', depsRouter);
+
+// Git integration: /she/git/*
+app.use('/she/git', gitRouter);
+
+// AI assistant proxy: /she/ai/*
+app.use('/she/ai', aiRouter);
+
+// Graceful daemon restart — exit(0) and let the process manager restart
+app.post('/she/restart', (req, res) => {
+    res.json({ ok: true });
+    setTimeout(() => process.exit(0), 200);
+});
+
+// Serve the built Svelte SPA from dist/web/
+// Hashed assets (JS/CSS) are immutable; index.html must never be cached so
+// browsers always pick up a freshly deployed version.
+const distWeb = path.resolve(__dirname, '../../dist/web');
+app.use(express.static(distWeb, { index: false })); // don't auto-serve index.html
+// SPA fallback — serve index.html for any non-API route, always no-cache
+app.use((req, res, next) => {
+    if (req.path.startsWith('/she') || req.path.startsWith('/api')) return next();
+    res.set('Cache-Control', 'no-cache, no-store, must-revalidate');
+    res.sendFile(path.join(distWeb, 'index.html'));
+});
+
+// Central route registry — key: 'METHOD /api/scriptname/path'
+const registry = new Map();
+
+/**
+ * Register an HTTP route. Throws if the same method+path pair is already registered.
+ * @param {'get'|'post'|'put'|'delete'} method
+ * @param {string} fullPath  - absolute Express path, e.g. '/api/myscript/foo'
+ * @param {Function} handler - Express route handler (req, res)
+ */
+function registerRoute(method, fullPath, handler) {
+    const key = `${method.toUpperCase()} ${fullPath}`;
+    if (registry.has(key)) {
+        throw new Error(`Route already registered: ${key}`);
+    }
+    registry.set(key, true);
+    app[method](fullPath, handler);
+}
+
+let httpServer = null;
+
+/**
+ * Start listening. Resolves with the actual port (useful when port 0 is given).
+ * @param {number} port
+ * @param {{ auth?: string, password?: string, proxyHeader?: string, bindAddress?: string, configPath?: string, scriptDir?: string }} [options]
+ * @returns {Promise<number>}
+ */
+function startServer(port, options = {}) {
+    initAuth({
+        auth: options.auth || 'none',
+        password: options.password || null,
+        proxyHeader: options.proxyHeader || 'X-Remote-User',
+        configPath: options.configPath || null,
+    });
+    if (options.configPath) {
+        app.locals.configPath = options.configPath;
+    }
+    if (options.scriptDir) {
+        app.locals.scriptDir = options.scriptDir;
+    }
+    const host = options.bindAddress || '0.0.0.0';
+    return new Promise((resolve, reject) => {
+        httpServer = app.listen(port, host, () => {
+            attachWss(httpServer, checkAuth);
+            resolve(httpServer.address().port);
+        });
+        httpServer.on('error', reject);
+    });
+}
+
+/**
+ * Stop the HTTP server gracefully.
+ * @returns {Promise<void>}
+ */
+function stopServer() {
+    return new Promise((resolve) => {
+        if (httpServer) {
+            closeWss().then(() => {
+                httpServer.close(resolve);
+                httpServer = null;
+            });
+        } else {
+            resolve();
+        }
+    });
+}
+
+module.exports = { app, registerRoute, startServer, stopServer };

package/src/web/shedb-api.js

@@ -0,0 +1,140 @@
+'use strict';
+
+/**
+ * sheDB REST API — Express router mounted at /she/db
+ *
+ * Document IDs may contain slashes (MQTT-topic style), so all document and
+ * view routes use router.use() to read req.path directly instead of named
+ * params, avoiding path-to-regexp v8 wildcard incompatibilities with Express 5.
+ *
+ * Routes:
+ *   GET    /she/db/docs              → sorted list of document IDs
+ *   GET    /she/db/docs/<id>         → get document
+ *   PUT    /she/db/docs/<id>         → set document (full overwrite)
+ *   PATCH  /she/db/docs/<id>         → extend document (deep merge)
+ *   DELETE /she/db/docs/<id>         → delete document
+ *
+ *   GET    /she/db/views             → sorted list of view IDs
+ *   GET    /she/db/views/<id>        → get view definition { filter, map, reduce }
+ *   PUT    /she/db/views/<id>        → create/update view
+ *   GET    /she/db/views/<id>/result → get computed view result
+ *   DELETE /she/db/views/<id>        → delete view
+ */
+
+const express = require('express');
+const { getCore } = require('./shedb');
+
+const router = express.Router();
+
+function core503(res) {
+    return res.status(503).json({ error: 'shedb not initialised' });
+}
+
+// ---------------------------------------------------------------------------
+// /she/db/docs — document CRUD
+// ---------------------------------------------------------------------------
+
+router.use('/docs', (req, res) => {
+    const core = getCore();
+    if (!core) return core503(res);
+
+    const method = req.method.toUpperCase();
+    // Strip leading slash; empty → list all
+    const id = req.path.replace(/^\/+/, '');
+
+    // GET /she/db/docs  — list all IDs
+    if (method === 'GET' && !id) {
+        return res.json(Object.keys(core.docs).sort());
+    }
+
+    // GET /she/db/docs/<id>
+    if (method === 'GET') {
+        const doc = core.get(id);
+        return doc ? res.json(doc) : res.status(404).json({ error: 'not found' });
+    }
+
+    // PUT /she/db/docs/<id>
+    if (method === 'PUT') {
+        if (!id) return res.status(400).json({ error: 'id required' });
+        if (!req.body || typeof req.body !== 'object') return res.status(400).json({ error: 'body must be a JSON object' });
+        core.set(id, req.body);
+        return res.json({ ok: true });
+    }
+
+    // PATCH /she/db/docs/<id>  — deep merge
+    if (method === 'PATCH') {
+        if (!id) return res.status(400).json({ error: 'id required' });
+        if (!req.body || typeof req.body !== 'object') return res.status(400).json({ error: 'body must be a JSON object' });
+        core.extend(id, req.body);
+        return res.json({ ok: true });
+    }
+
+    // DELETE /she/db/docs/<id>
+    if (method === 'DELETE') {
+        if (!id) return res.status(400).json({ error: 'id required' });
+        core.del(id);
+        return res.json({ ok: true });
+    }
+
+    res.status(405).json({ error: 'method not allowed' });
+});
+
+// ---------------------------------------------------------------------------
+// /she/db/views — named view CRUD
+// ---------------------------------------------------------------------------
+
+router.use('/views', (req, res) => {
+    const core = getCore();
+    if (!core) return core503(res);
+
+    const method = req.method.toUpperCase();
+    // Strip leading slash; detect /result suffix
+    const rawPath = req.path.replace(/^\/+/, '');
+    const isResult = rawPath.endsWith('/result');
+    const id = isResult ? rawPath.slice(0, -'/result'.length) : rawPath;
+
+    // GET /she/db/views  — list all view IDs
+    if (method === 'GET' && !rawPath) {
+        return res.json(Object.keys(core.queries).sort());
+    }
+
+    // GET /she/db/views/<id>/result
+    if (method === 'GET' && isResult) {
+        if (!id) return res.status(400).json({ error: 'id required' });
+        const view = core.views[id];
+        return view ? res.json(view) : res.status(404).json({ error: 'not found' });
+    }
+
+    // GET /she/db/views/<id>  — definition
+    if (method === 'GET') {
+        const query = core.queries[id];
+        return query ? res.json(query) : res.status(404).json({ error: 'not found' });
+    }
+
+    // PUT /she/db/views/<id>  — create/update view
+    if (method === 'PUT') {
+        if (!id || isResult) return res.status(400).json({ error: 'id required' });
+        const { filter, map, reduce, mqttpub, retain } = req.body || {};
+        if (typeof map !== 'string' || !map.trim()) return res.status(400).json({ error: '"map" function string is required' });
+        const payload = {
+            filter: filter || undefined,
+            map,
+            reduce: reduce || undefined,
+            ...(mqttpub ? { mqttpub: true } : {}),
+            ...(retain   ? { retain:   true } : {}),
+        };
+        core.query(id, payload);
+        return res.json({ ok: true });
+    }
+
+    // DELETE /she/db/views/<id>
+    if (method === 'DELETE') {
+        if (!id || isResult) return res.status(400).json({ error: 'id required' });
+        core.query(id, '');
+        return res.json({ ok: true });
+    }
+
+    res.status(405).json({ error: 'method not allowed' });
+});
+
+module.exports = { router };

package/src/web/shedb.js

@@ -0,0 +1,168 @@
+'use strict';
+
+/**
+ * sheDB integration module.
+ *
+ * Wraps SheDBCore and provides:
+ *   - MQTT command topic handling (she/db/set/#, extend/#, delete/#, prop/#, get/#)
+ *   - WebSocket broadcast of document/view change events
+ *   - Listener registry for she.db.sub() sandbox subscriptions
+ */
+
+const SheDBCore = require('../lib/shedb-core');
+const mqttWildcard = require('../lib/mqtt-wildcards');
+
+let _core = null;
+let _mqtt = null;
+let _mqttName = '';
+let _dbPublish = false;
+let _dbRetain = false;
+let _dbPrefix = 'she/db/';
+let _broadcast = () => {};
+
+/** Registry for she.db.sub() sandbox subscriptions */
+const _listeners = []; // { pattern: string, callback: Function, _script: string }
+
+/**
+ * Initialise sheDB.
+ *
+ * @param {object} opts
+ * @param {string}   opts.dbPath    - absolute path to the JSON data file
+ * @param {boolean}  opts.dbRetain  - whether to publish docs/views as retained MQTT messages
+ * @param {string}   opts.mqttName  - mqtt client name / topic prefix (config.name)
+ * @param {object}   opts.mqtt      - connected mqtt.js client (may be null if offline)
+ * @param {object}   opts.log       - pino-compatible logger
+ * @param {Function} opts.broadcast - function(msg) to push a message to all WS clients
+ * @returns {SheDBCore}
+ */
+function init({ dbPath, dbPublish, dbRetain, dbPrefix, mqttName, mqtt, log, broadcast }) {
+    _mqtt = mqtt;
+    _mqttName = mqttName;
+    _dbPublish = dbPublish;
+    _dbRetain = dbRetain;
+    _dbPrefix = (dbPrefix && dbPrefix.endsWith('/')) ? dbPrefix : (dbPrefix || 'she/db/') + '/';
+    _broadcast = broadcast;
+
+    _core = new SheDBCore({ dbPath, log });
+
+    _core.on('ready', () => {
+        log.info('shedb ready, ' + Object.keys(_core.docs).length + ' docs, ' + Object.keys(_core.queries).length + ' views');
+        _broadcast({ type: 'db:ids', ids: Object.keys(_core.docs).sort() });
+        _broadcast({ type: 'db:viewIds', ids: Object.keys(_core.queries).sort() });
+    });
+
+    _core.on('update', (id, doc) => {
+        _broadcast({ type: 'db:change', id, doc: doc || null });
+        _broadcast({ type: 'db:ids', ids: Object.keys(_core.docs).sort() });
+
+        if (_dbPublish && _mqtt) {
+            _mqtt.publish(_dbPrefix + 'doc/' + id, doc ? JSON.stringify(doc) : '', { retain: _dbRetain });
+        }
+
+        // Fire sandbox she.db.sub() listeners
+        for (const sub of _listeners) {
+            if (mqttWildcard(id, sub.pattern) !== null) {
+                try {
+                    sub.callback(id, doc || null);
+                } catch {
+                    /* errors are caught by the script domain wrapper */
+                }
+            }
+        }
+    });
+
+    _core.on('view', (id, view) => {
+        _broadcast({ type: 'db:viewUpdate', id });
+        _broadcast({ type: 'db:viewIds', ids: Object.keys(_core.queries).sort() });
+
+        // Per-view MQTT publish (independent of global dbPublish setting)
+        const query = _core.queries[id];
+        if (query && query.mqttpub && _mqtt && view && !view.error) {
+            _mqtt.publish(
+                _dbPrefix + 'view/' + id,
+                JSON.stringify(view.result ?? []),
+                { retain: query.retain === true }
+            );
+        }
+    });
+
+    return _core;
+}
+
+/**
+ * Route an incoming MQTT message to sheDB if it matches the db topic prefix.
+ * Called from the main mqtt.on('message') handler.
+ *
+ * @param {string} topic
+ * @param {Buffer} payload
+ * @returns {boolean} true if the message was handled by sheDB
+ */
+function handleMqttMessage(topic, payload) {
+    if (!_core) return false;
+
+    const prefix = _dbPrefix;
+    if (!topic.startsWith(prefix)) return false;
+
+    const rest = topic.slice(prefix.length);
+    const slash = rest.indexOf('/');
+    if (slash === -1) return false;
+
+    const cmd = rest.slice(0, slash);
+    const id = rest.slice(slash + 1);
+    const str = payload.toString();
+
+    switch (cmd) {
+        case 'set':
+            try {
+                _core.set(id, JSON.parse(str));
+            } catch {
+                /* ignore malformed payload */
+            }
+            break;
+        case 'extend':
+            try {
+                _core.extend(id, JSON.parse(str));
+            } catch {
+                /* ignore malformed payload */
+            }
+            break;
+        case 'delete':
+            _core.del(id);
+            break;
+        case 'prop':
+            try {
+                _core.prop(id, JSON.parse(str));
+            } catch {
+                /* ignore malformed payload */
+            }
+            break;
+        case 'get':
+            if (_mqtt) {
+                const doc = _core.get(id);
+                _mqtt.publish(_dbPrefix + 'result/' + id, doc ? JSON.stringify(doc) : '');
+            }
+            break;
+        default:
+            return false;
+    }
+    return true;
+}
+
+/** Register a she.db.sub() listener. */
+function addListener(pattern, callback, scriptName) {
+    _listeners.push({ pattern, callback, _script: scriptName });
+}
+
+/** Remove all listeners registered by a script (called on hot-reload / unload). */
+function removeListenersByScript(scriptName) {
+    for (let i = _listeners.length - 1; i >= 0; i--) {
+        if (_listeners[i]._script === scriptName) _listeners.splice(i, 1);
+    }
+}
+
+/** Return the live core instance (used by shedb-api.js). */
+function getCore() {
+    return _core;
+}
+
+module.exports = { init, handleMqttMessage, addListener, removeListenersByScript, getCore };