@alfacapital-tech/c4builder 0.3.0-rc.1 → 0.3.0-rc.3

package/dist/core/render/jre.js

@@ -8,10 +8,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import https from 'node:https';
 import crypto from 'node:crypto';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
+import { httpGetStream, httpGetJson } from "../../util/http.js";
 // yauzl/tar грузятся лениво (только при распаковке скачанного JRE) — сохраняем это
 // синхронным require через createRequire, а не тянем их на импорте модуля.
 const require = createRequire(import.meta.url);
@@ -115,50 +115,82 @@ const findJavaUnder = (root) => {
     }
     return null;
 };
-// (2) кеш: валиден только при наличии исполняемого bin/java.
-const cachedJava = () => {
-    const bin = findJavaUnder(jreCacheDir());
-    return bin ? { path: bin, source: 'cache' } : null;
+// Версия схемы кеша JRE: инкрементируется при смене раскладки каталога или формата
+// маркера. Внешние кеши (ключ actions/cache в .github/workflows/ci.yml) включают её,
+// иначе кеш, снятый старой схемой, восстанавливался бы вечно: cachedJava признал бы
+// его невалидным, а actions/cache при попадании в ключ не пересохраняет каталог.
+const JRE_CACHE_SCHEMA = 1;
+// Маркер завершённости распаковки: кладётся ПОСЛЕДНИМ в staging и едет в кеш вместе
+// с ним. cachedJava доверяет кешу только при его наличии — иначе прерванная (Ctrl+C)
+// или гоночная распаковка (bin/java уже есть, lib/modules ещё нет) навсегда выдавалась
+// бы за валидный JRE. Проверка дешёвая: существование файла, без запуска JVM.
+const MARKER_NAME = '.c4builder-jre-ready.json';
+const markerPath = (root) => path.join(root, MARKER_NAME);
+// Валиден ли распакованный JRE в каталоге root: маркер завершённости той же схемы +
+// НАЙДЕННЫЙ и ЗАПУСКАЕМЫЙ bin/java. Запускаемость проверяем так же, как detectSystemJava
+// (javaMajor): маркер мог остаться от оборванной мимо него распаковки или частичного
+// копирования кеша (битые lib/*), и тогда «валидный» по маркеру бинарь всё равно не
+// стартует. Возвращает путь к бинарю или null.
+const installedJavaAt = (root) => {
+    let marker;
+    try {
+        marker = JSON.parse(fs.readFileSync(markerPath(root), 'utf-8'));
+    }
+    catch {
+        return null; // маркера нет или он битый — распаковка не завершилась
+    }
+    if (marker.schema !== JRE_CACHE_SCHEMA)
+        return null; // кеш старой раскладки
+    const bin = findJavaUnder(root);
+    if (!bin)
+        return null;
+    return javaMajor(bin) !== null ? bin : null;
 };
-// --- HTTP с обработкой редиректов (assets-эндпоинт может 307-редиректить на github) ---
-const httpGet = (url) => new Promise((resolve, reject) => {
-    https
-        .get(url, { headers: { 'User-Agent': 'c4builder-jre-resolver' } }, (res) => {
-        const statusCode = res.statusCode; // ответ всегда со статусом
-        const { headers } = res;
-        if (statusCode >= 300 && statusCode < 400 && headers.location) {
-            res.resume();
-            return resolve(httpGet(new URL(headers.location, url).toString()));
+// (2) кеш: валиден при маркере той же схемы И запускаемом bin/java. Битый/неполный
+// каталог сносим, чтобы resolveJava ушёл на перекачку, а не залипал на нём (downloadJre
+// пишет в свой staging, поэтому невалидный dir — это заведомо остаток, а не чужая
+// установка в процессе).
+const cachedJava = () => {
+    const root = jreCacheDir();
+    const bin = installedJavaAt(root);
+    if (bin)
+        return { path: bin, source: 'cache' };
+    if (fs.existsSync(root)) {
+        try {
+            fs.rmSync(root, { recursive: true, force: true });
         }
-        if (statusCode !== 200) {
-            res.resume();
-            return reject(new Error(`HTTP ${statusCode} для ${url}`));
+        catch {
+            /* не удалось снести — downloadJre всё равно перезапишет каталог */
         }
-        resolve(res);
-    })
-        .on('error', reject);
-});
-const httpGetJson = async (url) => {
-    const res = await httpGet(url);
-    const chunks = [];
-    for await (const c of res)
-        chunks.push(c);
-    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    return null;
 };
-// Adoptium assets API отдаёт ссылку и sha256 одним запросом.
+// HTTP-запросы (редиректы + таймауты) — в общем util/http. Здесь только User-Agent
+// резолвера: Adoptium assets-эндпоинт 307-редиректит на github, приём архива ~50 МБ.
+const JRE_UA = { 'User-Agent': 'c4builder-jre-resolver' };
+// Adoptium assets API отдаёт ссылку и sha256 одним запросом. ВАЖНО: link и checksum
+// приходят из ОДНОГО ответа API — sha256 защищает лишь от повреждения при передаче
+// (усечённый/битый архив), но НЕ от компрометации самого API/ответа.
 const fetchAssetMeta = async () => {
     const url = `https://api.adoptium.net/v3/assets/latest/${TEMURIN_FEATURE}/hotspot` +
         `?image_type=jre&vendor=eclipse&os=${adoptiumOs()}&architecture=${adoptiumArch()}`;
-    const json = await httpGetJson(url);
+    const json = await httpGetJson(url, { headers: JRE_UA });
     const asset = Array.isArray(json) ? json.find((a) => a.binary?.package) : null;
     if (!asset) {
         throw new Error(`Adoptium не отдал JRE-сборку под ${adoptiumOs()}/${adoptiumArch()} (Temurin ${TEMURIN_FEATURE})`);
     }
     const pkg = asset.binary.package;
+    if (!pkg.link)
+        throw new Error('Adoptium не вернул ссылку на архив JRE');
+    // Отсутствие checksum — ошибка, а не молчаливый пропуск проверки целостности.
+    if (!pkg.checksum) {
+        throw new Error(`Adoptium не вернул sha256 для ${pkg.name || 'архива JRE'}: ` +
+            'отказ принимать архив без проверки целостности');
+    }
     return { link: pkg.link, sha256: pkg.checksum, name: pkg.name, release: asset.release_name };
 };
 const downloadAndVerify = async (link, expectedSha, destFile) => {
-    const res = await httpGet(link);
+    const res = await httpGetStream(link, { headers: JRE_UA });
     const hash = crypto.createHash('sha256');
     await new Promise((resolve, reject) => {
         const out = fs.createWriteStream(destFile);
@@ -168,16 +200,35 @@ const downloadAndVerify = async (link, expectedSha, destFile) => {
         out.on('finish', resolve);
         res.pipe(out);
     });
-    const actual = hash.digest('hex');
-    if (expectedSha && actual.toLowerCase() !== expectedSha.toLowerCase()) {
+    const actual = hash.digest('hex').toLowerCase();
+    if (!expectedSha)
+        throw new Error('Нет ожидаемого sha256 — проверка целостности архива невозможна');
+    if (actual !== expectedSha.toLowerCase()) {
         throw new Error(`sha256 архива не совпал: ожидалось ${expectedSha}, получено ${actual}`);
     }
 };
+// Защита от zip-slip: путь записи, разрешённый относительно destDir, обязан
+// оставаться ВНУТРИ него (не `../` за пределы). Экспортируется для юнит-теста.
+export const isPathInside = (destDir, entryName) => {
+    const root = path.resolve(destDir);
+    const dest = path.resolve(root, entryName);
+    return dest === root || dest.startsWith(root + path.sep);
+};
 const extractZip = (archive, destDir) => new Promise((resolve, reject) => {
     require('yauzl').open(archive, { lazyEntries: true }, (err, zip) => {
         if (err)
             return reject(err);
         zip.on('entry', (entry) => {
+            // zip-slip: злонамеренная запись `../../evil` вышла бы за destDir. tar-ветка
+            // защищена node-tar≥6 по умолчанию, zip (yauzl) — нет, проверяем сами.
+            if (!isPathInside(destDir, entry.fileName)) {
+                return reject(new Error(`Небезопасный путь в архиве JRE (выход за каталог): ${entry.fileName}`));
+            }
+            // Симлинки пропускаем: вне доверенного Adoptium-архива симлинк мог бы
+            // указывать за пределы каталога. Temurin Windows-zip симлинков не содержит.
+            const isSymlink = ((entry.externalFileAttributes >>> 16) & 0xffff & 0o170000) === 0o120000;
+            if (isSymlink)
+                return zip.readEntry();
             const dest = path.join(destDir, entry.fileName);
             if (entry.fileName.endsWith('/')) {
                 fs.mkdirSync(dest, { recursive: true });
@@ -210,25 +261,56 @@ const extractZip = (archive, destDir) => new Promise((resolve, reject) => {
     });
 });
 const extractArchive = (archive, destDir, isZip) => isZip ? extractZip(archive, destDir) : require('tar').x({ file: archive, cwd: destDir });
-// (3) скачивание: assets API → sha256 (до распаковки) → распаковка в кеш.
-// Битую/старую установку затираем целиком перед распаковкой.
+// (3) скачивание: assets API → sha256 (до распаковки) → распаковка в staging →
+// атомарная замена кеша. Распаковываем НЕ в финальный каталог, а в свой staging
+// (<dir>.tmp-<pid>, уникальный на процесс → параллельные сборки не топчут друг друга),
+// кладём маркер и лишь затем атомарным rename заменяем кеш. Прерывание (Ctrl+C) или
+// гонка не оставят финальный каталог полураспакованным.
 const downloadJre = async ({ log } = {}) => {
     const meta = await fetchAssetMeta();
     const dir = jreCacheDir();
     const isZip = adoptiumOs() === 'windows';
     const parent = path.dirname(dir);
     fs.mkdirSync(parent, { recursive: true });
-    const tmp = path.join(parent, `.download-${process.pid}${isZip ? '.zip' : '.tar.gz'}`);
+    const tmpArchive = path.join(parent, `.download-${process.pid}${isZip ? '.zip' : '.tar.gz'}`);
+    const stageDir = `${dir}.tmp-${process.pid}`;
     try {
         if (log)
             log(`Скачивание Temurin ${TEMURIN_FEATURE} JRE (${meta.release || meta.name})…`);
-        await downloadAndVerify(meta.link, meta.sha256, tmp);
-        fs.rmSync(dir, { recursive: true, force: true });
-        fs.mkdirSync(dir, { recursive: true });
-        await extractArchive(tmp, dir, isZip);
+        await downloadAndVerify(meta.link, meta.sha256, tmpArchive);
+        fs.rmSync(stageDir, { recursive: true, force: true });
+        fs.mkdirSync(stageDir, { recursive: true });
+        await extractArchive(tmpArchive, stageDir, isZip);
+        if (!findJavaUnder(stageDir)) {
+            throw new Error('JRE распакован, но исполняемый bin/java не найден');
+        }
+        fs.writeFileSync(markerPath(stageDir), JSON.stringify({
+            schema: JRE_CACHE_SCHEMA,
+            feature: TEMURIN_FEATURE,
+            release: meta.release,
+            sha256: meta.sha256
+        }));
+        // Установка в общий кеш без межпроцессной блокировки. Не делаем rm(dir)+rename
+        // (окно, в котором dir исчезает у параллельной сборки): если к этому моменту в dir
+        // уже валидный JRE — другой процесс успел, принимаем его и выбрасываем свой stage.
+        // Иначе пытаемся атомарный rename; провал rename (dir возник в гонке / остался
+        // старый невалидный каталог) разбираем: валиден теперь → чужой, невалиден → сносим
+        // и ставим свой.
+        if (!installedJavaAt(dir)) {
+            try {
+                fs.renameSync(stageDir, dir);
+            }
+            catch {
+                if (!installedJavaAt(dir)) {
+                    fs.rmSync(dir, { recursive: true, force: true });
+                    fs.renameSync(stageDir, dir);
+                }
+            }
+        }
     }
     finally {
-        fs.rmSync(tmp, { force: true });
+        fs.rmSync(tmpArchive, { force: true });
+        fs.rmSync(stageDir, { recursive: true, force: true }); // подчистить staging (no-op, если переименован)
     }
     const bin = findJavaUnder(dir);
     if (!bin)
@@ -244,22 +326,44 @@ const failureMessage = (cause) => [
 ]
     .filter(Boolean)
     .join('\n');
+// Мемо результата резолва на процесс: watch-режим не платит скан PATH + spawnSync
+// `java -version` (~50-300 мс) на каждый ребилд. Кешируем сам промис (как d2Promise
+// в d2renderer.ts). force обходит кеш (для `jre install --force`), но успешный резолв —
+// в т.ч. после force — его обновляет; провал не кешируем.
+let resolvePromise = null;
 // Резолв по цепочке. { force } пропускает систему и кеш (форс-скачивание для
 // `jre install --force`). Возвращает { path, source }.
 const resolveJava = async ({ force = false, log } = {}) => {
-    if (!force) {
-        const sys = detectSystemJava();
-        if (sys)
-            return sys;
-        const cached = cachedJava();
-        if (cached)
-            return cached;
-    }
+    if (!force && resolvePromise)
+        return resolvePromise;
+    const run = (async () => {
+        if (!force) {
+            const sys = detectSystemJava();
+            if (sys)
+                return sys;
+            const cached = cachedJava();
+            if (cached)
+                return cached;
+        }
+        try {
+            return await downloadJre({ log });
+        }
+        catch (e) {
+            throw new Error(failureMessage(e));
+        }
+    })();
+    resolvePromise = run;
     try {
-        return await downloadJre({ log });
+        return await run;
     }
     catch (e) {
-        throw new Error(failureMessage(e));
+        if (resolvePromise === run)
+            resolvePromise = null; // провал не кешируем — даём повторить
+        throw e;
     }
 };
-export { resolveJava, detectSystemJava, cachedJava, jreCacheDir, adoptiumOs, adoptiumArch, parseMajor, MAJOR_MIN, TEMURIN_FEATURE };
+// Публичный API модуля. jreCacheDir и JRE_CACHE_SCHEMA нужны подкоманде `jre info` —
+// из неё CI берёт путь кеша и материал ключа (см. .github/workflows/ci.yml), не
+// хардкодя путь и не grep'ая константы из исходников. adoptiumOs/adoptiumArch/
+// parseMajor/MAJOR_MIN — module-private.
+export { resolveJava, detectSystemJava, cachedJava, TEMURIN_FEATURE, JRE_CACHE_SCHEMA, jreCacheDir };

package/dist/core/render/pngraster.js

@@ -1,22 +1,16 @@
 import { createRequire } from 'node:module';
-import path from 'node:path';
-import { VENDOR_DIR } from "../../util/paths.js";
+// Шрифт-пин общий с java-direct рендером (одна точка правды, см. fonts.ts).
+import { FONTS_DIR, DEFAULT_FONT_NAME } from "./fonts.js";
 // @resvg/resvg-js — CJS-нативный аддон, грузим синхронно через createRequire
 // (ленивая загрузка ниже сохраняет прежнюю семантику: пакет тянется при первой
 // растеризации, не на импорте модуля).
 const require = createRequire(import.meta.url);
-// Растеризатор SVG→PNG (resvg, Rust/napi, prebuilt-бинарь, без браузера). Единая
-// детерминированная стадия PNG-выхода поверх SVG обоих движков (PlantUML и D2),
-// см. change resvg-png. Вендорный шрифт (тот же, что у java-direct) даёт кириллицу
-// и повторяемые метрики независимо от машины; системные шрифты отключены.
-const FONTS_DIR = path.join(VENDOR_DIR, 'fonts');
-const DEFAULT_FONT_NAME = 'Liberation Sans';
-let ResvgCtor = null;
+let resvgMod = null;
 const getResvg = () => {
-    if (ResvgCtor)
-        return ResvgCtor;
+    if (resvgMod)
+        return resvgMod;
     try {
-        ResvgCtor = require('@resvg/resvg-js').Resvg;
+        resvgMod = require('@resvg/resvg-js');
     }
     catch (err) {
         const e = err;
@@ -24,20 +18,20 @@ const getResvg = () => {
             'Установите его: npm install @resvg/resvg-js\n' +
             `Исходная ошибка: ${e.message || e}`);
     }
-    return ResvgCtor;
+    return resvgMod;
 };
+export const resvgFontOptions = (useSystemFonts) => useSystemFonts
+    ? { loadSystemFonts: true }
+    : { fontDirs: [FONTS_DIR], defaultFontFamily: DEFAULT_FONT_NAME, loadSystemFonts: false };
 // SVG (Buffer или строка) → PNG (Buffer), масштаб 1:1 к размеру SVG. Вход — валидный
 // SVG движка: PlantUML ссылается на шрифт по имени (грузим из vendor/fonts), D2 несёт
-// шрифт во вшитом @font-face, но loadSystemFonts:false фиксируем в обоих случаях.
-const rasterizeSvgToPng = (svg) => {
-    const Resvg = getResvg();
-    const resvg = new Resvg(svg, {
-        font: {
-            fontDirs: [FONTS_DIR],
-            defaultFontFamily: DEFAULT_FONT_NAME,
-            loadSystemFonts: false
-        }
-    });
-    return resvg.render().asPng();
+// шрифт во вшитом @font-face, но пин по умолчанию фиксируем в обоих случаях.
+// renderAsync считает в napi-пуле тредов: JS-поток не блокируется, PlantUML-пул и
+// D2-очередь продолжают крутиться параллельно растеризации (прежний sync render()
+// останавливал весь event loop на каждую картинку).
+const rasterizeSvgToPng = async (svg, useSystemFonts = false) => {
+    const { renderAsync } = getResvg();
+    const rendered = await renderAsync(svg, { font: resvgFontOptions(useSystemFonts) });
+    return rendered.asPng();
 };
 export { rasterizeSvgToPng };

package/dist/core/scan/tree.js

@@ -2,6 +2,20 @@ import fs from 'node:fs';
 import path from 'node:path';
 import fsextra from 'fs-extra';
 import { makeDirectory, readFile } from "../../util/utils.js";
+// Единый реестр движков диаграмм: расширение (с точкой) → рендерер + способности.
+// ЕДИНСТВЕННЫЙ источник истины о том, какие файлы считаются диаграммами. Из него
+// строятся фильтр scan (ниже), regex ссылок в compose/markdown.ts и ветвление
+// «есть ли у движка онлайн-рендер» (build/compose). Добавление движка = одна строка
+// здесь; фазы подхватят его без синхронной правки.
+export const DIAGRAM_ENGINES = [
+    { ext: '.puml', engine: 'plantuml', remoteRender: true },
+    { ext: '.d2', engine: 'd2', remoteRender: false }
+];
+// Расширение (lowercase, с точкой) → движок. undefined ⇒ файл не диаграмма.
+export const engineForExt = (ext) => DIAGRAM_ENGINES.find((e) => e.ext === ext)?.engine;
+// Есть ли у движка онлайн-рендер (сервер, как у PlantUML). Для движков без него (D2)
+// сборка при выключенном generateLocalImages невозможна — вывод не из чего собрать.
+export const engineSupportsRemote = (engine) => DIAGRAM_ENGINES.some((e) => e.engine === engine && e.remoteRender);
 export const getFolderName = (dir, root, homepage) => {
     return dir === root ? homepage : path.parse(dir).base;
 };
@@ -32,15 +46,31 @@ export const generateTree = async (dir, options) => {
             tree.push(item);
         }
         const IGNORED_FILES = ['CLAUDE.md'];
-        const files = fs.readdirSync(dir).filter((x) => x.charAt(0) !== '_' && !IGNORED_FILES.includes(x));
+        // withFileTypes: один readdir вместо statSync на каждый файл (и второго — в
+        // otherFiles-цикле ниже). Симлинкам — честный statSync (Dirent по ссылке не идёт),
+        // чтобы симлинк-на-каталог обходился как раньше.
+        const entries = fs
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.name.charAt(0) !== '_' && !IGNORED_FILES.includes(e.name));
+        const isDir = new Map(entries.map((e) => [
+            e.name,
+            e.isSymbolicLink() ? fs.statSync(path.join(dir, e.name)).isDirectory() : e.isDirectory()
+        ]));
+        const files = entries.map((e) => e.name);
         for (const file of files) {
             //if folder
-            if (fs.statSync(path.join(dir, file)).isDirectory()) {
+            const childDir = path.join(dir, file);
+            if (isDir.get(file)) {
+                // Выходной каталог не тащим в дерево: при rootFolder='.' distFolder был бы
+                // ребёнком корня → попадал в nav-меню (битая ссылка) и порождал docs/docs.
+                // Ранний return рекурсии срабатывал уже ПОСЛЕ push — отсекаем до него.
+                if (childDir === options.DIST_FOLDER)
+                    continue;
                 item.descendants.push(file);
                 //create corresponding dist folder
                 if (options.GENERATE_WEBSITE || options.GENERATE_MD || options.GENERATE_LOCAL_IMAGES)
                     await makeDirectory(path.join(options.DIST_FOLDER, dir.replace(options.ROOT_FOLDER, ''), file));
-                await build(path.join(dir, file), dir);
+                await build(childDir, dir);
             }
         }
         const mdFiles = files.filter((x) => path.extname(x).toLowerCase() === '.md');
@@ -48,12 +78,13 @@ export const generateTree = async (dir, options) => {
             const fileContents = await readFile(path.join(dir, mdFile));
             item.mdFiles.push(fileContents);
         }
-        // Диаграммы обоих бэкендов: .puml → PlantUML, .d2 → D2. Поле dir — имя файла
+        // Диаграммы: расширение → движок берём из DIAGRAM_ENGINES. Поле dir — имя файла
         // (историческое), engine выбирает рендерер, isDitaa — только для PlantUML.
-        const diagramFiles = files.filter((x) => ['.puml', '.d2'].includes(path.extname(x).toLowerCase()));
-        for (const diagramFile of diagramFiles) {
+        for (const diagramFile of files) {
             const ext = path.extname(diagramFile).toLowerCase();
-            const engine = ext === '.d2' ? 'd2' : 'plantuml';
+            const engine = engineForExt(ext);
+            if (!engine)
+                continue; // не диаграмма — пропускаем
             const fileContents = await readFile(path.join(dir, diagramFile));
             const isDitaa = engine === 'plantuml' &&
                 !!(fileContents ? fileContents.toString() : '').match(/(@startditaa)/gi);
@@ -63,10 +94,14 @@ export const generateTree = async (dir, options) => {
         //copy all other files (.d2 исходники, как и .puml, не копируем — они рендерятся)
         const otherFiles = options.EXCLUDE_OTHER_FILES
             ? []
-            : files.filter((x) => x.charAt(0) === '_' ||
-                ['.md', '.puml', '.d2'].indexOf(path.extname(x).toLowerCase()) === -1);
+            : files.filter((x) => {
+                const ext = path.extname(x).toLowerCase();
+                // копируем всё, кроме .md и исходников диаграмм (их рендерим);
+                // _-файлы сюда не доходят — отфильтрованы на readdir выше.
+                return ext !== '.md' && engineForExt(ext) === undefined;
+            });
         for (const otherFile of otherFiles) {
-            if (fs.statSync(path.join(dir, otherFile)).isDirectory())
+            if (isDir.get(otherFile))
                 continue;
             if (options.GENERATE_MD || options.GENERATE_WEBSITE)
                 await fsextra.copy(path.join(dir, otherFile), path.join(options.DIST_FOLDER, dir.replace(options.ROOT_FOLDER, ''), otherFile));
@@ -90,9 +125,17 @@ export const generateTree = async (dir, options) => {
     }
     return tree;
 };
+// Кеш чтения include-файлов на одну сборку: N диаграмм × M включений иначе перечитывают
+// одни и те же .iuml с диска (общие стили включаются каждой диаграммой). null = файл не
+// прочитался (маркер, чтобы не ретраить). Сбрасывается clearIncludeCache() на границах
+// build() — в watch-режиме иначе отдавались бы устаревшие данные.
+const includeReadCache = new Map();
+export const clearIncludeCache = () => includeReadCache.clear();
 // Свернуть локальные !include (.iuml и пр.) диаграммы в материал для чексуммы — рекурсивно.
 // Иначе правка включённого .iuml не инвалидирует кэш и на сайт уезжает устаревший рендер.
 // URL (!include https://…) и stdlib (!include <…>) пропускаем: локально не меняются.
+// Путь в материале — относительный к cwd, posix-разделители: чексумма не зависит от
+// машины/чекаута/ОС (абсолютный путь делал кеш непереносимым).
 export const foldIncludes = (content, fileDir, searchDir, visited) => {
     const re = /^[ \t]*!include(?:_once|_many|sub|url)?[ \t]+(.+?)[ \t]*$/gim;
     let out = '';
@@ -111,14 +154,19 @@ export const foldIncludes = (content, fileDir, searchDir, visited) => {
         if (!resolved || visited.has(resolved))
             continue; // защита от циклов и повторов
         visited.add(resolved);
-        let inc = '';
-        try {
-            inc = fs.readFileSync(resolved, 'utf-8');
+        let inc = includeReadCache.get(resolved);
+        if (inc === undefined) {
+            try {
+                inc = fs.readFileSync(resolved, 'utf-8');
+            }
+            catch {
+                inc = null;
+            }
+            includeReadCache.set(resolved, inc);
         }
-        catch {
+        if (inc === null)
             continue;
-        }
-        out += ` ${resolved} ${inc}`;
+        out += ` ${path.relative(process.cwd(), resolved).split(path.sep).join('/')} ${inc}`;
         out += foldIncludes(inc, path.dirname(resolved), searchDir, visited); // вложенные include
     }
     return out;

package/dist/util/http.js

@@ -0,0 +1,55 @@
+import http from 'node:http';
+import https from 'node:https';
+// Общий HTTP GET рендер-слоя (embed онлайн-рендера) и JRE-резолвера (скачивание с
+// Adoptium). Следует редиректам и держит два таймаута — коннекта и простоя приёма:
+// 3xx не роняет сборку, а молча повисший сокет не подвешивает её навсегда. Таймауты
+// переопределяются env (в т.ч. для тестов); имена C4BUILDER_JRE_* поддержаны для
+// обратной совместимости со старыми знобами JRE-резолвера.
+const posInt = (v, dflt) => {
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? n : dflt;
+};
+const env = process.env;
+const CONNECT_TIMEOUT_MS = posInt(env.C4BUILDER_HTTP_CONNECT_TIMEOUT_MS ?? env.C4BUILDER_JRE_CONNECT_TIMEOUT_MS, 30_000);
+const IDLE_TIMEOUT_MS = posInt(env.C4BUILDER_HTTP_IDLE_TIMEOUT_MS ?? env.C4BUILDER_JRE_IDLE_TIMEOUT_MS, 60_000);
+const MAX_REDIRECTS = 5;
+// Возвращает поток успешного (2xx) ответа. Редиректы (assets-эндпоинт Adoptium
+// 307-редиректит на github) следуются с лимитом против петель; не-2xx — reject.
+export const httpGetStream = (url, opts = {}) => {
+    const { headers = {}, redirectsLeft = MAX_REDIRECTS } = opts;
+    return new Promise((resolve, reject) => {
+        const lib = url.startsWith('https') ? https : http;
+        const req = lib.get(url, { headers, timeout: CONNECT_TIMEOUT_MS }, (res) => {
+            const status = res.statusCode; // ответ всегда со статусом
+            const location = res.headers.location;
+            if (status >= 300 && status < 400 && location) {
+                res.resume();
+                if (redirectsLeft <= 0) {
+                    return reject(new Error(`Слишком много редиректов (>${MAX_REDIRECTS}) для ${url}`));
+                }
+                const next = new URL(location, url).toString();
+                return resolve(httpGetStream(next, { headers, redirectsLeft: redirectsLeft - 1 }));
+            }
+            if (status < 200 || status > 299) {
+                res.resume();
+                return reject(new Error(`Не удалось загрузить ${url}, код ответа: ${status}`));
+            }
+            // Коннект установлен → с таймаута коннекта переключаемся на таймаут простоя
+            // приёма (крупный ответ тянется дольше): молчащий сокет уронит таймаут.
+            req.setTimeout(IDLE_TIMEOUT_MS);
+            resolve(res);
+        });
+        req.on('timeout', () => req.destroy(new Error(`Таймаут сети (${url})`)));
+        req.on('error', reject);
+    });
+};
+// Тело ответа целиком в Buffer.
+export const httpGetBuffer = async (url, opts = {}) => {
+    const res = await httpGetStream(url, opts);
+    const chunks = [];
+    for await (const c of res)
+        chunks.push(c);
+    return Buffer.concat(chunks);
+};
+// Тело ответа как JSON.
+export const httpGetJson = async (url, opts = {}) => JSON.parse((await httpGetBuffer(url, opts)).toString('utf8'));

package/dist/util/lock.js

@@ -0,0 +1,58 @@
+import fs from 'node:fs';
+// Межпроцессный advisory-лок сборки. Два одновременных запуска c4builder в одном
+// каталоге (watch + ручная сборка) гоняются за dist/dist_bk и за RMW-записью
+// .c4builder.cache (Configstore читает-модифицирует-пишет весь файл целиком) —
+// теряются чексуммы, а переименования dist топчут друг друга. Лок-файл создаётся
+// атомарно (flag 'wx'), владелец пишет в него свой pid и время захвата.
+// Страховка от переиспользованного ОС-ю pid: лок старше часа считается протухшим,
+// даже если pid формально жив (легитимная сборка длиннее часа — экзотика).
+const STALE_MS = 60 * 60 * 1000;
+// EPERM = процесс существует, но сигналить ему нельзя (чужой пользователь) — жив.
+const ownerAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+};
+// Отдельный класс: watch-режим по нему отличает «занято соседней сборкой»
+// (пропустить ребилд с коротким сообщением) от настоящего падения сборки.
+export class BuildLockHeldError extends Error {
+}
+// Захват лока: возвращает release-колбэк. Занято живым процессом — BuildLockHeldError.
+// Протухший лок (мёртвый владелец / нечитаемый файл / старше STALE_MS) снимается и
+// захват повторяется один раз; в гонке двух «снявших» победит один, второй получит
+// EEXIST со свежим живым владельцем и honest-ошибку.
+export const acquireBuildLock = (lockPath) => {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            fs.writeFileSync(lockPath, JSON.stringify({ pid: process.pid, at: Date.now() }), {
+                flag: 'wx'
+            });
+            return () => {
+                fs.rmSync(lockPath, { force: true });
+            };
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+            let meta = {};
+            try {
+                meta = JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+            }
+            catch {
+                /* нечитаемый лок = протухший */
+            }
+            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}, если это остаток упавшего процесса`);
+            }
+            fs.rmSync(lockPath, { force: true });
+        }
+    }
+    throw new BuildLockHeldError(`не удалось захватить лок сборки: ${lockPath}`);
+};