機能仕様書: Unity メニュー起動とサンプルワークフロー

## Spec

# 機能仕様書: Unity メニュー起動とサンプルワークフロー

**機能ID**: `SPEC-4ebff657`
**作成日**: 2025-12-04
**ステータス**: 下書き
**入力**: ユーザー説明: "Unity メニューで Start/Stop とサンプルワークフロー実行"

## ユーザーシナリオ＆テスト *(必須)*

### ユーザーストーリー1 - 非開発者でもサーバーを起動・停止したい (優先度: P1)
アート/QA がターミナルなしで Unity メニューから Unity CLI Bridge サーバーを Start/Stop でき、現在のチャネル/ポートが UI で確認できるようにしたい。

**この優先度の理由**: 導入障壁を下げ、非開発者でも自走できることが採用の鍵。

**独立テスト**: メニュー Start→ヘルスチェック成功、Stop→プロセス終了をエディタテストで確認すれば価値成立。

**受け入れシナリオ**:
1. **前提** Unity プロジェクトが開いている、**実行** `Unity CLI Bridge Server → Start`、**結果** 起動しステータス/ポートが UI に表示。
2. **前提** 稼働中、**実行** `Unity CLI Bridge Server → Stop`、**結果** プロセス停止と UI 更新。

---

### ユーザーストーリー2 - すぐ試せるサンプルを実行したい (優先度: P2)
導入直後に「動く例」をワンクリックで体験したい。シーン操作と Addressables 登録のサンプルを実行し、結果がログで確認できること。

**この優先度の理由**: 価値を短時間で示し、チーム合意を得やすくするため。

**独立テスト**: サンプル実行後にデモオブジェクト生成と Addressables 一時登録がログに出れば価値成立。

**受け入れシナリオ**:
1. **前提** サーバー稼働中、**実行** `Run Sample (Scene)`、**結果** デモオブジェクト生成とログ出力。
2. **前提** Addressables 有効、**実行** `Run Sample (Addressables)`、**結果** 一時グループ登録とログ出力。

---

### ユーザーストーリー3 - GUI から設定を切替えたい (優先度: P3)
HTTP/stdio 切替やテレメトリ on/off を GUI で変更し、その設定で起動できるようにしたい。

**独立テスト**: GUI で HTTP ON にして Start、ヘルスチェック成功とポート表示を確認すれば価値成立。

**受け入れシナリオ**:
1. **前提** サーバー停止中、**実行** GUI で HTTP を有効化し Start、**結果** HTTP ポートが UI/ログに表示。
2. **前提** テレメトリ禁止環境、**実行** GUI で Telemetry Off を選択し Start、**結果** 起動ログに「テレメトリ送信なし」が表示。

### エッジケース
- 稼働中に Start を押した場合は重複起動せずステータスを表示。
- Stop 実行時にプロセスが見つからなくても UI をエラーで落とさず再起動ガイドを出す。
- サンプル実行は一時オブジェクト/グループを使い、後処理でクリーンアップする。

## 要件 *(必須)*

### 機能要件
- **FR-001**: Unity メニュー/EditorWindow に Start/Stop ボタンと現在の接続チャネル・ポート表示を提供する。
- **FR-002**: Start 実行後にヘルスチェック結果を UI に表示し、ポート番号を明記する。
- **FR-003**: Stop 実行でサーバープロセスを確実に終了し、UI を停止状態に更新する。
- **FR-004**: Scene サンプル実行でデモオブジェクト生成とログ出力を行い、クリーンアップ手順を提示する。
- **FR-005**: Addressables サンプル実行でテスト用アセットを一時グループに登録し、結果をログ表示する。
- **FR-006**: GUI から HTTP/stdio 切替とテレメトリ On/Off を設定し、Start 時に反映する。
- **FR-007**: すべてのメニュー操作は日本語/英語の人間可読メッセージを返す。

### 主要エンティティ
- **StartupSettings**: transport, httpPort, telemetryEnabled。
- **SampleWorkflow**: Scene/Addressables の実行定義と結果。

## スコープ外
- GUI ログビューアや監視ダッシュボード。
- 自動ロールバックタイマー（手動クリーンアップのみ）。

## 技術制約
- Unity 2020.3 LTS 以降で動作。
- Play 中は Start/Stop を無効化または警告表示。

## 前提条件
- Addressables パッケージが有効（サンプル実行時）。

## 依存関係
- HTTP/stdio/telemetry 設定 (SPEC-a28f3f95) の CLI オプション。

## 成功基準
1. QA メンバーがメニュー操作だけで Start/Stop を 3 回連続成功（ヘルスチェック 200）。
2. Scene/Addressables サンプルが 1 回の操作で成功し、後処理が実行される。
3. GUI で切替えた transport/telemetry 設定が Start 時に正しく反映されることを 3 パターンで確認。

## Plan

# 実装計画: Unity メニュー起動とサンプルワークフロー

**機能ID**: `SPEC-4ebff657` | **日付**: 2025-12-04 | **仕様**: [spec.md](./spec.md)
**入力**: `/specs/SPEC-4ebff657/spec.md` の機能仕様

## 概要
Unity エディタメニューに Unity CLI Bridge Server の Start/Stop と HTTP/stdio/Telemetry 設定切替を追加し、非開発者が GUI で操作できるようにする。導入直後に試せるシーン操作・Addressables 登録のサンプルワークフローを同梱する。

## 技術コンテキスト
**言語/バージョン**: C# (Unity 2020.3+), Node.js 側 CLI 呼び出しをラップ
**主要依存関係**: UnityEditor APIs (MenuItem, EditorWindow), Addressables (サンプル用), 既存 MCP CLI
**ストレージ**: なし（設定は EditorPrefs または ScriptableObject）
**テスト**: Unity playmode/edittime tests (サンプルの副作用確認), node --test で CLI フック
**対象プラットフォーム**: Unity エディタ (Win/Mac)
**プロジェクトタイプ**: Unity package (UnityCliBridge/Packages/unity-cli-bridge/)
**パフォーマンス目標**: Start/Stop ボタン応答 <1s、サンプル実行 <3s
**制約**: Play 中は Start/Stop を無効化または警告
**スケール/スコープ**: GUI 1 画面 + サンプル 2 本

## 憲章チェック
シンプルさ: EditorWindow 1 つ + サンプル2本の最小構成 → OK
アーキテクチャ: 既存 CLI をラップ、独自サーバー実装を増やさない → OK
テスト: edittime で Start/Stop・サンプルの副作用確認を先に書く → 厳守
可観測性: UI 上に状態/ログを表示、ログファイルにも残す → OK
バージョニング: パッケージ minor 追加 (非破壊) → OK

## プロジェクト構造
```
UnityCliBridge/Packages/unity-cli-bridge/
  Editor/McpServerWindow.cs         # Start/Stop, toggles
  Editor/MenuItems.cs               # メニュー登録
  Editor/SampleWorkflows.cs         # シーン/Addressables サンプル
  Tests/Editor/ServerWindowTests.cs # UI/副作用テスト
  Tests/Editor/SampleWorkflowsTests.cs
specs/SPEC-4ebff657/
  spec.md
  plan.md
  research.md
  data-model.md
  quickstart.md
  contracts/gui-behavior.md
  tasks.md
```

## Phase 0: リサーチ (research.md)
- EditorWindow から外部プロセス (npx) を起動する安全な方法（ProcessStartInfo、パス解決）。
- Play Mode 中のメニュー無効化方法。
- Addressables をテスト用に一時グループへ登録し、後処理でクリーンに戻す手順。

## Phase 1: 設計 & 契約
- data-model: StartupSettings, SampleWorkflowResult。
- contracts: GUI 状態遷移、ボタンクリック時の期待結果、サンプルの副作用範囲。
- quickstart: メニュー操作手順とサンプル実行手順。

## Phase 2: タスク計画アプローチ
tasks.md で TDD 順に整理（次フェーズ）。

## Tasks

# タスク: Unity メニュー起動とサンプル (SPEC-4ebff657)

**入力**: plan.md, research.md, data-model.md, contracts/
**前提条件**: Unity 2020.3+ 環境, Addressables 有効 (サンプル用)

## Phase 3.1: セットアップ
- [ ] T201 UnityCliBridge/Packages/unity-cli-bridge/Editor/ に Editor 用フォルダ/asmdef 追加
- [ ] T202 [P] Addressables テスト用一時グループの作成/削除ユーティリティ雛形

## Phase 3.2: テストファースト
- [ ] T203 Tests/Editor/ServerWindowTests.cs に Start/Stop UI の edittime テスト（Play 中無効化含む）
- [ ] T204 [P] Tests/Editor/SampleWorkflowsTests.cs に Scene/Addressables サンプルの副作用テスト（生成→クリーンアップ）

## Phase 3.3: コア実装
- [ ] T205 Editor/McpServerWindow.cs 実装（Start/Stop, 状態表示, toggles）
- [ ] T206 Editor/MenuItems.cs でメニュー登録と Play 中無効化
- [ ] T207 Editor/SampleWorkflows.cs 実装（Scene/Addressables サンプル）

## Phase 3.4: 統合
- [ ] T208 外部プロセス起動/停止連携（npx CLI 呼び出し、ログストリーム）
- [ ] T209 Telemetry/HTTP 設定をウィンドウ設定から CLI に反映

## Phase 3.5: 仕上げ
- [ ] T210 [P] README/quickstart に GUI 手順とサンプル手順を追記
- [ ] T211 [P] 手動スモーク: Start/Stop 3 回、サンプル 2 種実行で成功ログを記録

## 依存関係
- T203,T204 → T205,T207
- T205 → T208,T209

## 並列実行候補
- [P] T202 と T203/T204 並列可
- [P] T210,T211 は実装後並列可

## TDD

_TODO_

## Research

# Research: Unity メニュー起動とサンプル (SPEC-4ebff657)

## 決定
- メニューは `Unity CLI Bridge Server/Start`, `Stop`, `Run Sample (Scene)`, `Run Sample (Addressables)` を追加。
- EditorWindow で状態表示とトグル (HTTP/stdio, Telemetry on/off) を持たせ、設定は EditorPrefs に保存。
- 外部起動は `ProcessStartInfo` で `npx @akiojin/unity-cli` を呼び、ログを Unity コンソールへストリーミング。
- サンプルは既存シーンに影響を与えないよう一時 GameObject/Addressables グループを作成し、実行後にクリーンアップ。

## 未解決/要確認
- Windows 環境での npx パス解決（`cmd /c` 必要性）。
- Addressables 無効プロジェクトでのサンプルスキップ方法（警告表示か自動有効化か）。

## 参考
- Unity Editor coroutines より EditorApplication.update でポーリングし、プロセス終了を検知。
- Play Mode 中のメニュー無効化は `Menu.SetChecked/RemoveMenuItem` ではなく `Validate` 属性で制御。

## Data Model

# Data Model: Unity メニュー起動 & サンプル (SPEC-4ebff657)

## StartupSettings
- transport: `"stdio" | "http" | "both"`
- httpPort: int (optional)
- telemetryEnabled: bool
- lastStartedAt?: ISO datetime

## SampleWorkflowResult
- name: string (scene | addressables)
- success: bool
- message: string
- durationMs: number

## UiState
- isRunning: bool
- activeTransport: string
- portInfo: string
- lastLogLines: string[]

## Quickstart

# Quickstart: Unity メニュー起動 & サンプル

## メニュー起動
1. Unity 上部メニュー `Unity CLI Bridge Server → Start` をクリック。
2. ウィンドウで transport/port/telemetry を設定し、Start を押す。
3. ステータスが "Running" になり、ヘルスチェックが OK と表示される。

## 停止
- `Unity CLI Bridge Server → Stop` をクリック。ステータスが Stopped になり、プロセス終了ログが出る。

## サンプル実行
- Scene サンプル: `Run Sample (Scene)` → デモオブジェクト生成後、ログに結果。
- Addressables サンプル: `Run Sample (Addressables)` → 一時グループ登録とログ出力。

## テレメトリ切替
- ウィンドウの toggle で On/Off を選択し Start。起動ログに telemetry 状態が表示される。

## Contracts

Migrated from local files. See artifact comments below.

## Checklists

Artifact files under `checklists/` are managed in issue comments with `checklist:<name>` entries.

## Acceptance Checklist

- [ ] Add acceptance checklist

機能仕様書: Unity メニュー起動とサンプルワークフロー #75

Description

Spec

機能仕様書: Unity メニュー起動とサンプルワークフロー

ユーザーシナリオ＆テスト (必須)

ユーザーストーリー1 - 非開発者でもサーバーを起動・停止したい (優先度: P1)

ユーザーストーリー2 - すぐ試せるサンプルを実行したい (優先度: P2)

ユーザーストーリー3 - GUI から設定を切替えたい (優先度: P3)

エッジケース

要件 (必須)

機能要件

主要エンティティ

スコープ外

技術制約

前提条件

依存関係

成功基準

Plan

実装計画: Unity メニュー起動とサンプルワークフロー

概要

技術コンテキスト

憲章チェック

プロジェクト構造

Phase 0: リサーチ (research.md)

Phase 1: 設計 & 契約

Phase 2: タスク計画アプローチ

Tasks

タスク: Unity メニュー起動とサンプル (SPEC-4ebff657)

Phase 3.1: セットアップ

Phase 3.2: テストファースト

Phase 3.3: コア実装

Phase 3.4: 統合

Phase 3.5: 仕上げ

依存関係

並列実行候補

TDD

Research

Research: Unity メニュー起動とサンプル (SPEC-4ebff657)

決定

未解決/要確認

参考

Data Model

Data Model: Unity メニュー起動 & サンプル (SPEC-4ebff657)

StartupSettings

SampleWorkflowResult

UiState

Quickstart

Quickstart: Unity メニュー起動 & サンプル

メニュー起動

停止

サンプル実行

テレメトリ切替

Contracts

Checklists

Acceptance Checklist

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions