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

package/README.MD

@@ -286,6 +286,124 @@ By default this is disabled. If enabled, the output will no longer include the a
 
 The current entity structure is inserted after the header
 
+## Plugins
+
+Plugins extend the build with content from outside `rootFolder` (virtual pages that go through
+the regular pipeline: sidebar, search, `generateMD`, complete markdown, local diagram render)
+and with site assets. They are listed in `.c4builder` under `plugins` — either `"name"` or
+`["name", { ...options }]`:
+
+```json
+{
+  "plugins": [
+    "openspec",
+    ["openapi", { "dir": "../contracts", "glob": "*/openapi.yaml" }]
+  ]
+}
+```
+
+A plugin identifier resolves in this order: a built-in name (`openspec`, `openapi`) → a local
+ESM module (`./plugins/my.mjs`, `../shared/plugin.mjs`, absolute path) → an npm package resolved
+from the project directory. Options are validated by the plugin's own zod schema **before** the
+build starts (built-in plugins are strict — an unknown option key is an error); `${ENV_VAR}`
+placeholders inside string options are replaced from the environment (unset → empty string) and
+never printed (archive URLs appear in messages without their query string, so a token passed as
+`?private_token=${TOKEN}` stays out of the logs). A malformed `plugins` entry always fails the
+build (it is the one key the wizard cannot repair). Older c4builder versions ignore the `plugins`
+key, so a rollback keeps building.
+
+### `openspec` — publish a local OpenSpec store
+
+Renders an [OpenSpec](https://github.com/Fission-AI/OpenSpec) store as a site section:
+a summary (counters, task progress), a page per active change, the specs tree and the archive.
+A change page shows the header (schema, dates, task progress, links to subpages) plus the first
+artifact of `artifacts` (by default `proposal` — the "why" is visible without a click); the
+remaining artifacts (`design`, `tasks`, then any other `*.md` alphabetically) are subpages, and
+spec deltas live under `specs/…` mirroring the folder layout (a folder that has its own
+`spec.md` and nested specs gets one page: the spec followed by the list of nested ones).
+```` ```plantuml ```` / ```` ```d2 ```` fences inside artifacts, deltas and store specs are
+rendered by the **local** engines (nothing is sent to plantuml.com); the image name is derived
+from the fence content, so inserting or reordering fences never reuses a neighbour's cached
+image. Relative links between artifacts of a change point to their pages, referenced files
+(images, notes) are copied next to the page (and to the output root for the complete markdown;
+`excludeOtherFiles` applies). The store folder is watched in `-w`.
+
+| Option      | Default                        | Meaning                                                        |
+|-------------|--------------------------------|----------------------------------------------------------------|
+| `dir`       | `openspec`                     | store folder (relative to the project directory)               |
+| `mount`     | `OpenSpec`                     | section name (and its path in the output folder)               |
+| `artifacts` | `["proposal","design","tasks"]`| artifact order; the first one is shown on the change page itself |
+
+### `openapi` — swagger-ui pages for a set of OpenAPI specs
+
+Finds specs by `glob` in a local folder (`dir`) **or** in a `tar.gz`/`zip` archive fetched over
+HTTP (`archive`, e.g. a GitLab/GitHub repository archive URL; `subdir` picks a folder inside it,
+`headers` adds request headers such as `{"PRIVATE-TOKEN": "${GITLAB_TOKEN}"}` — empty values are
+dropped, so the same config works with and without a token). One page per spec, named after the
+spec's parent folder (file name for specs in the source root), plus an index. All `yaml`/`yml`/
+`json` files of the source are copied into `<mount>/_specs/…` keeping their relative layout, so
+relative `$ref`s (including shared schema files that do not match `glob`) keep resolving; pages
+load swagger-ui from the bundled `vendor/` files — no CDN, no access to the source repository is
+needed by readers. The plugin forces `executeScript` (logged) and injects `swagger-ui.css` and
+`swagger-ui-bundle.js` into `index.html` after the template is rendered (skipped when the template
+already links the bundle), so custom `docsifyTemplate`s need no change. The output folder is never
+treated as a source (`dir: "."` is fine). Archives are downloaded once per process (watch mode
+reuses them).
+
+| Option    | Default                          | Meaning                                  |
+|-----------|----------------------------------|------------------------------------------|
+| `mount`   | `API`                            | section name                             |
+| `dir`     | —                                | local folder with specs (watched in `-w`)|
+| `archive` | —                                | HTTP(S) URL of a tar.gz/zip archive      |
+| `subdir`  | —                                | folder inside the archive / `dir`        |
+| `headers` | —                                | HTTP headers for the archive request     |
+| `glob`    | `**/openapi.{yaml,yml,json}`     | spec pattern (`**`, `*`, `?`, `{a,b}`)   |
+
+Example for a repository that keeps its `openspec/` store next to the C4 sources and consumes
+contracts from another repository:
+
+```json
+{
+  "plugins": [
+    "openspec",
+    ["openapi", {
+      "archive": "https://gitlab.example.com/api/v4/projects/123/repository/archive.tar.gz?sha=main",
+      "glob": "*/openapi.yaml",
+      "headers": { "PRIVATE-TOKEN": "${GITLAB_TOKEN}" }
+    }]
+  ]
+}
+```
+
+### Writing a plugin
+
+A plugin is an ESM module whose default export is a plain object (use `definePlugin` from
+`@alfacapital-tech/c4builder/dist/core/plugins/types.js` for typing):
+
+```js
+import { z } from 'zod';
+export default {
+  name: 'changelog',
+  options: z.object({ file: z.string().default('CHANGELOG.md') }).strict(), // optional
+  watchPaths: (opts) => [opts.file],                                          // optional
+  assets: { styles: ['/abs/path/x.css'], scripts: ['/abs/path/x.js'] },      // optional
+  requires: { executeScript: true },                                          // optional
+  async afterScan(ctx, opts) {
+    // ctx.tree, ctx.options — the build tree/options; ctx.source({ dir } | { archive, subdir, headers })
+    // resolves a folder; ctx.addPage adds a virtual page (missing parents become index pages).
+    ctx.addPage({
+      path: ['Changelog'],
+      markdown: '## Latest\n\n![flow](flow.puml)',
+      diagrams: [{ file: 'flow.puml', content: '@startuml\nA -> B\n@enduml' }]
+    });
+  },
+  async afterBuild(ctx, opts) { /* ctx.distFolder, ctx.options — copy extra files, run checks */ }
+};
+```
+
+Hooks run in the order of the `plugins` list; an exception aborts the build with the plugin's
+name (the previous `dist` backup is kept as usual).
+
 # Future plans
 
 I would like to bind the **build** phase to the C4 model. It could parse the diagrams and know what Person/System/Component/Container is related to what and help with additional validation. Maybe even export to [structurizr](https://structurizr.com/) or vice versa.
@@ -355,10 +473,19 @@ Publishes to dist-tag `latest`.
 
 ## Unreleased
 
+- Plugin system: `plugins` key in `.c4builder`, `afterScan`/`afterBuild` hooks, virtual pages,
+  plugin assets injected into `index.html`, `dir`/`archive` source resolver (see «Plugins»)
+- Built-in plugins: `openspec` (local OpenSpec store → site section, local diagram render) and
+  `openapi` (offline swagger-ui pages for a set of OpenAPI specs; `vendor/swagger-ui/swagger-ui.css` 5.32.1)
 - `c4builder check <file...>` — validate individual `.puml` / `.iuml` / `.d2` files with the
   bundled engines, without a project build (#13)
 - D2 compile errors are printed as readable `file:line:col: message` lines instead of raw JSON
 - Regression test for two adjacent `![..](x.puml)` embeds (#12 — the bug itself was fixed in 0.3.0)
+- Diagram cache key now includes the output path: diagrams that swap contents (or fence blocks
+  that shift position) are re-rendered instead of silently reusing a neighbour's cached image.
+  The first build after upgrading re-renders everything once.
+- Watch mode ignores the output folder, its backup and `.c4builder*`, and de-duplicates nested
+  watch roots (a plugin `dir` covering the project no longer loops the rebuild)
 
 ## v0.3.0
 

package/dist/cli/commands/help.js

@@ -36,6 +36,10 @@ ${chalk.cyan('Replace diagrams with a link')}
 Replaces the diagram images with links.
 ${chalk.cyan('Include breadcrumbs')}
 Shows the original folder hierarchy after each title.
+${chalk.cyan('Plugins')} (${chalk.gray('.c4builder → "plugins", no wizard prompt')})
+List of build plugins: "name" or ["name", { options }]. Built-in: openspec (local OpenSpec store →
+site section), openapi (swagger-ui pages for OpenAPI specs from a folder or an HTTP archive).
+See README «Plugins».
 ${chalk.cyan('Place diagrams before text')}
 Choose to place diagrams before or after the text.
 ${chalk.cyan('Exclude other files')}

package/dist/cli/commands/list.js

@@ -73,6 +73,9 @@ Charset: ${currentConfiguration.CHARSET !== undefined
 Exclude other files: ${currentConfiguration.EXCLUDE_OTHER_FILES !== undefined
         ? chalk.green(currentConfiguration.EXCLUDE_OTHER_FILES)
         : chalk.red('not set')}
+Plugins: ${currentConfiguration.PLUGINS?.length
+        ? chalk.green(currentConfiguration.PLUGINS.map((p) => (typeof p === 'string' ? p : p[0])).join(', '))
+        : chalk.gray('none')}
 `);
     // Битые ключи показаны выше как «not set» (щадящий разбор их выбросил); помечаем их
     // сырым значением и причиной, чтобы было видно, что и почему требует правки/визарда.

package/dist/cli/dispatch.js

@@ -11,6 +11,8 @@ import cmdList from "./commands/list.js";
 import cmdSite from "./commands/site.js";
 import cmdCollect from "./wizard/collect.js";
 import { build } from "../core/build.js";
+import { loadPlugins, pluginWatchPaths } from "../core/plugins/load.js";
+import fs from 'node:fs';
 import watch from 'node-watch';
 import { EventEmitter } from 'node:events';
 import { clearConsole } from "../util/utils.js";
@@ -20,7 +22,7 @@ import { acquireBuildLock, BuildLockHeldError } from "../util/lock.js";
 // больше не будет (одиночный запуск).
 import { teardownD2 } from "../core/render/d2renderer.js";
 import { packageJson as pkg } from "../util/paths.js";
-import { parseConfig } from "../config/options.js";
+import { outputDirs, parseConfig } from "../config/options.js";
 import { isValidPort } from "../config/schema.js";
 const intro = () => {
     console.log(chalk.blue(figlet.textSync('c4builder')));
@@ -94,7 +96,8 @@ function getOptions(c) {
         SUPPORT_SEARCH: c.supportSearch,
         EXECUTE_SCRIPT: c.executeScript,
         EXCLUDE_OTHER_FILES: c.excludeOtherFiles,
-        USE_SYSTEM_FONTS: c.useSystemFonts
+        USE_SYSTEM_FONTS: c.useSystemFonts,
+        PLUGINS: c.plugins
     };
 }
 export default async () => {
@@ -132,9 +135,9 @@ export default async () => {
     let cacheConf = { get: () => { }, set: () => { }, clear: () => { } };
     // Лок сборки — рядом с конфигом проекта (см. util/lock.ts). Заполняется вместе с conf.
     let lockPath = '';
+    const configPath = path.join(process.cwd(), opts.configFile ?? '.c4builder');
     if (!opts.new) {
         const projectKey = process.cwd().split(path.sep).splice(1).join('_');
-        const configPath = path.join(process.cwd(), opts.configFile ?? '.c4builder');
         lockPath = `${configPath}.lock`;
         conf = new Configstore(projectKey, {}, { configPath });
         cacheConf = new Configstore(`${projectKey}_cache`, {}, { configPath: `${configPath}.cache` });
@@ -178,9 +181,11 @@ export default async () => {
     // Повторная сборка установленного проекта (есть HAS_RUN, не --config) — строгий путь:
     // битый конфиг обязан упасть с внятной ошибкой сразу, а не быть тихо «починен» визардом.
     // Первый запуск (!HAS_RUN) и --config остаются щадящими — это штатный путь восстановления.
+    // `plugins` визард не спрашивает — salvage молча переписал бы его в `[]` и сборка
+    // прошла бы без раздела плагина; битый `plugins` роняет всегда.
     const strictBuild = !opts.config && !!currentConfig.HAS_RUN;
     if (configIssues.length) {
-        if (strictBuild)
+        if (strictBuild || configIssues.some((i) => i.key === 'plugins'))
             failOnConfigIssues(configIssues);
         warnConfigIssues(configIssues);
         // Битые ключи чиним физически (salvage-значение = дефолт схемы, либо удаление):
@@ -210,13 +215,30 @@ export default async () => {
         const options = getOptions(built.value);
         if (opts.systemFonts)
             options.USE_SYSTEM_FONTS = true; // флаг сильнее ключа конфига
+        // Плагины грузятся и валидируются до первой сборки: битые опции — exit 1 сразу.
+        const plugins = await loadPlugins(options.PLUGINS, process.cwd(), options).catch((e) => {
+            console.error(chalk.red(`Ошибка загрузки плагинов: ${e.message}`));
+            return process.exit(1);
+        });
         const reloadEmitter = new EventEmitter();
         reloadEmitter.setMaxListeners(0);
         if (opts.watch) {
             // node-watch: CJS-рантайм при ESM-.d.ts (export default) — дефолт-импорт
             // типизируется как namespace. Каст к реальной сигнатуре, рантайм не меняется.
             const watchDir = watch;
-            watchDir(options.ROOT_FOLDER, { recursive: true }, async (_evt, name) => {
+            const inside = (p, dir) => p === dir || p.startsWith(dir + path.sep);
+            // Пути наблюдения — абсолютные и без вложенных друг в друга: node-watch дедуплицирует
+            // события по имени, а один файл под двумя корнями приходил бы дважды.
+            const candidates = [
+                path.resolve(options.ROOT_FOLDER),
+                ...pluginWatchPaths(plugins, process.cwd(), fs.existsSync)
+            ];
+            const watchPaths = candidates.filter((p, i) => !candidates.some((q, j) => j !== i && inside(p, q) && (p !== q || j < i)));
+            // Собственные записи сборки (dist, dist_bk, .c4builder*) не должны триггерить
+            // ребилд — при dir плагина, накрывающем cwd, это бесконечная петля.
+            const output = outputDirs(options);
+            const filter = (name, skip) => output.some((d) => inside(name, d)) || name.startsWith(configPath) ? skip : true;
+            watchDir(watchPaths, { recursive: true, filter }, async (_evt, name) => {
                 // clearConsole();
                 // intro();
                 console.log(chalk.gray(`\n${name} changed. Rebuilding...`));
@@ -233,10 +255,10 @@ export default async () => {
                     // каталоге не потопчет dist_bk и не потеряет чексуммы кеша.
                     const release = acquireBuildLock(lockPath);
                     try {
-                        await build(options, cacheConf);
+                        await build(options, cacheConf, plugins);
                         while (attemptedWatchBuild) {
                             attemptedWatchBuild = false;
-                            await build(options, cacheConf);
+                            await build(options, cacheConf, plugins);
                         }
                     }
                     finally {
@@ -273,7 +295,7 @@ export default async () => {
             process.exit(1);
         }
         try {
-            await build(options, cacheConf);
+            await build(options, cacheConf, plugins);
         }
         finally {
             release();

package/dist/config/options.js

@@ -4,7 +4,13 @@
 // Форма файла `.c4builder` (camelCase) — единый тип задаёт zod-схема (config/schema),
 // её же валидацией опирается загрузка опций сборки. Ре-экспорт: потребители типа
 // (defaults, dispatch) продолжают импортировать его отсюда.
+import path from 'node:path';
 import { configSchema } from "./schema.js";
+/** Один невалидный ключ `.c4builder`: имя ключа верхнего уровня, его сырое значение и причина. */
+/** Суффикс бэкапа выходного каталога на время сборки (`docs` → `docs_bk`). */
+export const DIST_BACKUP_FOLDER_SUFFIX = '_bk';
+/** Выходные каталоги сборки (абсолютные): dist и его бэкап — их нельзя ни сканировать, ни наблюдать. */
+export const outputDirs = (options) => [options.DIST_FOLDER, options.DIST_FOLDER + DIST_BACKUP_FOLDER_SUFFIX].map((d) => path.resolve(d));
 /**
  * Разбирает сырой объект `.c4builder`, разделяя строгий и щадящий пути. Сам НЕ печатает
  * и НЕ завершает процесс — решение (ошибка+выход либо предупреждение) принимает CLI.

package/dist/config/schema.js

@@ -61,6 +61,14 @@ export const configSchema = z.object({
     // путей не валит сборку) — runtime дальше работает с чистым string[].
     excludeSidebarFolderByPath: nullish(z.preprocess((v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : v), z.array(z.string()).optional())),
     hasRun: optBool(),
+    // Плагины сборки: `"имя"` либо `["имя", {опции}]`. Опции здесь не валидируются —
+    // это делает схема самого плагина при загрузке (core/plugins/load); верхний уровень
+    // проверяет лишь форму записи, чтобы ошибка называла `plugins` и позицию.
+    plugins: nullish(z
+        .array(z.union([z.string(), z.tuple([z.string(), z.record(z.string(), z.unknown())])], {
+        error: 'ожидается "имя" либо ["имя", {опции}]'
+    }))
+        .default([])),
     // Легаси-ключи старых `.c4builder` — читаются лишь для однократного предупреждения.
     plantumlVersion: optStr(),
     generatePDF: optBool(),

package/dist/core/build.js

@@ -5,14 +5,18 @@ import { makeDirectory, writeOnSameLine } from "../util/utils.js";
 // clearD2FileCache: сброс кеша графа D2-импортов на границах сборки (сам webworker
 // D2 гасит CLI после одиночной сборки — в watch-режиме он переживает ребилды).
 import { clearD2FileCache } from "./render/d2renderer.js";
+import { DIST_BACKUP_FOLDER_SUFFIX } from "../config/options.js";
 // Фазы сборки: scan (дерево исходников) → render (диаграммы) → compose (markdown/сайт).
 import { generateTree, engineSupportsRemote, clearIncludeCache } from "./scan/tree.js";
 import { generateImages } from "./render/diagrams.js";
 import { generateMD, generateWebMD, generateCompleteMD, clearDiagramCache } from "./compose/markdown.js";
+// Плагины: хуки afterScan (виртуальные страницы) / afterBuild и ассеты сайта.
+// Загружены заранее в cli/dispatch и приходят третьим аргументом (как cacheConf).
+import { runAfterScan, runAfterBuild } from "./plugins/hooks.js";
+import { injectPluginAssets } from "./plugins/assets.js";
 // Оркестратор владеет lifecycle выходного каталога: dist бэкапится в dist_bk, откуда
 // generateImages восстанавливает неизменённые по чексумме картинки; в конце бэкап сносится.
-const DIST_BACKUP_FOLDER_SUFFIX = '_bk';
-const build = async (options, cacheConf) => {
+const build = async (options, cacheConf, plugins = []) => {
     const start_date = new Date();
     const bkFolderName = options.DIST_FOLDER + DIST_BACKUP_FOLDER_SUFFIX;
     // Generating local images, remove old backup image folder, rename current dist folder to new backup
@@ -38,6 +42,9 @@ const build = async (options, cacheConf) => {
         console.log(chalk.green(`\nbuilding documentation in ./${options.DIST_FOLDER}`));
         const tree = await generateTree(options.ROOT_FOLDER, options);
         console.log(chalk.blue(`parsed ${tree.length} folders`));
+        // Виртуальные страницы плагинов встают в дерево до рендера — дальше они
+        // неотличимы от реальных папок (диаграммы, sidebar, поиск, complete).
+        await runAfterScan(tree, options, plugins);
         // У движков без онлайн-рендера (D2, см. remoteRender в DIAGRAM_ENGINES) при
         // выключенной локальной генерации диаграммы не во что превратить — ссылки на
         // SVG вели бы в никуда. Падаем сразу с понятной ошибкой, а не молча битым выводом.
@@ -66,6 +73,7 @@ const build = async (options, cacheConf) => {
         if (options.GENERATE_WEBSITE) {
             console.log(chalk.blue('generating docsify site'));
             await generateWebMD(tree, options);
+            await injectPluginAssets(plugins, options);
         }
         if (options.GENERATE_COMPLETE_MD_FILE) {
             console.log(chalk.blue('generating complete markdown file'));
@@ -78,6 +86,7 @@ const build = async (options, cacheConf) => {
             console.log(chalk.bold(chalk.yellow('WARNING:')));
             console.log(chalk.yellow(`PDF-вывод больше не поддерживается. Удалите вручную из .c4builder: ${options.LEGACY_PDF_KEYS.join(', ')}.`));
         }
+        await runAfterBuild(options, plugins);
         console.log(chalk.green(`built in ${(Date.now() - start_date.getTime()) / 1000} seconds`));
         ok = true;
     }

package/dist/core/plugins/assets.js

@@ -0,0 +1,53 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { encodeURIPath } from "../../util/utils.js";
+// Вставка тегов в готовый HTML: стили — перед последним `</head>`, скрипты — перед
+// последним `</body>` (регистронезависимо); тега нет — в конец файла (браузер исполнит
+// и так). Пост-обработка не зависит от того, чей это шаблон (docsifyTemplate пользователя
+// править не требуется). Экспортируется для юнит-теста.
+export const injectHtml = (html, { styles, scripts }) => {
+    const before = (doc, closing, block) => {
+        if (!block)
+            return doc;
+        const m = [...doc.matchAll(closing)].pop();
+        return m?.index === undefined
+            ? `${doc}\n${block}`
+            : `${doc.slice(0, m.index)}${block}\n${doc.slice(m.index)}`;
+    };
+    const styleTags = styles.map((s) => `<link rel="stylesheet" href="${s}">`).join('\n');
+    const scriptTags = scripts.map((s) => `<script src="${s}"></script>`).join('\n');
+    return before(before(html, /<\/head>/gi, styleTags), /<\/body>/gi, scriptTags);
+};
+/**
+ * Копирует ассеты плагинов в `dist/vendor/plugins/<name>/` и подключает их в
+ * `dist/index.html`. Зовётся после generateWebMD (index.html уже записан).
+ */
+export const injectPluginAssets = async (plugins, options) => {
+    const indexPath = path.join(options.DIST_FOLDER, 'index.html');
+    const html = fs.readFileSync(indexPath, 'utf8');
+    // Файл с тем же именем уже подключён шаблоном (дефолтный шаблон сам грузит
+    // vendor/swagger-ui-bundle.js) — второй раз не копируем и не подключаем.
+    const linked = (file) => new RegExp(`(?:src|href)=["'][^"']*\\b${path.basename(file).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}["']`).test(html);
+    const styles = [];
+    const scripts = [];
+    for (const { plugin } of plugins) {
+        if (!plugin.assets)
+            continue;
+        const rel = path.posix.join('vendor', 'plugins', plugin.name);
+        const destDir = path.join(options.DIST_FOLDER, 'vendor', 'plugins', plugin.name);
+        const copy = (files, out) => {
+            for (const file of files ?? []) {
+                if (linked(file))
+                    continue;
+                fs.mkdirSync(destDir, { recursive: true });
+                fs.copyFileSync(file, path.join(destDir, path.basename(file)));
+                out.push(encodeURIPath(path.posix.join(rel, path.basename(file))));
+            }
+        };
+        copy(plugin.assets.styles, styles);
+        copy(plugin.assets.scripts, scripts);
+    }
+    if (!styles.length && !scripts.length)
+        return;
+    fs.writeFileSync(indexPath, injectHtml(html, { styles, scripts }));
+};

package/dist/core/plugins/hooks.js

@@ -0,0 +1,30 @@
+import { resolveSource } from "./source.js";
+import { addPage } from "./tree.js";
+const wrap = async (name, hook, fn) => {
+    try {
+        await fn();
+    }
+    catch (e) {
+        throw new Error(`Плагин ${name} (${hook}): ${e.message ?? e}`, { cause: e });
+    }
+};
+export const runAfterScan = async (tree, options, plugins) => {
+    for (const { plugin, opts } of plugins) {
+        if (!plugin.afterScan)
+            continue;
+        const ctx = {
+            tree,
+            options,
+            addPage: (page) => addPage(tree, options, page),
+            source: resolveSource
+        };
+        await wrap(plugin.name, 'afterScan', () => plugin.afterScan?.(ctx, opts));
+    }
+};
+export const runAfterBuild = async (options, plugins) => {
+    for (const { plugin, opts } of plugins) {
+        if (!plugin.afterBuild)
+            continue;
+        await wrap(plugin.name, 'afterBuild', () => plugin.afterBuild?.({ distFolder: options.DIST_FOLDER, options }, opts));
+    }
+};

package/dist/core/plugins/load.js

@@ -0,0 +1,125 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import chalk from 'chalk';
+import { BUILTIN_PLUGINS } from "../../plugins/index.js";
+// Подстановка `${NAME}` из окружения во всех строках опций (рекурсивно). Незаданная
+// переменная → пустая строка: так `headers: { 'PRIVATE-TOKEN': '${GITLAB_TOKEN}' }`
+// без токена даёт пустой заголовок, который резолвер источников отбрасывает.
+export const expandEnv = (value) => {
+    if (typeof value === 'string')
+        return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) => process.env[name] ?? '');
+    if (Array.isArray(value))
+        return value.map(expandEnv);
+    if (value && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, expandEnv(v)]));
+    return value;
+};
+const isPathId = (id) => id.startsWith('./') || id.startsWith('../') || path.isAbsolute(id);
+// Главный ESM-вход пакета по его package.json: `exports` (вложенные условия
+// import/default, subpath ".", массивы-фолбэки), иначе `module`/`main`. Покрывает
+// типовые формы; экзотические условия — за пределами (`ponytail`).
+const resolveEsmMain = (id, searchPaths) => {
+    const dir = searchPaths
+        .map((p) => path.join(p, id))
+        .find((d) => fs.existsSync(path.join(d, 'package.json')));
+    if (!dir)
+        return undefined;
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    const pick = (e) => {
+        if (typeof e === 'string')
+            return e;
+        if (Array.isArray(e))
+            return e.map(pick).find(Boolean);
+        if (!e || typeof e !== 'object')
+            return undefined;
+        const o = e;
+        return '.' in o ? pick(o['.']) : pick(o.import ?? o.default ?? o.node);
+    };
+    const main = pick(pkg.exports) ?? pkg.module ?? pkg.main;
+    return main ? path.join(dir, main) : undefined;
+};
+// Идентификатор → модуль плагина: встроенный по имени → путь от cwd → npm-пакет,
+// резолвится от cwd проекта (а не от установки c4builder — глобальный бинарь иначе
+// не видел бы локальные node_modules).
+const importPlugin = async (id, cwd) => {
+    if (Object.hasOwn(BUILTIN_PLUGINS, id))
+        return BUILTIN_PLUGINS[id]();
+    let mod;
+    if (isPathId(id)) {
+        mod = await import(__rewriteRelativeImportExtension(pathToFileURL(path.resolve(cwd, id)).href));
+    }
+    else {
+        const require = createRequire(path.join(cwd, 'package.json'));
+        let resolved;
+        try {
+            resolved = require.resolve(id);
+        }
+        catch (e) {
+            // ESM-only пакет (`exports` лишь с условием import) CJS-резолвер не берёт —
+            // находим пакет в цепочке node_modules от cwd и читаем его exports сами.
+            if (e.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED')
+                resolved = resolveEsmMain(id, require.resolve.paths(id) ?? []);
+            if (!resolved)
+                throw new Error(`не найден ни среди встроенных (${Object.keys(BUILTIN_PLUGINS).join(', ')}), ` +
+                    `ни как npm-пакет от ${cwd}: ${e.message}`);
+        }
+        mod = await import(__rewriteRelativeImportExtension(pathToFileURL(resolved).href));
+    }
+    const plugin = mod.default ?? mod;
+    if (!plugin || typeof plugin !== 'object' || typeof plugin.name !== 'string')
+        throw new Error('модуль должен экспортировать по умолчанию объект плагина с полем name');
+    return plugin;
+};
+/**
+ * Загружает плагины из `plugins` конфига: резолв, импорт, подстановка окружения и
+ * валидация опций схемой плагина. Fail-fast — любая ошибка прерывает до старта сборки
+ * с указанием позиции записи и имени плагина. `requires.executeScript` включает
+ * `EXECUTE_SCRIPT` в опциях сборки (с одной строкой в лог, если ключ был выключен).
+ */
+export const loadPlugins = async (entries, cwd, options) => {
+    const loaded = [];
+    for (const [i, entry] of entries.entries()) {
+        const [id, rawOpts] = typeof entry === 'string' ? [entry, {}] : entry;
+        let plugin;
+        try {
+            plugin = await importPlugin(id, cwd);
+        }
+        catch (e) {
+            throw new Error(`plugins[${i}] "${id}": ${e.message}`);
+        }
+        let opts = expandEnv(rawOpts);
+        if (plugin.options) {
+            const parsed = plugin.options.safeParse(opts);
+            if (!parsed.success) {
+                const issues = parsed.error.issues.map((iss) => `${iss.path.length ? iss.path.join('.') : '(опции)'} — ${iss.message}`);
+                throw new Error(`plugins[${i}] ${plugin.name}: ${issues.join('; ')}`);
+            }
+            opts = parsed.data;
+        }
+        if (plugin.requires?.executeScript && !options.EXECUTE_SCRIPT) {
+            options.EXECUTE_SCRIPT = true;
+            console.log(chalk.gray(`плагин ${plugin.name} требует executeScript — включён для этой сборки`));
+        }
+        loaded.push({ plugin, opts });
+    }
+    return loaded;
+};
+/** Существующие пути наблюдения всех плагинов (абсолютные); несуществующие — предупреждение. */
+export const pluginWatchPaths = (plugins, cwd, exists) => plugins.flatMap(({ plugin, opts }) => (plugin.watchPaths?.(opts) ?? [])
+    .map((p) => path.resolve(cwd, p))
+    .filter((p) => {
+    if (exists(p))
+        return true;
+    console.log(chalk.yellow(`плагин ${plugin.name}: путь наблюдения не существует — ${p}`));
+    return false;
+}));

package/dist/core/plugins/source.js

@@ -0,0 +1,86 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { httpGetBuffer } from "../../util/http.js";
+import { extractTarGz, extractZip } from "../../util/archive.js";
+// Кэш скачанных архивов на процесс: в watch-режиме повторные сборки не качают заново.
+// Ключ — URL; каталог на диске — по sha1(URL) в tmp, чистить не нужно.
+const archiveCache = new Map();
+// Формат по магическим байтам, а не по расширению: URL archive-API часто без него
+// (`…/archive?format=zip`). zip — `PK\x03\x04`, gzip — `\x1f\x8b`.
+const isZipBuffer = (b) => b.length > 3 && b[0] === 0x50 && b[1] === 0x4b && b[2] === 3 && b[3] === 4;
+const isGzipBuffer = (b) => b.length > 1 && b[0] === 0x1f && b[1] === 0x8b;
+// URL для сообщений: без query и userinfo — токен, переданный в URL
+// (`?private_token=${TOKEN}`), не должен попадать в логи сборки/CI.
+export const redactUrl = (url) => {
+    try {
+        const u = new URL(url);
+        return `${u.origin}${u.pathname}`;
+    }
+    catch {
+        return url;
+    }
+};
+const downloadArchive = async (url, headers) => {
+    const dir = path.join(os.tmpdir(), `c4builder-src-${crypto.createHash('sha1').update(url).digest('hex')}`);
+    // Распаковываем в свой staging и заменяем кэш атомарным rename — параллельная
+    // сборка того же URL не увидит полураспакованный каталог.
+    const stage = `${dir}.tmp-${process.pid}`;
+    const archive = `${stage}.archive`;
+    let body;
+    try {
+        body = await httpGetBuffer(url, { headers });
+    }
+    catch (e) {
+        throw new Error(`архив недоступен: ${e.message.replaceAll(url, redactUrl(url))}`);
+    }
+    fs.rmSync(stage, { recursive: true, force: true });
+    fs.mkdirSync(stage, { recursive: true });
+    fs.writeFileSync(archive, body);
+    try {
+        if (isZipBuffer(body))
+            await extractZip(archive, stage);
+        else if (isGzipBuffer(body))
+            await extractTarGz(archive, stage);
+        else
+            throw new Error(`неизвестный формат архива ${redactUrl(url)} (ожидается zip или tar.gz)`);
+        fs.rmSync(dir, { recursive: true, force: true });
+        fs.renameSync(stage, dir);
+    }
+    finally {
+        fs.rmSync(archive, { force: true });
+        fs.rmSync(stage, { recursive: true, force: true }); // no-op после rename
+    }
+    // GitLab/GitHub archive кладут всё в `<repo>-<sha>/` — единственный корневой каталог снимаем.
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    return entries.length === 1 && entries[0].isDirectory() ? path.join(dir, entries[0].name) : dir;
+};
+/**
+ * Резолв источника плагина в локальный каталог: `dir` (+ `subdir`) — проверка
+ * существования; `archive` — скачивание (с непустыми `headers`), распаковка в tmp-кэш,
+ * снятие единственного корневого каталога, затем `subdir`. Ошибки называют путь/URL.
+ */
+export const resolveSource = async (spec, cwd = process.cwd()) => {
+    if (spec.dir !== undefined) {
+        const abs = path.resolve(cwd, spec.dir, spec.subdir ?? '');
+        if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory())
+            throw new Error(`источник dir не найден: ${abs}`);
+        return abs;
+    }
+    if (spec.archive === undefined)
+        throw new Error('источник должен задавать dir либо archive');
+    const url = spec.archive;
+    const headers = Object.fromEntries(Object.entries(spec.headers ?? {}).filter(([, v]) => v !== ''));
+    let rootPromise = archiveCache.get(url);
+    if (!rootPromise) {
+        rootPromise = downloadArchive(url, headers);
+        archiveCache.set(url, rootPromise);
+        rootPromise.catch(() => archiveCache.delete(url)); // неудачу не кэшируем — следующая сборка повторит
+    }
+    const root = await rootPromise;
+    const result = spec.subdir ? path.join(root, spec.subdir) : root;
+    if (!fs.existsSync(result) || !fs.statSync(result).isDirectory())
+        throw new Error(`в архиве ${redactUrl(url)} нет каталога ${spec.subdir ?? '.'} (распаковано в ${root})`);
+    return result;
+};