backlog-exporter 0.5.0 → 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ShuntaToda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -52,7 +52,7 @@ Backlog のデータをエクスポートするためのコマンドラインツ
 backlog-exporter は、Backlog のデータをローカルにエクスポートするためのコマンドラインツールです。
 現在、以下の機能をサポートしています：
 
-- **課題（Issue）のエクスポート**：Backlog の課題を Markdown ファイルとして保存
+- **課題（Issue）のエクスポート**：Backlog の課題を Markdown ファイルとして保存（カスタム属性対応）
 - **Wiki 記事のエクスポート**：Backlog の Wiki 記事を Markdown ファイルとして保存
 - **ドキュメントのエクスポート**：Backlog のドキュメントを Markdown ファイルとして保存
 - **一括エクスポート**：課題・Wiki・ドキュメントを同時に取得する機能
@@ -66,7 +66,7 @@ $ npm install -g backlog-exporter
 $ backlog-exporter COMMAND
 running command...
 $ backlog-exporter (--version)
-backlog-exporter/0.5.0 linux-x64 node-v24.2.0
+backlog-exporter/0.6.0 linux-x64 node-v24.2.0
 $ backlog-exporter --help [COMMAND]
 USAGE
   $ backlog-exporter COMMAND
@@ -127,6 +127,28 @@ $ backlog-exporter issue --domain example.backlog.jp --projectIdOrKey PROJECT_KE
 
 エクスポートされた課題は、指定したディレクトリ内に Markdown ファイルとして保存されます。ファイル名は課題のキーに基づいて自動的に生成されます。
 
+## カスタム属性の対応
+
+課題のエクスポートでは、Backlogのカスタム属性も含めて出力されます：
+
+### 対応している値の型
+- **プリミティブ値**: 文字列、数値などの単純な値
+- **配列値**: 複数選択のカスタム属性（カンマ区切りで表示）
+- **オブジェクト値**: 単一選択のカスタム属性（name または value プロパティを使用）
+
+### 表示形式
+カスタム属性はMarkdownテーブル形式で表示され、改行やパイプ文字も適切に処理されます：
+
+```markdown
+## カスタム属性
+
+| 属性名 | 値 |
+|--------|----| 
+| 工数（エンジニア） | 3 |
+| 担当チーム | フロントエンド, バックエンド |
+| 詳細 | 実装内容<br>- 機能A<br>- 機能B |
+```
+
 # Wiki のエクスポート
 
 `wiki`コマンドを使用すると、Backlog の Wiki ページを Markdown ファイルとしてエクスポートできます。
@@ -281,7 +303,7 @@ EXAMPLES
   最大1000件の課題を取得する（デフォルトは5000件）
 ```
 
-_See code: [src/commands/all/index.ts](https://github.com/ShuntaToda/backlog-exporter/blob/v0.5.0/src/commands/all/index.ts)_
+_See code: [src/commands/all/index.ts](https://github.com/ShuntaToda/backlog-exporter/blob/v0.6.0/src/commands/all/index.ts)_
 
 ## `backlog-exporter document`
 
@@ -313,7 +335,7 @@ EXAMPLES
   キーワード「仕様書」を含むドキュメントのみを取得する
 ```
 
-_See code: [src/commands/document/index.ts](https://github.com/ShuntaToda/backlog-exporter/blob/v0.5.0/src/commands/document/index.ts)_
+_See code: [src/commands/document/index.ts](https://github.com/ShuntaToda/backlog-exporter/blob/v0.6.0/src/commands/document/index.ts)_
 
 ## `backlog-exporter help [COMMAND]`
 
@@ -369,7 +391,7 @@ EXAMPLES
   最大10000件の課題を取得する（デフォルトは5000件）
 ```
 
-_See code: [src/commands/issue/index.ts](https://github.com/ShuntaToda/backlog-exporter/blob/v0.5.0/src/commands/issue/index.ts)_
+_See code: [src/commands/issue/index.ts](https://github.com/ShuntaToda/backlog-exporter/blob/v0.6.0/src/commands/issue/index.ts)_
 
 ## `backlog-exporter plugins`
 
@@ -699,7 +721,7 @@ EXAMPLES
   指定したディレクトリの設定を使用して更新する
 ```
 
-_See code: [src/commands/update/index.ts](https://github.com/ShuntaToda/backlog-exporter/blob/v0.5.0/src/commands/update/index.ts)_
+_See code: [src/commands/update/index.ts](https://github.com/ShuntaToda/backlog-exporter/blob/v0.6.0/src/commands/update/index.ts)_
 
 ## `backlog-exporter wiki`
 
@@ -726,7 +748,7 @@ EXAMPLES
   指定したディレクトリにWikiを保存する
 ```
 
-_See code: [src/commands/wiki/index.ts](https://github.com/ShuntaToda/backlog-exporter/blob/v0.5.0/src/commands/wiki/index.ts)_
+_See code: [src/commands/wiki/index.ts](https://github.com/ShuntaToda/backlog-exporter/blob/v0.6.0/src/commands/wiki/index.ts)_
 <!-- commandsstop -->
 
 # 出力形式
@@ -748,6 +770,15 @@ _See code: [src/commands/wiki/index.ts](https://github.com/ShuntaToda/backlog-ex
 - 更新日時: 2023/01/02 15:30:45
 - [Backlog Issue Link](https://example.backlog.jp/view/PROJ-123)
 
+## カスタム属性
+
+| 属性名 | 値 |
+|--------|----| 
+| 工数（エンジニア） | 3 |
+| 工数（PPO） | なし |
+| 担当チーム | フロントエンド, バックエンド |
+| 詳細 | 実装内容<br>- 機能A<br>- 機能B |
+
 ## 詳細
 
 ここに課題の詳細説明が入ります。
@@ -822,3 +853,4 @@ Backlog の書式がそのまま保持されます。
 - **階層構造の保持**: Wiki の階層構造を保持したエクスポート
 - **キーワード検索**: ドキュメントの検索キーワード対応
 - **差分更新**: 前回の更新以降に変更されたデータのみを更新
+- **カスタム属性対応**: 課題のカスタム属性をテーブル形式で表示（配列・オブジェクト・プリミティブ値に対応）

package/dist/commands/all/index.js

@@ -123,6 +123,7 @@ export default class All extends Command {
                 domain,
                 outputDir: documentOutput,
                 projectId,
+                projectIdOrKey,
             });
             // ドキュメントフォルダの最終更新日時を更新
             await updateSettings(documentOutput, {

package/dist/commands/document/index.js

@@ -68,6 +68,7 @@ export default class Document extends Command {
                 keyword,
                 outputDir,
                 projectId,
+                projectIdOrKey,
             });
             // 最終更新日時を更新
             await updateSettings(outputDir, {

package/dist/commands/update/index.js

@@ -257,6 +257,7 @@ export default class Update extends Command {
             lastUpdated,
             outputDir: options.targetDir,
             projectId: options.projectId,
+            projectIdOrKey: options.projectIdOrKey,
         });
         // 設定ファイルを更新
         await updateSettings(options.targetDir, {

package/dist/utils/backlog-api.d.ts

@@ -1,8 +1,25 @@
 import { Command } from '@oclif/core';
+/**
+ * カスタム属性セクションを作成する
+ * @param customFields カスタム属性の配列
+ * @returns Markdownテーブル形式のカスタム属性セクション
+ */
+export declare function createCustomFieldsSection(customFields?: Array<{
+    id: number;
+    name: string;
+    value: unknown;
+}>): string;
 /**
  * Backlogから課題をダウンロードする
  * @param command コマンドインスタンス
  * @param options 課題ダウンロードのオプション
+ * @param options.apiKey Backlog API key
+ * @param options.count 取得する課題の最大数
+ * @param options.domain Backlogのドメイン
+ * @param options.lastUpdated 最終更新日時
+ * @param options.outputDir 出力ディレクトリ
+ * @param options.projectId プロジェクトID
+ * @param options.statusId ステータスID
  */
 export declare function downloadIssues(command: Command, options: {
     apiKey: string;
@@ -17,6 +34,11 @@ export declare function downloadIssues(command: Command, options: {
  * BacklogからWikiをダウンロードする
  * @param command コマンドインスタンス
  * @param options Wikiダウンロードのオプション
+ * @param options.apiKey Backlog API key
+ * @param options.domain Backlogのドメイン
+ * @param options.lastUpdated 最終更新日時
+ * @param options.outputDir 出力ディレクトリ
+ * @param options.projectIdOrKey プロジェクトIDまたはキー
  */
 export declare function downloadWikis(command: Command, options: {
     apiKey: string;
@@ -29,6 +51,13 @@ export declare function downloadWikis(command: Command, options: {
  * Backlogからドキュメントをダウンロードする
  * @param command コマンドインスタンス
  * @param options ドキュメントダウンロードのオプション
+ * @param options.apiKey Backlog API key
+ * @param options.domain Backlogのドメイン
+ * @param options.keyword キーワードフィルター
+ * @param options.lastUpdated 最終更新日時
+ * @param options.outputDir 出力ディレクトリ
+ * @param options.projectId プロジェクトID
+ * @param options.projectIdOrKey プロジェクトIDまたはキー
  */
 export declare function downloadDocuments(command: Command, options: {
     apiKey: string;
@@ -37,4 +66,5 @@ export declare function downloadDocuments(command: Command, options: {
     lastUpdated?: string;
     outputDir: string;
     projectId: number;
+    projectIdOrKey: string;
 }): Promise<void>;

package/dist/utils/backlog-api.js

@@ -5,10 +5,54 @@ import process from 'node:process';
 import { sanitizeFileName, sanitizeWikiFileName } from './common.js';
 import { appendLog } from './log.js';
 import { RateLimiter } from './sleep.js';
+/**
+ * カスタム属性セクションを作成する
+ * @param customFields カスタム属性の配列
+ * @returns Markdownテーブル形式のカスタム属性セクション
+ */
+export function createCustomFieldsSection(customFields) {
+    if (!customFields || customFields.length === 0) {
+        return '';
+    }
+    let customFieldsSection = '\n\n## カスタム属性\n\n| 属性名 | 値 |\n|--------|----|\n';
+    for (const customField of customFields) {
+        let fieldValue = 'なし';
+        if (customField.value !== null && customField.value !== undefined) {
+            if (Array.isArray(customField.value)) {
+                // 配列の場合（複数選択など）
+                fieldValue = customField.value
+                    .map(item => item.name || item.value || String(item))
+                    .join(', ');
+            }
+            else if (typeof customField.value === 'object' && customField.value !== null) {
+                // オブジェクトの場合（単一選択など）
+                const valueObj = customField.value;
+                fieldValue = valueObj.name || valueObj.value || String(customField.value);
+            }
+            else {
+                // プリミティブ値の場合
+                fieldValue = String(customField.value);
+            }
+        }
+        // テーブル内では改行をHTMLの<br>タグに変換し、パイプ文字をエスケープ
+        const escapedFieldValue = fieldValue
+            .replaceAll('|', String.raw `\|`)
+            .replaceAll('\n', '<br>');
+        customFieldsSection += `| ${customField.name} | ${escapedFieldValue} |\n`;
+    }
+    return customFieldsSection;
+}
 /**
  * Backlogから課題をダウンロードする
  * @param command コマンドインスタンス
  * @param options 課題ダウンロードのオプション
+ * @param options.apiKey Backlog API key
+ * @param options.count 取得する課題の最大数
+ * @param options.domain Backlogのドメイン
+ * @param options.lastUpdated 最終更新日時
+ * @param options.outputDir 出力ディレクトリ
+ * @param options.projectId プロジェクトID
+ * @param options.statusId ステータスID
  */
 export async function downloadIssues(command, options) {
     const baseUrl = `https://${options.domain}/api/v2`;
@@ -114,6 +158,8 @@ export async function downloadIssues(command, options) {
             // 年ごとのフォルダ内にMarkdownファイルを保存
             const issueFileName = `${sanitizeFileName(issue.summary)}.md`;
             const issueFilePath = path.join(yearDirPath, issueFileName);
+            // カスタム属性セクションを作成
+            const customFieldsSection = createCustomFieldsSection(issue.customFields);
             // Markdownファイルに書き込む
             const assigneeName = issue.assignee ? issue.assignee.name : '未割り当て';
             const markdownContent = `# ${issue.summary}
@@ -125,7 +171,7 @@ export async function downloadIssues(command, options) {
 - 担当者: ${assigneeName}
 - 作成日時: ${new Date(issue.created).toLocaleString('ja-JP')}
 - 更新日時: ${new Date(issue.updated).toLocaleString('ja-JP')}
-- [Backlog Issue Link](${backlogIssueUrl})
+- [Backlog Issue Link](${backlogIssueUrl})${customFieldsSection}
 
 ## 詳細
 ${issue.description || '詳細情報なし'}${commentsSection}`;
@@ -176,6 +222,11 @@ async function fetchAllCommentsForIssue({ apiKey, baseUrl, command, issueKey, ra
  * BacklogからWikiをダウンロードする
  * @param command コマンドインスタンス
  * @param options Wikiダウンロードのオプション
+ * @param options.apiKey Backlog API key
+ * @param options.domain Backlogのドメイン
+ * @param options.lastUpdated 最終更新日時
+ * @param options.outputDir 出力ディレクトリ
+ * @param options.projectIdOrKey プロジェクトIDまたはキー
  */
 export async function downloadWikis(command, options) {
     const baseUrl = `https://${options.domain}/api/v2`;
@@ -259,6 +310,13 @@ export async function downloadWikis(command, options) {
  * Backlogからドキュメントをダウンロードする
  * @param command コマンドインスタンス
  * @param options ドキュメントダウンロードのオプション
+ * @param options.apiKey Backlog API key
+ * @param options.domain Backlogのドメイン
+ * @param options.keyword キーワードフィルター
+ * @param options.lastUpdated 最終更新日時
+ * @param options.outputDir 出力ディレクトリ
+ * @param options.projectId プロジェクトID
+ * @param options.projectIdOrKey プロジェクトIDまたはキー
  */
 export async function downloadDocuments(command, options) {
     const baseUrl = `https://${options.domain}/api/v2`;
@@ -320,7 +378,7 @@ export async function downloadDocuments(command, options) {
                 const dirPath = path.dirname(documentFilePath);
                 await fs.mkdir(dirPath, { recursive: true });
                 // Backlogのドキュメントへのリンクを作成
-                const backlogDocumentUrl = `https://${options.domain}/document/${node.id}`;
+                const backlogDocumentUrl = `https://${options.domain}/document/${options.projectIdOrKey}/${node.id}`;
                 // 添付ファイルリストの作成
                 let attachmentsSection = '';
                 if (documentDetail.attachments && documentDetail.attachments.length > 0) {

package/oclif.manifest.json

@@ -70,14 +70,15 @@
         "index.js"
       ]
     },
-    "document": {
+    "issue": {
       "aliases": [],
       "args": {},
-      "description": "Backlogからドキュメントを取得してMarkdownファイルとして保存する",
+      "description": "Backlogから課題を取得してMarkdownファイルとして保存する",
       "examples": [
-        "<%= config.bin %> <%= command.id %> --domain example.backlog.jp --projectIdOrKey PROJECT_KEY --apiKey YOUR_API_KEY\nドキュメントをMarkdownファイルとして保存する\n",
-        "<%= config.bin %> <%= command.id %> --domain example.backlog.jp --projectIdOrKey PROJECT_KEY --apiKey YOUR_API_KEY --output ./my-documents\n指定したディレクトリにドキュメントを保存する\n",
-        "<%= config.bin %> <%= command.id %> --domain example.backlog.jp --projectIdOrKey PROJECT_KEY --apiKey YOUR_API_KEY --keyword 仕様書\nキーワード「仕様書」を含むドキュメントのみを取得する\n"
+        "<%= config.bin %> <%= command.id %> --domain example.backlog.jp --projectIdOrKey PROJECT_KEY --apiKey YOUR_API_KEY\n課題をMarkdownファイルとして保存する\n",
+        "<%= config.bin %> <%= command.id %> --domain example.backlog.jp --projectIdOrKey PROJECT_KEY --apiKey YOUR_API_KEY --output ./my-issues\n指定したディレクトリに課題を保存する\n",
+        "<%= config.bin %> <%= command.id %> --domain example.backlog.jp --projectIdOrKey PROJECT_KEY --apiKey YOUR_API_KEY --statusId 1,2,3\n指定したステータスIDの課題のみを取得する\n",
+        "<%= config.bin %> <%= command.id %> --domain example.backlog.jp --projectIdOrKey PROJECT_KEY --apiKey YOUR_API_KEY --maxCount 10000\n最大10000件の課題を取得する（デフォルトは5000件）\n"
       ],
       "flags": {
         "apiKey": {
@@ -96,10 +97,12 @@
           "multiple": false,
           "type": "option"
         },
-        "keyword": {
-          "description": "検索キーワード",
-          "name": "keyword",
+        "maxCount": {
+          "char": "m",
+          "description": "一度に取得する課題の最大数（デフォルト: 5000）",
+          "name": "maxCount",
           "required": false,
+          "default": 5000,
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -120,11 +123,19 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "statusId": {
+          "description": "ステータスID（カンマ区切りで複数指定可能）",
+          "name": "statusId",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "document",
+      "id": "issue",
       "pluginAlias": "backlog-exporter",
       "pluginName": "backlog-exporter",
       "pluginType": "core",
@@ -134,19 +145,18 @@
       "relativePath": [
         "dist",
         "commands",
-        "document",
+        "issue",
         "index.js"
       ]
     },
-    "issue": {
+    "document": {
       "aliases": [],
       "args": {},
-      "description": "Backlogから課題を取得してMarkdownファイルとして保存する",
+      "description": "Backlogからドキュメントを取得してMarkdownファイルとして保存する",
       "examples": [
-        "<%= config.bin %> <%= command.id %> --domain example.backlog.jp --projectIdOrKey PROJECT_KEY --apiKey YOUR_API_KEY\n課題をMarkdownファイルとして保存する\n",
-        "<%= config.bin %> <%= command.id %> --domain example.backlog.jp --projectIdOrKey PROJECT_KEY --apiKey YOUR_API_KEY --output ./my-issues\n指定したディレクトリに課題を保存する\n",
-        "<%= config.bin %> <%= command.id %> --domain example.backlog.jp --projectIdOrKey PROJECT_KEY --apiKey YOUR_API_KEY --statusId 1,2,3\n指定したステータスIDの課題のみを取得する\n",
-        "<%= 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\nドキュメントをMarkdownファイルとして保存する\n",
+        "<%= config.bin %> <%= command.id %> --domain example.backlog.jp --projectIdOrKey PROJECT_KEY --apiKey YOUR_API_KEY --output ./my-documents\n指定したディレクトリにドキュメントを保存する\n",
+        "<%= config.bin %> <%= command.id %> --domain example.backlog.jp --projectIdOrKey PROJECT_KEY --apiKey YOUR_API_KEY --keyword 仕様書\nキーワード「仕様書」を含むドキュメントのみを取得する\n"
       ],
       "flags": {
         "apiKey": {
@@ -165,12 +175,10 @@
           "multiple": false,
           "type": "option"
         },
-        "maxCount": {
-          "char": "m",
-          "description": "一度に取得する課題の最大数（デフォルト: 5000）",
-          "name": "maxCount",
+        "keyword": {
+          "description": "検索キーワード",
+          "name": "keyword",
           "required": false,
-          "default": 5000,
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -191,19 +199,11 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
-        },
-        "statusId": {
-          "description": "ステータスID（カンマ区切りで複数指定可能）",
-          "name": "statusId",
-          "required": false,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "issue",
+      "id": "document",
       "pluginAlias": "backlog-exporter",
       "pluginName": "backlog-exporter",
       "pluginType": "core",
@@ -213,7 +213,7 @@
       "relativePath": [
         "dist",
         "commands",
-        "issue",
+        "document",
         "index.js"
       ]
     },
@@ -364,5 +364,5 @@
       ]
     }
   },
-  "version": "0.5.0"
+  "version": "0.6.0"
 }

package/package.json

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