roku_control.py

#!/usr/bin/env python3
import sys
import os
import time
import json
import re
import socket
import subprocess
import xml.etree.ElementTree as ET
import difflib
import copy
import random
from pathlib import Path
from urllib.parse import quote
from datetime import datetime

import requests

if __name__ == "__main__" and not __file__:
    raise SystemExit("roku_control.py loaded without a file path")

# ------------------------------------------------------
# Subcommand: `roku remote` -> open curses TUI remote
# ------------------------------------------------------
if len(sys.argv) > 1 and sys.argv[1] in ("remote", "tui"):
    import os as _os
    import sys as _sys
    import subprocess as _subprocess

    root = _os.path.dirname(_os.path.realpath(__file__))
    env = dict(_os.environ)
    env["PYTHONPATH"] = root + (_os.pathsep + env["PYTHONPATH"] if env.get("PYTHONPATH") else "")

    raise SystemExit(_subprocess.call([_sys.executable, "-m", "roku_remote_tui"], cwd=root, env=env))

# ======================================================
# Roku Control (expanded)
# - Safe defaults: no lights, no auto wake, no daemon loops
# - Shorthand: unknown command => launch target
# - Config, cache, state, macros, discovery, follow mode
# ======================================================

# ------------------------------------------------------
# Defaults (used if config not found)
# ------------------------------------------------------
DEFAULT_CONFIG = {

    "default_device": "livingroom",
    "devices": {
        "livingroom": {
            "ip": "192.168.86.25",
            "port": 8060,
            "timeout": 3.0,
            "rate_delay": 0.15,
        }
    },
    "behavior": {
        "default_wake": False,
        "default_lights": False,
        "assume_input_switch_success": True,
        "apps_cache_ttl_seconds": 6 * 60 * 60,
        "max_state_actions": 50,
        "max_state_errors": 50,
        "max_vol_presses_per_command": 12,
        "max_volume_set_target": 12,
        "volume_chunk": 2,
        "volume_chunk_pause": 1.75,
        "volume_chunk_pause_up": 3.75,
        "volume_chunk_pause_down": 1.75,
        "volume_jitter_min": 0.0,
        "volume_jitter_max": 0.0,

        "nav_jitter_min": 0.0,
        "nav_jitter_max": 0.0,

        "type_char_delay": 0.06,
        "type_jitter_min": 0.0,
        "type_jitter_max": 0.0,

        # Minimum time between consecutive volume presses (seconds).
        # Helps prevent the TV from "jumping" when multiple presses happen fast.
        "volume_press_gap": 0.28,        # fallback for both directions
        "volume_up_press_gap": 0.28,     # optional override
        "volume_down_press_gap": 0.28,   # optional override

        # Zero-out preferences
        # If set (>0), vol zero holds VolumeDown for this many ms.
        # If not set, falls back to repeated VolumeDown presses (zero_out_down_presses).
        "zero_out_hold_ms": 1600,
        "zero_out_down_presses": 8,
    },
    "aliases": {
        "switch": "nintendo switch",
        "console": "nintendo switch",
        "pc": "computer",
        "computer": "computer",
        "tv": "live tv",
        "live": "live tv",
        "audio": "soundbar",
        "pluto": "pluto tv - free movies/shows",
        "pluto_tv": "pluto tv - free movies/shows",
        "plutotv": "pluto tv - free movies/shows",
    },
    "failback_inputs": {
        "nintendo switch": ["nintendo switch", "computer", "live tv"],
        "computer": ["computer", "live tv"],
    },
    "light_scenes": {
        "netflix": ["cozy"],
        "youtube": ["cozy"],
        "nintendo switch": ["cozy"],
        "computer": ["cozy"],
        "live tv": ["off"],
    },
    "lights": {
        "bin": "/home/pi/projects/wiz_lights/lights.py",
    },
    "follow": {
        "poll_seconds": 2.0,
        "min_seconds_between_light_changes": 6.0,
        "ignore_apps": ["roku", "screensaver"],
    },
    "macros": {
        "movie": {
            "steps": [
                {"action": "assert_or_wake_power_on"},
                {"action": "launch", "target": "netflix"},
                {"action": "scene_for", "target": "netflix", "requires_lights": True},
            ]
        },
        "console": {
            "steps": [
                {"action": "assert_or_wake_power_on"},
                {"action": "launch", "target": "nintendo switch"},
                {"action": "scene_for", "target": "nintendo switch", "requires_lights": True},
            ]
        },
        "work": {
            "steps": [
                {"action": "ensure_power_on", "wait": 2.5},
                {"action": "lights", "mode": "embers"},
                {"action": "launch", "target": "pluto"},
                {"action": "vol_hold", "dir": "down", "ms": 1600},
                {"action": "vol_up", "n": 1},
            ]
        },
        "shutdown": {
            "steps": [
                {"action": "lights", "mode": "off"},
                {"action": "key", "key": "Power"},
            ]
        },
        "vol_normalize_night": {
            "steps": [
                {"action": "vol_down", "n": 20},
                {"action": "vol_up", "n": 4},
            ]
        },
        "vol_normalize_day": {
            "steps": [
                {"action": "vol_down", "n": 20},
                {"action": "vol_up", "n": 8},
            ]
        },
    },
}

# ------------------------------------------------------
# Paths
# ------------------------------------------------------
CONFIG_PATH = Path.home() / ".config" / "roku_control" / "config.json"
CACHE_DIR = Path.home() / ".cache" / "roku_control"
STATE_PATH = Path.home() / ".local" / "state" / "roku_control" / "state.json"
FOLLOW_PID_PATH = Path.home() / ".local" / "state" / "roku_control" / "follow.pid"

# ------------------------------------------------------
# Commands
# ------------------------------------------------------
KNOWN_COMMANDS = {
    "status", "diag", "ping",
    "apps", "list", "cache",
    "launch",
    "power", "home",
    "key", "nav", "ok", "back", "info", "replay", "play", "pause", "fwd", "rev", "mute", "type",
    "keydown", "keyup",
    "vol", "volup", "voldown",
    "movie", "console", "scene", "work", "shutdown",
    "follow",
    "macro",
    "device", "discover",
    "help", "-h", "--help",
    "config",
}

# Key aliases to actual Roku keypress endpoints
KEY_ALIASES = {
    "home": "Home",
    "back": "Back",
    "select": "Select",
    "ok": "Select",
    "up": "Up",
    "down": "Down",
    "left": "Left",
    "right": "Right",
    "replay": "InstantReplay",
    "info": "Info",
    "play": "Play",
    "pause": "Play",
    "fwd": "Fwd",
    "ff": "Fwd",
    "rev": "Rev",
    "rw": "Rev",

    "power": "Power",
    "poweroff": "PowerOff",

    "mute": "VolumeMute",
    "volumemute": "VolumeMute",
    "volumeup": "VolumeUp",
    "volumedown": "VolumeDown",

    "enter": "Enter",
    "search": "Search",
}

# ------------------------------------------------------
# Globals set by CLI flags
# ------------------------------------------------------
G = {
    "device": None,
    "ip": None,
    "port": None,
    "timeout": None,
    "retries": None,
    "rate_delay": None,
    "wake": None,
    "lights": None,
    "no_lights": False,
    "json": False,
    "quiet": False,
    "debug": False,
    "dry_run": False,
}

# ------------------------------------------------------
# Small utils
# ------------------------------------------------------
def now_iso():
    return datetime.now().isoformat(timespec="seconds")

def eprint(msg):
    sys.stderr.write(str(msg) + "\n")

def out(msg):
    if not G["quiet"]:
        print(msg)

def debug(msg):
    if G["debug"] and not G["quiet"]:
        print(msg)

def normalize(s):
    return " ".join(str(s).replace("\xa0", " ").split()).strip()

def safe_int(s, default=None):
    try:
        return int(s)
    except Exception:
        return default

def mkdirp(p: Path):
    p.parent.mkdir(parents=True, exist_ok=True)

def read_json_file(path: Path, default=None):
    try:
        if not path.exists():
            return default
        return json.loads(path.read_text())
    except Exception:
        return default

def write_json_file(path: Path, data):
    mkdirp(path)
    path.write_text(json.dumps(data, indent=2, sort_keys=False) + "\n")

def _pid_alive(pid: int) -> bool:
    try:
        os.kill(int(pid), 0)
        return True
    except Exception:
        return False

def keydown(dev, retries, keyname):
    keyname = normalize(keyname).lower()
    real = KEY_ALIASES.get(keyname, None)

    if real is None:
        real = normalize(keyname)
        real = real[:1].upper() + real[1:]

    if G["dry_run"]:
        out(f"[DRY] keydown {real}")
        return

    http_post(dev, f"/keydown/{real}", retries)

def keyup(dev, retries, keyname):
    keyname = normalize(keyname).lower()
    real = KEY_ALIASES.get(keyname, None)

    if real is None:
        real = normalize(keyname)
        real = real[:1].upper() + real[1:]

    if G["dry_run"]:
        out(f"[DRY] keyup {real}")
        return

    http_post(dev, f"/keyup/{real}", retries)

def hold_key(dev, retries, keyname, ms):
    ms = int(ms)
    if ms < 1:
        ms = 1

    keydown(dev, retries, keyname)
    if G["dry_run"]:
        out(f"[DRY] sleep {ms/1000.0}")
    else:
        time.sleep(ms / 1000.0)
    keyup(dev, retries, keyname)

def type_text(cfg, dev, retries, text):
    if G["dry_run"]:
        out(f"[DRY] type {text}")
        return

    # Behavior source: cfg if provided, else load_config()
    if not isinstance(cfg, dict):
        try:
            cfg = load_config()
        except Exception:
            cfg = {}

    beh = (cfg.get("behavior", {}) or {}) if isinstance(cfg, dict) else {}

    # Base delay between characters (seconds)
    base = beh.get("type_char_delay", beh.get("type_delay", 0.06))
    try:
        base = float(base)
    except Exception:
        base = 0.06
    if base < 0:
        base = 0.0

    # Optional jitter per character (defaults OFF)
    jmin = beh.get("type_jitter_min", 0.0)
    jmax = beh.get("type_jitter_max", 0.0)
    try:
        jmin = float(jmin)
        jmax = float(jmax)
    except Exception:
        jmin = 0.0
        jmax = 0.0

    # Roku ECP: /keypress/Lit_<char> with URL encoding for special characters
    for ch in text:
        encoded = quote(ch, safe="")
        http_post(dev, f"/keypress/Lit_{encoded}", retries)

        _sleep_jitter(base, jmin, jmax)

# ------------------------------------------------------
# Config/state loading
# ------------------------------------------------------
def load_config():
    cfg = copy.deepcopy(DEFAULT_CONFIG)
    on_disk = read_json_file(CONFIG_PATH, default=None)
    if isinstance(on_disk, dict):
        cfg = deep_merge(cfg, on_disk)
    return cfg

def deep_merge(a, b):
    if not isinstance(a, dict) or not isinstance(b, dict):
        return b
    outd = dict(a)
    for k, v in b.items():
        if k in outd and isinstance(outd[k], dict) and isinstance(v, dict):
            outd[k] = deep_merge(outd[k], v)
        else:
            outd[k] = v
    return outd

def load_state(cfg):
    st = read_json_file(STATE_PATH, default=None)
    if not isinstance(st, dict):
        st = {"actions": [], "errors": []}
    st.setdefault("actions", [])
    st.setdefault("errors", [])
    return st

def record_action(cfg, st, action, details=None):
    maxn = cfg["behavior"].get("max_state_actions", 50)
    entry = {"ts": now_iso(), "action": action}
    if details is not None:
        entry["details"] = details
    st["actions"].append(entry)
    st["actions"] = st["actions"][-maxn:]
    write_json_file(STATE_PATH, st)

def record_error(cfg, st, where, msg, details=None):
    maxn = cfg["behavior"].get("max_state_errors", 50)
    entry = {"ts": now_iso(), "where": where, "error": str(msg)}
    if details is not None:
        entry["details"] = details
    st["errors"].append(entry)
    st["errors"] = st["errors"][-maxn:]
    write_json_file(STATE_PATH, st)

# ------------------------------------------------------
# Device selection
# ------------------------------------------------------
def get_device_cfg(cfg):
    dev_name = G["device"] or cfg.get("default_device")
    devs = cfg.get("devices", {})
    dev = devs.get(dev_name)
    if not dev:
        raise RuntimeError(f"Unknown device: {dev_name}")
    ip = G["ip"] or dev.get("ip")
    port = G["port"] or dev.get("port", 8060)
    timeout = G["timeout"] if G["timeout"] is not None else dev.get("timeout", 3.0)
    rate_delay = G["rate_delay"] if G["rate_delay"] is not None else dev.get("rate_delay", 0.15)

    base_url = f"http://{ip}:{port}"
    return {
        "name": dev_name,
        "ip": ip,
        "port": port,
        "timeout": float(timeout),
        "rate_delay": float(rate_delay),
        "base_url": base_url,
    }

# ------------------------------------------------------
# HTTP with retries
# ------------------------------------------------------
def should_retry_exception(ex):
    return isinstance(ex, (requests.exceptions.Timeout, requests.exceptions.ConnectionError, requests.exceptions.RequestException))

def _sleep_rate(dev):
    time.sleep(dev["rate_delay"])

def http_get(dev, path, retries):
    url = dev["base_url"] + path
    last_ex = None
    for attempt in range(retries + 1):
        try:
            debug(f"[HTTP] GET {path} (attempt {attempt+1}/{retries+1})")
            r = requests.get(url, timeout=dev["timeout"])
            if r.status_code >= 500 and attempt < retries:
                time.sleep(0.15 * (attempt + 1))
                continue
            r.raise_for_status()
            return r.text
        except Exception as ex:
            last_ex = ex
            if attempt >= retries or not should_retry_exception(ex):
                raise
            time.sleep(0.15 * (attempt + 1))
    raise last_ex

def http_post(dev, path, retries):
    url = dev["base_url"] + path
    last_ex = None
    for attempt in range(retries + 1):
        try:
            debug(f"[HTTP] POST {path} (attempt {attempt+1}/{retries+1})")
            r = requests.post(url, timeout=dev["timeout"])
            if r.status_code >= 500 and attempt < retries:
                time.sleep(0.15 * (attempt + 1))
                continue
            r.raise_for_status()
            _sleep_rate(dev)
            return
        except Exception as ex:
            last_ex = ex
            if attempt >= retries or not should_retry_exception(ex):
                raise
            time.sleep(0.15 * (attempt + 1))
    raise last_ex

# ------------------------------------------------------
# Roku queries
# ------------------------------------------------------
def query_device_info(dev, retries):
    xml = http_get(dev, "/query/device-info", retries)
    root = ET.fromstring(xml)
    return root

def tv_power_state(dev, retries):
    root = query_device_info(dev, retries)
    return root.findtext("power-mode", "unknown")

def active_app(dev, retries):
    xml = http_get(dev, "/query/active-app", retries)
    root = ET.fromstring(xml)
    app = root.find("app")
    if app is None or app.text is None:
        return "unknown"
    return normalize(app.text.strip().lower())

# ------------------------------------------------------
# Reachability
# ------------------------------------------------------
def socket_ping(ip, port, timeout=1.2):
    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    s.settimeout(timeout)
    try:
        s.connect((ip, int(port)))
        return True, None
    except Exception as ex:
        return False, str(ex)
    finally:
        try:
            s.close()
        except Exception:
            pass

# ------------------------------------------------------
# Apps cache
# ------------------------------------------------------
def cache_path_for(dev_name):
    CACHE_DIR.mkdir(parents=True, exist_ok=True)
    return CACHE_DIR / f"apps_{dev_name}.json"

def load_apps_cached(cfg, dev, retries, refresh=False):
    ttl = cfg["behavior"].get("apps_cache_ttl_seconds", 21600)
    cpath = cache_path_for(dev["name"])
    if not refresh and cpath.exists():
        try:
            blob = json.loads(cpath.read_text())
            ts = blob.get("ts", 0)
            age = time.time() - float(ts)
            if age <= ttl and isinstance(blob.get("apps"), dict):
                return blob["apps"], {"source": "cache", "age_seconds": age, "count": len(blob["apps"])}
        except Exception:
            pass

    apps = fetch_apps(cfg, dev, retries)
    save_apps_cache(dev["name"], apps)
    return apps, {"source": "live", "age_seconds": 0, "count": len(apps)}

def save_apps_cache(dev_name, apps):
    cpath = cache_path_for(dev_name)
    blob = {"ts": time.time(), "apps": apps}
    cpath.write_text(json.dumps(blob, indent=2, sort_keys=False) + "\n")

def fetch_apps(cfg, dev, retries):
    xml = http_get(dev, "/query/apps", retries)
    root = ET.fromstring(xml)
    outd = {}
    for app in root.findall("app"):
        name = normalize((app.text or "").strip()).lower()
        app_id = app.get("id", "")
        if name and app_id:
            outd[name] = app_id
    return outd

# ------------------------------------------------------
# Matching: aliases, exact, partial, fuzzy
# ------------------------------------------------------
def canonical_name(cfg, name):
    name = normalize(name).lower()
    return cfg.get("aliases", {}).get(name, name)

def find_app_match(cfg, apps, raw_name):
    """
    Returns (matched_name, reason, candidates)
    - matched_name: exact app name in `apps` keys, or None
    - reason: string
    - candidates: list of possible matches (for did-you-mean)
    """
    q = canonical_name(cfg, raw_name)
    if q in apps:
        return q, "exact", []

    # partial matches
    partial = [k for k in apps.keys() if q in k]
    if len(partial) == 1:
        return partial[0], "partial", []
    if len(partial) > 1:
        # try "starts with" to narrow
        starts = [k for k in partial if k.startswith(q)]
        if len(starts) == 1:
            return starts[0], "starts_with", []
        candidates = sorted(partial)[:10]
        return None, "ambiguous_partial", candidates

    # fuzzy matches
    close = difflib.get_close_matches(q, list(apps.keys()), n=5, cutoff=0.76)
    if len(close) == 1:
        return close[0], "fuzzy", []
    if len(close) > 1:
        return None, "ambiguous_fuzzy", close

    return None, "not_found", []

# ------------------------------------------------------
# Lights
# ------------------------------------------------------
def lights_allowed(cfg):
    if G["no_lights"]:
        return False
    if G["lights"] is True:
        return True
    if G["lights"] is False:
        return False
    return bool(cfg["behavior"].get("default_lights", False))

def lights_bin(cfg):
    return cfg.get("lights", {}).get("bin", DEFAULT_CONFIG["lights"]["bin"])

def run_lights(cfg, args, quiet=True, force=False):
    # --no-lights blocks everything, even work/shutdown
    if G["no_lights"]:
        return 0

    # Normal behavior: only allowed when --lights (or default_lights=true)
    if not force and not lights_allowed(cfg):
        return 0

    lb = lights_bin(cfg)
    cmd = [lb] + list(args)
    debug(f"[LIGHTS] run: {' '.join(cmd)}")

    if G["dry_run"]:
        out(f"[DRY] lights {' '.join(args)}")
        return 0

    kwargs = {}
    if quiet or G["quiet"]:
        kwargs["stdout"] = subprocess.DEVNULL
        kwargs["stderr"] = subprocess.DEVNULL
    try:
        r = subprocess.run(cmd, **kwargs)
        return r.returncode
    except Exception as ex:
        eprint(f"[LIGHTS] failed: {ex}")
        return 1

def apply_light_scene(cfg, app_name, force=False):
    if not force and not lights_allowed(cfg):
        return
    scene_map = cfg.get("light_scenes", {})
    cmd = scene_map.get(app_name)
    if not cmd:
        out(f"[ROKU] No light scene mapped for: {app_name}")
        return
    out(f"[ROKU] Applying light scene for: {app_name}")
    run_lights(cfg, cmd, quiet=True)

# ------------------------------------------------------
# Wake / assert power
# ------------------------------------------------------
def wake_enabled(cfg):
    if G["wake"] is True:
        return True
    if G["wake"] is False:
        return False
    return bool(cfg["behavior"].get("default_wake", False))

def ensure_or_exit_awake(cfg, dev, retries, context_cmd):
    p = tv_power_state(dev, retries)
    if p == "PowerOn":
        return True
    if wake_enabled(cfg):
        out("[ROKU] TV is off or asleep. Powering on because --wake is enabled.")
        keypress(dev, retries, "Power")
        time.sleep(2.5)
        return True
    if context_cmd == "power":
        return True
    out("[ROKU] TV is off or asleep. Skipping command. Use --wake to power on automatically.")
    return False

def _sleep(seconds: float):
    if seconds <= 0:
        return
    if G["dry_run"]:
        out(f"[DRY] sleep {seconds}")
    else:
        time.sleep(seconds)

def _sleep_jitter(base: float, jmin: float, jmax: float):
    """
    Sleep for base seconds, plus an optional uniform random jitter in [jmin, jmax].
    If jitter is disabled (<=0 or max < min), behaves like a normal base sleep.
    """
    base = float(base or 0.0)
    try:
        jmin = float(jmin or 0.0)
        jmax = float(jmax or 0.0)
    except Exception:
        jmin = 0.0
        jmax = 0.0

    extra = 0.0
    if jmax > 0.0 and jmax >= jmin:
        extra = random.uniform(jmin, jmax)

    _sleep(base + extra)

# ------------------------------------------------------
# Keypress / typing
# ------------------------------------------------------
def keypress(*args, **kwargs):
    """
    Backward compatible keypress.

    Supports BOTH:
      - keypress(dev, retries, keyname, n=1, cfg=None)
      - keypress(cfg, dev, retries, keyname, n=1)

    Disambiguation:
      - If args[0] looks like a Roku dev dict (has base_url), treat as old style.
      - If args[0] looks like a config dict (has behavior/devices) AND args[1] looks like dev dict, treat as new style.
    """
    if len(args) < 3:
        raise TypeError("keypress() missing required arguments")

    def looks_like_dev(x):
        return isinstance(x, dict) and ("base_url" in x or ("ip" in x and "port" in x))

    def looks_like_cfg(x):
        return isinstance(x, dict) and ("behavior" in x or "devices" in x or "macros" in x)

    cfg = None

    # OLD style: keypress(dev, retries, keyname, n=1, cfg=None)
    if looks_like_dev(args[0]):
        dev = args[0]
        retries = args[1]
        keyname = args[2]
        n = args[3] if len(args) >= 4 else kwargs.get("n", 1)
        cfg = kwargs.get("cfg", None)

    # NEW style: keypress(cfg, dev, retries, keyname, n=1)
    elif looks_like_cfg(args[0]) and len(args) >= 4 and looks_like_dev(args[1]):
        cfg = args[0]
        dev = args[1]
        retries = args[2]
        keyname = args[3]
        n = args[4] if len(args) >= 5 else kwargs.get("n", 1)

    else:
        # Fall back to old style layout to avoid dev becoming int
        dev = args[0]
        retries = args[1]
        keyname = args[2]
        n = args[3] if len(args) >= 4 else kwargs.get("n", 1)
        cfg = kwargs.get("cfg", None)

    keyname = normalize(keyname).lower()
    real = KEY_ALIASES.get(keyname, None)

    if real is None:
        # if user passes exact Roku name, accept it
        real = normalize(keyname)
        real = real[:1].upper() + real[1:]

    # Behavior source: cfg if provided, else load_config()
    if not isinstance(cfg, dict):
        try:
            cfg = load_config()
        except Exception:
            cfg = {}

    beh = (cfg.get("behavior", {}) or {}) if isinstance(cfg, dict) else {}

    # Optional extra gap for volume keys to prevent "jumping"
    # Resolution order:
    #   - per-direction override (volume_up_press_gap / volume_down_press_gap)
    #   - shared fallback (volume_press_gap)
    #   - None (disabled)
    def _get_gap_for(real_key: str):
        base_gap = beh.get("volume_press_gap", None)
        up_gap = beh.get("volume_up_press_gap", None)
        down_gap = beh.get("volume_down_press_gap", None)

        chosen = None
        if real_key == "VolumeUp":
            chosen = up_gap if up_gap is not None else base_gap
        elif real_key == "VolumeDown":
            chosen = down_gap if down_gap is not None else base_gap

        if chosen is None:
            return None
        try:
            chosen = float(chosen)
        except Exception:
            return None
        if chosen <= 0:
            return None
        return chosen

    presses = max(1, int(n))
    for i in range(presses):
        # Optional jitter for repeated keys that are sensitive to "machine-gun" timing
        if i < presses - 1:
            if real in ("VolumeUp", "VolumeDown"):
                _sleep_jitter(0.0, beh.get("volume_jitter_min", 0.0), beh.get("volume_jitter_max", 0.0))

            elif real in ("Up", "Down", "Left", "Right"):
                _sleep_jitter(0.0, beh.get("nav_jitter_min", 0.0), beh.get("nav_jitter_max", 0.0))

        if G["dry_run"]:
            out(f"[DRY] keypress {real}")
        else:
            http_post(dev, f"/keypress/{real}", retries)

        # Add only the missing time beyond rate_delay for volume keys
        if real in ("VolumeUp", "VolumeDown") and i < presses - 1:
            desired_gap = _get_gap_for(real)
            if desired_gap is not None:
                extra = max(0.0, float(desired_gap) - float(dev.get("rate_delay", 0.0)))
                if extra > 0:
                    if G["dry_run"]:
                        out(f"[DRY] sleep {extra}")
                    else:
                        time.sleep(extra)

# ------------------------------------------------------
# Volume helpers
# ------------------------------------------------------
def _chunked_counts(total, chunk_size):
    total = int(total)
    chunk_size = max(1, int(chunk_size))
    parts = []
    while total > 0:
        take = min(chunk_size, total)
        parts.append(take)
        total -= take
    return parts

def volume_zero_out(cfg, dev, retries, downs=None):
    """
    Zero-out behavior.

    Preferred: hold VolumeDown for a fixed duration (ms), because DOWN can be fast safely.
    Fallback: repeated VolumeDown presses.
    """
    beh = (cfg.get("behavior", {}) or {}) if isinstance(cfg, dict) else {}

    # Preferred hold duration (ms)
    hold_ms = beh.get("zero_out_hold_ms", None)
    try:
        hold_ms = int(hold_ms) if hold_ms is not None else None
    except Exception:
        hold_ms = None

    if hold_ms is not None and hold_ms > 0:
        out(f"[ROKU] Volume zero-out hold {hold_ms}ms")
        if G["dry_run"]:
            out(f"[DRY] hold VolumeDown {hold_ms}ms")
            return
        hold_key(dev, retries, "VolumeDown", hold_ms)
        return

    # Fallback to old press-based behavior if hold not configured
    if downs is None:
        downs = int(beh.get("zero_out_down_presses", 8))

    downs = int(downs)
    if downs <= 0:
        return

    out(f"[ROKU] Volume zero-out x{downs}")
    if G["dry_run"]:
        return

    keypress(dev, retries, "VolumeDown", downs)

def smart_volume(cfg, dev, retries, direction, n, chunk=None, chunk_pause=None):
    """
    Volume presses with optional chunking for pacing.

    Important: n means "number of keypresses" (not "volume units").
    Chunking is only used to insert pauses during larger adjustments.
    """
    direction = normalize(direction).lower()
    n = int(n)

    if n <= 0:
        return

    if direction not in ("up", "down"):
        raise RuntimeError(f"smart_volume invalid direction: {direction}")

    # Default chunk size (only affects pacing, not scaling)
    if chunk is None:
        chunk = int(cfg.get("behavior", {}).get("volume_chunk", 2))

    # Direction-specific default pause
    if chunk_pause is None:
        beh = cfg.get("behavior", {}) or {}
        if direction == "up":
            chunk_pause = float(beh.get("volume_chunk_pause_up", beh.get("volume_chunk_pause", 1.75)))
        else:
            chunk_pause = float(beh.get("volume_chunk_pause_down", beh.get("volume_chunk_pause", 1.75)))

    chunk = max(1, int(chunk))
    chunk_pause = float(chunk_pause)

    key = "VolumeUp" if direction == "up" else "VolumeDown"

    # Small adjustments: just press directly, no chunking
    if n <= chunk:
        keypress(cfg, dev, retries, key, n)
        return

    # Larger adjustments: chunk for pacing
    parts = _chunked_counts(n, chunk)
    for i, take in enumerate(parts):
        keypress(cfg, dev, retries, key, take)
        if i < len(parts) - 1:
            if G["dry_run"]:
                out(f"[DRY] sleep {chunk_pause}")
            else:
                time.sleep(chunk_pause)

def volume_set(cfg, dev, retries, target, zero_down=None, chunk=None, chunk_pause=None):
    """
    Set volume to target "number" by:
      1) zero out fast (downs or hold)
      2) smart up to target (with optional overrides)
    """
    target = int(target)
    if target < 0:
        target = 0

    volume_zero_out(cfg, dev, retries, downs=zero_down)
    if target > 0:
        smart_volume(cfg, dev, retries, "up", target, chunk=chunk, chunk_pause=chunk_pause)

def run_pre_launch(cfg, dev, retries, app_name):
    """
    Optional pre-launch actions that run immediately after /launch is sent.
    This is where we can zero out or set volume while the app is still loading.
    """
    pre = cfg.get("pre_launch") or {}
    rule = pre.get(app_name)
    if not isinstance(rule, dict):
        return

    # Option 1: set volume (fast zero, then smart up) during load
    if "set_volume" in rule:
        try:
            target = int(rule.get("set_volume"))
        except Exception:
            return
        zero_down = rule.get("zero_down")
        if zero_down is not None:
            try:
                zero_down = int(zero_down)
            except Exception:
                zero_down = None

        out(f"[ROKU] Pre-launch set volume: {target}")
        # Optional per-app overrides for the set-volume pacing
        chunk = rule.get("chunk")
        chunk_pause = rule.get("chunk_pause")
        if chunk is not None:
            try:
                chunk = int(chunk)
            except Exception:
                chunk = None
        if chunk_pause is not None:
            try:
                chunk_pause = float(chunk_pause)
            except Exception:
                chunk_pause = None

        volume_set(cfg, dev, retries, target, zero_down=zero_down, chunk=chunk, chunk_pause=chunk_pause)
        return

    # Option 2: just zero out fast during load
    if "zero_out_down" in rule:
        try:
            downs = int(rule.get("zero_out_down"))
        except Exception:
            downs = None
        out("[ROKU] Pre-launch volume zero-out")
        volume_zero_out(cfg, dev, retries, downs=downs)
        return

# ------------------------------------------------------
# Post-launch actions (volume sequences, etc.)
# ------------------------------------------------------
def _chunked_taps(total, chunk_size):
    total = int(total)
    chunk_size = max(1, int(chunk_size))
    out_chunks = []
    while total > 0:
        take = min(chunk_size, total)
        out_chunks.append(take)
        total -= take
    return out_chunks

def volume_taps(cfg, dev, retries, direction, n, chunk=2, chunk_pause=0.35):
    """
    Sends volume taps in chunks to avoid the TV "skipping" when 3+ taps happen in a row.
    Example: n=6 chunk=2 -> 2, pause, 2, pause, 2

    Uses cfg-aware keypress so volume_press_gap settings apply consistently.
    """
    direction = normalize(direction).lower()
    key = "VolumeUp" if direction == "up" else "VolumeDown"

    chunks = _chunked_taps(n, chunk)
    for idx, c in enumerate(chunks, start=1):
        out(f"[ROKU] Volume {direction} x{c}")
        keypress(cfg, dev, retries, key, c)
        if idx < len(chunks):
            if G["dry_run"]:
                out(f"[DRY] sleep {chunk_pause}")
            else:
                time.sleep(float(chunk_pause))

def run_post_launch(cfg, st, dev, retries, app_name):
    """
    Run optional post-launch actions for a specific app.
    This is intended to run ONLY when an app was actually launched (not when already active).
    """
    post = (cfg.get("post_launch") or {})
    rule = post.get(app_name)
    if not isinstance(rule, dict):
        return

    seq = rule.get("volume_sequence")
    if not isinstance(seq, list) or not seq:
        return

    out(f"[ROKU] Post-launch actions for: {app_name}")
    for step in seq:
        if not isinstance(step, dict):
            continue

        if "sleep" in step:
            secs = float(step.get("sleep") or 0)
            if secs > 0:
                if G["dry_run"]:
                    out(f"[DRY] sleep {secs}")
                else:
                    time.sleep(secs)
            continue

        direction = step.get("dir")
        n = step.get("n")
        if direction in ("up", "down") and isinstance(n, int):
            chunk = int(step.get("chunk", 2))
            chunk_pause = float(step.get("pause", 0.35))
            volume_taps(cfg, dev, retries, direction, n, chunk=chunk, chunk_pause=chunk_pause)
            continue

# ------------------------------------------------------
# Launch logic
# ------------------------------------------------------
def try_launch(cfg, dev, retries, apps, target_name):
    matched, reason, candidates = find_app_match(cfg, apps, target_name)
    if matched is None:
        if candidates:
            out("[ROKU] Ambiguous. Did you mean:")
            for c in candidates[:5]:
                out(f"  - {c}")
        else:
            out(f"[ROKU] App/input not found: {canonical_name(cfg, target_name)}")
        return False

    current = active_app(dev, retries)
    if current == matched:
        # Confirm, because active-app can lag right after Home/back transitions
        if not G["dry_run"]:
            time.sleep(0.75)

        current2 = active_app(dev, retries)
        if current2 == matched:
            out(f"[ROKU] Already on: {matched}")
            return True

        debug(f"[ROKU] active-app changed after confirm: {current} -> {current2}")

    out(f"[ROKU] Launching: {matched} ({reason})")
    if G["dry_run"]:
        out(f"[DRY] launch {matched}")
        return True

    http_post(dev, f"/launch/{apps[matched]}", retries)

    # Run pre-launch actions immediately after /launch is sent, while app is loading.
    run_pre_launch(cfg, dev, retries, matched)

    time.sleep(1.6)

    current2 = active_app(dev, retries)
    if current2 == matched:
        run_post_launch(cfg, None, dev, retries, matched)
        return True

    # HDMI / input launches often do not update active-app immediately
    if cfg["behavior"].get("assume_input_switch_success", True):
        fb = cfg.get("failback_inputs", {})
        if matched in fb or "tv" in matched or "computer" in matched:
            out(f"[ROKU] Assuming input switch success: {matched}")
            run_post_launch(cfg, None, dev, retries, matched)
            return True

    out(f"[ROKU] Launch did not settle on: {matched}")
    return False

def launch_with_failback(cfg, dev, retries, apps, raw_name):
    target = canonical_name(cfg, raw_name)
    fb = cfg.get("failback_inputs", {})
    if target in fb:
        out(f"[ROKU] Failback group for: {target}")
        for candidate in fb[target]:
            if try_launch(cfg, dev, retries, apps, candidate):
                return True
        out(f"[ROKU] All failback inputs failed for: {target}")
        return False

    return try_launch(cfg, dev, retries, apps, target)

# ------------------------------------------------------
# Status / diag
# ------------------------------------------------------
def cmd_status(cfg, st, dev, retries):
    ip = dev["ip"]
    port = dev["port"]

    ok, sock_err = socket_ping(ip, port)
    status = {"device": dev["name"], "ip": ip, "port": port, "reachable": ok}

    if not ok:
        status["socket_error"] = sock_err
        if G["json"]:
            print(json.dumps(status, indent=2))
        else:
            out(f"[ROKU] Device: {dev['name']} {ip}:{port}")
            out(f"[ROKU] Reachable: no ({sock_err})")
        return 1

    try:
        t0 = time.time()
        p = tv_power_state(dev, retries)
        a = active_app(dev, retries)
        dt = time.time() - t0
        status["power_mode"] = p
        status["active_app"] = a
        status["query_seconds"] = round(dt, 3)
    except Exception as ex:
        status["error"] = str(ex)
        if G["json"]:
            print(json.dumps(status, indent=2))
        else:
            out(f"[ROKU] Error reading status: {ex}")
        record_error(cfg, st, "status", ex)
        return 1

    cpath = cache_path_for(dev["name"])
    cache_info = {"path": str(cpath), "exists": cpath.exists()}
    if cpath.exists():
        try:
            blob = json.loads(cpath.read_text())
            ts = float(blob.get("ts", 0))
            cache_info["age_seconds"] = int(time.time() - ts)
            cache_info["count"] = len(blob.get("apps", {}) or {})
        except Exception:
            cache_info["age_seconds"] = None
            cache_info["count"] = None
    status["apps_cache"] = cache_info

    status["last_action"] = st["actions"][-1] if st["actions"] else None
    status["last_error"] = st["errors"][-1] if st["errors"] else None

    if G["json"]:
        print(json.dumps(status, indent=2))
    else:
        out(f"[ROKU] Device: {dev['name']} {ip}:{port}")
        out(f"[ROKU] Reachable: yes")
        out(f"[ROKU] Power: {status.get('power_mode')}")
        out(f"[ROKU] Active app: {status.get('active_app')}")
        if cache_info.get("exists"):
            out(f"[ROKU] Apps cache: age={cache_info.get('age_seconds')}s count={cache_info.get('count')}")
        else:
            out("[ROKU] Apps cache: none")
        if status["last_action"]:
            out(f"[ROKU] Last action: {status['last_action'].get('action')} @ {status['last_action'].get('ts')}")
        if status["last_error"]:
            out(f"[ROKU] Last error: {status['last_error'].get('where')} @ {status['last_error'].get('ts')}")
    return 0

def cmd_diag(cfg, st, dev, retries):
    # Reuse status, add recent actions/errors
    data = {
        "device": dev["name"],
        "ip": dev["ip"],
        "port": dev["port"],
        "retries": retries,
        "timeout": dev["timeout"],
        "rate_delay": dev["rate_delay"],
        "flags": {k: G[k] for k in ["wake", "lights", "no_lights", "json", "quiet", "debug", "dry_run"]},
        "recent_actions": st["actions"][-10:],
        "recent_errors": st["errors"][-10:],
    }

    ok, sock_err = socket_ping(dev["ip"], dev["port"])
    data["reachable"] = ok
    if not ok:
        data["socket_error"] = sock_err
        if G["json"]:
            print(json.dumps(data, indent=2))
        else:
            out(f"[ROKU] Reachable: no ({sock_err})")
        return 1

    try:
        data["power_mode"] = tv_power_state(dev, retries)
        data["active_app"] = active_app(dev, retries)
    except Exception as ex:
        data["error"] = str(ex)
        record_error(cfg, st, "diag", ex)

    cpath = cache_path_for(dev["name"])
    data["apps_cache_path"] = str(cpath)
    if cpath.exists():
        try:
            blob = json.loads(cpath.read_text())
            ts = float(blob.get("ts", 0))
            data["apps_cache_age_seconds"] = int(time.time() - ts)
            data["apps_cache_count"] = len(blob.get("apps", {}) or {})
        except Exception:
            data["apps_cache_age_seconds"] = None
            data["apps_cache_count"] = None
    else:
        data["apps_cache_age_seconds"] = None
        data["apps_cache_count"] = 0

    if G["json"]:
        print(json.dumps(data, indent=2))
    else:
        out(f"[ROKU] Device: {dev['name']} {dev['ip']}:{dev['port']}")
        out(f"[ROKU] Reachable: yes")
        out(f"[ROKU] Power: {data.get('power_mode')}")
        out(f"[ROKU] Active app: {data.get('active_app')}")
        out(f"[ROKU] Cache: age={data.get('apps_cache_age_seconds')}s count={data.get('apps_cache_count')}")
        out("[ROKU] Recent actions:")
        for a in data["recent_actions"]:
            out(f"  - {a.get('ts')} {a.get('action')}")
        out("[ROKU] Recent errors:")
        for e in data["recent_errors"]:
            out(f"  - {e.get('ts')} {e.get('where')}: {e.get('error')}")
    return 0

def cmd_ping(cfg, st, dev):
    ok, err = socket_ping(dev["ip"], dev["port"])
    if G["json"]:
        print(json.dumps({"device": dev["name"], "ip": dev["ip"], "port": dev["port"], "reachable": ok, "error": err}, indent=2))
    else:
        out(f"[ROKU] {dev['name']} {dev['ip']}:{dev['port']} reachable={'yes' if ok else 'no'}")
        if err and not ok:
            out(f"[ROKU] {err}")
    return 0 if ok else 1

# ------------------------------------------------------
# Apps listing
# ------------------------------------------------------
def cmd_apps(cfg, st, dev, retries, filter_text=None, refresh=False):
    apps, meta = load_apps_cached(cfg, dev, retries, refresh=refresh)

    # Build detailed list from live query when listing (names, ids, types)
    xml = http_get(dev, "/query/apps", retries) if (refresh or meta["source"] == "live") else None
    rows = []
    if xml:
        root = ET.fromstring(xml)
        for app in root.findall("app"):
            app_id = app.get("id", "")
            app_type = app.get("type", "")
            name = normalize((app.text or "").strip())
            roku_arg = name.lower()
            slug = re.sub(r"[^a-z0-9]+", "_", roku_arg).strip("_")
            slug = re.sub(r"_+", "_", slug)
            rows.append((name, roku_arg, slug, app_id, app_type))
    else:
        # fallback rows from cache keys only
        for name_lc, app_id in apps.items():
            name = name_lc
            roku_arg = name_lc
            slug = re.sub(r"[^a-z0-9]+", "_", roku_arg).strip("_")
            slug = re.sub(r"_+", "_", slug)
            rows.append((name, roku_arg, slug, app_id, ""))

    if filter_text:
        ft = normalize(filter_text).lower()
        rows = [r for r in rows if ft in r[0].lower() or ft in r[1] or ft in r[2] or ft in r[3]]

    rows.sort(key=lambda r: r[0].lower())

    if G["json"]:
        print(json.dumps({
            "meta": meta,
            "count": len(rows),
            "rows": [
                {"name": r[0], "roku_arg": r[1], "suggested": r[2], "id": r[3], "type": r[4]}
                for r in rows
            ]
        }, indent=2))
        return 0

    if not rows:
        out("[ROKU] No apps matched.")
        return 0

    name_w = min(60, max(len(r[0]) for r in rows))
    arg_w = min(55, max(len(r[1]) for r in rows))
    slug_w = min(35, max(len(r[2]) for r in rows))

    out(f"{'APP NAME':{name_w}}  {'ROKU ARG':{arg_w}}  {'SUGGESTED':{slug_w}}  {'ID':<16} TYPE")
    out(f"{'-'*name_w}  {'-'*arg_w}  {'-'*slug_w}  {'-'*16} {'-'*4}")
    for name, roku_arg, slug, app_id, app_type in rows:
        out(f"{name:{name_w}}  {roku_arg:{arg_w}}  {slug:{slug_w}}  {app_id:<16} {app_type}")
    return 0

# ------------------------------------------------------
# Macros
# ------------------------------------------------------
def cmd_macro_list(cfg):
    macros = cfg.get("macros", {}) or {}
    names = sorted(macros.keys())
    if G["json"]:
        print(json.dumps({"macros": names}, indent=2))
    else:
        out("[ROKU] Macros:")
        for n in names:
            out(f"  - {n}")
    return 0

def cmd_macro_show(cfg, name):
    macros = cfg.get("macros", {}) or {}
    if name not in macros:
        eprint(f"[ROKU] Macro not found: {name}")
        return 1
    if G["json"]:
        print(json.dumps({"name": name, "macro": macros[name]}, indent=2))
    else:
        out(json.dumps(macros[name], indent=2))
    return 0

def cmd_macro_edit():
    # We do not open an editor. We print the path.
    out(str(CONFIG_PATH))
    return 0

def run_macro(cfg, st, dev, retries, name):
    macros = cfg.get("macros", {}) or {}
    macro = macros.get(name)
    if not macro:
        eprint(f"[ROKU] Macro not found: {name}")
        return 1

    steps = macro.get("steps", [])
    if not isinstance(steps, list):
        eprint(f"[ROKU] Macro steps invalid: {name}")
        return 1

    record_action(cfg, st, "macro.run", {"name": name})

    apps, _meta = load_apps_cached(cfg, dev, retries, refresh=False)

    for i, step in enumerate(steps, start=1):
        if not isinstance(step, dict) or "action" not in step:
            eprint(f"[ROKU] Invalid macro step {i} in {name}")
            return 1

        action = step["action"]
        debug(f"[MACRO] step {i}: {action} {step}")

        # Optional waits
        wait = step.get("wait")
        if wait:
            if G["dry_run"]:
                out(f"[DRY] sleep {wait}")
            else:
                time.sleep(float(wait))

        if action == "sleep" or action == "wait":
            secs = float(step.get("seconds", step.get("wait", 0)))
            if secs > 0:
                if G["dry_run"]:
                    out(f"[DRY] sleep {secs}")
                else:
                    time.sleep(secs)

        elif action == "ensure_power_on":
            p = tv_power_state(dev, retries)
            if p != "PowerOn":
                out("[ROKU] TV is off. Powering on.")
                keypress(dev, retries, "Power", 1)
                time.sleep(float(step.get("wait", 2.5)))

        elif action == "assert_or_wake_power_on":
            p = tv_power_state(dev, retries)
            if p != "PowerOn":
                if wake_enabled(cfg):
                    out("[ROKU] TV is off. Powering on because --wake is enabled.")
                    keypress(dev, retries, "Power", 1)
                    time.sleep(float(step.get("wait", 2.5)))
                else:
                    out("[ROKU] TV is off. Use --wake to allow auto power-on.")
                    return 1

        elif action == "assert_power_on":
            p = tv_power_state(dev, retries)
            if p != "PowerOn":
                out("[ROKU] TV is off. Macro aborting.")
                return 1

        elif action == "launch":
            target = step.get("target", "")
            if not target:
                eprint("[ROKU] Macro launch missing target")
                return 1
            if not ensure_or_exit_awake(cfg, dev, retries, "launch"):
                return 1
            ok = launch_with_failback(cfg, dev, retries, apps, target)
            if not ok:
                # auto-refresh once and retry
                out("[ROKU] Launch failed. Refreshing apps cache and retrying once.")
                apps = fetch_apps(cfg, dev, retries)
                save_apps_cache(dev["name"], apps)
                ok2 = launch_with_failback(cfg, dev, retries, apps, target)
                if not ok2:
                    return 1

        elif action == "key":
            k = step.get("key", "")
            n = int(step.get("n", 1))
            if not ensure_or_exit_awake(cfg, dev, retries, "key"):
                return 1
            keypress(dev, retries, k, n)

        elif action == "home":
            if not ensure_or_exit_awake(cfg, dev, retries, "home"):
                return 1
            keypress(dev, retries, "Home", 1)

        elif action == "vol_up":
            n = int(step.get("n", 1))
            if not ensure_or_exit_awake(cfg, dev, retries, "vol"):
                return 1
            smart_volume(cfg, dev, retries, "up", n)

        elif action == "vol_down":
            n = int(step.get("n", 1))
            if not ensure_or_exit_awake(cfg, dev, retries, "vol"):
                return 1
            smart_volume(cfg, dev, retries, "down", n)

        elif action == "vol_hold":
            direction = normalize(step.get("dir", "")).lower()
            ms = safe_int(step.get("ms", None), None)

            # Safety: allow DOWN only, never UP
            if direction != "down" or ms is None:
                eprint("[ROKU] vol_hold requires dir=down and ms=<int>")
                return 1

            if not ensure_or_exit_awake(cfg, dev, retries, "vol"):
                return 1

            record_action(cfg, st, "vol.hold", {"dir": "down", "ms": ms})
            out(f"[ROKU] Volume down hold {ms}ms")
            hold_key(dev, retries, "VolumeDown", ms)

        elif action == "lights":
            mode = step.get("mode", "")
            if not mode:
                eprint("[LIGHTS] Macro lights missing mode")
                return 1

            if G["no_lights"]:
                out("[LIGHTS] --no-lights set. Skipping lights action.")
            else:
                out(f"[LIGHTS] Setting lights: {mode}")
                rc = run_lights(cfg, [mode], quiet=True, force=True)
                if rc != 0:
                    out(f"[LIGHTS] Lights command failed (returncode={rc})")

        elif action == "scene_for":
            # Apply scene for a named app mapping (does not launch)
            target = step.get("target", "")
            if not target:
                eprint("[ROKU] Macro scene_for missing target")
                return 1
            requires = bool(step.get("requires_lights", False))
            if requires and not lights_allowed(cfg):
                out("[ROKU] Lights not enabled. Skipping scene_for step.")
            else:
                tcanon = canonical_name(cfg, target)
                apply_light_scene(cfg, tcanon, force=True)

        elif action == "scene_sync":
            if not ensure_or_exit_awake(cfg, dev, retries, "scene"):
                return 1
            cur = active_app(dev, retries)
            if lights_allowed(cfg):
                apply_light_scene(cfg, cur, force=True)
            else:
                out("[ROKU] Lights not enabled. Skipping scene_sync.")

        elif action == "type":
            txt = step.get("text", "")
            if not txt:
                eprint("[ROKU] Macro type missing text")
                return 1
            if not ensure_or_exit_awake(cfg, dev, retries, "type"):
                return 1
            type_text(cfg, dev, retries, txt)

        elif action == "print":
            msg = step.get("msg", "")
            out(str(msg))

        else:
            eprint(f"[ROKU] Unknown macro action: {action}")
            return 1

    return 0

def run_macro_dry(cfg, st, dev, retries, name):
    prev = G.get("dry_run", False)
    try:
        G["dry_run"] = True
        out(f"[ROKU] macro test (dry-run): {name}")
        return run_macro(cfg, st, dev, retries, name)
    finally:
        G["dry_run"] = prev

# ------------------------------------------------------
# Follow mode (foreground + optional daemon)
# ------------------------------------------------------
def is_follow_running():
    if not FOLLOW_PID_PATH.exists():
        return False, None
    try:
        pid = int(FOLLOW_PID_PATH.read_text().strip())
    except Exception:
        return False, None
    try:
        os.kill(pid, 0)
        return True, pid
    except Exception:
        return False, pid

def cmd_follow_status():
    running, pid = is_follow_running()
    if G["json"]:
        print(json.dumps({"running": running, "pid": pid}, indent=2))
    else:
        out(f"[ROKU] follow running={'yes' if running else 'no'} pid={pid}")
    return 0

def cmd_follow_stop():
    running, pid = is_follow_running()
    if not pid:
        out("[ROKU] follow is not running.")
        try:
            FOLLOW_PID_PATH.unlink(missing_ok=True)
        except Exception:
            pass
        return 0
    if not running:
        out("[ROKU] follow pid file exists but process is not running. Clearing pid file.")
        try:
            FOLLOW_PID_PATH.unlink(missing_ok=True)
        except Exception:
            pass
        return 0

    if G["dry_run"]:
        out(f"[DRY] kill {pid}")
        return 0

    # TERM, then KILL if needed
    try:
        os.kill(pid, 15)
    except Exception as ex:
        eprint(f"[ROKU] failed to stop follow: {ex}")
        return 1

    # Wait briefly for clean exit
    t0 = time.time()
    while time.time() - t0 < 1.2:
        if not _pid_alive(pid):
            break
        time.sleep(0.1)

    if _pid_alive(pid):
        try:
            os.kill(pid, 9)
        except Exception:
            pass

    try:
        FOLLOW_PID_PATH.unlink(missing_ok=True)
    except Exception:
        pass

    out("[ROKU] follow stopped.")
    return 0

def cmd_follow_run(cfg, st, dev, retries, poll_override=None, daemon=False):
    if not lights_allowed(cfg):
        out("[ROKU] follow requires --lights (or default_lights=true in config).")
        return 1

    if daemon:
        running, pid = is_follow_running()
        if running:
            out(f"[ROKU] follow already running (pid={pid})")
            return 0

        # Clear stale pid file if present
        if pid and not running:
            try:
                FOLLOW_PID_PATH.unlink(missing_ok=True)
            except Exception:
                pass

        # Spawn self in foreground follow mode (no daemon flag)
        args = [sys.executable, __file__]
        # keep global flags that matter
        if G["device"]:
            args += ["--device", G["device"]]
        if G["ip"]:
            args += ["--ip", G["ip"]]
        if G["port"]:
            args += ["--port", str(G["port"])]
        if G["timeout"] is not None:
            args += ["--timeout", str(G["timeout"])]
        if G["retries"] is not None:
            args += ["--retries", str(G["retries"])]
        if G["rate_delay"] is not None:
            args += ["--rate-delay", str(G["rate_delay"])]
        if G["wake"] is True:
            args += ["--wake"]
        if G["no_lights"]:
            args += ["--no-lights"]
        else:
            args += ["--lights"]
        if G["quiet"]:
            args += ["--quiet"]
        if G["debug"]:
            args += ["--debug"]

        args += ["follow"]
        if poll_override is not None:
            args += ["--poll", str(poll_override)]

        if G["dry_run"]:
            out("[DRY] spawn follow daemon:")
            out("  " + " ".join(args))
            return 0

        p = subprocess.Popen(args, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
        mkdirp(FOLLOW_PID_PATH)
        FOLLOW_PID_PATH.write_text(str(p.pid) + "\n")
        out(f"[ROKU] follow started (pid={p.pid})")
        return 0

    poll = float(poll_override) if poll_override is not None else float(cfg.get("follow", {}).get("poll_seconds", 2.0))
    min_gap = float(cfg.get("follow", {}).get("min_seconds_between_light_changes", 6.0))
    ignore = set([normalize(x).lower() for x in (cfg.get("follow", {}).get("ignore_apps", []) or [])])

    record_action(cfg, st, "follow.start", {"poll_seconds": poll})

    last_app = None
    last_light_ts = 0.0

    out(f"[ROKU] follow running (poll={poll}s). Ctrl+C to stop.")
    try:
        while True:
            try:
                if not ensure_or_exit_awake(cfg, dev, retries, "follow"):
                    time.sleep(poll)
                    continue

                cur = active_app(dev, retries)
                if cur in ignore:
                    cur_effective = None
                else:
                    cur_effective = cur

                if cur_effective and cur_effective != last_app:
                    now = time.time()
                    if now - last_light_ts >= min_gap:
                        out(f"[ROKU] app change: {last_app} -> {cur_effective}")
                        apply_light_scene(cfg, cur_effective, force=True)
                        last_light_ts = now
                    last_app = cur_effective
                time.sleep(poll)
            except KeyboardInterrupt:
                raise
            except Exception as ex:
                record_error(cfg, st, "follow.loop", ex)
                debug(f"[ROKU] follow error: {ex}")
                time.sleep(max(1.0, poll))
    except KeyboardInterrupt:
        out("[ROKU] follow stopped.")
        record_action(cfg, st, "follow.stop", None)
        return 0

# ------------------------------------------------------
# Device commands and discovery
# ------------------------------------------------------
def cmd_device_list(cfg):
    devs = cfg.get("devices", {}) or {}
    names = sorted(devs.keys())
    if G["json"]:
        print(json.dumps({"default_device": cfg.get("default_device"), "devices": devs}, indent=2))
    else:
        out(f"[ROKU] default_device: {cfg.get('default_device')}")
        out("[ROKU] devices:")
        for n in names:
            d = devs[n]
            out(f"  - {n}: {d.get('ip')}:{d.get('port', 8060)}")
    return 0

def cmd_device_use(cfg, name):
    devs = cfg.get("devices", {}) or {}
    if name not in devs:
        eprint(f"[ROKU] Unknown device: {name}")
        return 1
    cfg["default_device"] = name
    if G["dry_run"]:
        out(f"[DRY] set default_device={name} in {CONFIG_PATH}")
        return 0
    write_json_file(CONFIG_PATH, cfg)
    out(f"[ROKU] default_device set to: {name}")
    return 0

def ssdp_discover(timeout=1.4):
    """
    SSDP M-SEARCH for Roku ECP.
    Returns list of dicts with ip, location, usn, st.
    """
    msg = "\r\n".join([
        "M-SEARCH * HTTP/1.1",
        "HOST: 239.255.255.250:1900",
        "MAN: \"ssdp:discover\"",
        "MX: 1",
        "ST: roku:ecp",
        "",
        ""
    ]).encode("utf-8")

    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP)
    s.settimeout(timeout)
    try:
        s.sendto(msg, ("239.255.255.250", 1900))
        seen = []
        while True:
            try:
                data, addr = s.recvfrom(65535)
            except socket.timeout:
                break
            text = data.decode("utf-8", errors="ignore")
            headers = {}
            for line in text.split("\r\n"):
                if ":" in line:
                    k, v = line.split(":", 1)
                    headers[k.strip().lower()] = v.strip()
            loc = headers.get("location")
            st = headers.get("st")
            usn = headers.get("usn")
            ip = addr[0]
            seen.append({"ip": ip, "location": loc, "st": st, "usn": usn})
        # de-dupe by ip
        outd = {}
        for r in seen:
            outd[r["ip"]] = r
        return list(outd.values())
    finally:
        try:
            s.close()
        except Exception:
            pass

def cmd_discover(cfg, st, retries):
    results = ssdp_discover()
    enriched = []
    for r in results:
        ip = r.get("ip")
        port = 8060
        dev = {"name": "discovered", "ip": ip, "port": port, "timeout": 2.0, "rate_delay": 0.05, "base_url": f"http://{ip}:{port}"}
        name = None
        model = None
        try:
            root = query_device_info(dev, retries=0)
            name = root.findtext("friendly-device-name") or root.findtext("friendly-model-name")
            model = root.findtext("model-name")
        except Exception:
            pass
        r2 = dict(r)
        if name:
            r2["name"] = name
        if model:
            r2["model"] = model
        enriched.append(r2)

    if G["json"]:
        print(json.dumps({"count": len(enriched), "devices": enriched}, indent=2))
    else:
        if not enriched:
            out("[ROKU] No Roku devices found via SSDP.")
        else:
            out("[ROKU] Discovered Roku devices:")
            for d in enriched:
                label = d.get("name") or "unknown"
                out(f"  - {label}: {d.get('ip')} ({d.get('location') or 'no location'})")
    record_action(cfg, st, "discover", {"count": len(enriched)})
    return 0

# ------------------------------------------------------
# Cache commands
# ------------------------------------------------------
def cmd_cache_info(cfg, dev):
    cpath = cache_path_for(dev["name"])
    info = {"path": str(cpath), "exists": cpath.exists()}
    if cpath.exists():
        try:
            blob = json.loads(cpath.read_text())
            ts = float(blob.get("ts", 0))
            info["age_seconds"] = int(time.time() - ts)
            info["count"] = len(blob.get("apps", {}) or {})
        except Exception as ex:
            info["error"] = str(ex)
    if G["json"]:
        print(json.dumps(info, indent=2))
    else:
        out(f"[ROKU] cache path: {info['path']}")
        out(f"[ROKU] exists: {info['exists']}")
        if info.get("exists"):
            out(f"[ROKU] age_seconds: {info.get('age_seconds')}")
            out(f"[ROKU] count: {info.get('count')}")
            if info.get("error"):
                out(f"[ROKU] error: {info.get('error')}")
    return 0

def cmd_cache_clear(dev):
    cpath = cache_path_for(dev["name"])
    if G["dry_run"]:
        out(f"[DRY] rm {cpath}")
        return 0
    try:
        cpath.unlink(missing_ok=True)
        out("[ROKU] cache cleared.")
        return 0
    except Exception as ex:
        eprint(f"[ROKU] failed to clear cache: {ex}")
        return 1

# ------------------------------------------------------
# Config commands
# ------------------------------------------------------
def cmd_config_path():
    out(str(CONFIG_PATH))
    return 0

def cmd_config_show(cfg):
    # show merged config (defaults + on-disk overrides)
    if G["json"]:
        print(json.dumps(cfg, indent=2, sort_keys=False))
    else:
        out(json.dumps(cfg, indent=2, sort_keys=False))
    return 0

def cmd_config_init():
    if CONFIG_PATH.exists():
        out(f"[ROKU] config already exists: {CONFIG_PATH}")
        return 0

    # write defaults to disk
    cfg = copy.deepcopy(DEFAULT_CONFIG)
    if G["dry_run"]:
        out(f"[DRY] would write default config to: {CONFIG_PATH}")
        return 0

    write_json_file(CONFIG_PATH, cfg)
    out(f"[ROKU] wrote default config: {CONFIG_PATH}")
    return 0

def cmd_config_validate(cfg):
    errors = []
    warns = []

    # devices
    devs = cfg.get("devices")
    if not isinstance(devs, dict) or not devs:
        errors.append("devices must be a non-empty object")

    default_device = cfg.get("default_device")
    if not isinstance(default_device, str) or not default_device.strip():
        errors.append("default_device must be a non-empty string")
    elif isinstance(devs, dict) and default_device not in devs:
        errors.append(f"default_device '{default_device}' not found in devices")

    if isinstance(devs, dict):
        for name, d in devs.items():
            if not isinstance(d, dict):
                errors.append(f"devices.{name} must be an object")
                continue
            ip = d.get("ip")
            if not isinstance(ip, str) or not ip.strip():
                errors.append(f"devices.{name}.ip must be a non-empty string")
            port = d.get("port", 8060)
            try:
                port_i = int(port)
                if port_i < 1 or port_i > 65535:
                    errors.append(f"devices.{name}.port out of range: {port}")
            except Exception:
                errors.append(f"devices.{name}.port must be an int")
            for fkey in ("timeout", "rate_delay"):
                if fkey in d:
                    try:
                        v = float(d.get(fkey))
                        if v <= 0:
                            errors.append(f"devices.{name}.{fkey} must be > 0")
                    except Exception:
                        errors.append(f"devices.{name}.{fkey} must be a number")

    # behavior checks
    beh = cfg.get("behavior")
    if not isinstance(beh, dict):
        errors.append("behavior must be an object")
        beh = {}

    numeric_nonneg = [
        "apps_cache_ttl_seconds",
        "max_state_actions",
        "max_state_errors",
        "max_vol_presses_per_command",
        "max_volume_set_target",
        "volume_chunk",
        "volume_chunk_pause",
        "volume_chunk_pause_up",
        "volume_chunk_pause_down",
        "volume_press_gap",
        "volume_up_press_gap",
        "volume_down_press_gap",
        "volume_jitter_min",
        "volume_jitter_max",
        "nav_jitter_min",
        "nav_jitter_max",
        "type_char_delay",
        "type_jitter_min",
        "type_jitter_max",
        "zero_out_hold_ms",
        "zero_out_down_presses",
    ]
    for k in numeric_nonneg:
        if k not in beh:
            continue
        v = beh.get(k)
        if v is None:
            continue
        try:
            fv = float(v)
            if fv < 0:
                errors.append(f"behavior.{k} must be >= 0")
        except Exception:
            errors.append(f"behavior.{k} must be a number or null")

    # lights bin existence (warn)
    lb = lights_bin(cfg)
    if not isinstance(lb, str) or not lb.strip():
        warns.append("lights.bin is empty, lights actions will not work")
    else:
        if not Path(lb).exists():
            warns.append(f"lights.bin not found: {lb}")

    # follow sanity
    follow = cfg.get("follow", {})
    if isinstance(follow, dict):
        for k in ("poll_seconds", "min_seconds_between_light_changes"):
            if k in follow:
                try:
                    fv = float(follow.get(k))
                    if fv <= 0:
                        errors.append(f"follow.{k} must be > 0")
                except Exception:
                    errors.append(f"follow.{k} must be a number")

    if G["json"]:
        print(json.dumps({"ok": (len(errors) == 0), "errors": errors, "warnings": warns}, indent=2))
        return 0 if len(errors) == 0 else 1

    if errors:
        out("[ROKU] config validate: FAIL")
        out("[ROKU] Errors:")
        for e in errors:
            out(f"  - {e}")
    else:
        out("[ROKU] config validate: OK")

    if warns:
        out("[ROKU] Warnings:")
        for w in warns:
            out(f"  - {w}")

    return 0 if len(errors) == 0 else 1

# ------------------------------------------------------
# CLI parsing
# ------------------------------------------------------
def usage(exit_code=1):
    print(
"""Usage:
  roku [global options] <command> [args]
  roku [global options] <app_or_input>        (shorthand for launch)

Core:
  status
  diag
  ping

Apps:
  apps [filter] [--refresh]
  list [filter] [--refresh]
  launch <name>

Remote:
  key <keyname> [n]
  keydown <keyname>
  keyup <keyname>
  nav up|down|left|right [n]
  ok [n]
  back [n]
  home
  info
  replay
  play
  pause
  fwd [n]
  rev [n]
  mute
  type "<text>"

Volume:
  vol up|down [n]
  vol hold up|down <ms>
  volup [n]
  voldown [n]
  vol normalize night|day
  vol set <n>
  vol zero [downs]

Modes:
  movie
  console
  scene
  work
  shutdown

Follow:
  follow [--poll <seconds>] [--daemon]
  follow stop
  follow status

Macros:
  macro list
  macro show <name>
  macro run <name>
  macro test <name>
  macro edit

Devices:
  device list
  device use <name>
  discover

Cache:
  cache info
  cache clear

Config:
  config path
  config show
  config init
  config validate

Global options:
  --device <name>
  --ip <ip>
  --port <port>
  --timeout <seconds>
  --retries <n>
  --rate-delay <seconds>

  --wake
  --no-wake

  --lights
  --no-lights

  --json
  --quiet
  --debug
  --dry-run
"""
    )
    sys.exit(exit_code)

def parse_global_flags(cfg, argv):
    """
    Consume global flags anywhere in argv.
    Returns remaining args.
    """
    outv = []
    i = 0
    while i < len(argv):
        a = argv[i]

        if a == "--device" and i + 1 < len(argv):
            G["device"] = argv[i + 1]
            i += 2
            continue
        if a == "--ip" and i + 1 < len(argv):
            G["ip"] = argv[i + 1]
            i += 2
            continue
        if a == "--port" and i + 1 < len(argv):
            G["port"] = safe_int(argv[i + 1], None)
            i += 2
            continue
        if a == "--timeout" and i + 1 < len(argv):
            try:
                G["timeout"] = float(argv[i + 1])
            except Exception:
                pass
            i += 2
            continue
        if a == "--retries" and i + 1 < len(argv):
            G["retries"] = safe_int(argv[i + 1], None)
            i += 2
            continue
        if a == "--rate-delay" and i + 1 < len(argv):
            try:
                G["rate_delay"] = float(argv[i + 1])
            except Exception:
                pass
            i += 2
            continue

        if a == "--wake":
            G["wake"] = True
            i += 1
            continue
        if a == "--no-wake":
            G["wake"] = False
            i += 1
            continue

        if a == "--lights":
            G["lights"] = True
            i += 1
            continue
        if a == "--no-lights":
            G["no_lights"] = True
            G["lights"] = False
            i += 1
            continue

        if a == "--json":
            G["json"] = True
            i += 1
            continue
        if a == "--quiet":
            G["quiet"] = True
            i += 1
            continue
        if a == "--debug":
            G["debug"] = True
            i += 1
            continue
        if a == "--dry-run":
            G["dry_run"] = True
            i += 1
            continue

        if a in ("help", "-h", "--help"):
            usage(0)

        outv.append(a)
        i += 1

    # Defaults if unset
    if G["wake"] is None:
        G["wake"] = cfg["behavior"].get("default_wake", False)
    if G["lights"] is None:
        G["lights"] = cfg["behavior"].get("default_lights", False)

    return outv

# ------------------------------------------------------
# Main dispatch
# ------------------------------------------------------
def main():
    cfg = load_config()
    st = load_state(cfg)

    argv = sys.argv[1:]
    if not argv:
        usage(1)

    argv = parse_global_flags(cfg, argv)
    if not argv:
        usage(1)

    retries = G["retries"] if G["retries"] is not None else 2

    # Handle commands that do not require a device
    cmd0 = argv[0].lower()
    if cmd0 == "macro" and len(argv) >= 2 and argv[1].lower() == "edit":
        return cmd_macro_edit()
    if cmd0 == "discover":
        dev_tmp = {"name": "tmp", "ip": "0.0.0.0", "port": 8060, "timeout": 2.0, "rate_delay": 0.05, "base_url": "http://0.0.0.0:8060"}
        return cmd_discover(cfg, st, retries=0)
    if cmd0 == "config" and len(argv) >= 2 and argv[1].lower() in ("path", "show", "init", "validate"):
        sub = argv[1].lower()
        if sub == "path":
            return cmd_config_path()
        if sub == "show":
            return cmd_config_show(cfg)
        if sub == "init":
            return cmd_config_init()
        if sub == "validate":
            return cmd_config_validate(cfg)

    # Device-required commands
    try:
        dev = get_device_cfg(cfg)
    except Exception as ex:
        eprint(f"[ROKU] {ex}")
        return 1

    # Back-compat: volup/voldown
    if cmd0 in ("volup", "voldown"):
        n = safe_int(argv[1], 1) if len(argv) > 1 else 1
        if not ensure_or_exit_awake(cfg, dev, retries, "vol"):
            return 0
        if cmd0 == "volup":
            record_action(cfg, st, "vol.up", {"n": n})
            smart_volume(cfg, dev, retries, "up", n)
        else:
            record_action(cfg, st, "vol.down", {"n": n})
            smart_volume(cfg, dev, retries, "down", n)
        return 0

    # Determine whether this is a known command or shorthand launch
    cmd = cmd0
    is_known = cmd in KNOWN_COMMANDS

    # If not known, treat remaining args as a single launch name
    if not is_known:
        target = " ".join(argv)
        if not ensure_or_exit_awake(cfg, dev, retries, "launch"):
            return 0
        apps, _meta = load_apps_cached(cfg, dev, retries, refresh=False)
        record_action(cfg, st, "launch", {"target": target})
        ok = launch_with_failback(cfg, dev, retries, apps, target)
        if not ok:
            out("[ROKU] Launch failed. Refreshing apps cache and retrying once.")
            apps = fetch_apps(cfg, dev, retries)
            save_apps_cache(dev["name"], apps)
            ok2 = launch_with_failback(cfg, dev, retries, apps, target)
            if not ok2:
                record_error(cfg, st, "launch", "failed", {"target": target})
                return 1
        return 0

    # Known command dispatch
    try:
        if cmd == "status":
            record_action(cfg, st, "status", None)
            return cmd_status(cfg, st, dev, retries)

        if cmd == "diag":
            record_action(cfg, st, "diag", None)
            return cmd_diag(cfg, st, dev, retries)

        if cmd == "ping":
            record_action(cfg, st, "ping", None)
            return cmd_ping(cfg, st, dev)

        if cmd in ("apps", "list"):
            filt = argv[1] if len(argv) > 1 and not argv[1].startswith("--") else None
            refresh = "--refresh" in argv
            record_action(cfg, st, "apps", {"filter": filt, "refresh": refresh})
            return cmd_apps(cfg, st, dev, retries, filter_text=filt, refresh=refresh)

        if cmd == "cache":
            sub = argv[1].lower() if len(argv) > 1 else ""
            if sub == "info":
                return cmd_cache_info(cfg, dev)
            if sub == "clear":
                return cmd_cache_clear(dev)
            usage(1)

        if cmd == "launch":
            if len(argv) < 2:
                usage(1)
            target = " ".join(argv[1:])
            if not ensure_or_exit_awake(cfg, dev, retries, "launch"):
                return 0
            apps, _meta = load_apps_cached(cfg, dev, retries, refresh=False)
            record_action(cfg, st, "launch", {"target": target})
            ok = launch_with_failback(cfg, dev, retries, apps, target)
            if not ok:
                out("[ROKU] Launch failed. Refreshing apps cache and retrying once.")
                apps = fetch_apps(cfg, dev, retries)
                save_apps_cache(dev["name"], apps)
                ok2 = launch_with_failback(cfg, dev, retries, apps, target)
                if not ok2:
                    record_error(cfg, st, "launch", "failed", {"target": target})
                    return 1
            return 0

        if cmd == "power":
            record_action(cfg, st, "key.power", None)
            keypress(dev, retries, "Power", 1)
            return 0

        if cmd == "home":
            if not ensure_or_exit_awake(cfg, dev, retries, "home"):
                return 0
            record_action(cfg, st, "key.home", None)
            keypress(dev, retries, "Home", 1)
            return 0

        if cmd == "key":
            if len(argv) < 2:
                usage(1)
            k = argv[1]
            n = safe_int(argv[2], 1) if len(argv) > 2 else 1
            if not ensure_or_exit_awake(cfg, dev, retries, "key"):
                return 0
            record_action(cfg, st, "key", {"key": k, "n": n})
            keypress(dev, retries, k, n)
            return 0

        if cmd == "keydown":
            if len(argv) < 2:
                usage(1)
            k = argv[1]
            if not ensure_or_exit_awake(cfg, dev, retries, "key"):
                return 0
            record_action(cfg, st, "keydown", {"key": k})
            keydown(dev, retries, k)
            return 0

        if cmd == "keyup":
            if len(argv) < 2:
                usage(1)
            k = argv[1]
            if not ensure_or_exit_awake(cfg, dev, retries, "key"):
                return 0
            record_action(cfg, st, "keyup", {"key": k})
            keyup(dev, retries, k)
            return 0

        if cmd == "nav":
            if len(argv) < 2:
                usage(1)
            direction = argv[1].lower()
            n = safe_int(argv[2], 1) if len(argv) > 2 else 1
            if direction not in ("up", "down", "left", "right"):
                usage(1)
            if not ensure_or_exit_awake(cfg, dev, retries, "nav"):
                return 0
            record_action(cfg, st, "nav", {"dir": direction, "n": n})
            keypress(dev, retries, direction, n)
            return 0

        if cmd == "ok":
            n = safe_int(argv[1], 1) if len(argv) > 1 else 1
            if not ensure_or_exit_awake(cfg, dev, retries, "ok"):
                return 0
            record_action(cfg, st, "ok", {"n": n})
            keypress(dev, retries, "Select", n)
            return 0

        if cmd in ("back", "info", "replay", "play", "pause", "fwd", "rev", "mute"):
            n = safe_int(argv[1], 1) if len(argv) > 1 else 1
            if not ensure_or_exit_awake(cfg, dev, retries, cmd):
                return 0
            record_action(cfg, st, f"key.{cmd}", {"n": n})
            keypress(dev, retries, cmd, n)
            return 0

        if cmd == "type":
            if len(argv) < 2:
                usage(1)
            text = " ".join(argv[1:])
            if not ensure_or_exit_awake(cfg, dev, retries, "type"):
                return 0
            record_action(cfg, st, "type", {"text": text})
            type_text(cfg, dev, retries, text)
            return 0

        if cmd == "vol":
            if len(argv) < 2:
                usage(1)
            sub = argv[1].lower()
            if sub in ("up", "down"):
                n = safe_int(argv[2], 1) if len(argv) > 2 else 1
                if not ensure_or_exit_awake(cfg, dev, retries, "vol"):
                    return 0
                record_action(cfg, st, f"vol.{sub}", {"n": n})
                smart_volume(cfg, dev, retries, sub, n)
                return 0
            if sub == "hold":
                if len(argv) < 4:
                    usage(1)
                direction = argv[2].lower()
                ms = safe_int(argv[3], None)
                if direction not in ("up", "down") or ms is None:
                    usage(1)

                # HARD SAFETY: disallow hold up on this TV
                if direction == "up":
                    eprint("[ROKU] vol hold up is disabled on this TV for safety.")
                    return 1

                if not ensure_or_exit_awake(cfg, dev, retries, "vol"):
                    return 0

                keyname = "VolumeDown"
                record_action(cfg, st, "vol.hold", {"dir": direction, "ms": ms})
                out(f"[ROKU] Volume {direction} hold {ms}ms")
                hold_key(dev, retries, keyname, ms)
                return 0

            if sub == "normalize":
                if len(argv) < 3:
                    usage(1)
                profile = argv[2].lower()
                if profile == "night":
                    return run_macro(cfg, st, dev, retries, "vol_normalize_night")
                if profile == "day":
                    return run_macro(cfg, st, dev, retries, "vol_normalize_day")
                eprint("[ROKU] Unknown normalize profile. Use night or day.")
                return 1

            if sub == "set":
                if len(argv) < 3:
                    usage(1)
                target = safe_int(argv[2], None)
                if target is None:
                    eprint("[ROKU] vol set requires an integer target.")
                    return 1

                # Clamp target to config max
                max_target = safe_int(cfg.get("behavior", {}).get("max_volume_set_target", 12), 12)
                if max_target is None:
                    max_target = 12
                if max_target < 0:
                    max_target = 0

                orig = target
                if target < 0:
                    target = 0
                if target > max_target:
                    target = max_target
                if target != orig:
                    out(f"[ROKU] clamped target {orig} -> {target} (max_volume_set_target)")

                if not ensure_or_exit_awake(cfg, dev, retries, "vol"):
                    return 0
                record_action(cfg, st, "vol.set", {"target": target})
                volume_set(cfg, dev, retries, target)
                return 0

            if sub == "zero":
                downs = safe_int(argv[2], None) if len(argv) > 2 else None
                if not ensure_or_exit_awake(cfg, dev, retries, "vol"):
                    return 0
                record_action(cfg, st, "vol.zero", {"downs": downs})
                volume_zero_out(cfg, dev, retries, downs=downs)
                return 0

            eprint("[ROKU] Unknown vol subcommand.")
            return 1

        if cmd in ("movie", "console", "work", "shutdown"):
            # treat modes as macros so you can edit them in config
            return run_macro(cfg, st, dev, retries, cmd)

        if cmd == "scene":
            if not ensure_or_exit_awake(cfg, dev, retries, "scene"):
                return 0
            cur = active_app(dev, retries)
            record_action(cfg, st, "scene", {"active_app": cur})
            if lights_allowed(cfg):
                apply_light_scene(cfg, cur, force=True)
            else:
                out("[ROKU] --lights not set. Not changing lights.")
            return 0

        if cmd == "follow":
            if len(argv) >= 2 and argv[1].lower() == "stop":
                record_action(cfg, st, "follow.stop.request", None)
                return cmd_follow_stop()
            if len(argv) >= 2 and argv[1].lower() == "status":
                return cmd_follow_status()

            # options: --poll <seconds> --daemon
            poll = None
            daemon = False
            i = 1
            while i < len(argv):
                if argv[i] == "--poll" and i + 1 < len(argv):
                    try:
                        poll = float(argv[i + 1])
                    except Exception:
                        poll = None
                    i += 2
                    continue
                if argv[i] == "--daemon":
                    daemon = True
                    i += 1
                    continue
                i += 1

            return cmd_follow_run(cfg, st, dev, retries, poll_override=poll, daemon=daemon)

        if cmd == "macro":
            if len(argv) < 2:
                usage(1)
            sub = argv[1].lower()
            if sub == "list":
                return cmd_macro_list(cfg)
            if sub == "show":
                if len(argv) < 3:
                    usage(1)
                return cmd_macro_show(cfg, argv[2])
            if sub == "run":
                if len(argv) < 3:
                    usage(1)
                return run_macro(cfg, st, dev, retries, argv[2])
            if sub == "test":
                if len(argv) < 3:
                    usage(1)
                return run_macro_dry(cfg, st, dev, retries, argv[2])
            if sub == "edit":
                return cmd_macro_edit()
            usage(1)

        if cmd == "device":
            if len(argv) < 2:
                usage(1)
            sub = argv[1].lower()
            if sub == "list":
                return cmd_device_list(cfg)
            if sub == "use":
                if len(argv) < 3:
                    usage(1)
                return cmd_device_use(cfg, argv[2])
            usage(1)

        if cmd == "discover":
            return cmd_discover(cfg, st, retries=0)

        if cmd == "config":
            sub = argv[1].lower() if len(argv) > 1 else ""
            if sub == "path":
                return cmd_config_path()
            if sub == "show":
                return cmd_config_show(cfg)
            if sub == "init":
                return cmd_config_init()
            if sub == "validate":
                return cmd_config_validate(cfg)
            usage(1)

        usage(1)

    except Exception as ex:
        record_error(cfg, st, "main", ex)
        eprint(f"[ROKU] error: {ex}")
        if G["debug"]:
            raise
        return 1

if __name__ == "__main__":
    sys.exit(main())