confluence-cli 1.31.0 → 1.32.0

package/README.md

@@ -304,6 +304,9 @@ For **read-only** usage, select at minimum: `read:confluence-content.all`, `read
 # Read by page ID
 confluence read 123456789
 
+# Read native Confluence storage content
+confluence read 123456789 --format storage
+
 # Read in markdown format
 confluence read 123456789 --format markdown
 
@@ -311,9 +314,28 @@ confluence read 123456789 --format markdown
 confluence read "https://your-domain.atlassian.net/wiki/viewpage.action?pageId=123456789"
 ```
 
+Use `--format storage` when you need Confluence's native storage representation, especially for macros and other Confluence-specific markup.
+
 ### Get Page Information
 ```bash
 confluence info 123456789
+
+# Emit machine-readable metadata
+confluence info 123456789 --format json
+```
+
+Example JSON shape:
+```json
+{
+  "id": "123456789",
+  "title": "Architecture Overview",
+  "type": "page",
+  "status": "current",
+  "spaceKey": "ENG",
+  "parentId": "100200300",
+  "version": 7,
+  "url": "https://your-domain.atlassian.net/wiki/spaces/ENG/pages/123456789/Architecture+Overview"
+}
 ```
 
 ### Search Pages
@@ -444,6 +466,36 @@ confluence children 123456789 --recursive --max-depth 3
 confluence children 123456789 --recursive --format json > children.json
 ```
 
+`children --format json` returns structured metadata for each page, including `id`, `title`, `type`, `status`, `spaceKey`, `parentId`, `version`, and `url`. Recursive output also includes `depth`, and when available, `ancestors`.
+
+Example recursive JSON item:
+```json
+{
+  "pageId": "123456789",
+  "childCount": 2,
+  "children": [
+    {
+      "id": "200300400",
+      "title": "Child Page",
+      "type": "page",
+      "status": "current",
+      "spaceKey": "ENG",
+      "parentId": "123456789",
+      "version": 4,
+      "url": "https://your-domain.atlassian.net/wiki/spaces/ENG/pages/200300400/Child+Page",
+      "depth": 1,
+      "ancestors": [
+        {
+          "id": "123456789",
+          "type": "page",
+          "title": "Architecture Overview"
+        }
+      ]
+    }
+  ]
+}
+```
+
 ### Find a Page by Title
 ```bash
 # Find page by title
@@ -612,8 +664,8 @@ confluence stats
 | Command | Description | Options |
 |---|---|---|
 | `init` | Initialize CLI configuration | `--read-only` |
-| `read <pageId_or_url>` | Read page content | `--format <html\|text\|markdown>` |
-| `info <pageId_or_url>` | Get page information | |
+| `read <pageId_or_url>` | Read page content | `--format <html\|text\|storage\|markdown>` |
+| `info <pageId_or_url>` | Get page information | `--format <text\|json>` |
 | `search <query>` | Search for pages | `--limit <number>` |
 | `spaces` | List all available spaces | |
 | `find <title>` | Find a page by its title | `--space <spaceKey>` |

package/bin/confluence.js

@@ -63,7 +63,7 @@ program
 program
   .command('read <pageId>')
   .description('Read a Confluence page by ID or URL')
-  .option('-f, --format <format>', 'Output format (html, text, markdown)', 'text')
+  .option('-f, --format <format>', 'Output format (html, text, storage, markdown)', 'text')
   .action(async (pageId, options) => {
     const analytics = new Analytics();
     try {
@@ -80,18 +80,24 @@ program
 program
   .command('info <pageId>')
   .description('Get information about a Confluence page')
-  .action(async (pageId) => {
+  .option('-f, --format <format>', 'Output format (text, json)', 'text')
+  .action(async (pageId, options) => {
     const analytics = new Analytics();
     try {
       const client = new ConfluenceClient(getConfig(getProfileName()));
       const info = await client.getPageInfo(pageId);
-      console.log(chalk.blue('Page Information:'));
-      console.log(`Title: ${chalk.green(info.title)}`);
-      console.log(`ID: ${chalk.green(info.id)}`);
-      console.log(`Type: ${chalk.green(info.type)}`);
-      console.log(`Status: ${chalk.green(info.status)}`);
-      if (info.space) {
-        console.log(`Space: ${chalk.green(info.space.name)} (${info.space.key})`);
+
+      if ((options.format || 'text').toLowerCase() === 'json') {
+        console.log(JSON.stringify(info, null, 2));
+      } else {
+        console.log(chalk.blue('Page Information:'));
+        console.log(`Title: ${chalk.green(info.title)}`);
+        console.log(`ID: ${chalk.green(info.id)}`);
+        console.log(`Type: ${chalk.green(info.type)}`);
+        console.log(`Status: ${chalk.green(info.status)}`);
+        if (info.space) {
+          console.log(`Space: ${chalk.green(info.space.name)} (${info.space.key})`);
+        }
       }
       analytics.track('info', true);
     } catch (error) {
@@ -1739,6 +1745,7 @@ program
     try {
       const config = getConfig(getProfileName());
       const client = new ConfluenceClient(config);
+      const format = (options.format || 'list').toLowerCase();
       
       // Extract page ID from URL if needed
       const resolvedPageId = await client.extractPageId(pageId);
@@ -1747,34 +1754,56 @@ program
       let children;
       if (options.recursive) {
         const maxDepth = parseInt(options.maxDepth) || 10;
-        children = await client.getAllDescendantPages(resolvedPageId, maxDepth);
+        children = await client.getAllDescendantPages(
+          resolvedPageId,
+          maxDepth,
+          { includeAncestors: format === 'json' }
+        );
       } else {
         children = await client.getChildPages(resolvedPageId);
       }
       
       if (children.length === 0) {
-        console.log(chalk.yellow('No child pages found.'));
+        if (format === 'json') {
+          console.log(JSON.stringify({
+            pageId: String(resolvedPageId),
+            childCount: 0,
+            children: []
+          }, null, 2));
+        } else {
+          console.log(chalk.yellow('No child pages found.'));
+        }
         analytics.track('children', true);
         return;
       }
       
-      // Format output
-      const format = options.format.toLowerCase();
-      
       if (format === 'json') {
         // JSON output
         const output = {
-          pageId: resolvedPageId,
+          pageId: String(resolvedPageId),
           childCount: children.length,
-          children: children.map(page => ({
-            id: page.id,
-            title: page.title,
-            type: page.type,
-            status: page.status,
-            spaceKey: page.space?.key,
-            url: `${client.buildUrl(`${client.webUrlPrefix}/spaces/${page.space?.key}/pages/${page.id}`)}`,
-            parentId: page.parentId || resolvedPageId
-          }))
+          children: children.map(page => {
+            const record = {
+              id: page.id,
+              title: page.title,
+              type: page.type,
+              status: page.status,
+              spaceKey: page.spaceKey || page.space?.key || null,
+              parentId: page.parentId || String(resolvedPageId),
+              version: page.version ?? null,
+              url: page.url || null
+            };
+
+            if (options.recursive && page.depth !== undefined) {
+              record.depth = page.depth;
+            }
+
+            if (options.recursive && Array.isArray(page.ancestors) && page.ancestors.length > 0) {
+              record.ancestors = page.ancestors;
+            }
+
+            return record;
+          })
         };
         console.log(JSON.stringify(output, null, 2));
       } else if (format === 'tree' && options.recursive) {