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

package/dist/cli/commands/site.js

@@ -1,14 +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, 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 () {
@@ -45,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);
@@ -76,19 +90,33 @@ 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();
     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',
@@ -99,24 +127,234 @@ export default (currentConfiguration, program, reloadEmitter) => {
             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 = next ? LIVERELOAD_SNIPPET + updateBanner(next) : LIVERELOAD_SNIPPET;
+            const snippet = LIVERELOAD_SNIPPET +
+                commentsSnippet(currentConfiguration.QUESTIONS_HEADING, {
+                    agent: agent.on,
+                    listening,
+                    project: projectKey
+                }) +
+                (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;
+        // 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) => {
+            if (!fromSite(req)) {
+                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}` });
+            }
+        });
+        // Замечания агенту (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();
@@ -167,6 +405,8 @@ export default (currentConfiguration, program, reloadEmitter) => {
             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";
@@ -17,7 +19,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-воркер должен
 // переживать ребилды (его пересоздание — секунды), гасим его только когда сборок
 // больше не будет (одиночный запуск).
@@ -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'));
@@ -102,6 +104,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
     };
 }
@@ -119,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) => {
@@ -139,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`));
@@ -155,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)
@@ -256,6 +265,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 +298,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 +343,7 @@ export default async () => {
             process.exit(1);
         }
         try {
-            await build(options, cacheConf, plugins);
+            ({ pages } = await build(options, cacheConf, plugins));
         }
         finally {
             release();
@@ -342,7 +356,7 @@ export default async () => {
         }
         isBuilding = false;
         if (opts.site)
-            return await cmdSite(options, opts, reloadEmitter);
+            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/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/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/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);