# API設計書

## 概要

本ドキュメントは、Doom Emacs（doomemacs-master）のコマンドラインインターフェース（CLI）APIについて記載します。Doom EmacsはEmacs Lisp設定フレームワークであり、従来のHTTP/REST APIは存在しません。代わりに、`bin/doom`コマンドを通じてアクセスできるCLI APIを提供しています。

本CLI APIは`lisp/doom-cli.el`で定義されたDSL（`defcli!`マクロ）を使用して実装されており、パッケージ管理、診断、設定同期などの機能を提供します。

## 共通仕様

### ベースコマンド

```
doom [OPTIONS] <COMMAND> [ARGS]
```

または

```
~/.config/emacs/bin/doom [OPTIONS] <COMMAND> [ARGS]
```

### 認証方式

CLIコマンドに認証は不要です。ただし、システム権限（ファイルシステムへのアクセス権）が必要です。rootユーザーでの実行は推奨されません。

### 共通オプション

| オプション | 短縮形 | 説明 |
| --- | --- | --- |
| `--force` | `-!` | プロンプトを抑制し、自動的に承諾する |
| `--debug` | `-D` | デバッグ出力を有効化 |
| `--verbose` | `-v` | 詳細出力を有効化 |
| `--doomdir DIR` | - | 指定したDIRのDoom設定を使用 |
| `--emacsdir DIR` | - | 指定したDIRのDoomインストールを使用 |
| `--pager CMD` | - | 大量出力用のページャーコマンドを指定 |
| `--profile NAME` | - | 指定したプロファイルを使用 |
| `--benchmark` | - | ベンチマークを常に表示 |
| `--color` | - | ANSIカラーコードの使用を制御 |
| `--load FILE` | `-L` | 指定したElispファイルをコマンド実行前にロード |
| `--eval FORM` | `-E` | 指定したElispフォームをコマンド実行前に評価 |

### 共通終了コード

| 終了コード | 説明 |
| --- | --- |
| 0 | 正常終了 |
| 1 | エラーは発生していないがコマンドを完了できなかった |
| 2 | 一般的な内部エラー |
| 3 | Emacs/Doomのインストールまたは実行コンテキストのエラー |
| 4 | ユーザー入力エラー |
| 5 | コマンドが見つからない、または不正/非推奨 |
| 6 | オプション/引数が無効、不足、または過剰 |
| 7-15 | Doom予約 |
| 16-192 | ユーザー拡張用予約 |
| 254 | 正常終了（動的生成されたアフタースクリプトを実行） |
| 255 | キャッチされていない重大エラー |

### 環境変数

| 変数名 | 説明 |
| --- | --- |
| `EMACS` | Emacs操作に使用するEmacs実行可能ファイルまたはコマンド |
| `EMACSDIR` | Doom Emacsのインストール場所（デフォルト: ~/.config/emacs または ~/.emacs.d） |
| `DOOMDIR` | Doomのプライベート設定の場所（デフォルト: ~/.config/doom または ~/.doom.d） |
| `DOOMPAGER` | 大量出力用のページャー（デフォルト: "less +g"） |
| `DOOMPROFILE` | アクティブにするDoomプロファイル（デフォルト: "_@0"） |
| `DOOMPROFILELOADFILE` | プロファイルローダースクリプトのパス |
| `DOOMPROFILELOADPATH` | プロファイル設定ファイルの検索パス（コロン区切り） |

## CLI一覧

| カテゴリ | コマンド | エイリアス | 説明 |
| --- | --- | --- | --- |
| ルート | doom | - | Doom EmacsのCLIエントリーポイント |
| ルート | doom version | doom v | バージョン情報を表示 |
| ルート | doom help | doom h | ヘルプを表示 |
| 診断 | doom doctor | doom doc | システムの診断を実行 |
| 情報 | doom info | - | 設定の詳細情報を出力 |
| 設定管理 | doom sync | doom s | 設定をDoom Emacsと同期 |
| 設定管理 | doom upgrade | doom up | Doomコアとパッケージを更新 |
| 設定管理 | doom env | - | 環境変数ファイルを生成 |
| 設定管理 | doom gc | - | 不要なパッケージとキャッシュを削除 |
| 設定管理 | doom install | - | Doom Emacsの初期インストールを実行 |
| プロファイル | doom profile | doom pf | プロファイル管理コマンド |
| プロファイル | doom profile sync | - | プロファイルをDoomと同期 |
| 開発 | doom emacs | - | Doom EmacsまたはEmacsサンドボックスを起動 |
| 開発 | doom ci | - | CI関連コマンド |
| 開発 | doom make | - | ビルド関連コマンド |

## 各CLIエンドポイント定義

### 診断コマンド

#### 1. doom doctor

システムとDoom設定の診断を実行し、一般的な問題を検出します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| コマンド | `doom doctor` |
| エイリアス | `doom doc` |
| 認証 | 不要 |
| 権限 | ファイルシステム読み取り権限 |

**パラメータ**

パラメータなし

**実行例**

```bash
doom doctor
```

**出力（成功時）**

```
The doctor will see you now...

> Checking your Emacs version...
> Checking for Doom's prerequisites...
> Checking for your private config...
...
```

**出力（問題検出時）**

```
The doctor will see you now...

> Checking your Emacs version...
! Emacs 27 is supported, but not for long!
  Doom will drop 27.x support sometime mid-2025...
```

---

#### 2. doom info

バグレポート用の詳細な設定情報を出力します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| コマンド | `doom info` |
| 認証 | 不要 |
| 権限 | ファイルシステム読み取り権限 |

**オプション**

| オプション | 説明 |
| --- | --- |
| `--json` | JSON形式で出力 |
| `--lisp` | Lisp形式で出力 |

**実行例**

```bash
doom info
doom info --json
doom info --lisp
```

**出力（成功時・テキスト形式）**

システム情報、Emacsバージョン、有効なモジュール一覧などが表示されます。

**出力（成功時・JSON形式）**

```json
{
  "emacs": {
    "version": "30.2",
    ...
  },
  "doom": {
    "version": "3.0.0",
    ...
  }
}
```

---

### 設定管理コマンド

#### 3. doom sync

設定をDoom Emacsと同期します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| コマンド | `doom sync` |
| エイリアス | `doom s` |
| 認証 | 不要 |
| 権限 | ファイルシステム読み書き権限 |

**オプション**

| オプション | 短縮形 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- | --- |
| - | `-e` | flag | - | - | 環境変数ファイルを再生成しない |
| - | `-u` | flag | - | - | 同期後にすべてのパッケージを更新 |
| - | `-U` | flag | - | - | パッケージを更新しない |
| `--gc` | - | flag | - | - | 孤立したパッケージリポジトリを削除 |
| `--jobs` | `-j` | int | - | CPU数 | ネイティブコンパイル用のスレッド数 |
| `--rebuild` | `-b` | flag | - | - | すべてのパッケージを無条件で再ビルド |
| - | `-B` | flag | - | - | ホスト名またはEmacsバージョンが変更されてもパッケージを再ビルドしない |
| `--aot` | - | flag | - | - | ネイティブコンパイルを事前に実行 |

**実行例**

```bash
doom sync
doom sync -u
doom sync --rebuild
doom sync -j 4 --aot
```

**出力（成功時）**

```
> Using Emacs 30.2 @ /usr/local/bin/emacs
> Synchronizing "default" profile...
  > Regenerating envvars file...
  > Installing packages...
  ...
```

---

#### 4. doom upgrade

Doomのコア、モジュールライブラリ、インストール済みパッケージを更新します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| コマンド | `doom upgrade` |
| エイリアス | `doom up` |
| 認証 | 不要 |
| 権限 | ファイルシステム読み書き権限、ネットワークアクセス |

**オプション**

| オプション | 短縮形 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- | --- |
| `--aot` | - | flag | - | - | ネイティブコンパイルを事前に実行 |
| `--packages` | `-p` | flag | - | - | パッケージのみを更新（Doomは更新しない） |
| `--jobs` | `-j` | int | - | CPU数 | ネイティブコンパイル用のCPU数 |
| - | `-B` | flag | - | - | ホスト名またはEmacsバージョンが変更されてもパッケージを再ビルドしない |

**実行例**

```bash
doom upgrade
doom upgrade --packages
doom upgrade -j 8
```

**出力（成功時）**

```
> Preparing to upgrade Doom Emacs and its packages...
> Pulling latest changes from remote...
...
> Finished upgrading Doom Emacs
```

---

#### 5. doom env

環境変数ファイルを生成または再生成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| コマンド | `doom env` |
| 認証 | 不要 |
| 権限 | ファイルシステム読み書き権限 |

**オプション**

| オプション | 短縮形 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- | --- |
| `--allow-all` | - | flag | - | - | すべての環境変数を許可 |
| `--deny-all` | - | flag | - | - | すべての環境変数を拒否 |
| `-o` | - | path | - | - | 非標準パスに出力 |
| `--allow` | `-a` | regexp | - | - | 指定した正規表現にマッチする環境変数を許可 |
| `--deny` | `-d` | regexp | - | - | 指定した正規表現にマッチする環境変数を拒否 |

**実行例**

```bash
doom env
doom env -o /path/to/envfile.el
doom env --allow "^JAVA_HOME$"
```

**出力（成功時）**

```
> Generating envvars file
  Generated /path/to/.local/env
```

---

#### 6. doom gc

孤立したパッケージ、ビルド成果物、ログファイルを削除します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| コマンド | `doom gc` |
| 認証 | 不要 |
| 権限 | ファイルシステム読み書き権限 |

**オプション**

| オプション | 説明 |
| --- | --- |
| `-b` | ビルドディレクトリを削除しない |
| `-e` | ELPAパッケージを削除しない |
| `-g` | リポジトリを再グラフトしない |
| `-p` | 孤立したパッケージリポジトリを削除しない |
| `-r` | 孤立したパッケージリポジトリを削除しない |

**実行例**

```bash
doom gc
doom gc -begpr
```

**出力（成功時）**

```
> Purging straight builds...
  Purged build/some-package
> Purging straight repositories...
  Purged repos/orphan-repo
```

---

#### 7. doom install

Doom Emacsの初期インストールとセットアップを実行します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| コマンド | `doom install` |
| 認証 | 不要 |
| 権限 | ファイルシステム読み書き権限、ネットワークアクセス |

**オプション**

| オプション | 型 | 説明 |
| --- | --- | --- |
| `--aot` | flag | ネイティブコンパイルを事前に実行 |
| `--config` | flag/bool | `$DOOMDIR`またはダミーファイルを作成するか |
| `--env` | flag | 環境変数ファイルを再生成するか |
| `--install` | flag/bool | パッケージを自動インストールするか |
| `--hooks` | flag/bool | Doomのgitフックをデプロイするか |

**実行例**

```bash
doom install
doom install --env
doom install --no-config
```

**出力（成功時）**

```
Installing Doom Emacs!

> Created ~/.config/doom
> Creating ~/.config/doom/init.el...
  Done!
> Creating ~/.config/doom/config.el...
  Done!
...
```

---

### プロファイル管理コマンド

#### 8. doom profile

プロファイル管理のルートコマンドです。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| コマンド | `doom profile` |
| エイリアス | `doom pf` |
| 認証 | 不要 |
| 権限 | ファイルシステム読み取り権限 |

---

#### 9. doom profile sync

プロファイルをDoomと同期します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| コマンド | `doom profile sync` |
| 認証 | 不要 |
| 権限 | ファイルシステム読み書き権限 |

**オプション**

| オプション | 説明 |
| --- | --- |
| `--all` | すべての既知のプロファイルを同期 |
| `--reload` | 最新であってもプロファイルロードファイルを強制的にリロード |

**実行例**

```bash
doom profile sync --all
doom profile sync --all --reload
```

**出力（成功時）**

```
> Synchronizing 3 known profiles...
  > Added "work"
  > Changed "default"
  > Regenerated profile loader: /path/to/load.el
```

---

### 開発コマンド

#### 10. doom emacs

Doom Emacsまたはサンドボックス環境でEmacsを起動します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| コマンド | `doom emacs` |
| 認証 | 不要 |
| 権限 | ファイルシステム読み取り権限 |

**オプション**

| オプション | 説明 |
| --- | --- |
| `--repl` | Elisp REPLを起動 |

**パススルー引数**

任意の追加引数はEmacsに直接渡されます。

**実行例**

```bash
doom emacs
doom emacs --repl
doom emacs -- --eval "(message \"hello\")"
```

**出力（成功時・REPL）**

```
(elisp) $ (+ 1 2)
3
(elisp) $ :quit
Goodbye!
```

---

## Emacs Lisp API

Doom Emacsは、Emacs Lispプログラムからアクセスできる内部APIも提供しています。主要なマクロと関数は以下の通りです：

### CLI定義マクロ

| マクロ/関数 | 説明 |
| --- | --- |
| `defcli!` | 新しいCLIコマンドを定義 |
| `defcli-group!` | CLIコマンドをグループ化 |
| `defcli-autoload!` | 遅延ロードCLIコマンドを定義 |
| `defcli-alias!` | CLIコマンドのエイリアスを定義 |
| `defcli-obsolete!` | 非推奨CLIコマンドを定義 |
| `defcli-stub!` | 未実装CLIコマンドのスタブを定義 |

### CLIコンテキスト関数

| 関数 | 説明 |
| --- | --- |
| `doom-cli-execute` | CLIコマンドを実行 |
| `doom-cli-context-parse` | コマンドライン引数をパース |
| `doom-cli-context-get` | コンテキストから値を取得 |
| `doom-cli-context-put` | コンテキストに値を設定 |

### 引数タイプ

CLIコマンドでは以下の引数タイプが使用可能です：

| タイプ | 説明 |
| --- | --- |
| `dir` | 既存ディレクトリへのパス |
| `file` | 既存ファイルへのパス |
| `path` | 任意のパス |
| `int` | 整数 |
| `num` | 数値（浮動小数点を含む） |
| `float` | 浮動小数点数 |
| `bool` | ブール値（yes/no, true/false, on/off, 1/0） |
| `date` | 日付（YYYY-MM-DD形式） |
| `time` | 時刻 |
| `duration` | 期間（例: 5h 20m 40s） |
| `size` | ファイルサイズ（例: 5mb, 10kb） |
| `form` | Elispフォーム |
| `regexp` | 正規表現 |

## 備考

1. **HTTP APIの不在**: Doom EmacsはWebアプリケーションフレームワークではなく、Emacs設定フレームワークです。そのため、HTTP/REST/GraphQL等のWebAPIは存在しません。

2. **拡張性**: ユーザーは`$DOOMDIR/cli.el`または`.doomrc`ファイルで独自のCLIコマンドを定義できます。

3. **モジュールCLI**: 各Doomモジュールは独自のCLIコマンドを`cli.el`ファイルで定義できます。これらは`doom +<module>`形式でアクセスできます。

4. **非推奨コマンド**: 以下のコマンドは非推奨となっています：
   - `doom build` -> `doom sync --rebuild`
   - `doom purge` -> `doom gc`
   - `doom run` -> `doom emacs`
   - `doom profiles sync` -> `doom profile sync --all`

5. **未実装コマンド（スタブ）**:
   - `doom module`
   - `doom nuke`
   - `doom package`
   - `doom rollback`
   - `doom test`
   - `doom profile hash`
   - `doom profile new`
   - `doom profile archive`
   - `doom profile remove`
   - `doom profile rename`
   - `doom profile nuke`
