# 機能設計書 56-新規ウィンドウ

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータの新規ウィンドウ機能(`+new-window`コマンド)の設計仕様を記載する。

### 本機能の処理概要

新規ウィンドウ機能は、プロセス間通信（IPC）を使用して、実行中のGhosttyインスタンスに新しいウィンドウを開くよう要求するCLIコマンドである。ウィンドウマネージャのキーバインドやシェルスクリプトから新規ターミナルウィンドウを開く際に使用される。

**業務上の目的・背景**：ウィンドウマネージャやランチャーから直接ターミナルウィンドウを開く必要がある場面は多い。本機能により、既存のGhosttyインスタンスに対してIPCで新規ウィンドウ作成を要求でき、システムリソースの効率的な利用と高速なウィンドウ起動を実現する。特にGTK環境でD-Bus経由のアクティベーションと連携できる。

**機能の利用シーン**：
- ウィンドウマネージャのグローバルキーバインドからターミナルを起動
- シェルスクリプトからプログラム的に新規ウィンドウを開く
- D-Busアクティベーションによる起動
- 特定のコマンドを実行する新規ウィンドウの作成

**主要な処理内容**：
1. コマンドライン引数の解析（`--class`、`-e`オプション）
2. IPC先の決定（--class指定またはデフォルト検出）
3. new_windowアクションのIPC送信
4. 結果の受信と終了コード決定

**関連システム・外部連携**：D-Bus（GTK環境）、実行中のGhosttyインスタンス

**権限による制御**：特になし。全ユーザーが実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 結果表示画面 | 新規作成されるウィンドウ |

## 機能種別

CLI操作 / IPC通信

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --class | 文字列 | No | カスタムGhosttyインスタンスのクラス名（GTKアプリケーションID） | 有効なGTKアプリケーションID |
| -e | 可変長引数 | No | 新規ウィンドウで実行するコマンドと引数 | -e以降の全引数をコマンドとして解釈 |

### 入力データソース

- コマンドライン引数

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| エラーメッセージ | テキスト | IPC失敗時のエラー情報 |

### 出力先

- 標準エラー出力（stderr）: エラーメッセージ
- 終了コード: 0（成功）または1（エラー）

## 処理フロー

### 処理シーケンス

```
1. コマンドライン引数の解析
   └─ Options構造体に--classと-e引数を設定
2. -e引数の検証
   └─ -eが指定されている場合、後続の引数が存在するか確認
3. IPC先の決定
   └─ --class指定時: 指定されたクラスのインスタンスを対象
   └─ 未指定時: デフォルトのインスタンスを自動検出
4. IPCの実行
   └─ apprt.App.performIpc()でnew_windowアクションを送信
5. 結果の処理
   └─ 成功時: 終了コード0
   └─ 失敗時: エラーメッセージを出力し終了コード1
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[引数解析]
    B --> C{-e指定あり?}
    C -->|Yes| D{引数あり?}
    D -->|No| E["エラー: -e後に引数なし"]
    E --> F[終了コード1]
    D -->|Yes| G[IPC先決定]
    C -->|No| G
    G --> H{--class指定?}
    H -->|Yes| I[指定クラスを対象]
    H -->|No| J[デフォルト検出]
    I --> K[performIpc実行]
    J --> K
    K --> L{成功?}
    L -->|Yes| M[終了コード0]
    L -->|No| N[エラー出力]
    N --> F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-56-1 | クラス形式 | --classはGTKアプリケーションID形式（例: com.mitchellh.ghostty） | --class指定時 |
| BR-56-2 | デフォルトクラス | リリースビルドはcom.mitchellh.ghostty、デバッグビルドはcom.mitchellh.ghostty-debug | --class未指定時 |
| BR-56-3 | D-Busアクティベーション | Ghosttyが実行されていなくても、D-Busが新規インスタンスを起動可能 | GTK環境 |
| BR-56-4 | プラットフォーム制限 | 現在はGTKのみサポート | 常時 |

### 計算ロジック

特になし

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

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

データベース操作なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | 引数不足 | -eが指定されているが後続の引数がない | コマンドを指定 |
| 1 | IPC失敗 | Ghosttyインスタンスとの通信に失敗 | インスタンスの状態を確認 |
| 1 | 未サポート | 現在のプラットフォームでIPCがサポートされていない | GTK環境を使用 |

### リトライ仕様

リトライなし

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

該当なし

## パフォーマンス要件

即座にレスポンスが返ること（通常1秒未満）

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

- D-Busを介した通信はシステムセキュリティポリシーに従う
- 任意のコマンド実行が可能なため、信頼できる環境でのみ使用

## 備考

- GTKのみサポート。macOSでは未サポート
- D-Busアクティベーションが適切に設定されている場合、Ghosttyが実行されていなくても新規ウィンドウを開ける
- バージョン1.2.0から利用可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | new_window.zig | `src/cli/new_window.zig` | Options構造体（9-55行目）でCLIオプションを定義 |
| 1-2 | ipc.zig | `src/apprt/ipc.zig` | Action/Target型（15-54、56行目〜）でIPC構造を定義 |

**読解のコツ**: parseManuallyHook関数（25-43行目）は-e引数の特別な処理を行う。-e以降の全引数をコマンドとして収集。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | new_window.zig | `src/cli/new_window.zig` | run関数（99-110行目）がエントリーポイント |

**主要処理フロー**:
1. **100-101行目**: argsIteratorの取得
2. **103-105行目**: stderrのwriter準備
3. **107行目**: runArgs関数の呼び出し

#### Step 3: メイン処理ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | new_window.zig | `src/cli/new_window.zig` | runArgs関数（112-179行目）でメイン処理 |

**主要処理フロー**:
- **117-126行目**: args.parse()でオプション解析
- **128-144行目**: 診断メッセージの処理
- **146-151行目**: -e引数の検証
- **157-174行目**: apprt.App.performIpc()でIPC実行

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

```
ghostty +new-window
    │
    └─ new_window.run()
           │
           ├─ args.parse() ─ オプション解析
           │      └─ parseManuallyHook() ─ -e引数の特別処理
           │
           └─ runArgs()
                  │
                  └─ apprt.App.performIpc()
                         │
                         ├─ Target解決 ─ クラス指定またはデフォルト検出
                         │
                         └─ Action.new_window ─ 新規ウィンドウ要求
                                │
                                └─ D-Bus通信（GTK環境）
```

### データフロー図

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

コマンドライン ───▶ args.parse() ───────▶ Options
引数                     │                (class, _arguments)
                         ▼
                  parseManuallyHook()
                  (-e引数収集)
                         │
                         ▼
                  performIpc()
                         │
                         ├─▶ Target ─────▶ 対象インスタンス決定
                         │
                         └─▶ Action ────▶ D-Bus経由でIPC送信
                                          │
                                          ▼
                                     新規ウィンドウ作成
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| new_window.zig | `src/cli/new_window.zig` | ソース | メインエントリーポイント |
| ipc.zig | `src/apprt/ipc.zig` | ソース | IPC型定義 |
| apprt.zig | `src/apprt.zig` | ソース | アプリケーションランタイム |
| gtk.zig | `src/apprt/gtk.zig` | ソース | GTKアプリケーション実装 |
| args.zig | `src/cli/args.zig` | ソース | コマンドライン引数解析 |
