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

package/dist/cli/commands/site.js

@@ -100,7 +100,7 @@ pages = () => new Map()) => {
     const distFolder = path.resolve(currentConfiguration.DIST_FOLDER);
     const liveReloadEnabled = !!(program.watch && reloadEmitter);
     const agent = { ...(program.agent ?? { on: false, name: '', explicit: false }) };
-    // Кеш index.html — отдаём его из памяти, если на диске его временно нет
+    // Кеш корневого index.html — отдаём его из памяти, если на диске его временно нет
     // (в окне build.js → emptyDir(DIST_FOLDER) перед записью).
     let lastIndexHtml = null;
     let sweeper;
@@ -421,6 +421,9 @@ pages = () => new Map()) => {
             }
             let filePath;
             const isIndex = urlPath.endsWith('/');
+            // docsify — один корневой index.html с hash-роутингом. Фолбэк окна ребилда только
+            // для корня: иначе любой несуществующий `…/` отвечал бы 200 главной, а не 404.
+            const isRoot = urlPath === '/';
             if (isIndex) {
                 filePath = path.join(distFolder, urlPath, 'index.html');
             }
@@ -436,14 +439,14 @@ pages = () => new Map()) => {
             fs.readFile(resolved, 'utf8', (err, data) => {
                 if (err) {
                     // ENOENT в окне ребилда (emptyDir → запись) — отдаём последний известный index.html.
-                    if (isIndex && lastIndexHtml) {
+                    if (isRoot && lastIndexHtml) {
                         res.set('Cache-Control', 'no-store').type('html').send(lastIndexHtml);
                         return;
                     }
                     return next();
                 }
                 const page = inject(data);
-                if (isIndex)
+                if (isRoot)
                     lastIndexHtml = page;
                 res.set('Cache-Control', 'no-store').type('html').send(page);
             });
@@ -453,7 +456,11 @@ pages = () => new Map()) => {
     // статику через app.use (тот же эффект: fallthrough-обработчик всех GET).
     app.use(express.static(distFolder));
     return new Promise((resolve, reject) => {
-        const server = app.listen(port, '127.0.0.1', () => {
+        // Express 5 зовёт колбэк listen и с ошибкой (занятый порт) — её разбирает
+        // server.on('error') ниже, а «serving» печатаем только после настоящего listen.
+        const server = app.listen(port, '127.0.0.1', (err) => {
+            if (err)
+                return;
             const url = `http://localhost:${port}`;
             console.log('serving your docsify site');
             console.log(`go to ${chalk.green(url)}`);

package/dist/cli/dispatch.js

@@ -31,7 +31,25 @@ 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', 'update', 'feedback', 'skills'];
+// Commander о них не знает — аргументы и описания здесь же, для блока команд в --help.
+const COMMANDS = {
+    check: ['<files...>', 'check diagrams without a build, exit code 0 or 1'],
+    jre: ['info|install', 'which Java will be used | download a JRE in advance'],
+    site: ['', 'build and serve the site locally (same as --site)'],
+    new: ['', 'create a project from the template (same as --new)'],
+    config: ['', 'setup wizard with the current values (same as --config)'],
+    update: ['', 'update a global npm install to the newest version'],
+    feedback: ['', 'wait for page feedback from site -w (--wait --as <name>)'],
+    skills: ['', 'install or update the agent skills in the current folder']
+};
+const commandsHelp = () => {
+    const rows = Object.entries(COMMANDS).map(([name, [args, about]]) => [
+        `${name} ${args}`.trim(),
+        about
+    ]);
+    const width = Math.max(...rows.map(([usage]) => usage.length));
+    return `\nCommands:\n${rows.map(([usage, about]) => `  ${usage.padEnd(width)}  ${about}`).join('\n')}`;
+};
 const intro = () => {
     console.log(chalk.blue(figlet.textSync('c4builder')));
     console.log(chalk.gray('Blow up your software documentation writing skills'));
@@ -113,6 +131,8 @@ function getOptions(c) {
 }
 export default async () => {
     program
+        .name('c4builder')
+        .usage('[command] [options]')
         .version(pkg.version)
         .option('--new', 'create a new project from template')
         .option('--name <name>', 'project name for --new (skips the name prompt)')
@@ -138,14 +158,15 @@ export default async () => {
         return Number(v);
     })
         .allowExcessArguments() // позиционные аргументы подкоманд `jre <action>` и `check <file...>`
+        .addHelpText('after', commandsHelp())
         .parse(process.argv);
     const opts = program.opts();
     const [cmd, ...cmdArgs] = program.args;
     // allowExcessArguments глотает любой позиционный аргумент — без этой проверки
     // опечатка (`c4builder nwe`) молча превращалась бы в сборку.
-    if (cmd !== undefined && !COMMANDS.includes(cmd)) {
+    if (cmd !== undefined && !Object.hasOwn(COMMANDS, cmd)) {
         console.error(chalk.red(`unknown command: ${cmd}`));
-        console.error(`available commands: ${COMMANDS.join(', ')} (see c4builder --help for options)`);
+        console.error(`available commands: ${Object.keys(COMMANDS).join(', ')} (see c4builder --help for options)`);
         process.exit(1);
     }
     // --version/--help уже вышли в parse. Уведомление — по кэшу прошлой проверки, до её
@@ -184,6 +205,11 @@ export default async () => {
         console.error(chalk.red(`no .c4builder in ${process.cwd()} — run inside a project or create one with c4builder new`));
         process.exit(1);
     }
+    // Без терминала мастеру неоткуда взять ответы: inquirer падал со стектрейсом и кодом 0.
+    if (!opts.new && !process.stdin.isTTY && !fs.existsSync(configPath)) {
+        console.error(chalk.red(`no ${opts.configFile ?? '.c4builder'} in ${process.cwd()} — run c4builder --new, or c4builder --config in a terminal`));
+        process.exit(1);
+    }
     let conf = { get: () => { } };
     let cacheConf = { get: () => { }, set: () => { }, clear: () => { } };
     // Лок сборки — рядом с конфигом проекта (см. util/lock.ts). Заполняется вместе с conf.
@@ -191,7 +217,15 @@ export default async () => {
     if (!opts.new) {
         const projectKey = process.cwd().split(path.sep).splice(1).join('_');
         lockPath = `${configPath}.lock`;
-        conf = new Configstore(projectKey, {}, { configPath });
+        try {
+            // По умолчанию Configstore молча затирает битый JSON пустым конфигом — настройки
+            // терялись, а сборка уходила в мастер. --reset стирает конфиг и так.
+            conf = new Configstore(projectKey, {}, { configPath, clearInvalidConfig: !!opts.reset });
+        }
+        catch (e) {
+            console.error(chalk.red(`.c4builder error — cannot read ${configPath}: ${e.message}`));
+            process.exit(1);
+        }
         cacheConf = new Configstore(`${projectKey}_cache`, {}, { configPath: `${configPath}.cache` });
         // Миграция: чексуммы раньше жили в .c4builder, переносим их в .c4builder.cache,
         // чтобы рабочий конфиг перестал «дёргаться» в git при каждой сборке.
@@ -367,8 +401,15 @@ export default async () => {
             }
         }
         isBuilding = false;
-        if (opts.site)
-            return await cmdSite(options, { ...opts, agent: detectAgent(process.env, opts) }, reloadEmitter, () => pages);
+        if (opts.site) {
+            try {
+                return await cmdSite(options, { ...opts, agent: detectAgent(process.env, opts) }, reloadEmitter, () => pages);
+            }
+            catch {
+                // Ошибку запуска сервера (занятый порт) cmdSite уже напечатал — остаётся код выхода.
+                process.exit(1);
+            }
+        }
         if (options.GENERATE_WEBSITE && !opts.watch) {
             console.log(chalk.gray('\nto view the generated website run'));
             console.log(`> c4builder site`);

package/dist/core/build.js

@@ -1,7 +1,7 @@
 import chalk from 'chalk';
 import path from 'node:path';
 import fsextra from 'fs-extra';
-import { makeDirectory, writeFile, writeOnSameLine } from "../util/utils.js";
+import { makeDirectory, writeFile, writeProgress } from "../util/utils.js";
 // clearD2FileCache: сброс кеша графа D2-импортов на границах сборки (сам webworker
 // D2 гасит CLI после одиночной сборки — в watch-режиме он переживает ребилды).
 import { clearD2FileCache } from "./render/d2renderer.js";
@@ -57,16 +57,12 @@ const build = async (options, cacheConf, plugins = []) => {
         }
         if (options.GENERATE_LOCAL_IMAGES) {
             console.log(chalk.blue('generating images'));
-            await generateImages(tree, options, (count, total) => {
-                writeOnSameLine(`processed ${count}/${total} images`);
-            }, cacheConf, bkFolderName);
+            await generateImages(tree, options, (count, total) => writeProgress(count, total, 'images'), cacheConf, bkFolderName);
             console.log('');
         }
         if (options.GENERATE_MD) {
             console.log(chalk.blue('generating markdown files'));
-            await generateMD(tree, options, (count, total) => {
-                writeOnSameLine(`processed ${count}/${total} files`);
-            });
+            await generateMD(tree, options, (count, total) => writeProgress(count, total, 'files'));
             console.log('');
         }
         if (options.GENERATE_WEBSITE) {

package/dist/index.js

@@ -1,4 +1,12 @@
 #!/usr/bin/env node
 //entry point
 import cli from "./cli/dispatch.js";
-cli();
+// Закрытый промпт (Ctrl+C или EOF без терминала) — отмена, а не сбой: одна строка вместо
+// стектрейса inquirer. Код выставляем сами: на EOF процесс уже выходил с кодом 0, и CI
+// принимал несобранный сайт за успех.
+cli().catch((e) => {
+    if (!(e instanceof Error && e.name === 'ExitPromptError'))
+        throw e;
+    console.error(`aborted: the prompt was closed${process.stdin.isTTY ? '' : ' (no terminal for the wizard)'}`);
+    process.exit(1);
+});

package/dist/util/utils.js

@@ -9,8 +9,14 @@ const makeDirectory = async (path) => {
 // Кодировка не передаётся ни одним вызовом → всегда Buffer (потребители зовут .toString()).
 const readFile = (path) => fs.promises.readFile(path);
 const writeFile = (path, data) => fs.promises.writeFile(path, data);
-const writeOnSameLine = async (message) => {
-    process.stdout.write(`${message}\r`);
+// Вне терминала (лог фонового `--site -w`, CI) `\r` не перетирает строку, а склеивает
+// все обновления в одну гигантскую — там печатаем только итог фазы. Перевод строки
+// после прогресса ставит вызывающий.
+const writeProgress = (count, total, unit) => {
+    if (process.stdout.isTTY)
+        process.stdout.write(`processed ${count}/${total} ${unit}\r`);
+    else if (count === total)
+        process.stdout.write(`processed ${total} ${unit}`);
 };
 const encodeURIPath = (path) => {
     path = path.split('\\').join('/');
@@ -110,4 +116,4 @@ const VENDORED_JAR = {
     version: '1.2026.8',
     jar: 'plantuml-1.2026.8.jar'
 };
-export { makeDirectory, readFile, writeFile, encodeURIPath, writeOnSameLine, clearConsole, plantUmlServerUrl, VENDORED_JAR };
+export { makeDirectory, readFile, writeFile, encodeURIPath, writeProgress, clearConsole, plantUmlServerUrl, VENDORED_JAR };

package/package.json

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

package/skills/c4builder/SKILL.md

@@ -72,8 +72,8 @@ How the source tree becomes pages:
 
    With a complete `.c4builder` (written by `c4builder --new --name <name> -y` or by the
    first interactive run) this is a one-off, non-interactive build. A missing or partial
-   config starts an interactive wizard — do not drive it, ask the user or write the full
-   config (references/config.md). A diagram that fails here aborts the build with a long
+   config needs the interactive wizard; without a terminal the run stops with exit code 1.
+   Do not drive the wizard: ask the user or write the full config (references/config.md). A diagram that fails here aborts the build with a long
    Java stack trace and keeps the previous output in `docs_bk/`; run `c4builder check` on
    the changed files to get the short message.
 4. **Look at the result** in `docs/`: `docs/<folder>/README.md` (markdown collection),