iobroker.autodoc 0.9.35

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +126 -0
  3. package/admin/autodoc.png +0 -0
  4. package/admin/i18n/de.json +244 -0
  5. package/admin/i18n/en.json +241 -0
  6. package/admin/i18n/es.json +229 -0
  7. package/admin/i18n/fr.json +235 -0
  8. package/admin/i18n/it.json +229 -0
  9. package/admin/i18n/nl.json +229 -0
  10. package/admin/i18n/pl.json +229 -0
  11. package/admin/i18n/pt.json +229 -0
  12. package/admin/i18n/ru.json +229 -0
  13. package/admin/i18n/uk.json +229 -0
  14. package/admin/i18n/zh-cn.json +229 -0
  15. package/admin/jsonConfig.json +1490 -0
  16. package/io-package.json +253 -0
  17. package/lib/adapter-config.d.ts +19 -0
  18. package/lib/aiEnhancer.js +2114 -0
  19. package/lib/autoHostTopologyMermaid.js +195 -0
  20. package/lib/dependencyAnalyzer.js +83 -0
  21. package/lib/diagnosisSnapshot.js +32 -0
  22. package/lib/discovery.js +953 -0
  23. package/lib/docTemplateConfig.js +422 -0
  24. package/lib/documentModel.js +640 -0
  25. package/lib/forumCard.js +70 -0
  26. package/lib/guestHelpContent.js +93 -0
  27. package/lib/guestScriptPrivacy.js +14 -0
  28. package/lib/hostDisplay.js +19 -0
  29. package/lib/htmlRenderer.js +4108 -0
  30. package/lib/htmlThemePresets.js +79 -0
  31. package/lib/htmlToPdf.js +99 -0
  32. package/lib/i18n.js +1309 -0
  33. package/lib/markdownRenderer.js +2025 -0
  34. package/lib/mermaidAutodocPalette.js +165 -0
  35. package/lib/mermaidServerSvg.js +252 -0
  36. package/lib/notifier.js +124 -0
  37. package/lib/quickStartGuide.js +180 -0
  38. package/lib/roleMapper.js +90 -0
  39. package/lib/scriptGroups.js +78 -0
  40. package/lib/versionTracker.js +312 -0
  41. package/main.js +1368 -0
  42. package/package.json +88 -0
package/lib/htmlThemePresets.js ADDED
@@ -0,0 +1,79 @@
1
+ /**
2
+ * Optional named CSS variable packs for Admin/User/Onboarding HTML (no user-written CSS).
3
+ * Applied as classes on the root <html> element: `autodoc-preset-{id}`.
4
+ */
5
+
6
+ /**
7
+ * @param {string} presetId From {@link import('./docTemplateConfig').parseHtmlThemePreset}
8
+ * @returns {string} Additional class on `<html>` (leading space) or empty for default
9
+ */
10
+ function themePresetHtmlClass(presetId) {
11
+ if (!presetId || presetId === 'default') {
12
+ return '';
13
+ }
14
+ if (presetId === 'highContrast' || presetId === 'warm' || presetId === 'slate') {
15
+ return ` autodoc-preset-${presetId}`;
16
+ }
17
+ return '';
18
+ }
19
+
20
+ /**
21
+ * Extra rules appended after the base :root / body.dark block (only theme variables).
22
+ * Kept compact: overrides --* tokens used in htmlRenderer's inline stylesheet.
23
+ *
24
+ * @returns {string} CSS (no <style> wrapper)
25
+ */
26
+ function getThemePresetStyleBlock() {
27
+ /* highContrast — higher edge contrast, readable links */
28
+ /* warm — light sepia; dark brown nav */
29
+ /* slate — cool gray-blue; calm nav */
30
+ return `
31
+ html.autodoc-preset-highContrast {
32
+ --bg: #e2e2e2; --surface: #fff; --border: #1f1f1f; --text: #0a0a0a; --text-muted: #333; --text-faint: #4a4a4a;
33
+ --link: #003b8e; --nav-bg: #0c0c14; --nav-text: #f0f0f0; --nav-hover: rgba(255,255,255,0.14);
34
+ --th-bg: #dedede; --row-hover: #ececec; --score-bar-bg: #c8c8c8;
35
+ --note-bg: #fff3cd; --note-border: #c9a000; --manual-bg: #fff8e6; --manual-border: #b8860b;
36
+ --ai-bg: #e6f0ff; --ai-border: #3d6bb8; --device-bg: #fff; --adapter-bg: #fff; --stat-bg: #fff; --meta-bg: #fff; --changelog-bg: #f0f0f0;
37
+ }
38
+ html.autodoc-preset-highContrast body.dark {
39
+ --bg: #0a0a0a; --surface: #141414; --border: #666; --text: #f5f5f5; --text-muted: #c8c8c8; --text-faint: #9a9a9a;
40
+ --link: #8cc4ff; --nav-bg: #050508; --nav-text: #e0e0e0; --nav-hover: rgba(255,255,255,0.1);
41
+ --th-bg: #222; --row-hover: #1c1c1c; --score-bar-bg: #333;
42
+ --note-bg: #2a2000; --note-border: #a07800; --manual-bg: #2a2000; --manual-border: #a07800;
43
+ --ai-bg: #101d32; --ai-border: #3d6a9c; --device-bg: #141414; --adapter-bg: #141414; --stat-bg: #141414; --meta-bg: #141414; --changelog-bg: #121212;
44
+ }
45
+ html.autodoc-preset-warm {
46
+ --bg: #efe8de; --surface: #faf6f0; --border: #c4b8a8; --text: #2a2218; --text-muted: #4a3f32; --text-faint: #6b5d4a;
47
+ --link: #8b4513; --nav-bg: #2d2418; --nav-text: #e8ddd0; --nav-hover: rgba(255,255,255,0.1);
48
+ --th-bg: #e2d9cc; --row-hover: #e8e0d4; --score-bar-bg: #d4c8b8;
49
+ --note-bg: #fff4e0; --note-border: #c4a000; --manual-bg: #fff0d8; --manual-border: #b8860b;
50
+ --ai-bg: #f2ecff; --ai-border: #9a7bc0; --device-bg: #faf6f0; --adapter-bg: #faf6f0; --stat-bg: #faf6f0; --meta-bg: #faf6f0; --changelog-bg: #f0ebe4;
51
+ }
52
+ html.autodoc-preset-warm body.dark {
53
+ --bg: #1a1510; --surface: #242018; --border: #4a3f32; --text: #e8ddd0; --text-muted: #b0a090; --text-faint: #7a6a58;
54
+ --link: #e6b86a; --nav-bg: #120e0a; --nav-text: #d4c4b0; --nav-hover: rgba(255,255,255,0.08);
55
+ --th-bg: #2a2418; --row-hover: #201c14; --score-bar-bg: #3a3228;
56
+ --note-bg: #2a2000; --note-border: #a07800; --manual-bg: #2a2000; --manual-border: #a07800;
57
+ --ai-bg: #1c1820; --ai-border: #5c4a70; --device-bg: #242018; --adapter-bg: #242018; --stat-bg: #242018; --meta-bg: #242018; --changelog-bg: #1c1814;
58
+ }
59
+ html.autodoc-preset-slate {
60
+ --bg: #e4e7ec; --surface: #f1f3f6; --border: #9aa3b0; --text: #1a1f2a; --text-muted: #3d4859; --text-faint: #5c6880;
61
+ --link: #0b5bb5; --nav-bg: #1a2330; --nav-text: #d4dce6; --nav-hover: rgba(255,255,255,0.1);
62
+ --th-bg: #d8dee8; --row-hover: #e8ebf0; --score-bar-bg: #cbd2dc;
63
+ --note-bg: #e8f0ff; --note-border: #4a6fa0; --manual-bg: #e8f0ff; --manual-border: #4a6fa0;
64
+ --ai-bg: #e4eef8; --ai-border: #5a7ca8; --device-bg: #f1f3f6; --adapter-bg: #f1f3f6; --stat-bg: #f1f3f6; --meta-bg: #f1f3f6; --changelog-bg: #e6eaf0;
65
+ }
66
+ html.autodoc-preset-slate body.dark {
67
+ --bg: #0f1117; --surface: #1a1f2a; --border: #3a4556; --text: #e0e6ef; --text-muted: #9aa8bc; --text-faint: #6a7690;
68
+ --link: #6ab0ff; --nav-bg: #0d1018; --nav-text: #b8c4d4; --nav-hover: rgba(255,255,255,0.08);
69
+ --th-bg: #242b38; --row-hover: #1c2230; --score-bar-bg: #2a3344;
70
+ --note-bg: #1a2030; --note-border: #3d5a8a; --manual-bg: #1a2030; --manual-border: #3d5a8a;
71
+ --ai-bg: #121a28; --ai-border: #2d4a70; --device-bg: #1a1f2a; --adapter-bg: #1a1f2a; --stat-bg: #1a1f2a; --meta-bg: #1a1f2a; --changelog-bg: #141a24;
72
+ }
73
+ `;
74
+ }
75
+
76
+ module.exports = {
77
+ themePresetHtmlClass,
78
+ getThemePresetStyleBlock,
79
+ };
package/lib/htmlToPdf.js ADDED
@@ -0,0 +1,99 @@
1
+ 'use strict';
2
+
3
+ const fs = require('node:fs').promises;
4
+ const path = require('node:path');
5
+ const os = require('node:os');
6
+ const { pathToFileURL } = require('node:url');
7
+
8
+ /**
9
+ * @returns {object|null} Resolved `puppeteer` module when installed, otherwise `null`.
10
+ */
11
+ function tryRequirePuppeteer() {
12
+ try {
13
+ return require('puppeteer');
14
+ } catch {
15
+ return null;
16
+ }
17
+ }
18
+
19
+ /**
20
+ * Wait for delayed client-side renders (e.g. Mermaid from jsDelivr).
21
+ *
22
+ * @param {number} ms - Delay in milliseconds
23
+ * @returns {Promise<void>}
24
+ */
25
+ function delay(ms) {
26
+ return new Promise(resolve => setTimeout(resolve, ms));
27
+ }
28
+
29
+ /**
30
+ * Renders three HTML profiles to PDF buffers using Puppeteer (optional npm package).
31
+ * Uses Chromium with the same sandbox flags as Mermaid CLI (Docker/LXC compatibility).
32
+ *
33
+ * @param {{ admin?: string, user?: string, onboarding?: string }} htmlAll UTF-8 HTML per profile.
34
+ * @param {(line: string) => void} [logInfo] Progress logger (optional).
35
+ * @returns {Promise<Partial<Record<'admin'|'user'|'onboarding', Buffer>>>} Non-empty buffers only when generation succeeded for that profile.
36
+ */
37
+ async function renderProfilesToPdfBuffers(htmlAll, logInfo) {
38
+ const puppeteer = tryRequirePuppeteer();
39
+ if (!puppeteer) {
40
+ throw new Error(
41
+ 'PDF export needs the optional "puppeteer" package with Chromium (npm install puppeteer in this adapter folder, or install dependencies including optional packages).',
42
+ );
43
+ }
44
+
45
+ const profiles = ['admin', 'user', 'onboarding'];
46
+ const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'iobroker-autodoc-pdf-'));
47
+
48
+ const browser = await puppeteer.launch({
49
+ headless: true,
50
+ args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
51
+ });
52
+
53
+ const log = typeof logInfo === 'function' ? logInfo : () => {};
54
+
55
+ const out = {};
56
+
57
+ try {
58
+ const page = await browser.newPage();
59
+ await page.setDefaultNavigationTimeout(120_000);
60
+
61
+ for (const profile of profiles) {
62
+ const html = htmlAll[profile];
63
+ if (!html || !String(html).trim()) {
64
+ continue;
65
+ }
66
+
67
+ const tmpHtml = path.join(tmpRoot, `${profile}.html`);
68
+ await fs.writeFile(tmpHtml, html, 'utf8');
69
+ const url = pathToFileURL(tmpHtml).href;
70
+ log(`profile ${profile}: loading (${tmpHtml})`);
71
+
72
+ try {
73
+ await page.goto(url, { waitUntil: 'networkidle0', timeout: 120_000 });
74
+ } catch {
75
+ await page.goto(url, { waitUntil: 'load', timeout: 120_000 });
76
+ }
77
+ /* Allow CDN-based Mermaid to finish rendering in the browser PDF path */
78
+ await delay(3500);
79
+
80
+ const pdfBuf = await page.pdf({
81
+ format: 'A4',
82
+ printBackground: true,
83
+ margin: { top: '10mm', bottom: '12mm', left: '8mm', right: '8mm' },
84
+ });
85
+ out[profile] = Buffer.isBuffer(pdfBuf) ? pdfBuf : Buffer.from(pdfBuf);
86
+ log(`profile ${profile}: ${out[profile].length} bytes PDF`);
87
+ }
88
+ } finally {
89
+ await browser.close();
90
+ await fs.rm(tmpRoot, { recursive: true, force: true });
91
+ }
92
+
93
+ return out;
94
+ }
95
+
96
+ module.exports = {
97
+ tryRequirePuppeteer,
98
+ renderProfilesToPdfBuffers,
99
+ };