# コード生成器修正など (v0.13.1) 実装計画

**目的**: `railway new entry` で生成されるテンプレートを v0.13.0 対応に更新し、**1コマンドで動作するプロジェクト**を生成する

**バージョン**: v0.13.1

---

## 背景

v0.13.0 で終端ノードの型安全性が強化されたが、コード生成器のテンプレートが更新されていない。
そのため、`railway new entry` で生成されるコードがランタイムエラーを引き起こす。

**ユーザー体験の問題**:
```bash
railway new entry greeting
railway sync transition --entry greeting
railway run greeting
# → LegacyExitFormatError: レガシー exit 形式 'exit::green::success' は v0.12.3 で廃止されました
```

**期待される体験（改善後）**:
```bash
railway new entry greeting
# → 自動で sync も実行され、すぐに run 可能

railway run greeting
# → 正常に動作（1コマンドで準備完了）
```

---

## Issue 一覧と依存関係

```
         #60 (YAMLテンプレート新形式化) ←── P0: 最優先
           ↓
    ┌──────┴──────┐
    ↓             ↓
  #61           #62
(エントリ     (終端ノード
 ポイント)     自動生成)
    └──────┬──────┘
           ↓
         #64 (new entry に sync 統合) ←── P0: UX改善
           ↓
         #65 (ドキュメント更新) ←── P2: 仕上げ
```

### Issue 一覧

| Issue | 優先度 | 内容 | 依存 |
|-------|--------|------|------|
| #60 | P0 | YAMLテンプレートを新形式に更新 | なし |
| #61 | P1 | エントリポイントテンプレート更新（run()使用） | #60 |
| #62 | P1 | 終端ノードスケルトン生成の統合 | #60 |
| #64 | P0 | `railway new entry` に sync を統合（デフォルト化） | #60, #61, #62 |
| #65 | P2 | ドキュメント更新（readme.md, TUTORIAL.md） | #64 |

**スコープ外**:
- #63（オフラインドキュメント）は v0.13.2 以降で対応

---

## 問題点と改善内容

### 問題1: YAMLテンプレートがレガシー形式 (#60)

**現状** (`_get_dag_yaml_template()`):
```yaml
exits:
  success:
    code: 0
transitions:
  start:
    success::done: exit::success  # ← v0.12.3で廃止
```

**改善後**:
```yaml
nodes:
  start:
    description: "開始ノード"
  exit:
    success:
      done:
        description: "正常終了"

transitions:
  start:
    success::done: exit.success.done  # ← 新形式
```

### 問題2: エントリポイントが同期されない (#61)

**現状** (`_get_dag_entry_template()`):
```python
from nodes.{name}.start import start  # ← YAML と二重管理
result = dag_runner(start=start, transitions=TRANSITIONS)
```

**改善後**:
```python
from _railway.generated.{name}_transitions import run
result = run({})  # ← シンプル
```

### 問題3: 終端ノードの手動作成が必要 (#62)

**現状**:
- `sync_exit_nodes()` が `sync.py` に存在するが、`railway new entry` からは呼ばれない

**改善後**:
- `railway new entry` で終端ノードスケルトンも同時生成
- 既存の `sync_exit_nodes()` を活用

### 問題4: sync が自動実行されない (#64)

**現状**:
```bash
railway new entry greeting    # YAML のみ生成
railway sync transition ...   # 手動で sync 必要
railway run greeting          # やっと実行可能
```

**改善後（デフォルト動作を変更）**:
```bash
railway new entry greeting    # sync も自動実行
railway run greeting          # すぐに実行可能
```

---

## 設計方針

### 既存コードとの整合性

| 既存関数 | 変更内容 |
|----------|----------|
| `_get_dag_yaml_template()` | 新形式に更新（#60） |
| `_get_dag_entry_template()` | `run()` 使用形式に更新（#61） |
| `sync_exit_nodes()` | `railway new entry` から呼び出し可能に（#62） |
| `_create_dag_entry()` | sync 自動実行を追加（#64） |

### デフォルト動作の変更

**理由**: `railway new entry` は新規プロジェクト作成なので、後方互換性の考慮は不要。
ユーザー体験を優先し、**sync をデフォルトで実行**する。

```bash
# デフォルト（推奨）
railway new entry greeting
# → YAML + ノード + sync + エントリポイント すべて生成

# 上級者向け（sync スキップ）
railway new entry greeting --no-sync
# → YAML + ノード のみ生成、後で手動 sync
```

### 関数型パラダイムの徹底

- テンプレート生成は純粋関数（副作用なし）
- ファイル書き込みは明確に分離された副作用関数
- `while` ループは末尾再帰または `itertools` で置換

---

## 受け入れ条件

### 機能要件
- [ ] `railway new entry greeting && railway run greeting` が正常動作
- [ ] 生成される YAML が新形式（`nodes.exit`, `exit.success.done`）
- [ ] 終端ノードスケルトンが自動生成される
- [ ] `--no-sync` オプションで sync スキップ可能

### E2E テスト（必須）
- [ ] 生成されたコードが型チェック（mypy）を通過
- [ ] 生成されたコードがリント（ruff）を通過
- [ ] 完全なワークフロー（init → new entry → run）が動作

### ドキュメント（#65）
- [ ] `readme.md` が v0.13.1 の変更を反映
- [ ] `TUTORIAL.md` テンプレートが新形式を使用
- [ ] レガシー形式（`exit::success`）がサンプルコードに含まれない

### TDD・関数型パラダイム
- [ ] 全 Issue で Red → Green → Refactor フェーズに従う
- [ ] 純粋関数と副作用関数の分離
- [ ] イミュータブルデータ構造の使用
- [ ] 全テスト通過

---

## 推奨ユーザーフロー

### 新規ユーザー（デフォルト）
```bash
railway init my_project
cd my_project
railway new entry my_workflow    # ← 1コマンドで準備完了
railway run my_workflow          # ← すぐに動作
```

### 上級ユーザー（カスタマイズ）
```bash
railway new entry my_workflow --no-sync  # YAML とスケルトンのみ生成
# YAML を編集してノード追加
railway sync transition --entry my_workflow
railway run my_workflow
```
