confluence-md-sync 0.5.2 → 0.7.0

package/README.md

@@ -18,9 +18,16 @@ 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).
+- **Managed-page banner** — optionally stamp a “edit this in <source>” notice
+  (info/warning panel with a link) into the page; injected into storage only,
+  never into the markdown source. See *Managed-page banner*.
 - **Fail before write** — placeholders, files and macro markers are validated
   up front; Confluence is never touched on a broken input.
 - **Pluggable macros** — built-in `core` + `table-filter` plugins, extend
@@ -117,6 +124,34 @@ await publishPage({
 }, cfg);
 ```
 
+### Managed-page banner
+
+When a page is generated from an external source (e.g. docs-studio) and users
+should not edit it in Confluence, add a `managedNotice`. It is injected into the
+**storage** at publish time — never into the markdown source, so export and
+round-trip stay clean, and git remains the single source of truth. The banner is
+deterministic (fixed macro id), so it doesn't break the no-history-spam hash skip.
+
+```ts
+await publishPage({
+  pageId,
+  markdownPath,
+  managedNotice: {
+    linkUrl: 'https://studio.example/doc/123',  // required
+    // everything below is optional:
+    linkText: 'постановка в docs-studio',       // default: 'docs-studio'
+    text: 'Правьте страницу в {link}. Здесь только чтение — правки будут перезаписаны.',
+    panel: 'warning',                           // info | note | warning | tip (default: info)
+    position: 'top',                            // 'top' (default) | 'bottom'
+  },
+}, cfg);
+```
+
+`{link}` in `text` is replaced by the link; omit it and the link is appended.
+The presence of `managedNotice` turns the banner on — leave it out and no notice
+is added. To apply one banner to every page of a CI plan, pass `managedNotice`
+to `runPublish(dir, plan, { managedNotice })`; a per-page value overrides it.
+
 ## BPMN diagrams out of the box
 
 Pass a `.bpmn` file as an image (a path or an `http(s)` URL) — it is

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/index.d.ts

@@ -10,6 +10,7 @@ export { Attachment, AttachmentService, toAttachmentVersion, SRC_SHA_SIDECAR_SUF
 export { Page, Table } from './pages/page.js';
 export { readTableFromConfluence, findTable, findTableInMacro, parseHtmlTable, decodeHtmlCell, renderMarkdownTable, escapeMdTableCell, readAndMapTable, type ColumnAlign, type TableColumn, } from './pages/tables.js';
 export { publishPage, computeContentHash, DEFAULT_HASH_PROPERTY_KEY, type PublishPageOptions, type PublishPageResult, type TableData, } from './publish/publish.js';
+export { buildManagedNotice, applyManagedNotice, DEFAULT_MANAGED_NOTICE_TEXT, DEFAULT_MANAGED_NOTICE_LINK_TEXT, type ManagedNoticeOptions, } from './publish/notice.js';
 export { isHttpUrl, remoteFilename, isSameConfluenceOrigin, remoteRequestHeaders, downloadToFile, } from './publish/remote.js';
 export { runPublish, type Here, type Build, type PublishPlan, type RunPublishOptions, } from './publish/runner.js';
 export { parseStorage, serializeStorage, decodeEntities, StorageParseError, type XNode, type XElement, } from './export/xhtml.js';

package/dist/index.js

@@ -17,6 +17,7 @@ export { Page, Table } from './pages/page.js';
 export { readTableFromConfluence, findTable, findTableInMacro, parseHtmlTable, decodeHtmlCell, renderMarkdownTable, escapeMdTableCell, readAndMapTable, } from './pages/tables.js';
 // Publish
 export { publishPage, computeContentHash, DEFAULT_HASH_PROPERTY_KEY, } from './publish/publish.js';
+export { buildManagedNotice, applyManagedNotice, DEFAULT_MANAGED_NOTICE_TEXT, DEFAULT_MANAGED_NOTICE_LINK_TEXT, } from './publish/notice.js';
 export { isHttpUrl, remoteFilename, isSameConfluenceOrigin, remoteRequestHeaders, downloadToFile, } from './publish/remote.js';
 export { runPublish, } from './publish/runner.js';
 // Export (storage → markdown) & round-trip

package/dist/publish/notice.d.ts

@@ -0,0 +1,34 @@
+/**
+ * «Баннер управляемой страницы»: примечание о том, что страница ведётся во
+ * внешнем источнике (docs-studio), а правки в самой Confluence будут
+ * перезаписаны. Вставляется в storage при публикации, но НЕ в markdown-
+ * источник — round-trip/экспорт его не увидят, git остаётся чистым.
+ */
+export interface ManagedNoticeOptions {
+    /**
+     * URL источника (docs-studio / репозиторий постановки), куда ведёт ссылка.
+     * Обязателен — без него примечание не имеет смысла.
+     */
+    linkUrl: string;
+    /** Текст ссылки. Default: {@link DEFAULT_MANAGED_NOTICE_LINK_TEXT}. */
+    linkText?: string;
+    /**
+     * Текст примечания. Плейсхолдер `{link}` заменяется ссылкой; если его в
+     * тексте нет, ссылка добавляется в конец. Default:
+     * {@link DEFAULT_MANAGED_NOTICE_TEXT}.
+     */
+    text?: string;
+    /** Куда вставлять баннер: 'top' (шапка) или 'bottom' (низ). Default: 'top'. */
+    position?: 'top' | 'bottom';
+    /**
+     * Тип панели Confluence (влияет на цвет/иконку). Default: 'info'.
+     * 'warning' — красная, самый заметный вариант для «не редактировать».
+     */
+    panel?: 'info' | 'note' | 'warning' | 'tip';
+}
+export declare const DEFAULT_MANAGED_NOTICE_TEXT: string;
+export declare const DEFAULT_MANAGED_NOTICE_LINK_TEXT = "docs-studio";
+/** Строит storage-разметку баннера (одиночный `<ac:structured-macro>`). */
+export declare function buildManagedNotice(opts: ManagedNoticeOptions): string;
+/** Дописывает баннер в начало (top) или конец (bottom) storage-контента. */
+export declare function applyManagedNotice(storage: string, opts: ManagedNoticeOptions): string;

package/dist/publish/notice.js

@@ -0,0 +1,37 @@
+/**
+ * «Баннер управляемой страницы»: примечание о том, что страница ведётся во
+ * внешнем источнике (docs-studio), а правки в самой Confluence будут
+ * перезаписаны. Вставляется в storage при публикации, но НЕ в markdown-
+ * источник — round-trip/экспорт его не увидят, git остаётся чистым.
+ */
+import { structuredMacro } from '../macros/xml.js';
+import { escapeXmlAttr } from '../macros/xml.js';
+export const DEFAULT_MANAGED_NOTICE_TEXT = 'Страница синхронизируется автоматически. Вносите правки в источнике ({link}) — ' +
+    'ручные изменения на этой странице будут перезаписаны при следующей публикации.';
+export const DEFAULT_MANAGED_NOTICE_LINK_TEXT = 'docs-studio';
+// Фиксированный ac:macro-id: баннер обязан давать БАЙТ-В-БАЙТ одинаковый
+// storage при каждой публикации. Со случайным id (generateMacroId) content-
+// hash менялся бы каждый раз → страница вечно считалась бы изменённой.
+const NOTICE_MACRO_ID = '0f0e0d0c-0b0a-4009-8008-000000000001';
+/** Собирает `<a href>`-ссылку на источник. */
+function noticeLink(opts) {
+    const text = opts.linkText ?? DEFAULT_MANAGED_NOTICE_LINK_TEXT;
+    return `<a href="${escapeXmlAttr(opts.linkUrl)}">${escapeXmlAttr(text)}</a>`;
+}
+/** Строит storage-разметку баннера (одиночный `<ac:structured-macro>`). */
+export function buildManagedNotice(opts) {
+    if (!opts.linkUrl)
+        throw new Error('managedNotice: linkUrl is required');
+    const panel = opts.panel ?? 'info';
+    const link = noticeLink(opts);
+    const text = opts.text ?? DEFAULT_MANAGED_NOTICE_TEXT;
+    const inner = text.includes('{link}')
+        ? text.split('{link}').map(escapeXmlAttr).join(link)
+        : `${escapeXmlAttr(text)} ${link}`;
+    return structuredMacro(panel, NOTICE_MACRO_ID, { richBody: `<p>${inner}</p>` });
+}
+/** Дописывает баннер в начало (top) или конец (bottom) storage-контента. */
+export function applyManagedNotice(storage, opts) {
+    const notice = buildManagedNotice(opts);
+    return (opts.position ?? 'top') === 'bottom' ? `${storage}${notice}` : `${notice}${storage}`;
+}

package/dist/publish/publish.d.ts

@@ -1,5 +1,6 @@
 import type { ConfluenceConfig } from '../client/config.js';
 import { type RenderStorageOptions } from '../markdown/render.js';
+import { type ManagedNoticeOptions } from './notice.js';
 import type { MacroRegistry } from '../macros/registry.js';
 import { Markdown } from '../markdown/markdown.js';
 export interface TableData {
@@ -42,6 +43,13 @@ export interface PublishPageOptions {
     labels?: string[];
     /** Комментарий к версии страницы. */
     versionMessage?: string;
+    /**
+     * Примечание «страница управляется извне» (docs-studio). Вставляется в
+     * storage при публикации, НО не в markdown-источник — экспорт/round-trip
+     * его не увидят. Наличие опции включает баннер; настраиваются текст, ссылка,
+     * её текст, тип панели и позиция (шапка/низ). См. {@link ManagedNoticeOptions}.
+     */
+    managedNotice?: ManagedNoticeOptions;
     /** Свой реестр макросов (default: встроенные core + table-filter). */
     registry?: MacroRegistry;
     /**

package/dist/publish/publish.js

@@ -8,6 +8,7 @@ import { bpmnOutputName, convertBpmn, isBpmnFile } from '../bpmn/convert.js';
 import { downloadToFile, isHttpUrl, remoteFilename } from './remote.js';
 import { renameImagePlaceholders, renderToStorage, } from '../markdown/render.js';
 import { validateMarkdown } from '../markdown/validate.js';
+import { applyManagedNotice } from './notice.js';
 import { processMacros } from '../macros/registry.js';
 import { defaultMacroRegistry } from '../macros/index.js';
 import { Markdown } from '../markdown/markdown.js';
@@ -28,15 +29,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];
@@ -81,6 +86,10 @@ export async function publishPage(opts, cfg) {
     const tables = opts.tables ?? [];
     const registry = opts.registry ?? defaultMacroRegistry;
     const hashKey = opts.hashPropertyKey ?? DEFAULT_HASH_PROPERTY_KEY;
+    // Fail fast: баннер без ссылки бессмыслен — падаем до любого сетевого I/O.
+    if (opts.managedNotice && !opts.managedNotice.linkUrl) {
+        throw new Error('publishPage: managedNotice.linkUrl is required');
+    }
     // 0a. Удалённые источники: http(s)://-элементы в images[]/files[]
     //     заменяются на локальный путь в downloadDir с именем из URL — дальше
     //     конвейер (валидация, BPMN, аплоад) работает с обычными путями.
@@ -191,6 +200,13 @@ export async function publishPage(opts, cfg) {
     let storage = renderToStorage(markdown, urls, opts.render ?? {});
     // 2.5. Преобразование маркеров макросов в XHTML.
     storage = processMacros(storage, registry).toString();
+    // 2.6. Баннер «страница управляется извне». Вставляется здесь, в storage —
+    //   не в markdown — поэтому источник/round-trip его не содержат. Баннер
+    //   детерминирован (фиксированный macro-id), значит попадает в content-hash
+    //   стабильно и не ломает идемпотентность.
+    if (opts.managedNotice) {
+        storage = applyManagedNotice(storage, opts.managedNotice);
+    }
     if (opts.dryRun) {
         console.log(`[publish] dry-run: page ${pageId} rendered OK (${storage.length} bytes of storage)`);
         return {
@@ -203,42 +219,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/dist/publish/runner.d.ts

@@ -1,4 +1,5 @@
 import { type PublishPageOptions, type PublishPageResult } from './publish.js';
+import type { ManagedNoticeOptions } from './notice.js';
 import { type ConfluenceConfig, type LoadConfigOptions } from '../client/config.js';
 export type Here = (relativePath: string) => string;
 export type Build = (relativePath: string) => string;
@@ -14,6 +15,12 @@ export interface RunPublishOptions {
      * соответствует компоновке репо `<repo>/docs/<set>` + `<repo>/build/<set>`.
      */
     buildDir?: string;
+    /**
+     * Баннер «страница управляется извне» по умолчанию для ВСЕХ страниц прогона
+     * (docs-studio). Значение, заданное у конкретной страницы в `managedNotice`,
+     * имеет приоритет. См. {@link ManagedNoticeOptions}.
+     */
+    managedNotice?: ManagedNoticeOptions;
 }
 /**
  * Минимальная точка входа для публикующего скрипта (`docs/<set>/publish.ts`).

package/dist/publish/runner.js

@@ -29,7 +29,11 @@ export async function runPublish(baseDir, plan, opts = {}) {
         const pages = typeof plan === 'function' ? await plan(here, build) : plan;
         const results = [];
         for (const page of pages) {
-            results.push(await publishPage(page, cfg));
+            // Дефолтный баннер прогона применяется, только если страница его не задала.
+            const merged = opts.managedNotice && page.managedNotice === undefined
+                ? { ...page, managedNotice: opts.managedNotice }
+                : page;
+            results.push(await publishPage(merged, cfg));
         }
         return results;
     }

package/package.json

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