[v0.1/CLI Args Review] Remove the ignored root --trace-perf option #54

New issue

Closed

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

natsukium commented

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

Owner

現状

トップレベル felis --trace-perf は user-visible な global option だが、window launch 以外では受理したまま無視される。

help 自身が「Passed through to the execed frontend; ignored by the headless verbs」と明記している。
felis --trace-perf sessions list、felis --trace-perf doctor、felis --trace-perf bridge は parse に成功するが、main.rs の headless 分岐は値を読まない。
config や window retarget は意味のない global carrier を明示的に拒否しており、同じ CLI の「無効な option は拒否する」姿勢と不一致。
実際のログフィルタには既存の RUST_LOG があり、felis-client --trace-perf / felis-daemon serve --trace-perf も各プロセスの内部診断面として残せる。root option を全 verb に公開して silent no-op を許す必要はない。
frontend <name> に対して root の --trace-perf を自動転送することも、opaque frontend の grammar を felis が知らないという同 subcommand の設計と緊張する。

初回 CLI contract を freeze した後に option を削るより、今 user-facing root surface から外すか、意味がある invocation だけに scope すべきである。

提案

第一候補はトップレベル felis --trace-perf を削除する。

perf 計測は RUST_LOG=... felis ...、または内部 frontend/daemon binary の診断 option で行う。
alternate frontend には felis frontend <name> --trace-perf と明示的に opaque argv として渡せるため、root が grammar を推測して挿入しない。

残す場合でも、headless/config/doctor/bridge/retarget で parse 後に silent ignore してはならない。適用可能な launch form だけが受理する構造にするか、意味のない組み合わせを usage error にする。

Principle check

Add only what earns its place — Pass. RUST_LOG と process-local 診断 option が同じ用途を既に担うため、重複した public surface を削る。
Render everything, fast — Pass. 計測手段は残り、rendering behavior は変えない。
The daemon owns state, the client owns pixels — Pass. 非該当。
Explicit over heuristic — Pass. 受理した option が必ず効果を持つ契約にする。

Acceptance criteria

felis --help に、headless verb で無視される global option がない。
felis --trace-perf sessions list のような無効組み合わせが silent success/通常 dispatch にならない。
GUI client と daemon の hot-path trace を有効にする再現可能な手順が perf-trace skill に残る。
alternate frontend の argv は引き続き frontend <name> 以降だけが opaque pass-through である。
help、completions、man pages、CLI reference、skills/felis/SKILL.md、CHANGELOG.md を更新する。

対象

crates/felis-cli/src/main.rs
crates/felis-cli/src/tests.rs
docs/reference/cli.md
docs/explanation/architecture/control-surfaces.md
skills/felis/SKILL.md
.claude/skills/perf-trace/SKILL.md

Parent review: #55

## 現状トップレベル `felis --trace-perf` は user-visible な global option だが、window launch 以外では受理したまま無視される。 - help 自身が「Passed through to the execed frontend; ignored by the headless verbs」と明記している。 - `felis --trace-perf sessions list`、`felis --trace-perf doctor`、`felis --trace-perf bridge` は parse に成功するが、`main.rs` の headless 分岐は値を読まない。 - `config` や `window retarget` は意味のない global carrier を明示的に拒否しており、同じ CLI の「無効な option は拒否する」姿勢と不一致。 - 実際のログフィルタには既存の `RUST_LOG` があり、`felis-client --trace-perf` / `felis-daemon serve --trace-perf` も各プロセスの内部診断面として残せる。root option を全 verb に公開して silent no-op を許す必要はない。 - `frontend <name>` に対して root の `--trace-perf` を自動転送することも、opaque frontend の grammar を felis が知らないという同 subcommand の設計と緊張する。初回 CLI contract を freeze した後に option を削るより、今 user-facing root surface から外すか、意味がある invocation だけに scope すべきである。 ## 提案第一候補はトップレベル `felis --trace-perf` を削除する。 - perf 計測は `RUST_LOG=... felis ...`、または内部 frontend/daemon binary の診断 option で行う。 - alternate frontend には `felis frontend <name> --trace-perf` と明示的に opaque argv として渡せるため、root が grammar を推測して挿入しない。残す場合でも、headless/config/doctor/bridge/retarget で parse 後に silent ignore してはならない。適用可能な launch form だけが受理する構造にするか、意味のない組み合わせを usage error にする。 ## Principle check 1. **Add only what earns its place — Pass.** `RUST_LOG` と process-local 診断 option が同じ用途を既に担うため、重複した public surface を削る。 2. **Render everything, fast — Pass.** 計測手段は残り、rendering behavior は変えない。 3. **The daemon owns state, the client owns pixels — Pass.** 非該当。 4. **Explicit over heuristic — Pass.** 受理した option が必ず効果を持つ契約にする。 ## Acceptance criteria - [ ] `felis --help` に、headless verb で無視される global option がない。 - [ ] `felis --trace-perf sessions list` のような無効組み合わせが silent success/通常 dispatch にならない。 - [ ] GUI client と daemon の hot-path trace を有効にする再現可能な手順が `perf-trace` skill に残る。 - [ ] alternate frontend の argv は引き続き `frontend <name>` 以降だけが opaque pass-through である。 - [ ] help、completions、man pages、CLI reference、`skills/felis/SKILL.md`、`CHANGELOG.md` を更新する。 ## 対象 - `crates/felis-cli/src/main.rs` - `crates/felis-cli/src/tests.rs` - `docs/reference/cli.md` - `docs/explanation/architecture/control-surfaces.md` - `skills/felis/SKILL.md` - `.claude/skills/perf-trace/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:46:07 +09:00

Author

Owner