backlog-exporter 1.0.0 → 1.1.1

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);
 }

package/oclif.manifest.json

@@ -31,6 +31,14 @@
           "multiple": false,
           "type": "option"
         },
+        "downloadAttachments": {
+          "char": "d",
+          "description": "課題の添付ファイルもダウンロードする",
+          "name": "downloadAttachments",
+          "required": false,
+          "allowNo": false,
+          "type": "boolean"
+        },
         "exclude": {
           "description": "Exclude the specified types, separated by commas (e.g., 'documents,wiki')",
           "name": "exclude",
@@ -131,6 +139,14 @@
           "multiple": false,
           "type": "option"
         },
+        "downloadAttachments": {
+          "char": "d",
+          "description": "添付ファイルもダウンロードする",
+          "name": "downloadAttachments",
+          "required": false,
+          "allowNo": false,
+          "type": "boolean"
+        },
         "keyword": {
           "description": "検索キーワード",
           "name": "keyword",
@@ -184,7 +200,8 @@
         "<%= config.bin %> <%= command.id %> --domain example.backlog.jp --projectIdOrKey PROJECT_KEY --apiKey YOUR_API_KEY --maxCount 10000\n最大10000件の課題を取得する（デフォルトは5000件）\n",
         "<%= config.bin %> <%= command.id %> --domain example.backlog.jp --projectIdOrKey PROJECT_KEY --apiKey YOUR_API_KEY --issueKeyFileName\nファイル名を課題キーにする\n",
         "<%= config.bin %> <%= command.id %> --domain example.backlog.jp --projectIdOrKey PROJECT_KEY --apiKey YOUR_API_KEY --issueKeyFolder\n課題キーでフォルダを作成する\n",
-        "<%= config.bin %> <%= command.id %> --domain example.backlog.jp --projectIdOrKey PROJECT_KEY --apiKey YOUR_API_KEY --issueKeyFileName --issueKeyFolder\n課題キーでフォルダを作成し、ファイル名も課題キーにする\n"
+        "<%= config.bin %> <%= command.id %> --domain example.backlog.jp --projectIdOrKey PROJECT_KEY --apiKey YOUR_API_KEY --issueKeyFileName --issueKeyFolder\n課題キーでフォルダを作成し、ファイル名も課題キーにする\n",
+        "<%= config.bin %> <%= command.id %> --domain example.backlog.jp --projectIdOrKey PROJECT_KEY --apiKey YOUR_API_KEY --downloadAttachments\n課題の添付ファイルもダウンロードする\n"
       ],
       "flags": {
         "apiKey": {
@@ -203,6 +220,14 @@
           "multiple": false,
           "type": "option"
         },
+        "downloadAttachments": {
+          "char": "d",
+          "description": "課題の添付ファイルもダウンロードする",
+          "name": "downloadAttachments",
+          "required": false,
+          "allowNo": false,
+          "type": "boolean"
+        },
         "issueKeyFileName": {
           "description": "ファイル名を課題キーにする",
           "name": "issueKeyFileName",
@@ -388,6 +413,14 @@
           "multiple": false,
           "type": "option"
         },
+        "downloadAttachments": {
+          "char": "d",
+          "description": "課題の添付ファイルもダウンロードする（未指定時は設定ファイルの値を使用）",
+          "name": "downloadAttachments",
+          "required": false,
+          "allowNo": false,
+          "type": "boolean"
+        },
         "force": {
           "char": "f",
           "description": "確認プロンプトをスキップする",
@@ -490,6 +523,14 @@
           "multiple": false,
           "type": "option"
         },
+        "downloadAttachments": {
+          "char": "d",
+          "description": "添付ファイルもダウンロードする",
+          "name": "downloadAttachments",
+          "required": false,
+          "allowNo": false,
+          "type": "boolean"
+        },
         "output": {
           "char": "o",
           "description": "出力ディレクトリパス",
@@ -525,5 +566,5 @@
       ]
     }
   },
-  "version": "1.0.0"
+  "version": "1.1.1"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "backlog-exporter",
   "description": "A new CLI generated with oclif",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "author": "ShuntaToda",
   "bin": {
     "backlog-exporter": "bin/run.js"

package/dist/shared/backlog/rate-limiter.d.ts

@@ -1,9 +0,0 @@
-export declare const sleep: (ms: number) => Promise<void>;
-export declare class RateLimiter {
-    private readonly onWait?;
-    private requestCount;
-    constructor(onWait?: () => void);
-    getCount(): number;
-    increment(): Promise<number>;
-    setCount(count: number): void;
-}

package/dist/shared/backlog/rate-limiter.js

@@ -1,25 +0,0 @@
-export const sleep = (ms) => new Promise((resolve) => {
-    setTimeout(resolve, ms);
-});
-// Backlogのレート制限(100req/15s)対策: 100リクエストごとに15秒待機する
-export class RateLimiter {
-    onWait;
-    requestCount = 0;
-    constructor(onWait) {
-        this.onWait = onWait;
-    }
-    getCount() {
-        return this.requestCount;
-    }
-    async increment() {
-        this.requestCount++;
-        if (this.requestCount > 1 && this.requestCount % 100 === 0) {
-            this.onWait?.();
-            await sleep(15_000);
-        }
-        return this.requestCount;
-    }
-    setCount(count) {
-        this.requestCount = count;
-    }
-}