# バッチ設計書 1-doom

## 概要

本ドキュメントは、Doom Emacs CLIのメインエントリポイントである`doom`スクリプトの設計仕様を定義するものである。

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

`doom`スクリプトは、Doom Emacsのパッケージ管理、診断、バイトコンパイル等の機能を提供するコマンドラインインターフェースのメインエントリポイントである。シェルスクリプトとEmacs Lispのポリグロット（多言語混在）ファイルとして実装されており、様々なシェル環境で動作可能である。

**業務上の目的・背景**：Doom Emacsは高度にカスタマイズされたEmacs設定フレームワークであり、パッケージ管理、設定同期、診断などの複雑な操作を簡単に行うためのCLIツールが必要である。`doom`コマンドは、これらの操作を統一されたインターフェースで提供し、ユーザーがDoom Emacsの管理を効率的に行えるようにする。

**バッチの実行タイミング**：ユーザーが手動でコマンドを実行する随時実行型。主に設定変更後、パッケージ更新時、トラブルシューティング時などに使用される。

**主要な処理内容**：
1. シェル環境の検証とEmacs実行可能ファイルの確認
2. ターミナル情報の環境変数への設定（サイズ、パイプ状態等）
3. Doom Emacsコアの初期化（early-init.el の読み込み）
4. ルート権限チェックとセキュリティ検証
5. ユーザー設定とCLIモジュールの読み込み
6. サブコマンドの実行とディスパッチ

**前後の処理との関連**：本スクリプトは他のすべてのDoom CLIコマンド（sync, gc, env, install, upgrade等）の基盤となる。各サブコマンドは本スクリプトを通じて呼び出される。

**影響範囲**：Doom Emacsの全設定ファイル、パッケージディレクトリ、プロファイルデータに影響を与える可能性がある。

## バッチ種別

CLI基盤 / コマンドディスパッチャー

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | ユーザー任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動（ユーザーコマンド実行） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Emacs インストール | Emacs が $PATH に存在し実行可能であること |
| Doom Emacs インストール | $EMACSDIR に Doom Emacs がインストール済みであること |
| POSIX 互換シェル | /bin/sh が POSIX 互換であること |

### 実行可否判定

1. `$EMACS` 環境変数で指定されたEmacsコマンド、または `emacs` が実行可能か確認
2. Doom Emacs のインストールディレクトリに `early-init.el` が存在するか確認
3. ルートユーザーで実行する場合、`$EMACSDIR` の所有者がルートであるか確認

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --force (-!) | フラグ | No | false | プロンプトを抑制し自動承認 |
| --debug (-D) | フラグ | No | false | デバッグ出力を有効化 |
| --verbose (-v) | フラグ | No | false | 詳細出力を有効化 |
| --doomdir | パス | No | ~/.doom.d または ~/.config/doom | Doom設定ディレクトリを指定 |
| --emacsdir | パス | No | ~/.emacs.d または ~/.config/emacs | Doomインストールディレクトリを指定 |
| --pager | コマンド | No | "less +g" | ページャーコマンドを指定 |
| --profile | 文字列 | No | "_@0" | 使用するプロファイル名 |
| --benchmark | フラグ | No | false | ベンチマーク表示を常に有効化 |
| --color | フラグ | No | 自動判定 | ANSIカラー出力の有無 |
| --load (-L) | ファイルパス | No | なし | コマンド実行前に読み込むElispファイル |
| --eval (-E) | Elisp式 | No | なし | コマンド実行前に評価するElisp式 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| $DOOMDIR/init.el | Emacs Lisp | ユーザーのDoom設定（doom!ブロック） |
| $DOOMDIR/cli.el | Emacs Lisp | ユーザー定義CLIコマンド |
| .doomrc / .doom.el | Emacs Lisp | プロジェクトローカルCLI設定 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | コマンド実行結果、ログメッセージ |
| 標準エラー出力 | テキスト | エラーメッセージ、警告 |
| $TMPDIR/doom.*.sh | シェルスクリプト | 終了後に実行する一時スクリプト（終了コード254の場合） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | doom.${__DOOMPID}.${__DOOMSTEP}.sh |
| 出力先 | $TMPDIR |
| 文字コード | UTF-8 |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. シェルスクリプト部分の実行
   └─ Emacs実行可能性の確認
   └─ ターミナル環境変数の設定（__DOOMGEOM, __DOOMPIPE等）
   └─ Emacsをバッチモードで起動し本ファイルを読み込み

2. Emacs Lisp部分の実行
   └─ early-init.el の読み込みによるDoomコア初期化
   └─ ルート権限チェック

3. CLIフレームワーク初期化
   └─ doom!ブロックの処理（doom-modules-initialize）
   └─ サブコマンドの遅延読み込み設定

4. ユーザー設定の読み込み
   └─ $DOOMDIR/init.el の処理
   └─ .doomrc / .doom.el の処理

5. コマンドディスパッチ
   └─ run! によるサブコマンド実行
```

### フローチャート

```mermaid
flowchart TD
    A[スクリプト開始] --> B{Emacs存在確認}
    B -->|なし| C[エラー終了]
    B -->|あり| D[環境変数設定]
    D --> E[Emacsバッチモード起動]
    E --> F[early-init.el読み込み]
    F --> G{ルート権限チェック}
    G -->|警告必要| H[警告表示]
    H --> I[続行確認]
    G -->|OK| J[CLIフレームワーク初期化]
    I -->|中止| C
    I -->|続行| J
    J --> K[モジュール初期化]
    K --> L[サブコマンド実行]
    L --> M{終了コード確認}
    M -->|254| N[一時スクリプト実行]
    M -->|その他| O[終了]
    N --> O
```

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

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

本バッチはデータベースを使用しない。ファイルシステムベースの操作のみを行う。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | N/A | データベース操作なし |

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

データベース操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | 実行エラー | コマンドが完了できなかった | ログを確認し原因を特定 |
| 2 | 内部エラー | 一般的な内部エラー | doom doctor で診断 |
| 3 | 環境エラー | Emacs/Doomのインストールまたは実行コンテキストの問題 | 環境設定を確認 |
| 4 | 入力エラー | 認識できないユーザー入力 | ヘルプを参照 |
| 5 | コマンドエラー | コマンドが見つからないまたは非推奨 | doom help で確認 |
| 6 | 引数エラー | 無効、不足、または余分なオプション/引数 | 正しい引数を指定 |
| 254 | 継続実行 | 正常終了後に子プロセス実行が必要 | 自動処理される |
| 255 | 致命的エラー | 捕捉されない重大なエラー | ログを確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（手動再実行） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

1. `doom doctor` を実行して環境診断
2. `DEBUG=1 doom <command>` でデバッグモード実行
3. 必要に応じて `doom sync` で設定を再同期

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（ファイル操作のみ） |
| コミットタイミング | N/A |
| ロールバック条件 | 中断時は手動で doom sync 実行 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回/実行 |
| 目標処理時間 | サブコマンドに依存（1秒〜数分） |
| メモリ使用量上限 | Emacsプロセス標準使用量 |

## 排他制御

- 同時に複数の `doom` コマンドを実行することは推奨されない
- パッケージ操作中は straight のロック機構が働く
- プロファイル同期中は他の doom コマンドを待機させる

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | コマンド開始時 | 使用するEmacs情報、プロファイル名 |
| 進捗ログ | 処理中 | 各処理ステップの状態 |
| 終了ログ | コマンド終了時 | ベンチマーク結果（有効時） |
| エラーログ | エラー発生時 | エラーメッセージ、スタックトレース（デバッグ時） |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | サブコマンド依存 | 標準出力（ベンチマーク表示時） |
| エラー件数 | 1件以上 | 標準エラー出力 |

## 備考

- 本スクリプトはシェルスクリプトとEmacs Lispのポリグロットファイルとして実装されている
- `:;` ハックにより、シェルとElispの両方のインタプリタで正しく解釈される
- POSIX互換性を重視し、特定のシェル（bashなど）に依存しない設計
- `/tmp` が noexec でマウントされている場合でも動作するよう配慮されている
