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

package/dist/cli/commands/site.js

@@ -4,7 +4,7 @@ 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 { batchSchema, formatBatch, LISTENER_NAME } 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";
@@ -103,20 +103,51 @@ pages = () => new Map()) => {
     // Кеш index.html — отдаём его из памяти, если на диске его временно нет
     // (в окне build.js → emptyDir(DIST_FOLDER) перед записью).
     let lastIndexHtml = null;
+    let sweeper;
     // 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)
+        // Ящики слушателей `c4builder feedback --as <name>` (change feedback-mailboxes, D3–D4).
+        // Слушает, пока открыт long-poll или с конца последнего прошло меньше idleMs — зазор между
+        // повторами команды. Пачки без адресата (ящиков ещё не было) достаются любому имени.
+        const { pollMs = 25_000, idleMs = 30_000, mailboxTtlMs = 30 * 60_000 } = program;
+        const mailboxes = new Map();
+        const unaddressed = [];
+        const box = (name) => {
+            const b = mailboxes.get(name) ?? {
+                queue: [],
+                waiters: [],
+                polls: 0,
+                listening: false,
+                lastSeen: Date.now()
+            };
+            mailboxes.set(name, b);
+            return b;
+        };
+        const agentState = () => ({
+            on: agent.on,
+            mailboxes: [...mailboxes].map(([name, b]) => ({
+                name,
+                state: b.listening ? 'listening' : 'reconnecting',
+                queued: b.queue.length
+            }))
+        });
+        // Событие — только когда снимок изменился: publish зовётся после любой смены очередей.
+        let published = JSON.stringify(agentState());
+        const publish = () => {
+            const state = agentState();
+            const json = JSON.stringify(state);
+            if (json === published)
                 return;
-            agent.on = on;
-            listening = listen;
-            reloadEmitter.emit('agent', agentState());
+            published = json;
+            reloadEmitter.emit('agent', state);
         };
+        sweeper = setInterval(() => {
+            for (const [name, b] of mailboxes)
+                if (!b.polls && !b.queue.length && Date.now() - b.lastSeen >= mailboxTtlMs)
+                    mailboxes.delete(name);
+            publish();
+        }, Math.min(mailboxTtlMs, 60_000)).unref();
         app.get(LIVERELOAD_PATH, (req, res) => {
             res.set({
                 'Content-Type': 'text/event-stream',
@@ -153,8 +184,9 @@ pages = () => new Map()) => {
             const snippet = LIVERELOAD_SNIPPET +
                 commentsSnippet(currentConfiguration.QUESTIONS_HEADING, {
                     agent: agent.on,
-                    listening,
-                    project: projectKey
+                    mailboxes: agentState().mailboxes,
+                    project: projectKey,
+                    language: currentConfiguration.UI_LANGUAGE
                 }) +
                 (next ? updateBanner(next) : '');
             if (html.includes('</body>'))
@@ -259,35 +291,39 @@ pages = () => new Map()) => {
         });
         // Замечания агенту (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);
+        const drop = (b, res) => {
+            const i = b.waiters.indexOf(res);
             if (i >= 0)
-                waiters.splice(i, 1);
+                b.waiters.splice(i, 1);
         };
-        const pump = () => {
-            while (queue.length && waiters.length) {
-                const res = waiters.shift();
-                const item = queue.shift();
+        const pump = (name, b) => {
+            for (;;) {
+                const source = b.queue.length ? b.queue : unaddressed;
+                if (!source.length || !b.waiters.length)
+                    return;
+                const res = b.waiters.shift();
+                const item = source.shift();
                 if (res && item)
-                    deliver(res, item);
+                    deliver(name, res, item, source);
             }
         };
-        const deliver = (res, item) => {
+        const pumpAll = () => {
+            for (const [name, b] of mailboxes)
+                pump(name, b);
+        };
+        const deliver = (name, res, item, source) => {
             res.on('close', () => {
                 if (!res.writableFinished) {
-                    queue.unshift(item);
-                    pump();
-                    return;
+                    source.unshift(item);
+                    pumpAll();
                 }
-                console.log(chalk.gray(`feedback: batch delivered to the agent (${item.batch.decision})`));
-                reloadEmitter.emit('delivered', { id: item.id });
+                else {
+                    console.log(chalk.gray(`feedback: batch delivered to ${name} (${item.batch.decision})`));
+                    reloadEmitter.emit('delivered', { id: item.id, to: name });
+                }
+                publish();
             });
             res.type('text/markdown').send(formatBatch(item.batch, pages(), process.cwd()));
         };
@@ -308,17 +344,21 @@ pages = () => new Map()) => {
                 });
                 return;
             }
-            const batch = parsed.data;
+            const { to, ...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 });
+            // Ящик адресата создаётся и здесь: выбранный на вкладке адресат не теряется, даже если
+            // его пустой ящик успели удалить.
+            const target = to === undefined ? undefined : box(to);
+            const queued = !(target ? [target] : [...mailboxes.values()]).some((b) => b.waiters.length);
+            (target?.queue ?? unaddressed).push({ id, batch });
+            pumpAll();
+            publish();
+            console.log(chalk.gray(`feedback for ${to ?? 'any listener'}: ${batch.decision}, ${batch.comments.length} comment(s)${queued ? ' — queued, not listening' : ''}`));
+            res.json({ id, queued, to });
         });
         // Нестандартный заголовок вынуждает браузер к preflight, на который сервер не отвечает:
         // чужая страница не может ни прочитать, ни «съесть» очередь простым запросом (design D6).
@@ -331,27 +371,41 @@ pages = () => new Map()) => {
                 res.status(404).json({ error: 'agent feedback is disabled (--no-agent)' });
                 return;
             }
+            const name = req.query.as;
+            if (typeof name !== 'string' || !LISTENER_NAME.test(name)) {
+                res.status(400).json({
+                    error: '--as <name> is required: 1-64 letters, digits, ".", "_" or "-" (c4builder feedback --wait --as <name>)'
+                });
+                return;
+            }
             if (!agent.on)
-                console.log(chalk.gray('agent mode on: "c4builder feedback" connected'));
-            polls++;
-            clearTimeout(idleTimer);
-            setAgent(true, true);
+                console.log(chalk.gray(`agent mode on: "c4builder feedback --as ${name}" connected`));
+            agent.on = true;
+            const b = box(name);
+            b.polls++;
+            b.listening = true;
+            clearTimeout(b.idle);
+            publish();
             let timer;
             res.on('close', () => {
                 clearTimeout(timer);
-                drop(res);
-                if (--polls === 0)
-                    idleTimer = setTimeout(() => setAgent(agent.on, false), idleMs);
+                drop(b, res);
+                b.lastSeen = Date.now();
+                if (--b.polls === 0)
+                    b.idle = setTimeout(() => {
+                        b.listening = false;
+                        publish();
+                    }, idleMs);
             });
-            waiters.push(res);
-            pump();
-            if (!waiters.includes(res))
+            b.waiters.push(res);
+            pump(name, b);
+            if (!b.waiters.includes(res))
                 return;
             timer = setTimeout(() => {
                 // Пачку успели отдать этому запросу — ответ уже пишется, 204 не нужен.
-                if (!waiters.includes(res))
+                if (!b.waiters.includes(res))
                     return;
-                drop(res);
+                drop(b, res);
                 res.status(204).end();
             }, req.query.wait === '0' ? 0 : pollMs);
         });
@@ -406,12 +460,13 @@ pages = () => new Map()) => {
             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`);
+                console.log(`agent mode (${agent.name}): page feedback goes to "c4builder feedback --wait --as <name>${program.port ? ` -p ${port}` : ''}" — run it in the background, <name> is your change or task; run it again with the same name 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')));
             resolve(server);
         });
+        server.on('close', () => clearInterval(sweeper));
         server.on('error', (err) => {
             if (err.code === 'EADDRINUSE') {
                 console.log(chalk.red(`port ${port} is already in use — pass a different one with -p <port>`));

package/dist/cli/dispatch.js

@@ -25,6 +25,7 @@ import { acquireBuildLock, BuildLockHeldError, waitBuildLock } from "../util/loc
 // больше не будет (одиночный запуск).
 import { teardownD2 } from "../core/render/d2renderer.js";
 import { teardownBpmn } from "../core/render/bpmnrenderer.js";
+import { teardownMermaid } from "../core/render/mermaidrenderer.js";
 import { packageJson as pkg } from "../util/paths.js";
 import { outputDirs, parseConfig } from "../config/options.js";
 import { isValidPort } from "../config/schema.js";
@@ -105,6 +106,7 @@ function getOptions(c) {
         EXCLUDE_OTHER_FILES: c.excludeOtherFiles,
         USE_SYSTEM_FONTS: c.useSystemFonts,
         QUESTIONS_HEADING: c.questionsHeading,
+        UI_LANGUAGE: c.uiLanguage,
         PLUGINS: c.plugins
     };
 }
@@ -125,6 +127,7 @@ export default async () => {
         .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('--as <name>', 'for `feedback`: listener name (your change or task) — the page sends batches to it')
         .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) => {
@@ -352,6 +355,7 @@ export default async () => {
             if (!opts.watch) {
                 await teardownD2();
                 await teardownBpmn();
+                await teardownMermaid();
             }
         }
         isBuilding = false;

package/dist/config/defaults.js

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

package/dist/config/schema.js

@@ -60,6 +60,8 @@ export const configSchema = z.object({
     // Заголовок раздела, куда `site -w` дописывает комментарии к странице (в коде кириллицы
     // быть не может — русский заголовок задаёт сам проект).
     questionsHeading: str(defaultConfig.questionsHeading),
+    // Язык интерфейса страницы `site -w`; `auto` — по языку браузера (change site-ui-language).
+    uiLanguage: z.preprocess(strPre, z.enum(['auto', 'en', 'ru'], 'expected auto, en or ru').default(defaultConfig.uiLanguage)),
     // Задаются явно (флаг/промпт) либо тонкой правкой файла — в defaultConfig не входят.
     projectName: optStr(),
     webFileName: optStr(),

package/dist/core/compose/markdown.js

@@ -223,7 +223,7 @@ export const generateLlmsTxt = (tree, options) => {
     });
     return (`# ${options.PROJECT_NAME}\n\n` +
         '> Architecture documentation built with c4builder. Pages are markdown; full text with ' +
-        'diagram sources (PlantUML/D2/BPMN): [llms-full.txt](llms-full.txt).\n\n' +
+        'diagram sources (PlantUML/D2/BPMN/Mermaid): [llms-full.txt](llms-full.txt).\n\n' +
         `## Pages\n\n${pages.join('')}`);
 };
 // Fence длиннее самой длинной серии обратных кавычек текста — иначе блок закрылся бы изнутри.
@@ -235,7 +235,8 @@ const FENCE_LANG = {
     '.puml': 'plantuml',
     '.iuml': 'plantuml',
     '.d2': 'd2',
-    '.bpmn': 'xml'
+    '.bpmn': 'xml',
+    '.mmd': 'mermaid'
 };
 // llms-full.txt: состав complete-документа, но диаграмма — исходником (C4-PlantUML/D2-текст
 // агенту полезнее SVG). Локальные include/импорты — один раз в приложении, а не инлайном:

package/dist/core/feedback.js

@@ -10,7 +10,10 @@ const clip = (s) => {
     const q = collapse(s);
     return q.length > TEXT_MAX ? `${q.slice(0, TEXT_MAX - 1).trimEnd()}…` : q;
 };
+// Имя слушателя `c4builder feedback --as` и адресат пачки (change feedback-mailboxes, D1).
+export const LISTENER_NAME = /^[A-Za-z0-9._-]{1,64}$/;
 export const batchSchema = z.object({
+    to: z.string().regex(LISTENER_NAME).optional(),
     decision: z.enum(['submitted', 'approved']),
     comments: z
         .array(z.object({

package/dist/core/render/bpmnrenderer.js

@@ -10,7 +10,7 @@ import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import chalk from 'chalk';
 import { DEFAULT_FONT_NAME } from "./fonts.js";
-import { getResvg, resvgFontOptions } from "./pngraster.js";
+import { ASCENT, DESCENT, clearTextWidths, textWidth } from "./textmetrics.js";
 // Третий бэкенд рендера: BPMN 2.0 XML без координат → валидация (bpmnlint) → раскладка
 // (bpmn-auto-layout) → рендер bpmn-js в jsdom → SVG. Все пакеты — optionalDependencies,
 // грузятся лениво при первом .bpmn: проекты без BPMN их не трогают (как D2).
@@ -112,32 +112,7 @@ const C4BUILDER_RULES = {
     })
 };
 // Ширины строк для переноса подписей: diagram-js меряет текст только через
-// canvas.measureText, а jsdom канваса не умеет. Меряем вендорный Nimbus Sans тем же
-// resvg, что растрирует PNG: ширина = bbox «|текст|» минус bbox «||» — так получается
-// advance-ширина с пробелами по краям, а не ширина чернил. Режим системных шрифтов на
-// BPMN не влияет (как и на D2): детерминизм важнее.
-const widthMemo = new Map();
-const escapeXml = (s) => s.replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' })[c]);
-const inkWidth = (text, size) => {
-    const { Resvg } = getResvg();
-    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"><text y="${size}" ` +
-        `font-family="${DEFAULT_FONT_NAME}" font-size="${size}" xml:space="preserve">${escapeXml(text)}</text></svg>`;
-    return new Resvg(svg, { font: resvgFontOptions(false) }).getBBox()?.width ?? 0;
-};
-const textWidth = (text, size) => {
-    const key = `${size}\0${text}`;
-    let width = widthMemo.get(key);
-    if (width === undefined) {
-        // Округление гасит f32-шум resvg между платформами: координаты текста в SVG
-        // считаются из этой ширины и должны совпадать побайтно.
-        width = Math.round((inkWidth(`|${text}|`, size) - inkWidth('||', size)) * 100) / 100;
-        widthMemo.set(key, width);
-    }
-    return width;
-};
-// hhea Nimbus Sans Regular: ascender 729, descender −271 на 1000 единиц (vendor/fonts).
-const ASCENT = 0.729;
-const DESCENT = 0.271;
+// canvas.measureText, а jsdom канваса не умеет — меряем вендорный шрифт (textmetrics).
 // Полифилы окна jsdom: ровно то, что bpmn-js зовёт при импорте и saveSVG. Трансформации
 // пишутся в атрибут сразу — сериализатор берёт атрибуты, а не baseVal.
 const installPolyfills = (window) => {
@@ -334,7 +309,7 @@ export const teardownBpmn = async () => {
         return;
     const pending = enginePromise;
     enginePromise = null;
-    widthMemo.clear();
+    clearTextWidths();
     try {
         (await pending).window.close();
     }

package/dist/core/render/diagrams.js

@@ -13,6 +13,8 @@ import { httpGetBuffer } from "../../util/http.js";
 import { renderD2, foldD2Imports } from "./d2renderer.js";
 // BPMN-бэкенд: пакеты движка грузятся лениво внутри renderBpmn.
 import { renderBpmn, BPMN_CACHE_PACKAGES } from "./bpmnrenderer.js";
+// Mermaid-бэкенд: пакет движка грузится лениво внутри renderMermaid.
+import { renderMermaid, MERMAID_PACKAGE } from "./mermaidrenderer.js";
 import { resolveJava } from "./jre.js";
 // PNG-выход: SVG обоих движков растеризуется resvg (ленивая загрузка внутри модуля).
 import { rasterizeSvgToPng } from "./pngraster.js";
@@ -65,7 +67,7 @@ const runPool = async (tasks, concurrency) => {
     if (firstError !== undefined)
         throw firstError;
 };
-// Версии пакетов движков (D2, BPMN) для чексуммы кэша (апгрейд движка → перерендер).
+// Версии пакетов движков (D2, BPMN, mermaid) для чексуммы кэша (апгрейд движка → перерендер).
 // Читаем package.json лениво и один раз: pure-PlantUML сборки их не трогают.
 const versionCache = new Map();
 const pkgVersion = (name) => {
@@ -100,7 +102,9 @@ export const renderKey = (diagram, options, outFormat) => (diagram.engine === 'd
     ? `d2\0${pkgVersion('@terrastruct/d2')}\0layout=${options.D2_LAYOUT}\0fmt=${outFormat}`
     : diagram.engine === 'bpmn'
         ? `bpmn\0${BPMN_CACHE_PACKAGES.map(pkgVersion).join('\0')}\0fmt=${outFormat}`
-        : `puml\0${VENDORED_JAR.version}\0charset=${options.CHARSET}\0fmt=${outFormat}\0ditaa=${diagram.isDitaa}`) +
+        : diagram.engine === 'mermaid'
+            ? `mermaid\0${pkgVersion(MERMAID_PACKAGE)}\0fmt=${outFormat}`
+            : `puml\0${VENDORED_JAR.version}\0charset=${options.CHARSET}\0fmt=${outFormat}\0ditaa=${diagram.isDitaa}`) +
     `\0font=${fontCacheTag(options)}`;
 export const getMime = (format) => {
     if (format === 'svg')
@@ -279,19 +283,22 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
     // BPMN рендерится в общем окне jsdom главного потока — параллельность ничего не даёт,
     // а последовательная очередь исключает гонки на общем состоянии бандла bpmn-js.
     const bpmnTasks = [];
+    // Mermaid — так же: своё окно jsdom, глобальный конфиг и подмены на время рендера.
+    const mermaidTasks = [];
     const otherTasks = [];
     for (const item of tree) {
         for (const diagram of item.diagrams) {
             // Чексумма = контент диаграммы + свёрнутый граф её зависимостей, чтобы
             // правка включаемого/импортируемого файла инвалидировала кэш: PlantUML —
-            // !include-граф (.iuml и пр.), D2 — граф @/...@-импортов. У BPMN зависимостей нет.
+            // !include-граф (.iuml и пр.), D2 — граф @/...@-импортов. У BPMN и mermaid их нет.
             const body = `${diagram.content || ''}`;
             const entryPath = path.join(item.dir, diagram.dir);
             const isD2 = diagram.engine === 'd2';
             const isBpmn = diagram.engine === 'bpmn';
+            const isMermaid = diagram.engine === 'mermaid';
             const includes = isD2
                 ? foldD2Imports(entryPath, body)
-                : isBpmn
+                : isBpmn || isMermaid
                     ? ''
                     : foldIncludes(body, item.dir, item.dir, new Set());
             const outFormat = diagramOutputFormat(diagram, options);
@@ -340,12 +347,16 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
                 // Для растеризации PlantUML не-ditaa рендерим в svg (не -tpng), затем resvg.
                 let rendered;
                 try {
+                    // Путь для сообщений движка; у блоков в markdown — их страница.
+                    const file = source ?? path.relative(process.cwd(), entryPath).split(path.sep).join('/');
                     if (isD2) {
                         rendered = await renderD2(entryPath, { layout: options.D2_LAYOUT, seed: body });
                     }
                     else if (isBpmn) {
-                        // Путь для сообщений валидации; у виртуальных страниц — их источник.
-                        rendered = await renderBpmn(body, source ?? path.relative(process.cwd(), entryPath).split(path.sep).join('/'));
+                        rendered = await renderBpmn(body, file);
+                    }
+                    else if (isMermaid) {
+                        rendered = await renderMermaid(body, file);
                     }
                     else {
                         // Резолв JRE отложен до первого реального PlantUML-рендера (эта
@@ -380,18 +391,19 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
                     await writeFile(filePath, outFormat === 'png' ? await rasterizeSvgToPng(svg, options.USE_SYSTEM_FONTS) : svg);
                 }
             });
-            (isD2 ? d2Tasks : isBpmn ? bpmnTasks : otherTasks).push(task);
+            (isD2 ? d2Tasks : isBpmn ? bpmnTasks : isMermaid ? mermaidTasks : otherTasks).push(task);
         }
     }
-    // PlantUML-пул, D2- и BPMN-очереди работают независимо (процессы java, WASM-worker,
-    // главный поток) и параллельно друг другу. allSettled — чтобы падение одной очереди не
+    // PlantUML-пул, D2-, BPMN- и mermaid-очереди работают независимо (процессы java,
+    // WASM-worker, главный поток) и параллельно друг другу. allSettled — чтобы падение одной очереди не
     // оставляло другие как floating promise с висящими JVM: все доосушаются, затем бросаем первую
     // ошибку (приоритет — PlantUML-пул, порядок между очередями не значим).
     try {
         const results = await Promise.allSettled([
             runPool(otherTasks, renderConcurrency()),
             runPool(d2Tasks, 1),
-            runPool(bpmnTasks, 1)
+            runPool(bpmnTasks, 1),
+            runPool(mermaidTasks, 1)
         ]);
         const failed = results.find((r) => r.status === 'rejected');
         if (failed && failed.status === 'rejected')