docs: README/ドキュメントを現状の階層メニュー TUI に合わせて更新

takemi-ohama · claude · takemi-ohama · commit b9c7ca148c15 · 2026-06-13T03:28:25.000Z
PR #63〜#66 の TUI 変更 (確認プロンプト整理 / Enter 待ち / env メニュー再構成 / 最下部メニューバー) を反映し、ドキュメントを実装と整合させる。 - README: 「対話的なプロジェクト選択」を「階層メニュー TUI」へ刷新。 プロジェクト操作と最下部カテゴリメニュー (←→ 移動) を明記 - cli-reference: `devbase project list` を全面刷新。番号入力の旧説明を廃止し、 TUI の画面構成図・キー操作表・カテゴリ別操作一覧・確認プロンプトの範囲を追加 - container-operations: プロジェクト一覧の説明を TUI 前提に更新し詳細へリンク - architecture: 構成図と commands 表に project.py / tui/ を追加。tui/ の モジュール構成表を新設。cmd_project が container.py 側にある実態を反映 - 既存ドキュメントに元々抜けていた CLI サブコマンド (project rebuild / plugin migrate / env export・import) をコマンド一覧・ツリー図に補完 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
diff --git a/README.md b/README.md
@@ -15,7 +15,7 @@ devbaseは、Docker Composeを使った再現性の高い開発環境を提供
 - **データ永続化**: 名前付きボリュームでコンテナ再起動後もデータを保持
 - **スナップショット管理**: `/home/ubuntu` 共通ボリュームの増分バックアップ・復元・世代管理
 - **環境変数の自動収集**: `devbase env init`でAWS/Git/GCP認証情報を対話的に設定
-- **対話的なプロジェクト選択**: `devbase list` の TUI メニュー（矢印キー移動・名前絞り込み対応）から起動対象を選択。起動中なら再起動 (up) / 再ビルド (rebuild) / 停止 (down) も選べます
+- **階層メニュー TUI**: `devbase list` のプロジェクト一覧（矢印キー移動・名前絞り込み対応）から起動・操作（up / down / login / ps / logs / scale / build / rebuild）を選択。画面最下部の常設メニュー（環境変数 / プラグイン / スナップショット / ステータス）へは ←→ キーで移動できます
 - **キャッシュ無効リビルド**: `devbase rebuild [name]` で `docker compose build --no-cache` 相当のイメージ再ビルドができます
 
 ## クイックスタート
@@ -112,9 +112,9 @@ devbaseのコマンドは4つのグループにまとめられています。
 
 | グループ | 略記 | 説明 |
 |---------|------|------|
-| `project` | — | プロジェクト管理（up / down / login / ps / logs / scale / build / list） |
+| `project` | — | プロジェクト管理（up / down / login / ps / logs / scale / build / rebuild / list） |
 | `env` | — | 環境変数管理（init / sync / list / set / get / delete / edit / project / export / import） |
-| `plugin` | `pl` | プラグイン管理（list / install / uninstall / update / info / sync / repo） |
+| `plugin` | `pl` | プラグイン管理（list / install / uninstall / update / info / sync / migrate / repo） |
 | `snapshot` | `ss` | スナップショット管理（create / list / restore / copy / delete / rotate） |
 
 > **`container`（略記 `ct`）グループは非推奨です。** `devbase project <sub>` のエイリアスとして当面動作しますが、非推奨警告を表示します。新しいコマンドは `project` を使用してください。
diff --git a/docs/developer/architecture.md b/docs/developer/architecture.md
@@ -20,11 +20,14 @@ flowchart TB
 
     CliPy --> Init["commands/init.py"]
     CliPy --> Status["commands/status.py"]
-    CliPy --> Container["commands/container.py"]
+    CliPy --> Project["commands/project.py<br/>(list)"]
+    CliPy --> Container["commands/container.py<br/>(project ライフサイクル / 非推奨 container)"]
     CliPy --> Env["commands/env.py"]
     CliPy --> Plugin["commands/plugin.py"]
     CliPy --> Snapshot["commands/snapshot.py"]
 
+    Project -->|"list (TTY)"| Tui["tui/<br/>(階層メニュー TUI)"]
+
     CmdBuild --> Docker["docker buildx build / docker compose build"]
 ```
 
@@ -33,7 +36,7 @@ flowchart TB
 | 層 | 担当 | 利点 |
 |----|------|------|
 | **Bash** (`bin/devbase`) | PATH 設定、シェル補完登録、環境変数エクスポート、`build` コマンド | シェル環境へのネイティブ統合。`source` で `.env` を読み込み、`DEVBASE_ROOT` を確定してから Python に渡せる |
-| **Python** (`lib/devbase/`) | init, status, container, env, plugin, snapshot | 複雑なロジック（YAML パース、Git 操作、差分バックアップ等）を安全かつ保守的に実装できる |
+| **Python** (`lib/devbase/`) | init, status, project, env, plugin, snapshot, tui | 複雑なロジック（YAML パース、Git 操作、差分バックアップ等）を安全かつ保守的に実装できる |
 
 `build` コマンドだけが Bash 側に残っている理由は、Docker buildx の制御と compose.yml のパース処理がシェルスクリプトで完結するためである。
 
@@ -64,11 +67,28 @@ Python 側のエントリーポイント。以下の責務を持つ。
 |-----------|---------|------|
 | `init.py` | `cmd_init` | PATH 追加、シェル補完設定、plugins.yml 初期化 |
 | `status.py` | `cmd_status` | コンテナ・プラグイン・環境変数の状態表示 |
-| `container.py` | `cmd_container` | docker compose を操作。up/down/ps/login/logs/scale/build |
-| `env.py` | `cmd_env` | 環境変数の管理。init/sync/list/set/get/delete/edit/project |
-| `plugin.py` | `cmd_plugin` | プラグインの管理。list/install/uninstall/update/info/sync/repo |
+| `project.py` | `cmd_project_list` ほか | プロジェクト一覧の表示と、TTY での `tui/` 階層メニュー起動 |
+| `container.py` | `cmd_project` / `cmd_container` | `project` / `container` グループのディスパッチと docker compose 操作の実体（up/down/ps/login/logs/scale/build/rebuild）。`container` は非推奨エイリアス（警告を出して転送） |
+| `env.py` | `cmd_env` | 環境変数の管理。init/sync/list/set/get/delete/edit/project/export/import |
+| `plugin.py` | `cmd_plugin` | プラグインの管理。list/install/uninstall/update/info/sync/migrate/repo |
 | `snapshot.py` | `cmd_snapshot` | スナップショットの管理。create/list/restore/copy/delete/rotate |
 
+### tui/ -- 階層メニュー TUI
+
+`devbase list`（= `project list`）が TTY で起動する対話メニュー。questionary
+(prompt_toolkit ベース) を任意依存とし、未導入時は番号入力フォールバックへ縮退する。
+各 `actions_*.py` は引数を収集して既存の `commands/*.py` ハンドラへ委譲するだけで、
+コマンドロジックを二重実装しない。
+
+| モジュール | 役割 |
+|-----------|------|
+| `app.py` | トップ画面のループ。プロジェクト一覧 + 最下部の常設カテゴリメニューバー（`menu.select_with_menubar`）を表示し、選択を各カテゴリへ routing する |
+| `menu.py` | questionary ラッパ（`select` / `select_with_menubar` / `text` / `confirm` / `integer` / `path`）と Esc/← キーバインド・回答後ガード |
+| `flow.py` | 中止系番兵（Ctrl-C=`None` / Esc=`MENU_BACK` / 確認拒否）を例外へ変換する共通ナビ制御 |
+| `dispatch.py` | 収集した属性を Namespace に詰めて `cmd_*` ハンドラを呼ぶ薄い委譲層 |
+| `actions_project.py` | プロジェクト行の処理（up / 起動中は操作サブメニュー） |
+| `actions_env.py` / `actions_plugin.py` / `actions_snapshot.py` / `actions_status.py` | 各カテゴリの操作フロー |
+
 ### env/ -- 環境変数管理システム
 
 環境変数の収集・保存・同期を担うサブシステム。
diff --git a/docs/user/cli-reference.md b/docs/user/cli-reference.md
@@ -16,10 +16,10 @@ graph TD
     A --> G[snapshot / ss]
     D --> D1["up / down / ps / logs / scale [name]"]
     D --> D3["login [index]"]
-    D --> D4["build [image]"]
+    D --> D4["build [image] / rebuild"]
     D --> D2["list [--no-interactive]"]
-    E --> E1[init / sync / list / set / get / delete / edit / project]
-    F --> F1[list / install / uninstall / update / info / sync]
+    E --> E1[init / sync / list / set / get / delete / edit / project / export / import]
+    F --> F1[list / install / uninstall / update / info / sync / migrate]
     F --> F2[repo add / repo remove / repo list / repo refresh]
     G --> G1[create / list / restore / copy / delete / rotate]
 ```
@@ -276,9 +276,10 @@ devbase build [image]
 `$DEVBASE_ROOT/projects/` 配下のプロジェクトを `NAME` / `PLUGIN` / `STATUS` の一覧で
 表示します。
 
-TTY（端末）では**デフォルトで対話選択**になり、番号入力で選んだプロジェクトを
-`project up` で起動します。パイプ・リダイレクト・CI などの非 TTY 環境では自動的に
-一覧表示のみへフォールバックします。
+TTY（端末）では**デフォルトで階層メニュー TUI** が起動し、プロジェクトの起動・操作と
+カテゴリ操作（環境変数 / プラグイン / スナップショット / ステータス）を 1 画面から
+実行できます。パイプ・リダイレクト・CI などの非 TTY 環境では自動的に一覧表示のみへ
+フォールバックします。
 
 ```
 devbase project list [--no-interactive|--plain|-P]
@@ -287,18 +288,55 @@ devbase list [--no-interactive|--plain|-P]
 
 | オプション | 説明 |
 |-----------|------|
-| `--no-interactive` / `--plain` / `-P` | 対話選択せず一覧表示のみ |
-| `--interactive` / `-i` | （後方互換）対話選択。デフォルトのため通常は不要 |
+| `--no-interactive` / `--plain` / `-P` | TUI を起動せず一覧表示のみ |
+| `--interactive` / `-i` | （後方互換）TUI 起動。デフォルトのため通常は不要 |
+
+#### TUI の画面構成とキー操作
+
+```
+? プロジェクトまたは操作を選択 (↑↓ 移動 / 名前で絞り込み / ←→ 下部メニュー / Enter 決定 / Esc・Ctrl-C 終了):
+ » [1] adminer    (adminer, running (2 containers))
+   [2] carmo      (carmo, stopped)
+──────────────────────────────────────────────────────────────
+  環境変数    プラグイン    スナップショット    ステータス
+```
+
+| キー | 動作 |
+|------|------|
+| ↑↓ / 文字入力 | プロジェクト一覧の移動・名前での絞り込み |
+| ← → | 最下部の常設カテゴリメニューへ移動し項目間を巡回（バー上の ↑↓ で一覧へ戻る） |
+| Enter | 決定。停止中プロジェクトはそのまま起動 (up)、起動中プロジェクトは操作サブメニューを表示 |
+| Esc / ← | サブメニューでは 1 つ前の画面へ戻る（トップでは Esc で終了） |
+| Ctrl-C | どの画面でも全体を中止 |
+
+起動中プロジェクトの操作サブメニューでは up / down / login / ps / logs / scale /
+build / rebuild を選べます。最下部のカテゴリメニューから実行できる操作
+（実体は対応する CLI コマンドへの委譲）:
+
+| カテゴリ | 選べる操作 |
+|---------|-----------|
+| 環境変数 | 変数一覧（グローバル）/ edit / sync / project / init |
+| プラグイン | 導入済み一覧 / 利用可能一覧 / install / uninstall / update / info / sync / migrate / repo 管理 |
+| スナップショット | list / create / restore / copy / delete / rotate |
+| ステータス | 環境全体の状態を表示（`devbase status` 相当） |
+
+- 確認プロンプト (y/N) が出るのは破壊的操作（plugin uninstall / plugin repo remove /
+  snapshot restore / snapshot delete）のみで、その他は CLI 既定値で即実行します
+- 操作の出力後は Enter キーで一覧へ戻ります（出力が流れて読めなくなるのを防ぐため）
+- TUI が提供しない細かいオプション（`env get/set/delete/export/import`、
+  `plugin install --link/--all`、`snapshot create --full`、`logs --follow` 等）は
+  CLI を使用してください
+- questionary 未導入時は従来の番号入力（選択 → up）にフォールバックします
 
 ```bash
-# 一覧を表示して番号で選択・起動（TTY デフォルト）
+# 階層メニュー TUI を起動（TTY デフォルト）
 devbase list
 
-# 一覧表示のみ（選択しない）
+# 一覧表示のみ（TUI を起動しない）
 devbase list --no-interactive
 ```
 
-出力例:
+出力例（`--no-interactive` / 非 TTY）:
 
 ```
 NAME          PLUGIN        STATUS
diff --git a/docs/user/container-operations.md b/docs/user/container-operations.md
@@ -238,16 +238,20 @@ devbase project logs -f --tail 100
 ### プロジェクト一覧
 
 ```bash
-# 一覧を表示し、番号で選択して起動（TTY ではこれがデフォルト）
+# 階層メニュー TUI を起動（TTY ではこれがデフォルト）
 devbase list
 
 # 選択せず NAME / PLUGIN / STATUS の一覧表示のみ
 devbase list --no-interactive   # --plain / -P も同義
 ```
 
-> TTY（端末）では `devbase list` はデフォルトで対話選択になり、番号入力で
-> そのプロジェクトを起動します。パイプ・リダイレクト・CI などの非 TTY 環境では
-> 自動的に一覧表示のみにフォールバックします。
+> TTY（端末）では `devbase list` はデフォルトで階層メニュー TUI になり、
+> プロジェクトを選んで起動・操作（up / down / login / ps / logs / scale /
+> build / rebuild）できるほか、画面最下部の常設メニュー（環境変数 / プラグイン /
+> スナップショット / ステータス）へ ←→ キーで移動して各管理操作を実行できます。
+> パイプ・リダイレクト・CI などの非 TTY 環境では自動的に一覧表示のみに
+> フォールバックします。画面構成とキー操作の詳細は
+> [CLI リファレンス](cli-reference.md#devbase-project-list) を参照してください。
 
 `devbase project ps` が「対象プロジェクト 1 つのコンテナ状態」を表示するのに対し、
 `devbase list` は「全プロジェクトの横断一覧」を表示します。
