# バッチ設計書 51-darc-init.sh

## 概要

本ドキュメントは、DARC (Dependency Auto Update Repository Client) CLIツールの初期化・インストールを行うバッチスクリプト `eng/common/darc-init.sh` の設計書です。

### 本バッチの処理概要

このバッチは、.NETエコシステムにおける依存関係管理ツールであるDARC CLIをインストールおよび更新するためのスクリプトです。DARCは、マイクロソフトの依存関係自動更新システムであるMaestro/DARCの一部として機能し、リポジトリ間の依存関係を管理します。

**業務上の目的・背景**：F#コンパイラプロジェクトは、.NETランタイムや他のArcade SDKを使用するリポジトリと複雑な依存関係を持っています。これらの依存関係を自動的に追跡し、更新するためにDARC CLIが必要です。手動での依存関係管理は煩雑でエラーが発生しやすいため、DARCによる自動化が重要な役割を果たしています。また、CI/CDパイプラインにおいて、依存関係の一貫性を保つために使用されます。

**バッチの実行タイミング**：主に以下のタイミングで実行されます。
- 開発者が初めてリポジトリをセットアップする際
- CI/CDパイプラインで依存関係の更新が必要な場合
- DARCの新しいバージョンがリリースされ、アップグレードが必要な場合
- 手動でdarcコマンドを使用する前の準備として

**主要な処理内容**：
1. コマンドライン引数の解析（DARCバージョン、バージョンエンドポイント、詳細度、ツールパス）
2. スクリプトルートディレクトリの解決（シンボリックリンク対応）
3. tools.shの読み込みによる共通関数の初期化
4. DARCバージョンの取得（指定がない場合はMaestroエンドポイントから最新版を取得）
5. .NET CLIの初期化
6. 既存のDARC CLIがインストールされている場合はアンインストール
7. 指定されたバージョンのDARC CLIをNuGetフィードからインストール

**前後の処理との関連**：このスクリプトは `tools.sh` に依存しており、InitializeDotNetCli関数を使用して.NET SDKを初期化します。また、`tools.sh` 内の `GetDarc` 関数から呼び出されることもあり、他のビルドスクリプトからの間接的な利用も想定されています。

**影響範囲**：
- グローバルツールとしてインストールする場合：ユーザーのグローバル.NETツール領域
- ツールパス指定の場合：指定されたローカルディレクトリ
- 環境変数やPATH設定には直接影響しないが、インストール後のdarcコマンドの可用性に影響

## バッチ種別

ツールインストール / 環境セットアップ

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動 / CI/CDパイプライン |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| bashシェル | Linux/macOS環境またはWSL |
| ネットワーク接続 | Maestroエンドポイントおよびdnceng NuGetフィードへのアクセス |
| curlコマンド | バージョン情報取得に使用 |
| .NET SDK | tools.shによって自動インストールされる |

### 実行可否判定

- 既存のDARC CLIがインストールされている場合でも実行可能（アンインストール後に再インストール）
- ネットワーク接続がない場合は失敗
- 指定されたバージョンが存在しない場合は失敗

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --darcversion | string | No | Maestroから取得 | インストールするDARCのバージョン |
| --versionendpoint | string | No | https://maestro.dot.net/api/assets/darc-version?api-version=2020-02-20 | バージョン情報を取得するエンドポイント |
| --verbosity | string | No | minimal | dotnet toolコマンドの詳細度レベル |
| --toolpath | string | No | (グローバルインストール) | インストール先のローカルパス |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| Maestro APIエンドポイント | HTTP/REST | 最新DARCバージョンの取得 |
| tools.sh | シェルスクリプト | 共通関数の読み込み |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| グローバルツール領域 | .NET Tool | --toolpath未指定時のインストール先 |
| 指定されたtoolpath | .NET Tool | --toolpath指定時のインストール先 |
| 標準出力 | テキスト | インストール進捗メッセージ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | darc（実行可能ファイル） |
| 出力先 | ~/.dotnet/tools/ または指定されたtoolpath |
| 文字コード | バイナリ |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. コマンドライン引数の解析
   └─ --darcversion, --versionendpoint, --verbosity, --toolpath の処理

2. スクリプトルートの解決
   └─ シンボリックリンクを辿って実際のパスを取得

3. tools.shの読み込み
   └─ 共通関数（InitializeDotNetCliなど）を利用可能にする

4. DARCバージョンの決定
   └─ 引数で指定がなければMaestroエンドポイントからcurlで取得

5. InstallDarcCli関数の実行
   ├─ InitializeDotNetCliで.NET CLIを初期化
   ├─ 既存のDARC CLIがあればアンインストール
   └─ dotnet tool installで新規インストール
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[引数解析]
    B --> C[スクリプトルート解決]
    C --> D[tools.sh読み込み]
    D --> E{darcVersion指定あり?}
    E -->|なし| F[Maestroからバージョン取得]
    E -->|あり| G[指定バージョン使用]
    F --> G
    G --> H[InitializeDotNetCli]
    H --> I{toolpath指定あり?}
    I -->|なし| J[グローバルツール確認]
    I -->|あり| K[ローカルツール確認]
    J --> L{既存DARC?}
    K --> L
    L -->|あり| M[既存DARCアンインストール]
    L -->|なし| N[新規インストール]
    M --> N
    N --> O[バッチ終了]
```

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

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

このバッチはデータベース操作を行いません。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | - | - | - |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | 引数エラー | 無効な引数が指定された場合 | usage関数でヘルプを表示 |
| 1 | ネットワークエラー | Maestroエンドポイントに接続できない場合 | ネットワーク接続を確認 |
| 1 | インストールエラー | dotnet tool installが失敗した場合 | NuGetフィードへのアクセスを確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（dotnet toolコマンドに依存） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

1. ネットワーク接続を確認
2. `--darcversion` オプションで明示的にバージョンを指定して再実行
3. 手動で `dotnet tool install microsoft.dotnet.darc` を実行
4. NuGetフィード `https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-eng/nuget/v3/index.json` への接続を確認

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（ファイルシステム操作のみ） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回のインストール |
| 目標処理時間 | 60秒以内（ネットワーク状況による） |
| メモリ使用量上限 | .NET SDKの要件に準拠 |

## 排他制御

- 同時実行は非推奨（同一ツールパスへの競合インストールを避けるため）
- dotnet toolコマンドのファイルロック機構に依存

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 進捗ログ | インストール開始時 | "Installing Darc CLI version $darcVersion..." |
| 案内ログ | インストール完了時 | シェル再起動の案内メッセージ |
| エラーログ | 引数エラー時 | "Invalid argument: $1" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | 120秒 | CI/CDパイプラインタイムアウト |
| 終了コード | 0以外 | CI/CDパイプライン失敗通知 |

## 備考

- このスクリプトはArcadeフレームワークの共通コンポーネントとして提供されている
- `tools.sh` の `GetDarc` 関数から呼び出されることがある
- 初回インストール時はシェルの再起動が必要な場合がある
- dnceng Azure DevOps NuGetフィードへのアクセスが必要
