# 通知設計書 13-coded/logInstall

## 概要

本ドキュメントは、カスタム通知 `coded/logInstall` の設計仕様を定義する。この通知はサーバー（serve-d）からクライアント（エディタ）に送信され、DCD（D Completion Daemon）やその他コンポーネントのインストール・ビルド進捗ログをクライアントに送信する。

### 本通知の処理概要

`coded/logInstall` 通知は、serve-dがDCDなどの外部ツールのダウンロード・ビルド・インストールを行う際に、その進捗状況やコマンド出力をリアルタイムでクライアントに送信するための通知である。インストールプロセスの各ステップで複数回送信される。

**業務上の目的・背景**：DCDのインストールはネットワークダウンロードやソースコードからのコンパイルを伴い、長時間かかる場合がある。ユーザーに進捗状況をリアルタイムで通知することで、操作が正常に進行中であることを確認でき、問題発生時には原因の特定が容易になる。

**通知の送信タイミング**：DCD更新処理（`updateDCD` 関数）の実行中、およびソースからのビルド処理（`compileDependency` 関数）中に、各ステップの開始・進捗・終了時点で送信される。ファイルダウンロード時にも送信される。

**通知の受信者**：LSPクライアント（エディタ拡張機能）が受信する。クライアント側ではインストールログ用の出力チャンネルやパネルに表示されることが想定される。

**通知内容の概要**：文字列メッセージが送信される。メッセージ内容は、実行中のコマンド（`> git clone ...` など）、ダウンロード進捗、エラーメッセージ、成功/失敗メッセージなど多岐にわたる。

**期待されるアクション**：クライアントはメッセージを専用のログパネルに表示し、ユーザーがインストール状況を確認できるようにする。エラーメッセージの場合は、ユーザーが問題を認識し手動対処を行えるようにする。

## 通知種別

LSPカスタム通知（JSON-RPC notification）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 非同期（インストール処理中に随時送信） |
| 優先度 | 中 |
| リトライ | 無し |

### 送信先決定ロジック

サーバーからクライアントへの一方向通知。LSP接続で確立されたクライアントプロセスに固定。

## 通知テンプレート

### JSON-RPC通知メッセージ

| 項目 | 内容 |
|-----|------|
| メソッド名 | `coded/logInstall` |
| パラメータ型 | `string`（文字列メッセージ） |
| レスポンス | なし（通知） |

### メッセージ構造

```json
{
  "jsonrpc": "2.0",
  "method": "coded/logInstall",
  "params": "Installing DCD: DCD is outdated. Expected: 0.15.2, got none"
}
```

### 本文テンプレート

代表的なメッセージパターン：

```
Installing DCD
Installing DCD: {理由メッセージ}
Downloading from {URL} to {出力フォルダ}
Zip file already exists! Trying to install existing zip.
Extracting download...
> tar xvfz {ファイル名}
{コマンド出力の各行}
Installing into {フォルダパス}
Deleting old installation from {パス}
WARNING: Failed to delete {パス}
> {コマンド名} {引数...}
Successfully downloaded DCD, but could not find the executables.
Successfully installed DCD
DCD install failed
Failed installing: {例外メッセージ}
Failed to install {コンポーネント名}
```

### 添付ファイル

該当なし。

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| message | ログメッセージ文字列 | 各処理ステップで動的生成 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API | served/updateDCD通知受信 | DCD更新処理開始 | DCDのダウンロード・ビルド開始時および各ステップ |
| 内部処理 | compileDependency関数実行 | ソースからのビルド時 | gitクローン・ビルドコマンドの各ステップ |
| 内部処理 | downloadFile関数実行 | ファイルダウンロード時 | ダウンロード進捗通知 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| なし | インストール処理中は常に送信される |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[DCD更新トリガー] --> B[updateDCD関数開始]
    B --> C{ソースからビルド?}
    C -->|Yes| D[compileDependency実行]
    C -->|No| E[downloadFile実行]
    D --> F[各コマンド実行]
    F --> G[coded/logInstall送信: コマンド出力]
    E --> H[coded/logInstall送信: ダウンロード進捗]
    G --> I{全コマンド完了?}
    I -->|No| F
    I -->|Yes| J[結果判定]
    H --> J
    J -->|成功| K[coded/logInstall送信: 成功メッセージ]
    J -->|失敗| L[coded/logInstall送信: 失敗メッセージ]
    K --> M[終了]
    L --> M
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（データベースを使用しない）。

### 更新テーブル一覧

該当なし（データベースを使用しない）。

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ダウンロード失敗 | ネットワークエラー等 | エラーメッセージをcoded/logInstallで送信し、手動ダウンロード先を案内 |
| ビルド失敗 | コンパイルエラー等 | エラー出力をcoded/logInstallで送信 |
| 実行ファイル不在 | ダウンロード成功後に実行ファイルが見つからない | パスのリストと手動設定の案内をcoded/logInstallで送信 |
| バージョン確認失敗 | dcd-server --version が失敗 | エラー出力をcoded/logInstallで送信 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（coded/logInstall自体のリトライはなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし（インストール中は大量送信あり） |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし。インストール処理中に随時送信。

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

- メッセージにはファイルパス、URL、コマンド出力が含まれる
- 個人情報は通常含まれないが、ユーザー環境のパス情報が含まれる可能性がある
- ダウンロードURLが外部に公開されるリスクは低い（GitHub公開リポジトリのURL）

## 備考

- `coded/` プレフィックスはcode-d拡張機能のカスタムプロトコルを示す
- インストール処理は Fiber（協調スレッド）上で実行されるため、RPC通信と並行して動作する
- ダウンロード方式は `letEditorDownload` フラグにより、エディタ側ダウンロード（`coded/interactiveDownload`）とサーバー側手動ダウンロードの2つのモードがある

---

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

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

### 推奨読解順序

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

coded/logInstallは文字列パラメータのみであり、特別なデータ構造はない。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | dcd_update.d | `source/served/commands/dcd_update.d` | updateDCD関数全体（L82-307）を通読し、送信されるメッセージのパターンを把握 |

**読解のコツ**: `rpc.notifyMethod("coded/logInstall", ...)` の呼び出し箇所を追跡することで、送信パターンを網羅的に把握できる。

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

DCD更新のトリガーとなる箇所を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | dcd_update.d | `source/served/commands/dcd_update.d` | `@protocolNotification("served/updateDCD")` アトリビュート（L82）によるトリガー登録 |
| 2-2 | extension.d | `source/served/extension.d` | doGlobalStartup内のDCD更新フロー（L426-472）-- aggressiveUpdateまたはユーザー確認後にupdateDCDが呼ばれる |

**主要処理フロー**:
1. **dcd_update.d L82-83**: `served/updateDCD` 通知で `updateDCD` が起動
2. **dcd_update.d L91-94**: 更新理由があればcoded/logInstallで送信
3. **dcd_update.d L127-129**: ソースビルドかバイナリダウンロードかを判定
4. **dcd_update.d L185-201**: ダウンロードとアーカイブ展開のログ送信

#### Step 3: ソースビルド処理を理解する

git_build.dのcompileDependency関数を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | git_build.d | `source/served/io/git_build.d` | compileDependency関数（L13-79）のログ送信パターン |

**主要処理フロー**:
- **L21**: 各コマンド実行前に `> {コマンド}` を送信
- **L40**: コマンドの標準出力を1行ずつ送信
- **L47**: インストール先フォルダを送信
- **L53**: 古いインストールの削除を送信
- **L75-76**: 失敗メッセージを送信

#### Step 4: ダウンロード処理を理解する

http_wrap.dのdownloadFile関数を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | http_wrap.d | `source/served/io/http_wrap.d` | downloadFile関数（L17-31）のログ送信 |

**主要処理フロー**:
- **L27-29**: 手動ダウンロードモード時にcoded/logInstallを使用してダウンロード進捗を送信

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

```
updateDCD (dcd_update.d:83)
    |
    +-- rpc.notifyMethod("coded/logInstall", ...) -- 開始メッセージ
    |
    +-- [ソースビルドの場合]
    |       |
    |       +-- compileDependency (git_build.d:13)
    |               |
    |               +-- rpc.notifyMethod("coded/logInstall", ...) -- 各ステップ
    |               +-- run() -- 外部コマンド実行
    |                       +-- rpc.notifyMethod("coded/logInstall", ...) -- 出力行
    |
    +-- [バイナリダウンロードの場合]
    |       |
    |       +-- downloadFile (http_wrap.d:17)
    |       |       +-- rpc.notifyMethod("coded/logInstall", ...) -- 進捗
    |       |
    |       +-- tar/zip展開
    |               +-- rpc.notifyMethod("coded/logInstall", ...) -- 展開ログ
    |
    +-- rpc.notifyMethod("coded/logInstall", ...) -- 結果メッセージ
```

### データフロー図

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

served/updateDCD       updateDCD()                   coded/logInstall
通知               --> (dcd_update.d:83)          --> クライアントの
                       |                              ログパネル
                       +-- compileDependency()
                       |   (git_build.d:13)
                       |
                       +-- downloadFile()
                           (http_wrap.d:17)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| dcd_update.d | `source/served/commands/dcd_update.d` | ソース | DCD更新メイン処理、coded/logInstallの主要送信元 |
| git_build.d | `source/served/io/git_build.d` | ソース | ソースからのビルド処理、ログ送信 |
| http_wrap.d | `source/served/io/http_wrap.d` | ソース | ファイルダウンロード処理、ログ送信 |
| extension.d | `source/served/extension.d` | ソース | DCD更新トリガー（doGlobalStartup内） |
