confluence-md-sync 0.2.0 → 0.3.0

package/README.md

@@ -10,7 +10,8 @@ typed tables back, attach files — idempotently, with a **pluggable macro
 system**. ESM-only, zero-config CI.
 
 ```bash
-npm install confluence-md-sync
+npm install confluence-md-sync          # as a library
+npm install -g confluence-md-sync       # as a CLI: `confluence-md-sync …`
 ```
 
 ## Highlights
@@ -23,7 +24,13 @@ npm install confluence-md-sync
 - **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
-  with your own in a few lines.
+  with your own in a few lines; unknown macros pass through unchanged.
+- **Flexible sources** — images/files accept relative paths, absolute paths
+  or `http(s)` URLs; URLs on your Confluence host are fetched with the
+  configured token.
+- **Loss-free round-trip** — export a page to Markdown and publish it back;
+  what Markdown can't express is kept verbatim, verified by canonical
+  storage comparison.
 
 ## Configuration
 
@@ -48,10 +55,11 @@ Markdown + three placeholder kinds:
 ```markdown
 # Отчёт за месяц
 
-{{img:flow.png}}          <!-- inline image from images[] -->
+{{img:chart.png}}            <!-- inline image from images[] -->
+{{img:flow.bpmn}}            <!-- BPMN diagram — rendered to PNG automatically -->
 Исходник: {{file:data.csv}}  <!-- attachment link from files[] -->
 
-{{table:summary}}         <!-- table injected from tables[] -->
+{{table:summary}}            <!-- table injected from tables[] -->
 ```
 
 ```ts
@@ -66,7 +74,10 @@ const summary = renderMarkdownTable(rows, [
 await publishPage({
   pageId: '123456789',
   markdownPath: 'docs/report.md',
-  images: ['build/flow.png'],
+  images: [
+    'build/chart.png',
+    'docs/flow.bpmn',   // converted to flow.png on the fly (see BPMN section)
+  ],
   files: ['build/data.csv'],
   tables: [{
     name: 'summary',
@@ -93,25 +104,47 @@ const { storage } = await publishPage({ pageId, markdownPath, dryRun: true }, cf
 
 // Inline content instead of a file
 await publishPage({ pageId, markdown: '# Generated\n\ntext' }, cfg);
+
+// Remote sources — downloaded at publish time; the filename for {{img:...}}
+// comes from the URL path. URLs on the configured Confluence host are
+// fetched with your token, so you can pull attachments from other pages.
+await publishPage({
+  pageId,
+  markdownPath,
+  images: ['https://confluence.example.com/download/attachments/999/flow.bpmn'],
+  files: ['https://files.example.com/exports/выгрузка.csv'],
+  downloadDir: 'build',   // optional; default: temp dir per run
+}, cfg);
 ```
 
 ## BPMN diagrams out of the box
 
-Pass a `.bpmn` file as an image — it is rendered to PNG at publish time
+Pass a `.bpmn` file as an image (a path or an `http(s)` URL) — it is
+rendered to PNG at publish time
 (headless Chromium via [bpmn-to-image](https://npmjs.com/package/bpmn-to-image),
-an optional peer dependency):
+an optional peer dependency).
+
+Setup — install the converter **and** force a current puppeteer:
 
 ```bash
-npm install -D bpmn-to-image
+npm install -D bpmn-to-image puppeteer
 ```
 
-> bpmn-to-image pins puppeteer 21, whose bundled Chromium fails to launch on
-> recent OSes ("socket hang up"). Force a current puppeteer in your
-> `package.json`:
->
-> ```json
-> "overrides": { "puppeteer": "^24.0.0" }
-> ```
+```jsonc
+// package.json — required: bpmn-to-image pins puppeteer 21, whose bundled
+// Chromium fails to launch on recent OSes ("socket hang up"). The override
+// must reference the direct dependency ("$puppeteer"), otherwise `npm ci`
+// fails with "Override for puppeteer conflicts with direct dependency".
+{
+  "devDependencies": {
+    "bpmn-to-image": "^0.7.0",
+    "puppeteer": "^24.0.0"
+  },
+  "overrides": {
+    "puppeteer": "$puppeteer"
+  }
+}
+```
 
 ```markdown
 Процесс выпуска релиза:
@@ -138,6 +171,59 @@ import { convertBpmnFolder } from 'confluence-md-sync';
 await convertBpmnFolder({ srcDir: 'docs/diagrams', outDir: 'build' });
 ```
 
+## Export a page back to Markdown (round-trip)
+
+Pull an existing page by ID and turn its storage format into Markdown —
+without losing markup. The conversion is **loss-free by construction**: a
+three-tier policy renders each node as clean Markdown where possible,
+macro markers where a macro round-trips, and verbatim storage (raw HTML,
+or a ` ```confluence-storage ` fence) as a fallback. Attachments and page
+links become `{{img:...}}` / `{{file:...}}` / `{{page:...}}` placeholders.
+
+```ts
+import { exportPage } from 'confluence-md-sync';
+
+const { markdownPath, images, downloaded } = await exportPage(
+  '123456789',
+  { outDir: 'exported' },   // writes exported/page.md + exported/attachments/
+  cfg,
+);
+```
+
+Round-trip means *edit the Markdown, then publish it straight back*:
+
+```ts
+await publishPage({
+  pageId: '123456789',
+  markdownPath: 'exported/page.md',
+  images: ['exported/attachments/diagram.png'],
+  // exported markup uses native attachment/link references, not URLs:
+  render: { imageStyle: 'attachment', fileStyle: 'attachment', linkify: false },
+}, cfg);
+```
+
+Verify a page survives the trip with no markup loss (writes nothing):
+
+```ts
+import { roundTripPage } from 'confluence-md-sync';
+
+const r = await roundTripPage('123456789', cfg);
+console.log(r.equal, r.stats);   // true { markers, fenced, rawHtml }
+// r.diffs lists any canonical differences when equal === false
+```
+
+Equivalence is **canonical**, not byte-for-byte: `ac:macro-id`,
+schema-version, attribute/parameter order and entity vs literal forms are
+normalised away (Confluence itself rewrites these on every save). Use
+`compareStorage(a, b)` directly to diff two storage fragments.
+
+From the CLI:
+
+```bash
+confluence-md-sync export    123456789 --out-dir exported
+confluence-md-sync roundtrip 123456789 --show-markdown   # exit 2 on loss
+```
+
 ## Read pages and tables
 
 ```ts
@@ -191,6 +277,7 @@ macros.tableExcerptInclude('name', 'Source Page');
 // Table Filter and Charts app
 macros.tableExcerpt(md, 'name', /* hide */ true);
 macros.tableFilter(md, { totalrow: ',,Sum' });
+macros.tableJoiner(includesMd, "SELECT * FROM T1 LEFT JOIN T2 ON …");  // multiline SQL ok
 ```
 
 Or write markers by hand right in Markdown:
@@ -201,6 +288,10 @@ Any **markdown**, including nested macros.
 <!-- MACRO:end:expand -->
 ```
 
+Any macro name works out of the box — one that isn't registered passes
+through to `<ac:structured-macro>` as-is (params + rich-text body). Disable
+with `registry.passthroughUnknownMacros(false)`.
+
 ### Custom macro plugin
 
 ```ts
@@ -221,11 +312,24 @@ splitting; `pageLinkValue()` builds `<ac:link><ri:page/>` parameter values.
 
 ## CLI
 
+Installed globally (`npm i -g confluence-md-sync`) the `confluence-md-sync`
+command is on your PATH; otherwise prefix the examples with `npx`. The
+instance URL and token come from the environment.
+
 ```bash
-npx confluence-md-sync publish docs/page.md --page-id 123456789 \
+export CONFLUENCE_BASE_URL='https://confluence.example.com'
+export CONFLUENCE_TOKEN='<your-PAT>'
+
+# Download a page to an exact .md path (add --no-attachments for the md only)
+confluence-md-sync export 123456789 --out ./page.md
+
+confluence-md-sync publish docs/page.md --page-id 123456789 \
   --image build/flow.png --file build/data.csv --label docs
 
-npx confluence-md-sync publish docs/page.md --space DOCS --title "Моя страница" --dry-run
+confluence-md-sync publish docs/page.md --space DOCS --title "Моя страница" --dry-run
+
+confluence-md-sync export    123456789 --out-dir exported   # page.md + attachments/
+confluence-md-sync roundtrip 123456789                      # exit 2 if markup would be lost
 ```
 
 ## CI publish plans
@@ -260,7 +364,8 @@ src/
 ├── macros/        registry, builder, plugins (core, table-filter)
 ├── attachments/   sha256 dedup, sidecar source hashes, version history
 ├── pages/         Page/Table object model, table parse & render
-├── publish/       idempotent publish pipeline, runPublish plans
+├── publish/       idempotent publish pipeline, runPublish plans, remote sources
+├── export/        storage parser, storage→Markdown, canonical compare, round-trip
 ├── wrapper.ts     confluence() facade
 ├── csv.ts         CSV helpers (subpath export ./csv)
 └── cli.ts         confluence-md-sync CLI
@@ -268,9 +373,9 @@ src/
 
 ## Roadmap
 
-Cloud API v2 backend · page-tree sync from a directory · storage→Markdown
-reverse conversion · Mermaid/PlantUML fences → images · fenced code →
-`code` macro · HTTP retry/backoff · comments API · dry-run diff preview.
+Cloud API v2 backend · page-tree sync from a directory · Mermaid/PlantUML
+fences → images · fenced code → `code` macro · HTTP retry/backoff ·
+comments API · dry-run diff preview.
 
 Issues and PRs welcome.
 

package/dist/cli.d.ts

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 /**
- * Минимальный CLI:
+ * CLI: три подкоманды.
  *
  *   confluence-md-sync publish page.md --page-id 12345 \
  *     --image build/p1.png --file data.csv --label docs --dry-run
- *
  *   confluence-md-sync publish page.md --space DOCS --title "My Page" --parent-id 777
  *
+ *   confluence-md-sync export 12345 --out-dir ./exported
+ *   confluence-md-sync roundtrip 12345           # проверка без потерь, ничего не пишет
+ *
  * Конфиг — из env: CONFLUENCE_BASE_URL, CONFLUENCE_TOKEN (или CONFLUENCE_PAT),
  * CONFLUENCE_USERNAME, CONFLUENCE_AUTH_TYPE (bearer|basic).
  */

package/dist/cli.js

@@ -1,35 +1,52 @@
 #!/usr/bin/env node
 /**
- * Минимальный CLI:
+ * CLI: три подкоманды.
  *
  *   confluence-md-sync publish page.md --page-id 12345 \
  *     --image build/p1.png --file data.csv --label docs --dry-run
- *
  *   confluence-md-sync publish page.md --space DOCS --title "My Page" --parent-id 777
  *
+ *   confluence-md-sync export 12345 --out-dir ./exported
+ *   confluence-md-sync roundtrip 12345           # проверка без потерь, ничего не пишет
+ *
  * Конфиг — из env: CONFLUENCE_BASE_URL, CONFLUENCE_TOKEN (или CONFLUENCE_PAT),
  * CONFLUENCE_USERNAME, CONFLUENCE_AUTH_TYPE (bearer|basic).
  */
 import { parseArgs } from 'node:util';
 import { loadConfigFromEnv } from './client/config.js';
 import { publishPage } from './publish/publish.js';
-const HELP = `confluence-md-sync — publish Markdown to Confluence
+import { exportPage } from './export/export-page.js';
+import { roundTripPage } from './export/roundtrip.js';
+const HELP = `confluence-md-sync — Markdown ⇄ Confluence
 
 Usage:
-  confluence-md-sync publish <markdown-file> [options]
+  confluence-md-sync publish   <markdown-file> [options]
+  confluence-md-sync export    <page-id> [--out <file> | --out-dir <dir>] [--no-attachments]
+  confluence-md-sync roundtrip <page-id> [--show-markdown]
 
-Options:
+publish options:
   --page-id <id>        Target page ID
   --space <key>         Space key (with --title, when page ID is unknown)
   --title <title>       Page title (rename, or lookup/create key with --space)
   --parent-id <id>      Parent page for page creation
-  --image <path>        Attach an image (repeatable), referenced as {{img:name.png}}
-  --file <path>         Attach a file (repeatable), referenced as {{file:name.csv}}
+  --image <src>         Attach an image (repeatable), referenced as {{img:name.png}}
+  --file <src>          Attach a file (repeatable), referenced as {{file:name.csv}}
+                        <src> is a relative/absolute path or an http(s) URL;
+                        URLs on the Confluence host are fetched with your token
   --label <name>        Ensure label on the page (repeatable)
   --message <text>      Page version comment
   --no-create           Fail instead of creating a missing page
   --dry-run             Render and validate without writing to Confluence
-  --help                Show this help
+
+export options:
+  --out <file>          Write the Markdown to exactly this path (attachments,
+                        if any, go to attachments/ next to it)
+  --out-dir <dir>       Output directory (default: ./<page-id>); writes page.md
+                        and attachments/
+  --no-attachments      Do not download referenced attachments
+
+roundtrip options:
+  --show-markdown       Print the intermediate Markdown to stdout
 
 Environment:
   CONFLUENCE_BASE_URL   e.g. https://confluence.example.com
@@ -51,33 +68,64 @@ async function main() {
             message: { type: 'string' },
             'no-create': { type: 'boolean' },
             'dry-run': { type: 'boolean' },
+            out: { type: 'string' },
+            'out-dir': { type: 'string' },
+            'no-attachments': { type: 'boolean' },
+            'show-markdown': { type: 'boolean' },
             help: { type: 'boolean' },
         },
     });
-    if (values.help || positionals.length === 0) {
+    const [command, arg] = positionals;
+    if (values.help || command === undefined) {
         console.log(HELP);
         process.exit(values.help ? 0 : 1);
     }
-    const [command, markdownPath] = positionals;
-    if (command !== 'publish' || !markdownPath) {
-        console.error(`Unknown command or missing file. See --help.`);
-        process.exit(1);
-    }
     const cfg = loadConfigFromEnv();
-    const result = await publishPage({
-        pageId: values['page-id'],
-        spaceKey: values.space,
-        title: values.title,
-        parentPageId: values['parent-id'],
-        markdownPath,
-        images: values.image ?? [],
-        files: values.file ?? [],
-        labels: values.label,
-        versionMessage: values.message,
-        createIfMissing: values['no-create'] ? false : undefined,
-        dryRun: values['dry-run'],
-    }, cfg);
-    console.log(`[cli] ${result.updated ? 'published' : 'unchanged'}: page ${result.pageId} v${result.version}`);
+    if (command === 'publish') {
+        if (!arg)
+            throw new Error('publish: markdown file is required');
+        const result = await publishPage({
+            pageId: values['page-id'],
+            spaceKey: values.space,
+            title: values.title,
+            parentPageId: values['parent-id'],
+            markdownPath: arg,
+            images: values.image ?? [],
+            files: values.file ?? [],
+            labels: values.label,
+            versionMessage: values.message,
+            createIfMissing: values['no-create'] ? false : undefined,
+            dryRun: values['dry-run'],
+        }, cfg);
+        console.log(`[cli] ${result.updated ? 'published' : 'unchanged'}: page ${result.pageId} v${result.version}`);
+        return;
+    }
+    if (command === 'export') {
+        if (!arg)
+            throw new Error('export: page id is required');
+        const result = await exportPage(arg, {
+            outFile: values.out,
+            outDir: values['out-dir'],
+            downloadAttachments: !values['no-attachments'],
+        }, cfg);
+        console.log(`[cli] exported page ${result.pageId} "${result.title}" v${result.version} → ${result.markdownPath}` +
+            ` (${result.downloaded.size} attachment(s), ${result.stats.fenced} raw storage block(s))`);
+        return;
+    }
+    if (command === 'roundtrip') {
+        if (!arg)
+            throw new Error('roundtrip: page id is required');
+        const result = await roundTripPage(arg, cfg);
+        if (values['show-markdown'])
+            console.log(result.markdown);
+        console.log(`[cli] roundtrip page ${arg} "${result.title}": ${result.equal ? 'OK — no markup loss' : 'DIFFERENCES FOUND'}` +
+            ` (markers=${result.stats.markers}, fenced=${result.stats.fenced}, rawHtml=${result.stats.rawHtml})`);
+        for (const d of result.diffs)
+            console.error(`  ${d.path}: ${d.message}`);
+        process.exit(result.equal ? 0 : 2);
+    }
+    console.error(`Unknown command '${command}'. See --help.`);
+    process.exit(1);
 }
 main().catch((err) => {
     console.error(`[cli] failed: ${err instanceof Error ? err.message : String(err)}`);

package/dist/export/canonical.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Канонизация storage-деревьев и сравнение «без потери разметки».
+ *
+ * Побайтовое равенство storage → md → storage недостижимо и не нужно:
+ * Confluence сам нормализует storage при каждом сохранении, ac:macro-id
+ * генерируется заново, markdown-it меняет форму сущностей. Критерий
+ * эквивалентности: XML-деревья равны после канонизации —
+ *  - ac:macro-id / ac:schema-version отброшены;
+ *  - сущности декодированы, пробельные последовательности схлопнуты;
+ *  - пробельные text-узлы между блочными элементами удалены;
+ *  - краевые пробелы вынесены из инлайн-форматирования
+ *    (<strong>a </strong>b ≡ <strong>a</strong> b);
+ *  - параметры макросов отсортированы по имени;
+ *  - <img src=…> ≡ <ac:image><ri:url ri:value=…/></ac:image>;
+ *  - атрибуты отсортированы по имени.
+ */
+import { type XNode } from './xhtml.js';
+/** Канонический узел: element | text (после нормализации). */
+export type CNode = {
+    kind: 'el';
+    name: string;
+    attrs: Record<string, string>;
+    children: CNode[];
+} | {
+    kind: 'text';
+    text: string;
+};
+export declare function canonicalize(nodes: XNode[]): CNode[];
+export interface StorageDiff {
+    path: string;
+    message: string;
+}
+export interface CompareResult {
+    equal: boolean;
+    diffs: StorageDiff[];
+}
+/** Сравнивает два storage-фрагмента с точностью до канонизации. */
+export declare function compareStorage(a: string, b: string, maxDiffs?: number): CompareResult;