smart-home-engine 0.0.1 → 0.10.4

package/src/web/git-api.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const express = require('express');
+const { execFile } = require('child_process');
+const path = require('path');
+
+const router = express.Router();
+
+function getRoot(req) {
+    return req.app.locals.scriptDir || null;
+}
+
+/**
+ * Run a git command in the given cwd.
+ * Resolves with { stdout, stderr }; rejects with an error that carries .stderr and .stdout.
+ */
+function git(args, cwd, timeout = 30000) {
+    return new Promise((resolve, reject) => {
+        execFile('git', args, { cwd, timeout }, (err, stdout, stderr) => {
+            if (err) {
+                const e = new Error(stderr.trim() || err.message);
+                e.stderr = stderr;
+                e.stdout = stdout;
+                reject(e);
+            } else {
+                resolve({ stdout, stderr });
+            }
+        });
+    });
+}
+
+/**
+ * Find the git root for the given directory.
+ * Returns null when the directory is not inside a git repository.
+ */
+async function getGitRoot(dir) {
+    try {
+        const { stdout } = await git(['rev-parse', '--show-toplevel'], dir);
+        return stdout.trim().replace(/\//g, path.sep);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Resolve a safe absolute path within the script root.
+ * Returns null when the path escapes the root (traversal attempt).
+ */
+function safePath(root, relPath) {
+    const abs = path.resolve(root, relPath.replace(/^\/+/, ''));
+    if (!abs.startsWith(root + path.sep) && abs !== root) return null;
+    return abs;
+}
+
+/** Validate commit message: non-empty, no null bytes. */
+function isValidMessage(msg) {
+    return typeof msg === 'string' && msg.trim().length > 0 && !msg.includes('\0');
+}
+
+// GET /she/git/status
+// Returns branch name, changed files, and ahead/behind counts vs. upstream.
+router.get('/status', async (req, res) => {
+    const scriptDir = getRoot(req);
+    if (!scriptDir) return res.status(500).json({ error: 'scriptDir not configured' });
+
+    const gitRoot = await getGitRoot(scriptDir);
+    if (!gitRoot) return res.status(404).json({ error: 'Not a git repository' });
+
+    try {
+        const [statusOut, branchOut] = await Promise.all([git(['status', '--porcelain', '-u'], gitRoot), git(['rev-parse', '--abbrev-ref', 'HEAD'], gitRoot)]);
+
+        const branch = branchOut.stdout.trim();
+        const changes = statusOut.stdout
+            .split('\n')
+            .filter(Boolean)
+            .map((line) => ({
+                status: line.slice(0, 2).trim(),
+                file: line.slice(3),
+            }));
+
+        let ahead = 0;
+        let behind = 0;
+        try {
+            const { stdout } = await git(['rev-list', '--left-right', '--count', 'HEAD...@{upstream}'], gitRoot);
+            const parts = stdout.trim().split(/\s+/);
+            ahead = parseInt(parts[0], 10) || 0;
+            behind = parseInt(parts[1], 10) || 0;
+        } catch {
+            // No upstream configured — leave as 0.
+        }
+
+        res.json({ branch, changes, ahead, behind });
+    } catch (e) {
+        res.status(500).json({ error: e.message });
+    }
+});
+
+// GET /she/git/remotes
+// Returns the configured git remotes: [{ name, fetch, push }].
+router.get('/remotes', async (req, res) => {
+    const scriptDir = getRoot(req);
+    if (!scriptDir) return res.status(500).json({ error: 'scriptDir not configured' });
+
+    const gitRoot = await getGitRoot(scriptDir);
+    if (!gitRoot) return res.status(404).json({ error: 'Not a git repository' });
+
+    try {
+        const { stdout } = await git(['remote', '-v'], gitRoot);
+        const remotes = {};
+        for (const line of stdout.split('\n').filter(Boolean)) {
+            const m = line.match(/^(\S+)\s+(\S+)\s+\((fetch|push)\)$/);
+            if (!m) continue;
+            const [, name, url, type] = m;
+            if (!remotes[name]) remotes[name] = { name, fetch: '', push: '' };
+            remotes[name][type] = url;
+        }
+        res.json(Object.values(remotes));
+    } catch (e) {
+        res.status(500).json({ error: e.message });
+    }
+});
+
+// POST /she/git/commit
+// Body: { path?: string, files?: string[], message: string }
+// Stages the given file(s) (or the whole scriptDir when neither is provided) and commits.
+router.post('/commit', async (req, res) => {
+    const scriptDir = getRoot(req);
+    if (!scriptDir) return res.status(500).json({ error: 'scriptDir not configured' });
+
+    const message = String(req.body?.message ?? '').trim();
+    if (!isValidMessage(message)) return res.status(400).json({ error: 'Invalid or empty commit message' });
+
+    // Accept a single path or an array of paths.
+    let relPaths;
+    if (req.body?.path) {
+        relPaths = [String(req.body.path)];
+    } else if (Array.isArray(req.body?.files) && req.body.files.length > 0) {
+        relPaths = req.body.files.map(String);
+    } else {
+        relPaths = [];
+    }
+
+    const gitRoot = await getGitRoot(scriptDir);
+    if (!gitRoot) return res.status(404).json({ error: 'Not a git repository' });
+
+    try {
+        if (relPaths.length > 0) {
+            for (const rel of relPaths) {
+                const abs = safePath(scriptDir, rel);
+                if (!abs) return res.status(400).json({ error: `Invalid path: ${rel}` });
+                // Convert to forward slashes for git portability.
+                const relToRoot = path.relative(gitRoot, abs).replace(/\\/g, '/');
+                await git(['add', relToRoot], gitRoot);
+            }
+        } else {
+            // Stage the entire script directory.
+            const scriptDirRel = path.relative(gitRoot, scriptDir).replace(/\\/g, '/');
+            await git(['add', scriptDirRel + '/'], gitRoot);
+        }
+
+        await git(['commit', '-m', message], gitRoot);
+        res.json({ ok: true });
+    } catch (e) {
+        res.status(500).json({ error: e.message, stderr: e.stderr });
+    }
+});
+
+// POST /she/git/push
+// Body: { remote?: string }  — defaults to "origin".
+router.post('/push', async (req, res) => {
+    const scriptDir = getRoot(req);
+    if (!scriptDir) return res.status(500).json({ error: 'scriptDir not configured' });
+
+    const remote = String(req.body?.remote ?? 'origin').trim();
+    if (!/^[a-zA-Z0-9_./-]+$/.test(remote)) return res.status(400).json({ error: 'Invalid remote name' });
+
+    const gitRoot = await getGitRoot(scriptDir);
+    if (!gitRoot) return res.status(404).json({ error: 'Not a git repository' });
+
+    try {
+        const { stdout, stderr } = await git(['push', remote], gitRoot, 60000);
+        res.json({ ok: true, stdout, stderr });
+    } catch (e) {
+        res.status(500).json({ error: e.message, stderr: e.stderr });
+    }
+});
+
+module.exports = { router };

package/src/web/log-ws.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const { WebSocketServer } = require('ws');
+
+let _wss = null;
+const _clients = new Set();
+
+/**
+ * Attach a WebSocketServer to an existing http.Server.
+ * Clients connect to /she/ws. Once connected they receive:
+ *   - { type: 'log', line: string }  — every pino log line
+ *   - { type: 'ping' }               — keepalive every 30 s
+ *
+ * @param {import('http').Server} httpServer
+ */
+function attachWss(httpServer) {
+    _wss = new WebSocketServer({ server: httpServer, path: '/she/ws' });
+
+    _wss.on('connection', (ws) => {
+        _clients.add(ws);
+        ws.on('close', () => _clients.delete(ws));
+        ws.on('error', () => _clients.delete(ws));
+    });
+
+    // Keepalive ping every 30 s
+    const pingInterval = setInterval(() => {
+        const msg = JSON.stringify({ type: 'ping' });
+        for (const ws of _clients) {
+            if (ws.readyState === ws.OPEN) ws.send(msg);
+        }
+    }, 30_000);
+
+    _wss.on('close', () => clearInterval(pingInterval));
+}
+
+/**
+ * Broadcast an arbitrary JSON message to all connected WebSocket clients.
+ * @param {object} msg - must be JSON-serialisable
+ */
+function broadcast(msg) {
+    if (_clients.size === 0) return;
+    const str = JSON.stringify(msg);
+    for (const ws of _clients) {
+        if (ws.readyState === ws.OPEN) ws.send(str);
+    }
+}
+
+/**
+ * Broadcast a structured log entry to all connected WebSocket clients.
+ * @param {{ level: string, msg: string, ts: number }} entry
+ */
+function broadcastLog(entry) {
+    broadcast({ type: 'log', ...entry });
+}
+
+/**
+ * Close the WebSocket server.
+ * @returns {Promise<void>}
+ */
+function closeWss() {
+    return new Promise((resolve) => {
+        if (_wss) {
+            _wss.close(resolve);
+            _wss = null;
+        } else {
+            resolve();
+        }
+    });
+}
+
+module.exports = { attachWss, broadcast, broadcastLog, closeWss };

package/src/web/matter-api.js

@@ -0,0 +1,102 @@
+'use strict';
+
+/**
+ * Matter controller REST API — Express router mounted at /she/matter
+ *
+ * Routes:
+ *   GET    /she/matter/devices                          → list paired nodes
+ *   POST   /she/matter/commission                       → commission a device
+ *   GET    /she/matter/devices/:nodeId                  → node detail (endpoints + clusters)
+ *   DELETE /she/matter/devices/:nodeId                  → unpair a device
+ *   POST   /she/matter/devices/:nodeId/command          → invoke a cluster command
+ *
+ * All NodeIds are represented as decimal strings in JSON.
+ */
+
+const express = require('express');
+
+const router = express.Router();
+
+function getController() {
+    return require('../matter/controller');
+}
+
+function notReady(res) {
+    return res.status(503).json({ error: 'Matter controller not started (--matter-storage not set)' });
+}
+
+function isReady() {
+    try {
+        const c = getController();
+        return typeof c.listPaired === 'function';
+    } catch {
+        return false;
+    }
+}
+
+// GET /she/matter/devices — list paired nodes
+router.get('/devices', (req, res) => {
+    if (!isReady()) return notReady(res);
+    try {
+        res.json(getController().listPaired());
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+// POST /she/matter/commission — { passcode, discriminator? } or { pairingCode }
+router.post('/commission', async (req, res) => {
+    if (!isReady()) return notReady(res);
+    const body = req.body;
+    if (!body || (body.passcode === undefined && body.pairingCode === undefined)) {
+        return res.status(400).json({ error: 'body must contain passcode or pairingCode' });
+    }
+    try {
+        const nodeId = await getController().commission(body);
+        res.status(201).json({ nodeId });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+// GET /she/matter/devices/:nodeId — node detail
+router.get('/devices/:nodeId', (req, res) => {
+    if (!isReady()) return notReady(res);
+    try {
+        const endpoints = getController().getEndpoints(req.params.nodeId);
+        res.json({ nodeId: req.params.nodeId, endpoints });
+    } catch (err) {
+        if (err.message.includes('not found')) return res.status(404).json({ error: err.message });
+        res.status(500).json({ error: err.message });
+    }
+});
+
+// DELETE /she/matter/devices/:nodeId — unpair
+router.delete('/devices/:nodeId', async (req, res) => {
+    if (!isReady()) return notReady(res);
+    try {
+        await getController().unpair(req.params.nodeId);
+        res.json({ ok: true });
+    } catch (err) {
+        if (err.message.includes('not found')) return res.status(404).json({ error: err.message });
+        res.status(500).json({ error: err.message });
+    }
+});
+
+// POST /she/matter/devices/:nodeId/command — { endpointId, clusterName, command, args? }
+router.post('/devices/:nodeId/command', async (req, res) => {
+    if (!isReady()) return notReady(res);
+    const { endpointId, clusterName, command, args } = req.body || {};
+    if (endpointId === undefined || !clusterName || !command) {
+        return res.status(400).json({ error: 'body must contain endpointId, clusterName, command' });
+    }
+    try {
+        const result = await getController().sendCommand(req.params.nodeId, Number(endpointId), clusterName, command, args ?? {});
+        res.json({ ok: true, result: result ?? null });
+    } catch (err) {
+        if (err.message.includes('not found')) return res.status(404).json({ error: err.message });
+        res.status(500).json({ error: err.message });
+    }
+});
+
+module.exports = { router };

package/src/web/mqtt-api.js

@@ -0,0 +1,65 @@
+'use strict';
+
+/**
+ * MQTT state REST API — Express router mounted at /she/mqtt
+ *
+ * Routes:
+ *   GET  /she/mqtt/state    → snapshot of all retained MQTT topic values
+ *   POST /she/mqtt/publish  → publish a message to a topic
+ *
+ * Call init(store, getMqttClient) once after the state store is created.
+ * The getMqttClient callback is a zero-arg function returning the live mqtt client
+ * (or null when no broker is configured).
+ *
+ * State changes for mqtt:: keys are automatically broadcast to WebSocket clients
+ * as { type: 'mqtt', topic, val, ts }.
+ */
+
+const express = require('express');
+const { broadcast } = require('./log-ws');
+
+const router = express.Router();
+
+let _store = null;
+let _getMqtt = () => null;
+
+/**
+ * Initialise the MQTT API with the state store and an MQTT client getter.
+ * @param {import('../lib/state-store')} store
+ * @param {() => import('mqtt').MqttClient | null} getMqttClient
+ */
+function init(store, getMqttClient) {
+    _store = store;
+    _getMqtt = getMqttClient;
+
+    // Forward every mqtt:: state change to connected WebSocket clients
+    store.on('change', (key, val, obj) => {
+        if (!key.startsWith('mqtt::')) return;
+        broadcast({ type: 'mqtt', topic: key.slice(6), val: obj.val, ts: obj.ts });
+    });
+}
+
+// GET /she/mqtt/state — sorted snapshot of all retained MQTT topic values
+router.get('/state', (req, res) => {
+    if (!_store) return res.json([]);
+    const result = [];
+    for (const [topic, obj] of _store.mqttEntries()) {
+        result.push({ topic, val: obj.val, ts: obj.ts });
+    }
+    result.sort((a, b) => a.topic.localeCompare(b.topic));
+    res.json(result);
+});
+
+// POST /she/mqtt/publish — { topic, payload, retain?, qos? }
+router.post('/publish', (req, res) => {
+    const mqtt = _getMqtt();
+    if (!mqtt) return res.status(503).json({ error: 'MQTT not connected' });
+    const { topic, payload, retain = false, qos = 0 } = req.body || {};
+    if (!topic) return res.status(400).json({ error: 'topic required' });
+    mqtt.publish(topic, String(payload ?? ''), { retain, qos }, (err) => {
+        if (err) return res.status(500).json({ error: err.message });
+        res.json({ ok: true });
+    });
+});
+
+module.exports = { router, init };

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