iobroker.autodoc 0.9.35

package/lib/mermaidAutodocPalette.js

@@ -0,0 +1,165 @@
+/**
+ * Optional named CSS variable packs — same ids as `htmlThemePreset` / `lib/htmlThemePresets.js`.
+ */
+'use strict';
+
+const PRESET_SET = new Set(['default', 'highContrast', 'warm', 'slate']);
+
+/**
+ * @param {string} presetId Raw or normalized `htmlThemePreset` id
+ * @returns {string} One of default, highContrast, warm, slate
+ */
+function normalizeMermaidPreset(presetId) {
+	const s = String(presetId || 'default');
+	return PRESET_SET.has(s) ? s : 'default';
+}
+
+/**
+ * Full `themeVariables` for Mermaid `theme: base` (one HTML palette × light/dark shell).
+ *
+ * @param {string} presetId Preset id (see {@link normalizeMermaidPreset})
+ * @param {boolean} isDark Whether export uses dark diagram palette (body.dark / mmdc dark)
+ * @returns {Record<string, string | boolean>} Mermaid themeVariables
+ */
+function getAutodocMermaidThemeVariables(presetId, isDark) {
+	const p = normalizeMermaidPreset(presetId);
+	if (!isDark) {
+		switch (p) {
+			case 'highContrast':
+				return {
+					darkMode: false,
+					background: '#e2e2e2',
+					primaryColor: '#f5f5f5',
+					primaryTextColor: '#0a0a0a',
+					lineColor: '#0a0a0a',
+					arrowheadColor: '#0a0a0a',
+					defaultLinkColor: '#0a0a0a',
+					clusterBkg: '#dedede',
+					clusterBorder: '#1f1f1f',
+					titleColor: '#0a0a0a',
+				};
+			case 'warm':
+				return {
+					darkMode: false,
+					background: '#efe8de',
+					primaryColor: '#f5ebe0',
+					primaryTextColor: '#2a2218',
+					lineColor: '#4a3f32',
+					arrowheadColor: '#4a3f32',
+					defaultLinkColor: '#4a3f32',
+					clusterBkg: '#e2d9cc',
+					clusterBorder: '#c4b8a8',
+					titleColor: '#2a2218',
+				};
+			case 'slate':
+				return {
+					darkMode: false,
+					background: '#e4e7ec',
+					primaryColor: '#e8ecf0',
+					primaryTextColor: '#1a1f2a',
+					lineColor: '#3d4859',
+					arrowheadColor: '#3d4859',
+					defaultLinkColor: '#3d4859',
+					clusterBkg: '#d8dee8',
+					clusterBorder: '#9aa3b0',
+					titleColor: '#1a1f2a',
+				};
+			default:
+				return {
+					darkMode: false,
+					lineColor: '#334155',
+					arrowheadColor: '#334155',
+					defaultLinkColor: '#334155',
+					clusterBkg: '#f0f3f7',
+					clusterBorder: '#c8d0db',
+					titleColor: '#333333',
+				};
+		}
+	}
+	switch (p) {
+		case 'highContrast':
+			return {
+				darkMode: true,
+				background: '#0a0a0a',
+				primaryColor: '#2a2a2a',
+				primaryTextColor: '#f5f5f5',
+				lineColor: '#f0f0f0',
+				arrowheadColor: '#f0f0f0',
+				defaultLinkColor: '#f0f0f0',
+				clusterBkg: '#222222',
+				clusterBorder: '#666666',
+				titleColor: '#f5f5f5',
+			};
+		case 'warm':
+			return {
+				darkMode: true,
+				background: '#1a1510',
+				primaryColor: '#3a3228',
+				primaryTextColor: '#e8ddd0',
+				lineColor: '#c8b8a8',
+				arrowheadColor: '#c8b8a8',
+				defaultLinkColor: '#c8b8a8',
+				clusterBkg: '#2a2418',
+				clusterBorder: '#4a3f32',
+				titleColor: '#e8ddd0',
+			};
+		case 'slate':
+			return {
+				darkMode: true,
+				background: '#0f1117',
+				primaryColor: '#2a3344',
+				primaryTextColor: '#e0e6ef',
+				lineColor: '#9aa8bc',
+				arrowheadColor: '#9aa8bc',
+				defaultLinkColor: '#9aa8bc',
+				clusterBkg: '#242b38',
+				clusterBorder: '#3a4556',
+				titleColor: '#e0e6ef',
+			};
+		default:
+			return {
+				darkMode: true,
+				background: '#1a1d2e',
+				primaryColor: '#5c4d7a',
+				primaryTextColor: '#f0f0f0',
+				lineColor: '#d0d5e0',
+				arrowheadColor: '#d0d5e0',
+				defaultLinkColor: '#d0d5e0',
+				clusterBkg: '#262a3f',
+				clusterBorder: '#3d4556',
+				titleColor: '#e0e0e0',
+			};
+	}
+}
+
+/**
+ * All preset × mode pairs for client `mermaid.initialize` (embedded JSON in HTML).
+ *
+ * @returns {object} Keys default, highContrast, warm, slate → { light, dark } variable maps
+ */
+function getMermaidClientThemeMatrix() {
+	return {
+		default: {
+			light: getAutodocMermaidThemeVariables('default', false),
+			dark: getAutodocMermaidThemeVariables('default', true),
+		},
+		highContrast: {
+			light: getAutodocMermaidThemeVariables('highContrast', false),
+			dark: getAutodocMermaidThemeVariables('highContrast', true),
+		},
+		warm: {
+			light: getAutodocMermaidThemeVariables('warm', false),
+			dark: getAutodocMermaidThemeVariables('warm', true),
+		},
+		slate: {
+			light: getAutodocMermaidThemeVariables('slate', false),
+			dark: getAutodocMermaidThemeVariables('slate', true),
+		},
+	};
+}
+
+module.exports = {
+	normalizeMermaidPreset,
+	getAutodocMermaidThemeVariables,
+	getMermaidClientThemeMatrix,
+};

package/lib/mermaidServerSvg.js

@@ -0,0 +1,252 @@
+'use strict';
+
+/**
+ * Embed Mermaid diagrams as inline SVG during HTML generation (Phase 5 — TODO § 1.2a).
+ * Uses @mermaid-js/mermaid-cli (Puppeteer) when installed as optional dependency; otherwise leaves <pre class="mermaid"> for client-side jsDelivr render.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { execFile } = require('node:child_process');
+const { promisify } = require('node:util');
+
+const execFileAsync = promisify(execFile);
+
+const { parseHtmlThemePreset } = require('./docTemplateConfig');
+const { getAutodocMermaidThemeVariables, normalizeMermaidPreset } = require('./mermaidAutodocPalette');
+
+/** @returns {string|null} Path to mermaid-cli `src/cli.js`, or null if not installed */
+function resolveMmdcCliJs() {
+	let dir = path.join(__dirname, '..');
+	for (let i = 0; i < 12; i++) {
+		const candidate = path.join(dir, 'node_modules', '@mermaid-js', 'mermaid-cli', 'src', 'cli.js');
+		if (fs.existsSync(candidate)) {
+			return candidate;
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) {
+			break;
+		}
+		dir = parent;
+	}
+	return null;
+}
+
+/**
+ * Undo {@link esc} in htmlRenderer (ampersand must be last).
+ *
+ * @param {string} innerHtml Raw inner HTML of `pre.mermaid`
+ * @returns {string} Decoded Mermaid source text
+ */
+function decodePreEscapedMermaid(innerHtml) {
+	return innerHtml
+		.replace(/&quot;/g, '"')
+		.replace(/&gt;/g, '>')
+		.replace(/&lt;/g, '<')
+		.replace(/&amp;/g, '&');
+}
+
+/**
+ * Puppeteer launch options for headless Chromium inside Docker/LXC/Unraid, where the
+ * kernel/user-namespace often provides no usable SUID sandbox (Chromium then exits with
+ * "No usable sandbox"). Diagram source is adapter-admin-controlled Mermaid text only.
+ *
+ * @param {string} tmpDir Temp directory (mkdtemp) — config file is removed with the rest
+ * @returns {Promise<string>} Absolute path to written JSON file
+ * @see https://pptr.dev/troubleshooting
+ */
+async function writeMmdcPuppeteerConfigFile(tmpDir) {
+	const cfgPath = path.join(tmpDir, 'puppeteer-config.json');
+	const cfg = {
+		args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
+	};
+	await fs.promises.writeFile(cfgPath, JSON.stringify(cfg), 'utf8');
+	return cfgPath;
+}
+
+/**
+ * Mermaid JSON for `mmdc -c` — uses `theme: "base"` so `themeVariables` apply (cluster + edge colors).
+ * Respects `htmlThemePreset` the same way as export CSS (`lib/htmlThemePresets.js`).
+ *
+ * @param {string} tmpDir Temp dir for `mermaid-config.json`
+ * @param {'default'|'dark'} mmdcTheme Palette from {@link mermaidCliTheme}
+ * @param {unknown} [htmlThemePreset] Raw or parsed `htmlThemePreset` config id
+ * @returns {Promise<string>} Path to written JSON
+ */
+async function writeMmdcMermaidConfigFile(tmpDir, mmdcTheme, htmlThemePreset) {
+	const cfgPath = path.join(tmpDir, 'mermaid-config.json');
+	const isDark = mmdcTheme === 'dark';
+	const preset = normalizeMermaidPreset(parseHtmlThemePreset(htmlThemePreset));
+	const cfg = { theme: 'base', themeVariables: getAutodocMermaidThemeVariables(preset, isDark) };
+	await fs.promises.writeFile(cfgPath, JSON.stringify(cfg), 'utf8');
+	return cfgPath;
+}
+
+/**
+ * @param {string} source Mermaid definition
+ * @param {{ theme: 'default'|'dark', themePreset?: unknown, width?: number, height?: number }} opts mmdc sizing, shell light/dark, HTML theme preset
+ * @returns {Promise<string>} SVG markup
+ */
+async function runMmdcToSvg(source, opts) {
+	const cliJs = resolveMmdcCliJs();
+	if (!cliJs || !fs.existsSync(cliJs)) {
+		throw new Error('@mermaid-js/mermaid-cli not available');
+	}
+	const width = opts.width ?? 1400;
+	const height = opts.height ?? 1000;
+	const palette = opts.theme === 'dark' ? 'dark' : 'default';
+	const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'autodoc-mermaid-'));
+	const inFile = path.join(tmpDir, 'diagram.mmd');
+	const outFile = path.join(tmpDir, 'diagram.svg');
+	try {
+		await fs.promises.writeFile(inFile, source, 'utf8');
+		const puppeteerConfigFile = await writeMmdcPuppeteerConfigFile(tmpDir);
+		const mermaidConfigFile = await writeMmdcMermaidConfigFile(tmpDir, palette, opts.themePreset);
+		await execFileAsync(
+			process.execPath,
+			[
+				cliJs,
+				'-i',
+				inFile,
+				'-o',
+				outFile,
+				/* CLI 10.x only allows default|forest|dark|neutral; config overwrites with theme "base". */
+				'-t',
+				palette,
+				'-c',
+				mermaidConfigFile,
+				'-w',
+				String(width),
+				'-H',
+				String(height),
+				'-b',
+				'transparent',
+				'-p',
+				puppeteerConfigFile,
+				'-q',
+			],
+			{ timeout: 120000, windowsHide: true, maxBuffer: 8 * 1024 * 1024 },
+		);
+		return await fs.promises.readFile(outFile, 'utf8');
+	} finally {
+		await fs.promises.rm(tmpDir, { recursive: true, force: true });
+	}
+}
+
+/**
+ * @param {'light'|'dark'|'auto'} colorScheme From {@link parseHtmlColorScheme}
+ * @returns {'default'|'dark'} Theme value for mmdc `-t`
+ */
+function mermaidCliTheme(colorScheme) {
+	return colorScheme === 'dark' ? 'dark' : 'default';
+}
+
+/**
+ * @param {string} html Full HTML document
+ * @param {{ colorScheme?: 'light'|'dark'|'auto', themePreset?: unknown, log?: { debug?: Function, warn?: Function } }} [options] Adapter logger + `htmlThemePreset`
+ * @returns {Promise<string>} HTML with diagrams embedded or unchanged
+ */
+async function embedMermaidDiagramsInHtml(html, options = {}) {
+	const cliJs = resolveMmdcCliJs();
+	if (!cliJs || !fs.existsSync(cliJs)) {
+		options.log?.debug?.(
+			'Mermaid: @mermaid-js/mermaid-cli not installed — HTML uses client-side Mermaid (jsDelivr). Install optional dependency for embedded SVG.',
+		);
+		return html;
+	}
+
+	const scheme =
+		options.colorScheme === 'light' || options.colorScheme === 'dark' || options.colorScheme === 'auto'
+			? options.colorScheme
+			: 'auto';
+	const theme = mermaidCliTheme(scheme);
+	const themePreset = options.themePreset;
+
+	/**
+	 * @param {string} docHtml HTML to scan
+	 * @param {RegExp} re Full block to replace; group 1 = inner `pre.mermaid` text
+	 * @returns {Promise<{ html: string, mmdcFailureCount: number, firstMmdcError: string }>} Rebuilt HTML and failure stats
+	 */
+	async function replaceMermaidPreBlocks(docHtml, re) {
+		const parts = [];
+		let lastIndex = 0;
+		let match;
+		const reGlobal = new RegExp(re.source, 'g');
+		let failCount = 0;
+		let firstErr = '';
+		while ((match = reGlobal.exec(docHtml)) !== null) {
+			parts.push(docHtml.slice(lastIndex, match.index));
+			const inner = match[1];
+			const fullMatch = match[0];
+			const source = decodePreEscapedMermaid(inner).trim();
+			if (!source) {
+				parts.push(fullMatch);
+			} else {
+				try {
+					const svg = await runMmdcToSvg(source, { theme, themePreset });
+					parts.push(`<div class="mermaid-wrap mermaid-svg-embedded">${svg}</div>`);
+				} catch (e) {
+					failCount++;
+					if (!firstErr) {
+						firstErr = e instanceof Error ? e.message : String(e);
+					}
+					const msg = e instanceof Error ? e.message : String(e);
+					options.log?.debug?.(
+						`Mermaid SVG (mmdc) failed for one diagram — keeping <pre class="mermaid">: ${msg}`,
+					);
+					parts.push(fullMatch);
+				}
+			}
+			lastIndex = match.index + fullMatch.length;
+		}
+		parts.push(docHtml.slice(lastIndex));
+		return { html: parts.join(''), mmdcFailureCount: failCount, firstMmdcError: firstErr };
+	}
+
+	const wrappedRe = /<div class="mermaid-wrap">\s*<pre class="mermaid">([\s\S]*?)<\/pre>\s*<\/div>/g;
+	const barePreRe = /<pre class="mermaid">([\s\S]*?)<\/pre>/g;
+
+	let mmdcFailureCount = 0;
+	let firstMmdcError = '';
+	let out = html;
+
+	const pass1 = await replaceMermaidPreBlocks(out, wrappedRe);
+	out = pass1.html;
+	mmdcFailureCount += pass1.mmdcFailureCount;
+	if (pass1.firstMmdcError) {
+		firstMmdcError = pass1.firstMmdcError;
+	}
+
+	const pass2 = await replaceMermaidPreBlocks(out, barePreRe);
+	out = pass2.html;
+	mmdcFailureCount += pass2.mmdcFailureCount;
+	if (!firstMmdcError && pass2.firstMmdcError) {
+		firstMmdcError = pass2.firstMmdcError;
+	}
+
+	if (mmdcFailureCount > 0) {
+		let hint =
+			'Install OS libraries for headless Chromium on Linux if you see libnss3 (etc.); see https://pptr.dev/troubleshooting — or use generated HTML online (jsDelivr).';
+		if (/sandbox|no-sandbox/i.test(firstMmdcError)) {
+			hint =
+				'If the error mentions Chromium sandbox / Docker: autodoc passes --no-sandbox to mmdc (update adapter). Else install OS libs (libnss3, …) — https://pptr.dev/troubleshooting.';
+		}
+		const errShort = firstMmdcError.length > 180 ? `${firstMmdcError.slice(0, 180)}…` : firstMmdcError;
+		options.log?.warn?.(
+			`Mermaid: ${mmdcFailureCount} diagram(s) not embedded as SVG (mmdc failed). ${hint} First error: ${errShort}`,
+		);
+	}
+	return out;
+}
+
+module.exports = {
+	getAutodocMermaidThemeVariables,
+	embedMermaidDiagramsInHtml,
+	resolveMmdcCliJs,
+	decodePreEscapedMermaid,
+	runMmdcToSvg,
+	mermaidCliTheme,
+	writeMmdcPuppeteerConfigFile,
+	writeMmdcMermaidConfigFile,
+};

package/lib/notifier.js

@@ -0,0 +1,124 @@
+/**
+ * AutoDoc Notifier Module
+ * Sends a notification via ioBroker messaging adapters after documentation generation.
+ */
+
+const ADAPTER_TELEGRAM = 'telegram';
+const ADAPTER_PUSHOVER = 'pushover';
+const ADAPTER_EMAIL = 'email';
+const ADAPTER_SIGNAL = 'signal-cmb';
+const ADAPTER_WHATSAPP = 'whatsapp-cmb';
+
+/**
+ * Notifier sends a message via sendTo after documentation generation.
+ *
+ * @param {object} adapter ioBroker adapter instance
+ */
+class Notifier {
+	/**
+	 * @param {object} adapter ioBroker adapter instance
+	 */
+	constructor(adapter) {
+		this.adapter = adapter;
+	}
+
+	/**
+	 * Send notification if enabled and configured.
+	 *
+	 * @param {object} docModel Generated document model
+	 * @param {object} changeData Change summary from version tracker
+	 * @returns {Promise<void>}
+	 */
+	async send(docModel, changeData) {
+		const config = this.adapter.config;
+
+		if (!config.notifyEnabled) {
+			return;
+		}
+
+		const instance = (config.notifyInstance || '').trim();
+		if (!instance) {
+			this.adapter.log.warn('Notification enabled but no adapter instance configured');
+			return;
+		}
+
+		const message = this.buildMessage(docModel, changeData);
+		const adapterType = instance.split('.')[0].toLowerCase();
+		const payload = this.buildPayload(adapterType, message, config.notifyTarget);
+
+		try {
+			await this.adapter.sendToAsync(instance, 'send', payload);
+			this.adapter.log.info(`Notification sent via ${instance}`);
+		} catch (err) {
+			this.adapter.log.warn(`Notification failed (${instance}): ${err.message}`);
+		}
+	}
+
+	/**
+	 * Build the notification message text.
+	 *
+	 * @param {object} docModel Document model
+	 * @param {object} changeData Change summary
+	 * @returns {string} Message text
+	 */
+	buildMessage(docModel, changeData) {
+		const template = (this.adapter.config.notifyMessage || '').trim();
+		const vars = {
+			'{project}': docModel.system.projectName || 'ioBroker',
+			'{summary}': changeData.summary || '',
+			'{version}': docModel.meta.version || '',
+			'{trigger}': docModel.meta.trigger || '',
+		};
+
+		if (template) {
+			return template.replace(/\{project\}|\{summary\}|\{version\}|\{trigger\}/g, m => vars[m] || m);
+		}
+
+		return `AutoDoc: "${vars['{project}']}" documentation generated — ${vars['{summary}']} (v${vars['{version}']}, trigger: ${vars['{trigger}']})`;
+	}
+
+	/**
+	 * Build adapter-specific sendTo payload.
+	 *
+	 * @param {string} adapterType Adapter name without instance number
+	 * @param {string} message Notification text
+	 * @param {string} target Optional recipient (user/chatId/email)
+	 * @returns {object} Payload for sendTo
+	 */
+	buildPayload(adapterType, message, target) {
+		const t = (target || '').trim();
+
+		switch (adapterType) {
+			case ADAPTER_TELEGRAM:
+				return t ? { text: message, user: t } : { text: message };
+
+			case ADAPTER_EMAIL:
+				return {
+					text: message,
+					subject: 'AutoDoc: Documentation generated',
+					...(t ? { to: t } : {}),
+				};
+
+			case ADAPTER_PUSHOVER:
+				return {
+					message,
+					title: 'AutoDoc',
+					...(t ? { device: t } : {}),
+				};
+
+			case ADAPTER_SIGNAL:
+			case ADAPTER_WHATSAPP:
+				return t ? { text: message, phone: t } : { text: message };
+
+			default:
+				// Generic fallback: try common fields
+				return {
+					text: message,
+					message,
+					...(t ? { to: t, user: t } : {}),
+				};
+		}
+	}
+}
+
+module.exports = Notifier;