smart-home-engine 0.0.1 → 0.11.0

package/src/web/deps-api.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const express = require('express');
+const { execFile } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const { STORAGE_ROOT } = require('../lib/storage');
+
+const router = express.Router();
+
+/** Ensure ~/.she/package.json exists so npm commands work. */
+function ensurePackageJson() {
+    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',
+        );
+    }
+}
+
+function readPackageJson() {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(STORAGE_ROOT, 'package.json'), 'utf8'));
+    } catch {
+        return { dependencies: {} };
+    }
+}
+
+/**
+ * Strict npm package-name validation.
+ * Allows scoped (@scope/name) and plain names; lowercase; no path traversal.
+ */
+function isValidPkgName(name) {
+    return typeof name === 'string' && name.length > 0 && name.length <= 214 && /^(@[a-z0-9][a-z0-9_\-.]*\/)?[a-z0-9][a-z0-9_\-.]*$/.test(name);
+}
+
+/** Allow semver ranges, tags, and dist-tags (no shell-special chars). */
+function isValidVersion(v) {
+    return typeof v === 'string' && v.length > 0 && v.length <= 50 && /^[a-z0-9_\-.*^~>=<|]+$/i.test(v);
+}
+
+// GET /she/deps  — list installed packages from ~/.she/package.json
+router.get('/', (req, res) => {
+    const pkg = readPackageJson();
+    const deps = pkg.dependencies || {};
+    res.json(Object.entries(deps).map(([name, version]) => ({ name, version })));
+});
+
+// GET /she/deps/search?q=term  — search the npm registry
+router.get('/search', (req, res) => {
+    const q = String(req.query.q ?? '').trim();
+    if (!q) return res.status(400).json({ error: 'Missing q parameter' });
+
+    const url = `https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(q)}&size=20`;
+    const npmReq = https.get(url, { timeout: 10000 }, (npmRes) => {
+        let data = '';
+        npmRes.on('data', (chunk) => {
+            data += chunk;
+        });
+        npmRes.on('end', () => {
+            try {
+                const parsed = JSON.parse(data);
+                const results = (parsed.objects ?? []).map((obj) => ({
+                    name: obj.package.name,
+                    version: obj.package.version,
+                    description: obj.package.description ?? '',
+                }));
+                res.json(results);
+            } catch {
+                if (!res.headersSent) res.status(502).json({ error: 'Failed to parse npm registry response' });
+            }
+        });
+    });
+    npmReq.on('error', (err) => {
+        if (!res.headersSent) res.status(502).json({ error: err.message });
+    });
+    npmReq.on('timeout', () => {
+        npmReq.destroy();
+        if (!res.headersSent) res.status(504).json({ error: 'npm registry timeout' });
+    });
+});
+
+// POST /she/deps/install  — { name, version? }
+router.post('/install', (req, res) => {
+    const name = String(req.body?.name ?? '').trim();
+    const version = req.body?.version ? String(req.body.version).trim() : null;
+
+    if (!isValidPkgName(name)) return res.status(400).json({ error: 'Invalid package name' });
+    if (version !== null && !isValidVersion(version)) return res.status(400).json({ error: 'Invalid version specifier' });
+
+    ensurePackageJson();
+    const spec = version ? `${name}@${version}` : name;
+    execFile('npm', ['install', '--save', spec], { cwd: STORAGE_ROOT, timeout: 120000 }, (err, stdout, stderr) => {
+        if (err) return res.status(500).json({ error: stderr || err.message, stdout });
+        res.json({ ok: true, stdout, stderr });
+    });
+});
+
+// POST /she/deps/remove  — { name }
+router.post('/remove', (req, res) => {
+    const name = String(req.body?.name ?? '').trim();
+
+    if (!isValidPkgName(name)) return res.status(400).json({ error: 'Invalid package name' });
+
+    ensurePackageJson();
+    execFile('npm', ['uninstall', '--save', name], { cwd: STORAGE_ROOT, timeout: 60000 }, (err, stdout, stderr) => {
+        if (err) return res.status(500).json({ error: stderr || err.message, stdout });
+        res.json({ ok: true, stdout, stderr });
+    });
+});
+
+// POST /she/deps/update  — { name }
+router.post('/update', (req, res) => {
+    const name = String(req.body?.name ?? '').trim();
+
+    if (!isValidPkgName(name)) return res.status(400).json({ error: 'Invalid package name' });
+
+    ensurePackageJson();
+    execFile('npm', ['install', '--save', `${name}@latest`], { cwd: STORAGE_ROOT, timeout: 120000 }, (err, stdout, stderr) => {
+        if (err) return res.status(500).json({ error: stderr || err.message, stdout });
+        res.json({ ok: true, stdout, stderr });
+    });
+});
+
+module.exports = { router };

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,78 @@
+'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
+ * @param {(req: import('http').IncomingMessage) => boolean} [authCheck]
+ *   Optional function that receives the upgrade request and returns true if
+ *   the connection should be allowed. Defaults to always-allow.
+ */
+function attachWss(httpServer, authCheck = () => true) {
+    _wss = new WebSocketServer({ server: httpServer, path: '/she/ws' });
+
+    _wss.on('connection', (ws, req) => {
+        if (!authCheck(req)) {
+            ws.close(1008, 'Unauthorized');
+            return;
+        }
+        _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 };