confluence-md-sync 0.6.0 → 0.7.0

package/README.md

@@ -25,6 +25,9 @@ npm install -g confluence-md-sync       # as a CLI: `confluence-md-sync …`
 - **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
@@ -121,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/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';
@@ -85,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, аплоад) работает с обычными путями.
@@ -195,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 {

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.6.0",
+  "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",