# Issue #18: チュートリアルと railway init の整合性修正

## 優先度: 高

## 概要

`railway init` 実行後に生成されるプロジェクトと、TUTORIAL.md の手順に不整合がある。チュートリアルでは `railway run hello` を最初に実行するが、実際には `hello` エントリポイントが存在しない。

## 現状の問題

### コード調査結果

`railway/cli/init.py` を確認した結果:

1. **TUTORIAL.md Step 1** の記載:
```markdown
uv run railway run hello
# 期待: "Hello, World!"
```

2. **実際の `railway init` の動作**:
   - `src/hello.py` は `--with-examples` フラグ使用時のみ作成される
   - デフォルトでは**エントリポイントは生成されない**

3. **init後のNext steps表示** (line 675):
```
4. railway new entry hello --example
```
   - ユーザーが手動でentryを作成する必要がある

### 不整合の構造

```
TUTORIAL Step 1: "railway run hello"を実行
      ↓
実際: hello.pyが存在しない → エラー
      ↓
Next steps: "railway new entry hello --example"が必要
      ↓
問題: TUTORIALの「2分でHello World」が達成できない
```

## 解決策の選択肢

### Option A: railway init でhelloエントリポイントを含める（推奨）

`railway init` 実行時に、最小限の動作確認用エントリポイントを自動生成する。

**生成するファイル**:
- `src/main.py` - シンプルな Hello World エントリポイント

```python
# src/main.py
"""Main entry point - Hello World example."""
from railway import entry_point

@entry_point
def main():
    """Simple hello world to verify setup."""
    print("Hello from Railway!")
    return {"status": "success"}
```

**メリット**:
- `railway init` → `uv sync` → `railway run main` が即座に動作
- チュートリアルとの整合性が取れる
- 初回体験がスムーズ

### Option B: チュートリアルを修正

チュートリアル Step 1 を修正して、`railway new entry` を先に実行する手順に変更。

**デメリット**:
- 「2分でHello World」の体験が損なわれる
- 初期段階でコマンドが増える

### Option C: --minimal オプション追加

`railway init --minimal` でhelloなしのプロジェクト生成、デフォルトはhelloを含める。

## 推奨実装（Option A）

### 1. init.py の修正

`railway/cli/init.py` に新しい関数を追加し、`_create_project_structure()` で呼び出す:

**追加する関数**（line 585付近に追加）:
```python
def _create_hello_entry(project_path: Path) -> None:
    """Create minimal hello.py for immediate verification."""
    content = '''"""Hello World entry point."""
from railway import entry_point


@entry_point
def hello():
    """最小限のHello World - セットアップ確認用"""
    print("Hello from Railway!")
    return {"message": "Hello from Railway!"}
'''
    _write_file(project_path / "src" / "hello.py", content)
```

**`_create_project_structure()` の修正**（line 654付近）:
```python
# Create example if requested
if with_examples:
    _create_example_entry(project_path)  # 複雑な例（既存）
else:
    _create_hello_entry(project_path)    # シンプルなhello（新規）
```

**設計意図**:
- デフォルト（`--with-examples`なし）: シンプルな `hello.py` を生成
- `--with-examples`あり: 既存の複雑な例（pipeline使用）を生成

### 2. テスト追加

```python
# tests/unit/cli/test_init_hello.py
def test_init_creates_hello_entry_by_default():
    """railway init should create hello.py by default."""
    with tempfile.TemporaryDirectory() as tmpdir:
        original_cwd = os.getcwd()
        try:
            os.chdir(tmpdir)
            result = runner.invoke(app, ["init", "test_proj"])
            assert result.exit_code == 0

            hello_py = Path(tmpdir) / "test_proj" / "src" / "hello.py"
            assert hello_py.exists()

            content = hello_py.read_text()
            assert "@entry_point" in content
            assert "Hello from Railway!" in content
        finally:
            os.chdir(original_cwd)

def test_init_with_examples_creates_complex_entry():
    """railway init --with-examples should create pipeline example."""
    with tempfile.TemporaryDirectory() as tmpdir:
        original_cwd = os.getcwd()
        try:
            os.chdir(tmpdir)
            result = runner.invoke(app, ["init", "test_proj", "--with-examples"])
            hello_py = Path(tmpdir) / "test_proj" / "src" / "hello.py"
            content = hello_py.read_text()
            assert "pipeline" in content  # 複雑な例にはpipelineが含まれる
        finally:
            os.chdir(original_cwd)
```

### 3. Next steps表示の更新

`_show_success_output()` を修正（line 671付近）:

```python
typer.echo("Next steps:")
typer.echo(f"  1. cd {project_name}")
typer.echo("  2. uv sync --group dev")
typer.echo("  3. cp .env.example .env")
typer.echo("  4. uv run railway run hello  # 動作確認")
typer.echo("  5. Open TUTORIAL.md and follow the guide")
```

### 4. チュートリアル確認

修正後、以下のフローが動作することを確認:

```bash
railway init my_project
cd my_project
uv sync --group dev
cp .env.example .env
uv run railway run hello  # → "Hello from Railway!" が表示される
```

## 受け入れ条件

- [ ] `railway init` 後、`uv run railway run hello` が即座に動作する
- [ ] 出力が「Hello from Railway!」
- [ ] TUTORIAL.md の Step 1 と実際の動作が一致する
- [ ] Next steps の表示を更新する
- [ ] `--with-examples` 使用時は既存の複雑な例が生成される
- [ ] テストが全てパスする

## 修正対象ファイル

1. `railway/cli/init.py`
   - `_create_hello_entry()` 関数追加
   - `_create_project_structure()` 修正
   - `_show_success_output()` 修正

2. `tests/unit/cli/test_init_hello.py` (新規)
   - デフォルトでhello.py生成のテスト
   - --with-examplesで複雑な例生成のテスト

## 関連

- レビュー3（2026-01-19）: セットアップ体験 7/10
- チュートリアル Step 1: Hello World
- Issue #21: 対応不要に（TUTORIALは--exampleなしで実行するため）
