backlog-exporter 1.0.0 → 1.1.1

package/dist/commands/all/index.d.ts

@@ -5,6 +5,7 @@ export default class All extends Command {
     static flags: {
         apiKey: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         domain: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        downloadAttachments: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         exclude: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         issueKeyFileName: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         issueKeyFolder: import("@oclif/core/interfaces").BooleanFlag<boolean>;

package/dist/commands/all/index.js

@@ -44,6 +44,11 @@ export default class All extends Command {
             description: 'Backlog domain (e.g. example.backlog.jp)',
             required: true,
         }),
+        downloadAttachments: Flags.boolean({
+            char: 'd',
+            description: '課題の添付ファイルもダウンロードする',
+            required: false,
+        }),
         exclude: Flags.string({
             description: "Exclude the specified types, separated by commas (e.g., 'documents,wiki')",
             required: false,
@@ -79,7 +84,7 @@ export default class All extends Command {
     async run() {
         const { flags } = await this.parse(All);
         try {
-            const { domain, exclude, issueKeyFileName, issueKeyFolder, maxCount, only, projectIdOrKey } = flags;
+            const { domain, downloadAttachments, exclude, issueKeyFileName, issueKeyFolder, maxCount, only, projectIdOrKey } = flags;
             const apiKey = resolveApiKey(flags.apiKey, () => this.log('環境変数 BACKLOG_API_KEY からAPIキーを使用します')) ??
                 this.error(API_KEY_NOT_FOUND_MESSAGE);
             const outputRoot = flags.output || './backlog-data';
@@ -93,11 +98,12 @@ export default class All extends Command {
             const repositories = createBacklogRepositories({
                 apiKey,
                 domain,
-                onRateLimitWait: () => this.log('レート制限を回避するため15秒間待機します...'),
+                onRateLimitExceeded: (waitSeconds) => this.log(`レート制限の上限に達しました。${waitSeconds}秒待機します...`),
             });
             await exportAll({ ...repositories, logger }, {
                 apiKey,
                 domain,
+                downloadAttachments,
                 issueKeyFileName,
                 issueKeyFolder,
                 maxCount,

package/dist/commands/document/index.d.ts

@@ -5,6 +5,7 @@ export default class Document extends Command {
     static flags: {
         apiKey: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         domain: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        downloadAttachments: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         keyword: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         output: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         projectIdOrKey: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/document/index.js

@@ -29,6 +29,11 @@ export default class Document extends Command {
             description: 'Backlog domain (e.g. example.backlog.jp)',
             required: true,
         }),
+        downloadAttachments: Flags.boolean({
+            char: 'd',
+            description: '添付ファイルもダウンロードする',
+            required: false,
+        }),
         keyword: Flags.string({
             description: '検索キーワード',
             required: false,
@@ -46,7 +51,7 @@ export default class Document extends Command {
     async run() {
         const { flags } = await this.parse(Document);
         try {
-            const { domain, keyword, projectIdOrKey } = flags;
+            const { domain, downloadAttachments, keyword, projectIdOrKey } = flags;
             const apiKey = resolveApiKey(flags.apiKey, () => this.log('環境変数 BACKLOG_API_KEY からAPIキーを使用します')) ??
                 this.error(API_KEY_NOT_FOUND_MESSAGE);
             const outputDir = flags.output || './backlog-documents';
@@ -54,7 +59,7 @@ export default class Document extends Command {
             const { documentRepository, projectRepository } = createBacklogRepositories({
                 apiKey,
                 domain,
-                onRateLimitWait: () => this.log('レート制限を回避するため15秒間待機します...'),
+                onRateLimitExceeded: (waitSeconds) => this.log(`レート制限の上限に達しました。${waitSeconds}秒待機します...`),
             });
             // 出力ディレクトリの作成
             await ensureDirectory(outputDir);
@@ -65,6 +70,7 @@ export default class Document extends Command {
             await updateSettings(outputDir, {
                 apiKey,
                 domain,
+                downloadAttachments,
                 folderType: FolderType.DOCUMENT,
                 outputDir,
                 projectIdOrKey,
@@ -72,6 +78,7 @@ export default class Document extends Command {
             // ドキュメントの取得と保存
             await exportDocuments({ documentRepository, logger }, {
                 domain,
+                downloadAttachments,
                 keyword,
                 outputDir,
                 projectId,

package/dist/commands/issue/index.d.ts

@@ -5,6 +5,7 @@ export default class Issue extends Command {
     static flags: {
         apiKey: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         domain: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        downloadAttachments: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         issueKeyFileName: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         issueKeyFolder: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         maxCount: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/issue/index.js

@@ -30,6 +30,9 @@ export default class Issue extends Command {
 `,
         `<%= config.bin %> <%= command.id %> --domain example.backlog.jp --projectIdOrKey PROJECT_KEY --apiKey YOUR_API_KEY --issueKeyFileName --issueKeyFolder
 課題キーでフォルダを作成し、ファイル名も課題キーにする
+`,
+        `<%= config.bin %> <%= command.id %> --domain example.backlog.jp --projectIdOrKey PROJECT_KEY --apiKey YOUR_API_KEY --downloadAttachments
+課題の添付ファイルもダウンロードする
 `,
     ];
     static flags = {
@@ -41,6 +44,11 @@ export default class Issue extends Command {
             description: 'Backlog domain (e.g. example.backlog.jp)',
             required: true,
         }),
+        downloadAttachments: Flags.boolean({
+            char: 'd',
+            description: '課題の添付ファイルもダウンロードする',
+            required: false,
+        }),
         issueKeyFileName: Flags.boolean({
             description: 'ファイル名を課題キーにする',
             required: false,
@@ -72,7 +80,7 @@ export default class Issue extends Command {
     async run() {
         const { flags } = await this.parse(Issue);
         try {
-            const { domain, issueKeyFileName, issueKeyFolder, maxCount, projectIdOrKey, statusId } = flags;
+            const { domain, downloadAttachments, issueKeyFileName, issueKeyFolder, maxCount, projectIdOrKey, statusId } = flags;
             const apiKey = resolveApiKey(flags.apiKey, () => this.log('環境変数 BACKLOG_API_KEY からAPIキーを使用します')) ??
                 this.error(API_KEY_NOT_FOUND_MESSAGE);
             const outputDir = flags.output || './backlog-issues';
@@ -80,7 +88,7 @@ export default class Issue extends Command {
             const { issueRepository, projectRepository } = createBacklogRepositories({
                 apiKey,
                 domain,
-                onRateLimitWait: () => this.log('レート制限を回避するため15秒間待機します...'),
+                onRateLimitExceeded: (waitSeconds) => this.log(`レート制限の上限に達しました。${waitSeconds}秒待機します...`),
             });
             // 出力ディレクトリの作成
             await ensureDirectory(outputDir);
@@ -91,6 +99,7 @@ export default class Issue extends Command {
             await updateSettings(outputDir, {
                 apiKey,
                 domain,
+                downloadAttachments,
                 folderType: FolderType.ISSUE,
                 issueKeyFileName,
                 issueKeyFolder,
@@ -101,6 +110,7 @@ export default class Issue extends Command {
             await exportIssues({ issueRepository, logger }, {
                 count: maxCount,
                 domain,
+                downloadAttachments,
                 issueKeyFileName,
                 issueKeyFolder,
                 outputDir,

package/dist/commands/update/index.d.ts

@@ -10,6 +10,7 @@ export default class Update extends Command {
         documentId: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         documentsOnly: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         domain: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        downloadAttachments: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         issueIdOrKey: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         issueKeyFileName: import("@oclif/core/interfaces").BooleanFlag<boolean>;

package/dist/commands/update/index.js

@@ -62,6 +62,11 @@ export default class Update extends Command {
             description: 'Backlog domain (e.g. example.backlog.jp)',
             required: false,
         }),
+        downloadAttachments: Flags.boolean({
+            char: 'd',
+            description: '課題の添付ファイルもダウンロードする（未指定時は設定ファイルの値を使用）',
+            required: false,
+        }),
         force: Flags.boolean({
             char: 'f',
             description: '確認プロンプトをスキップする',

package/dist/commands/wiki/index.d.ts

@@ -5,6 +5,7 @@ export default class Wiki extends Command {
     static flags: {
         apiKey: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         domain: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        downloadAttachments: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         output: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         projectIdOrKey: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     };

package/dist/commands/wiki/index.js

@@ -26,6 +26,11 @@ Wikiをダウンロードする
             description: 'Backlog domain (e.g. example.backlog.jp)',
             required: true,
         }),
+        downloadAttachments: Flags.boolean({
+            char: 'd',
+            description: '添付ファイルもダウンロードする',
+            required: false,
+        }),
         output: Flags.string({
             char: 'o',
             description: '出力ディレクトリパス',
@@ -39,7 +44,7 @@ Wikiをダウンロードする
     async run() {
         const { flags } = await this.parse(Wiki);
         try {
-            const { domain, projectIdOrKey } = flags;
+            const { domain, downloadAttachments, projectIdOrKey } = flags;
             const apiKey = resolveApiKey(flags.apiKey, () => this.log('環境変数 BACKLOG_API_KEY からAPIキーを使用します')) ??
                 this.error(API_KEY_NOT_FOUND_MESSAGE);
             const outputDir = flags.output || './wiki';
@@ -47,7 +52,7 @@ Wikiをダウンロードする
             const { wikiRepository } = createBacklogRepositories({
                 apiKey,
                 domain,
-                onRateLimitWait: () => this.log('レート制限を回避するため15秒間待機します...'),
+                onRateLimitExceeded: (waitSeconds) => this.log(`レート制限の上限に達しました。${waitSeconds}秒待機します...`),
             });
             // 出力ディレクトリの作成
             await ensureDirectory(outputDir);
@@ -55,6 +60,7 @@ Wikiをダウンロードする
             await updateSettings(outputDir, {
                 apiKey,
                 domain,
+                downloadAttachments,
                 folderType: FolderType.WIKI,
                 outputDir,
                 projectIdOrKey,
@@ -62,6 +68,7 @@ Wikiをダウンロードする
             // Wikiの取得と保存
             await exportWikis({ logger, wikiRepository }, {
                 domain,
+                downloadAttachments,
                 outputDir,
                 projectIdOrKey,
             });

package/dist/composition/backlog-repositories.d.ts

@@ -5,7 +5,7 @@ import { WikiRepository } from '../modules/wiki/domain/wiki-repository.js';
 export interface BacklogConnection {
     apiKey: string;
     domain: string;
-    onRateLimitWait?: () => void;
+    onRateLimitExceeded?: (waitSeconds: number) => void;
 }
 export interface BacklogRepositories {
     documentRepository: DocumentRepository;

package/dist/composition/backlog-repositories.js

@@ -3,7 +3,7 @@ import { newBacklogIssueRepository } from '../modules/issue/repository/backlog-i
 import { newBacklogProjectRepository } from '../modules/project/repository/backlog-project-repository.js';
 import { newBacklogWikiRepository } from '../modules/wiki/repository/backlog-wiki-repository.js';
 import { BacklogHttpClient } from '../shared/backlog/http-client.js';
-// 1つのHTTPクライアント（＝レート制限カウンタ）を全repositoryで共有する
+// 1つのHTTPクライアントを全repositoryで共有する
 export function createBacklogRepositories(connection) {
     const client = new BacklogHttpClient(connection);
     return {

package/dist/modules/all/use-case/export-all.d.ts

@@ -14,6 +14,7 @@ export type ExportTarget = 'documents' | 'issues' | 'wiki';
 export interface ExportAllOptions {
     apiKey: string;
     domain: string;
+    downloadAttachments?: boolean;
     issueKeyFileName?: boolean;
     issueKeyFolder?: boolean;
     maxCount: number;

package/dist/modules/all/use-case/export-all.js

@@ -7,7 +7,7 @@ import { updateSettings } from '../../settings/repository/settings-store.js';
 import { exportWikis } from '../../wiki/use-case/export-wikis.js';
 export async function exportAll(deps, options) {
     const { documentRepository, issueRepository, logger, projectRepository, wikiRepository } = deps;
-    const { apiKey, domain, issueKeyFileName, issueKeyFolder, maxCount, outputRoot, projectIdOrKey, targets } = options;
+    const { apiKey, domain, downloadAttachments, issueKeyFileName, issueKeyFolder, maxCount, outputRoot, projectIdOrKey, targets } = options;
     await ensureDirectory(outputRoot);
     const projectId = await projectRepository.resolveProjectId(projectIdOrKey);
     logger.log(`プロジェクトID: ${projectId} を使用します`);
@@ -17,6 +17,7 @@ export async function exportAll(deps, options) {
         await updateSettings(issueOutput, {
             apiKey,
             domain,
+            downloadAttachments,
             folderType: FolderType.ISSUE,
             issueKeyFileName,
             issueKeyFolder,
@@ -27,6 +28,7 @@ export async function exportAll(deps, options) {
         await exportIssues({ issueRepository, logger }, {
             count: maxCount,
             domain,
+            downloadAttachments,
             issueKeyFileName,
             issueKeyFolder,
             outputDir: issueOutput,
@@ -41,6 +43,7 @@ export async function exportAll(deps, options) {
         await updateSettings(wikiOutput, {
             apiKey,
             domain,
+            downloadAttachments,
             folderType: FolderType.WIKI,
             outputDir: wikiOutput,
             projectIdOrKey,
@@ -48,6 +51,7 @@ export async function exportAll(deps, options) {
         logger.log('Wikiの取得を開始します...');
         await exportWikis({ logger, wikiRepository }, {
             domain,
+            downloadAttachments,
             outputDir: wikiOutput,
             projectIdOrKey,
         });
@@ -60,6 +64,7 @@ export async function exportAll(deps, options) {
         await updateSettings(documentOutput, {
             apiKey,
             domain,
+            downloadAttachments,
             folderType: FolderType.DOCUMENT,
             outputDir: documentOutput,
             projectIdOrKey,
@@ -67,6 +72,7 @@ export async function exportAll(deps, options) {
         logger.log('ドキュメントの取得を開始します...');
         await exportDocuments({ documentRepository, logger }, {
             domain,
+            downloadAttachments,
             outputDir: documentOutput,
             projectId,
             projectIdOrKey,

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

@@ -1,2 +1,2 @@
 import { DocumentDetail } from './document.js';
-export declare function buildDocumentMarkdown(documentDetail: DocumentDetail, backlogDocumentUrl: string): string;
+export declare function buildDocumentMarkdown(documentDetail: DocumentDetail, backlogDocumentUrl: string, attachmentLinks?: Map<number, string>): string;

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

@@ -1,13 +1,16 @@
+import { escapeLinkText } from '../../../shared/attachment.js';
 import { wrapBody } from '../../../shared/markdown/body-marker.js';
-export function buildDocumentMarkdown(documentDetail, backlogDocumentUrl) {
-    // 添付ファイルリストの作成
+export function buildDocumentMarkdown(documentDetail, backlogDocumentUrl, attachmentLinks) {
+    // 添付ファイルリストの作成（ダウンロード済みはローカルへの相対リンク付き）
     let attachmentsSection = '';
     if (documentDetail.attachments && documentDetail.attachments.length > 0) {
         attachmentsSection = '\n\n## 添付ファイル\n';
         for (const attachment of documentDetail.attachments) {
             const attachmentDate = new Date(attachment.created).toLocaleString('ja-JP');
             const fileSize = (attachment.size / 1024).toFixed(1);
-            attachmentsSection += `- **${attachment.name}** (${fileSize} KB) - 作成者: ${attachment.createdUser.name}, 作成日時: ${attachmentDate}\n`;
+            const link = attachmentLinks?.get(attachment.id);
+            const label = link ? `[${escapeLinkText(attachment.name)}](${link})` : `**${attachment.name}**`;
+            attachmentsSection += `- ${label} (${fileSize} KB) - 作成者: ${attachment.createdUser.name}, 作成日時: ${attachmentDate}\n`;
         }
     }
     // タグリストの作成

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

@@ -1,9 +1,18 @@
 import { ExpectedPaths } from '../../prune/domain/expected-paths.js';
-import { DocumentNode } from './document.js';
+import { DocumentNode, DocumentSummary } from './document.js';
 export declare const PARENT_DOCUMENT_INDEX_FILENAME = "00_index.md";
+export declare const DOCUMENT_FALLBACK_PARENT_PATH = "";
 export declare function documentFolderPath(currentPath: string, folderName: string): string;
 export declare function documentFileName(title: string, asParentIndex: boolean): string;
 export declare function documentUrl(domain: string, projectIdOrKey: string, documentId: string): string;
+export declare function documentAttachmentRelativePath(currentPath: string, documentTitle: string, attachment: {
+    id: number;
+    name: string;
+}): string;
+export declare function documentAttachmentMarkdownLink(documentTitle: string, attachment: {
+    id: number;
+    name: string;
+}): string;
 export interface DocumentTreePaths extends ExpectedPaths {
     leafNodes: Array<{
         currentPath: string;
@@ -13,3 +22,4 @@ export interface DocumentTreePaths extends ExpectedPaths {
 }
 export declare function collectDocumentTreePaths(rootNodes: DocumentNode[]): DocumentTreePaths;
 export declare function resolveDocumentLeafPaths(paths: DocumentTreePaths, titlesById: Map<string, string>): void;
+export declare function addFallbackDocumentPaths(paths: ExpectedPaths, documents: DocumentSummary[]): void;

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

@@ -1,8 +1,11 @@
 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';
 // 子を持つ親ドキュメント自身の本文の保存先。ダウンロード側とprune側でレイアウト定義を共有する
 export const PARENT_DOCUMENT_INDEX_FILENAME = '00_index.md';
+// ツリーに現れないドキュメントの保存先。ツリー上の位置が分からないため出力ルート直下に置く
+export const DOCUMENT_FALLBACK_PARENT_PATH = '';
 export function documentFolderPath(currentPath, folderName) {
     return path.join(currentPath, sanitizeFileName(folderName));
 }
@@ -12,6 +15,14 @@ export function documentFileName(title, asParentIndex) {
 export function documentUrl(domain, projectIdOrKey, documentId) {
     return `${backlogOrigin(domain)}/document/${projectIdOrKey}/${documentId}`;
 }
+// 添付の保存先はMarkdownと同じディレクトリの attachments/{ドキュメント名}/ 配下。
+// タイトル改名時は再ダウンロードになるが、Markdown本体（{タイトル}.md）と同じ挙動で閲覧性を優先する
+export function documentAttachmentRelativePath(currentPath, documentTitle, attachment) {
+    return path.join(currentPath, 'attachments', sanitizeFileName(documentTitle), attachmentFileName(attachment));
+}
+export function documentAttachmentMarkdownLink(documentTitle, attachment) {
+    return encodeLinkDestination(['.', 'attachments', sanitizeFileName(documentTitle), attachmentFileName(attachment)].join('/'));
+}
 export function collectDocumentTreePaths(rootNodes) {
     const expectedFiles = new Set();
     const expectedDirs = new Set();
@@ -46,3 +57,9 @@ export function resolveDocumentLeafPaths(paths, titlesById) {
         paths.expectedFiles.add(path.join(leaf.currentPath, `${sanitizeFileName(title)}.md`).normalize('NFC'));
     }
 }
+// ツリーに現れないドキュメントは出力ルート直下に保存されるため、同じ配置で期待パスに加える
+export function addFallbackDocumentPaths(paths, documents) {
+    for (const document of documents) {
+        paths.expectedFiles.add(path.join(DOCUMENT_FALLBACK_PARENT_PATH, documentFileName(document.title, false)).normalize('NFC'));
+    }
+}

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

@@ -1,5 +1,6 @@
 import { DocumentDetail, DocumentTree } from './document.js';
 export interface DocumentRepository {
+    downloadAttachment(documentId: string, attachmentId: number): Promise<ArrayBuffer>;
     fetchAllTitles(projectId: number): Promise<Map<string, string>>;
     fetchDetail(documentId: string): Promise<DocumentDetail>;
     fetchTree(projectId: number): Promise<DocumentTree>;

package/dist/modules/document/domain/document-save-plan.d.ts

@@ -1,9 +1,10 @@
-export type DocumentSaveAction = 'delete-stale-parent-index' | 'save' | 'skip-empty-parent' | 'skip-parent-index-collision' | 'skip-unchanged';
+export type DocumentSaveAction = 'delete-stale-parent-index' | 'save' | 'skip-empty-parent' | 'skip-fallback-collision' | 'skip-parent-index-collision' | 'skip-unchanged';
 export declare function planDocumentSave(input: {
+    alreadyWrittenThisRun: boolean;
     asParentIndex: boolean;
     body: null | string | undefined;
+    fileExists: boolean;
     lastUpdated?: string;
-    parentIndexAlreadyWrittenThisRun: boolean;
-    parentIndexExists: boolean;
+    missingFromTree: boolean;
     updated: string;
 }): DocumentSaveAction;

package/dist/modules/document/domain/document-save-plan.js

@@ -1,15 +1,21 @@
 // 保存/スキップ/親index削除の判断。本文が空の親はファイルを作らず、空に変更された場合は古い親indexを削除する
 export function planDocumentSave(input) {
-    if (input.asParentIndex && input.parentIndexAlreadyWrittenThisRun) {
+    if (input.asParentIndex && input.alreadyWrittenThisRun) {
         return 'skip-parent-index-collision';
     }
-    // 前回の更新日時チェック（親indexがまだ存在しない場合はバックフィルのため未更新でも保存する）
-    const backfillParentIndex = input.asParentIndex && !input.parentIndexExists;
-    if (input.lastUpdated && !backfillParentIndex && new Date(input.updated) <= new Date(input.lastUpdated)) {
+    // ツリーに現れないドキュメントは出力ルート直下に固定で置かれるため、同名の保存先が既に使われていたら譲る。
+    // ツリー上の位置が確かなドキュメントを、位置の分からないドキュメントで黙って上書きしないための保険
+    if (input.missingFromTree && input.alreadyWrittenThisRun) {
+        return 'skip-fallback-collision';
+    }
+    // 前回の更新日時チェック。親index・ツリーに現れないドキュメントは、そもそも過去のエクスポートで
+    // 取得できていない可能性があるため、ファイルが無い場合は未更新でもバックフィルとして保存する
+    const backfill = (input.asParentIndex || input.missingFromTree) && !input.fileExists;
+    if (input.lastUpdated && !backfill && new Date(input.updated) <= new Date(input.lastUpdated)) {
         return 'skip-unchanged';
     }
     if (input.asParentIndex && !input.body?.trim()) {
-        return input.parentIndexExists ? 'delete-stale-parent-index' : 'skip-empty-parent';
+        return input.fileExists ? 'delete-stale-parent-index' : 'skip-empty-parent';
     }
     return 'save';
 }

package/dist/modules/document/domain/document-tree-gap.d.ts

@@ -0,0 +1,2 @@
+import { DocumentSummary, DocumentTree } from './document.js';
+export declare function findDocumentsMissingFromTree(tree: DocumentTree, titlesById: Map<string, string>): DocumentSummary[];

package/dist/modules/document/domain/document-tree-gap.js

@@ -0,0 +1,21 @@
+// Backlogのドキュメントツリーは、作成後に一度も再保存されていないドキュメントを返さないことがある。
+// ツリーだけを辿るとそれらが構造的に取得できないため、全件が載る一覧APIとの差分で拾う。
+// ゴミ箱のドキュメントを復活させないよう、trashTreeに載っているものは差分から除く。
+export function findDocumentsMissingFromTree(tree, titlesById) {
+    const knownIds = new Set();
+    const collect = (nodes) => {
+        for (const node of nodes ?? []) {
+            knownIds.add(node.id);
+            collect(node.children);
+        }
+    };
+    collect(tree.activeTree.children);
+    collect(tree.trashTree?.children);
+    const missing = [];
+    for (const [id, title] of titlesById) {
+        if (!knownIds.has(id)) {
+            missing.push({ id, title });
+        }
+    }
+    return missing;
+}

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

@@ -11,6 +11,10 @@ export interface DocumentTree {
         children: DocumentNode[];
         id: string;
     };
+    trashTree?: {
+        children: DocumentNode[];
+        id: string;
+    };
 }
 export interface DocumentSummary {
     id: string;

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

@@ -1,5 +1,9 @@
 export function newBacklogDocumentRepository(client) {
     return {
+        // 公式ドキュメント未記載だが公式SDK(nulab/backlog-js)に存在するエンドポイント
+        async downloadAttachment(documentId, attachmentId) {
+            return client.getBinary(`/documents/${documentId}/attachments/${attachmentId}`);
+        },
         async fetchAllTitles(projectId) {
             const titlesById = new Map();
             const pageSize = 100;

package/dist/modules/document/use-case/export-documents.d.ts

@@ -7,6 +7,7 @@ export interface ExportDocumentsDeps {
 export interface ExportDocumentsOptions {
     documentIds?: string[];
     domain: string;
+    downloadAttachments?: boolean;
     keyword?: string;
     lastUpdated?: string;
     outputDir: string;