confluence-md-sync 0.1.1 → 0.2.0

package/README.md

@@ -95,6 +95,49 @@ const { storage } = await publishPage({ pageId, markdownPath, dryRun: true }, cf
 await publishPage({ pageId, markdown: '# Generated\n\ntext' }, cfg);
 ```
 
+## BPMN diagrams out of the box
+
+Pass a `.bpmn` file as an image — it is rendered to PNG at publish time
+(headless Chromium via [bpmn-to-image](https://npmjs.com/package/bpmn-to-image),
+an optional peer dependency):
+
+```bash
+npm install -D bpmn-to-image
+```
+
+> bpmn-to-image pins puppeteer 21, whose bundled Chromium fails to launch on
+> recent OSes ("socket hang up"). Force a current puppeteer in your
+> `package.json`:
+>
+> ```json
+> "overrides": { "puppeteer": "^24.0.0" }
+> ```
+
+```markdown
+Процесс выпуска релиза:
+
+{{img:release-flow.bpmn}}
+```
+
+```ts
+await publishPage({
+  pageId: '123456789',
+  markdownPath: 'docs/process.md',
+  images: ['docs/release-flow.bpmn'],   // converted to release-flow.png automatically
+  bpmnOutDir: 'build',                  // optional; default: temp dir per run
+}, cfg);
+```
+
+Chromium PNG output is not byte-stable between runs, so dedup is pinned to
+the SHA-256 of the *source* `.bpmn` via a `.src-sha256` sidecar — unchanged
+diagrams never create new attachment versions. Batch pre-conversion is also
+available:
+
+```ts
+import { convertBpmnFolder } from 'confluence-md-sync';
+await convertBpmnFolder({ srcDir: 'docs/diagrams', outDir: 'build' });
+```
+
 ## Read pages and tables
 
 ```ts

package/dist/bpmn/convert.d.ts

@@ -0,0 +1,46 @@
+/**
+ * BPMN → image conversion (out-of-the-box BPMN support).
+ *
+ * Тяжёлые зависимости (`bpmn-to-image` + puppeteer/Chromium) — опциональный
+ * peer dependency: импортируются динамически только когда конвертация
+ * реально запрошена. Ядро библиотеки остаётся лёгким.
+ *
+ *   npm install -D bpmn-to-image
+ */
+export type BpmnImageFormat = 'png' | 'svg' | 'pdf';
+export declare const BPMN_FILE_RE: RegExp;
+export declare function isBpmnFile(path: string): boolean;
+/** `p1.bpmn` → `p1.png` (имя выходного файла для формата). */
+export declare function bpmnOutputName(file: string, format?: BpmnImageFormat): string;
+export interface BpmnConversion {
+    input: string;
+    output: string;
+}
+/**
+ * Конвертирует BPMN-файлы в изображения по явному списку input → output.
+ *
+ * Рядом с каждым результатом пишется sidecar `<output>.src-sha256` с SHA-256
+ * исходного BPMN — AttachmentService использует его как dedup-tag вместо SHA
+ * результата (PNG от Chromium байт-нестабилен между запусками, BPMN —
+ * стабилен). Так Confluence не плодит лишние версии аттача, когда диаграмма
+ * не менялась.
+ */
+export declare function convertBpmn(conversions: BpmnConversion[]): Promise<void>;
+export interface ConvertBpmnFolderOptions {
+    /** Папка-источник с `*.bpmn`. */
+    srcDir: string;
+    /** Папка-приёмник для сгенерированных изображений. Будет создана, если её нет. */
+    outDir: string;
+    /** Формат выхода. Дефолт — `png`. */
+    format?: BpmnImageFormat;
+    /** Регулярка для фильтра входов. Дефолт — `/\.bpmn$/i`. */
+    pattern?: RegExp;
+}
+/**
+ * Конвертирует все BPMN-файлы из `srcDir` в изображения в `outDir`.
+ * Файлы получают то же базовое имя с расширением формата (`p1.bpmn` → `p1.png`).
+ *
+ * Сгенерированные файлы — артефакты сборки: коммитить их не нужно.
+ * В Confluence они улетают как аттачи на этапе публикации.
+ */
+export declare function convertBpmnFolder(opts: ConvertBpmnFolderOptions): Promise<BpmnConversion[]>;

package/dist/bpmn/convert.js

@@ -0,0 +1,109 @@
+/**
+ * BPMN → image conversion (out-of-the-box BPMN support).
+ *
+ * Тяжёлые зависимости (`bpmn-to-image` + puppeteer/Chromium) — опциональный
+ * peer dependency: импортируются динамически только когда конвертация
+ * реально запрошена. Ядро библиотеки остаётся лёгким.
+ *
+ *   npm install -D bpmn-to-image
+ */
+import { createHash } from 'node:crypto';
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, extname, join } from 'node:path';
+import { SRC_SHA_SIDECAR_SUFFIX } from '../attachments/attachment.js';
+export const BPMN_FILE_RE = /\.bpmn$/i;
+export function isBpmnFile(path) {
+    return BPMN_FILE_RE.test(path);
+}
+/** `p1.bpmn` → `p1.png` (имя выходного файла для формата). */
+export function bpmnOutputName(file, format = 'png') {
+    return `${basename(file, extname(file))}.${format}`;
+}
+let puppeteerPatched = false;
+/**
+ * bpmn-to-image вызывает puppeteer.launch() без флагов. В CI Chromium
+ * запускается из-под root и без --no-sandbox просто не стартует. Патчим
+ * глобальный puppeteer.launch один раз — best-effort: если puppeteer
+ * не резолвится из нашего контекста, bpmn-to-image разберётся сам.
+ */
+async function patchPuppeteerForCI() {
+    if (puppeteerPatched)
+        return;
+    puppeteerPatched = true;
+    try {
+        const { default: puppeteer } = await import('puppeteer');
+        const origLaunch = puppeteer.launch.bind(puppeteer);
+        puppeteer.launch = ((options = {}) => {
+            const existing = options?.args ?? [];
+            const patched = [
+                ...existing,
+                '--no-sandbox',
+                '--disable-setuid-sandbox',
+                '--disable-dev-shm-usage',
+            ];
+            return origLaunch({ ...options, args: patched });
+        });
+    }
+    catch {
+        // puppeteer не установлен отдельно — положимся на bpmn-to-image
+    }
+}
+async function loadConverter() {
+    try {
+        const mod = await import('bpmn-to-image');
+        await patchPuppeteerForCI();
+        return mod;
+    }
+    catch (err) {
+        if (err.code === 'ERR_MODULE_NOT_FOUND') {
+            throw new Error("BPMN conversion requires the optional peer dependency 'bpmn-to-image'. " +
+                'Install it with: npm install -D bpmn-to-image');
+        }
+        throw err;
+    }
+}
+/**
+ * Конвертирует BPMN-файлы в изображения по явному списку input → output.
+ *
+ * Рядом с каждым результатом пишется sidecar `<output>.src-sha256` с SHA-256
+ * исходного BPMN — AttachmentService использует его как dedup-tag вместо SHA
+ * результата (PNG от Chromium байт-нестабилен между запусками, BPMN —
+ * стабилен). Так Confluence не плодит лишние версии аттача, когда диаграмма
+ * не менялась.
+ */
+export async function convertBpmn(conversions) {
+    if (conversions.length === 0)
+        return;
+    const { convertAll } = await loadConverter();
+    for (const c of conversions) {
+        mkdirSync(dirname(c.output), { recursive: true });
+    }
+    console.log(`[bpmn] converting ${conversions.length} diagram(s)`);
+    await convertAll(conversions.map((c) => ({ input: c.input, outputs: [c.output] })));
+    for (const c of conversions) {
+        const sha = createHash('sha256').update(readFileSync(c.input)).digest('hex');
+        writeFileSync(c.output + SRC_SHA_SIDECAR_SUFFIX, sha);
+    }
+}
+/**
+ * Конвертирует все BPMN-файлы из `srcDir` в изображения в `outDir`.
+ * Файлы получают то же базовое имя с расширением формата (`p1.bpmn` → `p1.png`).
+ *
+ * Сгенерированные файлы — артефакты сборки: коммитить их не нужно.
+ * В Confluence они улетают как аттачи на этапе публикации.
+ */
+export async function convertBpmnFolder(opts) {
+    const format = opts.format ?? 'png';
+    const pattern = opts.pattern ?? BPMN_FILE_RE;
+    const files = readdirSync(opts.srcDir).filter((f) => pattern.test(f));
+    if (files.length === 0) {
+        console.log(`[bpmn] no files matching ${pattern} in ${opts.srcDir}`);
+        return [];
+    }
+    const conversions = files.map((f) => ({
+        input: join(opts.srcDir, f),
+        output: join(opts.outDir, bpmnOutputName(f, format)),
+    }));
+    await convertBpmn(conversions);
+    return conversions;
+}

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 export { ConfluenceClient, ConfluenceApiError, type ConfluencePage, type ConfluencePageStorage, type ConfluenceAttachment, type ConfluenceLabel, type AttachmentVersionData, type CreatePageOptions, } from './client/client.js';
 export { authHeader, loadConfigFromEnv, type ConfluenceAuthType, type ConfluenceConfig, type LoadConfigOptions, } from './client/config.js';
 export { Markdown } from './markdown/markdown.js';
-export { renderToStorage, extractPlaceholders, MissingAttachmentUrlError, PLACEHOLDER_RE, type AttachmentUrls, type ExtractedPlaceholders, } from './markdown/render.js';
+export { renderToStorage, extractPlaceholders, renameImagePlaceholders, MissingAttachmentUrlError, PLACEHOLDER_RE, type AttachmentUrls, type ExtractedPlaceholders, } from './markdown/render.js';
 export { validateMarkdown, MarkdownValidationError, type ValidateOptions } from './markdown/validate.js';
 export * from './macros/index.js';
+export { convertBpmn, convertBpmnFolder, isBpmnFile, bpmnOutputName, BPMN_FILE_RE, type BpmnConversion, type BpmnImageFormat, type ConvertBpmnFolderOptions, } from './bpmn/convert.js';
 export { fileSha256, HASH_TAG_PREFIX } from './attachments/hash.js';
 export { Attachment, AttachmentService, toAttachmentVersion, SRC_SHA_SIDECAR_SUFFIX, type AttachmentVersion, type EnsuredAttachment, } from './attachments/attachment.js';
 export { Page, Table } from './pages/page.js';

package/dist/index.js

@@ -3,10 +3,12 @@ export { ConfluenceClient, ConfluenceApiError, } from './client/client.js';
 export { authHeader, loadConfigFromEnv, } from './client/config.js';
 // Markdown
 export { Markdown } from './markdown/markdown.js';
-export { renderToStorage, extractPlaceholders, MissingAttachmentUrlError, PLACEHOLDER_RE, } from './markdown/render.js';
+export { renderToStorage, extractPlaceholders, renameImagePlaceholders, MissingAttachmentUrlError, PLACEHOLDER_RE, } from './markdown/render.js';
 export { validateMarkdown, MarkdownValidationError } from './markdown/validate.js';
 // Macros (pluggable)
 export * from './macros/index.js';
+// BPMN (optional peer dep 'bpmn-to-image' is loaded lazily on use)
+export { convertBpmn, convertBpmnFolder, isBpmnFile, bpmnOutputName, BPMN_FILE_RE, } from './bpmn/convert.js';
 // Attachments
 export { fileSha256, HASH_TAG_PREFIX } from './attachments/hash.js';
 export { Attachment, AttachmentService, toAttachmentVersion, SRC_SHA_SIDECAR_SUFFIX, } from './attachments/attachment.js';

package/dist/markdown/render.d.ts

@@ -4,6 +4,12 @@ export interface ExtractedPlaceholders {
     files: string[];
 }
 export declare function extractPlaceholders(markdown: string): ExtractedPlaceholders;
+/**
+ * Переименовывает `{{img:...}}`-плейсхолдеры по карте старое→новое имя.
+ * Используется BPMN-конвейером: автор пишет `{{img:p1.bpmn}}`, публикация
+ * подменяет на `{{img:p1.png}}` после конвертации диаграммы.
+ */
+export declare function renameImagePlaceholders(markdown: string, renames: Map<string, string>): string;
 export interface AttachmentUrls {
     /** filename → абсолютный URL аттача, полученный из Confluence после аплоада. */
     images: Map<string, string>;

package/dist/markdown/render.js

@@ -34,6 +34,19 @@ function escapeXmlAttr(s) {
         }
     });
 }
+/**
+ * Переименовывает `{{img:...}}`-плейсхолдеры по карте старое→новое имя.
+ * Используется BPMN-конвейером: автор пишет `{{img:p1.bpmn}}`, публикация
+ * подменяет на `{{img:p1.png}}` после конвертации диаграммы.
+ */
+export function renameImagePlaceholders(markdown, renames) {
+    if (renames.size === 0)
+        return markdown;
+    return markdown.replace(/\{\{img:([^}]+)\}\}/g, (full, rawName) => {
+        const renamed = renames.get(rawName.trim());
+        return renamed ? `{{img:${renamed}}}` : full;
+    });
+}
 export class MissingAttachmentUrlError extends Error {
     constructor(message) {
         super(message);

package/dist/publish/publish.d.ts

@@ -37,6 +37,12 @@ export interface PublishPageOptions {
     versionMessage?: string;
     /** Свой реестр макросов (default: встроенные core + table-filter). */
     registry?: MacroRegistry;
+    /**
+     * Каталог для PNG, сгенерированных из `*.bpmn` в images[].
+     * Default: временный каталог на каждый запуск — дедуп аттачей всё равно
+     * идёт по SHA-256 исходного BPMN через sidecar, лишних версий не будет.
+     */
+    bpmnOutDir?: string;
     /**
      * Ключ content property для хранения content-hash.
      * Default: 'confluence-md-sync-content-hash'.

package/dist/publish/publish.js

@@ -1,8 +1,11 @@
-import { readFileSync } from 'node:fs';
+import { mkdtempSync, readFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
 import { ConfluenceClient } from '../client/client.js';
 import { AttachmentService } from '../attachments/attachment.js';
-import { renderToStorage } from '../markdown/render.js';
+import { bpmnOutputName, convertBpmn, isBpmnFile } from '../bpmn/convert.js';
+import { renameImagePlaceholders, renderToStorage } from '../markdown/render.js';
 import { validateMarkdown } from '../markdown/validate.js';
 import { processMacros } from '../macros/registry.js';
 import { defaultMacroRegistry } from '../macros/index.js';
@@ -60,11 +63,29 @@ export async function publishPage(opts, cfg) {
     else {
         throw new Error('publishPage: either markdownPath or markdown must be provided');
     }
-    const images = opts.images ?? [];
+    let images = opts.images ?? [];
     const files = opts.files ?? [];
     const tables = opts.tables ?? [];
     const registry = opts.registry ?? defaultMacroRegistry;
     const hashKey = opts.hashPropertyKey ?? DEFAULT_HASH_PROPERTY_KEY;
+    // 0. BPMN из коробки: *.bpmn в images[] конвертируются в PNG, а
+    //    {{img:p1.bpmn}} в markdown подменяется на {{img:p1.png}} ДО валидации.
+    //    Сама конвертация (puppeteer) — после валидации, чтобы падать быстро.
+    const bpmnConversions = [];
+    const bpmnInputs = images.filter(isBpmnFile);
+    if (bpmnInputs.length > 0) {
+        const outDir = opts.bpmnOutDir ?? mkdtempSync(join(tmpdir(), 'confluence-md-sync-bpmn-'));
+        const renames = new Map();
+        const outputByInput = new Map();
+        for (const input of bpmnInputs) {
+            const output = join(outDir, bpmnOutputName(input));
+            bpmnConversions.push({ input, output });
+            outputByInput.set(input, output);
+            renames.set(basename(input), basename(output));
+        }
+        images = images.map((p) => outputByInput.get(p) ?? p);
+        markdown = renameImagePlaceholders(markdown, renames);
+    }
     validateMarkdown({
         markdown,
         imagePaths: images,
@@ -77,6 +98,11 @@ export async function publishPage(opts, cfg) {
         const tableMarkdown = table.markdown instanceof Markdown ? table.markdown.toString() : table.markdown;
         markdown = markdown.replace(new RegExp(`\\{\\{table:${escapeRegex(table.name)}\\}\\}`, 'g'), () => tableMarkdown);
     }
+    // Конвертация диаграмм — до аплоада; в dry-run пропускается (аттачи всё
+    // равно не загружаются, URL подставляются фиктивные).
+    if (bpmnConversions.length > 0 && !opts.dryRun) {
+        await convertBpmn(bpmnConversions);
+    }
     const client = new ConfluenceClient(cfg);
     const attachmentSvc = new AttachmentService(client);
     const { pageId, created } = await resolvePage(client, opts);
@@ -89,9 +115,9 @@ export async function publishPage(opts, cfg) {
         // В dry-run не трогаем Confluence — подставляем фиктивные URL, чтобы
         // рендер и валидация плейсхолдеров отработали полностью.
         for (const p of images)
-            urls.images.set(basenameOf(p), `dry-run://img/${basenameOf(p)}`);
+            urls.images.set(basename(p), `dry-run://img/${basename(p)}`);
         for (const p of files)
-            urls.files.set(basenameOf(p), `dry-run://file/${basenameOf(p)}`);
+            urls.files.set(basename(p), `dry-run://file/${basename(p)}`);
     }
     else {
         for (const p of images) {
@@ -155,10 +181,6 @@ export async function publishPage(opts, cfg) {
     console.log(`[publish] ${pageId} "${title}" → v${nextVersion} (hash ${newHash.slice(0, 12)})`);
     return { pageId, title, version: nextVersion, attachments, updated: true, created, storage };
 }
-function basenameOf(p) {
-    const idx = Math.max(p.lastIndexOf('/'), p.lastIndexOf('\\'));
-    return idx === -1 ? p : p.slice(idx + 1);
-}
 function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "confluence-md-sync",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Publish Markdown to Confluence (Data Center & Cloud): idempotent page sync, attachment dedup, tables and a pluggable macro system",
   "keywords": [
     "confluence",
@@ -63,7 +63,20 @@
   "devDependencies": {
     "@types/markdown-it": "^14.1.2",
     "@types/node": "^20.14.0",
+    "bpmn-to-image": "^0.7.0",
+    "puppeteer": "^24.43.1",
     "typescript": "^5.6.0",
     "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "bpmn-to-image": ">=0.7.0"
+  },
+  "peerDependenciesMeta": {
+    "bpmn-to-image": {
+      "optional": true
+    }
+  },
+  "overrides": {
+    "puppeteer": "$puppeteer"
   }
 }