From b22e57a9d22672ae383a7e0825ef40fa3fdb255b Mon Sep 17 00:00:00 2001 From: "takemi.ohama" Date: Mon, 16 Nov 2026 22:25:26 +0900 Subject: [PATCH 1/7] =?UTF-8?q?Docs:=20#523=20=E3=81=AE=E8=A6=81=E6=B1=82?= =?UTF-8?q?=E3=81=A8=E5=8F=97=E3=81=91=E5=85=A5=E3=82=8C=E6=9D=A1=E4=BB=B6?= =?UTF-8?q?=E3=82=92=E6=9B=B8=E3=81=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit tmux でソケットを拾い直したときに、合う remote-cli を PATH の先頭に入れる 要求と受け入れ条件を課題の本文に書き、その写しを issues/ に置く。 用語集へ セッション環境・IPC ソケットの拾い直し・remote-cli・デスクトップ版の code を足す。 Co-Authored-By: Claude Opus 5.5 --- docs/glossary.md | 4 + docs/glossary/glossary.json | 28 +++++ issues/issue-523-requirements.md | 194 +++++++++++++++++++++++++++++++ 3 files changed, 226 insertions(+) create mode 100644 issues/issue-523-requirements.md diff --git a/docs/glossary.md b/docs/glossary.md index 44eab8a3..8298ad69 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -58,6 +58,10 @@ up の後に VS Code で dev コンテナを開く(docs/specifications/editor- | コンテナごとの VS Code Server の状態 | — | ~/.vscode-server のうち bin/ 以外(extensions/・extensionsCache/・data/)。拡張・接続トークン・.devport・マシンの設定(window.title を含む)・ログ・User/ の状態を持つ。どのボリュームにも置かず、コンテナの書き込みレイヤーに残る。devbase up の作り直しで消え、docker restart では残る | — | — | `docs/specifications/vscode-server-volume.md` | | 旧形式の VS Code Server ボリューム | — | #463 より前の devbase が dev コンテナ 1 つに 1 本付けていた devbase_vscode__。~/.vscode-server を丸ごと持つ。#463 の後は付けず、devbase は消さない | — | — | `docs/specifications/vscode-server-volume.md` | | Dev Containers の共有の置き場 | — | すべての dev コンテナが /vscode に付ける 1 本のボリューム vscode。名前は Dev Containers 拡張の決め打ちで、付いていると拡張のキャッシュ(/vscode/vscode-server/extensionsCache)と VS Code Server の新しい版の本体(/vscode/vscode-server/bin//)を手元の端末でなくこの中に置く。docker ホストごとにあり、別の CPU 向けの拡張が混ざらない | — | — | `docs/specifications/vscode-server-volume.md` | +| セッション環境 | — | tmux のサーバーがセッションごとに持つ環境変数。update-environment に挙げた変数は attach のたびにいまのクライアントの値へ更新される。ペインのシェルの環境変数はペインを作ったときの値のまま残る | — | — | — | +| IPC ソケットの拾い直し | — | ペインのシェルの VSCODE_IPC_HOOK_CLI が使えないとき、セッション環境の VSCODE_IPC_HOOK_CLI が接続できればそちらを使うこと | — | — | — | +| remote-cli | — | Remote-SSH などの VS Code サーバーが持つ CLI の置き場(<サーバーのディレクトリ>/bin/remote-cli)。中の code は VSCODE_IPC_HOOK_CLI のソケットを通じて手元の VS Code に窓を開かせる | — | — | — | +| デスクトップ版の code | — | ホストに入れたデスクトップ版の VS Code の CLI。VSCODE_IPC_HOOK_CLI を読まず、ホストの VS Code に向けて開く | — | — | — | ## 機密の置き場(`secret`) diff --git a/docs/glossary/glossary.json b/docs/glossary/glossary.json index d5b0aead..03fcd25c 100644 --- a/docs/glossary/glossary.json +++ b/docs/glossary/glossary.json @@ -1073,6 +1073,34 @@ "context": "plugin-distribution", "meaning": "作成フローが書き込みの前に確定する、作るもの・ファイル・マージ先の組", "source": "docs/specifications/plugin-creation-flow.md" + }, + { + "term": "セッション環境", + "context": "editor", + "meaning": "tmux のサーバーがセッションごとに持つ環境変数。update-environment に挙げた変数は attach のたびにいまのクライアントの値へ更新される。ペインのシェルの環境変数はペインを作ったときの値のまま残る", + "source": "", + "pending_source": "issues/issue-523-requirements.md" + }, + { + "term": "IPC ソケットの拾い直し", + "context": "editor", + "meaning": "ペインのシェルの VSCODE_IPC_HOOK_CLI が使えないとき、セッション環境の VSCODE_IPC_HOOK_CLI が接続できればそちらを使うこと", + "source": "", + "pending_source": "issues/issue-523-requirements.md" + }, + { + "term": "remote-cli", + "context": "editor", + "meaning": "Remote-SSH などの VS Code サーバーが持つ CLI の置き場(<サーバーのディレクトリ>/bin/remote-cli)。中の code は VSCODE_IPC_HOOK_CLI のソケットを通じて手元の VS Code に窓を開かせる", + "source": "", + "pending_source": "issues/issue-523-requirements.md" + }, + { + "term": "デスクトップ版の code", + "context": "editor", + "meaning": "ホストに入れたデスクトップ版の VS Code の CLI。VSCODE_IPC_HOOK_CLI を読まず、ホストの VS Code に向けて開く", + "source": "", + "pending_source": "issues/issue-523-requirements.md" } ] } diff --git a/issues/issue-523-requirements.md b/issues/issue-523-requirements.md new file mode 100644 index 00000000..6d8b4861 --- /dev/null +++ b/issues/issue-523-requirements.md @@ -0,0 +1,194 @@ +# #523: エディタの自動オープン: tmux でソケットを拾い直しても PATH の code がデスクトップ版のままで、手元の VS Code に開かない + +正は課題の本文(#523)で、この文書はその写しである。`spec-copy.py write` で作り直す。手で直さない。 + +## 起票者の推定 + +題・本文のうち、利用者の指示の原文に無く起票者が推して足した条件。設計承認ゲートで確かめるまで、利用者の決定として扱わない。扱いを書いた行は、設計者が決めた判断として読む。 + +この課題の本文は、起票者(AI)が事象の調査の記録として書いたものである。利用者の指示の原文は本文に引用されていない(「依頼(原文)」の節)。そのため、本文の条件はすべてこの節に並べる。 + +| # | 条件 | 推した出所 | この要求での扱い | +| --- | --- | --- | --- | +| S1 | 拾い直したソケットに合う `remote-cli` を `PATH` の先頭に入れて直す(本文の「直し方の案」1) | 課題の本文「直し方の案」 | 受け入れ条件 1・2 | +| S2 | 合う `remote-cli` は、セッション環境の `VSCODE_GIT_ASKPASS_NODE` から求める | 課題の本文「直し方の案」1 | 受け入れ条件 2・前提 1 | +| S3 | `~/.vscode-server/cli/servers/*/server/bin/remote-cli/code` を探して使う(本文の「直し方の案」2) | 課題の本文「直し方の案」2 | 採らない(理由: 拾い直したソケットとサーバーの版がずれ得る。本文も 1 のほうを推している。前提 2) | +| S4 | 拾い直しが起きないときの振る舞いは変えない | 課題の本文「受け入れ条件」 | 受け入れ条件 6・7 | +| S5 | テストで、拾い直したソケットに合う `remote-cli` が `PATH` の先頭に入ることを確かめる | 課題の本文「受け入れ条件」 | 受け入れ条件 2(検証手段のテスト) | +| S6 | `remote-cli` の `code` を拾い直したソケットで起動すれば手元の PC の VS Code で開く | 課題の本文「確かめたこと」(終了コード 0 までを確認。手元で開くかは利用者が確認中) | 前提 3・手動確認 | + +## 事象 + +手元の PC の VS Code から Remote-SSH で macOS のホストへ入り、ホストの tmux のペインで `devbase` からプロジェクト(`proj-a`)のエディタを開こうとすると、手元の PC の VS Code に窓が開かない。エラーも出ない。 + +`open_editor` の起動を差し替えて実行すると、起動されるのは `['code', '--folder-uri', 'vscode-remote://attached-container+…@ssh-remote+/work']` で、`code` はホストの `/usr/local/bin/code`(デスクトップ版の VS Code の CLI)に解決される。 + +判定は正しい。実行の場面の判定は「VS Code の中・SSH 越し」を返し、方針は起動(`launch`)で、URI も SSH 先を経由する形(`…@ssh-remote+/work`)で組まれている。違うのは起動する実行ファイルだけである。 + +原因: tmux のセッション環境から IPC ソケットを拾い直すと、エディタの自動オープンは `VSCODE_IPC_HOOK_CLI` だけを差し替え、`PATH` は変えない(`lib/devbase/editor/opener.py` の `_prepare_ipc_env`)。デスクトップ版の CLI は `VSCODE_IPC_HOOK_CLI` を読まない(`Visual Studio Code.app/Contents/Resources/app/out/cli.js` での出現は 0、`remote-cli` の `server-cli.js` では 1)。そのため手元の PC へは何も届かない。 + +## 期待する結果 + +拾い直したソケットと同じ VS Code サーバーの `remote-cli` の `code` が起動され、手元の PC の VS Code に dev コンテナへ接続した窓が開く。 + +## 再現手順 + +1. 手元の PC の VS Code から Remote-SSH で macOS のホストへ入る +2. ホストにデスクトップ版の VS Code が入っており、`/usr/local/bin/code` がその CLI を指している +3. 以前のクライアントで作った tmux のペインに attach する。ペインのシェルの `VSCODE_IPC_HOOK_CLI` が指すソケットはもう無く、`PATH` に Remote-SSH の `remote-cli` が入っていない +4. tmux のセッション環境には、いま attach しているクライアントの `VSCODE_IPC_HOOK_CLI`(接続できる)が入っている +5. そのペインで `devbase` からプロジェクトのエディタを開く + +## 環境 + +- 確かめた版: `main` の 180a0c8(v4.2.0 の後) +- ホスト: macOS、Remote-SSH の VS Code サーバーは `~/.vscode-server/cli/servers/Stable-/server/` の配置 +- 手元: VS Code(Remote-SSH) + +## 用語 + +| 用語 | 意味 | +| --- | --- | +| セッション環境 | tmux のサーバーがセッションごとに持つ環境変数。`update-environment` に挙げた変数は attach のたびにいまのクライアントの値へ更新される。ペインのシェルの環境変数はペインを作ったときの値のまま残る | +| IPC ソケットの拾い直し | ペインのシェルの `VSCODE_IPC_HOOK_CLI` が使えないとき、セッション環境の `VSCODE_IPC_HOOK_CLI` が接続できればそちらを使うこと([エディタで開く](docs/specifications/editor-open.md)・[環境変数ガイド](docs/user/environment-variables.md) の tmux の節) | +| remote-cli | Remote-SSH などの VS Code サーバーが持つ CLI の置き場(`<サーバーのディレクトリ>/bin/remote-cli`)。中の `code` は `VSCODE_IPC_HOOK_CLI` のソケットを通じて、手元の VS Code に窓を開かせる | +| デスクトップ版の code | ホストに入れたデスクトップ版の VS Code の CLI。`VSCODE_IPC_HOOK_CLI` を読まず、ホストの VS Code に向けて開く | + +## 前提 + +- 前提 1: 合う `remote-cli` は、セッション環境の `VSCODE_GIT_ASKPASS_NODE`(VS Code サーバーの `node` のパス)から求める。`node` の置かれたディレクトリの `bin/remote-cli` を合う `remote-cli` とする。現行の配置(`~/.vscode-server/cli/servers/Stable-/server/node`)と旧い配置(`~/.vscode-server/bin//node`)のどちらでも、この関係が成り立つ。`VSCODE_GIT_ASKPASS_NODE` は tmux の `update-environment` の既定に入っていないため、[環境変数ガイド](docs/user/environment-variables.md) の推奨設定(`set -ga update-environment " VSCODE_IPC_HOOK_CLI … VSCODE_GIT_ASKPASS_NODE …"`)を入れた利用者でだけセッション環境に入る +- 前提 2: セッション環境から合う `remote-cli` が求められないとき(`VSCODE_GIT_ASKPASS_NODE` が無い・消されている・求めたディレクトリに `code` が無い)は、ほかの場所を探さない。`PATH` を変えずにこれまでどおり起動し、合う `remote-cli` が見つからなかったことと、推奨設定の場所を警告のログに出す。サーバーのディレクトリを探して使う方法は、拾い直したソケットと版がずれ得るため採らない +- 前提 3: 拾い直したソケットと合う `remote-cli` の `code` で URI を開けば、手元の PC の VS Code に窓が開く。起票の時点で確かめたのは終了コード 0 までで、窓が開くことは未確認(手動確認で確かめる) +- 前提 4: `DEVBASE_EDITOR` で実行ファイルを指定しているときも、`PATH` の差し替えは同じに行う。`DEVBASE_EDITOR` が絶対パスなら、その実行ファイルがそのまま使われる(`PATH` で探さないため)。Cursor など VS Code 以外のサーバーでも、前提 1 の関係が成り立てば同じに扱う + +## 対象範囲 + +含む: +- IPC ソケットを拾い直したときに、セッション環境から合う `remote-cli` を求め、エディタを探す `PATH` と起動するエディタへ渡す `PATH` の先頭に入れること +- 合う `remote-cli` を求められなかったときの警告のログ +- 上の振る舞いを確かめる単体テスト +- 確定仕様([エディタで開く](docs/specifications/editor-open.md))と[環境変数ガイド](docs/user/environment-variables.md)の tmux の節への反映 +- `CHANGELOG.md` の `[Unreleased]` の記入 + +含まない: +- 拾い直しが起きないときの振る舞い(ペインのソケットが生きている・tmux の外・セッション環境に生きたソケットが無い) +- `VSCODE_GIT_ASKPASS_NODE` が無いときに VS Code サーバーのディレクトリを探す方法(前提 2) +- 実行の場面の判定(VS Code の中か・SSH 越しか)、方針の決め方、URI の組み立て +- ペインのシェル自身の環境変数を追随させる仕組み(シェルのフック) +- tmux の `update-environment` の既定を利用者の設定へ書き込むこと + +## ドメインイベント + +| # | イベント | 引き金 | 失敗したとき | 順序の前提 | +| --- | --- | --- | --- | --- | +| E1 | 利用者が tmux のペインで `devbase` からエディタを開いた | `devbase up` の後のエディタの自動オープン・`devbase open` | — | — | +| E2 | ペインのシェルの IPC ソケットを使えないと判定した | E1 | 判定できない(tmux 外・tmux の失敗)ときは拾い直しをせず、これまでの振る舞い | E1 | +| E3 | セッション環境から接続できる IPC ソケットを拾い直した | E2 | 拾えなければ IPC 無しとして扱う(これまでの振る舞い。この課題の範囲外) | E2 | +| E4 | セッション環境から VS Code サーバーの `node` のパスを読んだ | E3 | 無い・消されている → 前提 2 の警告、`PATH` は変えない(受け入れ条件 4) | E3 | +| E5 | 合う `remote-cli` を求め、`PATH` の先頭に入れた | E4 | 求めたディレクトリに `code` が無い → 前提 2 の警告、`PATH` は変えない(受け入れ条件 5) | E4 | +| E6 | 起動するエディタを `PATH` から求めた | E5 か E4・E5 の失敗 | 見つからなければ skip(これまでの振る舞い) | E3 の後 | +| E7 | エディタを、拾い直したソケットと差し替えた `PATH` で起動した | E6 | 起動の失敗は警告にして `up` を続ける(これまでの振る舞い) | E6 | + +## 受け入れ条件 + +- [ ] 1. 再現手順の条件(ペインの `PATH` の先頭の `code` がデスクトップ版で、セッション環境のソケットだけが接続できる)で、セッション環境に `VSCODE_GIT_ASKPASS_NODE=<サーバー>/node` があり `<サーバー>/bin/remote-cli/code` が実在するとき、起動するコマンドの先頭の `code` は `<サーバー>/bin/remote-cli/code` に解決される +- [ ] 2. 1 の起動で、エディタへ渡す環境の `PATH` の先頭の要素は `<サーバー>/bin/remote-cli` で、`VSCODE_IPC_HOOK_CLI` は拾い直したソケットである。`PATH` の 2 番目以降は、ペインの `PATH` の要素を同じ順で持つ(単体テストで確かめる) +- [ ] 3. 1 のとき、使った `remote-cli` のディレクトリを info のログに 1 行出す +- [ ] 4. ソケットを拾い直したが、セッション環境の `VSCODE_GIT_ASKPASS_NODE` が未設定か消されている(`-VSCODE_GIT_ASKPASS_NODE`)とき、`PATH` は変えず、合う `remote-cli` が見つからなかったことと[環境変数ガイド](docs/user/environment-variables.md)の tmux の設定を案内する警告を 1 行出す。起動はこれまでどおり行う +- [ ] 5. ソケットを拾い直したが、`VSCODE_GIT_ASKPASS_NODE` から求めたディレクトリに実行できる `code` が無いとき、`PATH` は変えず、4 と同じ形の警告を出す +- [ ] 6. 拾い直しが起きないとき(ペインのソケットが接続できる・tmux の外・セッション環境に接続できるソケットが無い)は、起動するコマンドと渡す環境が変更前と同じである。`tests/editor/` の既存のテストが変更なしで通る +- [ ] 7. ペインのソケットを以前のクライアントのものとして外し、セッション環境からも拾えなかったとき、`PATH` から `remote-cli` を除いて手元の `code` を探す振る舞いは変わらない +- [ ] 8. 確定仕様([エディタで開く](docs/specifications/editor-open.md))と[環境変数ガイド](docs/user/environment-variables.md)の tmux の節に、拾い直したときに合う `remote-cli` を `PATH` の先頭に入れること・それに `VSCODE_GIT_ASKPASS_NODE` を `update-environment` に入れる必要があることが書かれている + +## 非機能の条件 + +| 大項目 | 条件 | +| --- | --- | +| 性能・拡張性 | 追加の外部コマンドは、拾い直したときの `tmux show-environment VSCODE_GIT_ASKPASS_NODE` の 1 回だけで、既存の待ち時間の上限(2 秒)に従う。拾い直しが起きないときは追加の呼び出しをしない | +| 運用・保守性 | 合う `remote-cli` が見つからなかった理由を、利用者が直し方まで辿れる警告で出す(受け入れ条件 4・5) | +| セキュリティ | セッション環境の値から求めたパスは、`remote-cli` という名のディレクトリで、中に実行できる `code` があるときだけ `PATH` に入れる | + +## 影響 + +| 対象 | 影響 | +| --- | --- | +| 公開インタフェース | 変わらない(コマンドの引数・環境変数の名前・設定のキーは増えない) | +| データ | 無し | +| 既存の振る舞い | tmux でソケットを拾い直したときに起動するエディタの実行ファイルと、エディタへ渡す `PATH` が変わる | + +## 検証手段 + +| 項目 | 手段 | +| --- | --- | +| テスト | `env -u DEVBASE_ROOT uv run --locked pytest tests/editor -q` | +| 静的解析・型検査 | `uvx ruff check --select=E9,F63,F7,F82 lib` | +| 手動確認 | 利用者が、手元の PC の VS Code → Remote-SSH → macOS のホストの tmux のペイン(再現手順の状態、`update-environment` に `VSCODE_GIT_ASKPASS_NODE` を入れたもの)で `devbase open proj-a` を実行し、手元の PC の VS Code に dev コンテナへ接続した窓が開くことを見る(リリース後テスト) | + +## 前提とする取り決め + +| 項目 | 参照先 / 決めたこと | +| --- | --- | +| プロジェクト構造 | `AGENTS.md` の「このリポジトリ」。実装は `lib/devbase/editor/`、テストは `tests/editor/` | +| コーディング規約 | `AGENTS.md` の「書き方」と周りのコードの書き方。確認は検証手段の静的解析 | +| テスト戦略 | 単体テストで担保する。tmux とソケットは既存のテストと同じく差し替え口で与え、実の tmux サーバーと VS Code に触れない(`AGENTS.md` の落とし穴の tmux の行)。手元の PC で窓が開くことは手動確認で見る | + +## 境界 + +| 区分 | 内容 | +| --- | --- | +| 常に行う | `tests/editor` のテストと静的解析の実行、`CHANGELOG.md` の `[Unreleased]` の記入 | +| 確認してから行う | 無し(公開インタフェースの変更・依存パッケージの追加は無い) | +| 行わない | 利用者の tmux 設定(`~/.tmux.conf`)の書き換え、範囲外のエディタの自動オープンの整理、実の tmux サーバーに触れるテスト | + +## 未決 + +| 項目 | 誰が決めるか | 期限 | +| --- | --- | --- | +| 前提 2(`VSCODE_GIT_ASKPASS_NODE` が無いときにサーバーのディレクトリを探さない)でよいか | 利用者 | 設計承認ゲート | + +## 依頼(原文) + +利用者の指示の原文は、課題の本文に引用されていない。起票時の課題の本文(起票者の調査の記録)をそのまま写す。 + +> ## 起きていること +> +> 手元の PC の VS Code から Remote-SSH で macOS のホストへ入り、そこの tmux の中で `devbase` からプロジェクト(`proj-a`)のエディタを開こうとすると、手元の PC の VS Code に窓が開かない。エラーも出ない。 +> +> ## 再現の条件 +> +> - 手元の PC の VS Code → Remote-SSH → macOS のホスト +> - ホストにデスクトップ版の VS Code が入っていて、`/usr/local/bin/code` がその CLI を指している +> - `devbase` を tmux のペインの中で実行する。ペインは以前のクライアントの環境で作られていて、`VSCODE_IPC_HOOK_CLI` のソケットはもう無く、`PATH` に Remote-SSH の `remote-cli` が入っていない +> - tmux のセッション環境には、いま attach しているクライアントの `VSCODE_IPC_HOOK_CLI`(接続できる)がある +> +> ## 原因 +> +> `lib/devbase/editor/opener.py` の `_prepare_ipc_env` は、tmux のセッション環境からソケットを拾い直すと `VSCODE_IPC_HOOK_CLI` だけを差し替え、`PATH` は変えない。`resolve_editor_cmd` が引く `code` はペインの `PATH` の先頭にある `/usr/local/bin/code`(デスクトップ版)になる。 +> +> デスクトップ版の CLI(`Visual Studio Code.app/Contents/Resources/app/out/cli.js`)は `VSCODE_IPC_HOOK_CLI` を読まない(ファイル中の出現は 0。`remote-cli` の `server-cli.js` では 1)。そのため手元の PC へは何も届かず、ホスト側のデスクトップ版に向けて開こうとして終わる。 +> +> 判定そのものは正しい。`detect_context` は `in_vscode=True`・`is_ssh=True` を返し、方針は `launch`(VS Code 統合ターミナル経由)で、URI もネストした authority(`…@ssh-remote+/work`)で組まれている。違うのは起動する実行ファイルだけ。 +> +> ## 確かめたこと +> +> - `open_editor` の起動を差し替えて実行すると、起動されるのは `['code', '--folder-uri', 'vscode-remote://attached-container+…@ssh-remote+/work']` で、`code` は `/usr/local/bin/code` に解決される +> - 同じ URI と拾い直したソケットを、`~/.vscode-server/cli/servers/Stable-/server/bin/remote-cli/code` で実行すると終了コードは 0(手元の PC で開くかは利用者が確認中) +> +> ## 直し方の案 +> +> 1. ソケットを拾い直したときに、それに合う `remote-cli` を `PATH` の先頭に入れる。セッション環境の `VSCODE_GIT_ASKPASS_NODE`(`…/cli/servers/Stable-/server/node`)から、サーバーのディレクトリと `bin/remote-cli` が分かる +> 2. `in_vscode` かつ `is_ssh` で、解決した `code` が `remote-cli` の下に無いときは、`~/.vscode-server/cli/servers/*/server/bin/remote-cli/code` を探して使う +> +> 1 のほうが、拾ったソケットとサーバーの版がずれない。 +> +> ## 当面の回避策 +> +> tmux の外の、Remote-SSH の統合ターミナルを新しく開き、そこで `devbase` を実行する。 +> +> ## 受け入れ条件 +> +> - 上の条件(tmux のペインの `PATH` がデスクトップ版の `code` を指し、セッション環境のソケットだけが生きている)で、起動する `code` が `remote-cli` のものになる +> - テストで、拾い直したソケットに合う `remote-cli` が `PATH` の先頭に入ることを確かめる +> - 拾い直しが起きないときの振る舞いは変えない + +(書き手: 起票者、日付: 2026-11-16。書き手が利用者でないため、利用者の指示の原文として扱わない) From 045aad4997e90a5484fb66d7fa4985c1c67366a5 Mon Sep 17 00:00:00 2001 From: "takemi.ohama" Date: Mon, 16 Nov 2026 22:31:11 +0900 Subject: [PATCH 2/7] =?UTF-8?q?Docs:=20#523=20=E3=81=AE=E8=A8=AD=E8=A8=88?= =?UTF-8?q?=E3=82=92=E6=9B=B8=E3=81=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit tmux で IPC ソケットを拾い直したときに、セッション環境の VSCODE_GIT_ASKPASS_NODE から 合う remote-cli を求めて PATH の先頭に入れる設計を書く。求められないときは PATH を変えずに 警告する。用語集へ「合う remote-cli」を足し、「デスクトップ版の code」の意味を VS Code のラッパーの振る舞い(PATH の remote-cli へ委ねる)に合わせて直す。 Co-Authored-By: Claude Opus 5.5 --- docs/glossary.md | 3 +- docs/glossary/glossary.json | 11 +- issues/issue-523-design.md | 308 ++++++++++++++++++++++++++++++++++++ 3 files changed, 319 insertions(+), 3 deletions(-) create mode 100644 issues/issue-523-design.md diff --git a/docs/glossary.md b/docs/glossary.md index 8298ad69..da251a05 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -61,7 +61,8 @@ up の後に VS Code で dev コンテナを開く(docs/specifications/editor- | セッション環境 | — | tmux のサーバーがセッションごとに持つ環境変数。update-environment に挙げた変数は attach のたびにいまのクライアントの値へ更新される。ペインのシェルの環境変数はペインを作ったときの値のまま残る | — | — | — | | IPC ソケットの拾い直し | — | ペインのシェルの VSCODE_IPC_HOOK_CLI が使えないとき、セッション環境の VSCODE_IPC_HOOK_CLI が接続できればそちらを使うこと | — | — | — | | remote-cli | — | Remote-SSH などの VS Code サーバーが持つ CLI の置き場(<サーバーのディレクトリ>/bin/remote-cli)。中の code は VSCODE_IPC_HOOK_CLI のソケットを通じて手元の VS Code に窓を開かせる | — | — | — | -| デスクトップ版の code | — | ホストに入れたデスクトップ版の VS Code の CLI。VSCODE_IPC_HOOK_CLI を読まず、ホストの VS Code に向けて開く | — | — | — | +| 合う remote-cli | — | 拾い直したソケットと同じ VS Code サーバーの remote-cli。セッション環境の VSCODE_GIT_ASKPASS_NODE(サーバーの node のパス)の置かれたディレクトリの bin/remote-cli | — | — | — | +| デスクトップ版の code | — | ホストに入れたデスクトップ版の VS Code の CLI。VSCODE_IPC_HOOK_CLI があっても、PATH に remote-cli が無ければホストの VS Code に向けて開く | — | — | — | ## 機密の置き場(`secret`) diff --git a/docs/glossary/glossary.json b/docs/glossary/glossary.json index 03fcd25c..3469fe38 100644 --- a/docs/glossary/glossary.json +++ b/docs/glossary/glossary.json @@ -1095,12 +1095,19 @@ "source": "", "pending_source": "issues/issue-523-requirements.md" }, + { + "term": "合う remote-cli", + "context": "editor", + "meaning": "拾い直したソケットと同じ VS Code サーバーの remote-cli。セッション環境の VSCODE_GIT_ASKPASS_NODE(サーバーの node のパス)の置かれたディレクトリの bin/remote-cli", + "source": "", + "pending_source": "issues/issue-523-design.md" + }, { "term": "デスクトップ版の code", "context": "editor", - "meaning": "ホストに入れたデスクトップ版の VS Code の CLI。VSCODE_IPC_HOOK_CLI を読まず、ホストの VS Code に向けて開く", + "meaning": "ホストに入れたデスクトップ版の VS Code の CLI。VSCODE_IPC_HOOK_CLI があっても、PATH に remote-cli が無ければホストの VS Code に向けて開く", "source": "", - "pending_source": "issues/issue-523-requirements.md" + "pending_source": "issues/issue-523-design.md" } ] } diff --git a/issues/issue-523-design.md b/issues/issue-523-design.md new file mode 100644 index 00000000..ee5692f2 --- /dev/null +++ b/issues/issue-523-design.md @@ -0,0 +1,308 @@ +# エディタの自動オープン: tmux でソケットを拾い直したときも手元の VS Code に窓を開く(#523) + +## 目的 + +- **今どうなっているか**: 手元の PC の VS Code から Remote-SSH で入った macOS のホストで、以前のクライアントが作った tmux のペインから `devbase` でエディタを開くと、IPC ソケットは拾い直せても、起動されるのはペインの `PATH` の先頭にあるデスクトップ版の `code` である。手元の PC には窓が開かず、エラーも出ない +- **誰に効くか**: Remote-SSH で入ったホストの tmux の中で `devbase up` / `devbase open` を使う利用者 +- **変えると何が成り立つか**: 拾い直したソケットと同じ VS Code サーバーの `remote-cli` の `code` が起動され、手元の PC の VS Code に dev コンテナへ接続した窓が開く。拾い直しが起きないときの振る舞いは変わらない + +## 適用範囲 + +- **働く範囲**: このリポジトリの CLI(エディタの自動オープンと `devbase open`)だけ。プラグインのリポジトリは触らない +- **プロジェクトごとに違うもの**: 無し(プロジェクトの設定・引数は増えない。tmux の `update-environment` は利用者の `~/.tmux.conf` の設定として案内するだけ) +- **当たるモード**: `standard` + +## あるべき姿の根拠 + +| 根拠 | 種類 | 何を示すか | +| --- | --- | --- | +| PRD1 | 外部の一次情報 | VS Code サーバーは統合ターミナルの `PATH` の先頭に自分の `remote-cli` を足す。`PATH` の先頭に合う `remote-cli` を入れる形は、VS Code 自身が統合ターミナルで作る状態と同じになる | +| PRD2 | 外部の一次情報 | デスクトップ版の `code` のラッパーは、`VSCODE_IPC_HOOK_CLI` があっても `PATH` に `remote-cli` が無ければホストの VS Code を開く。事象の原因が `PATH` にあることを示す | +| PRD3 | 外部の一次情報 | `VSCODE_GIT_ASKPASS_NODE` は VS Code サーバーの `node` の絶対パス(`process.execPath`)である。拾い直したソケットと同じサーバーを指す | +| 手元のホストの `ls` と `grep -c` | 実測 | 現行の配置で `<サーバー>/node` と `<サーバー>/bin/remote-cli/code`(実行できる)が並び、`server-cli.js` は `VSCODE_IPC_HOOK_CLI` を 1 回読み、デスクトップ版の `cli.js` は 0 回(外部の調査の「実測」の行) | + +要求と受け入れ条件は #523 の本文にある(コピーは [issue-523-requirements.md](issue-523-requirements.md))。この文書は「どう作るか」だけを扱う。 + +## ドメインモデル + +### コンテキスト + +| コンテキスト | 何の語が 1 つの意味に決まるか | +| --- | --- | +| エディタで開く(`editor`) | IPC ソケット・セッション環境・IPC ソケットの拾い直し・`remote-cli`・合う `remote-cli`・起動に渡す環境 | + +変更はこのコンテキストの中で閉じる。用語集の `tmux` のコンテキスト(base イメージの tmux のコマンド)は触らない。 + +### 集約 + +| 集約 | 持ち主(書き換えてよいもの) | 根 | エンティティ | 値オブジェクト | +| --- | --- | --- | --- | --- | +| 起動の準備 | IPC の差し替え(エディタの自動オープンの、起動に渡す環境を作る段) | 起動に渡す環境 | — | IPC ソケット・合う `remote-cli`・`PATH` | + +実行の場面の判定(`EditorContext`)は読むだけで書き換えない。判定と方針と URI の組み立ては範囲外である(要求の「含まない」)。 + +### 不変条件 + +| # | 集約 | 条件 | 破れたときの扱い | +| --- | --- | --- | --- | +| I1 | 起動の準備 | `PATH` に足す `remote-cli` は、拾い直したソケットと同じセッション環境から読んだ `VSCODE_GIT_ASKPASS_NODE` だけから求める。VS Code サーバーのディレクトリを探さない | 求められなければ `PATH` を変えない(I4) | +| I2 | 起動の準備 | 拾い直しが起きないとき、起動するコマンド・起動に渡す環境・tmux への問い合わせの回数は変更前と同じである | — | +| I3 | 起動の準備 | `PATH` に足すディレクトリは、絶対パスで、名前が `remote-cli` で、中に起動するエディタの名前の実行できるファイルがあるものだけである | 足さずに警告する(I4) | +| I4 | 起動の準備 | 合う `remote-cli` を求められないとき、`PATH` は変えず、警告を 1 行出し、起動はこれまでどおり続ける | — | +| I5 | 起動の準備 | 合う `remote-cli` を足したとき、`PATH` の先頭の要素はそのディレクトリで、2 番目以降はペインの `PATH` の要素を同じ順で持つ | — | + +### ドメインイベント + +| # | イベント | 発生元 | 受け手 | +| --- | --- | --- | --- | +| E1 | 利用者が tmux のペインで `devbase` からエディタを開いた | 利用者(`devbase up` の後の自動オープン・`devbase open`) | 実行の場面の判定 | +| E2 | ペインのシェルの IPC ソケットを使えないと判定した | 実行の場面の判定 | 実行の場面の判定(拾い直し) | +| E3 | セッション環境から接続できる IPC ソケットを拾い直した | 実行の場面の判定 | IPC の差し替え | +| E4 | セッション環境から VS Code サーバーの `node` のパスを読んだ | IPC の差し替え | 合う `remote-cli` の探索 | +| E5 | 合う `remote-cli` を求め、`PATH` の先頭に入れた | 合う `remote-cli` の探索 | エディタの解決 | +| E6 | 起動するエディタを `PATH` から求めた | エディタの解決 | 方針の決定・起動 | +| E7 | エディタを、拾い直したソケットと差し替えた `PATH` で起動した | 起動 | 利用者(手元の PC の VS Code) | + +### 用語 + +| 用語 | 意味 | 用語集への反映 | +| --- | --- | --- | +| セッション環境 | tmux のサーバーがセッションごとに持つ環境変数。`update-environment` に挙げた変数は attach のたびにいまのクライアントの値へ更新される | 追加(要求の段で追加済み) | +| IPC ソケットの拾い直し | ペインのシェルの `VSCODE_IPC_HOOK_CLI` が使えないとき、セッション環境の接続できる値を使うこと | 追加(要求の段で追加済み) | +| remote-cli | VS Code サーバーが持つ CLI の置き場(`<サーバーのディレクトリ>/bin/remote-cli`) | 追加(要求の段で追加済み) | +| 合う remote-cli | 拾い直したソケットと同じ VS Code サーバーの `remote-cli`。セッション環境の `VSCODE_GIT_ASKPASS_NODE` の置かれたディレクトリの `bin/remote-cli` | 追加 | +| デスクトップ版の code | ホストに入れたデスクトップ版の VS Code の CLI。`VSCODE_IPC_HOOK_CLI` があっても、`PATH` に `remote-cli` が無ければホストの VS Code に向けて開く | 意味の変更(ラッパーが `PATH` の `remote-cli` へ委ねることを足す。PRD2) | + +## 外部の調査 + +| 種類 | 調べるか | 理由 | +| --- | --- | --- | +| 標準・仕様 | 調べる | tmux の `update-environment` の既定に `VSCODE_GIT_ASKPASS_NODE` が入るかで、警告が要る場面が決まる | +| 主要な製品 | 調べる | VS Code のサーバー・デスクトップ版の CLI・git 拡張が、`remote-cli` と `PATH` と `node` のパスをどう扱うかが、直し方の根拠になる | +| ライブラリとサービス | 調べる | 実行ファイルの探索と起動を、既に依存している Python の標準ライブラリで足りるかを確かめる | + +### 標準・仕様 + +| # | 標準・仕様 | 何を定めているか | 設計への反映 | 出典 | +| --- | --- | --- | --- | --- | +| STD1 | tmux の `update-environment` | attach と新しいセッションの作成のたびに、挙げた変数をクライアントの環境からセッション環境へ写す。クライアントに無い変数は消された印(`-NAME`)になる。既定の一覧は `DISPLAY`・`SSH_CONNECTION` など 13 個で、`VSCODE_*` を含まない | `VSCODE_GIT_ASKPASS_NODE` は推奨設定を入れた利用者でだけセッション環境に入る。無い・消されたときは警告で推奨設定を案内する(決定 4) | `man tmux`(tmux 3.7b)、`env -u TMUX tmux -L ndf523probe -f /dev/null start-server \; show -gv update-environment \; kill-server`(2026-11-16) | + +### 主要な製品 + +| # | 製品 | どう解いているか | 設計への反映 | 出典 | +| --- | --- | --- | --- | --- | +| PRD1 | VS Code サーバーの拡張ホストの起動 | 統合ターミナルなどへ渡す環境の `PATH` の先頭に `<サーバー>/bin/remote-cli` を足す。`PATH` が無ければ `remote-cli` だけにする | 合う `remote-cli` を `PATH` の先頭に足し、ペインの要素は並びを変えずに残す(決定 2) | https://github.com/microsoft/vscode/blob/6e68549edb69380c9316e49df5d3795d5064a2b0/src/vs/server/node/extensionHostConnection.ts の 49〜58 行(2026-11-16) | +| PRD2 | VS Code のデスクトップ版の `code`(macOS のラッパー) | `VSCODE_IPC_HOOK_CLI` があるとき、`PATH` から `/remote-cli/` を含む `code` を探して委ねる。無ければデスクトップ版を開く | `PATH` に合う `remote-cli` があれば正しいクライアントへ届く。原因と直し方の根拠 | https://github.com/microsoft/vscode/blob/6e68549edb69380c9316e49df5d3795d5064a2b0/resources/darwin/bin/code.sh の 6〜13 行、手元の `/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code`(1.146.0)の 6〜13 行(2026-11-16) | +| PRD3 | VS Code の git 拡張の askpass | 端末へ渡す環境に `VSCODE_GIT_ASKPASS_NODE = process.execPath`(拡張ホストを動かす `node` の絶対パス)を入れる | `node` の置かれたディレクトリを VS Code サーバーのディレクトリとして読む(決定 1) | https://github.com/microsoft/vscode/blob/6e68549edb69380c9316e49df5d3795d5064a2b0/extensions/git/src/askpass.ts の 36〜43 行(2026-11-16) | +| PRD4 | VS Code サーバーの CLI(`server-cli`) | `VSCODE_IPC_HOOK_CLI` のソケットを通じて手元のクライアントへ依頼する | `remote-cli` の `code` には拾い直したソケットを渡す(既存の振る舞いを保つ) | https://github.com/microsoft/vscode/blob/6e68549edb69380c9316e49df5d3795d5064a2b0/src/vs/server/node/server.cli.ts の 24・87 行(2026-11-16) | +| 実測 | 手元のホストの VS Code サーバー | `~/.vscode-server/cli/servers/Stable-/server/` に `node` と `bin/remote-cli/code`(`-rwxr-xr-x`)が並ぶ。`out/server-cli.js` の `VSCODE_IPC_HOOK_CLI` は 1 回、デスクトップ版の `out/cli.js` は 0 回 | 前提 1 の関係を現行の配置で確かめた | `ls -l <サーバー>/node <サーバー>/bin/remote-cli/`、`grep -c VSCODE_IPC_HOOK_CLI <サーバー>/out/server-cli.js`(2026-11-16) | + +### ライブラリとサービス + +| # | 候補 | 版 | ライセンス | 最後のリリースの日付 | 終了のアナウンス | 要件を満たすか | 出典 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| LIB1 | Python の標準ライブラリ(`shutil.which(path=)`・`os.access`・`subprocess.Popen(env=)`) | プロジェクトの `requires-python >=3.10` に従う | PSF | Python 本体の版に従う | 無し | 満たす。`Popen` は `env` を渡すと `os.get_exec_path(env)` で実行ファイルを探すため、`PATH` の差し替えだけで起動する実行ファイルが変わる | `pyproject.toml`、`python3 -c "import inspect,subprocess; ..."` で `Popen._execute_child` の `os.get_exec_path(env)` を確認(2026-11-16) | + +依存は増えない。 + +### 確かめられなかったこと + +| 対象 | 試した手段 | 結果と理由 | +| --- | --- | --- | +| Cursor などのサーバーで `remote-cli` の中の実行ファイルの名前 | `ls ~/.cursor-server/cli/servers/*/server/bin/remote-cli` | 手元に Cursor のサーバーが無く、出力は空だった。公開の資料は試していない | +| git 拡張が統合ターミナルへ `VSCODE_GIT_ASKPASS_NODE` を渡さない設定(端末の認証を切った場合など)の有無 | 試していない | 渡さない場合は警告の経路に入る(決定 4)。設計の形は変わらない | + +調べた量: 候補 6 件・取得の試み 13 回。 + +## 機能一覧 + +| # | 機能 | 誰が使うか | +| --- | --- | --- | +| F1 | IPC ソケットを拾い直したとき、合う `remote-cli` を `PATH` の先頭に入れてエディタを探し、起動する | Remote-SSH で入ったホストの tmux で `devbase` を使う利用者 | +| F2 | 合う `remote-cli` を求められなかったとき、理由と tmux の設定の置き場を警告で示す | 同上 | +| F3 | 確定仕様と環境変数ガイドで、拾い直しと `VSCODE_GIT_ASKPASS_NODE` の設定の要否を読める | 同上・devbase の開発者 | + +## 構成要素 + +| 要素 | 責務 | +| --- | --- | +| 実行の場面の判定(既存・変えない) | ペインの IPC が使えるか、セッション環境から拾い直せるかを判定し、使うソケットを決める | +| IPC の差し替え(既存・変える) | 拾い直したとき、起動に渡す環境の `VSCODE_IPC_HOOK_CLI` を差し替え、続けて合う `remote-cli` の探索を呼ぶ。見つかれば `PATH` の先頭に足し、info を 1 行出す。見つからなければ `PATH` を変えず warning を 1 行出す | +| 合う `remote-cli` の探索(新設) | セッション環境の `VSCODE_GIT_ASKPASS_NODE` を 1 回読み、`/bin/remote-cli` を求め、I3 の条件を確かめる。結果は「ディレクトリ」か「見つからない理由(未設定・消された・実行ファイルが無い)」のどちらか | +| エディタの解決(既存・呼び方を変える) | `PATH` を差し替えたときは、差し替えた `PATH` でエディタを探す(現状は IPC を外したときだけ起動に渡す環境の `PATH` を渡し、ほかは実行中のプロセスの `PATH` で探す) | +| 起動(既存・変えない) | 起動に渡す環境の `PATH` で実行ファイルを探して起動する(LIB1) | +| 確定仕様・環境変数ガイド・変更履歴(変える) | 拾い直したときの `PATH` の扱いと、`VSCODE_GIT_ASKPASS_NODE` を `update-environment` に入れる必要を書く。`[Unreleased]` に利用者に見える変更を書く | + +```mermaid +graph TD + subgraph エディタの自動オープン + 判定[実行の場面の判定] --> 差し替え[IPC の差し替え] + 差し替え --> 探索[合う remote-cli の探索] + 差し替え --> 解決[エディタの解決] + 解決 --> 起動[起動] + end + 探索 --> セッション環境[(tmux のセッション環境)] + 判定 --> セッション環境 + 文書[確定仕様・環境変数ガイド・変更履歴] +``` + +文書の要素は実行の流れに加わらないため、図では辺を持たない。 + +### システムの文脈と配置 + +```mermaid +graph LR + subgraph 手元の PC + VSC[VS Code] + end + subgraph macOS のホスト + TMUX[(tmux のサーバー)] + DB[devbase] + RC[VS Code サーバーの remote-cli] + DESK[デスクトップ版の code] + end + VSC -- Remote-SSH --> RC + DB -- show-environment --> TMUX + DB -- 起動 --> RC + RC -- IPC ソケット --> VSC + DB -. 変更前の起動 .-> DESK +``` + +変えるのは devbase だけである。tmux のサーバー・VS Code サーバー・デスクトップ版の `code`・手元の VS Code は変えられない外部の系として扱う。 + +## 構造 + +型の追加・変更は無い(`EditorContext`・`OpenPlan` は変えない)。変えるのはエディタの自動オープンのモジュールの中の処理の順序で、次の節に描く。関数の粒度の配置は詳細設計の文書が持つ。 + +## 処理の流れ + +```mermaid +sequenceDiagram + participant 判定 as 実行の場面の判定 + participant 差し替え as IPC の差し替え + participant 探索 as 合う remote-cli の探索 + participant tmux as tmux のセッション環境 + 判定->>tmux: SSH_CONNECTION・VSCODE_IPC_HOOK_CLI を読む + 判定->>差し替え: 使うソケット + alt 拾い直した + 差し替え->>探索: 合う remote-cli を求める + 探索->>tmux: VSCODE_GIT_ASKPASS_NODE を読む + alt 合う remote-cli がある + 探索-->>差し替え: remote-cli のディレクトリ + Note over 差し替え: IPC を差し替え、PATH の先頭に足す(info) + else 未設定・消された・実行できるエディタが無い + 探索-->>差し替え: 見つからない理由 + Note over 差し替え: IPC だけ差し替え、PATH はそのまま(warning) + end + else 拾い直していない + Note over 差し替え: 変更前と同じ起動に渡す環境(tmux へ問い合わせない) + end + Note over 判定,差し替え: エディタの解決が起動に渡す環境の PATH でエディタを探して方針を決め、起動が同じ PATH で実行ファイルを探して起動する +``` + +「拾い直した」は、判定が使うと決めたソケットがペインの `VSCODE_IPC_HOOK_CLI` と違うときを指す。ペインのソケットが死んでいた場合と、ペインのソケットが以前のクライアントのもので使わない場合(`ipc_from_previous_client`)の両方を含む。ペインに `VSCODE_IPC_HOOK_CLI` が無く、セッション環境から拾えた場合も含む。 + +拾い直したときに出すログは次の 2 つで、どちらか 1 行だけを出す。既存の「拾い直しました」の info はそのまま残す。 + +| 場面 | 水準 | 載せること | +| --- | --- | --- | +| 合う `remote-cli` を足した | info | 足した `remote-cli` のディレクトリ | +| 求められなかった | warning | 合う `remote-cli` が見つからなかったこと、理由(未設定・消された・実行できるエディタが無い)、手元の `code` で起動すること、環境変数ガイドの tmux の設定(`update-environment` に `VSCODE_GIT_ASKPASS_NODE` を入れる)の案内 | + +## 非機能の実現方式 + +| 大項目 | 要求の条件 | 実現方式 | 確かめ方 | +| --- | --- | --- | --- | +| 性能・拡張性 | 追加の外部コマンドは、拾い直したときの `tmux show-environment VSCODE_GIT_ASKPASS_NODE` の 1 回だけで、既存の待ち時間の上限(2 秒)に従う。拾い直しが起きないときは追加の呼び出しをしない | 探索は拾い直したときの分岐の中からだけ呼び、既存のセッション環境の読み(上限 2 秒)を 1 回使う。ファイルの確かめは `stat` 系の呼び出しだけで外部コマンドを起動しない | tmux の呼び出しを差し替えて数え、拾い直したときは 1 回増え、拾い直さないときは増えないことを単体テストで見る | +| 運用・保守性 | 合う `remote-cli` が見つからなかった理由を、利用者が直し方まで辿れる警告で出す | warning に理由の区分と環境変数ガイドの tmux の設定への案内を載せる(処理の流れの表) | 理由ごとに warning の文面を単体テストで見る | +| セキュリティ | セッション環境の値から求めたパスは、`remote-cli` という名のディレクトリで、中に実行できる `code` があるときだけ `PATH` に入れる | 値が絶対パスでないときは足さない。求めたディレクトリの名前が `remote-cli` で、中の起動するエディタの名前のファイルが通常のファイルで実行できるときだけ足す(決定 3) | 相対パス・実行権の無いファイル・ディレクトリの `code` で足さないことを単体テストで見る | + +## 決定の記録 + +### 決定 1: 拾い直したソケットと同じサーバーを使うため、セッション環境の `VSCODE_GIT_ASKPASS_NODE` から合う `remote-cli` を求める + +`VSCODE_GIT_ASKPASS_NODE` は VS Code サーバーの `node` の絶対パスで(PRD3)、`VSCODE_IPC_HOOK_CLI` と同じ attach でセッション環境へ写る(STD1)。同じ読みから求めれば、ソケットとサーバーの版がずれない。`node` の置かれたディレクトリの `bin/remote-cli` を合う `remote-cli` とし、現行の配置と旧い配置のどちらでもこの関係が成り立つ(実測・要求の前提 1)。 + +VS Code サーバーのディレクトリ(`~/.vscode-server/cli/servers/*`)を探して選ぶ方法は採らない。手元のホストに版の違うサーバーが 6 つ並んでおり(実測。`ls -d ~/.vscode-server/cli/servers/*/server | wc -l` が 6)、どれが拾い直したソケットのものかを決める手がかりが無いためである。 + +- 作り方: 自前で作る・標準に倣う +- 比べた候補: STD1 / PRD1 / PRD3 / LIB1 + +根拠: Mission / Value 1(MVV 版 1) + +### 決定 2: VS Code の統合ターミナルと同じ状態にするため、合う `remote-cli` を `PATH` の先頭に足し、ペインの要素は並びを変えずに残す + +VS Code サーバーは統合ターミナルの `PATH` の先頭に自分の `remote-cli` を足し、ほかの要素は触らない(PRD1)。同じ形にすれば、エディタの子のプロセス(`remote-cli` の `code` が使う `dirname` など)もペインの `PATH` で動く。ペインの `PATH` に別の版の `remote-cli` が残っていても、先頭の要素が先に当たるため起動には使われない。ペインのシェルの環境変数に `PATH` が無いときは、PRD1 と同じく `remote-cli` だけを `PATH` にする。 + +ペインの `PATH` から古い `remote-cli` を除いてから足す方法は採らない。先頭に足すだけで起動する実行ファイルは決まり、除くと受け入れ条件 2 の「2 番目以降はペインの要素を同じ順で持つ」を満たさなくなる。 + +- 作り方: 標準に倣う +- 比べた候補: PRD1 / PRD2 + +根拠: Value 1(MVV 版 1) + +### 決定 3: セッション環境の値で任意の場所を `PATH` に入れないため、絶対パス・`remote-cli` の名前・実行できるエディタの 3 つを満たすときだけ足す + +セッション環境の値は attach してきたクライアントが決める。相対パスを許すと、`devbase` を実行したディレクトリからの位置として読まれる。そのため値が絶対パスであること、求めたディレクトリの名前が `remote-cli` であること、中に起動するエディタの名前の通常のファイルがあり実行できることを確かめる。確かめに外部コマンドは使わない(非機能の条件)。 + +確かめるファイルの名前は、起動するエディタの名前とする。既定は `code`、`DEVBASE_EDITOR` があればその先頭の語のファイル名(絶対パスならその末尾)である。要求の前提 4 のとおり Cursor など VS Code 以外のサーバーも同じに扱うため、`code` に固定しない。`DEVBASE_EDITOR` が絶対パスでも `PATH` の差し替えは同じに行い、起動する実行ファイルはその絶対パスのまま変わらない。 + +- 作り方: 自前で作る +- 比べた候補: LIB1 / PRD2 + +根拠: Value 3(MVV 版 1) + +### 決定 4: 版のずれたサーバーへ委ねないため、合う `remote-cli` を求められないときはほかを探さず、`PATH` を変えずに警告する + +`VSCODE_GIT_ASKPASS_NODE` が未設定・消された(`-VSCODE_GIT_ASKPASS_NODE`)・求めたディレクトリに実行できるエディタが無い、のいずれでも、`PATH` を変えずにこれまでどおり起動し、warning を 1 行出す。tmux の既定の `update-environment` は `VSCODE_*` を含まないため(STD1)、この経路は推奨設定を入れていない利用者で必ず通る。警告には環境変数ガイドの tmux の設定を案内し、利用者が `~/.tmux.conf` に 1 行足せば次から直る形にする。 + +サーバーのディレクトリを探して代わりに使う方法は採らない(決定 1 と同じ理由)。起動を止める方法も採らない。これまでの振る舞いより悪くしないためである。 + +根拠: Value 1(MVV 版 1) + +### 決定 5: 起動の形を変えないため、起動するコマンドの先頭の語はエディタの名前のまま残し、起動に渡す環境の `PATH` で解決させる + +`subprocess.Popen` は渡した環境変数の `PATH` で実行ファイルを探す(LIB1)。エディタの解決も同じ `PATH` で探すようにすれば(構成要素の「エディタの解決」)、存在の確かめと起動が同じ実行ファイルを指す。先頭の語を絶対パスへ書き換えないので、`DEVBASE_EDITOR` に引数を書いた場合も、起動のログと既存のテストの期待値の形も変わらない。 + +先頭の語を `remote-cli` の絶対パスへ書き換える方法は採らない。`PATH` の差し替えと 2 か所で同じ事実を持つことになり、`DEVBASE_EDITOR` が絶対パスのときの扱いが分かれるためである。 + +- 作り方: ライブラリやサービスを使う +- 比べた候補: LIB1 + +根拠: Value 1(MVV 版 1) + +## テスト設計 + +| 受け入れ条件・不変条件 | どの振る舞いで縛るか | どう壊したら落ちるべきか | +| --- | --- | --- | +| 受け入れ条件 1 | ペインの `PATH` の先頭にデスクトップ版を模した `code`、セッション環境だけが接続できるソケットと `VSCODE_GIT_ASKPASS_NODE=<サーバー>/node` を持ち、`<サーバー>/bin/remote-cli/code` が実在するとき、起動するコマンドの先頭の語を起動に渡す環境の `PATH` で解決すると `<サーバー>/bin/remote-cli/code` になる | 探索を呼ばない・エディタの解決が実行中のプロセスの `PATH` で探す、と落ちる | +| 受け入れ条件 2・I5 | 1 の起動で渡す環境の `PATH` の先頭が `<サーバー>/bin/remote-cli`、2 番目以降がペインの `PATH` と同じ並び、`VSCODE_IPC_HOOK_CLI` が拾い直したソケット | 末尾へ足す・ペインの要素を除く・並べ替える・IPC を差し替えない、と落ちる | +| 受け入れ条件 3 | 1 のとき、足したディレクトリを含む info が 1 行出る | ログを出さない・2 行以上出す、と落ちる | +| 受け入れ条件 4・I4 | 拾い直したがセッション環境の `VSCODE_GIT_ASKPASS_NODE` が未設定・消されたとき、`PATH` はペインのまま、tmux の設定を案内する warning が 1 行出て、起動は行われる | `PATH` を変える・警告を出さない・起動を止める・消された印をパスとして扱う、と落ちる | +| 受け入れ条件 5・I4 | 求めたディレクトリに `code` が無い・実行できないとき、4 と同じ形の warning が出て `PATH` は変わらない | 実在だけを見て実行権を見ない・ディレクトリの存在だけで足す、と落ちる | +| 受け入れ条件 6・I2 | ペインのソケットが接続できる・tmux の外・セッション環境に接続できるソケットが無いとき、起動するコマンドと渡す環境が変更前と同じで、`VSCODE_GIT_ASKPASS_NODE` を問い合わせない。`tests/editor/` の既存のテストが変更なしで通る | 拾い直していないときにも探索を呼ぶ・`PATH` を触る、と落ちる | +| 受け入れ条件 7 | ペインのソケットを以前のクライアントのものとして外し、セッション環境からも拾えないとき、`PATH` から `remote-cli` を除いて手元の `code` を探す | 探索の追加で IPC を外す経路の `PATH` の扱いが変わる、と落ちる(既存のテストが縛る) | +| 受け入れ条件 8 | 確定仕様と環境変数ガイドの tmux の節に、拾い直したときに合う `remote-cli` を `PATH` の先頭に入れること・`VSCODE_GIT_ASKPASS_NODE` を `update-environment` に入れる必要があることが書かれている | 文書の確認(レビューと手動の読み合わせ) | +| I1 | セッション環境の `VSCODE_GIT_ASKPASS_NODE` が無く、VS Code サーバーのディレクトリには `remote-cli/code` が実在するとき、`PATH` は変わらない | サーバーのディレクトリを探して足す、と落ちる | +| I3 | `VSCODE_GIT_ASKPASS_NODE` が相対パスのとき・求めた場所の `code` がディレクトリのとき、`PATH` に足さず warning を出す。`DEVBASE_EDITOR=cursor` のときは `remote-cli/cursor` の有無で決まる | 名前を `code` に固定する・相対パスを受け入れる・ディレクトリを実行ファイルとみなす、と落ちる | +| 性能の条件 | 拾い直したときの tmux の問い合わせは変更前より 1 回だけ多い | 2 回以上読む・拾い直さないときにも読む、と落ちる | +| 手動確認(前提 3) | 手元の PC の VS Code → Remote-SSH → macOS のホストの tmux のペインで `devbase open proj-a` を実行し、手元の PC に dev コンテナへ接続した窓が開く | リリース後テストで利用者が見る | + +## 設計の結果 + +| 課題 | 扱い | 取り込み先 | 触るファイル | +| --- | --- | --- | --- | +| #523 | 実装する | — | `lib/devbase/editor/opener.py`、`tests/editor/test_opener.py`、`docs/specifications/editor-open.md`、`docs/user/environment-variables.md`、`CHANGELOG.md` | + +## 人へ残す判断 + +無し + +## 未確認のまま残ること + +| 項目 | 内容 | +| --- | --- | +| 手元の PC に窓が開くこと(前提 3) | 起票の時点で確かめたのは `remote-cli` の `code` の終了コード 0 までである。窓が開くかはリリース後テストで、利用者が手元の PC の VS Code から確かめる | +| Cursor などのサーバーでの `remote-cli` の中身 | 手元に無く確かめていない(外部の調査の「確かめられなかったこと」)。中の実行ファイルの名前が起動するエディタの名前と違えば、決定 4 の警告の経路に入る。使う利用者が現れた時点の報告で分かる | +| git 拡張が `VSCODE_GIT_ASKPASS_NODE` を端末へ渡さない場面 | 設定によって渡さない場面があるかを確かめていない。渡さない場合は決定 4 の警告の経路に入り、これまでの振る舞いのまま起動する。警告を受けた利用者の報告で分かる | +| macOS 以外のホスト(Linux・WSL2)での振る舞い | 確かめたのは macOS のホストだけである。`node` と `bin/remote-cli` の位置関係は VS Code サーバーの配置で決まり OS に依らないと読んでいるが、実機では確かめていない。Linux のホストで Remote-SSH を使う利用者の報告で分かる | From 48329f467ea3fb43b9abb43c386adec21970d6c3 Mon Sep 17 00:00:00 2001 From: "takemi.ohama" Date: Mon, 16 Nov 2026 22:34:53 +0900 Subject: [PATCH 3/7] =?UTF-8?q?Docs:=20#523=20=E3=81=AE=E8=A8=AD=E8=A8=88?= =?UTF-8?q?=E3=82=92=E8=A8=AD=E8=A8=88=E5=8D=98=E4=BD=93=E3=81=AE=E3=83=AC?= =?UTF-8?q?=E3=83=93=E3=83=A5=E3=83=BC=E3=81=AB=E5=90=88=E3=82=8F=E3=81=9B?= =?UTF-8?q?=E3=81=A6=E7=9B=B4=E3=81=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 人へ残す判断に、要求の前提 2 の採否と起票者の推定 S1〜S6 の確認を載せる - 「拾い直した」と受け入れ条件 6 の「ペインのソケットが接続できる」の区分をそろえる - 拾い直す場面の既存のテストが追加の tmux の問い合わせを受けても通ることをテスト設計に足す - ソケットと node のパスの 2 つの読みが同じ attach の値であることは保証しない、と I1・決定 1 を弱める - 触るファイルに用語集を足す Co-Authored-By: Claude Opus 5.5 --- issues/issue-523-design.md | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/issues/issue-523-design.md b/issues/issue-523-design.md index ee5692f2..fc0a9192 100644 --- a/issues/issue-523-design.md +++ b/issues/issue-523-design.md @@ -45,8 +45,8 @@ | # | 集約 | 条件 | 破れたときの扱い | | --- | --- | --- | --- | -| I1 | 起動の準備 | `PATH` に足す `remote-cli` は、拾い直したソケットと同じセッション環境から読んだ `VSCODE_GIT_ASKPASS_NODE` だけから求める。VS Code サーバーのディレクトリを探さない | 求められなければ `PATH` を変えない(I4) | -| I2 | 起動の準備 | 拾い直しが起きないとき、起動するコマンド・起動に渡す環境・tmux への問い合わせの回数は変更前と同じである | — | +| I1 | 起動の準備 | `PATH` に足す `remote-cli` は、ソケットを拾い直したのと同じ tmux のセッションのセッション環境から読んだ `VSCODE_GIT_ASKPASS_NODE` だけから求める。VS Code サーバーのディレクトリを探さない。ソケットの読みと `VSCODE_GIT_ASKPASS_NODE` の読みは別の tmux の呼び出しで、2 つが同じ attach の値であることは保証しない(決定 1) | 求められなければ `PATH` を変えない(I4) | +| I2 | 起動の準備 | 拾い直しが起きないとき(処理の流れの「拾い直した」に当たらないとき)、起動するコマンド・起動に渡す環境・tmux への問い合わせの回数は変更前と同じである | — | | I3 | 起動の準備 | `PATH` に足すディレクトリは、絶対パスで、名前が `remote-cli` で、中に起動するエディタの名前の実行できるファイルがあるものだけである | 足さずに警告する(I4) | | I4 | 起動の準備 | 合う `remote-cli` を求められないとき、`PATH` は変えず、警告を 1 行出し、起動はこれまでどおり続ける | — | | I5 | 起動の準備 | 合う `remote-cli` を足したとき、`PATH` の先頭の要素はそのディレクトリで、2 番目以降はペインの `PATH` の要素を同じ順で持つ | — | @@ -70,8 +70,8 @@ | セッション環境 | tmux のサーバーがセッションごとに持つ環境変数。`update-environment` に挙げた変数は attach のたびにいまのクライアントの値へ更新される | 追加(要求の段で追加済み) | | IPC ソケットの拾い直し | ペインのシェルの `VSCODE_IPC_HOOK_CLI` が使えないとき、セッション環境の接続できる値を使うこと | 追加(要求の段で追加済み) | | remote-cli | VS Code サーバーが持つ CLI の置き場(`<サーバーのディレクトリ>/bin/remote-cli`) | 追加(要求の段で追加済み) | -| 合う remote-cli | 拾い直したソケットと同じ VS Code サーバーの `remote-cli`。セッション環境の `VSCODE_GIT_ASKPASS_NODE` の置かれたディレクトリの `bin/remote-cli` | 追加 | -| デスクトップ版の code | ホストに入れたデスクトップ版の VS Code の CLI。`VSCODE_IPC_HOOK_CLI` があっても、`PATH` に `remote-cli` が無ければホストの VS Code に向けて開く | 意味の変更(ラッパーが `PATH` の `remote-cli` へ委ねることを足す。PRD2) | +| 合う remote-cli | 拾い直したソケットと同じ VS Code サーバーの `remote-cli`。セッション環境の `VSCODE_GIT_ASKPASS_NODE` の置かれたディレクトリの `bin/remote-cli` | 追加(この設計の段で `docs/glossary.md` と `docs/glossary/glossary.json` に反映済み) | +| デスクトップ版の code | ホストに入れたデスクトップ版の VS Code の CLI。`VSCODE_IPC_HOOK_CLI` があっても、`PATH` に `remote-cli` が無ければホストの VS Code に向けて開く | 意味の変更(ラッパーが `PATH` の `remote-cli` へ委ねることを足す。PRD2。この設計の段で同じ 2 つのファイルに反映済み) | ## 外部の調査 @@ -200,7 +200,9 @@ sequenceDiagram Note over 判定,差し替え: エディタの解決が起動に渡す環境の PATH でエディタを探して方針を決め、起動が同じ PATH で実行ファイルを探して起動する ``` -「拾い直した」は、判定が使うと決めたソケットがペインの `VSCODE_IPC_HOOK_CLI` と違うときを指す。ペインのソケットが死んでいた場合と、ペインのソケットが以前のクライアントのもので使わない場合(`ipc_from_previous_client`)の両方を含む。ペインに `VSCODE_IPC_HOOK_CLI` が無く、セッション環境から拾えた場合も含む。 +「拾い直した」は、判定が使うと決めたソケットがペインの `VSCODE_IPC_HOOK_CLI` と違うときを指す。ペインのソケットが死んでいた場合と、ペインのソケットが接続できても以前のクライアントのものとして使わず、セッション環境のソケットを使うと決めた場合(`ipc_from_previous_client`)の両方を含む。ペインに `VSCODE_IPC_HOOK_CLI` が無く、セッション環境から拾えた場合も含む。 + +受け入れ条件 6 の「ペインのソケットが接続できる」は、接続できて、かつ判定がペインのソケットを使うと決めた場合を指す。接続できても以前のクライアントのものとして使わない場合は、セッション環境から拾えれば「拾い直した」に入り `PATH` を変える。拾えなければ受け入れ条件 7 の経路(IPC を外す)に入る。I2 とテスト設計の受け入れ条件 6 の行は、この区分に従う。 拾い直したときに出すログは次の 2 つで、どちらか 1 行だけを出す。既存の「拾い直しました」の info はそのまま残す。 @@ -213,7 +215,7 @@ sequenceDiagram | 大項目 | 要求の条件 | 実現方式 | 確かめ方 | | --- | --- | --- | --- | -| 性能・拡張性 | 追加の外部コマンドは、拾い直したときの `tmux show-environment VSCODE_GIT_ASKPASS_NODE` の 1 回だけで、既存の待ち時間の上限(2 秒)に従う。拾い直しが起きないときは追加の呼び出しをしない | 探索は拾い直したときの分岐の中からだけ呼び、既存のセッション環境の読み(上限 2 秒)を 1 回使う。ファイルの確かめは `stat` 系の呼び出しだけで外部コマンドを起動しない | tmux の呼び出しを差し替えて数え、拾い直したときは 1 回増え、拾い直さないときは増えないことを単体テストで見る | +| 性能・拡張性 | 追加の外部コマンドは、拾い直したときの `tmux show-environment VSCODE_GIT_ASKPASS_NODE` の 1 回だけで、既存の待ち時間の上限(2 秒)に従う。拾い直しが起きないときは追加の呼び出しをしない | 探索は拾い直したときの分岐の中からだけ呼び、既存のセッション環境の読み(上限 2 秒)を 1 回使う。ファイルの確かめは `stat` 系の呼び出しだけで外部コマンドを起動しない | tmux の呼び出しを差し替えて数え、拾い直したときは 1 回増え、拾い直さないときは増えないことを新しい単体テストで見る。拾い直す場面の既存のテストが増えた 1 回を受けても変わらず通ることは、テスト設計の「受け入れ条件 6(既存のテスト)」の行で見る | | 運用・保守性 | 合う `remote-cli` が見つからなかった理由を、利用者が直し方まで辿れる警告で出す | warning に理由の区分と環境変数ガイドの tmux の設定への案内を載せる(処理の流れの表) | 理由ごとに warning の文面を単体テストで見る | | セキュリティ | セッション環境の値から求めたパスは、`remote-cli` という名のディレクトリで、中に実行できる `code` があるときだけ `PATH` に入れる | 値が絶対パスでないときは足さない。求めたディレクトリの名前が `remote-cli` で、中の起動するエディタの名前のファイルが通常のファイルで実行できるときだけ足す(決定 3) | 相対パス・実行権の無いファイル・ディレクトリの `code` で足さないことを単体テストで見る | @@ -221,7 +223,11 @@ sequenceDiagram ### 決定 1: 拾い直したソケットと同じサーバーを使うため、セッション環境の `VSCODE_GIT_ASKPASS_NODE` から合う `remote-cli` を求める -`VSCODE_GIT_ASKPASS_NODE` は VS Code サーバーの `node` の絶対パスで(PRD3)、`VSCODE_IPC_HOOK_CLI` と同じ attach でセッション環境へ写る(STD1)。同じ読みから求めれば、ソケットとサーバーの版がずれない。`node` の置かれたディレクトリの `bin/remote-cli` を合う `remote-cli` とし、現行の配置と旧い配置のどちらでもこの関係が成り立つ(実測・要求の前提 1)。 +`VSCODE_GIT_ASKPASS_NODE` は VS Code サーバーの `node` の絶対パスで(PRD3)、`VSCODE_IPC_HOOK_CLI` と同じ attach でセッション環境へ写る(STD1)。同じセッション環境から求めれば、attach の後にソケットとサーバーの版がずれた状態は残らない。 + +ただし、判定がソケットを読む呼び出しと、探索が `VSCODE_GIT_ASKPASS_NODE` を読む呼び出しは別で、2 つが同じ attach の値であることは保証しない。2 つの読みの間に別のクライアントが attach すると、ソケットと `node` のパスが別のクライアントのものになり得る。この間の attach は許容する。2 つの読みは続けて行う tmux の呼び出しで、間に利用者の操作は挟まらない。1 回の呼び出しでまとめて読む形は、判定の既存の問い合わせを変え、I2(拾い直しが起きないときの問い合わせの回数)と非機能の条件(追加は 1 回だけ)を崩すため採らない。食い違ったときに起きることは「未確認のまま残ること」に置く。 + +`node` の置かれたディレクトリの `bin/remote-cli` を合う `remote-cli` とし、現行の配置と旧い配置のどちらでもこの関係が成り立つ(実測・要求の前提 1)。 VS Code サーバーのディレクトリ(`~/.vscode-server/cli/servers/*`)を探して選ぶ方法は採らない。手元のホストに版の違うサーバーが 6 つ並んでおり(実測。`ls -d ~/.vscode-server/cli/servers/*/server | wc -l` が 6)、どれが拾い直したソケットのものかを決める手がかりが無いためである。 @@ -280,7 +286,8 @@ VS Code サーバーは統合ターミナルの `PATH` の先頭に自分の `re | 受け入れ条件 3 | 1 のとき、足したディレクトリを含む info が 1 行出る | ログを出さない・2 行以上出す、と落ちる | | 受け入れ条件 4・I4 | 拾い直したがセッション環境の `VSCODE_GIT_ASKPASS_NODE` が未設定・消されたとき、`PATH` はペインのまま、tmux の設定を案内する warning が 1 行出て、起動は行われる | `PATH` を変える・警告を出さない・起動を止める・消された印をパスとして扱う、と落ちる | | 受け入れ条件 5・I4 | 求めたディレクトリに `code` が無い・実行できないとき、4 と同じ形の warning が出て `PATH` は変わらない | 実在だけを見て実行権を見ない・ディレクトリの存在だけで足す、と落ちる | -| 受け入れ条件 6・I2 | ペインのソケットが接続できる・tmux の外・セッション環境に接続できるソケットが無いとき、起動するコマンドと渡す環境が変更前と同じで、`VSCODE_GIT_ASKPASS_NODE` を問い合わせない。`tests/editor/` の既存のテストが変更なしで通る | 拾い直していないときにも探索を呼ぶ・`PATH` を触る、と落ちる | +| 受け入れ条件 6・I2 | ペインのソケットが接続できて判定がそれを使うと決めた・tmux の外・セッション環境に接続できるソケットが無いとき、起動するコマンドと渡す環境が変更前と同じで、`VSCODE_GIT_ASKPASS_NODE` を問い合わせない。ペインのソケットが接続できても以前のクライアントのものとしてセッション環境のソケットを使う場合は、拾い直した側(受け入れ条件 1〜5)で縛る | 拾い直していないときにも探索を呼ぶ・`PATH` を触る、と落ちる | +| 受け入れ条件 6(既存のテスト) | `tests/editor/` の既存のテストを変更せずに通す。拾い直す場面の既存のテスト(拾い直したソケットを起動に渡す・以前のクライアントの IPC の代わりにセッション環境の IPC を使う、など)は tmux の差し替えが `VSCODE_GIT_ASKPASS_NODE` の問い合わせも受ける。差し替えは問い合わせた名前に合わない行か空を返し、例外を投げないため、探索は未設定として扱い `PATH` を変えずに warning を 1 行足す。これらのテストが見ているのは起動の結果・起動に渡す `VSCODE_IPC_HOOK_CLI`・起動するコマンドで、warning の有無と tmux の呼び出しの回数は見ていない(`tests/editor/test_opener.py` の `_FakeRun` と `_FakeTmuxEnv` を使うテストを読んで確かめた)。変えてよいテストは無い。通らなければ、実装をこの形に合わせて直す | 探索の追加で既存のテストを書き換える必要が出る、と落ちる | | 受け入れ条件 7 | ペインのソケットを以前のクライアントのものとして外し、セッション環境からも拾えないとき、`PATH` から `remote-cli` を除いて手元の `code` を探す | 探索の追加で IPC を外す経路の `PATH` の扱いが変わる、と落ちる(既存のテストが縛る) | | 受け入れ条件 8 | 確定仕様と環境変数ガイドの tmux の節に、拾い直したときに合う `remote-cli` を `PATH` の先頭に入れること・`VSCODE_GIT_ASKPASS_NODE` を `update-environment` に入れる必要があることが書かれている | 文書の確認(レビューと手動の読み合わせ) | | I1 | セッション環境の `VSCODE_GIT_ASKPASS_NODE` が無く、VS Code サーバーのディレクトリには `remote-cli/code` が実在するとき、`PATH` は変わらない | サーバーのディレクトリを探して足す、と落ちる | @@ -292,11 +299,14 @@ VS Code サーバーは統合ターミナルの `PATH` の先頭に自分の `re | 課題 | 扱い | 取り込み先 | 触るファイル | | --- | --- | --- | --- | -| #523 | 実装する | — | `lib/devbase/editor/opener.py`、`tests/editor/test_opener.py`、`docs/specifications/editor-open.md`、`docs/user/environment-variables.md`、`CHANGELOG.md` | +| #523 | 実装する | — | `lib/devbase/editor/opener.py`、`tests/editor/test_opener.py`、`docs/specifications/editor-open.md`、`docs/user/environment-variables.md`、`CHANGELOG.md`、`docs/glossary.md`・`docs/glossary/glossary.json`(用語の追加と意味の変更。設計の段で反映済みで、実装の段では内容を変えない) | ## 人へ残す判断 -無し +| 判断 | 何が決まるか | 設計の扱い | +| --- | --- | --- | +| 要求の前提 2 の採否(`VSCODE_GIT_ASKPASS_NODE` から合う `remote-cli` を求められないとき、VS Code サーバーのディレクトリを探さず、`PATH` を変えずに警告する) | 推奨設定(`update-environment` に `VSCODE_GIT_ASKPASS_NODE` を入れる)をしていない利用者で、拾い直したときに手元の PC に窓が開くか、警告を受けて設定を足すまで開かないか | 要求の「未決」で利用者が設計承認ゲートで決めるとした項目である。決定 1・決定 4 は前提 2 を採る形で書いている。採らない場合は、決定 1・決定 4 と I1・テスト設計の I1 の行を書き直す | +| 要求の「起票者の推定」S1〜S6 の確認 | 直し方(`PATH` の先頭に合う `remote-cli` を入れる・`VSCODE_GIT_ASKPASS_NODE` から求める・サーバーのディレクトリを探さない・拾い直しが起きないときは変えない・テストの範囲・手元で窓が開く見込み)が利用者の意図に合うか | 課題の本文から読んだ推定で、利用者の決定としては扱っていない。設計はこの推定に沿って書いている。外れる項目があれば、その項目に対応する決定を書き直す | ## 未確認のまま残ること @@ -305,4 +315,5 @@ VS Code サーバーは統合ターミナルの `PATH` の先頭に自分の `re | 手元の PC に窓が開くこと(前提 3) | 起票の時点で確かめたのは `remote-cli` の `code` の終了コード 0 までである。窓が開くかはリリース後テストで、利用者が手元の PC の VS Code から確かめる | | Cursor などのサーバーでの `remote-cli` の中身 | 手元に無く確かめていない(外部の調査の「確かめられなかったこと」)。中の実行ファイルの名前が起動するエディタの名前と違えば、決定 4 の警告の経路に入る。使う利用者が現れた時点の報告で分かる | | git 拡張が `VSCODE_GIT_ASKPASS_NODE` を端末へ渡さない場面 | 設定によって渡さない場面があるかを確かめていない。渡さない場合は決定 4 の警告の経路に入り、これまでの振る舞いのまま起動する。警告を受けた利用者の報告で分かる | +| ソケットの読みと `node` のパスの読みの間の attach | 2 つの読みの間に別のクライアントが attach すると、ソケットと `remote-cli` が別のクライアントのものになり得る(決定 1)。その組み合わせで起動したときに、起動が失敗するか・どちらのクライアントに窓が開くかは確かめていない。起きる幅は続けて行う 2 回の tmux の呼び出しの間に限られる | | macOS 以外のホスト(Linux・WSL2)での振る舞い | 確かめたのは macOS のホストだけである。`node` と `bin/remote-cli` の位置関係は VS Code サーバーの配置で決まり OS に依らないと読んでいるが、実機では確かめていない。Linux のホストで Remote-SSH を使う利用者の報告で分かる | From 6bc3cca729972471bb1daa6be83cc6fc7cdcef04 Mon Sep 17 00:00:00 2001 From: "takemi.ohama" Date: Mon, 16 Nov 2026 22:39:06 +0900 Subject: [PATCH 4/7] =?UTF-8?q?Docs:=20#523=20=E3=81=AE=E8=A9=B3=E7=B4=B0?= =?UTF-8?q?=E8=A8=AD=E8=A8=88=E3=82=92=E6=9B=B8=E3=81=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 設計文書の構成要素を opener.py の関数の粒度へ下ろした。新設する関数 4 つ (エディタの名前・実行できるファイルの確かめ・合う remote-cli の探索・PATH の先頭への追加)と、 変える _prepare_ipc_env の仕様・異常系・ログ・再利用の確認・単体テストの観点を置いた。 設計文書の「設計の結果」の触るファイルのセルは、検査が区切りとして読めるよう 用語集の 2 ファイルを読点で並べた。 Co-Authored-By: Claude Opus 5.5 --- issues/issue-523-design-detail.md | 178 ++++++++++++++++++++++++++++++ issues/issue-523-design.md | 2 +- 2 files changed, 179 insertions(+), 1 deletion(-) create mode 100644 issues/issue-523-design-detail.md diff --git a/issues/issue-523-design-detail.md b/issues/issue-523-design-detail.md new file mode 100644 index 00000000..ca62dc57 --- /dev/null +++ b/issues/issue-523-design-detail.md @@ -0,0 +1,178 @@ +# #523 の詳細設計: tmux でソケットを拾い直したときに合う remote-cli を PATH の先頭に入れる + +設計文書 [issue-523-design.md](issue-523-design.md) の「構成要素」と「処理の流れ」を、ファイルと関数の粒度へ下ろした文書である。 +決定の理由は設計文書の「決定の記録」にあり、ここでは繰り返さない。 + +この文書で使う語は設計文書の「用語」の表に従う。加えて次の語を使う。 + +| 語 | この文書での意味 | +| --- | --- | +| 拾い直した | 判定が使うと決めたソケット(`EditorContext.ipc_socket`)があり、それがペインの `VSCODE_IPC_HOOK_CLI` と違うこと。既存の `_prepare_ipc_env` の最初の分岐の条件(`ctx.ipc_socket and ctx.ipc_socket != stale_ipc`)と同じで、条件は変えない | +| ペインの PATH | `open_editor` が受け取った環境変数(既定は `os.environ`)の `PATH`。差し替える前の値 | +| 起動に渡す環境 | `_prepare_ipc_env` が返し、エディタの解決と起動に使う環境変数の辞書 | +| 見つからない理由 | 合う `remote-cli` を求められなかった理由を表す文字列。warning にそのまま載せる | + +## ファイル配置 + +パッケージ・モジュール構成(触るファイルだけ。新設のファイルは無い): + +```text +devbase/ +├── CHANGELOG.md +├── docs/ +│ ├── specifications/ +│ │ └── editor-open.md +│ └── user/ +│ └── environment-variables.md +├── lib/devbase/editor/ +│ └── opener.py +└── tests/editor/ + └── test_opener.py +``` + +依存の向きは、テストから `opener.py` への一方向だけである。`opener.py` は新しい依存を持たない(標準ライブラリの `os` と +既存の `devbase.log` だけ)。文書の 3 ファイルはコードから参照されない。 + +| パス | 種類 | 役割 1 文 | 依存する先 | +| --- | --- | --- | --- | +| `lib/devbase/editor/opener.py` | 変更 | 拾い直したとき、セッション環境の `VSCODE_GIT_ASKPASS_NODE` から合う `remote-cli` を求め、起動に渡す環境の `PATH` の先頭に入れ、その `PATH` でエディタを探す | 無し(同じモジュールの `_tmux_show_env`・`_is_remote_cli_dir`・`resolve_editor_display` を使う) | +| `tests/editor/test_opener.py` | 変更 | 新設の関数の単体テストと、拾い直したときの `open_editor` の起動の結果を見るテストを足す。既存のテストは変えない | `lib/devbase/editor/opener.py` | +| `docs/specifications/editor-open.md` | 変更 | 拾い直したときの `PATH` の扱いと、`VSCODE_GIT_ASKPASS_NODE` の要否を確定仕様に書く | 無し | +| `docs/user/environment-variables.md` | 変更 | 「tmux / screen 経由で使う場合」の節に、合う `remote-cli` を `PATH` の先頭に入れることと、`update-environment` に `VSCODE_GIT_ASKPASS_NODE` が要ることを書く | 無し | +| `CHANGELOG.md` | 変更 | `[Unreleased]` に、tmux で拾い直したときに手元の VS Code に窓が開くようになったことを書く | 無し | + +用語集(`docs/glossary.md`・`docs/glossary/glossary.json`)は設計の段で反映済みで、実装の段では触らない。 + +## クラスと関数の構造 + +型の関係は設計文書の「構造」の節のとおりで、型の追加・変更は無い(`EditorContext`・`OpenPlan` は変えない)。 +クラスは足さず、モジュールの最上位の関数で書く。 + +| 置き場 | クラスまたはモジュール | メソッドと最上位の関数 | +| --- | --- | --- | +| `lib/devbase/editor/opener.py` | モジュール `devbase.editor.opener` | 新設: `_editor_name`・`_is_executable_file`・`_find_matching_remote_cli`・`_prepend_path`。変更: `_prepare_ipc_env`(責務と失敗の扱い)・`open_editor`(`resolve_editor_cmd` に渡す `path` の決め方だけ。シグネチャ・責務・失敗の扱いは変えない) | +| `tests/editor/test_opener.py` | モジュール | 新設: 下の「単体テストの観点」の行ごとのテスト関数。既存の `_FakeTmuxEnv` を使い、tmux の差し替えを新設しない | + +`resolve_editor_cmd`・`_launch`・`_tmux_show_env`・`_drop_vscode_ipc`・`detect_context` は変えない。 + +## 関数の仕様 + +| 関数 | 置き場 | 種類 | シグネチャ | 責務 1 文 | 事前条件 | 事後条件 | 副作用 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| `_editor_name` | `lib/devbase/editor/opener.py` | 新設 | `(environ: Mapping[str, str]) -> Optional[str]` | 起動するエディタのファイル名(`remote-cli` の中で確かめる名前)を返す | 無し | `DEVBASE_EDITOR` があればその先頭の語の末尾の名前(`os.path.basename`)、無ければ `"code"`。`DEVBASE_EDITOR` を語に分けられない・先頭の語の名前が空のときは `None` | 無し | +| `_is_executable_file` | `lib/devbase/editor/opener.py` | 新設 | `(path: str) -> bool` | パスが実行できる通常のファイルかを返す | 無し | `os.path.isfile(path)` かつ `os.access(path, os.X_OK)` のとき `True`。確かめの途中の `OSError`・`ValueError` は `False` | 無し | +| `_find_matching_remote_cli` | `lib/devbase/editor/opener.py` | 新設 | `(environ: Mapping[str, str], editor_name: Optional[str]) -> tuple[Optional[str], Optional[str]]` | セッション環境の `VSCODE_GIT_ASKPASS_NODE` から合う `remote-cli` のディレクトリを求める | 拾い直した後に呼ぶ(`environ` に `TMUX` がある) | 戻り値の 2 つのうち、ちょうど 1 つが `None` でない。1 つ目はディレクトリ(絶対パスで、末尾の名前が `remote-cli` で、中に `editor_name` の実行できる通常のファイルがある)、2 つ目は見つからない理由 | 外部コマンド `tmux show-environment VSCODE_GIT_ASKPASS_NODE` を 1 回起動する(`editor_name` が `None` のときは起動しない)。ファイルの属性を読む | +| `_prepend_path` | `lib/devbase/editor/opener.py` | 新設 | `(path: Optional[str], directory: str) -> str` | `directory` を先頭の要素にした `PATH` の文字列を返す | `directory` は空でない | `path` が `None` か空文字なら `directory` だけ。そうでなければ `directory + os.pathsep + path`(`path` の要素は並びも重複もそのまま) | 無し | +| `_prepare_ipc_env` | `lib/devbase/editor/opener.py` | 変更 | `(env: Mapping[str, str], ctx: EditorContext) -> Mapping[str, str]`(変えない) | 拾い直したソケットを起動に渡す環境へ入れ、合う `remote-cli` が求められればその `PATH` の先頭に足す | 変えない | 拾い直したとき: 戻り値の `VSCODE_IPC_HOOK_CLI` は `ctx.ipc_socket`。合う `remote-cli` があれば戻り値の `PATH` は `_prepend_path(ペインの PATH, ディレクトリ)`、無ければペインの `PATH` のまま。拾い直していないとき: 戻り値・ログ・tmux への問い合わせは変更前と同じ | 拾い直したとき、`_find_matching_remote_cli` を通じて外部コマンドを 1 回起動する。ログを出す(「ログと記録の出力」) | + +`open_editor` の変える箇所は、`resolve_editor_cmd` に渡す `path` の決め方だけである(「処理の手順」の 2 つ目の表)。 + +## 異常系の処理 + +| 関数 | 失敗 | 原因 | 検出する場所 | 扱い | 利用者に見える出力と終了コード | 後始末と再実行の可否 | +| --- | --- | --- | --- | --- | --- | --- | +| `_find_matching_remote_cli` | `tmux` を起動できない・2 秒で返らない・終了コードが 0 でない・出力が想定外 | `tmux` が `PATH` に無い、サーバーが応答しない | 既存の `_tmux_show_env`(例外と終了コードを見て `None` を返す) | 既定値で続ける(見つからない理由「未設定」を返す) | 呼び出し元の warning 1 行。終了コードは変わらない | 後始末は無い。次の `devbase open` で読み直す | +| `_find_matching_remote_cli` | 値が無い・空 | 利用者の `update-environment` に `VSCODE_GIT_ASKPASS_NODE` が無く、セッションを作ったときの環境にも無い | `_tmux_show_env` の戻り値が `None` | 既定値で続ける(理由「未設定」) | 同上 | 利用者が `~/.tmux.conf` に設定を足し、attach し直せば次から求められる | +| `_find_matching_remote_cli` | 値が消されている | attach してきたクライアントが `VSCODE_GIT_ASKPASS_NODE` を持たない(`-VSCODE_GIT_ASKPASS_NODE`) | `_tmux_show_env` の戻り値が `_TMUX_REMOVED` | 既定値で続ける(理由「消された」) | 同上 | VS Code の統合ターミナルから attach し直せば次から求められる | +| `_find_matching_remote_cli` | 値が絶対パスでない | セッション環境の値を別のクライアントやツールが書いた | `os.path.isabs` | 既定値で続ける(理由「絶対パスでない」) | 同上 | 後始末は無い | +| `_find_matching_remote_cli` | 求めたディレクトリに実行できるエディタが無い | VS Code サーバーの版が消された・配置が違う・`DEVBASE_EDITOR` の名前のファイルが `remote-cli` に無い・`editor_name` が `None` | `_is_executable_file` が `False` | 既定値で続ける(理由「実行できるエディタが無い」) | 同上 | 後始末は無い | +| `_is_executable_file` | 属性を読めない | 権限・パスの長さ・値に NUL が入っている | `os.path.isfile`・`os.access` が投げる `OSError`・`ValueError` | 既定値で続ける(`False`) | 無し(呼び出し元が warning にする) | 後始末は無い | +| `_prepare_ipc_env` | 合う `remote-cli` を求められない | 上の `_find_matching_remote_cli` の 5 行のいずれか | `_find_matching_remote_cli` の 2 つ目の戻り値が `None` でない | 既定値で続ける(`PATH` を変えずに起動に渡す環境を返す。起動は止めない) | warning 1 行(理由・手元のエディタで起動すること・環境変数ガイドの tmux の設定の案内)。`devbase up` / `devbase open` の終了コードは変わらない | 後始末は無い。設定を直して `devbase open` を打ち直せる | + +起動そのものの失敗(`Popen` の例外)は既存の `open_editor` が warning にしており、扱いを変えない。 + +## 処理の手順 + +`_find_matching_remote_cli` の判定表(上から順に当て、最初に当たった行で返す): + +| 関数 | 条件の組み合わせ | 結果 | +| --- | --- | --- | +| `_find_matching_remote_cli` | `editor_name` が `None` | `(None, 理由「実行できるエディタが無い」)`。tmux へ問い合わせない | +| `_find_matching_remote_cli` | `_tmux_show_env` が `_TMUX_REMOVED` | `(None, 理由「消された」)` | +| `_find_matching_remote_cli` | `_tmux_show_env` が `None` | `(None, 理由「未設定」)` | +| `_find_matching_remote_cli` | 値が絶対パスでない | `(None, 理由「絶対パスでない」)` | +| `_find_matching_remote_cli` | `os.path.join(os.path.dirname(値), "bin", "remote-cli", editor_name)` が `_is_executable_file` で `False` | `(None, 理由「実行できるエディタが無い」と求めたディレクトリ)` | +| `_find_matching_remote_cli` | それ以外 | `(os.path.join(os.path.dirname(値), "bin", "remote-cli"), None)` | + +求めるディレクトリは、`node` の置かれたディレクトリに `bin/remote-cli` を連結して作る。`os.path.normpath` を掛けないため、 +末尾の名前は必ず `remote-cli` になり、決定 3 の「名前が `remote-cli`」はこの作り方で満たす(`_is_remote_cli_dir` で +確かめ直す行は置かない。当たらない分岐はテストで踏めないため)。テストは足したディレクトリの末尾の名前を見る。 + +`_prepare_ipc_env` と `open_editor` の判定表: + +| 関数 | 条件の組み合わせ | 結果 | +| --- | --- | --- | +| `_prepare_ipc_env` | 拾い直した、合う `remote-cli` がある | `VSCODE_IPC_HOOK_CLI` を差し替え、`PATH` を `_prepend_path(ペインの PATH, ディレクトリ)` にする。既存の info「拾い直しました」と、新しい info 1 行を出す | +| `_prepare_ipc_env` | 拾い直した、合う `remote-cli` が無い | `VSCODE_IPC_HOOK_CLI` だけ差し替える。既存の info「拾い直しました」と、新しい warning 1 行を出す | +| `_prepare_ipc_env` | 拾い直していない | 変更前と同じ(`_find_matching_remote_cli` を呼ばない) | +| `_prepare_ipc_env` | 拾い直した、かつ `ctx.ipc_from_previous_client` | 上の 2 行のどちらかに続けて、既存の「以前のクライアントのもの」の info を出す。`ctx.ipc_socket` があるので IPC は外さない(変更前と同じ) | +| `open_editor` | 起動に渡す環境の `PATH` がペインの `PATH` と違う、または IPC を外した | `resolve_editor_cmd(env, path=起動に渡す環境の PATH)`。起動も同じ `PATH` で実行ファイルを探すため(決定 5)、確かめと起動が同じファイルを指す | +| `open_editor` | それ以外 | `resolve_editor_cmd(env, path=None)`(変更前と同じ。実行中のプロセスの `PATH` で探す) | + +`open_editor` は `_prepare_ipc_env` を呼ぶ前にペインの `PATH`(`env.get("PATH")`)を控え、呼んだ後の値と比べる。IPC を +外したときは `PATH` が変わらないこともある(ペインの `PATH` に `remote-cli` が無いとき)ため、既存の `dropped_ipc` の条件も残す。 + +- 繰り返しの終わる条件: 繰り返しは無い(`_prepend_path` は文字列の連結だけで、`PATH` の要素を走査しない) +- 計算量の注意: 無し。追加の外部コマンドは拾い直したときの 1 回で、上限は既存の `_TMUX_TIMEOUT`(2 秒) + +## 内部のデータと定数 + +| 名前 | 種類 | 置き場 | 既定値 | +| --- | --- | --- | --- | +| `_ASKPASS_NODE_VAR` | 定数 | `lib/devbase/editor/opener.py` | `"VSCODE_GIT_ASKPASS_NODE"`。tmux への問い合わせと warning の文面の両方がこの定数を使う | +| `_REMOTE_CLI_UNSET` | 定数(見つからない理由) | `lib/devbase/editor/opener.py` | `"tmux のセッション環境に VSCODE_GIT_ASKPASS_NODE がありません"` | +| `_REMOTE_CLI_REMOVED` | 定数(見つからない理由) | `lib/devbase/editor/opener.py` | `"tmux のセッション環境の VSCODE_GIT_ASKPASS_NODE が消されています (-VSCODE_GIT_ASKPASS_NODE)"` | +| `_REMOTE_CLI_NOT_ABSOLUTE` | 定数(見つからない理由) | `lib/devbase/editor/opener.py` | `"VSCODE_GIT_ASKPASS_NODE が絶対パスではありません"` | +| `_REMOTE_CLI_NO_EDITOR` | 定数(見つからない理由の書式) | `lib/devbase/editor/opener.py` | `"{directory} に実行できる {name} がありません"`。`editor_name` が `None` のときの `name` は `"エディタ"` | +| `_TMUX_TIMEOUT` | 定数(既存) | `lib/devbase/editor/opener.py` | `2.0`。新しく持たず、`_tmux_show_env` を通じて使う | +| `_TMUX_REMOVED` | 定数(既存) | `lib/devbase/editor/opener.py` | 消された印。新しく持たない | + +見つからない理由の区分は、設計文書の 3 つ(未設定・消された・実行できるエディタが無い)に、不変条件 I3 の「絶対パスで +ない」を分けて 4 つにした。warning が直し方を示せるよう、絶対パスでない値を「未設定」に混ぜない。 + +## 並行と排他 + +| 同時に走りうる処理 | 共有する資源 | 排他の取り方 | 冪等性と中断からの再開 | +| --- | --- | --- | --- | +| `devbase` の 2 回の tmux の呼び出し(判定のソケットの読み・探索の `VSCODE_GIT_ASKPASS_NODE` の読み)の間に、別のクライアントが同じセッションへ attach する | tmux のセッション環境 | 取らない(決定 1 で許容した。2 つの読みは続けて行う呼び出しで、間に利用者の操作は挟まらない) | 読むだけで書かない。食い違ったときの結果は設計文書の「未確認のまま残ること」にある。`devbase open` を打ち直せば読み直す | +| 同じホストで複数の `devbase open` / `devbase up` が同時に走る | tmux のセッション環境・VS Code サーバーのディレクトリ | 取らない(どちらも読むだけで、起動に渡す環境は呼び出しごとの複製) | 冪等。中断しても残るものは無い | +| 確かめた後、起動するまでに VS Code サーバーの版が消される | `<サーバー>/bin/remote-cli/<エディタ>` | 取らない | 起動の失敗は既存の `open_editor` の warning になり、`up` は続く。打ち直すと警告の経路に入る | + +## ログと記録の出力 + +| 関数 | 出すもの | レベルまたは書き先 | 出さないもの | +| --- | --- | --- | --- | +| `_prepare_ipc_env` | 合う `remote-cli` を足したこと。1 行: 「拾い直したソケットに合う remote-cli を PATH の先頭に入れました (<ディレクトリ>)」 | info(`devbase.log` のロガー) | ペインの `PATH` の全体 | +| `_prepare_ipc_env` | 合う `remote-cli` が見つからなかったこと。1 行: 「拾い直したソケットに合う remote-cli が見つかりません (<見つからない理由>)。PATH は変えずに <エディタの名前> で起動します。tmux の update-environment に VSCODE_GIT_ASKPASS_NODE を入れると次から直ります (環境変数ガイドの tmux 設定を参照してください)」 | warning(同上) | セッション環境のほかの変数(`VSCODE_NONCE`・`GIT_ASKPASS` などの認証に関わる値)。`VSCODE_GIT_ASKPASS_NODE` だけを読む | +| `_find_matching_remote_cli` | 出さない(理由は戻り値で返し、ログは呼び出し元がまとめて 1 行にする) | — | — | + +既存の info「拾い直しました」と「以前のクライアントのもの」、既存の warning「接続できません」は文面も条件も変えない。 +拾い直したときに出るのは、既存の info に加えて、上の 2 行のどちらか 1 行だけである(受け入れ条件 3・4)。 + +## 既存の部品の再利用 + +| 新設する関数 | 確かめた既存の部品 | 確かめた手段 | 結果 | +| --- | --- | --- | --- | +| `_editor_name` | `resolve_editor_display`(`DEVBASE_EDITOR` を語に分け、無ければ `["code"]`) | `grep -n "def resolve_editor" lib/devbase/editor/opener.py` | 使う。先頭の語を取り、`os.path.basename` を掛ける。`shlex` の `ValueError` だけをこの関数で受けて `None` にする | +| `_editor_name` | `resolve_editor_cmd` | 同上 | 使えない。実在の確かめ(`shutil.which`)を含み、ペインの `PATH` に無い名前で `None` を返すため、名前だけが要る場面に合わない | +| `_is_executable_file` | `_which`(`shutil.which` の包み)に `path=` を渡す | `grep -n "_which\|shutil.which" lib/devbase/editor/opener.py`、`python3 -c "import inspect,shutil; print(inspect.getsource(shutil._access_check))"` | 使えない。ディレクトリでないことしか見ず通常のファイルかを見ない、名前に `/` を含むと `path` を無視する、の 2 点で決定 3 の確かめにならない | +| `_is_executable_file` | リポジトリの中の実行権の確かめ | `grep -rn "os.access\|X_OK" lib --include=*.py` | 使えない。当たりは `lib/devbase/commands/env.py:1662` の `os.R_OK` の 1 件だけで、実行権を見る部品は無い | +| `_find_matching_remote_cli` | `_tmux_show_env`(セッション環境の読み・消された印・2 秒の上限・例外の吸収) | `grep -n "def _tmux" lib/devbase/editor/opener.py` | 使う。消されたと未設定を分けるため、`_tmux_env` ではなく `_tmux_show_env` を使う | +| `_find_matching_remote_cli` | `lib/devbase/editor/vscode_server.py` の関数(`bin_fix_script`・`prepare_bin_dir`・`shared_cache_prune_script`・`prune_shared_cache`) | `grep -n "^def " lib/devbase/editor/vscode_server.py` | 使えない。どれもコンテナの中の VS Code サーバーのキャッシュを扱い、ホストのサーバーのディレクトリを求める部品ではない。サーバーのディレクトリを探す方法は決定 1 で採らない | +| `_find_matching_remote_cli` | `_is_remote_cli_dir`(`PATH` の要素の末尾が `remote-cli` か) | `grep -n "_is_remote_cli_dir" lib/devbase/editor/opener.py` | 使わない。求めるディレクトリは作り方で末尾が `remote-cli` に決まり、確かめ直す分岐が当たらない(「処理の手順」) | +| `_prepend_path` | `_drop_vscode_ipc` の `PATH` の組み直し、リポジトリの中の `os.pathsep` の扱い | `grep -rn "os.pathsep" lib --include=*.py` | 使えない。当たりは `opener.py` の `_drop_vscode_ipc`(要素を除く)だけで、先頭に足す部品は無い | + +## 単体テストの観点 + +テストは `tests/editor/test_opener.py` に置き、tmux は既存の `_FakeTmuxEnv`(変数ごとの出力を返す)を `opener.subprocess.run` +の差し替えに使う。VS Code サーバーの配置は `tmp_path` に `node` と `bin/remote-cli/<エディタ>` を作って与え、ソケットの +接続は既存のテストと同じく `_socket_connectable` を差し替える。実の tmux サーバーに触れない。 + +| 関数 | 正常 | 境界値 | 異常 | +| --- | --- | --- | --- | +| `_editor_name` | `DEVBASE_EDITOR` が無ければ `"code"`。`"cursor --reuse-window"` なら `"cursor"` | `DEVBASE_EDITOR=/opt/bin/cursor` なら `"cursor"`。`DEVBASE_EDITOR=""`(空)は未設定と同じく `"code"`(`resolve_editor_display` に従う) | 引用符の閉じない値で `None`。`'""'` で `None` | +| `_is_executable_file` | 実行権のある通常のファイルで `True` | シンボリックリンクの先が実行できる通常のファイルなら `True` | 実行権の無いファイル・ディレクトリ・無いパス・NUL を含むパスで `False`(例外を投げない) | +| `_find_matching_remote_cli` | `VSCODE_GIT_ASKPASS_NODE=/server/node` で `/server/bin/remote-cli/code` があれば、ディレクトリ `/server/bin/remote-cli` と理由 `None`。末尾の名前は `remote-cli`。旧い配置(`/bin//node`)でも同じ。tmux の呼び出しは `VSCODE_GIT_ASKPASS_NODE` の 1 回 | `editor_name="cursor"` で `remote-cli/cursor` だけがあれば見つかり、`remote-cli/code` だけなら見つからない | 異常系の処理の 5 行ごと: tmux の失敗(`_FakeRun(returncode=1)`)と値なしで「未設定」、`-VSCODE_GIT_ASKPASS_NODE` で「消された」、相対パスで「絶対パスでない」、`code` が無い・実行できない・ディレクトリで「実行できるエディタが無い」。`editor_name=None` で tmux を呼ばない。サーバーのディレクトリを別に置いても値が無ければ見つからない(I1) | +| `_prepend_path` | `"/a:/b"` と `"/rc"` で `"/rc:/a:/b"` | `path=None` と `path=""` で `"/rc"`(空の要素を作らない)。ペインの `PATH` に別の `remote-cli` があっても除かず、並びを保つ | 無し(例外の経路が無い) | +| `_prepare_ipc_env` | 拾い直して合う `remote-cli` があれば、`PATH` の先頭がそのディレクトリ・2 番目以降がペインの要素と同じ並び・`VSCODE_IPC_HOOK_CLI` が拾い直したソケット、info 1 行(受け入れ条件 2・3) | ペインの `PATH` が無いとき `PATH` はディレクトリだけ。`ipc_from_previous_client` と拾い直しが重なっても IPC を外さない | 合う `remote-cli` が無い 4 つの理由で `PATH` がペインのまま、warning 1 行に理由と `update-environment` の案内(受け入れ条件 4・5)。拾い直していないとき `VSCODE_GIT_ASKPASS_NODE` を問い合わせない(受け入れ条件 6・性能の条件) | +| `open_editor` | 再現手順の条件(ペインの `PATH` の先頭にデスクトップ版を模した `code`、セッション環境だけが接続できるソケット、合う `remote-cli`)で、差し替えた起動の受け取る `cmd[0]` を起動に渡す環境の `PATH` で解決すると `<サーバー>/bin/remote-cli/code`(受け入れ条件 1) | `DEVBASE_EDITOR` が絶対パスのとき、起動するコマンドの先頭の語は絶対パスのままで、`PATH` は差し替わる(前提 4) | 合う `remote-cli` が無いとき、起動は行われ戻り値は `"launch"`。拾い直さない経路(ペインのソケットを使う・tmux の外・セッション環境から拾えない)と IPC を外す経路の既存のテストが変更なしで通る(受け入れ条件 6・7) | diff --git a/issues/issue-523-design.md b/issues/issue-523-design.md index fc0a9192..c41fddf7 100644 --- a/issues/issue-523-design.md +++ b/issues/issue-523-design.md @@ -299,7 +299,7 @@ VS Code サーバーは統合ターミナルの `PATH` の先頭に自分の `re | 課題 | 扱い | 取り込み先 | 触るファイル | | --- | --- | --- | --- | -| #523 | 実装する | — | `lib/devbase/editor/opener.py`、`tests/editor/test_opener.py`、`docs/specifications/editor-open.md`、`docs/user/environment-variables.md`、`CHANGELOG.md`、`docs/glossary.md`・`docs/glossary/glossary.json`(用語の追加と意味の変更。設計の段で反映済みで、実装の段では内容を変えない) | +| #523 | 実装する | — | `lib/devbase/editor/opener.py`、`tests/editor/test_opener.py`、`docs/specifications/editor-open.md`、`docs/user/environment-variables.md`、`CHANGELOG.md`、`docs/glossary.md`、`docs/glossary/glossary.json`(用語の追加と意味の変更。設計の段で反映済みで、実装の段では内容を変えない) | ## 人へ残す判断 From 3431a31aeff630d33e658d93ca12e3b9d1178f92 Mon Sep 17 00:00:00 2001 From: "takemi.ohama" Date: Mon, 16 Nov 2026 22:41:15 +0900 Subject: [PATCH 5/7] =?UTF-8?q?Docs:=20#523=20=E3=81=AE=E8=A8=AD=E8=A8=88?= =?UTF-8?q?=E6=96=87=E6=9B=B8=E3=82=92=E7=B5=84=E3=81=BF=E7=9B=B4=E3=81=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 内容は足さず、100 字を超える文を分け、決定 1 の段落を要点から並べた。 Co-Authored-By: Claude Opus 5.5 --- issues/issue-523-design-detail.md | 10 +++++----- issues/issue-523-design.md | 24 +++++++++++++++++------- 2 files changed, 22 insertions(+), 12 deletions(-) diff --git a/issues/issue-523-design-detail.md b/issues/issue-523-design-detail.md index ca62dc57..b4ae2d2d 100644 --- a/issues/issue-523-design-detail.md +++ b/issues/issue-523-design-detail.md @@ -95,8 +95,8 @@ devbase/ | `_find_matching_remote_cli` | それ以外 | `(os.path.join(os.path.dirname(値), "bin", "remote-cli"), None)` | 求めるディレクトリは、`node` の置かれたディレクトリに `bin/remote-cli` を連結して作る。`os.path.normpath` を掛けないため、 -末尾の名前は必ず `remote-cli` になり、決定 3 の「名前が `remote-cli`」はこの作り方で満たす(`_is_remote_cli_dir` で -確かめ直す行は置かない。当たらない分岐はテストで踏めないため)。テストは足したディレクトリの末尾の名前を見る。 +末尾の名前は必ず `remote-cli` になる。決定 3 の「名前が `remote-cli`」はこの作り方で満たす。`_is_remote_cli_dir` で +確かめ直す行は置かない。当たらない分岐はテストで踏めないためである。テストは足したディレクトリの末尾の名前を見る。 `_prepare_ipc_env` と `open_editor` の判定表: @@ -164,9 +164,9 @@ devbase/ ## 単体テストの観点 -テストは `tests/editor/test_opener.py` に置き、tmux は既存の `_FakeTmuxEnv`(変数ごとの出力を返す)を `opener.subprocess.run` -の差し替えに使う。VS Code サーバーの配置は `tmp_path` に `node` と `bin/remote-cli/<エディタ>` を作って与え、ソケットの -接続は既存のテストと同じく `_socket_connectable` を差し替える。実の tmux サーバーに触れない。 +テストは `tests/editor/test_opener.py` に置く。tmux は、既存の `_FakeTmuxEnv`(変数ごとの出力を返す)を +`opener.subprocess.run` の差し替えに使う。VS Code サーバーの配置は、`tmp_path` に `node` と `bin/remote-cli/<エディタ>` を +作って与える。ソケットの接続は、既存のテストと同じく `_socket_connectable` を差し替える。実の tmux サーバーに触れない。 | 関数 | 正常 | 境界値 | 異常 | | --- | --- | --- | --- | diff --git a/issues/issue-523-design.md b/issues/issue-523-design.md index c41fddf7..128016e5 100644 --- a/issues/issue-523-design.md +++ b/issues/issue-523-design.md @@ -2,9 +2,9 @@ ## 目的 -- **今どうなっているか**: 手元の PC の VS Code から Remote-SSH で入った macOS のホストで、以前のクライアントが作った tmux のペインから `devbase` でエディタを開くと、IPC ソケットは拾い直せても、起動されるのはペインの `PATH` の先頭にあるデスクトップ版の `code` である。手元の PC には窓が開かず、エラーも出ない +- **今どうなっているか**: 手元の PC の VS Code から Remote-SSH で macOS のホストへ入り、以前のクライアントが作った tmux のペインから `devbase` でエディタを開く。IPC ソケットは拾い直せても、起動されるのはペインの `PATH` の先頭にあるデスクトップ版の `code` である。手元の PC には窓が開かず、エラーも出ない - **誰に効くか**: Remote-SSH で入ったホストの tmux の中で `devbase up` / `devbase open` を使う利用者 -- **変えると何が成り立つか**: 拾い直したソケットと同じ VS Code サーバーの `remote-cli` の `code` が起動され、手元の PC の VS Code に dev コンテナへ接続した窓が開く。拾い直しが起きないときの振る舞いは変わらない +- **変えると何が成り立つか**: 拾い直したソケットと同じ VS Code サーバーの `remote-cli` の `code` が起動される。手元の PC の VS Code に、dev コンテナへ接続した窓が開く。拾い直しが起きないときの振る舞いは変わらない ## 適用範囲 @@ -200,7 +200,11 @@ sequenceDiagram Note over 判定,差し替え: エディタの解決が起動に渡す環境の PATH でエディタを探して方針を決め、起動が同じ PATH で実行ファイルを探して起動する ``` -「拾い直した」は、判定が使うと決めたソケットがペインの `VSCODE_IPC_HOOK_CLI` と違うときを指す。ペインのソケットが死んでいた場合と、ペインのソケットが接続できても以前のクライアントのものとして使わず、セッション環境のソケットを使うと決めた場合(`ipc_from_previous_client`)の両方を含む。ペインに `VSCODE_IPC_HOOK_CLI` が無く、セッション環境から拾えた場合も含む。 +「拾い直した」は、判定が使うと決めたソケットがペインの `VSCODE_IPC_HOOK_CLI` と違うときを指す。次の 3 つの場合を含む。 + +- ペインのソケットが死んでいた +- ペインのソケットは接続できるが、以前のクライアントのものとして使わず、セッション環境のソケットを使うと決めた(`ipc_from_previous_client`) +- ペインに `VSCODE_IPC_HOOK_CLI` が無く、セッション環境から拾えた 受け入れ条件 6 の「ペインのソケットが接続できる」は、接続できて、かつ判定がペインのソケットを使うと決めた場合を指す。接続できても以前のクライアントのものとして使わない場合は、セッション環境から拾えれば「拾い直した」に入り `PATH` を変える。拾えなければ受け入れ条件 7 の経路(IPC を外す)に入る。I2 とテスト設計の受け入れ条件 6 の行は、この区分に従う。 @@ -223,12 +227,12 @@ sequenceDiagram ### 決定 1: 拾い直したソケットと同じサーバーを使うため、セッション環境の `VSCODE_GIT_ASKPASS_NODE` から合う `remote-cli` を求める -`VSCODE_GIT_ASKPASS_NODE` は VS Code サーバーの `node` の絶対パスで(PRD3)、`VSCODE_IPC_HOOK_CLI` と同じ attach でセッション環境へ写る(STD1)。同じセッション環境から求めれば、attach の後にソケットとサーバーの版がずれた状態は残らない。 - -ただし、判定がソケットを読む呼び出しと、探索が `VSCODE_GIT_ASKPASS_NODE` を読む呼び出しは別で、2 つが同じ attach の値であることは保証しない。2 つの読みの間に別のクライアントが attach すると、ソケットと `node` のパスが別のクライアントのものになり得る。この間の attach は許容する。2 つの読みは続けて行う tmux の呼び出しで、間に利用者の操作は挟まらない。1 回の呼び出しでまとめて読む形は、判定の既存の問い合わせを変え、I2(拾い直しが起きないときの問い合わせの回数)と非機能の条件(追加は 1 回だけ)を崩すため採らない。食い違ったときに起きることは「未確認のまま残ること」に置く。 +`VSCODE_GIT_ASKPASS_NODE` は VS Code サーバーの `node` の絶対パスである(PRD3)。`VSCODE_IPC_HOOK_CLI` と同じ attach でセッション環境へ写る(STD1)。同じセッション環境から求めれば、attach の後にソケットとサーバーの版がずれた状態は残らない。 `node` の置かれたディレクトリの `bin/remote-cli` を合う `remote-cli` とし、現行の配置と旧い配置のどちらでもこの関係が成り立つ(実測・要求の前提 1)。 +ただし、判定がソケットを読む呼び出しと、探索が `VSCODE_GIT_ASKPASS_NODE` を読む呼び出しは別で、2 つが同じ attach の値であることは保証しない。2 つの読みの間に別のクライアントが attach すると、ソケットと `node` のパスが別のクライアントのものになり得る。この間の attach は許容する。2 つの読みは続けて行う tmux の呼び出しで、間に利用者の操作は挟まらない。1 回の呼び出しでまとめて読む形は、判定の既存の問い合わせを変え、I2(拾い直しが起きないときの問い合わせの回数)と非機能の条件(追加は 1 回だけ)を崩すため採らない。食い違ったときに起きることは「未確認のまま残ること」に置く。 + VS Code サーバーのディレクトリ(`~/.vscode-server/cli/servers/*`)を探して選ぶ方法は採らない。手元のホストに版の違うサーバーが 6 つ並んでおり(実測。`ls -d ~/.vscode-server/cli/servers/*/server | wc -l` が 6)、どれが拾い直したソケットのものかを決める手がかりが無いためである。 - 作り方: 自前で作る・標準に倣う @@ -260,7 +264,13 @@ VS Code サーバーは統合ターミナルの `PATH` の先頭に自分の `re ### 決定 4: 版のずれたサーバーへ委ねないため、合う `remote-cli` を求められないときはほかを探さず、`PATH` を変えずに警告する -`VSCODE_GIT_ASKPASS_NODE` が未設定・消された(`-VSCODE_GIT_ASKPASS_NODE`)・求めたディレクトリに実行できるエディタが無い、のいずれでも、`PATH` を変えずにこれまでどおり起動し、warning を 1 行出す。tmux の既定の `update-environment` は `VSCODE_*` を含まないため(STD1)、この経路は推奨設定を入れていない利用者で必ず通る。警告には環境変数ガイドの tmux の設定を案内し、利用者が `~/.tmux.conf` に 1 行足せば次から直る形にする。 +次のいずれのときも、`PATH` を変えずにこれまでどおり起動し、warning を 1 行出す。 + +- `VSCODE_GIT_ASKPASS_NODE` が未設定 +- `VSCODE_GIT_ASKPASS_NODE` が消された(`-VSCODE_GIT_ASKPASS_NODE`) +- 求めたディレクトリに実行できるエディタが無い + +tmux の既定の `update-environment` は `VSCODE_*` を含まないため(STD1)、この経路は推奨設定を入れていない利用者で必ず通る。警告には環境変数ガイドの tmux の設定を案内し、利用者が `~/.tmux.conf` に 1 行足せば次から直る形にする。 サーバーのディレクトリを探して代わりに使う方法は採らない(決定 1 と同じ理由)。起動を止める方法も採らない。これまでの振る舞いより悪くしないためである。 From 330862fcc201972516893683c055ecdaa9eab916 Mon Sep 17 00:00:00 2001 From: "takemi.ohama" Date: Mon, 16 Nov 2026 22:45:06 +0900 Subject: [PATCH 6/7] =?UTF-8?q?docs(design):=20=E3=83=89=E3=83=A1=E3=82=A4?= =?UTF-8?q?=E3=83=B3=E3=82=A4=E3=83=99=E3=83=B3=E3=83=88=20E4=E3=83=BBE5?= =?UTF-8?q?=20=E3=81=AE=E7=99=BA=E7=94=9F=E5=85=83=E3=82=92=E6=A7=8B?= =?UTF-8?q?=E6=88=90=E8=A6=81=E7=B4=A0=E3=81=AE=E8=A1=A8=E3=81=AB=E6=8F=83?= =?UTF-8?q?=E3=81=88=E3=82=8B=20(#523)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit tmux から node のパスを読んで合う remote-cli を求めるのは探索、 PATH の先頭へ足すのは IPC の差し替えである。E4 の発生元を探索、 E5 の発生元を IPC の差し替えにし、探索が PATH を書き換えないことを E5 の行に書いた。 Co-Authored-By: Claude Opus 5.5 --- issues/issue-523-design.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/issues/issue-523-design.md b/issues/issue-523-design.md index 128016e5..457a8aaf 100644 --- a/issues/issue-523-design.md +++ b/issues/issue-523-design.md @@ -58,8 +58,8 @@ | E1 | 利用者が tmux のペインで `devbase` からエディタを開いた | 利用者(`devbase up` の後の自動オープン・`devbase open`) | 実行の場面の判定 | | E2 | ペインのシェルの IPC ソケットを使えないと判定した | 実行の場面の判定 | 実行の場面の判定(拾い直し) | | E3 | セッション環境から接続できる IPC ソケットを拾い直した | 実行の場面の判定 | IPC の差し替え | -| E4 | セッション環境から VS Code サーバーの `node` のパスを読んだ | IPC の差し替え | 合う `remote-cli` の探索 | -| E5 | 合う `remote-cli` を求め、`PATH` の先頭に入れた | 合う `remote-cli` の探索 | エディタの解決 | +| E4 | セッション環境から VS Code サーバーの `node` のパスを読み、合う `remote-cli` のディレクトリか見つからない理由を求めた | 合う `remote-cli` の探索 | IPC の差し替え | +| E5 | 合う `remote-cli` を `PATH` の先頭に入れた。`PATH` を書き換えるのは IPC の差し替えだけで、探索は書き換えない | IPC の差し替え | エディタの解決 | | E6 | 起動するエディタを `PATH` から求めた | エディタの解決 | 方針の決定・起動 | | E7 | エディタを、拾い直したソケットと差し替えた `PATH` で起動した | 起動 | 利用者(手元の PC の VS Code) | From 19da98ec8e2c50137bc12d70bab9fdc663bc23ce Mon Sep 17 00:00:00 2001 From: "takemi.ohama" Date: Mon, 16 Nov 2026 22:47:42 +0900 Subject: [PATCH 7/7] =?UTF-8?q?docs(design):=20#523=20=E3=81=AE=E5=89=8D?= =?UTF-8?q?=E6=8F=90=202=20=E3=81=A8=E8=B5=B7=E7=A5=A8=E8=80=85=E3=81=AE?= =?UTF-8?q?=E6=8E=A8=E5=AE=9A=E3=82=92=E6=B1=BA=E5=AE=9A=E3=81=AE=E8=A8=98?= =?UTF-8?q?=E9=8C=B2=E3=81=B8=E7=A7=BB=E3=81=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit レッドラインに当たらない 2 件の判断を「人へ残す判断」から外し、 決定 1・決定 4 に設計の判断として理由とともに書いた。 Co-Authored-By: Claude Opus 5.5 --- issues/issue-523-design.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/issues/issue-523-design.md b/issues/issue-523-design.md index 457a8aaf..fe4bd57d 100644 --- a/issues/issue-523-design.md +++ b/issues/issue-523-design.md @@ -233,6 +233,8 @@ sequenceDiagram ただし、判定がソケットを読む呼び出しと、探索が `VSCODE_GIT_ASKPASS_NODE` を読む呼び出しは別で、2 つが同じ attach の値であることは保証しない。2 つの読みの間に別のクライアントが attach すると、ソケットと `node` のパスが別のクライアントのものになり得る。この間の attach は許容する。2 つの読みは続けて行う tmux の呼び出しで、間に利用者の操作は挟まらない。1 回の呼び出しでまとめて読む形は、判定の既存の問い合わせを変え、I2(拾い直しが起きないときの問い合わせの回数)と非機能の条件(追加は 1 回だけ)を崩すため採らない。食い違ったときに起きることは「未確認のまま残ること」に置く。 +直し方は、要求の「起票者の推定」の S1・S2・S4〜S6 に沿い、S3(サーバーのディレクトリを探して使う)は採らない。推定はどれも課題の本文から読んだもので、設計はその対応を要求の表のとおりに引き継ぐ。 + VS Code サーバーのディレクトリ(`~/.vscode-server/cli/servers/*`)を探して選ぶ方法は採らない。手元のホストに版の違うサーバーが 6 つ並んでおり(実測。`ls -d ~/.vscode-server/cli/servers/*/server | wc -l` が 6)、どれが拾い直したソケットのものかを決める手がかりが無いためである。 - 作り方: 自前で作る・標準に倣う @@ -272,6 +274,8 @@ VS Code サーバーは統合ターミナルの `PATH` の先頭に自分の `re tmux の既定の `update-environment` は `VSCODE_*` を含まないため(STD1)、この経路は推奨設定を入れていない利用者で必ず通る。警告には環境変数ガイドの tmux の設定を案内し、利用者が `~/.tmux.conf` に 1 行足せば次から直る形にする。 +この決定は要求の前提 2 を採る。推奨設定をしていない利用者は、警告を受けて設定を足すまで手元の PC に窓が開かない。それでも採るのは、版のずれたサーバーで開くと、開いた窓が拾い直したソケットのクライアントのものである保証が無いためである。設定の 1 行で直る経路を警告で示せば、利用者は自分で直せる。 + サーバーのディレクトリを探して代わりに使う方法は採らない(決定 1 と同じ理由)。起動を止める方法も採らない。これまでの振る舞いより悪くしないためである。 根拠: Value 1(MVV 版 1) @@ -313,10 +317,7 @@ tmux の既定の `update-environment` は `VSCODE_*` を含まないため(ST ## 人へ残す判断 -| 判断 | 何が決まるか | 設計の扱い | -| --- | --- | --- | -| 要求の前提 2 の採否(`VSCODE_GIT_ASKPASS_NODE` から合う `remote-cli` を求められないとき、VS Code サーバーのディレクトリを探さず、`PATH` を変えずに警告する) | 推奨設定(`update-environment` に `VSCODE_GIT_ASKPASS_NODE` を入れる)をしていない利用者で、拾い直したときに手元の PC に窓が開くか、警告を受けて設定を足すまで開かないか | 要求の「未決」で利用者が設計承認ゲートで決めるとした項目である。決定 1・決定 4 は前提 2 を採る形で書いている。採らない場合は、決定 1・決定 4 と I1・テスト設計の I1 の行を書き直す | -| 要求の「起票者の推定」S1〜S6 の確認 | 直し方(`PATH` の先頭に合う `remote-cli` を入れる・`VSCODE_GIT_ASKPASS_NODE` から求める・サーバーのディレクトリを探さない・拾い直しが起きないときは変えない・テストの範囲・手元で窓が開く見込み)が利用者の意図に合うか | 課題の本文から読んだ推定で、利用者の決定としては扱っていない。設計はこの推定に沿って書いている。外れる項目があれば、その項目に対応する決定を書き直す | +無し(この設計の判断に、共通原則の C1〜C8・プロジェクト MVV の P1〜P3 に当たるものは無い) ## 未確認のまま残ること