@alfacapital-tech/c4builder 0.5.1 → 0.7.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/index.js

@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { z } from 'zod';
 import { definePlugin } from "../../core/plugins/types.js";
+import { layoutChanges, pageOrder } from "./layout.js";
 import { scanStore } from "./scan.js";
 import { renderArchiveIndex, renderChange, renderChangesIndex, relSource, renderMarkdown, renderSpecTree, renderSummary } from "./render.js";
 const optionsSchema = z
@@ -12,7 +13,10 @@ const optionsSchema = z
     mount: z.string().min(1).default('OpenSpec'),
     // Порядок артефактов change'а; первый выводится на странице change'а, остальные —
     // подстраницами; не перечисленные — после, по алфавиту.
-    artifacts: z.array(z.string()).default(['proposal', 'design', 'tasks'])
+    artifacts: z.array(z.string()).default(['proposal', 'design', 'tasks']),
+    // Ключ `.openspec.yaml` со ссылкой на родительский change (например `x-parent`):
+    // вложенный change выводится страницей под родителем. Не задан — плоский список.
+    parentKey: z.string().min(1).optional()
 })
     .strict();
 export default definePlugin({
@@ -47,14 +51,24 @@ export default definePlugin({
                 }
             }
         };
-        const addChange = (change, segments) => addPages(renderChange(change, segments, o.artifacts, options), change.dir);
-        ctx.addPage({ path: [mount], markdown: renderSummary(store, mount, options) });
+        // Родитель добавляется раньше вложенных: в sidebar под ним сначала его артефакты,
+        // затем вложенные change'ы.
+        const addChanges = (changes, layout) => {
+            for (const change of pageOrder(changes, layout)) {
+                const at = layout.get(change);
+                if (at)
+                    addPages(renderChange(change, at.segments, o.artifacts, options, layout), change.dir);
+            }
+        };
+        const { parentKey } = o;
+        const active = layoutChanges(store.changes, [mount, 'Changes'], { parentKey });
+        const archived = layoutChanges(store.archive, [mount, 'Archive'], { parentKey, archived: true });
+        ctx.addPage({ path: [mount], markdown: renderSummary(store, mount, options, active) });
         ctx.addPage({
             path: [mount, 'Changes'],
-            markdown: renderChangesIndex(store.changes, mount, options)
+            markdown: renderChangesIndex(store.changes, mount, options, active)
         });
-        for (const change of store.changes)
-            addChange(change, [mount, 'Changes', change.id]);
+        addChanges(store.changes, active);
         // Specs: индекс, промежуточные папки, страницы спек — тем же рендером, что и
         // дельты (fenced-диаграммы локально, ссылки на файлы рядом со спекой).
         const specsDir = path.join(storeDir, 'specs');
@@ -66,9 +80,8 @@ export default definePlugin({
         })), specsDir);
         ctx.addPage({
             path: [mount, 'Archive'],
-            markdown: renderArchiveIndex(store.archive, mount, options)
+            markdown: renderArchiveIndex(store.archive, mount, options, archived)
         });
-        for (const change of store.archive)
-            addChange(change, [mount, 'Archive', change.id]);
+        addChanges(store.archive, archived);
     }
 });

package/dist/plugins/openspec/layout.js

@@ -0,0 +1,57 @@
+// Архивный change — `<YYYY-MM-DD>-<id>`; ссылка на родителя пишется по активному id.
+const DATE_PREFIX = /^\d{4}-\d{2}-\d{2}-/;
+const originalId = (c, archived) => archived ? c.id.replace(DATE_PREFIX, '') : c.id;
+/**
+ * Без `parentKey` — все change'ы на верхнем уровне `base` (прежнее поведение). С ним
+ * change, у которого в `.openspec.yaml` есть `parentKey`, указывающий на change того же
+ * списка, кладётся страницей под родителя. Вложенность — один уровень: родитель сам
+ * вложенный или не найден — change остаётся на верхнем уровне. Подпись вложенного — хвост
+ * id после `<id родителя>-`; если хвоста нет или он совпадает с подстраницей родителя
+ * (артефакт, `specs`) или с подписью соседа — полный id.
+ */
+export const layoutChanges = (changes, base, { parentKey, archived = false } = {}) => {
+    const byId = new Map(changes.map((c) => [originalId(c, archived), c]));
+    const parentOf = (c) => {
+        const ref = parentKey ? c.meta[parentKey] : undefined;
+        const p = ref ? byId.get(ref) : undefined;
+        return p && p !== c ? p : undefined;
+    };
+    const layout = new Map();
+    const top = changes.filter((c) => {
+        const p = parentOf(c);
+        return !p || parentOf(p);
+    });
+    for (const c of top)
+        layout.set(c, { segments: [...base, c.id], label: c.id, children: [] });
+    for (const c of changes) {
+        if (layout.has(c))
+            continue;
+        const parent = parentOf(c);
+        const host = layout.get(parent);
+        const taken = new Set([
+            ...parent.artifacts.map((a) => a.name),
+            'specs',
+            ...host.children.map((s) => layout.get(s).label)
+        ]);
+        const own = originalId(c, archived);
+        const prefix = `${originalId(parent, archived)}-`;
+        const tail = own.startsWith(prefix) ? own.slice(prefix.length) : '';
+        const label = tail && !taken.has(tail) ? tail : c.id;
+        layout.set(c, { segments: [...host.segments, label], label, parent, children: [] });
+        host.children.push(c);
+    }
+    return layout;
+};
+/**
+ * Change'ы в порядке вывода: каждый верхнего уровня, сразу за ним — его вложенные. Порядок
+ * внутри обоих уровней — порядок `changes` (по имени для страниц, по дате для таблиц).
+ */
+export const pageOrder = (changes, layout) => {
+    const pos = new Map(changes.map((c, i) => [c, i]));
+    return changes
+        .filter((c) => !layout.get(c)?.parent)
+        .flatMap((c) => [
+        c,
+        ...[...(layout.get(c)?.children ?? [])].sort((a, b) => (pos.get(a) ?? 0) - (pos.get(b) ?? 0))
+    ]);
+};

package/dist/plugins/openspec/render.js

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createFenceExtractor, mapOutsideFences } from "../../core/scan/fences.js";
 import { encodeURIPath } from "../../util/utils.js";
+import { pageOrder } from "./layout.js";
 // Ссылка на страницу сайта от корня (без ведущего «/»): так же строится sidebar,
 // а docsify без relativePath резолвит ссылки от корня сайта.
 export const pageLink = (segments, options) => encodeURIPath(path.posix.join(...segments, options.WEB_FILE_NAME || segments[segments.length - 1]));
@@ -10,17 +11,23 @@ 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) => {
+/**
+ * Таблица change'ов (сводка и индекс Changes): по дате изменения от новых к старым. С `layout`
+ * вложенные change'ы идут сразу под родителем (`↳` + подпись) и ведут на свои вложенные страницы.
+ */
+export const renderChangesIndex = (changes, mount, options, layout) => {
     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)} |`);
+    const byDate = [...changes].sort((a, b) => b.mtime - a.mtime);
+    const rows = (layout ? pageOrder(byDate, layout) : byDate).map((c) => {
+        const at = layout?.get(c);
+        const link = `[${at?.label ?? c.id}](${pageLink(at?.segments ?? [mount, 'Changes', c.id], options)})`;
+        return `| ${at?.parent ? `↳ ${link}` : link} | ${c.schema ?? '—'} | ${fmtProgress(c)} | ${fmtDate(c.mtime)} |`;
+    });
     return ['| Change | Schema | Tasks | Updated |', '|---|---|---|---|', ...rows].join('\n');
 };
 /** Сводка store (страница mount): счётчики, суммарный прогресс, таблица активных change'ов. */
-export const renderSummary = (store, mount, options) => {
+export const renderSummary = (store, mount, options, layout) => {
     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);
@@ -33,11 +40,18 @@ export const renderSummary = (store, mount, options) => {
         '',
         '## Active changes',
         '',
-        renderChangesIndex(store.changes, mount, options)
+        renderChangesIndex(store.changes, mount, options, layout)
     ].join('\n');
 };
-export const renderArchiveIndex = (archive, mount, options) => archive.length
-    ? archive.map((c) => `- [${c.id}](${pageLink([mount, 'Archive', c.id], options)})`).join('\n')
+/** Список архива: от новых к старым; с `layout` вложенные — пунктами под родителем. */
+export const renderArchiveIndex = (archive, mount, options, layout) => archive.length
+    ? (layout ? pageOrder(archive, layout) : archive)
+        .map((c) => {
+        const at = layout?.get(c);
+        const link = pageLink(at?.segments ?? [mount, 'Archive', c.id], options);
+        return `${at?.parent ? '  ' : ''}- [${at?.label ?? c.id}](${link})`;
+    })
+        .join('\n')
     : '_Archive is empty._';
 /** Индекс папки спек (Specs, промежуточные папки, дельты change'а): вложенный список под prefix. */
 export const renderSpecIndex = (specs, prefix, base, options) => {
@@ -179,7 +193,7 @@ const orderArtifacts = (artifacts, order) => [...artifacts].sort((a, b) => {
  * `specs` дельт (страница на capability, структура папок). Артефакт с именем `specs`
  * делит страницу с индексом дельт.
  */
-export const renderChange = (change, segments, order, options) => {
+export const renderChange = (change, segments, order, options, layout) => {
     const ordered = orderArtifacts(change.artifacts, order);
     const inline = ordered[0]?.name === order[0] ? ordered[0] : undefined;
     const deltas = change.deltas.map((d) => ({
@@ -222,11 +236,23 @@ export const renderChange = (change, segments, order, options) => {
     ]
         .filter(Boolean)
         .join(' · ');
+    // Связи по опции parentKey: у вложенного — ссылка на родителя, у родителя — на вложенные.
+    const at = layout?.get(change);
+    const linkTo = (c) => {
+        const p = layout?.get(c);
+        return p ? `[${p.label}](${pageLink(p.segments, options)})` : c.id;
+    };
+    const family = [
+        at?.parent && `**Parent:** ${linkTo(at.parent)}`,
+        at?.children.length && `**Sub-changes:** ${at.children.map(linkTo).join(' · ')}`
+    ]
+        .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'),
+            markdown: [head, family, links.join(' · '), main?.markdown].filter(Boolean).join('\n\n'),
             diagrams: main?.diagrams ?? [],
             files: main?.files ?? []
         },

package/dist/plugins/openspec/scan.js

@@ -32,17 +32,19 @@ export const taskProgress = (tasks) => {
         return undefined;
     return { done: boxes.filter((m) => m[1] !== ' ').length, total: boxes.length };
 };
-// Метаданные `.openspec.yaml` построчно: нужны два скаляра, yaml-парсер избыточен.
+// Метаданные `.openspec.yaml` построчно: нужны только скаляры верхнего уровня (schema,
+// created и пользовательские ключи вроде `x-parent`), 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;
+    if (fs.existsSync(file))
+        for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+            const m = line.match(/^([A-Za-z0-9_.-]+):[ \t]*(.+?)\s*$/);
+            if (!m || m[2].startsWith('#'))
+                continue;
+            // Комментарий в конце строки (` # …`) — не часть значения.
+            meta[m[1]] = m[2].replace(/\s+#.*$/, '').replace(/^["']|["']$/g, '');
+        }
+    return { schema: meta.schema, created: meta.created, meta };
 };
 const scanChange = (dir) => {
     const files = fs.readdirSync(dir, { withFileTypes: true });

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.1",
+  "version": "0.7.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