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

package/dist/core/plugins/tree.js

@@ -0,0 +1,83 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { engineForExt } from "../scan/tree.js";
+// Виртуальные элементы дерева (добавлены плагинами, каталога на диске нет). Нужно
+// лишь для правила коллизий в addPage: реальную папку затирать нельзя, а свой же
+// пустой промежуточный узел плагин вправе наполнить позже.
+const VIRTUAL = new WeakSet();
+export const isVirtual = (item) => VIRTUAL.has(item);
+// Индекс сразу за концом поддерева элемента: дерево DFS-упорядочено, потомки идут
+// подряд за родителем — вставка туда сохраняет порядок обхода (sidebar/навигация).
+const subtreeEnd = (tree, parent) => {
+    const prefix = parent.dir + path.sep;
+    let i = tree.indexOf(parent) + 1;
+    while (i < tree.length && tree[i].dir.startsWith(prefix))
+        i++;
+    return i;
+};
+/**
+ * Добавляет виртуальную страницу в дерево сборки: считает `dir`/`level`/`parent` как
+ * scan (dir = ROOT_FOLDER/сегменты), дополняет `descendants` родителя, вставляет в конец
+ * поддерева родителя; недостающие промежуточные сегменты создаёт пустыми узлами
+ * (авто-заголовок, как папка без README). Каталог в dist создаётся здесь же — compose
+ * пишет страницы без mkdir, полагаясь на scan.
+ */
+export const addPage = (tree, options, page) => {
+    const segments = page.path;
+    if (!segments.length || segments.some((s) => !s || /[\\/]/.test(s) || s === '.' || s === '..'))
+        throw new Error(`addPage: некорректный путь страницы ${JSON.stringify(segments)}`);
+    const root = tree.find((x) => !x.parent);
+    if (!root)
+        throw new Error('addPage: в дереве нет корневого элемента');
+    let parent = root;
+    let item = root;
+    for (const [i, seg] of segments.entries()) {
+        const dir = path.join(parent.dir, seg);
+        const last = i === segments.length - 1;
+        const existing = tree.find((x) => x.dir === dir);
+        if (existing) {
+            if (last) {
+                if (!VIRTUAL.has(existing))
+                    throw new Error(`addPage: путь ${segments.join('/')} занят реальной папкой ${dir} — переименуйте раздел плагина (mount)`);
+                if (existing.mdFiles.length || existing.diagrams.length)
+                    throw new Error(`addPage: страница ${segments.join('/')} уже добавлена`);
+            }
+            item = existing;
+        }
+        else {
+            item = {
+                dir,
+                name: seg,
+                level: dir.split(path.sep).length,
+                parent: parent.dir,
+                mdFiles: [],
+                diagrams: [],
+                descendants: []
+            };
+            VIRTUAL.add(item);
+            parent.descendants.push(seg);
+            tree.splice(subtreeEnd(tree, parent), 0, item);
+            if (options.GENERATE_WEBSITE || options.GENERATE_MD || options.GENERATE_LOCAL_IMAGES)
+                fs.mkdirSync(path.join(options.DIST_FOLDER, dir.replace(options.ROOT_FOLDER, '')), {
+                    recursive: true
+                });
+        }
+        parent = item;
+    }
+    const md = page.markdown === undefined ? [] : Array.isArray(page.markdown) ? page.markdown : [page.markdown];
+    item.mdFiles.push(...md);
+    for (const d of page.diagrams ?? []) {
+        const ext = path.extname(d.file).toLowerCase();
+        const engine = engineForExt(ext);
+        if (!engine)
+            throw new Error(`addPage: у диаграммы "${d.file}" страницы ${segments.join('/')} неизвестное расширение`);
+        item.diagrams.push({
+            dir: d.file,
+            ext,
+            engine,
+            content: d.content,
+            isDitaa: engine === 'plantuml' && /@startditaa/i.test(d.content)
+        });
+    }
+    return item;
+};

package/dist/core/plugins/types.js

@@ -0,0 +1,2 @@
+/** Identity ради вывода типа опций из схемы. */
+export const definePlugin = (plugin) => plugin;

package/dist/core/render/d2renderer.js

@@ -81,7 +81,9 @@ const resolveImport = (ref, fromDir) => {
 // пробел — иначе инлайновый spread `x: { ...@lib }` захватил бы `lib }`. Флаг `u` —
 // корректный юникод. Хвостовые `.key`-сегменты частичного импорта отрезает resolveImport.
 const IMPORT_RE = /(?<!\w)@(?:"([^"\n]+)"|([^\s"#;}\n][^#;}\n]*?)\s*(?=[#;}\n]|$))/gu;
-const collectFiles = (entryAbs, acc = new Map()) => {
+// seed — контент входного файла из дерева сборки: у виртуальных страниц плагинов
+// файла на диске нет, а импорты (`@…`) по-прежнему резолвятся от его каталога.
+const collectFiles = (entryAbs, acc = new Map(), seed) => {
     const abs = path.resolve(entryAbs);
     if (acc.has(abs))
         return acc;
@@ -89,7 +91,7 @@ const collectFiles = (entryAbs, acc = new Map()) => {
     try {
         // Строго UTF-8: язык D2 определён поверх UTF-8, опция CHARSET конфига относится
         // к PlantUML (уходит в -charset) и на .d2 сознательно не распространяется.
-        content = fs.readFileSync(abs, 'utf-8');
+        content = seed ?? fs.readFileSync(abs, 'utf-8');
     }
     catch {
         return acc;
@@ -117,14 +119,14 @@ let filesMemo = null;
 const clearD2FileCache = () => {
     filesMemo = null;
 };
-const collectFilesCached = (entryAbs) => {
+const collectFilesCached = (entryAbs, seed) => {
     const abs = path.resolve(entryAbs);
     if (!filesMemo)
         filesMemo = new Map();
     const hit = filesMemo.get(abs);
     if (hit)
         return hit;
-    const built = collectFiles(abs);
+    const built = collectFiles(abs, new Map(), seed);
     filesMemo.set(abs, built);
     return built;
 };
@@ -144,8 +146,8 @@ const commonAncestor = (files) => {
     return common.join(path.sep) || path.sep;
 };
 // Подготовить аргументы compile(): виртуальная fs (все файлы графа) + inputPath.
-const buildCompileRequest = (entryAbs) => {
-    const files = collectFilesCached(entryAbs);
+const buildCompileRequest = (entryAbs, seed) => {
+    const files = collectFilesCached(entryAbs, seed);
     // Пустой граф = не прочитался сам входной файл (удалён/недоступен — гонка в watch).
     // Без guard'а commonAncestor([]) давал бы сырой TypeError (Math.min()=Infinity).
     if (files.size === 0) {
@@ -170,9 +172,9 @@ const d2ErrorText = (message) => {
     catch { }
     return message;
 };
-const renderD2 = async (entryAbs, { layout = 'dagre' } = {}) => {
+const renderD2 = async (entryAbs, { layout = 'dagre', seed } = {}) => {
     const d2 = await getD2();
-    const { fs: fsMap, inputPath } = buildCompileRequest(entryAbs);
+    const { fs: fsMap, inputPath } = buildCompileRequest(entryAbs, seed);
     let result;
     try {
         result = await d2.compile({ fs: fsMap, inputPath, options: { layout } });
@@ -196,9 +198,9 @@ const renderD2 = async (entryAbs, { layout = 'dagre' } = {}) => {
 // диаграммы — аналог foldIncludes для PlantUML.
 // Путь в материале — относительный к cwd, posix-разделители: чексумма не зависит
 // от машины/чекаута/ОС (абсолютный путь делал кеш непереносимым).
-const foldD2Imports = (entryAbs) => {
+const foldD2Imports = (entryAbs, seed) => {
     const abs = path.resolve(entryAbs);
-    const files = collectFilesCached(entryAbs);
+    const files = collectFilesCached(entryAbs, seed);
     const rel = (p) => path.relative(process.cwd(), p).split(path.sep).join('/');
     // Мемоизированную Map не мутируем (её же использует buildCompileRequest) —
     // входной файл исключаем фильтром, а не delete. Сортировка по относительному

package/dist/core/render/diagrams.js

@@ -250,7 +250,7 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
             // entryPath !== null ⟺ engine === 'd2' — используем как сужение типа вместо assertion.
             const entryPath = diagram.engine === 'd2' ? path.join(item.dir, diagram.dir) : null;
             const includes = entryPath !== null
-                ? foldD2Imports(entryPath)
+                ? foldD2Imports(entryPath, body)
                 : foldIncludes(body, item.dir, item.dir, new Set());
             const outFormat = diagramOutputFormat(diagram, options);
             // renderKey: параметры, влияющие на БАЙТЫ вывода помимо контента и графа
@@ -262,20 +262,25 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
                 ? `d2\0${d2EngineVersion()}\0layout=${options.D2_LAYOUT}\0fmt=${outFormat}`
                 : `puml\0${VENDORED_JAR.version}\0charset=${options.CHARSET}\0fmt=${outFormat}\0ditaa=${diagram.isDitaa}`) +
                 `\0font=${fontCacheTag(options)}`;
+            const outName = `${path.parse(diagram.dir).name}.${outFormat}`;
+            const relOut = path.join(item.dir.replace(options.ROOT_FOLDER, ''), outName);
+            // Путь выхода — тоже в чексумме: восстановление из бэкапа идёт по паре
+            // «чексумма встречалась» + «бэкап с этим именем есть», иначе диаграммы,
+            // обменявшиеся содержимым (или сдвинувшиеся имена fence-блоков плагинов),
+            // молча получали бы чужую старую картинку.
             const cksum = crypto
                 .createHash('sha256')
-                .update(body + includes + renderKey, 'utf-8')
+                .update(`${body}${includes}${renderKey}\0out=${relOut.split(path.sep).join('/')}`, 'utf-8')
                 .digest('hex');
             // Записи копим в порядке обхода дерева, СИНХРОННО и до запуска задач:
             // порядок массива не зависит от того, кто из воркеров финиширует раньше —
             // .c4builder.cache детерминирован (важно для сравнения кэша между сборками).
             const cksumEntry = { cksum, ok: false };
             checksumEntries.push(cksumEntry);
-            const outName = `${path.parse(diagram.dir).name}.${outFormat}`;
             // path to backup image file
-            const bkFilePath = path.join(bkFolderName, item.dir.replace(options.ROOT_FOLDER, ''), outName);
+            const bkFilePath = path.join(bkFolderName, relOut);
             // path to image in dist folder
-            const filePath = path.join(options.DIST_FOLDER, item.dir.replace(options.ROOT_FOLDER, ''), outName);
+            const filePath = path.join(options.DIST_FOLDER, relOut);
             // if checksum exists (diagram untouched) and file/image exists - copy image back from backup folder
             if (oldChecksums.has(cksum) && fs.existsSync(bkFilePath)) {
                 // Восстановление из бэкапа — без рендера; JVM/worker не задействованы,
@@ -299,7 +304,7 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
                 let rendered;
                 try {
                     if (entryPath !== null) {
-                        rendered = await renderD2(entryPath, { layout: options.D2_LAYOUT });
+                        rendered = await renderD2(entryPath, { layout: options.D2_LAYOUT, seed: body });
                     }
                     else {
                         // Резолв JRE отложен до первого реального PlantUML-рендера (эта

package/dist/core/render/jre.js

@@ -9,12 +9,12 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 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);
+// Распаковка (zip-slip-guard общий) вынесена в util/archive — её же использует
+// резолвер источников плагинов. isPathInside ре-экспортируется для тестов.
+import { extractZip, extractTarGz, isPathInside } from "../../util/archive.js";
+export { isPathInside };
 const MAJOR_MIN = 17; // минимальная годная мажорная версия системной java
 const TEMURIN_FEATURE = 21; // скачиваем ровно Temurin 21 JRE
 const JAVA_BIN = process.platform === 'win32' ? 'java.exe' : 'java';
@@ -207,60 +207,7 @@ const downloadAndVerify = async (link, expectedSha, destFile) => {
         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 });
-                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();
-    });
-});
-const extractArchive = (archive, destDir, isZip) => isZip ? extractZip(archive, destDir) : require('tar').x({ file: archive, cwd: destDir });
+const extractArchive = (archive, destDir, isZip) => isZip ? extractZip(archive, destDir) : extractTarGz(archive, destDir);
 // (3) скачивание: assets API → sha256 (до распаковки) → распаковка в staging →
 // атомарная замена кеша. Распаковываем НЕ в финальный каталог, а в свой staging
 // (<dir>.tmp-<pid>, уникальный на процесс → параллельные сборки не топчут друг друга),

package/dist/plugins/index.js

@@ -0,0 +1,4 @@
+export const BUILTIN_PLUGINS = {
+    openspec: async () => (await import("./openspec/index.js")).default,
+    openapi: async () => (await import("./openapi/index.js")).default
+};

package/dist/plugins/openapi/index.js

@@ -0,0 +1,95 @@
+// Встроенный плагин openapi: набор OpenAPI-спек (локальная папка или архив репозитория
+// контрактов) → раздел сайта со страницей swagger-ui на спеку. Полностью офлайн:
+// бандл swagger-ui и CSS — вендорные ассеты плагина, спеки копируются в dist статикой
+// с сохранением относительных путей ($ref).
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { outputDirs } from "../../config/options.js";
+import { redactUrl } from "../../core/plugins/source.js";
+import { definePlugin } from "../../core/plugins/types.js";
+import { globFiles } from "../../util/glob.js";
+import { VENDOR_DIR } from "../../util/paths.js";
+import { encodeURIPath } from "../../util/utils.js";
+const optionsSchema = z
+    .object({
+    mount: z.string().min(1).default('API'),
+    dir: z.string().min(1).optional(),
+    archive: z.string().optional(),
+    subdir: z.string().optional(),
+    headers: z.record(z.string(), z.string()).optional(),
+    glob: z.string().default('**/openapi.{yaml,yml,json}')
+})
+    .strict()
+    .refine((o) => (o.dir === undefined) !== (o.archive === undefined), {
+    message: 'нужен ровно один источник: dir либо archive'
+});
+// Имя страницы: родительская папка спеки; в корне источника — имя файла без расширения.
+const pageName = (rel) => {
+    const dir = path.posix.dirname(rel);
+    return dir === '.' ? path.posix.basename(rel).replace(/\.[^.]+$/, '') : path.posix.basename(dir);
+};
+export default definePlugin({
+    name: 'openapi',
+    options: optionsSchema,
+    requires: { executeScript: true },
+    // Бандл объявлен ассетом, а не взят из шаблона docsify: пользовательский docsifyTemplate
+    // может его не подключать; при дефолтном шаблоне injectPluginAssets дубль не добавит.
+    assets: {
+        styles: [path.join(VENDOR_DIR, 'swagger-ui', 'swagger-ui.css')],
+        scripts: [path.join(VENDOR_DIR, 'docsify', 'swagger-ui-bundle.js')]
+    },
+    watchPaths: (o) => (o.dir ? [path.join(o.dir, o.subdir ?? '')] : []),
+    async afterScan(ctx, o) {
+        const { mount } = o;
+        const source = o.dir ?? redactUrl(o.archive ?? '');
+        const root = await ctx.source({
+            dir: o.dir,
+            archive: o.archive,
+            subdir: o.subdir,
+            headers: o.headers
+        });
+        // Источник может быть предком выходного каталога (dir: '.') — свои же копии
+        // спек прошлой сборки в dist/dist_bk не считаются источником.
+        const skip = outputDirs(ctx.options);
+        const files = globFiles(root, o.glob, skip);
+        if (!files.length)
+            throw new Error(`по шаблону "${o.glob}" в ${source} не найдено ни одной спеки`);
+        const names = new Map();
+        for (const rel of files) {
+            const name = pageName(rel);
+            const dup = names.get(name);
+            if (dup)
+                throw new Error(`две спеки дают одно имя страницы "${name}": ${dup} и ${rel}`);
+            names.set(name, rel);
+        }
+        // Статикой в dist — все yaml/json источника, а не только совпавшие с glob: $ref
+        // может вести в общие схемы (components), не являющиеся спеками.
+        for (const rel of globFiles(root, '**/*.{yaml,yml,json}', skip)) {
+            const dest = path.join(ctx.options.DIST_FOLDER, mount, '_specs', rel);
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            fs.copyFileSync(path.join(root, rel), dest);
+        }
+        const sorted = [...names.entries()].sort(([a], [b]) => a.localeCompare(b));
+        const link = (name) => encodeURIPath(path.posix.join(mount, name, ctx.options.WEB_FILE_NAME || name));
+        ctx.addPage({
+            path: [mount],
+            markdown: sorted.map(([name, rel]) => `- [${name}](${link(name)}) — \`${rel}\``).join('\n')
+        });
+        for (const [name, rel] of sorted) {
+            // Спека грузится swagger-ui по ссылке от корня сайта (SPA: base = index.html);
+            // относительные $ref внутри спек резолвятся от её URL — структура сохранена.
+            const specUrl = encodeURIPath(path.posix.join(mount, '_specs', rel));
+            const domId = `swagger-${name.replace(/[^A-Za-z0-9_-]/g, '_')}`;
+            ctx.addPage({
+                path: [mount, name],
+                markdown: [
+                    `<div id="${domId}"></div>`,
+                    '<script>',
+                    `SwaggerUIBundle({ url: '${specUrl}', dom_id: '#${domId}' });`,
+                    '</script>'
+                ].join('\n')
+            });
+        }
+    }
+});

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]);
+    }
+});