[v0.1/CLI Args Review] Expose the finite --format/--source vocabularies to clap #184

New issue

Closed

opened 2026-09-07 16:10:18 +09:00 by natsukium · 1 comment

natsukium commented

2026-09-07 16:10:18 +09:00

Owner

現状

--format と capture --source は有限語彙なのに、clap へ value_parser = fn で渡しているため、possible values が help と generated completion のどちらにも現れない。#55 で指摘済みだが子 issue がなく、追跡されていない。

実機確認 (felis sessions capture --help):

--format <FORMAT> — [possible values: …] なし。本文に `human` (default) or `jsonl` と書くのみ。
--source <SOURCE> — 同上。visible / scrollback / command-output / last-command は本文のみ。

該当 parser:

crates/felis-cli/src/cli_output.rs — parse_point_format (human/json)、parse_stream_format (human/jsonl)
crates/felis-cli/src/cli_sessions.rs:469 — parse_region_source (visible / scrollback / command-output / last-command)

completions <shell> は clap_complete 経由で生成されるが、fn parser の値域は補完候補に出ない (fish/zsh overlay が足すのは session id のみ)。--key の chord 文法や KEY=VAL、ID-OR-PREFIX は無限文法なので対象外。completions <shell> の shell 名は clap_complete::Shell (ValueEnum) で公開済み。

提案

有限語彙の 2 flag を PossibleValuesParser / ValueEnum 化し、語彙を clap に公開する。

無効値は従来どおり exit 2 の usage error。ただし現行の親切な文言 (例: `jsonl` frames a stream; …) は clap 既定の invalid-value error に変わる。これは pre-publish の破壊的変更として許容し、CHANGELOG.md Unreleased に記す。文言を残す安価な手段があれば残すが、必須としない。
felis completions bash|zsh|fish の生成物に当該値が現れることを golden で固定する。
help snapshot (本件と同時に #184 が立てる場合はそちらへ) と man pages を再生成する。

Principle check

Add only what earns its place — Pass. 能力は増やさず、重複記述 (本文中の語彙列挙) を単一の機械可読な定義に寄せる。
Explicit over heuristic — Pass. 受け入れる値を grammar 層で明示する変更。

Acceptance criteria

sessions capture --help 等の --format / --source に [possible values: …] が現れる。
生成された bash/zsh/fish completion が当該値を補完する (golden test)。
無効値 (--format jsonl on point verb、--source bogus) が exit 2 であることがテストされる。
docs/reference/cli.md が error 文言を引用している箇所があれば新文言に同期する。
CHANGELOG.md に pre-publish break として記す。

対象

crates/felis-cli/src/cli_output.rs (PointFormat, StreamFormat, parser 2 関数)
crates/felis-cli/src/cli_sessions.rs (parse_region_source と使用箇所)
crates/felis-cli/src/tests.rs (help/completion golden)
docs/reference/cli.md、CHANGELOG.md

Parent review: #55. Release tracker: #12.

## 現状 `--format` と `capture --source` は有限語彙なのに、clap へ `value_parser = fn` で渡しているため、possible values が help と generated completion のどちらにも現れない。#55 で指摘済みだが子 issue がなく、追跡されていない。実機確認 (`felis sessions capture --help`): - `--format <FORMAT>` — `[possible values: …]` なし。本文に `` `human` (default) or `jsonl` `` と書くのみ。 - `--source <SOURCE>` — 同上。`visible` / `scrollback` / `command-output` / `last-command` は本文のみ。該当 parser: - `crates/felis-cli/src/cli_output.rs` — `parse_point_format` (`human`/`json`)、`parse_stream_format` (`human`/`jsonl`) - `crates/felis-cli/src/cli_sessions.rs:469` — `parse_region_source` (`visible` / `scrollback` / `command-output` / `last-command`) `completions <shell>` は clap_complete 経由で生成されるが、fn parser の値域は補完候補に出ない (fish/zsh overlay が足すのは session id のみ)。`--key` の chord 文法や `KEY=VAL`、`ID-OR-PREFIX` は無限文法なので対象外。`completions <shell>` の shell 名は `clap_complete::Shell` (ValueEnum) で公開済み。 ## 提案有限語彙の 2 flag を `PossibleValuesParser` / `ValueEnum` 化し、語彙を clap に公開する。 - 無効値は従来どおり exit `2` の usage error。ただし現行の親切な文言 (例: `` `jsonl` frames a stream; … ``) は clap 既定の invalid-value error に変わる。これは pre-publish の破壊的変更として許容し、`CHANGELOG.md` Unreleased に記す。文言を残す安価な手段があれば残すが、必須としない。 - `felis completions bash|zsh|fish` の生成物に当該値が現れることを golden で固定する。 - help snapshot (本件と同時に #184 が立てる場合はそちらへ) と man pages を再生成する。 ## Principle check 1. **Add only what earns its place — Pass.** 能力は増やさず、重複記述 (本文中の語彙列挙) を単一の機械可読な定義に寄せる。 2. **Explicit over heuristic — Pass.** 受け入れる値を grammar 層で明示する変更。 ## Acceptance criteria - [ ] `sessions capture --help` 等の `--format` / `--source` に `[possible values: …]` が現れる。 - [ ] 生成された bash/zsh/fish completion が当該値を補完する (golden test)。 - [ ] 無効値 (`--format jsonl` on point verb、`--source bogus`) が exit `2` であることがテストされる。 - [ ] `docs/reference/cli.md` が error 文言を引用している箇所があれば新文言に同期する。 - [ ] `CHANGELOG.md` に pre-publish break として記す。 ## 対象 - `crates/felis-cli/src/cli_output.rs` (`PointFormat`, `StreamFormat`, parser 2 関数) - `crates/felis-cli/src/cli_sessions.rs` (`parse_region_source` と使用箇所) - `crates/felis-cli/src/tests.rs` (help/completion golden) - `docs/reference/cli.md`、`CHANGELOG.md` Parent review: #55. Release tracker: #12.

natsukium referenced this issue

2026-09-07 16:10:23 +09:00

[v0.1/CLI Args Review] Snapshot the visible help and pin the valid/invalid argv matrix #185

natsukium added the

priority/P1

release/v0.1.0

labels

2026-09-07 16:10:35 +09:00

natsukium referenced this issue

2026-09-07 16:10:44 +09:00

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

natsukium referenced this issue

2026-09-07 16:16:40 +09:00

Request schema accepts source and attachment strings the runtime rejects, so schema-valid requests can still fail as malformed #178

natsukium commented

2026-09-07 16:31:32 +09:00

Author

Owner

Merged into #187, which carries the same change (ValueEnums for --format and capture --source, possible values in help, completion golden, exit 2 on a bad value, CHANGELOG entry) and is being implemented on branch feat/finite-option-values-187. Closing as a duplicate; #187 reports back to #55.

Merged into #187, which carries the same change (ValueEnums for `--format` and `capture --source`, possible values in help, completion golden, exit 2 on a bad value, CHANGELOG entry) and is being implemented on branch `feat/finite-option-values-187`. Closing as a duplicate; #187 reports back to #55.

natsukium closed this issue

2026-09-07 16:31:32 +09:00

natsukium referenced this issue

2026-09-08 01:39:59 +09:00

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