confluence-md-sync 0.2.0 → 0.2.1

package/README.md

@@ -48,10 +48,11 @@ Markdown + three placeholder kinds:
 ```markdown
 # Отчёт за месяц
 
-{{img:flow.png}}          <!-- inline image from images[] -->
+{{img:chart.png}}            <!-- inline image from images[] -->
+{{img:flow.bpmn}}            <!-- BPMN diagram — rendered to PNG automatically -->
 Исходник: {{file:data.csv}}  <!-- attachment link from files[] -->
 
-{{table:summary}}         <!-- table injected from tables[] -->
+{{table:summary}}            <!-- table injected from tables[] -->
 ```
 
 ```ts
@@ -66,7 +67,10 @@ const summary = renderMarkdownTable(rows, [
 await publishPage({
   pageId: '123456789',
   markdownPath: 'docs/report.md',
-  images: ['build/flow.png'],
+  images: [
+    'build/chart.png',
+    'docs/flow.bpmn',   // converted to flow.png on the fly (see BPMN section)
+  ],
   files: ['build/data.csv'],
   tables: [{
     name: 'summary',
@@ -99,19 +103,29 @@ await publishPage({ pageId, markdown: '# Generated\n\ntext' }, cfg);
 
 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):
+an optional peer dependency).
+
+Setup — install the converter **and** force a current puppeteer:
 
 ```bash
-npm install -D bpmn-to-image
+npm install -D bpmn-to-image puppeteer
 ```
 
-> 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" }
-> ```
+```jsonc
+// package.json — required: bpmn-to-image pins puppeteer 21, whose bundled
+// Chromium fails to launch on recent OSes ("socket hang up"). The override
+// must reference the direct dependency ("$puppeteer"), otherwise `npm ci`
+// fails with "Override for puppeteer conflicts with direct dependency".
+{
+  "devDependencies": {
+    "bpmn-to-image": "^0.7.0",
+    "puppeteer": "^24.0.0"
+  },
+  "overrides": {
+    "puppeteer": "$puppeteer"
+  }
+}
+```
 
 ```markdown
 Процесс выпуска релиза:

package/dist/publish/publish.js

@@ -20,14 +20,26 @@ import { Markdown } from '../markdown/markdown.js';
 export const DEFAULT_HASH_PROPERTY_KEY = 'confluence-md-sync-content-hash';
 export function computeContentHash(storage) {
     // Перед хешированием вычищаем query (?version=N&modificationDate=…) из
-    // attachment download-URL'ов. Иначе любой ребамп аттача (новая версия
-    // от не-детерминированной генерации картинок → новый SHA → новый
-    // version N в URL) ломал бы hash страницы, хотя тело логически
-    // не изменилось — Confluence сам отдаст последнюю версию аттача по
-    // base-URL без query.
+    // attachment download-URL'ов — защита для storage, писанного схемой 1
+    // (см. HASH_SCHEME): там в body лежали URL с пином версии. Начиная со
+    // схемы 2 в body подставляются канонические URL без query, и replace —
+    // no-op.
     const canonical = storage.replace(/(\/download\/attachments\/[^"?\s]+)\?[^"\s]*/g, '$1');
     return createHash('sha256').update(canonical, 'utf-8').digest('hex');
 }
+// Схема записи download-URL в body. Схема 1 подставляла URL из
+// _links.download как есть — с ?version=N&modificationDate=…; при ребампе
+// аттача без изменения текста страница оставалась UNCHANGED и продолжала
+// отдавать старую, пиненную версию картинки. Схема 2 подставляет
+// канонический URL без query — Confluence по нему отдаёт последнюю версию
+// аттача, и обновление диаграммы видно без переписывания body. Property со
+// схемой ≠ текущей (в т.ч. без поля scheme) считается устаревшей — страница
+// один раз переписывается каноническими URL.
+const HASH_SCHEME = 2;
+/** Канонический download-URL аттача: без query (?version=N&…). */
+function canonicalDownloadUrl(url) {
+    return url.split('?')[0];
+}
 async function resolvePage(client, opts) {
     if (opts.pageId)
         return { pageId: opts.pageId, created: false };
@@ -120,15 +132,18 @@ export async function publishPage(opts, cfg) {
             urls.files.set(basename(p), `dry-run://file/${basename(p)}`);
     }
     else {
+        // В body уходит канонический URL без query (см. HASH_SCHEME) — страница
+        // всегда отдаёт последнюю версию аттача. Полный URL с версией остаётся
+        // в результате для caller'а.
         for (const p of images) {
             const r = await attachmentSvc.ensure(pageId, p);
-            urls.images.set(r.filename, r.downloadUrl);
+            urls.images.set(r.filename, canonicalDownloadUrl(r.downloadUrl));
             attachments.push({ filename: r.filename, id: r.id, reused: r.reused, url: r.downloadUrl });
             console.log(`[attachment] ${r.filename}: ${r.reused ? 'reused' : 'uploaded'} (id=${r.id})`);
         }
         for (const p of files) {
             const r = await attachmentSvc.ensure(pageId, p);
-            urls.files.set(r.filename, r.downloadUrl);
+            urls.files.set(r.filename, canonicalDownloadUrl(r.downloadUrl));
             attachments.push({ filename: r.filename, id: r.id, reused: r.reused, url: r.downloadUrl });
             console.log(`[attachment] ${r.filename}: ${r.reused ? 'reused' : 'uploaded'} (id=${r.id})`);
         }
@@ -156,8 +171,14 @@ export async function publishPage(opts, cfg) {
         client.getContentProperty(pageId, hashKey),
     ]);
     const title = opts.title ?? existing.title;
-    const existingHash = hashProp && typeof hashProp.value === 'object' && hashProp.value !== null
-        ? hashProp.value.hash ?? null
+    // Property, писанная другой схемой (или до появления scheme), не считается
+    // совпадением: body мог быть записан с пином версий аттачей — его нужно
+    // один раз переписать каноническими URL.
+    const propValue = hashProp && typeof hashProp.value === 'object' && hashProp.value !== null
+        ? hashProp.value
+        : null;
+    const existingHash = propValue && propValue.scheme === HASH_SCHEME
+        ? (propValue.hash ?? null)
         : null;
     if (existingHash === newHash && title === existing.title) {
         console.log(`[publish] ${pageId} "${title}" → UNCHANGED (hash ${newHash.slice(0, 12)}, v${existing.version})`);
@@ -175,7 +196,7 @@ export async function publishPage(opts, cfg) {
     });
     // 5. Запись/обновление content property с новым hash. Делаем ПОСЛЕ
     //    updatePage чтобы при сбое publish hash не «опередил» реальное содержимое.
-    await client.setContentProperty(pageId, hashKey, { hash: newHash }, hashProp ? hashProp.version : null);
+    await client.setContentProperty(pageId, hashKey, { hash: newHash, scheme: HASH_SCHEME }, hashProp ? hashProp.version : null);
     if (opts.labels?.length)
         await client.addLabels(pageId, opts.labels);
     console.log(`[publish] ${pageId} "${title}" → v${nextVersion} (hash ${newHash.slice(0, 12)})`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "confluence-md-sync",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Publish Markdown to Confluence (Data Center & Cloud): idempotent page sync, attachment dedup, tables and a pluggable macro system",
   "keywords": [
     "confluence",