@baiyibai-antora/confluence-publisher 1.0.0-beta.1

package/README.adoc

@@ -0,0 +1,5 @@
+= @baiyibai-antora/confluence-publisher
+
+Publishes an Antora site's ADF manifest (produced by `@baiyibai-antora/adf-extension`) to a Confluence Cloud space: page tree, attachments, link rewriting, state tracking, and overwrite guard. Zero runtime dependencies.
+
+Full documentation lives in the repository https://gitlab.com/baiyibai-antora/confluora/-/blob/main/README.adoc[README].

package/bin/confluence-publish.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+'use strict'
+
+const { parseArgs } = require('node:util')
+const { publish } = require('../lib')
+const ConfluenceAdapter = require('../lib/client/confluence-adapter')
+const resolveSettings = require('../lib/settings')
+
+const HELP = `Usage: confluence-publish [options] <manifest-dir>
+
+Publishes an ADF manifest directory (produced by @baiyibai-antora/adf-extension,
+default ./build/adf) to a Confluence Cloud space.
+
+Options:
+  --space <key>       Confluence space key (or CONFLUENCE_SPACE_KEY)
+  --parent <pageId>   page to anchor the tree under (default: space homepage)
+  --base-url <url>    e.g. https://your-site.atlassian.net (or CONFLUENCE_BASE_URL)
+  --email <email>     Atlassian account email (or ATLASSIAN_EMAIL)
+  --dry-run           print the reconcile plan without writing anything
+  --force             overwrite pages that were edited in Confluence
+  --prune             archive pages that are no longer in the manifest
+  --no-banner         omit the "published automatically, do not edit" panel
+  --banner-text <t>   override the banner wording
+  --help              show this help
+
+Credentials: set ATLASSIAN_API_TOKEN in the environment (never a flag).
+`
+
+async function main () {
+  const { values: flags, positionals } = parseArgs({
+    options: {
+      space: { type: 'string' },
+      parent: { type: 'string' },
+      'base-url': { type: 'string' },
+      email: { type: 'string' },
+      'dry-run': { type: 'boolean', default: false },
+      force: { type: 'boolean', default: false },
+      prune: { type: 'boolean', default: false },
+      'no-banner': { type: 'boolean', default: false },
+      'banner-text': { type: 'string' },
+      help: { type: 'boolean', default: false },
+    },
+    allowPositionals: true,
+  })
+  if (flags.help) {
+    process.stdout.write(HELP)
+    return
+  }
+  const manifestDir = positionals[0] || 'build/adf'
+  const settings = resolveSettings({
+    space: flags.space,
+    parent: flags.parent,
+    baseUrl: flags['base-url'],
+    email: flags.email,
+  })
+  const port = new ConfluenceAdapter(settings)
+  const logger = {
+    info: (msg) => console.log(`[info] ${msg}`),
+    warn: (msg) => console.warn(`[warn] ${msg}`),
+  }
+  const { plan } = await publish(manifestDir, port, {
+    rootPageId: settings.rootPageId,
+    dryRun: flags['dry-run'],
+    force: flags.force,
+    prune: flags.prune,
+    banner: !flags['no-banner'],
+    bannerText: flags['banner-text'],
+    logger,
+  })
+
+  const counts = {}
+  for (const entry of plan) counts[entry.action] = (counts[entry.action] || 0) + 1
+  if (flags['dry-run']) {
+    console.log('\nDry run — no changes were made. Plan:')
+    for (const entry of plan) {
+      console.log(`  ${entry.action.padEnd(8)} ${entry.key}${entry.reason ? `  (${entry.reason})` : ''}`)
+    }
+  }
+  console.log(
+    '\n' +
+      Object.entries(counts)
+        .map(([action, n]) => `${action}: ${n}`)
+        .join(', ')
+  )
+  if (plan.some((entry) => entry.action === 'blocked')) process.exitCode = 2
+}
+
+main().catch((err) => {
+  console.error(`[error] ${err.message}`)
+  process.exitCode = 1
+})

package/lib/attachments.js

@@ -0,0 +1,29 @@
+'use strict'
+
+// MD5-incremental attachment sync (modelled on @markdown-confluence/lib's
+// Attachments.ts, Apache-2.0, which proved unusable as a dependency): the MD5
+// of the file travels in the attachment comment; a matching comment on an
+// existing attachment of the same name means the upload can be skipped.
+
+async function syncAttachments (port, pageId, attachments, readFile, logger) {
+  if (!attachments.length) return new Map()
+  const existing = new Map()
+  for (const att of await port.getAttachments(pageId)) {
+    existing.set(att.title, att)
+  }
+  const mediaIds = new Map() // placeholderId -> { id: fileId, collection }
+  for (const att of attachments) {
+    const current = existing.get(att.filename)
+    if (current && current.comment === att.md5 && current.fileId) {
+      mediaIds.set(att.placeholderId, { id: current.fileId, collection: `contentId-${pageId}` })
+      continue
+    }
+    const buffer = await readFile(att.path)
+    const uploaded = await port.uploadAttachment(pageId, att.filename, buffer, att.md5)
+    logger.info(`uploaded attachment ${att.filename} to page ${pageId}`)
+    mediaIds.set(att.placeholderId, { id: uploaded.fileId, collection: uploaded.collection })
+  }
+  return mediaIds
+}
+
+module.exports = syncAttachments

package/lib/banner.js

@@ -0,0 +1,24 @@
+'use strict'
+
+// The "bumper": a note panel prepended to every published body declaring the
+// content machine-published and not intended for editing (same role as
+// Captain's show-banner macro). On by default; text overridable.
+
+const DEFAULT_TEXT =
+  'This page is published automatically from an Antora documentation site and is not intended to be ' +
+  'edited here. Changes made in Confluence will be skipped or overwritten by the next publish. ' +
+  'Comments are preserved.'
+
+function bannerPanel ({ text = DEFAULT_TEXT, sourceUrl = null } = {}) {
+  const content = [{ type: 'text', text: text + (sourceUrl ? ' ' : '') }]
+  if (sourceUrl) {
+    content.push({
+      type: 'text',
+      text: 'View/Edit the source.',
+      marks: [{ type: 'link', attrs: { href: sourceUrl } }],
+    })
+  }
+  return { type: 'panel', attrs: { panelType: 'note' }, content: [{ type: 'paragraph', content }] }
+}
+
+module.exports = { bannerPanel, DEFAULT_TEXT }

package/lib/client/confluence-adapter.js

@@ -0,0 +1,151 @@
+'use strict'
+
+// Confluence Cloud adapter implementing the port (see ./port.js) over the v2
+// REST API with Node's built-in fetch. Attachment upload uses the v1
+// endpoint — v2 offers no multipart upload. `fetch` is injectable for tests.
+
+class ConfluenceAdapter {
+  constructor ({ baseUrl, email, apiToken, spaceKey, fetch: fetchImpl }) {
+    if (!baseUrl || !email || !apiToken || !spaceKey) {
+      throw new Error('confluence adapter requires baseUrl, email, apiToken, and spaceKey')
+    }
+    this.baseUrl = baseUrl.replace(/\/$/, '')
+    this.spaceKey = spaceKey
+    this.fetch = fetchImpl || globalThis.fetch
+    this.authHeader = 'Basic ' + Buffer.from(`${email}:${apiToken}`).toString('base64')
+    this.spaceId = undefined
+    this.webUrlCache = new Map()
+  }
+
+  async request (method, path, { body, headers, form } = {}) {
+    const opts = { method, headers: { Authorization: this.authHeader, Accept: 'application/json', ...headers } }
+    if (form) {
+      opts.body = form
+      opts.headers['X-Atlassian-Token'] = 'nocheck'
+    } else if (body !== undefined) {
+      opts.headers['Content-Type'] = 'application/json'
+      opts.body = JSON.stringify(body)
+    }
+    const response = await this.fetch(`${this.baseUrl}${path}`, opts)
+    if (response.status === 404) return null
+    if (!response.ok) {
+      const detail = await response.text().catch(() => '')
+      throw new Error(`Confluence ${method} ${path} failed: ${response.status} ${detail.slice(0, 500)}`)
+    }
+    if (response.status === 204) return {}
+    return response.json()
+  }
+
+  async getSpace () {
+    if (this.spaceId === undefined) {
+      const result = await this.request('GET', `/wiki/api/v2/spaces?keys=${encodeURIComponent(this.spaceKey)}`)
+      const space = result && result.results && result.results[0]
+      if (!space) throw new Error(`space "${this.spaceKey}" not found`)
+      this.space = space
+      this.spaceId = space.id
+    }
+    return this.space
+  }
+
+  async getSpaceHomeId () {
+    const space = await this.getSpace()
+    if (!space.homepageId) throw new Error(`space "${this.spaceKey}" has no homepage to anchor the page tree`)
+    return String(space.homepageId)
+  }
+
+  async getPage (pageId) {
+    const page = await this.request('GET', `/wiki/api/v2/pages/${pageId}`)
+    if (!page) return null
+    if (page._links && page._links.webui) {
+      this.webUrlCache.set(String(page.id), this.wikiUrl(page._links.webui))
+    }
+    return {
+      id: String(page.id),
+      title: page.title,
+      parentId: page.parentId == null ? null : String(page.parentId),
+      version: { number: page.version.number },
+    }
+  }
+
+  async createPage ({ title, parentId, body }) {
+    const space = await this.getSpace()
+    const page = await this.request('POST', '/wiki/api/v2/pages', {
+      body: { spaceId: space.id, status: 'current', title, parentId, body },
+    })
+    if (page._links && page._links.webui) this.webUrlCache.set(String(page.id), this.wikiUrl(page._links.webui))
+    return { id: String(page.id), version: { number: page.version.number } }
+  }
+
+  async updatePage ({ id, title, parentId, version, body }) {
+    const payload = { id, status: 'current', title, body, version: { number: version } }
+    if (parentId != null) payload.parentId = parentId
+    const page = await this.request('PUT', `/wiki/api/v2/pages/${id}`, { body: payload })
+    return { id: String(page.id), version: { number: page.version.number } }
+  }
+
+  async archivePage (pageId) {
+    // v2 delete moves the page to the trash (purge is a separate call).
+    await this.request('DELETE', `/wiki/api/v2/pages/${pageId}`)
+  }
+
+  async getContentProperty (pageId, key) {
+    const result = await this.request(
+      'GET',
+      `/wiki/api/v2/pages/${pageId}/properties?key=${encodeURIComponent(key)}`
+    )
+    const prop = result && result.results && result.results[0]
+    if (!prop) return null
+    return { id: String(prop.id), key: prop.key, value: prop.value, version: { number: prop.version.number } }
+  }
+
+  async setContentProperty (pageId, key, value, existing) {
+    if (existing) {
+      await this.request('PUT', `/wiki/api/v2/pages/${pageId}/properties/${existing.id}`, {
+        body: { key, value, version: { number: existing.version.number + 1 } },
+      })
+    } else {
+      await this.request('POST', `/wiki/api/v2/pages/${pageId}/properties`, { body: { key, value } })
+    }
+  }
+
+  async getAttachments (pageId) {
+    const result = await this.request('GET', `/wiki/api/v2/pages/${pageId}/attachments?limit=250`)
+    return ((result && result.results) || []).map((att) => ({
+      id: String(att.id),
+      title: att.title,
+      fileId: att.fileId,
+      comment: att.comment || '',
+      pageId: String(pageId),
+    }))
+  }
+
+  async uploadAttachment (pageId, filename, buffer, comment) {
+    const form = new FormData()
+    form.append('file', new Blob([buffer]), filename)
+    form.append('comment', comment)
+    form.append('minorEdit', 'true')
+    const result = await this.request('PUT', `/wiki/rest/api/content/${pageId}/child/attachment`, { form })
+    const uploaded = result && result.results && result.results[0]
+    if (!uploaded) throw new Error(`attachment upload of ${filename} to page ${pageId} returned no result`)
+    return {
+      fileId: uploaded.extensions && uploaded.extensions.fileId,
+      collection: `contentId-${pageId}`,
+    }
+  }
+
+  attachmentDownloadUrl (pageId, filename) {
+    return `${this.baseUrl}/wiki/download/attachments/${pageId}/${encodeURIComponent(filename)}`
+  }
+
+  async getPageWebUrl (pageId) {
+    const id = String(pageId)
+    if (!this.webUrlCache.has(id)) await this.getPage(id)
+    return this.webUrlCache.get(id) || null
+  }
+
+  wikiUrl (webui) {
+    return `${this.baseUrl}/wiki${webui}`
+  }
+}
+
+module.exports = ConfluenceAdapter

package/lib/client/port.js

@@ -0,0 +1,23 @@
+'use strict'
+
+// The narrow Confluence interface the publisher is written against. The real
+// implementation is ./confluence-adapter (v2 REST over fetch); tests use an
+// in-memory fake with the same surface.
+//
+// interface ConfluencePort {
+//   getSpaceHomeId () -> pageId                      // root of the configured space
+//   getPage (pageId) -> { id, title, parentId, version: { number } } | null
+//   createPage ({ title, parentId, body? }) -> { id, version: { number } }
+//   updatePage ({ id, title, version, body }) -> { id, version: { number } }
+//   archivePage (pageId)
+//   getContentProperty (pageId, key) -> { id, key, value, version: { number } } | null
+//   setContentProperty (pageId, key, value, existing?) -> void
+//   getAttachments (pageId) -> [{ id, title, fileId, comment, pageId }]
+//   uploadAttachment (pageId, filename, buffer, comment) -> { fileId, collection }
+//   attachmentDownloadUrl (pageId, filename) -> absolute url string (sync)
+//   getPageWebUrl (pageId) -> absolute url string
+// }
+//
+// `body` is always { representation: 'atlas_doc_format', value: <ADF JSON string> }.
+
+module.exports = {}

package/lib/index.js

@@ -0,0 +1,242 @@
+'use strict'
+
+const fsp = require('node:fs/promises')
+const ospath = require('node:path')
+const { createHash } = require('node:crypto')
+
+const buildTree = require('./tree')
+const rewriteAdf = require('./rewrite')
+const syncAttachments = require('./attachments')
+const { bannerPanel, DEFAULT_TEXT } = require('./banner')
+const { INDEX_KEY, readIndex, writeIndex, readPageState, writePageState } = require('./state')
+
+const sha1 = (str) => createHash('sha1').update(str).digest('hex')
+const STUB_BODY = { version: 1, type: 'doc', content: [] }
+
+/**
+ * Publish an ADF manifest directory (produced by @baiyibai-antora/adf-extension)
+ * to Confluence through the given port.
+ *
+ * Three passes:
+ *  1. skeleton — every page gets a Confluence id (missing pages are created
+ *     top-down with a stub body), so xrefs and attachments have targets
+ *  2. attachments — MD5-incremental upload per changed page
+ *  3. body — media/link rewrite, then the ADF body is written
+ *
+ * Overwrite guard (on by default): a page whose remote version no longer
+ * matches the version we last published was edited in Confluence; it is
+ * skipped with a warning unless `force` is set.
+ */
+async function publish (manifestDir, port, options = {}) {
+  const { force = false, prune = false, dryRun = false, banner = true, bannerText, logger = console } = options
+  const manifest = JSON.parse(await fsp.readFile(ospath.join(manifestDir, 'manifest.json'), 'utf8'))
+  const { nodes, warnings } = buildTree(manifest)
+  for (const warning of warnings) logger.warn(warning)
+
+  const rootPageId = options.rootPageId || (await port.getSpaceHomeId())
+  const { entries: index } = await readIndex(port, rootPageId)
+  const idByKey = new Map()
+  const plan = []
+  let indexDirty = false
+  let newCounter = 0
+  // The index property may be written twice per run (after creation, after
+  // prune); always write against its current version.
+  const flushIndex = async () => {
+    await writeIndex(port, rootPageId, index, await port.getContentProperty(rootPageId, INDEX_KEY))
+    indexDirty = false
+  }
+
+  // Pass 1: skeleton — every node ends up with a page id.
+  for (const node of nodes) {
+    let pageId = index[node.key]
+    let remote = pageId ? await port.getPage(pageId) : null
+    if (pageId && !remote) {
+      logger.warn(`${node.key}: indexed page ${pageId} no longer exists; will recreate`)
+      pageId = null
+    }
+    node.desiredParentId = node.parentKey ? idByKey.get(node.parentKey) : rootPageId
+    if (!pageId) {
+      if (dryRun) {
+        pageId = `(new-${++newCounter})`
+      } else {
+        const created = await port.createPage({
+          title: node.title,
+          parentId: node.desiredParentId,
+          body: { representation: 'atlas_doc_format', value: JSON.stringify(STUB_BODY) },
+        })
+        pageId = created.id
+        index[node.key] = pageId
+        indexDirty = true
+        node.remoteVersion = created.version.number
+      }
+      node.created = true
+    } else {
+      node.remoteVersion = remote.version.number
+      node.remoteTitle = remote.title
+      node.remoteParentId = remote.parentId
+    }
+    node.pageId = pageId
+    idByKey.set(node.key, pageId)
+  }
+  if (indexDirty) await flushIndex()
+
+  // The banner's source link points at the page's source in its git
+  // repository (falling back to the page on the static site).
+  const bannerSourceUrl = (node) =>
+    (node.page && node.page.sourceUrl) ||
+    (manifest.site.url && node.page && node.page.url ? manifest.site.url + node.page.url : manifest.site.url || null)
+
+  // Decide per-node action before touching bodies. The banner content is part
+  // of the published body, so changing its text, link, or toggle
+  // re-publishes; so are a home page's exports (the Downloads list lives in
+  // its body).
+  for (const node of nodes) {
+    node.bannerSig = banner ? sha1(`${bannerText || DEFAULT_TEXT}|${bannerSourceUrl(node) || ''}`) : 'off'
+    const exportsSig = JSON.stringify((node.exports || []).map((e) => ({ filename: e.filename, md5: e.md5 })))
+    const contentHash =
+      node.kind === 'page'
+        ? node.page.contentHash
+        : node.kind === 'home'
+          ? sha1(node.page.contentHash + exportsSig)
+          : sha1(exportsSig)
+    node.contentHash = contentHash
+    if (node.created) {
+      node.action = 'create'
+      continue
+    }
+    const { state, prop } = await readPageState(port, node.pageId)
+    node.stateProp = prop
+    if (!state) {
+      node.action = force ? 'update' : 'blocked'
+      node.reason = 'page exists but was not published by this tool'
+    } else if (state.publishedVersion !== node.remoteVersion) {
+      node.action = force ? 'update' : 'blocked'
+      node.reason = `page was edited in Confluence (version ${node.remoteVersion}, last published ${state.publishedVersion})`
+    } else if (
+      state.sourceHash === contentHash &&
+      node.remoteTitle === node.title &&
+      state.bannerSig === node.bannerSig &&
+      // site.url feeds unpublished-target link fallbacks.
+      state.siteUrl === (manifest.site.url || null) &&
+      String(node.remoteParentId) === String(node.desiredParentId)
+    ) {
+      node.action = 'skip'
+    } else {
+      node.action = 'update'
+    }
+    if (node.action === 'blocked') {
+      logger.warn(`${node.key}: ${node.reason}; skipping (use --force to overwrite)`)
+    }
+  }
+
+  // Link targets: manifest page url -> Confluence web url + heading anchors.
+  const linkUrls = new Map()
+  const anchorsByUrl = new Map()
+  for (const node of nodes) {
+    if (!node.page) continue
+    const webUrl = dryRun && node.created ? `about:blank#${node.key}` : await port.getPageWebUrl(node.pageId)
+    if (node.page.url && webUrl) {
+      linkUrls.set(node.page.url, webUrl)
+      if (node.page.anchors) anchorsByUrl.set(node.page.url, node.page.anchors)
+    }
+  }
+
+  // Passes 2 + 3 per node that needs its body written.
+  for (const node of nodes) {
+    plan.push({ action: node.action, key: node.key, title: node.title, pageId: node.pageId, reason: node.reason })
+    if (node.action === 'skip' || node.action === 'blocked' || dryRun) continue
+
+    const readFile = (relPath) => fsp.readFile(ospath.join(manifestDir, ...relPath.split('/')))
+    let body
+    if (node.kind === 'root') {
+      // Page-less component version that still has downloads.
+      await syncAttachments(port, node.pageId, node.exports || [], readFile, logger)
+      const content = banner ? [bannerPanel({ text: bannerText, sourceUrl: manifest.site.url || null })] : []
+      content.push(...downloadsSection(node, port))
+      body = { version: 1, type: 'doc', content }
+    } else {
+      const adf = JSON.parse(await fsp.readFile(ospath.join(manifestDir, node.page.adfPath), 'utf8'))
+      const attachments = [...node.page.attachments, ...(node.exports || [])]
+      const mediaIds = await syncAttachments(port, node.pageId, attachments, readFile, logger)
+      const rewriteWarnings = []
+      body = rewriteAdf(
+        adf,
+        { mediaIds, linkUrls, anchorsByUrl, selfAnchors: node.page.anchors || {}, siteUrl: manifest.site.url },
+        rewriteWarnings
+      )
+      for (const warning of rewriteWarnings) logger.warn(`${node.key}: ${warning}`)
+      const content = [...body.content, ...downloadsSection(node, port)]
+      if (banner) content.unshift(bannerPanel({ text: bannerText, sourceUrl: bannerSourceUrl(node) }))
+      body = { ...body, content }
+    }
+
+    const updated = await port.updatePage({
+      id: node.pageId,
+      title: node.title,
+      parentId: node.desiredParentId,
+      version: node.remoteVersion + 1,
+      body: { representation: 'atlas_doc_format', value: JSON.stringify(body) },
+    })
+    await writePageState(
+      port,
+      node.pageId,
+      {
+        pageKey: node.key,
+        sourceHash: node.contentHash,
+        publishedVersion: updated.version.number,
+        bannerSig: node.bannerSig,
+        siteUrl: manifest.site.url || null,
+      },
+      node.stateProp
+    )
+    logger.info(`${node.action === 'create' ? 'created' : 'updated'} ${node.key} -> page ${node.pageId}`)
+  }
+
+  // Orphans: indexed pages that are no longer in the manifest.
+  const desiredKeys = new Set(nodes.map((n) => n.key))
+  for (const [key, pageId] of Object.entries(index)) {
+    if (desiredKeys.has(key)) continue
+    if (prune && !dryRun) {
+      await port.archivePage(pageId)
+      delete index[key]
+      indexDirty = true
+      plan.push({ action: 'pruned', key, pageId })
+      logger.info(`archived orphaned page ${key} (${pageId})`)
+    } else {
+      plan.push({ action: 'orphan', key, pageId })
+      logger.warn(`${key}: page ${pageId} is no longer in the manifest${prune ? '' : ' (use --prune to archive)'}`)
+    }
+  }
+  if (indexDirty && !dryRun) await flushIndex()
+
+  return { plan, rootPageId }
+}
+
+// Downloads list for assembler exports (PDFs etc.) attached to this page.
+function downloadsSection (node, port) {
+  const exports_ = node.exports || []
+  if (!exports_.length) return []
+  return [
+    { type: 'paragraph', content: [{ type: 'text', text: 'Downloads', marks: [{ type: 'strong' }] }] },
+    {
+      type: 'bulletList',
+      content: exports_.map((e) => ({
+        type: 'listItem',
+        content: [
+          {
+            type: 'paragraph',
+            content: [
+              {
+                type: 'text',
+                text: e.filename,
+                marks: [{ type: 'link', attrs: { href: port.attachmentDownloadUrl(node.pageId, e.filename) } }],
+              },
+            ],
+          },
+        ],
+      })),
+    },
+  ]
+}
+
+module.exports = { publish }

package/lib/rewrite.js

@@ -0,0 +1,63 @@
+'use strict'
+
+// Pure ADF-tree passes run just before a page body is written:
+//  - media nodes carrying a placeholder id -> the real attachment fileId +
+//    collection produced by the attachment pass
+//  - link marks whose href maps to a published page -> that page's Confluence
+//    URL (falling back to the static site URL when the target isn't published)
+//  - URL fragments -> Confluence heading anchors (Confluence derives anchors
+//    from the heading text, e.g. "Quick Start" -> #Quick-Start, not from
+//    Asciidoctor ids like #_quick_start)
+
+// Confluence Cloud heading anchor: the heading text with whitespace collapsed
+// to single dashes, case preserved.
+const confluenceAnchor = (headingText) => headingText.trim().replace(/\s+/g, '-')
+
+function rewriteAdf (
+  adf,
+  { mediaIds = new Map(), linkUrls = new Map(), anchorsByUrl = new Map(), selfAnchors = {}, siteUrl = null },
+  warnings = []
+) {
+  const mapFragment = (fragment, anchors) =>
+    fragment && anchors && anchors[fragment] ? confluenceAnchor(anchors[fragment]) : fragment
+
+  const visit = (node) => {
+    const out = { ...node }
+    if (node.type === 'media' && node.attrs && node.attrs.type === 'file') {
+      const real = mediaIds.get(node.attrs.id)
+      if (real) {
+        out.attrs = { ...node.attrs, id: real.id, collection: real.collection }
+      } else {
+        warnings.push(`media placeholder "${node.attrs.id}" has no uploaded attachment`)
+      }
+    }
+    if (node.marks) {
+      out.marks = node.marks.map((mark) => {
+        if (mark.type !== 'link' || !mark.attrs || typeof mark.attrs.href !== 'string') return mark
+        const href = mark.attrs.href
+        if (href.charAt(0) === '#') {
+          const fragment = mapFragment(href.slice(1), selfAnchors)
+          return { ...mark, attrs: { ...mark.attrs, href: `#${fragment}` } }
+        }
+        if (href.charAt(0) !== '/') return mark
+        const [urlPath, fragment] = href.split('#')
+        const target = linkUrls.get(urlPath)
+        if (target) {
+          const mapped = mapFragment(fragment, anchorsByUrl.get(urlPath))
+          return { ...mark, attrs: { ...mark.attrs, href: mapped ? `${target}#${mapped}` : target } }
+        }
+        if (siteUrl) {
+          return { ...mark, attrs: { ...mark.attrs, href: siteUrl + href } }
+        }
+        warnings.push(`link "${href}" targets an unpublished page and no site url is configured`)
+        return mark
+      })
+    }
+    if (node.content) out.content = node.content.map(visit)
+    return out
+  }
+  return visit(adf)
+}
+
+module.exports = rewriteAdf
+module.exports.confluenceAnchor = confluenceAnchor

package/lib/settings.js

@@ -0,0 +1,28 @@
+'use strict'
+
+// Credentials come from the environment (CI-friendly, never on the command
+// line); everything else from CLI flags.
+//
+//   CONFLUENCE_BASE_URL   e.g. https://your-site.atlassian.net
+//   ATLASSIAN_EMAIL       account email for the API token
+//   ATLASSIAN_API_TOKEN   https://id.atlassian.com/manage-profile/security/api-tokens
+
+function resolveSettings (flags, env = process.env) {
+  const settings = {
+    baseUrl: flags.baseUrl || env.CONFLUENCE_BASE_URL,
+    email: flags.email || env.ATLASSIAN_EMAIL || env.CONFLUENCE_USER_EMAIL,
+    apiToken: env.ATLASSIAN_API_TOKEN || env.CONFLUENCE_API_TOKEN,
+    spaceKey: flags.space || env.CONFLUENCE_SPACE_KEY,
+    rootPageId: flags.parent || env.CONFLUENCE_PARENT_PAGE_ID || undefined,
+  }
+  const missing = ['baseUrl', 'email', 'apiToken', 'spaceKey'].filter((key) => !settings[key])
+  if (missing.length) {
+    throw new Error(
+      `missing Confluence settings: ${missing.join(', ')} ` +
+        '(set CONFLUENCE_BASE_URL, ATLASSIAN_EMAIL, ATLASSIAN_API_TOKEN, CONFLUENCE_SPACE_KEY or pass flags)'
+    )
+  }
+  return settings
+}
+
+module.exports = resolveSettings

package/lib/state.js

@@ -0,0 +1,30 @@
+'use strict'
+
+// Publish state lives in Confluence content properties:
+//  - one index property on the root page mapping pageKey -> pageId
+//  - one property per published page recording what we last wrote
+// Content properties survive page moves and are shared across CI runners,
+// unlike a local state file.
+
+const INDEX_KEY = 'antora-adf-publisher-index'
+const PAGE_KEY = 'antora-adf-publisher'
+
+async function readIndex (port, rootPageId) {
+  const prop = await port.getContentProperty(rootPageId, INDEX_KEY)
+  return { entries: (prop && prop.value && prop.value.entries) || {}, prop }
+}
+
+async function writeIndex (port, rootPageId, entries, prop) {
+  await port.setContentProperty(rootPageId, INDEX_KEY, { entries }, prop)
+}
+
+async function readPageState (port, pageId) {
+  const prop = await port.getContentProperty(pageId, PAGE_KEY)
+  return { state: (prop && prop.value) || null, prop }
+}
+
+async function writePageState (port, pageId, state, prop) {
+  await port.setContentProperty(pageId, PAGE_KEY, state, prop)
+}
+
+module.exports = { INDEX_KEY, PAGE_KEY, readIndex, writeIndex, readPageState, writePageState }

package/lib/tree.js

@@ -0,0 +1,154 @@
+'use strict'
+
+// Builds the desired Confluence page tree from a manifest. Each component
+// version's subtree is rooted at its own START PAGE (kind "home") — no
+// synthetic container pages — with that version's exports (PDFs) attached to
+// it. Component versions with no pages are skipped entirely unless they carry
+// exports (then a minimal "root" page holds the downloads). Confluence
+// requires unique page titles per space, so colliding titles get
+// deterministic suffixes; residual collisions are a hard error.
+
+function buildTree (manifest) {
+  const warnings = []
+  const nodes = []
+  const byKey = new Map()
+
+  const exportsFor = (component, version) =>
+    (manifest.exports || [])
+      .filter((e) => e.component === component && e.version === version)
+      .map((e) => ({ ...e, placeholderId: e.md5 }))
+
+  const groups = new Map()
+  for (const page of manifest.pages) {
+    const [component, version] = page.key.split(':')
+    const groupKey = `${component}@${version}`
+    if (!groups.has(groupKey)) groups.set(groupKey, [])
+    groups.get(groupKey).push(page)
+  }
+  const navByGroup = new Map(manifest.nav.map((n) => [`${n.component}@${n.version}`, n]))
+
+  // Page-less component versions: keep a minimal root only if there is
+  // something to download; otherwise they'd just be nav noise.
+  for (const navEntry of manifest.nav) {
+    const groupKey = `${navEntry.component}@${navEntry.version}`
+    if (groups.has(groupKey)) continue
+    const exports_ = exportsFor(navEntry.component, navEntry.version)
+    if (!exports_.length) continue
+    const node = { key: groupKey, kind: 'root', title: componentTitle(navEntry), parentKey: null, exports: exports_ }
+    nodes.push(node)
+    byKey.set(groupKey, node)
+  }
+
+  const homeByGroup = new Map()
+  const pending = []
+  for (const [groupKey, pages] of groups) {
+    const [component, version] = groupKey.split('@')
+    const navEntry = navByGroup.get(groupKey)
+    let home = navEntry && navEntry.startKey && pages.find((p) => p.key === navEntry.startKey)
+    if (!home) home = pages.find((p) => p.navOrder != null) || pages[0]
+    const homeNode = {
+      key: home.key,
+      kind: 'home',
+      // The subtree root represents the component: use the component title
+      // plus its version — the one place the version belongs.
+      title: componentTitle(navEntry || { component, version }),
+      parentKey: null,
+      page: home,
+      exports: exportsFor(component, version),
+    }
+    nodes.push(homeNode)
+    byKey.set(home.key, homeNode)
+    homeByGroup.set(groupKey, home.key)
+    for (const page of pages) {
+      if (page.key === home.key) continue
+      pending.push({
+        key: page.key,
+        kind: 'page',
+        title: page.title,
+        parentKey: page.parentKey && page.parentKey !== home.key ? page.parentKey : home.key,
+        page,
+      })
+    }
+  }
+
+  // Topological order: repeatedly take nodes whose parent is already placed.
+  const pendingKeys = new Set(pending.map((n) => n.key))
+  let remaining = pending
+  while (remaining.length) {
+    const ready = remaining.filter((n) => !pendingKeys.has(n.parentKey) && byKey.has(n.parentKey))
+    const stuck = remaining.filter((n) => !pendingKeys.has(n.parentKey) && !byKey.has(n.parentKey))
+    for (const node of stuck) {
+      // Dangling parentKey (e.g. parent filtered out): reattach to the home page.
+      const [component, version] = node.key.split(':')
+      warnings.push(`page "${node.key}" has an unresolvable parent "${node.parentKey}"; attaching to the component home page`)
+      node.parentKey = homeByGroup.get(`${component}@${version}`)
+      ready.push(node)
+    }
+    if (!ready.length) {
+      for (const node of remaining) {
+        const [component, version] = node.key.split(':')
+        warnings.push(`page "${node.key}" is in a parent cycle; attaching to the component home page`)
+        node.parentKey = homeByGroup.get(`${component}@${version}`)
+        pendingKeys.delete(node.key)
+        nodes.push(node)
+        byKey.set(node.key, node)
+      }
+      break
+    }
+    for (const node of ready) {
+      pendingKeys.delete(node.key)
+      nodes.push(node)
+      byKey.set(node.key, node)
+    }
+    remaining = remaining.filter((n) => pendingKeys.has(n.key))
+  }
+
+  disambiguateTitles(nodes)
+  return { nodes, warnings }
+}
+
+function componentTitle ({ component, version, displayVersion, title }) {
+  const base = title || component
+  const shownVersion = displayVersion || version
+  return shownVersion ? `${base} (${shownVersion})` : base
+}
+
+// Colliding child-page titles escalate gently: the component version scopes
+// the whole subtree, so the version only appears on a child when the same
+// component publishes several versions of the same page.
+function disambiguateTitles (nodes) {
+  const collide = () => {
+    const seen = new Map()
+    const dupes = new Set()
+    for (const node of nodes) {
+      if (seen.has(node.title)) dupes.add(node.title)
+      seen.set(node.title, node)
+    }
+    return dupes
+  }
+
+  const suffix = (node, tier) => {
+    const [component, version, , relative] = node.key.split(':')
+    if (!relative) return node.title
+    const base = node.originalTitle || node.title
+    const stem = relative.replace(/\.adoc$/, '').split('/').pop()
+    if (tier === 1) return `${base} (${component})`
+    if (tier === 2) return `${base} (${component}, ${stem})`
+    return `${base} (${component} ${version}, ${stem})`
+  }
+
+  for (const tier of [1, 2, 3]) {
+    const dupes = collide()
+    if (!dupes.size) return
+    for (const node of nodes) {
+      if (node.kind === 'page' && dupes.has(node.title)) {
+        node.originalTitle ??= node.title
+        node.title = suffix(node, tier)
+      }
+    }
+  }
+  const dupes = collide()
+  if (dupes.size) throw new Error(`unresolvable page title collision(s): ${[...dupes].join(', ')}`)
+}
+
+module.exports = buildTree

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@baiyibai-antora/confluence-publisher",
+  "version": "1.0.0-beta.1",
+  "description": "Publish an Antora ADF manifest (from @baiyibai-antora/adf-extension) to a Confluence Cloud space",
+  "license": "MIT",
+  "author": "baiyibai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/baiyibai-antora/confluora.git",
+    "directory": "packages/confluence-publisher"
+  },
+  "type": "commonjs",
+  "main": "lib/index.js",
+  "bin": {
+    "confluence-publish": "bin/confluence-publish.js"
+  },
+  "files": [
+    "lib",
+    "bin"
+  ],
+  "scripts": {
+    "test": "node --test test/*-test.js"
+  },
+  "keywords": [
+    "confluora",
+    "antora",
+    "confluence",
+    "adf",
+    "publisher"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://gitlab.com/baiyibai-antora/confluora",
+  "bugs": "https://gitlab.com/baiyibai-antora/confluora/-/issues"
+}