router-cli 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

router_cli/commands.py

@@ -0,0 +1,227 @@
+"""Command handlers for the router CLI."""
+
+import json
+import sys
+from dataclasses import asdict
+
+from .client import (
+    AuthenticationError,
+    ConnectionError,
+    HTTPError,
+    RouterClient,
+    RouterError,
+)
+from .config import KnownDevices
+from .display import spinner
+from .formatters import (
+    format_clients,
+    format_dhcp,
+    format_logs,
+    format_overview,
+    format_routes,
+    format_stats,
+    format_status,
+)
+
+
+def _handle_error(e: Exception, json_output: bool = False) -> int:
+    """Handle exceptions and print user-friendly error messages.
+
+    Returns the exit code to use.
+    """
+    error_info = {"error": str(e), "type": type(e).__name__}
+
+    if isinstance(e, AuthenticationError):
+        error_info["hint"] = "Check your username/password in the config file."
+        error_info["code"] = 2
+    elif isinstance(e, ConnectionError):
+        error_info["hint"] = "Ensure the router is reachable and the IP is correct."
+        error_info["code"] = 3
+    elif isinstance(e, HTTPError):
+        error_info["code"] = 4
+        if e.status_code == 503:
+            error_info["hint"] = "The router may be busy. Wait a moment and try again."
+        error_info["status_code"] = e.status_code
+    elif isinstance(e, RouterError):
+        error_info["code"] = 1
+    else:
+        error_info["code"] = 1
+
+    if json_output:
+        print(json.dumps(error_info, indent=2), file=sys.stderr)
+    else:
+        if isinstance(e, AuthenticationError):
+            print(f"Authentication error: {e}", file=sys.stderr)
+            print(
+                "  Hint: Check your username/password in the config file.",
+                file=sys.stderr,
+            )
+        elif isinstance(e, ConnectionError):
+            print(f"Connection error: {e}", file=sys.stderr)
+            print(
+                "  Hint: Ensure the router is reachable and the IP is correct.",
+                file=sys.stderr,
+            )
+        elif isinstance(e, HTTPError):
+            print(f"Router error: {e}", file=sys.stderr)
+            if e.status_code == 503:
+                print(
+                    "  Hint: The router may be busy. Wait a moment and try again.",
+                    file=sys.stderr,
+                )
+        elif isinstance(e, RouterError):
+            print(f"Router error: {e}", file=sys.stderr)
+        else:
+            print(f"Unexpected error ({type(e).__name__}): {e}", file=sys.stderr)
+
+    return error_info["code"]
+
+
+def _to_json(obj) -> str:
+    """Convert dataclass or list of dataclasses to JSON."""
+    if isinstance(obj, list):
+        return json.dumps([asdict(item) for item in obj], indent=2)
+    return json.dumps(asdict(obj), indent=2)
+
+
+def cmd_status(client: RouterClient, json_output: bool = False) -> int:
+    """Execute status command."""
+    try:
+        with spinner("Fetching router status..."):
+            status = client.get_status()
+        if json_output:
+            # Convert WANConnection objects to dicts for JSON
+            data = asdict(status)
+            print(json.dumps(data, indent=2))
+        else:
+            print(format_status(status))
+        return 0
+    except Exception as e:
+        return _handle_error(e, json_output)
+
+
+def cmd_reboot(client: RouterClient) -> int:
+    """Execute reboot command."""
+    try:
+        with spinner("Sending reboot command..."):
+            client.reboot()
+        print("Reboot command sent successfully.")
+        print("The router will restart in a few seconds.")
+        return 0
+    except Exception as e:
+        return _handle_error(e)
+
+
+def cmd_clients(
+    client: RouterClient, known_devices: KnownDevices, json_output: bool = False
+) -> int:
+    """Execute clients command."""
+    try:
+        with spinner("Fetching wireless clients..."):
+            clients = client.get_wireless_clients()
+        if json_output:
+            print(_to_json(clients))
+        else:
+            print(format_clients(clients, known_devices))
+        return 0
+    except Exception as e:
+        return _handle_error(e, json_output)
+
+
+def cmd_dhcp(
+    client: RouterClient, known_devices: KnownDevices, json_output: bool = False
+) -> int:
+    """Execute dhcp command."""
+    try:
+        with spinner("Fetching DHCP leases..."):
+            leases = client.get_dhcp_leases()
+        if json_output:
+            print(_to_json(leases))
+        else:
+            print(format_dhcp(leases, known_devices))
+        return 0
+    except Exception as e:
+        return _handle_error(e, json_output)
+
+
+def cmd_routes(client: RouterClient, json_output: bool = False) -> int:
+    """Execute routes command."""
+    try:
+        with spinner("Fetching routing table..."):
+            routes = client.get_routes()
+        if json_output:
+            print(_to_json(routes))
+        else:
+            print(format_routes(routes))
+        return 0
+    except Exception as e:
+        return _handle_error(e, json_output)
+
+
+def cmd_stats(client: RouterClient, json_output: bool = False) -> int:
+    """Execute stats command."""
+    try:
+        with spinner("Fetching network statistics..."):
+            stats = client.get_statistics()
+        if json_output:
+            print(_to_json(stats))
+        else:
+            print(format_stats(stats))
+        return 0
+    except Exception as e:
+        return _handle_error(e, json_output)
+
+
+def cmd_logs(
+    client: RouterClient,
+    tail: int | None = None,
+    level: str | None = None,
+    json_output: bool = False,
+) -> int:
+    """Execute logs command."""
+    try:
+        with spinner("Fetching system logs..."):
+            logs = client.get_logs()
+
+        # Filter by severity level if specified
+        if level:
+            level_upper = level.upper()
+            logs = [log for log in logs if log.severity.upper() == level_upper]
+
+        # Limit to last N entries if tail specified
+        if tail and tail > 0:
+            logs = logs[-tail:]
+
+        if json_output:
+            print(_to_json(logs))
+        else:
+            print(format_logs(logs))
+        return 0
+    except Exception as e:
+        return _handle_error(e, json_output)
+
+
+def cmd_overview(
+    client: RouterClient, known_devices: KnownDevices, json_output: bool = False
+) -> int:
+    """Execute overview command."""
+    try:
+        with spinner("Fetching router overview..."):
+            status = client.get_status()
+            clients = client.get_wireless_clients()
+            leases = client.get_dhcp_leases()
+            stats = client.get_statistics()
+
+        if json_output:
+            data = {
+                "status": asdict(status),
+                "wireless_clients": [asdict(c) for c in clients],
+                "dhcp_leases": [asdict(lease) for lease in leases],
+                "statistics": asdict(stats),
+            }
+            print(json.dumps(data, indent=2))
+        else:
+            print(format_overview(status, clients, leases, stats, known_devices))
+        return 0
+    except Exception as e:
+        return _handle_error(e, json_output)

router_cli/config.py

@@ -1,5 +1,6 @@
 """Configuration loading for router CLI."""
 
+import os
 import sys
 from pathlib import Path
 
@@ -9,6 +10,11 @@ else:
     import tomli as tomllib
 
 
+# Default configuration values
+DEFAULT_IP = "192.168.1.1"
+DEFAULT_USERNAME = "admin"
+
+
 def get_config_paths() -> list[Path]:
     """Return list of config file paths in order of priority."""
     return [
@@ -27,40 +33,164 @@ def _load_config_file() -> dict | None:
     return None
 
 
-def load_config() -> dict:
-    """Load configuration from TOML file.
+def load_config(
+    cli_ip: str | None = None,
+    cli_user: str | None = None,
+    cli_pass: str | None = None,
+) -> dict:
+    """Load configuration with priority: CLI args > env vars > config file > defaults.
+
+    Args:
+        cli_ip: IP address from CLI argument (highest priority)
+        cli_user: Username from CLI argument
+        cli_pass: Password from CLI argument
 
-    Searches for config in:
-    1. ./config.toml (current directory)
-    2. ~/.config/router/config.toml
-    3. /etc/router/config.toml
+    Environment variables:
+        ROUTER_IP: Router IP address
+        ROUTER_USER: Username for authentication
+        ROUTER_PASS: Password for authentication
+
+    Config file locations (in order of priority):
+        1. ./config.toml (current directory)
+        2. ~/.config/router/config.toml
+        3. /etc/router/config.toml
     """
-    config = _load_config_file()
-    if config is not None:
-        return config.get("router", {})
-
-    raise FileNotFoundError(
-        "No config.toml found. Create one at ~/.config/router/config.toml with:\n"
-        "[router]\n"
-        'ip = "192.168.1.1"\n'
-        'username = "admin"\n'
-        'password = "your_password"\n'
-        "\n"
-        "[known_devices]\n"
-        '"AA:BB:CC:DD:EE:FF" = "My Phone"\n'
-        '"11:22:33:44:55:66" = "Smart TV"'
-    )
-
-
-def load_known_devices() -> dict[str, str]:
+    # Start with defaults
+    config: dict[str, str] = {
+        "ip": DEFAULT_IP,
+        "username": DEFAULT_USERNAME,
+        "password": "",
+    }
+
+    # Layer 1: Config file (lowest priority for file-based config)
+    file_config = _load_config_file()
+    if file_config is not None:
+        router_config = file_config.get("router", {})
+        config.update(router_config)
+
+    # Layer 2: Environment variables
+    if os.environ.get("ROUTER_IP"):
+        config["ip"] = os.environ["ROUTER_IP"]
+    if os.environ.get("ROUTER_USER"):
+        config["username"] = os.environ["ROUTER_USER"]
+    if os.environ.get("ROUTER_PASS"):
+        config["password"] = os.environ["ROUTER_PASS"]
+
+    # Layer 3: CLI arguments (highest priority)
+    if cli_ip:
+        config["ip"] = cli_ip
+    if cli_user:
+        config["username"] = cli_user
+    if cli_pass:
+        config["password"] = cli_pass
+
+    # Require password from some source
+    if not config.get("password"):
+        # Check if we have a config file - if not, show helpful error
+        if file_config is None and not os.environ.get("ROUTER_PASS"):
+            raise FileNotFoundError(
+                "No password configured. Either:\n"
+                "  1. Create ~/.config/router/config.toml with:\n"
+                "     [router]\n"
+                '     ip = "192.168.1.1"\n'
+                '     username = "admin"\n'
+                '     password = "your_password"\n'
+                "\n"
+                "  2. Set environment variables:\n"
+                "     export ROUTER_PASS=your_password\n"
+                "\n"
+                "  3. Use CLI flags:\n"
+                "     router --pass your_password status"
+            )
+
+    return config
+
+
+def _is_mac_address(identifier: str) -> bool:
+    """Check if a string looks like a MAC address.
+
+    MAC addresses contain colons and are in format XX:XX:XX:XX:XX:XX
+    """
+    import re
+
+    # Match typical MAC address formats (with colons)
+    return bool(re.match(r"^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$", identifier))
+
+
+class KnownDevices:
+    """Container for known devices, supporting lookup by MAC or hostname.
+
+    This class supports devices that use random MAC addresses by allowing
+    hostname-based identification in addition to MAC-based.
+    """
+
+    def __init__(
+        self,
+        by_mac: dict[str, str] | None = None,
+        by_hostname: dict[str, str] | None = None,
+    ):
+        self.by_mac: dict[str, str] = by_mac or {}
+        self.by_hostname: dict[str, str] = by_hostname or {}
+
+    def get_alias(self, mac: str, hostname: str = "") -> str | None:
+        """Get alias for a device by MAC or hostname.
+
+        MAC lookup takes priority. Returns None if device is not known.
+        """
+        # First try MAC lookup (normalized to uppercase)
+        alias = self.by_mac.get(mac.upper())
+        if alias:
+            return alias
+
+        # Then try hostname lookup (case-insensitive)
+        if hostname:
+            alias = self.by_hostname.get(hostname.lower())
+            if alias:
+                return alias
+
+        return None
+
+    def is_known(self, mac: str, hostname: str = "") -> bool:
+        """Check if a device is known by MAC or hostname."""
+        return self.get_alias(mac, hostname) is not None
+
+    def get(self, key: str, default: str | None = None) -> str | None:
+        """Dict-like get for backward compatibility (MAC lookup only)."""
+        return self.by_mac.get(key, default)
+
+    def __contains__(self, key: str) -> bool:
+        """Dict-like contains for backward compatibility (MAC lookup only)."""
+        return key in self.by_mac
+
+
+def load_known_devices() -> KnownDevices:
     """Load known devices from config file.
 
-    Returns a dict mapping MAC addresses (uppercase) to aliases.
+    Returns a KnownDevices object supporting lookup by MAC address or hostname.
+
+    Config format:
+        [known_devices]
+        "AA:BB:CC:DD:EE:FF" = "My Phone"      # MAC-based (for stable MACs)
+        "android-abc123" = "John's Pixel"     # Hostname-based (for random MACs)
+
+    MAC addresses are identified by format (XX:XX:XX:XX:XX:XX with colons).
+    Any other identifier is treated as a hostname.
     """
     config = _load_config_file()
     if config is None:
-        return {}
+        return KnownDevices()
 
     known = config.get("known_devices", {})
-    # Normalize MAC addresses to uppercase for case-insensitive matching
-    return {mac.upper(): alias for mac, alias in known.items()}
+
+    by_mac: dict[str, str] = {}
+    by_hostname: dict[str, str] = {}
+
+    for identifier, alias in known.items():
+        if _is_mac_address(identifier):
+            # MAC address - normalize to uppercase
+            by_mac[identifier.upper()] = alias
+        else:
+            # Hostname - normalize to lowercase for case-insensitive matching
+            by_hostname[identifier.lower()] = alias
+
+    return KnownDevices(by_mac=by_mac, by_hostname=by_hostname)

router_cli/display.py

@@ -0,0 +1,191 @@
+"""Display utilities for terminal output."""
+
+import re
+import sys
+import threading
+from contextlib import contextmanager
+
+from .config import KnownDevices
+
+
+# ANSI color codes
+_COLORS = {
+    "green": "\033[32m",
+    "red": "\033[31m",
+    "yellow": "\033[33m",
+    "reset": "\033[0m",
+}
+
+
+def colorize(text: str, color: str) -> str:
+    """Apply ANSI color to text if stdout is a TTY."""
+    if not sys.stdout.isatty():
+        return text
+    return f"{_COLORS.get(color, '')}{text}{_COLORS['reset']}"
+
+
+# Spinner frames - braille pattern for smooth animation
+_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+_SPINNER_INTERVAL = 0.08  # seconds between frames
+
+
+@contextmanager
+def spinner(message: str = "Loading..."):
+    """Display an animated spinner while waiting for an operation.
+
+    Usage:
+        with spinner("Fetching status..."):
+            result = client.get_status()
+
+    Only displays spinner if stdout is a TTY.
+    """
+    if not sys.stdout.isatty():
+        # Not a TTY, just run without spinner
+        yield
+        return
+
+    stop_event = threading.Event()
+    spinner_thread = None
+
+    def animate():
+        frame_idx = 0
+        # Hide cursor
+        sys.stdout.write("\033[?25l")
+        sys.stdout.flush()
+
+        while not stop_event.is_set():
+            frame = _SPINNER_FRAMES[frame_idx % len(_SPINNER_FRAMES)]
+            # Write spinner frame and message, then return cursor to start
+            sys.stdout.write(f"\r{frame} {message}")
+            sys.stdout.flush()
+            frame_idx += 1
+            stop_event.wait(_SPINNER_INTERVAL)
+
+        # Clear the spinner line
+        sys.stdout.write("\r" + " " * (len(message) + 3) + "\r")
+        # Show cursor
+        sys.stdout.write("\033[?25h")
+        sys.stdout.flush()
+
+    try:
+        spinner_thread = threading.Thread(target=animate, daemon=True)
+        spinner_thread.start()
+        yield
+    finally:
+        stop_event.set()
+        if spinner_thread:
+            spinner_thread.join(timeout=0.5)
+
+
+def format_bytes(num_bytes: int) -> str:
+    """Format bytes as human-readable string."""
+    for unit in ["B", "KB", "MB", "GB", "TB"]:
+        if abs(num_bytes) < 1024:
+            return f"{num_bytes:.1f} {unit}"
+        num_bytes /= 1024
+    return f"{num_bytes:.1f} PB"
+
+
+def format_expires(expires_in: str) -> str:
+    """Convert verbose expires string to compact HH:MM:SS format.
+
+    Input: "22 hours, 27 minutes, 15 seconds"
+    Output: "22:27:15"
+    """
+    hours = minutes = seconds = 0
+
+    h_match = re.search(r"(\d+)\s*hour", expires_in)
+    m_match = re.search(r"(\d+)\s*minute", expires_in)
+    s_match = re.search(r"(\d+)\s*second", expires_in)
+
+    if h_match:
+        hours = int(h_match.group(1))
+    if m_match:
+        minutes = int(m_match.group(1))
+    if s_match:
+        seconds = int(s_match.group(1))
+
+    return f"{hours:02d}:{minutes:02d}:{seconds:02d}"
+
+
+def get_device_display(
+    mac: str, hostname: str, known_devices: KnownDevices | None
+) -> tuple[str, bool]:
+    """Get display name for a device and whether it's known.
+
+    Returns (display_name, is_known) tuple.
+    If known, display_name is 'Alias (hostname)'.
+
+    Supports lookup by both MAC address and hostname (for devices with
+    random MAC addresses like some Android phones).
+    """
+    if known_devices is None:
+        return hostname or mac, False
+
+    alias = known_devices.get_alias(mac, hostname)
+    if alias:
+        if hostname and hostname != alias:
+            return f"{alias} ({hostname})", True
+        return alias, True
+    return hostname or mac, False
+
+
+def format_table(
+    headers: list[str],
+    rows: list[list[str]],
+    row_colors: list[str | None] | None = None,
+    padding: int = 2,
+) -> str:
+    """Format data as an aligned table with optional row coloring.
+
+    Args:
+        headers: Column header labels
+        rows: List of rows, each row is a list of cell values
+        row_colors: Optional list of color names (one per row), None for no color
+        padding: Extra padding to add to column widths
+
+    Returns:
+        Formatted table as a string
+
+    Example:
+        >>> format_table(
+        ...     ["Name", "Value"],
+        ...     [["foo", "123"], ["bar", "456"]],
+        ...     row_colors=["green", "red"]
+        ... )
+    """
+    if not rows:
+        return ""
+
+    # Calculate column widths based on headers and data
+    widths = [len(h) for h in headers]
+    for row in rows:
+        for i, val in enumerate(row):
+            if i < len(widths):
+                widths[i] = max(widths[i], len(str(val)))
+
+    # Add padding
+    widths = [w + padding for w in widths]
+
+    # Build header line
+    header_line = "".join(h.ljust(widths[i]) for i, h in enumerate(headers))
+
+    # Build separator line
+    sep_line = "".join(("-" * (w - padding)).ljust(w) for w in widths)
+
+    # Build data lines
+    lines = [header_line, sep_line]
+
+    for row_idx, row in enumerate(rows):
+        line = "".join(
+            str(val).ljust(widths[i]) if i < len(widths) else str(val)
+            for i, val in enumerate(row)
+        )
+
+        # Apply color if specified
+        if row_colors and row_idx < len(row_colors) and row_colors[row_idx]:
+            line = colorize(line, row_colors[row_idx])
+
+        lines.append(line)
+
+    return "\n".join(lines)