confluence-md-sync 0.1.1

package/dist/publish/publish.js

@@ -0,0 +1,164 @@
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { ConfluenceClient } from '../client/client.js';
+import { AttachmentService } from '../attachments/attachment.js';
+import { renderToStorage } from '../markdown/render.js';
+import { validateMarkdown } from '../markdown/validate.js';
+import { processMacros } from '../macros/registry.js';
+import { defaultMacroRegistry } from '../macros/index.js';
+import { Markdown } from '../markdown/markdown.js';
+// Content property с SHA-256 от рендеренного storage. Хранится отдельно
+// от body через /rest/api/content/{id}/property/{key}, поэтому:
+//  - не попадает в HTML страницы (пользователь не видит);
+//  - переживает любую нормализацию storage Confluence (HTML-comment не
+//    переживал — был первый подход, не сработал).
+// При повторной публикации того же контента hash совпадёт → updatePage
+// не вызываем → версия страницы не растёт, история не пухнет.
+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.
+    const canonical = storage.replace(/(\/download\/attachments\/[^"?\s]+)\?[^"\s]*/g, '$1');
+    return createHash('sha256').update(canonical, 'utf-8').digest('hex');
+}
+async function resolvePage(client, opts) {
+    if (opts.pageId)
+        return { pageId: opts.pageId, created: false };
+    if (!opts.spaceKey || !opts.title) {
+        throw new Error('publishPage: either pageId or spaceKey + title must be provided');
+    }
+    const existing = await client.getPageByTitle(opts.spaceKey, opts.title);
+    if (existing)
+        return { pageId: existing.id, created: false };
+    if (opts.createIfMissing === false) {
+        throw new Error(`publishPage: page '${opts.title}' not found in space '${opts.spaceKey}' and createIfMissing is false`);
+    }
+    if (opts.dryRun) {
+        console.log(`[publish] dry-run: would create page '${opts.title}' in space '${opts.spaceKey}'`);
+        return { pageId: 'dry-run', created: true };
+    }
+    const page = await client.createPage({
+        spaceKey: opts.spaceKey,
+        title: opts.title,
+        parentId: opts.parentPageId,
+    });
+    console.log(`[publish] created page ${page.id} "${opts.title}" in space ${opts.spaceKey}`);
+    return { pageId: page.id, created: true };
+}
+export async function publishPage(opts, cfg) {
+    let markdown;
+    if (opts.markdownPath) {
+        markdown = readFileSync(opts.markdownPath, 'utf-8');
+    }
+    else if (opts.markdown !== undefined) {
+        markdown = opts.markdown instanceof Markdown ? opts.markdown.toString() : opts.markdown;
+    }
+    else {
+        throw new Error('publishPage: either markdownPath or markdown must be provided');
+    }
+    const images = opts.images ?? [];
+    const files = opts.files ?? [];
+    const tables = opts.tables ?? [];
+    const registry = opts.registry ?? defaultMacroRegistry;
+    const hashKey = opts.hashPropertyKey ?? DEFAULT_HASH_PROPERTY_KEY;
+    validateMarkdown({
+        markdown,
+        imagePaths: images,
+        filePaths: files,
+        tableNames: tables.map((t) => t.name),
+        sourceLabel: opts.markdownPath,
+    });
+    // Подставляем таблицы в markdown (уже могут быть обёрнуты в макросы).
+    for (const table of tables) {
+        const tableMarkdown = table.markdown instanceof Markdown ? table.markdown.toString() : table.markdown;
+        markdown = markdown.replace(new RegExp(`\\{\\{table:${escapeRegex(table.name)}\\}\\}`, 'g'), () => tableMarkdown);
+    }
+    const client = new ConfluenceClient(cfg);
+    const attachmentSvc = new AttachmentService(client);
+    const { pageId, created } = await resolvePage(client, opts);
+    // 1. Загрузка аттачей (или переиспользование по SHA-256). Собираем
+    //    отдельные карты «имя → URL» для картинок и файлов — рендер потом
+    //    подставит эти URL в <img src=…> и <a href=…> вместо плейсхолдеров.
+    const urls = { images: new Map(), files: new Map() };
+    const attachments = [];
+    if (opts.dryRun) {
+        // В dry-run не трогаем Confluence — подставляем фиктивные URL, чтобы
+        // рендер и валидация плейсхолдеров отработали полностью.
+        for (const p of images)
+            urls.images.set(basenameOf(p), `dry-run://img/${basenameOf(p)}`);
+        for (const p of files)
+            urls.files.set(basenameOf(p), `dry-run://file/${basenameOf(p)}`);
+    }
+    else {
+        for (const p of images) {
+            const r = await attachmentSvc.ensure(pageId, p);
+            urls.images.set(r.filename, 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);
+            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);
+    // 2.5. Преобразование маркеров макросов в XHTML.
+    storage = processMacros(storage, registry).toString();
+    if (opts.dryRun) {
+        console.log(`[publish] dry-run: page ${pageId} rendered OK (${storage.length} bytes of storage)`);
+        return {
+            pageId,
+            title: opts.title ?? '',
+            version: 0,
+            attachments,
+            updated: false,
+            created,
+            storage,
+        };
+    }
+    // 3. Content-hash check. Hash хранится в content property, не в body.
+    const newHash = computeContentHash(storage);
+    const [existing, hashProp] = await Promise.all([
+        client.getPageStorage(pageId),
+        client.getContentProperty(pageId, hashKey),
+    ]);
+    const title = opts.title ?? existing.title;
+    const existingHash = hashProp && typeof hashProp.value === 'object' && hashProp.value !== null
+        ? hashProp.value.hash ?? null
+        : null;
+    if (existingHash === newHash && title === existing.title) {
+        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, {
+        title,
+        version: nextVersion,
+        storage,
+        versionMessage: opts.versionMessage,
+    });
+    // 5. Запись/обновление content property с новым hash. Делаем ПОСЛЕ
+    //    updatePage чтобы при сбое publish hash не «опередил» реальное содержимое.
+    await client.setContentProperty(pageId, hashKey, { hash: newHash }, 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)})`);
+    return { pageId, title, version: nextVersion, attachments, updated: true, created, storage };
+}
+function basenameOf(p) {
+    const idx = Math.max(p.lastIndexOf('/'), p.lastIndexOf('\\'));
+    return idx === -1 ? p : p.slice(idx + 1);
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/publish/runner.d.ts

@@ -0,0 +1,36 @@
+import { type PublishPageOptions, type PublishPageResult } from './publish.js';
+import { type ConfluenceConfig, type LoadConfigOptions } from '../client/config.js';
+export type Here = (relativePath: string) => string;
+export type Build = (relativePath: string) => string;
+export type PublishPlan = PublishPageOptions[] | ((here: Here, build: Build) => PublishPageOptions[] | Promise<PublishPageOptions[]>);
+export interface RunPublishOptions {
+    /** Готовый конфиг вместо загрузки из env. */
+    config?: ConfluenceConfig;
+    /** Опции загрузки конфига из env (кастомные имена переменных токена). */
+    env?: LoadConfigOptions;
+    /**
+     * Каталог для сгенерированных артефактов (PNG и т.п.), доступный через
+     * `build(rel)`. Default: `<baseDir>/../../build/<basename(baseDir)>` —
+     * соответствует компоновке репо `<repo>/docs/<set>` + `<repo>/build/<set>`.
+     */
+    buildDir?: string;
+}
+/**
+ * Минимальная точка входа для публикующего скрипта (`docs/<set>/publish.ts`).
+ *
+ *   await runPublish(import.meta.dirname, (here, build) => [
+ *     {
+ *       pageId: '...',
+ *       markdownPath: here('overview.md'),
+ *       images: [build('p1.png')], // сгенерировано отдельным шагом в build-каталоге
+ *     },
+ *   ]);
+ *
+ * - `here(rel)`  — пути относительно папки запускающего модуля.
+ * - `build(rel)` — пути относительно build-каталога (см. RunPublishOptions.buildDir).
+ *
+ * Конфиг Confluence загружается из env (CONFLUENCE_BASE_URL, CONFLUENCE_TOKEN,
+ * CONFLUENCE_USERNAME, CONFLUENCE_AUTH_TYPE). При любой ошибке пишет одну
+ * строку в stderr и завершает процесс с кодом 1 — Confluence не трогается.
+ */
+export declare function runPublish(baseDir: string, plan: PublishPlan, opts?: RunPublishOptions): Promise<PublishPageResult[]>;

package/dist/publish/runner.js

@@ -0,0 +1,41 @@
+import { basename, join } from 'node:path';
+import { publishPage } from './publish.js';
+import { loadConfigFromEnv } from '../client/config.js';
+/**
+ * Минимальная точка входа для публикующего скрипта (`docs/<set>/publish.ts`).
+ *
+ *   await runPublish(import.meta.dirname, (here, build) => [
+ *     {
+ *       pageId: '...',
+ *       markdownPath: here('overview.md'),
+ *       images: [build('p1.png')], // сгенерировано отдельным шагом в build-каталоге
+ *     },
+ *   ]);
+ *
+ * - `here(rel)`  — пути относительно папки запускающего модуля.
+ * - `build(rel)` — пути относительно build-каталога (см. RunPublishOptions.buildDir).
+ *
+ * Конфиг Confluence загружается из env (CONFLUENCE_BASE_URL, CONFLUENCE_TOKEN,
+ * CONFLUENCE_USERNAME, CONFLUENCE_AUTH_TYPE). При любой ошибке пишет одну
+ * строку в stderr и завершает процесс с кодом 1 — Confluence не трогается.
+ */
+export async function runPublish(baseDir, plan, opts = {}) {
+    const here = (p) => join(baseDir, p);
+    const folderName = basename(baseDir);
+    const buildBase = opts.buildDir ?? join(baseDir, '..', '..', 'build', folderName);
+    const build = (p) => join(buildBase, p);
+    try {
+        const cfg = opts.config ?? loadConfigFromEnv(opts.env);
+        const pages = typeof plan === 'function' ? await plan(here, build) : plan;
+        const results = [];
+        for (const page of pages) {
+            results.push(await publishPage(page, cfg));
+        }
+        return results;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[publish] failed: ${msg}`);
+        process.exit(1);
+    }
+}

package/dist/wrapper.d.ts

@@ -0,0 +1,21 @@
+import type { ConfluenceConfig } from './client/config.js';
+import { ConfluenceClient } from './client/client.js';
+import { AttachmentService } from './attachments/attachment.js';
+import { Page } from './pages/page.js';
+import { type PublishPageOptions, type PublishPageResult } from './publish/publish.js';
+/**
+ * Высокоуровневый фасад: один объект на конфиг, отдаёт клиент, сервис
+ * аттачей, объектную модель страниц и публикацию.
+ */
+export declare class ConfluenceWrapper {
+    private readonly cfg;
+    readonly client: ConfluenceClient;
+    readonly attachments: AttachmentService;
+    constructor(cfg: ConfluenceConfig);
+    readPage(pageId: string): Promise<Page>;
+    /** Находит страницу по space + title и возвращает объектную модель. */
+    findPage(spaceKey: string, title: string): Promise<Page | null>;
+    /** Публикует markdown на страницу (см. {@link publishPage}). */
+    publish(opts: PublishPageOptions): Promise<PublishPageResult>;
+}
+export declare function confluence(cfg: ConfluenceConfig): ConfluenceWrapper;

package/dist/wrapper.js

@@ -0,0 +1,36 @@
+import { ConfluenceClient } from './client/client.js';
+import { AttachmentService } from './attachments/attachment.js';
+import { Page } from './pages/page.js';
+import { publishPage } from './publish/publish.js';
+/**
+ * Высокоуровневый фасад: один объект на конфиг, отдаёт клиент, сервис
+ * аттачей, объектную модель страниц и публикацию.
+ */
+export class ConfluenceWrapper {
+    cfg;
+    client;
+    attachments;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.client = new ConfluenceClient(cfg);
+        this.attachments = new AttachmentService(this.client);
+    }
+    async readPage(pageId) {
+        const { title, storage } = await this.client.getPageStorage(pageId);
+        return new Page(pageId, title, storage, this.client);
+    }
+    /** Находит страницу по space + title и возвращает объектную модель. */
+    async findPage(spaceKey, title) {
+        const found = await this.client.getPageByTitle(spaceKey, title);
+        if (!found)
+            return null;
+        return this.readPage(found.id);
+    }
+    /** Публикует markdown на страницу (см. {@link publishPage}). */
+    async publish(opts) {
+        return publishPage(opts, this.cfg);
+    }
+}
+export function confluence(cfg) {
+    return new ConfluenceWrapper(cfg);
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "confluence-md-sync",
+  "version": "0.1.1",
+  "description": "Publish Markdown to Confluence (Data Center & Cloud): idempotent page sync, attachment dedup, tables and a pluggable macro system",
+  "keywords": [
+    "confluence",
+    "markdown",
+    "sync",
+    "publish",
+    "atlassian",
+    "docs-as-code",
+    "storage-format",
+    "macros"
+  ],
+  "license": "MIT",
+  "author": "hexstyle",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hexstyle/confluence-md-sync.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hexstyle/confluence-md-sync/issues"
+  },
+  "homepage": "https://github.com/hexstyle/confluence-md-sync#readme",
+  "type": "module",
+  "engines": {
+    "node": ">=20.11"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./csv": {
+      "types": "./dist/csv.d.ts",
+      "import": "./dist/csv.js"
+    },
+    "./macros": {
+      "types": "./dist/macros/index.d.ts",
+      "import": "./dist/macros/index.js"
+    }
+  },
+  "bin": {
+    "confluence-md-sync": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "markdown-it": "^14.1.0"
+  },
+  "devDependencies": {
+    "@types/markdown-it": "^14.1.2",
+    "@types/node": "^20.14.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  }
+}