# 機能設計書 15-doom install

## 概要

本ドキュメントは、Doom Emacsの初期インストールコマンド「doom install」の機能設計を定義する。このコマンドは、Doom Emacsを初めてセットアップする際に使用するインストールウィザードである。

### 本機能の処理概要

doom installは、Doom Emacsの初期セットアップを自動化するコマンドである。プライベート設定ディレクトリの作成、テンプレートファイルの配置、パッケージのインストールまでを一括で行う。

**業務上の目的・背景**：Doom Emacsを初めて使用するユーザーにとって、セットアップは複雑なプロセスになりがちである。doom installはこのプロセスを自動化し、ユーザーが最小限の手順でDoomを利用開始できるようにする。また、設定テンプレートを提供することで、ユーザーが自分の設定をカスタマイズする出発点を提供する。

**機能の利用シーン**：
- Doom Emacsを初めてインストールした直後
- 既存のDoom設定を削除して再セットアップする場合
- 新しいマシンにDoomを設定する場合

**主要な処理内容**：
1. $DOOMDIRの作成（~/.config/doom または ~/.doom.d）
2. テンプレートファイルのコピー（init.el, config.el, packages.el）
3. 環境変数ファイルの生成（オプション）
4. パッケージのインストール（doom-packages-ensure）
5. プロファイルの初期化と同期
6. Gitフックのデプロイ（commit-msg, pre-push）

**関連システム・外部連携**：
- straight.el: パッケージ管理
- git: フックのデプロイ

**権限による制御**：各処理ステップは--config, --env, --install, --hooksフラグで制御可能。

## 関連画面

本機能はCLIコマンドであり、GUIの画面は持たない。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | ターミナル | 主画面 | コマンドライン実行、進捗表示 |

## 機能種別

インストール処理 / 初期セットアップ / 設定生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --aot | フラグ | No | ネイティブコンパイルを有効化 | - |
| --config | フラグ | No | DOOMDIRとテンプレートを作成するか（デフォルト: yes） | :yes または :no |
| --env | フラグ | No | 環境変数ファイルを生成するか | - |
| --install | フラグ | No | パッケージを自動インストールするか（デフォルト: yes） | :yes または :no |
| --hooks | フラグ | No | Gitフックをデプロイするか（デフォルト: yes） | :yes または :no |

### 入力データソース

- テンプレートディレクトリ（doom-emacs-dir/static/）
- ユーザー入力（y-or-n-pによる確認）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| $DOOMDIR | ディレクトリ | プライベート設定ディレクトリ |
| init.el | ファイル | モジュール設定ファイル |
| config.el | ファイル | ユーザー設定ファイル |
| packages.el | ファイル | パッケージ宣言ファイル |

### 出力先

- $DOOMDIR（~/.config/doom または ~/.doom.d）
- doom-env-file（環境変数ファイル）
- .git/hooks/（Gitフック）

## 処理フロー

### 処理シーケンス

```
1. DOOMDIRの決定
   └─ XDG_CONFIG_HOME/doom または ~/.doom.d
   └─ 既存の場合はスキップ

2. テンプレートファイルのコピー
   └─ init.el.example → init.el
   └─ config.el.example → config.el
   └─ packages.el.example → packages.el
   └─ 既存の場合はスキップ

3. 設定ファイルのロード
   └─ init.elをロード
   └─ cli.elをロード（存在する場合）

4. 環境変数ファイル生成（オプション）
   └─ ユーザー確認または--envフラグ
   └─ doom envを呼び出し

5. パッケージインストール
   └─ --installが:noでなければ
   └─ doom-packages-ensureを実行

6. プロファイル初期化
   └─ profile sync --all --reload
   └─ doom-profile-generate

7. Gitフックのデプロイ
   └─ --hooksが:noでなければ
   └─ ci deploy-hooksを呼び出し

8. 警告チェック
   └─ ~/.emacsが存在する場合は警告

9. 完了メッセージ
   └─ QUICKSTART_INTROの表示
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{--config<br>= :no?}
    B -->|Yes| C[スキップ]
    B -->|No| D[DOOMDIR決定]
    C --> E
    D --> E{DOOMDIR<br>存在?}
    E -->|Yes| F[スキップ]
    E -->|No| G[作成]
    F --> H[テンプレートコピー]
    G --> H
    H --> I[設定ロード]
    I --> J{--env?}
    J -->|Yes| K[doom env実行]
    J -->|No| L{ユーザー確認}
    L -->|Yes| K
    L -->|No| M{--install<br>= :no?}
    K --> M
    M -->|Yes| N[スキップ]
    M -->|No| O[パッケージインストール]
    N --> P[プロファイル初期化]
    O --> P
    P --> Q{--hooks<br>= :no?}
    Q -->|Yes| R[スキップ]
    Q -->|No| S[Gitフックデプロイ]
    R --> T[警告チェック]
    S --> T
    T --> U[完了メッセージ]
    U --> V[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | XDG優先 | doom-emacs-dirがXDG_CONFIG_HOME配下ならDOOMDIRも同配下 | インストール時 |
| BR-02 | 既存ファイル保護 | 既存のファイル/ディレクトリは上書きしない | 常時 |
| BR-03 | .emacs警告 | ~/.emacsが存在する場合は競合警告を表示 | インストール完了時 |
| BR-04 | 冪等性 | コマンドは何度実行しても安全 | 常時 |

### 計算ロジック

**DOOMDIR決定ロジック**:
```elisp
(when (and (not (file-directory-p doom-user-dir))
           (not (getenv "DOOMDIR")))
  (let ((xdg-config-dir (or (getenv "XDG_CONFIG_HOME") "~/.config")))
    (when (file-in-directory-p doom-emacs-dir xdg-config-dir)
      (setq doom-user-dir (expand-file-name "doom/" xdg-config-dir)))))
```

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 警告 | ~/.emacsが存在 | 競合ファイルを削除 |
| - | ユーザーエラー | Gitフックデプロイ失敗 | 手動でフックを設定 |

### リトライ仕様

コマンドは冪等であり、何度でも再実行可能。

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

各ファイル作成は個別に行われ、トランザクション管理はない。失敗した場合は再実行で対応。

## パフォーマンス要件

- パッケージインストールに時間がかかる可能性
- ネットワーク速度に依存

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

- テンプレートファイルはDoomのリポジトリから取得
- Gitフックはdoom cliを実行するスクリプト

## 備考

- QUICKSTART_INTROは初心者向けのガイダンステキスト
- --doomdirオプションで別の場所にインストール可能

---

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

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

### 推奨読解順序

#### Step 1: コマンド定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | install.el | `lisp/cli/install.el` | 17-24行目のdefcli!定義 |

**主要処理フロー**:
- **17-24行目**: コマンド定義と各フラグの意味

#### Step 2: DOOMDIR作成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | install.el | `lisp/cli/install.el` | 46-80行目のDOOMDIR処理 |

**主要処理フロー**:
- **47-48行目**: --config :noの場合のスキップ
- **50-54行目**: DOOMDIR位置の決定ロジック
- **56-59行目**: ディレクトリ作成
- **62-80行目**: テンプレートファイルのコピー

#### Step 3: パッケージインストールを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | install.el | `lisp/cli/install.el` | 98-109行目のパッケージ処理 |

**主要処理フロー**:
- **99-102行目**: パッケージインストール
- **104-106行目**: プロファイル初期化
- **108-109行目**: プロファイル同期

#### Step 4: フック処理と完了を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | install.el | `lisp/cli/install.el` | 111-126行目の完了処理 |

**主要処理フロー**:
- **111-118行目**: Gitフックのデプロイ
- **120-121行目**: ~/.emacs警告
- **123-126行目**: 完了メッセージとQUICKSTART_INTRO表示

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

```
doom install (defcli!)
    │
    ├─ DOOMDIR作成
    │      └─ make-directory
    │
    ├─ テンプレートコピー
    │      └─ with-temp-file + insert-file-contents
    │
    ├─ 設定ロード
    │      ├─ doom-load (init.el)
    │      └─ doom-load (cli.el)
    │
    ├─ call! '(env)
    │
    ├─ doom-packages-ensure
    │
    ├─ call! '(profile sync --all --reload)
    │
    ├─ doom-profile-generate
    │
    └─ call! '(ci deploy-hooks)
```

### データフロー図

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

static/init.example.el  ───▶  テンプレート   ───▶  $DOOMDIR/init.el
                               コピー
static/config.example.el ───▶              ───▶  $DOOMDIR/config.el

static/packages.example.el ───▶            ───▶  $DOOMDIR/packages.el

packages定義           ───▶  パッケージ    ───▶  straight/build/
                             インストール

プロファイル設定       ───▶  プロファイル  ───▶  プロファイルキャッシュ
                             生成
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| install.el | `lisp/cli/install.el` | ソース | installコマンドの主実装 |
| init.example.el | `static/init.example.el` | テンプレート | init.elのテンプレート |
| config.example.el | `static/config.example.el` | テンプレート | config.elのテンプレート |
| packages.example.el | `static/packages.example.el` | テンプレート | packages.elのテンプレート |
| QUICKSTART_INTRO | `static/QUICKSTART_INTRO` | テキスト | インストール完了後のガイダンス |
| env.el | `lisp/cli/env.el` | ソース | 環境変数ファイル生成 |
| ci.el | `lisp/cli/ci.el` | ソース | Gitフックデプロイ |
