atl-fetch 1.0.0 → 1.2.0

package/README.md

@@ -16,6 +16,9 @@ Atlassian Cloud（Jira / Confluence）から情報を取得する Node.js CLI
 - **複数出力形式**: JSON / Markdown / YAML
 - **差分表示**: バージョン間の Unified diff 形式表示
 - **添付ファイルダウンロード**: 指定ディレクトリへの保存
+- **親切なエラーメッセージ**: エラーコード、原因、解決策を表示
+- **進捗表示**: スピナーによる処理状況の可視化
+- **認証チェック**: `atl-fetch auth check` で設定状態を確認
 
 ## 動作要件
 
@@ -37,7 +40,6 @@ pnpm add -g atl-fetch
 ### 1. 環境変数の設定
 
 ```bash
-export ATLASSIAN_DOMAIN="your-domain.atlassian.net"
 export ATLASSIAN_EMAIL="your-email@example.com"
 export ATLASSIAN_API_TOKEN="your-api-token"
 ```
@@ -56,54 +58,63 @@ atl-fetch https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/123456/Page+
 # Markdown 形式で出力
 atl-fetch https://your-domain.atlassian.net/browse/PROJECT-123 --format markdown
 
-# ファイルに保存
-atl-fetch https://your-domain.atlassian.net/browse/PROJECT-123 --output result.json
+# 添付ファイルをダウンロード
+atl-fetch https://your-domain.atlassian.net/browse/PROJECT-123 --download --dir ./output
+
+# ファイルに保存（リダイレクト）
+atl-fetch https://your-domain.atlassian.net/browse/PROJECT-123 > result.json
 ```
 
 ## CLI オプション
 
-| オプション                    | 短縮形  | 説明                           | デフォルト         |
-| ------------------------ | ---- | ---------------------------- | ------------- |
-| `--format`               | `-f` | 出力形式（json / markdown / yaml） | json          |
-| `--output`               | `-o` | 出力ファイルパス                     | stdout        |
-| `--include-comments`     | `-c` | コメントを含める                     | false         |
-| `--include-history`      | `-h` | 変更履歴を含める                     | false         |
-| `--include-attachments`  | `-a` | 添付ファイルを含める                   | false         |
-| `--download-attachments` | `-d` | 添付ファイルをダウンロード                | false         |
-| `--attachments-dir`      |      | 添付ファイルの保存先                   | ./attachments |
-| `--diff`                 |      | 指定バージョンとの差分を表示               | -             |
-| `--help`                 |      | ヘルプを表示                       | -             |
-| `--version`              |      | バージョンを表示                     | -             |
-
-## ライブラリとしての使用
-
-```typescript
-import { fetchJiraIssue, fetchConfluencePage } from 'atl-fetch';
-
-// Jira Issue を取得
-const jiraResult = await fetchJiraIssue({
-  url: 'https://your-domain.atlassian.net/browse/PROJECT-123',
-  includeComments: true,
-  includeHistory: false,
-});
-
-if (jiraResult.isOk()) {
-  console.log(jiraResult.value);
-} else {
-  console.error(jiraResult.error);
-}
-
-// Confluence ページを取得
-const confluenceResult = await fetchConfluencePage({
-  url: 'https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/123456/Page+Title',
-  includeHistory: true,
-});
-
-if (confluenceResult.isOk()) {
-  console.log(confluenceResult.value);
-}
+| オプション        | 短縮形  | 説明                           | デフォルト |
+| ------------ | ---- | ---------------------------- | ----- |
+| `--format`   | `-f` | 出力形式（json / markdown / yaml） | json  |
+| `--download` | `-d` | 添付ファイルをダウンロード                | false |
+| `--dir`      | `-o` | 保存先ディレクトリ                    | -     |
+| `--diff`     |      | 差分のみを出力                      | false |
+| `--color`    |      | カラー出力を有効化                    | true  |
+| `--verbose`  | `-v` | 詳細出力を有効化                     | false |
+| `--debug`    |      | デバッグ出力を有効化（開発者向け）            | false |
+| `--help`     | `-h` | ヘルプを表示                       | -     |
+| `--version`  | `-V` | バージョンを表示                     | -     |
+
+**注意**: `--dir` は `--download` と一緒に使用する必要があります。
+
+## サブコマンド
+
+### `atl-fetch auth check`
+
+認証情報の設定状態を確認します。
+
+```bash
+atl-fetch auth check
 ```
 
+出力例（設定済み）:
+```
+認証情報チェック
+────────────────────────────────────────
+
+✓ 認証情報が正しく設定されています
+
+  設定状態:
+    ATLASSIAN_EMAIL:     user@example.com
+    ATLASSIAN_API_TOKEN: ***abcd
+```
+
+## エラーコード
+
+問題が発生した場合、以下のエラーコードと解決策が表示されます。
+
+| コード          | 説明                 | 主な原因                    |
+| ------------ | ------------------ | ----------------------- |
+| `ATL-URL-001`  | URL の形式が不正         | サポートされていない URL 形式       |
+| `ATL-AUTH-001` | 認証失敗               | API トークンが無効または期限切れ     |
+| `ATL-404-001`  | リソースが見つからない        | URL が間違っている、または削除済み    |
+| `ATL-403-001`  | アクセス権限なし           | 該当リソースへの権限がない          |
+| `ATL-NET-001`  | ネットワークエラー          | インターネット接続の問題           |
+
 ## ライセンス
 
 [MIT](LICENSE)

package/dist/cli/cli.d.ts

@@ -19,6 +19,10 @@ export interface CliArgs {
     diff: boolean;
     /** カラー出力を有効にする */
     color: boolean;
+    /** 詳細出力を有効にする */
+    verbose: boolean;
+    /** デバッグ出力を有効にする */
+    debug: boolean;
 }
 /**
  * CLI 作成オプション
@@ -45,6 +49,10 @@ export declare function createCli(options?: CliOptions): import("yargs").Argv<{
     diff: boolean;
 } & {
     color: boolean;
+} & {
+    verbose: boolean;
+} & {
+    debug: boolean;
 }>;
 /**
  * CLI を実行する

package/dist/cli/cli.js

@@ -6,7 +6,9 @@
 import { createRequire } from 'node:module';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
+import { getCredentials } from '../services/auth/auth-service.js';
 import { fetchAndOutput, fetchAndSave } from '../services/fetch/fetch-service.js';
+import { CliSpinner, colors, formatError, formatSuccess, formatWarn, SPINNER_STEPS } from './spinner.js';
 const require = createRequire(import.meta.url);
 const packageJson = require('../../package.json');
 /**
@@ -25,13 +27,16 @@ export function createCli(options = {}) {
     const { exitProcess = true } = options;
     return yargs()
         .scriptName('atl-fetch')
-        .usage('Usage: $0 <url> [options]')
+        .usage('Usage: $0 <command> [options]')
         .command('$0 <url>', 'Atlassian Cloud の URL から情報を取得する', (yargs) => {
         return yargs.positional('url', {
             demandOption: true,
             describe: 'Atlassian Cloud URL (Jira Issue または Confluence ページ)',
             type: 'string',
         });
+    })
+        .command('auth', '認証情報を管理する', (yargs) => {
+        return yargs.command('check', '認証情報の設定状態を確認する', () => { }, runAuthCheck);
     })
         .option('format', {
         alias: 'f',
@@ -68,6 +73,39 @@ export function createCli(options = {}) {
         describe: 'カラー出力を有効にする',
         type: 'boolean',
     })
+        .option('verbose', {
+        alias: 'v',
+        default: false,
+        describe: '詳細出力を有効にする',
+        type: 'boolean',
+    })
+        .option('debug', {
+        default: false,
+        describe: 'デバッグ出力を有効にする（開発者向け）',
+        type: 'boolean',
+    })
+        .example([
+        ['$0 https://mycompany.atlassian.net/browse/PROJ-123', 'Jira Issue を JSON で取得'],
+        ['$0 https://mycompany.atlassian.net/browse/PROJ-123 -f markdown', 'Markdown 形式で取得'],
+        [
+            '$0 https://mycompany.atlassian.net/wiki/spaces/DOCS/pages/123456 -d -o ./output',
+            'Confluence ページを添付ファイルごとダウンロード',
+        ],
+        ['$0 https://mycompany.atlassian.net/browse/PROJ-123 -v', '詳細モードで実行'],
+    ])
+        .epilogue(`環境変数:
+  ATLASSIAN_EMAIL       Atlassian アカウントのメールアドレス（必須）
+  ATLASSIAN_API_TOKEN   API トークン（必須）
+                        https://id.atlassian.com/manage-profile/security/api-tokens で生成
+
+エラーコード:
+  ATL-URL-001   URL の形式が不正
+  ATL-AUTH-001  認証失敗
+  ATL-404-001   リソースが見つからない
+  ATL-403-001   アクセス権限なし
+  ATL-NET-001   ネットワークエラー
+
+詳細: https://github.com/semba-yui/atl-fetch`)
         .help('help')
         .alias('h', 'help')
         .version(CLI_VERSION)
@@ -103,29 +141,144 @@ export async function runCli() {
     const download = argv['download'];
     const dir = argv['dir'];
     const colorEnabled = argv['color'];
+    const verbose = argv['verbose'];
+    const debug = argv['debug'];
+    const spinner = new CliSpinner(colorEnabled);
+    // verbose モードの場合、処理開始を表示
+    if (verbose) {
+        console.log(colors.dim(`atl-fetch v${CLI_VERSION}`));
+        console.log(colors.dim(`URL: ${url}`));
+        console.log(colors.dim(`形式: ${format}`));
+        if (download) {
+            console.log(colors.dim(`ダウンロードモード: 有効`));
+            console.log(colors.dim(`保存先: ${dir ?? process.cwd()}`));
+        }
+        console.log('');
+    }
     // ダウンロードモード
     if (download) {
         const baseDir = dir ?? process.cwd();
+        spinner.startStep(SPINNER_STEPS.FETCH_DATA);
         const result = await fetchAndSave(url, {
             baseDir,
             cliVersion: CLI_VERSION,
             sourceUrl: url,
         });
         if (result.isErr()) {
-            console.error(`エラー: ${result.error.message}`);
+            spinner.fail();
+            console.error(formatErrorForKind(result.error.kind, result.error.message, url, debug));
             process.exit(1);
         }
-        console.log(`保存完了: ${result.value.directory}`);
+        spinner.succeedStep(SPINNER_STEPS.SAVE_FILES);
+        console.log(formatSuccess('保存完了', {
+            URL: url,
+            保存先: result.value.directory,
+        }));
         return;
     }
     // 通常モード（標準出力）
+    spinner.startStep(SPINNER_STEPS.FETCH_DATA);
     const result = await fetchAndOutput(url, {
         colorEnabled,
         format,
     });
     if (result.isErr()) {
-        console.error(`エラー: ${result.error.message}`);
+        spinner.fail();
+        console.error(formatErrorForKind(result.error.kind, result.error.message, url, debug));
         process.exit(1);
     }
+    spinner.succeedStep(SPINNER_STEPS.FORMAT_OUTPUT);
     console.log(result.value);
 }
+/**
+ * エラー種別に応じたエラーメッセージを生成する
+ *
+ * @param kind エラー種別
+ * @param message エラーメッセージ
+ * @param url 対象URL
+ * @param debug デバッグモードが有効かどうか
+ * @returns 整形されたエラーメッセージ
+ */
+function formatErrorForKind(kind, message, url, debug) {
+    let result;
+    switch (kind) {
+        case 'URL_PARSE_ERROR':
+            result = formatError('ATL-URL-001', message, 'URLの形式が正しくありません', `サポートされるURL形式:\n    - Jira: https://<site>.atlassian.net/browse/<KEY>\n    - Confluence: https://<site>.atlassian.net/wiki/spaces/<SPACE>/pages/<ID>`);
+            break;
+        case 'AUTH_FAILED':
+            result = formatError('ATL-AUTH-001', message, 'APIトークンが無効または期限切れです', `環境変数を確認してください:\n    - ATLASSIAN_EMAIL: Atlassianアカウントのメールアドレス\n    - ATLASSIAN_API_TOKEN: https://id.atlassian.com/manage-profile/security/api-tokens で生成`);
+            break;
+        case 'NOT_FOUND':
+            result = formatError('ATL-404-001', message, '指定されたリソースが見つかりません', `URL: ${colors.cyan(url)}\n    - URLが正しいか確認してください\n    - リソースが削除されていないか確認してください`);
+            break;
+        case 'FORBIDDEN':
+            result = formatError('ATL-403-001', message, 'アクセス権限がありません', `URL: ${colors.cyan(url)}\n    - 該当リソースへのアクセス権限があるか確認してください`);
+            break;
+        case 'NETWORK_ERROR':
+            result = formatError('ATL-NET-001', message, 'ネットワーク接続に問題があります', '- インターネット接続を確認してください\n    - ファイアウォール/プロキシ設定を確認してください');
+            break;
+        default:
+            result = formatError('ATL-ERR-001', message, '予期しないエラーが発生しました', '--debug フラグで詳細を確認してください');
+    }
+    // デバッグモードの場合、追加情報を表示
+    if (debug) {
+        result += `\n\n${colors.dim('--- デバッグ情報 ---')}`;
+        result += `\n${colors.dim(`エラー種別: ${kind}`)}`;
+        result += `\n${colors.dim(`対象URL: ${url}`)}`;
+        result += `\n${colors.dim(`タイムスタンプ: ${new Date().toISOString()}`)}`;
+    }
+    return result;
+}
+/**
+ * 認証情報のチェックを実行する
+ *
+ * 環境変数が正しく設定されているかを確認し、結果を表示する。
+ */
+function runAuthCheck() {
+    console.log(colors.bold('認証情報チェック'));
+    console.log(colors.dim('─'.repeat(40)));
+    console.log('');
+    const result = getCredentials();
+    if (result.isOk()) {
+        const email = result.value.email;
+        const maskedToken = `***${result.value.apiToken.slice(-4)}`;
+        console.log(colors.success('✓ 認証情報が正しく設定されています'));
+        console.log('');
+        console.log(colors.dim('  設定状態:'));
+        console.log(colors.dim(`    ATLASSIAN_EMAIL:     ${colors.cyan(email)}`));
+        console.log(colors.dim(`    ATLASSIAN_API_TOKEN: ${colors.cyan(maskedToken)}`));
+        console.log('');
+        console.log(colors.dim('  ※ 実際のAPI接続テストは行っていません。'));
+        console.log(colors.dim('    トークンが有効かどうかは、実際にURLを取得して確認してください。'));
+    }
+    else {
+        const error = result.error;
+        console.log(colors.error('✗ 認証情報の設定に問題があります'));
+        console.log('');
+        switch (error.kind) {
+            case 'MISSING_EMAIL':
+                console.log(formatWarn('ATLASSIAN_EMAIL が設定されていません'));
+                console.log('');
+                console.log(colors.dim('  設定方法:'));
+                console.log(colors.dim('    export ATLASSIAN_EMAIL="your-email@example.com"'));
+                break;
+            case 'MISSING_TOKEN':
+                console.log(formatWarn('ATLASSIAN_API_TOKEN が設定されていません'));
+                console.log('');
+                console.log(colors.dim('  設定方法:'));
+                console.log(colors.dim('    export ATLASSIAN_API_TOKEN="your-api-token"'));
+                console.log('');
+                console.log(colors.dim('  トークンの取得:'));
+                console.log(colors.dim('    https://id.atlassian.com/manage-profile/security/api-tokens'));
+                break;
+            case 'INVALID_EMAIL':
+                console.log(formatWarn('ATLASSIAN_EMAIL の形式が無効です'));
+                console.log('');
+                console.log(colors.dim('  有効なメールアドレス形式で設定してください。'));
+                break;
+            default:
+                console.log(formatWarn(error.message));
+        }
+        process.exit(1);
+    }
+}

package/dist/cli/spinner.d.ts

@@ -0,0 +1,189 @@
+/**
+ * CLI スピナー・進捗表示ユーティリティ
+ *
+ * ora と picocolors を使用した統一的な進捗表示を提供する。
+ */
+/**
+ * スピナーのステップ定義
+ */
+export interface SpinnerStep {
+    /** ステップ名（内部識別用） */
+    name: string;
+    /** 表示テキスト（進行中） */
+    text: string;
+    /** 完了時のテキスト */
+    successText?: string;
+}
+/**
+ * 事前定義されたスピナーステップ
+ */
+export declare const SPINNER_STEPS: {
+    readonly AUTH_CHECK: {
+        readonly name: "auth_check";
+        readonly successText: "認証情報を確認しました";
+        readonly text: "認証情報を確認中...";
+    };
+    readonly DOWNLOAD_ATTACHMENTS: {
+        readonly name: "download_attachments";
+        readonly successText: "添付ファイルをダウンロードしました";
+        readonly text: "添付ファイルをダウンロード中...";
+    };
+    readonly FETCH_CONFLUENCE: {
+        readonly name: "fetch_confluence";
+        readonly successText: "Confluence ページを取得しました";
+        readonly text: "Confluence ページを取得中...";
+    };
+    readonly FETCH_DATA: {
+        readonly name: "fetch_data";
+        readonly successText: "データを取得しました";
+        readonly text: "データを取得中...";
+    };
+    readonly FETCH_JIRA: {
+        readonly name: "fetch_jira";
+        readonly successText: "Jira Issue を取得しました";
+        readonly text: "Jira Issue を取得中...";
+    };
+    readonly FORMAT_OUTPUT: {
+        readonly name: "format_output";
+        readonly successText: "出力を整形しました";
+        readonly text: "出力を整形中...";
+    };
+    readonly SAVE_FILES: {
+        readonly name: "save_files";
+        readonly successText: "ファイルを保存しました";
+        readonly text: "ファイルを保存中...";
+    };
+    readonly URL_PARSE: {
+        readonly name: "url_parse";
+        readonly successText: "URLを解析しました";
+        readonly text: "URLを解析中...";
+    };
+};
+/**
+ * CLI 出力のカラーヘルパー
+ */
+export declare const colors: {
+    /** 太字 */
+    readonly bold: (text: string) => string;
+    /** シアン（ファイルパスなど） */
+    readonly cyan: (text: string) => string;
+    /** 薄いテキスト（グレー） */
+    readonly dim: (text: string) => string;
+    /** エラーメッセージ（赤） */
+    readonly error: (text: string) => string;
+    /** 情報メッセージ（青） */
+    readonly info: (text: string) => string;
+    /** マゼンタ（URL など） */
+    readonly magenta: (text: string) => string;
+    /** 成功メッセージ（緑） */
+    readonly success: (text: string) => string;
+    /** 警告メッセージ（黄） */
+    readonly warn: (text: string) => string;
+};
+/**
+ * CLI スピナー管理クラス
+ *
+ * 処理の進捗状況をユーザーに表示するためのスピナーを管理する。
+ *
+ * @example
+ * ```typescript
+ * const spinner = new CliSpinner();
+ * spinner.start('データを取得中...');
+ * // ... 処理 ...
+ * spinner.succeed('データを取得しました');
+ * ```
+ */
+export declare class CliSpinner {
+    private spinner;
+    private enabled;
+    /**
+     * CliSpinner インスタンスを作成する
+     *
+     * @param enabled スピナーを有効にするかどうか（CI環境などでは無効にする）
+     */
+    constructor(enabled?: boolean);
+    /**
+     * スピナーを開始する
+     *
+     * @param text 表示するテキスト
+     */
+    start(text: string): void;
+    /**
+     * スピナーのテキストを更新する
+     *
+     * @param text 新しいテキスト
+     */
+    update(text: string): void;
+    /**
+     * スピナーを成功状態で終了する
+     *
+     * @param text 成功時に表示するテキスト
+     */
+    succeed(text?: string): void;
+    /**
+     * スピナーを失敗状態で終了する
+     *
+     * @param text 失敗時に表示するテキスト
+     */
+    fail(text?: string): void;
+    /**
+     * スピナーを警告状態で終了する
+     *
+     * @param text 警告時に表示するテキスト
+     */
+    warn(text?: string): void;
+    /**
+     * スピナーを情報状態で終了する
+     *
+     * @param text 情報として表示するテキスト
+     */
+    info(text?: string): void;
+    /**
+     * スピナーを停止する（状態なし）
+     */
+    stop(): void;
+    /**
+     * 事前定義されたステップでスピナーを開始する
+     *
+     * @param step スピナーステップ定義
+     */
+    startStep(step: SpinnerStep): void;
+    /**
+     * 事前定義されたステップを成功状態で終了する
+     *
+     * @param step スピナーステップ定義
+     */
+    succeedStep(step: SpinnerStep): void;
+}
+/**
+ * エラーメッセージを整形して出力する
+ *
+ * @param code エラーコード
+ * @param message エラーメッセージ
+ * @param cause 原因の説明（オプション）
+ * @param solution 解決策の説明（オプション）
+ * @returns 整形されたエラーメッセージ
+ */
+export declare function formatError(code: string, message: string, cause?: string, solution?: string): string;
+/**
+ * 成功メッセージを整形する
+ *
+ * @param message メッセージ
+ * @param details 詳細情報（オプション）
+ * @returns 整形されたメッセージ
+ */
+export declare function formatSuccess(message: string, details?: Record<string, string>): string;
+/**
+ * 情報メッセージを整形する
+ *
+ * @param message メッセージ
+ * @returns 整形されたメッセージ
+ */
+export declare function formatInfo(message: string): string;
+/**
+ * 警告メッセージを整形する
+ *
+ * @param message メッセージ
+ * @returns 整形されたメッセージ
+ */
+export declare function formatWarn(message: string): string;