# 機能設計書 39-リポジトリ一覧取得

## 概要

本ドキュメントは、Giselleワークフローエンジンにおける「リポジトリ一覧取得」機能の設計を記述する。本機能は、連携しているGitHubリポジトリの一覧を取得するAPIを提供する。

### 本機能の処理概要

本機能は、設定されたGitHub認証情報（Personal Access TokenまたはGitHub App）を使用して、アクセス可能なリポジトリの一覧を取得し、ノードIDとフルネーム（owner/repo形式）のリストとして返却する。

**業務上の目的・背景**：ワークフローのトリガー設定時に、ユーザーが連携可能なGitHubリポジトリを選択できるようにするため、アクセス可能なリポジトリの一覧が必要となる。インテグレーション設定画面やワークフローエディタでのリポジトリ選択に使用される。

**機能の利用シーン**：
- インテグレーション設定画面でGitHub連携リポジトリを確認する場合
- ワークフローエディタでトリガーのリポジトリを選択する場合
- ベクトルストア設定画面でGitHubリポジトリを選択する場合

**主要な処理内容**：
1. GiselleContextからGitHub認証設定を取得
2. 認証戦略（PAT/App）に応じたAPI呼び出し
3. Personal Access Token: ユーザーリポジトリを取得
4. GitHub App: 各インストレーションのリポジトリを並列取得
5. リポジトリ情報（nodeId、fullName）のリストを返却

**関連システム・外部連携**：
- GitHub REST API

**権限による制御**：設定されたGitHub認証情報のスコープに依存

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 28 | インテグレーション設定画面 | 主画面 | 連携しているGitHubリポジトリの一覧取得と表示 |
| 31 | GitHub Vector Store設定画面 | API連携 | 連携可能なGitHubリポジトリの取得 |

## 機能種別

データ取得（SELECT操作）/ 外部API連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| context | GiselleContext | Yes | Giselle実行コンテキスト（GitHub認証設定を含む） | - |

### 入力データソース

- GiselleContext内のGitHub認証設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (配列) | Repository[] | リポジトリ情報の配列 |

#### Repository型の構造

| フィールド | 型 | 説明 |
|-----------|-----|------|
| nodeId | string | GitHubリポジトリのノードID（GraphQL ID） |
| fullName | string | リポジトリのフルネーム（owner/repo形式） |

### 出力先

呼び出し元への戻り値として返却

## 処理フロー

### 処理シーケンス

```
1. GitHub設定の取得
   └─ context.integrationConfigs?.githubを確認

2. 設定なしの場合
   └─ 空配列を返却

3. 認証戦略の判定
   ├─ personal-access-token: PATでユーザーリポジトリ取得
   └─ app-installation: Appでインストレーションリポジトリ取得

4. Personal Access Token戦略
   └─ GET /user/repos API呼び出し

5. App Installation戦略
   ├─ インストレーションID一覧を取得
   └─ 各インストレーションのリポジトリを並列取得

6. リポジトリ情報の整形
   └─ nodeId、fullNameを抽出

7. 結果を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[GitHub設定取得]
    B --> C{設定あり?}
    C -->|No| D[空配列返却]
    C -->|Yes| E{認証戦略?}
    E -->|PAT| F[GET /user/repos]
    E -->|App| G[インストレーションID取得]
    G --> H[各インストレーションで並列取得]
    H --> I[GET /installation/repositories]
    F --> J[リポジトリ情報整形]
    I --> J
    J --> K[Repository[]返却]
    D --> L[終了]
    K --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-39-001 | 設定なし時の動作 | GitHub設定がない場合は空配列を返却 | 常時 |
| BR-39-002 | PAT戦略 | Personal Access Tokenの場合はユーザーリポジトリを取得 | strategy === "personal-access-token" |
| BR-39-003 | App戦略 | GitHub Appの場合は全インストレーションのリポジトリを取得 | strategy === "app-installation" |
| BR-39-004 | 並列取得 | 複数インストレーションは並列処理 | App戦略時 |

### 計算ロジック

該当なし

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| (なし) | - | - | 外部APIのみ使用 |

### テーブル別操作詳細

該当なし（外部API呼び出しのみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | GitHub API Error | API呼び出し失敗 | エラーをスロー |

### リトライ仕様

該当なし（GitHub APIのリトライはoctokitに依存）

## トランザクション仕様

該当なし（読み取り専用）

## パフォーマンス要件

- レスポンス時間：2秒以内（GitHub API応答に依存）
- 並列取得によるインストレーション数増加時の最適化

## セキュリティ考慮事項

- Personal Access Tokenの安全な管理
- GitHub App秘密鍵の安全な管理
- 最小権限原則（必要なスコープのみ）

## 備考

- GitHub AppのインストレーションIDはresolverから取得
- nodeIdはGraphQL APIで使用されるID形式

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

まず、返却されるRepository型を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | get-github-repositories.ts | `packages/giselle/src/github/get-github-repositories.ts` | Repository interfaceの定義（4-7行目） |

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | get-github-repositories.ts | `packages/giselle/src/github/get-github-repositories.ts` | メイン処理（全51行） |

**主要処理フロー**:
1. **4-7行目**: Repository interface定義
2. **8行目**: getGitHubRepositories関数開始
3. **9-12行目**: GitHub設定の取得と存在チェック
4. **14-26行目**: Personal Access Token戦略の処理
5. **27-50行目**: GitHub App戦略の処理

#### Step 3: Personal Access Token戦略を理解する

**主要処理フロー（PAT）**:
- **14行目**: strategy === "personal-access-token"の判定
- **15-18行目**: octokit初期化とAPI呼び出し
- **19-25行目**: レスポンスからnodeIdとfullNameを抽出

#### Step 4: GitHub App戦略を理解する

**主要処理フロー（App）**:
- **27-28行目**: appIdとprivateKeyの取得
- **30行目**: resolver.installationIds()でインストレーションID一覧取得
- **33-49行目**: Promise.allで各インストレーションのリポジトリを並列取得

### プログラム呼び出し階層図

```
getGitHubRepositories (get-github-repositories.ts)
    │
    ├─ [PAT戦略]
    │      │
    │      └─ octokit({ strategy: "personal-access-token" })
    │             │
    │             └─ GET /user/repos
    │
    └─ [App戦略]
           │
           ├─ resolver.installationIds()
           │
           └─ Promise.all
                  │
                  └─ [各インストレーション]
                         │
                         └─ octokit({ strategy: "app-installation" })
                                │
                                └─ GET /installation/repositories
```

### データフロー図

```
[入力]               [処理]                    [出力]

GiselleContext ───▶ GitHub設定取得
        │
        ▼
{設定なし?} ───────▶ 空配列返却 ───▶ []
        │
        ▼
{strategy判定}
        │
        ├─ PAT ───▶ GET /user/repos ───▶ リポジトリリスト
        │
        └─ App ───▶ installationIds()
                         │
                         ▼
               [並列] GET /installation/repositories
                         │
                         ▼
                   マージ処理
        │
        ▼
Repository[] ───▶ { nodeId, fullName }[]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| get-github-repositories.ts | `packages/giselle/src/github/get-github-repositories.ts` | ソース | メイン処理 |
| octokit | `@giselles-ai/github-tool` | 外部モジュール | GitHub APIクライアント |
| types.ts | `packages/giselle/src/types.ts` | ソース | GiselleContext型 |
