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

natsukium commented

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

Owner

概要

v0.1.0 の public contract freeze 前提で、CLI argument grammar を 2645b986 + review working tree (5077d74b) に対して重点レビューした。互換性は考慮せず、以下を実施した。

felis / 全 visible subcommand / felis-client / felis-daemon の実 help を生成して比較
clap derive 定義と parser tests を全走査
docs/reference/cli.md、reference/control-surfaces.md、explanation/architecture/control-surfaces.md、IPC/requirements/backlog と照合
typo、option placement、mutual exclusion、machine mode、command argv separator、dynamic completion の失敗経路を実コマンドで確認

設計の主軸（window launch と headless verbs の分離、typed argv、session prefix、Point/Stream/Exempt の分類）は維持できる。一方、凍結前に直すべき新規2件と、既存 P0/P1 issue に追加して確認すべき argument-level gap が見つかった。

新規 issue

Issue	優先度	判定	理由
#53	P1	破壊的変更推奨	`sessions spawn` だけ `--` を要求せず、option typo (`spawn --json`) を program 実行要求として受理する。bare launch/retarget と `-- <CMD>...` に統一する。
#54	P1	削除または scope 制限推奨	root `--trace-perf` は headless/config/doctor/bridge で受理後 silent ignore。`RUST_LOG` と process-local 診断面があるため public global に置く根拠が弱い。

既存 issue に統合する確認事項

#17 — version grammar

felis --version sessions list と felis --version -- htop が parse に成功し、後続 command を無視して version report を exit 0 で返す。#17 の offline/self-only 化に加え、標準 --version と同様に exclusive であることを acceptance に含めるべき。

#23 — machine/usage contract

#23 の方針は妥当だが、実装時に次を golden test へ含める必要がある。

sessions spawn --format json --json の daemon-autospawn failure では、stderr に tracing の INFO 行が先行し、現在の「point failure は exactly one JSON object」という契約を破る。machine channel と logs を分離または machine mode で console logs を抑止する。
--format と capture --source は custom value_parser = fn のため、help/completion metadata に possible values が載らない。completions を public surface とするなら finite vocabulary を clap に公開する。
window retarget --session 1a -- htop、SSH carrier なしの --ssh-arg、payload なしの send は clap 後の usage error。#23 の「valid machine format 認識後の usage error は同 format」をこの全経路で揃える。
send --raw --wait / send --raw --key enter は --raw の対象 payload がないのに受理される。無効 option を拒否するか、効果がある意味を定義する。

#27 — config path

--config PATH は argument review でも必要性を再確認した。Windows test だけでなく、実 profile を置換せず config check/show-effective を試す唯一の再現可能な入口になる。既存 #27 の scope で十分。

#23 / #37 / #38 / #39 — carrier spelling and placement

同じ --host が root では「この invocation が dial する daemon」、window retarget 配下では「window の destination」を意味し、flag の位置だけで役割が変わる。#23 の --to-host + felis ssh removal が最も単純で、#37–#39 の問いをまとめて閉じられる。root carrier を真の global option として subcommand 後にも許すか、常に root-before-command と凍結するかも同時に決める。

#39 / #42 — dynamic completion の network side effect

fish/zsh completion は <TAB> ごとに hidden __complete-sessions を実行し、in-flight --host を転送して SSH 接続する。connect_stdio_command は SSH stderr/TTY を継承し felis-side timeout を持たないため、remote session-id completion が password/host-key prompt や不達 host で対話シェルを停止し得る。

completion は local-only に戻す、短い hard timeout + noninteractive SSH + cache を設ける、または remote dynamic completion を削る、のどれかを #39/#42 の carrier/timeout 決定に含めるべき。explanation/architecture/control-surfaces.md は helper を local-only と記述する一方、実装と reference/cli.md は remote forwarding を normative としており、現状は docs も不整合。

今回は変更不要と判断した点

felis attach を top-level launcher、sessions switch を headless IPC verb とする分離: process boundary を正しく表しており、closed #3 の再オープン理由なし。
frontend <name> [ARGS]... のみ opaque pass-through: namespace が明示されており、unknown built-in typo を exec しない。
send <id> - の stdin convention、repeatable --key、--env KEY=VAL: shell string evaluator を導入せず typed data のまま。
session id の full hex + unique prefix: human paste-back と persisted id の区別が明確。

推奨順序

#17 で --version の standard/exclusive contract を確定。
#23 と #37–#39 で machine output / carrier naming / alias を一度に確定。
#53 で全 command-launch form の separator を統一。
#54 で ignored root option を除去。
#39/#42 で completion の remote dial policy を確定。
#27 を実装後、全 clap help/completion/man/schema golden を #29 で freeze。

Principle verdict

提案はいずれも capability を増やさず、曖昧・重複・silent no-op を削る。principles 1–4 はすべて Pass。特に command separator と ignored option の除去は principle 4 の explicitness を強める。

完了条件

新規2件と上記既存 P0/P1 issue の argument-level acceptance が解決済み。
全 visible command の help snapshot と valid/invalid argv matrix がテストされる。
machine mode の stdout/stderr に console log が混ざらない。
finite option values が help と generated completion の両方に現れる。
completion が <TAB> から無期限/対話的 network operation を起動しない。
docs/reference/cli.md、reference/explanation twins、tutorials、man、completion、skills/felis、CHANGELOG.md が同じ grammar を示す。

レビュー対象

crates/felis-cli/src/{main,cli_sessions,cli_output,cli_completions,cli_notifications,cli_config,cli_daemon}.rs
crates/felis-client/src/main.rs
crates/felis-daemon/src/main.rs
crates/felis-client-core/src/{dial,connector,local_socket}.rs
docs/reference/{cli,control-surfaces,spec}.md
docs/explanation/{design,principles,non-goals,architecture/control-surfaces,architecture/ipc}.md
docs/backlog.md

Parent release tracker: #12

## 概要 v0.1.0 の public contract freeze 前提で、CLI argument grammar を `2645b986` + review working tree (`5077d74b`) に対して重点レビューした。互換性は考慮せず、以下を実施した。 - `felis` / 全 visible subcommand / `felis-client` / `felis-daemon` の実 help を生成して比較 - clap derive 定義と parser tests を全走査 - `docs/reference/cli.md`、`reference/control-surfaces.md`、`explanation/architecture/control-surfaces.md`、IPC/requirements/backlog と照合 - typo、option placement、mutual exclusion、machine mode、command argv separator、dynamic completion の失敗経路を実コマンドで確認設計の主軸（window launch と headless verbs の分離、typed argv、session prefix、Point/Stream/Exempt の分類）は維持できる。一方、**凍結前に直すべき新規2件**と、既存 P0/P1 issue に追加して確認すべき argument-level gap が見つかった。 ## 新規 issue | Issue | 優先度 | 判定 | 理由 | |---|---:|---|---| | #53 | P1 | 破壊的変更推奨 | `sessions spawn` だけ `--` を要求せず、option typo (`spawn --json`) を program 実行要求として受理する。bare launch/retarget と `-- <CMD>...` に統一する。 | | #54 | P1 | 削除または scope 制限推奨 | root `--trace-perf` は headless/config/doctor/bridge で受理後 silent ignore。`RUST_LOG` と process-local 診断面があるため public global に置く根拠が弱い。 | ## 既存 issue に統合する確認事項 ### #17 — version grammar `felis --version sessions list` と `felis --version -- htop` が parse に成功し、後続 command を無視して version report を exit 0 で返す。#17 の offline/self-only 化に加え、標準 `--version` と同様に exclusive であることを acceptance に含めるべき。 ### #23 — machine/usage contract #23 の方針は妥当だが、実装時に次を golden test へ含める必要がある。 1. `sessions spawn --format json --json` の daemon-autospawn failure では、stderr に tracing の INFO 行が先行し、現在の「point failure は exactly one JSON object」という契約を破る。machine channel と logs を分離または machine mode で console logs を抑止する。 2. `--format` と `capture --source` は custom `value_parser = fn` のため、help/completion metadata に possible values が載らない。`completions` を public surface とするなら finite vocabulary を clap に公開する。 3. `window retarget --session 1a -- htop`、SSH carrier なしの `--ssh-arg`、payload なしの `send` は clap 後の usage error。#23 の「valid machine format 認識後の usage error は同 format」をこの全経路で揃える。 4. `send --raw --wait` / `send --raw --key enter` は `--raw` の対象 payload がないのに受理される。無効 option を拒否するか、効果がある意味を定義する。 ### #27 — config path `--config PATH` は argument review でも必要性を再確認した。Windows test だけでなく、実 profile を置換せず `config check/show-effective` を試す唯一の再現可能な入口になる。既存 #27 の scope で十分。 ### #23 / #37 / #38 / #39 — carrier spelling and placement 同じ `--host` が root では「この invocation が dial する daemon」、`window retarget` 配下では「window の destination」を意味し、flag の位置だけで役割が変わる。#23 の `--to-host` + `felis ssh` removal が最も単純で、#37–#39 の問いをまとめて閉じられる。root carrier を真の global option として subcommand 後にも許すか、常に root-before-command と凍結するかも同時に決める。 ### #39 / #42 — dynamic completion の network side effect fish/zsh completion は `<TAB>` ごとに hidden `__complete-sessions` を実行し、in-flight `--host` を転送して SSH 接続する。`connect_stdio_command` は SSH stderr/TTY を継承し felis-side timeout を持たないため、remote session-id completion が password/host-key prompt や不達 host で対話シェルを停止し得る。 completion は local-only に戻す、短い hard timeout + noninteractive SSH + cache を設ける、または remote dynamic completion を削る、のどれかを #39/#42 の carrier/timeout 決定に含めるべき。`explanation/architecture/control-surfaces.md` は helper を local-only と記述する一方、実装と `reference/cli.md` は remote forwarding を normative としており、現状は docs も不整合。 ## 今回は変更不要と判断した点 - `felis attach` を top-level launcher、`sessions switch` を headless IPC verb とする分離: process boundary を正しく表しており、closed #3 の再オープン理由なし。 - `frontend <name> [ARGS]...` のみ opaque pass-through: namespace が明示されており、unknown built-in typo を exec しない。 - `send <id> -` の stdin convention、repeatable `--key`、`--env KEY=VAL`: shell string evaluator を導入せず typed data のまま。 - session id の full hex + unique prefix: human paste-back と persisted id の区別が明確。 ## 推奨順序 1. #17 で `--version` の standard/exclusive contract を確定。 2. #23 と #37–#39 で machine output / carrier naming / alias を一度に確定。 3. #53 で全 command-launch form の separator を統一。 4. #54 で ignored root option を除去。 5. #39/#42 で completion の remote dial policy を確定。 6. #27 を実装後、全 clap help/completion/man/schema golden を #29 で freeze。 ## Principle verdict 提案はいずれも capability を増やさず、曖昧・重複・silent no-op を削る。principles 1–4 はすべて Pass。特に command separator と ignored option の除去は principle 4 の explicitness を強める。 ## 完了条件 - [ ] 新規2件と上記既存 P0/P1 issue の argument-level acceptance が解決済み。 - [ ] 全 visible command の help snapshot と valid/invalid argv matrix がテストされる。 - [ ] machine mode の stdout/stderr に console log が混ざらない。 - [ ] finite option values が help と generated completion の両方に現れる。 - [ ] completion が `<TAB>` から無期限/対話的 network operation を起動しない。 - [ ] `docs/reference/cli.md`、reference/explanation twins、tutorials、man、completion、`skills/felis`、`CHANGELOG.md` が同じ grammar を示す。 ## レビュー対象 - `crates/felis-cli/src/{main,cli_sessions,cli_output,cli_completions,cli_notifications,cli_config,cli_daemon}.rs` - `crates/felis-client/src/main.rs` - `crates/felis-daemon/src/main.rs` - `crates/felis-client-core/src/{dial,connector,local_socket}.rs` - `docs/reference/{cli,control-surfaces,spec}.md` - `docs/explanation/{design,principles,non-goals,architecture/control-surfaces,architecture/ipc}.md` - `docs/backlog.md` Parent release tracker: #12

natsukium added the

release/v0.1.0

type/tracker

labels

Rows
Columns

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

概要