[v0.1/CLI Args Review] Require -- before detached command argv #53

New issue

Closed

opened 2026-09-03 16:44:51 +09:00 by natsukium · 1 comment

natsukium commented

2026-09-03 16:44:51 +09:00

Owner

現状

felis sessions spawn だけが command argv の境界を -- で固定していない。

実装は #[arg(trailing_var_arg = true, allow_hyphen_values = true)] なので、felis sessions spawn htop と felis sessions spawn -- htop の両方を受理する。
help は Usage: felis sessions spawn [OPTIONS] [CMD]... と表示する一方、docs/reference/cli.md と tutorials は spawn [-- cmd…] / spawn -- <cmd> を正規形として説明している。
command を読み始めた後の felis option は child argv に吸われる。たとえば felis sessions spawn htop --format json の --format json は machine output 指定ではなく htop の引数になる。
さらに felis sessions spawn --json は unknown option にならず、--json という program を spawn しようとして daemon へ接続する。crates/felis-cli/src/tests.rs::the_retired_json_flag_is_an_unknown_argument も、この危険な例外を明示的に固定している。
bare launch (felis -- <cmd>) と retarget (felis ssh host -- <cmd>, felis window retarget -- <cmd>) はすでに last = true で -- を要求している。

これは互換性より安全性を優先できる初回リリース前に直すべき文法差である。option typo が usage error ではなく「その名前の program を実行する要求」に変わる境界は、CLI の explicitness と fail-closed 性を損なう。

提案

sessions spawn の command を bare launch / retarget と同じ -- <CMD>... grammar に統一する。

trailing_var_arg をやめ、last = true を使う。
felis sessions spawn htop は usage error (exit 2) にする。
felis sessions spawn -- htop --format json は --format json を child argv として保つ。
felis sessions spawn --format json -- htop は felis の machine format として保つ。
frontend <name> [ARGS]... は明示的な opaque pass-through namespace なので例外のままにする。

Principle check

Add only what earns its place — Pass. 新しい capability は増やさず、同一操作の重複文法を削る。
Render everything, fast — Pass. 非該当。
The daemon owns state, the client owns pixels — Pass. 非該当。
Explicit over heuristic — Pass. option と child argv の境界を明示する変更。

Acceptance criteria

spawn の usage が [OPTIONS] [-- <CMD>...] になる。
spawn htop / spawn --json / spawn htop --format json が clap usage error になる。
spawn --format json -- htop --format json では前者だけを felis が消費し、後者は child argv にそのまま残る。
bare launch、detached spawn、retarget の command separator 契約が同じになる。
clap tests、help、completions、man pages、docs/reference/cli.md、tutorials、skills/felis/SKILL.md、CHANGELOG.md を同時に更新する。

対象

crates/felis-cli/src/cli_sessions.rs
crates/felis-cli/src/tests.rs
docs/reference/cli.md
docs/tutorials/drive-without-a-window.md
skills/felis/SKILL.md

Parent review: #55

## 現状 `felis sessions spawn` だけが command argv の境界を `--` で固定していない。 - 実装は `#[arg(trailing_var_arg = true, allow_hyphen_values = true)]` なので、`felis sessions spawn htop` と `felis sessions spawn -- htop` の両方を受理する。 - help は `Usage: felis sessions spawn [OPTIONS] [CMD]...` と表示する一方、`docs/reference/cli.md` と tutorials は `spawn [-- cmd…]` / `spawn -- <cmd>` を正規形として説明している。 - command を読み始めた後の felis option は child argv に吸われる。たとえば `felis sessions spawn htop --format json` の `--format json` は machine output 指定ではなく htop の引数になる。 - さらに `felis sessions spawn --json` は unknown option にならず、`--json` という program を spawn しようとして daemon へ接続する。`crates/felis-cli/src/tests.rs::the_retired_json_flag_is_an_unknown_argument` も、この危険な例外を明示的に固定している。 - bare launch (`felis -- <cmd>`) と retarget (`felis ssh host -- <cmd>`, `felis window retarget -- <cmd>`) はすでに `last = true` で `--` を要求している。これは互換性より安全性を優先できる初回リリース前に直すべき文法差である。option typo が usage error ではなく「その名前の program を実行する要求」に変わる境界は、CLI の explicitness と fail-closed 性を損なう。 ## 提案 `sessions spawn` の command を bare launch / retarget と同じ `-- <CMD>...` grammar に統一する。 - `trailing_var_arg` をやめ、`last = true` を使う。 - `felis sessions spawn htop` は usage error (exit 2) にする。 - `felis sessions spawn -- htop --format json` は `--format json` を child argv として保つ。 - `felis sessions spawn --format json -- htop` は felis の machine format として保つ。 - `frontend <name> [ARGS]...` は明示的な opaque pass-through namespace なので例外のままにする。 ## Principle check 1. **Add only what earns its place — Pass.** 新しい capability は増やさず、同一操作の重複文法を削る。 2. **Render everything, fast — Pass.** 非該当。 3. **The daemon owns state, the client owns pixels — Pass.** 非該当。 4. **Explicit over heuristic — Pass.** option と child argv の境界を明示する変更。 ## Acceptance criteria - [ ] `spawn` の usage が `[OPTIONS] [-- <CMD>...]` になる。 - [ ] `spawn htop` / `spawn --json` / `spawn htop --format json` が clap usage error になる。 - [ ] `spawn --format json -- htop --format json` では前者だけを felis が消費し、後者は child argv にそのまま残る。 - [ ] bare launch、detached spawn、retarget の command separator 契約が同じになる。 - [ ] clap tests、help、completions、man pages、`docs/reference/cli.md`、tutorials、`skills/felis/SKILL.md`、`CHANGELOG.md` を同時に更新する。 ## 対象 - `crates/felis-cli/src/cli_sessions.rs` - `crates/felis-cli/src/tests.rs` - `docs/reference/cli.md` - `docs/tutorials/drive-without-a-window.md` - `skills/felis/SKILL.md` Parent review: #55

natsukium referenced this issue

2026-09-03 16:45:17 +09:00

[v0.1/CLI Args Review] CLI 引数のリリース前設計レビュー #55

natsukium added the

priority/P1

release/v0.1.0

labels

2026-09-03 16:45:27 +09:00

natsukium commented

2026-09-03 16:45:39 +09:00

Author

Owner