feat: PLAN32-docs ドキュメントと CHANGELOG

CHANGELOG.md

@@ -4,7 +4,32 @@
 
 ## [Unreleased]
 
+### Changed
+- **1 プロジェクト = 1 コンテナ = 複数リポジトリ**に対応しました。プロジェクトが開発対象と
+ するリポジトリは `projects/<name>/project.yml` の `repos` 配列で指定し、すべてが同じ
+ コンテナの `/work` 配下へ clone されます。リポジトリごとに Git ホスト・オーナー・
+ ブランチ・clone 先ディレクトリ名・`init.sh` の実行有無を指定できます。関連する複数
+ リポジトリ (本体・ドキュメント・インフラ等) を 1 つの開発環境で横断的に扱えます。
+ リポジトリが 2 件以上あるときは、全リポジトリを含む multi-root ワークスペース
+ `/work/<プロジェクト名>.code-workspace` を生成してエディタで開きます。
+ 詳細は [project.yml リファレンス](docs/user/project-yml.md) を参照してください。
+- **プロジェクト設定を `env` から `project.yml` へ移しました (破壊的変更)。**
+ `GIT_USER` / `GIT_REPO` / `GIT_HOST` / `WORK_DIR` / `CONTAINER_SCALE` /
+ `DEVBASE_OPEN_EDITOR` は `project.yml` の `repos` / `work_dir` / `scale` /
+ `open_editor` に移行しました。`env` は「コンテナへ渡す環境変数」だけを持ちます。
+ 配列を表現できない環境変数では複数リポジトリを書けないためです。
+ `project.yml` を持たないプロジェクトは `devbase up` が移行手順を案内して停止します
+ (旧形式へ暗黙にフォールバックすると、移行漏れを検出できないため)。
+ `devbase project scale N` の書き込み先も `project.yml` の `scale` になります。
+
+> **Note:** リポジトリの clone は `entrypoint.sh` で行われ、これはイメージに焼き込まれます。
+> 適用には `devbase build --no-cache` によるベースイメージの再ビルドが必要です。
+
 ### Added
+- **`devbase project migrate-config`** を追加しました。旧 `env` 形式のプロジェクト定義を
+ `project.yml` へ機械的に変換します。`--dry-run` で変換結果を確認でき、既存の
+ `project.yml` は上書きしないため何度実行しても同じ状態に収束します。
+ 変換対象は上記 6 キーのみで、`ENABLE_SSH` などそれ以外は `env` に残ります。
 - **tmux 内では `VSCODE_IPC_HOOK_CLI` が古くても VS Code を自動で開く**ようにしました。
  tmux サーバーはセッション作成時の環境変数を保持し続けますが、`update-environment` に
  登録した変数は attach のたびに更新されるため、**ペインのシェルは古い値・tmux の

README.md

@@ -144,6 +144,7 @@ devbaseのコマンドは4つのグループにまとめられています。
 | [はじめに](docs/user/getting-started.md) | 前提条件、初回セットアップ、日常ワークフロー |
 | [CLIリファレンス](docs/user/cli-reference/README.md) | 全コマンドの構文・オプション・使用例（コマンドグループ別） |
 | [プラグインレジストリ](docs/user/plugin-registries.md) | 公開・社内レジストリの一覧と追加方法 |
+| [project.yml リファレンス](docs/user/project-yml.md) | プロジェクト設定（複数リポジトリ・scale・エディタ） |
 | [環境変数ガイド](docs/user/environment-variables.md) | 3レベル構造、コレクター、ソース同期 |
 | [環境変数の export/import ガイド](docs/user/env-export-import.md) | バンドル形式・age 暗号化・S3 連携・merge/replace の運用 |
 | [コンテナ操作ガイド](docs/user/container-operations.md) | ライフサイクル、並行開発、ボリューム構造 |

docs/README.md

@@ -45,6 +45,7 @@ graph TD
 | [はじめに](user/getting-started.md) | 前提条件、初回セットアップ、日常ワークフロー |
 | [CLI リファレンス](user/cli-reference/README.md) | 全コマンドの構文・オプション・使用例 |
 | [プラグインレジストリ](user/plugin-registries.md) | 公開・社内レジストリの一覧と追加方法 |
+| [project.yml リファレンス](user/project-yml.md) | プロジェクト設定（複数リポジトリ・scale・エディタ） |
 | [環境変数ガイド](user/environment-variables.md) | 3レベル構造、コレクター、ソース同期 |
 | [環境変数の暗号化](user/env-encryption.md) | 認証情報を暗号化して保存する / 鍵とチーム共有 / 平文へ戻す |
 | [コンテナ操作ガイド](user/container-operations.md) | ライフサイクル、並行開発、ボリューム構造 |
@@ -101,6 +102,7 @@ docs/
 │ │ ├── 04-plugin.md ← plugin グループ
 │ │ └── 05-snapshot.md ← snapshot グループ
 │ ├── plugin-registries.md ← プラグインレジストリ
+│ ├── project-yml.md ← project.yml リファレンス
 │ ├── environment-variables.md ← 環境変数ガイド
 │ ├── env-encryption.md ← 環境変数の暗号化
 │ ├── container-operations.md ← コンテナ操作ガイド
@@ -128,6 +130,7 @@ docs/
 | 環境変数を設定する | [環境変数ガイド](user/environment-variables.md#環境変数の操作) |
 | 認証情報を暗号化して保存する | [環境変数の暗号化](user/env-encryption.md) |
 | 複数コンテナで並行開発する | [コンテナ操作ガイド](user/container-operations.md#並行開発) |
+| 1 つのコンテナで複数リポジトリを扱う | [project.yml リファレンス](user/project-yml.md#複数リポジトリ) |
 | データをバックアップ・復元する | [スナップショットガイド](user/snapshot-guide.md) |
 | エラーが発生した | [トラブルシューティング](user/troubleshooting.md) |
 | 旧 Orca 接続から移行する | [Orca 削除の移行ガイド](user/orca-removal-migration.md) |

docs/developer/architecture.md

@@ -139,6 +139,26 @@ flowchart LR
 
 `snapshot/manager.py` の `SnapshotManager` クラスが全機能を提供する。差分バックアップとフルバックアップに対応し、zstd 圧縮を使用する。
 
+### project/ -- プロジェクト設定 (project.yml)
+
+`projects/<name>/project.yml` を読み、コンテナとエディタが使える形へ変換する層。
+YAML の解釈をホスト側の Python に閉じ込めることで、コンテナ側 (`entrypoint.sh`) は
+復号して 1 行ずつ clone するだけで済み、イメージへ YAML パーサ依存を持ち込まない。
+
+| モジュール | 役割 |
+|-----------|------|
+| `config.py` | `project.yml` の読み込み・`defaults` 継承・検証・正規化 (`ProjectConfig` / `RepoSpec`)。clone プランの符号化 (`encode_repo_plan`) |
+| `runtime.py` | コンテナへ渡す環境変数の組み立て (`DEVBASE_REPOS` / `DEVBASE_PRIMARY_DIR` / `DEVBASE_WORKSPACE*`)、multi-root ワークスペース JSON の生成、`scale` の読み書き |
+| `migrate.py` | 旧 `env` 形式 (`GIT_USER` / `GIT_REPO` 等) から `project.yml` への変換 |
+
+```mermaid
+flowchart LR
+ Y["project.yml"] --> C["config.py<br/>検証・正規化"]
+ C --> R["runtime.py<br/>環境変数へ"]
+ R --> Compose[".docker-compose.scale.yml<br/>dev サービス"]
+ Compose --> E["entrypoint.sh<br/>復号して clone"]
+```
+
 ### その他
 
 | ディレクトリ | 役割 |

docs/plugin-dev/compose-yml-guidelines.md

@@ -71,10 +71,9 @@ flowchart TB
  G1["共通APIキー"]
  G2["共有設定値"]
  end
- subgraph level2["レベル2: プロジェクト設定（env）"]
- P1["GIT_USER / GIT_REPO"]
- P2["WORK_DIR"]
- P3["CONTAINER_SCALE"]
+ subgraph level2["レベル2: プロジェクト環境変数（env）"]
+ P1["ENABLE_SSH など"]
+ P2["アプリが読む変数"]
  end
  subgraph level3["レベル3: プロジェクト機密（.env）"]
  S1["プロジェクト固有のAPIキー"]
@@ -90,7 +89,7 @@ flowchart TB
 | レベル | ファイル | Git管理 | 用途 | 例 |
 |--------|---------|---------|------|-----|
 | 1 | `${DEVBASE_ROOT}/.env` | No | 全プロジェクト共通の設定 | 共通APIキー |
-| 2 | `env` | Yes | プロジェクト固有の設定 | `GIT_REPO`, `CONTAINER_SCALE` |
+| 2 | `env` | Yes | コンテナへ渡すプロジェクト固有の環境変数 | `ENABLE_SSH` |
 | 3 | `.env` | No | プロジェクト固有の機密 | DB接続文字列、秘密鍵 |
 
 ---
@@ -204,9 +203,9 @@ ports:
 
 例: `CONTAINER_INDEX=1` の場合は `13000:3000`、`CONTAINER_INDEX=2` の場合は `23000:3000`
 
-### 5.3 CONTAINER_SCALE の設定
+### 5.3 コンテナ数（scale）の設定
 
-`env` ファイルで `CONTAINER_SCALE` を設定すると、`devbase up` 実行時に `.docker-compose.scale.yml` が自動生成され、指定された数のコンテナが起動します。
+`project.yml` の `scale` を設定すると、`devbase up` 実行時に `.docker-compose.scale.yml` が自動生成され、指定された数のコンテナが起動します（既定: 2）。詳細は [project.yml リファレンス](../user/project-yml.md) を参照してください。
 
 ---
 
@@ -241,15 +240,18 @@ networks:
  external: true
 ```
 
-対応する `env` ファイル:
+対応する `project.yml`:
 
-```bash
-GIT_USER=your-org
-GIT_REPO=my-webapp
-WORK_DIR=/work/$GIT_REPO
-CONTAINER_SCALE=1
+```yaml
+version: 1
+scale: 1
+repos:
+ - owner: your-org
+ repo: my-webapp
 ```
 
+`env` にはコンテナへ渡す環境変数だけを書きます（無くてもファイル自体は残します。`env_file` が参照するため）。
+
 ### 6.2 データベースを含む構成
 
 基本構成に `db` サービスを追加し、`depends_on` で依存関係を定義します。

docs/plugin-dev/quickstart.md

@@ -53,7 +53,8 @@ my-plugin/
 └── projects/
  └── my-project/
  ├── compose.yml
- └── env
+ ├── project.yml
+ └── env # 中身は任意だが、ファイルは必須
 ```
 
 ### 2.2 compose.yml の作成
@@ -93,26 +94,60 @@ networks:
 
 > **補足:** compose.yml の記述ルール詳細は [compose.yml ガイドライン](compose-yml-guidelines.md) を参照してください。
 
-### 2.3 env ファイルの作成
+### 2.3 project.yml の作成
 
-`projects/my-project/env` を作成します。このファイルはGit管理対象です。
+`projects/my-project/project.yml` を作成します。このファイルはGit管理対象で、**プロジェクト設定の正**です。
 
-```bash
-GIT_USER=your-github-user
-GIT_REPO=my-repo
-WORK_DIR=/work/$GIT_REPO
-CONTAINER_SCALE=1
-# GitLab等GitHub以外のホストを使う場合:
-# GIT_HOST=gitlab.com
+```yaml
+version: 1
+scale: 1
+repos:
+ - owner: your-github-user
+ repo: my-repo
 ```
 
-| 変数 | 説明 |
+複数のリポジトリを 1 つのコンテナへチェックアウトできます。
+
+```yaml
+version: 1
+scale: 1
+defaults:
+ owner: your-github-user
+repos:
+ - repo: my-app # 先頭が primary（ログイン直後の作業ディレクトリ）
+ - repo: my-app-docs
+ - repo: my-app-infra
+ host: gitlab.com # リポジトリごとに Git ホストを変えられる
+ owner: another-org
+ dir: infra # /work 配下の clone 先名（既定: repo 名）
+ branch: develop # clone 後にチェックアウトするブランチ
+ init: false # 起動のたびの ./init.sh 実行を無効化する
+```
+
+主なキーは以下のとおりです。全項目は [project.yml リファレンス](../user/project-yml.md) を参照してください。
+
+| キー | 説明 |
 |------|------|
-| `GIT_USER` | Gitホストのユーザー名またはOrganization名 |
-| `GIT_REPO` | リポジトリ名 |
-| `GIT_HOST` | Gitホスト名（デフォルト: `github.com`）。GitLabの場合は `gitlab.com` を指定 |
-| `WORK_DIR` | コンテナ内の作業ディレクトリ |
-| `CONTAINER_SCALE` | 起動するコンテナ数（デフォルト: 2） |
+| `version` | スキーマ版。現在は `1` |
+| `repos[].owner` / `repos[].repo` | Git ホストのユーザー名（Organization 名）とリポジトリ名 |
+| `repos[].host` | Git ホスト名（既定: `github.com`）。GitLab なら `gitlab.com` |
+| `repos[].dir` / `branch` / `init` / `primary` | clone 先ディレクトリ名 / チェックアウトするブランチ（clone 直後のみ） / `init.sh` の実行有無（起動のたびに実行。冪等に書くこと） / 既定の作業リポジトリ |
+| `scale` | 起動するコンテナ数（既定: 2） |
+| `open_editor` | `devbase up` 後に VS Code を自動で開くか |
+
+### 2.3.1 env ファイル（ファイルは必須・中身は任意）
+
+`projects/my-project/env` には、**コンテナへ渡す環境変数**だけを書きます（`ENABLE_SSH` など）。devbase 自身の設定は `project.yml` にあります。
+
+```bash
+ENABLE_SSH=true
+```
+
+2.2 の `compose.yml` が `env_file: - env` で参照するため、**ファイルは必ず作成してください**（実在しないと `devbase up` が compose の起動時に失敗します）。渡したい環境変数が無ければ空ファイルで構いません。
+
+```bash
+touch projects/my-project/env
+```
 
 ### 2.4 .env ファイル（任意）
 
@@ -137,12 +172,10 @@ MY_SECRET_API_KEY=sk-xxxxxxxxxxxx
 # projects/my-project/pre-up
 set -e
 
-# env から GIT_USER / GIT_REPO を取得
-source ./env
-
 # build context に使うリポジトリが無ければ clone
+# (pre-up はホスト側で動くフックなので、clone 先も URL もここに直接書く)
 if [ ! -d "./repo" ]; then
- git clone "https://github.com/${GIT_USER}/${GIT_REPO}.git" repo
+ git clone "https://github.com/your-github-user/my-repo.git" repo
 fi
 ```