@alfacapital-tech/c4builder 0.5.0 → 0.6.0

package/dist/cli/commands/site.js

@@ -3,6 +3,8 @@ import path from 'node:path';
 import fs from 'node:fs';
 import express from 'express';
 import open from 'open';
+import { packageJson as pkg } from "../../util/paths.js";
+import { pendingUpdate } from "../update.js";
 const LIVERELOAD_PATH = '/__livereload';
 // Восстановление скролла после reload: docsify рендерит контент асинхронно после fetch md,
 // высота страницы доступна не сразу — поллим до достижения нужной y или таймаута.
@@ -52,6 +54,28 @@ const LIVERELOAD_SNIPPET = `
     connect();
 })();
 </script>`;
+// Плашка о новой версии — только в отдаче dev-сервера, в dist не попадает. Флаг закрытия — в
+// sessionStorage: переживает reload ребилдом и живёт до закрытия вкладки.
+const updateBanner = (next) => `
+<div id="c4builder-update" style="position:fixed;right:16px;bottom:16px;z-index:1000;max-width:360px;padding:10px 36px 10px 14px;border:1px solid #e0c060;border-radius:6px;background:#fff8dc;color:#333;font:14px/1.4 sans-serif;box-shadow:0 2px 8px rgba(0,0,0,.15)">
+c4builder ${next} is available (current ${pkg.version}). Run: <code>c4builder update</code>
+<button type="button" aria-label="Close" style="position:absolute;top:4px;right:8px;border:0;background:none;color:inherit;font-size:18px;line-height:1;cursor:pointer">&times;</button>
+</div>
+<script>
+(function () {
+    var KEY = '__c4builderUpdateClosed';
+    var el = document.getElementById('c4builder-update');
+    try {
+        if (sessionStorage.getItem(KEY)) return el.remove();
+    } catch (e) {}
+    el.querySelector('button').onclick = function () {
+        el.remove();
+        try {
+            sessionStorage.setItem(KEY, '1');
+        } catch (e) {}
+    };
+})();
+</script>`;
 export default (currentConfiguration, program, reloadEmitter) => {
     if (!currentConfiguration.DIST_FOLDER)
         return console.log(chalk.red('No destination folder configured'));
@@ -84,10 +108,14 @@ export default (currentConfiguration, program, reloadEmitter) => {
                 console.log(chalk.gray(`livereload: client disconnected (${reloadEmitter.listenerCount('reload')} left)`));
             });
         });
+        // Кэш проверки обновлений читается на каждую страницу: результат фоновой проверки,
+        // запущенной этим же `site -w`, виден со следующей перезагрузки без рестарта сервера.
         const inject = (html) => {
+            const next = pendingUpdate();
+            const snippet = next ? LIVERELOAD_SNIPPET + updateBanner(next) : LIVERELOAD_SNIPPET;
             if (html.includes('</body>'))
-                return html.replace('</body>', `${LIVERELOAD_SNIPPET}</body>`);
-            return html + LIVERELOAD_SNIPPET;
+                return html.replace('</body>', `${snippet}</body>`);
+            return html + snippet;
         };
         app.use((req, res, next) => {
             if (req.method !== 'GET')
@@ -122,9 +150,10 @@ export default (currentConfiguration, program, reloadEmitter) => {
                     }
                     return next();
                 }
+                const page = inject(data);
                 if (isIndex)
-                    lastIndexHtml = inject(data);
-                res.set('Cache-Control', 'no-store').type('html').send(inject(data));
+                    lastIndexHtml = page;
+                res.set('Cache-Control', 'no-store').type('html').send(page);
             });
         });
     }

package/dist/cli/dispatch.js

@@ -9,6 +9,7 @@ import cmdJre from "./commands/jre.js";
 import cmdCheck from "./commands/check.js";
 import cmdList from "./commands/list.js";
 import cmdSite from "./commands/site.js";
+import { cmdUpdate, pendingUpdate, startUpdateCheck } from "./update.js";
 import cmdCollect from "./wizard/collect.js";
 import { build } from "../core/build.js";
 import { loadPlugins, pluginWatchPaths } from "../core/plugins/load.js";
@@ -26,7 +27,7 @@ import { packageJson as pkg } from "../util/paths.js";
 import { outputDirs, parseConfig } from "../config/options.js";
 import { isValidPort } from "../config/schema.js";
 // Позиционные подкоманды: allowExcessArguments пропускает любые, список — единственный фильтр.
-const COMMANDS = ['check', 'jre', 'site', 'new', 'config'];
+const COMMANDS = ['check', 'jre', 'site', 'new', 'config', 'update'];
 const intro = () => {
     console.log(chalk.blue(figlet.textSync('c4builder')));
     console.log(chalk.gray('Blow up your software documentation writing skills'));
@@ -137,12 +138,23 @@ export default async () => {
         console.error(`available commands: ${COMMANDS.join(', ')} (see c4builder --help for options)`);
         process.exit(1);
     }
+    // --version/--help уже вышли в parse. Уведомление — по кэшу прошлой проверки, до её
+    // перезапуска; exit покрывает и выходы через process.exit.
+    if (cmd !== 'update') {
+        const next = pendingUpdate();
+        if (next)
+            process.once('exit', () => process.stderr.write(`c4builder ${next} is available (current ${pkg.version}). Run: c4builder update\n`));
+        startUpdateCheck();
+    }
     // Прогрев JRE — до загрузки конфига проекта и intro: команда самостоятельна.
     if (cmd === 'jre')
         return cmdJre(cmdArgs, { force: opts.force });
     // Проверка отдельных диаграмм — тоже без конфига проекта.
     if (cmd === 'check')
         return cmdCheck(cmdArgs);
+    // Обновление CLI — до Configstore, чтобы не создавать .c4builder в любом каталоге.
+    if (cmd === 'update')
+        return cmdUpdate();
     // `site`/`new`/`config` — позиционные синонимы одноимённых флагов: эту форму печатают
     // подсказки CLI и учат README, шаблон и скиллы.
     if (cmd)

package/dist/cli/update.js

@@ -0,0 +1,133 @@
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import chalk from 'chalk';
+import { isPathInside } from "../util/archive.js";
+import { PACKAGE_ROOT, packageJson as pkg } from "../util/paths.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+const SEMVER = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
+// Без лимитов npm в сети, молча теряющей пакеты, висит минутами (повторы с паузами до 60 с).
+const VIEW = ['view', pkg.name, 'dist-tags', '--json', '--fetch-retries=0', '--fetch-timeout=5000'];
+// npm на Windows — npm.cmd, а .cmd Node ≥ 20.12 запускает только через shell. Команду склеиваем
+// сами: shell с массивом аргументов Node помечает DEP0190. Аргументы фиксированные или прошли SEMVER.
+const WIN = process.platform === 'win32';
+const npmCommand = (args) => WIN ? [['npm', ...args].join(' '), []] : ['npm', args];
+const npmSync = (args, options) => {
+    const [cmd, argv] = npmCommand(args);
+    return spawnSync(cmd, argv, { ...options, encoding: 'utf8', shell: WIN, windowsHide: true });
+};
+// CI ставят GitLab CI, GitHub Actions и большинство CI; C4BUILDER_DOCKER — наш Dockerfile;
+// NO_UPDATE_NOTIFIER — общая конвенция с пакетом update-notifier.
+const disabled = () => !!(process.env.CI || process.env.NO_UPDATE_NOTIFIER || process.env.C4BUILDER_DOCKER);
+const cacheFile = () => path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'c4builder', 'dist-tags.json');
+// Порядок semver без зависимости semver: numeric-коллатор сравнивает цифровые серии численно
+// (0.10.0 > 0.9.0, rc.10 > rc.2); стабильная версия старше пререлиза того же ядра.
+const collator = new Intl.Collator('en', { numeric: true });
+export const compareVersions = (a, b) => {
+    const [coreA = '', preA = ''] = a.split(/-(.*)/);
+    const [coreB = '', preB = ''] = b.split(/-(.*)/);
+    return collator.compare(coreA, coreB) || Number(!preA) - Number(!preB) || collator.compare(preA, preB);
+};
+// Версия для обновления по dist-tags от npm, или undefined: нет данных (пустой, битый, недописанный
+// кэш, JSON-ошибка npm) либо ничего новее текущей. Пререлиз смотрит и на rc, который может отстать
+// от latest. npm 12 отдаёт dist-tags массивом из одного объекта, npm ≤ 11 — самим объектом.
+export const newestVersion = (current, distTags) => {
+    let tags;
+    try {
+        tags = [JSON.parse(distTags)].flat()[0];
+    }
+    catch {
+        return undefined;
+    }
+    let newest = current;
+    for (const tag of current.includes('-') ? ['latest', 'rc'] : ['latest']) {
+        const v = tags?.[tag];
+        if (typeof v === 'string' && SEMVER.test(v) && compareVersions(v, newest) > 0)
+            newest = v;
+    }
+    return newest === current ? undefined : newest;
+};
+// Обновление, известное по прошлой проверке; читать до startUpdateCheck — она обнуляет кэш.
+export const pendingUpdate = () => {
+    if (disabled())
+        return undefined;
+    try {
+        return newestVersion(pkg.version, fs.readFileSync(cacheFile(), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+};
+// Не чаще раза в сутки — отсоединённый `npm view` со stdout прямо в файл кэша: CLI его не ждёт,
+// а реестр, прокси и сертификаты npm берёт из npmrc — тот же путь, что у установки обновления.
+// mtime кэша — время последней попытки, удачной или нет.
+export const startUpdateCheck = () => {
+    if (disabled())
+        return;
+    try {
+        const file = cacheFile();
+        if (Date.now() - (fs.statSync(file, { throwIfNoEntry: false })?.mtimeMs ?? 0) < DAY_MS)
+            return;
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const fd = fs.openSync(file, 'w');
+        try {
+            // open('w') уже пустого файла (прошлая попытка без сети) обновляет mtime не на всех ФС.
+            fs.futimesSync(fd, new Date(), new Date());
+            // fd/ignore, а не pipe: pipe ребёнка держал бы event loop CLI до выхода npm.
+            const [cmd, argv] = npmCommand(VIEW);
+            spawn(cmd, argv, {
+                detached: true,
+                stdio: ['ignore', fd, 'ignore'],
+                shell: WIN,
+                windowsHide: true
+            })
+                .on('error', () => { }) // нет npm в PATH: без обработчика ENOENT роняет CLI
+                .unref();
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        // Проверка необязательна: недоступный на запись каталог конфигурации не должен мешать CLI.
+    }
+};
+// realpath: npm link и симлинки prefix'а (nvm, Homebrew) — сравниваем реальные пути.
+const installedGlobally = (globalRoot) => {
+    try {
+        return isPathInside(fs.realpathSync(globalRoot), fs.realpathSync(PACKAGE_ROOT));
+    }
+    catch {
+        return false;
+    }
+};
+// `c4builder update`: ставит новейшую версию при глобальной npm-установке, иначе подсказывает,
+// как обновиться. Ставим точную версию, а не @latest: для пререлиза новейшей бывает и latest.
+export const cmdUpdate = () => {
+    if (process.env.C4BUILDER_DOCKER) {
+        console.log('c4builder runs in the Docker image, pull the new image instead:');
+        console.log('  docker pull ghcr.io/alfacapital-tech/c4builder:latest');
+        process.exit(1);
+    }
+    const view = npmSync(VIEW, { stdio: ['ignore', 'pipe', 'inherit'], timeout: 60_000 });
+    if (view.status !== 0) {
+        const reason = view.error?.message ?? `npm exited with code ${view.status}`;
+        console.error(chalk.red(`could not query the npm registry: ${reason}`));
+        process.exit(1);
+    }
+    const next = newestVersion(pkg.version, view.stdout);
+    if (!next) {
+        console.log(chalk.green(`c4builder ${pkg.version} is up to date`));
+        return;
+    }
+    const root = npmSync(['root', '-g'], { stdio: ['ignore', 'pipe', 'ignore'], timeout: 60_000 });
+    if (root.status === 0 && installedGlobally(root.stdout.trim())) {
+        console.log(`updating c4builder ${pkg.version} -> ${next}`);
+        process.exit(npmSync(['install', '-g', `${pkg.name}@${next}`], { stdio: 'inherit' }).status ?? 1);
+    }
+    console.log(`c4builder ${next} is available (current ${pkg.version}), but this copy is not a global npm install.`);
+    console.log(`update the project dependency:  npm i -D ${pkg.name}@${next}`);
+    console.log(`or run the new version once:    npx ${pkg.name}@${next}`);
+    process.exit(1);
+};

package/dist/plugins/openspec/render.js

@@ -87,10 +87,13 @@ const FENCE_LANGS = ['plantuml', 'puml', 'd2'];
  * Markdown одного исходного файла → страница сайта: fenced-диаграммы вырезаются, ссылки
  * на другие страницы источника (`target`, `#x` → `?id=x`) — на их адреса, прочие
  * относительные ссылки на существующие файлы источника регистрируются для копирования к
- * странице (картинки docsify грузит относительно страницы, обычные ссылки — от корня сайта).
- * `fromDir` — posix-каталог файла относительно `srcRoot` (ссылки в нём резолвятся от файла).
+ * странице (картинки и embed docsify грузит относительно страницы, обычные ссылки — от корня
+ * сайта). Embed `':include'` markdown-файла встраивается при сборке: сырой файл docsify
+ * показал бы без локального рендера диаграмм и переписывания ссылок.
+ * `fromDir` — posix-каталог файла относительно `srcRoot` (ссылки в нём резолвятся от файла),
+ * `pageDir` — каталог, от которого считаются пути файлов страницы (у встроенного — каталог страницы).
  */
-export const renderMarkdown = (pagePath, base, content, { srcRoot, fromDir = '', target = () => undefined, source, options }) => {
+export const renderMarkdown = (pagePath, base, content, { srcRoot, fromDir = '', pageDir = fromDir, included = new Set(), target = () => undefined, source, options }) => {
     const { markdown, diagrams } = createFenceExtractor(FENCE_LANGS).extract(content, base, source);
     const files = [];
     const rewrite = (t) => t.replace(LINK_RE, (whole, bang, text, href, title = '') => {
@@ -114,10 +117,28 @@ export const renderMarkdown = (pagePath, base, content, { srcRoot, fromDir = '',
         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)})`;
+        const embed = !bang && /:include\b/.test(title);
+        if (embed && /\.md$/i.test(rel) && !included.has(rel)) {
+            const dir = path.posix.dirname(rel);
+            const sub = renderMarkdown(pagePath, base, fs.readFileSync(abs, 'utf8'), {
+                srcRoot,
+                fromDir: dir === '.' ? '' : dir,
+                pageDir,
+                included: new Set([...included, rel]),
+                target,
+                source: relSource(srcRoot, rel),
+                options
+            });
+            diagrams.push(...sub.diagrams);
+            files.push(...sub.files);
+            return sub.markdown;
+        }
+        const sameDir = fromDir === pageDir;
+        const to = sameDir ? decoded : path.posix.relative(pageDir, rel);
+        files.push({ from: rel, to });
+        return bang || embed
+            ? `${bang}[${inner}](${sameDir ? href : encodeURIPath(to)}${title})`
+            : `[${inner}](${encodeURIPath(path.posix.join(...pagePath, to))}${ignoreTitle(title)})`;
     });
     return { path: pagePath, markdown: mapOutsideFences(markdown, rewrite).trim(), diagrams, files };
 };

package/dist/util/paths.js

@@ -20,5 +20,5 @@ const findPackageRoot = (startDir) => {
 export const PACKAGE_ROOT = findPackageRoot(path.dirname(fileURLToPath(import.meta.url)));
 export const VENDOR_DIR = path.join(PACKAGE_ROOT, 'vendor');
 export const TEMPLATE_DIR = path.join(PACKAGE_ROOT, 'template');
-// Потребляется только как pkg.version (cli/dispatch) — типизируем по факту.
+// Потребляются только version и name (cli/dispatch, cli/update) — типизируем по факту.
 export const packageJson = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'));

package/package.json

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

package/template/AGENTS.md

@@ -12,7 +12,8 @@ c4builder --site -w          # live preview on http://localhost:3000 - never exi
 ```
 
 Not installed: `npm i -g @alfacapital-tech/c4builder` (Node.js 22.17+; Java 17+ is used
-when present, otherwise c4builder downloads a private JRE).
+when present, otherwise c4builder downloads a private JRE). Installed: `c4builder update`
+updates it.
 
 ## Workflow
 
@@ -22,6 +23,8 @@ when present, otherwise c4builder downloads a private JRE).
    Fix until the exit code is 0.
 3. Run `c4builder` and make sure it exits with code 0. Leave `c4builder --site -w` to a
    human or run it in the background.
+4. A stderr line `c4builder <new> is available (current <current>). Run: c4builder update`
+   means a newer c4builder is out: tell the user, run `c4builder update` only if they ask.
 
 ## Layout