++
+
+
+@@ -74,4 +76,6 @@
+
+
++ Dokumentation
++ Preise
+
+ })
${title ? `${escape(title)}` : ''}`;
+ },
+ heading({ tokens, depth }) {
+ const text = this.parser.parseInline(tokens);
+ const base = slug(sanitizeHtml(text, { allowedTags: [], allowedAttributes: {} }));
+ const count = ids.get(base) || 0;
+ ids.set(base, count + 1);
+ const id = `${base}${count ? `-${count}` : ''}`;
+ if (depth === 2) toc.push({ id, title: sanitizeHtml(text, { allowedTags: [], allowedAttributes: {} }) });
+ return `${text}# `;
+ },
+ link({ href, tokens }) {
+ const label = this.parser.parseInline(tokens);
+ const target = resolveLink(href, page, pages);
+ return target ? `${label}` : `${label}`;
+ },
+ table(token) { return `${escape(page.title)} `;
+ return ['Anleitungen', 'Enelix EMS', 'Enelix Utils'].map(group => {
+ const members = pages.filter(page => page.group === group);
+ const rendered = new Set();
+ const entries = members.map(page => {
+ const folder = referenceFolders.find(item => item.outputs.includes(page.output));
+ if (!folder) return link(page);
+ if (rendered.has(folder.id)) return '';
+ rendered.add(folder.id);
+ const children = members.filter(child => folder.outputs.includes(child.output));
+ const active = children.some(child => child.output === current.output);
+ return `${escape(page.title)} | Enelix Dokumentation
+Zum InhaltenelixDokumentation
+
\n\n[bad](javascript:alert(1))\n\n[bad](data:text/html,test)\n\n**bold**\n\n```html\n\n```' }, targets);
+ assert.doesNotMatch(html, /bold<\/strong>/);
+ assert.match(html, /<script>literal/);
+});
+test('tables, duplicate headings and contents are rendered', () => {
+ const result = renderMarkdown({ ...page, markdown:'# Name\n\n## Gleich\n\n## Gleich\n\n| Name | Wert |\n| --- | --- |\n| Test | 12 |' }, targets);
+ assert.match(result.html, /table-scroll/); assert.match(result.html, //); assert.deepEqual(result.toc.map(x => x.id), ['gleich', 'gleich-1']);
+});
+test('HTML has public navigation and no login dependencies', () => {
+ const html = renderPage(page, [page], { branch:'develop', checkedAt:'2026-10-06T12:00:00Z' }, '123456');
+ assert.match(html, /lang="de"/); assert.match(html, /Testing/); assert.match(html, /href="\/docs\/preise.html"/); assert.doesNotMatch(html, /api\/session|app\.js/);
+});
+test('publication allowlist excludes internal operations', () => {
+ for (const repo of repositories) for (const [source] of repo.pages) assert.doesNotMatch(source, /HANDOFF|AGENT|Offene-Punkte|\.env|services|data\//);
+});
+const navigationPages = repositories.flatMap(repo => repo.pages.map(([source,title,output]) => ({ repo:repo.name, source, title, output, markdown:`# ${title}`, group:repo.id === 'ems' ? 'Enelix EMS' : 'Enelix Utils' })));
+test('navigation groups all consumers and interfaces without duplicating or changing URLs', () => {
+ const html = renderNavigation(page, navigationPages);
+ for (const item of navigationPages) assert.equal(html.split(`href="/docs/${item.output}"`).length - 1, 1);
+ const consumers = html.match(/data-folder="verbraucher"[^>]*>(.*?)<\/details>/s)[1];
+ assert.equal((consumers.match(/data-search=/g) || []).length, 8);
+ assert.match(consumers, /ems\/Batterie.html/); assert.match(consumers, /ems\/Easee-Gateway.html/);
+ assert.doesNotMatch(consumers, /ems\/Manager.html|ems\/schnittstelle.html/);
+ assert.match(html, /
Eigentümer
diff --git a/tools/public-docs/preview.mjs b/tools/public-docs/preview.mjs
new file mode 100644
index 0000000..8d7180a
--- /dev/null
+++ b/tools/public-docs/preview.mjs
@@ -0,0 +1,7 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const root = path.dirname(fileURLToPath(import.meta.url));
+process.env.DOCS_PUBLIC_DIR = path.join(root, 'preview');
+process.env.DOCS_STATE_DIR = path.join(root, 'preview-state');
+process.env.DOCS_ALLOW_DRAFTS = 'true';
+await import('./sync.mjs');
diff --git a/tools/public-docs/render.mjs b/tools/public-docs/render.mjs
new file mode 100644
index 0000000..e2394ed
--- /dev/null
+++ b/tools/public-docs/render.mjs
@@ -0,0 +1,105 @@
+import { posix } from 'node:path';
+import { Marked } from 'marked';
+import sanitizeHtml from 'sanitize-html';
+
+export const escape = value => String(value).replace(/[&<>"']/g, c => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' }[c]));
+export const slug = value => value.toLowerCase().replace(/<[^>]*>/g, '').replace(/[^\p{L}\p{N}\s_-]/gu, '').trim().replace(/\s/g, '-');
+
+export function resolveLink(href, page, pages) {
+ if (!href || /[\u0000-\u0020\\]/.test(href)) return null;
+ if (href.startsWith('#')) return href;
+ if (href === '/') return '/';
+ const [path, anchor] = href.split('#', 2);
+ let key;
+ if (/^https:\/\/git\.belevo\.ch\/ENELIX\/(Enelix-EMS|Enelix-Utils)\/src\/branch\/[^/]+\//.test(path)) {
+ const match = path.match(/^https:\/\/git\.belevo\.ch\/ENELIX\/(Enelix-EMS|Enelix-Utils)\/src\/branch\/[^/]+\/(.+)$/);
+ key = `${match[1]}/${match[2]}`;
+ } else if (/^https:\/\//.test(href)) {
+ try { const url = new URL(href); return url.username || url.password ? null : url.href; } catch { return null; }
+ } else if (/^[\w+.-]+:|^\/\//.test(href) || path.startsWith('/')) return null;
+ else key = posix.normalize(posix.join(page.repo, posix.dirname(page.source), path));
+ const target = pages.find(p => `${p.repo}/${p.source}` === key);
+ return target ? `/docs/${target.output}${anchor ? `#${anchor}` : ''}` : null;
+}
+
+export function resolveImage(href, page, images) {
+ if (!/^images\/[a-z0-9-]+\.png$/.test(href || '') || page.repo !== 'Enelix-EMS' || !/^docs\/public\/[a-z0-9-]+\.md$/.test(page.source)) return null;
+ return images.find(image => image.repo === page.repo && image.source === `docs/public/${href}`) || null;
+}
+
+export function renderMarkdown(page, pages, images = []) {
+ const toc = [];
+ const ids = new Map();
+ const marked = new Marked({ gfm: true, renderer: {
+ html() { return ''; },
+ image({ href, text, title }) {
+ const image = resolveImage(href, page, images);
+ if (!image) return `${escape(text)}`;
+ return `${this.constructor.prototype.table.call(this, token)}
`; }
+ } });
+ const html = sanitizeHtml(marked.parse(page.markdown), {
+ allowedTags: [...sanitizeHtml.defaults.allowedTags, 'h1', 'h2', 'span', 'img'],
+ allowedAttributes: { a: ['href', 'class', 'aria-label'], '*': ['id'], span: ['class', 'title'], img:['src','alt','width','height','loading','decoding'], div: ['class', 'tabindex', 'role', 'aria-label'], th: ['align'], td: ['align'], code: ['class'] },
+ allowedSchemes: ['https'], allowProtocolRelative: false
+ });
+ return { html, toc };
+}
+
+const pricing = `Aktueller Katalog
+ +Aktuelle Preise werden geladen.
+${group}
- ${entries}
+
+${isPrices ? html.replace(/(]*>)/, `${pricing}$1`) : html}
+
+${isPrices ? `` : ''}`;
+}
diff --git a/tools/public-docs/sync.mjs b/tools/public-docs/sync.mjs
new file mode 100644
index 0000000..62ba413
--- /dev/null
+++ b/tools/public-docs/sync.mjs
@@ -0,0 +1,142 @@
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { repositories, guides } from './config.mjs';
+import { renderPage } from './render.mjs';
+import { screenshotSources, screenshotInfo } from './images.mjs';
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+const publicDir = path.resolve(process.env.DOCS_PUBLIC_DIR || '/home/agent/services/license/public');
+const stateDir = path.resolve(process.env.DOCS_STATE_DIR || path.join(root, 'state'));
+const branch = process.env.DOCS_BRANCH || 'develop';
+if (!['develop', 'beta', 'main'].includes(branch)) throw new Error('Unsupported documentation branch');
+const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding:'utf8', timeout:60000, maxBuffer:4e6, stdio:['ignore', 'pipe', 'pipe'], env:{ ...process.env, GIT_TERMINAL_PROMPT:'0' } });
+const hash = value => createHash('sha256').update(value).digest('hex').slice(0, 16);
+const statusPath = path.join(publicDir, 'docs-status.json');
+await fs.mkdir(stateDir, { recursive:true, mode:0o700 });
+await fs.mkdir(publicDir, { recursive:true, mode:0o755 });
+let lock;
+try { lock = await fs.open(path.join(stateDir, 'sync.lock'), 'wx', 0o600); }
+catch (error) { if (error.code === 'EEXIST') { console.error('Documentation sync already running; inspect stale lock after interruption.'); process.exit(1); } throw error; }
+
+async function atomicWrite(target, content) {
+ const temporary = `${target}.${randomUUID()}.tmp`;
+ await fs.writeFile(temporary, content, { mode:0o644 });
+ await fs.rename(temporary, target);
+}
+
+try {
+ const pages = [];
+ const commits = {};
+ const mirrors = {};
+ for (const repo of repositories) {
+ const mirror = path.join(stateDir, `${repo.id}.git`);
+ await fs.mkdir(mirror, { recursive:true, mode:0o700 });
+ if (!existsSync(path.join(mirror, 'HEAD'))) {
+ git(mirror, 'init', '--bare');
+ git(mirror, 'remote', 'add', 'origin', repo.url);
+ }
+ // A separate read-only mirror never changes a developer checkout.
+ if (git(mirror, 'remote', 'get-url', 'origin').trim() !== repo.url) throw new Error('Unexpected source remote');
+ git(mirror, 'fetch', '--quiet', '--depth=1', 'origin', `refs/heads/${branch}`);
+ const commit = git(mirror, 'rev-parse', 'FETCH_HEAD').trim();
+ if (!/^[a-f0-9]{40}$/.test(commit)) throw new Error('Invalid source revision');
+ commits[repo.name] = commit;
+ mirrors[repo.name] = mirror;
+ for (const [source, title, output] of repo.pages) {
+ const entry = git(mirror, 'ls-tree', commit, '--', source);
+ if (!/^100644 blob |^100755 blob /.test(entry)) throw new Error(`Missing regular documentation source: ${repo.name}/${source}`);
+ const markdown = git(mirror, 'show', `${commit}:${source}`);
+ if (markdown.length > 400000 || /-----BEGIN [A-Z ]*PRIVATE KEY-----|\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}|\bENX-(?:[A-Z0-9]{4}-){3}[A-Z0-9]{4}\b/.test(markdown.replaceAll('ENX-XXXX-XXXX-XXXX-XXXX', ''))) throw new Error('Public documentation safety check failed');
+ pages.push({ repo:repo.name, source, title, output, markdown, commit, group:repo.id === 'ems' ? 'Enelix EMS' : 'Enelix Utils' });
+ }
+ }
+ let drafts = false;
+ for (const [name, title] of guides) {
+ const source = `docs/public/${name}.md`;
+ let markdown, commit = commits['Enelix-EMS'];
+ try { markdown = git(mirrors['Enelix-EMS'], 'show', `${commit}:${source}`); }
+ catch {
+ // Temporary bootstrap only until the newly written guides are approved for Git.
+ if (process.env.DOCS_ALLOW_DRAFTS !== 'true') throw new Error(`Guide not published in Git: ${source}`);
+ markdown = await fs.readFile(path.join(root, 'guides', `${name}.md`), 'utf8');
+ commit = null; drafts = true;
+ }
+ pages.unshift({ repo:'Enelix-EMS', source, title, output:`${name}.html`, markdown, commit, group:'Anleitungen' });
+ }
+ pages.sort((a, b) => a.group === 'Anleitungen' && b.group === 'Anleitungen' ? guides.findIndex(([key]) => `${key}.html` === a.output) - guides.findIndex(([key]) => `${key}.html` === b.output) : 0);
+ const images = [], imageData = new Map();
+ for (const source of screenshotSources) {
+ let commit = commits['Enelix-EMS'], data;
+ const mirror = mirrors['Enelix-EMS'];
+ const entry = git(mirror, 'ls-tree', commit, '--', source);
+ if (entry) {
+ if (!/^100644 blob |^100755 blob /.test(entry)) throw new Error('Screenshot must be a regular file');
+ data = execFileSync('git', ['show', `${commit}:${source}`], { cwd:mirror, timeout:60000, maxBuffer:4_000_000, stdio:['ignore','pipe','pipe'] });
+ } else {
+ if (process.env.DOCS_ALLOW_DRAFTS !== 'true') throw new Error('Screenshot not published in Git');
+ const local = path.join(root, 'guides/images', path.basename(source));
+ if (!(await fs.lstat(local)).isFile()) throw new Error('Draft screenshot must be a regular file');
+ data = await fs.readFile(local);
+ commit = null; drafts = true;
+ }
+ const image = { ...screenshotInfo(source, data), commit };
+ images.push(image); imageData.set(image.output, data);
+ }
+ const assets = {};
+ for (const name of ['site.css', 'site.js', 'prices.js']) assets[name] = await fs.readFile(path.join(root, 'assets', name), 'utf8');
+ const engine = await fs.readFile(path.join(root, 'render.mjs'), 'utf8') + await fs.readFile(path.join(root, 'images.mjs'), 'utf8');
+ const version = hash(JSON.stringify({ pages, assets, images, engine, branch }));
+ const checkedAt = new Date().toISOString();
+ const manifest = { branch, checkedAt, commits, drafts, version, images, pages:pages.map(({ repo, source, output, commit }) => ({ repo, source, output, commit })) };
+ const releases = path.join(publicDir, '.documentation-releases');
+ const release = path.join(releases, version);
+ const current = path.join(publicDir, 'docs');
+ await fs.mkdir(releases, { recursive:true, mode:0o755 });
+ if (!existsSync(release)) {
+ const staging = path.join(releases, `.staging-${randomUUID()}`);
+ await fs.mkdir(staging, { mode:0o755 });
+ try {
+ for (const page of pages) {
+ const target = path.join(staging, page.output);
+ await fs.mkdir(path.dirname(target), { recursive:true, mode:0o755 });
+ await fs.writeFile(target, renderPage(page, pages, manifest, version), { mode:0o644 });
+ }
+ for (const [name, content] of Object.entries(assets)) {
+ const extension = path.extname(name), stem = path.basename(name, extension);
+ await fs.writeFile(path.join(staging, `${stem}-${version}${extension}`), content, { mode:0o644 });
+ }
+ await fs.mkdir(path.join(staging, 'images'), { mode:0o755 });
+ for (const [output, data] of imageData) await fs.writeFile(path.join(staging, output), data, { mode:0o644 });
+ // Cached HTML may still reference the previous release's fingerprinted assets.
+ if (existsSync(current)) for (const name of await fs.readdir(current)) {
+ if (/^(site|prices)-[a-f0-9]{16}\.(css|js)$/.test(name)) await fs.copyFile(path.join(current, name), path.join(staging, name));
+ }
+ const previousImages = path.join(current, 'images');
+ if (existsSync(previousImages)) for (const name of await fs.readdir(previousImages)) {
+ if (/^symcon-[a-z-]+-[a-f0-9]{16}\.png$/.test(name)) await fs.copyFile(path.join(previousImages, name), path.join(staging, 'images', name));
+ }
+ await fs.writeFile(path.join(staging, 'manifest.json'), JSON.stringify(manifest), { mode:0o644 });
+ await fs.rename(staging, release);
+ } catch (error) { await fs.rm(staging, { recursive:true, force:true }); throw error; }
+ }
+ const existing = await fs.lstat(current).catch(error => { if (error.code !== 'ENOENT') throw error; return null; });
+ if (existing && !existing.isSymbolicLink()) throw new Error('Refusing to replace an existing documentation directory');
+ const temporaryLink = path.join(publicDir, `.docs-${randomUUID()}`);
+ await fs.symlink(path.relative(publicDir, release), temporaryLink);
+ await fs.rename(temporaryLink, current);
+ await atomicWrite(statusPath, JSON.stringify({ ok:true, lastAttempt:checkedAt, lastSuccess:checkedAt, branch, commits, drafts, version }));
+ console.log(JSON.stringify({ ok:true, branch, commits, drafts, version, pages:pages.length }));
+} catch {
+ let previous = {};
+ try { previous = JSON.parse(await fs.readFile(statusPath, 'utf8')); } catch { /* No successful publication yet. */ }
+ await atomicWrite(statusPath, JSON.stringify({ ...previous, ok:false, lastAttempt:new Date().toISOString() }));
+ console.error('Documentation sync failed; last successful publication retained. Check source availability, guide publication and permissions.');
+ process.exitCode = 1;
+} finally {
+ await lock.close();
+ await fs.unlink(path.join(stateDir, 'sync.lock'));
+}
diff --git a/tools/public-docs/tests/render.test.mjs b/tools/public-docs/tests/render.test.mjs
new file mode 100644
index 0000000..f03690d
--- /dev/null
+++ b/tools/public-docs/tests/render.test.mjs
@@ -0,0 +1,92 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { renderMarkdown, renderPage, renderNavigation, resolveLink, resolveImage } from '../render.mjs';
+import { screenshotInfo, screenshotSources } from '../images.mjs';
+import { validateCatalog, grossAmount, termLabel } from '../assets/prices.js';
+import { repositories } from '../config.mjs';
+
+const page = { repo:'Enelix-EMS', source:'docs/public/manager.md', output:'manager.html', title:'Manager', group:'Anleitungen', markdown:'# Manager\n\n## Einrichten\n\nInhalt.', commit:'a'.repeat(40) };
+const targets = [page, { repo:'Enelix-EMS', source:'docs/module/Manager/README.md', output:'ems/Manager.html' }, { repo:'Enelix-Utils', source:'docs/module/Energiediagramm/README.md', output:'utils/Energiediagramm.html' }];
+test('relative README links remain public', () => assert.equal(resolveLink('../module/Manager/README.md#variablen', page, targets), '/docs/ems/Manager.html#variablen'));
+test('cross-repository links remain public', () => assert.equal(resolveLink('../../../Enelix-Utils/docs/module/Energiediagramm/README.md', page, targets), '/docs/utils/Energiediagramm.html'));
+test('private and unsafe targets are not published', () => {
+ for (const href of ['../NETPLAN_V4_AGENT_HANDOFF.md', '../Offene-Punkte.md', 'javascript:alert(1)', '//evil.example', 'data:text/html,hello', 'https://user:pass@example.com', '/srv/agent/.netrc']) assert.equal(resolveLink(href, page, targets), null);
+});
+test('markdown escapes scripts, event handlers and injected attributes', () => {
+ const { html } = renderMarkdown({ ...page, markdown:'# Test\n\n\n\n
{
+ for (const href of ['https://example.com/pixel.png','data:image/png;base64,aaaa','images/private.png','../public/images/symcon-manager.png','images/../images/symcon-manager.png','images/%2e%2e/symcon-manager.png','/docs/images/symcon-manager.png','images\\symcon-manager.png']) {
+ assert.equal(resolveImage(href, page, [screenshot]), null);
+ }
+ assert.equal(resolveImage('images/symcon-manager.png', { ...page, repo:'Enelix-Utils' }, [screenshot]), null);
+ const { html } = renderMarkdown({ ...page, markdown:'
\n\n' }, targets, [screenshot]);
+ assert.doesNotMatch(html, /