@alfacapital-tech/c4builder 0.3.0 → 0.4.0-rc.2

package/dist/plugins/openspec/fences.js

@@ -0,0 +1,55 @@
+// Fenced-блоки ```plantuml / ```d2 в артефактах → диаграммы страницы (рендер общим
+// локальным движком) + ссылка `![…](name.ext)` на их месте: compose подставит картинку
+// inline, а клиентский docsify-plantuml (онлайн-рендер в браузере) не сработает —
+// fence в выводе уже отсутствует.
+import crypto from 'node:crypto';
+// Fenced-блок по CommonMark: открывающая ``` или ~~~ (≥3) с любым отступом (fence в
+// списке), инфо-строка, тело (может быть пустым), закрывающая того же вида не короче
+// открывающей. Тело захватывается вместе с завершающим переводом строки.
+const FENCE_RE = /^([ \t]*)(`{3,}|~{3,})[ \t]*([^\n]*)\n([\s\S]*?)^[ \t]*\2[`~]*[ \t]*$/gm;
+const ENGINE_EXT = { plantuml: '.puml', puml: '.puml', d2: '.d2' };
+/** Применить fn к тексту вне fenced-блоков (сами блоки — без изменений). */
+export const mapOutsideFences = (md, fn) => {
+    let out = '';
+    let last = 0;
+    for (const m of md.matchAll(FENCE_RE)) {
+        out += fn(md.slice(last, m.index)) + m[0];
+        last = m.index + m[0].length;
+    }
+    return out + fn(md.slice(last));
+};
+/**
+ * Экстрактор диаграмм одной страницы. Имя файла — `<base>-<sha1 контента>`: не зависит
+ * от позиции fence, поэтому вставка/удаление соседнего блока не сдвигает имена и не
+ * подсовывает картинку соседа из кэша; одинаковые блоки дают одну диаграмму.
+ */
+export const createFenceExtractor = () => {
+    const seen = new Set();
+    return {
+        extract(md, base) {
+            const diagrams = [];
+            const markdown = md.replace(FENCE_RE, (whole, indent, _fence, info, body) => {
+                const lang = info.trim().split(/\s+/)[0]?.toLowerCase() ?? '';
+                const ext = ENGINE_EXT[lang];
+                if (!ext)
+                    return whole;
+                // Отступ fence (в списке) снимаем со строк тела, как CommonMark.
+                const src = body
+                    .replace(/\n$/, '')
+                    .split('\n')
+                    .map((l) => (l.startsWith(indent) ? l.slice(indent.length) : l))
+                    .join('\n');
+                // PlantUML требует @startuml/@enduml; в артефактах их часто опускают.
+                const content = ext === '.puml' && !/@start\w+/.test(src) ? `@startuml\n${src}\n@enduml` : src;
+                const hash = crypto.createHash('sha1').update(content).digest('hex').slice(0, 8);
+                const file = `${base}-${hash}${ext}`;
+                if (!seen.has(file)) {
+                    seen.add(file);
+                    diagrams.push({ file, content });
+                }
+                return `${indent}![${file}](${file})`;
+            });
+            return { markdown, diagrams };
+        }
+    };
+};

package/dist/plugins/openspec/index.js

@@ -0,0 +1,73 @@
+// Встроенный плагин openspec: локальный OpenSpec-store → раздел сайта (сводка, активные
+// change'ы, спеки, архив). Диаграммы артефактов рендерятся локальным движком сборки.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { definePlugin } from "../../core/plugins/types.js";
+import { scanStore } from "./scan.js";
+import { renderArchiveIndex, renderChange, renderChangesIndex, renderMarkdown, renderSpecTree, renderSummary } from "./render.js";
+const optionsSchema = z
+    .object({
+    dir: z.string().default('openspec'),
+    mount: z.string().min(1).default('OpenSpec'),
+    // Порядок артефактов change'а; первый выводится на странице change'а, остальные —
+    // подстраницами; не перечисленные — после, по алфавиту.
+    artifacts: z.array(z.string()).default(['proposal', 'design', 'tasks'])
+})
+    .strict();
+export default definePlugin({
+    name: 'openspec',
+    options: optionsSchema,
+    watchPaths: (o) => [o.dir],
+    afterScan(ctx, o) {
+        const storeDir = path.resolve(o.dir);
+        if (!fs.existsSync(storeDir))
+            throw new Error(`OpenSpec store не найден: ${storeDir} (опция dir плагина openspec)`);
+        const store = scanStore(storeDir);
+        const { mount } = o;
+        const { options } = ctx;
+        // Страницы + файлы, на которые они ссылаются (картинки): рядом со страницей (каталог
+        // в dist уже создан addPage) и, как scan для реальных папок, в корень dist для
+        // complete-markdown; excludeOtherFiles действует и здесь.
+        const addPages = (pages, srcRoot) => {
+            for (const page of pages) {
+                ctx.addPage({ path: page.path, markdown: page.markdown, diagrams: page.diagrams });
+                if (options.EXCLUDE_OTHER_FILES)
+                    continue;
+                for (const { from, to } of page.files) {
+                    const src = path.join(srcRoot, from);
+                    const dests = [path.join(options.DIST_FOLDER, ...page.path, to)];
+                    // Ссылки вверх (`../` из дельты) от корня complete-файла всё равно никуда не ведут.
+                    if (options.GENERATE_COMPLETE_MD_FILE && !path.posix.normalize(to).startsWith('..'))
+                        dests.push(path.join(options.DIST_FOLDER, to));
+                    for (const dest of dests) {
+                        fs.mkdirSync(path.dirname(dest), { recursive: true });
+                        fs.copyFileSync(src, dest);
+                    }
+                }
+            }
+        };
+        const addChange = (change, segments) => addPages(renderChange(change, segments, o.artifacts, options), change.dir);
+        ctx.addPage({ path: [mount], markdown: renderSummary(store, mount, options) });
+        ctx.addPage({
+            path: [mount, 'Changes'],
+            markdown: renderChangesIndex(store.changes, mount, options)
+        });
+        for (const change of store.changes)
+            addChange(change, [mount, 'Changes', change.id]);
+        // Specs: индекс, промежуточные папки, страницы спек — тем же рендером, что и
+        // дельты (fenced-диаграммы локально, ссылки на файлы рядом со спекой).
+        const specsDir = path.join(storeDir, 'specs');
+        addPages(renderSpecTree(store.specs, [mount, 'Specs'], options, (pagePath, spec) => renderMarkdown(pagePath, `spec-${spec.path.join('-')}`, spec.content, {
+            srcRoot: specsDir,
+            fromDir: spec.path.join('/'),
+            options
+        })), specsDir);
+        ctx.addPage({
+            path: [mount, 'Archive'],
+            markdown: renderArchiveIndex(store.archive, mount, options)
+        });
+        for (const change of store.archive)
+            addChange(change, [mount, 'Archive', change.id]);
+    }
+});

package/dist/plugins/openspec/render.js

@@ -0,0 +1,216 @@
+// Markdown страниц раздела OpenSpec: сводка, change и его подстраницы, индексы подразделов.
+import fs from 'node:fs';
+import path from 'node:path';
+import { encodeURIPath } from "../../util/utils.js";
+import { createFenceExtractor, mapOutsideFences } from "./fences.js";
+// Ссылка на страницу сайта от корня (без ведущего «/»): так же строится sidebar,
+// а docsify без relativePath резолвит ссылки от корня сайта.
+export const pageLink = (segments, options) => encodeURIPath(path.posix.join(...segments, options.WEB_FILE_NAME || segments[segments.length - 1]));
+const fmtDate = (ms) => new Date(ms).toISOString().slice(0, 10);
+// Прогресс задач: нативный <progress> (docsify рендерит HTML в markdown) + числа и процент.
+const progressBar = (done, total) => `<progress value="${done}" max="${total}"></progress> ${done}/${total} (${Math.round((done / total) * 100)}%)`;
+const fmtProgress = (c) => c.progress ? progressBar(c.progress.done, c.progress.total) : '—';
+/** Таблица change'ов (сводка и индекс Changes): по дате изменения от новых к старым. */
+export const renderChangesIndex = (changes, mount, options) => {
+    if (!changes.length)
+        return '_No changes._';
+    const rows = [...changes]
+        .sort((a, b) => b.mtime - a.mtime)
+        .map((c) => `| [${c.id}](${pageLink([mount, 'Changes', c.id], options)}) | ${c.schema ?? '—'} | ${fmtProgress(c)} | ${fmtDate(c.mtime)} |`);
+    return ['| Change | Schema | Tasks | Updated |', '|---|---|---|---|', ...rows].join('\n');
+};
+/** Сводка store (страница mount): счётчики, суммарный прогресс, таблица активных change'ов. */
+export const renderSummary = (store, mount, options) => {
+    const withProgress = store.changes.filter((c) => c.progress);
+    const done = withProgress.reduce((s, c) => s + (c.progress?.done ?? 0), 0);
+    const total = withProgress.reduce((s, c) => s + (c.progress?.total ?? 0), 0);
+    const link = (section) => pageLink([mount, section], options);
+    return [
+        `**Active changes:** [${store.changes.length}](${link('Changes')}) · ` +
+            `**Specs:** [${store.specs.length}](${link('Specs')}) · ` +
+            `**Archived:** [${store.archive.length}](${link('Archive')}) · ` +
+            `**Tasks:** ${total ? progressBar(done, total) : '—'}`,
+        '',
+        '## Active changes',
+        '',
+        renderChangesIndex(store.changes, mount, options)
+    ].join('\n');
+};
+export const renderArchiveIndex = (archive, mount, options) => archive.length
+    ? archive.map((c) => `- [${c.id}](${pageLink([mount, 'Archive', c.id], options)})`).join('\n')
+    : '_Archive is empty._';
+/** Индекс папки спек (Specs, промежуточные папки, дельты change'а): вложенный список под prefix. */
+export const renderSpecIndex = (specs, prefix, base, options) => {
+    const under = specs.filter((s) => prefix.every((p, i) => s.path[i] === p) && s.path.length > prefix.length);
+    if (!under.length)
+        return '_No specs._';
+    // Папки — тоже строки списка (со ссылкой на свою страницу-индекс), чтобы вложенность читалась.
+    const seen = new Set();
+    const lines = [];
+    for (const s of under) {
+        for (let depth = prefix.length + 1; depth <= s.path.length; depth++) {
+            const segs = s.path.slice(0, depth);
+            const key = segs.join('/');
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const indent = '  '.repeat(depth - prefix.length - 1);
+            lines.push(`${indent}- [${segs[depth - 1]}](${pageLink([...base, ...segs], options)})`);
+        }
+    }
+    return lines.join('\n');
+};
+/** Промежуточные папки набора спек (для индексов): ['a'], ['a','b'], …, сортировано. */
+export const specFolders = (specs) => {
+    const folders = new Set();
+    for (const s of specs)
+        for (let i = 1; i < s.path.length; i++)
+            folders.add(s.path.slice(0, i).join('/'));
+    return [...folders].sort().map((f) => f.split('/'));
+};
+// Ссылки markdown: `[text](href "title")` и `![alt](src)`. Текст ссылки может содержать
+// вложенную картинку (`[![alt](img)](href)`) — альтернатива с ней стоит первой, чтобы
+// не оборваться на её `)`.
+const LINK_RE = /(!?)\[((?:!\[[^\]\n]*\]\([^)\n]*\)|[^\]\n])*)\]\(([^)\s]+)(\s+[^)]*)?\)/g;
+// docsify-title `':ignore'` (ссылка не в роутер) поверх пользовательского title: docsify
+// вырезает `:ignore` из title и оставляет остаток как обычный title.
+const ignoreTitle = (title) => {
+    const t = title.trim().replace(/^(["'])(.*)\1$/s, '$2');
+    return ` ':ignore${t ? ` ${t}` : ''}'`;
+};
+/**
+ * Markdown одного исходного файла → страница сайта: fenced-диаграммы вырезаются, ссылки
+ * на другие страницы источника (`target`, `#x` → `?id=x`) — на их адреса, прочие
+ * относительные ссылки на существующие файлы источника регистрируются для копирования к
+ * странице (картинки docsify грузит относительно страницы, обычные ссылки — от корня сайта).
+ * `fromDir` — posix-каталог файла относительно `srcRoot` (ссылки в нём резолвятся от файла).
+ */
+export const renderMarkdown = (pagePath, base, content, { srcRoot, fromDir = '', target = () => undefined, options }) => {
+    const { markdown, diagrams } = createFenceExtractor().extract(content, base);
+    const files = [];
+    const rewrite = (t) => t.replace(LINK_RE, (whole, bang, text, href, title = '') => {
+        const inner = text.includes('![') ? rewrite(text) : text;
+        if (/^[a-z][a-z0-9+.-]*:|^[#/]/i.test(href))
+            return `${bang}[${inner}](${href}${title})`; // абсолютные, якоря, от корня
+        const [rawPath, hash] = href.split('#');
+        let decoded;
+        try {
+            decoded = decodeURI(rawPath);
+        }
+        catch {
+            return whole; // битый %-escape — не ссылка на файл, оставляем как есть
+        }
+        const rel = path.posix.normalize(path.posix.join(fromDir, decoded));
+        if (rel.startsWith('../'))
+            return whole;
+        const page = target(rel);
+        if (page)
+            return `${bang}[${inner}](${pageLink(page, options)}${hash ? `?id=${hash}` : ''}${title})`;
+        const abs = path.join(srcRoot, rel);
+        if (!fs.existsSync(abs) || fs.statSync(abs).isDirectory())
+            return whole;
+        files.push({ from: rel, to: decoded });
+        return bang
+            ? `![${inner}](${href}${title})`
+            : `[${inner}](${encodeURIPath(path.posix.join(...pagePath, decoded))}${ignoreTitle(title)})`;
+    });
+    return { path: pagePath, markdown: mapOutsideFences(markdown, rewrite).trim(), diagrams, files };
+};
+/**
+ * Страницы дерева спек под `base`: корень, промежуточные папки, спеки. Папка с собственной
+ * spec.md — одна страница (спека + список вложенных), иначе addPage упал бы на коллизии.
+ * `render` — рендер содержимого спеки в страницу с нужным источником.
+ */
+export const renderSpecTree = (specs, base, options, render) => {
+    const byKey = new Map(specs.map((s) => [s.path.join('/'), s]));
+    const keys = new Set(['', ...specFolders(specs).map((f) => f.join('/')), ...byKey.keys()]);
+    return [...keys].sort().map((key) => {
+        const prefix = key ? key.split('/') : [];
+        const pagePath = [...base, ...prefix];
+        const spec = byKey.get(key);
+        const page = spec
+            ? render(pagePath, spec)
+            : { path: pagePath, markdown: '', diagrams: [], files: [] };
+        const nested = specs.some((s) => s.path.length > prefix.length && prefix.every((p, i) => s.path[i] === p));
+        if (nested || !spec)
+            page.markdown = [page.markdown, renderSpecIndex(specs, prefix, base, options)]
+                .filter(Boolean)
+                .join('\n\n');
+        return page;
+    });
+};
+/** Артефакты в порядке опции `artifacts`; не перечисленные — после, по алфавиту. */
+const orderArtifacts = (artifacts, order) => [...artifacts].sort((a, b) => {
+    const ia = order.indexOf(a.name);
+    const ib = order.indexOf(b.name);
+    if (ia !== -1 || ib !== -1)
+        return (ia === -1 ? 99 : ia) - (ib === -1 ? 99 : ib);
+    return a.name.localeCompare(b.name);
+});
+/**
+ * Страницы change'а: главная (шапка с метаданными, прогрессом и ссылками на подстраницы +
+ * первый артефакт из `order`, если он есть), подстраницы остальных артефактов и подраздел
+ * `specs` дельт (страница на capability, структура папок). Артефакт с именем `specs`
+ * делит страницу с индексом дельт.
+ */
+export const renderChange = (change, segments, order, options) => {
+    const ordered = orderArtifacts(change.artifacts, order);
+    const inline = ordered[0]?.name === order[0] ? ordered[0] : undefined;
+    const deltas = change.deltas.map((d) => ({
+        path: d.relPath
+            .replace(/^specs\//, '')
+            .replace(/\/spec\.md$/, '')
+            .split('/'),
+        content: d.content
+    }));
+    const specsBase = [...segments, 'specs'];
+    // Страница сайта для относительной (от корня change'а) ссылки на артефакт/дельту.
+    const target = (rel) => {
+        const md = rel.match(/^([^/]+)\.md$/i);
+        if (md && change.artifacts.some((a) => a.name === md[1]))
+            return md[1] === inline?.name ? segments : [...segments, md[1]];
+        const delta = deltas.find((d) => `specs/${d.path.join('/')}/spec.md` === rel);
+        return delta && [...specsBase, ...delta.path];
+    };
+    const render = (pagePath, base, content, fromDir = '') => renderMarkdown(pagePath, base, content, { srcRoot: change.dir, fromDir, target, options });
+    const subpages = ordered
+        .filter((a) => a !== inline)
+        .map((a) => render([...segments, a.name], a.name, a.content));
+    const links = [
+        ...subpages.map((p) => `[${p.path[p.path.length - 1]}](${pageLink(p.path, options)})`),
+        ...(deltas.length && !subpages.some((p) => p.path[p.path.length - 1] === 'specs')
+            ? [`[specs](${pageLink(specsBase, options)})`]
+            : [])
+    ];
+    const head = [
+        change.schema && `**Schema:** ${change.schema}`,
+        change.created && `**Created:** ${change.created}`,
+        `**Tasks:** ${fmtProgress(change)}`,
+        `**Updated:** ${fmtDate(change.mtime)}`
+    ]
+        .filter(Boolean)
+        .join(' · ');
+    const main = inline ? render(segments, inline.name, inline.content) : undefined;
+    const pages = [
+        {
+            path: segments,
+            markdown: [head, links.join(' · '), main?.markdown].filter(Boolean).join('\n\n'),
+            diagrams: main?.diagrams ?? [],
+            files: main?.files ?? []
+        },
+        ...subpages
+    ];
+    if (deltas.length) {
+        const tree = renderSpecTree(deltas, specsBase, options, (pagePath, spec) => render(pagePath, `spec-${spec.path.join('-')}`, spec.content, `specs/${spec.path.join('/')}`));
+        // Артефакт specs.md и корень дельт — один путь: сливаем в страницу артефакта.
+        const artifact = pages.find((p) => p.path.length === segments.length + 1 && p.path.at(-1) === 'specs');
+        for (const p of tree) {
+            if (artifact && p.path.length === specsBase.length) {
+                artifact.markdown = [artifact.markdown, p.markdown].filter(Boolean).join('\n\n');
+            }
+            else
+                pages.push(p);
+        }
+    }
+    return pages;
+};

package/dist/plugins/openspec/scan.js

@@ -0,0 +1,99 @@
+// Сканер OpenSpec-store: активные change'ы, архив, спеки. Только файловая система —
+// `openspec` CLI не шеллим (сборка не зависит от его наличия/версии).
+import fs from 'node:fs';
+import path from 'node:path';
+const listDirs = (dir) => fs.existsSync(dir)
+    ? fs
+        .readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+        .map((e) => e.name)
+        .sort()
+    : [];
+// Все spec.md под dir рекурсивно: относительные posix-пути (сортировано).
+const findSpecFiles = (dir, rel = '') => {
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const e of fs
+        .readdirSync(dir, { withFileTypes: true })
+        .sort((a, b) => a.name.localeCompare(b.name))) {
+        const r = rel ? `${rel}/${e.name}` : e.name;
+        if (e.isDirectory())
+            out.push(...findSpecFiles(path.join(dir, e.name), r));
+        else if (e.name === 'spec.md')
+            out.push(r);
+    }
+    return out;
+};
+// Прогресс по чекбоксам: `- [ ]` / `- [x]` в любом месте tasks.md.
+export const taskProgress = (tasks) => {
+    const boxes = [...tasks.matchAll(/^[ \t]*[-*+][ \t]+\[([ xX])\]/gm)];
+    if (!boxes.length)
+        return undefined;
+    return { done: boxes.filter((m) => m[1] !== ' ').length, total: boxes.length };
+};
+// Метаданные `.openspec.yaml` построчно: нужны два скаляра, yaml-парсер избыточен.
+const readMeta = (file) => {
+    if (!fs.existsSync(file))
+        return {};
+    const meta = {};
+    for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+        const m = line.match(/^(schema|created):\s*(.+?)\s*$/);
+        if (m)
+            meta[m[1]] = m[2].replace(/^["']|["']$/g, '');
+    }
+    return meta;
+};
+const scanChange = (dir) => {
+    const files = fs.readdirSync(dir, { withFileTypes: true });
+    let mtime = 0;
+    const touch = (file) => {
+        mtime = Math.max(mtime, fs.statSync(file).mtimeMs);
+    };
+    const artifacts = files
+        .filter((e) => e.isFile() && e.name.toLowerCase().endsWith('.md'))
+        .map((e) => e.name)
+        .sort()
+        .map((name) => {
+        const file = path.join(dir, name);
+        touch(file);
+        return { name: name.slice(0, -3), content: fs.readFileSync(file, 'utf8') };
+    });
+    const deltas = findSpecFiles(path.join(dir, 'specs'), 'specs').map((relPath) => {
+        const file = path.join(dir, relPath);
+        touch(file);
+        return { relPath, content: fs.readFileSync(file, 'utf8') };
+    });
+    const metaFile = path.join(dir, '.openspec.yaml');
+    if (fs.existsSync(metaFile))
+        touch(metaFile);
+    const tasks = artifacts.find((a) => a.name === 'tasks');
+    return {
+        id: path.basename(dir),
+        dir,
+        artifacts,
+        deltas,
+        ...readMeta(metaFile),
+        progress: tasks ? taskProgress(tasks.content) : undefined,
+        mtime
+    };
+};
+/** Читает store целиком; отсутствующие подпапки (changes/, specs/) — пустые списки. */
+export const scanStore = (storeDir) => {
+    const changesDir = path.join(storeDir, 'changes');
+    const archiveDir = path.join(changesDir, 'archive');
+    const specsDir = path.join(storeDir, 'specs');
+    return {
+        changes: listDirs(changesDir)
+            .filter((n) => n !== 'archive')
+            .map((n) => scanChange(path.join(changesDir, n))),
+        // Архив — от новых к старым: имя начинается с даты архивации.
+        archive: listDirs(archiveDir)
+            .reverse()
+            .map((n) => scanChange(path.join(archiveDir, n))),
+        specs: findSpecFiles(specsDir).map((rel) => ({
+            path: rel.split('/').slice(0, -1),
+            content: fs.readFileSync(path.join(specsDir, rel), 'utf8')
+        }))
+    };
+};

package/dist/util/archive.js

@@ -0,0 +1,61 @@
+// Распаковка архивов (zip через yauzl, tar.gz через node-tar) — общий слой для
+// JRE-резолвера и резолвера источников плагинов. Оба формата защищены от выхода
+// записей за целевой каталог: tar — самим node-tar (≥6 по умолчанию), zip — здесь.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+// yauzl/tar грузятся лениво (только при распаковке) — не тянем их на импорте модуля.
+const require = createRequire(import.meta.url);
+// Защита от 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);
+};
+export 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.
+            if (!isPathInside(destDir, entry.fileName)) {
+                return reject(new Error(`Небезопасный путь в архиве (выход за каталог): ${entry.fileName}`));
+            }
+            // Симлинки пропускаем: в недоверенном архиве симлинк мог бы указывать
+            // за пределы каталога.
+            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 });
+                return zip.readEntry();
+            }
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            zip.openReadStream(entry, (e, rs) => {
+                if (e)
+                    return reject(e);
+                const ws = fs.createWriteStream(dest);
+                ws.on('error', reject);
+                ws.on('finish', () => {
+                    const mode = (entry.externalFileAttributes >>> 16) & 0o777;
+                    if (mode) {
+                        try {
+                            fs.chmodSync(dest, mode);
+                        }
+                        catch {
+                            /* права не критичны на windows */
+                        }
+                    }
+                    zip.readEntry();
+                });
+                rs.pipe(ws);
+            });
+        });
+        zip.on('end', resolve);
+        zip.on('error', reject);
+        zip.readEntry();
+    });
+});
+export const extractTarGz = (archive, destDir) => require('tar').x({ file: archive, cwd: destDir });

package/dist/util/glob.js

@@ -0,0 +1,66 @@
+// Мини-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';
+export const globToRegExp = (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 {
+                re += `(?:${glob
+                    .slice(i + 1, end)
+                    .split(',')
+                    .map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+                    .join('|')})`;
+                i = end;
+            }
+        }
+        else
+            re += c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+    return new RegExp(`^${re}$`);
+};
+/**
+ * Файлы под 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();
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfacapital-tech/c4builder",
-  "version": "0.3.0",
+  "version": "0.4.0-rc.2",
   "description": "A CLI tool designed to compile a folder structure of markdowns and plant uml files into a site, single file markdown or a collection of markdowns with links",
   "type": "module",
   "main": "dist/index.js",

package/vendor/swagger-ui/README.md

@@ -0,0 +1,6 @@
+# swagger-ui
+
+`swagger-ui.css` — стили swagger-ui-dist **5.32.1** (та же версия, что `docsify/swagger-ui-bundle.js`,
+sha256 бандла совпадает с npm-пакетом). Подключается только плагином `openapi` (ассет →
+`dist/vendor/plugins/openapi/`), поэтому лежит отдельно от `docsify/`, который копируется в каждый сайт целиком.
+Обновлять парой с бандлом: `npm pack swagger-ui-dist@<v>` → `swagger-ui-bundle.js` и `swagger-ui.css`.