@repo-toolkit/confluence 0.8.0 → 0.11.0

package/index.js

@@ -1,22 +1,39 @@
 // src/index.ts
 import { readFileSync as readFileSync2 } from "fs";
 import { dirname, isAbsolute as isAbsolute2, resolve as resolve2 } from "path";
-import { parseFlags, resolveCliOptions, isPlainObject } from "@repo-toolkit/publish-package";
 
 // src/confluence-client.ts
 import { Buffer } from "buffer";
-import { readFileSync } from "fs";
+import { randomBytes } from "crypto";
+import { statSync, createReadStream } from "fs";
 import { basename } from "path";
+import { Readable } from "stream";
 var V2_PATH = "/api/v2";
 var V1_PATH = "/rest/api";
 var DEFAULT_USER_AGENT = "repo-toolkit-confluence/1.0 (+node)";
 var MAX_LIMIT = 250;
+var MAX_ERROR_BODY_LENGTH = 8192;
+var MAX_PAGES_PER_QUERY = 100;
+var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
+var SAFE_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS"]);
+var ConfluenceUploadError = class extends Error {
+  constructor(message, status, endpoint, responseBody) {
+    super(`${message} (status=${status}, endpoint=${endpoint})`);
+    this.name = "ConfluenceUploadError";
+    this.status = status;
+    this.endpoint = endpoint;
+    this.responseBody = responseBody;
+  }
+};
 var STATUS_CODES = {
   BAD_REQUEST: 400,
   UNAUTHORIZED: 401,
   FORBIDDEN: 403,
   NOT_FOUND: 404,
-  CONFLICT: 409
+  CONFLICT: 409,
+  TOO_MANY_REQUESTS: 429
 };
 var ConfluenceApiError = class extends Error {
   constructor(message, status, endpoint, responseBody) {
@@ -35,10 +52,15 @@ var ConfluenceClient = class {
     if (!options.username || !options.apiToken) {
       throw new Error("ConfluenceClient: username and apiToken are required");
     }
-    this.baseUrl = normalizeBaseUrl(options.baseUrl);
+    const normalized = normalizeBaseUrl(options.baseUrl);
+    this.baseUrl = normalized;
+    this.baseUrlOrigin = new URL(normalized).origin;
     this.authHeader = "Basic " + Buffer.from(`${options.username}:${options.apiToken}`, "utf8").toString("base64");
     this.fetchFn = options.fetch ?? globalThis.fetch;
     this.userAgent = options.userAgent ?? DEFAULT_USER_AGENT;
+    this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.maxUploadBytes = options.maxUploadBytes ?? DEFAULT_MAX_UPLOAD_BYTES;
   }
   async getSpaceIdByKey(spaceKey) {
     const query = new URLSearchParams({ keys: spaceKey, limit: "1" });
@@ -52,17 +74,33 @@ var ConfluenceClient = class {
     }
     return result.id;
   }
-  async getPageByTitle(spaceId, title) {
-    const query = new URLSearchParams({
-      "space-id": spaceId,
-      title,
-      limit: "1",
-      "body-format": "storage"
-    });
-    const data = await this.requestJson(this.v2Url(`/pages?${query.toString()}`), {
-      method: "GET"
-    });
-    return data.results[0];
+  async getPagesByTitle(spaceId, title) {
+    const pages = [];
+    const visited = /* @__PURE__ */ new Set();
+    let pageCount = 0;
+    const startUrl = this.v2Url(
+      `/pages?${new URLSearchParams({
+        "space-id": spaceId,
+        title,
+        limit: String(MAX_LIMIT),
+        "body-format": "storage"
+      }).toString()}`
+    );
+    let nextUrl = startUrl;
+    while (nextUrl) {
+      pageCount += 1;
+      if (pageCount > MAX_PAGES_PER_QUERY) {
+        throw new ConfluenceApiError(`Pagination limit (${MAX_PAGES_PER_QUERY}) exceeded`, 0, nextUrl, "");
+      }
+      if (visited.has(nextUrl)) {
+        throw new ConfluenceApiError("Confluence pagination loop detected", 0, nextUrl, "");
+      }
+      visited.add(nextUrl);
+      const data = await this.requestJson(nextUrl, { method: "GET" });
+      pages.push(...data.results);
+      nextUrl = resolveNextUrl(this.baseUrl, this.baseUrlOrigin, data._links?.next);
+    }
+    return pages;
   }
   async getPage(pageId) {
     return this.requestJson(this.v2Url(`/pages/${encodeURIComponent(pageId)}?body-format=storage`), {
@@ -105,89 +143,182 @@ var ConfluenceClient = class {
   }
   async getAttachments(pageId) {
     const results = [];
-    let cursor;
-    do {
-      const query = new URLSearchParams({ limit: String(MAX_LIMIT) });
-      if (cursor) {
-        query.set("cursor", cursor);
-      }
-      const data = await this.requestJson(
-        this.v2Url(`/pages/${encodeURIComponent(pageId)}/attachments?${query.toString()}`),
-        { method: "GET" }
-      );
+    const visited = /* @__PURE__ */ new Set();
+    let pageCount = 0;
+    let nextUrl = this.v2Url(
+      `/pages/${encodeURIComponent(pageId)}/attachments?${new URLSearchParams({
+        limit: String(MAX_LIMIT)
+      }).toString()}`
+    );
+    while (nextUrl) {
+      pageCount += 1;
+      if (pageCount > MAX_PAGES_PER_QUERY) {
+        throw new ConfluenceApiError(`Pagination limit (${MAX_PAGES_PER_QUERY}) exceeded`, 0, nextUrl, "");
+      }
+      if (visited.has(nextUrl)) {
+        throw new ConfluenceApiError("Confluence pagination loop detected", 0, nextUrl, "");
+      }
+      visited.add(nextUrl);
+      const data = await this.requestJson(nextUrl, {
+        method: "GET"
+      });
       for (const item of data.results) {
         results.push(item);
       }
-      cursor = data._links?.next;
-    } while (cursor);
+      nextUrl = resolveNextUrl(this.baseUrl, this.baseUrlOrigin, data._links?.next);
+    }
     return results;
   }
-  async uploadAttachment(pageId, filePath, comment) {
-    return this.sendAttachmentMultipart(pageId, void 0, filePath, comment);
+  async uploadAttachment(pageId, filePath, comment, filename) {
+    return this.sendAttachmentMultipart(pageId, void 0, filePath, comment, filename);
   }
-  async updateAttachmentData(pageId, attachmentId, filePath, comment) {
-    return this.sendAttachmentMultipart(pageId, attachmentId, filePath, comment);
+  async updateAttachmentData(pageId, attachmentId, filePath, comment, filename) {
+    return this.sendAttachmentMultipart(pageId, attachmentId, filePath, comment, filename);
   }
-  async sendAttachmentMultipart(pageId, attachmentId, filePath, comment) {
-    const fileBuffer = readFileSync(filePath);
-    const filename = basename(filePath);
-    const boundary = "----repo-toolkit-confluence-" + Math.random().toString(16).slice(2);
-    const parts = [];
-    parts.push(multipartField(boundary, "file", filename, fileBuffer));
-    if (comment) {
-      parts.push(multipartField(boundary, "comment", void 0, Buffer.from(comment, "utf8")));
+  async sendAttachmentMultipart(pageId, attachmentId, filePath, comment, filenameOverride) {
+    const info = statSync(filePath);
+    if (!info.isFile()) {
+      throw new ConfluenceApiError(`Attachment source must be a regular file: ${filePath}`, 0, filePath, "");
     }
-    parts.push(Buffer.from(`--${boundary}--\r
-`));
+    if (info.size > this.maxUploadBytes) {
+      throw new ConfluenceApiError(
+        `Attachment exceeds upload size limit (${this.maxUploadBytes} bytes): ${filePath}`,
+        0,
+        filePath,
+        ""
+      );
+    }
+    const filename = sanitizeFilename(filenameOverride ?? basename(filePath));
     const endpoint = attachmentId ? this.v1Url(`/content/${encodeURIComponent(pageId)}/child/attachment/${encodeURIComponent(attachmentId)}/data`) : this.v1Url(`/content/${encodeURIComponent(pageId)}/child/attachment`);
-    const data = await this.requestJson(endpoint, {
-      method: "POST",
-      headers: {
-        "Content-Type": `multipart/form-data; boundary=${boundary}`,
-        "X-Atlassian-Token": "no-check"
-      },
-      body: Buffer.concat(parts)
-    });
-    return normalizeAttachmentResult(data);
+    const boundary = "----repo-toolkit-confluence-" + randomBytes(16).toString("hex");
+    const fileStream = createReadStream(filePath);
+    const commentBuffer = comment ? multipartField(boundary, "comment", void 0, Buffer.from(comment, "utf8")) : null;
+    const body = Readable.from(
+      (async function* () {
+        const fileHeader = Buffer.from(
+          `--${boundary}\r
+Content-Disposition: form-data; name="file"; filename="${filename}"\r
+Content-Type: application/octet-stream\r
+\r
+`,
+          "utf8"
+        );
+        yield fileHeader;
+        for await (const chunk of fileStream) {
+          yield Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        }
+        yield Buffer.from("\r\n", "utf8");
+        if (commentBuffer) {
+          yield commentBuffer;
+        }
+        yield Buffer.from(`--${boundary}--\r
+`, "utf8");
+      })()
+    );
+    try {
+      const data = await this.requestJson(endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": `multipart/form-data; boundary=${boundary}`,
+          "X-Atlassian-Token": "no-check"
+        },
+        body,
+        uploadKind: "attachment",
+        contentTypeExplicit: true
+      });
+      return normalizeAttachmentResult(data);
+    } catch (cause) {
+      if (cause instanceof ConfluenceApiError) {
+        const status = cause.status;
+        if (status === STATUS_CODES.UNAUTHORIZED || status === STATUS_CODES.FORBIDDEN || status === STATUS_CODES.TOO_MANY_REQUESTS || status >= 500) {
+          const uploadErr = new ConfluenceUploadError(cause.message, status, cause.endpoint, cause.responseBody);
+          uploadErr.stack = cause.stack;
+          throw uploadErr;
+        }
+      }
+      throw cause;
+    }
   }
   async requestJson(endpoint, init) {
+    void init.uploadKind;
+    void init.contentTypeExplicit;
     const headers = {
       Authorization: this.authHeader,
       Accept: "application/json",
       "User-Agent": this.userAgent
     };
-    if (init.headers) {
-      for (const [k, v] of Object.entries(init.headers)) {
-        headers[k] = v;
+    for (const [k, v] of Object.entries(init.headers ?? {})) {
+      headers[k] = v;
+    }
+    const method = init.method.toUpperCase();
+    const isSafe = SAFE_METHODS.has(method);
+    const maxRetries = isSafe ? this.maxRetries : 0;
+    let attempt = 0;
+    let lastError;
+    while (attempt <= maxRetries) {
+      const signal = this.makeTimeoutSignal();
+      try {
+        const response = await this.fetchFn(endpoint, {
+          method,
+          headers,
+          body: init.body,
+          redirect: "manual",
+          signal
+        });
+        if (response.status >= 300 && response.status < 400) {
+          throw new ConfluenceApiError("Redirect responses are not allowed", response.status, endpoint, "");
+        }
+        const text = await readBodyBounded(response, MAX_ERROR_BODY_LENGTH);
+        if (!response.ok) {
+          if (isSafe && shouldRetryStatus(response.status) && attempt < maxRetries) {
+            attempt += 1;
+            lastError = new ConfluenceApiError(describeStatus(response.status), response.status, endpoint, text);
+            await sleepBackoff(response, endpoint);
+            continue;
+          }
+          throw new ConfluenceApiError(describeStatus(response.status), response.status, endpoint, text);
+        }
+        if (text.length === 0) {
+          return {};
+        }
+        try {
+          return JSON.parse(text);
+        } catch {
+          throw new ConfluenceApiError("Response was not valid JSON", response.status, endpoint, text);
+        }
+      } catch (cause) {
+        if (cause instanceof ConfluenceApiError || cause instanceof ConfluenceUploadError) {
+          throw cause;
+        }
+        const reason = cause instanceof Error ? cause : void 0;
+        if (isSafe && reason && reason.name !== "AbortError" && attempt < maxRetries) {
+          attempt += 1;
+          lastError = cause;
+          await sleepBackoff(void 0, endpoint, reason);
+          continue;
+        }
+        throw new ConfluenceApiError(reason ? `Network error: ${reason.message}` : "Network error", 0, endpoint, "");
       }
     }
-    let response;
-    try {
-      response = await this.fetchFn(endpoint, {
-        method: init.method,
-        headers,
-        body: init.body
-      });
-    } catch (cause) {
-      throw new ConfluenceApiError(
-        cause instanceof Error ? `Network error: ${cause.message}` : "Network error",
-        0,
-        endpoint,
-        ""
-      );
+    if (lastError instanceof Error) {
+      throw new ConfluenceApiError(`Network error: ${lastError.message}`, 0, endpoint, "");
     }
-    const text = await response.text();
-    if (!response.ok) {
-      throw new ConfluenceApiError(describeStatus(response.status), response.status, endpoint, text);
+    throw new ConfluenceApiError("Network error", 0, endpoint, "");
+  }
+  makeTimeoutSignal() {
+    const ms = this.requestTimeoutMs;
+    if (ms <= 0) {
+      return new AbortController().signal;
     }
-    if (text.length === 0) {
-      return {};
+    if (typeof AbortSignal.timeout === "function") {
+      return AbortSignal.timeout(ms);
     }
-    try {
-      return JSON.parse(text);
-    } catch {
-      throw new ConfluenceApiError("Response was not valid JSON", response.status, endpoint, text);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error(`Request timed out after ${ms}ms`)), ms);
+    if (typeof timer.unref === "function") {
+      timer.unref();
     }
+    return controller.signal;
   }
   v2Url(path) {
     return this.baseUrl + V2_PATH + path;
@@ -196,6 +327,102 @@ var ConfluenceClient = class {
     return this.baseUrl + V1_PATH + path;
   }
 };
+function shouldRetryStatus(status) {
+  return status === STATUS_CODES.TOO_MANY_REQUESTS || status >= 500;
+}
+async function sleepBackoff(response, endpoint, cause) {
+  let delayMs = 0;
+  if (response) {
+    const retryAfter = response.headers.get("Retry-After");
+    if (retryAfter) {
+      delayMs = parseRetryAfter(retryAfter, endpoint);
+    }
+  }
+  if (delayMs <= 0) {
+    const base = cause ? 200 : 500;
+    const jitter = Math.floor(Math.random() * 250);
+    delayMs = base + jitter;
+  }
+  const boundedDelay = Math.min(delayMs, 3e4);
+  await delay(boundedDelay);
+}
+function parseRetryAfter(value, endpoint) {
+  if (!value) {
+    return 0;
+  }
+  if (/^\d+$/.test(value.trim())) {
+    const seconds = Number(value);
+    if (!Number.isFinite(seconds) || seconds < 0) {
+      return 0;
+    }
+    return Math.min(seconds * 1e3, 3e4);
+  }
+  const date = Date.parse(value);
+  if (!Number.isNaN(date)) {
+    return Math.max(0, Math.min(date - Date.now(), 3e4));
+  }
+  void endpoint;
+  return 0;
+}
+function delay(ms) {
+  if (ms <= 0) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve3) => {
+    setTimeout(resolve3, ms);
+  });
+}
+async function readBodyBounded(response, maxBytes) {
+  let total = 0;
+  const chunks = [];
+  const reader = response.body?.[Symbol.asyncIterator]?.();
+  if (reader) {
+    let oversized = false;
+    while (true) {
+      const step = await reader.next();
+      if (step.done) {
+        break;
+      }
+      const chunk = Buffer.isBuffer(step.value) ? step.value : Buffer.from(step.value);
+      if (total + chunk.length > maxBytes) {
+        oversized = true;
+        chunks.push(chunk.subarray(0, Math.max(0, maxBytes - total)));
+        break;
+      }
+      total += chunk.length;
+      chunks.push(chunk);
+    }
+    let body = Buffer.concat(chunks).toString("utf8");
+    if (oversized) {
+      body = body + "...";
+    }
+    return body;
+  }
+  const text = await response.text();
+  if (text.length > maxBytes) {
+    return text.slice(0, maxBytes) + "...";
+  }
+  return text;
+}
+function sanitizeFilename(name) {
+  if (name === "" || name === "." || name === "..") {
+    throw new ConfluenceApiError("Invalid attachment filename", 0, "attachment", "");
+  }
+  let cleaned = "";
+  for (let i = 0; i < name.length; i += 1) {
+    const code = name.charCodeAt(i);
+    if (code === 34 || code === 39 || code === 13 || code === 10 || code === 0) {
+      cleaned += "_";
+      continue;
+    }
+    cleaned += name[i] ?? "";
+  }
+  cleaned = cleaned.replace(/[/\\]/g, "_");
+  if (cleaned === "" || cleaned === "." || cleaned === "..") {
+    throw new ConfluenceApiError("Invalid attachment filename", 0, "attachment", "");
+  }
+  return cleaned;
+}
 function multipartField(boundary, name, filename, value) {
   const headerLines = [`--${boundary}\r
 `];
@@ -227,11 +454,41 @@ function normalizeBaseUrl(baseUrl) {
   if (trimmed.length === 0) {
     throw new Error("baseUrl must not be empty");
   }
-  let url = trimmed;
-  while (url.endsWith("/")) {
-    url = url.slice(0, -1);
+  let url;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    throw new Error(`Invalid baseUrl: ${baseUrl}`);
+  }
+  if (url.protocol !== "https:") {
+    throw new Error(`baseUrl must use https: ${baseUrl}`);
+  }
+  if (url.username || url.password) {
+    throw new Error("baseUrl must not include embedded credentials");
   }
-  return url;
+  if (url.search || url.hash) {
+    throw new Error("baseUrl must not include query or fragment components");
+  }
+  const normalizedPath = url.pathname.replace(/\/+$/u, "") || "/";
+  if (normalizedPath !== "/" && normalizedPath !== "/wiki") {
+    throw new Error(`baseUrl path must be empty or /wiki: ${baseUrl}`);
+  }
+  return normalizedPath === "/" ? url.origin : `${url.origin}${normalizedPath}`;
+}
+function resolveNextUrl(baseUrl, baseUrlOrigin, next) {
+  if (!next) {
+    return void 0;
+  }
+  let resolved;
+  try {
+    resolved = new URL(next, baseUrl);
+  } catch {
+    throw new ConfluenceApiError(`Confluence pagination returned a malformed next link`, 0, next, "");
+  }
+  if (resolved.origin !== baseUrlOrigin) {
+    throw new ConfluenceApiError(`Confluence pagination returned a cross-origin next link: ${next}`, 0, next, "");
+  }
+  return resolved.toString();
 }
 function describeStatus(status) {
   switch (status) {
@@ -243,6 +500,8 @@ function describeStatus(status) {
       return "Resource not found";
     case STATUS_CODES.CONFLICT:
       return "Version conflict (page was updated concurrently)";
+    case STATUS_CODES.TOO_MANY_REQUESTS:
+      return "Rate limited by Confluence";
     default:
       if (status >= STATUS_CODES.BAD_REQUEST && status < 500) {
         return `Client error (${status})`;
@@ -308,15 +567,79 @@ function titleFromSegment(segment) {
 // src/markdown.ts
 var STORAGE_LINE_BREAK = "<br />";
 var LINE_BREAK_SENTINEL = "
BR
";
-var PROTOCOL_BLOCKLIST = /^(?:javascript|data|file|vbscript):/i;
 var AMP = "&amp;";
 var LT = "&lt;";
 var GT = "&gt;";
 var QUOT = "&quot;";
 var APOS = "&#39;";
-function markdownToStorage(markdown) {
-  const lines = markdown.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+var HTTP_SRE = /^(https?:)?\/\//i;
+var ABSOLUTE_SCHEME_RE = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
+var BLOCKED_SCHEMES = /* @__PURE__ */ new Set(["javascript", "data", "file", "vbscript"]);
+var ALLOWED_SCHEMES = /* @__PURE__ */ new Set(["http", "https", "mailto", "tel"]);
+function schemeOf(url) {
+  const match = ABSOLUTE_SCHEME_RE.exec(url);
+  if (!match) {
+    return null;
+  }
+  return match[0].slice(0, -1).toLowerCase();
+}
+function decodedSchemeOrNull(url) {
+  const match = ABSOLUTE_SCHEME_RE.exec(url);
+  if (!match) {
+    return null;
+  }
+  const rawScheme = match[0].slice(0, -1);
+  try {
+    return decodeURIComponent(rawScheme).toLowerCase();
+  } catch {
+    return rawScheme.toLowerCase();
+  }
+}
+function isAllowedUrl(url) {
+  if (url.length === 0) {
+    return false;
+  }
+  for (let i = 0; i < url.length; i += 1) {
+    const code = url.charCodeAt(i);
+    if (code < 32 || code === 127) {
+      return false;
+    }
+  }
+  const scheme = schemeOf(url);
+  if (scheme === null) {
+    return HTTP_SRE.test(url) || /^[/?#]/.test(url) || !/:/.test(url);
+  }
+  const decoded = decodedSchemeOrNull(url) ?? scheme;
+  if (BLOCKED_SCHEMES.has(scheme) || BLOCKED_SCHEMES.has(decoded)) {
+    return false;
+  }
+  return ALLOWED_SCHEMES.has(scheme);
+}
+var MERMAID_PLACEHOLDER_PREFIX = '<ac:structured-macro ac:name="mermaid-placeholder" data-mermaid-id="';
+var MERMAID_PLACEHOLDER_RE_STRICT = /<ac:structured-macro ac:name="mermaid-placeholder" data-mermaid-id="([^"]+)"><\/ac:structured-macro>/g;
+function mermaidPlaceholderRe() {
+  return new RegExp(MERMAID_PLACEHOLDER_RE_STRICT.source, "g");
+}
+function renderMermaidPlaceholder(id) {
+  return `${MERMAID_PLACEHOLDER_PREFIX}${escapeXmlAttribute(id)}"></ac:structured-macro>`;
+}
+function markdownToStorage(markdown, options = {}) {
+  const renderHtmlBlocks = options.renderHtmlBlocks === true;
+  let lines = markdown.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+  if (lines.length > 0 && lines[0] === "---") {
+    let closeIndex = -1;
+    for (let j = 1; j < lines.length; j += 1) {
+      if (lines[j] === "---" || lines[j] === "...") {
+        closeIndex = j;
+        break;
+      }
+    }
+    if (closeIndex !== -1) {
+      lines = lines.slice(closeIndex + 1);
+    }
+  }
   const out = [];
+  const mermaidBlocks = [];
   let i = 0;
   while (i < lines.length) {
     const line = lines[i];
@@ -339,7 +662,16 @@ function markdownToStorage(markdown) {
         i += 1;
       }
       i += 1;
-      out.push(renderCodeBlock(buf.join("\n"), lang));
+      const code = buf.join("\n");
+      if (lang === "mermaid") {
+        const id = `mermaid-${mermaidBlocks.length + 1}`;
+        mermaidBlocks.push({ id, source: code });
+        out.push(renderMermaidPlaceholder(id));
+      } else if (lang === "html" && renderHtmlBlocks) {
+        out.push(renderHtmlBlock(code));
+      } else {
+        out.push(renderCodeBlock(code, lang));
+      }
       continue;
     }
     if (/^\s{0,3}(?:-|\*|\+)\s+/.test(line) || /^\s{0,3}\d+\.\s+/.test(line)) {
@@ -376,7 +708,7 @@ function markdownToStorage(markdown) {
     const renderedPara = renderInline(para.join(LINE_BREAK_SENTINEL));
     out.push(`<p>${renderedPara.split(LINE_BREAK_SENTINEL).join(STORAGE_LINE_BREAK)}</p>`);
   }
-  return { html: out.join("\n") };
+  return { html: out.join("\n"), mermaidBlocks };
 }
 function isLikelyListTerminator(lines, currentIndex) {
   for (let k = currentIndex + 1; k < lines.length; k += 1) {
@@ -403,6 +735,9 @@ function renderCodeBlock(code, _lang) {
   const titleAttr = escapeXmlAttribute(lang);
   return `<ac:structured-macro ac:name="code"><ac:parameter ac:name="language">${titleAttr}</ac:parameter><ac:plain-text-body><![CDATA[${escapeCdataTerminator(code)}]]></ac:plain-text-body></ac:structured-macro>`;
 }
+function renderHtmlBlock(code) {
+  return `<ac:structured-macro ac:name="html"><ac:plain-text-body><![CDATA[${escapeCdataTerminator(code)}]]></ac:plain-text-body></ac:structured-macro>`;
+}
 function escapeCdataTerminator(text) {
   return text.replace(/]]>/g, "]]]]><![CDATA[>");
 }
@@ -427,86 +762,264 @@ function renderList(listLines) {
   return `<${tag}>${body}</${tag}>`;
 }
 function renderInline(text) {
-  let s = text;
-  s = escapeHtml(s);
-  s = applyImages(s);
-  s = applyLinks(s);
-  s = applyStrong(s);
-  s = applyInlineCode(s);
-  return s;
-}
-function applyLinks(text) {
-  return replaceBalancedSyntax(text, /\[([^\]]+)\]\(/g, (label, url) => {
-    if (PROTOCOL_BLOCKLIST.test(url)) {
-      return label;
-    }
-    return '<a href="' + escapeXmlAttribute(url) + '">' + label + "</a>";
-  });
+  const out = [];
+  const tokens = tokenizeInline(text, 0, text.length);
+  renderTokens(text, tokens, out);
+  return out.join("");
+}
+function renderTokens(text, tokens, out) {
+  renderTokenRange(text, tokens, 0, tokens.length, out);
 }
-function applyImages(text) {
-  return replaceBalancedSyntax(text, /!\[([^\]]*)\]\(/g, (alt, src) => {
-    if (PROTOCOL_BLOCKLIST.test(src)) {
-      return alt;
+function renderTokenRange(text, tokens, from, to, out) {
+  for (let i = from; i < to; i += 1) {
+    const open = tokens[i];
+    if (open.kind !== "delimiter" || !open.canOpen) {
+      out.push(renderSingleToken(text, open));
+      continue;
     }
-    if (isRemoteUrl(src)) {
-      return '<ac:image><ri:url ri:value="' + escapeXmlAttribute(src) + '" /></ac:image>';
+    const closeIdx = findEmphasisClose(tokens, i, to, open);
+    if (closeIdx === -1) {
+      out.push(renderSingleToken(text, open));
+      continue;
     }
-    return '<ac:image data-local-src="' + escapeXmlAttribute(src) + '"></ac:image>';
-  });
+    const tag = open.runLength === 1 ? "em" : "strong";
+    const innerOut = [];
+    renderTokenRange(text, tokens, i + 1, closeIdx, innerOut);
+    out.push("<" + tag + ">" + innerOut.join("") + "</" + tag + ">");
+    i = closeIdx;
+  }
 }
-function replaceBalancedSyntax(text, openerRe, render) {
-  let out = "";
-  let cursor = 0;
-  let m;
-  const re = new RegExp(openerRe.source, "g");
-  while ((m = re.exec(text)) !== null) {
-    out += text.slice(cursor, m.index);
-    const captured = m[1] ?? "";
-    const after = text.slice(m.index + m[0].length);
-    const scan = scanBalancedUrl(after);
-    if (scan === null) {
-      out += m[0];
-      cursor = m.index + m[0].length;
+function renderSingleToken(text, token) {
+  if (token.kind === "text") {
+    return token.end > token.start ? escapeHtml(text.slice(token.start, token.end)) : "";
+  }
+  if (token.kind === "code") {
+    return "<code>" + escapeHtml(text.slice(token.contentStart, token.contentEnd)) + "</code>";
+  }
+  if (token.kind === "image") {
+    return renderImageToken(text, token);
+  }
+  if (token.kind === "link") {
+    return renderLinkToken(text, token);
+  }
+  return escapeHtml(token.marker.repeat(token.runLength));
+}
+function renderImageToken(text, token) {
+  const labelRaw = text.slice(token.labelStart, token.labelEnd);
+  if (!isAllowedUrl(token.url)) {
+    return escapeHtml(labelRaw);
+  }
+  if (!isRemoteUrl(token.url)) {
+    return '<ac:image data-local-src="' + escapeXmlAttribute(token.url) + '"></ac:image>';
+  }
+  const alt = renderInline(labelRaw);
+  return '<ac:image><ri:url ri:value="' + escapeXmlAttribute(token.url) + '" />' + alt + "</ac:image>";
+}
+function renderLinkToken(text, token) {
+  const labelRaw = text.slice(token.labelStart, token.labelEnd);
+  if (!isAllowedUrl(token.url)) {
+    return renderInline(labelRaw);
+  }
+  return '<a href="' + escapeXmlAttribute(token.url) + '">' + renderInline(labelRaw) + "</a>";
+}
+function findEmphasisClose(tokens, openIdx, to, open) {
+  let depth = 0;
+  for (let i = openIdx + 1; i < to; i += 1) {
+    const t = tokens[i];
+    if (t.kind !== "delimiter") {
+      continue;
+    }
+    const m = t.marker;
+    if (m === open.marker && t.runLength === open.runLength && t.canOpen && !t.canClose) {
+      depth += 1;
+    } else if (m === open.marker && t.runLength === open.runLength && t.canClose) {
+      if (depth === 0) {
+        return i;
+      }
+      depth -= 1;
+    }
+  }
+  return -1;
+}
+function tokenizeInline(text, start, end) {
+  const tokens = [];
+  let cursor = start;
+  let textStart = start;
+  const flushText = (stop) => {
+    if (stop > textStart) {
+      tokens.push({ kind: "text", start: textStart, end: stop });
+    }
+    textStart = stop;
+  };
+  while (cursor < end) {
+    const ch = text[cursor];
+    if (ch === "\\" && cursor + 1 < end && isAsciiPunctuation(text.charCodeAt(cursor + 1))) {
+      flushText(cursor);
+      tokens.push({ kind: "text", start: cursor + 1, end: cursor + 2 });
+      cursor += 2;
+      textStart = cursor;
+      continue;
+    }
+    if (ch === "`") {
+      const codeSpan = scanInlineCode(text, cursor, end);
+      if (codeSpan) {
+        flushText(cursor);
+        tokens.push({ kind: "code", contentStart: codeSpan.contentStart, contentEnd: codeSpan.contentEnd });
+        cursor = codeSpan.nextCursor;
+        textStart = cursor;
+        continue;
+      }
+      cursor += 1;
+      continue;
+    }
+    if (ch === "!" && cursor + 1 < end && text[cursor + 1] === "[") {
+      const link = tryParseLink(text, cursor + 1, end);
+      if (link) {
+        flushText(cursor);
+        tokens.push({ kind: "image", labelStart: cursor + 2, labelEnd: link.labelEnd, url: link.url });
+        cursor = link.nextCursor;
+        textStart = cursor;
+        continue;
+      }
+    }
+    if (ch === "[") {
+      const link = tryParseLink(text, cursor, end);
+      if (link) {
+        flushText(cursor);
+        tokens.push({ kind: "link", labelStart: cursor + 1, labelEnd: link.labelEnd, url: link.url });
+        cursor = link.nextCursor;
+        textStart = cursor;
+        continue;
+      }
+    }
+    if (ch === "*" || ch === "_") {
+      let runEnd = cursor;
+      while (runEnd < end && text[runEnd] === ch) {
+        runEnd += 1;
+      }
+      const runLength = runEnd - cursor;
+      const beforeCode = cursor === start ? -1 : text.charCodeAt(cursor - 1);
+      const afterCode = runEnd === end ? -1 : text.charCodeAt(runEnd);
+      const beforeIsSpace = beforeCode === -1 || isInlineWhitespace(beforeCode);
+      const afterIsSpace = afterCode === -1 || isInlineWhitespace(afterCode);
+      const leftFlanking = !afterIsSpace;
+      const rightFlanking = !beforeIsSpace;
+      let canOpen;
+      let canClose;
+      if (ch === "_") {
+        const beforeIsPunct = beforeCode !== -1 && isAsciiPunctuation(beforeCode);
+        const afterIsPunct = afterCode !== -1 && isAsciiPunctuation(afterCode);
+        canOpen = leftFlanking && (!rightFlanking || afterIsPunct);
+        canClose = rightFlanking && (!leftFlanking || beforeIsPunct);
+      } else {
+        canOpen = leftFlanking;
+        canClose = rightFlanking;
+      }
+      flushText(cursor);
+      const m = ch;
+      tokens.push({ kind: "delimiter", marker: m, runLength, canOpen, canClose });
+      cursor = runEnd;
+      textStart = cursor;
       continue;
     }
-    out += render(captured, scan.url);
-    cursor = m.index + m[0].length + scan.consumed;
+    cursor += 1;
   }
-  out += text.slice(cursor);
-  return out;
+  flushText(end);
+  return tokens;
 }
-function scanBalancedUrl(rest) {
+function scanInlineCode(text, start, end) {
+  let openEnd = start;
+  while (openEnd < end && text[openEnd] === "`") {
+    openEnd += 1;
+  }
+  const openRun = openEnd - start;
+  let closeStart = -1;
+  let search = openEnd;
+  while (search < end) {
+    if (text[search] !== "`") {
+      search += 1;
+      continue;
+    }
+    let runEnd = search;
+    while (runEnd < end && text[runEnd] === "`") {
+      runEnd += 1;
+    }
+    if (runEnd - search === openRun) {
+      closeStart = search;
+      break;
+    }
+    search = runEnd;
+  }
+  if (closeStart === -1) {
+    return null;
+  }
+  let contentStart = openEnd;
+  let contentEnd = closeStart;
+  if (contentEnd - contentStart >= 2 && text[contentStart] === " " && text[contentEnd - 1] === " ") {
+    contentStart += 1;
+    contentEnd -= 1;
+  }
+  return { contentStart, contentEnd, nextCursor: closeStart + openRun };
+}
+function isInlineWhitespace(code) {
+  return code === 32 || code === 9 || code === 10 || code === 13;
+}
+function isAsciiPunctuation(code) {
+  return code >= 33 && code <= 47 || code >= 58 && code <= 64 || code >= 91 && code <= 96 || code >= 123 && code <= 126;
+}
+function tryParseLink(text, bracketStart, end) {
   let depth = 0;
-  let i = 0;
-  for (; i < rest.length; i += 1) {
-    const ch = rest[i];
-    if (ch === "(") {
+  let i = bracketStart + 1;
+  while (i < end) {
+    const c = text[i];
+    if (c === "\\") {
+      i += 2;
+      continue;
+    }
+    if (c === "[") {
       depth += 1;
-    } else if (ch === ")") {
+    } else if (c === "]") {
       if (depth === 0) {
-        const url = rest.slice(0, i);
+        break;
+      }
+      depth -= 1;
+    }
+    i += 1;
+  }
+  if (i >= end || text[i] !== "]" || depth !== 0) {
+    return null;
+  }
+  const labelEnd = i;
+  if (i + 1 >= end || text[i + 1] !== "(") {
+    return null;
+  }
+  let j = i + 2;
+  let parenDepth = 0;
+  while (j < end) {
+    const c = text[j];
+    if (c === "\\") {
+      j += 2;
+      continue;
+    }
+    if (c === "(") {
+      parenDepth += 1;
+    } else if (c === ")") {
+      if (parenDepth === 0) {
+        const url = text.slice(i + 2, j).trim();
         if (url.length === 0) {
           return null;
         }
-        return { url, consumed: i + 1 };
+        return { labelEnd, url, nextCursor: j + 1 };
       }
-      depth -= 1;
-    } else if (ch === " " || ch === "	" || ch === "\n") {
+      parenDepth -= 1;
+    } else if (c === " " || c === "	" || c === "\n") {
       return null;
     }
+    j += 1;
   }
   return null;
 }
 var LOCAL_IMAGE_PLACEHOLDER_RE = /<ac:image\s+data-local-src="([^"]*)"\s*><\/ac:image>/g;
-function applyStrong(text) {
-  let s = text.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
-  s = s.replace(/\*([^*]+)\*/g, "<em>$1</em>");
-  s = s.replace(/__([^_]+)__/g, "<strong>$1</strong>");
-  return s.replace(/_([^_]+)_/g, "<em>$1</em>");
-}
-function applyInlineCode(text) {
-  return text.replace(/`([^`]+)`/g, (_m, code) => `<code>${code}</code>`);
-}
 function isRemoteUrl(src) {
   return /^(https?:)?\/\//i.test(src) || /^\/\//.test(src);
 }
@@ -528,14 +1041,58 @@ function escapeAttachmentFilename(filename) {
 }
 
 // src/attachments.ts
-import { existsSync } from "fs";
-import { normalize as normalize2, isAbsolute, resolve } from "path";
+import { existsSync, lstatSync, realpathSync } from "fs";
+import { normalize as normalize2, isAbsolute, relative as relative2, resolve } from "path";
+
+// src/content-hash.ts
+import { createHash } from "crypto";
+import { readFileSync } from "fs";
+var SHORT_HASH_LENGTH = 16;
+function shortHashBytes(bytes) {
+  return createHash("sha256").update(bytes).digest("hex").slice(0, SHORT_HASH_LENGTH);
+}
+function shortHashString(value) {
+  return createHash("sha256").update(value, "utf8").digest("hex").slice(0, SHORT_HASH_LENGTH);
+}
+function shortHashFile(absPath) {
+  const buf = readFileSync(absPath);
+  return shortHashBytes(buf);
+}
+function splitStemAndExt(basename2) {
+  const dot = basename2.lastIndexOf(".");
+  if (dot <= 0 || dot === basename2.length - 1) {
+    return { stem: basename2, ext: "" };
+  }
+  return { stem: basename2.slice(0, dot), ext: basename2.slice(dot + 1) };
+}
+function buildStableName(originalBasename, hash) {
+  const { stem, ext } = splitStemAndExt(originalBasename);
+  const safeStem = sanitizeNameSegment(stem);
+  const safeExt = ext ? "." + sanitizeNameSegment(ext) : "";
+  return `${safeStem}-${hash}${safeExt}`;
+}
+function sanitizeNameSegment(segment) {
+  return segment.replace(/[/\\]/g, "_");
+}
+
+// src/attachments.ts
+var DEFAULT_MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+var DEFAULT_MAX_TOTAL_ATTACHMENT_BYTES = 50 * 1024 * 1024;
+var UPLOAD_COMMENT_PREFIX = "rt-content-sha256:";
+function validateAttachmentSources(html, options) {
+  const collected = collectLocalSources(html, options);
+  return collected.map(({ src, abs }) => ({
+    src,
+    abs,
+    filename: stableAttachmentFilename(abs)
+  }));
+}
 async function rewriteImagesToAttachments(html, pageId, client, options) {
   const uploaded = [];
   const resolved = await resolvePlaceholders(html, pageId, client, options, uploaded);
   return { html: resolved, uploaded };
 }
-async function resolvePlaceholders(html, pageId, client, options, uploaded) {
+async function preflightImagesToAttachments(html, pageId, client, options) {
   const existing = await client.getAttachments(pageId);
   const existingByName = /* @__PURE__ */ new Map();
   for (const a of existing) {
@@ -544,30 +1101,53 @@ async function resolvePlaceholders(html, pageId, client, options, uploaded) {
       existingByName.set(name, a);
     }
   }
-  const collected = [];
-  const seen = /* @__PURE__ */ new Set();
-  let m;
-  LOCAL_IMAGE_PLACEHOLDER_RE.lastIndex = 0;
-  while ((m = LOCAL_IMAGE_PLACEHOLDER_RE.exec(html)) !== null) {
-    const rawSrc = decodePlaceholder(m[1] ?? "");
-    if (seen.has(rawSrc)) {
-      continue;
+  const collected = collectLocalSources(html, options);
+  const pending = [];
+  const reused = [];
+  const srcToFilename = /* @__PURE__ */ new Map();
+  for (const { src, abs } of collected) {
+    const hash = shortHashFile(abs);
+    const filename = stableAttachmentFilename(abs);
+    srcToFilename.set(src, filename);
+    const existingAtt = existingByName.get(filename);
+    if (existingAtt && existingAtt.id && attachmentContentHash(existingAtt) === hash) {
+      reused.push({ src, attachment: existingAtt });
+    } else {
+      pending.push({ src, filename, hash });
     }
-    seen.add(rawSrc);
-    const abs = resolveImageForUpload(options.markdownDir, rawSrc);
-    if (!existsSync(abs)) {
-      continue;
+  }
+  const predicted = html.replace(LOCAL_IMAGE_PLACEHOLDER_RE, (full, encodedSrc) => {
+    const src = decodePlaceholder(encodedSrc);
+    const filename = srcToFilename.get(src);
+    if (!filename) {
+      return full;
+    }
+    return renderAttachmentMacro(filename);
+  });
+  return { html: predicted, pending, reused };
+}
+async function resolvePlaceholders(html, pageId, client, options, uploaded) {
+  const existing = await client.getAttachments(pageId);
+  const existingByName = /* @__PURE__ */ new Map();
+  for (const a of existing) {
+    const name = a.filename ?? a.title;
+    if (name) {
+      existingByName.set(name, a);
     }
-    collected.push({ src: rawSrc, abs });
   }
+  const collected = collectLocalSources(html, options);
   const srcToFilename = /* @__PURE__ */ new Map();
   for (const { src, abs } of collected) {
-    const filename = escapeAttachmentFilename(basenameLocal(abs));
-    let attachment = existingByName.get(filename);
-    if (attachment && attachment.id) {
-      attachment = await client.updateAttachmentData(pageId, attachment.id, abs, `Updated via repo-toolkit-confluence`);
+    const hash = shortHashFile(abs);
+    const filename = stableAttachmentFilename(abs);
+    const existingAtt = existingByName.get(filename);
+    let attachment;
+    if (existingAtt && existingAtt.id && attachmentContentHash(existingAtt) === hash) {
+      attachment = existingAtt;
+    } else if (existingAtt && existingAtt.id) {
+      attachment = await client.updateAttachmentData(pageId, existingAtt.id, abs, contentHashComment(hash), filename);
     } else {
-      attachment = await client.uploadAttachment(pageId, abs, `Uploaded via repo-toolkit-confluence`);
+      attachment = await client.uploadAttachment(pageId, abs, contentHashComment(hash), filename);
     }
     uploaded.push({ src, attachment });
     srcToFilename.set(src, filename);
@@ -581,18 +1161,76 @@ async function resolvePlaceholders(html, pageId, client, options, uploaded) {
     return renderAttachmentMacro(filename);
   });
 }
+function collectLocalSources(html, options) {
+  const collected = [];
+  const seen = /* @__PURE__ */ new Set();
+  const maxAttachmentBytes = options.maxAttachmentBytes ?? DEFAULT_MAX_ATTACHMENT_BYTES;
+  const maxTotalAttachmentBytes = options.maxTotalAttachmentBytes ?? DEFAULT_MAX_TOTAL_ATTACHMENT_BYTES;
+  let totalBytes = 0;
+  let m;
+  LOCAL_IMAGE_PLACEHOLDER_RE.lastIndex = 0;
+  while ((m = LOCAL_IMAGE_PLACEHOLDER_RE.exec(html)) !== null) {
+    const rawSrc = decodePlaceholder(m[1] ?? "");
+    if (seen.has(rawSrc)) {
+      continue;
+    }
+    seen.add(rawSrc);
+    const abs = resolveImageForUpload(options.markdownDir, options.allowedRoot, rawSrc);
+    const sourceInfo = lstatSync(abs);
+    if (!sourceInfo.isFile()) {
+      throw new Error(`Attachment source must be a regular file: ${rawSrc}`);
+    }
+    if (sourceInfo.size > maxAttachmentBytes) {
+      throw new Error(`Attachment source exceeds the size limit: ${rawSrc}`);
+    }
+    totalBytes += sourceInfo.size;
+    if (totalBytes > maxTotalAttachmentBytes) {
+      throw new Error(`Attachment sources exceed the total size limit for this document`);
+    }
+    collected.push({ src: rawSrc, abs });
+  }
+  return collected;
+}
+function stableAttachmentFilename(absPath) {
+  const basename2 = basenameLocal(absPath);
+  const hash = shortHashFile(absPath);
+  return escapeAttachmentFilename(buildStableName(basename2, hash));
+}
+function attachmentContentHash(attachment) {
+  const message = attachment.version?.message;
+  if (!message) {
+    return null;
+  }
+  if (!message.startsWith(UPLOAD_COMMENT_PREFIX)) {
+    return null;
+  }
+  return message.slice(UPLOAD_COMMENT_PREFIX.length) || null;
+}
+function contentHashComment(hash) {
+  return `${UPLOAD_COMMENT_PREFIX}${hash}`;
+}
 function renderAttachmentMacro(filename) {
   const safe = escapeAttachmentFilename(filename);
   return `<ac:image><ri:attachment ri:filename="${escapeXmlAttribute(safe)}" /></ac:image>`;
 }
-function resolveImageForUpload(markdownDir, src) {
+function resolveImageForUpload(markdownDir, allowedRoot, src) {
   if (isRemoteUrl(src)) {
     throw new Error(`Remote image should not be uploaded: ${src}`);
   }
   if (isAbsolute(src)) {
-    return normalize2(src);
+    throw new Error(`Attachment source must be relative to the documentation root: ${src}`);
+  }
+  const resolvedPath = normalize2(resolve(markdownDir, src));
+  if (!existsSync(resolvedPath)) {
+    throw new Error(`Attachment source not found: ${src}`);
   }
-  return normalize2(resolve(markdownDir, src));
+  const resolvedRoot = realpathSync(allowedRoot);
+  const realSourcePath = realpathSync(resolvedPath);
+  const relativePath = relative2(resolvedRoot, realSourcePath);
+  if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+    throw new Error(`Attachment source escapes the documentation root: ${src}`);
+  }
+  return realSourcePath;
 }
 function basenameLocal(absPath) {
   const norm = normalize2(absPath);
@@ -609,23 +1247,348 @@ function decodePlaceholder(value) {
   return value.replace(new RegExp(AMP2, "g"), "&").replace(new RegExp(QUOT2, "g"), '"').replace(new RegExp(LT2, "g"), "<").replace(new RegExp(GT2, "g"), ">");
 }
 
+// src/mermaid.ts
+import { spawn, spawnSync } from "child_process";
+import { mkdtemp, rm, writeFile, readFile } from "fs/promises";
+import { tmpdir } from "os";
+import { join as join2 } from "path";
+var DEFAULT_MERMAID_RENDER_TIMEOUT_MS = 3e4;
+var DEFAULT_MERMAID_MAX_STREAM_BYTES = 1024 * 1024;
+var SVG_START_RE = /<svg[\s/>]/;
+var SVG_END_RE = /<\/svg>\s*$|\/>\s*$/;
+var UPLOAD_COMMENT_PREFIX2 = "rt-content-sha256:";
+var MERMAID_BASENAME = "mermaid.svg";
+async function rewriteMermaidBlocks(html, blocks, pageId, client, options = {}) {
+  const fallbacks = [];
+  const uploaded = [];
+  if (blocks.length === 0) {
+    return { html, fallbacks, uploaded };
+  }
+  const existing = await client.getAttachments(pageId);
+  const existingByName = /* @__PURE__ */ new Map();
+  for (const a of existing) {
+    const name = a.filename ?? a.title;
+    if (name) {
+      existingByName.set(name, a);
+    }
+  }
+  const renderHook = options.renderHook ?? defaultRenderHook;
+  let mmdcAvailable;
+  if (options.renderHook) {
+    mmdcAvailable = true;
+  } else if (options.available !== void 0) {
+    mmdcAvailable = options.available;
+  } else {
+    mmdcAvailable = await isMmdcAvailable(options.mmdcPath);
+  }
+  const resolved = /* @__PURE__ */ new Map();
+  const remainingIds = /* @__PURE__ */ new Set();
+  for (const block of blocks) {
+    const hash = shortHashString(block.source);
+    const filename = mermaidAttachmentFilename(hash);
+    if (!mmdcAvailable) {
+      fallbacks.push(block.id);
+      remainingIds.add(block.id);
+      continue;
+    }
+    const existingAtt = existingByName.get(filename);
+    if (existingAtt && existingAtt.id && attachmentContentHash2(existingAtt) === hash) {
+      resolved.set(block.id, { filename, attachment: existingAtt });
+      continue;
+    }
+    const workDir = await mkdtemp(join2(tmpdir(), "rt-mermaid-"));
+    try {
+      const inPath = join2(workDir, "diagram.mmd");
+      const outPath = join2(workDir, "diagram.svg");
+      await writeFile(inPath, block.source, "utf8");
+      try {
+        await renderHook(block.source, outPath, options.mmdcPath, options.renderTimeoutMs, options.maxStreamBytes);
+      } catch {
+        fallbacks.push(block.id);
+        remainingIds.add(block.id);
+        continue;
+      }
+      let svg;
+      try {
+        svg = await readFile(outPath, "utf8");
+      } catch {
+        fallbacks.push(block.id);
+        remainingIds.add(block.id);
+        continue;
+      }
+      const trimmed = svg.trim();
+      if (trimmed.length === 0 || !SVG_START_RE.test(trimmed) || !SVG_END_RE.test(trimmed)) {
+        fallbacks.push(block.id);
+        remainingIds.add(block.id);
+        continue;
+      }
+      let attachment;
+      if (existingAtt && existingAtt.id) {
+        attachment = await client.updateAttachmentData(
+          pageId,
+          existingAtt.id,
+          outPath,
+          contentHashComment2(hash),
+          filename
+        );
+      } else {
+        attachment = await client.uploadAttachment(pageId, outPath, contentHashComment2(hash), filename);
+      }
+      if (attachment) {
+        uploaded.push({ id: block.id, attachment });
+        resolved.set(block.id, { filename, attachment });
+      } else {
+        fallbacks.push(block.id);
+        remainingIds.add(block.id);
+      }
+    } finally {
+      await rm(workDir, { recursive: true, force: true }).catch(() => {
+      });
+    }
+  }
+  const re = mermaidPlaceholderRe();
+  const replaced = html.replace(re, (full, id) => {
+    const entry = resolved.get(id);
+    if (entry) {
+      return renderAttachmentMacro2(entry.filename);
+    }
+    if (remainingIds.has(id)) {
+      const block = blocks.find((b) => b.id === id);
+      if (block) {
+        return renderCodeBlock(block.source, "mermaid");
+      }
+    }
+    return full;
+  });
+  return { html: replaced, fallbacks, uploaded };
+}
+async function preflightMermaidBlocks(html, blocks, pageId, client, options = {}) {
+  const fallbacks = [];
+  const pending = [];
+  const reused = [];
+  if (blocks.length === 0) {
+    return { html, pending, reused, fallbacks };
+  }
+  const existing = await client.getAttachments(pageId);
+  const existingByName = /* @__PURE__ */ new Map();
+  for (const a of existing) {
+    const name = a.filename ?? a.title;
+    if (name) {
+      existingByName.set(name, a);
+    }
+  }
+  let mmdcAvailable;
+  if (options.renderHook) {
+    mmdcAvailable = true;
+  } else if (options.available !== void 0) {
+    mmdcAvailable = options.available;
+  } else {
+    mmdcAvailable = await isMmdcAvailable(options.mmdcPath);
+  }
+  const resolved = /* @__PURE__ */ new Map();
+  const remainingIds = /* @__PURE__ */ new Set();
+  for (const block of blocks) {
+    const hash = shortHashString(block.source);
+    const filename = mermaidAttachmentFilename(hash);
+    if (!mmdcAvailable) {
+      fallbacks.push(block.id);
+      remainingIds.add(block.id);
+      continue;
+    }
+    const existingAtt = existingByName.get(filename);
+    if (existingAtt && existingAtt.id && attachmentContentHash2(existingAtt) === hash) {
+      reused.push({ id: block.id, attachment: existingAtt });
+      resolved.set(block.id, filename);
+    } else {
+      pending.push({ id: block.id, filename, hash });
+    }
+  }
+  const re = mermaidPlaceholderRe();
+  const predicted = html.replace(re, (full, id) => {
+    const filename = resolved.get(id);
+    if (filename) {
+      return renderAttachmentMacro2(filename);
+    }
+    if (remainingIds.has(id)) {
+      const block = blocks.find((b) => b.id === id);
+      if (block) {
+        return renderCodeBlock(block.source, "mermaid");
+      }
+    }
+    return full;
+  });
+  return { html: predicted, pending, reused, fallbacks };
+}
+function mermaidAttachmentFilename(hash) {
+  return escapeAttachmentFilename(buildStableName(MERMAID_BASENAME, hash));
+}
+function attachmentContentHash2(attachment) {
+  const message = attachment.version?.message;
+  if (!message) {
+    return null;
+  }
+  if (!message.startsWith(UPLOAD_COMMENT_PREFIX2)) {
+    return null;
+  }
+  return message.slice(UPLOAD_COMMENT_PREFIX2.length) || null;
+}
+function contentHashComment2(hash) {
+  return `${UPLOAD_COMMENT_PREFIX2}${hash}`;
+}
+function renderAttachmentMacro2(filename) {
+  const safe = escapeAttachmentFilename(filename);
+  return `<ac:image><ri:attachment ri:filename="${escapeXmlAttribute(safe)}" /></ac:image>`;
+}
+async function isMmdcAvailable(override) {
+  if (override) {
+    return true;
+  }
+  return spawnSync("sh", ["-c", "command -v mmdc"], { stdio: "ignore" }).status === 0;
+}
+async function defaultRenderHook(source, outFile, mmdcPath, timeoutMs, maxStreamBytes) {
+  const timeout = timeoutMs ?? DEFAULT_MERMAID_RENDER_TIMEOUT_MS;
+  const maxBytes = maxStreamBytes ?? DEFAULT_MERMAID_MAX_STREAM_BYTES;
+  const cmdPath = mmdcPath ?? "mmdc";
+  return runMmdc(cmdPath, source, outFile, timeout, maxBytes);
+}
+function runMmdc(cmdPath, source, outFile, timeoutMs, maxStreamBytes) {
+  return new Promise((resolve3, reject) => {
+    const child = spawn(cmdPath, ["-i", "-", "-o", outFile, "-t", "default", "-b", "transparent"], {
+      stdio: ["pipe", "pipe", "pipe"],
+      shell: false
+    });
+    let stdoutLen = 0;
+    let stderrLen = 0;
+    let stderr = "";
+    let killed = false;
+    const timer = setTimeout(() => {
+      killed = true;
+      child.kill("SIGTERM");
+      const sigKillTimer = setTimeout(() => {
+        try {
+          child.kill("SIGKILL");
+        } catch {
+        }
+      }, 2e3);
+      if (typeof sigKillTimer.unref === "function") {
+        sigKillTimer.unref();
+      }
+    }, timeoutMs);
+    if (typeof timer.unref === "function") {
+      timer.unref();
+    }
+    child.stdout?.on("data", (chunk) => {
+      stdoutLen += chunk.length;
+      if (stdoutLen > maxStreamBytes && !killed) {
+        killed = true;
+        child.kill("SIGKILL");
+      }
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderrLen += chunk.length;
+      if (stderrLen > maxStreamBytes && !killed) {
+        killed = true;
+        child.kill("SIGKILL");
+      }
+      if (stderr.length < maxStreamBytes) {
+        stderr += chunk.toString("utf8").slice(0, Math.max(0, maxStreamBytes - stderr.length));
+      }
+    });
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      if (killed && code !== 0) {
+        reject(new Error(`mmdc exceeded ${timeoutMs}ms or output limit (killed=${signal ?? code})`));
+        return;
+      }
+      if (code === 0) {
+        resolve3();
+      } else {
+        reject(new Error(`mmdc exited with code ${String(code)}${stderr ? `: ${stderr}` : ""}`));
+      }
+    });
+    child.stdin?.on("error", () => void 0);
+    child.stdin?.end(source);
+  });
+}
+
 // src/index.ts
 var INTERACTIVE_FLAG = { name: "interactive", aliases: ["i"], boolean: true };
+var LocalSyncValidationAggregateError = class extends Error {
+  constructor(defects) {
+    const summary = defects.map((d) => `${d.entry.segments.join("/")}: ${d.error.message}`).join("; ");
+    super(`Local sync validation failed for ${defects.length} document(s): ${summary}`);
+    this.name = "LocalSyncValidationAggregateError";
+    this.defects = defects;
+  }
+};
+function validateLocalSync(entries, plan) {
+  const defects = [];
+  const plans = [];
+  for (const entry of entries) {
+    try {
+      const markdown = readFileSync2(entry.absolute, "utf8");
+      const { html, mermaidBlocks } = markdownToStorage(markdown, {
+        renderHtmlBlocks: plan.renderHtmlBlocks
+      });
+      const markdownDir = dirname(entry.absolute);
+      const hasLocalImages = hasLocalImagePlaceholder(html);
+      const hasMermaidBlocks = mermaidBlocks.length > 0;
+      const attachments = hasLocalImages ? validateAttachmentSources(html, {
+        markdownDir,
+        allowedRoot: plan.folder
+      }) : [];
+      plans.push({
+        entry,
+        html,
+        mermaidBlocks,
+        markdownDir,
+        hasLocalImages,
+        hasMermaidBlocks,
+        attachments
+      });
+    } catch (error) {
+      defects.push({
+        entry,
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+  }
+  if (defects.length > 0) {
+    throw new LocalSyncValidationAggregateError(defects);
+  }
+  return { entries: plans };
+}
+var SyncMutationError = class extends Error {
+  constructor(input) {
+    super(input.failure.error.message);
+    this.name = "SyncMutationError";
+    this.changes = input.changes;
+    this.failure = input.failure;
+    this.unprocessed = input.unprocessed;
+  }
+};
 function resolveConfluenceSyncPlan(options = {}) {
   const cwd = resolve2(options.cwd ?? process.cwd());
   const folder = resolveInputPath(cwd, options.folder ?? "");
   if (!options.folder) {
     throw new Error("folder is required");
   }
+  const hasGateway = options.client !== void 0;
   if (!options.dryRun) {
-    if (!options.username) {
-      throw new Error("username is required");
-    }
-    if (!options.apiToken) {
-      throw new Error("apiToken is required");
-    }
-    if (!options.baseUrl) {
-      throw new Error("baseUrl is required");
+    if (!hasGateway) {
+      if (!options.username) {
+        throw new Error("username is required");
+      }
+      if (!options.apiToken) {
+        throw new Error("apiToken is required");
+      }
+      if (!options.baseUrl) {
+        throw new Error("baseUrl is required");
+      }
     }
     if (!options.spaceKey) {
       throw new Error("spaceKey is required");
@@ -647,23 +1610,28 @@ function resolveConfluenceSyncPlan(options = {}) {
     parentPageId: options.parentPageId ?? "",
     versionMessage: options.versionMessage ?? "Synced via repo-toolkit-confluence",
     skipUnchanged: options.skipUnchanged ?? true,
-    dryRun: options.dryRun ?? false
+    dryRun: options.dryRun ?? false,
+    renderHtmlBlocks: options.renderHtmlBlocks === true
   };
 }
 async function syncConfluenceToDocs(options = {}) {
   const plan = resolveConfluenceSyncPlan(options);
   const log = options.log ?? ((msg) => console.log(msg));
-  if (plan.dryRun) {
-    log("[dry-run] Walking documentation tree only.");
-  }
   const tree = await readDocTree(plan.folder);
   if (tree.entries.length === 0) {
     log(`No markdown files found under ${plan.folder}`);
     return;
   }
+  validateLocalHierarchy(tree.entries);
+  const localPlan = validateLocalSync(tree.entries, plan);
   if (plan.dryRun) {
-    for (const entry of tree.entries) {
-      log(`[dry-run] would sync ${entry.segments.join("/")}`);
+    log("[dry-run] Walking documentation tree only.");
+    for (const entryPlan of localPlan.entries) {
+      const attCount = entryPlan.attachments.length;
+      const mermaidCount = entryPlan.mermaidBlocks.length;
+      log(
+        `[dry-run] would sync ${entryPlan.entry.segments.join("/")}` + (attCount > 0 ? ` (${attCount} attachment${attCount === 1 ? "" : "s"} validated)` : "") + (mermaidCount > 0 ? ` (${mermaidCount} mermaid block${mermaidCount === 1 ? "" : "s"})` : "")
+      );
     }
     return;
   }
@@ -674,11 +1642,23 @@ async function syncConfluenceToDocs(options = {}) {
   });
   const spaceId = await client.getSpaceIdByKey(plan.spaceKey);
   const cache = new PageTitleCache(spaceId, client);
-  for (const entry of tree.entries) {
-    await syncEntry(entry, plan, client, cache, log);
+  const changes = [];
+  for (let i = 0; i < localPlan.entries.length; i += 1) {
+    const entryPlan = localPlan.entries[i];
+    try {
+      await syncEntry(entryPlan, plan, client, cache, log, changes);
+    } catch (error) {
+      throw new SyncMutationError({
+        changes,
+        failure: { entry: entryPlan.entry, error: error instanceof Error ? error : new Error(String(error)) },
+        unprocessed: localPlan.entries.slice(i + 1).map((p) => p.entry)
+      });
+    }
   }
+  return { changes };
 }
-async function syncEntry(entry, plan, client, cache, log) {
+async function syncEntry(entryPlan, plan, client, cache, log, changes) {
+  const { entry, html: precomputedHtml, mermaidBlocks, markdownDir, hasLocalImages, hasMermaidBlocks } = entryPlan;
   const segments = entry.segments;
   if (segments.length === 0) {
     return;
@@ -689,24 +1669,53 @@ async function syncEntry(entry, plan, client, cache, log) {
     const segment = segments[idx] ?? "";
     if (isLast && isMarkdownName(segment)) {
       const title = titleFromSegment(segment);
-      const page2 = await cache.findOrCreate(title, currentParentId);
-      const pageId = page2.id;
-      const markdown = readFileSync2(entry.absolute, "utf8");
-      const { html } = markdownToStorage(markdown);
-      const markdownDir = dirname(entry.absolute);
-      let body = html;
-      LOCAL_IMAGE_PLACEHOLDER_RE.lastIndex = 0;
-      if (LOCAL_IMAGE_PLACEHOLDER_RE.test(body)) {
-        const result = await rewriteImagesToAttachments(body, pageId, client, { markdownDir });
-        body = result.html;
+      const leafNeedsUploads = hasLocalImages || hasMermaidBlocks;
+      const existing = await cache.find(title, currentParentId);
+      if (!existing && !leafNeedsUploads) {
+        const pageId2 = await cache.createEntry({
+          title,
+          parentId: currentParentId,
+          body: { representation: "storage", value: precomputedHtml }
+        });
+        log(`created: ${segments.join("/")} (page ${pageId2})`);
+        changes.push({ entry, pageId: pageId2, kind: "created" });
+        return;
       }
+      const existingPage = existing ?? await cache.findOrCreate(title, currentParentId);
+      const pageId = existingPage.id;
       const current = await client.getPage(pageId);
       const currentBody = current.body?.storage?.value ?? "";
-      const nextVersion = (current.version?.number ?? 0) + 1;
-      if (plan.skipUnchanged && currentBody === body) {
-        log(`unchanged: ${segments.join("/")} (page ${pageId})`);
-        return;
+      let body = precomputedHtml;
+      if (plan.skipUnchanged) {
+        const predicted = await predictBody(precomputedHtml, mermaidBlocks, pageId, client, {
+          markdownDir,
+          allowedRoot: plan.folder,
+          hasLocalImages,
+          hasMermaidBlocks
+        });
+        if (predicted !== null && predicted === currentBody) {
+          log(`unchanged: ${segments.join("/")} (page ${pageId})`);
+          changes.push({ entry, pageId, kind: "unchanged" });
+          return;
+        }
+      }
+      if (hasMermaidBlocks) {
+        const mermaidResult = await rewriteMermaidBlocks(body, [...mermaidBlocks], pageId, client);
+        body = mermaidResult.html;
+        if (mermaidResult.fallbacks.length > 0) {
+          log(
+            `mermaid: ${mermaidResult.fallbacks.length} block(s) not rendered (mmdc unavailable or failed); emitted as code macros`
+          );
+        }
+      }
+      if (hasLocalImages) {
+        const result = await rewriteImagesToAttachments(body, pageId, client, {
+          markdownDir,
+          allowedRoot: plan.folder
+        });
+        body = result.html;
       }
+      const nextVersion = (current.version?.number ?? 0) + 1;
       await client.updatePage({
         id: pageId,
         title,
@@ -714,6 +1723,7 @@ async function syncEntry(entry, plan, client, cache, log) {
         version: { number: nextVersion, message: plan.versionMessage }
       });
       log(`updated: ${segments.join("/")} (page ${pageId}, v${nextVersion})`);
+      changes.push({ entry, pageId, kind: "updated" });
       return;
     }
     if (isMarkdownName(segment)) {
@@ -732,13 +1742,48 @@ var PageTitleCache = class {
     this.spaceId = spaceId;
     this.client = client;
   }
+  async find(title, parentId) {
+    const key = `${parentId}::${title}`;
+    const cached = this.cache.get(key);
+    if (cached) {
+      return void 0;
+    }
+    const matches = (await this.client.getPagesByTitle(this.spaceId, title)).filter(
+      (page) => page.parentId === parentId
+    );
+    if (matches.length > 1) {
+      throw new Error(`Multiple Confluence pages matched title ${title} under parent ${parentId}`);
+    }
+    const found = matches[0];
+    if (found) {
+      this.cache.set(key, { id: found.id });
+    }
+    return found;
+  }
+  async createEntry(input) {
+    const created = await this.client.createPage({
+      spaceId: this.spaceId,
+      title: input.title,
+      parentId: input.parentId,
+      body: { representation: input.body.representation, value: input.body.value }
+    });
+    const pageId = created.id;
+    this.cache.set(`${input.parentId}::${input.title}`, { id: pageId });
+    return pageId;
+  }
   async findOrCreate(title, parentId) {
     const key = `${parentId}::${title}`;
     const existing = this.cache.get(key);
     if (existing) {
       return existing;
     }
-    let page = await this.client.getPageByTitle(this.spaceId, title);
+    const matches = (await this.client.getPagesByTitle(this.spaceId, title)).filter(
+      (page2) => page2.parentId === parentId
+    );
+    let page = matches[0];
+    if (matches.length > 1) {
+      throw new Error(`Multiple Confluence pages matched title ${title} under parent ${parentId}`);
+    }
     if (!page) {
       page = await this.client.createPage({
         spaceId: this.spaceId,
@@ -758,24 +1803,71 @@ function resolveInputPath(baseDir, inputPath) {
   }
   return resolve2(baseDir, inputPath);
 }
+function hasLocalImagePlaceholder(html) {
+  LOCAL_IMAGE_PLACEHOLDER_RE.lastIndex = 0;
+  return LOCAL_IMAGE_PLACEHOLDER_RE.test(html);
+}
+async function predictBody(html, mermaidBlocks, pageId, client, ctx) {
+  let predicted = html;
+  if (ctx.hasMermaidBlocks) {
+    const preflight = await preflightMermaidBlocks(predicted, [...mermaidBlocks], pageId, client);
+    if (preflight.pending.length > 0) {
+      return null;
+    }
+    predicted = preflight.html;
+  }
+  if (ctx.hasLocalImages) {
+    const preflight = await preflightImagesToAttachments(predicted, pageId, client, {
+      markdownDir: ctx.markdownDir,
+      allowedRoot: ctx.allowedRoot
+    });
+    if (preflight.pending.length > 0) {
+      return null;
+    }
+    predicted = preflight.html;
+  }
+  return predicted;
+}
+function validateLocalHierarchy(entries) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    let parentKey = "";
+    for (let index = 0; index < entry.segments.length; index += 1) {
+      const segment = entry.segments[index] ?? "";
+      const isLast = index === entry.segments.length - 1;
+      const title = isMarkdownName(segment) ? titleFromSegment(segment) : segment;
+      const kind = isLast && isMarkdownName(segment) ? "file" : "dir";
+      const key = `${parentKey}::${title}`;
+      const existing = seen.get(key);
+      if (existing && existing !== kind) {
+        throw new Error(`Local documentation tree contains conflicting page titles under the same parent: ${title}`);
+      }
+      seen.set(key, existing ?? kind);
+      parentKey = key;
+    }
+  }
+}
 export {
   ConfluenceApiError,
   ConfluenceClient,
   INTERACTIVE_FLAG,
-  LOCAL_IMAGE_PLACEHOLDER_RE,
+  LocalSyncValidationAggregateError,
+  SyncMutationError,
   escapeAttachmentFilename,
   escapeXmlAttribute,
+  isAllowedUrl,
   isMarkdownName,
-  isPlainObject,
   isRemoteUrl,
   markdownToStorage,
-  parseFlags,
+  preflightImagesToAttachments,
+  preflightMermaidBlocks,
   readDocTree,
-  renderInline,
-  resolveCliOptions,
   resolveConfluenceSyncPlan,
   resolveConfluenceSyncPlan as resolveSyncPlan,
   rewriteImagesToAttachments,
+  rewriteMermaidBlocks,
   syncConfluenceToDocs,
-  titleFromSegment
+  titleFromSegment,
+  validateAttachmentSources,
+  validateLocalSync
 };