@alfacapital-tech/c4builder 0.4.0 → 0.5.0

package/dist/util/lock.js

@@ -48,11 +48,11 @@ export const acquireBuildLock = (lockPath) => {
             const alive = typeof meta.pid === 'number' && ownerAlive(meta.pid);
             const fresh = typeof meta.at === 'number' && Date.now() - meta.at < STALE_MS;
             if (alive && fresh) {
-                throw new BuildLockHeldError(`сборка уже идёт в этом каталоге (pid ${meta.pid}) — дождитесь её завершения ` +
-                    `или удалите ${lockPath}, если это остаток упавшего процесса`);
+                throw new BuildLockHeldError(`a build is already running in this folder (pid ${meta.pid}) — wait for it to finish ` +
+                    `or delete ${lockPath} if it is left over from a crashed process`);
             }
             fs.rmSync(lockPath, { force: true });
         }
     }
-    throw new BuildLockHeldError(`не удалось захватить лок сборки: ${lockPath}`);
+    throw new BuildLockHeldError(`failed to acquire the build lock: ${lockPath}`);
 };

package/dist/util/paths.js

@@ -13,7 +13,7 @@ const findPackageRoot = (startDir) => {
             return dir;
         const parent = path.dirname(dir);
         if (parent === dir)
-            throw new Error(`package.json не найден вверх от ${startDir}`);
+            throw new Error(`package.json not found above ${startDir}`);
         dir = parent;
     }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfacapital-tech/c4builder",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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",
@@ -17,9 +17,9 @@
     "license"
   ],
   "engines": {
-    "node": ">=20.19"
+    "node": ">=22.17"
   },
-  "homepage": "https://github.com/AlfaCapital-Tech/C4-Builder",
+  "homepage": "https://alfacapital-tech.github.io/C4-Builder/",
   "bugs": {
     "url": "https://github.com/AlfaCapital-Tech/C4-Builder/issues"
   },
@@ -80,6 +80,11 @@
     "vitest": "^4.1.9"
   },
   "optionalDependencies": {
-    "@terrastruct/d2": "0.1.33"
+    "@terrastruct/d2": "0.1.33",
+    "bpmn-auto-layout": "2.0.0-alpha.2",
+    "bpmn-js": "18.31.0",
+    "bpmn-moddle": "10.3.1",
+    "bpmnlint": "11.14.0",
+    "jsdom": "29.1.1"
   }
 }

package/template/AGENTS.md

@@ -0,0 +1,52 @@
+# AGENTS.md
+
+Architecture documentation built with [c4builder](https://github.com/AlfaCapital-Tech/C4-Builder):
+C4 diagrams (PlantUML, D2), BPMN processes and markdown in `src/` are compiled into `docs/`.
+
+## Commands
+
+```bash
+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
+```
+
+Not installed: `npm i -g @alfacapital-tech/c4builder` (Node.js 22.17+; Java 17+ is used
+when present, otherwise c4builder downloads a private JRE).
+
+## Workflow
+
+1. Edit files in `src/` only — `docs/` is generated and wiped on every build.
+2. Run `c4builder check` on every diagram you changed, `src/styles.iuml` included. Errors
+   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.
+
+## Layout
+
+- One folder = one page. All `.md` files of a folder form its text; every `.puml` / `.d2` /
+  `.bpmn` in it is rendered onto the page, or placed inline with `![title](diagram.puml)`.
+- Files and folders starting with `_` are not published (shared libraries, drafts).
+- `.c4builder` is the config (JSON); unknown keys are silently ignored.
+
+## Diagram conventions
+
+- C4 comes from the PlantUML stdlib — `!include <C4/C4_Context>` (`C4_Container`,
+  `C4_Component`, `C4_Dynamic`, `C4_Deployment`). It is bundled, rendering is offline;
+  never include C4 by URL.
+- Shared styles live in `src/styles.iuml`, included after the C4 include by a relative
+  path: `!include styles.iuml` in `src/`, `!include ../styles.iuml` one level down.
+- D2 diagrams share classes through `src/_c4lib.d2` (`...@../_c4lib`).
+- BPMN: write only the semantic BPMN 2.0 XML, never `bpmndi` coordinates — the build lays the
+  diagram out. Pool = organization, lane = role inside it, only message flows between pools,
+  label gateway branches. Example: `src/5 BPMN Example/account-opening.bpmn`.
+
+## Agent skills
+
+Detailed guidance (project layout, config keys, plugins, installation) as skills for
+Claude Code, Codex, Cursor and other agents:
+
+```bash
+npx skills add AlfaCapital-Tech/C4-Builder/skills
+```

package/template/readme.md

@@ -1,6 +1,6 @@
 # Introduction
 
-This project was created using [c4builder](https://adrianvlupu.github.io/C4-Builder/)
+This project was created using [c4builder](https://alfacapital-tech.github.io/C4-Builder/)
 
 Take a look at 
 
@@ -12,12 +12,12 @@ Take a look at
 
 - [C4-PlantUML](https://github.com/RicardoNiepel/C4-PlantUML) C4 syntax support for generating plantuml diagrams
 
-- [vscode-plantuml](https://github.com/qjebbs/vscode-plantuml) plugin for visual studio code to view diagrams at design time
+- `c4builder --site -w` live preview: rebuilds on save and reloads the browser; `c4builder check <file>` validates a single diagram
 
 Open the terminal and run the following commands to start compiling the documentation
 
 ```bash
-npm i -g c4builder
+npm i -g @alfacapital-tech/c4builder
 c4builder
 ```
 

package/template/src/5 BPMN Example/account-opening.bpmn

@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Только семантическая часть BPMN: координат (bpmndi) нет, раскладку делает c4builder. -->
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
+                  id="Definitions_AccountOpening"
+                  targetNamespace="https://example.com/bpmn/account-opening">
+  <bpmn:collaboration id="Collaboration_AccountOpening">
+    <bpmn:participant id="Pool_Bank" name="Банк" processRef="Process_AccountOpening" />
+    <bpmn:participant id="Pool_CreditBureau" name="Бюро кредитных историй" />
+    <bpmn:messageFlow id="Message_HistoryRequest" name="Запрос истории"
+                      sourceRef="Task_RequestHistory" targetRef="Pool_CreditBureau" />
+    <bpmn:messageFlow id="Message_CreditReport" name="Кредитный отчёт"
+                      sourceRef="Pool_CreditBureau" targetRef="Task_ReceiveReport" />
+  </bpmn:collaboration>
+
+  <bpmn:process id="Process_AccountOpening" name="Открытие счёта" isExecutable="false">
+    <bpmn:laneSet id="LaneSet_Bank">
+      <bpmn:lane id="Lane_Client" name="Клиент">
+        <bpmn:flowNodeRef>Start_AccountNeeded</bpmn:flowNodeRef>
+        <bpmn:flowNodeRef>Task_SubmitApplication</bpmn:flowNodeRef>
+        <bpmn:flowNodeRef>End_AccountOpened</bpmn:flowNodeRef>
+        <bpmn:flowNodeRef>End_Rejected</bpmn:flowNodeRef>
+      </bpmn:lane>
+      <bpmn:lane id="Lane_FrontOffice" name="Фронт-офис">
+        <bpmn:flowNodeRef>Task_CheckDocuments</bpmn:flowNodeRef>
+        <bpmn:flowNodeRef>Task_RequestHistory</bpmn:flowNodeRef>
+        <bpmn:flowNodeRef>Task_ReceiveReport</bpmn:flowNodeRef>
+      </bpmn:lane>
+      <bpmn:lane id="Lane_BackOffice" name="Бэк-офис">
+        <bpmn:flowNodeRef>Task_Assess</bpmn:flowNodeRef>
+        <bpmn:flowNodeRef>Timer_AssessOverdue</bpmn:flowNodeRef>
+        <bpmn:flowNodeRef>Task_Escalate</bpmn:flowNodeRef>
+        <bpmn:flowNodeRef>End_Escalated</bpmn:flowNodeRef>
+        <bpmn:flowNodeRef>Gateway_Decision</bpmn:flowNodeRef>
+        <bpmn:flowNodeRef>Task_OpenAccount</bpmn:flowNodeRef>
+        <bpmn:flowNodeRef>Task_PrepareRejection</bpmn:flowNodeRef>
+      </bpmn:lane>
+    </bpmn:laneSet>
+
+    <bpmn:startEvent id="Start_AccountNeeded" name="Нужен счёт" />
+    <bpmn:userTask id="Task_SubmitApplication" name="Подать заявку" />
+    <bpmn:userTask id="Task_CheckDocuments" name="Проверить документы" />
+    <bpmn:sendTask id="Task_RequestHistory" name="Запросить кредитную историю" />
+    <bpmn:receiveTask id="Task_ReceiveReport" name="Получить кредитный отчёт" />
+    <bpmn:userTask id="Task_Assess" name="Оценить заявку" />
+    <bpmn:boundaryEvent id="Timer_AssessOverdue" name="3 рабочих дня" attachedToRef="Task_Assess">
+      <bpmn:timerEventDefinition id="TimerDef_AssessOverdue" />
+    </bpmn:boundaryEvent>
+    <bpmn:task id="Task_Escalate" name="Эскалировать руководителю" />
+    <bpmn:endEvent id="End_Escalated" name="Заявка у руководителя" />
+    <bpmn:exclusiveGateway id="Gateway_Decision" name="Одобрить?" />
+    <bpmn:serviceTask id="Task_OpenAccount" name="Открыть счёт" />
+    <bpmn:task id="Task_PrepareRejection" name="Подготовить отказ" />
+    <bpmn:endEvent id="End_AccountOpened" name="Счёт открыт" />
+    <bpmn:endEvent id="End_Rejected" name="Получен отказ" />
+
+    <bpmn:sequenceFlow id="Flow_Start" sourceRef="Start_AccountNeeded" targetRef="Task_SubmitApplication" />
+    <bpmn:sequenceFlow id="Flow_Submitted" sourceRef="Task_SubmitApplication" targetRef="Task_CheckDocuments" />
+    <bpmn:sequenceFlow id="Flow_Checked" sourceRef="Task_CheckDocuments" targetRef="Task_RequestHistory" />
+    <bpmn:sequenceFlow id="Flow_Requested" sourceRef="Task_RequestHistory" targetRef="Task_ReceiveReport" />
+    <bpmn:sequenceFlow id="Flow_Received" sourceRef="Task_ReceiveReport" targetRef="Task_Assess" />
+    <bpmn:sequenceFlow id="Flow_Assessed" sourceRef="Task_Assess" targetRef="Gateway_Decision" />
+    <bpmn:sequenceFlow id="Flow_Approved" name="Да" sourceRef="Gateway_Decision" targetRef="Task_OpenAccount" />
+    <bpmn:sequenceFlow id="Flow_Declined" name="Нет" sourceRef="Gateway_Decision" targetRef="Task_PrepareRejection" />
+    <bpmn:sequenceFlow id="Flow_Opened" sourceRef="Task_OpenAccount" targetRef="End_AccountOpened" />
+    <bpmn:sequenceFlow id="Flow_Rejected" sourceRef="Task_PrepareRejection" targetRef="End_Rejected" />
+    <bpmn:sequenceFlow id="Flow_Overdue" sourceRef="Timer_AssessOverdue" targetRef="Task_Escalate" />
+    <bpmn:sequenceFlow id="Flow_Escalated" sourceRef="Task_Escalate" targetRef="End_Escalated" />
+  </bpmn:process>
+</bpmn:definitions>

package/template/src/5 BPMN Example/account-opening.md

@@ -0,0 +1,7 @@
+**Бизнес-процесс в нотации BPMN (третий бэкенд рендера)**
+
+Эта страница демонстрирует BPMN-диаграммы: процесс «Открытие счёта» с пулом «Банк» и его дорожками «Клиент», «Фронт-офис», «Бэк-офис», внешним пулом «Бюро кредитных историй», шлюзом с подписанными ветками, граничным таймером и message flow между пулами.
+
+Файл `.bpmn` содержит только семантическую часть BPMN 2.0 XML: пулы, дорожки, события, задачи, шлюзы и потоки. Координат (секции `bpmndi`) в нём нет — раскладку делает сборка: пулы и дорожки горизонтальными полосами, поток слева направо. Если координаты в файле есть, они игнорируются. Перед раскладкой модель проверяется (несвязанные узлы, узел вне дорожки, sequence flow между пулами и т.п.), ошибки ссылаются на id элемента. Отдельный файл проверяется командой `c4builder check account-opening.bpmn`.
+
+**Область применения**: показать, что `.bpmn`-диаграммы, их раскладка и кириллица корректно попадают в собранный сайт, SVG и PNG без обращений в интернет.

package/dist/util/glob.js

@@ -1,69 +0,0 @@
-// Мини-glob без зависимостей: `**` (любые каталоги), `*` (в пределах сегмента),
-// `?`, `{a,b}`; остальное — буквально. Покрывает `*/openapi.yaml` и
-// `**/openapi.{yaml,yml,json}`; `fs.glob` появился только в Node 22, engines — ≥20.19.
-import fs from 'node:fs';
-import path from 'node:path';
-const convert = (glob) => {
-    let re = '';
-    for (let i = 0; i < glob.length; i++) {
-        const c = glob[i];
-        if (c === '*') {
-            if (glob[i + 1] === '*') {
-                // `**/` — ноль и более каталогов; одиночное `**` в конце — что угодно
-                i++;
-                if (glob[i + 1] === '/') {
-                    i++;
-                    re += '(?:.*/)?';
-                }
-                else
-                    re += '.*';
-            }
-            else
-                re += '[^/]*';
-        }
-        else if (c === '?')
-            re += '[^/]';
-        else if (c === '{') {
-            const end = glob.indexOf('}', i);
-            if (end === -1)
-                re += '\\{';
-            else {
-                // Альтернативы — тем же конвертером: `{*.yaml,*.yml}` должен работать
-                // как glob, а не как буквальная звёздочка.
-                re += `(?:${glob
-                    .slice(i + 1, end)
-                    .split(',')
-                    .map(convert)
-                    .join('|')})`;
-                i = end;
-            }
-        }
-        else
-            re += c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    }
-    return re;
-};
-export const globToRegExp = (glob) => new RegExp(`^${convert(glob)}$`);
-/**
- * Файлы под root, чьи относительные posix-пути совпадают с glob (сортировано).
- * `.git`/`node_modules` и абсолютные каталоги `skipDirs` не обходятся.
- */
-export const globFiles = (root, glob, skipDirs = []) => {
-    const re = globToRegExp(glob);
-    const skip = new Set(skipDirs.map((d) => path.resolve(d)));
-    const out = [];
-    const walk = (rel) => {
-        for (const e of fs.readdirSync(path.join(root, rel), { withFileTypes: true })) {
-            const r = rel ? `${rel}/${e.name}` : e.name;
-            if (e.isDirectory()) {
-                if (e.name === '.git' || e.name === 'node_modules' || skip.has(path.resolve(root, r)))
-                    continue;
-                walk(r);
-            }
-            else if (re.test(r))
-                out.push(r);
-        }
-    };
-    walk('');
-    return out.sort();
-};