[1.0 Review] config.toml の単一文書オーバレイと探索パス・キー名の凍結 #4

New issue

Closed

opened 2026-09-03 16:02:21 +09:00 by natsukium · 1 comment

natsukium commented

2026-09-03 16:02:21 +09:00

Owner

背景

config.toml は client-only（daemon は読まない）で、1ファイルに [client.<name>] オーバレイを深マージする設計。reference/config.md と explanation/architecture/control-surfaces.md に「一つの文書を全クライアントで共有する」決定として記録されている。1.0 でファイル形式と探索パスを凍結する前に見直す。

現状の問題 / 凍結前に決めるべき点

1. 単一文書 + オーバレイ vs 複数ファイル

現行: ~/.config/felis/config.toml（Linux: XDG, macOS: Application Support, Windows: %APPDATA%\felis\config\config.toml）1ファイルに base + client.felis / client.<other> を同居。ConfigDocument → EffectiveConfig の二段階解決、unknown key は warn、他 client セクションは inert。

長所: 1箇所で全体を見渡せる、共有できない値が drift しない。
短所:

サードパーティ frontend が独自キーを追加すると base の schema 検証を汚す（additionalProperties: false にできない理由）。
felis config check --client <id> が「一つの overlay だけ」を見る仕様は直感的でない。
Nix/home-manager の symlink 管理（config.toml が /nix/store への symlink）では mtime ではなく resolved path の変化で reload する特殊分岐が必要。

代替案（今なら破壊的変更可能）:

config.toml + config.d/<client>.toml の drop-in ディレクトリ。
あるいは XDG 準拠で felis/config.toml と felis/clients/felis.toml に分離。

いずれも additionalProperties: false を有効にでき、JSON Schema を strict にできる。

2. 探索パスと platform 差

macOS が ~/Library/Application Support/felis/config.toml で ~/.config/felis を無視する点は ProjectDirs 由来だが、ユーザの混乱が継続（docs/how-to/fix-terminfo-problems.md にも言及）。1.0 で XDG_CONFIG_HOME を全 platform で優先するか、両方を読むフォールバックにするか。
Windows の extra config\ セグメント（%APPDATA%\felis\config\config.toml）も同様。
felis config の E2E テストが Windows で cfg(unix) に限定されているのは、Known Folder API が env var を読まないため。--config <path> / FELIS_CONFIG のような override surface が無いのが直接原因（backlog.md にも記載）。

問い: 1.0 で config path の override（--config flag / FELIS_CONFIG env）を追加するか？追加しないなら Windows でのテスト不能を 1.0 の既知制限として凍結する。

3. キー名とデフォルト値の凍結

window.opacity (0.0–1.0) と window.backdrop (none/blur/acrylic/mica/tabbed) の結合: blur は opacity < 1.0 でないと無効、Windows material は常に title bar のみに効く。1キーに OS 依存の値集合を持たせるのは例外として文書化されているが、将来 backdrop に Linux 値が追加されると OS ごとの値集合がさらに分岐する。
clipboard.osc_52 = "mirror" | "system" は security-conscious デフォルトだが、将来的に "reject" を追加する余地があるか。
font.fallback が [{family, features}] の配列で、省略時 auto-discover（CJK+emoji+nerd）。空配列で auto-discover を無効化する暗黙の切り替えは、explicitness 原則と緊張する。
shader.post = {builtin="trail"} | {file="..."} の2形態は、将来 shader.post = ["trail", {file=...}] のような多段 post-process を許すかどうかに影響。

4. 生存期間と reload

font.size 等は live reload、window.opacity の opaque↔translucent 跨ぎは要 relaunch という例外が reference/config.md に表で列挙されている。1.0 で「どれが live でどれが要 relaunch か」をユーザが推測できる命名（例: window.opacity を window.startup_opacity に）にする必要はないか。

提案

1.0 リリース前に config surface の最終形を決め、reference/config.md の「Not configurable today」（scrollback depth）と併せて「1.0 で凍結したキー集合」として明記。追加キーも additive（#[serde(default)]）で読める契約は維持するが、キー名自体は今しか変えられない。
--config / FELIS_CONFIG の要否を backlog.md の「config path control surface」項目と紐づけて判断。追加するなら felis config {path,check,show-effective} がそれを尊重する仕様にし、Windows の E2E を cfg(unix) から外す。
client.<name> オーバレイを残すなら、JSON Schema の additionalProperties を non-strict にする理由を felis-config.schema.json のコメントと config.md に残し、将来の strict 化トリガ（例: 全 client が schema を共有できた時）を explanation/architecture/control-surfaces.md に記録。

判定基準

新規ユーザが felis config path の出力を見て、どこに何を書けばいいか迷わないこと。
サードパーティ frontend が独自キーを追加しても base の検証が壊れず、かつ typo が editor 上で検出できること（lenient parsing と strict schema の両立）。

cc @natsukium

## 背景 `config.toml` は client-only（daemon は読まない）で、1ファイルに `[client.<name>]` オーバレイを深マージする設計。`reference/config.md` と `explanation/architecture/control-surfaces.md` に「一つの文書を全クライアントで共有する」決定として記録されている。1.0 でファイル形式と探索パスを凍結する前に見直す。 ## 現状の問題 / 凍結前に決めるべき点 ### 1. 単一文書 + オーバレイ vs 複数ファイル現行: `~/.config/felis/config.toml`（Linux: XDG, macOS: Application Support, Windows: `%APPDATA%\felis\config\config.toml`）1ファイルに base + `client.felis` / `client.<other>` を同居。`ConfigDocument` → `EffectiveConfig` の二段階解決、unknown key は warn、他 client セクションは inert。長所: 1箇所で全体を見渡せる、共有できない値が drift しない。短所: - サードパーティ frontend が独自キーを追加すると base の schema 検証を汚す（`additionalProperties: false` にできない理由）。 - `felis config check --client <id>` が「一つの overlay だけ」を見る仕様は直感的でない。 - Nix/home-manager の symlink 管理（`config.toml` が `/nix/store` への symlink）では mtime ではなく resolved path の変化で reload する特殊分岐が必要。代替案（今なら破壊的変更可能）: - `config.toml` + `config.d/<client>.toml` の drop-in ディレクトリ。 - あるいは XDG 準拠で `felis/config.toml` と `felis/clients/felis.toml` に分離。いずれも `additionalProperties: false` を有効にでき、JSON Schema を strict にできる。 ### 2. 探索パスと platform 差 - macOS が `~/Library/Application Support/felis/config.toml` で `~/.config/felis` を無視する点は `ProjectDirs` 由来だが、ユーザの混乱が継続（`docs/how-to/fix-terminfo-problems.md` にも言及）。1.0 で `XDG_CONFIG_HOME` を全 platform で優先するか、両方を読むフォールバックにするか。 - Windows の extra `config\` セグメント（`%APPDATA%\felis\config\config.toml`）も同様。 - `felis config` の E2E テストが Windows で `cfg(unix)` に限定されているのは、Known Folder API が env var を読まないため。`--config <path>` / `FELIS_CONFIG` のような override surface が無いのが直接原因（`backlog.md` にも記載）。 **問い:** 1.0 で config path の override（`--config` flag / `FELIS_CONFIG` env）を追加するか？追加しないなら Windows でのテスト不能を 1.0 の既知制限として凍結する。 ### 3. キー名とデフォルト値の凍結 - `window.opacity` (0.0–1.0) と `window.backdrop` (`none/blur/acrylic/mica/tabbed`) の結合: `blur` は `opacity < 1.0` でないと無効、Windows material は常に title bar のみに効く。1キーに OS 依存の値集合を持たせるのは例外として文書化されているが、将来 `backdrop` に Linux 値が追加されると OS ごとの値集合がさらに分岐する。 - `clipboard.osc_52 = "mirror" | "system"` は security-conscious デフォルトだが、将来的に `"reject"` を追加する余地があるか。 - `font.fallback` が `[{family, features}]` の配列で、省略時 auto-discover（CJK+emoji+nerd）。空配列で auto-discover を無効化する暗黙の切り替えは、explicitness 原則と緊張する。 - `shader.post = {builtin="trail"} | {file="..."}` の2形態は、将来 `shader.post = ["trail", {file=...}]` のような多段 post-process を許すかどうかに影響。 ### 4. 生存期間と reload `font.size` 等は live reload、`window.opacity` の opaque↔translucent 跨ぎは要 relaunch という例外が `reference/config.md` に表で列挙されている。1.0 で「どれが live でどれが要 relaunch か」をユーザが推測できる命名（例: `window.opacity` を `window.startup_opacity` に）にする必要はないか。 ## 提案 - 1.0 リリース前に config surface の最終形を決め、`reference/config.md` の「Not configurable today」（scrollback depth）と併せて「1.0 で凍結したキー集合」として明記。追加キーも additive（`#[serde(default)]`）で読める契約は維持するが、キー名自体は今しか変えられない。 - `--config` / `FELIS_CONFIG` の要否を `backlog.md` の「config path control surface」項目と紐づけて判断。追加するなら `felis config {path,check,show-effective}` がそれを尊重する仕様にし、Windows の E2E を `cfg(unix)` から外す。 - `client.<name>` オーバレイを残すなら、JSON Schema の `additionalProperties` を non-strict にする理由を `felis-config.schema.json` のコメントと `config.md` に残し、将来の strict 化トリガ（例: 全 client が schema を共有できた時）を `explanation/architecture/control-surfaces.md` に記録。 ## 判定基準 - 新規ユーザが `felis config path` の出力を見て、どこに何を書けばいいか迷わないこと。 - サードパーティ frontend が独自キーを追加しても base の検証が壊れず、かつ typo が editor 上で検出できること（lenient parsing と strict schema の両立）。 cc @natsukium

natsukium referenced this issue

2026-09-03 16:05:02 +09:00

[1.0 Review] リリース前設計レビュー — 親トラッキング（8件） #11

natsukium referenced this issue

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

[v0.1/P1] Add one explicit --config PATH control surface #27

natsukium commented

2026-09-03 16:19:13 +09:00

Author

Owner

Superseded by #27 (--config PATH) and #28 (font.size_px). The later review retained the single-document overlay and default discovery model; #12 now tracks the accepted v0.1.0 changes.

Superseded by #27 (`--config PATH`) and #28 (`font.size_px`). The later review retained the single-document overlay and default discovery model; #12 now tracks the accepted v0.1.0 changes.

natsukium closed this issue

2026-09-03 16:19:13 +09:00

natsukium referenced this issue

2026-09-03 16:26:57 +09:00

[Post-v0.1/P2] Choose the scrollback capacity control surface #36

natsukium referenced this issue

2026-09-05 11:37:45 +09:00

[v0.1/Config Review] Windows/macOS の config 探索パス二重化は 1.0 で正規化すべき #137

natsukium referenced this issue

2026-09-05 11:38:37 +09:00

[v0.1/Config Review] client overlay の schema/runtime 乖離と additionalProperties 凍結 #140

natsukium referenced this issue