confluence-md-sync 0.2.0 → 0.3.0

package/dist/markdown/render.js

@@ -2,25 +2,53 @@ import MarkdownIt from 'markdown-it';
 // xhtmlOut: true — Confluence storage format = XHTML, void-элементы
 // (<hr/>, <br/>, <img/>) обязаны быть самозакрывающимися.
 // html: true — разрешить HTML (нужно для <!-- MACRO:... --> комментариев)
-const md = new MarkdownIt({
+const mdOptions = {
     html: true,
     linkify: true,
     typographer: false,
     breaks: false,
     xhtmlOut: true,
-});
-export const PLACEHOLDER_RE = /\{\{(img|file):([^}]+)\}\}/g;
+};
+const md = new MarkdownIt(mdOptions);
+// Вариант без linkify: голые URL в тексте остаются текстом. Используется
+// для страниц из exportPage — иначе round-trip превращал бы нессылочные
+// упоминания URL в <a>.
+const mdNoLinkify = new MarkdownIt({ ...mdOptions, linkify: false });
+/**
+ * Плейсхолдеры: `{{img:name}}`, `{{file:name}}`, `{{page:Title}}`.
+ * После имени допустимы `|key=value`-атрибуты:
+ *   {{img:chart.png|thumbnail=true|height=250}}
+ *   {{page:Другая страница|space=DOCS|text=якорный текст}}
+ */
+export const PLACEHOLDER_RE = /\{\{(img|file|page):([^}]+)\}\}/g;
+/** Разбирает содержимое плейсхолдера: `name|k=v|k2=v2`. */
+export function parsePlaceholder(body) {
+    const parts = body.split('|');
+    const name = parts[0].trim();
+    const attrs = [];
+    for (const part of parts.slice(1)) {
+        const eq = part.indexOf('=');
+        if (eq === -1)
+            attrs.push([part.trim(), '']);
+        else
+            attrs.push([part.slice(0, eq).trim(), part.slice(eq + 1).trim()]);
+    }
+    return { name, attrs };
+}
 export function extractPlaceholders(markdown) {
     const images = new Set();
     const files = new Set();
+    const pages = new Set();
     for (const m of markdown.matchAll(PLACEHOLDER_RE)) {
-        const name = m[2].trim();
+        const { name } = parsePlaceholder(m[2]);
         if (m[1] === 'img')
             images.add(name);
-        else
+        else if (m[1] === 'file')
             files.add(name);
+        else
+            pages.add(name);
     }
-    return { images: [...images], files: [...files] };
+    return { images: [...images], files: [...files], pages: [...pages] };
 }
 function escapeXmlAttr(s) {
     return s.replace(/[<>&"']/g, (c) => {
@@ -42,9 +70,13 @@ function escapeXmlAttr(s) {
 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;
+    return markdown.replace(/\{\{img:([^}]+)\}\}/g, (full, rawBody) => {
+        const { name, attrs } = parsePlaceholder(rawBody);
+        const renamed = renames.get(name);
+        if (!renamed)
+            return full;
+        const attrStr = attrs.map(([k, v]) => `|${k}=${v}`).join('');
+        return `{{img:${renamed}${attrStr}}}`;
     });
 }
 export class MissingAttachmentUrlError extends Error {
@@ -73,17 +105,36 @@ export class MissingAttachmentUrlError extends Error {
  * HTML этой проблемы лишена — `{{img:foo}}` мимо markdown-it проходит
  * посимвольно.
  */
-export function renderToStorage(markdown, urls) {
-    const html = md.render(markdown);
-    return html.replace(PLACEHOLDER_RE, (_full, kind, rawName) => {
-        const name = String(rawName).trim();
+export function renderToStorage(markdown, urls, opts = {}) {
+    const renderer = opts.linkify === false ? mdNoLinkify : md;
+    let html = renderer.render(markdown);
+    // ```confluence-storage — транспорт для дословного XHTML (ac:/ri:-теги
+    // markdown-it сквозь себя не пропускает). Fence рендерится в экранированный
+    // <pre><code>; здесь разэкранируем содержимое обратно в живую разметку.
+    html = html.replace(/<pre><code class="language-confluence-storage">([\s\S]*?)<\/code><\/pre>\n?/g, (_full, escaped) => unescapeHtml(escaped.replace(/\n$/, '')) + '\n');
+    return html.replace(PLACEHOLDER_RE, (_full, kind, rawBody) => {
+        const { name, attrs } = parsePlaceholder(String(rawBody));
+        if (kind === 'page') {
+            return renderPageLink(name, attrs);
+        }
         if (kind === 'img') {
+            if (opts.imageStyle === 'attachment') {
+                const acAttrs = attrs
+                    .map(([k, v]) => ` ac:${k}="${escapeXmlAttr(v)}"`)
+                    .join('');
+                return `<ac:image${acAttrs}><ri:attachment ri:filename="${escapeXmlAttr(name)}" /></ac:image>`;
+            }
             const url = urls.images.get(name);
             if (!url) {
                 throw new MissingAttachmentUrlError(`No uploaded URL for image '${name}' — was it included in publishPage().images and successfully uploaded?`);
             }
             return `<img src="${escapeXmlAttr(url)}" alt="${escapeXmlAttr(name)}" />`;
         }
+        if (opts.fileStyle === 'attachment') {
+            const text = attrs.find(([k]) => k === 'text')?.[1];
+            const body = text !== undefined ? plainTextLinkBody(text) : '';
+            return `<ac:link><ri:attachment ri:filename="${escapeXmlAttr(name)}" />${body}</ac:link>`;
+        }
         const url = urls.files.get(name);
         if (!url) {
             throw new MissingAttachmentUrlError(`No uploaded URL for file '${name}' — was it included in publishPage().files and successfully uploaded?`);
@@ -91,3 +142,22 @@ export function renderToStorage(markdown, urls) {
         return `<a href="${escapeXmlAttr(url)}">${escapeXmlAttr(name)}</a>`;
     });
 }
+function renderPageLink(title, attrs) {
+    const space = attrs.find(([k]) => k === 'space')?.[1];
+    const text = attrs.find(([k]) => k === 'text')?.[1];
+    const spaceAttr = space !== undefined ? ` ri:space-key="${escapeXmlAttr(space)}"` : '';
+    const body = text !== undefined ? plainTextLinkBody(text) : '';
+    return `<ac:link><ri:page ri:content-title="${escapeXmlAttr(title)}"${spaceAttr} />${body}</ac:link>`;
+}
+function plainTextLinkBody(text) {
+    const safe = text.replace(/\]\]>/g, ']]]]><![CDATA[>');
+    return `<ac:plain-text-link-body><![CDATA[${safe}]]></ac:plain-text-link-body>`;
+}
+/** Обратное к markdown-it escapeHtml (& < > "). */
+function unescapeHtml(s) {
+    return s
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&amp;/g, '&');
+}

package/dist/publish/publish.d.ts

@@ -1,4 +1,5 @@
 import type { ConfluenceConfig } from '../client/config.js';
+import { type RenderStorageOptions } from '../markdown/render.js';
 import type { MacroRegistry } from '../macros/registry.js';
 import { Markdown } from '../markdown/markdown.js';
 export interface TableData {
@@ -18,7 +19,13 @@ export interface PublishPageOptions {
     markdownPath?: string;
     /** Готовый markdown-контент (вместо markdownPath). */
     markdown?: Markdown | string;
+    /**
+     * Картинки для страницы: относительный или абсолютный путь на диске либо
+     * http(s)-URL (файл скачивается при публикации; для URL с того же
+     * Confluence используется токен из конфига). `*.bpmn` конвертируются в PNG.
+     */
     images?: string[];
+    /** Файлы-аттачи; те же виды источников, что и images. */
     files?: string[];
     tables?: TableData[];
     /**
@@ -43,6 +50,11 @@ export interface PublishPageOptions {
      * идёт по SHA-256 исходного BPMN через sidecar, лишних версий не будет.
      */
     bpmnOutDir?: string;
+    /**
+     * Каталог для файлов, скачанных по http(s)-URL из images[]/files[].
+     * Default: временный каталог на каждый запуск.
+     */
+    downloadDir?: string;
     /**
      * Ключ content property для хранения content-hash.
      * Default: 'confluence-md-sync-content-hash'.
@@ -50,6 +62,11 @@ export interface PublishPageOptions {
     hashPropertyKey?: string;
     /** Рендер и валидация без записи в Confluence. */
     dryRun?: boolean;
+    /**
+     * Опции рендера markdown → storage. Для страниц из exportPage:
+     * `{ imageStyle: 'attachment', fileStyle: 'attachment', linkify: false }`.
+     */
+    render?: RenderStorageOptions;
 }
 export interface PublishPageResult {
     pageId: string;

package/dist/publish/publish.js

@@ -5,7 +5,8 @@ import { basename, join } from 'node:path';
 import { ConfluenceClient } from '../client/client.js';
 import { AttachmentService } from '../attachments/attachment.js';
 import { bpmnOutputName, convertBpmn, isBpmnFile } from '../bpmn/convert.js';
-import { renameImagePlaceholders, renderToStorage } from '../markdown/render.js';
+import { downloadToFile, isHttpUrl, remoteFilename } from './remote.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';
@@ -20,14 +21,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 };
@@ -64,11 +77,41 @@ export async function publishPage(opts, cfg) {
         throw new Error('publishPage: either markdownPath or markdown must be provided');
     }
     let images = opts.images ?? [];
-    const files = opts.files ?? [];
+    let 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, а
+    // 0a. Удалённые источники: http(s)://-элементы в images[]/files[]
+    //     заменяются на локальный путь в downloadDir с именем из URL — дальше
+    //     конвейер (валидация, BPMN, аплоад) работает с обычными путями.
+    //     Скачивание — после валидации (fail fast, до любого сетевого I/O).
+    const remoteDownloads = [];
+    if ([...images, ...files].some(isHttpUrl)) {
+        const dlDir = opts.downloadDir ?? mkdtempSync(join(tmpdir(), 'confluence-md-sync-dl-'));
+        const toLocal = (spec) => {
+            if (!isHttpUrl(spec))
+                return spec;
+            const dest = join(dlDir, remoteFilename(spec));
+            remoteDownloads.push({ url: spec, dest });
+            return dest;
+        };
+        images = images.map(toLocal);
+        files = files.map(toLocal);
+    }
+    // Плейсхолдеры и dedup-карты ключуются по basename — одинаковые имена из
+    // разных источников молча перетёрли бы друг друга. С URL-источниками это
+    // легко словить случайно, поэтому проверяем явно.
+    for (const list of [images, files]) {
+        const byName = new Map();
+        for (const p of list) {
+            const prev = byName.get(basename(p));
+            if (prev !== undefined && prev !== p) {
+                throw new Error(`publishPage: duplicate attachment filename '${basename(p)}' from different sources: '${prev}' and '${p}'`);
+            }
+            byName.set(basename(p), p);
+        }
+    }
+    // 0b. BPMN из коробки: *.bpmn в images[] конвертируются в PNG, а
     //    {{img:p1.bpmn}} в markdown подменяется на {{img:p1.png}} ДО валидации.
     //    Сама конвертация (puppeteer) — после валидации, чтобы падать быстро.
     const bpmnConversions = [];
@@ -98,6 +141,14 @@ 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);
     }
+    // Скачивание удалённых источников — после валидации, до конвертации
+    // (скачанный .bpmn нужен convertBpmn). В dry-run пропускается.
+    if (remoteDownloads.length > 0 && !opts.dryRun) {
+        for (const { url, dest } of remoteDownloads) {
+            await downloadToFile(url, dest, cfg);
+            console.log(`[download] ${url} → ${basename(dest)}`);
+        }
+    }
     // Конвертация диаграмм — до аплоада; в dry-run пропускается (аттачи всё
     // равно не загружаются, URL подставляются фиктивные).
     if (bpmnConversions.length > 0 && !opts.dryRun) {
@@ -120,21 +171,24 @@ 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})`);
         }
     }
     // 2. Рендер MD → storage format с подстановкой полученных URL-ов.
-    let storage = renderToStorage(markdown, urls);
+    let storage = renderToStorage(markdown, urls, opts.render ?? {});
     // 2.5. Преобразование маркеров макросов в XHTML.
     storage = processMacros(storage, registry).toString();
     if (opts.dryRun) {
@@ -156,8 +210,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 +235,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/dist/publish/remote.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Удалённые источники для images[]/files[]: элемент со схемой http(s)://
+ * скачивается во временный каталог перед публикацией и дальше проходит
+ * обычный конвейер (BPMN-конвертация, dedup по SHA-256, аплоад).
+ *
+ * Если URL указывает на тот же Confluence, что и cfg.baseUrl (совпадает
+ * origin — протокол + хост + порт), запрос уходит с Authorization из
+ * текущего конфига (PAT/API token). На чужие хосты токен НЕ отправляется;
+ * undici к тому же сам вырезает Authorization при cross-origin redirect.
+ */
+import { type ConfluenceConfig } from '../client/config.js';
+/** true для http:// и https:// (остальное трактуется как путь на диске). */
+export declare function isHttpUrl(spec: string): boolean;
+/**
+ * Имя файла из URL: basename от pathname (query/fragment отбрасываются),
+ * percent-encoding декодируется. `.../p1.bpmn?version=2` → `p1.bpmn` —
+ * это же имя используется в `{{img:...}}`/`{{file:...}}` плейсхолдерах.
+ */
+export declare function remoteFilename(spec: string): string;
+/** Совпадает ли origin URL-а с origin Confluence из конфига. */
+export declare function isSameConfluenceOrigin(url: string, cfg: ConfluenceConfig): boolean;
+/** Заголовки запроса: Authorization — только для своего Confluence. */
+export declare function remoteRequestHeaders(url: string, cfg: ConfluenceConfig): Record<string, string>;
+/** Скачивает URL в destPath. Не-2xx → ошибка с кодом и URL. */
+export declare function downloadToFile(url: string, destPath: string, cfg: ConfluenceConfig): Promise<void>;

package/dist/publish/remote.js

@@ -0,0 +1,52 @@
+/**
+ * Удалённые источники для images[]/files[]: элемент со схемой http(s)://
+ * скачивается во временный каталог перед публикацией и дальше проходит
+ * обычный конвейер (BPMN-конвертация, dedup по SHA-256, аплоад).
+ *
+ * Если URL указывает на тот же Confluence, что и cfg.baseUrl (совпадает
+ * origin — протокол + хост + порт), запрос уходит с Authorization из
+ * текущего конфига (PAT/API token). На чужие хосты токен НЕ отправляется;
+ * undici к тому же сам вырезает Authorization при cross-origin redirect.
+ */
+import { writeFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { authHeader } from '../client/config.js';
+/** true для http:// и https:// (остальное трактуется как путь на диске). */
+export function isHttpUrl(spec) {
+    return /^https?:\/\//i.test(spec);
+}
+/**
+ * Имя файла из URL: basename от pathname (query/fragment отбрасываются),
+ * percent-encoding декодируется. `.../p1.bpmn?version=2` → `p1.bpmn` —
+ * это же имя используется в `{{img:...}}`/`{{file:...}}` плейсхолдерах.
+ */
+export function remoteFilename(spec) {
+    const pathname = new URL(spec).pathname;
+    // node:path.basename('/dir/') === 'dir' — трейлинг-слэш надо ловить явно.
+    const name = pathname.endsWith('/') ? '' : decodeURIComponent(basename(pathname));
+    if (!name) {
+        throw new Error(`Cannot derive a filename from URL '${spec}' — the path ends with '/'`);
+    }
+    return name;
+}
+/** Совпадает ли origin URL-а с origin Confluence из конфига. */
+export function isSameConfluenceOrigin(url, cfg) {
+    try {
+        return new URL(url).origin === new URL(cfg.baseUrl).origin;
+    }
+    catch {
+        return false;
+    }
+}
+/** Заголовки запроса: Authorization — только для своего Confluence. */
+export function remoteRequestHeaders(url, cfg) {
+    return isSameConfluenceOrigin(url, cfg) ? { Authorization: authHeader(cfg) } : {};
+}
+/** Скачивает URL в destPath. Не-2xx → ошибка с кодом и URL. */
+export async function downloadToFile(url, destPath, cfg) {
+    const res = await fetch(url, { headers: remoteRequestHeaders(url, cfg) });
+    if (!res.ok) {
+        throw new Error(`Download failed: HTTP ${res.status} ${res.statusText} for ${url}`);
+    }
+    writeFileSync(destPath, Buffer.from(await res.arrayBuffer()));
+}

package/package.json

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