confluence-md-sync 0.5.1 → 0.6.0

package/README.md

@@ -18,6 +18,10 @@ npm install -g confluence-md-sync       # as a CLI: `confluence-md-sync …`
 
 - **No history spam** — rendered content is SHA-256-hashed into a content
   property; identical re-publish skips the update, page version doesn't grow.
+- **Drift-proof** — the content property also stores the page version we last
+  wrote. If someone edits or wipes the page in Confluence, the version diverges
+  and the next publish detects the drift and restores the page from markdown
+  (git stays the source of truth) instead of trusting the stale hash.
 - **Attachment dedup** — uploads are tagged `sha256:<hash>`; unchanged files
   are reused. `<file>.src-sha256` sidecars pin dedup to the *source* of
   non-deterministic artifacts (e.g. PNGs rendered by a headless browser).

package/dist/client/client.d.ts

@@ -73,12 +73,13 @@ export declare class ConfluenceClient {
     /** Finds a page by space key and exact title. Returns null if not found. */
     getPageByTitle(spaceKey: string, title: string): Promise<ConfluencePage | null>;
     createPage(opts: CreatePageOptions): Promise<ConfluencePage>;
+    /** Обновляет страницу и возвращает номер версии из ответа Confluence. */
     updatePage(pageId: string, body: {
         title: string;
         version: number;
         storage: string;
         versionMessage?: string;
-    }): Promise<void>;
+    }): Promise<number>;
     deletePage(pageId: string): Promise<void>;
     /** Direct child pages of a page. */
     getChildPages(pageId: string, limit?: number): Promise<ConfluencePage[]>;

package/dist/client/client.js

@@ -99,6 +99,7 @@ export class ConfluenceClient {
             await this.parseError(res, `createPage(${opts.spaceKey}/${opts.title})`);
         return (await res.json());
     }
+    /** Обновляет страницу и возвращает номер версии из ответа Confluence. */
     async updatePage(pageId, body) {
         const version = { number: body.version };
         if (body.versionMessage)
@@ -118,6 +119,10 @@ export class ConfluenceClient {
         });
         if (!res.ok)
             await this.parseError(res, `updatePage(${pageId})`);
+        // Confluence возвращает обновлённый content с актуальным version.number.
+        // Если тела/поля нет — падаем обратно на посланную версию.
+        const data = (await res.json().catch(() => null));
+        return data?.version?.number ?? body.version;
     }
     async deletePage(pageId) {
         const res = await fetch(this.url(`/rest/api/content/${pageId}`), {

package/dist/export/to-markdown.js

@@ -630,10 +630,11 @@ class Converter {
         let headerCount = 0;
         while (headerCount < grid.length && headerFlags[headerCount])
             headerCount++;
-        if (headerCount === 0)
-            headerCount = 1; // нет <th>-шапки → первая строка как ключи
-        if (headerCount >= grid.length)
-            headerCount = 1; // не съедать всю таблицу
+        // Нет <th>-шапки (или вся таблица — заголовки): в записи разворачивать
+        // нечего — первая строка данных стала бы «ключами» (в т.ч. картинка →
+        // ключ `**<img …>:**`). Такую таблицу отдаём как GFM.
+        if (headerCount === 0 || headerCount >= grid.length)
+            return this.readableTable(table);
         const header = grid[headerCount - 1];
         const titleCells = grid
             .slice(0, headerCount - 1)

package/dist/publish/publish.js

@@ -28,15 +28,19 @@ export function computeContentHash(storage) {
     const canonical = storage.replace(/(\/download\/attachments\/[^"?\s]+)\?[^"\s]*/g, '$1');
     return createHash('sha256').update(canonical, 'utf-8').digest('hex');
 }
-// Схема записи download-URL в body. Схема 1 подставляла URL из
+// Схема content property. Схема 1 подставляла в body download-URL из
 // _links.download как есть — с ?version=N&modificationDate=…; при ребампе
 // аттача без изменения текста страница оставалась UNCHANGED и продолжала
 // отдавать старую, пиненную версию картинки. Схема 2 подставляет
 // канонический URL без query — Confluence по нему отдаёт последнюю версию
-// аттача, и обновление диаграммы видно без переписывания body. Property со
-// схемой ≠ текущей (в т.ч. без поля scheme) считается устаревшей — страница
-// один раз переписывается каноническими URL.
-const HASH_SCHEME = 2;
+// аттача, и обновление диаграммы видно без переписывания body. Схема 3
+// добавляет pageVersion — номер версии страницы после нашей последней
+// записи; по нему детектится «дрейф» (страницу правили мимо публикатора:
+// version.number вырос, а hash-свойство осталось прежним → без этой проверки
+// испорченная страница никогда бы не восстановилась из markdown). Property со
+// схемой ≠ текущей (в т.ч. без поля scheme/pageVersion) считается устаревшей —
+// hash не сверяется, страница один раз переписывается в новом формате.
+const HASH_SCHEME = 3;
 /** Канонический download-URL аттача: без query (?version=N&…). */
 function canonicalDownloadUrl(url) {
     return url.split('?')[0];
@@ -203,42 +207,71 @@ export async function publishPage(opts, cfg) {
             storage,
         };
     }
-    // 3. Content-hash check. Hash хранится в content property, не в body.
+    // 3. Решение о публикации. Hash и версия нашей последней записи хранятся в
+    //    content property (не в body — normalize storage её бы съел). Страница
+    //    и её версия так и так читаются перед сравнением. Причина публикации
+    //    (для диагностики инцидентов пишется в лог):
+    //      no-property   — свойства нет (мы эту страницу ещё не публиковали);
+    //      hash-mismatch — контент изменился (или свойство устаревшей схемы);
+    //      title-change  — сменился заголовок при том же контенте;
+    //      drift         — страницу правили мимо публикатора (version.number
+    //                      разошёлся с записанным нами) → чиним из markdown.
     const newHash = computeContentHash(storage);
     const [existing, hashProp] = await Promise.all([
         client.getPageStorage(pageId),
         client.getContentProperty(pageId, hashKey),
     ]);
     const title = opts.title ?? existing.title;
-    // Property, писанная другой схемой (или до появления scheme), не считается
-    // совпадением: body мог быть записан с пином версий аттачей — его нужно
-    // один раз переписать каноническими URL.
+    // Только свойство текущей схемы несёт доверенные hash + pageVersion.
+    // Устаревшая схема (или без scheme) — «версия неизвестна»: hash не сверяем
+    // (existingHash = null → одна принудительная публикация с записью нового
+    // формата; она же самовосстанавливает ранее испорченные страницы).
     const propValue = hashProp && typeof hashProp.value === 'object' && hashProp.value !== null
         ? hashProp.value
         : null;
-    const existingHash = propValue && propValue.scheme === HASH_SCHEME
+    const isCurrentScheme = propValue !== null && propValue.scheme === HASH_SCHEME;
+    const existingHash = isCurrentScheme
         ? (propValue.hash ?? null)
         : null;
-    if (existingHash === newHash && title === existing.title) {
+    const publishedVersion = isCurrentScheme && typeof propValue.pageVersion === 'number'
+        ? propValue.pageVersion
+        : null;
+    let reason;
+    if (propValue === null)
+        reason = 'no-property';
+    else if (existingHash !== newHash)
+        reason = 'hash-mismatch';
+    else if (title !== existing.title)
+        reason = 'title-change';
+    else if (publishedVersion !== existing.version)
+        reason = 'drift';
+    else
+        reason = null;
+    if (reason === null) {
         console.log(`[publish] ${pageId} "${title}" → UNCHANGED (hash ${newHash.slice(0, 12)}, v${existing.version})`);
         if (opts.labels?.length)
             await client.addLabels(pageId, opts.labels);
         return { pageId, title, version: existing.version, attachments, updated: false, created, storage };
     }
     // 4. Обновление страницы — только после успешного аплоада всех аттачей.
-    const nextVersion = existing.version + 1;
-    await client.updatePage(pageId, {
+    //    Версию берём из ответа Confluence (update инкрементирует её сам).
+    const nextVersion = await client.updatePage(pageId, {
         title,
-        version: nextVersion,
+        version: existing.version + 1,
         storage,
         versionMessage: opts.versionMessage,
     });
-    // 5. Запись/обновление content property с новым hash. Делаем ПОСЛЕ
-    //    updatePage чтобы при сбое publish hash не «опередил» реальное содержимое.
-    await client.setContentProperty(pageId, hashKey, { hash: newHash, scheme: HASH_SCHEME }, hashProp ? hashProp.version : null);
+    // 5. Запись/обновление content property: hash + версия, которая ПОЛУЧИЛАСЬ
+    //    после нашей записи. Делаем ПОСЛЕ updatePage, чтобы при сбое publish
+    //    свойство не «опередило» реальное содержимое. pageVersion закрывает
+    //    слепую зону дрейфа (см. HASH_SCHEME).
+    await client.setContentProperty(pageId, hashKey, { hash: newHash, scheme: HASH_SCHEME, pageVersion: nextVersion }, 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)})`);
+    const detail = reason === 'drift'
+        ? `DRIFT (page v${existing.version} != published v${publishedVersion})`
+        : reason;
+    console.log(`[publish] ${pageId} "${title}" → ${detail} → v${nextVersion} (hash ${newHash.slice(0, 12)})`);
     return { pageId, title, version: nextVersion, attachments, updated: true, created, storage };
 }
 function escapeRegex(s) {

package/package.json

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