feat: finalize HTTP direct dispatch refactor and pending milestone updates

Switch API execution to direct daemon request handling, add regression coverage for non-socket HTTP dispatch, and include the remaining pending local updates across CLI/daemon/docs from the current worktree.
2026-04-18 11:42:10 -04:00
parent 26cc0c973a
commit 274844b558
14 changed files with 1131 additions and 108 deletions
@@ -0,0 +1,716 @@
+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
+```