confluence-cli 2.4.0 → 2.6.0

package/README.md

@@ -707,6 +707,9 @@ confluence stats
 | `update <pageId>` | Update a page's title or content | `--title <string>`, `--content <string>`, `--file <path>`, `--format <storage\|html\|markdown>` |
 | `move <pageId_or_url> <newParentId_or_url>` | Move a page to a new parent location | `--title <string>` |
 | `delete <pageId_or_url>` | Delete a page by ID or URL | `--yes` |
+| `versions <pageId_or_url>` | List historical versions of a page | `--format <text\|json>` |
+| `version-delete <pageId_or_url> <versionNumber>` | Delete a single non-current version of a page | `--yes` |
+| `versions-purge <pageId_or_url>` | Delete every non-current historical version of a page | `--yes`, `--throttle <seconds>` |
 | `edit <pageId>` | Export page content for editing | `--output <file>` |
 | `attachments <pageId_or_url>` | List or download attachments for a page | `--limit <number>`, `--pattern <glob>`, `--download`, `--dest <directory>` |
 | `attachment-upload <pageId_or_url>` | Upload attachments to a page | `--file <path>`, `--comment <text>`, `--replace`, `--minor-edit` |

package/bin/confluence.js

@@ -453,6 +453,147 @@ program
     }
   });
 
+// List historical versions of a page
+program
+  .command('versions <pageId>')
+  .description('List historical versions of a Confluence page')
+  .option('--format <format>', 'Output format: text or json (default: text)', 'text')
+  .action(async (pageId, options) => {
+    const analytics = new Analytics();
+    try {
+      const config = getConfig(getProfileName());
+      const client = new ConfluenceClient(config);
+      const resolvedId = String(await client.extractPageId(pageId));
+      const versions = await client.listVersions(resolvedId);
+
+      if (options.format === 'json') {
+        console.log(JSON.stringify({ pageId: resolvedId, versions }, null, 2));
+      } else {
+        const max = versions.length ? Math.max(...versions.map(v => v.number)) : 0;
+        console.log(chalk.blue(`Versions for page ${resolvedId} (${versions.length} total):`));
+        if (versions.length === 0) {
+          console.log(chalk.yellow('  (no versions returned)'));
+        }
+        for (const v of versions) {
+          const tag = v.number === max ? chalk.green(' [current]') : '';
+          const author = v.by || 'unknown';
+          const note = v.message ? `  — ${v.message}` : '';
+          console.log(`  v${v.number}${tag}  ${v.when}  ${author}${note}`);
+        }
+      }
+      analytics.track('versions', true);
+    } catch (error) {
+      handleCommandError(analytics, 'versions', error);
+    }
+  });
+
+// Delete a single historical version of a page
+program
+  .command('version-delete <pageId> <versionNumber>')
+  .description('Delete a single historical version of a page (cannot delete the current version)')
+  .option('-y, --yes', 'Skip confirmation prompt')
+  .action(async (pageId, versionNumber, options) => {
+    const analytics = new Analytics();
+    try {
+      const config = getConfig(getProfileName());
+      assertWritable(config);
+      const client = new ConfluenceClient(config);
+      const resolvedId = String(await client.extractPageId(pageId));
+      const n = Number(versionNumber);
+
+      if (!options.yes) {
+        const { confirmed } = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'confirmed',
+          default: false,
+          message: `Delete v${n} of page ${resolvedId}? This cannot be undone.`
+        }]);
+        if (!confirmed) {
+          console.log(chalk.yellow('Cancelled.'));
+          analytics.track('version_delete_cancel', true);
+          return;
+        }
+      }
+
+      const result = await client.deleteVersion(resolvedId, n);
+      const note = result.viaExperimental ? chalk.yellow(' (via experimental endpoint)') : '';
+      console.log(chalk.green(`✅ Deleted v${result.versionNumber} of page ${result.id}${note}`));
+      analytics.track('version_delete', true);
+    } catch (error) {
+      handleCommandError(analytics, 'version_delete', error);
+    }
+  });
+
+// Convenience: delete every non-current historical version of a page,
+// keeping only the current one.
+program
+  .command('versions-purge <pageId>')
+  .description('Delete every non-current historical version of a page (keeps only current)')
+  .option('-y, --yes', 'Skip confirmation prompt')
+  .option('--throttle <seconds>', 'Sleep between version-delete calls', '0')
+  .action(async (pageId, options) => {
+    const analytics = new Analytics();
+    try {
+      const config = getConfig(getProfileName());
+      assertWritable(config);
+      const client = new ConfluenceClient(config);
+      const resolvedId = String(await client.extractPageId(pageId));
+      const versions = await client.listVersions(resolvedId);
+
+      if (versions.length === 0) {
+        console.log(chalk.yellow(`No versions returned for page ${resolvedId}.`));
+        analytics.track('versions_purge', true);
+        return;
+      }
+      const max = Math.max(...versions.map(v => v.number));
+      const historicalCount = versions.filter(v => v.number !== max).length;
+      if (historicalCount === 0) {
+        console.log(chalk.yellow(`Only current version v${max} exists for page ${resolvedId}; nothing to purge.`));
+        analytics.track('versions_purge', true);
+        return;
+      }
+
+      if (!options.yes) {
+        const { confirmed } = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'confirmed',
+          default: false,
+          message: `Delete ${historicalCount} historical version(s) of page ${resolvedId}? Current version (v${max}) will be kept.`
+        }]);
+        if (!confirmed) {
+          console.log(chalk.yellow('Cancelled.'));
+          analytics.track('versions_purge_cancel', true);
+          return;
+        }
+      }
+
+      const throttleMs = Math.max(0, parseFloat(options.throttle || '0')) * 1000;
+      const result = await client.purgeNonCurrentVersions(resolvedId, {
+        onProgress: async (event) => {
+          if (event.kind === 'deleted') {
+            const note = event.viaExperimental ? chalk.yellow(' (experimental)') : '';
+            console.log(chalk.green(`  ✓ deleted v${event.versionNumber}${note}`));
+          } else if (event.kind === 'failed') {
+            console.log(chalk.red(`  ✗ v${event.versionNumber}: ${event.message}`));
+          }
+          if (throttleMs > 0) {
+            await new Promise(r => setTimeout(r, throttleMs));
+          }
+        }
+      });
+
+      console.log('');
+      console.log(chalk.green(`✅ Purge complete for page ${result.id}: ` +
+        `${result.deleted} deleted, ${result.failed} failed, kept v${result.kept}.`));
+      analytics.track('versions_purge', result.failed === 0);
+      if (result.failed > 0) {
+        process.exitCode = 1;
+      }
+    } catch (error) {
+      handleCommandError(analytics, 'versions_purge', error);
+    }
+  });
+
 // Edit command - opens page content for editing
 program
   .command('edit <pageId>')

package/lib/confluence-client.js

@@ -1443,6 +1443,148 @@ class ConfluenceClient {
     return { id: String(pageId) };
   }
 
+  /**
+   * Build the absolute URL for the experimental version endpoint.
+   * Confluence Server/Data Center exposes content versions only at
+   * /rest/experimental/ (the modern /rest/api/.../version path 404s
+   * there). Cloud accepts both. We use this as a fallback when the
+   * configured apiPath returns 404/405.
+   */
+  experimentalVersionUrl(pageId, versionNumber = null) {
+    const base = `${this.protocol}://${this.domain}${this.webUrlPrefix}/rest/experimental/content/${pageId}/version`;
+    return versionNumber == null ? base : `${base}/${versionNumber}`;
+  }
+
+  /**
+   * List historical versions of a page. Returns an array sorted by
+   * version number ascending. Each entry has: number, when, by,
+   * minorEdit, message.
+   *
+   * Pages with many versions (e.g. heavily edited or repeatedly
+   * uploaded) may exceed a single page of results, so this paginates
+   * via start/limit until all versions are collected.
+   *
+   * Path strategy: try the configured /rest/api/ path first; on 404
+   * or 405 (typical of Server/DC where the version endpoints live
+   * under /rest/experimental/), fall back transparently. Subsequent
+   * pages use whichever path succeeded so we don't double the
+   * round-trip count on long histories.
+   */
+  async listVersions(pageIdOrUrl) {
+    const pageId = await this.extractPageId(pageIdOrUrl);
+    const limit = 200;
+    let start = 0;
+    let useExperimental = false;
+    const all = [];
+    while (true) {
+      let response;
+      try {
+        const url = useExperimental
+          ? this.experimentalVersionUrl(pageId)
+          : `/content/${pageId}/version`;
+        response = await this.client.get(url, { params: { start, limit } });
+      } catch (error) {
+        const status = error.response && error.response.status;
+        if (!useExperimental && (status === 404 || status === 405)) {
+          useExperimental = true;
+          continue;
+        }
+        throw error;
+      }
+      const results = response.data.results || [];
+      all.push(...results);
+      if (results.length < limit) {
+        break;
+      }
+      start += limit;
+    }
+    return all.map(v => ({
+      number: v.number,
+      when: v.when,
+      by: v.by ? (v.by.displayName || v.by.publicName || v.by.email || null) : null,
+      minorEdit: v.minorEdit === true,
+      message: v.message || ''
+    })).sort((a, b) => a.number - b.number);
+  }
+
+  /**
+   * Delete a single historical version of a page.
+   *
+   * Confluence refuses to delete the current version (returns 400).
+   * The "rolled up into the next version" wording in Atlassian's
+   * docs refers to the diff representation; the deleted version's
+   * snapshot is removed from page history.
+   *
+   * Server/DC instances expose this only at /rest/experimental/, so
+   * a 404 or 405 on the configured /rest/api/ path triggers a
+   * one-shot retry against the experimental URL.
+   */
+  async deleteVersion(pageIdOrUrl, versionNumber) {
+    const pageId = await this.extractPageId(pageIdOrUrl);
+    const n = Number(versionNumber);
+    if (!Number.isInteger(n) || n < 1) {
+      throw new Error(`versionNumber must be a positive integer, got: ${versionNumber}`);
+    }
+    try {
+      await this.client.delete(`/content/${pageId}/version/${n}`);
+      return { id: String(pageId), versionNumber: n, viaExperimental: false };
+    } catch (error) {
+      const status = error.response && error.response.status;
+      if (status !== 404 && status !== 405) {
+        throw error;
+      }
+      await this.client.delete(this.experimentalVersionUrl(pageId, n));
+      return { id: String(pageId), versionNumber: n, viaExperimental: true };
+    }
+  }
+
+  /**
+   * Delete every non-current version of a page. Used to purge the
+   * historical content snapshots that may still hold a leaked secret
+   * even after the current version has been overwritten with a
+   * redacted copy.
+   *
+   * Returns { id, kept, deleted, failed } where `kept` is the version
+   * number that survived (the current one) and `deleted`/`failed` are
+   * the counts of historical versions removed/errored.
+   */
+  async purgeNonCurrentVersions(pageIdOrUrl, options = {}) {
+    const onProgress = typeof options.onProgress === 'function' ? options.onProgress : () => {};
+    const pageId = String(await this.extractPageId(pageIdOrUrl));
+    const versions = await this.listVersions(pageId);
+
+    if (versions.length === 0) {
+      return { id: pageId, kept: null, deleted: 0, failed: 0, errors: [] };
+    }
+
+    const max = Math.max(...versions.map(v => v.number));
+    // Delete in descending order. Some Confluence builds renumber
+    // historical versions when an earlier one is removed; deleting
+    // newest-first sidesteps the resulting off-by-one drift.
+    const toDelete = versions
+      .filter(v => v.number !== max)
+      .map(v => v.number)
+      .sort((a, b) => b - a);
+
+    let deleted = 0;
+    const errors = [];
+    for (const n of toDelete) {
+      try {
+        const res = await this.deleteVersion(pageId, n);
+        deleted += 1;
+        onProgress({ kind: 'deleted', versionNumber: n, viaExperimental: res.viaExperimental });
+      } catch (error) {
+        const detail = error.response
+          ? `HTTP ${error.response.status} ${error.response.statusText || ''}`.trim()
+          : error.message;
+        errors.push({ versionNumber: n, message: detail });
+        onProgress({ kind: 'failed', versionNumber: n, message: detail });
+      }
+    }
+
+    return { id: pageId, kept: max, deleted, failed: errors.length, errors };
+  }
+
   /**
    * Search for a page by title and space
    */

package/lib/html-to-storage.js

@@ -21,6 +21,8 @@ class HtmlDepthExceededError extends Error {
 // whatever shape the source had (markdown-it emits them without a slash).
 const VOID_TAGS = new Set(['hr']);
 const CALLOUT_MARKERS = ['info', 'warning', 'note'];
+// these tags are wrapped into Confluence HTML macro
+const HTML_MACRO_TAGS = new Set(['svg', 'div']);
 
 // Phrasing-content tags that trigger the `<li>` / `<th>` / `<td>` `<p>`-wrap
 // quirk: if an item contains only inline children and no text-node newline,
@@ -218,6 +220,36 @@ function convertBlockquote(node, ctx) {
         </ac:structured-macro>`;
 }
 
+// `<details><summary>` becomes expand macro. If no summary child is found,
+// falls through to plain HTML.
+function convertDetails(node, ctx) {
+  const children = node.children || [];
+  let summaryNode = null;
+  let bodyNodes = [];
+
+  for (const child of children) {
+    if (child.type === 'tag' && child.name === 'summary') {
+      summaryNode = child;
+    } else if (!isWhitespaceOnly(child)) {
+      bodyNodes.push(child);
+    }
+  }
+
+  if (!summaryNode) {
+    return `<details${renderAttrs(node.attribs)}>${walkChildren(node, ctx)}</details>`;
+  }
+
+  const titleHtml = walkChildren(summaryNode, ctx);
+  const cleanTitle = titleHtml.replace(/<[^>]+>/g, '').trim();
+
+  const bodyHtml = bodyNodes
+    .map((c) => walkNode(c, ctx))
+    .join('')
+    .trim();
+
+  return `<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>`;
+}
+
 // 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
@@ -243,6 +275,20 @@ function convertCodeBlock(node, ctx) {
   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>`;
 }
 
+// Wrap allowlisted HTML tags (svg, div) in Confluence HTML macro with CDATA.
+// Used for embedding custom HTML that Confluence doesn't natively support.
+function convertHtmlBlock(node, ctx) {
+  const { randomUUID } = require('crypto');
+  const inner = walkChildren(node, ctx);
+  const attrsStr = renderAttrs(node.attribs);
+  const openTag = `<${node.name}${attrsStr}>`;
+  const closeTag = `</${node.name}>`;
+  const htmlContent = openTag + inner + closeTag;
+  const safeContent = htmlContent.replace(/]]>/g, ']]]]><![CDATA[>');
+  const macroId = randomUUID();
+  return `<ac:structured-macro ac:name="html" ac:schema-version="1" ac:macro-id="${macroId}"><ac:plain-text-body><![CDATA[${safeContent}]]></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
@@ -344,10 +390,11 @@ function dispatchTag(node, ctx) {
     return `<img${renderAttrs(node.attribs)}>`;
   case 'ul':
   case 'ol':
-    return `<${node.name}>${walkChildren(node, ctx)}</${node.name}>`;
+    return `<${node.name}${renderAttrs(node.attribs)}>${walkChildren(node, ctx)}</${node.name}>`;
   case 'li': {
     const inner = walkChildren(node, ctx);
-    return shouldWrapInP(node) ? `<li><p>${inner}</p></li>` : `<li>${inner}</li>`;
+    const open = `<li${renderAttrs(node.attribs)}>`;
+    return shouldWrapInP(node) ? `${open}<p>${inner}</p></li>` : `${open}${inner}</li>`;
   }
   case 'pre':
     return convertCodeBlock(node, ctx);
@@ -358,6 +405,8 @@ function dispatchTag(node, ctx) {
     return convertLink(node, ctx);
   case 'blockquote':
     return convertBlockquote(node, ctx);
+  case 'details':
+    return convertDetails(node, ctx);
   case 'table':
   case 'thead':
   case 'tbody':
@@ -374,6 +423,9 @@ function dispatchTag(node, ctx) {
     if (VOID_TAGS.has(node.name)) {
       return `<${node.name}${renderAttrs(node.attribs)} />`;
     }
+    if (HTML_MACRO_TAGS.has(node.name)) {
+      return convertHtmlBlock(node, ctx);
+    }
     return `<${node.name}${renderAttrs(node.attribs)}>${walkChildren(node, ctx)}</${node.name}>`;
   }
 }

package/lib/macro-converter.js

@@ -21,7 +21,9 @@ const STASH_DELIM = '\uE000';
 // The body alternation `"[^"]*"|'[^']*'|[^>]` makes the match quote-aware
 // so a literal `>` inside a quoted attribute value (e.g.
 // `<mark title="1>0">`) does not terminate the tag prematurely.
-const PASSTHROUGH_TAG_RE = /<\/?(?:u|sub|sup|mark)(?=[\s/>])(?:"[^"]*"|'[^']*'|[^>])*>/gi;
+const PASSTHROUGH_TAG_RE = /<\/?(?:u|sub|sup|mark|details|summary)(?=[\s/>])(?:"[^"]*"|'[^']*'|[^>])*>/gi;
+// Block-level HTML elements that should pass through WITHOUT markdown processing of their content. 
+const PASSTHROUGH_BLOCK_RE = /<(svg|div)(?:\s[^>]*)?>[\s\S]*?<\/\1>/gi;
 // Single-backtick inline code spans. Block-level code (fenced + indented) is
 // detected via MarkdownIt's tokenizer in `_findCodeRanges` because a regex
 // can't reliably distinguish a 4-space-indented code block from a list-item
@@ -92,10 +94,19 @@ class MacroConverter {
   _renderMarkdownToHtml(markdown) {
     const codeRanges = this._findCodeRanges(markdown);
     const htmlStash = [];
-    const stashHtml = (text) => text.replace(PASSTHROUGH_TAG_RE, (m) => {
-      htmlStash.push(m);
-      return `${STASH_DELIM}H${htmlStash.length - 1}${STASH_DELIM}`;
-    });
+    const stashHtml = (text) => {
+      // block-level HTML (svg, div with all content) must be stashed before inline tags to avoid matching the closing tag as inline HTML
+      let result = text.replace(PASSTHROUGH_BLOCK_RE, (m) => {
+        htmlStash.push(m);
+        return `${STASH_DELIM}H${htmlStash.length - 1}${STASH_DELIM}`;
+      });
+      // Then stash inline HTML tags
+      result = result.replace(PASSTHROUGH_TAG_RE, (m) => {
+        htmlStash.push(m);
+        return `${STASH_DELIM}H${htmlStash.length - 1}${STASH_DELIM}`;
+      });
+      return result;
+    };
 
     let src = '';
     let pos = 0;

package/npm-shrinkwrap.json

@@ -1,15 +1,15 @@
 {
   "name": "confluence-cli",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "confluence-cli",
-      "version": "2.4.0",
+      "version": "2.6.0",
       "license": "MIT",
       "dependencies": {
-        "axios": "^1.15.0",
+        "axios": "~1.15.2",
         "chalk": "^4.1.2",
         "commander": "^11.1.0",
         "entities": "^4.5.0",
@@ -129,9 +129,9 @@
       "license": "MIT"
     },
     "node_modules/axios": {
-      "version": "1.15.0",
-      "resolved": "https://registry.npmjs.org/axios/-/axios-1.15.0.tgz",
-      "integrity": "sha512-wWyJDlAatxk30ZJer+GeCWS209sA42X+N5jU2jy6oHTp7ufw8uzUTVFBX9+wTfAlhiJXGS0Bq7X6efruWjuK9Q==",
+      "version": "1.15.2",
+      "resolved": "https://registry.npmjs.org/axios/-/axios-1.15.2.tgz",
+      "integrity": "sha512-wLrXxPtcrPTsNlJmKjkPnNPK2Ihe0hn0wGSaTEiHRPxwjvJwT3hKmXF4dpqxmPO9SoNb2FsYXj/xEo0gHN+D5A==",
       "license": "MIT",
       "dependencies": {
         "follow-redirects": "^1.15.11",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "confluence-cli",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "A command-line interface for Atlassian Confluence with page creation and editing capabilities",
   "main": "index.js",
   "bin": {
@@ -23,7 +23,7 @@
   "author": "pchuri",
   "license": "MIT",
   "dependencies": {
-    "axios": "^1.15.0",
+    "axios": "~1.15.2",
     "chalk": "^4.1.2",
     "commander": "^11.1.0",
     "entities": "^4.5.0",