confluence-cli 2.1.8 → 2.1.10

package/lib/html-to-storage.js

@@ -0,0 +1,394 @@
+// HTML → Confluence storage walker. Parses with htmlparser2 using
+// `decodeEntities: false` so attribute and text entities round-trip
+// byte-identical. Dispatches by tag; unhandled tags pass through with
+// attributes preserved.
+
+const { parseDocument } = require('htmlparser2');
+
+const VALID_LINK_STYLES = ['smart', 'plain', 'wiki'];
+// Hard cap on input HTML nesting to keep the recursive walker off the JS
+// stack ceiling for pathological / malicious input.
+const DEFAULT_MAX_DEPTH = 256;
+
+class HtmlDepthExceededError extends Error {
+  constructor(maxDepth) {
+    super(`HTML nesting exceeds limit of ${maxDepth} levels`);
+    this.name = 'HtmlDepthExceededError';
+    this.maxDepth = maxDepth;
+  }
+}
+// Only `hr` is normalized to self-closing. `br` / `img` flow through in
+// whatever shape the source had (markdown-it emits them without a slash).
+const VOID_TAGS = new Set(['hr']);
+const CALLOUT_MARKERS = ['info', 'warning', 'note'];
+
+// Phrasing-content tags that trigger the `<li>` / `<th>` / `<td>` `<p>`-wrap
+// quirk: if an item contains only inline children and no text-node newline,
+// the walker wraps its content in `<p>`. markdown-it never emits the latter
+// half of this set, but raw HTML input does, so they need the same treatment.
+const INLINE_TAGS = new Set([
+  'a', 'strong', 'em', 'code', 'br', 'img', 'span',
+  'mark', 'sub', 'sup', 'ins', 'del', 'b', 'i', 'u', 'small', 's',
+  'abbr', 'kbd', 'q', 'var', 'cite', 'time', 'dfn', 'samp',
+]);
+
+function shouldWrapInP(node) {
+  if (!node.children) return true;
+  for (const child of node.children) {
+    if (child.type === 'text' && child.data.includes('\n')) return false;
+    if (child.type === 'tag' && !INLINE_TAGS.has(child.name)) return false;
+  }
+  return true;
+}
+
+function isWhitespaceOnly(node) {
+  return node.type === 'text' && /^\s*$/.test(node.data);
+}
+
+// Filter out whitespace-only text nodes so structural shape checks (single
+// `<strong>` inside a paragraph, etc.) tolerate parser variations that emit
+// trailing/leading whitespace text siblings.
+function meaningfulChildren(node) {
+  return (node.children || []).filter((c) => !isWhitespaceOnly(c));
+}
+
+// Detects `<p><strong>TOC</strong></p>` and `<p><strong>ANCHOR: id</strong></p>`
+// macro markers. The strict "p > one strong > one text" shape is intentional —
+// any embellishment must fall through to a plain paragraph.
+function detectParagraphMarker(node) {
+  if (node.name !== 'p') return null;
+  const kids = meaningfulChildren(node);
+  if (kids.length !== 1) return null;
+  const strong = kids[0];
+  if (strong.type !== 'tag' || strong.name !== 'strong') return null;
+  const strongKids = meaningfulChildren(strong);
+  if (strongKids.length !== 1) return null;
+  const text = strongKids[0];
+  if (text.type !== 'text') return null;
+  if (text.data === 'TOC') return { kind: 'toc' };
+  const anchor = text.data.match(/^ANCHOR: (.+)$/);
+  if (anchor) return { kind: 'anchor', id: anchor[1] };
+  return null;
+}
+
+// EXPAND open `<p><strong>EXPAND: …</strong></p>`. The title may contain
+// nested inline HTML (em, code, a, s, …) which gets stripped later — so we
+// only require that the strong's first text child starts with `EXPAND: `,
+// not that it's the only child.
+function isExpandOpen(node) {
+  if (node.type !== 'tag' || node.name !== 'p') return false;
+  const kids = meaningfulChildren(node);
+  if (kids.length !== 1) return false;
+  const strong = kids[0];
+  if (strong.type !== 'tag' || strong.name !== 'strong') return false;
+  if (!strong.children || strong.children.length === 0) return false;
+  const first = strong.children[0];
+  return first.type === 'text' && first.data.startsWith('EXPAND: ');
+}
+
+function isExpandClose(node) {
+  if (node.type !== 'tag' || node.name !== 'p') return false;
+  const kids = meaningfulChildren(node);
+  if (kids.length !== 1) return false;
+  const strong = kids[0];
+  if (strong.type !== 'tag' || strong.name !== 'strong') return false;
+  const strongKids = meaningfulChildren(strong);
+  if (strongKids.length !== 1) return false;
+  const text = strongKids[0];
+  return text.type === 'text' && text.data === 'EXPAND_END';
+}
+
+// Replacement order matters for doubly-escaped input: the default order
+// replaces the ampersand entity first, which over-decodes (the escaped
+// form of an `<`-entity collapses all the way to `<`). `preserveDouble`
+// reverses the order so the same input round-trips as `&lt;` instead.
+// Both orderings are intentional — call sites pick via the option.
+function decodeEntities(text, { preserveDouble = false } = {}) {
+  if (preserveDouble) {
+    // Apostrophe (`&#39;`) intentionally omitted from this branch: the
+    // previous code-fence decoder didn't list it either, only the anchor
+    // body decoder did. The asymmetry is preserved for byte parity.
+    return text
+      .replace(/&quot;/g, '"')
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&amp;/g, '&');
+  }
+  return text
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, '\'');
+}
+
+// Anchor links (`href="#id"`) short-circuit linkStyle; external href
+// branches on it.
+function convertLink(node, ctx) {
+  const attribs = node.attribs || {};
+  const href = attribs.href || '';
+  const inner = walkChildren(node, ctx);
+
+  if (href.startsWith('#')) {
+    const anchor = href.slice(1);
+    const text = decodeEntities(inner);
+    return `<ac:link ac:anchor="${anchor}"><ac:plain-text-link-body><![CDATA[${text}]]></ac:plain-text-link-body></ac:link>`;
+  }
+
+  switch (ctx.linkStyle) {
+  case 'smart': {
+    // Spread order forces policy: any pre-existing `data-card-appearance`
+    // on the source `<a>` is overwritten — smart links must be inline.
+    const merged = { ...attribs, 'data-card-appearance': 'inline' };
+    return `<a${renderAttrs(merged)}>${inner}</a>`;
+  }
+  case 'wiki':
+    return `<ac:link><ri:url ri:value="${href}" /><ac:plain-text-link-body><![CDATA[${inner}]]></ac:plain-text-link-body></ac:link>`;
+  case 'plain':
+  default:
+    return `<a${renderAttrs(attribs)}>${inner}</a>`;
+  }
+}
+
+// `> **INFO|WARNING|NOTE**` blockquotes become callout macros; others pass
+// through. Detection runs structurally on the DOM so false-positives for
+// mid-paragraph `**INFO**` are ruled out — the strong must be the first
+// meaningful child of the first paragraph.
+//
+// Two markdown-it shapes:
+//   separated: `<blockquote><p><strong>INFO</strong></p><p>body</p></blockquote>`
+//   same-line: `<blockquote><p><strong>INFO</strong>\nbody</p></blockquote>`
+function detectBlockquoteCallout(node) {
+  const kids = meaningfulChildren(node);
+  if (kids.length === 0) return null;
+  const firstP = kids[0];
+  if (firstP.type !== 'tag' || firstP.name !== 'p') return null;
+  const pKids = firstP.children || [];
+  const firstIdx = pKids.findIndex((c) => !isWhitespaceOnly(c));
+  if (firstIdx < 0) return null;
+  const strong = pKids[firstIdx];
+  if (strong.type !== 'tag' || strong.name !== 'strong') return null;
+  const strongKids = meaningfulChildren(strong);
+  if (strongKids.length !== 1 || strongKids[0].type !== 'text') return null;
+  const marker = CALLOUT_MARKERS.find((m) => strongKids[0].data === m.toUpperCase());
+  if (!marker) return null;
+  const tail = pKids.slice(firstIdx + 1);
+  const tailHasContent = tail.some((c) => !isWhitespaceOnly(c));
+  if (tailHasContent) {
+    // Check tail[0] (not the first meaningful child): the body of
+    // `> **INFO**\n> body` must literally start with a newline. A leading
+    // whitespace-only text node without a newline (`<strong>INFO</strong>
+    // body`) is prose continuation, not callout — it must be rejected here
+    // even though `meaningfulChildren` would otherwise look past it.
+    if (tail[0].type !== 'text' || !/^\s*\n/.test(tail[0].data)) return null;
+  }
+  return { marker, sameLine: tailHasContent, markerP: firstP, tail };
+}
+
+function convertBlockquote(node, ctx) {
+  const detected = detectBlockquoteCallout(node);
+  if (!detected) {
+    return `<blockquote>${walkChildren(node, ctx)}</blockquote>`;
+  }
+  const { marker, sameLine, markerP, tail } = detected;
+  const blockquoteKids = node.children || [];
+  let body;
+  if (sameLine) {
+    // Same-line form: the strong's siblings inside the marker paragraph form
+    // the body of the first `<p>`. Strip the leading newline that markdown-it
+    // emits between strong and body text.
+    const firstPBody = tail.map((c) => walkNode(c, ctx)).join('').replace(/^\s*\n/, '');
+    const rest = blockquoteKids
+      .filter((c) => c !== markerP)
+      .map((c) => walkNode(c, ctx))
+      .join('');
+    body = `<p>${firstPBody}</p>${rest}`;
+  } else {
+    // Separated form: drop the marker paragraph entirely and walk the rest.
+    // Leading whitespace from the now-removed paragraph's neighbor text node
+    // is trimmed.
+    body = blockquoteKids
+      .filter((c) => c !== markerP)
+      .map((c) => walkNode(c, ctx))
+      .join('')
+      .replace(/^\s+/, '');
+  }
+  return `<ac:structured-macro ac:name="${marker}">
+          <ac:rich-text-body>${body}</ac:rich-text-body>
+        </ac:structured-macro>`;
+}
+
+// Strict `<pre><code>` adjacency only — `<pre>` with whitespace siblings or
+// any other shape falls through as plain `<pre>`. The body needs manual
+// entity decode because the parser keeps entities raw and CDATA is opaque
+// downstream.
+function convertCodeBlock(node, ctx) {
+  const children = node.children || [];
+  const isCodeBlock = children.length === 1 &&
+    children[0].type === 'tag' &&
+    children[0].name === 'code';
+  if (!isCodeBlock) {
+    return `<pre>${walkChildren(node, ctx)}</pre>`;
+  }
+  const codeNode = children[0];
+  const classAttr = codeNode.attribs.class || '';
+  const langMatch = classAttr.match(/language-(\w+)/);
+  const language = langMatch ? langMatch[1] : 'text';
+  let body = '';
+  for (const c of codeNode.children || []) {
+    if (c.type === 'text') body += c.data;
+  }
+  body = decodeEntities(body.replace(/\n$/, ''), { preserveDouble: true })
+    .replace(/]]>/g, ']]]]><![CDATA[>');
+  return `<ac:structured-macro ac:name="code"><ac:parameter ac:name="language">${language}</ac:parameter><ac:plain-text-body><![CDATA[${body}]]></ac:plain-text-body></ac:structured-macro>`;
+}
+
+// Re-escape literal `"` inside attribute values. htmlparser2 with
+// `decodeEntities: false` keeps source-escaped entities intact, but a
+// single-quoted source attribute (`<a title='he said "hi"'>`) lands a
+// literal `"` here that would close the emitted double-quoted slot and
+// corrupt the XML. `&` is left as-is so already-escaped sources
+// (`&amp;`, `&quot;`, …) round-trip cleanly.
+//
+// Trust boundary: input is assumed to be valid HTML. A valid HTML
+// attribute value cannot contain raw `<` or `>` (they must be entities),
+// so they're not escaped here. Malformed input that smuggles raw
+// angle brackets through would produce malformed XML.
+function escapeAttrValue(v) {
+  return String(v).replace(/"/g, '&quot;');
+}
+
+function renderAttrs(attribs) {
+  if (!attribs) return '';
+  return Object.keys(attribs)
+    .map((k) => ` ${k}="${escapeAttrValue(attribs[k])}"`)
+    .join('');
+}
+
+function walkChildren(node, ctx) {
+  if (!node.children) return '';
+  const children = node.children;
+  const out = [];
+  let i = 0;
+  while (i < children.length) {
+    const child = children[i];
+    // Sibling-level EXPAND span — collapse open/close pair into one macro
+    // with everything between as the body. Pairs the first EXPAND_END
+    // after this open: a nested EXPAND open/close pair inside the body
+    // would have its close consumed by the outer open, leaving the
+    // second close as an orphan paragraph. Same non-greedy behavior as
+    // the previous regex pipeline.
+    if (isExpandOpen(child)) {
+      const endIdx = children.findIndex((c, j) => j > i && isExpandClose(c));
+      if (endIdx !== -1) {
+        const titleStrong = child.children[0];
+        const titleHtml = walkChildren(titleStrong, ctx).replace(/^EXPAND: /, '');
+        // Confluence's `<ac:parameter>` normalizer is text-only (rejects `<s>`
+        // with HTTP 500, silently truncates at the first '<'). Strip literal
+        // tags; entities survive because the rule requires a literal '<'.
+        const cleanTitle = titleHtml.replace(/<[^>]+>/g, '').trim();
+        const bodyHtml = children
+          .slice(i + 1, endIdx)
+          .map((c) => walkNode(c, ctx))
+          .join('')
+          .trim();
+        out.push(`<ac:structured-macro ac:name="expand"><ac:parameter ac:name="title">${cleanTitle}</ac:parameter><ac:rich-text-body>${bodyHtml}</ac:rich-text-body></ac:structured-macro>`);
+        i = endIdx + 1;
+        continue;
+      }
+    }
+    out.push(walkNode(child, ctx));
+    i++;
+  }
+  return out.join('');
+}
+
+function walkNode(node, ctx) {
+  if (node.type === 'text') return node.data;
+  if (node.type !== 'tag') return '';
+  if (++ctx.depth > ctx.maxDepth) {
+    ctx.depth--;
+    throw new HtmlDepthExceededError(ctx.maxDepth);
+  }
+  try {
+    return dispatchTag(node, ctx);
+  } finally {
+    ctx.depth--;
+  }
+}
+
+function dispatchTag(node, ctx) {
+  switch (node.name) {
+  case 'p': {
+    const marker = detectParagraphMarker(node);
+    if (marker && marker.kind === 'toc') return '<ac:structured-macro ac:name="toc" />';
+    if (marker && marker.kind === 'anchor') {
+      return `<ac:structured-macro ac:name="anchor"><ac:parameter ac:name="">${marker.id}</ac:parameter></ac:structured-macro>`;
+    }
+    return `<p${renderAttrs(node.attribs)}>${walkChildren(node, ctx)}</p>`;
+  }
+  case 'h1':
+  case 'h2':
+  case 'h3':
+  case 'h4':
+  case 'h5':
+  case 'h6':
+  case 'strong':
+  case 'em':
+    return `<${node.name}${renderAttrs(node.attribs)}>${walkChildren(node, ctx)}</${node.name}>`;
+  case 'hr':
+    return '<hr />';
+  case 'br':
+    return '<br>';
+  case 'img':
+    return `<img${renderAttrs(node.attribs)}>`;
+  case 'ul':
+  case 'ol':
+    return `<${node.name}>${walkChildren(node, ctx)}</${node.name}>`;
+  case 'li': {
+    const inner = walkChildren(node, ctx);
+    return shouldWrapInP(node) ? `<li><p>${inner}</p></li>` : `<li>${inner}</li>`;
+  }
+  case 'pre':
+    return convertCodeBlock(node, ctx);
+  case 'code':
+    // Inline only — `<code>` inside `<pre>` is consumed by convertCodeBlock.
+    return `<code${renderAttrs(node.attribs)}>${walkChildren(node, ctx)}</code>`;
+  case 'a':
+    return convertLink(node, ctx);
+  case 'blockquote':
+    return convertBlockquote(node, ctx);
+  case 'table':
+  case 'thead':
+  case 'tbody':
+  case 'tfoot':
+  case 'tr':
+    return `<${node.name}${renderAttrs(node.attribs)}>${walkChildren(node, ctx)}</${node.name}>`;
+  case 'th':
+  case 'td': {
+    const inner = walkChildren(node, ctx);
+    const open = `<${node.name}${renderAttrs(node.attribs)}>`;
+    return shouldWrapInP(node) ? `${open}<p>${inner}</p></${node.name}>` : `${open}${inner}</${node.name}>`;
+  }
+  default:
+    if (VOID_TAGS.has(node.name)) {
+      return `<${node.name}${renderAttrs(node.attribs)} />`;
+    }
+    return `<${node.name}${renderAttrs(node.attribs)}>${walkChildren(node, ctx)}</${node.name}>`;
+  }
+}
+
+function htmlToStorage(html, options = {}) {
+  const isCloud = !!options.isCloud;
+  const linkStyle = VALID_LINK_STYLES.includes(options.linkStyle)
+    ? options.linkStyle
+    : (isCloud ? 'smart' : 'wiki');
+  const ctx = {
+    linkStyle,
+    depth: 0,
+    maxDepth: typeof options.maxDepth === 'number' ? options.maxDepth : DEFAULT_MAX_DEPTH,
+  };
+  return walkChildren(parseDocument(html, { decodeEntities: false }), ctx);
+}
+
+module.exports = { htmlToStorage, HtmlDepthExceededError };

package/lib/macro-converter.js

@@ -1,5 +1,6 @@
 const MarkdownIt = require('markdown-it');
 const { StorageWalker } = require('./storage-walker');
+const { htmlToStorage } = require('./html-to-storage');
 
 const VALID_LINK_STYLES = ['smart', 'plain', 'wiki'];
 const CALLOUT_MARKERS = ['info', 'warning', 'note'];
@@ -39,9 +40,7 @@ class MacroConverter {
 
       // Anchor `[!info]` to the start of a line (string start or after a
       // newline) so prose mid-paragraph, headings on the same line, and
-      // `> [!info]` GitHub-style alerts are left alone. The latter would
-      // otherwise expand to a nested blockquote that the storage handler's
-      // lazy regex cannot balance, producing malformed XML.
+      // `> [!info]` GitHub-style alerts are left alone.
       for (const m of CALLOUT_MARKERS) {
         const re = new RegExp(`(^|\\n)\\[!${m}\\]\\s*([\\s\\S]*?)(?=\\n\\s*\\n|\\n\\s*\\[!|$)`, 'g');
         state.src = state.src.replace(re, (_, pre, content) =>
@@ -68,129 +67,7 @@ class MacroConverter {
   }
 
   htmlToConfluenceStorage(html) {
-    let storage = html;
-
-    storage = storage.replace(/<h([1-6])>(.*?)<\/h[1-6]>/g, '<h$1>$2</h$1>');
-
-    storage = storage.replace(/<p>(.*?)<\/p>/g, '<p>$1</p>');
-
-    storage = storage.replace(/<strong>(.*?)<\/strong>/g, '<strong>$1</strong>');
-
-    storage = storage.replace(/<em>(.*?)<\/em>/g, '<em>$1</em>');
-
-    storage = storage.replace(/<ul>(.*?)<\/ul>/gs, '<ul>$1</ul>');
-    storage = storage.replace(/<li>(.*?)<\/li>/g, '<li><p>$1</p></li>');
-
-    storage = storage.replace(/<ol>(.*?)<\/ol>/gs, '<ol>$1</ol>');
-
-    storage = storage.replace(/<pre><code(?:\s+class="language-(\w+)")?>(.*?)<\/code><\/pre>/gs, (_, lang, code) => {
-      const language = lang || 'text';
-      const decodedCode = code.replace(/\n$/, '')
-        .replace(/&quot;/g, '"')
-        .replace(/&lt;/g, '<')
-        .replace(/&gt;/g, '>')
-        .replace(/&amp;/g, '&');
-      const safeCode = decodedCode.replace(/]]>/g, ']]]]><![CDATA[>');
-      return `<ac:structured-macro ac:name="code"><ac:parameter ac:name="language">${language}</ac:parameter><ac:plain-text-body><![CDATA[${safeCode}]]></ac:plain-text-body></ac:structured-macro>`;
-    });
-
-    storage = storage.replace(/<code>(.*?)<\/code>/g, '<code>$1</code>');
-
-    // **TOC** paragraph → Confluence Table of Contents macro (uses macro defaults)
-    storage = storage.replace(
-      /<p><strong>TOC<\/strong><\/p>/g,
-      '<ac:structured-macro ac:name="toc" />'
-    );
-
-    storage = storage.replace(/<blockquote>(.*?)<\/blockquote>/gs, (_, content) => {
-      // Detect the marker only when it sits at the very start of the first
-      // paragraph, immediately followed by a `</p>` close (separated form) or
-      // a `\n` (same-line body form). This is the same anchor condition the
-      // strip step uses below, so detection and stripping stay in sync.
-      // Without this anchor, a quotation that merely *mentions* `**INFO**` —
-      // e.g. `> Use **INFO** at the start.` — would be silently wrapped in an
-      // info macro, surprising the author.
-      const marker = CALLOUT_MARKERS.find((m) =>
-        new RegExp(`<p><strong>${m.toUpperCase()}<\\/strong>(<\\/p>|\\s*\\n)`).test(content)
-      );
-      if (!marker) {
-        // Plain blockquote — `> …` is a quotation, not an alert. Use the
-        // `> **INFO**` / `> **WARNING**` / `> **NOTE**` markers above to
-        // produce a Confluence info / warning / note macro instead.
-        return `<blockquote>${content}</blockquote>`;
-      }
-      // Strip the leading `<strong>MARKER</strong>`. markdown-it produces two
-      // shapes depending on whether a blank `>` line separates marker and body:
-      //   case A (separated):  `<p><strong>MARKER</strong></p>\n<p>body</p>`
-      //   case B (same-line):  `<p><strong>MARKER</strong>\nbody</p>`
-      // The original cleanup only handled case A, so case B leaked the marker
-      // into the rendered macro body. README's recommended `> **INFO**\n> body`
-      // form parses as case B — exactly the form that broke.
-      const cleanContent = content.replace(
-        new RegExp(`<p><strong>${marker.toUpperCase()}<\\/strong>(<\\/p>\\s*|\\s*\\n)`),
-        (_, tail) => tail.startsWith('</p>') ? '' : '<p>'
-      );
-      return `<ac:structured-macro ac:name="${marker}">
-          <ac:rich-text-body>${cleanContent}</ac:rich-text-body>
-        </ac:structured-macro>`;
-    });
-
-    storage = storage.replace(/<table>(.*?)<\/table>/gs, '<table>$1</table>');
-    storage = storage.replace(/<thead>(.*?)<\/thead>/gs, '<thead>$1</thead>');
-    storage = storage.replace(/<tbody>(.*?)<\/tbody>/gs, '<tbody>$1</tbody>');
-    storage = storage.replace(/<tr>(.*?)<\/tr>/gs, '<tr>$1</tr>');
-    storage = storage.replace(/<th>(.*?)<\/th>/g, '<th><p>$1</p></th>');
-    storage = storage.replace(/<td>(.*?)<\/td>/g, '<td><p>$1</p></td>');
-
-    // **ANCHOR: id** paragraph → Confluence anchor macro
-    storage = storage.replace(
-      /<p><strong>ANCHOR: (.*?)<\/strong><\/p>/g,
-      '<ac:structured-macro ac:name="anchor"><ac:parameter ac:name="">$1</ac:parameter></ac:structured-macro>'
-    );
-
-    // **EXPAND: title** … **EXPAND_END** → Confluence expand macro. Runs
-    // after code/blockquote/table conversion so the body can contain those
-    // macros. Strips inline HTML from the title because Confluence's storage
-    // normalizer treats <ac:parameter> as text-only — it silently truncates
-    // at the first '<' and rejects <s> outright with HTTP 500. Entities
-    // (&amp;, &lt;) survive because the regex requires a literal '<'.
-    storage = storage.replace(
-      /<p><strong>EXPAND: (.*?)<\/strong><\/p>\s*([\s\S]*?)\s*<p><strong>EXPAND_END<\/strong><\/p>/g,
-      (_, title, body) => {
-        const cleanTitle = title.replace(/<[^>]+>/g, '').trim();
-        return `<ac:structured-macro ac:name="expand"><ac:parameter ac:name="title">${cleanTitle}</ac:parameter><ac:rich-text-body>${body.trim()}</ac:rich-text-body></ac:structured-macro>`;
-      }
-    );
-
-    // Same-page anchor links (href="#id") → ac:link with ac:anchor. Must run
-    // before the general link conversion below so the #id pattern is not
-    // consumed by the generic <a href> replacement (and so it works under
-    // all linkStyle modes, including "plain" which leaves <a> tags as-is).
-    storage = storage.replace(/<a href="#(.*?)">(.*?)<\/a>/gs, (_, anchor, body) => {
-      const text = body
-        .replace(/&amp;/g, '&')
-        .replace(/&lt;/g, '<')
-        .replace(/&gt;/g, '>')
-        .replace(/&quot;/g, '"')
-        .replace(/&#39;/g, '\'');
-      return `<ac:link ac:anchor="${anchor}"><ac:plain-text-link-body><![CDATA[${text}]]></ac:plain-text-link-body></ac:link>`;
-    });
-
-    // Convert links based on linkStyle:
-    //   "smart" — Cloud smart links (<a data-card-appearance="inline">)
-    //   "plain" — simple <a href>; workaround for "Cannot handle: DefaultLink"
-    //             errors on custom-domain Cloud instances
-    //   "wiki"  — Server/DC ac:link + ri:url storage format
-    if (this.linkStyle === 'smart') {
-      storage = storage.replace(/<a href="(.*?)">(.*?)<\/a>/g, '<a href="$1" data-card-appearance="inline">$2</a>');
-    } else if (this.linkStyle === 'wiki') {
-      storage = storage.replace(/<a href="(.*?)">(.*?)<\/a>/g, '<ac:link><ri:url ri:value="$1" /><ac:plain-text-link-body><![CDATA[$2]]></ac:plain-text-link-body></ac:link>');
-    }
-    // "plain" — leave <a href> tags as-is
-
-    storage = storage.replace(/<hr\s*\/?>/g, '<hr />');
-
-    return storage;
+    return htmlToStorage(html, { isCloud: this._isCloud, linkStyle: this.linkStyle });
   }
 
   detectLanguageLabels(text) {

package/lib/storage-walker.js

@@ -281,19 +281,23 @@ class StorageWalker {
 
   handleAnchor(node) {
     const param = this.findParamByName(node, '');
-    const id = param ? this.getTextContent(param) : '';
+    const id = (param ? this.getTextContent(param) : '').trim();
+    if (!id) return '';
     return `\n**ANCHOR: ${id}**\n`;
   }
 
   handlePanel(node) {
     const titleParam = this.findParamByName(node, 'title');
-    const title = titleParam ? this.getTextContent(titleParam) : '';
+    const title = (titleParam ? this.getTextContent(titleParam) : '').trim();
     const body = this.getMacroBody(node);
     // Trim before quoting — walkNodes wraps every <p> with a leading and
     // trailing \n, so untrimmed body splits into ['', 'body', ''] and emits
     // extra `>` blank lines that bracket the real content.
     const cleanContent = this.walkNodes(body).trim();
+    if (!title && !cleanContent) return '';
     const quoted = cleanContent.split('\n').map((line) => (line ? `> ${line}` : '>')).join('\n');
+    if (!title) return `\n${quoted}\n`;
+    if (!cleanContent) return `\n> **${title}**\n`;
     return `\n> **${title}**\n>\n${quoted}\n`;
   }
 
@@ -313,12 +317,13 @@ class StorageWalker {
     if (!riPage) return '';
     const spaceKey = decodeEntities(riPage.attribs['ri:space-key'] || '');
     const title = decodeEntities(riPage.attribs['ri:content-title'] || '');
+    const escapedTitle = this.escapeMarkdownText(title);
     const label = this.labels.includePage || 'Include Page';
     if (spaceKey.startsWith('~')) {
       const spacePath = `display/${spaceKey}/${encodeURIComponent(title)}`;
-      return `\n> 📄 **${label}**: [${title}](${this.buildUrl(`${this.webUrlPrefix}/${spacePath}`)})\n`;
+      return `\n> 📄 **${label}**: [${escapedTitle}](${this.buildUrl(`${this.webUrlPrefix}/${spacePath}`)})\n`;
     }
-    return `\n> 📄 **${label}**: [${title}](${this.buildUrl(`${this.webUrlPrefix}/spaces/${spaceKey}/pages/[PAGE_ID_HERE]`)}) _(manual link correction required)_\n`;
+    return `\n> 📄 **${label}**: [${escapedTitle}](${this.buildUrl(`${this.webUrlPrefix}/spaces/${spaceKey}/pages/[PAGE_ID_HERE]`)}) _(manual link correction required)_\n`;
   }
 
   handleSharedBlock(node, type) {
@@ -330,7 +335,7 @@ class StorageWalker {
       if (acLink) {
         const riPage = this.findChildByName(acLink, 'ri:page');
         if (riPage) {
-          const pageTitle = decodeEntities(riPage.attribs['ri:content-title'] || '');
+          const pageTitle = this.escapeMarkdownText(decodeEntities(riPage.attribs['ri:content-title'] || ''));
           const includeLabel = this.labels.includeSharedBlock || 'Include Shared Block';
           const fromPageLabel = this.labels.fromPage || 'from page';
           return `\n> 📄 **${includeLabel}**: ${blockKey} (${fromPageLabel}: ${pageTitle} [link needs manual correction])\n`;
@@ -394,7 +399,7 @@ class StorageWalker {
     }
     const riPage = this.findChildByName(node, 'ri:page');
     if (riPage) {
-      const title = decodeEntities(riPage.attribs['ri:content-title'] || '');
+      const title = this.escapeMarkdownText(decodeEntities(riPage.attribs['ri:content-title'] || ''));
       return `[${title}]`;
     }
     return '';
@@ -454,6 +459,16 @@ class StorageWalker {
     return decodeEntities(this._collectText(node));
   }
 
+  // Escape markdown structural characters in text that will be interpolated
+  // into link syntax (`[text](url)`). Confluence page titles can legitimately
+  // contain `()` / `[]`, and a maliciously-crafted title could otherwise inject
+  // a sibling link or break downstream parsers. Backslash is escaped so that
+  // an existing `\` in a title isn't reinterpreted as a markdown escape.
+  escapeMarkdownText(s) {
+    if (!s) return '';
+    return s.replace(/([\\[\]()])/g, '\\$1');
+  }
+
   _collectText(node) {
     if (!node) return '';
     if (node.type === 'text') return node.data || '';

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "confluence-cli",
-  "version": "2.1.8",
+  "version": "2.1.10",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "confluence-cli",
-      "version": "2.1.8",
+      "version": "2.1.10",
       "license": "MIT",
       "dependencies": {
         "axios": "^1.15.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "confluence-cli",
-  "version": "2.1.8",
+  "version": "2.1.10",
   "description": "A command-line interface for Atlassian Confluence with page creation and editing capabilities",
   "main": "index.js",
   "bin": {