backlog-exporter 1.0.0 → 1.1.1

package/dist/modules/document/use-case/export-documents.js

@@ -1,10 +1,11 @@
 import path from 'node:path';
 import { writeProgress } from '../../../shared/console/progress.js';
-import { deleteFile, ensureDirectory, fileExists, writeMarkdownFile } from '../../../shared/storage/markdown-store.js';
+import { deleteFile, ensureDirectory, fileExists, fileSize, writeBinaryFile, writeMarkdownFile, } from '../../../shared/storage/markdown-store.js';
 import { appendLog } from '../../../shared/storage/update-log.js';
 import { buildDocumentMarkdown } from '../domain/document-markdown.js';
-import { documentFileName, documentFolderPath, documentUrl, PARENT_DOCUMENT_INDEX_FILENAME, } from '../domain/document-path.js';
+import { DOCUMENT_FALLBACK_PARENT_PATH, documentAttachmentMarkdownLink, documentAttachmentRelativePath, documentFileName, documentFolderPath, documentUrl, PARENT_DOCUMENT_INDEX_FILENAME, } from '../domain/document-path.js';
 import { planDocumentSave } from '../domain/document-save-plan.js';
+import { findDocumentsMissingFromTree } from '../domain/document-tree-gap.js';
 export async function exportDocuments(deps, options) {
     const { documentRepository, logger } = deps;
     logger.log('ドキュメントの取得を開始します...');
@@ -13,13 +14,15 @@ export async function exportDocuments(deps, options) {
     logger.log('アクティブなドキュメントツリーを処理します...');
     const processedDocuments = [];
     const writtenFiles = new Set();
-    const fetchAndSaveDocument = async (node, currentPath, asParentIndex = false) => {
+    // 戻り値はファイルを書き出したかどうか（保存件数の集計に使う）
+    const fetchAndSaveDocument = async (node, currentPath, placement = {}) => {
+        const asParentIndex = placement.asParentIndex ?? false;
         try {
             if (processedDocuments.includes(node.id)) {
-                return;
+                return false;
             }
             if (options.documentIds && options.documentIds.length > 0 && !options.documentIds.includes(node.id)) {
-                return;
+                return false;
             }
             processedDocuments.push(node.id);
             writeProgress(`ドキュメント「${node.name}」を処理中...`);
@@ -27,11 +30,12 @@ export async function exportDocuments(deps, options) {
             const fileName = documentFileName(documentDetail.title, asParentIndex);
             const filePath = path.join(options.outputDir, currentPath, fileName);
             const action = planDocumentSave({
+                alreadyWrittenThisRun: writtenFiles.has(filePath),
                 asParentIndex,
                 body: documentDetail.plain,
+                fileExists: await fileExists(filePath),
                 lastUpdated: options.lastUpdated,
-                parentIndexAlreadyWrittenThisRun: writtenFiles.has(filePath),
-                parentIndexExists: asParentIndex && (await fileExists(filePath)),
+                missingFromTree: placement.missingFromTree ?? false,
                 updated: documentDetail.updated,
             });
             switch (action) {
@@ -42,9 +46,16 @@ export async function exportDocuments(deps, options) {
                 }
                 case 'save': {
                     const backlogDocumentUrl = documentUrl(options.domain, options.projectIdOrKey, node.id);
-                    await writeMarkdownFile(filePath, buildDocumentMarkdown(documentDetail, backlogDocumentUrl));
+                    const attachmentLinks = options.downloadAttachments
+                        ? await downloadDocumentAttachments(deps, documentDetail, currentPath, options.outputDir)
+                        : undefined;
+                    await writeMarkdownFile(filePath, buildDocumentMarkdown(documentDetail, backlogDocumentUrl, attachmentLinks));
                     writtenFiles.add(filePath);
                     await appendLog(options.outputDir, `ドキュメント「${documentDetail.title}」を更新しました: ${backlogDocumentUrl}`);
+                    return true;
+                }
+                case 'skip-fallback-collision': {
+                    logger.warn(`ツリーに現れないドキュメント「${documentDetail.title}」は、同名のファイルを既に出力しているため保存をスキップしました`);
                     break;
                 }
                 case 'skip-parent-index-collision': {
@@ -57,6 +68,7 @@ export async function exportDocuments(deps, options) {
         catch (error) {
             logger.warn(`ドキュメント ${node.name} の取得に失敗しました: ${error instanceof Error ? error.message : String(error)}`);
         }
+        return false;
     };
     /* eslint-disable no-await-in-loop */
     const processDocumentNode = async (node, currentPath) => {
@@ -67,7 +79,7 @@ export async function exportDocuments(deps, options) {
                 await processDocumentNode(child, folderRelPath);
             }
             // 親自身の本文はフォルダ内の親indexとして子の後に保存する
-            await fetchAndSaveDocument(node, folderRelPath, true);
+            await fetchAndSaveDocument(node, folderRelPath, { asParentIndex: true });
         }
         else {
             await fetchAndSaveDocument(node, currentPath);
@@ -76,7 +88,58 @@ export async function exportDocuments(deps, options) {
     for (const rootNode of documentTree.activeTree.children ?? []) {
         await processDocumentNode(rootNode, '');
     }
+    const missingFromTree = await findDocumentsOutsideTree(deps, documentTree, options, processedDocuments);
+    let savedMissingFromTree = 0;
+    for (const document of missingFromTree) {
+        const saved = await fetchAndSaveDocument({ children: [], id: document.id, name: document.title }, DOCUMENT_FALLBACK_PARENT_PATH, { missingFromTree: true });
+        if (saved) {
+            savedMissingFromTree++;
+        }
+    }
     /* eslint-enable no-await-in-loop */
+    // 検出件数ではなく実際に保存した件数を出す（未更新でスキップした分まで毎回報告しないため）
+    if (savedMissingFromTree > 0) {
+        logger.log(`ツリーに現れないドキュメント${savedMissingFromTree}件を出力ルート直下に保存しました`);
+    }
     logger.log(`\n合計 ${processedDocuments.length}件のドキュメントが処理されました。`);
     logger.log('ドキュメントのダウンロードが完了しました！');
 }
+// ツリーに現れないドキュメントを一覧API（全件が載る）との差分から求める。
+// 一覧の取得に失敗しても従来どおりツリー分のエクスポートは成立させるため、警告に留めて空を返す
+async function findDocumentsOutsideTree(deps, documentTree, options, processedDocuments) {
+    // ID指定の取得で対象がすべてツリー内に見つかっている場合は、一覧APIを呼ぶ必要がない
+    const targetedIds = options.documentIds && options.documentIds.length > 0 ? options.documentIds : undefined;
+    if (targetedIds?.every((id) => processedDocuments.includes(id))) {
+        return [];
+    }
+    try {
+        const titlesById = await deps.documentRepository.fetchAllTitles(options.projectId);
+        return findDocumentsMissingFromTree(documentTree, titlesById);
+    }
+    catch (error) {
+        deps.logger.warn(`ドキュメント一覧の取得に失敗したため、ツリーに現れないドキュメントの確認をスキップします: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+}
+// 保存できた添付のみリンク化する。個々の失敗は警告に留め、ドキュメント本体の保存は続行する
+async function downloadDocumentAttachments(deps, documentDetail, currentPath, outputDir) {
+    const links = new Map();
+    for (const attachment of documentDetail.attachments ?? []) {
+        const absolutePath = path.join(outputDir, documentAttachmentRelativePath(currentPath, documentDetail.title, attachment));
+        try {
+            // 添付IDは不変のため、サイズの一致するファイルが既にあれば再ダウンロードしない
+            // eslint-disable-next-line no-await-in-loop
+            if ((await fileSize(absolutePath)) !== attachment.size) {
+                // eslint-disable-next-line no-await-in-loop
+                const data = await deps.documentRepository.downloadAttachment(documentDetail.id, attachment.id);
+                // eslint-disable-next-line no-await-in-loop
+                await writeBinaryFile(absolutePath, data);
+            }
+            links.set(attachment.id, documentAttachmentMarkdownLink(documentDetail.title, attachment));
+        }
+        catch (error) {
+            deps.logger.warn(`ドキュメント「${documentDetail.title}」の添付ファイル「${attachment.name}」の取得に失敗しました: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return links;
+}

package/dist/modules/issue/domain/issue-markdown.d.ts

@@ -1,4 +1,5 @@
-import { CustomField, Issue, IssueComment } from './issue.js';
+import { CustomField, Issue, IssueAttachment, IssueComment } from './issue.js';
 export declare function createCustomFieldsSection(customFields?: CustomField[]): string;
-export declare function buildCommentsSection(comments: IssueComment[], backlogIssueUrl: string): string;
-export declare function buildIssueMarkdown(issue: Issue, comments: IssueComment[], backlogIssueUrl: string): string;
+export declare function buildAttachmentsSection(attachments: IssueAttachment[] | undefined, localLinks?: Map<number, string>): string;
+export declare function buildCommentsSection(comments: IssueComment[], backlogIssueUrl: string, rewriteBody?: (text: string) => string): string;
+export declare function buildIssueMarkdown(issue: Issue, comments: IssueComment[], backlogIssueUrl: string, attachmentLinks?: Map<number, string>): string;

package/dist/modules/issue/domain/issue-markdown.js

@@ -1,3 +1,4 @@
+import { escapeLinkText, rewriteInlineImages } from '../../../shared/attachment.js';
 import { wrapBody } from '../../../shared/markdown/body-marker.js';
 // Backlogの変更履歴（changeLog）のfieldを画面表示に合わせた日本語ラベルへ変換する
 const CHANGE_FIELD_LABELS = {
@@ -31,10 +32,10 @@ function formatChange(change) {
     const label = CHANGE_FIELD_LABELS[change.field] ?? change.field;
     return `- ${label}: ${formatChangeValue(change.originalValue)} → ${formatChangeValue(change.newValue)}`;
 }
-function buildCommentBody(comment) {
+function buildCommentBody(comment, rewriteBody) {
     const parts = [];
     if (comment.content) {
-        parts.push(comment.content);
+        parts.push(rewriteBody(comment.content));
     }
     if (comment.changeLog && comment.changeLog.length > 0) {
         parts.push(['**変更内容**', ...comment.changeLog.map((change) => formatChange(change))].join('\n'));
@@ -71,7 +72,19 @@ export function createCustomFieldsSection(customFields) {
     }
     return customFieldsSection;
 }
-export function buildCommentsSection(comments, backlogIssueUrl) {
+// ダウンロード済みの添付はローカルへの相対リンク付き、未ダウンロードはメタデータのみを出力する
+export function buildAttachmentsSection(attachments, localLinks) {
+    if (!attachments || attachments.length === 0) {
+        return '';
+    }
+    const lines = attachments.map((attachment) => {
+        const fileSize = `${(attachment.size / 1024).toFixed(1)} KB`;
+        const link = localLinks?.get(attachment.id);
+        return link ? `- [${escapeLinkText(attachment.name)}](${link}) (${fileSize})` : `- ${attachment.name} (${fileSize})`;
+    });
+    return `\n\n## 添付ファイル\n\n${lines.join('\n')}`;
+}
+export function buildCommentsSection(comments, backlogIssueUrl, rewriteBody = (text) => text) {
     if (comments.length === 0) {
         return '';
     }
@@ -80,15 +93,17 @@ export function buildCommentsSection(comments, backlogIssueUrl) {
     for (const comment of comments) {
         const commentDate = new Date(comment.created).toLocaleString('ja-JP');
         const backlogCommentUrl = `${backlogIssueUrl}#comment-${comment.id}`;
-        commentsSection += `\n### コメント ${commentIndex}\n- **投稿者**: ${comment.createdUser.name}\n- **日時**: ${commentDate}\n- [Backlog Comment Link](${backlogCommentUrl})\n\n${buildCommentBody(comment)}\n\n---\n`;
+        commentsSection += `\n### コメント ${commentIndex}\n- **投稿者**: ${comment.createdUser.name}\n- **日時**: ${commentDate}\n- [Backlog Comment Link](${backlogCommentUrl})\n\n${buildCommentBody(comment, rewriteBody)}\n\n---\n`;
         commentIndex++;
     }
     // 最後の区切り線を削除
     return commentsSection.slice(0, -5);
 }
-export function buildIssueMarkdown(issue, comments, backlogIssueUrl) {
-    const commentsSection = buildCommentsSection(comments, backlogIssueUrl);
+export function buildIssueMarkdown(issue, comments, backlogIssueUrl, attachmentLinks) {
+    const rewriteBody = (text) => rewriteInlineImages(text, issue.attachments, attachmentLinks);
+    const commentsSection = buildCommentsSection(comments, backlogIssueUrl, rewriteBody);
     const customFieldsSection = createCustomFieldsSection(issue.customFields);
+    const attachmentsSection = buildAttachmentsSection(issue.attachments, attachmentLinks);
     const assigneeName = issue.assignee ? issue.assignee.name : '未割り当て';
     const startDate = issue.startDate ? new Date(issue.startDate).toLocaleDateString('ja-JP') : '未設定';
     const dueDate = issue.dueDate ? new Date(issue.dueDate).toLocaleDateString('ja-JP') : '未設定';
@@ -104,9 +119,9 @@ export function buildIssueMarkdown(issue, comments, backlogIssueUrl) {
 - 期限日: ${dueDate}
 - 作成日時: ${new Date(issue.created).toLocaleString('ja-JP')}
 - 更新日時: ${new Date(issue.updated).toLocaleString('ja-JP')}
-- [Backlog Issue Link](${backlogIssueUrl})${customFieldsSection}
+- [Backlog Issue Link](${backlogIssueUrl})${customFieldsSection}${attachmentsSection}
 
 ## 詳細
 
-${wrapBody(issue.description || '詳細情報なし')}${commentsSection}`;
+${wrapBody(issue.description ? rewriteBody(issue.description) : '詳細情報なし')}${commentsSection}`;
 }

package/dist/modules/issue/domain/issue-path.d.ts

@@ -1,5 +1,5 @@
 import { ExpectedPaths } from '../../prune/domain/expected-paths.js';
-import { Issue } from './issue.js';
+import { Issue, IssueAttachment } from './issue.js';
 export declare function issueFileName(issue: {
     issueKey: string;
     summary: string;
@@ -16,6 +16,17 @@ export declare function issueRelativePath(issue: {
     issueKeyFileName?: boolean;
     issueKeyFolder?: boolean;
 }): string;
+export declare function attachmentRelativePath(issue: {
+    created: string;
+    issueKey: string;
+}, attachment: Pick<IssueAttachment, 'id' | 'name'>, options: {
+    issueKeyFolder?: boolean;
+}): string;
+export declare function attachmentMarkdownLink(issue: {
+    issueKey: string;
+}, attachment: Pick<IssueAttachment, 'id' | 'name'>, options: {
+    issueKeyFolder?: boolean;
+}): string;
 export declare function issueUrl(domain: string, issueKey: string): string;
 export declare function buildIssueExpectedPaths(issues: Issue[], options: {
     issueKeyFileName?: boolean;

package/dist/modules/issue/domain/issue-path.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { attachmentFileName, encodeLinkDestination } from '../../../shared/attachment.js';
 import { backlogOrigin } from '../../../shared/backlog-url.js';
 import { sanitizeFileName } from '../../../shared/file-name.js';
 export function issueFileName(issue, useIssueKey) {
@@ -11,6 +12,17 @@ export function issueRelativeDir(issue, useIssueKeyFolder) {
 export function issueRelativePath(issue, options) {
     return path.join(issueRelativeDir(issue, options.issueKeyFolder ?? false), issueFileName(issue, options.issueKeyFileName ?? false));
 }
+// issueKeyFolderありなら課題フォルダ直下のattachments/、なしなら年フォルダのattachments/{課題キー}/
+function attachmentDirSegments(issueKey, useIssueKeyFolder) {
+    return useIssueKeyFolder ? ['attachments'] : ['attachments', issueKey];
+}
+export function attachmentRelativePath(issue, attachment, options) {
+    return path.join(issueRelativeDir(issue, options.issueKeyFolder ?? false), ...attachmentDirSegments(issue.issueKey, options.issueKeyFolder ?? false), attachmentFileName(attachment));
+}
+export function attachmentMarkdownLink(issue, attachment, options) {
+    const segments = attachmentDirSegments(issue.issueKey, options.issueKeyFolder ?? false);
+    return encodeLinkDestination(['.', ...segments, attachmentFileName(attachment)].join('/'));
+}
 export function issueUrl(domain, issueKey) {
     return `${backlogOrigin(domain)}/view/${issueKey}`;
 }

package/dist/modules/issue/domain/issue-repository.d.ts

@@ -1,5 +1,6 @@
 import { Issue, IssueComment } from './issue.js';
 export interface IssueRepository {
+    downloadAttachment(issueIdOrKey: string, attachmentId: number): Promise<ArrayBuffer>;
     fetchAllComments(issueKey: string): Promise<IssueComment[]>;
     fetchByIdOrKey(issueIdOrKey: string): Promise<Issue>;
     fetchPage(options: {

package/dist/modules/issue/domain/issue.d.ts

@@ -3,6 +3,7 @@ export interface Issue {
         id: number;
         name: string;
     };
+    attachments?: IssueAttachment[];
     created: string;
     customFields: CustomField[];
     description: string;
@@ -25,6 +26,11 @@ export interface Issue {
     summary: string;
     updated: string;
 }
+export interface IssueAttachment {
+    id: number;
+    name: string;
+    size: number;
+}
 export interface CustomField {
     id: number;
     name: string;

package/dist/modules/issue/repository/backlog-issue-repository.js

@@ -1,5 +1,8 @@
 export function newBacklogIssueRepository(client) {
     return {
+        async downloadAttachment(issueIdOrKey, attachmentId) {
+            return client.getBinary(`/issues/${issueIdOrKey}/attachments/${attachmentId}`);
+        },
         async fetchAllComments(issueKey) {
             const allComments = [];
             let minId;

package/dist/modules/issue/use-case/export-issues.d.ts

@@ -7,6 +7,7 @@ export interface ExportIssuesDeps {
 export interface ExportIssuesOptions {
     count?: number;
     domain: string;
+    downloadAttachments?: boolean;
     issueIdOrKeys?: string[];
     issueKeyFileName?: boolean;
     issueKeyFolder?: boolean;

package/dist/modules/issue/use-case/export-issues.js

@@ -1,10 +1,10 @@
 import path from 'node:path';
 import { writeProgress } from '../../../shared/console/progress.js';
-import { writeMarkdownFile } from '../../../shared/storage/markdown-store.js';
+import { fileSize, writeBinaryFile, writeMarkdownFile } from '../../../shared/storage/markdown-store.js';
 import { appendLog } from '../../../shared/storage/update-log.js';
 import { filterIssuesUpdatedSince } from '../domain/issue-filter.js';
 import { buildIssueMarkdown } from '../domain/issue-markdown.js';
-import { issueRelativePath, issueUrl } from '../domain/issue-path.js';
+import { attachmentMarkdownLink, attachmentRelativePath, issueRelativePath, issueUrl } from '../domain/issue-path.js';
 export async function exportIssues(deps, options) {
     const { logger } = deps;
     logger.log('課題の取得を開始します...');
@@ -81,7 +81,33 @@ async function saveIssue(deps, issue, options) {
     catch (error) {
         deps.logger.warn(`課題 ${issue.issueKey} のコメント取得に失敗しました: ${error instanceof Error ? error.message : String(error)}`);
     }
+    const attachmentLinks = options.downloadAttachments
+        ? await downloadIssueAttachments(deps, issue, options)
+        : undefined;
     const filePath = path.join(options.outputDir, issueRelativePath(issue, options));
-    await writeMarkdownFile(filePath, buildIssueMarkdown(issue, comments, backlogIssueUrl));
+    await writeMarkdownFile(filePath, buildIssueMarkdown(issue, comments, backlogIssueUrl, attachmentLinks));
     await appendLog(options.outputDir, `課題「${issue.summary}」を更新しました: ${backlogIssueUrl}`);
 }
+// 保存できた添付のみリンク化する。個々の失敗は警告に留め、課題本体の保存は続行する
+async function downloadIssueAttachments(deps, issue, options) {
+    const links = new Map();
+    for (const attachment of issue.attachments ?? []) {
+        const absolutePath = path.join(options.outputDir, attachmentRelativePath(issue, attachment, options));
+        try {
+            // 添付IDは不変のため、サイズの一致するファイルが既にあれば再ダウンロードしない
+            // （サイズ不一致は過去の中断等による破損とみなして取得し直す）
+            // eslint-disable-next-line no-await-in-loop
+            if ((await fileSize(absolutePath)) !== attachment.size) {
+                // eslint-disable-next-line no-await-in-loop
+                const data = await deps.issueRepository.downloadAttachment(issue.issueKey, attachment.id);
+                // eslint-disable-next-line no-await-in-loop
+                await writeBinaryFile(absolutePath, data);
+            }
+            links.set(attachment.id, attachmentMarkdownLink(issue, attachment, options));
+        }
+        catch (error) {
+            deps.logger.warn(`課題 ${issue.issueKey} の添付ファイル「${attachment.name}」の取得に失敗しました: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return links;
+}

package/dist/modules/prune/repository/prune-walker.js

@@ -17,6 +17,11 @@ export async function pruneLocalMarkdownFiles(options) {
             const fullPath = path.join(dir, entry.name);
             const relativePath = path.relative(options.outputDir, fullPath).normalize('NFC');
             if (entry.isDirectory()) {
+                // 添付ファイルの保存先。Wiki・ドキュメントのpruneは一覧APIしか呼ばず添付の期待パスを持てないため、
+                // attachments/ 配下は走査せず丸ごと保護する（.md形式の添付の誤削除防止）
+                if (entry.name === 'attachments') {
+                    continue;
+                }
                 await pruneDirectory(fullPath);
                 const remaining = await fs.readdir(fullPath);
                 if (remaining.length === 0 && !expectedDirs.has(relativePath.toLowerCase())) {

package/dist/modules/prune/use-case/prune-directories.d.ts

@@ -12,7 +12,7 @@ export interface PruneDeps {
     createRepositories: (connection: {
         apiKey: string;
         domain: string;
-        onRateLimitWait?: () => void;
+        onRateLimitExceeded?: (waitSeconds: number) => void;
     }) => {
         documentRepository: DocumentRepository;
         issueRepository: IssueRepository;

package/dist/modules/prune/use-case/prune-directories.js

@@ -53,7 +53,7 @@ async function pruneDirectory(deps, targetDir, flags, confirmDirectory) {
     const { documentRepository, issueRepository, projectRepository, wikiRepository } = deps.createRepositories({
         apiKey,
         domain,
-        onRateLimitWait: () => logger.log('レート制限を回避するため15秒間待機します...'),
+        onRateLimitExceeded: (waitSeconds) => logger.log(`レート制限の上限に達しました。${waitSeconds}秒待機します...`),
     });
     if (target === 'wiki') {
         await pruneWikis({ logger, wikiRepository }, { outputDir: targetDir, projectIdOrKey });

package/dist/modules/prune/use-case/prune-exports.js

@@ -1,4 +1,5 @@
-import { collectDocumentTreePaths, resolveDocumentLeafPaths } from '../../document/domain/document-path.js';
+import { addFallbackDocumentPaths, collectDocumentTreePaths, resolveDocumentLeafPaths, } from '../../document/domain/document-path.js';
+import { findDocumentsMissingFromTree } from '../../document/domain/document-tree-gap.js';
 import { buildIssueExpectedPaths } from '../../issue/domain/issue-path.js';
 import { buildWikiExpectedPaths } from '../../wiki/domain/wiki-path.js';
 import { pruneLocalMarkdownFiles } from '../repository/prune-walker.js';
@@ -7,19 +8,21 @@ export async function pruneDocuments(deps, options) {
     logger.log('Backlogのドキュメントツリーを取得しています...');
     const documentTree = await documentRepository.fetchTree(options.projectId);
     const expected = collectDocumentTreePaths(documentTree.activeTree.children);
-    // 保存時のファイル名は詳細のtitle基準のため、一覧APIでタイトルを解決してから期待パスを確定する
-    let titlesById = new Map();
-    if (expected.leafNodes.length > 0) {
-        logger.log(`${expected.leafNodes.length}件のドキュメントの正規ファイル名を確認しています...`);
-        try {
-            titlesById = await documentRepository.fetchAllTitles(options.projectId);
-        }
-        catch (error) {
-            // 一覧に欠けが生じると実在ドキュメントを誤削除するため、何も削除せずに中止する
-            throw new Error(`ドキュメント一覧の取得に失敗しました。誤削除を防ぐため、何も削除せずに中止します: ${error instanceof Error ? error.message : String(error)}`);
-        }
+    // 保存時のファイル名は詳細のtitle基準のため、一覧APIでタイトルを解決してから期待パスを確定する。
+    // 一覧はツリーに現れないドキュメントを拾う台帳でもあるため、リーフの有無に関わらず取得する
+    logger.log('ドキュメント一覧でファイル名を確認しています...');
+    let titlesById;
+    try {
+        titlesById = await documentRepository.fetchAllTitles(options.projectId);
+    }
+    catch (error) {
+        // 一覧に欠けが生じると実在ドキュメントを誤削除するため、何も削除せずに中止する
+        throw new Error(`ドキュメント一覧の取得に失敗しました。誤削除を防ぐため、何も削除せずに中止します: ${error instanceof Error ? error.message : String(error)}`);
     }
     resolveDocumentLeafPaths(expected, titlesById);
+    // 取得側はツリーに現れないドキュメントを出力ルート直下に保存するため、同じ配置を期待集合に加える
+    // （加えないと、補完して取得したファイルをpruneが即座に削除してしまう）
+    addFallbackDocumentPaths(expected, findDocumentsMissingFromTree(documentTree, titlesById));
     return pruneLocalMarkdownFiles({
         expected,
         label: 'ドキュメント',

package/dist/modules/settings/domain/settings.d.ts

@@ -6,6 +6,7 @@ export declare enum FolderType {
 export interface Settings {
     apiKey?: string;
     domain?: string;
+    downloadAttachments?: boolean;
     folderType?: FolderType;
     issueKeyFileName?: boolean;
     issueKeyFolder?: boolean;

package/dist/modules/update/domain/update-plan.d.ts

@@ -4,6 +4,7 @@ export interface UpdateFlags {
     documentId?: string;
     documentsOnly?: boolean;
     domain?: string;
+    downloadAttachments?: boolean;
     force?: boolean;
     issueIdOrKey?: string;
     issueKeyFileName?: boolean;
@@ -16,6 +17,7 @@ export interface UpdateFlags {
 export interface UpdatePlan {
     documentIds?: string[];
     domain?: string;
+    downloadAttachments: boolean;
     folderType?: FolderType;
     issueIdOrKeys?: string[];
     issueKeyFileName: boolean;

package/dist/modules/update/domain/update-plan.js

@@ -56,6 +56,7 @@ export function buildUpdatePlan(settings, flags) {
         documentIds,
         // コマンドライン引数と設定ファイルを組み合わせて使用する値を決定
         domain: flags.domain || settings.domain,
+        downloadAttachments: flags.downloadAttachments ?? settings.downloadAttachments ?? false,
         folderType: settings.folderType,
         issueIdOrKeys,
         // 設定ファイルからオプションを読み込み、コマンドライン引数で上書き

package/dist/modules/update/use-case/update-exports.d.ts

@@ -9,7 +9,7 @@ export interface UpdateDeps {
     createRepositories: (connection: {
         apiKey: string;
         domain: string;
-        onRateLimitWait?: () => void;
+        onRateLimitExceeded?: (waitSeconds: number) => void;
     }) => {
         documentRepository: DocumentRepository;
         issueRepository: IssueRepository;

package/dist/modules/update/use-case/update-exports.js

@@ -48,7 +48,7 @@ async function updateDirectory(deps, targetDir, flags) {
     const { documentRepository, issueRepository, projectRepository, wikiRepository } = deps.createRepositories({
         apiKey,
         domain: plan.domain,
-        onRateLimitWait: () => logger.log('レート制限を回避するため15秒間待機します...'),
+        onRateLimitExceeded: (waitSeconds) => logger.log(`レート制限の上限に達しました。${waitSeconds}秒待機します...`),
     });
     const projectId = await projectRepository.resolveProjectId(plan.projectIdOrKey);
     logger.log(`プロジェクトID: ${projectId} を使用します`);
@@ -65,6 +65,7 @@ async function updateDirectory(deps, targetDir, flags) {
         await exportIssues({ issueRepository, logger }, {
             count: 100,
             domain: plan.domain,
+            downloadAttachments: plan.downloadAttachments,
             issueIdOrKeys: plan.issueIdOrKeys,
             issueKeyFileName: plan.issueKeyFileName,
             issueKeyFolder: plan.issueKeyFolder,
@@ -82,6 +83,7 @@ async function updateDirectory(deps, targetDir, flags) {
         logger.log('Wikiの更新を開始します...');
         await exportWikis({ logger, wikiRepository }, {
             domain: plan.domain,
+            downloadAttachments: plan.downloadAttachments,
             lastUpdated: plan.wikiIds ? undefined : plan.lastUpdated,
             outputDir: targetDir,
             projectIdOrKey: plan.projectIdOrKey,
@@ -97,6 +99,7 @@ async function updateDirectory(deps, targetDir, flags) {
         await exportDocuments({ documentRepository, logger }, {
             documentIds: plan.documentIds,
             domain: plan.domain,
+            downloadAttachments: plan.downloadAttachments,
             lastUpdated: plan.documentIds ? undefined : plan.lastUpdated,
             outputDir: targetDir,
             projectId,

package/dist/modules/wiki/domain/wiki-markdown.d.ts

@@ -1 +1,6 @@
-export declare function buildWikiMarkdown(wikiName: string, backlogWikiUrl: string, content: string): string;
+import { WikiAttachment } from './wiki.js';
+export interface WikiAttachmentsView {
+    items?: WikiAttachment[];
+    localLinks?: Map<number, string>;
+}
+export declare function buildWikiMarkdown(wikiName: string, backlogWikiUrl: string, content: string, attachments?: WikiAttachmentsView): string;

package/dist/modules/wiki/domain/wiki-markdown.js

@@ -1,4 +1,19 @@
+import { escapeLinkText } from '../../../shared/attachment.js';
 import { wrapBody } from '../../../shared/markdown/body-marker.js';
-export function buildWikiMarkdown(wikiName, backlogWikiUrl, content) {
-    return `# ${wikiName}\n\n[Backlog Wiki Link](${backlogWikiUrl})\n\n${wrapBody(content || '（内容なし）')}`;
+// ダウンロード済みの添付はローカルへの相対リンク付き、未ダウンロードはメタデータのみを出力する
+function buildAttachmentsSection(attachments) {
+    if (!attachments.items || attachments.items.length === 0) {
+        return '';
+    }
+    const lines = attachments.items.map((attachment) => {
+        const fileSize = `${(attachment.size / 1024).toFixed(1)} KB`;
+        const link = attachments.localLinks?.get(attachment.id);
+        return link ? `- [${escapeLinkText(attachment.name)}](${link}) (${fileSize})` : `- ${attachment.name} (${fileSize})`;
+    });
+    return `## 添付ファイル\n\n${lines.join('\n')}\n\n`;
+}
+// 本文はBacklogの原文を維持する（添付参照記法の書き換えは行わない）
+export function buildWikiMarkdown(wikiName, backlogWikiUrl, content, attachments = {}) {
+    const attachmentsSection = buildAttachmentsSection(attachments);
+    return `# ${wikiName}\n\n[Backlog Wiki Link](${backlogWikiUrl})\n\n${attachmentsSection}${wrapBody(content || '（内容なし）')}`;
 }

package/dist/modules/wiki/domain/wiki-path.d.ts

@@ -1,4 +1,7 @@
 import { ExpectedPaths } from '../../prune/domain/expected-paths.js';
+import { WikiAttachment } from './wiki.js';
 export declare function wikiRelativePath(wikiName: string): string;
+export declare function wikiAttachmentRelativePath(wikiName: string, attachment: Pick<WikiAttachment, 'id' | 'name'>): string;
+export declare function wikiAttachmentMarkdownLink(wikiName: string, attachment: Pick<WikiAttachment, 'id' | 'name'>): string;
 export declare function wikiUrl(domain: string, wikiId: string): string;
 export declare function buildWikiExpectedPaths(wikiNames: string[]): ExpectedPaths;

package/dist/modules/wiki/domain/wiki-path.js

@@ -1,9 +1,21 @@
 import path from 'node:path';
+import { attachmentFileName, encodeLinkDestination } from '../../../shared/attachment.js';
 import { backlogOrigin } from '../../../shared/backlog-url.js';
 import { sanitizeWikiFileName } from '../../../shared/file-name.js';
 export function wikiRelativePath(wikiName) {
     return `${sanitizeWikiFileName(wikiName)}.md`;
 }
+// 添付の保存先はMarkdownと同じディレクトリの attachments/{Wikiファイル名}/ 配下。
+// Wiki名変更時は再ダウンロードになるが、Markdown本体（{Wiki名}.md）と同じ挙動で閲覧性を優先する
+function wikiAttachmentDirName(wikiName) {
+    return path.basename(wikiRelativePath(wikiName), '.md');
+}
+export function wikiAttachmentRelativePath(wikiName, attachment) {
+    return path.join(path.dirname(wikiRelativePath(wikiName)), 'attachments', wikiAttachmentDirName(wikiName), attachmentFileName(attachment));
+}
+export function wikiAttachmentMarkdownLink(wikiName, attachment) {
+    return encodeLinkDestination(['.', 'attachments', wikiAttachmentDirName(wikiName), attachmentFileName(attachment)].join('/'));
+}
 export function wikiUrl(domain, wikiId) {
     return `${backlogOrigin(domain)}/alias/wiki/${wikiId}`;
 }

package/dist/modules/wiki/domain/wiki-repository.d.ts

@@ -1,5 +1,6 @@
 import { WikiDetail, WikiSummary } from './wiki.js';
 export interface WikiRepository {
+    downloadAttachment(wikiId: string, attachmentId: number): Promise<ArrayBuffer>;
     fetchDetail(wikiId: string, projectIdOrKey: string): Promise<WikiDetail>;
     fetchWikis(projectIdOrKey: string): Promise<WikiSummary[]>;
 }

package/dist/modules/wiki/domain/wiki.d.ts

@@ -3,7 +3,13 @@ export interface WikiSummary {
     name: string;
     updated: string;
 }
+export interface WikiAttachment {
+    id: number;
+    name: string;
+    size: number;
+}
 export interface WikiDetail {
+    attachments?: WikiAttachment[];
     content?: string;
     id: string;
     name: string;

package/dist/modules/wiki/repository/backlog-wiki-repository.js

@@ -1,5 +1,8 @@
 export function newBacklogWikiRepository(client) {
     return {
+        async downloadAttachment(wikiId, attachmentId) {
+            return client.getBinary(`/wikis/${wikiId}/attachments/${attachmentId}`);
+        },
         async fetchDetail(wikiId, projectIdOrKey) {
             return client.getJson(`/wikis/${wikiId}`, { projectIdOrKey });
         },

package/dist/modules/wiki/use-case/export-wikis.d.ts

@@ -6,6 +6,7 @@ export interface ExportWikisDeps {
 }
 export interface ExportWikisOptions {
     domain: string;
+    downloadAttachments?: boolean;
     lastUpdated?: string;
     outputDir: string;
     projectIdOrKey: string;