atl-fetch 1.1.0 → 1.2.1

package/README.md

@@ -25,7 +25,18 @@ Atlassian Cloud（Jira / Confluence）から情報を取得する Node.js CLI
 - Node.js 22.0.0 以上
 - pnpm（推奨）または npm
 
-## インストール
+## 使い方
+
+### npx で即時実行（インストール不要）
+
+```bash
+# 環境変数を設定して実行
+ATLASSIAN_EMAIL="your-email@example.com" \
+ATLASSIAN_API_TOKEN="your-api-token" \
+npx atl-fetch https://your-domain.atlassian.net/browse/PROJECT-123
+```
+
+### グローバルインストール
 
 ```bash
 # npm
@@ -50,21 +61,23 @@ API トークンは [Atlassian Account Settings](https://id.atlassian.com/manage
 
 ```bash
 # Jira Issue を取得
-atl-fetch https://your-domain.atlassian.net/browse/PROJECT-123
+npx atl-fetch https://your-domain.atlassian.net/browse/PROJECT-123
 
 # Confluence ページを取得
-atl-fetch https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/123456/Page+Title
+npx atl-fetch https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/123456/Page+Title
 
 # Markdown 形式で出力
-atl-fetch https://your-domain.atlassian.net/browse/PROJECT-123 --format markdown
+npx atl-fetch https://your-domain.atlassian.net/browse/PROJECT-123 --format markdown
 
 # 添付ファイルをダウンロード
-atl-fetch https://your-domain.atlassian.net/browse/PROJECT-123 --download --dir ./output
+npx atl-fetch https://your-domain.atlassian.net/browse/PROJECT-123 --download --dir ./output
 
 # ファイルに保存（リダイレクト）
-atl-fetch https://your-domain.atlassian.net/browse/PROJECT-123 > result.json
+npx atl-fetch https://your-domain.atlassian.net/browse/PROJECT-123 > result.json
 ```
 
+**Note**: グローバルインストール済みの場合は `npx` を省略して `atl-fetch` として実行できます。
+
 ## CLI オプション
 
 | オプション        | 短縮形  | 説明                           | デフォルト |
@@ -88,7 +101,7 @@ atl-fetch https://your-domain.atlassian.net/browse/PROJECT-123 > result.json
 認証情報の設定状態を確認します。
 
 ```bash
-atl-fetch auth check
+npx atl-fetch auth check
 ```
 
 出力例（設定済み）:

package/dist/services/fetch/fetch-service.js

@@ -3,7 +3,7 @@ import { fetchConfluencePage } from '../confluence/confluence-service.js';
 import { fetchJiraIssue } from '../jira/jira-service.js';
 import { formatConfluencePage, formatJiraIssue, writeToFile } from '../output/output-service.js';
 import { saveConfluencePage, saveConfluenceVersions, saveJiraIssue } from '../storage/storage-service.js';
-import { convertAdfToPlainText, convertStorageFormatToPlainText } from '../text-converter/text-converter.js';
+import { convertStorageFormatToPlainText } from '../text-converter/text-converter.js';
 import { parseUrl } from '../url-parser/url-parser.js';
 /**
  * Jira エラーを FetchError に変換する
@@ -230,15 +230,14 @@ export async function fetchAndSave(url, options) {
             return err(mapJiraErrorToFetchError(issueResult.error));
         }
         const issue = issueResult.value;
-        // ADF をプレーンテキストに変換
-        const descriptionPlainText = issue.description !== null ? convertAdfToPlainText(issue.description) : null;
         // Jira Issue をディレクトリ構造で保存
+        // description は ADF 形式で保存、descriptionPlainText は後方互換性のため維持
         const saveResult = await saveJiraIssue({
             attachments: issue.attachments,
             changelog: issue.changelog,
             comments: issue.comments,
-            description: issue.description,
-            descriptionPlainText,
+            description: issue.descriptionAdf,
+            descriptionPlainText: issue.description,
             key: issue.key,
             summary: issue.summary,
         }, {

package/dist/services/jira/jira-service.js

@@ -108,6 +108,7 @@ function mapApiCommentToJiraComment(apiComment) {
     return {
         author: apiComment.author.displayName,
         body: extractTextFromAdf(apiComment.body),
+        bodyAdf: apiComment.body,
         created: apiComment.created,
         id: apiComment.id,
         updated: apiComment.updated,
@@ -254,6 +255,7 @@ export async function fetchJiraIssue(organization, issueKey) {
         changelog: (apiResponse.changelog?.histories ?? []).map(mapApiChangelogEntryToJiraChangelogEntry),
         comments: (apiResponse.fields.comment?.comments ?? []).map(mapApiCommentToJiraComment),
         description: apiResponse.fields.description ? extractTextFromAdf(apiResponse.fields.description) : null,
+        descriptionAdf: apiResponse.fields.description,
         key: apiResponse.key,
         summary: apiResponse.fields.summary,
     };

package/dist/services/storage/storage-service.d.ts

@@ -16,9 +16,11 @@ import type { ConfluenceSaveData, ConfluenceSaveResult, ConfluenceStorageOptions
  * ├── manifest.json          # 取得メタデータ
  * ├── issue.json             # Issue 全データ（JSON 形式）
  * ├── description.txt        # 説明文のプレーンテキスト
- * ├── content.md             # Markdown 形式
- * ├── changelog.json         # 変更履歴
- * ├── comments.json          # コメント一覧
+ * ├── content.md             # Markdown 形式（Description + Attachments）
+ * ├── comments.md            # コメント一覧（Markdown 形式）
+ * ├── changelog.md           # 変更履歴（Markdown 形式）
+ * ├── changelog.json         # 変更履歴（JSON 形式）
+ * ├── comments.json          # コメント一覧（JSON 形式）
  * ├── attachments.json       # 添付ファイル一覧メタデータ
  * └── attachments/           # 添付ファイル実体
  *     └── {id}_{filename}

package/dist/services/storage/storage-service.js

@@ -10,7 +10,7 @@ import { ensureDir, writeFileContent } from '../../ports/file/file-port.js';
 import { downloadConfluenceAttachment } from '../confluence/confluence-service.js';
 import { diffText } from '../diff/diff-service.js';
 import { downloadJiraAttachment } from '../jira/jira-service.js';
-import { convertStorageFormatToMarkdown } from '../text-converter/text-converter.js';
+import { convertAdfToMarkdown, convertStorageFormatToMarkdown } from '../text-converter/text-converter.js';
 /**
  * 現在時刻を ISO 8601 形式で取得する
  *
@@ -51,9 +51,11 @@ const createJiraManifest = (data, options, attachmentResults) => {
  * ├── manifest.json          # 取得メタデータ
  * ├── issue.json             # Issue 全データ（JSON 形式）
  * ├── description.txt        # 説明文のプレーンテキスト
- * ├── content.md             # Markdown 形式
- * ├── changelog.json         # 変更履歴
- * ├── comments.json          # コメント一覧
+ * ├── content.md             # Markdown 形式（Description + Attachments）
+ * ├── comments.md            # コメント一覧（Markdown 形式）
+ * ├── changelog.md           # 変更履歴（Markdown 形式）
+ * ├── changelog.json         # 変更履歴（JSON 形式）
+ * ├── comments.json          # コメント一覧（JSON 形式）
  * ├── attachments.json       # 添付ファイル一覧メタデータ
  * └── attachments/           # 添付ファイル実体
  *     └── {id}_{filename}
@@ -150,7 +152,7 @@ export const saveJiraIssue = async (data, options) => {
             path: descPath,
         });
     }
-    // content.md を保存（Markdown 形式）
+    // content.md を保存（Markdown 形式：Description + Attachments）
     const markdownContent = formatJiraIssueAsMarkdown(data, attachmentResults);
     const markdownPath = join(issueDir, 'content.md');
     const markdownWriteResult = await writeFileContent(markdownPath, markdownContent);
@@ -161,6 +163,28 @@ export const saveJiraIssue = async (data, options) => {
             path: markdownPath,
         });
     }
+    // comments.md を保存（Markdown 形式）
+    const commentsMarkdownContent = formatCommentsAsMarkdown(data, attachmentResults);
+    const commentsMarkdownPath = join(issueDir, 'comments.md');
+    const commentsMarkdownWriteResult = await writeFileContent(commentsMarkdownPath, commentsMarkdownContent);
+    if (commentsMarkdownWriteResult.isErr()) {
+        return err({
+            kind: 'FILE_WRITE_FAILED',
+            message: `comments.md の書き込みに失敗しました: ${commentsMarkdownWriteResult.error.message}`,
+            path: commentsMarkdownPath,
+        });
+    }
+    // changelog.md を保存（Markdown 形式）
+    const changelogMarkdownContent = formatChangelogAsMarkdown(data);
+    const changelogMarkdownPath = join(issueDir, 'changelog.md');
+    const changelogMarkdownWriteResult = await writeFileContent(changelogMarkdownPath, changelogMarkdownContent);
+    if (changelogMarkdownWriteResult.isErr()) {
+        return err({
+            kind: 'FILE_WRITE_FAILED',
+            message: `changelog.md の書き込みに失敗しました: ${changelogMarkdownWriteResult.error.message}`,
+            path: changelogMarkdownPath,
+        });
+    }
     // changelog.json を保存
     const changelogPath = join(issueDir, 'changelog.json');
     const changelogWriteResult = await writeFileContent(changelogPath, JSON.stringify(data.changelog, null, 2));
@@ -199,54 +223,38 @@ export const saveJiraIssue = async (data, options) => {
 /**
  * Jira Issue を Markdown 形式にフォーマットする（ファイル保存用）
  *
+ * ADF (Atlassian Document Format) を Markdown に変換して保存する。
+ * Confluence と同様に構造を保持した Markdown を生成する。
+ *
  * @param data 保存データ
  * @param attachmentResults 添付ファイルのダウンロード結果
  * @returns Markdown 文字列
  */
 const formatJiraIssueAsMarkdown = (data, attachmentResults) => {
+    // 添付ファイル ID → savedPath のマッピングを生成
+    const attachmentPaths = {};
+    for (const att of attachmentResults) {
+        if (att.status === 'success' && att.savedPath !== undefined) {
+            attachmentPaths[att.id] = att.savedPath;
+        }
+    }
     const lines = [];
     // Title
     lines.push(`# ${data.key}`);
     lines.push('');
     lines.push(`**${data.summary}**`);
     lines.push('');
-    // Description
+    // Description - ADF を Markdown に変換
     lines.push('## Description');
     lines.push('');
-    lines.push(data.descriptionPlainText ?? '(No description)');
-    lines.push('');
-    // Comments
-    lines.push('## Comments');
-    lines.push('');
-    if (data.comments.length === 0) {
-        lines.push('No comments');
+    if (data.description !== null && data.description !== undefined) {
+        const descriptionMarkdown = convertAdfToMarkdown(data.description, attachmentPaths);
+        lines.push(descriptionMarkdown || '(No description)');
     }
     else {
-        for (const comment of data.comments) {
-            lines.push(`### ${comment.author} (${comment.created})`);
-            lines.push('');
-            lines.push(comment.body);
-            lines.push('');
-        }
+        lines.push('(No description)');
     }
-    // Changelog
-    lines.push('## Changelog');
     lines.push('');
-    if (data.changelog.length === 0) {
-        lines.push('No changelog');
-    }
-    else {
-        for (const entry of data.changelog) {
-            lines.push(`### ${entry.author} (${entry.created})`);
-            lines.push('');
-            for (const item of entry.items) {
-                const from = item.fromString ?? '(empty)';
-                const to = item.toString ?? '(empty)';
-                lines.push(`- **${item.field}**: ${from} → ${to}`);
-            }
-            lines.push('');
-        }
-    }
     // Attachments
     lines.push('## Attachments');
     lines.push('');
@@ -272,6 +280,66 @@ const formatJiraIssueAsMarkdown = (data, attachmentResults) => {
     }
     return lines.join('\n');
 };
+/**
+ * Jira コメントを Markdown 形式にフォーマットする（ファイル保存用）
+ *
+ * @param data 保存データ
+ * @param attachmentResults 添付ファイルのダウンロード結果
+ * @returns Markdown 文字列
+ */
+const formatCommentsAsMarkdown = (data, attachmentResults) => {
+    // 添付ファイル ID → savedPath のマッピングを生成
+    const attachmentPaths = {};
+    for (const att of attachmentResults) {
+        if (att.status === 'success' && att.savedPath !== undefined) {
+            attachmentPaths[att.id] = att.savedPath;
+        }
+    }
+    const lines = [];
+    lines.push(`# ${data.key} - Comments`);
+    lines.push('');
+    if (data.comments.length === 0) {
+        lines.push('No comments');
+    }
+    else {
+        for (const comment of data.comments) {
+            lines.push(`## ${comment.author} (${comment.created})`);
+            lines.push('');
+            // コメント本文も ADF 形式なので Markdown に変換
+            const commentMarkdown = convertAdfToMarkdown(comment.bodyAdf, attachmentPaths);
+            lines.push(commentMarkdown || comment.body);
+            lines.push('');
+        }
+    }
+    return lines.join('\n');
+};
+/**
+ * Jira 変更履歴を Markdown 形式にフォーマットする（ファイル保存用）
+ *
+ * @param data 保存データ
+ * @returns Markdown 文字列
+ */
+const formatChangelogAsMarkdown = (data) => {
+    const lines = [];
+    lines.push(`# ${data.key} - Changelog`);
+    lines.push('');
+    if (data.changelog.length === 0) {
+        lines.push('No changelog');
+    }
+    else {
+        for (const entry of data.changelog) {
+            lines.push(`## ${entry.author} (${entry.created})`);
+            lines.push('');
+            for (const item of entry.items) {
+                const from = item.fromString ?? '(empty)';
+                const to = item.toString ?? '(empty)';
+                lines.push(`- **${item.field}**: ${from} → ${to}`);
+            }
+            lines.push('');
+        }
+    }
+    return lines.join('\n');
+};
 /**
  * Confluence ページ用の Manifest を生成する
  *
@@ -735,4 +803,197 @@ if (import.meta.vitest) {
             });
         });
     });
+    describe('formatCommentsAsMarkdown (in-source testing)', () => {
+        // テストの目的: コメントがない場合に "No comments" が出力されること
+        it('Given: コメントがない JiraSaveData, When: formatCommentsAsMarkdown を呼び出す, Then: "No comments" が出力される', () => {
+            const data = {
+                attachments: [],
+                changelog: [],
+                comments: [],
+                description: null,
+                descriptionPlainText: null,
+                key: 'TEST-001',
+                summary: 'テスト',
+            };
+            const result = formatCommentsAsMarkdown(data, []);
+            expect(result).toContain('# TEST-001 - Comments');
+            expect(result).toContain('No comments');
+        });
+        // テストの目的: コメントが正しくフォーマットされること
+        it('Given: コメントを含む JiraSaveData, When: formatCommentsAsMarkdown を呼び出す, Then: コメントが Markdown 形式でフォーマットされる', () => {
+            const data = {
+                attachments: [],
+                changelog: [],
+                comments: [
+                    {
+                        author: 'TestUser',
+                        body: 'テストコメント',
+                        bodyAdf: null, // bodyAdf が null の場合は body が使用される
+                        created: '2024-01-15T10:30:00.000Z',
+                        id: 'cmt-1',
+                        updated: '2024-01-15T10:30:00.000Z',
+                    },
+                ],
+                description: null,
+                descriptionPlainText: null,
+                key: 'TEST-002',
+                summary: 'テスト',
+            };
+            const result = formatCommentsAsMarkdown(data, []);
+            expect(result).toContain('# TEST-002 - Comments');
+            expect(result).toContain('## TestUser');
+            expect(result).toContain('2024-01-15T10:30:00.000Z');
+            expect(result).toContain('テストコメント');
+        });
+        // テストの目的: 複数のコメントが正しくフォーマットされること
+        it('Given: 複数のコメントを含む JiraSaveData, When: formatCommentsAsMarkdown を呼び出す, Then: すべてのコメントが Markdown 形式でフォーマットされる', () => {
+            const data = {
+                attachments: [],
+                changelog: [],
+                comments: [
+                    {
+                        author: 'User1',
+                        body: 'コメント1',
+                        bodyAdf: null,
+                        created: '2024-01-15T10:00:00.000Z',
+                        id: 'cmt-1',
+                        updated: '2024-01-15T10:00:00.000Z',
+                    },
+                    {
+                        author: 'User2',
+                        body: 'コメント2',
+                        bodyAdf: null,
+                        created: '2024-01-16T11:00:00.000Z',
+                        id: 'cmt-2',
+                        updated: '2024-01-16T11:00:00.000Z',
+                    },
+                ],
+                description: null,
+                descriptionPlainText: null,
+                key: 'TEST-003',
+                summary: 'テスト',
+            };
+            const result = formatCommentsAsMarkdown(data, []);
+            expect(result).toContain('## User1');
+            expect(result).toContain('## User2');
+            expect(result).toContain('コメント1');
+            expect(result).toContain('コメント2');
+        });
+    });
+    describe('formatChangelogAsMarkdown (in-source testing)', () => {
+        // テストの目的: 変更履歴がない場合に "No changelog" が出力されること
+        it('Given: 変更履歴がない JiraSaveData, When: formatChangelogAsMarkdown を呼び出す, Then: "No changelog" が出力される', () => {
+            const data = {
+                attachments: [],
+                changelog: [],
+                comments: [],
+                description: null,
+                descriptionPlainText: null,
+                key: 'TEST-001',
+                summary: 'テスト',
+            };
+            const result = formatChangelogAsMarkdown(data);
+            expect(result).toContain('# TEST-001 - Changelog');
+            expect(result).toContain('No changelog');
+        });
+        // テストの目的: 変更履歴が正しくフォーマットされること
+        it('Given: 変更履歴を含む JiraSaveData, When: formatChangelogAsMarkdown を呼び出す, Then: 変更履歴が Markdown 形式でフォーマットされる', () => {
+            const data = {
+                attachments: [],
+                changelog: [
+                    {
+                        author: 'ChangeUser',
+                        created: '2024-01-15T10:00:00.000Z',
+                        id: 'cl-1',
+                        items: [{ field: 'status', fromString: 'Open', toString: 'In Progress' }],
+                    },
+                ],
+                comments: [],
+                description: null,
+                descriptionPlainText: null,
+                key: 'TEST-002',
+                summary: 'テスト',
+            };
+            const result = formatChangelogAsMarkdown(data);
+            expect(result).toContain('# TEST-002 - Changelog');
+            expect(result).toContain('## ChangeUser');
+            expect(result).toContain('2024-01-15T10:00:00.000Z');
+            expect(result).toContain('**status**');
+            expect(result).toContain('Open');
+            expect(result).toContain('In Progress');
+        });
+        // テストの目的: null 値が (empty) として表示されること
+        it('Given: fromString が null の変更履歴, When: formatChangelogAsMarkdown を呼び出す, Then: (empty) が表示される', () => {
+            const data = {
+                attachments: [],
+                changelog: [
+                    {
+                        author: 'ChangeUser',
+                        created: '2024-01-15T10:00:00.000Z',
+                        id: 'cl-1',
+                        items: [{ field: 'assignee', fromString: null, toString: 'Developer' }],
+                    },
+                ],
+                comments: [],
+                description: null,
+                descriptionPlainText: null,
+                key: 'TEST-003',
+                summary: 'テスト',
+            };
+            const result = formatChangelogAsMarkdown(data);
+            expect(result).toContain('(empty)');
+            expect(result).toContain('Developer');
+        });
+        // テストの目的: toString が null の場合も (empty) として表示されること
+        it('Given: toString が null の変更履歴, When: formatChangelogAsMarkdown を呼び出す, Then: (empty) が表示される', () => {
+            const data = {
+                attachments: [],
+                changelog: [
+                    {
+                        author: 'ChangeUser',
+                        created: '2024-01-15T10:00:00.000Z',
+                        id: 'cl-1',
+                        items: [{ field: 'assignee', fromString: 'Developer', toString: null }],
+                    },
+                ],
+                comments: [],
+                description: null,
+                descriptionPlainText: null,
+                key: 'TEST-004',
+                summary: 'テスト',
+            };
+            const result = formatChangelogAsMarkdown(data);
+            expect(result).toContain('Developer');
+            expect(result).toContain('(empty)');
+        });
+        // テストの目的: 複数の変更項目が正しくフォーマットされること
+        it('Given: 複数の変更項目を含む変更履歴, When: formatChangelogAsMarkdown を呼び出す, Then: すべての項目が Markdown 形式でフォーマットされる', () => {
+            const data = {
+                attachments: [],
+                changelog: [
+                    {
+                        author: 'ChangeUser',
+                        created: '2024-01-15T10:00:00.000Z',
+                        id: 'cl-1',
+                        items: [
+                            { field: 'status', fromString: 'Open', toString: 'In Progress' },
+                            { field: 'priority', fromString: 'Low', toString: 'High' },
+                        ],
+                    },
+                ],
+                comments: [],
+                description: null,
+                descriptionPlainText: null,
+                key: 'TEST-005',
+                summary: 'テスト',
+            };
+            const result = formatChangelogAsMarkdown(data);
+            expect(result).toContain('**status**');
+            expect(result).toContain('**priority**');
+            expect(result).toContain('Open');
+            expect(result).toContain('In Progress');
+            expect(result).toContain('Low');
+            expect(result).toContain('High');
+        });
+    });
 }

package/dist/services/text-converter/adf-to-html.d.ts

@@ -0,0 +1,37 @@
+/**
+ * ADF（Atlassian Document Format）→ HTML 変換
+ *
+ * Markdown 変換の中間形式として HTML を生成する
+ */
+import type { AdfMark, AdfNode, AttachmentPathMapping } from './types.js';
+/**
+ * HTML 特殊文字をエスケープする
+ *
+ * @param text エスケープ対象の文字列
+ * @returns エスケープ済み文字列
+ */
+export declare const escapeHtml: (text: string) => string;
+/**
+ * ADF マークを HTML タグで囲む
+ *
+ * @param text 対象のテキスト
+ * @param marks 適用するマーク配列
+ * @returns マークを適用した HTML
+ */
+export declare const applyMarksToHtml: (text: string, marks: readonly AdfMark[]) => string;
+/**
+ * ADF ノードを HTML に変換する
+ *
+ * @param node ADF ノード
+ * @param attachmentPaths 添付ファイル ID → ローカルパスのマッピング
+ * @returns HTML 文字列
+ */
+export declare const convertAdfNodeToHtml: (node: AdfNode, attachmentPaths?: AttachmentPathMapping) => string;
+/**
+ * ADF ドキュメントを HTML に変換する
+ *
+ * @param content ADF ドキュメントのコンテンツ配列
+ * @param attachmentPaths 添付ファイル ID → ローカルパスのマッピング
+ * @returns HTML 文字列
+ */
+export declare const convertAdfContentToHtml: (content: readonly AdfNode[] | undefined, attachmentPaths?: AttachmentPathMapping) => string;