tvctl/claude-observations.txt

AGENT INSTRUCTION: BELOW ARE SOME OBSERVATIONS FROM CLAUDE. ITS ONLY PARTIAL BECAUSE THE FREE PLAN LIMIT WAS REACHED. BUT READ THIS AND LEARN WHAT YOU CAN ABOUT IT. THEN IMPLEMENT SOME FIXES ETC AFTER VALIDATING THE ISSUE.



Now I have a thorough picture of the entire codebase. Let me compile my findings.---

Here's a thorough analysis of the project with agent instructions ready for use.

---

## Project Health Summary

**On track**: The project is genuinely following its plan. Milestones 1–5 are complete. Milestone 6 is partially done. Architecture, data shapes, CLI surface, IPC protocol, and adapter trait are all correctly implemented. The `node-compile-cache/` and `phantomjs/` directories in the archive are clearly accidental inclusions from the working directory — they should not be in the repo.

---

## Agent Instructions

```
You are working on the `tvctl` Rust project. Read PROJECT_MAP.md first.
Do NOT rewrite files wholesale. Make targeted, surgical changes only.
Do NOT touch anything not explicitly listed below.
Run `cargo clippy` and `cargo test` after each change and fix any new warnings before moving on.

---

### 1. CRITICAL BUG — `format_tv_key` duplicates `parse_normalized_tv_key` in reverse

File: `src/daemon/mod.rs`, function `format_tv_key`

This function is a full 33-arm hand-written match over `TvKey` that returns the kebab-case string for each key.
The `TvKey` enum in `src/adapters/mod.rs` is already decorated with `#[serde(rename_all = "kebab-case")]`.

`format_tv_key` can never drift from the parse table without silently producing wrong values. It is
duplication by definition and contains a latent inconsistency: if a new `TvKey` variant is added, it
must be added in three places (the enum, `parse_normalized_tv_key`, AND `format_tv_key`) with no
compiler enforcement that the last one is updated.

**Fix**: Delete `format_tv_key` and replace its single call site with a serde round-trip:

```rust
// In place of: format_tv_key(&key)
// Use:
serde_json::to_value(&key)
    .ok()
    .and_then(|v| v.as_str().map(str::to_string))
    .unwrap_or_else(|| format!("{key:?}"))
```

Or, alternatively, implement `std::fmt::Display` for `TvKey` in `src/adapters/mod.rs` using serde's
rename logic, and use that in the call site. Either approach eliminates the duplicate table.

---

### 2. BUG — `DeviceRegistry::remove` duplicates the match logic of `DeviceRegistry::find`

File: `src/daemon/registry.rs`

`find` uses an inline closure:
```rust
self.devices.iter().find(|device| {
    target_uuid.map(|uuid| device.id == uuid).unwrap_or(false)
        || device.name.to_ascii_lowercase() == normalized
})
```

`remove` uses a separate private `matches_target` free function with identical logic.

These two code paths will diverge if the matching rules ever change (e.g., adding prefix-match support).

**Fix**: Refactor `remove` to use `find` to locate the index first:

```rust
pub fn remove(&mut self, target: &str) -> Option<Device> {
    let id = self.find(target)?.id;
    let index = self.devices.iter().position(|d| d.id == id)?;
    let removed = self.devices.remove(index);
    self.ensure_default();
    Some(removed)
}
```

Then delete the `matches_target` free function entirely.

---

### 3. BUG — `parse_bool` is a useless wrapper in `src/daemon/config.rs`

File: `src/daemon/config.rs`, lines ~300–303

```rust
fn parse_bool(key: &str, value: &str) -> anyhow::Result<bool> {
    parse_value(key, value)
}
```

This is a zero-value indirection. `parse_value::<bool>` already exists and already handles `bool`.
`parse_bool` exists solely because someone called it before `parse_value` was made generic.

**Fix**: Delete `parse_bool`. Replace the three call sites with `parse_value::<bool>(key, value)?`
(or just `parse_value(key, value)?` — Rust will infer the type from the assignment target).

---

### 4. ARCHITECTURE CONCERN — HTTP API routes through the Unix socket unnecessarily

File: `src/api/mod.rs`, function `send_daemon_request`

The HTTP API runs *inside the same process as the daemon*. It already holds `SharedDaemon: Arc<Mutex<Daemon>>`.
Despite this, every HTTP handler opens a new Unix socket connection back to the daemon, serializes
the request to JSON, sends it over the socket, and deserializes the response back. This is:
- An unnecessary round-trip through the OS socket layer
- A source of failure (`daemon_socket_unreachable`) for requests that should never fail
- A potential deadlock: the HTTP handler acquires the Mutex briefly to get the socket path, releases it,
  then the request comes back in on a socket connection and tries to acquire the Mutex in `execute_request`.
  This works today because `handle_connection` holds no lock, but it is a footgun as the code evolves.

The daemon already exposes `pub(crate) async fn execute_request(request: DaemonRequest, daemon: SharedDaemon)`.

**Fix**: Replace `send_daemon_request` in the HTTP API with a direct call to `daemon::execute_request`.
The refactor is mechanical:

```rust
// In execute_json and execute_json_value, instead of:
match send_daemon_request(daemon, &request).await { ... }

// Use:
let (response, _stop) = daemon::execute_request(request, daemon).await;
from_daemon_response::<T>(response)
```

Then delete `send_daemon_request` entirely. This eliminates ~60 lines of socket boilerplate from the
HTTP path, removes a class of failure modes, and eliminates the latent deadlock risk.

---

### 5. DOCUMENTATION STALENESS — PROJECT_MAP.md out of date

File: `PROJECT_MAP.md`

The "What Has NOT Been Started" section still says:
```
- HTTP route handlers and request validation
```

This was completed in Milestone 5. Update that section to reflect the current state (Milestone 6 in
progress, remaining items are tracing log output, systemd unit generation, CI, cross-compile test,
and first binary release).

Also update the `## Project Status` block:
- Change "Phase: Milestone 5 in progress" to "Phase: Milestone 6 in progress"
- Update the description to reflect that the HTTP API is complete

---

### 6. CLEANUP — Accidental files in the archive / repo

The project archive contains two directories that must not be in the repo:
- `node-compile-cache/` — Node.js V8 bytecode cache, clearly from the developer's working environment
- `phantomjs/` — A 23 MB PhantomJS binary distribution

Neither is referenced by the Rust project in any way. Confirm these are excluded in `.gitignore` and
remove them from any committed state if they were accidentally committed. The `.gitignore` should
include at minimum:
```
node-compile-cache/
phantomjs/
```

---

### 7. MINOR — `get_value` allocates a full BTreeMap to look up one key

File: `src/daemon/config.rs`, `get_value` method

```rust
pub fn get_value(&self, key: &str) -> Option<String> {
    self.entries().remove(key)  // allocates entire map just to look up one key
}
```

This allocates and populates a full `BTreeMap` (15 entries) just to retrieve one value.

**Fix**: Inline the lookup directly in `get_value` using a `match` on the key, identical to the
pattern already used in `set_value`. This is a micro-optimization but it also eliminates the
inconsistency where `entries()` and `set_value` are two separate parallel tables that must stay in
sync. Alternatively, make `set_value` call `entries()` for validation but that's heavier. The
simplest correct fix is to re-express `get_value` as a `match` block mirroring `set_value`.

---

### 8. MINOR — `roku_key_paths` uses mixed return styles

File: `src/adapters/roku/mod.rs`, function `roku_key_paths`

The function has two code paths:
1. The first ~25 arms `return Ok(vec!["SomeKey".to_string()])` inline
2. The last 5 arms fall through to a `let path = match { "some-string" }` followed by
   `Err(TvError::InvalidKey(path.to_string()))`

This is intentional (the last 5 keys have no known Roku mapping), but the pattern is confusing:
those 5 arms look like they map to valid paths but actually the entire bottom branch returns `Err`.

**Fix**: Consolidate to make the intent obvious. The simplest approach: keep the two-style structure
but add a comment before the fall-through block making it explicit that these keys are
**intentionally unsupported** and the string values are used only for the error message:

```rust
// The following keys have no documented Roku ECP equivalent.
// The string values are used only to populate the InvalidKey error.
TvKey::Stop => "stop",
TvKey::Skip => "skip",
TvKey::Power => "power",
TvKey::PowerOn => "power-on",
TvKey::Options => "options",
```

No logic change required — just a documentation fix to prevent future maintainers from trying to
"fix" this by making it return Ok.

---

### 9. MINOR — `RefreshAppsBody` optional body field can use `unwrap_or_default`

File: `src/api/mod.rs`

```rust
clear: body.map(|value| value.clear).unwrap_or(false),
```

`bool` implements `Default` (defaults to `false`), so this can be simplified to:
```rust
clear: body.map_or(false, |value| value.clear),
```

Or better: make `clear` default-able in the body by giving it `#[serde(default)]` (it already has
that) and unwrap the optional body using `unwrap_or_default()` on the struct. Either is fine.
This is cosmetic.

---

### 10. NOTE — `edition = "2024"` in Cargo.toml

File: `Cargo.toml`

The crate uses `edition = "2024"`. Rust 2024 edition stabilized in Rust 1.85 (Feb 2025).
This is fine and intentional, but it explains the `if clear && let Err(...)` syntax in `daemon/mod.rs`
which is a 2024-edition `let chains` feature. No change needed — just confirm the CI target
(when it lands) pins to `rustup toolchain` >= 1.85.
```



Let me check the remaining files I haven't read yet — the CLI's full body and the cache/state files.Good — now I have seen everything. Let me produce the complete, final agent instructions.Now I have a complete picture. Here are the full, final agent instructions:

---

## Complete Agent Instructions for tvctl

```
You are working on the `tvctl` Rust project. Read PROJECT_MAP.md and ROADMAP.md first.
Do NOT rewrite files wholesale. Make targeted, surgical str_replace changes only.
Do NOT touch any code not explicitly listed in the tasks below.
After all changes, run `cargo clippy` and `cargo test` and fix any new warnings before finishing.

---

## VERIFIED PROJECT STATUS

Milestones 1–5 are complete. Milestone 6 is partially done. The following Milestone 6 items
remain open per ROADMAP.md:
- `tvctl daemon install` generating a correct systemd unit ← DONE (render_systemd_unit exists)
- Log output via `tracing` (respects `log_level` config) ← STILL OPEN
- Cross-compile test ← STILL OPEN
- GitHub Actions CI ← STILL OPEN
- First binary release ← STILL OPEN

**The PROJECT_MAP.md is stale.** Update it as part of these tasks (see Task 9).

---

## TASK 1 — CRITICAL BUG: Eliminate `format_tv_key` — it is a duplicate of `parse_normalized_tv_key` in reverse

**File:** `src/daemon/mod.rs`

`format_tv_key` is a 33-arm match over `TvKey` that reconstructs the kebab-case name for each key.
`TvKey` is already decorated with `#[serde(rename_all = "kebab-case")]`, so serde already owns
this mapping. `format_tv_key` will silently drift if any variant is added or renamed. There is no
compiler enforcement.

**Step 1:** In `src/adapters/mod.rs`, implement `std::fmt::Display` for `TvKey` using serde's
rename output as the source of truth:

```rust
impl std::fmt::Display for TvKey {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // Delegate to serde's kebab-case serialization so the display name
        // is always consistent with what the CLI and API accept as input.
        let name = serde_json::to_value(self)
            .ok()
            .and_then(|v| v.as_str().map(str::to_string))
            .unwrap_or_else(|| format!("{self:?}"));
        f.write_str(&name)
    }
}
```

Place this impl block directly after the `TvKey` enum definition.

**Step 2:** In `src/daemon/mod.rs`, find the single call site of `format_tv_key`:

```rust
let detail = format!("Sent key '{}' to {}.", format_tv_key(&key), device.name);
```

Replace it with:

```rust
let detail = format!("Sent key '{key}' to {}.", device.name);
```

(This works because `TvKey` now implements `Display`.)

**Step 3:** Delete the entire `format_tv_key` function from `src/daemon/mod.rs`.

---

## TASK 2 — BUG: `DeviceRegistry::remove` duplicates the match logic of `DeviceRegistry::find`

**File:** `src/daemon/registry.rs`

`find` (line ~84) and `matches_target` (line ~322) contain identical UUID + case-insensitive name
matching logic. They will silently diverge if matching rules change.

**Step 1:** Replace the body of `remove` so it delegates to `find`:

Current:
```rust
pub fn remove(&mut self, target: &str) -> Option<Device> {
    let index = self
        .devices
        .iter()
        .position(|device| matches_target(device, target))?;
    let removed = self.devices.remove(index);
    self.ensure_default();
    Some(removed)
}
```

Replace with:
```rust
pub fn remove(&mut self, target: &str) -> Option<Device> {
    let id = self.find(target)?.id;
    let index = self.devices.iter().position(|d| d.id == id)?;
    let removed = self.devices.remove(index);
    self.ensure_default();
    Some(removed)
}
```

**Step 2:** Delete the `matches_target` free function at the bottom of the file entirely.

---

## TASK 3 — BUG: `parse_bool` is a zero-value wrapper

**File:** `src/daemon/config.rs`

```rust
fn parse_bool(key: &str, value: &str) -> anyhow::Result<bool> {
    parse_value(key, value)
}
```

This function does nothing that `parse_value::<bool>` does not already do.

**Step 1:** Delete the `parse_bool` function.

**Step 2:** Replace its three call sites:
- `parse_bool(key, value)?` → `parse_value(key, value)?`

The Rust type inference will resolve `parse_value` to `bool` from the assignment context in each case.
Confirm that `cargo build` passes after this change.

---

## TASK 4 — ARCHITECTURE BUG: HTTP API routes through the Unix socket when it could call directly

**File:** `src/api/mod.rs`

The HTTP API server runs **inside the same process** as the daemon. It holds `SharedDaemon`. Despite
this, every HTTP handler calls `send_daemon_request`, which opens a new Unix socket connection back
to the same daemon process, serializes the request to JSON, sends it over the socket, and deserializes
the response back.

Problems:
1. Unnecessary OS round-trip on every HTTP request.
2. A class of failures (`daemon_socket_unreachable`) that can never legitimately occur for in-process calls.
3. Latent deadlock risk: handler acquires the Mutex to read the socket path, releases it, then the
   request re-enters via the socket handler and tries to acquire the Mutex again. Works today only
   because `handle_connection` holds no lock during execution, but this is not enforced.

`daemon::execute_request` is already `pub(crate)` and accepts `(DaemonRequest, SharedDaemon)`.

**Step 1:** Replace the two implementations of `execute_json` and `execute_json_value` with versions
that call `daemon::execute_request` directly:

```rust
async fn execute_json<T>(daemon: SharedDaemon, request: DaemonRequest) -> Response
where
    T: Serialize + DeserializeOwned,
{
    let (response, _) = crate::daemon::execute_request(request, daemon).await;
    from_daemon_response::<T>(response)
}

async fn execute_json_value(daemon: SharedDaemon, request: DaemonRequest) -> Response {
    let (response, _) = crate::daemon::execute_request(request, daemon).await;
    from_daemon_response::<Value>(response)
}
```

**Step 2:** Delete the entire `send_daemon_request` async function (~65 lines).

**Step 3:** Remove the now-unused imports from `src/api/mod.rs`:
- `tokio::io::{AsyncReadExt, AsyncWriteExt}`
- `tokio::net::UnixStream`

Confirm `cargo build` passes after this change.

---

## TASK 5 — BUG: `PowerState` rendered with `{:?}` in human-readable output

**File:** `src/cli/mod.rs`, function `render_state`

```rust
format!("Power: {:?}", state.power),
```

`{:?}` prints `On`, `Off`, or `Unknown` (Rust variant names). This is fine but inconsistent with
the rest of the output, which is lowercase prose. Worse, it will break if `PowerState` is ever
renamed or repr-changed.

`PowerState` is already `#[serde(rename_all = "snake_case")]`, so it serializes to `"on"`, `"off"`,
`"unknown"`.

**Fix:** Implement `std::fmt::Display` for `PowerState` in `src/adapters/mod.rs`, mirroring the
serde rename:

```rust
impl std::fmt::Display for PowerState {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            PowerState::On => f.write_str("on"),
            PowerState::Off => f.write_str("off"),
            PowerState::Unknown => f.write_str("unknown"),
        }
    }
}
```

Then in `render_state`, change:
```rust
format!("Power: {:?}", state.power),
```
to:
```rust
format!("Power: {}", state.power),
```

---

## TASK 6 — BUG: Secret redaction logic is duplicated across three locations

**Files:** `src/cli/mod.rs`, `src/api/mod.rs`

The password redaction pattern appears in three places:

1. `src/cli/mod.rs` — `redact_config_value` (checks `is_secret_config_key`) — used in `config list`
   and `config get`
2. `src/cli/mod.rs` — `sanitize_config_reload_result` (manually mutates `roku_password`) — used in
   `config reload`
3. `src/api/mod.rs` — `get_config` (manually mutates `roku_password`) — used in `GET /v1/config`

These three will drift if new secret keys are added to the config.

**Fix:**

**Step 1:** Add a `redact_secrets` method to `TvctlConfig` in `src/daemon/config.rs`:

```rust
impl TvctlConfig {
    /// Return a copy of this config with sensitive fields replaced by "<redacted>".
    pub fn redacted(&self) -> Self {
        let mut copy = self.clone();
        if !copy.dev.roku_password.is_empty() {
            copy.dev.roku_password = "<redacted>".to_string();
        }
        copy
    }
}
```

**Step 2:** In `src/api/mod.rs`, replace the manual redaction in `get_config`:

Current:
```rust
Ok(mut config) => {
    if !config.dev.roku_password.is_empty() {
        config.dev.roku_password = "<redacted>".to_string();
    }
    api_success(StatusCode::OK, config)
}
```
Replace with:
```rust
Ok(config) => api_success(StatusCode::OK, config.redacted()),
```

**Step 3:** In `src/cli/mod.rs`, replace `sanitize_config_reload_result`:

Current:
```rust
fn sanitize_config_reload_result(mut result: ConfigReloadResult) -> ConfigReloadResult {
    if !result.config.dev.roku_password.is_empty() {
        result.config.dev.roku_password = "<redacted>".to_string();
    }
    result
}
```
Replace with:
```rust
fn sanitize_config_reload_result(mut result: ConfigReloadResult) -> ConfigReloadResult {
    result.config = result.config.redacted();
    result
}
```

The existing `redact_config_value` / `is_secret_config_key` pair in the CLI can remain as-is for now
since it serves a different path (key-by-key display), but the two manual inline redactions are gone.

---

## TASK 7 — MINOR: `get_value` allocates a full BTreeMap to look up one key

**File:** `src/daemon/config.rs`

```rust
pub fn get_value(&self, key: &str) -> Option<String> {
    self.entries().remove(key)
}
```

This allocates and populates a 15-entry `BTreeMap` to look up a single value. `set_value` already
has a `match` on the key — the same pattern should be used here.

**Fix:** Replace `get_value` with a match block that mirrors the structure of `set_value`:

```rust
pub fn get_value(&self, key: &str) -> Option<String> {
    match key {
        "daemon.socket" => Some(self.daemon.socket.clone()),
        "daemon.http_enabled" => Some(self.daemon.http_enabled.to_string()),
        "daemon.http_port" => Some(self.daemon.http_port.to_string()),
        "daemon.http_host" => Some(self.daemon.http_host.clone()),
        "daemon.log_level" => Some(self.daemon.log_level.clone()),
        "discovery.auto_discover" => Some(self.discovery.auto_discover.to_string()),
        "discovery.interval_secs" => Some(self.discovery.interval_secs.to_string()),
        "discovery.timeout_secs" => Some(self.discovery.timeout_secs.to_string()),
        "devices.default" => Some(self.devices.default.clone()),
        "remote.roku_key_mode" => Some(self.remote.roku_key_mode.clone()),
        "remote.roku_press_duration_ms" => Some(self.remote.roku_press_duration_ms.to_string()),
        "dev.enabled" => Some(self.dev.enabled.to_string()),
        "dev.roku_username" => Some(self.dev.roku_username.clone()),
        "dev.roku_password" => Some(self.dev.roku_password.clone()),
        _ => None,
    }
}
```

This eliminates the allocation and keeps `get_value` and `set_value` as a symmetric pair that the
compiler will force you to update together.

---

## TASK 8 — MINOR: `roku_key_paths` unsupported-key arms need a clarifying comment

**File:** `src/adapters/roku/mod.rs`, function `roku_key_paths`

The first ~25 arms of `roku_key_paths` `return Ok(vec!["..."])`. The last 5 arms fall through to
`let path = match { ... }` followed by `Err(TvError::InvalidKey(...))`. This is intentional but
looks like the strings in the last 5 arms are ECP key paths when they are actually just error
message content.

**Fix:** Add a comment before the fall-through block, no logic change:

Find this section in `roku_key_paths`:
```rust
        TvKey::Stop => "stop",
        TvKey::Skip => "skip",
        TvKey::Power => "power",
        TvKey::PowerOn => "power-on",
        TvKey::Options => "options",
    };

    Err(TvError::InvalidKey(path.to_string()))
```

Replace with:
```rust
        // The following keys have no documented Roku ECP equivalent.
        // These strings populate the InvalidKey error message only — they are NOT ECP paths.
        TvKey::Stop => "stop",
        TvKey::Skip => "skip",
        TvKey::Power => "power",
        TvKey::PowerOn => "power-on",
        TvKey::Options => "options",
    };

    Err(TvError::InvalidKey(path.to_string()))
```

---

## TASK 9 — Update PROJECT_MAP.md and clean up the archive

**Step 1:** In `PROJECT_MAP.md`:

Under `## Project Status`, change:
```
**Phase:** Milestone 5 in progress. ...
```
to:
```
**Phase:** Milestone 6 in progress. Milestones 1–5 are complete. The HTTP API is live. Remaining
Milestone 6 work: tracing log level enforcement, cross-compile test, GitHub Actions CI, and first
binary release.
**Platform v1:** Roku only (via ECP HTTP API)
**Language:** Rust
**Crate type:** Binary (single binary distribution target)
```

Under `## What Has NOT Been Started`, remove the line:
```
- HTTP route handlers and request validation
```
Replace the entire section with what actually remains:
```
## What Has NOT Been Started

- Log level enforcement via `tracing` (config key `daemon.log_level` is parsed but the subscriber
  filter is not updated at runtime after config reload)
- CI/CD configuration (GitHub Actions)
- Cross-compile targets (x86_64 + aarch64)
- First binary release
```

**Step 2:** Confirm that `node-compile-cache/` and `phantomjs/` are listed in `.gitignore`.
If `.gitignore` does not exist, create it at the project root with at minimum:
```
/target
node-compile-cache/
phantomjs/
*.lock
```
Do not add `Cargo.lock` to gitignore (binary crates should commit their lockfile).
The correct ignore for Cargo lockfile in a binary crate is to NOT ignore it. Keep `Cargo.lock` tracked.

---

## TASK 10 — NOTE: `AppInfo.id` and `AppInfo.platform_id` are always identical for Roku (no fix needed, but document)

In `src/adapters/roku/mod.rs`, every `AppInfo` constructed in `parse_apps` and `parse_active_app`
sets both `id` and `platform_id` to the same value:

```rust
AppInfo {
    id: platform_id.to_string(),
    name: name.to_string(),
    version: ...,
    platform_id: platform_id.to_string(),
}
```

The design intent (per `src/adapters/mod.rs` comments) is that `id` is a "tvctl-normalized app
identifier" and `platform_id` is the "raw platform-specific app identifier." For Roku these are
the same. For a future platform (e.g., Google TV via ADB) they could differ.

**No code change needed.** Add a comment in the Roku `parse_apps` function to document the intent:

```rust
Some(AppInfo {
    // For Roku, the tvctl-normalized id and the raw ECP channel id are the same value.
    // Future platforms may produce different normalized and platform-specific identifiers.
    id: platform_id.to_string(),
    name: name.to_string(),
    version: node.attribute("version").map(ToString::to_string),
    platform_id: platform_id.to_string(),
})
```

Apply the same comment in `parse_active_app`.

---

## VERIFICATION CHECKLIST

After completing all tasks:
1. `cargo build` — must produce zero errors
2. `cargo clippy -- -D warnings` — must produce zero warnings  
3. `cargo test` — all tests must pass
4. Manually verify that Task 4 (API direct call) did not break the HTTP integration path by
   confirming `execute_request` in `daemon/mod.rs` is `pub(crate)` (it already is)
5. Verify PROJECT_MAP.md and ROADMAP.md are consistent with each other after Task 9 edits
```