docs: [name] / --context を取るサブコマンドの列挙を揃え、profiles に requires.devbase の手順を足す (#208, #195)

docs/plugin-dev/compose-profiles.md

@@ -7,7 +7,7 @@ dev のほかに app / db などのサービスを持つプロジェクトで、
 | 項目 | 条件 |
 | --- | --- |
 | Docker Compose | **2.20.0 以上**。`depends_on` の `required` を使うため。動作を確かめたのは v5.1.4 |
-| devbase | `devbase project profile` があるバージョン |
+| devbase | **3.5.0 以上**。`devbase project profile` が入った版です（CHANGELOG の `[3.5.0]`）。Plugin として配るなら [`plugin.yml` の `requires.devbase` も上げます](#plugin-として配るなら-requiresdevbase-を-350-以上へ上げる) |
 
 ## 1. `compose.yml` の書き方
 
@@ -43,6 +43,26 @@ services:
 
 プロファイル名に `__devbase_none__` は使わないでください。devbase が「どのプロファイルも有効にしない」ために予約している名前です。
 
+### Plugin として配るなら `requires.devbase` を 3.5.0 以上へ上げる
+
+`profiles:` を使うプロジェクトを含む Plugin は、`plugin.yml` の `requires.devbase` を
+`">=3.5.0"` へ上げてください。`compose.yml` を書き換えたのと同じ Pull Request で上げます。
+
+```yaml
+# <plugin>/plugin.yml
+requires:
+  devbase: ">=3.5.0"
+```
+
+3.5.0 未満の devbase では、`profiles:` を付けたサービスが `devbase up` の起動対象から外れたまま、
+後から起動する手段（`devbase project profile up`）もありません。テスト用サーバ群が黙って起動
+しない状態になります。
+
+`requires.devbase` を上げておけば、新規の `devbase plugin install` はその場で拒否され、
+`devbase plugin update` では警告が出ます。仕組みは既にあるため、Plugin 側でやることは版数を
+書くことだけです。書式（必ずクォートする）と検証の詳細は
+[`plugin.yml` リファレンスの `requires`](plugin-yml-reference.md#requires) を参照してください。
+
 ## 2. コマンド
 
 ```bash

docs/plugin-dev/plugin-yml-reference.md

@@ -169,8 +169,15 @@ WARNING プラグイン 'carmo-web' は devbase >=4.0.0 を要求しています
 devbase 本体を更新してください (この警告を止める場合は DEVBASE_IGNORE_PLUGIN_REQUIRES=1)。
 ```
 
-> `requires.devbase` を上げるのは、**Plugin が `project.yml` 形式へ移行したタイミング**です。
-> 本体の版数と一緒に自動では上がりません。
+> **`requires.devbase` は本体の版数と一緒に自動では上がりません。** 上げるのは、**Plugin が
+> devbase の新しい機能に依存しはじめたタイミング**です。契機は次のとおりです。
+>
+> | 契機 | 上げる版数 |
+> | --- | --- |
+> | Plugin が `project.yml` 形式へ移行した | その形式を読める版 |
+> | Plugin のプロジェクトが `compose.yml` に `profiles:` を使う | `">=3.5.0"`（[テスト用サーバを後から起動・停止する](compose-profiles.md#plugin-として配るなら-requiresdevbase-を-350-以上へ上げる)） |
+>
+> どちらも、その機能を使い始めた Pull Request で一緒に上げます。
 
 ### `priority`
 

docs/specifications/compose-profiles.md

@@ -193,7 +193,7 @@ subcommand より前に置く。`<サービス...>` はプロファイル X に
   `cli._dispatch` が `project profile list` を `project list`（プロジェクト一覧）へ流すためである
 - 前方一致の省略は `project p` / `container p` を従来どおり `ps` に解決し（`SUBCMD_PREFIX_PREFERENCES`）、
   `project pr` は `profile` に解決する
-- `bin/devbase` の `_PROJECT_NAME_SUBCOMMANDS`（`up down ps logs scale rebuild`）に `profile` は
+- `bin/devbase` の `_PROJECT_NAME_SUBCOMMANDS`（`up down ps logs scale rebuild open`）に `profile` は
   入れない。wrapper は 3 番目の引数をプロジェクト名として解決するが、`profile` ではそこに
   `up` / `down` / `list` が来るため、同名のプロジェクトが実在すると誤って移動する。名前の解決は
   Python 側の `_dispatch_lifecycle` が行う

docs/specifications/remote-docker-context.md

@@ -4,7 +4,7 @@
 
 devbase は、プロジェクトごとの個人設定 `projects/<name>/project.local.yml` に docker context の
 名前を書くと、そのプロジェクトの `up` / `down` / `ps` / `logs` / `login` / `scale` / `build` /
-`rebuild` を別ホストの docker daemon へ向ける。compose クライアントと機密の復号は手元で行い、
+`rebuild` / `open` を別ホストの docker daemon へ向ける。compose クライアントと機密の復号は手元で行い、
 daemon だけがリモートにある。リモートに要るのは docker CLI・dockerd・sshd で、devbase・
 `projects/`・機密鍵をリモートへ複製しない。`devbase up` が開く VS Code は、attach URI の
 `settings.context` でそのホストのコンテナへ接続する。
@@ -40,8 +40,9 @@ daemon だけがリモートにある。リモートに要るのは docker CLI
 この段階では docker を呼ばない。
 
 `--context` は `project` / `container` 配下の `up` / `down` / `ps` / `logs` / `login` / `scale` /
-`build` / `rebuild`、トップレベルのショートカット `up` / `down` / `ps` / `login` / `scale` /
-`build` / `rebuild`、および `env exec` が受け付ける。空文字と空白のみは終了コード 2 で拒む
+`build` / `rebuild` / `open` / `profile up` / `profile down` / `profile list`、トップレベルの
+ショートカット `up` / `down` / `ps` / `login` / `scale` / `build` / `rebuild` / `open`、および
+`env exec` / `env token` が受け付ける。空文字と空白のみは終了コード 2 で拒む
 （Python の parser と `bin/devbase` の両方）。
 
 ### リモート扱いの判定

docs/user/cli-reference/02-project.md

@@ -6,7 +6,7 @@
 
 ## プロジェクト名指定（CWD 非依存）
 
-`up` / `down` / `ps` / `logs` / `scale` は省略可能な `[name]` 引数を取ります。`[name]`
+`up` / `down` / `ps` / `logs` / `scale` / `rebuild` / `open` は省略可能な `[name]` 引数を取ります。`[name]`
 を指定すると、**現在のディレクトリに依存せず** `$DEVBASE_ROOT/projects/<name>` を対象に
 操作できます。
 
@@ -18,6 +18,13 @@ devbase project up adminer
 cd $DEVBASE_ROOT/projects/adminer && devbase project up
 ```
 
+> **`profile` も `[name]` を取りますが、解決の経路が違います。** `project profile up` /
+> `profile down` / `profile list` は `[name]` を受け付けますが、`bin/devbase` の
+> `_PROJECT_NAME_SUBCOMMANDS`（`up` / `down` / `ps` / `logs` / `scale` / `rebuild` / `open`）
+> には入っていません。`profile` では 3 番目の引数に `up` / `down` / `list` が来るため、
+> ラッパーでは位置で名前を解決できないからです。名前の解決は Python 側の
+> `_dispatch_lifecycle` が行います。
+
 - `<name>` は `$DEVBASE_ROOT/projects/` 配下のプロジェクト名（`devbase project list` で確認可能）
 - 名前として受け付ける形は、英数字で始まり英数字・`.`・`-`・`_` だけからなる文字列です
   （`carmo`、`github_work_time`、`carmo-ai`、`carmo.takemi`）。`../etc` や `a/b` のように
@@ -57,7 +64,7 @@ cd $DEVBASE_ROOT/projects/adminer && devbase project up
 
 ## `--context NAME`（共通オプション）
 
-`up` / `down` / `ps` / `logs` / `login` / `scale` / `build` / `rebuild` / `profile`（`project` /
+`up` / `down` / `ps` / `logs` / `login` / `scale` / `build` / `rebuild` / `open` / `profile`（`project` /
 `container` 配下と、トップレベルのショートカット）は `--context NAME` を受け付けます。
 そのコマンドの `docker` / `docker compose` を、指定した docker context の daemon へ向けます。
 

docs/user/cli-reference/README.md

@@ -5,7 +5,7 @@ devbase の全コマンドの構文、オプション、使用例をまとめた
 | ファイル | 内容 |
 |---------|------|
 | [トップレベルコマンド](01-toplevel.md) | `init` / `status` / `bin/rc` |
-| [project グループ](02-project.md) | コンテナのライフサイクル管理・一覧（`up` / `down` / `login` / `ps` / `logs` / `scale` / `build` / `rebuild` / `list`）と非推奨の `container` グループ |
+| [project グループ](02-project.md) | コンテナのライフサイクル管理・一覧（`up` / `down` / `login` / `ps` / `logs` / `scale` / `build` / `rebuild` / `open` / `profile` / `list`）と非推奨の `container` グループ |
 | [env グループ](03-env.md) | 環境変数の管理（`init` / `sync` / `list` / `set` / `get` / `delete` / `edit` / `project` / `keygen` / `encrypt` / `decrypt` / `exec` / `token` / `rekey` / `doctor` / `export` / `import`） |
 | [plugin グループ](04-plugin.md) | プラグインの管理（`list` / `install` / `uninstall` / `update` / `info` / `sync` / `migrate` / `repo *`） |
 | [snapshot グループ](05-snapshot.md) | スナップショットの管理（`create` / `list` / `restore` / `copy` / `delete` / `rotate`） |
@@ -22,9 +22,10 @@ graph TD
     A --> E[env]
     A --> F[plugin / pl]
     A --> G[snapshot / ss]
-    D --> D1["up / down / ps / logs / scale [name]"]
+    D --> D1["up / down / ps / logs / scale / open [name]"]
     D --> D3["login [index]"]
     D --> D4["build [image] / rebuild [name]"]
+    D --> D5["profile up / down / list [name]"]
     D --> D2["list [--no-interactive]"]
     E --> E1[init / sync / list / set / get / delete / edit / project]
     E --> E2[keygen / encrypt / decrypt / exec / token / rekey / doctor]
@@ -61,10 +62,16 @@ graph TD
 | `devbase ps [name]` | `devbase project ps [name]` |
 | `devbase scale [name] <num>` | `devbase project scale [name] <num>` |
 | `devbase rebuild [name]` | `devbase project rebuild [name]` |
+| `devbase open [name]` | `devbase project open [name]` |
 | `devbase list` | `devbase project list` |
 
 > **Note:** `logs` はトップレベルシノニムを持ちません。`devbase project logs` を使用してください。
 >
+> **`profile` について:** `devbase project profile up|down|list` もトップレベルシノニムを持ちません。
+> `[name]` は受け付けますが、3 番目の引数に `up` / `down` / `list` が来るためラッパーでは位置で
+> 解決できず、名前の解決は Python 側が行います。詳細は
+> [project グループの「プロジェクト名指定」](02-project.md#プロジェクト名指定cwd-非依存)を参照してください。
+>
 > **※ `build` の転送先について:** `devbase build`（既定 / `--no-cache` / `--project-no-cache`）は他の
 > ショートカットのように `project` グループ（Python 実装）へ転送されるのではなく、`bin/devbase` の
 > シェル実装 `cmd_build` に直接委譲されます。base イメージの段階ビルド等を CWD で行う必要があるため

docs/user/container-operations.md

@@ -5,8 +5,10 @@ devbase のコンテナ管理機能について、ライフサイクル、並行
 > **コマンド体系について:** コンテナ操作は `devbase project <sub>` グループ（および
 > トップレベルショートカット `devbase up` 等）で行います。旧 `devbase container <sub>` は
 > 非推奨となり、`project` へのエイリアスとして警告付きで当面動作します。`project` では
-> `up` / `down` / `ps` / `logs` / `scale` に `[name]` を指定することで **任意のディレクトリ
-> から** 対象プロジェクトを操作できます。プロジェクト一覧は `devbase project list` を参照
+> `up` / `down` / `ps` / `logs` / `scale` / `rebuild` / `open` に `[name]` を指定することで
+> **任意のディレクトリから** 対象プロジェクトを操作できます。`profile up` / `profile down` /
+> `profile list` も `[name]` を取りますが、ラッパーでは位置で解決できず Python 側が解決する
+> 点が違います。プロジェクト一覧は `devbase project list` を参照
 > してください。詳細は [CLI リファレンス: project グループ](cli-reference/02-project.md) を参照。
 
 ## コンテナライフサイクル

docs/user/environment-variables.md

@@ -368,8 +368,8 @@ DEVBASE_WINDOW_TITLE=0
 
 `devbase up` は既定で **コマンドを実行した環境の Docker** にコンテナを立てます。
 `projects/<name>/project.local.yml` に docker context の名前を書くと、そのプロジェクトの
-`up` / `down` / `ps` / `logs` / `login` / `scale` / `build` / `rebuild` を**別ホストの daemon**
-へ向けられます。用途は、CUDA が使える Windows（WSL2）の GPU、負荷分散のための 3 台目の PC、
+`up` / `down` / `ps` / `logs` / `login` / `scale` / `build` / `rebuild` / `open` を
+**別ホストの daemon** へ向けられます。用途は、CUDA が使える Windows（WSL2）の GPU、負荷分散のための 3 台目の PC、
 AWS EC2 の計算資源などです。
 
 仕組みは「compose クライアントは手元、daemon はリモート」です。devbase・`projects/`・機密鍵を