@alfacapital-tech/c4builder 0.7.0 → 0.9.0-rc.1

package/dist/cli/commands/site.comments.js

@@ -0,0 +1,378 @@
+export const COMMENTS_PATH = '/__c4builder/comments';
+const CSS = [
+    '.c4b-cbtn{position:absolute;z-index:1001;padding:4px 10px;border:1px solid #42b983;border-radius:4px;background:#fff;color:#2c3e50;font:13px/1.4 sans-serif;cursor:pointer;box-shadow:0 2px 8px rgba(0,0,0,.15)}',
+    '.c4b-cpop{position:absolute;z-index:1002;width:380px;max-width:calc(100vw - 32px);padding:10px;border:1px solid #ddd;border-radius:6px;background:#fff;color:#2c3e50;font:13px/1.4 sans-serif;box-shadow:0 4px 16px rgba(0,0,0,.2)}',
+    '.c4b-cpop blockquote{margin:0 0 8px;padding:4px 8px;border-left:3px solid #42b983;background:#f8f8f8;max-height:80px;overflow:auto;font-size:12px;white-space:pre-wrap}',
+    '.c4b-cpop textarea{width:100%;box-sizing:border-box;min-height:70px;padding:6px;border:1px solid #ccc;border-radius:4px;font:13px/1.4 sans-serif;resize:vertical}',
+    '.c4b-cpop .c4b-row{display:flex;justify-content:space-between;align-items:center;gap:8px;margin-top:8px}',
+    '.c4b-cpop small{color:#888;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}',
+    '.c4b-cpop button{padding:4px 12px;border:1px solid #ccc;border-radius:4px;background:#fff;color:#2c3e50;cursor:pointer;font:13px sans-serif}',
+    '.c4b-cpop button.c4b-primary{border-color:#42b983;background:#42b983;color:#fff}',
+    '.c4b-cpop button:disabled{opacity:.6;cursor:default}',
+    '.c4b-ctoast{position:fixed;left:16px;bottom:16px;z-index:1003;max-width:420px;padding:8px 14px;border-radius:6px;background:#2c3e50;color:#fff;font:13px/1.4 sans-serif;box-shadow:0 2px 8px rgba(0,0,0,.3)}',
+    '.c4b-ctoast.c4b-err{background:#c0392b}',
+    'mark.c4b-hl{background:#fff3a0;color:inherit;padding:0;border-radius:2px}',
+    'sup.c4b-ref{font-size:.7em;line-height:0;margin-left:1px;user-select:none}',
+    'sup.c4b-ref a{color:#b58900;text-decoration:none;font-weight:700;cursor:pointer}',
+    '.c4b-qrow{transition:background .3s}',
+    '.c4b-qflash{background:#fff3a0!important}',
+    '.c4b-del{margin-left:6px;padding:0 5px;border:1px solid transparent;border-radius:3px;background:none;color:#999;font:12px/1.4 sans-serif;cursor:pointer;opacity:0;vertical-align:middle}',
+    '.c4b-qrow:hover .c4b-del{opacity:1}',
+    '.c4b-del:hover{color:#fff;background:#c0392b;border-color:#c0392b}',
+    '.c4b-del:disabled{opacity:.5;cursor:default}'
+].join('');
+const jsString = (s) => JSON.stringify(s)
+    .replace(/</g, '\\u003c')
+    .replace(/[\u0080-￿]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+export const commentsSnippet = (heading) => `
+<script>
+(function () {
+    if (window.__c4builderComments) return;
+    window.__c4builderComments = true;
+    var ENDPOINT = '${COMMENTS_PATH}';
+    var HEADING = ${jsString(heading)};
+    var TOAST_KEY = '__c4builderCommentToast';
+    var BLOCKS = 'p,li,td,th,h1,h2,h3,h4,h5,h6,pre,blockquote,dd,dt,div,section,details,summary';
+    var style = document.createElement('style');
+    style.textContent = ${jsString(CSS)};
+    document.head.appendChild(style);
+
+    var collapse = function (s) { return String(s).replace(/\\s+/g, ' ').trim(); };
+    var same = function (a, b) { return collapse(a).toLowerCase() === collapse(b).toLowerCase(); };
+
+    var toastEl = null, toastTimer = 0;
+    var toast = function (msg, err) {
+        if (toastEl) toastEl.remove();
+        toastEl = document.createElement('div');
+        toastEl.className = 'c4b-ctoast' + (err ? ' c4b-err' : '');
+        toastEl.textContent = msg;
+        document.body.appendChild(toastEl);
+        clearTimeout(toastTimer);
+        toastTimer = setTimeout(function () { if (toastEl) { toastEl.remove(); toastEl = null; } }, err ? 8000 : 5000);
+    };
+    try {
+        var saved = sessionStorage.getItem(TOAST_KEY);
+        if (saved) { sessionStorage.removeItem(TOAST_KEY); toast(saved); }
+    } catch (e) {}
+
+    var content = function () { return document.querySelector('.markdown-section'); };
+    var headingLevel = function (el) { return /^H[1-6]$/.test(el.tagName) ? Number(el.tagName[1]) : 0; };
+    var sectionOf = function (h) {
+        var out = [], lvl = headingLevel(h);
+        for (var el = h.nextElementSibling; el; el = el.nextElementSibling) {
+            var l = headingLevel(el);
+            if (l && l <= lvl) break;
+            out.push(el);
+        }
+        return out;
+    };
+    var findHeading = function (root, text) {
+        var hs = root.querySelectorAll('h1,h2,h3,h4,h5,h6');
+        for (var i = 0; i < hs.length; i++) if (same(hs[i].textContent, text)) return hs[i];
+        return null;
+    };
+
+    var SEP = ' \\u2014 \\u00ab';
+    var parseQuestions = function (text) {
+        var s = collapse(text), out = [];
+        for (var at = s.indexOf(SEP); at >= 0; at = s.indexOf(SEP, at + 1)) {
+            var m = s.slice(at + SEP.length).match(/^([\\s\\S]*)\\u00bb(?: \\(\\u00a7 (.*)\\))?$/);
+            var quote = m ? m[1].replace(/\\u2026$/, '').trim() : '';
+            if (quote) out.push({ comment: s.slice(0, at), quote: quote, section: m[2] || '' });
+        }
+        return out;
+    };
+    var textIndex = function (roots, skip) {
+        var chars = [], map = [], lastBlock = null, prevSpace = true;
+        var walk = function (node) {
+            if (node.nodeType === 1) {
+                if (skip.indexOf(node) >= 0 || (node.tagName === 'SUP' && node.classList.contains('c4b-ref'))) return;
+                if (/^(SCRIPT|STYLE)$/.test(node.tagName)) return;
+                for (var c = node.firstChild; c; c = c.nextSibling) walk(c);
+                return;
+            }
+            if (node.nodeType !== 3) return;
+            var block = node.parentNode.closest ? node.parentNode.closest(BLOCKS) : null;
+            if (block !== lastBlock && !prevSpace && chars.length) { chars.push(' '); map.push(null); prevSpace = true; }
+            lastBlock = block;
+            var s = node.nodeValue;
+            for (var i = 0; i < s.length; i++) {
+                var ch = s[i];
+                if (/\\s/.test(ch)) {
+                    if (prevSpace) continue;
+                    chars.push(' '); map.push(null); prevSpace = true;
+                } else {
+                    chars.push(ch); map.push({ node: node, offset: i }); prevSpace = false;
+                }
+            }
+        };
+        for (var r = 0; r < roots.length; r++) walk(roots[r]);
+        return { text: chars.join(''), map: map };
+    };
+    var wrapRange = function (idx, from, to, title) {
+        var first = null, last = null, i;
+        for (i = from; i < to && !first; i++) first = idx.map[i];
+        for (i = to - 1; i >= from && !last; i--) last = idx.map[i];
+        if (!first || !last) return null;
+        var nodes = [], cur = first.node;
+        var walker = document.createTreeWalker(content(), NodeFilter.SHOW_TEXT);
+        walker.currentNode = cur;
+        while (cur) { nodes.push(cur); if (cur === last.node) break; cur = walker.nextNode(); }
+        var marks = [];
+        for (i = nodes.length - 1; i >= 0; i--) {
+            var n = nodes[i];
+            var start = n === first.node ? first.offset : 0;
+            var end = n === last.node ? last.offset + 1 : n.nodeValue.length;
+            if (end < n.nodeValue.length) n.splitText(end);
+            var mid = start > 0 ? n.splitText(start) : n;
+            if (!mid.nodeValue.trim()) continue;
+            var mark = document.createElement('mark');
+            mark.className = 'c4b-hl';
+            mark.title = title;
+            mid.parentNode.insertBefore(mark, mid);
+            mark.appendChild(mid);
+            marks.unshift(mark);
+        }
+        return marks;
+    };
+    var flash = function (row) {
+        row.scrollIntoView({ block: 'center', behavior: 'smooth' });
+        row.classList.add('c4b-qflash');
+        setTimeout(function () { row.classList.remove('c4b-qflash'); }, 1500);
+    };
+    var highlight = function () {
+        var root = content();
+        if (!root || root.querySelector('mark.c4b-hl, .c4b-del')) return;
+        var h = findHeading(root, HEADING);
+        if (!h) return;
+        var section = sectionOf(h);
+        var items = [];
+        section.forEach(function (el) {
+            if (el.tagName === 'TABLE') {
+                var rows = el.querySelectorAll('tbody tr');
+                for (var i = 0; i < rows.length; i++) {
+                    var cells = rows[i].querySelectorAll('td');
+                    if (!cells.length) continue;
+                    var numeric = /^\\d+$/.test(collapse(cells[0].textContent));
+                    var textCell = numeric && cells.length > 1 ? cells[1] : cells[0];
+                    if (!collapse(textCell.textContent)) continue;
+                    items.push({ row: rows[i], cell: textCell, number: numeric ? collapse(cells[0].textContent) : String(items.length + 1), text: textCell.textContent });
+                }
+            } else if (/^[UO]L$/.test(el.tagName)) {
+                var lis = el.children;
+                for (var j = 0; j < lis.length; j++) items.push({ row: lis[j], cell: lis[j], number: String(items.length + 1), text: lis[j].textContent });
+            }
+        });
+        var addDelete = function (item) {
+            var del = document.createElement('button');
+            del.type = 'button';
+            del.className = 'c4b-del';
+            del.textContent = '\\u00d7';
+            del.title = 'Remove this question';
+            del.addEventListener('click', function (e) {
+                e.preventDefault();
+                e.stopPropagation();
+                del.disabled = true;
+                send({ page: pageFile(), number: Number(item.number) || null, text: collapse(item.text) }, 'DELETE').then(function (r) {
+                    var msg = 'Removed from ' + r.file;
+                    try { sessionStorage.setItem(TOAST_KEY, msg); } catch (e) {}
+                    toast(msg);
+                }, function (err) {
+                    del.disabled = false;
+                    toast('Remove failed: ' + (err && err.message ? err.message : err), true);
+                });
+            });
+            item.cell.appendChild(del);
+        };
+        var skip = [h].concat(section);
+        var tryIn = function (idx, q) {
+            var at = idx.text.indexOf(q.quote);
+            var marks = at < 0 ? null : wrapRange(idx, at, at + q.quote.length, q.comment);
+            return marks && marks.length ? marks : null;
+        };
+        items.forEach(function (item) {
+            item.row.classList.add('c4b-qrow');
+            item.row.id = item.row.id || 'c4b-q-' + item.number;
+            addDelete(item);
+            // Index is rebuilt per try: wrapping splits text nodes and stales the previous map.
+            var q = null, marks = null;
+            parseQuestions(item.text).some(function (c) {
+                if (c.section) {
+                    var sh = findHeading(root, c.section);
+                    if (sh && skip.indexOf(sh) < 0) marks = tryIn(textIndex(sectionOf(sh), skip), c);
+                }
+                marks = marks || tryIn(textIndex([root], skip), c);
+                q = marks ? c : null;
+                return !!marks;
+            });
+            if (!marks) return;
+            var sup = document.createElement('sup');
+            sup.className = 'c4b-ref';
+            var a = document.createElement('a');
+            a.setAttribute('role', 'button');
+            a.tabIndex = 0;
+            a.textContent = item.number;
+            a.title = q.comment;
+            a.addEventListener('click', function (e) { e.preventDefault(); flash(item.row); });
+            sup.appendChild(a);
+            var lastMark = marks[marks.length - 1];
+            lastMark.parentNode.insertBefore(sup, lastMark.nextSibling);
+        });
+    };
+    var schedule = function () { setTimeout(function () { try { highlight(); } catch (e) {} }, 50); };
+    var docsifyVm = null;
+    if (window.$docsify) {
+        window.$docsify.plugins = [].concat(window.$docsify.plugins || [], function (hook, vm) {
+            docsifyVm = vm || null;
+            hook.doneEach(schedule);
+        });
+    }
+    window.addEventListener('hashchange', function () { setTimeout(schedule, 300); });
+    window.addEventListener('load', function () { setTimeout(schedule, 500); });
+
+    var btn = document.createElement('button');
+    btn.type = 'button';
+    btn.className = 'c4b-cbtn';
+    btn.textContent = 'Comment';
+    btn.hidden = true;
+    document.body.appendChild(btn);
+    var pop = null;
+
+    var selection = function () {
+        var sel = window.getSelection();
+        if (!sel || sel.rangeCount === 0 || sel.isCollapsed) return null;
+        var range = sel.getRangeAt(0);
+        var root = content();
+        if (!root) return null;
+        var node = range.commonAncestorContainer;
+        var el = node.nodeType === 1 ? node : node.parentNode;
+        if (!root.contains(el) || (pop && pop.contains(el))) return null;
+        var text = sel.toString().trim();
+        return text ? { range: range, text: text } : null;
+    };
+    var headingBefore = function (range) {
+        var root = content();
+        if (!root) return '';
+        var hs = root.querySelectorAll('h1,h2,h3,h4,h5,h6');
+        var found = '';
+        for (var i = 0; i < hs.length; i++) {
+            if (hs[i].compareDocumentPosition(range.startContainer) & Node.DOCUMENT_POSITION_FOLLOWING)
+                found = hs[i].textContent.trim();
+            else break;
+        }
+        return found;
+    };
+    var anchorRect = function (range) {
+        var rects = range.getClientRects();
+        return rects.length ? rects[rects.length - 1] : range.getBoundingClientRect();
+    };
+    var place = function (el, rect) {
+        el.style.top = (rect.bottom + window.scrollY + 6) + 'px';
+        el.style.left = Math.max(8, Math.min(rect.left + window.scrollX, window.innerWidth - el.offsetWidth - 8)) + 'px';
+    };
+    var update = function () {
+        if (pop) return;
+        var s = selection();
+        if (!s) { btn.hidden = true; return; }
+        btn.hidden = false;
+        place(btn, anchorRect(s.range));
+    };
+    document.addEventListener('selectionchange', function () { setTimeout(update, 0); });
+
+    var pageFile = function () {
+        var file = docsifyVm && docsifyVm.route && docsifyVm.route.file;
+        if (typeof file === 'string' && file) {
+            try { file = decodeURIComponent(file); } catch (e) {}
+            file = file.replace(/^https?:\\/\\/[^/]+/, '').replace(/^\\/+/, '');
+            if (file) return file;
+        }
+        var p = location.hash.replace(/^#/, '').split('?')[0];
+        try { p = decodeURIComponent(p); } catch (e) {}
+        p = p.replace(/^\\/+/, '').replace(/\\/+$/, '');
+        if (!p) return (window.$docsify && window.$docsify.homepage) || 'README.md';
+        return /\\.md$/i.test(p) ? p : p + '.md';
+    };
+    var send = function (body, method) {
+        return fetch(ENDPOINT, {
+            method: method || 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body)
+        }).then(function (res) {
+            return res.json().catch(function () { return {}; }).then(function (data) {
+                if (!res.ok) throw new Error(data.error || ('HTTP ' + res.status));
+                return data;
+            });
+        });
+    };
+
+    var close = function () {
+        if (pop) { pop.remove(); pop = null; }
+        btn.hidden = true;
+    };
+    var open = function (data, rect) {
+        close();
+        pop = document.createElement('div');
+        pop.className = 'c4b-cpop';
+        var quote = document.createElement('blockquote');
+        quote.textContent = data.quote;
+        var ta = document.createElement('textarea');
+        ta.placeholder = 'Your question or comment (Ctrl+Enter to add, Esc to cancel)';
+        var row = document.createElement('div');
+        row.className = 'c4b-row';
+        var hint = document.createElement('small');
+        hint.textContent = 'To: ' + HEADING + (data.section ? ' / ' + data.section : '');
+        hint.title = hint.textContent;
+        var actions = document.createElement('span');
+        var cancel = document.createElement('button');
+        cancel.type = 'button';
+        cancel.textContent = 'Cancel';
+        var ok = document.createElement('button');
+        ok.type = 'button';
+        ok.className = 'c4b-primary';
+        ok.textContent = 'Add';
+        actions.appendChild(cancel);
+        actions.appendChild(document.createTextNode(' '));
+        actions.appendChild(ok);
+        row.appendChild(hint);
+        row.appendChild(actions);
+        pop.appendChild(quote);
+        pop.appendChild(ta);
+        pop.appendChild(row);
+        document.body.appendChild(pop);
+        place(pop, rect);
+        ta.focus();
+        var submit = function () {
+            var comment = ta.value.trim();
+            if (!comment) { ta.focus(); return; }
+            ok.disabled = true;
+            cancel.disabled = true;
+            send({ page: pageFile(), quote: data.quote, section: data.section, comment: comment }).then(function (r) {
+                var msg = 'Added to ' + r.file + (r.number ? ' as #' + r.number : '');
+                try { sessionStorage.setItem(TOAST_KEY, msg); } catch (e) {}
+                close();
+                toast(msg);
+            }, function (err) {
+                ok.disabled = false;
+                cancel.disabled = false;
+                toast('Comment failed: ' + (err && err.message ? err.message : err), true);
+            });
+        };
+        ok.addEventListener('click', submit);
+        cancel.addEventListener('click', close);
+        ta.addEventListener('keydown', function (e) {
+            if (e.key === 'Escape') { e.preventDefault(); close(); }
+            else if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) { e.preventDefault(); submit(); }
+        });
+    };
+
+    btn.addEventListener('mousedown', function (e) { e.preventDefault(); });
+    btn.addEventListener('click', function () {
+        var s = selection();
+        if (s) open({ quote: s.text, section: headingBefore(s.range) }, anchorRect(s.range));
+    });
+    document.addEventListener('mousedown', function (e) {
+        if (pop && !pop.contains(e.target) && e.target !== btn) close();
+    });
+    window.addEventListener('hashchange', close);
+})();
+</script>`;

package/dist/cli/commands/site.js

@@ -3,8 +3,11 @@ import path from 'node:path';
 import fs from 'node:fs';
 import express from 'express';
 import open from 'open';
+import { deleteQuestion, formatQuestion, pickSource, writeQuestion } from "../../core/questions.js";
 import { packageJson as pkg } from "../../util/paths.js";
 import { pendingUpdate } from "../update.js";
+import { COMMENTS_PATH, commentsSnippet } from "./site.comments.js";
+const COMMENT_MAX = 2000;
 const LIVERELOAD_PATH = '/__livereload';
 // Восстановление скролла после reload: docsify рендерит контент асинхронно после fetch md,
 // высота страницы доступна не сразу — поллим до достижения нужной y или таймаута.
@@ -76,7 +79,9 @@ c4builder ${next} is available (current ${pkg.version}). Run: <code>c4builder up
     };
 })();
 </script>`;
-export default (currentConfiguration, program, reloadEmitter) => {
+export default (currentConfiguration, program, reloadEmitter, 
+// Карта «страница → исходники» текущей сборки — геттером, чтобы видеть результат ребилдов watch.
+pages = () => new Map()) => {
     if (!currentConfiguration.DIST_FOLDER)
         return console.log(chalk.red('No destination folder configured'));
     const app = express();
@@ -112,11 +117,103 @@ export default (currentConfiguration, program, reloadEmitter) => {
         // запущенной этим же `site -w`, виден со следующей перезагрузки без рестарта сервера.
         const inject = (html) => {
             const next = pendingUpdate();
-            const snippet = next ? LIVERELOAD_SNIPPET + updateBanner(next) : LIVERELOAD_SNIPPET;
+            const snippet = LIVERELOAD_SNIPPET +
+                commentsSnippet(currentConfiguration.QUESTIONS_HEADING) +
+                (next ? updateBanner(next) : '');
             if (html.includes('</body>'))
                 return html.replace('</body>', `${snippet}</body>`);
             return html + snippet;
         };
+        // Комментарий к выделенному тексту → раздел вопросов исходного файла страницы
+        // (change site-comments, design D3). Сервер слушает только 127.0.0.1, но страница
+        // любого сайта в браузере может слать POST на localhost — требуем Origin самого сайта.
+        const str = (v) => (typeof v === 'string' ? v : '');
+        const heading = currentConfiguration.QUESTIONS_HEADING;
+        // Общая часть POST/DELETE: проверка Origin и исходный файл страницы из тела запроса.
+        // Ошибка уже отправлена клиенту, когда возвращается undefined.
+        const resolveTarget = (req, res) => {
+            const origin = req.get('origin');
+            const host = req.get('host');
+            // Host — только локальный: при DNS rebinding чужой домен резолвится в 127.0.0.1 и
+            // присылает согласованные Host и Origin, сверка Origin с одним Host это пропускает.
+            const local = [`127.0.0.1:${req.socket.localPort}`, `localhost:${req.socket.localPort}`];
+            if (!origin || !host || !local.includes(host) || origin !== `http://${host}`) {
+                res.status(403).json({ error: 'comments are accepted only from the site itself' });
+                return undefined;
+            }
+            const body = (req.body ?? {});
+            const page = path.posix.normalize(str(body.page).replace(/^\/+/, ''));
+            const sources = page.startsWith('..') ? undefined : pages().get(page);
+            if (!sources) {
+                res.status(404).json({ error: `unknown page: ${page}` });
+                return undefined;
+            }
+            const cwd = process.cwd();
+            const file = pickSource(sources.filter((s) => s.startsWith(cwd + path.sep)), heading);
+            if (!file) {
+                res.status(404).json({ error: 'this page has no source file to write to' });
+                return undefined;
+            }
+            return { file, rel: path.relative(cwd, file).split(path.sep).join('/'), body };
+        };
+        app.post(COMMENTS_PATH, express.json({ limit: '64kb' }), (req, res) => {
+            const target = resolveTarget(req, res);
+            if (!target)
+                return;
+            const { file, rel, body } = target;
+            const comment = str(body.comment).trim();
+            const quote = str(body.quote);
+            const section = str(body.section);
+            if (!comment) {
+                res.status(400).json({ error: 'comment is empty' });
+                return;
+            }
+            if (comment.length > COMMENT_MAX || quote.length > COMMENT_MAX) {
+                res.status(400).json({
+                    error: `comment and quote must be at most ${COMMENT_MAX} characters`
+                });
+                return;
+            }
+            try {
+                const number = writeQuestion(file, heading, formatQuestion({ comment, quote, section }));
+                console.log(chalk.gray(`comment added to ${rel}${number ? ` as #${number}` : ''}`));
+                res.json({ file: rel, number });
+            }
+            catch (e) {
+                res.status(500).json({ error: `could not write the comment: ${e.message}` });
+            }
+        });
+        // Удаление вопроса: по номеру (числовая таблица) и тексту, как он виден на странице.
+        app.delete(COMMENTS_PATH, express.json({ limit: '64kb' }), (req, res) => {
+            const target = resolveTarget(req, res);
+            if (!target)
+                return;
+            const { file, rel, body } = target;
+            const text = str(body.text).trim();
+            if (!text) {
+                res.status(400).json({ error: 'question text is empty' });
+                return;
+            }
+            const number = typeof body.number === 'number' ? body.number : Number(str(body.number)) || null;
+            try {
+                const result = deleteQuestion(file, heading, { number, text });
+                if ('error' in result) {
+                    const messages = {
+                        'not-found': `question not found in ${rel} — the page may be stale, reload it`,
+                        ambiguous: `several identical questions in ${rel} — remove it by hand`
+                    };
+                    res.status(result.error === 'not-found' ? 404 : 409).json({
+                        error: messages[result.error]
+                    });
+                    return;
+                }
+                console.log(chalk.gray(`comment removed from ${rel}`));
+                res.json({ file: rel });
+            }
+            catch (e) {
+                res.status(500).json({ error: `could not remove the comment: ${e.message}` });
+            }
+        });
         app.use((req, res, next) => {
             if (req.method !== 'GET')
                 return next();

package/dist/cli/dispatch.js

@@ -17,7 +17,7 @@ import fs from 'node:fs';
 import watch from 'node-watch';
 import { EventEmitter } from 'node:events';
 import { clearConsole } from "../util/utils.js";
-import { acquireBuildLock, BuildLockHeldError } from "../util/lock.js";
+import { acquireBuildLock, BuildLockHeldError, waitBuildLock } from "../util/lock.js";
 // teardownD2 живёт здесь, а не в finally build(): в watch-режиме D2-воркер должен
 // переживать ребилды (его пересоздание — секунды), гасим его только когда сборок
 // больше не будет (одиночный запуск).
@@ -102,6 +102,7 @@ function getOptions(c) {
         EXECUTE_SCRIPT: c.executeScript,
         EXCLUDE_OTHER_FILES: c.excludeOtherFiles,
         USE_SYSTEM_FONTS: c.useSystemFonts,
+        QUESTIONS_HEADING: c.questionsHeading,
         PLUGINS: c.plugins
     };
 }
@@ -256,6 +257,9 @@ export default async () => {
         });
         const reloadEmitter = new EventEmitter();
         reloadEmitter.setMaxListeners(0);
+        // Карта «страница сайта → исходники» последней удачной сборки: dev-сервер читает её
+        // геттером, поэтому после ребилда в watch видит свежую без рестарта.
+        let pages = new Map();
         if (opts.watch) {
             // node-watch: CJS-рантайм при ESM-.d.ts (export default) — дефолт-импорт
             // типизируется как namespace. Каст к реальной сигнатуре, рантайм не меняется.
@@ -286,13 +290,15 @@ export default async () => {
                 let buildOk = true;
                 try {
                     // Лок на всю серию ребилдов: параллельная ручная сборка в этом же
-                    // каталоге не потопчет dist_bk и не потеряет чексуммы кеша.
-                    const release = acquireBuildLock(lockPath);
+                    // каталоге не потопчет dist_bk и не потеряет чексуммы кеша. Занят другим
+                    // живым процессом (второй `site -w` на той же папке) — ждём до минуты и
+                    // собираем сами: иначе ребилд пропадает и браузер не получает reload.
+                    const release = await waitBuildLock(lockPath, 60_000, (e) => console.log(chalk.gray(`waiting for another build: ${e.message}`)));
                     try {
-                        await build(options, cacheConf, plugins);
+                        ({ pages } = await build(options, cacheConf, plugins));
                         while (attemptedWatchBuild) {
                             attemptedWatchBuild = false;
-                            await build(options, cacheConf, plugins);
+                            ({ pages } = await build(options, cacheConf, plugins));
                         }
                     }
                     finally {
@@ -329,7 +335,7 @@ export default async () => {
             process.exit(1);
         }
         try {
-            await build(options, cacheConf, plugins);
+            ({ pages } = await build(options, cacheConf, plugins));
         }
         finally {
             release();
@@ -342,7 +348,7 @@ export default async () => {
         }
         isBuilding = false;
         if (opts.site)
-            return await cmdSite(options, opts, reloadEmitter);
+            return await cmdSite(options, opts, reloadEmitter, () => pages);
         if (options.GENERATE_WEBSITE && !opts.watch) {
             console.log(chalk.gray('\nto view the generated website run'));
             console.log(`> c4builder site`);

package/dist/config/defaults.js

@@ -31,6 +31,7 @@ const defaultConfig = {
     diagramFormat: 'svg',
     d2Layout: 'dagre',
     charset: 'UTF-8',
-    useSystemFonts: false
+    useSystemFonts: false,
+    questionsHeading: 'Open questions'
 };
 export { defaultConfig };

package/dist/config/schema.js

@@ -57,6 +57,9 @@ export const configSchema = z.object({
     d2Layout: str(defaultConfig.d2Layout),
     charset: str(defaultConfig.charset),
     useSystemFonts: bool(defaultConfig.useSystemFonts),
+    // Заголовок раздела, куда `site -w` дописывает комментарии к странице (в коде кириллицы
+    // быть не может — русский заголовок задаёт сам проект).
+    questionsHeading: str(defaultConfig.questionsHeading),
     // Задаются явно (флаг/промпт) либо тонкой правкой файла — в defaultConfig не входят.
     projectName: optStr(),
     webFileName: optStr(),

package/dist/core/build.js

@@ -14,10 +14,9 @@ import { generateMD, generateWebMD, generateCompleteMD, generateLlmsTxt, generat
 // Загружены заранее в cli/dispatch и приходят третьим аргументом (как cacheConf).
 import { runAfterScan, runAfterBuild } from "./plugins/hooks.js";
 import { injectPluginAssets } from "./plugins/assets.js";
-// Оркестратор владеет lifecycle выходного каталога: dist бэкапится в dist_bk, откуда
-// generateImages восстанавливает неизменённые по чексумме картинки; в конце бэкап сносится.
 const build = async (options, cacheConf, plugins = []) => {
     const start_date = new Date();
+    let pages = new Map();
     const bkFolderName = options.DIST_FOLDER + DIST_BACKUP_FOLDER_SUFFIX;
     // Generating local images, remove old backup image folder, rename current dist folder to new backup
     if (options.GENERATE_LOCAL_IMAGES) {
@@ -72,7 +71,7 @@ const build = async (options, cacheConf, plugins = []) => {
         }
         if (options.GENERATE_WEBSITE) {
             console.log(chalk.blue('generating docsify site'));
-            await generateWebMD(tree, options);
+            pages = await generateWebMD(tree, options);
             await injectPluginAssets(plugins, options);
         }
         // llms.txt ссылается на .md страниц сайта — без website ссылаться не на что.
@@ -98,6 +97,7 @@ const build = async (options, cacheConf, plugins = []) => {
         await runAfterBuild(options, plugins);
         console.log(chalk.green(`built in ${(Date.now() - start_date.getTime()) / 1000} seconds`));
         ok = true;
+        return { pages };
     }
     finally {
         // Бэкап dist сносим ТОЛЬКО при успехе: при падении фазы dist_bk — единственная

package/dist/core/compose/markdown.js

@@ -315,6 +315,7 @@ export const generateMD = async (tree, options, onProgress) => {
 export const generateWebMD = async (tree, options) => {
     const filePromises = [];
     let docsifySideBar = '';
+    const pages = new Map();
     const getWebFileName = (originalFileName) => options.WEB_FILE_NAME || originalFileName;
     for (const item of tree) {
         if (inSidebar(item, options)) {
@@ -322,7 +323,9 @@ export const generateWebMD = async (tree, options) => {
         }
         const MD = await compilePage(item, options);
         //write to disk
-        filePromises.push(writeFile(path.join(options.DIST_FOLDER, item.dir.replace(options.ROOT_FOLDER, ''), `${getWebFileName(item.name)}.md`), MD));
+        const pageRel = path.join(item.dir.replace(options.ROOT_FOLDER, ''), `${getWebFileName(item.name)}.md`);
+        pages.set(pageRel.split(path.sep).filter(Boolean).join('/'), item.sources);
+        filePromises.push(writeFile(path.join(options.DIST_FOLDER, pageRel), MD));
     }
     if (options.DOCSIFY_TEMPLATE && options.DOCSIFY_TEMPLATE !== '') {
         // require ESM/TS-шаблона возвращает namespace { default: fn }, а не саму функцию —
@@ -375,4 +378,5 @@ export const generateWebMD = async (tree, options) => {
     //sidebar
     filePromises.push(writeFile(path.join(options.DIST_FOLDER, '_sidebar.md'), docsifySideBar));
     await Promise.all(filePromises);
+    return pages;
 };

package/dist/core/plugins/tree.js

@@ -52,7 +52,8 @@ export const addPage = (tree, options, page) => {
                 parent: parent.dir,
                 mdFiles: [],
                 diagrams: [],
-                descendants: []
+                descendants: [],
+                sources: []
             };
             VIRTUAL.add(item);
             parent.descendants.push(seg);
@@ -66,6 +67,7 @@ export const addPage = (tree, options, page) => {
     }
     const md = page.markdown === undefined ? [] : Array.isArray(page.markdown) ? page.markdown : [page.markdown];
     item.mdFiles.push(...md);
+    item.sources.push(...(page.sources ?? []).map((s) => path.resolve(s)));
     for (const d of page.diagrams ?? []) {
         const ext = path.extname(d.file).toLowerCase();
         const engine = engineForExt(ext);

package/dist/core/questions.js

@@ -0,0 +1,227 @@
+// Правка раздела вопросов исходного markdown по комментарию со страницы `site -w`
+// (см. change site-comments, design D4): добавление и удаление. Чистые функции + запись
+// файла; формат раздела (таблица / список / его отсутствие) определяется по содержимому,
+// чтобы не навязывать проектам одну форму таблицы.
+import fs from 'node:fs';
+const QUOTE_MAX = 200;
+const collapse = (s) => s.replace(/\s+/g, ' ').trim();
+// docsify рендерит HTML из markdown как есть: без экранирования цитата `List<String>` теряет
+// `<String>` на странице, а `<img onerror>` из комментария становится скриптом и в dist.
+const escapeHtml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+/** Текст вопроса: комментарий, цитата (до 200 символов) и раздел страницы, где сделано выделение. */
+export const formatQuestion = ({ comment, quote, section }) => {
+    let q = collapse(quote ?? '');
+    if (q.length > QUOTE_MAX)
+        q = `${q.slice(0, QUOTE_MAX - 1).trimEnd()}…`;
+    const s = collapse(section ?? '');
+    return escapeHtml(`${collapse(comment)}${q ? ` — «${q}»` : ''}${s ? ` (§ ${s})` : ''}`);
+};
+// Заголовок раздела: любой уровень, без учёта регистра и лишних пробелов, с необязательными
+// закрывающими `#`.
+const headingLevel = (line, heading) => {
+    const m = line.match(/^(#{1,6})\s+(.*?)\s*#*\s*$/);
+    if (!m)
+        return 0;
+    return collapse(m[2]).toLowerCase() === collapse(heading).toLowerCase() ? m[1].length : 0;
+};
+const isFence = (line) => /^\s*(```|~~~)/.test(line);
+const isRow = (line) => line.trim().startsWith('|');
+const isSeparator = (line) => /^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?\s*$/.test(line);
+const isListItem = (line) => /^\s*([-*+]|\d+[.)])\s+/.test(line);
+const splitRow = (line) => line
+    .trim()
+    .replace(/^\|/, '')
+    .replace(/\|$/, '')
+    .split(/(?<!\\)\|/)
+    .map((c) => c.trim());
+const isPlaceholder = (cell) => /^(\.{3}|…|)$/.test(cell);
+const escapeCell = (s) => s.replace(/\|/g, '\\|');
+// Текст ячейки/пункта без inline-разметки — для сравнения с тем, что видно на странице
+// (docsify отрисовал markdown, клиент прислал textContent). Применяется к обеим сторонам:
+// сущности декодируются до срезания тегов, чтобы `&lt;T&gt;` из файла и `<T>` со страницы
+// свелись к одному.
+const plain = (s) => collapse(s
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&')
+    .replace(/\\\|/g, '|')
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/<[^>]+>/g, '')
+    .replace(/[`*_~]/g, ''));
+/** Границы раздела: строка заголовка и индекс первой строки за разделом. */
+const findSection = (lines, heading) => {
+    let start = -1;
+    let level = 0;
+    let fenced = false;
+    for (const [i, line] of lines.entries()) {
+        if (isFence(line))
+            fenced = !fenced;
+        if (fenced)
+            continue;
+        level = headingLevel(line, heading);
+        if (level) {
+            start = i;
+            break;
+        }
+    }
+    if (start < 0)
+        return undefined;
+    let end = lines.length;
+    fenced = false;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (isFence(lines[i]))
+            fenced = !fenced;
+        if (fenced)
+            continue;
+        const m = lines[i].match(/^(#{1,6})\s/);
+        if (m && m[1].length <= level) {
+            end = i;
+            break;
+        }
+    }
+    return { start, end };
+};
+const findTable = (lines, start, end) => {
+    for (let i = start + 1; i + 1 < end; i++) {
+        if (!isRow(lines[i]) || !isSeparator(lines[i + 1]))
+            continue;
+        let last = i + 1;
+        while (last + 1 < end && isRow(lines[last + 1]))
+            last++;
+        const cols = splitRow(lines[i]).length;
+        const rows = lines.slice(i + 2, last + 1).map(splitRow);
+        // Числовая первая колонка: по данным, а у пустой таблицы — по заголовку (`#`, `№`, `No`).
+        const numeric = rows.length
+            ? rows.every((r) => /^\d+$/.test(r[0] ?? ''))
+            : /^(#|№|no\.?)$/i.test(splitRow(lines[i])[0] ?? '');
+        return { header: i, last, cols, numeric, textCol: numeric ? Math.min(1, cols - 1) : 0 };
+    }
+    return undefined;
+};
+/**
+ * Дописывает вопрос в раздел `heading`: строкой таблицы (с номером, если первая колонка
+ * числовая; заглушка `1 | ... | ...` заменяется), иначе пунктом списка в конце раздела;
+ * нет раздела — создаёт его в конце файла. Перевод строки файла сохраняется.
+ */
+export const appendQuestion = (markdown, heading, text) => {
+    const eol = markdown.includes('\r\n') ? '\r\n' : '\n';
+    const lines = markdown.split(/\r?\n/);
+    const section = findSection(lines, heading);
+    if (!section) {
+        while (lines.length && lines[lines.length - 1].trim() === '')
+            lines.pop();
+        lines.push('', `## ${heading}`, '', `- ${text}`, '');
+        return { markdown: lines.join(eol), number: null };
+    }
+    const { start, end } = section;
+    const table = findTable(lines, start, end);
+    if (table) {
+        const { header, last, cols, numeric, textCol } = table;
+        const rows = lines.slice(header + 2, last + 1).map(splitRow);
+        // Единственная строка шаблона с `...` в ячейке вопроса — заглушка: заменяем её, сохраняя
+        // заполненные ячейки (например, «Кому: Аналитик»), остальные `...` очищаем.
+        const placeholder = rows.length === 1 && isPlaceholder(rows[0][textCol] ?? '');
+        const number = numeric
+            ? placeholder
+                ? 1
+                : rows.reduce((max, r) => Math.max(max, Number(r[0])), 0) + 1
+            : null;
+        const cells = placeholder
+            ? Array.from({ length: cols }, (_, c) => isPlaceholder(rows[0][c] ?? '') ? '' : (rows[0][c] ?? ''))
+            : new Array(cols).fill('');
+        if (number !== null)
+            cells[0] = String(number);
+        cells[textCol] = escapeCell(text);
+        const row = `| ${cells.join(' | ')} |`;
+        if (placeholder)
+            lines.splice(last, 1, row);
+        else
+            lines.splice(last + 1, 0, row);
+        return { markdown: lines.join(eol), number };
+    }
+    let lastText = end - 1;
+    while (lastText > start && lines[lastText].trim() === '')
+        lastText--;
+    if (lastText === start) {
+        // Пустой раздел: пункт через пустую строку после заголовка; перед следующим
+        // заголовком — тоже пустая строка.
+        const insert = ['', `- ${text}`];
+        if (start + 1 < lines.length && lines[start + 1].trim() !== '')
+            insert.push('');
+        lines.splice(start + 1, 0, ...insert);
+        return { markdown: lines.join(eol), number: null };
+    }
+    // Нумерованный список продолжаем его же маркером: `-` после `2.` начал бы второй список.
+    const ordered = lines
+        .slice(start + 1, lastText + 1)
+        .reverse()
+        .find((l) => /^([-*+]|\d+[.)])\s/.test(l))
+        ?.match(/^(\d+)([.)])\s/);
+    lines.splice(lastText + 1, 0, ordered ? `${Number(ordered[1]) + 1}${ordered[2]} ${text}` : `- ${text}`);
+    return { markdown: lines.join(eol), number: null };
+};
+/**
+ * Удаляет вопрос из раздела `heading`: строку таблицы (по номеру и тексту; без совпадения
+ * номера — только по тексту) или пункт списка по тексту. Текст сравнивается без inline-разметки.
+ * Номера остальных строк не меняются — на них ссылаются другие документы.
+ */
+export const removeQuestion = (markdown, heading, ref) => {
+    const eol = markdown.includes('\r\n') ? '\r\n' : '\n';
+    const lines = markdown.split(/\r?\n/);
+    const section = findSection(lines, heading);
+    if (!section)
+        return { error: 'not-found' };
+    const { start, end } = section;
+    const want = plain(ref.text);
+    const table = findTable(lines, start, end);
+    let candidates = [];
+    if (table) {
+        const { header, last, numeric, textCol } = table;
+        const rows = [];
+        for (let i = header + 2; i <= last; i++)
+            rows.push({ line: i, cells: splitRow(lines[i]) });
+        const byText = rows.filter((r) => plain(r.cells[textCol] ?? '') === want);
+        const byNumber = numeric && ref.number != null ? byText.filter((r) => Number(r.cells[0]) === ref.number) : [];
+        candidates = (byNumber.length ? byNumber : byText).map((r) => r.line);
+    }
+    else {
+        for (let i = start + 1; i < end; i++)
+            if (isListItem(lines[i]) && plain(lines[i].replace(/^\s*([-*+]|\d+[.)])\s+/, '')) === want)
+                candidates.push(i);
+    }
+    if (!candidates.length)
+        return { error: 'not-found' };
+    if (candidates.length > 1)
+        return { error: 'ambiguous' };
+    lines.splice(candidates[0], 1);
+    return { markdown: lines.join(eol) };
+};
+const hasHeading = (file, heading) => {
+    try {
+        return fs
+            .readFileSync(file, 'utf8')
+            .split(/\r?\n/)
+            .some((l) => headingLevel(l, heading) > 0);
+    }
+    catch {
+        return false;
+    }
+};
+/** Файл страницы для записи: первый с разделом `heading`, иначе первый существующий. */
+export const pickSource = (files, heading) => {
+    const existing = files.filter((f) => fs.existsSync(f));
+    return existing.find((f) => hasHeading(f, heading)) ?? existing[0];
+};
+/** Дописывает вопрос в файл и возвращает номер строки таблицы (null — список). */
+export const writeQuestion = (file, heading, text) => {
+    const { markdown, number } = appendQuestion(fs.readFileSync(file, 'utf8'), heading, text);
+    fs.writeFileSync(file, markdown);
+    return number;
+};
+/** Удаляет вопрос из файла; ошибка поиска возвращается, не бросается. */
+export const deleteQuestion = (file, heading, ref) => {
+    const result = removeQuestion(fs.readFileSync(file, 'utf8'), heading, ref);
+    if ('markdown' in result)
+        fs.writeFileSync(file, result.markdown);
+    return result;
+};

package/dist/core/scan/tree.js

@@ -43,7 +43,8 @@ export const generateTree = async (dir, options) => {
                 parent: parent,
                 mdFiles: [],
                 diagrams: [],
-                descendants: []
+                descendants: [],
+                sources: []
             };
             tree.push(item);
         }
@@ -84,6 +85,7 @@ export const generateTree = async (dir, options) => {
             const mdPath = path.join(dir, mdFile);
             const { markdown, diagrams } = fences.extract((await readFile(mdPath)).toString(), path.parse(mdFile).name, path.relative(process.cwd(), mdPath).split(path.sep).join('/'));
             item.mdFiles.push(markdown);
+            item.sources.push(path.resolve(mdPath));
             for (const d of diagrams)
                 item.diagrams.push({
                     dir: d.file,

package/dist/plugins/openspec/index.js

@@ -16,7 +16,16 @@ const optionsSchema = z
     artifacts: z.array(z.string()).default(['proposal', 'design', 'tasks']),
     // Ключ `.openspec.yaml` со ссылкой на родительский change (например `x-parent`):
     // вложенный change выводится страницей под родителем. Не задан — плоский список.
-    parentKey: z.string().min(1).optional()
+    parentKey: z.string().min(1).optional(),
+    // Ключ `.openspec.yaml` с группой change'а (например `x-team`): change'ы верхнего
+    // уровня раскладываются по папкам групп `Changes/<группа>/<id>`. Не задан — без групп.
+    groupKey: z.string().min(1).optional(),
+    // Ключ `.openspec.yaml` с человеческим именем change'а (например `x-name`): подпись и
+    // сегмент пути change'а верхнего уровня вместо id. Не задан — id.
+    nameKey: z.string().min(1).optional(),
+    // Дополнительные колонки таблицы Changes из `.openspec.yaml` (например исполнитель):
+    // `[{ key: "x-assignee", title: "Assignee" }]`. Не задана — прежняя таблица.
+    columns: z.array(z.object({ key: z.string().min(1), title: z.string().min(1) }).strict()).optional()
 })
     .strict();
 export default definePlugin({
@@ -35,7 +44,12 @@ export default definePlugin({
         // complete-markdown; excludeOtherFiles действует и здесь.
         const addPages = (pages, srcRoot) => {
             for (const page of pages) {
-                ctx.addPage({ path: page.path, markdown: page.markdown, diagrams: page.diagrams });
+                ctx.addPage({
+                    path: page.path,
+                    markdown: page.markdown,
+                    diagrams: page.diagrams,
+                    sources: page.sources
+                });
                 if (options.EXCLUDE_OTHER_FILES)
                     continue;
                 for (const { from, to } of page.files) {
@@ -52,23 +66,36 @@ export default definePlugin({
             }
         };
         // Родитель добавляется раньше вложенных: в sidebar под ним сначала его артефакты,
-        // затем вложенные change'ы.
-        const addChanges = (changes, layout) => {
+        // затем вложенные change'ы. Страница группы — перед первым её change'ем, со своей
+        // таблицей (без секций — она сама и есть секция).
+        const addChanges = (changes, layout, section, index) => {
+            const seen = new Set();
             for (const change of pageOrder(changes, layout)) {
                 const at = layout.get(change);
-                if (at)
-                    addPages(renderChange(change, at.segments, o.artifacts, options, layout), change.dir);
+                if (!at)
+                    continue;
+                if (at.group && !seen.has(at.group)) {
+                    seen.add(at.group);
+                    const members = changes.filter((c) => layout.get(c)?.group === at.group);
+                    ctx.addPage({ path: [mount, section, at.group], markdown: index(members) });
+                }
+                addPages(renderChange(change, at.segments, o.artifacts, options, layout), change.dir);
             }
         };
-        const { parentKey } = o;
-        const active = layoutChanges(store.changes, [mount, 'Changes'], { parentKey });
-        const archived = layoutChanges(store.archive, [mount, 'Archive'], { parentKey, archived: true });
-        ctx.addPage({ path: [mount], markdown: renderSummary(store, mount, options, active) });
+        const { parentKey, groupKey, nameKey } = o;
+        const active = layoutChanges(store.changes, [mount, 'Changes'], { parentKey, groupKey, nameKey });
+        const archived = layoutChanges(store.archive, [mount, 'Archive'], {
+            parentKey,
+            groupKey,
+            nameKey,
+            archived: true
+        });
+        ctx.addPage({ path: [mount], markdown: renderSummary(store, mount, options, active, o.columns) });
         ctx.addPage({
             path: [mount, 'Changes'],
-            markdown: renderChangesIndex(store.changes, mount, options, active)
+            markdown: renderChangesIndex(store.changes, mount, options, active, { columns: o.columns })
         });
-        addChanges(store.changes, active);
+        addChanges(store.changes, active, 'Changes', (members) => renderChangesIndex(members, mount, options, active, { sections: false, columns: o.columns }));
         // Specs: индекс, промежуточные папки, страницы спек — тем же рендером, что и
         // дельты (fenced-диаграммы локально, ссылки на файлы рядом со спекой).
         const specsDir = path.join(storeDir, 'specs');
@@ -82,6 +109,6 @@ export default definePlugin({
             path: [mount, 'Archive'],
             markdown: renderArchiveIndex(store.archive, mount, options, archived)
         });
-        addChanges(store.archive, archived);
+        addChanges(store.archive, archived, 'Archive', (members) => renderArchiveIndex(members, mount, options, archived, { sections: false }));
     }
 });

package/dist/plugins/openspec/layout.js

@@ -8,8 +8,15 @@ const originalId = (c, archived) => archived ? c.id.replace(DATE_PREFIX, '') : c
  * вложенный или не найден — change остаётся на верхнем уровне. Подпись вложенного — хвост
  * id после `<id родителя>-`; если хвоста нет или он совпадает с подстраницей родителя
  * (артефакт, `specs`) или с подписью соседа — полный id.
+ * С `groupKey` change верхнего уровня, у которого задан этот ключ, кладётся под папку
+ * группы: `<base>/<группа>/<id>`; вложенные идут за родителем. Значение со `/` или
+ * совпадающее с подписью change'а без группы (коллизия путей) — группой не считается.
+ * С `nameKey` подпись и сегмент пути change'а верхнего уровня — значение ключа (например
+ * `x-name: Оплата картой`): sidebar и таблицы читаются по-человечески, а адрес страницы
+ * стабилен, пока значение не меняют. Недопустимое значение (`/`, `\`, `#`, `?`, `.`, `..`) или
+ * занятое в той же папке — подпись остаётся id; для группы — то же, change остаётся без группы.
  */
-export const layoutChanges = (changes, base, { parentKey, archived = false } = {}) => {
+export const layoutChanges = (changes, base, { parentKey, groupKey, nameKey, archived = false } = {}) => {
     const byId = new Map(changes.map((c) => [originalId(c, archived), c]));
     const parentOf = (c) => {
         const ref = parentKey ? c.meta[parentKey] : undefined;
@@ -21,8 +28,41 @@ export const layoutChanges = (changes, base, { parentKey, archived = false } = {
         const p = parentOf(c);
         return !p || parentOf(p);
     });
-    for (const c of top)
-        layout.set(c, { segments: [...base, c.id], label: c.id, children: [] });
+    // Значение ключа как сегмент пути: addPage отвергает `/`, `\`, `.`, `..` и пустые, а `#` и
+    // `?` encodeURI оставляет как есть — ссылка в sidebar оборвалась бы на якоре или запросе.
+    const segment = (key, c) => {
+        const v = key ? c.meta[key]?.trim() : undefined;
+        return v && !/[\\/#?]/.test(v) && v !== '.' && v !== '..' ? v : undefined;
+    };
+    // Имя, совпадающее с id другого change'а, дало бы тот же путь — остаётся id.
+    const ids = new Set(changes.map((c) => c.id));
+    const wanted = (c) => {
+        const name = segment(nameKey, c);
+        return name && !ids.has(name) ? name : c.id;
+    };
+    // Подписи change'ов без группы заняты на уровне base — группа с таким именем дала бы коллизию.
+    const flat = new Set(top.filter((c) => !segment(groupKey, c)).map(wanted));
+    const groups = new Set();
+    const used = new Map();
+    for (const c of top) {
+        const g = segment(groupKey, c);
+        const group = g && !flat.has(g) ? g : undefined;
+        if (group)
+            groups.add(group);
+        const folder = group ?? '';
+        const taken = used.get(folder) ?? new Set();
+        used.set(folder, taken);
+        // Повтор подписи в папке (или имя группы на уровне base) — откат на уникальный id.
+        const want = wanted(c);
+        const label = taken.has(want) || (!group && want !== c.id && groups.has(want)) ? c.id : want;
+        taken.add(label);
+        layout.set(c, {
+            segments: group ? [...base, group, label] : [...base, label],
+            label,
+            children: [],
+            group
+        });
+    }
     for (const c of changes) {
         if (layout.has(c))
             continue;
@@ -37,19 +77,34 @@ export const layoutChanges = (changes, base, { parentKey, archived = false } = {
         const prefix = `${originalId(parent, archived)}-`;
         const tail = own.startsWith(prefix) ? own.slice(prefix.length) : '';
         const label = tail && !taken.has(tail) ? tail : c.id;
-        layout.set(c, { segments: [...host.segments, label], label, parent, children: [] });
+        layout.set(c, {
+            segments: [...host.segments, label],
+            label,
+            parent,
+            children: [],
+            group: host.group
+        });
         host.children.push(c);
     }
     return layout;
 };
+/** Группы раскладки по алфавиту; change'ы без группы в список не входят. */
+export const groupNames = (changes, layout) => [...new Set(changes.map((c) => layout.get(c)?.group).filter((g) => !!g))].sort((a, b) => a.localeCompare(b));
 /**
  * Change'ы в порядке вывода: каждый верхнего уровня, сразу за ним — его вложенные. Порядок
- * внутри обоих уровней — порядок `changes` (по имени для страниц, по дате для таблиц).
+ * внутри обоих уровней — порядок `changes` (по имени для страниц, по дате для таблиц); с
+ * группами — сначала группы по алфавиту, затем change'ы без группы.
  */
 export const pageOrder = (changes, layout) => {
     const pos = new Map(changes.map((c, i) => [c, i]));
+    const groups = groupNames(changes, layout);
+    const rank = (c) => {
+        const g = layout.get(c)?.group;
+        return g ? groups.indexOf(g) : groups.length;
+    };
     return changes
         .filter((c) => !layout.get(c)?.parent)
+        .sort((a, b) => rank(a) - rank(b) || (pos.get(a) ?? 0) - (pos.get(b) ?? 0))
         .flatMap((c) => [
         c,
         ...[...(layout.get(c)?.children ?? [])].sort((a, b) => (pos.get(a) ?? 0) - (pos.get(b) ?? 0))

package/dist/plugins/openspec/render.js

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createFenceExtractor, mapOutsideFences } from "../../core/scan/fences.js";
 import { encodeURIPath } from "../../util/utils.js";
-import { pageOrder } from "./layout.js";
+import { groupNames, pageOrder } from "./layout.js";
 // Ссылка на страницу сайта от корня (без ведущего «/»): так же строится sidebar,
 // а docsify без relativePath резолвит ссылки от корня сайта.
 export const pageLink = (segments, options) => encodeURIPath(path.posix.join(...segments, options.WEB_FILE_NAME || segments[segments.length - 1]));
@@ -11,23 +11,46 @@ const fmtDate = (ms) => new Date(ms).toISOString().slice(0, 10);
 // Прогресс задач: нативный <progress> (docsify рендерит HTML в markdown) + числа и процент.
 const progressBar = (done, total) => `<progress value="${done}" max="${total}"></progress> ${done}/${total} (${Math.round((done / total) * 100)}%)`;
 const fmtProgress = (c) => c.progress ? progressBar(c.progress.done, c.progress.total) : '—';
+// Секции по группам (опция groupKey): `### <группа>` над своей частью таблицы или списка,
+// change'ы без группы — последней секцией `### Ungrouped`. Групп нет или `sections` выключен
+// (страница самой группы) — один блок без заголовка, как раньше.
+const bySections = (changes, layout, sections, render) => {
+    const groups = layout && sections ? groupNames(changes, layout) : [];
+    if (!groups.length)
+        return render(changes);
+    const groupOf = (c) => layout?.get(c)?.group;
+    const parts = groups.map((g) => `### ${g}\n\n${render(changes.filter((c) => groupOf(c) === g))}`);
+    const rest = changes.filter((c) => !groupOf(c));
+    if (rest.length)
+        parts.push(`### Ungrouped\n\n${render(rest)}`);
+    return parts.join('\n\n');
+};
+// Значение ячейки markdown-таблицы: `|` разорвал бы строку на колонки.
+const cell = (v) => (v ? v.replace(/\|/g, '\\|') : '—');
 /**
  * Таблица change'ов (сводка и индекс Changes): по дате изменения от новых к старым. С `layout`
- * вложенные change'ы идут сразу под родителем (`↳` + подпись) и ведут на свои вложенные страницы.
+ * вложенные change'ы идут сразу под родителем (`↳` + подпись) и ведут на свои вложенные
+ * страницы, а при группах таблица делится на секции по группам. `columns` — колонки из
+ * `.openspec.yaml` после стандартных (например исполнитель); нет значения — `—`.
  */
-export const renderChangesIndex = (changes, mount, options, layout) => {
+export const renderChangesIndex = (changes, mount, options, layout, { sections = true, columns = [] } = {}) => {
     if (!changes.length)
         return '_No changes._';
-    const byDate = [...changes].sort((a, b) => b.mtime - a.mtime);
-    const rows = (layout ? pageOrder(byDate, layout) : byDate).map((c) => {
-        const at = layout?.get(c);
-        const link = `[${at?.label ?? c.id}](${pageLink(at?.segments ?? [mount, 'Changes', c.id], options)})`;
-        return `| ${at?.parent ? `↳ ${link}` : link} | ${c.schema ?? '—'} | ${fmtProgress(c)} | ${fmtDate(c.mtime)} |`;
-    });
-    return ['| Change | Schema | Tasks | Updated |', '|---|---|---|---|', ...rows].join('\n');
+    const head = ['Change', 'Schema', 'Tasks', 'Updated', ...columns.map((c) => cell(c.title))];
+    const table = (part) => {
+        const byDate = [...part].sort((a, b) => b.mtime - a.mtime);
+        const rows = (layout ? pageOrder(byDate, layout) : byDate).map((c) => {
+            const at = layout?.get(c);
+            const link = `[${at?.label ?? c.id}](${pageLink(at?.segments ?? [mount, 'Changes', c.id], options)})`;
+            const extra = columns.map((col) => ` ${cell(c.meta[col.key])} |`).join('');
+            return `| ${at?.parent ? `↳ ${link}` : link} | ${c.schema ?? '—'} | ${fmtProgress(c)} | ${fmtDate(c.mtime)} |${extra}`;
+        });
+        return [`| ${head.join(' | ')} |`, `|${'---|'.repeat(head.length)}`, ...rows].join('\n');
+    };
+    return bySections(changes, layout, sections, table);
 };
 /** Сводка store (страница mount): счётчики, суммарный прогресс, таблица активных change'ов. */
-export const renderSummary = (store, mount, options, layout) => {
+export const renderSummary = (store, mount, options, layout, columns = []) => {
     const withProgress = store.changes.filter((c) => c.progress);
     const done = withProgress.reduce((s, c) => s + (c.progress?.done ?? 0), 0);
     const total = withProgress.reduce((s, c) => s + (c.progress?.total ?? 0), 0);
@@ -40,18 +63,18 @@ export const renderSummary = (store, mount, options, layout) => {
         '',
         '## Active changes',
         '',
-        renderChangesIndex(store.changes, mount, options, layout)
+        renderChangesIndex(store.changes, mount, options, layout, { columns })
     ].join('\n');
 };
-/** Список архива: от новых к старым; с `layout` вложенные — пунктами под родителем. */
-export const renderArchiveIndex = (archive, mount, options, layout) => archive.length
-    ? (layout ? pageOrder(archive, layout) : archive)
+/** Список архива: от новых к старым; с `layout` вложенные — пунктами под родителем, по секциям групп. */
+export const renderArchiveIndex = (archive, mount, options, layout, { sections = true } = {}) => archive.length
+    ? bySections(archive, layout, sections, (part) => (layout ? pageOrder(part, layout) : part)
         .map((c) => {
         const at = layout?.get(c);
         const link = pageLink(at?.segments ?? [mount, 'Archive', c.id], options);
         return `${at?.parent ? '  ' : ''}- [${at?.label ?? c.id}](${link})`;
     })
-        .join('\n')
+        .join('\n'))
     : '_Archive is empty._';
 /** Индекс папки спек (Specs, промежуточные папки, дельты change'а): вложенный список под prefix. */
 export const renderSpecIndex = (specs, prefix, base, options) => {
@@ -110,6 +133,7 @@ const FENCE_LANGS = ['plantuml', 'puml', 'd2'];
 export const renderMarkdown = (pagePath, base, content, { srcRoot, fromDir = '', pageDir = fromDir, included = new Set(), target = () => undefined, source, options }) => {
     const { markdown, diagrams } = createFenceExtractor(FENCE_LANGS).extract(content, base, source);
     const files = [];
+    const sources = source ? [source] : [];
     const rewrite = (t) => t.replace(LINK_RE, (whole, bang, text, href, title = '') => {
         const inner = text.includes('![') ? rewrite(text) : text;
         if (/^[a-z][a-z0-9+.-]*:|^[#/]/i.test(href))
@@ -145,6 +169,7 @@ export const renderMarkdown = (pagePath, base, content, { srcRoot, fromDir = '',
             });
             diagrams.push(...sub.diagrams);
             files.push(...sub.files);
+            sources.push(...sub.sources);
             return sub.markdown;
         }
         const sameDir = fromDir === pageDir;
@@ -154,7 +179,7 @@ export const renderMarkdown = (pagePath, base, content, { srcRoot, fromDir = '',
             ? `${bang}[${inner}](${sameDir ? href : encodeURIPath(to)}${title})`
             : `[${inner}](${encodeURIPath(path.posix.join(...pagePath, to))}${ignoreTitle(title)})`;
     });
-    return { path: pagePath, markdown: mapOutsideFences(markdown, rewrite).trim(), diagrams, files };
+    return { path: pagePath, markdown: mapOutsideFences(markdown, rewrite).trim(), diagrams, files, sources };
 };
 /**
  * Страницы дерева спек под `base`: корень, промежуточные папки, спеки. Папка с собственной
@@ -170,7 +195,7 @@ export const renderSpecTree = (specs, base, options, render) => {
         const spec = byKey.get(key);
         const page = spec
             ? render(pagePath, spec)
-            : { path: pagePath, markdown: '', diagrams: [], files: [] };
+            : { path: pagePath, markdown: '', diagrams: [], files: [], sources: [] };
         const nested = specs.some((s) => s.path.length > prefix.length && prefix.every((p, i) => s.path[i] === p));
         if (nested || !spec)
             page.markdown = [page.markdown, renderSpecIndex(specs, prefix, base, options)]
@@ -254,7 +279,8 @@ export const renderChange = (change, segments, order, options, layout) => {
             path: segments,
             markdown: [head, family, links.join(' · '), main?.markdown].filter(Boolean).join('\n\n'),
             diagrams: main?.diagrams ?? [],
-            files: main?.files ?? []
+            files: main?.files ?? [],
+            sources: main?.sources ?? []
         },
         ...subpages
     ];

package/dist/plugins/openspec/scan.js

@@ -41,8 +41,10 @@ const readMeta = (file) => {
             const m = line.match(/^([A-Za-z0-9_.-]+):[ \t]*(.+?)\s*$/);
             if (!m || m[2].startsWith('#'))
                 continue;
-            // Комментарий в конце строки (` # …`) — не часть значения.
-            meta[m[1]] = m[2].replace(/\s+#.*$/, '').replace(/^["']|["']$/g, '');
+            // Значение в кавычках — целиком (`x-name: "Задача #5"`); у остальных комментарий в
+            // конце строки (` # …`) — не часть значения.
+            const quoted = m[2].match(/^(["'])(.*?)\1(?:\s+#.*)?$/);
+            meta[m[1]] = quoted ? quoted[2] : m[2].replace(/\s+#.*$/, '').replace(/^["']|["']$/g, '');
         }
     return { schema: meta.schema, created: meta.created, meta };
 };

package/dist/util/lock.js

@@ -56,3 +56,26 @@ export const acquireBuildLock = (lockPath) => {
     }
     throw new BuildLockHeldError(`failed to acquire the build lock: ${lockPath}`);
 };
+/**
+ * Захват лока с ожиданием: пока сборку держит другой живой процесс (второй `site -w` в той же
+ * папке), пробуем каждые `stepMs`, не дольше `timeoutMs`; затем — исходная BuildLockHeldError.
+ * `onWait` зовётся один раз при первом отказе — для сообщения в терминал.
+ */
+export const waitBuildLock = async (lockPath, timeoutMs, onWait, stepMs = 500) => {
+    const deadline = Date.now() + timeoutMs;
+    let waited = false;
+    for (;;) {
+        try {
+            return acquireBuildLock(lockPath);
+        }
+        catch (e) {
+            if (!(e instanceof BuildLockHeldError) || Date.now() >= deadline)
+                throw e;
+            if (!waited) {
+                waited = true;
+                onWait?.(e);
+            }
+            await new Promise((r) => setTimeout(r, stepMs));
+        }
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfacapital-tech/c4builder",
-  "version": "0.7.0",
+  "version": "0.9.0-rc.1",
   "description": "A CLI tool designed to compile a folder structure of markdowns and plant uml files into a site, single file markdown or a collection of markdowns with links",
   "type": "module",
   "main": "dist/index.js",