@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/lib/md2confluence-v3.py

@@ -0,0 +1,1076 @@
+#!/usr/bin/env python3
+"""
+md2confluence-v3.py
+
+Markdown to Confluence storage XML converter with v8.11.0 features:
+  - Multipart attachment upload (PNG screenshots)
+  - <ac:image ri:filename> injection from markdown image references
+  - Mermaid macro support with numbered-list fallback
+  - Footnote-style tooltips (^[text]) rendered as tooltip macro with fallback
+  - YAML front-matter parsing for backend metadata + labels
+  - Pre-conversion punctuation gate (em-dash, ellipsis, curly quotes, section sign)
+
+Usage:
+  md2confluence-v3.py create --space <SPACE> --parent-page-id <ID> --title "..." \
+      --markdown <path.md> [--attachments-dir <dir>] [--mermaid-fallback] [--dry-run]
+
+  md2confluence-v3.py update --page-id <ID> --title "..." \
+      --markdown <path.md> [--attachments-dir <dir>] [--mermaid-fallback] [--dry-run]
+
+Authentication:
+  CONFLUENCE_BASE_URL  - base URL, e.g. https://confluence.example.com
+  CONFLUENCE_USER      - user (informational; bearer token auth is used)
+  Token is resolved from ~/.claude/lib/credential-store.sh using the logical key
+  found in ~/.claude/multi-agent-preferences.json .global.keychainMapping.confluence
+  If that path fails, env CONFLUENCE_TOKEN is used as a fallback.
+
+Output:
+  JSON envelope on stdout describing what happened (page id, url, attachments,
+  fallbacks used, warnings, parsed front-matter).
+"""
+
+from __future__ import annotations
+
+import argparse
+import html
+import io
+import json
+import mimetypes
+import os
+import re
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+
+# ---------------------------------------------------------------------------
+# Punctuation gate
+# ---------------------------------------------------------------------------
+
+PUNCT_MAP_DEFAULT_TR = {
+    "\u2014": " - ",   # em-dash codepoint U+2014
+    "\u2013": "-",     # en-dash codepoint U+2013
+    "\u2026": "...",   # horizontal ellipsis codepoint U+2026
+    "\u201C": '"',     # curly double quote left codepoint U+201C
+    "\u201D": '"',     # curly double quote right codepoint U+201D
+    "\u2018": "'",     # curly single quote left codepoint U+2018
+    "\u2019": "'",     # curly single quote right codepoint U+2019
+    "\u00A7": "bolum", # section sign codepoint U+00A7 (TR fallback, plain ASCII)
+}
+
+PUNCT_MAP_EN = dict(PUNCT_MAP_DEFAULT_TR)
+PUNCT_MAP_EN["\u00A7"] = "section"
+
+
+def detect_language(markdown: str, front_matter_lang: str | None) -> str:
+    if front_matter_lang:
+        lang = front_matter_lang.lower()
+        if lang.startswith("en"):
+            return "en"
+        return "tr"
+    # Heuristic: presence of TR-only characters in headings
+    for line in markdown.splitlines():
+        if line.startswith("#"):
+            if re.search(r"[ğışçöü]", line):
+                return "tr"
+    return "tr"
+
+
+def apply_punctuation_gate(text: str, language: str) -> tuple[str, list[str]]:
+    mapping = PUNCT_MAP_EN if language == "en" else PUNCT_MAP_DEFAULT_TR
+    out = text
+    for src, dst in mapping.items():
+        out = out.replace(src, dst)
+
+    warnings: list[str] = []
+    leftover = [ch for ch in mapping.keys() if ch in out]
+    if leftover:
+        warnings.append(
+            "punctuation gate: residual forbidden characters: "
+            + " ".join(f"U+{ord(c):04X}" for c in leftover)
+        )
+    return out, warnings
+
+
+# ---------------------------------------------------------------------------
+# YAML front-matter (tiny subset parser - flat key: value pairs only)
+# ---------------------------------------------------------------------------
+
+FRONT_MATTER_RE = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)
+
+
+def parse_front_matter(text: str) -> tuple[dict[str, str], str]:
+    m = FRONT_MATTER_RE.match(text)
+    if not m:
+        return {}, text
+    block = m.group(1)
+    body = text[m.end():]
+    data: dict[str, str] = {}
+    for raw in block.splitlines():
+        if not raw.strip() or raw.lstrip().startswith("#"):
+            continue
+        if ":" not in raw:
+            continue
+        key, _, value = raw.partition(":")
+        key = key.strip()
+        value = value.strip().strip('"').strip("'")
+        if key:
+            data[key] = value
+    return data, body
+
+
+# ---------------------------------------------------------------------------
+# Mermaid blocks
+# ---------------------------------------------------------------------------
+
+MERMAID_FENCE_OPEN_RE = re.compile(r"^```mermaid\s*$")
+
+
+def mermaid_macro(body: str) -> str:
+    return (
+        '<ac:structured-macro ac:name="mermaid">'
+        f'<ac:plain-text-body><![CDATA[\n{body}\n]]></ac:plain-text-body>'
+        '</ac:structured-macro>'
+    )
+
+
+def mermaid_to_numbered_list(body: str) -> str:
+    """Best-effort flowchart node extraction for fallback rendering."""
+    nodes: list[str] = []
+    edges: list[tuple[str, str]] = []
+    node_label: dict[str, str] = {}
+    node_pattern = re.compile(r"([A-Za-z0-9_]+)\s*(?:\[([^\]]+)\]|\(([^)]+)\)|\{([^}]+)\})")
+    edge_pattern = re.compile(r"([A-Za-z0-9_]+)\s*-->\s*([A-Za-z0-9_]+)")
+
+    for raw in body.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("%%"):
+            continue
+        for em in edge_pattern.finditer(line):
+            a, b = em.group(1), em.group(2)
+            edges.append((a, b))
+            for nm in (a, b):
+                if nm not in node_label:
+                    node_label[nm] = nm
+                    nodes.append(nm)
+        for nm in node_pattern.finditer(line):
+            key = nm.group(1)
+            label = nm.group(2) or nm.group(3) or nm.group(4) or key
+            if key not in node_label:
+                node_label[key] = label
+                nodes.append(key)
+            else:
+                node_label[key] = label
+
+    if not nodes:
+        # Could not parse; emit as plain pre block
+        return f"<pre>{html.escape(body)}</pre>"
+
+    next_map: dict[str, list[str]] = {}
+    for a, b in edges:
+        next_map.setdefault(a, []).append(b)
+
+    items: list[str] = []
+    for idx, key in enumerate(nodes, start=1):
+        label = node_label[key]
+        nxt = next_map.get(key, [])
+        suffix = ""
+        if nxt:
+            suffix = " next: " + ", ".join(node_label.get(n, n) for n in nxt)
+        items.append(f"<li>{html.escape(label)}{html.escape(suffix)}</li>")
+    return "<ol>" + "".join(items) + "</ol>"
+
+
+# ---------------------------------------------------------------------------
+# Inline conversions
+# ---------------------------------------------------------------------------
+
+INLINE_CODE_RE = re.compile(r"`([^`\n]+)`")
+LINK_RE = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
+IMAGE_RE = re.compile(r"!\[([^\]]*)\]\(([^)]+)\)")
+BOLD_RE = re.compile(r"\*\*([^*\n]+)\*\*")
+ITALIC_RE = re.compile(r"(?<![\*\w])\*([^*\n]+)\*(?![\*\w])")
+FOOTNOTE_RE = re.compile(r"\^\[([^\]]+)\]")
+
+
+def esc(s: str) -> str:
+    return html.escape(s, quote=False)
+
+
+@dataclass
+class InlineContext:
+    attachments_available: set[str]
+    tooltip_macro_supported: bool
+    warnings: list[str] = field(default_factory=list)
+    tooltip_fallback_used: bool = False
+    images_referenced: list[str] = field(default_factory=list)
+
+
+def render_image(alt: str, src: str, ctx: InlineContext) -> str:
+    filename = os.path.basename(src)
+    # If src is an http(s) URL, render as external image link.
+    if re.match(r"^https?://", src):
+        return f'<a href="{html.escape(src, quote=True)}">{esc(alt) or esc(filename)}</a>'
+    ctx.images_referenced.append(filename)
+    if ctx.attachments_available and filename not in ctx.attachments_available:
+        ctx.warnings.append(f"image reference has no matching attachment: {filename}")
+        return f'<a href="{html.escape(src, quote=True)}">{esc(alt) or esc(filename)}</a>'
+    alt_attr = f' ac:alt="{html.escape(alt, quote=True)}"' if alt else ""
+    return (
+        f"<ac:image{alt_attr}>"
+        f'<ri:attachment ri:filename="{html.escape(filename, quote=True)}" />'
+        "</ac:image>"
+    )
+
+
+def render_footnote(text: str, ctx: InlineContext) -> str:
+    if ctx.tooltip_macro_supported:
+        return (
+            '<ac:structured-macro ac:name="tooltip">'
+            f'<ac:parameter ac:name="text">{esc(text)}</ac:parameter>'
+            '</ac:structured-macro>'
+        )
+    ctx.tooltip_fallback_used = True
+    return f" <em>({esc(text)})</em>"
+
+
+def inline(s: str, ctx: InlineContext) -> str:
+    # 1. Stash images first so their alt text is not treated as link.
+    image_segs: list[str] = []
+
+    def stash_image(m: re.Match[str]) -> str:
+        alt, src = m.group(1), m.group(2)
+        image_segs.append(render_image(alt, src, ctx))
+        return f"\x00IMG{len(image_segs) - 1}\x00"
+
+    s = IMAGE_RE.sub(stash_image, s)
+
+    # 2. Inline code.
+    code_segs: list[str] = []
+
+    def stash_code(m: re.Match[str]) -> str:
+        code_segs.append(m.group(1))
+        return f"\x00CODE{len(code_segs) - 1}\x00"
+
+    s = INLINE_CODE_RE.sub(stash_code, s)
+
+    # 3. Links.
+    link_segs: list[tuple[str, str]] = []
+
+    def stash_link(m: re.Match[str]) -> str:
+        link_segs.append((m.group(1), m.group(2)))
+        return f"\x00LINK{len(link_segs) - 1}\x00"
+
+    s = LINK_RE.sub(stash_link, s)
+
+    # 4. Footnotes (must run before HTML escape so the brackets survive).
+    footnote_segs: list[str] = []
+
+    def stash_footnote(m: re.Match[str]) -> str:
+        footnote_segs.append(render_footnote(m.group(1), ctx))
+        return f"\x00FN{len(footnote_segs) - 1}\x00"
+
+    s = FOOTNOTE_RE.sub(stash_footnote, s)
+
+    # 5. Escape, then bold/italic.
+    s = esc(s)
+    s = BOLD_RE.sub(lambda m: f"<strong>{m.group(1)}</strong>", s)
+    s = ITALIC_RE.sub(lambda m: f"<em>{m.group(1)}</em>", s)
+
+    # 6. Restore stash markers.
+    def restore_link(m: re.Match[str]) -> str:
+        idx = int(m.group(1))
+        label, url = link_segs[idx]
+        return f'<a href="{html.escape(url, quote=True)}">{esc(label)}</a>'
+
+    s = re.sub(r"\x00LINK(\d+)\x00", restore_link, s)
+    s = re.sub(r"\x00CODE(\d+)\x00", lambda m: f"<code>{esc(code_segs[int(m.group(1))])}</code>", s)
+    s = re.sub(r"\x00FN(\d+)\x00", lambda m: footnote_segs[int(m.group(1))], s)
+    s = re.sub(r"\x00IMG(\d+)\x00", lambda m: image_segs[int(m.group(1))], s)
+    return s
+
+
+# ---------------------------------------------------------------------------
+# Block-level conversion
+# ---------------------------------------------------------------------------
+
+def is_table_sep(line: str) -> bool:
+    s = line.strip()
+    if not s.startswith("|"):
+        return False
+    inner = s.strip("|").strip()
+    return all(re.match(r":?-{3,}:?", c.strip()) for c in inner.split("|"))
+
+
+@dataclass
+class ConvertResult:
+    storage_xml: str
+    mermaid_fallback_used: bool
+    tooltip_fallback_used: bool
+    images_referenced: list[str]
+    warnings: list[str]
+
+
+def markdown_to_storage(
+    markdown: str,
+    *,
+    attachments_available: set[str],
+    mermaid_fallback: bool,
+    tooltip_macro_supported: bool,
+) -> ConvertResult:
+    ctx = InlineContext(
+        attachments_available=attachments_available,
+        tooltip_macro_supported=tooltip_macro_supported,
+    )
+    lines = markdown.split("\n")
+    out: list[str] = []
+    i = 0
+    in_code = False
+    code_buf: list[str] = []
+    code_lang = ""
+    in_mermaid = False
+    mermaid_buf: list[str] = []
+    para_buf: list[str] = []
+    mermaid_fallback_used = False
+
+    def flush_para() -> None:
+        if not para_buf:
+            return
+        text = " ".join(para_buf).strip()
+        if text:
+            out.append(f"<p>{inline(text, ctx)}</p>")
+        para_buf.clear()
+
+    while i < len(lines):
+        line = lines[i]
+        stripped = line.strip()
+
+        # Mermaid fence
+        if MERMAID_FENCE_OPEN_RE.match(stripped):
+            flush_para()
+            in_mermaid = True
+            mermaid_buf = []
+            i += 1
+            continue
+        if in_mermaid:
+            if stripped == "```":
+                body = "\n".join(mermaid_buf)
+                if mermaid_fallback:
+                    mermaid_fallback_used = True
+                    out.append(mermaid_to_numbered_list(body))
+                else:
+                    out.append(mermaid_macro(body))
+                in_mermaid = False
+                mermaid_buf = []
+            else:
+                mermaid_buf.append(line)
+            i += 1
+            continue
+
+        # Generic code fence
+        if stripped.startswith("```"):
+            if not in_code:
+                in_code = True
+                code_lang = stripped[3:].strip() or "none"
+                code_buf = []
+            else:
+                in_code = False
+                body = "\n".join(code_buf)
+                flush_para()
+                out.append(
+                    '<ac:structured-macro ac:name="code">'
+                    f'<ac:parameter ac:name="language">{esc(code_lang)}</ac:parameter>'
+                    f'<ac:plain-text-body><![CDATA[{body}]]></ac:plain-text-body>'
+                    '</ac:structured-macro>'
+                )
+            i += 1
+            continue
+        if in_code:
+            code_buf.append(line)
+            i += 1
+            continue
+
+        # Horizontal rule
+        if stripped in ("---", "***", "___"):
+            flush_para()
+            out.append("<hr />")
+            i += 1
+            continue
+
+        # Headings
+        h = re.match(r"^(#{1,6})\s+(.*)$", stripped)
+        if h:
+            flush_para()
+            level = len(h.group(1))
+            out.append(f"<h{level}>{inline(h.group(2), ctx)}</h{level}>")
+            i += 1
+            continue
+
+        # Blockquote
+        if stripped.startswith("> "):
+            flush_para()
+            bq: list[str] = []
+            while i < len(lines) and lines[i].strip().startswith("> "):
+                bq.append(lines[i].strip()[2:])
+                i += 1
+            out.append(f"<blockquote><p>{inline(' '.join(bq), ctx)}</p></blockquote>")
+            continue
+
+        # Tables
+        if stripped.startswith("|") and i + 1 < len(lines) and is_table_sep(lines[i + 1]):
+            flush_para()
+            header = [c.strip() for c in stripped.strip("|").split("|")]
+            i += 2
+            rows: list[list[str]] = []
+            while i < len(lines) and lines[i].strip().startswith("|"):
+                rows.append([c.strip() for c in lines[i].strip().strip("|").split("|")])
+                i += 1
+            thead = "<thead><tr>" + "".join(f"<th>{inline(c, ctx)}</th>" for c in header) + "</tr></thead>"
+            tbody_rows = "".join(
+                "<tr>" + "".join(f"<td>{inline(c, ctx)}</td>" for c in r) + "</tr>" for r in rows
+            )
+            tbody = f"<tbody>{tbody_rows}</tbody>"
+            out.append(f"<table>{thead}{tbody}</table>")
+            continue
+
+        # Unordered list
+        if re.match(r"^\s*[-*]\s+", line):
+            flush_para()
+            items: list[str] = []
+            while i < len(lines) and re.match(r"^\s*[-*]\s+", lines[i]):
+                items.append(re.sub(r"^\s*[-*]\s+", "", lines[i]))
+                i += 1
+            body = "".join(f"<li>{inline(it, ctx)}</li>" for it in items)
+            out.append(f"<ul>{body}</ul>")
+            continue
+
+        # Ordered list
+        if re.match(r"^\s*\d+\.\s+", line):
+            flush_para()
+            items = []
+            while i < len(lines) and re.match(r"^\s*\d+\.\s+", lines[i]):
+                items.append(re.sub(r"^\s*\d+\.\s+", "", lines[i]))
+                i += 1
+            body = "".join(f"<li>{inline(it, ctx)}</li>" for it in items)
+            out.append(f"<ol>{body}</ol>")
+            continue
+
+        if stripped == "":
+            flush_para()
+        else:
+            para_buf.append(line)
+        i += 1
+
+    flush_para()
+    return ConvertResult(
+        storage_xml="".join(out),
+        mermaid_fallback_used=mermaid_fallback_used,
+        tooltip_fallback_used=ctx.tooltip_fallback_used,
+        images_referenced=ctx.images_referenced,
+        warnings=ctx.warnings,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Confluence HTTP helpers
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ConfluenceAuth:
+    base_url: str
+    token: str
+    user: str | None = None
+
+
+def resolve_token() -> str | None:
+    prefs_path = Path.home() / ".claude" / "multi-agent-preferences.json"
+    cred_script = Path.home() / ".claude" / "lib" / "credential-store.sh"
+    if prefs_path.exists() and cred_script.exists():
+        try:
+            with prefs_path.open(encoding="utf-8") as fh:
+                prefs = json.load(fh)
+            logical = (
+                prefs.get("global", {})
+                .get("keychainMapping", {})
+                .get("confluence")
+            )
+            if logical:
+                proc = subprocess.run(
+                    [str(cred_script), "get", str(logical)],
+                    capture_output=True,
+                    text=True,
+                    timeout=10,
+                )
+                token = (proc.stdout or "").strip()
+                if proc.returncode == 0 and token:
+                    return token
+        except (OSError, json.JSONDecodeError, subprocess.SubprocessError):
+            pass
+    return os.environ.get("CONFLUENCE_TOKEN") or None
+
+
+def resolve_auth() -> ConfluenceAuth:
+    base = os.environ.get("CONFLUENCE_BASE_URL", "").rstrip("/")
+    if not base:
+        sys.stderr.write("error: CONFLUENCE_BASE_URL is not set\n")
+        sys.exit(2)
+    token = resolve_token()
+    if not token:
+        sys.stderr.write(
+            "error: no Confluence token available (credential-store + "
+            "CONFLUENCE_TOKEN both empty)\n"
+        )
+        sys.exit(2)
+    return ConfluenceAuth(base_url=base, token=token, user=os.environ.get("CONFLUENCE_USER"))
+
+
+def _retry_http(fn: Callable[..., Any], *args: Any, max_attempts: int = 3, **kwargs: Any) -> Any:
+    """Generic retry wrapper for HTTP calls.
+
+    Retries on 5xx, 429, and transport URLError. Backoff: 1s, 2s, 4s.
+    HTTPError with 4xx status codes (other than 429) propagates immediately so
+    Confluence-level error semantics (e.g. mermaid macro missing) remain
+    actionable at the call site.
+    """
+    last_exc: Exception | None = None
+    for attempt in range(max_attempts):
+        try:
+            return fn(*args, **kwargs)
+        except urllib.error.HTTPError as e:
+            if e.code >= 500 or e.code == 429:
+                if attempt < max_attempts - 1:
+                    time.sleep(2 ** attempt)
+                    last_exc = e
+                    continue
+            raise
+        except urllib.error.URLError as e:
+            if attempt < max_attempts - 1:
+                time.sleep(2 ** attempt)
+                last_exc = e
+                continue
+            raise
+    if last_exc:
+        raise last_exc
+    raise RuntimeError("_retry_http: unreachable")
+
+
+def http_json(
+    auth: ConfluenceAuth,
+    method: str,
+    path: str,
+    payload: dict | list | None = None,
+) -> tuple[int, dict | list | None, str]:
+    url = f"{auth.base_url}{path}"
+    data = json.dumps(payload).encode("utf-8") if payload is not None else None
+    req = urllib.request.Request(
+        url,
+        data=data,
+        method=method,
+        headers={
+            "Authorization": f"Bearer {auth.token}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        },
+    )
+
+    def _do() -> tuple[int, dict | list | None, str]:
+        with urllib.request.urlopen(req) as resp:
+            body = resp.read().decode("utf-8")
+            return resp.status, (json.loads(body) if body else None), body
+
+    try:
+        return _retry_http(_do)
+    except urllib.error.HTTPError as e:
+        body = ""
+        try:
+            body = e.read().decode("utf-8", errors="replace")
+        except Exception:
+            pass
+        return e.code, None, body
+    except urllib.error.URLError as e:
+        # All retries exhausted; surface as a synthetic 0 status so callers
+        # treat it as a hard failure without crashing.
+        return 0, None, f"URLError: {e.reason}"
+
+
+def build_multipart(files: list[tuple[str, bytes, str]]) -> tuple[bytes, str]:
+    boundary = f"----md2confluence-{uuid.uuid4().hex}"
+    buf = io.BytesIO()
+    for field_name, content, filename in files:
+        ctype, _ = mimetypes.guess_type(filename)
+        ctype = ctype or "application/octet-stream"
+        buf.write(f"--{boundary}\r\n".encode("utf-8"))
+        buf.write(
+            (
+                f'Content-Disposition: form-data; name="{field_name}"; '
+                f'filename="{filename}"\r\n'
+            ).encode("utf-8")
+        )
+        buf.write(f"Content-Type: {ctype}\r\n\r\n".encode("utf-8"))
+        buf.write(content)
+        buf.write(b"\r\n")
+    buf.write(f"--{boundary}--\r\n".encode("utf-8"))
+    return buf.getvalue(), f"multipart/form-data; boundary={boundary}"
+
+
+def upload_attachment(
+    auth: ConfluenceAuth,
+    page_id: str,
+    file_path: Path,
+) -> tuple[bool, str]:
+    """Attach file to page. Uses POST .../child/attachment, which overwrites if
+    Confluence is configured to accept the same filename. Wrapped in retry so
+    transient 5xx/429/network errors recover before the call site sees them."""
+    data = file_path.read_bytes()
+    body, content_type = build_multipart([("file", data, file_path.name)])
+    url = f"{auth.base_url}/rest/api/content/{page_id}/child/attachment"
+    req = urllib.request.Request(
+        url,
+        data=body,
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {auth.token}",
+            "Content-Type": content_type,
+            "X-Atlassian-Token": "no-check",
+            "Accept": "application/json",
+        },
+    )
+
+    def _do() -> tuple[bool, str]:
+        with urllib.request.urlopen(req) as resp:
+            resp.read()
+            return True, "ok"
+
+    try:
+        return _retry_http(_do)
+    except urllib.error.HTTPError as e:
+        # If attachment already exists, retry against the existing attachment id.
+        if e.code == 400:
+            err_body = ""
+            try:
+                err_body = e.read().decode("utf-8", errors="replace")
+            except Exception:
+                pass
+            existing = find_existing_attachment(auth, page_id, file_path.name)
+            if existing:
+                ok, msg = update_attachment_data(auth, page_id, existing, file_path)
+                return ok, msg
+            return False, f"HTTP 400: {err_body[:300]}"
+        return False, f"HTTP {e.code}"
+    except urllib.error.URLError as e:
+        return False, f"URLError: {e.reason}"
+
+
+def upload_attachments_parallel(
+    auth: ConfluenceAuth,
+    page_id: str,
+    attachments: dict[str, Path],
+    max_workers: int = 4,
+) -> tuple[int, list[str]]:
+    """Upload many attachments concurrently via a small thread pool.
+
+    Returns (success_count, warning_messages). Sequential ordering is not
+    preserved (the prior implementation processed `sorted(referenced)`), but
+    that ordering had no semantic meaning - it was just deterministic for
+    debugging. The thread pool keeps per-task retry semantics intact via
+    upload_attachment().
+    """
+    if not attachments:
+        return 0, []
+    warnings: list[str] = []
+    uploaded = 0
+    workers = max(1, min(max_workers, len(attachments)))
+    with ThreadPoolExecutor(max_workers=workers) as executor:
+        future_to_name = {
+            executor.submit(upload_attachment, auth, page_id, file_path): name
+            for name, file_path in attachments.items()
+        }
+        for future in as_completed(future_to_name):
+            name = future_to_name[future]
+            try:
+                ok, msg = future.result()
+                if ok:
+                    uploaded += 1
+                else:
+                    warnings.append(f"attachment upload failed for {name}: {msg}")
+            except Exception as e:
+                warnings.append(f"attachment upload exception for {name}: {e}")
+    return uploaded, warnings
+
+
+def find_existing_attachment(
+    auth: ConfluenceAuth, page_id: str, filename: str
+) -> str | None:
+    status, body, _ = http_json(
+        auth,
+        "GET",
+        f"/rest/api/content/{page_id}/child/attachment?filename="
+        + urllib.parse.quote(filename),
+    )
+    if status == 200 and isinstance(body, dict):
+        results = body.get("results") or []
+        if results:
+            return results[0].get("id")
+    return None
+
+
+def update_attachment_data(
+    auth: ConfluenceAuth,
+    page_id: str,
+    attachment_id: str,
+    file_path: Path,
+) -> tuple[bool, str]:
+    data = file_path.read_bytes()
+    body, content_type = build_multipart([("file", data, file_path.name)])
+    url = (
+        f"{auth.base_url}/rest/api/content/{page_id}/child/attachment/"
+        f"{attachment_id}/data"
+    )
+    req = urllib.request.Request(
+        url,
+        data=body,
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {auth.token}",
+            "Content-Type": content_type,
+            "X-Atlassian-Token": "no-check",
+            "Accept": "application/json",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req) as resp:
+            resp.read()
+            return True, "updated"
+    except urllib.error.HTTPError as e:
+        return False, f"HTTP {e.code}"
+
+
+def add_labels(auth: ConfluenceAuth, page_id: str, labels: list[str]) -> list[str]:
+    if not labels:
+        return []
+    payload = [{"prefix": "global", "name": label} for label in labels]
+    status, _, body = http_json(
+        auth, "POST", f"/rest/api/content/{page_id}/label", payload
+    )
+    if status not in (200, 201, 204):
+        return [f"label POST returned {status}: {body[:200]}"]
+    return []
+
+
+def page_web_url(auth: ConfluenceAuth, page: dict | None, page_id: str) -> str:
+    if isinstance(page, dict):
+        web = page.get("_links", {}).get("webui")
+        if web:
+            return f"{auth.base_url}{web}"
+    return f"{auth.base_url}/pages/viewpage.action?pageId={page_id}"
+
+
+# ---------------------------------------------------------------------------
+# Attachment discovery
+# ---------------------------------------------------------------------------
+
+def collect_attachments(attachments_dir: Path | None) -> dict[str, Path]:
+    if not attachments_dir:
+        return {}
+    if not attachments_dir.is_dir():
+        return {}
+    found: dict[str, Path] = {}
+    for path in sorted(attachments_dir.iterdir()):
+        if path.is_file() and path.suffix.lower() in {".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp"}:
+            found[path.name] = path
+    return found
+
+
+# ---------------------------------------------------------------------------
+# Mermaid macro detection (post-publish error handling)
+# ---------------------------------------------------------------------------
+
+def looks_like_macro_missing(error_body: str, macro_name: str) -> bool:
+    needle = error_body.lower()
+    return (
+        macro_name in needle
+        and (
+            "unknown macro" in needle
+            or "macro not found" in needle
+            or "no such macro" in needle
+        )
+    )
+
+
+# ---------------------------------------------------------------------------
+# Build a publish-ready storage XML pipeline
+# ---------------------------------------------------------------------------
+
+def build_storage(
+    markdown_text: str,
+    *,
+    attachments_dir: Path | None,
+    mermaid_fallback: bool,
+    tooltip_macro_supported: bool = True,
+) -> tuple[ConvertResult, dict[str, str], dict[str, Path], list[str]]:
+    front_matter, body = parse_front_matter(markdown_text)
+    language = detect_language(body, front_matter.get("language"))
+    body, punct_warnings = apply_punctuation_gate(body, language)
+    attachments = collect_attachments(attachments_dir)
+    result = markdown_to_storage(
+        body,
+        attachments_available=set(attachments.keys()),
+        mermaid_fallback=mermaid_fallback,
+        tooltip_macro_supported=tooltip_macro_supported,
+    )
+    result.warnings = punct_warnings + result.warnings
+    return result, front_matter, attachments, []
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+def cmd_create(args: argparse.Namespace) -> int:
+    md_text = Path(args.markdown).read_text(encoding="utf-8")
+    attachments_dir = Path(args.attachments_dir) if args.attachments_dir else None
+    result, front_matter, attachments, _ = build_storage(
+        md_text,
+        attachments_dir=attachments_dir,
+        mermaid_fallback=args.mermaid_fallback,
+    )
+
+    if args.dry_run:
+        sys.stdout.write(result.storage_xml + "\n")
+        envelope = {
+            "front_matter": front_matter,
+            "page_id": None,
+            "page_url": None,
+            "attachments_uploaded": 0,
+            "attachments_available": len(attachments),
+            "mermaid_macro_fallback_used": result.mermaid_fallback_used,
+            "tooltip_macro_fallback_used": result.tooltip_fallback_used,
+            "warnings": result.warnings,
+            "dry_run": True,
+        }
+        sys.stderr.write(json.dumps(envelope, indent=2, ensure_ascii=False) + "\n")
+        return 0
+
+    auth = resolve_auth()
+    warnings = list(result.warnings)
+
+    # 1. Create the page with current storage body.
+    create_payload = {
+        "type": "page",
+        "title": args.title,
+        "ancestors": [{"id": args.parent_page_id}],
+        "space": {"key": args.space},
+        "body": {"storage": {"value": result.storage_xml, "representation": "storage"}},
+    }
+    status, body, raw = http_json(auth, "POST", "/rest/api/content", create_payload)
+
+    # Retry with mermaid fallback if the macro isn't installed.
+    if status >= 400 and not args.mermaid_fallback and looks_like_macro_missing(raw, "mermaid"):
+        warnings.append("mermaid macro missing; retrying with numbered-list fallback")
+        result, front_matter, attachments, _ = build_storage(
+            md_text,
+            attachments_dir=attachments_dir,
+            mermaid_fallback=True,
+        )
+        create_payload["body"]["storage"]["value"] = result.storage_xml
+        status, body, raw = http_json(auth, "POST", "/rest/api/content", create_payload)
+
+    if status >= 400 or not isinstance(body, dict):
+        sys.stderr.write(f"create failed: HTTP {status}\n{raw[:600]}\n")
+        return 2
+    page_id = str(body.get("id"))
+    page_url = page_web_url(auth, body, page_id)
+
+    # 2. Upload attachments referenced by markdown - parallel thread pool.
+    uploaded = 0
+    if attachments and result.images_referenced:
+        to_upload = {
+            name: attachments[name]
+            for name in result.images_referenced
+            if name in attachments
+        }
+        if to_upload:
+            uploaded, upload_warnings = upload_attachments_parallel(auth, page_id, to_upload)
+            warnings.extend(upload_warnings)
+
+    # 3. Apply labels from front matter.
+    labels = build_labels(front_matter)
+    label_errors = add_labels(auth, page_id, labels)
+    warnings.extend(label_errors)
+
+    envelope = {
+        "front_matter": front_matter,
+        "page_id": page_id,
+        "page_url": page_url,
+        "attachments_uploaded": uploaded,
+        "attachments_available": len(attachments),
+        "mermaid_macro_fallback_used": result.mermaid_fallback_used,
+        "tooltip_macro_fallback_used": result.tooltip_fallback_used,
+        "warnings": warnings,
+    }
+    sys.stdout.write(json.dumps(envelope, indent=2, ensure_ascii=False) + "\n")
+    return 0
+
+
+def cmd_update(args: argparse.Namespace) -> int:
+    md_text = Path(args.markdown).read_text(encoding="utf-8")
+    attachments_dir = Path(args.attachments_dir) if args.attachments_dir else None
+    result, front_matter, attachments, _ = build_storage(
+        md_text,
+        attachments_dir=attachments_dir,
+        mermaid_fallback=args.mermaid_fallback,
+    )
+
+    if args.dry_run:
+        sys.stdout.write(result.storage_xml + "\n")
+        envelope = {
+            "front_matter": front_matter,
+            "page_id": args.page_id,
+            "page_url": None,
+            "attachments_uploaded": 0,
+            "attachments_available": len(attachments),
+            "mermaid_macro_fallback_used": result.mermaid_fallback_used,
+            "tooltip_macro_fallback_used": result.tooltip_fallback_used,
+            "warnings": result.warnings,
+            "dry_run": True,
+        }
+        sys.stderr.write(json.dumps(envelope, indent=2, ensure_ascii=False) + "\n")
+        return 0
+
+    auth = resolve_auth()
+    warnings = list(result.warnings)
+
+    # Fetch current version.
+    status, body, raw = http_json(
+        auth, "GET", f"/rest/api/content/{args.page_id}?expand=version"
+    )
+    if status >= 400 or not isinstance(body, dict):
+        sys.stderr.write(f"fetch failed: HTTP {status}\n{raw[:600]}\n")
+        return 2
+    current_version = int(body.get("version", {}).get("number", 1))
+    new_version = current_version + 1
+
+    update_payload = {
+        "id": args.page_id,
+        "type": "page",
+        "title": args.title,
+        "version": {"number": new_version},
+        "body": {"storage": {"value": result.storage_xml, "representation": "storage"}},
+    }
+    status, body, raw = http_json(
+        auth, "PUT", f"/rest/api/content/{args.page_id}", update_payload
+    )
+
+    if status >= 400 and not args.mermaid_fallback and looks_like_macro_missing(raw, "mermaid"):
+        warnings.append("mermaid macro missing; retrying with numbered-list fallback")
+        result, front_matter, attachments, _ = build_storage(
+            md_text,
+            attachments_dir=attachments_dir,
+            mermaid_fallback=True,
+        )
+        update_payload["body"]["storage"]["value"] = result.storage_xml
+        status, body, raw = http_json(
+            auth, "PUT", f"/rest/api/content/{args.page_id}", update_payload
+        )
+
+    if status >= 400 or not isinstance(body, dict):
+        sys.stderr.write(f"update failed: HTTP {status}\n{raw[:600]}\n")
+        return 2
+
+    page_id = str(body.get("id") or args.page_id)
+    page_url = page_web_url(auth, body, page_id)
+
+    uploaded = 0
+    if attachments and result.images_referenced:
+        to_upload = {
+            name: attachments[name]
+            for name in result.images_referenced
+            if name in attachments
+        }
+        if to_upload:
+            uploaded, upload_warnings = upload_attachments_parallel(auth, page_id, to_upload)
+            warnings.extend(upload_warnings)
+
+    labels = build_labels(front_matter)
+    label_errors = add_labels(auth, page_id, labels)
+    warnings.extend(label_errors)
+
+    envelope = {
+        "front_matter": front_matter,
+        "page_id": page_id,
+        "page_url": page_url,
+        "attachments_uploaded": uploaded,
+        "attachments_available": len(attachments),
+        "mermaid_macro_fallback_used": result.mermaid_fallback_used,
+        "tooltip_macro_fallback_used": result.tooltip_fallback_used,
+        "warnings": warnings,
+    }
+    sys.stdout.write(json.dumps(envelope, indent=2, ensure_ascii=False) + "\n")
+    return 0
+
+
+def build_labels(front_matter: dict[str, str]) -> list[str]:
+    labels: list[str] = []
+    for key in ("feature", "platform", "evidence_digest"):
+        value = front_matter.get(key)
+        if not value:
+            continue
+        normalized = re.sub(r"[^A-Za-z0-9_-]", "-", value)[:60].strip("-").lower()
+        if normalized:
+            labels.append(f"{key}-{normalized}")
+    return labels
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="md2confluence-v3.py",
+        description=(
+            "Convert markdown to Confluence storage XML and create or update a page. "
+            "Supports attachment upload, mermaid macro, tooltip macro, and YAML "
+            "front-matter labels."
+        ),
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    create = sub.add_parser("create", help="Create a new Confluence page")
+    create.add_argument("--space", required=True)
+    create.add_argument("--parent-page-id", required=True)
+    create.add_argument("--title", required=True)
+    create.add_argument("--markdown", required=True)
+    create.add_argument("--attachments-dir")
+    create.add_argument("--mermaid-fallback", action="store_true")
+    create.add_argument("--dry-run", action="store_true")
+    create.set_defaults(func=cmd_create)
+
+    update = sub.add_parser("update", help="Update an existing Confluence page")
+    update.add_argument("--page-id", required=True)
+    update.add_argument("--title", required=True)
+    update.add_argument("--markdown", required=True)
+    update.add_argument("--attachments-dir")
+    update.add_argument("--mermaid-fallback", action="store_true")
+    update.add_argument("--dry-run", action="store_true")
+    update.set_defaults(func=cmd_update)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())