eeroctl 1.7.1__py3-none-any.whl

eeroctl/commands/troubleshoot.py

@@ -0,0 +1,317 @@
+"""Troubleshooting commands for the Eero CLI.
+
+Commands:
+- eero troubleshoot connectivity: Check connectivity
+- eero troubleshoot ping: Ping a host
+- eero troubleshoot trace: Traceroute to a host
+- eero troubleshoot doctor: Run diagnostic checks
+"""
+
+from typing import Optional
+
+import click
+from eero import EeroClient
+from rich.panel import Panel
+from rich.table import Table
+
+from ..context import ensure_cli_context
+from ..formatting import get_network_status_value
+from ..options import apply_options, network_option, output_option
+from ..utils import with_client
+
+
+@click.group(name="troubleshoot")
+@click.pass_context
+def troubleshoot_group(ctx: click.Context) -> None:
+    """Troubleshooting and diagnostics.
+
+    \b
+    Commands:
+      connectivity - Check network connectivity
+      ping         - Ping a target host
+      trace        - Traceroute to target
+      doctor       - Run diagnostic checks
+
+    \b
+    Examples:
+      eero troubleshoot connectivity
+      eero troubleshoot ping --target 8.8.8.8
+      eero troubleshoot doctor
+    """
+    ensure_cli_context(ctx)
+
+
+@troubleshoot_group.command(name="connectivity")
+@output_option
+@network_option
+@click.pass_context
+@with_client
+async def troubleshoot_connectivity(
+    ctx: click.Context, client: EeroClient, output: Optional[str], network_id: Optional[str]
+) -> None:
+    """Check network connectivity status."""
+    cli_ctx = apply_options(ctx, output=output, network_id=network_id)
+    console = cli_ctx.console
+
+    with cli_ctx.status("Checking connectivity..."):
+        network = await client.get_network(cli_ctx.network_id)
+        diagnostics = await client.get_diagnostics(cli_ctx.network_id)
+
+    if cli_ctx.is_structured_output():
+        data = {
+            "network_status": get_network_status_value(network),
+            "public_ip": network.public_ip,
+            "isp": network.isp_name,
+            "diagnostics": diagnostics,
+        }
+        cli_ctx.render_structured(data, "eero.troubleshoot.connectivity/v1")
+    else:
+        status = get_network_status_value(network)
+        if "online" in status.lower() or "connected" in status.lower():
+            status_display = f"[green]{status}[/green]"
+        elif "offline" in status.lower():
+            status_display = f"[red]{status}[/red]"
+        else:
+            status_display = f"[yellow]{status}[/yellow]"
+
+        content = (
+            f"[bold]Status:[/bold] {status_display}\n"
+            f"[bold]Public IP:[/bold] {network.public_ip or 'N/A'}\n"
+            f"[bold]ISP:[/bold] {network.isp_name or 'N/A'}"
+        )
+
+        # Add health info if available
+        health = getattr(network, "health", {})
+        if health:
+            internet_status = health.get("internet", {}).get("status", "Unknown")
+            content += f"\n[bold]Internet Status:[/bold] {internet_status}"
+
+        console.print(Panel(content, title="Connectivity Status", border_style="blue"))
+
+
+@troubleshoot_group.command(name="ping")
+@click.option("--target", "-t", required=True, help="Target host or IP")
+@click.option("--from", "from_eero", help="Eero node to ping from (ID or name)")
+@output_option
+@network_option
+@click.pass_context
+@with_client
+async def troubleshoot_ping(
+    ctx: click.Context,
+    client: EeroClient,
+    target: str,
+    from_eero: Optional[str],
+    output: Optional[str],
+    network_id: Optional[str],
+) -> None:
+    """Ping a target host.
+
+    Note: This is a placeholder - actual ping functionality
+    depends on Eero API support.
+
+    \b
+    Options:
+      --target, -t  Target host or IP (required)
+      --from        Eero node to ping from
+    """
+    cli_ctx = apply_options(ctx, output=output, network_id=network_id)
+    console = cli_ctx.console
+
+    console.print(
+        "[yellow]Note: Direct ping functionality may not be available in Eero API[/yellow]"
+    )
+    console.print(f"[dim]Target: {target}[/dim]")
+    if from_eero:
+        console.print(f"[dim]From: {from_eero}[/dim]")
+
+    with cli_ctx.status("Running diagnostics..."):
+        diagnostics = await client.get_diagnostics(cli_ctx.network_id)
+
+    if cli_ctx.is_structured_output():
+        cli_ctx.render_structured(
+            {
+                "target": target,
+                "from_eero": from_eero,
+                "note": "Direct ping not available via API",
+                "diagnostics": diagnostics,
+            },
+            "eero.troubleshoot.ping/v1",
+        )
+    else:
+        console.print(
+            Panel(
+                f"[bold]Target:[/bold] {target}\n"
+                f"[bold]From:[/bold] {from_eero or 'gateway'}\n\n"
+                "[dim]Ping results would appear here if API supports it.[/dim]\n"
+                "[dim]Use `eero troubleshoot doctor` for full diagnostics.[/dim]",
+                title="Ping",
+                border_style="blue",
+            )
+        )
+
+
+@troubleshoot_group.command(name="trace")
+@click.option("--target", "-t", required=True, help="Target host or IP")
+@click.option("--from", "from_eero", help="Eero node to trace from (ID or name)")
+@output_option
+@network_option
+@click.pass_context
+@with_client
+async def troubleshoot_trace(
+    ctx: click.Context,
+    client: EeroClient,
+    target: str,
+    from_eero: Optional[str],
+    output: Optional[str],
+    network_id: Optional[str],
+) -> None:
+    """Traceroute to a target host.
+
+    Note: This is a placeholder - actual traceroute functionality
+    depends on Eero API support.
+
+    \b
+    Options:
+      --target, -t  Target host or IP (required)
+      --from        Eero node to trace from
+    """
+    cli_ctx = apply_options(ctx, output=output, network_id=network_id)
+    console = cli_ctx.console
+
+    console.print(
+        "[yellow]Note: Direct traceroute functionality may not be available in Eero API[/yellow]"
+    )
+    console.print(f"[dim]Target: {target}[/dim]")
+
+    with cli_ctx.status("Running diagnostics..."):
+        # diagnostics not currently used but may be needed for full trace support
+        _ = await client.get_diagnostics(cli_ctx.network_id)
+        routing = await client.get_routing(cli_ctx.network_id)
+
+    if cli_ctx.is_structured_output():
+        cli_ctx.render_structured(
+            {
+                "target": target,
+                "from_eero": from_eero,
+                "note": "Direct traceroute not available via API",
+                "routing": routing,
+            },
+            "eero.troubleshoot.trace/v1",
+        )
+    else:
+        console.print(
+            Panel(
+                f"[bold]Target:[/bold] {target}\n"
+                f"[bold]From:[/bold] {from_eero or 'gateway'}\n\n"
+                "[dim]Traceroute results would appear here if API supports it.[/dim]\n"
+                "[dim]Use `eero network routing` for routing information.[/dim]",
+                title="Traceroute",
+                border_style="blue",
+            )
+        )
+
+
+@troubleshoot_group.command(name="doctor")
+@output_option
+@network_option
+@click.pass_context
+@with_client
+async def troubleshoot_doctor(
+    ctx: click.Context, client: EeroClient, output: Optional[str], network_id: Optional[str]
+) -> None:
+    """Run diagnostic checks on the network.
+
+    Performs a comprehensive health check of your Eero network
+    including connectivity, mesh health, and configuration.
+    """
+    cli_ctx = apply_options(ctx, output=output, network_id=network_id)
+    console = cli_ctx.console
+
+    checks = []
+
+    with cli_ctx.status("Running diagnostics..."):
+        # Check network status
+        try:
+            network = await client.get_network(cli_ctx.network_id)
+            status = get_network_status_value(network)
+            if "online" in status.lower() or "connected" in status.lower():
+                checks.append(("Network Status", "pass", status))
+            else:
+                checks.append(("Network Status", "fail", status))
+        except Exception as e:
+            checks.append(("Network Status", "fail", str(e)))
+
+        # Check eeros
+        try:
+            eeros = await client.get_eeros(cli_ctx.network_id)
+            online_count = sum(1 for e in eeros if e.status == "green")
+            total_count = len(eeros)
+            if online_count == total_count:
+                checks.append(("Mesh Nodes", "pass", f"{online_count}/{total_count} online"))
+            elif online_count > 0:
+                checks.append(("Mesh Nodes", "warn", f"{online_count}/{total_count} online"))
+            else:
+                checks.append(("Mesh Nodes", "fail", f"0/{total_count} online"))
+        except Exception as e:
+            checks.append(("Mesh Nodes", "fail", str(e)))
+
+        # Check devices
+        try:
+            devices = await client.get_devices(cli_ctx.network_id)
+            connected = sum(1 for d in devices if d.connected)
+            checks.append(("Connected Devices", "info", f"{connected} devices"))
+        except Exception as e:
+            checks.append(("Connected Devices", "warn", str(e)))
+
+        # Check diagnostics
+        try:
+            _ = await client.get_diagnostics(cli_ctx.network_id)
+            checks.append(("Diagnostics API", "pass", "Available"))
+        except Exception:
+            checks.append(("Diagnostics API", "warn", "Not available"))
+
+        # Check premium status
+        try:
+            is_premium = await client.is_premium(cli_ctx.network_id)
+            checks.append(("Eero Plus", "info", "Active" if is_premium else "Not active"))
+        except Exception:
+            checks.append(("Eero Plus", "info", "Unknown"))
+
+    if cli_ctx.is_structured_output():
+        data = {
+            "checks": [
+                {"name": name, "status": status, "message": msg} for name, status, msg in checks
+            ],
+            "overall": "pass" if all(s != "fail" for _, s, _ in checks) else "fail",
+        }
+        cli_ctx.render_structured(data, "eero.troubleshoot.doctor/v1")
+    else:
+        table = Table(title="Network Health Check")
+        table.add_column("Check", style="cyan")
+        table.add_column("Status", justify="center")
+        table.add_column("Details")
+
+        for name, status, message in checks:
+            if status == "pass":
+                status_display = "[green]✓ PASS[/green]"
+            elif status == "fail":
+                status_display = "[red]✗ FAIL[/red]"
+            elif status == "warn":
+                status_display = "[yellow]⚠ WARN[/yellow]"
+            else:
+                status_display = "[blue]ℹ INFO[/blue]"
+
+            table.add_row(name, status_display, message)
+
+        console.print(table)
+
+        # Overall status
+        has_failures = any(s == "fail" for _, s, _ in checks)
+        has_warnings = any(s == "warn" for _, s, _ in checks)
+
+        if has_failures:
+            console.print("\n[bold red]⚠ Issues detected. Review the checks above.[/bold red]")
+        elif has_warnings:
+            console.print("\n[bold yellow]⚠ Some warnings detected.[/bold yellow]")
+        else:
+            console.print("\n[bold green]✓ All checks passed![/bold green]")

eeroctl/context.py

@@ -0,0 +1,254 @@
+"""CLI context management.
+
+This module provides a context object that is passed through Click commands
+to share state like the client, output settings, and global flags.
+"""
+
+from contextlib import nullcontext
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, ContextManager, Dict, Optional
+
+import click
+from eero import EeroClient
+from rich.console import Console
+
+from .output import DetailLevel, OutputContext, OutputFormat, OutputManager, OutputRenderer
+
+if TYPE_CHECKING:
+    pass
+
+
+@dataclass
+class EeroCliContext:
+    """Context object to pass shared resources to Click commands."""
+
+    # Core components
+    client: Optional[EeroClient] = None
+    console: Console = field(default_factory=Console)
+    err_console: Console = field(default_factory=lambda: Console(stderr=True))
+    output_manager: Optional[OutputManager] = None
+
+    # Network selection
+    network_id: Optional[str] = None
+
+    # Output settings
+    output_format: str = "table"  # table, list, json
+    detail_level: str = "brief"  # brief, full
+
+    # Safety and interaction flags
+    non_interactive: bool = False
+    force: bool = False
+    dry_run: bool = False
+    quiet: bool = False
+    no_color: bool = False
+
+    # Debug/logging flags
+    debug: bool = False
+    verbose: bool = False
+
+    # Retry/timeout settings
+    timeout: Optional[int] = None
+    retries: Optional[int] = None
+    retry_backoff: Optional[int] = None
+
+    # Additional storage for subcommand state
+    _extra: Dict[str, Any] = field(default_factory=dict)
+
+    # Cached renderer instance
+    _renderer: Optional[OutputRenderer] = field(default=None, repr=False)
+
+    def __post_init__(self):
+        """Initialize derived components."""
+        if self.output_manager is None:
+            self.output_manager = OutputManager(self.console)
+
+    @property
+    def renderer(self) -> OutputRenderer:
+        """Get the output renderer for this context."""
+        if self._renderer is None:
+            output_ctx = OutputContext(
+                format=(
+                    OutputFormat(self.output_format)
+                    if self.output_format in ("table", "list", "json", "yaml", "text")
+                    else OutputFormat.TABLE
+                ),
+                detail=(
+                    DetailLevel(self.detail_level)
+                    if self.detail_level in ("brief", "full")
+                    else DetailLevel.BRIEF
+                ),
+                quiet=self.quiet,
+                no_color=self.no_color,
+                network_id=self.network_id,
+            )
+            self._renderer = OutputRenderer(output_ctx)
+        return self._renderer
+
+    def is_json_output(self) -> bool:
+        """Check if output format is JSON."""
+        return self.output_format == "json"
+
+    def is_yaml_output(self) -> bool:
+        """Check if output format is YAML."""
+        return self.output_format == "yaml"
+
+    def is_text_output(self) -> bool:
+        """Check if output format is plain text."""
+        return self.output_format == "text"
+
+    def is_structured_output(self) -> bool:
+        """Check if output format is a structured format (JSON, YAML, or text)."""
+        return self.output_format in ("json", "yaml", "text")
+
+    def status(self, message: str) -> ContextManager:
+        """Return a status spinner context manager, but only for table output.
+
+        For parseable outputs (json, yaml, list, text), returns a no-op context
+        to avoid polluting the output with status messages.
+
+        Args:
+            message: Status message to display
+
+        Returns:
+            Status context manager or nullcontext
+        """
+        if self.output_format == "table":
+            return self.console.status(message)
+        return nullcontext()
+
+    def render_structured(self, data: Any, schema: str) -> None:
+        """Render data in the current structured format (JSON, YAML, or text).
+
+        Args:
+            data: Data to render (dict or list)
+            schema: Schema identifier for envelope
+        """
+        if self.is_json_output():
+            self.renderer.render_json(data, schema)
+        elif self.is_yaml_output():
+            self.renderer.render_yaml(data, schema)
+        else:
+            self.renderer.render_text(data, schema)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a value from extra storage."""
+        return self._extra.get(key, default)
+
+    def set(self, key: str, value: Any) -> None:
+        """Set a value in extra storage."""
+        self._extra[key] = value
+
+    def __getitem__(self, key: str) -> Any:
+        """Get a value from extra storage using [] syntax."""
+        return self._extra.get(key)
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        """Set a value in extra storage using [] syntax."""
+        self._extra[key] = value
+
+
+def ensure_cli_context(ctx: click.Context) -> EeroCliContext:
+    """Ensure the Click context has an EeroCliContext object.
+
+    If ctx.obj is None or not an EeroCliContext, creates a new one.
+
+    Args:
+        ctx: Click context
+
+    Returns:
+        The EeroCliContext object
+    """
+    if ctx.obj is None or not isinstance(ctx.obj, EeroCliContext):
+        ctx.obj = EeroCliContext()
+    return ctx.obj
+
+
+def get_cli_context(ctx: click.Context) -> EeroCliContext:
+    """Get the EeroCliContext from a Click context.
+
+    Args:
+        ctx: Click context
+
+    Returns:
+        The EeroCliContext object
+
+    Raises:
+        RuntimeError: If no EeroCliContext is found
+    """
+    if ctx.obj is None:
+        # Try to find it in parent contexts
+        parent = ctx.parent
+        while parent is not None:
+            if isinstance(parent.obj, EeroCliContext):
+                return parent.obj
+            parent = parent.parent
+        # Create a default one if not found
+        ctx.obj = EeroCliContext()
+
+    if not isinstance(ctx.obj, EeroCliContext):
+        raise RuntimeError(
+            f"Expected EeroCliContext but got {type(ctx.obj).__name__}. "
+            "Make sure the CLI is properly initialized."
+        )
+
+    return ctx.obj
+
+
+def create_cli_context(
+    debug: bool = False,
+    verbose: bool = False,
+    output_format: str = "table",
+    detail_level: str = "brief",
+    network_id: Optional[str] = None,
+    non_interactive: bool = False,
+    force: bool = False,
+    dry_run: bool = False,
+    quiet: bool = False,
+    no_color: bool = False,
+    timeout: Optional[int] = None,
+    retries: Optional[int] = None,
+    retry_backoff: Optional[int] = None,
+) -> EeroCliContext:
+    """Create a new CLI context with the given settings.
+
+    Factory function for creating an EeroCliContext with specific options.
+    Used primarily by the main CLI entry point.
+
+    Args:
+        debug: Enable debug logging.
+        verbose: Enable verbose output.
+        output_format: Output format (table, list, json).
+        detail_level: Detail level (brief, full).
+        network_id: Network ID to use.
+        non_interactive: Never prompt for input.
+        force: Skip confirmation prompts.
+        dry_run: Show what would happen without making changes.
+        quiet: Suppress non-essential output.
+        no_color: Disable colored output.
+        timeout: Request timeout in seconds.
+        retries: Number of retries for failed requests.
+        retry_backoff: Backoff time between retries in milliseconds.
+
+    Returns:
+        A configured EeroCliContext instance.
+    """
+    console = Console(force_terminal=not no_color, no_color=no_color, quiet=quiet)
+
+    return EeroCliContext(
+        client=None,  # Will be initialized later
+        console=console,
+        output_manager=OutputManager(console),
+        network_id=network_id,
+        output_format=output_format,
+        detail_level=detail_level,
+        non_interactive=non_interactive,
+        force=force,
+        dry_run=dry_run,
+        quiet=quiet,
+        no_color=no_color,
+        debug=debug,
+        verbose=verbose,
+        timeout=timeout,
+        retries=retries,
+        retry_backoff=retry_backoff,
+    )