diff --git a/README.md b/README.md index 5d7d59f..6999329 100644 --- 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,14 +112,14 @@ 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 ` のエイリアスとして当面動作しますが、非推奨警告を表示します。新しいコマンドは `project` を使用してください。 -- **ショートカット**: `up [name]`, `down [name]`, `login [index]`, `build [image]`, `ps [name]`, `scale [name] `, `list` はトップレベルから直接使用可能(`project` グループへ自動転送。`logs` はシノニムを持ちません)。なお `build` のみ挙動が一部異なります(詳細は [CLI リファレンス](docs/user/cli-reference.md#ショートカットコマンド)) +- **ショートカット**: `up [name]`, `down [name]`, `login [index]`, `build [image]`, `ps [name]`, `scale [name] `, `rebuild [name]`, `list` はトップレベルから直接使用可能(`project` グループへ自動転送。`logs` はシノニムを持ちません)。なお `build` のみ挙動が一部異なります(詳細は [CLI リファレンス](docs/user/cli-reference.md#ショートカットコマンド)) - **プレフィックス略記**: `devbase p l` → `devbase plugin list` - **トップレベルコマンド**: `init`, `status` diff --git a/docs/developer/architecture.md b/docs/developer/architecture.md index 7b9cb6c..4e1ef27 100644 --- 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
(list)"] + CliPy --> Container["commands/container.py
(project ライフサイクル / 非推奨 container)"] CliPy --> Env["commands/env.py"] CliPy --> Plugin["commands/plugin.py"] CliPy --> Snapshot["commands/snapshot.py"] + Project -->|"list (TTY)"| Tui["tui/
(階層メニュー 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 のパース処理がシェルスクリプトで完結するためである。 @@ -52,7 +55,7 @@ Python 側のエントリーポイント。以下の責務を持つ。 | 定数 | 役割 | |------|------| -| `SHORTCUTS` | トップレベルショートカット → (グループ, サブコマンド) のマッピング。`up`, `down`, `login`, `build`, `ps` が `container` グループに転送される | +| `SHORTCUTS` | トップレベルショートカット → サブコマンドのマッピング。`up`, `down`, `login`, `ps`, `scale`, `rebuild` が `project` グループへ転送される(`build` は shell 実装へ委譲するため除外、`list` は lifecycle ではないため `_dispatch` で個別 routing) | | `GROUP_ALIASES` | グループのエイリアス。`ct` → `container`, `pl` → `plugin`, `ss` → `snapshot` | | `SUBCMD_MAP` | 各グループが受け付けるサブコマンド一覧。プレフィックスマッチの候補として使用される | @@ -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 index 879f08b..842d8f4 100644 --- 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 [name]"] 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] ``` @@ -50,6 +50,7 @@ graph TD | `devbase build [image]` | `bin/devbase` の `cmd_build`(シェル実装)※ | | `devbase ps [name]` | `devbase project ps [name]` | | `devbase scale [name] ` | `devbase project scale [name] ` | +| `devbase rebuild [name]` | `devbase project rebuild [name]` | | `devbase list` | `devbase project list` | > **Note:** `logs` はトップレベルシノニムを持ちません。`devbase project logs` を使用してください。 @@ -271,14 +272,29 @@ devbase build [image] |-----------|------|------| | `image` | いいえ | ビルドするイメージ名(省略時は全イメージ) | +### `devbase project rebuild` + +キャッシュを使わずにコンテナイメージを再ビルドします(`docker compose build --no-cache`)。 +`build` と異なり Python 実装で完結するため、トップレベルショートカット `devbase rebuild` を持ちます。 + +``` +devbase project rebuild [name] +devbase rebuild [name] +``` + +| パラメータ | 必須 | 説明 | +|-----------|------|------| +| `name` | いいえ | 対象プロジェクト名(省略時はカレント) | + ### `devbase project list` `$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 +303,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 @@ -431,6 +484,28 @@ devbase env edit devbase env project ``` +### `devbase env export` + +複数プロジェクトの `.env` 群を暗号化したまま 1 つのバンドルにまとめて書き出します。 + +``` +devbase env export +``` + +オプション(age 鍵 / passphrase / S3 入出力など)の詳細は +[環境変数の export / import ガイド](env-export-import.md#devbase-env-export-リファレンス)を参照してください。 + +### `devbase env import` + +`devbase env export` で作成したバンドルを復号し、環境変数を取り込みます。 + +``` +devbase env import +``` + +`--dry-run` での確認や identity 鍵指定などの詳細は +[環境変数の export / import ガイド](env-export-import.md#devbase-env-import-リファレンス)を参照してください。 + ## plugin (pl) グループ プラグインの管理を行うコマンド群です。 diff --git a/docs/user/container-operations.md b/docs/user/container-operations.md index 6ec3bb1..0a0d5dc 100644 --- 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` は「全プロジェクトの横断一覧」を表示します。