backlog-exporter 0.7.3 → 1.1.0

package/dist/modules/settings/repository/settings-store.d.ts

@@ -0,0 +1,6 @@
+import { Settings } from '../domain/settings.js';
+export declare function getSettingsFilePath(directory: string): string;
+export declare function loadSettings(directory: string): Promise<Settings>;
+export declare function saveSettings(directory: string, settings: Settings): Promise<void>;
+export declare function updateSettings(directory: string, newSettings: Partial<Settings>): Promise<Settings>;
+export declare function findSettingsDirectories(rootDir: string, onReadError?: (directory: string) => void): Promise<string[]>;

package/dist/modules/settings/repository/settings-store.js

@@ -0,0 +1,56 @@
+import { access, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export function getSettingsFilePath(directory) {
+    return join(directory, 'backlog-settings.json');
+}
+export async function loadSettings(directory) {
+    const settingsPath = getSettingsFilePath(directory);
+    try {
+        const data = await readFile(settingsPath, 'utf8');
+        return JSON.parse(data);
+    }
+    catch {
+        return {};
+    }
+}
+export async function saveSettings(directory, settings) {
+    const settingsPath = getSettingsFilePath(directory);
+    // ディレクトリが存在しない場合は作成
+    await mkdir(directory, { recursive: true });
+    await writeFile(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
+}
+export async function updateSettings(directory, newSettings) {
+    const currentSettings = await loadSettings(directory);
+    // 新しい設定で更新（apiKeyは除外）
+    const { apiKey, ...settingsToSave } = newSettings;
+    const updatedSettings = { ...currentSettings, ...settingsToSave };
+    await saveSettings(directory, updatedSettings);
+    return { ...updatedSettings, apiKey };
+}
+// 設定ファイルを持つディレクトリを親→子の順に列挙する（update/pruneの処理順を保つ）
+export async function findSettingsDirectories(rootDir, onReadError) {
+    const found = [];
+    const walk = async (dir) => {
+        try {
+            await access(getSettingsFilePath(dir));
+            found.push(dir);
+        }
+        catch {
+            // 設定ファイルが存在しないディレクトリはスキップ
+        }
+        try {
+            const entries = await readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    // eslint-disable-next-line no-await-in-loop
+                    await walk(join(dir, entry.name));
+                }
+            }
+        }
+        catch {
+            onReadError?.(dir);
+        }
+    };
+    await walk(rootDir);
+    return found;
+}

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

@@ -0,0 +1,38 @@
+import { FolderType, Settings } from '../../settings/domain/settings.js';
+export interface UpdateFlags {
+    apiKey?: string;
+    documentId?: string;
+    documentsOnly?: boolean;
+    domain?: string;
+    downloadAttachments?: boolean;
+    force?: boolean;
+    issueIdOrKey?: string;
+    issueKeyFileName?: boolean;
+    issueKeyFolder?: boolean;
+    issuesOnly?: boolean;
+    projectIdOrKey?: string;
+    wikiId?: string;
+    wikisOnly?: boolean;
+}
+export interface UpdatePlan {
+    documentIds?: string[];
+    domain?: string;
+    downloadAttachments: boolean;
+    folderType?: FolderType;
+    issueIdOrKeys?: string[];
+    issueKeyFileName: boolean;
+    issueKeyFolder: boolean;
+    lastUpdated?: string;
+    projectIdOrKey?: string;
+    updateDocuments: boolean;
+    updateIssues: boolean;
+    updateWikis: boolean;
+    wikiIds?: string[];
+}
+export declare function parseIds(value: string | undefined): string[] | undefined;
+export declare function determineUpdateTargets(folderType: FolderType | undefined, documentsOnly: boolean | undefined, issuesOnly: boolean | undefined, wikisOnly: boolean | undefined): {
+    updateDocuments: boolean;
+    updateIssues: boolean;
+    updateWikis: boolean;
+};
+export declare function buildUpdatePlan(settings: Settings, flags: UpdateFlags): UpdatePlan;

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

@@ -0,0 +1,70 @@
+import { FolderType } from '../../settings/domain/settings.js';
+export function parseIds(value) {
+    if (!value)
+        return undefined;
+    const ids = value
+        .split(',')
+        .map((id) => id.trim())
+        .filter(Boolean);
+    return ids.length > 0 ? ids : undefined;
+}
+export function determineUpdateTargets(folderType, documentsOnly, issuesOnly, wikisOnly) {
+    let updateIssues = !wikisOnly && !documentsOnly;
+    let updateWikis = !issuesOnly && !documentsOnly;
+    let updateDocuments = !issuesOnly && !wikisOnly;
+    // フォルダタイプに応じて更新対象を決定
+    switch (folderType) {
+        case FolderType.DOCUMENT: {
+            updateIssues = false;
+            updateWikis = false;
+            updateDocuments = true;
+            break;
+        }
+        case FolderType.ISSUE: {
+            updateIssues = true;
+            updateWikis = false;
+            updateDocuments = false;
+            break;
+        }
+        case FolderType.WIKI: {
+            updateIssues = false;
+            updateWikis = true;
+            updateDocuments = false;
+            break;
+        }
+    }
+    return { updateDocuments, updateIssues, updateWikis };
+}
+export function buildUpdatePlan(settings, flags) {
+    const issueIdOrKeys = parseIds(flags.issueIdOrKey);
+    const wikiIds = parseIds(flags.wikiId);
+    const documentIds = parseIds(flags.documentId);
+    // 更新対象の決定
+    const targets = determineUpdateTargets(settings.folderType, flags.documentsOnly, flags.issuesOnly, flags.wikisOnly);
+    // いずれかのID指定がある場合は「指定した項目のみ再取得」モードとし、
+    // ID指定のない種別は更新対象から外す（例: --wikiId のみ指定時は課題・ドキュメントを更新しない）
+    const hasTargetedFetch = Boolean(issueIdOrKeys || wikiIds || documentIds);
+    if (hasTargetedFetch) {
+        if (!issueIdOrKeys)
+            targets.updateIssues = false;
+        if (!wikiIds)
+            targets.updateWikis = false;
+        if (!documentIds)
+            targets.updateDocuments = false;
+    }
+    return {
+        documentIds,
+        // コマンドライン引数と設定ファイルを組み合わせて使用する値を決定
+        domain: flags.domain || settings.domain,
+        downloadAttachments: flags.downloadAttachments ?? settings.downloadAttachments ?? false,
+        folderType: settings.folderType,
+        issueIdOrKeys,
+        // 設定ファイルからオプションを読み込み、コマンドライン引数で上書き
+        issueKeyFileName: flags.issueKeyFileName ?? settings.issueKeyFileName ?? false,
+        issueKeyFolder: flags.issueKeyFolder ?? settings.issueKeyFolder ?? false,
+        lastUpdated: settings.lastUpdated,
+        projectIdOrKey: flags.projectIdOrKey || settings.projectIdOrKey,
+        wikiIds,
+        ...targets,
+    };
+}

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

@@ -0,0 +1,21 @@
+import { Logger } from '../../../shared/ports.js';
+import { DocumentRepository } from '../../document/domain/document-repository.js';
+import { IssueRepository } from '../../issue/domain/issue-repository.js';
+import { ProjectRepository } from '../../project/domain/project-repository.js';
+import { WikiRepository } from '../../wiki/domain/wiki-repository.js';
+import { UpdateFlags } from '../domain/update-plan.js';
+export type { UpdateFlags } from '../domain/update-plan.js';
+export interface UpdateDeps {
+    createRepositories: (connection: {
+        apiKey: string;
+        domain: string;
+        onRateLimitExceeded?: (waitSeconds: number) => void;
+    }) => {
+        documentRepository: DocumentRepository;
+        issueRepository: IssueRepository;
+        projectRepository: ProjectRepository;
+        wikiRepository: WikiRepository;
+    };
+    logger: Logger;
+}
+export declare function updateExports(deps: UpdateDeps, rootDir: string, flags: UpdateFlags): Promise<void>;

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

@@ -0,0 +1,139 @@
+import { resolveApiKey } from '../../../shared/config/env.js';
+import { readYesNo } from '../../../shared/console/prompt.js';
+import { assertDirectoryExists, ensureDirectory } from '../../../shared/storage/markdown-store.js';
+import { exportDocuments } from '../../document/use-case/export-documents.js';
+import { exportIssues } from '../../issue/use-case/export-issues.js';
+import { FolderType } from '../../settings/domain/settings.js';
+import { findSettingsDirectories, loadSettings, updateSettings } from '../../settings/repository/settings-store.js';
+import { exportWikis } from '../../wiki/use-case/export-wikis.js';
+import { buildUpdatePlan } from '../domain/update-plan.js';
+export async function updateExports(deps, rootDir, flags) {
+    const { logger } = deps;
+    await assertDirectoryExists(rootDir);
+    const directories = await findSettingsDirectories(rootDir, (dir) => {
+        logger.warn(`ディレクトリの読み取りに失敗しました: ${dir}`);
+    });
+    if (directories.length === 0) {
+        logger.warn(`設定ファイル（backlog-settings.json）が見つかりませんでした: ${rootDir}`);
+        return;
+    }
+    for (const directory of directories) {
+        // eslint-disable-next-line no-await-in-loop
+        await updateDirectory(deps, directory, flags);
+    }
+}
+async function updateDirectory(deps, targetDir, flags) {
+    const { logger } = deps;
+    const settings = await loadSettings(targetDir);
+    const plan = buildUpdatePlan(settings, flags);
+    if (!plan.domain) {
+        logger.warn(`${targetDir}: ドメインが指定されていません。スキップします。`);
+        return;
+    }
+    if (!plan.projectIdOrKey) {
+        logger.warn(`${targetDir}: プロジェクトIDまたはキーが指定されていません。スキップします。`);
+        return;
+    }
+    const apiKey = flags.apiKey ||
+        settings.apiKey ||
+        resolveApiKey(undefined, () => logger.log('環境変数 BACKLOG_API_KEY からAPIキーを使用します'));
+    if (!apiKey) {
+        logger.warn(`${targetDir}: APIキーが指定されていません。--apiKey フラグまたは BACKLOG_API_KEY 環境変数で設定してください。`);
+        return;
+    }
+    const confirmed = await confirmUpdate(logger, targetDir, plan, flags.force || false);
+    if (!confirmed)
+        return;
+    await ensureDirectory(targetDir);
+    const { documentRepository, issueRepository, projectRepository, wikiRepository } = deps.createRepositories({
+        apiKey,
+        domain: plan.domain,
+        onRateLimitExceeded: (waitSeconds) => logger.log(`レート制限の上限に達しました。${waitSeconds}秒待機します...`),
+    });
+    const projectId = await projectRepository.resolveProjectId(plan.projectIdOrKey);
+    logger.log(`プロジェクトID: ${projectId} を使用します`);
+    const saveFullUpdateResult = (folderType) => updateSettings(targetDir, {
+        apiKey,
+        domain: plan.domain,
+        folderType,
+        lastUpdated: new Date().toISOString(),
+        outputDir: targetDir,
+        projectIdOrKey: plan.projectIdOrKey,
+    });
+    if (plan.updateIssues) {
+        logger.log('課題の更新を開始します...');
+        await exportIssues({ issueRepository, logger }, {
+            count: 100,
+            domain: plan.domain,
+            downloadAttachments: plan.downloadAttachments,
+            issueIdOrKeys: plan.issueIdOrKeys,
+            issueKeyFileName: plan.issueKeyFileName,
+            issueKeyFolder: plan.issueKeyFolder,
+            // ID指定時は該当項目のみを取得するため、lastUpdatedによる絞り込みと最終更新日時の記録は行わない
+            lastUpdated: plan.issueIdOrKeys ? undefined : plan.lastUpdated,
+            outputDir: targetDir,
+            projectId,
+        });
+        if (!plan.issueIdOrKeys) {
+            await saveFullUpdateResult(FolderType.ISSUE);
+        }
+        logger.log('課題の更新が完了しました');
+    }
+    if (plan.updateWikis) {
+        logger.log('Wikiの更新を開始します...');
+        await exportWikis({ logger, wikiRepository }, {
+            domain: plan.domain,
+            downloadAttachments: plan.downloadAttachments,
+            lastUpdated: plan.wikiIds ? undefined : plan.lastUpdated,
+            outputDir: targetDir,
+            projectIdOrKey: plan.projectIdOrKey,
+            wikiIds: plan.wikiIds,
+        });
+        if (!plan.wikiIds) {
+            await saveFullUpdateResult(FolderType.WIKI);
+        }
+        logger.log('Wikiの更新が完了しました');
+    }
+    if (plan.updateDocuments) {
+        logger.log('ドキュメントの更新を開始します...');
+        await exportDocuments({ documentRepository, logger }, {
+            documentIds: plan.documentIds,
+            domain: plan.domain,
+            downloadAttachments: plan.downloadAttachments,
+            lastUpdated: plan.documentIds ? undefined : plan.lastUpdated,
+            outputDir: targetDir,
+            projectId,
+            projectIdOrKey: plan.projectIdOrKey,
+        });
+        if (!plan.documentIds) {
+            await saveFullUpdateResult(FolderType.DOCUMENT);
+        }
+        logger.log('ドキュメントの更新が完了しました');
+    }
+    logger.log(`${targetDir} の更新が完了しました！`);
+}
+async function confirmUpdate(logger, targetDir, plan, force) {
+    if (force)
+        return true;
+    logger.log(`以下の設定で更新を実行します:`);
+    logger.log(`- ディレクトリ: ${targetDir}`);
+    logger.log(`- ドメイン: ${plan.domain}`);
+    logger.log(`- プロジェクト: ${plan.projectIdOrKey}`);
+    if (plan.folderType) {
+        logger.log(`- フォルダタイプ: ${plan.folderType}`);
+    }
+    const updateTargets = [];
+    if (plan.updateIssues)
+        updateTargets.push('課題');
+    if (plan.updateWikis)
+        updateTargets.push('Wiki');
+    if (plan.updateDocuments)
+        updateTargets.push('ドキュメント');
+    logger.log(`- 更新対象: ${updateTargets.join('・')}`);
+    logger.log('更新を実行しますか？ (y/n)');
+    const response = await readYesNo();
+    if (!response) {
+        logger.log('更新をキャンセルしました');
+    }
+    return response;
+}

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

@@ -0,0 +1,9 @@
+import { WikiSummary } from './wiki.js';
+export interface WikiSelection {
+    reason: 'all' | 'ids' | 'updatedSince';
+    wikis: WikiSummary[];
+}
+export declare function selectWikisToExport(wikis: WikiSummary[], options: {
+    lastUpdated?: string;
+    wikiIds?: string[];
+}): WikiSelection;

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

@@ -0,0 +1,11 @@
+export function selectWikisToExport(wikis, options) {
+    if (options.wikiIds && options.wikiIds.length > 0) {
+        const wikiIdSet = new Set(options.wikiIds.map(String));
+        return { reason: 'ids', wikis: wikis.filter((wiki) => wikiIdSet.has(String(wiki.id))) };
+    }
+    if (options.lastUpdated) {
+        const lastUpdatedDate = new Date(options.lastUpdated);
+        return { reason: 'updatedSince', wikis: wikis.filter((wiki) => new Date(wiki.updated) > lastUpdatedDate) };
+    }
+    return { reason: 'all', wikis };
+}

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

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,19 @@
+import { escapeLinkText } from '../../../shared/attachment.js';
+import { wrapBody } from '../../../shared/markdown/body-marker.js';
+// ダウンロード済みの添付はローカルへの相対リンク付き、未ダウンロードはメタデータのみを出力する
+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

@@ -0,0 +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

@@ -0,0 +1,37 @@
+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}`;
+}
+// 比較相手のpath.relativeはOS標準の区切り文字を返すため、path.normalizeで揃える（Windows対策）
+export function buildWikiExpectedPaths(wikiNames) {
+    const expectedFiles = new Set();
+    const expectedDirs = new Set();
+    for (const name of wikiNames) {
+        const relativePath = path.normalize(wikiRelativePath(name)).normalize('NFC');
+        expectedFiles.add(relativePath);
+        // "親/子.md" のような名前では親ディレクトリも「あるべきディレクトリ」として登録する
+        let dir = path.dirname(relativePath);
+        while (dir && dir !== '.') {
+            expectedDirs.add(dir.normalize('NFC'));
+            dir = path.dirname(dir);
+        }
+    }
+    return { expectedDirs, expectedFiles };
+}

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

@@ -0,0 +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-repository.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,16 @@
+export interface WikiSummary {
+    id: string;
+    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/domain/wiki.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,3 @@
+import { BacklogHttpClient } from '../../../shared/backlog/http-client.js';
+import { WikiRepository } from '../domain/wiki-repository.js';
+export declare function newBacklogWikiRepository(client: BacklogHttpClient): WikiRepository;

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

@@ -0,0 +1,13 @@
+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 });
+        },
+        async fetchWikis(projectIdOrKey) {
+            return client.getJson('/wikis', { projectIdOrKey });
+        },
+    };
+}

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

@@ -0,0 +1,15 @@
+import { Logger } from '../../../shared/ports.js';
+import { WikiRepository } from '../domain/wiki-repository.js';
+export interface ExportWikisDeps {
+    logger: Logger;
+    wikiRepository: WikiRepository;
+}
+export interface ExportWikisOptions {
+    domain: string;
+    downloadAttachments?: boolean;
+    lastUpdated?: string;
+    outputDir: string;
+    projectIdOrKey: string;
+    wikiIds?: string[];
+}
+export declare function exportWikis(deps: ExportWikisDeps, options: ExportWikisOptions): Promise<void>;

package/dist/modules/wiki/use-case/export-wikis.js

@@ -0,0 +1,71 @@
+import path from 'node:path';
+import { writeProgress } from '../../../shared/console/progress.js';
+import { fileSize, writeBinaryFile, writeMarkdownFile } from '../../../shared/storage/markdown-store.js';
+import { appendLog } from '../../../shared/storage/update-log.js';
+import { selectWikisToExport } from '../domain/wiki-filter.js';
+import { buildWikiMarkdown } from '../domain/wiki-markdown.js';
+import { wikiAttachmentMarkdownLink, wikiAttachmentRelativePath, wikiRelativePath, wikiUrl } from '../domain/wiki-path.js';
+export async function exportWikis(deps, options) {
+    const { logger, wikiRepository } = deps;
+    logger.log('Wikiの取得を開始します...');
+    logger.log('Wiki一覧を取得しています...');
+    const allWikis = await wikiRepository.fetchWikis(options.projectIdOrKey);
+    logger.log(`${allWikis.length}件のWikiが見つかりました。`);
+    const { reason, wikis } = selectWikisToExport(allWikis, options);
+    if (reason === 'ids') {
+        logger.log(`指定された${wikis.length}件のWikiを処理します。`);
+    }
+    else if (reason === 'updatedSince') {
+        logger.log(`前回の更新日時(${options.lastUpdated})以降に更新された${wikis.length}件のWikiを処理します。`);
+    }
+    if (wikis.length === 0) {
+        logger.log('更新が必要なWikiはありません。');
+        return;
+    }
+    logger.log('Wiki詳細を取得しています...');
+    /* eslint-disable no-await-in-loop */
+    for (const [index, wiki] of wikis.entries()) {
+        try {
+            writeProgress(`Wikiを取得中... (${index + 1}/${wikis.length}件)`);
+            const wikiDetail = await wikiRepository.fetchDetail(wiki.id, options.projectIdOrKey);
+            const filePath = path.join(options.outputDir, wikiRelativePath(wiki.name));
+            const backlogWikiUrl = wikiUrl(options.domain, wiki.id);
+            const attachmentLinks = options.downloadAttachments
+                ? await downloadWikiAttachments(deps, wiki, wikiDetail.attachments ?? [], options.outputDir)
+                : undefined;
+            await writeMarkdownFile(filePath, buildWikiMarkdown(wiki.name, backlogWikiUrl, wikiDetail.content || '', {
+                items: wikiDetail.attachments,
+                localLinks: attachmentLinks,
+            }));
+            await appendLog(options.outputDir, `Wiki「${wiki.name}」を更新しました: ${backlogWikiUrl}`);
+            writeProgress(`Wikiを保存中... (${index + 1}/${wikis.length}件)`);
+        }
+        catch (error) {
+            logger.warn(`Wiki ${wiki.name} の取得に失敗しました: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /* eslint-enable no-await-in-loop */
+    logger.log('\nWikiのダウンロードが完了しました！');
+}
+// 保存できた添付のみリンク化する。個々の失敗は警告に留め、Wiki本体の保存は続行する
+async function downloadWikiAttachments(deps, wiki, attachments, outputDir) {
+    const links = new Map();
+    for (const attachment of attachments) {
+        const absolutePath = path.join(outputDir, wikiAttachmentRelativePath(wiki.name, 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.wikiRepository.downloadAttachment(wiki.id, attachment.id);
+                // eslint-disable-next-line no-await-in-loop
+                await writeBinaryFile(absolutePath, data);
+            }
+            links.set(attachment.id, wikiAttachmentMarkdownLink(wiki.name, attachment));
+        }
+        catch (error) {
+            deps.logger.warn(`Wiki「${wiki.name}」の添付ファイル「${attachment.name}」の取得に失敗しました: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return links;
+}

package/dist/shared/attachment.d.ts

@@ -0,0 +1,8 @@
+export interface AttachmentRef {
+    id: number;
+    name: string;
+}
+export declare function attachmentFileName(attachment: AttachmentRef): string;
+export declare function encodeLinkDestination(linkPath: string): string;
+export declare function escapeLinkText(name: string): string;
+export declare function rewriteInlineImages(text: string, attachments: AttachmentRef[] | undefined, localLinks?: Map<number, string>): string;

package/dist/shared/attachment.js

@@ -0,0 +1,37 @@
+import { sanitizeAttachmentFileName } from './file-name.js';
+// 添付IDを前置して同名添付の衝突を防ぎ、存在チェックだけでDL済み判定できるようにする
+export function attachmentFileName(attachment) {
+    return `${attachment.id}_${sanitizeAttachmentFileName(attachment.name)}`;
+}
+// Markdownリンク先の丸括弧はインラインリンクを壊すためエンコードする
+export function encodeLinkDestination(linkPath) {
+    return linkPath.replaceAll('(', '%28').replaceAll(')', '%29');
+}
+// ファイル名中の角括弧はリンク構文を壊すためエスケープする
+export function escapeLinkText(name) {
+    return name.replaceAll('[', String.raw `\[`).replaceAll(']', String.raw `\]`);
+}
+// Backlogの添付画像インライン記法（Markdown拡張の ![alt][ファイル名] とBacklog記法の #image(ファイル名)）を
+// ダウンロード済みファイルへのローカルリンクに変換する。未ダウンロードの参照は壊さずそのまま残す
+export function rewriteInlineImages(text, attachments, localLinks) {
+    if (!text || !attachments || attachments.length === 0 || !localLinks || localLinks.size === 0) {
+        return text;
+    }
+    // 同名添付が複数ある場合は記法から特定できないため先勝ちで解決する。
+    // 記法内のファイル名はNFD（macOSからのD&D等）で入ることがあるため、照合はNFC正規化で行う
+    const linkByName = new Map();
+    for (const attachment of attachments) {
+        const link = localLinks.get(attachment.id);
+        const name = attachment.name.normalize('NFC');
+        if (link && !linkByName.has(name)) {
+            linkByName.set(name, link);
+        }
+    }
+    const toLocalImage = (match, name) => {
+        const link = linkByName.get(name.normalize('NFC'));
+        return link ? `![${escapeLinkText(name)}](${link})` : match;
+    };
+    return text
+        .replaceAll(/!\[[^\]]*\]\[([^\]]+)\]/g, toLocalImage)
+        .replaceAll(/#image\(([^)]+)\)/g, toLocalImage);
+}

package/dist/shared/backlog/http-client.d.ts

@@ -0,0 +1,20 @@
+export declare class HttpError extends Error {
+    readonly status: number;
+    constructor(status: number, statusText: string, url: string);
+}
+export declare function rateLimitWaitMs(resetHeader: null | string, nowMs: number): number;
+export declare class BacklogHttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly onRateLimitExceeded?;
+    constructor(options: {
+        apiKey: string;
+        domain: string;
+        onRateLimitExceeded?: (waitSeconds: number) => void;
+    });
+    getBinary(pathname: string, params?: Record<string, string>): Promise<ArrayBuffer>;
+    getJson<T>(pathname: string, params?: Record<string, string>): Promise<T>;
+    private fetchWithRetry;
+    private maskApiKey;
+    private requestUrl;
+}