tvctl/claude-observations-plan.md

Claude Observations Plan

Reference source: claude-observations.txt

This file is a fact-checked implementation plan based on the numbered observations in claude-observations.txt. It reflects the current worktree state on 2026-04-18, not just the last committed main.

Fact Check Summary

Observation	Status	Fact Check	Planned Action
1. format_tv_key duplicates normalized key mapping	Confirmed	src/daemon/mod.rs still has a 33-arm format_tv_key helper and one call site in the SendKey action detail path. src/adapters/mod.rs still has a separate parse_normalized_tv_key table and TvKey keeps #[serde(rename_all = "kebab-case")].	Remove the duplicate reverse table. Preferred fix: add a canonical string conversion on TvKey and use it from the daemon response text.
2. DeviceRegistry::remove duplicates find matching logic	Confirmed	src/daemon/registry.rs has find() with inline UUID/name matching and remove() with separate matches_target(...) logic.	Refactor remove() to reuse find() or otherwise share one target-matching implementation. Delete the duplicate matcher after the refactor.
3. parse_bool is a no-value wrapper	Confirmed	src/daemon/config.rs still has fn parse_bool(...) { parse_value(...) } and uses it in set_value(...).	Delete parse_bool and switch the bool assignments to parse_value(...).
4. HTTP API loops back through the Unix socket even though it is in-process	Completed locally on 2026-04-18	Refactored src/api/mod.rs to call daemon::execute_request(...) directly and added an in-process HTTP regression test that succeeds without starting the daemon Unix socket server.	No further change needed unless follow-up regressions are found.
5. PROJECT_MAP.md is stale about Milestone 5 / HTTP status	Stale in current worktree	In the current worktree, PROJECT_MAP.md is already locally updated to Last updated: 2026-04-18 and Phase: Milestone 6 in progress. This observation was valid against an older snapshot, not the current tree.	No repo change needed for this item unless those local doc edits are reverted before commit.
6. Missing cleanup for node-compile-cache/ and phantomjs/	Partially confirmed	Neither directory exists in the current repo tree, but .gitignore does not currently list them. The observation appears archive-related rather than evidence of a current tracked repo problem.	Add preventive ignore entries later if desired. No tracked-file cleanup is needed unless those directories reappear.
7. get_value() allocates a full BTreeMap for one lookup	Confirmed	src/daemon/config.rs still implements get_value() as self.entries().remove(key).	Rewrite get_value() as a direct match over stable keys so it no longer allocates the full map for single-key reads.
8. roku_key_paths unsupported-key intent is unclear	Confirmed	src/adapters/roku/mod.rs still falls through from valid Ok(...) arms into a bottom branch where Stop, Skip, Power, PowerOn, and Options are only used to build InvalidKey(...).	Add a clarifying comment above the fall-through block. No behavior change needed.
9. RefreshAppsBody optional clear handling can be simplified	Cosmetic	src/api/mod.rs still uses `body.map(	value
10. Rust 2024 edition note	Informational only	Cargo.toml already uses edition = "2024". No code issue is implied.	No repo change needed now. Keep the note in mind when CI is added so the toolchain is new enough.

Execution Order

The future implementation order should stay low-risk first and defer the heavier HTTP refactor until the small cleanups are merged or at least locally stable.

1. Remove duplication and low-risk cleanup

   • Observation 3: delete parse_bool
   • Observation 8: add unsupported-key comment in roku_key_paths
   • Observation 9: simplify RefreshAppsBody boolean handling if already editing src/api/mod.rs

2. Remove duplicated matching / key-string tables

   • Observation 2: unify DeviceRegistry target matching
   • Observation 1: replace format_tv_key with one canonical TvKey string path
   • Observation 7: rewrite get_value() to avoid entries() allocation

3. Perform the medium-risk HTTP architecture cleanup

   • Observation 4: replace Unix-socket loopback in the HTTP API with direct execute_request(...)
   • Add focused regression coverage around HTTP handlers after this change because it changes the transport path, not just formatting

4. Preventive hygiene

   • Observation 6: add .gitignore entries for node-compile-cache/ and phantomjs/ if we want to harden against future archive/worktree leakage

Constraints For Future Work

• Keep this work separate from the current uncommitted logging-related changes already in the worktree unless the user explicitly asks to batch them together.
• Do not assume all Claude observations are still valid against the live tree. Re-check each item immediately before implementation.
• Preserve current user-facing behavior where possible, especially for daemon/API error payloads and CLI help/output.