atl-fetch 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 仙波 琉一朗 / Ryuichiro Semba
+
+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

@@ -0,0 +1,113 @@
+# atl-fetch
+
+[![CI](https://github.com/semba-yui/atl-fetch/actions/workflows/ci.yml/badge.svg)](https://github.com/semba-yui/atl-fetch/actions/workflows/ci.yml)
+[![npm version](https://badge.fury.io/js/atl-fetch.svg)](https://www.npmjs.com/package/atl-fetch)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=semba-yui_atl-fetch\&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=semba-yui_atl-fetch)
+![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/semba-yui/atl-fetch?utm_source=oss\&utm_medium=github\&utm_campaign=semba-yui%2Fatl-fetch\&labelColor=171717\&color=FF570A\&link=https%3A%2F%2Fcoderabbit.ai\&label=CodeRabbit+Reviews)
+[![DeepWiki](https://img.shields.io/badge/DeepWiki-semba--yui%2Fatl--fetch-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/semba-yui/atl-fetch)
+
+Atlassian Cloud（Jira / Confluence）から情報を取得する Node.js CLI ツール兼ライブラリです。
+
+## 主な機能
+
+- **Jira Issue 取得**: タイトル、説明、コメント、変更履歴、添付ファイル
+- **Confluence ページ取得**: タイトル、本文、バージョン履歴、添付ファイル
+- **複数出力形式**: JSON / Markdown / YAML
+- **差分表示**: バージョン間の Unified diff 形式表示
+- **添付ファイルダウンロード**: 指定ディレクトリへの保存
+
+## 動作要件
+
+- Node.js 22.0.0 以上
+- pnpm（推奨）または npm
+
+## インストール
+
+```bash
+# npm
+npm install -g atl-fetch
+
+# pnpm
+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"
+```
+
+API トークンは [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens) から取得できます。
+
+### 2. 基本的な使用方法
+
+```bash
+# Jira Issue を取得
+atl-fetch https://your-domain.atlassian.net/browse/PROJECT-123
+
+# Confluence ページを取得
+atl-fetch https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/123456/Page+Title
+
+# 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
+```
+
+## 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);
+}
+```
+
+## ライセンス
+
+[MIT](LICENSE)
+
+## 貢献
+
+[CONTRIBUTING.md](CONTRIBUTING.md) をご覧ください。

package/dist/cli/cli.d.ts

@@ -0,0 +1,61 @@
+/**
+ * CLI エントリーポイント
+ *
+ * yargs を使用した CLI インターフェースを提供する。
+ */
+/**
+ * CLI の引数の型
+ */
+export interface CliArgs {
+    /** Atlassian Cloud URL */
+    url: string;
+    /** 出力形式（json/markdown/yaml） */
+    format: 'json' | 'markdown' | 'yaml';
+    /** 添付ファイルダウンロードを有効にする */
+    download: boolean;
+    /** 保存先ディレクトリ */
+    dir?: string;
+    /** 差分のみを出力する */
+    diff: boolean;
+    /** カラー出力を有効にする */
+    color: boolean;
+}
+/**
+ * CLI 作成オプション
+ */
+export interface CliOptions {
+    /** process.exit を呼び出すかどうか（テスト時は false にする） */
+    exitProcess?: boolean;
+}
+/**
+ * CLI インスタンスを作成する
+ *
+ * yargs を使用して CLI 引数をパースするインスタンスを返す。
+ *
+ * @param options CLI 作成オプション
+ * @returns yargs インスタンス
+ */
+export declare function createCli(options?: CliOptions): import("yargs").Argv<{
+    format: "json" | "markdown" | "yaml";
+} & {
+    download: boolean;
+} & {
+    dir: string | undefined;
+} & {
+    diff: boolean;
+} & {
+    color: boolean;
+}>;
+/**
+ * CLI を実行する
+ *
+ * process.argv から引数を取得してパースし、適切な処理を実行する。
+ * メインエントリーポイントとして使用する。
+ *
+ * @example
+ * ```typescript
+ * // メインエントリーポイント
+ * await runCli();
+ * ```
+ */
+export declare function runCli(): Promise<void>;

package/dist/cli/cli.js

@@ -0,0 +1,131 @@
+/**
+ * CLI エントリーポイント
+ *
+ * yargs を使用した CLI インターフェースを提供する。
+ */
+import { createRequire } from 'node:module';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { fetchAndOutput, fetchAndSave } from '../services/fetch/fetch-service.js';
+const require = createRequire(import.meta.url);
+const packageJson = require('../../package.json');
+/**
+ * CLI バージョン（package.json から取得）
+ */
+const CLI_VERSION = packageJson.version;
+/**
+ * CLI インスタンスを作成する
+ *
+ * yargs を使用して CLI 引数をパースするインスタンスを返す。
+ *
+ * @param options CLI 作成オプション
+ * @returns yargs インスタンス
+ */
+export function createCli(options = {}) {
+    const { exitProcess = true } = options;
+    return yargs()
+        .scriptName('atl-fetch')
+        .usage('Usage: $0 <url> [options]')
+        .command('$0 <url>', 'Atlassian Cloud の URL から情報を取得する', (yargs) => {
+        return yargs.positional('url', {
+            demandOption: true,
+            describe: 'Atlassian Cloud URL (Jira Issue または Confluence ページ)',
+            type: 'string',
+        });
+    })
+        .option('format', {
+        alias: 'f',
+        choices: ['json', 'markdown', 'yaml'],
+        default: 'json',
+        describe: '出力形式',
+        type: 'string',
+    })
+        .option('download', {
+        alias: 'd',
+        default: false,
+        describe: '添付ファイルをダウンロードする',
+        type: 'boolean',
+    })
+        .option('dir', {
+        alias: 'o',
+        describe: '保存先ディレクトリ',
+        type: 'string',
+    })
+        .check((argv) => {
+        // --dir オプションは --download オプションと一緒に指定する必要がある
+        if (argv['dir'] !== undefined && !argv['download']) {
+            throw new Error('--dir オプションは --download オプションと一緒に指定してください');
+        }
+        return true;
+    })
+        .option('diff', {
+        default: false,
+        describe: '差分のみを出力する',
+        type: 'boolean',
+    })
+        .option('color', {
+        default: true,
+        describe: 'カラー出力を有効にする',
+        type: 'boolean',
+    })
+        .help('help')
+        .alias('h', 'help')
+        .version(CLI_VERSION)
+        .alias('V', 'version')
+        .strict()
+        .exitProcess(exitProcess)
+        .demandCommand(1, 'URL を指定してください')
+        .fail((msg, err) => {
+        if (err) {
+            throw err;
+        }
+        throw new Error(msg);
+    })
+        .wrap(null);
+}
+/**
+ * CLI を実行する
+ *
+ * process.argv から引数を取得してパースし、適切な処理を実行する。
+ * メインエントリーポイントとして使用する。
+ *
+ * @example
+ * ```typescript
+ * // メインエントリーポイント
+ * await runCli();
+ * ```
+ */
+export async function runCli() {
+    const cli = createCli();
+    const argv = await cli.parse(hideBin(process.argv));
+    const url = argv['url'];
+    const format = argv['format'];
+    const download = argv['download'];
+    const dir = argv['dir'];
+    const colorEnabled = argv['color'];
+    // ダウンロードモード
+    if (download) {
+        const baseDir = dir ?? process.cwd();
+        const result = await fetchAndSave(url, {
+            baseDir,
+            cliVersion: CLI_VERSION,
+            sourceUrl: url,
+        });
+        if (result.isErr()) {
+            console.error(`エラー: ${result.error.message}`);
+            process.exit(1);
+        }
+        console.log(`保存完了: ${result.value.directory}`);
+        return;
+    }
+    // 通常モード（標準出力）
+    const result = await fetchAndOutput(url, {
+        colorEnabled,
+        format,
+    });
+    if (result.isErr()) {
+        console.error(`エラー: ${result.error.message}`);
+        process.exit(1);
+    }
+    console.log(result.value);
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * CLI モジュールのバレルエクスポート
+ */
+export type { CliArgs, CliOptions } from './cli.js';
+export { createCli, runCli } from './cli.js';

package/dist/cli/index.js

@@ -0,0 +1,4 @@
+/**
+ * CLI モジュールのバレルエクスポート
+ */
+export { createCli, runCli } from './cli.js';

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * atl-fetch - Atlassian Cloud からコンテンツを取得する CLI ツール
+ *
+ * CLI エントリーポイント。
+ * このファイルは `npx atl-fetch` または `atl-fetch` コマンドとして実行される。
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * atl-fetch - Atlassian Cloud からコンテンツを取得する CLI ツール
+ *
+ * CLI エントリーポイント。
+ * このファイルは `npx atl-fetch` または `atl-fetch` コマンドとして実行される。
+ */
+import { runCli } from './cli/index.js';
+// CLI を実行
+runCli().catch((error) => {
+    console.error('エラーが発生しました:', error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/ports/file/file-port.d.ts

@@ -0,0 +1,89 @@
+import type { Readable } from 'node:stream';
+import { type Result } from 'neverthrow';
+import type { FileError } from '../../types/file.js';
+/**
+ * ファイルにテキストコンテンツを書き込む
+ *
+ * UTF-8 エンコーディングで指定されたパスにテキストを書き込む。
+ * 親ディレクトリが存在しない場合はエラーを返す。
+ *
+ * @param path - 書き込み先のファイルパス
+ * @param content - 書き込むテキストコンテンツ
+ * @returns 成功時は Ok(void)、失敗時は Err(FileError)
+ *
+ * @example
+ * ```typescript
+ * const result = await writeFileContent('/path/to/file.txt', 'Hello, World!');
+ * if (result.isOk()) {
+ *   console.log('ファイルを書き込みました');
+ * }
+ * ```
+ */
+export declare function writeFileContent(path: string, content: string): Promise<Result<void, FileError>>;
+/**
+ * ストリームからファイルに書き込む
+ *
+ * Node.js の Readable ストリームを受け取り、指定されたパスにファイルとして書き込む。
+ * 大きなファイルのダウンロードに適している。
+ *
+ * @param path - 書き込み先のファイルパス
+ * @param stream - 読み取り元のストリーム
+ * @returns 成功時は Ok(void)、失敗時は Err(FileError)
+ *
+ * @example
+ * ```typescript
+ * import { Readable } from 'node:stream';
+ *
+ * const stream = Readable.from(['chunk1', 'chunk2']);
+ * const result = await writeStream('/path/to/file.bin', stream);
+ * if (result.isOk()) {
+ *   console.log('ストリームを書き込みました');
+ * }
+ * ```
+ */
+export declare function writeStream(path: string, stream: Readable): Promise<Result<void, FileError>>;
+/**
+ * ディレクトリを再帰的に作成する
+ *
+ * 指定されたパスにディレクトリを作成する。中間ディレクトリも自動的に作成される。
+ * 既にディレクトリが存在する場合は何もせずに成功を返す。
+ *
+ * @param path - 作成するディレクトリパス
+ * @returns 成功時は Ok(void)、失敗時は Err(FileError)
+ *
+ * @example
+ * ```typescript
+ * const result = await ensureDir('/path/to/nested/directory');
+ * if (result.isOk()) {
+ *   console.log('ディレクトリを作成しました');
+ * }
+ * ```
+ */
+export declare function ensureDir(path: string): Promise<Result<void, FileError>>;
+/**
+ * ファイルまたはディレクトリの存在を確認する
+ *
+ * 指定されたパスにファイルまたはディレクトリが存在するかを確認する。
+ * アクセス権限がない場合も false を返す。
+ *
+ * @param path - 確認するパス
+ * @returns ファイルまたはディレクトリが存在する場合は true、そうでない場合は false
+ *
+ * @example
+ * ```typescript
+ * if (await exists('/path/to/file.txt')) {
+ *   console.log('ファイルが存在します');
+ * }
+ * ```
+ */
+export declare function exists(path: string): Promise<boolean>;
+/**
+ * エラーを FileError にマッピングする
+ *
+ * @param path - 操作対象のパス
+ * @param error - キャッチしたエラー
+ * @returns 対応する FileError
+ *
+ * @internal テスト用に export
+ */
+export declare function mapErrorToFileError(path: string, error: unknown): FileError;

package/dist/ports/file/file-port.js

@@ -0,0 +1,155 @@
+import { createWriteStream } from 'node:fs';
+import { access, mkdir, writeFile } from 'node:fs/promises';
+import { pipeline } from 'node:stream/promises';
+import { err, ok } from 'neverthrow';
+/**
+ * ファイルにテキストコンテンツを書き込む
+ *
+ * UTF-8 エンコーディングで指定されたパスにテキストを書き込む。
+ * 親ディレクトリが存在しない場合はエラーを返す。
+ *
+ * @param path - 書き込み先のファイルパス
+ * @param content - 書き込むテキストコンテンツ
+ * @returns 成功時は Ok(void)、失敗時は Err(FileError)
+ *
+ * @example
+ * ```typescript
+ * const result = await writeFileContent('/path/to/file.txt', 'Hello, World!');
+ * if (result.isOk()) {
+ *   console.log('ファイルを書き込みました');
+ * }
+ * ```
+ */
+export async function writeFileContent(path, content) {
+    try {
+        await writeFile(path, content, 'utf-8');
+        return ok(undefined);
+    }
+    catch (error) {
+        return err(mapErrorToFileError(path, error));
+    }
+}
+/**
+ * ストリームからファイルに書き込む
+ *
+ * Node.js の Readable ストリームを受け取り、指定されたパスにファイルとして書き込む。
+ * 大きなファイルのダウンロードに適している。
+ *
+ * @param path - 書き込み先のファイルパス
+ * @param stream - 読み取り元のストリーム
+ * @returns 成功時は Ok(void)、失敗時は Err(FileError)
+ *
+ * @example
+ * ```typescript
+ * import { Readable } from 'node:stream';
+ *
+ * const stream = Readable.from(['chunk1', 'chunk2']);
+ * const result = await writeStream('/path/to/file.bin', stream);
+ * if (result.isOk()) {
+ *   console.log('ストリームを書き込みました');
+ * }
+ * ```
+ */
+export async function writeStream(path, stream) {
+    try {
+        const writeStream = createWriteStream(path);
+        await pipeline(stream, writeStream);
+        return ok(undefined);
+    }
+    catch (error) {
+        return err(mapErrorToFileError(path, error));
+    }
+}
+/**
+ * ディレクトリを再帰的に作成する
+ *
+ * 指定されたパスにディレクトリを作成する。中間ディレクトリも自動的に作成される。
+ * 既にディレクトリが存在する場合は何もせずに成功を返す。
+ *
+ * @param path - 作成するディレクトリパス
+ * @returns 成功時は Ok(void)、失敗時は Err(FileError)
+ *
+ * @example
+ * ```typescript
+ * const result = await ensureDir('/path/to/nested/directory');
+ * if (result.isOk()) {
+ *   console.log('ディレクトリを作成しました');
+ * }
+ * ```
+ */
+export async function ensureDir(path) {
+    try {
+        await mkdir(path, { recursive: true });
+        return ok(undefined);
+    }
+    catch (error) {
+        return err(mapErrorToFileError(path, error));
+    }
+}
+/**
+ * ファイルまたはディレクトリの存在を確認する
+ *
+ * 指定されたパスにファイルまたはディレクトリが存在するかを確認する。
+ * アクセス権限がない場合も false を返す。
+ *
+ * @param path - 確認するパス
+ * @returns ファイルまたはディレクトリが存在する場合は true、そうでない場合は false
+ *
+ * @example
+ * ```typescript
+ * if (await exists('/path/to/file.txt')) {
+ *   console.log('ファイルが存在します');
+ * }
+ * ```
+ */
+export async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * エラーを FileError にマッピングする
+ *
+ * @param path - 操作対象のパス
+ * @param error - キャッチしたエラー
+ * @returns 対応する FileError
+ *
+ * @internal テスト用に export
+ */
+export function mapErrorToFileError(path, error) {
+    if (!(error instanceof Error)) {
+        return {
+            kind: 'WRITE_FAILED',
+            message: '不明なエラーが発生しました',
+            path,
+        };
+    }
+    const nodeError = error;
+    const code = nodeError.code;
+    // パーミッションエラー
+    if (code === 'EACCES' || code === 'EPERM') {
+        return {
+            kind: 'PERMISSION_DENIED',
+            message: `ファイルへのアクセス権限がありません: ${error.message}`,
+            path,
+        };
+    }
+    // ディスク容量不足
+    if (code === 'ENOSPC') {
+        return {
+            kind: 'DISK_FULL',
+            message: `ディスク容量が不足しています: ${error.message}`,
+            path,
+        };
+    }
+    // その他のエラー（ディレクトリが存在しない、等）
+    return {
+        kind: 'WRITE_FAILED',
+        message: `ファイル書き込みに失敗しました: ${error.message}`,
+        path,
+    };
+}

package/dist/ports/file/index.d.ts

@@ -0,0 +1 @@
+export { ensureDir, exists, writeFileContent, writeStream } from './file-port.js';

package/dist/ports/file/index.js

@@ -0,0 +1 @@
+export { ensureDir, exists, writeFileContent, writeStream } from './file-port.js';