atl-fetch 1.0.0

package/dist/services/url-parser/index.d.ts

@@ -0,0 +1 @@
+export { parseUrl } from './url-parser.js';

package/dist/services/url-parser/index.js

@@ -0,0 +1 @@
+export { parseUrl } from './url-parser.js';

package/dist/services/url-parser/url-parser.d.ts

@@ -0,0 +1,43 @@
+import { type Result } from 'neverthrow';
+import type { UrlParseError, UrlParseResult } from '../../types/url-parser.js';
+/**
+ * Atlassian Cloud の URL を解析し、リソース情報を抽出する
+ *
+ * サポートする URL 形式:
+ * - Jira Issue: `https://{org}.atlassian.net/browse/{ISSUE-KEY}`
+ * - Jira Board: `https://{org}.atlassian.net/jira/software/projects/{PROJECT}/boards/{id}?selectedIssue={ISSUE-KEY}`
+ * - Confluence Page: `https://{org}.atlassian.net/wiki/spaces/{SPACE}/pages/{PAGE-ID}/{TITLE}`
+ *
+ * @param url - 解析対象の Atlassian Cloud URL（完全な URL 文字列）
+ * @returns 成功時は {@link UrlParseResult} を含む Ok、失敗時は {@link UrlParseError} を含む Err
+ *
+ * @example
+ * ```typescript
+ * // 成功例: Jira Issue URL
+ * const result = parseUrl('https://mycompany.atlassian.net/browse/PROJ-123');
+ * if (result.isOk()) {
+ *   console.log(result.value);
+ *   // { type: 'jira', organization: 'mycompany', resourceId: 'PROJ-123', projectKey: 'PROJ' }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // 成功例: Confluence ページ URL
+ * const result = parseUrl('https://mycompany.atlassian.net/wiki/spaces/DOCS/pages/123456789/Title');
+ * if (result.isOk()) {
+ *   console.log(result.value);
+ *   // { type: 'confluence', organization: 'mycompany', resourceId: '123456789', spaceKey: 'DOCS' }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // 失敗例: Atlassian Cloud 以外の URL
+ * const result = parseUrl('https://example.com/browse/PROJ-123');
+ * if (result.isErr()) {
+ *   console.log(result.error.kind); // 'UNSUPPORTED_HOST'
+ * }
+ * ```
+ */
+export declare function parseUrl(url: string): Result<UrlParseResult, UrlParseError>;

package/dist/services/url-parser/url-parser.js

@@ -0,0 +1,283 @@
+import { err, ok } from 'neverthrow';
+/**
+ * Atlassian Cloud のホスト名パターン
+ *
+ * キャプチャグループ:
+ * - グループ1: 組織名（サブドメイン部分）
+ *
+ * @example
+ * // マッチする例
+ * 'mycompany.atlassian.net' // グループ1: 'mycompany'
+ * 'my-company-name.atlassian.net' // グループ1: 'my-company-name'
+ *
+ * @example
+ * // マッチしない例
+ * 'jira.mycompany.com' // Atlassian Cloud ではない
+ * 'atlassian.net' // サブドメインがない
+ */
+const ATLASSIAN_CLOUD_HOST_PATTERN = /^([a-z0-9-]+)\.atlassian\.net$/i;
+/**
+ * Jira Issue キーのパターン
+ *
+ * Issue キーは `{プロジェクトキー}-{番号}` の形式。
+ * プロジェクトキーは英大文字で始まり、英大文字または数字が続く。
+ *
+ * キャプチャグループ:
+ * - グループ1: プロジェクトキー
+ * - グループ2: Issue 番号
+ *
+ * @example
+ * // マッチする例
+ * 'PROJ-123' // グループ1: 'PROJ', グループ2: '123'
+ * 'ABC-1' // グループ1: 'ABC', グループ2: '1'
+ * 'A1B2-999' // グループ1: 'A1B2', グループ2: '999'
+ *
+ * @example
+ * // マッチしない例
+ * 'proj-123' // 小文字（ただし i フラグにより実際はマッチする）
+ * 'PROJ' // 番号がない
+ * '123-PROJ' // 順序が逆
+ */
+const JIRA_ISSUE_KEY_PATTERN = /^([A-Z][A-Z0-9]*)-(\d+)$/i;
+/**
+ * Confluence ページ URL のパスパターン
+ *
+ * `/wiki/spaces/{spaceKey}/pages/{pageId}` または
+ * `/wiki/spaces/{spaceKey}/pages/{pageId}/{title}` 形式をマッチ。
+ *
+ * キャプチャグループ:
+ * - グループ1: スペースキー
+ * - グループ2: ページ ID（任意の文字列、後で数字かどうか検証）
+ *
+ * @example
+ * // マッチする例
+ * '/wiki/spaces/DOCS/pages/123456789' // グループ1: 'DOCS', グループ2: '123456789'
+ * '/wiki/spaces/TEAM/pages/987654321/Page+Title' // グループ1: 'TEAM', グループ2: '987654321'
+ *
+ * @example
+ * // マッチしない例
+ * '/wiki/display/DOCS/Page' // 古い形式
+ * '/wiki/spaces/DOCS/overview' // ページではない
+ */
+const CONFLUENCE_PAGE_PATH_PATTERN = /^\/wiki\/spaces\/([^/]+)\/pages\/([^/]+)(?:\/.*)?$/;
+/**
+ * ページ ID が有効な数字形式かどうかを検証するパターン
+ */
+const PAGE_ID_PATTERN = /^\d+$/;
+/**
+ * Atlassian Cloud の URL を解析し、リソース情報を抽出する
+ *
+ * サポートする URL 形式:
+ * - Jira Issue: `https://{org}.atlassian.net/browse/{ISSUE-KEY}`
+ * - Jira Board: `https://{org}.atlassian.net/jira/software/projects/{PROJECT}/boards/{id}?selectedIssue={ISSUE-KEY}`
+ * - Confluence Page: `https://{org}.atlassian.net/wiki/spaces/{SPACE}/pages/{PAGE-ID}/{TITLE}`
+ *
+ * @param url - 解析対象の Atlassian Cloud URL（完全な URL 文字列）
+ * @returns 成功時は {@link UrlParseResult} を含む Ok、失敗時は {@link UrlParseError} を含む Err
+ *
+ * @example
+ * ```typescript
+ * // 成功例: Jira Issue URL
+ * const result = parseUrl('https://mycompany.atlassian.net/browse/PROJ-123');
+ * if (result.isOk()) {
+ *   console.log(result.value);
+ *   // { type: 'jira', organization: 'mycompany', resourceId: 'PROJ-123', projectKey: 'PROJ' }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // 成功例: Confluence ページ URL
+ * const result = parseUrl('https://mycompany.atlassian.net/wiki/spaces/DOCS/pages/123456789/Title');
+ * if (result.isOk()) {
+ *   console.log(result.value);
+ *   // { type: 'confluence', organization: 'mycompany', resourceId: '123456789', spaceKey: 'DOCS' }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // 失敗例: Atlassian Cloud 以外の URL
+ * const result = parseUrl('https://example.com/browse/PROJ-123');
+ * if (result.isErr()) {
+ *   console.log(result.error.kind); // 'UNSUPPORTED_HOST'
+ * }
+ * ```
+ */
+export function parseUrl(url) {
+    // 空文字列チェック
+    if (url.trim() === '') {
+        return err({
+            kind: 'INVALID_FORMAT',
+            message: 'URL が空です。有効な Atlassian Cloud URL を指定してください。',
+        });
+    }
+    // URL のパース
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(url);
+    }
+    catch {
+        return err({
+            kind: 'INVALID_FORMAT',
+            message: `無効な URL 形式です: ${url}`,
+        });
+    }
+    // Atlassian Cloud ホストの検証
+    const hostMatch = ATLASSIAN_CLOUD_HOST_PATTERN.exec(parsedUrl.hostname);
+    if (!hostMatch) {
+        return err({
+            kind: 'UNSUPPORTED_HOST',
+            message: `Atlassian Cloud 以外の URL はサポートされていません: ${parsedUrl.hostname}`,
+        });
+    }
+    const organization = hostMatch[1];
+    if (organization === undefined) {
+        return err({
+            kind: 'INVALID_FORMAT',
+            message: '組織名を抽出できませんでした。',
+        });
+    }
+    // Confluence URL のパース（/wiki/ で始まる場合）
+    if (parsedUrl.pathname.startsWith('/wiki/')) {
+        return parseConfluenceUrl(parsedUrl, organization);
+    }
+    // Jira Issue URL のパース
+    return parseJiraUrl(parsedUrl, organization);
+}
+/**
+ * Jira URL を解析し、Issue 情報を抽出する
+ *
+ * サポートする URL パターン:
+ * 1. `/browse/{ISSUE-KEY}` - 標準的な Issue ページ URL
+ * 2. `/jira/software/projects/{PROJECT}/boards/{id}?selectedIssue={ISSUE-KEY}` - ボード上で選択された Issue
+ *
+ * @param parsedUrl - パース済みの URL オブジェクト
+ * @param organization - Atlassian Cloud の組織名（サブドメイン）
+ * @returns 成功時は {@link UrlParseResult} を含む Ok、失敗時は {@link UrlParseError} を含む Err
+ *
+ * @internal この関数は内部実装であり、外部から直接呼び出すべきではありません
+ */
+function parseJiraUrl(parsedUrl, organization) {
+    const pathname = parsedUrl.pathname;
+    // /browse/{key} 形式
+    if (pathname.startsWith('/browse/')) {
+        const issueKey = pathname.slice('/browse/'.length);
+        return validateAndCreateJiraResult(issueKey, organization);
+    }
+    // /jira/software/projects/.../boards/...?selectedIssue={key} 形式
+    if (pathname.includes('/jira/software/projects/')) {
+        const selectedIssue = parsedUrl.searchParams.get('selectedIssue');
+        if (!selectedIssue) {
+            return err({
+                kind: 'MISSING_RESOURCE_ID',
+                message: 'selectedIssue パラメータが見つかりません。',
+            });
+        }
+        return validateAndCreateJiraResult(selectedIssue, organization);
+    }
+    return err({
+        kind: 'MISSING_RESOURCE_ID',
+        message: 'サポートされている Jira URL 形式ではありません。',
+    });
+}
+/**
+ * Jira Issue キーを検証し、パース結果オブジェクトを生成する
+ *
+ * Issue キーの形式 `{PROJECT}-{NUMBER}` を検証し、
+ * 有効な場合は {@link UrlParseResult} を生成して返す。
+ *
+ * @param issueKey - 検証対象の Issue キー（例: 'PROJ-123'）
+ * @param organization - Atlassian Cloud の組織名（サブドメイン）
+ * @returns 成功時は {@link UrlParseResult} を含む Ok、失敗時は {@link UrlParseError} を含む Err
+ *
+ * @remarks
+ * エラーケース:
+ * - 空文字列の場合: `MISSING_RESOURCE_ID`
+ * - 形式が不正な場合: `INVALID_FORMAT`
+ *
+ * @internal この関数は内部実装であり、外部から直接呼び出すべきではありません
+ */
+function validateAndCreateJiraResult(issueKey, organization) {
+    // 空チェック
+    if (issueKey.trim() === '') {
+        return err({
+            kind: 'MISSING_RESOURCE_ID',
+            message: 'Issue キーが指定されていません。',
+        });
+    }
+    // Issue キー形式の検証
+    const keyMatch = JIRA_ISSUE_KEY_PATTERN.exec(issueKey);
+    if (!keyMatch) {
+        return err({
+            kind: 'INVALID_FORMAT',
+            message: `無効な Issue キー形式です: ${issueKey}。形式は PROJECT-123 のようにしてください。`,
+        });
+    }
+    const projectKey = keyMatch[1];
+    if (projectKey === undefined) {
+        return err({
+            kind: 'INVALID_FORMAT',
+            message: 'プロジェクトキーを抽出できませんでした。',
+        });
+    }
+    return ok({
+        organization,
+        projectKey,
+        resourceId: issueKey,
+        type: 'jira',
+    });
+}
+/**
+ * Confluence URL を解析し、ページ情報を抽出する
+ *
+ * サポートする URL パターン:
+ * 1. `/wiki/spaces/{SPACE}/pages/{PAGE-ID}` - タイトルなし
+ * 2. `/wiki/spaces/{SPACE}/pages/{PAGE-ID}/{TITLE}` - タイトルあり
+ *
+ * @param parsedUrl - パース済みの URL オブジェクト
+ * @param organization - Atlassian Cloud の組織名（サブドメイン）
+ * @returns 成功時は {@link UrlParseResult} を含む Ok、失敗時は {@link UrlParseError} を含む Err
+ *
+ * @internal この関数は内部実装であり、外部から直接呼び出すべきではありません
+ */
+function parseConfluenceUrl(parsedUrl, organization) {
+    const pathname = parsedUrl.pathname;
+    // /wiki/spaces/{space}/pages/{id} 形式
+    const pageMatch = CONFLUENCE_PAGE_PATH_PATTERN.exec(pathname);
+    if (!pageMatch) {
+        return err({
+            kind: 'MISSING_RESOURCE_ID',
+            message: 'サポートされている Confluence URL 形式ではありません。/wiki/spaces/{SPACE}/pages/{PAGE-ID} 形式を使用してください。',
+        });
+    }
+    const spaceKey = pageMatch[1];
+    const pageId = pageMatch[2];
+    // スペースキーの検証
+    if (spaceKey === undefined || spaceKey.trim() === '') {
+        return err({
+            kind: 'MISSING_RESOURCE_ID',
+            message: 'スペースキーが指定されていません。',
+        });
+    }
+    // ページ ID の検証
+    if (pageId === undefined || pageId.trim() === '') {
+        return err({
+            kind: 'MISSING_RESOURCE_ID',
+            message: 'ページ ID が指定されていません。',
+        });
+    }
+    // ページ ID が数字形式かどうかを検証
+    if (!PAGE_ID_PATTERN.test(pageId)) {
+        return err({
+            kind: 'INVALID_FORMAT',
+            message: `無効なページ ID 形式です: ${pageId}。ページ ID は数字のみで構成される必要があります。`,
+        });
+    }
+    return ok({
+        organization,
+        resourceId: pageId,
+        spaceKey,
+        type: 'confluence',
+    });
+}

package/dist/types/auth.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 認証情報の型
+ */
+export interface Credentials {
+    /** Atlassian アカウントのメールアドレス */
+    readonly email: string;
+    /** Atlassian API トークン */
+    readonly apiToken: string;
+}
+/**
+ * 認証エラーの型
+ */
+export type AuthError = {
+    kind: 'MISSING_EMAIL';
+    message: string;
+} | {
+    kind: 'MISSING_TOKEN';
+    message: string;
+} | {
+    kind: 'INVALID_EMAIL';
+    message: string;
+} | {
+    kind: 'INVALID_CREDENTIALS';
+    message: string;
+};

package/dist/types/auth.js

@@ -0,0 +1 @@
+export {};

package/dist/types/confluence.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Confluence ページのバージョン情報の型
+ */
+export interface ConfluenceVersion {
+    /** バージョン番号 */
+    readonly number: number;
+    /** 作成者の表示名 */
+    readonly by: string;
+    /** 作成日時（ISO 8601 形式） */
+    readonly when: string;
+    /** バージョンメッセージ（null の場合はメッセージなし） */
+    readonly message: string | null;
+    /** 本文（バージョン詳細取得時のみ） */
+    readonly body?: string;
+}
+/**
+ * Confluence ページの添付ファイルの型
+ */
+export interface ConfluenceAttachment {
+    /** 添付ファイル ID */
+    readonly id: string;
+    /** ファイルタイトル */
+    readonly title: string;
+    /** メディアタイプ */
+    readonly mediaType: string;
+    /** ファイルサイズ（バイト） */
+    readonly fileSize: number;
+    /** ダウンロード URL */
+    readonly downloadUrl: string;
+}
+/**
+ * Confluence ページの型
+ */
+export interface ConfluencePage {
+    /** ページ ID */
+    readonly id: string;
+    /** ページタイトル */
+    readonly title: string;
+    /** ページ本文（HTML 形式） */
+    readonly body: string;
+    /** スペースキー */
+    readonly spaceKey: string;
+    /** 現在のバージョン番号 */
+    readonly currentVersion: number;
+    /** バージョン一覧 */
+    readonly versions: readonly ConfluenceVersion[];
+    /** 添付ファイル一覧 */
+    readonly attachments: readonly ConfluenceAttachment[];
+}
+/**
+ * Confluence サービスのエラーの型
+ */
+export type ConfluenceError = {
+    kind: 'NOT_FOUND';
+    message: string;
+} | {
+    kind: 'FORBIDDEN';
+    message: string;
+} | {
+    kind: 'AUTH_FAILED';
+    message: string;
+} | {
+    kind: 'NETWORK_ERROR';
+    message: string;
+} | {
+    kind: 'PARSE_ERROR';
+    message: string;
+};

package/dist/types/confluence.js

@@ -0,0 +1 @@
+export {};

package/dist/types/diff.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 差分計算に関する型定義
+ *
+ * DiffService で使用する型を定義する。
+ * unified diff 形式での出力、差分統計の計算に対応。
+ */
+/**
+ * 差分オプション
+ *
+ * 差分計算時の設定を指定する。
+ */
+export interface DiffOptions {
+    /** カラー出力を有効にするか */
+    readonly colorEnabled: boolean;
+    /** コンテキスト行数（デフォルト: 3） */
+    readonly contextLines?: number;
+}
+/**
+ * 差分行の種別
+ */
+export type DiffLineType = 'add' | 'remove' | 'context';
+/**
+ * 差分行
+ *
+ * 1行分の差分情報を表す。
+ */
+export interface DiffLine {
+    /** 行の種別 */
+    readonly type: DiffLineType;
+    /** 行の内容 */
+    readonly content: string;
+}
+/**
+ * 差分ハンク
+ *
+ * 連続した差分行のグループを表す。
+ * unified diff 形式の @@ -start,lines +start,lines @@ に対応。
+ */
+export interface DiffHunk {
+    /** 変更前テキストでの開始行番号 */
+    readonly oldStart: number;
+    /** 変更前テキストでの行数 */
+    readonly oldLines: number;
+    /** 変更後テキストでの開始行番号 */
+    readonly newStart: number;
+    /** 変更後テキストでの行数 */
+    readonly newLines: number;
+    /** 差分行のリスト */
+    readonly lines: readonly DiffLine[];
+}
+/**
+ * 差分統計
+ *
+ * 差分の追加・削除行数を集計した情報。
+ */
+export interface DiffStats {
+    /** 追加された行数 */
+    readonly additions: number;
+    /** 削除された行数 */
+    readonly deletions: number;
+    /** 変更があったハンクの数 */
+    readonly changes: number;
+}
+/**
+ * 差分結果
+ *
+ * 差分計算の結果を表す。
+ * ハンクのリストとフォーマット済み文字列を含む。
+ */
+export interface DiffResult {
+    /** 差分ハンクのリスト */
+    readonly hunks: readonly DiffHunk[];
+    /** unified diff 形式でフォーマットされた文字列 */
+    readonly formatted: string;
+    /** 差分統計 */
+    readonly stats: DiffStats;
+}

package/dist/types/diff.js

@@ -0,0 +1,7 @@
+/**
+ * 差分計算に関する型定義
+ *
+ * DiffService で使用する型を定義する。
+ * unified diff 形式での出力、差分統計の計算に対応。
+ */
+export {};

package/dist/types/fetch.d.ts

@@ -0,0 +1,65 @@
+import type { ConfluencePage } from './confluence.js';
+import type { JiraIssue } from './jira.js';
+/**
+ * Fetch 結果の型（判別共用体）
+ *
+ * Jira または Confluence のいずれかのデータを含む
+ */
+export type FetchResult = {
+    readonly type: 'jira';
+    readonly data: JiraIssue;
+} | {
+    readonly type: 'confluence';
+    readonly data: ConfluencePage;
+};
+/**
+ * Fetch サービスのエラーの型
+ */
+export type FetchError = {
+    kind: 'URL_PARSE_ERROR';
+    message: string;
+} | {
+    kind: 'JIRA_ERROR';
+    message: string;
+} | {
+    kind: 'CONFLUENCE_ERROR';
+    message: string;
+} | {
+    kind: 'AUTH_FAILED';
+    message: string;
+} | {
+    kind: 'NOT_FOUND';
+    message: string;
+} | {
+    kind: 'FORBIDDEN';
+    message: string;
+} | {
+    kind: 'NETWORK_ERROR';
+    message: string;
+} | {
+    kind: 'OUTPUT_ERROR';
+    message: string;
+} | {
+    kind: 'STORAGE_ERROR';
+    message: string;
+};
+/**
+ * FetchAndSave のオプションの型
+ */
+export interface FetchAndSaveOptions {
+    /** 出力先ベースディレクトリ */
+    readonly baseDir: string;
+    /** 入力 URL */
+    readonly sourceUrl: string;
+    /** CLI バージョン */
+    readonly cliVersion: string;
+}
+/**
+ * FetchAndSave の結果の型
+ */
+export interface FetchAndSaveResult {
+    /** 保存先ディレクトリパス */
+    readonly directory: string;
+    /** 生成された Manifest */
+    readonly manifest: import('./storage.js').Manifest;
+}

package/dist/types/fetch.js

@@ -0,0 +1 @@
+export {};

package/dist/types/file.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ファイルエラーの型
+ *
+ * FilePort の操作で発生するエラーを表現する判別共用体。
+ */
+export type FileError = {
+    kind: 'WRITE_FAILED';
+    path: string;
+    message: string;
+} | {
+    kind: 'PERMISSION_DENIED';
+    path: string;
+    message: string;
+} | {
+    kind: 'DISK_FULL';
+    path: string;
+    message: string;
+} | {
+    kind: 'READ_FAILED';
+    path: string;
+    message: string;
+};

package/dist/types/file.js

@@ -0,0 +1 @@
+export {};

package/dist/types/http.d.ts

@@ -0,0 +1,45 @@
+/**
+ * HTTP リクエストオプションの型
+ */
+export interface HttpRequestOptions {
+    /** HTTP メソッド */
+    readonly method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** リクエストヘッダー */
+    readonly headers?: Record<string, string>;
+    /** リクエストボディ */
+    readonly body?: string;
+    /** タイムアウト（ミリ秒） */
+    readonly timeout?: number;
+}
+/**
+ * HTTP レスポンスの型
+ */
+export interface HttpResponse<T> {
+    /** HTTP ステータスコード */
+    readonly status: number;
+    /** レスポンスヘッダー */
+    readonly headers: Record<string, string>;
+    /** レスポンスデータ */
+    readonly data: T;
+}
+/**
+ * HTTP エラーの型
+ */
+export type HttpError = {
+    kind: 'NETWORK_ERROR';
+    message: string;
+} | {
+    kind: 'TIMEOUT';
+    message: string;
+} | {
+    kind: 'HTTP_ERROR';
+    status: number;
+    message: string;
+};
+/**
+ * ダウンロード進捗コールバックの型
+ *
+ * @param transferred - 転送済みバイト数
+ * @param total - 総バイト数（不明な場合は undefined）
+ */
+export type ProgressCallback = (transferred: number, total: number | undefined) => void;

package/dist/types/http.js

@@ -0,0 +1 @@
+export {};