44r0n7/tvctl
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
45620b1ab51bec24299a20ee05ef1737d60cfe79
tvctl/ROADMAP.md
T
44r0n7 45620b1ab5 refactor: clean up daemon and CLI duplication 
Reduce repeated adapter dispatch, CLI action rendering, and config save
flows while keeping the current Roku behavior and docs aligned with the
known secret-menu limitations.
2026-04-15 15:25:49 -04:00

7.8 KiB
Raw Blame History

ROADMAP.md

tvctl — Feature Roadmap and Milestone Tracker

Agents: update this file as work is completed. See AGENT.md for instructions.

Last updated: 2026-04-14

Current Focus

Milestone 5 — HTTP API CLI coverage is complete. Begin exposing the same surface over loopback HTTP.

In Progress

  • Milestone 5 has not started yet; CLI validation and polish are complete enough to move on

Milestone 1 — Project Foundation

Goal: A compiling Rust project with correct structure and no logic yet.

Completed 2026-04-14. See Completed below.

Milestone 2 — Roku Adapter

Goal: Can communicate with a real Roku TV over ECP.

  • 2026-04-14 — Implement core Roku ECP adapter in src/adapters/roku/
  • 2026-04-14 — discover() — SSDP scan returning Roku devices
  • 2026-04-14 — list_apps() — fetch installed channel list via ECP
  • 2026-04-14 — launch() — launch app by ECP channel ID
  • 2026-04-14 — stop_app() — exit current app
  • 2026-04-14 — key() — send ECP keypress
  • 2026-04-14 — sequence() — send multiple keypresses
  • 2026-04-14 — state() — query power state and active app
  • 2026-04-14 — dev_install() — zip upload via ECP developer web installer with Digest auth
  • 2026-04-14 — dev_reload() — reload the sideloaded app via launch/dev
  • 2026-04-14 — dev_logs() — fetch BrightScript debugger output from the live dev socket
  • 2026-04-14 — Key translation table (TvKey → Roku ECP key string)
  • 2026-04-14 — Automated live validation against 58" Hisense Roku TV at 10.10.0.136

Milestone 3 — Daemon Core

Goal: tvctld runs, manages devices, and handles the Unix socket.

  • 2026-04-14 — Daemon entry point and lifecycle (src/daemon/mod.rs)
  • 2026-04-14 — Unix socket listener
  • 2026-04-14 — Device registry (src/daemon/registry.rs)
    • Load from devices.json on start
    • Persist on change
    • CRUD operations
  • 2026-04-14 — Discovery service (src/daemon/discovery.rs)
    • SSDP scan
    • Auto-discover on startup (if configured)
    • Interval-based re-scan
    • Manual add by IP
  • 2026-04-14 — App cache manager (src/daemon/cache.rs)
    • Per-platform JSON files
    • Organic growth strategy
    • app refresh invalidation
  • 2026-04-14 — State cache (src/daemon/state.rs)
    • In-memory only
    • Per-device last-known state
    • Timestamp on every entry
  • 2026-04-14 — Adapter registry (map platform string → adapter instance)
  • 2026-04-14 — Config loading from TOML

Milestone 4 — CLI

Goal: All tvctl commands work against a running daemon.

  • 2026-04-14 — CLI entry point and dispatch (src/cli/mod.rs)
  • 2026-04-14 — Unix socket client (send commands, receive responses)
  • 2026-04-14 tvctl daemon commands
    • start stop restart status
    • install (generate systemd user unit)
    • uninstall
  • 2026-04-14 tvctl device commands
    • list discover add select info remove
  • tvctl app commands
    • 2026-04-14 list launch stop refresh
  • tvctl remote commands
    • 2026-04-14 key sequence
  • 2026-04-14 tvctl state
  • 2026-04-14 tvctl dev commands
    • install reload logs
  • 2026-04-14 tvctl config commands
    • list get set reset reload
  • 2026-04-14 Global flags: --device --json --help --version
  • 2026-04-14 Full help text on every command (see AGENT.md definition of done)
  • 2026-04-14 Full help output on bare tvctl
  • 2026-04-14 Friendly error messages with hints on every failure path
  • 2026-04-14 --json output verified on every command

Milestone 5 — HTTP API

Goal: Full /v1/ API running on 127.0.0.1:7272.

  • axum server setup in src/api/mod.rs
  • All routes implemented (see PROJECT_MAP.md API surface)
  • Standard response envelope on all routes
  • Error responses with code + message + hint
  • Device addressable by UUID or friendly name on all routes
  • PATCH /v1/config with partial update support
  • POST /v1/config/reload triggers live config reload in daemon
  • Integration test: curl all endpoints against running daemon

Milestone 6 — Polish and Release Prep

Goal: Ready for real use.

  • Shell completions (bash, zsh, fish) via clap
  • tvctl daemon install generates correct systemd unit file
  • First-run experience: helpful output when no devices discovered yet
  • Daemon startup message with socket path and HTTP port
  • Log output via tracing (respects log_level config)
  • README accuracy pass (verify all examples work)
  • cargo clippy clean
  • cargo test passing
  • Cross-compile test (x86_64 + aarch64)
  • GitHub Actions CI (build + clippy + test)
  • First binary release

Post-MVP (Do Not Implement in v1)

These are captured here so they are not forgotten, but they are explicitly out of scope until Milestone 6 is complete and stable.

  • Google TV / Android TV adapter (ADB)
  • Fire TV adapter (ADB variant)
  • WebSocket live state updates
  • Event watching / triggers
  • Device groups (send command to multiple TVs)
  • Automation rules engine
  • Home Assistant integration
  • Web UI (consumes HTTP API, no business logic)
  • tvctl dev logs streaming (currently returns last N lines only)
  • macOS support (launchd instead of systemd)

Completed

  • 2026-04-14 — Initialize Cargo workspace (cargo init)
  • 2026-04-14 — Add baseline dependencies to Cargo.toml
  • 2026-04-14 — Create module skeleton and placeholder docs layout
  • 2026-04-14 — Define the adapter contract and core shared data types
  • 2026-04-14 — Compile the project cleanly with cargo build
  • 2026-04-14 — Add Roku ECP discovery, input, app, and state adapter support with unit tests
  • 2026-04-14 — Add env-gated live Roku integration tests and validate against the Hisense TV on the LAN
  • 2026-04-14 — Implement Roku developer-mode install/log support and validate sideloading on the Hisense TV
  • 2026-04-14 — Add daemon config loading, runtime paths, persisted registry/cache stores, and discovery foundations
  • 2026-04-14 — Add daemon Unix socket IPC plus working daemon and device lifecycle/discovery commands
  • 2026-04-14 — Finish Milestone 3 with registry CRUD, periodic discovery, manual add, and app-cache refresh plus live daemon validation
  • 2026-04-14 — Add daemon-backed app control, remote input, state queries, and dev workflows with live Roku CLI validation
  • 2026-04-14 — Add config list/get/set/reset/reload plus systemd user-service install/uninstall commands
  • 2026-04-14 — Finish Milestone 4 with help, JSON-mode, config socket-reload, and secret-redaction polish

Decision Log

Significant decisions made during development should be logged here so future agents understand why things are the way they are.

Date Decision Reason
2026-04-14 Full design completed before any code written Intentional — design-first approach
2026-04-14 Samsung deprioritized Unstable app IDs per region/model make universal support unreliable
2026-04-14 No pre-populated app database Organic cache from live TV data is more accurate and zero-maintenance
2026-04-14 Unix socket for CLI, HTTP for tool builders Clean security boundary, loopback-only by default
2026-04-14 User-level systemd service No root required, correct ownership model
2026-04-15 Future remote input options should use a generalized adapter capability model If multiple adapters need press/release or other delivery semantics, model it as adapter capabilities instead of hard-coding Roku-only behavior
Reference in New Issue View Git Blame Copy Permalink