# バッチ設計書 8-doom env

## 概要

本ドキュメントは、シェル環境から環境変数ファイルを生成するCLIコマンド`doom env`の設計仕様を定義するものである。

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

`doom env`は、現在のシェル環境から環境変数をスクレイピングし、EmacsがシェルのPATHやその他の環境変数を正しく継承できるようにするためのファイルを生成するコマンドである。特にmacOSや一部のLinux環境で、EmacsがGUIから起動された際に正しい環境変数を取得できない問題を解決する。

**業務上の目的・背景**：macOSでは、GUIアプリケーション（Emacs.appなど）はログインシェルの環境変数を継承しない。これにより、ターミナルで設定したPATH、GOPATH、pyenv、nvm等の環境変数がEmacsから見えなくなる問題が発生する。`exec-path-from-shell`パッケージはこの問題を解決するが、起動時にシェルを起動するため遅くなる。`doom env`は事前に環境変数をファイルに保存することで、起動時のオーバーヘッドなしに問題を解決する。

**バッチの実行タイミング**：以下の場合に実行が推奨される：
- 初回インストール時（doom installで自動実行）
- シェル環境変数を変更した後
- .bashrc/.zshrc等を編集した後
- doom syncで自動実行（ファイルが存在する場合のみ）

**主要な処理内容**：
1. 現在のprocess-environmentを取得
2. doom-env-denyリストで除外する環境変数をフィルタリング
3. doom-env-allowリストで明示的に許可する環境変数を追加
4. 結果をLisp形式で環境変数ファイルに書き込み

**前後の処理との関連**：`doom install`で生成、`doom sync`で再生成（既存時のみ）、`doom env clear`で削除。

**影響範囲**：doom-env-file（プロファイルディレクトリ内）、Emacs起動時の環境変数。

## バッチ種別

環境設定 / 設定ファイル生成

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（環境変更時） |
| 実行時刻 | ユーザー任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動 または doom sync/install からの呼び出し |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| シェル環境 | 正しい環境変数が設定されたシェルから実行すること |
| 書き込み権限 | 出力先ディレクトリへの書き込み権限があること |

### 実行可否判定

1. 出力先ディレクトリが存在し、書き込み可能であること

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --allow-all | フラグ | No | false | 全ての環境変数を許可 |
| --deny-all | フラグ | No | false | 全ての環境変数を拒否 |
| -o | パス | No | doom-env-file | 出力先ファイルパス |
| -a, --allow | 正規表現 | No | なし | 許可する環境変数パターン（複数指定可） |
| -d, --deny | 正規表現 | No | なし | 拒否する環境変数パターン（複数指定可） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| process-environment | リスト | 現在のシェル環境変数 |
| doom-env-deny | 正規表現リスト | デフォルトで除外する変数 |
| doom-env-allow | 正規表現リスト | 明示的に許可する変数 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| doom-env-file | Emacs Lisp | 環境変数のリスト |
| 標準出力 | テキスト | 生成進捗とステータス |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | カスタマイズ可能（デフォルト: doom-env-file） |
| 出力先 | プロファイルディレクトリ |
| 文字コード | UTF-8-unix |
| 形式 | Lispリスト（"KEY=VALUE" 形式の文字列） |

## 処理フロー

### 処理シーケンス

```
1. 出力ファイルパスの決定
   └─ -o オプションまたは doom-env-file

2. ファイルヘッダーの生成
   └─ mode: lisp-interaction
   └─ 自動生成警告コメント
   └─ 編集可否に関する注意事項

3. 許可/拒否リストの構築
   └─ doom-env-deny をベースに
   └─ --allow-all, --deny-all の適用
   └─ -a, -d オプションの適用
   └─ doom-env-allow による上書き

4. 環境変数のフィルタリング
   └─ 各環境変数を拒否リストでチェック
   └─ 拒否された場合、許可リストでオーバーライド確認
   └─ 許可された変数のみ出力

5. ファイルの書き込み
   └─ with-temp-file でアトミック書き込み
   └─ prin1-to-string で適切にエスケープ
```

### フローチャート

```mermaid
flowchart TD
    A[doom env 開始] --> B[出力パス決定]
    B --> C[ヘッダー生成]
    C --> D[許可/拒否リスト構築]
    D --> E[process-environment 反復]
    E --> F{拒否リストにマッチ?}
    F -->|Yes| G{許可リストにマッチ?}
    F -->|No| H[変数を出力に追加]
    G -->|Yes| I[ログ: allow]
    G -->|No| J[ログ: deny]
    I --> H
    J --> K[スキップ]
    H --> L{次の変数あり?}
    K --> L
    L -->|Yes| E
    L -->|No| M[ファイル書き込み]
    M --> N[成功メッセージ出力]
    N --> O[終了]
```

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

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

本コマンドはデータベースを使用しない。

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 非ゼロ | 書き込みエラー | 出力先に書き込めない | パーミッション確認 |
| user-error | ファイル不在 | doom env clear 時にファイルが存在しない | 無視可能 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

1. 出力先ディレクトリの存在とパーミッションを確認
2. -o オプションで別の出力先を指定して試行

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | ファイル書き込み全体 |
| コミットタイミング | with-temp-file 完了時 |
| ロールバック条件 | エラー時は元のファイルが保持される |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 環境変数数（通常数十〜数百） |
| 目標処理時間 | 1秒以内 |
| メモリ使用量上限 | 最小限（環境変数リスト分） |

## 排他制御

- 同時に複数の`doom env`を実行しても、with-temp-fileにより安全

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | コマンド開始時 | "Regenerating/Generating envvars file" |
| デバッグログ | 各変数処理時 | "cli:env: allow/deny VARNAME" |
| 成功ログ | コマンド完了時 | "Generated PATH" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| N/A | N/A | 監視対象外 |

## 備考

- デフォルトで除外される環境変数（doom-env-deny）：
  - HOME, PWD, OLDPWD, SHLVL, PS1, PROMPT, TERM, TERMCAP, USER
  - DISPLAY, WAYLAND_DISPLAY, DBUS_SESSION_BUS_ADDRESS, XAUTHORITY
  - WSL_INTEROP
  - XDG_CURRENT_DESKTOP, XDG_RUNTIME_DIR, XDG_VTNR, XDG_SEAT, XDG_BACKEND, XDG_SESSION_*
  - *SOCK, *SOCKET（ソケット関連）
  - SSH_AUTH_SOCK, SSH_AGENT_PID, SSH_TTY, GPG_TTY, GPG_AGENT_INFO
  - DEBUG, INSECURE, EMACSDIR, DOOMDIR, DOOMLOCALDIR, DOOMPATH, DOOMPROFILE, __*
- `exec-path-from-shell`よりも高速（起動時にシェルを起動しない）
- `-o`オプションで別のファイルに出力した場合、手動で`doom-load-envvars-file`で読み込む必要がある
- `doom env clear`サブコマンドで環境変数ファイルを削除可能
