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

package/dist/cli/agent.js

@@ -0,0 +1,21 @@
+const AGENT_VARS = [
+    ['CLAUDECODE', 'claude-code'],
+    ['CODEX_THREAD_ID', 'codex'],
+    ['GEMINI_CLI', 'gemini-cli'],
+    ['OPENCODE', 'opencode'],
+    ['COPILOT_CLI', 'copilot-cli']
+];
+const fromEnv = (env) => {
+    const own = env.C4BUILDER_AGENT;
+    if (own)
+        return { on: own !== '0', name: own, explicit: true };
+    const known = AGENT_VARS.find(([key]) => env[key]);
+    const name = known ? known[1] : env.AI_AGENT;
+    return { on: !!name, name: name ?? '', explicit: false };
+};
+export const detectAgent = (env, flags) => {
+    const found = fromEnv(env);
+    if (flags.agent === undefined)
+        return found;
+    return { on: flags.agent, name: found.on ? found.name : 'agent', explicit: true };
+};

package/dist/cli/commands/feedback.js

@@ -0,0 +1,45 @@
+import chalk from 'chalk';
+import fs from 'node:fs';
+import { parseConfig } from "../../config/options.js";
+import { FEEDBACK_HEADER, FEEDBACK_PATH } from "./site.comments.js";
+// `c4builder feedback` (change site-agent-feedback, design D9): забирает пачку замечаний у `site -w`.
+// Конфиг читается как JSON без Configstore — тот создал бы `.c4builder` в любом каталоге. Ошибки —
+// через exitCode, а не process.exit: напечатанная в pipe пачка должна успеть уйти целиком.
+export default async (configPath, opts) => {
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    }
+    catch { }
+    const config = parseConfig(raw && typeof raw === 'object' ? raw : {});
+    const port = opts.port ?? (config.ok ? config.value : config.salvaged).webPort;
+    const shown = `http://localhost:${port}`;
+    const fail = (message) => {
+        console.error(chalk.red(message));
+        process.exitCode = 1;
+    };
+    // 127.0.0.1, а не localhost: сервер слушает только IPv4, а `localhost` → `::1` на части машин
+    // подвешивает соединение.
+    const url = `http://127.0.0.1:${port}${FEEDBACK_PATH}/next${opts.wait ? '' : '?wait=0'}`;
+    for (;;) {
+        let res;
+        try {
+            res = await fetch(url, { headers: { [FEEDBACK_HEADER]: '1' } });
+        }
+        catch {
+            return fail(`no c4builder site -w on ${shown} — start it first`);
+        }
+        if (res.status === 200) {
+            process.stdout.write(await res.text());
+            return;
+        }
+        if (res.status === 204) {
+            if (opts.wait)
+                continue;
+            return;
+        }
+        if (res.status === 404)
+            return fail(`agent feedback is disabled on ${shown} — the server runs without -w or with --no-agent`);
+        return fail(`unexpected response ${res.status} from ${shown}`);
+    }
+};

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

@@ -1,17 +1,32 @@
 export const COMMENTS_PATH = '/__c4builder/comments';
+export const FEEDBACK_PATH = '/__c4builder/feedback';
+export const FEEDBACK_HEADER = 'X-C4builder-Feedback';
 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-cbtns{position:absolute;z-index:1001;white-space:nowrap}',
+    '.c4b-cbtns button{margin-right:4px;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-cbtns button.c4b-fb{border-color:#3b82f6}',
     '.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 textarea,.c4b-review 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-cpop button,.c4b-review 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,.c4b-review button.c4b-primary{border-color:#42b983;background:#42b983;color:#fff}',
+    '.c4b-cpop button:disabled,.c4b-review button:disabled{opacity:.6;cursor:default}',
+    // Панель review — ниже кнопок у выделения и поповера: она прибита к низу экрана и иначе
+    // перекрывает их у выделения в нижних строках.
+    '.c4b-review{position:fixed;left:50%;bottom:16px;transform:translateX(-50%);z-index:1000;width:520px;max-width:calc(100vw - 32px);box-sizing:border-box;padding:8px 12px;border:1px solid #3b82f6;border-radius:6px;background:#fff;color:#2c3e50;font:13px/1.4 sans-serif;box-shadow:0 2px 8px rgba(0,0,0,.2)}',
+    '.c4b-review .c4b-row{display:flex;flex-wrap:wrap;align-items:center;gap:6px}',
+    '.c4b-review .c4b-row small{flex:1;color:#888;white-space:nowrap}',
+    '.c4b-review button.c4b-link{padding:0;border:0;background:none;color:#2c3e50;font-weight:700;text-decoration:underline dotted}',
+    '.c4b-review ul{margin:6px 0;padding:0;list-style:none;max-height:40vh;overflow:auto}',
+    '.c4b-review li{padding:3px 0;border-top:1px solid #eee;overflow-wrap:anywhere}',
+    '.c4b-review textarea{margin-top:6px}',
+    '.c4b-review .c4b-del{opacity:1}',
     '.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}',
+    'mark.c4b-dhl{background:#cfe3ff;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}',
@@ -24,14 +39,19 @@ const CSS = [
 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) => `
+// Начальное состояние агентского режима и ключ проекта вставляет сервер, дальше его обновляют
+// события `c4builder:agent` от сниппета livereload (change site-agent-feedback, design D4, D8).
+export const commentsSnippet = (heading, { agent = false, listening = false, project = '' } = {}) => `
 <script>
 (function () {
     if (window.__c4builderComments) return;
     window.__c4builderComments = true;
     var ENDPOINT = '${COMMENTS_PATH}';
+    var FEEDBACK = '${FEEDBACK_PATH}';
     var HEADING = ${jsString(heading)};
     var TOAST_KEY = '__c4builderCommentToast';
+    var DRAFT_KEY = '__c4builderReview:' + ${jsString(project)};
+    var AGENT = { on: ${agent}, listening: ${listening} };
     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)};
@@ -109,7 +129,7 @@ export const commentsSnippet = (heading) => `
         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 wrapRange = function (idx, from, to, title, cls) {
         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];
@@ -125,9 +145,10 @@ export const commentsSnippet = (heading) => `
             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;
+            // Overlapping quotes: the number link of a question is not part of the text.
+            if (!mid.nodeValue.trim() || mid.parentNode.closest('sup.c4b-ref')) continue;
             var mark = document.createElement('mark');
-            mark.className = 'c4b-hl';
+            mark.className = cls;
             mark.title = title;
             mid.parentNode.insertBefore(mark, mid);
             mark.appendChild(mid);
@@ -135,6 +156,20 @@ export const commentsSnippet = (heading) => `
         }
         return marks;
     };
+    var tryIn = function (idx, quote, cls, title) {
+        var at = idx.text.indexOf(quote);
+        var marks = at < 0 ? null : wrapRange(idx, at, at + quote.length, title, cls);
+        return marks && marks.length ? marks : null;
+    };
+    // The quote is searched in its own section first: the same words may repeat on the page.
+    var locate = function (root, q, skip, cls, title) {
+        var marks = null;
+        if (q.section) {
+            var sh = findHeading(root, q.section);
+            if (sh && skip.indexOf(sh) < 0) marks = tryIn(textIndex(sectionOf(sh), skip), q.quote, cls, title);
+        }
+        return marks || tryIn(textIndex([root], skip), q.quote, cls, title);
+    };
     var flash = function (row) {
         row.scrollIntoView({ block: 'center', behavior: 'smooth' });
         row.classList.add('c4b-qflash');
@@ -185,11 +220,6 @@ export const commentsSnippet = (heading) => `
             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;
@@ -197,11 +227,7 @@ export const commentsSnippet = (heading) => `
             // 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);
+                marks = locate(root, c, skip, 'c4b-hl', c.comment);
                 q = marks ? c : null;
                 return !!marks;
             });
@@ -219,7 +245,12 @@ export const commentsSnippet = (heading) => `
             lastMark.parentNode.insertBefore(sup, lastMark.nextSibling);
         });
     };
-    var schedule = function () { setTimeout(function () { try { highlight(); } catch (e) {} }, 50); };
+    var schedule = function () {
+        setTimeout(function () {
+            try { highlight(); } catch (e) {}
+            try { highlightDraft(); } catch (e) {}
+        }, 50);
+    };
     var docsifyVm = null;
     if (window.$docsify) {
         window.$docsify.plugins = [].concat(window.$docsify.plugins || [], function (hook, vm) {
@@ -230,12 +261,24 @@ export const commentsSnippet = (heading) => `
     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 button = function (label, onClick, cls) {
+        var b = document.createElement('button');
+        b.type = 'button';
+        b.textContent = label;
+        if (cls) b.className = cls;
+        if (onClick) b.addEventListener('click', onClick);
+        return b;
+    };
+    var btns = document.createElement('div');
+    btns.className = 'c4b-cbtns';
+    btns.hidden = true;
+    var fbBtn = button('Feedback', null, 'c4b-fb');
+    fbBtn.title = 'Tell the agent what to change';
+    var qBtn = button('Question');
+    qBtn.title = 'Add a question to the ' + HEADING + ' section of the source file';
+    btns.appendChild(fbBtn);
+    btns.appendChild(qBtn);
+    document.body.appendChild(btns);
     var pop = null;
 
     var selection = function () {
@@ -273,9 +316,9 @@ export const commentsSnippet = (heading) => `
     var update = function () {
         if (pop) return;
         var s = selection();
-        if (!s) { btn.hidden = true; return; }
-        btn.hidden = false;
-        place(btn, anchorRect(s.range));
+        if (!s) { btns.hidden = true; return; }
+        btns.hidden = false;
+        place(btns, anchorRect(s.range));
     };
     document.addEventListener('selectionchange', function () { setTimeout(update, 0); });
 
@@ -292,8 +335,8 @@ export const commentsSnippet = (heading) => `
         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, {
+    var send = function (body, method, url) {
+        return fetch(url || ENDPOINT, {
             method: method || 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify(body)
@@ -304,75 +347,239 @@ export const commentsSnippet = (heading) => `
             });
         });
     };
+    var failure = function (what) {
+        return function (err) { toast(what + ' failed: ' + (err && err.message ? err.message : err), true); };
+    };
+
+    // Feedback to the agent: "Delivered" only after the server handed the batch to
+    // "c4builder feedback"; the event may outrun the POST response, hence both maps.
+    var delivered = {}, pending = {};
+    var sendBatch = function (decision, comments, general) {
+        return send({ decision: decision, comments: comments, general: general }, 'POST', FEEDBACK).then(function (r) {
+            if (delivered[r.id]) return toast('Delivered to the agent');
+            pending[r.id] = true;
+            toast(r.queued ? 'Queued \\u2014 agent is not listening' : 'Sent to the agent');
+        });
+    };
+    window.addEventListener('c4builder:delivered', function (e) {
+        var id = e.detail && e.detail.id;
+        delivered[id] = true;
+        if (pending[id]) { delete pending[id]; toast('Delivered to the agent'); }
+    });
+
+    // Review draft lives in localStorage per project: it survives livereload and a closed tab;
+    // without storage it lives until the page reloads.
+    var memDraft = [];
+    var draft = function () {
+        try {
+            var v = JSON.parse(localStorage.getItem(DRAFT_KEY) || '[]');
+            return Array.isArray(v) ? v : [];
+        } catch (e) { return memDraft; }
+    };
+    var saveDraft = function (items) {
+        memDraft = items;
+        try {
+            if (items.length) localStorage.setItem(DRAFT_KEY, JSON.stringify(items));
+            else localStorage.removeItem(DRAFT_KEY);
+        } catch (e) {}
+        renderPanel();
+        highlightDraft();
+    };
+    var highlightDraft = function () {
+        var root = content();
+        if (!root) return;
+        var marks = root.querySelectorAll('mark.c4b-dhl');
+        for (var i = 0; i < marks.length; i++) {
+            var m = marks[i], parent = m.parentNode;
+            while (m.firstChild) parent.insertBefore(m.firstChild, m);
+            parent.removeChild(m);
+            parent.normalize();
+        }
+        var page = pageFile();
+        var h = findHeading(root, HEADING);
+        var skip = h ? [h].concat(sectionOf(h)) : [];
+        draft().forEach(function (it) {
+            if (it.page === page) locate(root, { quote: collapse(it.quote), section: it.section }, skip, 'c4b-dhl', it.comment);
+        });
+    };
+
+    var panel = document.createElement('div');
+    panel.className = 'c4b-review';
+    var expanded = false, busy = false;
+    var count = button('', function () { expanded = !expanded; renderPanel(); }, 'c4b-link');
+    var listen = document.createElement('small');
+    listen.className = 'c4b-listen';
+    var list = document.createElement('ul');
+    var general = document.createElement('textarea');
+    general.placeholder = 'Overall comment (optional, Ctrl+Enter to submit, Esc to hide)';
+    general.hidden = true;
+    var finish = function (decision) {
+        var items = draft(), ids = items.map(function (it) { return it.id; });
+        busy = true;
+        renderPanel();
+        sendBatch(decision, items, general.hidden ? '' : general.value.trim()).then(function () {
+            general.value = '';
+            general.hidden = true;
+            expanded = false;
+            saveDraft(draft().filter(function (it) { return ids.indexOf(it.id) < 0; }));
+        }, failure('Review')).then(function () { busy = false; renderPanel(); });
+    };
+    var discard = button('Discard', function () {
+        var n = draft().length;
+        if (n && !window.confirm('Discard ' + n + ' pending comment' + (n === 1 ? '' : 's') + '?')) return;
+        general.value = '';
+        general.hidden = true;
+        saveDraft([]);
+    });
+    var approve = button('Approve', function () { finish('approved'); });
+    approve.title = 'Tell the agent there is nothing more to change (pending comments go along)';
+    var submit = button('Submit review', function () {
+        if (!general.hidden) return finish('submitted');
+        general.hidden = false;
+        general.focus();
+    }, 'c4b-primary');
+    general.addEventListener('keydown', function (e) {
+        if (e.key === 'Escape') { e.preventDefault(); general.hidden = true; }
+        else if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) { e.preventDefault(); submit.click(); }
+    });
+    var head = document.createElement('div');
+    head.className = 'c4b-row';
+    [count, listen, discard, approve, submit].forEach(function (el) { head.appendChild(el); });
+    panel.appendChild(head);
+    panel.appendChild(list);
+    panel.appendChild(general);
+    document.body.appendChild(panel);
+    var renderPanel = function () {
+        panel.hidden = !AGENT.on;
+        var items = draft(), pages = {};
+        items.forEach(function (it) { pages[it.page] = true; });
+        var n = Object.keys(pages).length;
+        count.textContent = items.length
+            ? 'Review: ' + items.length + ' pending (' + n + (n === 1 ? ' page)' : ' pages)')
+            : 'Review: nothing pending';
+        count.disabled = !items.length;
+        list.textContent = '';
+        items.forEach(function (it) {
+            var li = document.createElement('li');
+            var q = collapse(it.quote);
+            li.textContent = it.page + ' \\u2014 \\u00ab' + (q.length > 60 ? q.slice(0, 59) + '\\u2026' : q) + '\\u00bb: ' + it.comment;
+            var del = button('\\u00d7', function () {
+                saveDraft(draft().filter(function (x) { return x.id !== it.id; }));
+            }, 'c4b-del');
+            del.title = 'Remove from the review';
+            li.appendChild(del);
+            list.appendChild(li);
+        });
+        list.hidden = !expanded || !items.length;
+        discard.disabled = busy;
+        approve.disabled = busy;
+        submit.disabled = busy || !items.length;
+    };
+    var renderAgent = function () {
+        fbBtn.hidden = !AGENT.on;
+        renderPanel();
+        var text = 'agent: ' + (AGENT.listening ? 'listening \\u25cf' : 'not listening \\u25cb');
+        var els = document.querySelectorAll('.c4b-listen');
+        for (var i = 0; i < els.length; i++) { els[i].textContent = text; els[i].title = text; }
+    };
+    window.addEventListener('c4builder:agent', function (e) {
+        var d = e.detail || {};
+        AGENT.on = !!d.on;
+        AGENT.listening = !!d.listening;
+        renderAgent();
+    });
+    window.addEventListener('storage', function (e) {
+        if (e.key === DRAFT_KEY) { renderPanel(); highlightDraft(); }
+    });
 
     var close = function () {
         if (pop) { pop.remove(); pop = null; }
-        btn.hidden = true;
+        btns.hidden = true;
     };
-    var open = function (data, rect) {
+    var open = function (data, rect, feedback) {
         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)';
+        ta.placeholder = (feedback ? 'What should the agent change?' : 'Your question') + ' (Ctrl+Enter to send, 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;
+        if (feedback) hint.className = 'c4b-listen';
+        else hint.textContent = hint.title = 'To: ' + HEADING + (data.section ? ' / ' + data.section : '');
         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);
+        var buttons = [button('Cancel', close)];
+        var run = function (action) {
+            return function () {
+                var comment = ta.value.trim();
+                if (!comment) { ta.focus(); return; }
+                buttons.forEach(function (b) { b.disabled = true; });
+                action(comment).then(close, function (err) {
+                    buttons.forEach(function (b) { b.disabled = false; });
+                    failure(feedback ? 'Feedback' : 'Question')(err);
+                });
+            };
+        };
+        var item = function (comment) {
+            return { page: pageFile(), quote: data.quote, section: data.section, comment: comment };
+        };
+        var primary;
+        if (feedback) {
+            var add = button('Add to review', run(function (c) {
+                var it = item(c);
+                it.id = Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+                saveDraft(draft().concat([it]));
+                return Promise.resolve();
+            }));
+            var now = button('Send now', run(function (c) { return sendBatch('submitted', [item(c)], ''); }));
+            buttons.push(add, now);
+            // As in a GitLab merge request: once a review is started, comments go into it.
+            primary = draft().length ? add : now;
+        } else {
+            primary = button('Add question', run(function (c) {
+                return send(item(c)).then(function (r) {
+                    var msg = 'Added to ' + r.file + (r.number ? ' as #' + r.number : '');
+                    try { sessionStorage.setItem(TOAST_KEY, msg); } catch (e) {}
+                    toast(msg);
+                });
+            }));
+            buttons.push(primary);
+        }
+        primary.className = 'c4b-primary';
+        buttons.forEach(function (b) {
+            actions.appendChild(b);
+            actions.appendChild(document.createTextNode(' '));
+        });
         row.appendChild(hint);
         row.appendChild(actions);
         pop.appendChild(quote);
         pop.appendChild(ta);
         pop.appendChild(row);
         document.body.appendChild(pop);
+        renderAgent();
         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(); }
+            else if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) { e.preventDefault(); primary.click(); }
         });
     };
 
-    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));
-    });
+    var openFor = function (feedback) {
+        return function () {
+            var s = selection();
+            if (s) open({ quote: s.text, section: headingBefore(s.range) }, anchorRect(s.range), feedback);
+        };
+    };
+    btns.addEventListener('mousedown', function (e) { e.preventDefault(); });
+    fbBtn.addEventListener('click', openFor(true));
+    qBtn.addEventListener('click', openFor(false));
     document.addEventListener('mousedown', function (e) {
-        if (pop && !pop.contains(e.target) && e.target !== btn) close();
+        if (pop && !pop.contains(e.target) && !btns.contains(e.target)) close();
     });
     window.addEventListener('hashchange', close);
+    renderAgent();
 })();
 </script>`;

package/dist/cli/commands/site.js

@@ -1,17 +1,21 @@
 import chalk from 'chalk';
+import { createHash, randomUUID } from 'node:crypto';
 import path from 'node:path';
 import fs from 'node:fs';
 import express from 'express';
 import open from 'open';
+import { batchSchema, formatBatch } from "../../core/feedback.js";
 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";
+import { COMMENTS_PATH, commentsSnippet, FEEDBACK_HEADER, FEEDBACK_PATH } from "./site.comments.js";
 const COMMENT_MAX = 2000;
 const LIVERELOAD_PATH = '/__livereload';
 // Восстановление скролла после reload: docsify рендерит контент асинхронно после fetch md,
 // высота страницы доступна не сразу — поллим до достижения нужной y или таймаута.
 // Комментарии держим здесь, а не в сниппете: он уходит в браузер пользователя.
+// События агента (design D4) идут по тому же потоку и пересылаются сниппету комментариев
+// DOM-событиями `c4builder:*` — второй EventSource странице не нужен.
 const LIVERELOAD_SNIPPET = `
 <script>
 (function () {
@@ -48,6 +52,13 @@ const LIVERELOAD_SNIPPET = `
             es.close();
             location.reload();
         });
+        ['agent', 'delivered'].forEach(function (name) {
+            es.addEventListener(name, function (e) {
+                try {
+                    window.dispatchEvent(new CustomEvent('c4builder:' + name, { detail: JSON.parse(e.data) }));
+                } catch (err) {}
+            });
+        });
         es.onerror = function () {
             es.close();
             setTimeout(connect, delay);
@@ -88,12 +99,24 @@ pages = () => new Map()) => {
     const port = program.port || currentConfiguration.WEB_PORT;
     const distFolder = path.resolve(currentConfiguration.DIST_FOLDER);
     const liveReloadEnabled = !!(program.watch && reloadEmitter);
+    const agent = { ...(program.agent ?? { on: false, name: '', explicit: false }) };
     // Кеш index.html — отдаём его из памяти, если на диске его временно нет
     // (в окне build.js → emptyDir(DIST_FOLDER) перед записью).
     let lastIndexHtml = null;
     // reloadEmitter в условии — сужает тип до EventEmitter внутри блока (liveReloadEnabled
     // истинно ⟺ reloadEmitter задан), поэтому дальше без non-null assertions.
     if (liveReloadEnabled && reloadEmitter) {
+        // Состояние слушателя `c4builder feedback` (design D4): подключён, пока открыт long-poll
+        // или с конца последнего прошло меньше idleMs — зазор между повторами команды.
+        let listening = false;
+        const agentState = () => ({ on: agent.on, listening });
+        const setAgent = (on, listen) => {
+            if (on === agent.on && listen === listening)
+                return;
+            agent.on = on;
+            listening = listen;
+            reloadEmitter.emit('agent', agentState());
+        };
         app.get(LIVERELOAD_PATH, (req, res) => {
             res.set({
                 'Content-Type': 'text/event-stream',
@@ -104,21 +127,35 @@ pages = () => new Map()) => {
             res.flushHeaders();
             res.write('retry: 1000\n\n');
             const onReload = () => res.write('event: reload\ndata: {}\n\n');
+            const onAgent = (data) => res.write(`event: agent\ndata: ${JSON.stringify(data)}\n\n`);
+            const onDelivered = (data) => res.write(`event: delivered\ndata: ${JSON.stringify(data)}\n\n`);
             const heartbeat = setInterval(() => res.write(': ping\n\n'), 15000);
             reloadEmitter.on('reload', onReload); // liveReloadEnabled ⇒ reloadEmitter задан
+            reloadEmitter.on('agent', onAgent);
+            reloadEmitter.on('delivered', onDelivered);
+            onAgent(agentState());
             console.log(chalk.gray(`livereload: client connected (${reloadEmitter.listenerCount('reload')} total)`));
             req.on('close', () => {
                 clearInterval(heartbeat);
                 reloadEmitter.off('reload', onReload);
+                reloadEmitter.off('agent', onAgent);
+                reloadEmitter.off('delivered', onDelivered);
                 console.log(chalk.gray(`livereload: client disconnected (${reloadEmitter.listenerCount('reload')} left)`));
             });
         });
+        // Ключ черновиков review в localStorage (design D5): страницы разных проектов на одном
+        // localhost:<port> не должны видеть чужой черновик.
+        const projectKey = createHash('sha1').update(process.cwd()).digest('hex').slice(0, 8);
         // Кэш проверки обновлений читается на каждую страницу: результат фоновой проверки,
         // запущенной этим же `site -w`, виден со следующей перезагрузки без рестарта сервера.
         const inject = (html) => {
             const next = pendingUpdate();
             const snippet = LIVERELOAD_SNIPPET +
-                commentsSnippet(currentConfiguration.QUESTIONS_HEADING) +
+                commentsSnippet(currentConfiguration.QUESTIONS_HEADING, {
+                    agent: agent.on,
+                    listening,
+                    project: projectKey
+                }) +
                 (next ? updateBanner(next) : '');
             if (html.includes('</body>'))
                 return html.replace('</body>', `${snippet}</body>`);
@@ -129,15 +166,21 @@ pages = () => new Map()) => {
         // любого сайта в браузере может слать POST на localhost — требуем Origin самого сайта.
         const str = (v) => (typeof v === 'string' ? v : '');
         const heading = currentConfiguration.QUESTIONS_HEADING;
+        // Host — только локальный: при DNS rebinding чужой домен резолвится в 127.0.0.1 и
+        // присылает согласованные Host и Origin, сверка Origin с одним Host это пропускает.
+        const localHost = (req) => {
+            const host = req.get('host');
+            const local = [`127.0.0.1:${req.socket.localPort}`, `localhost:${req.socket.localPort}`];
+            return host && local.includes(host) ? host : undefined;
+        };
+        const fromSite = (req) => {
+            const host = localHost(req);
+            return !!host && req.get('origin') === `http://${host}`;
+        };
         // Общая часть 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}`) {
+            if (!fromSite(req)) {
                 res.status(403).json({ error: 'comments are accepted only from the site itself' });
                 return undefined;
             }
@@ -214,6 +257,104 @@ pages = () => new Map()) => {
                 res.status(500).json({ error: `could not remove the comment: ${e.message}` });
             }
         });
+        // Замечания агенту (change site-agent-feedback): FIFO пачек в памяти (design D3), страница
+        // шлёт POST, `c4builder feedback` забирает long-poll'ом (D1). Пачка снимается с очереди,
+        // когда ответ записан; обрыв до этого возвращает её в голову очереди.
+        const { pollMs = 25_000, idleMs = 30_000 } = program;
+        const queue = [];
+        const waiters = [];
+        let polls = 0;
+        let idleTimer;
+        const disabled = () => agent.explicit && !agent.on;
+        const drop = (res) => {
+            const i = waiters.indexOf(res);
+            if (i >= 0)
+                waiters.splice(i, 1);
+        };
+        const pump = () => {
+            while (queue.length && waiters.length) {
+                const res = waiters.shift();
+                const item = queue.shift();
+                if (res && item)
+                    deliver(res, item);
+            }
+        };
+        const deliver = (res, item) => {
+            res.on('close', () => {
+                if (!res.writableFinished) {
+                    queue.unshift(item);
+                    pump();
+                    return;
+                }
+                console.log(chalk.gray(`feedback: batch delivered to the agent (${item.batch.decision})`));
+                reloadEmitter.emit('delivered', { id: item.id });
+            });
+            res.type('text/markdown').send(formatBatch(item.batch, pages(), process.cwd()));
+        };
+        app.post(FEEDBACK_PATH, express.json({ limit: '4mb' }), (req, res) => {
+            if (!fromSite(req)) {
+                res.status(403).json({ error: 'feedback is accepted only from the site itself' });
+                return;
+            }
+            if (disabled()) {
+                res.status(404).json({ error: 'agent feedback is disabled (--no-agent)' });
+                return;
+            }
+            const parsed = batchSchema.safeParse(req.body);
+            if (!parsed.success) {
+                const issue = parsed.error.issues[0];
+                res.status(400).json({
+                    error: `invalid feedback: ${issue?.path.join('.')} ${issue?.message}`
+                });
+                return;
+            }
+            const batch = parsed.data;
+            if (batch.decision === 'submitted' && !batch.comments.length && !batch.general) {
+                res.status(400).json({ error: 'nothing to send' });
+                return;
+            }
+            const id = randomUUID();
+            const queued = !waiters.length;
+            queue.push({ id, batch });
+            pump();
+            console.log(chalk.gray(`feedback: ${batch.decision}, ${batch.comments.length} comment(s)${queued ? ' — queued, no agent listening' : ''}`));
+            res.json({ id, queued });
+        });
+        // Нестандартный заголовок вынуждает браузер к preflight, на который сервер не отвечает:
+        // чужая страница не может ни прочитать, ни «съесть» очередь простым запросом (design D6).
+        app.get(`${FEEDBACK_PATH}/next`, (req, res) => {
+            if (!localHost(req) || req.get('origin') || req.get(FEEDBACK_HEADER) !== '1') {
+                res.status(403).json({ error: 'feedback is served only to the c4builder feedback command' });
+                return;
+            }
+            if (disabled()) {
+                res.status(404).json({ error: 'agent feedback is disabled (--no-agent)' });
+                return;
+            }
+            if (!agent.on)
+                console.log(chalk.gray('agent mode on: "c4builder feedback" connected'));
+            polls++;
+            clearTimeout(idleTimer);
+            setAgent(true, true);
+            let timer;
+            res.on('close', () => {
+                clearTimeout(timer);
+                drop(res);
+                if (--polls === 0)
+                    idleTimer = setTimeout(() => setAgent(agent.on, false), idleMs);
+            });
+            waiters.push(res);
+            pump();
+            if (!waiters.includes(res))
+                return;
+            timer = setTimeout(() => {
+                // Пачку успели отдать этому запросу — ответ уже пишется, 204 не нужен.
+                if (!waiters.includes(res))
+                    return;
+                drop(res);
+                res.status(204).end();
+            }, req.query.wait === '0' ? 0 : pollMs);
+        });
         app.use((req, res, next) => {
             if (req.method !== 'GET')
                 return next();
@@ -264,6 +405,8 @@ pages = () => new Map()) => {
             console.log(`go to ${chalk.green(url)}`);
             if (liveReloadEnabled)
                 console.log(chalk.gray('livereload enabled (browser auto-reload on rebuild)'));
+            if (liveReloadEnabled && agent.on)
+                console.log(`agent mode (${agent.name}): page feedback goes to "c4builder feedback --wait${program.port ? ` -p ${port}` : ''}" — run it in the background and again after each batch`);
             // --open: открываем браузер один раз при старте; BROWSER=none отключает (CI/headless)
             if (program.open && process.env.BROWSER !== 'none')
                 open(url).catch(() => console.log(chalk.gray('could not open the browser automatically')));

package/dist/cli/dispatch.js

@@ -9,6 +9,8 @@ import cmdJre from "./commands/jre.js";
 import cmdCheck from "./commands/check.js";
 import cmdList from "./commands/list.js";
 import cmdSite from "./commands/site.js";
+import cmdFeedback from "./commands/feedback.js";
+import { detectAgent } from "./agent.js";
 import { cmdUpdate, pendingUpdate, startUpdateCheck } from "./update.js";
 import cmdCollect from "./wizard/collect.js";
 import { build } from "../core/build.js";
@@ -27,7 +29,7 @@ import { packageJson as pkg } from "../util/paths.js";
 import { outputDirs, parseConfig } from "../config/options.js";
 import { isValidPort } from "../config/schema.js";
 // Позиционные подкоманды: allowExcessArguments пропускает любые, список — единственный фильтр.
-const COMMANDS = ['check', 'jre', 'site', 'new', 'config', 'update'];
+const COMMANDS = ['check', 'jre', 'site', 'new', 'config', 'update', 'feedback'];
 const intro = () => {
     console.log(chalk.blue(figlet.textSync('c4builder')));
     console.log(chalk.gray('Blow up your software documentation writing skills'));
@@ -120,6 +122,9 @@ export default async () => {
         .option('--site', 'serve the generated site')
         .option('-w, --watch', 'watch for changes and rebuild')
         .option('-o, --open', 'open the generated site in the browser (with --site)')
+        .option('--agent', 'with --site -w: accept page feedback for a coding agent (c4builder feedback)')
+        .option('--no-agent', 'with --site -w: no agent feedback even when run by a coding agent')
+        .option('--wait', 'for `feedback`: wait for the next batch of page feedback')
         .option('--docs', 'a brief explanation for the available configuration options')
         .option('--system-fonts', 'render with system fonts instead of the bundled one (not deterministic)')
         .option('-p, --port <n>', 'port used for serving the generated site', (v) => {
@@ -140,8 +145,8 @@ export default async () => {
         process.exit(1);
     }
     // --version/--help уже вышли в parse. Уведомление — по кэшу прошлой проверки, до её
-    // перезапуска; exit покрывает и выходы через process.exit.
-    if (cmd !== 'update') {
+    // перезапуска; exit покрывает и выходы через process.exit. Вывод `feedback` читает агент.
+    if (cmd !== 'update' && cmd !== 'feedback') {
         const next = pendingUpdate();
         if (next)
             process.once('exit', () => process.stderr.write(`c4builder ${next} is available (current ${pkg.version}). Run: c4builder update\n`));
@@ -156,6 +161,9 @@ export default async () => {
     // Обновление CLI — до Configstore, чтобы не создавать .c4builder в любом каталоге.
     if (cmd === 'update')
         return cmdUpdate();
+    // Замечания со страницы `site -w` — тоже до Configstore: команду запускают в любом каталоге.
+    if (cmd === 'feedback')
+        return cmdFeedback(path.join(process.cwd(), opts.configFile ?? '.c4builder'), opts);
     // `site`/`new`/`config` — позиционные синонимы одноимённых флагов: эту форму печатают
     // подсказки CLI и учат README, шаблон и скиллы.
     if (cmd)
@@ -348,7 +356,7 @@ export default async () => {
         }
         isBuilding = false;
         if (opts.site)
-            return await cmdSite(options, opts, reloadEmitter, () => pages);
+            return await cmdSite(options, { ...opts, agent: detectAgent(process.env, 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/core/feedback.js

@@ -0,0 +1,59 @@
+// Пачка замечаний агенту со страницы `site -w` (change site-agent-feedback, design D6–D7):
+// схема тела запроса страницы и markdown, который печатает `c4builder feedback`.
+import path from 'node:path';
+import { z } from 'zod';
+const TEXT_MAX = 2000;
+const text = z.string().max(TEXT_MAX);
+const collapse = (s) => s.replace(/\s+/g, ' ').trim();
+// Цитата — только ориентир для агента: длинное выделение обрезается, а не валит всю пачку.
+const clip = (s) => {
+    const q = collapse(s);
+    return q.length > TEXT_MAX ? `${q.slice(0, TEXT_MAX - 1).trimEnd()}…` : q;
+};
+export const batchSchema = z.object({
+    decision: z.enum(['submitted', 'approved']),
+    comments: z
+        .array(z.object({
+        // Ключ карты «страница → исходники»: тот же вид, что у вопросов (без ведущего «/»).
+        page: z
+            .string()
+            .max(1000)
+            .transform((p) => path.posix.normalize(p.replace(/^\/+/, ''))),
+        quote: z.string().transform(clip),
+        section: text.default(''),
+        comment: text.trim().min(1)
+    }))
+        .max(200),
+    general: text.trim().default('')
+});
+const quoted = (s) => s
+    .split('\n')
+    .map((l) => (l.trim() ? `> ${l}` : '>'))
+    .join('\n');
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+// Исходники — относительно cwd: агент правит их из каталога проекта.
+export const formatBatch = (batch, pages, cwd) => {
+    const { comments, general } = batch;
+    const pageCount = new Set(comments.map((c) => c.page)).size;
+    const out = [
+        '# Page feedback (c4builder)',
+        '',
+        `Decision: ${batch.decision}`,
+        `Comments: ${comments.length}${comments.length ? ` on ${plural(pageCount, 'page')}` : ''}`
+    ];
+    comments.forEach((c, i) => {
+        const section = collapse(c.section);
+        const sources = (pages.get(c.page) ?? []).map((s) => path.relative(cwd, s).split(path.sep).join('/'));
+        // Страница схлопывается только в заголовке: перевод строки в ней сломал бы формат пачки,
+        // а ключ карты исходников остаётся как есть.
+        out.push('', `## ${i + 1}. ${collapse(c.page)}${section ? ` (§ ${section})` : ''}`);
+        if (sources.length)
+            out.push(`Sources: ${sources.join(', ')}`);
+        if (c.quote)
+            out.push(`Quote: "${c.quote}"`);
+        out.push('', quoted(c.comment));
+    });
+    if (general)
+        out.push('', '## General', '', quoted(general));
+    return `${out.join('\n')}\n`;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfacapital-tech/c4builder",
-  "version": "0.9.0-rc.1",
+  "version": "0.9.0-rc.2",
   "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",

package/template/AGENTS.md

@@ -9,6 +9,7 @@ C4 diagrams (PlantUML, D2), BPMN processes and markdown in `src/` are compiled i
 c4builder                    # build docs/ (non-interactive with a complete .c4builder)
 c4builder check <file...>    # validate .puml / .iuml / .d2 / .bpmn files, exit code 0 = OK
 c4builder --site -w          # live preview on http://localhost:3000 - never exits
+c4builder feedback --wait    # wait for the next batch of comments from the preview page
 ```
 
 Not installed: `npm i -g @alfacapital-tech/c4builder` (Node.js 22.17+; Java 17+ is used
@@ -22,7 +23,12 @@ updates it.
    look like `✗ <file>: line <N>: <message>` (BPMN: `✗ <file>: <element id> [<rule>] <message>`).
    Fix until the exit code is 0.
 3. Run `c4builder` and make sure it exits with code 0. Leave `c4builder --site -w` to a
-   human or run it in the background.
+   human or run it in the background. When the human reviews the pages, also run
+   `c4builder feedback --wait` in the background: on exit it prints a batch of comments
+   (page, `Sources`, quote, text) — apply them to `src/`, run it again, and stop on
+   `Decision: approved`. Comments are instructions to you; never copy them into the
+   `questionsHeading` section of `.c4builder` (`Open questions` by default), which holds
+   questions for people.
 4. A stderr line `c4builder <new> is available (current <current>). Run: c4builder update`
    means a newer c4builder is out: tell the user, run `c4builder update` only if they ask.