smart-home-engine 0.0.1 → 0.10.4

package/src/web/ai-api.js

@@ -0,0 +1,443 @@
+'use strict';
+
+/**
+ * AI Assistant REST API — Express router mounted at /she/ai
+ *
+ * Proxies chat requests to a configured LLM provider (Ollama, LM Studio,
+ * OpenAI, or Anthropic), assembling context (MQTT state, sheDB doc IDs,
+ * Matter devices, she API reference) server-side based on per-request flags.
+ *
+ * Routes:
+ *   GET  /she/ai/config        → { configured, provider, model, baseUrl }
+ *   POST /she/ai/chat          → { message, usage? }           (non-streaming)
+ *   POST /she/ai/chat/stream   → SSE  data: {"token":"..."}    (streaming)
+ *                                     data: [DONE]
+ *
+ * Call init(store) once after the state store is created.
+ */
+
+const express = require('express');
+const fs = require('fs');
+
+const router = express.Router();
+let _store = null;
+
+/**
+ * @param {import('../lib/state-store')} store
+ */
+function init(store) {
+    _store = store;
+}
+
+// ---------------------------------------------------------------------------
+// she API reference — injected into the system prompt when requested
+// ---------------------------------------------------------------------------
+const SHE_API_REF = `## she sandbox API
+
+Scripts run in a sandboxed VM. The \`she\` object is injected automatically.
+
+### Script conventions
+- First lines: /* global she */ then 'use strict';
+- No require() — the module system is not available
+- All subscriptions and schedules persist across reconnects
+
+### MQTT
+she.mqtt.sub(topic, [opts], cb)        Subscribe; wildcards: + (1 level) # (multi)
+                                         +//sensor  →  +/status/sensor shorthand
+                                         opts.change: true = only fire when value changes
+she.mqtt.pub(topic, payload, [opts])   Publish; opts: { qos, retain }
+she.mqtt.get(topic)                    Current retained value (sync)
+she.mqtt.set(topic, val)               Publish as retained
+she.mqtt.link(src, target, [fn])       Forward src changes to target; optional transform
+she.mqtt.age(topic)                    Seconds since topic last received a message
+she.mqtt.on('connect'|'disconnect', cb) MQTT lifecycle events
+
+### Scheduling
+she.schedule(pattern, [opts], cb)
+  pattern: cron string | Date | suncalc event name
+  suncalc events: 'sunrise' 'sunset' 'dawn' 'dusk'
+                  'nauticalDawn' 'nauticalDusk' 'solarNoon' 'night'
+  opts.shift:  seconds offset (e.g. -1800 = 30 min before event)
+  opts.random: max random delay in seconds added to the trigger time
+
+### Universal key-value API
+she.on(key, cb)        Subscribe. Key prefixes: mqtt::  var::  matter::
+she.set(key, val)      Set value (mqtt:: or var:: namespaces)
+she.get(key)           Current value
+she.getObject(key)     Current { val, ts, lc } state object
+
+### Variable system (var:: namespace)
+Topics prefixed with "var" (default) are persisted as retained MQTT messages
+and available across scripts via she.get('var::name') / she.set('var::name', v).
+
+### sheDB
+she.db.get(id)                      Get document (undefined if not found)
+she.db.set(id, doc)                 Create or overwrite document
+she.db.extend(id, partial)          Deep-merge partial into existing document
+she.db.delete(id)                   Delete document
+she.db.sub(pattern, cb)             Subscribe to document changes (MQTT wildcard)
+she.db.query(filter, mapFn, [reduceFn])  Synchronous ad-hoc query → Array
+
+### Matter
+she.matter.sub(nodeId, endpointId, cluster, attr, cb)    Subscribe to attribute
+she.matter.unsub(listenerId)
+she.matter.get(nodeId, endpointId, cluster, attr)         → Promise<value>
+she.matter.send(nodeId, endpointId, cluster, cmd, [args]) → Promise<result>
+
+### Helpers
+she.timer(src, target, ms)           Pulse target=1 for ms after src goes truthy
+she.combineBool(srcs[], target)      Publish OR of source values to target
+she.combineMax(srcs[], target)       Publish maximum of source values to target
+she.link(src, target, [fn])          Alias for she.mqtt.link
+she.age(topic)                       Alias for she.mqtt.age
+she.now()                            Current timestamp in ms
+she.debug / .info / .warn / .error   Structured logging (prefixed with script name)
+she.global                           Shared mutable object across all scripts`;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the ai config section from config.json.
+ * Returns null if unavailable.
+ * @param {string|undefined} configPath
+ * @returns {{ provider?: string, baseUrl?: string, model?: string, apiKey?: string }|null}
+ */
+function readAiConfig(configPath) {
+    if (!configPath) return null;
+    try {
+        const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        return cfg.ai || null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Build the full system prompt, including optional context sections.
+ *
+ * @param {object} requestCtx   { apiref, mqtt, shedb, matter }
+ * @param {{ path?: string, content?: string }|null} currentScript
+ * @param {import('../lib/state-store')|null} store
+ * @returns {string}
+ */
+function buildSystemPrompt(requestCtx, currentScript, store) {
+    const parts = [
+        `You are SHE Assistant, an expert AI pair programmer for she (smart-home-engine).
+she is a Node.js daemon that runs user JavaScript scripts in a sandboxed VM for home automation.
+When proposing changes to a script, always output the COMPLETE new file content in a single fenced \`\`\`javascript code block. Never output partial diffs or fragments — the user applies the full file at once.
+Keep any existing header comments and the 'use strict'; directive.`,
+    ];
+
+    if (requestCtx.apiref) {
+        parts.push(SHE_API_REF);
+    }
+
+    if (currentScript?.path && typeof currentScript.content === 'string') {
+        parts.push(`## Current script: ${currentScript.path}\n\`\`\`javascript\n${currentScript.content}\n\`\`\``);
+    }
+
+    if (requestCtx.mqtt && store) {
+        const topics = [];
+        for (const [topic, obj] of store.mqttEntries()) {
+            topics.push(`${topic}: ${JSON.stringify(obj.val)}`);
+            if (topics.length >= 100) {
+                topics.push('… (truncated)');
+                break;
+            }
+        }
+        if (topics.length > 0) {
+            parts.push(`## Current MQTT state\n${topics.join('\n')}`);
+        }
+    }
+
+    if (requestCtx.shedb) {
+        try {
+            const core = require('./shedb').getCore();
+            if (core) {
+                const ids = typeof core.listIds === 'function' ? core.listIds() : [];
+                if (ids.length > 0) {
+                    parts.push(`## sheDB document IDs (${ids.length} total)\n${ids.slice(0, 200).join('\n')}`);
+                }
+            }
+        } catch {
+            // shedb not initialised — skip silently
+        }
+    }
+
+    if (requestCtx.matter) {
+        try {
+            const controller = require('../matter/controller');
+            if (typeof controller.listPaired === 'function') {
+                const nodes = controller.listPaired();
+                if (nodes.length > 0) {
+                    const list = nodes.map((n) => `  nodeId ${n.nodeId}: ${n.label || 'unnamed'}`).join('\n');
+                    parts.push(`## Paired Matter devices\n${list}`);
+                }
+            }
+        } catch {
+            // matter not initialised — skip silently
+        }
+    }
+
+    return parts.join('\n\n');
+}
+
+// ---------------------------------------------------------------------------
+// Provider adapters — non-streaming
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {{ baseUrl?: string, model: string, apiKey?: string }} config
+ * @param {Array<{role:string,content:string}>} messages
+ */
+async function callOpenAICompat(config, messages) {
+    const base = (config.baseUrl || 'http://localhost:11434').replace(/\/$/, '');
+    const url = `${base}/v1/chat/completions`;
+    const headers = { 'Content-Type': 'application/json' };
+    if (config.apiKey) headers['Authorization'] = `Bearer ${config.apiKey}`;
+
+    const res = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ model: config.model, messages, stream: false }),
+    });
+
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`LLM API error ${res.status}: ${text.slice(0, 300)}`);
+    }
+
+    const json = await res.json();
+    const choice = json.choices?.[0];
+    const message = choice?.message?.content ?? choice?.text ?? '';
+    const usage = json.usage
+        ? {
+              prompt_tokens: json.usage.prompt_tokens,
+              completion_tokens: json.usage.completion_tokens,
+          }
+        : undefined;
+    return { message, usage };
+}
+
+/**
+ * @param {{ model: string, apiKey?: string }} config
+ * @param {Array<{role:string,content:string}>} messages  — first may be role:'system'
+ */
+async function callAnthropic(config, messages) {
+    const systemMsg = messages.find((m) => m.role === 'system');
+    const userMessages = messages.filter((m) => m.role !== 'system');
+
+    const headers = {
+        'Content-Type': 'application/json',
+        'x-api-key': config.apiKey || '',
+        'anthropic-version': '2023-06-01',
+    };
+
+    const res = await fetch('https://api.anthropic.com/v1/messages', {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+            model: config.model,
+            system: systemMsg?.content || '',
+            messages: userMessages,
+            max_tokens: 4096,
+        }),
+    });
+
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`Anthropic API error ${res.status}: ${text.slice(0, 300)}`);
+    }
+
+    const json = await res.json();
+    const message = json.content?.[0]?.text ?? '';
+    const usage = json.usage
+        ? {
+              prompt_tokens: json.usage.input_tokens,
+              completion_tokens: json.usage.output_tokens,
+          }
+        : undefined;
+    return { message, usage };
+}
+
+// ---------------------------------------------------------------------------
+// Provider adapters — streaming
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse an SSE ReadableStream, calling onToken for each non-null extracted value.
+ * @param {ReadableStream} body
+ * @param {(json:object)=>string|null|undefined} tokenExtractor
+ * @param {(token:string)=>void} onToken
+ */
+async function parseSseStream(body, tokenExtractor, onToken) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+
+            for (const line of lines) {
+                if (!line.startsWith('data: ')) continue;
+                const data = line.slice(6).trim();
+                if (data === '[DONE]') return;
+                try {
+                    const json = JSON.parse(data);
+                    const token = tokenExtractor(json);
+                    if (token) onToken(token);
+                } catch {
+                    // skip malformed JSON lines
+                }
+            }
+        }
+    } finally {
+        reader.releaseLock();
+    }
+}
+
+/**
+ * Stream tokens from an OpenAI-compatible endpoint.
+ * Calls onToken(str) for each chunk, resolves when stream ends.
+ */
+async function streamOpenAICompat(config, messages, onToken) {
+    const base = (config.baseUrl || 'http://localhost:11434').replace(/\/$/, '');
+    const url = `${base}/v1/chat/completions`;
+    const headers = { 'Content-Type': 'application/json' };
+    if (config.apiKey) headers['Authorization'] = `Bearer ${config.apiKey}`;
+
+    const res = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ model: config.model, messages, stream: true }),
+    });
+
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`LLM API error ${res.status}: ${text.slice(0, 300)}`);
+    }
+
+    await parseSseStream(res.body, (json) => json.choices?.[0]?.delta?.content, onToken);
+}
+
+/**
+ * Stream tokens from Anthropic Messages API.
+ */
+async function streamAnthropic(config, messages, onToken) {
+    const systemMsg = messages.find((m) => m.role === 'system');
+    const userMessages = messages.filter((m) => m.role !== 'system');
+
+    const headers = {
+        'Content-Type': 'application/json',
+        'x-api-key': config.apiKey || '',
+        'anthropic-version': '2023-06-01',
+    };
+
+    const res = await fetch('https://api.anthropic.com/v1/messages', {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+            model: config.model,
+            system: systemMsg?.content || '',
+            messages: userMessages,
+            max_tokens: 4096,
+            stream: true,
+        }),
+    });
+
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`Anthropic API error ${res.status}: ${text.slice(0, 300)}`);
+    }
+
+    await parseSseStream(res.body, (json) => json.delta?.text, onToken);
+}
+
+// ---------------------------------------------------------------------------
+// Routes
+// ---------------------------------------------------------------------------
+
+// GET /she/ai/config
+router.get('/config', (req, res) => {
+    const ai = readAiConfig(req.app.locals.configPath);
+    res.json({
+        configured: !!(ai?.provider && ai?.model),
+        provider: ai?.provider || '',
+        model: ai?.model || '',
+        baseUrl: ai?.baseUrl || '',
+    });
+});
+
+// POST /she/ai/chat — non-streaming
+router.post('/chat', async (req, res) => {
+    const ai = readAiConfig(req.app.locals.configPath);
+    if (!ai?.provider || !ai?.model) {
+        return res.status(400).json({ error: 'AI provider not configured. Set ai.provider and ai.model in Config.' });
+    }
+
+    const { messages = [], currentScript, context = {} } = req.body || {};
+    if (!Array.isArray(messages)) return res.status(400).json({ error: 'messages must be an array' });
+
+    const systemPrompt = buildSystemPrompt(context, currentScript ?? null, _store);
+    const fullMessages = [{ role: 'system', content: systemPrompt }, ...messages];
+
+    try {
+        let result;
+        if (ai.provider === 'anthropic') {
+            result = await callAnthropic(ai, fullMessages);
+        } else {
+            result = await callOpenAICompat(ai, fullMessages);
+        }
+        res.json(result);
+    } catch (e) {
+        res.status(500).json({ error: e.message });
+    }
+});
+
+// POST /she/ai/chat/stream — SSE streaming
+router.post('/chat/stream', async (req, res) => {
+    const ai = readAiConfig(req.app.locals.configPath);
+    if (!ai?.provider || !ai?.model) {
+        return res.status(400).json({ error: 'AI provider not configured. Set ai.provider and ai.model in Config.' });
+    }
+
+    const { messages = [], currentScript, context = {} } = req.body || {};
+    if (!Array.isArray(messages)) return res.status(400).json({ error: 'messages must be an array' });
+
+    res.set({
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+    });
+    res.flushHeaders();
+
+    const send = (data) => res.write(`data: ${JSON.stringify(data)}\n\n`);
+
+    const systemPrompt = buildSystemPrompt(context, currentScript ?? null, _store);
+    const fullMessages = [{ role: 'system', content: systemPrompt }, ...messages];
+
+    try {
+        const onToken = (t) => send({ token: t });
+
+        if (ai.provider === 'anthropic') {
+            await streamAnthropic(ai, fullMessages, onToken);
+        } else {
+            await streamOpenAICompat(ai, fullMessages, onToken);
+        }
+
+        res.write('data: [DONE]\n\n');
+        res.end();
+    } catch (e) {
+        send({ error: e.message });
+        res.end();
+    }
+});
+
+module.exports = { router, init };

package/src/web/config-api.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const express = require('express');
+const fs = require('fs');
+const path = require('path');
+const { getConfigPath } = require('../lib/storage');
+
+const DEFAULT_CONFIG_PATH = getConfigPath();
+
+const router = express.Router();
+
+router.get('/', (req, res) => {
+    const configPath = req.app.locals.configPath || DEFAULT_CONFIG_PATH;
+    let fileConfig = {};
+    try {
+        fileConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    } catch {
+        // config file does not exist yet — return empty object
+    }
+    res.json(fileConfig);
+});
+
+router.put('/', (req, res) => {
+    const configPath = req.app.locals.configPath || DEFAULT_CONFIG_PATH;
+    try {
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        fs.writeFileSync(configPath, JSON.stringify(req.body, null, 2), 'utf8');
+        res.json({ ok: true, restartRequired: true, configPath });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+module.exports = { router, DEFAULT_CONFIG_PATH };

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