backlog-exporter 1.0.0 → 1.1.0

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/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;

package/dist/modules/wiki/use-case/export-wikis.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 { selectWikisToExport } from '../domain/wiki-filter.js';
 import { buildWikiMarkdown } from '../domain/wiki-markdown.js';
-import { wikiRelativePath, wikiUrl } from '../domain/wiki-path.js';
+import { wikiAttachmentMarkdownLink, wikiAttachmentRelativePath, wikiRelativePath, wikiUrl } from '../domain/wiki-path.js';
 export async function exportWikis(deps, options) {
     const { logger, wikiRepository } = deps;
     logger.log('Wikiの取得を開始します...');
@@ -30,7 +30,13 @@ export async function exportWikis(deps, options) {
             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);
-            await writeMarkdownFile(filePath, buildWikiMarkdown(wiki.name, backlogWikiUrl, wikiDetail.content || ''));
+            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}件)`);
         }
@@ -41,3 +47,25 @@ export async function exportWikis(deps, options) {
     /* 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

@@ -2,16 +2,19 @@ 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 rateLimiter;
+    private readonly onRateLimitExceeded?;
     constructor(options: {
         apiKey: string;
         domain: string;
-        onRateLimitWait?: () => void;
+        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;
 }

package/dist/shared/backlog/http-client.js

@@ -1,5 +1,5 @@
 import { backlogOrigin } from '../backlog-url.js';
-import { RateLimiter, sleep } from './rate-limiter.js';
+import { sleep } from './sleep.js';
 // fetchは4xx/5xxでthrowしないため、response.okでない場合にこれを投げる
 export class HttpError extends Error {
     status;
@@ -9,30 +9,47 @@ export class HttpError extends Error {
         this.name = 'HttpError';
     }
 }
-const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+const RETRYABLE_STATUSES = new Set([408, 500, 502, 503, 504]);
 const MAX_RETRIES = 2;
+// 429待機は1回ごとにレート制限ウィンドウ(1分)が更新されるため、通常リトライとは別枠で上限を設ける
+const MAX_RATE_LIMIT_WAITS = 5;
 const RETRY_BASE_DELAY_MS = 300;
-// apiKey付与・レート制限(100req/15s)・一時エラーのリトライを担うBacklog APIクライアント
+const RATE_LIMIT_MIN_WAIT_MS = 1000;
+const RATE_LIMIT_FALLBACK_WAIT_MS = 60_000;
+const RATE_LIMIT_MAX_WAIT_MS = 120_000;
+// レート制限(429)はウィンドウが1分単位のため、短いbackoffではなく
+// X-RateLimit-Reset(UNIX秒)まで待つ。ヘッダーが無い/不正な場合は1分待つ
+export function rateLimitWaitMs(resetHeader, nowMs) {
+    const resetSeconds = Number(resetHeader);
+    if (!resetHeader || !Number.isFinite(resetSeconds))
+        return RATE_LIMIT_FALLBACK_WAIT_MS;
+    // リセット直後の境界ずれで再度429にならないよう1秒の余裕を持たせる
+    const waitMs = resetSeconds * 1000 - nowMs + 1000;
+    return Math.min(Math.max(waitMs, RATE_LIMIT_MIN_WAIT_MS), RATE_LIMIT_MAX_WAIT_MS);
+}
+// apiKey付与・429時のX-RateLimit-Resetまでの待機・一時エラーのリトライを担うBacklog APIクライアント
 export class BacklogHttpClient {
     apiKey;
     baseUrl;
-    rateLimiter;
+    onRateLimitExceeded;
     constructor(options) {
         this.apiKey = options.apiKey;
         this.baseUrl = `${backlogOrigin(options.domain)}/api/v2`;
-        this.rateLimiter = new RateLimiter(options.onRateLimitWait);
+        this.onRateLimitExceeded = options.onRateLimitExceeded;
+    }
+    async getBinary(pathname, params = {}) {
+        const response = await this.fetchWithRetry(this.requestUrl(pathname, params));
+        return response.arrayBuffer();
     }
     async getJson(pathname, params = {}) {
-        await this.rateLimiter.increment();
-        const searchParams = new URLSearchParams({ apiKey: this.apiKey, ...params });
-        const url = `${this.baseUrl}${pathname}?${searchParams.toString()}`;
-        const response = await this.fetchWithRetry(url);
+        const response = await this.fetchWithRetry(this.requestUrl(pathname, params));
         return (await response.json());
     }
     // リトライのため、ループ内のawaitは意図したもの
     /* eslint-disable no-await-in-loop */
     async fetchWithRetry(url) {
-        for (let attempt = 0;; attempt++) {
+        let rateLimitWaits = 0;
+        for (let attempt = 0;;) {
             let response;
             try {
                 response = await fetch(url);
@@ -41,6 +58,7 @@ export class BacklogHttpClient {
                 // ネットワークエラー
                 if (attempt < MAX_RETRIES) {
                     await sleep(RETRY_BASE_DELAY_MS * 2 ** attempt);
+                    attempt++;
                     continue;
                 }
                 throw error;
@@ -48,8 +66,17 @@ export class BacklogHttpClient {
             if (response.ok) {
                 return response;
             }
+            // 429は待機すれば解消する見込みが高いため、通常のリトライ回数を消費しない
+            if (response.status === 429 && rateLimitWaits < MAX_RATE_LIMIT_WAITS) {
+                const waitMs = rateLimitWaitMs(response.headers.get('x-ratelimit-reset'), Date.now());
+                this.onRateLimitExceeded?.(Math.ceil(waitMs / 1000));
+                await sleep(waitMs);
+                rateLimitWaits++;
+                continue;
+            }
             if (attempt < MAX_RETRIES && RETRYABLE_STATUSES.has(response.status)) {
                 await sleep(RETRY_BASE_DELAY_MS * 2 ** attempt);
+                attempt++;
                 continue;
             }
             throw new HttpError(response.status, response.statusText, this.maskApiKey(url));
@@ -59,4 +86,8 @@ export class BacklogHttpClient {
     maskApiKey(url) {
         return url.replace(/apiKey=[^&]*/, 'apiKey=***');
     }
+    requestUrl(pathname, params) {
+        const searchParams = new URLSearchParams({ apiKey: this.apiKey, ...params });
+        return `${this.baseUrl}${pathname}?${searchParams.toString()}`;
+    }
 }

package/dist/shared/backlog/sleep.d.ts

@@ -0,0 +1 @@
+export declare const sleep: (ms: number) => Promise<void>;

package/dist/shared/backlog/sleep.js

@@ -0,0 +1,3 @@
+export const sleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});

package/dist/shared/console/progress.js

@@ -1,4 +1,11 @@
 import process from 'node:process';
 export function writeProgress(message) {
-    process.stdout.write(`\r${message}`);
+    if (process.stdout.isTTY) {
+        // ESC[K でカーソル位置から行末まで消去し、前の長いメッセージの残骸を防ぐ
+        process.stdout.write(`\r\u001B[K${message}`);
+    }
+    else {
+        // 非TTY（CIログ・パイプ）では \r が効かず1行に連結されるため改行して出力する
+        process.stdout.write(`${message}\n`);
+    }
 }

package/dist/shared/file-name.d.ts

@@ -1,2 +1,3 @@
 export declare function sanitizeFileName(name: string): string;
+export declare function sanitizeAttachmentFileName(name: string): string;
 export declare function sanitizeWikiFileName(name: string): string;

package/dist/shared/file-name.js

@@ -5,6 +5,17 @@ export function sanitizeFileName(name) {
         .replaceAll('.', '_') // ドットを置換
         .slice(0, 200); // 長すぎるファイル名を防ぐために200文字に制限
 }
+// 添付ファイル用: sanitizeFileNameと異なり、拡張子が消えないようドットを保持する
+export function sanitizeAttachmentFileName(name) {
+    const sanitized = name.replaceAll(/[\\/:*?"<>|]/g, '_').replaceAll(/\s+/g, '_');
+    if (sanitized.length <= 200)
+        return sanitized;
+    const dotIndex = sanitized.lastIndexOf('.');
+    const extension = dotIndex > 0 ? sanitized.slice(dotIndex) : '';
+    if (extension.length === 0 || extension.length >= 200)
+        return sanitized.slice(0, 200);
+    return sanitized.slice(0, 200 - extension.length) + extension;
+}
 export function sanitizeWikiFileName(name) {
     const invalidChars = ['\\', ':', '*', '?', '"', '<', '>', '|'];
     let sanitizedName = name;

package/dist/shared/storage/markdown-store.d.ts

@@ -1,5 +1,7 @@
 export declare function ensureDirectory(directory: string): Promise<void>;
 export declare function fileExists(filePath: string): Promise<boolean>;
 export declare function writeMarkdownFile(filePath: string, content: string): Promise<void>;
+export declare function writeBinaryFile(filePath: string, data: ArrayBuffer): Promise<void>;
+export declare function fileSize(filePath: string): Promise<null | number>;
 export declare function deleteFile(filePath: string): Promise<void>;
 export declare function assertDirectoryExists(directory: string): Promise<void>;

package/dist/shared/storage/markdown-store.js

@@ -10,6 +10,17 @@ export async function writeMarkdownFile(filePath, content) {
     await fs.mkdir(path.dirname(filePath), { recursive: true });
     await fs.writeFile(filePath, content);
 }
+// 中断で壊れたファイルが完成品として残らないよう、一時ファイルに書いてからrenameする
+export async function writeBinaryFile(filePath, data) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.tmp`;
+    await fs.writeFile(tempPath, new Uint8Array(data));
+    await fs.rename(tempPath, filePath);
+}
+export async function fileSize(filePath) {
+    const stats = await fs.stat(filePath).catch(() => null);
+    return stats?.size ?? null;
+}
 export async function deleteFile(filePath) {
     await fs.unlink(filePath);
 }