@bestend/confluence-cli 1.15.8 → 1.16.1

package/AGENTS.md

@@ -0,0 +1,105 @@
+# Confluence CLI — 프로젝트 가이드
+
+## 아키텍처
+
+```
+bin/
+  index.js          # 엔트리포인트 (Node 버전 체크 → confluence.js 로딩)
+  confluence.js     # Commander CLI 정의 (모든 커맨드 등록)
+
+lib/
+  confluence-client.js  # 핵심 클라이언트 (API 호출, 포맷 변환, 페이지 CRUD)
+  config.js             # 설정 로드 (~/.confluence-cli/config.json)
+  analytics.js          # 익명 사용 통계
+
+tests/
+  confluence-client.test.js  # Jest 단위 테스트
+
+.github/workflows/
+  ci.yml        # push/PR → lint + test (Node 18.x, 20.x)
+  publish.yml   # tag push (v*) → npm publish with OIDC provenance
+```
+
+## 코드 스타일
+
+- ESLint flat config (`eslint.config.js`)
+- 들여쓰기: 2칸 스페이스
+- 따옴표: 작은따옴표
+- 세미콜론: 필수
+- `no-unused-vars`: `_` 접두사 무시
+
+## 핵심 변환 파이프라인
+
+```
+Markdown → MarkdownIt.render() → HTML → htmlToConfluenceStorage() → Storage XML
+```
+
+`htmlToConfluenceStorage()`는 MarkdownIt이 생성한 HTML 중 Confluence 전용 처리가 필요한 것만 변환:
+- `<li>` → `<li><p>...</p></li>` (Confluence 필수)
+- `<pre><code>` → `ac:structured-macro` code block with CDATA
+- `<blockquote>` → info/warning/note 매크로
+- `<th>`, `<td>` → `<p>` 래핑
+- `<hr>` → `<hr />` (self-closing)
+
+나머지 HTML 태그(h1-h6, p, strong, em, ul, ol, table 등)는 이미 Confluence storage와 호환되므로 변환하지 않음.
+
+## 버전 관리
+
+- `package.json`의 version은 직접 올리지 않아도 됨
+- publish.yml이 git tag에서 버전을 추출해서 package.json을 자동 맞춤
+- 단, 로컬 개발 시 혼동 방지를 위해 릴리스 전 맞춰두는 것을 권장
+
+## 릴리스 절차
+
+```bash
+# 1. 변경 커밋 (Conventional Commits)
+git add -A
+git commit -m "feat: add --parent option to create command"
+
+# 2. 태그 생성 (SemVer)
+git tag v1.16.0
+
+# 3. 푸시 (커밋 + 태그)
+git push origin main --follow-tags
+```
+
+태그 push 시 자동으로:
+1. `ci.yml` → lint + test (push to main 트리거)
+2. `publish.yml` → npm publish with OIDC provenance (tag 트리거)
+
+### 버전 결정 기준
+
+| 변경 유형 | 예시 | 버전 |
+|-----------|------|------|
+| 새 명령어/옵션 추가 | `--parent` 옵션 | minor (x.Y.0) |
+| 버그 수정, 내부 정리 | no-op regex 제거 | patch (x.y.Z) |
+| 하위 호환 깨짐 | 명령어 인터페이스 변경 | major (X.0.0) |
+
+### npm OIDC Trusted Publishing
+
+publish.yml은 `id-token: write` 권한으로 npm OIDC provenance를 사용.
+npm 토큰이 아닌 GitHub Actions OIDC로 인증하므로 시크릿 관리 불필요.
+Node.js 24.x (npm 11.5.1+) 필요.
+
+## 테스트
+
+```bash
+npm test          # Jest 단위 테스트 (40개)
+npm run lint      # ESLint
+```
+
+테스트는 `axios-mock-adapter`로 HTTP 모킹. 실제 Confluence 인스턴스 불필요.
+
+## agent-rules 연동
+
+이 CLI는 [mona/agent-rules](https://oss.navercorp.com/mona/agent-rules)의 `confluence-cli` 스킬로 사용됨:
+- 스킬 문서: `sources/skills/confluence-cli/SKILL.md`
+- 설치: `npm install -g @bestend/confluence-cli@latest`
+
+CLI 버전 릴리스 후 agent-rules의 SKILL.md `metadata.version`도 맞춰 업데이트할 것.
+
+## 금지 사항
+
+- `htmlToConfluenceStorage()`에 no-op regex 추가 금지 (X→X 변환은 의미 없음)
+- 전역 entity unescape (`&lt;`→`<` 등) 금지 — code block 내부는 이미 별도 디코딩됨
+- OIDC publish 설정 변경 시 Node.js 24.x 이상 유지 필수

package/bin/confluence.js

@@ -141,11 +141,12 @@ program
 
 // Create command
 program
-  .command('create <title> <spaceKey>')
+  .command('create <title> [spaceKey]')
   .description('Create a new Confluence page')
   .option('-f, --file <file>', 'Read content from file')
   .option('-c, --content <content>', 'Page content as string')
   .option('--format <format>', 'Content format (storage, html, markdown)', 'storage')
+  .option('--parent <parentId>', 'Parent page ID (creates page as child of this page)')
   .option('--validate-storage', 'Validate storage content (XML well-formed) before sending')
   .option('--no-sanitize-storage', 'Disable auto-escaping raw ampersands in storage format')
   .action(async (title, spaceKey, options) => {
@@ -168,17 +169,33 @@ program
         throw new Error('Either --file or --content option is required');
       }
       
-      const result = await client.createPage(title, spaceKey, content, options.format, {
-        validateStorage: options.validateStorage,
-        sanitizeStorage: options.sanitizeStorage
-      });
-      
-      console.log(chalk.green('✅ Page created successfully!'));
-      console.log(`Title: ${chalk.blue(result.title)}`);
-      console.log(`ID: ${chalk.blue(result.id)}`);
+      let result;
+      if (options.parent) {
+        const parentInfo = await client.getPageInfo(options.parent);
+        const derivedSpaceKey = parentInfo.space.key;
+        result = await client.createChildPage(title, derivedSpaceKey, options.parent, content, options.format, {
+          validateStorage: options.validateStorage,
+          sanitizeStorage: options.sanitizeStorage
+        });
+        console.log(chalk.green('✅ Page created successfully!'));
+        console.log(`Title: ${chalk.blue(result.title)}`);
+        console.log(`ID: ${chalk.blue(result.id)}`);
+        console.log(`Parent: ${chalk.blue(parentInfo.title)} (${options.parent})`);
+      } else {
+        if (!spaceKey) {
+          throw new Error('Space key is required when --parent is not specified');
+        }
+        result = await client.createPage(title, spaceKey, content, options.format, {
+          validateStorage: options.validateStorage,
+          sanitizeStorage: options.sanitizeStorage
+        });
+        console.log(chalk.green('✅ Page created successfully!'));
+        console.log(`Title: ${chalk.blue(result.title)}`);
+        console.log(`ID: ${chalk.blue(result.id)}`);
+      }
       console.log(`Space: ${chalk.blue(result.space.name)} (${result.space.key})`);
-      console.log(`URL: ${chalk.gray(`https://${config.domain}/wiki${result._links.webui}`)}`);
-      
+      console.log(`URL: ${chalk.gray(client.pageUrl(result._links.webui))}`);
+
       analytics.track('create', true);
     } catch (error) {
       analytics.track('create', false);
@@ -232,8 +249,8 @@ program
       console.log(`ID: ${chalk.blue(result.id)}`);
       console.log(`Parent: ${chalk.blue(parentInfo.title)} (${parentId})`);
       console.log(`Space: ${chalk.blue(result.space.name)} (${result.space.key})`);
-      console.log(`URL: ${chalk.gray(`https://${config.domain}/wiki${result._links.webui}`)}`);
-      
+      console.log(`URL: ${chalk.gray(client.pageUrl(result._links.webui))}`);
+
       analytics.track('create_child', true);
     } catch (error) {
       analytics.track('create_child', false);
@@ -284,8 +301,8 @@ program
       console.log(`Title: ${chalk.blue(result.title)}`);
       console.log(`ID: ${chalk.blue(result.id)}`);
       console.log(`Version: ${chalk.blue(result.version.number)}`);
-      console.log(`URL: ${chalk.gray(`https://${config.domain}/wiki${result._links.webui}`)}`);
-      
+      console.log(`URL: ${chalk.gray(client.pageUrl(result._links.webui))}`);
+
       analytics.track('update', true);
     } catch (error) {
       analytics.track('update', false);
@@ -390,8 +407,8 @@ program
       console.log(`Title: ${chalk.green(pageInfo.title)}`);
       console.log(`ID: ${chalk.green(pageInfo.id)}`);
       console.log(`Space: ${chalk.green(pageInfo.space.name)} (${pageInfo.space.key})`);
-      console.log(`URL: ${chalk.gray(`https://${config.domain}/wiki${pageInfo.url}`)}`);
-      
+      console.log(`URL: ${chalk.gray(client.pageUrl(pageInfo.url))}`);
+
       analytics.track('find', true);
     } catch (error) {
       analytics.track('find', false);
@@ -1067,7 +1084,7 @@ program
           console.log(` - ...and ${result.failures.length - 10} more`);
         }
       }
-      console.log(`URL: ${chalk.gray(`https://${config.domain}/wiki${result.rootPage._links.webui}`)}`);
+      console.log(`URL: ${chalk.gray(client.pageUrl(result.rootPage._links.webui))}`);
       if (options.failOnError && result.failures?.length) {
         analytics.track('copy_tree', false);
         console.error(chalk.red('Completed with failures and --fail-on-error is set.'));
@@ -1129,7 +1146,7 @@ program
             type: page.type,
             status: page.status,
             spaceKey: page.space?.key,
-            url: `https://${config.domain}/wiki/spaces/${page.space?.key}/pages/${page.id}`,
+            url: client.pageUrl(`/spaces/${page.space?.key}/pages/${page.id}`),
             parentId: page.parentId || resolvedPageId
           }))
         };
@@ -1141,7 +1158,7 @@ program
         
         // Build tree structure
         const tree = buildTree(children, resolvedPageId);
-        printTree(tree, config, options, 1);
+        printTree(tree, client, options, 1);
         
         console.log('');
         console.log(chalk.gray(`Total: ${children.length} child page${children.length === 1 ? '' : 's'}`));
@@ -1158,7 +1175,7 @@ program
           }
           
           if (options.showUrl) {
-            const url = `https://${config.domain}/wiki/spaces/${page.space?.key}/pages/${page.id}`;
+            const url = client.pageUrl(`/spaces/${page.space?.key}/pages/${page.id}`);
             output += `\n   ${chalk.gray(url)}`;
           }
           
@@ -1210,27 +1227,27 @@ function buildTree(pages, rootId) {
 }
 
 // Helper function to print tree
-function printTree(nodes, config, options, depth = 1) {
+function printTree(nodes, client, options, depth = 1) {
   nodes.forEach((node, index) => {
     const isLast = index === nodes.length - 1;
     const indent = '  '.repeat(depth - 1);
     const prefix = isLast ? '└── ' : '├── ';
-    
+
     let output = `${indent}${prefix}📄 ${chalk.green(node.title)}`;
-    
+
     if (options.showId) {
       output += ` ${chalk.gray(`(ID: ${node.id})`)}`;
     }
-    
+
     if (options.showUrl) {
-      const url = `https://${config.domain}/wiki/spaces/${node.space?.key}/pages/${node.id}`;
+      const url = client.pageUrl(`/spaces/${node.space?.key}/pages/${node.id}`);
       output += `\n${indent}${isLast ? '    ' : '│   '}${chalk.gray(url)}`;
     }
-    
+
     console.log(output);
-    
+
     if (node.children && node.children.length > 0) {
-      printTree(node.children, config, options, depth + 1);
+      printTree(node.children, client, options, depth + 1);
     }
   });
 }

package/lib/confluence-client.js

@@ -23,6 +23,25 @@ class ConfluenceClient {
       baseURL: this.baseURL,
       headers
     });
+
+    // Auto-detect context path (e.g., "/wiki" or "") from first API response
+    this._contextPath = null;
+    this.client.interceptors.response.use((response) => {
+      if (this._contextPath === null && response.data?._links?.context !== undefined) {
+        this._contextPath = response.data._links.context;
+      }
+      return response;
+    });
+  }
+
+  /**
+   * Build a full page URL from a webui path (e.g., /spaces/SPACE/pages/123)
+   * Context path is auto-detected from API responses.
+   */
+  pageUrl(path) {
+    if (!path) return '';
+    const context = this._contextPath || '';
+    return `https://${this.domain}${context}${path}`;
   }
 
   sanitizeStorageContent(content, options = {}) {
@@ -373,7 +392,7 @@ class ConfluenceClient {
         const webui = page._links?.webui || '';
         return {
           title: page.title,
-          url: webui ? `https://${this.domain}/wiki${webui}` : ''
+          url: this.pageUrl(webui)
         };
       }
       return null;
@@ -467,7 +486,7 @@ class ConfluenceClient {
       // Format: - [Page Title](URL)
       const childPagesList = childPages.map(page => {
         const webui = page._links?.webui || '';
-        const url = webui ? `https://${this.domain}/wiki${webui}` : '';
+        const url = this.pageUrl(webui);
         if (url) {
           return `- [${page.title}](${url})`;
         } else {
@@ -853,27 +872,18 @@ class ConfluenceClient {
    * Convert HTML to native Confluence storage format
    */
   htmlToConfluenceStorage(html) {
+    // MarkdownIt already produces valid HTML tags (h1-h6, p, strong, em, ul, ol, table, etc.)
+    // This function only transforms elements that need Confluence-specific handling:
+    // - li content wrapped in p (Confluence requirement)
+    // - pre/code → ac:structured-macro code blocks with CDATA
+    // - blockquote → info/warning/note macros
+    // - th/td content wrapped in p
+    // - hr → self-closing hr /
     let storage = html;
     
-    // Convert headings to native Confluence format
-    storage = storage.replace(/<h([1-6])>(.*?)<\/h[1-6]>/g, '<h$1>$2</h$1>');
-    
-    // Convert paragraphs
-    storage = storage.replace(/<p>(.*?)<\/p>/g, '<p>$1</p>');
-    
-    // Convert strong/bold text
-    storage = storage.replace(/<strong>(.*?)<\/strong>/g, '<strong>$1</strong>');
-    
-    // Convert emphasis/italic text
-    storage = storage.replace(/<em>(.*?)<\/em>/g, '<em>$1</em>');
-    
-    // Convert unordered lists
-    storage = storage.replace(/<ul>(.*?)<\/ul>/gs, '<ul>$1</ul>');
+    // Wrap li content in p tags (Confluence requirement)
     storage = storage.replace(/<li>(.*?)<\/li>/g, '<li><p>$1</p></li>');
     
-    // Convert ordered lists
-    storage = storage.replace(/<ol>(.*?)<\/ol>/gs, '<ol>$1</ol>');
-    
     // Convert code blocks to Confluence code macro
     storage = storage.replace(/<pre><code(?:\s+class="language-(\w+)")?>(.*?)<\/code><\/pre>/gs, (_, lang, code) => {
       const language = lang || 'text';
@@ -892,9 +902,6 @@ class ConfluenceClient {
       </ac:structured-macro>`;
     });
     
-    // Convert inline code
-    storage = storage.replace(/<code>(.*?)<\/code>/g, '<code>$1</code>');
-    
     // Convert blockquotes to appropriate macros based on content
     storage = storage.replace(/<blockquote>(.*?)<\/blockquote>/gs, (_, content) => {
       // Check for admonition patterns
@@ -921,11 +928,7 @@ class ConfluenceClient {
       }
     });
     
-    // Convert tables
-    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>');
+    // Wrap th/td content in p tags (Confluence requirement)
     storage = storage.replace(/<th>(.*?)<\/th>/g, '<th><p>$1</p></th>');
     storage = storage.replace(/<td>(.*?)<\/td>/g, '<td><p>$1</p></td>');
     
@@ -934,9 +937,6 @@ class ConfluenceClient {
     // Convert horizontal rules
     storage = storage.replace(/<hr\s*\/?>/g, '<hr />');
     
-    // Clean up any remaining HTML entities and normalize whitespace
-    storage = storage.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
-    
     return storage;
   }
 
@@ -1154,12 +1154,12 @@ class ConfluenceClient {
     markdown = markdown.replace(/<ac:structured-macro ac:name="include"[^>]*>[\s\S]*?<ac:parameter ac:name="">[\s\S]*?<ac:link>[\s\S]*?<ri:page\s+ri:space-key="([^"]+)"\s+ri:content-title="([^"]+)"[^>]*\/>[\s\S]*?<\/ac:link>[\s\S]*?<\/ac:parameter>[\s\S]*?<\/ac:structured-macro>/g, (_, spaceKey, title) => {
       // Try to build a proper URL - if spaceKey starts with ~, it's a user space
       if (spaceKey.startsWith('~')) {
-        const spacePath = `display/${spaceKey}/${encodeURIComponent(title)}`;
-        return `\n> 📄 **${labels.includePage}**: [${title}](https://${this.domain}/wiki/${spacePath})\n`;
+        const spacePath = `/display/${spaceKey}/${encodeURIComponent(title)}`;
+        return `\n> 📄 **${labels.includePage}**: [${title}](${this.pageUrl(spacePath)})\n`;
       } else {
         // For non-user spaces, we cannot construct a valid link without the page ID.
         // Document that manual correction is required.
-        return `\n> 📄 **${labels.includePage}**: [${title}](https://${this.domain}/wiki/spaces/${spaceKey}/pages/[PAGE_ID_HERE]) _(manual link correction required)_\n`;
+        return `\n> 📄 **${labels.includePage}**: [${title}](${this.pageUrl(`/spaces/${spaceKey}/pages/[PAGE_ID_HERE]`)}) _(manual link correction required)_\n`;
       }
     });
     

package/package.json

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