atl-fetch 1.0.0 → 1.1.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;

package/dist/cli/spinner.js

@@ -0,0 +1,247 @@
+/**
+ * CLI スピナー・進捗表示ユーティリティ
+ *
+ * ora と picocolors を使用した統一的な進捗表示を提供する。
+ */
+import ora, {} from 'ora';
+import pc from 'picocolors';
+/**
+ * 事前定義されたスピナーステップ
+ */
+export const SPINNER_STEPS = {
+    AUTH_CHECK: {
+        name: 'auth_check',
+        successText: '認証情報を確認しました',
+        text: '認証情報を確認中...',
+    },
+    DOWNLOAD_ATTACHMENTS: {
+        name: 'download_attachments',
+        successText: '添付ファイルをダウンロードしました',
+        text: '添付ファイルをダウンロード中...',
+    },
+    FETCH_CONFLUENCE: {
+        name: 'fetch_confluence',
+        successText: 'Confluence ページを取得しました',
+        text: 'Confluence ページを取得中...',
+    },
+    FETCH_DATA: {
+        name: 'fetch_data',
+        successText: 'データを取得しました',
+        text: 'データを取得中...',
+    },
+    FETCH_JIRA: {
+        name: 'fetch_jira',
+        successText: 'Jira Issue を取得しました',
+        text: 'Jira Issue を取得中...',
+    },
+    FORMAT_OUTPUT: {
+        name: 'format_output',
+        successText: '出力を整形しました',
+        text: '出力を整形中...',
+    },
+    SAVE_FILES: {
+        name: 'save_files',
+        successText: 'ファイルを保存しました',
+        text: 'ファイルを保存中...',
+    },
+    URL_PARSE: {
+        name: 'url_parse',
+        successText: 'URLを解析しました',
+        text: 'URLを解析中...',
+    },
+};
+/**
+ * CLI 出力のカラーヘルパー
+ */
+export const colors = {
+    /** 太字 */
+    bold: (text) => pc.bold(text),
+    /** シアン（ファイルパスなど） */
+    cyan: (text) => pc.cyan(text),
+    /** 薄いテキスト（グレー） */
+    dim: (text) => pc.dim(text),
+    /** エラーメッセージ（赤） */
+    error: (text) => pc.red(text),
+    /** 情報メッセージ（青） */
+    info: (text) => pc.blue(text),
+    /** マゼンタ（URL など） */
+    magenta: (text) => pc.magenta(text),
+    /** 成功メッセージ（緑） */
+    success: (text) => pc.green(text),
+    /** 警告メッセージ（黄） */
+    warn: (text) => pc.yellow(text),
+};
+/**
+ * CLI スピナー管理クラス
+ *
+ * 処理の進捗状況をユーザーに表示するためのスピナーを管理する。
+ *
+ * @example
+ * ```typescript
+ * const spinner = new CliSpinner();
+ * spinner.start('データを取得中...');
+ * // ... 処理 ...
+ * spinner.succeed('データを取得しました');
+ * ```
+ */
+export class CliSpinner {
+    spinner = null;
+    enabled;
+    /**
+     * CliSpinner インスタンスを作成する
+     *
+     * @param enabled スピナーを有効にするかどうか（CI環境などでは無効にする）
+     */
+    constructor(enabled = true) {
+        // CI環境やテスト環境ではスピナーを無効化
+        this.enabled = enabled && !process.env['CI'] && process.stdout.isTTY === true;
+    }
+    /**
+     * スピナーを開始する
+     *
+     * @param text 表示するテキスト
+     */
+    start(text) {
+        if (!this.enabled) {
+            return;
+        }
+        this.spinner = ora({
+            spinner: 'dots',
+            text,
+        }).start();
+    }
+    /**
+     * スピナーのテキストを更新する
+     *
+     * @param text 新しいテキスト
+     */
+    update(text) {
+        if (this.spinner) {
+            this.spinner.text = text;
+        }
+    }
+    /**
+     * スピナーを成功状態で終了する
+     *
+     * @param text 成功時に表示するテキスト
+     */
+    succeed(text) {
+        if (this.spinner) {
+            this.spinner.succeed(text);
+            this.spinner = null;
+        }
+    }
+    /**
+     * スピナーを失敗状態で終了する
+     *
+     * @param text 失敗時に表示するテキスト
+     */
+    fail(text) {
+        if (this.spinner) {
+            this.spinner.fail(text);
+            this.spinner = null;
+        }
+    }
+    /**
+     * スピナーを警告状態で終了する
+     *
+     * @param text 警告時に表示するテキスト
+     */
+    warn(text) {
+        if (this.spinner) {
+            this.spinner.warn(text);
+            this.spinner = null;
+        }
+    }
+    /**
+     * スピナーを情報状態で終了する
+     *
+     * @param text 情報として表示するテキスト
+     */
+    info(text) {
+        if (this.spinner) {
+            this.spinner.info(text);
+            this.spinner = null;
+        }
+    }
+    /**
+     * スピナーを停止する（状態なし）
+     */
+    stop() {
+        if (this.spinner) {
+            this.spinner.stop();
+            this.spinner = null;
+        }
+    }
+    /**
+     * 事前定義されたステップでスピナーを開始する
+     *
+     * @param step スピナーステップ定義
+     */
+    startStep(step) {
+        this.start(step.text);
+    }
+    /**
+     * 事前定義されたステップを成功状態で終了する
+     *
+     * @param step スピナーステップ定義
+     */
+    succeedStep(step) {
+        this.succeed(step.successText ?? step.text);
+    }
+}
+/**
+ * エラーメッセージを整形して出力する
+ *
+ * @param code エラーコード
+ * @param message エラーメッセージ
+ * @param cause 原因の説明（オプション）
+ * @param solution 解決策の説明（オプション）
+ * @returns 整形されたエラーメッセージ
+ */
+export function formatError(code, message, cause, solution) {
+    const lines = [];
+    lines.push(colors.error(`${colors.bold(code)}: ${message}`));
+    if (cause) {
+        lines.push(colors.dim(`  原因: ${cause}`));
+    }
+    if (solution) {
+        lines.push(colors.info(`  解決策: ${solution}`));
+    }
+    return lines.join('\n');
+}
+/**
+ * 成功メッセージを整形する
+ *
+ * @param message メッセージ
+ * @param details 詳細情報（オプション）
+ * @returns 整形されたメッセージ
+ */
+export function formatSuccess(message, details) {
+    const lines = [];
+    lines.push(colors.success(`✓ ${message}`));
+    if (details) {
+        for (const [key, value] of Object.entries(details)) {
+            lines.push(colors.dim(`  ${key}: ${colors.cyan(value)}`));
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * 情報メッセージを整形する
+ *
+ * @param message メッセージ
+ * @returns 整形されたメッセージ
+ */
+export function formatInfo(message) {
+    return colors.info(`ℹ ${message}`);
+}
+/**
+ * 警告メッセージを整形する
+ *
+ * @param message メッセージ
+ * @returns 整形されたメッセージ
+ */
+export function formatWarn(message) {
+    return colors.warn(`⚠ ${message}`);
+}

package/package.json

@@ -12,6 +12,8 @@
     "got": "14.6.6",
     "jsdom": "27.4.0",
     "neverthrow": "8.2.0",
+    "ora": "^9.0.0",
+    "picocolors": "^1.1.1",
     "turndown": "7.2.2",
     "turndown-plugin-gfm": "1.0.2",
     "yaml": "2.8.2",
@@ -80,7 +82,7 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",

package/dist/types/result.d.ts

@@ -1,104 +0,0 @@
-/**
- * Result 型 - 成功または失敗を表現する discriminated union
- *
- * @example
- * ```typescript
- * function divide(a: number, b: number): Result<number, DivisionError> {
- *   if (b === 0) {
- *     return err({ kind: 'DIVISION_BY_ZERO', message: 'Cannot divide by zero' });
- *   }
- *   return ok(a / b);
- * }
- * ```
- */
-/**
- * 成功を表す型
- */
-export interface Ok<T> {
-    readonly success: true;
-    readonly value: T;
-}
-/**
- * 失敗を表す型
- */
-export interface Err<E> {
-    readonly success: false;
-    readonly error: E;
-}
-/**
- * Result 型 - 成功（Ok）または失敗（Err）のどちらかを表す
- */
-export type Result<T, E> = Ok<T> | Err<E>;
-/**
- * 成功 Result を作成する
- *
- * @param value - 成功値
- * @returns 成功 Result
- */
-export declare function ok<T>(value: T): Ok<T>;
-/**
- * 失敗 Result を作成する
- *
- * @param error - エラー値
- * @returns 失敗 Result
- */
-export declare function err<E>(error: E): Err<E>;
-/**
- * Result が成功かどうかを判定する型ガード
- *
- * @param result - 判定対象の Result
- * @returns 成功の場合 true
- */
-export declare function isOk<T, E>(result: Result<T, E>): result is Ok<T>;
-/**
- * Result が失敗かどうかを判定する型ガード
- *
- * @param result - 判定対象の Result
- * @returns 失敗の場合 true
- */
-export declare function isErr<T, E>(result: Result<T, E>): result is Err<E>;
-/**
- * 成功 Result から値を取り出す
- * 失敗 Result の場合はエラーをスローする
- *
- * @param result - 対象の Result
- * @returns 成功値
- * @throws 失敗 Result の場合
- */
-export declare function unwrap<T, E>(result: Result<T, E>): T;
-/**
- * 失敗 Result からエラー値を取り出す
- * 成功 Result の場合はエラーをスローする
- *
- * @param result - 対象の Result
- * @returns エラー値
- * @throws 成功 Result の場合
- */
-export declare function unwrapErr<T, E>(result: Result<T, E>): E;
-/**
- * 成功 Result から値を取り出す
- * 失敗 Result の場合はデフォルト値を返す
- *
- * @param result - 対象の Result
- * @param defaultValue - 失敗時のデフォルト値
- * @returns 成功値またはデフォルト値
- */
-export declare function unwrapOr<T, E>(result: Result<T, E>, defaultValue: T): T;
-/**
- * 成功 Result の値を変換する
- * 失敗 Result の場合はそのまま返す
- *
- * @param result - 対象の Result
- * @param fn - 変換関数
- * @returns 変換された Result
- */
-export declare function mapResult<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;
-/**
- * 失敗 Result のエラー値を変換する
- * 成功 Result の場合はそのまま返す
- *
- * @param result - 対象の Result
- * @param fn - 変換関数
- * @returns 変換された Result
- */
-export declare function mapErr<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;

package/dist/types/result.js

@@ -1,119 +0,0 @@
-/**
- * Result 型 - 成功または失敗を表現する discriminated union
- *
- * @example
- * ```typescript
- * function divide(a: number, b: number): Result<number, DivisionError> {
- *   if (b === 0) {
- *     return err({ kind: 'DIVISION_BY_ZERO', message: 'Cannot divide by zero' });
- *   }
- *   return ok(a / b);
- * }
- * ```
- */
-/**
- * 成功 Result を作成する
- *
- * @param value - 成功値
- * @returns 成功 Result
- */
-export function ok(value) {
-    return { success: true, value };
-}
-/**
- * 失敗 Result を作成する
- *
- * @param error - エラー値
- * @returns 失敗 Result
- */
-export function err(error) {
-    return { error, success: false };
-}
-/**
- * Result が成功かどうかを判定する型ガード
- *
- * @param result - 判定対象の Result
- * @returns 成功の場合 true
- */
-export function isOk(result) {
-    return result.success;
-}
-/**
- * Result が失敗かどうかを判定する型ガード
- *
- * @param result - 判定対象の Result
- * @returns 失敗の場合 true
- */
-export function isErr(result) {
-    return !result.success;
-}
-/**
- * 成功 Result から値を取り出す
- * 失敗 Result の場合はエラーをスローする
- *
- * @param result - 対象の Result
- * @returns 成功値
- * @throws 失敗 Result の場合
- */
-export function unwrap(result) {
-    if (isOk(result)) {
-        return result.value;
-    }
-    throw new Error(`Attempted to unwrap an Err value: ${String(result.error)}`);
-}
-/**
- * 失敗 Result からエラー値を取り出す
- * 成功 Result の場合はエラーをスローする
- *
- * @param result - 対象の Result
- * @returns エラー値
- * @throws 成功 Result の場合
- */
-export function unwrapErr(result) {
-    if (isErr(result)) {
-        return result.error;
-    }
-    throw new Error('Attempted to unwrapErr an Ok value');
-}
-/**
- * 成功 Result から値を取り出す
- * 失敗 Result の場合はデフォルト値を返す
- *
- * @param result - 対象の Result
- * @param defaultValue - 失敗時のデフォルト値
- * @returns 成功値またはデフォルト値
- */
-export function unwrapOr(result, defaultValue) {
-    if (isOk(result)) {
-        return result.value;
-    }
-    return defaultValue;
-}
-/**
- * 成功 Result の値を変換する
- * 失敗 Result の場合はそのまま返す
- *
- * @param result - 対象の Result
- * @param fn - 変換関数
- * @returns 変換された Result
- */
-export function mapResult(result, fn) {
-    if (isOk(result)) {
-        return ok(fn(result.value));
-    }
-    return result;
-}
-/**
- * 失敗 Result のエラー値を変換する
- * 成功 Result の場合はそのまま返す
- *
- * @param result - 対象の Result
- * @param fn - 変換関数
- * @returns 変換された Result
- */
-export function mapErr(result, fn) {
-    if (isErr(result)) {
-        return err(fn(result.error));
-    }
-    return result;
-}