@alfacapital-tech/c4builder 0.3.0-rc.2 → 0.3.0

package/README.MD

@@ -33,15 +33,22 @@ I strongly encourage people to check them out first but if you want to dive righ
 `npm install` (no tag) always installs the latest stable release. Release candidates are
 opt-in only — see [Installing a release candidate](#installing-a-release-candidate).
 
-**Requirements:** local diagram generation needs a Java runtime (JRE 17+) on `PATH`.
-Graphviz is **not** required — layout is computed by PlantUML's built-in Java engine
-(Smetana). The PlantUML jar and the diagram font are bundled with c4builder.
+**Requirements:** Node.js ≥ 20.19. Local diagram generation needs Java 17+: a system
+`java` (`JAVA_HOME`/`PATH`) is used when present, otherwise c4builder downloads a private
+JRE into its cache automatically (`c4builder jre install` pre-warms it, `jre info` shows
+what would be used). Graphviz is **not** required — layout is computed by PlantUML's
+built-in Java engine (Smetana). The PlantUML jar and the diagram font are bundled.
 
 With `diagramFormat: png`, diagrams are produced by rasterizing their SVG with
 [`@resvg/resvg-js`](https://github.com/thx/resvg-js) (a bundled dependency, prebuilt
 native binary, no browser). This gives a single deterministic PNG for both PlantUML and
 D2, using the bundled font. ditaa diagrams stay native PlantUML PNG.
 
+**Fonts.** Diagrams use the bundled Nimbus Sans (Helvetica metrics, Cyrillic and Greek —
+see `vendor/fonts/README.md`), so diagram geometry is identical on any machine.
+`useSystemFonts: true` in `.c4builder` (or `--system-fonts` for one run) renders with the
+machine's fonts instead — machine-dependent by design.
+
 The easiest way to get started is with the _new project_ template.
 
 ![new](docs/images/new.gif)
@@ -57,24 +64,36 @@ A sample project is available at [C4Builder-Demo](https://github.com/adrianvlupu
 ## Available Commands
 
 ```bash
-PS C:\docprojects\Online Banking> c4builder --help
+$ c4builder --help
 Usage: index [options]
 
 Options:
-  -V, --version                     output the version number
-  new                               create a new project from template
-  config                            change configuration for the current directory
-  list                              display the current configuration
-  reset                             clear all configuration
-  site                              serve the generated site
-  -w, --watch                       watch for changes and rebuild
-  -o, --open                        open the generated site in the browser (with --site)
-  docs                              a brief explanation for the available configuration options
-  -p, --port <n>                    port used for serving the generated site
-  -c, --config-file <.c4builder>    set the configuration file relative path
-  -h, --help                        output usage information
+  -V, --version                   output the version number
+  --new                           create a new project from template
+  --name <name>                   project name for --new (skips the name prompt)
+  -y, --yes                       non-interactive --new: defaults, no prompts
+                                  (requires --name)
+  --force                         for `jre install`: force JRE download even if
+                                  system java is present
+  --config                        change configuration for the current directory
+  -c, --config-file <.c4builder>  set the configuration file relative path
+  --list                          display the current configuration
+  --reset                         clear all configuration
+  --site                          serve the generated site
+  -w, --watch                     watch for changes and rebuild
+  -o, --open                      open the generated site in the browser (with
+                                  --site)
+  --docs                          a brief explanation for the available
+                                  configuration options
+  --system-fonts                  render with system fonts instead of the
+                                  bundled one (not deterministic)
+  -p, --port <n>                  port used for serving the generated site
+  -h, --help                      display help for command
 ```
 
+There is also a `jre` subcommand: `c4builder jre install [--force]` pre-downloads the
+private JRE cache, `c4builder jre info` prints which Java would be used.
+
 By default, running `c4builder` will attempt to build the project.
 
 If no configuration was set it will ask for it and then do the actual build. Running just `c4builder` after a configuration will no longer show the wizard.
@@ -212,7 +231,7 @@ The generated markdown file makes for an easy single page readme for the reposit
 
 ### Docsify site with a sidebar
 
-After choosing to generate a docsify site, it can be viewed locally by running `c4builder site` and accessing `http://localhost:3000`;
+After choosing to generate a docsify site, it can be viewed locally by running `c4builder --site` and accessing `http://localhost:3000`;
 
 The site is minimalistic including only a sidebar with the System/Container/Components hierarchy.
 
@@ -259,6 +278,28 @@ Pre-release builds (`0.x.y-rc.N`) are published under the npm dist-tag `rc` and
 
 `npm install` without a tag keeps installing the latest stable version.
 
+## Docker
+
+The image ships everything needed for a build (Node, JRE, PlantUML jar, fonts, D2) —
+mount a project into `/pwd`:
+
+```bash
+docker run --rm -v "$PWD:/pwd" ghcr.io/alfacapital-tech/c4builder:latest c4builder
+```
+
+Tags (in sync with npm dist-tags):
+
+| tag | meaning |
+|---|---|
+| `X.Y.Z`, `sha-…` | immutable releases / commits |
+| `latest` | latest stable release |
+| `rc` | latest release candidate |
+| `edge` | last master commit |
+| `pr-N` | pull request builds |
+
+Use the image directly in CI (GitHub Actions, GitLab CI) as the job image — the
+`c4builder` binary is on `PATH`.
+
 ## Releasing
 
 Publishing is triggered by pushing a git tag `v<version>` — pushes/merges to `master` alone
@@ -286,7 +327,22 @@ Publishes to dist-tag `latest`.
 
 ## v0.3.0
 
-PDF output removed — use the docsify site or the single/collection markdown outputs instead (the `pdf`/`pdfCss` options no longer exist).
+Full TypeScript rewrite (ESM, Node.js ≥ 20.19) with the same CLI and `.c4builder` format.
+
+- PlantUML renders via a direct `java` call with the built-in Smetana layout — graphviz
+  is no longer needed; the jar is bundled (`vendor/`)
+- Java itself is optional: system java ≥ 17 is used when present, otherwise a private
+  JRE is downloaded automatically (`c4builder jre install` / `jre info`)
+- Second diagram backend: [D2](https://d2lang.com) (`.d2` files, optional
+  `@terrastruct/d2` dependency, imports supported)
+- `diagramFormat: png` rasterizes SVG with `@resvg/resvg-js` — deterministic PNG for
+  PlantUML and D2 alike
+- Bundled Nimbus Sans font for identical diagram geometry everywhere;
+  `useSystemFonts` / `--system-fonts` opts out
+- Config is validated (zod): typos and wrong types fail with a clear message
+- Docker image on GHCR with a tag scheme in sync with npm dist-tags (see [Docker](#docker))
+- PDF output removed — use the docsify site or the single/collection markdown outputs
+  instead (the `pdf`/`pdfCss` options no longer exist)
 
 ## v0.2.20
 

package/dist/cli/dispatch.js

@@ -92,7 +92,8 @@ function getOptions(c) {
         WEB_FILE_NAME: c.webFileName,
         SUPPORT_SEARCH: c.supportSearch,
         EXECUTE_SCRIPT: c.executeScript,
-        EXCLUDE_OTHER_FILES: c.excludeOtherFiles
+        EXCLUDE_OTHER_FILES: c.excludeOtherFiles,
+        USE_SYSTEM_FONTS: c.useSystemFonts
     };
 }
 export default async () => {
@@ -110,6 +111,7 @@ export default async () => {
         .option('-w, --watch', 'watch for changes and rebuild')
         .option('-o, --open', 'open the generated site in the browser (with --site)')
         .option('--docs', 'a brief explanation for the available configuration options')
+        .option('--system-fonts', 'render with system fonts instead of the bundled one (not deterministic)')
         .option('-p, --port <n>', 'port used for serving the generated site', (v) => {
         // parseInt молча резал бы опечатку ('30OO' → 30) — валидируем строго.
         if (!isValidPort(v))
@@ -202,6 +204,8 @@ export default async () => {
         // уводил бы последующие запуски на строгий путь (exit 1 до визарда).
         conf.set('hasRun', true);
         const options = getOptions(built.value);
+        if (opts.systemFonts)
+            options.USE_SYSTEM_FONTS = true; // флаг сильнее ключа конфига
         const reloadEmitter = new EventEmitter();
         reloadEmitter.setMaxListeners(0);
         if (opts.watch) {

package/dist/config/defaults.js

@@ -29,6 +29,7 @@ const defaultConfig = {
     plantumlServerUrl: 'https://www.plantuml.com/plantuml',
     diagramFormat: 'svg',
     d2Layout: 'dagre',
-    charset: 'UTF-8'
+    charset: 'UTF-8',
+    useSystemFonts: false
 };
 export { defaultConfig };

package/dist/config/schema.js

@@ -53,6 +53,7 @@ export const configSchema = z.object({
     diagramFormat: str(defaultConfig.diagramFormat),
     d2Layout: str(defaultConfig.d2Layout),
     charset: str(defaultConfig.charset),
+    useSystemFonts: bool(defaultConfig.useSystemFonts),
     // Задаются явно (флаг/промпт) либо тонкой правкой файла — в defaultConfig не входят.
     projectName: optStr(),
     webFileName: optStr(),

package/dist/core/render/diagrams.js

@@ -78,6 +78,9 @@ const d2EngineVersion = () => {
     }
     return d2VersionCache;
 };
+// В ключ кеша: смена режима не должна отдавать картинку, отрисованную другим шрифтом
+// (D2 тоже — его PNG растрирует общий resvg).
+export const fontCacheTag = (options) => options.USE_SYSTEM_FONTS ? 'system' : DEFAULT_FONT_NAME;
 export const getMime = (format) => {
     if (format === 'svg')
         return `image/svg+xml`;
@@ -102,22 +105,24 @@ export const httpGet = async (url) => (await httpGetBuffer(url)).toString('base6
 // расходятся между ОС. С пином шрифт берётся из vendor/fonts (JRE своих не несёт,
 // freetype у Temurin бандлед), и SVG получается одинаковым везде.
 // ditaa этим не лечится: его движок берёт AWT-шрифт мимо обеих опций.
-export const renderDiagram = (content, { javaBin, jarPath, includePath, format, charset, isDitaa }) => new Promise((resolve, reject) => {
-    const argv = [
-        '-Djava.awt.headless=true',
-        `-Dplantuml.include.path=${includePath}`,
-        `-Dsun.java2d.fontpath=prepend:${FONTS_DIR}`,
-        '-jar',
-        jarPath,
-        ...(isDitaa ? [] : ['-Playout=smetana']),
-        `-SdefaultFontName=${DEFAULT_FONT_NAME}`,
-        `-SCircledCharacterFontName=${DEFAULT_FONT_NAME}`,
-        '-charset',
-        charset,
-        `-t${format}`,
-        '-pipe'
-    ];
-    const child = spawn(javaBin, argv);
+// useSystemFonts убирает все три шрифтовых аргумента — рендер как до пина (машинозависим).
+export const renderArgv = ({ jarPath, includePath, format, charset, isDitaa, useSystemFonts }) => [
+    '-Djava.awt.headless=true',
+    `-Dplantuml.include.path=${includePath}`,
+    ...(useSystemFonts ? [] : [`-Dsun.java2d.fontpath=prepend:${FONTS_DIR}`]),
+    '-jar',
+    jarPath,
+    ...(isDitaa ? [] : ['-Playout=smetana']),
+    ...(useSystemFonts
+        ? []
+        : [`-SdefaultFontName=${DEFAULT_FONT_NAME}`, `-SCircledCharacterFontName=${DEFAULT_FONT_NAME}`]),
+    '-charset',
+    charset,
+    `-t${format}`,
+    '-pipe'
+];
+export const renderDiagram = (content, options) => new Promise((resolve, reject) => {
+    const child = spawn(options.javaBin, renderArgv(options));
     const stdout = [];
     const stderr = [];
     // stdio по умолчанию 'pipe' → потоки заведомо не null; берём их деструктуризацией
@@ -253,9 +258,10 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
             // чексумму → из бэкапа копировалась старая картинка (новые параметры молча
             // игнорировались, кэш чистился только через --reset). Формат/движок/версия
             // движка тоже в ключе: их смена обязана приводить к перерендеру.
-            const renderKey = entryPath !== null
+            const renderKey = (entryPath !== null
                 ? `d2\0${d2EngineVersion()}\0layout=${options.D2_LAYOUT}\0fmt=${outFormat}`
-                : `puml\0${VENDORED_JAR.version}\0charset=${options.CHARSET}\0fmt=${outFormat}\0ditaa=${diagram.isDitaa}\0font=${DEFAULT_FONT_NAME}`;
+                : `puml\0${VENDORED_JAR.version}\0charset=${options.CHARSET}\0fmt=${outFormat}\0ditaa=${diagram.isDitaa}`) +
+                `\0font=${fontCacheTag(options)}`;
             const cksum = crypto
                 .createHash('sha256')
                 .update(body + includes + renderKey, 'utf-8')
@@ -305,10 +311,13 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
                             includePath,
                             format: needsRaster ? 'svg' : outFormat,
                             charset: options.CHARSET,
-                            isDitaa
+                            isDitaa,
+                            useSystemFonts: options.USE_SYSTEM_FONTS
                         });
                     }
-                    const image = needsRaster ? await rasterizeSvgToPng(rendered) : rendered;
+                    const image = needsRaster
+                        ? await rasterizeSvgToPng(rendered, options.USE_SYSTEM_FONTS)
+                        : rendered;
                     await writeFile(filePath, image);
                     cksumEntry.ok = true;
                 }

package/dist/core/render/fonts.js

@@ -5,4 +5,4 @@ import { VENDOR_DIR } from "../../util/paths.js";
 // (`fontDirs`, `defaultFontFamily`). Значения обязаны совпадать — иначе метрики
 // текста разъедутся и PNG-golden покраснеют. НЕ менять без пересбора эталонов.
 export const FONTS_DIR = path.join(VENDOR_DIR, 'fonts');
-export const DEFAULT_FONT_NAME = 'Liberation Sans';
+export const DEFAULT_FONT_NAME = 'Nimbus Sans';

package/dist/core/render/pngraster.js

@@ -20,21 +20,18 @@ const getResvg = () => {
     }
     return resvgMod;
 };
+export const resvgFontOptions = (useSystemFonts) => useSystemFonts
+    ? { loadSystemFonts: true }
+    : { fontDirs: [FONTS_DIR], defaultFontFamily: DEFAULT_FONT_NAME, loadSystemFonts: false };
 // SVG (Buffer или строка) → PNG (Buffer), масштаб 1:1 к размеру SVG. Вход — валидный
 // SVG движка: PlantUML ссылается на шрифт по имени (грузим из vendor/fonts), D2 несёт
-// шрифт во вшитом @font-face, но loadSystemFonts:false фиксируем в обоих случаях.
+// шрифт во вшитом @font-face, но пин по умолчанию фиксируем в обоих случаях.
 // renderAsync считает в napi-пуле тредов: JS-поток не блокируется, PlantUML-пул и
 // D2-очередь продолжают крутиться параллельно растеризации (прежний sync render()
 // останавливал весь event loop на каждую картинку).
-const rasterizeSvgToPng = async (svg) => {
+const rasterizeSvgToPng = async (svg, useSystemFonts = false) => {
     const { renderAsync } = getResvg();
-    const rendered = await renderAsync(svg, {
-        font: {
-            fontDirs: [FONTS_DIR],
-            defaultFontFamily: DEFAULT_FONT_NAME,
-            loadSystemFonts: false
-        }
-    });
+    const rendered = await renderAsync(svg, { font: resvgFontOptions(useSystemFonts) });
     return rendered.asPng();
 };
 export { rasterizeSvgToPng };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfacapital-tech/c4builder",
-  "version": "0.3.0-rc.2",
+  "version": "0.3.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/vendor/fonts/README.md

@@ -1,17 +1,20 @@
 # Вендорные шрифты
 
-## Liberation Sans
+## Nimbus Sans
 
-`LiberationSans-{Regular,Bold,Italic,BoldItalic}.ttf`
+`NimbusSans-{Regular,Bold,Italic,BoldItalic}.otf`
 
 - **Назначение:** детерминизм метрик текста в SVG. Ширина текста (`textLength`)
   считается PlantUML из AWT-метрик шрифта; системный `sans-serif` резолвится
   по-разному на разных машинах. Шрифт отдаётся JVM через
-  `-Dsun.java2d.fontpath=prepend:` + `-SdefaultFontName=Liberation Sans`, чтобы
-  метрики не зависели от машины (см. `build.js`).
-- **Происхождение:** пакет `ttf-liberation` / `fonts-liberation`, версия 2.1.5
-  (font version 2.1). Метрически совместим с Arial; та же версия поставляется на
-  CI-раннере `ubuntu-24.04`.
-- **Лицензия:** SIL Open Font License 1.1 (разрешает вендоринг и распространение).
-  Полный текст: <https://openfontlicense.org/> · апстрим:
-  <https://github.com/liberationfonts/liberation-fonts>.
+  `-Dsun.java2d.fontpath=prepend:` + `-SdefaultFontName=Nimbus Sans` и resvg через
+  `fontDirs` (см. `src/core/render/fonts.ts`). Пин снимается ключом `useSystemFonts`
+  в `.c4builder` / флагом `--system-fonts` — тогда рендер идёт системным шрифтом и
+  перестаёт быть машинонезависимым.
+- **Происхождение:** URW base35 (Artifex), релиз 20200910 — файлы побайтно совпадают
+  с пакетом `gsfonts` этой версии. Метрически совместим с Helvetica, содержит
+  кириллицу и греческий. Апстрим:
+  <https://github.com/ArtifexSoftware/urw-base35-fonts>.
+- **Лицензия:** AGPL-3.0-only с шрифтовым исключением
+  (`PS-or-PDF-font-exception-20170817`): встраивание шрифта в документы не делает их
+  производными работами. Полный текст — в апстрим-репозитории (`LICENSE`).