exosphere-cli 0.9.9__py3-none-any.whl

exosphere/__init__.py

@@ -0,0 +1,14 @@
+import importlib.metadata
+
+from .config import Configuration
+
+# Global Instances: configuration and GlobalState
+# These are set at runtime and should be used as singletons
+# to hold the global state and configuration.
+
+app_config = Configuration()  # Has default values out of the box
+
+# Current software version, imported from pyproject metadata
+__version__ = importlib.metadata.version("exosphere_cli")
+
+__all__ = ["__version__", "app_config"]

exosphere/cli.py

@@ -0,0 +1,129 @@
+import logging
+import sys
+from typing import Annotated
+
+# ------------------win32 readline monkeypatch---------------------
+if sys.platform == "win32":
+    try:
+        # On windows, we use a wrapper module for pyreadline3 in order
+        # to provide readline compatibility.
+        from exosphere.compat import win32readline as readline
+
+        # This needs monkeypatched in order for click_shell to make use
+        # of it instead of its internal, broken, legacy pyreadline.
+        sys.modules["readline"] = readline
+    except ImportError:
+        sys.stderr.write(
+            "Warning: pyreadline3 not found. "
+            "Interactive shell may not enable all features.\n"
+        )
+# -----------------------------------------------------------------
+
+from click_shell import make_click_shell
+from rich import print
+from rich.panel import Panel
+from typer import Argument, Context, Exit, Typer
+
+from exosphere import __version__
+from exosphere.commands import config, host, inventory, ui
+
+banner = f"""[turquoise4]
+                         ▗▖
+                         ▐▌
+ ▟█▙ ▝█ █▘ ▟█▙ ▗▟██▖▐▙█▙ ▐▙██▖ ▟█▙  █▟█▌ ▟█▙
+▐▙▄▟▌ ▐█▌ ▐▛ ▜▌▐▙▄▖▘▐▛ ▜▌▐▛ ▐▌▐▙▄▟▌ █▘  ▐▙▄▟▌
+▐▛▀▀▘ ▗█▖ ▐▌ ▐▌ ▀▀█▖▐▌ ▐▌▐▌ ▐▌▐▛▀▀▘ █   ▐▛▀▀▘
+▝█▄▄▌ ▟▀▙ ▝█▄█▘▐▄▄▟▌▐█▄█▘▐▌ ▐▌▝█▄▄▌ █   ▝█▄▄▌
+ ▝▀▀ ▝▀ ▀▘ ▝▀▘  ▀▀▀ ▐▌▀▘ ▝▘ ▝▘ ▝▀▀  ▀    ▝▀▀
+                    ▐▌ [green]v{__version__}[/green][/turquoise4]
+"""
+
+app = Typer(
+    no_args_is_help=False,
+)
+
+# Setup commands from modules
+app.add_typer(inventory.app, name="inventory")
+app.add_typer(host.app, name="host")
+app.add_typer(ui.app, name="ui")
+app.add_typer(config.app, name="config")
+
+
+@app.command(hidden=True)
+def help(ctx: Context, command: Annotated[str | None, Argument()] = None):
+    """
+    Help for interactive REPL use
+
+    Provides help for the root REPL command when used interactively,
+    in a way that is friendler for that specific context.
+    If a command is specified, it will show help for that command.
+
+    This only applies when in the interactive REPL, commands (including
+    the root 'exosphere' program) will use the standard Typer help
+    system when invoked from the command line or non-interactively.
+    """
+
+    msg = "\nUse '<command> --help' or 'help <command>' for help on a specific command."
+
+    # Show root help if no command is specified
+    if not command:
+        if ctx.parent and getattr(ctx.parent, "command", None):
+            subcommands = getattr(ctx.parent.command, "commands", {})
+            lines = []
+            for name, cmd in subcommands.items():
+                if cmd.hidden:
+                    continue
+                lines.append(
+                    f"[cyan]{name:<11}[/cyan] {cmd.help or 'No description available.'}"
+                )
+            content = "\n".join(lines)
+            panel = Panel.fit(
+                content,
+                title="Commands",
+                title_align="left",
+            )
+            print("\nAvailable modules during interactive use:\n")
+            print(panel)
+        print(msg)
+        return
+
+    # Show command help if one is specified
+    subcommand = None
+    if ctx.parent and getattr(ctx.parent, "command", None):
+        subcommands = getattr(ctx.parent.command, "commands", None)
+        subcommand = subcommands.get(command) if subcommands else None
+        if subcommand:
+            subcommand.get_help(ctx)
+            print(f"\nUse '{str(subcommand.name)} <command> --help' for more details.")
+            return
+
+    # Fall through for unknown commands
+    print(f"[red]Unkown command '{command}'[/red]")
+    print(msg)
+
+
+@app.callback(invoke_without_command=True)
+def cli(ctx: Context) -> None:
+    """
+    Exosphere CLI
+
+    The main command-line interface for Exosphere.
+    It provides a REPL interface for interactive use as a prompt, but can
+    also be used to run commands directly from the command line.
+
+    Run without arguments to start the interactive mode.
+    """
+    if ctx.invoked_subcommand is None:
+        logger = logging.getLogger(__name__)
+        logger.info("Starting Exosphere REPL interface")
+
+        # Print the banner
+        print(banner)
+
+        # Start interactive REPL
+        repl = make_click_shell(
+            ctx,
+            prompt="exosphere> ",
+        )
+        repl.cmdloop()
+        Exit(0)

exosphere/commands/config.py

@@ -0,0 +1,163 @@
+import os
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.pretty import Pretty
+from rich.text import Text
+
+from exosphere import app_config, context
+from exosphere.config import Configuration
+
+app = typer.Typer(
+    help="Runtime Configuration Commands",
+    no_args_is_help=True,
+)
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+@app.command()
+def show(
+    option: Annotated[
+        str | None,
+        typer.Argument(help="Name of the option to show. All if not specified."),
+    ] = None,
+    full: Annotated[
+        bool,
+        typer.Option(
+            "--full",
+            "-f",
+            help="Show full configuration structure, including inventory.",
+        ),
+    ] = False,
+) -> None:
+    """
+    Show the current configuration.
+
+    Displays the current configuration options, or the value of a specific option
+    if specified.
+
+    If `--full` is specified, it will show the entire configuration structure,
+    including the inventory, beyond just the "options" section.
+    """
+
+    if full:
+        if option:
+            err_console.print(
+                "[yellow]Full configuration requested, ignoring option name.[/yellow]"
+            )
+        console.print(Pretty(app_config, expand_all=True, max_depth=None))
+        return
+
+    if option:
+        if option in app_config["options"]:
+            console.print(app_config["options"][option])
+        else:
+            err_console.print(
+                f"[red]Option '{option}' not found in configuration.[/red]"
+            )
+
+        return
+
+    console.print(Pretty(app_config["options"], expand_all=True))
+
+
+@app.command()
+def source(
+    env: Annotated[
+        bool,
+        typer.Option(
+            help="Show environment variables that affect the configuration.",
+        ),
+    ] = True,
+) -> None:
+    """
+    Show the configuration source, where it was loaded from.
+
+    Displays the path of the configuration file loaded, if any, and
+    any environment variables that affect the configuration.
+    """
+
+    if context.confpath:
+        console.print(f"{context.confpath}")
+    else:
+        err_console.print("No configuration loaded, using defaults.")
+
+    if not env:
+        return
+
+    env_lines: list[str] = []
+
+    prefix = "EXOSPHERE_OPTIONS_"
+
+    for key, value in os.environ.items():
+        if (
+            key.startswith(prefix)
+            and key.removeprefix(prefix).lower() in app_config["options"]
+        ):
+            env_lines.append(f"{key}={value}")
+
+    if env_lines:
+        console.print()
+        console.print("Environment variable overrides:\n")
+        for line in env_lines:
+            console.print(f"  {line}")
+        console.print()
+
+
+@app.command()
+def diff(
+    full: Annotated[
+        bool,
+        typer.Option(
+            "--full",
+            "-f",
+            help="Show full configuration diff, including unmodified options.",
+        ),
+    ] = False,
+):
+    """
+    Show the differences between the current configuration and the defaults.
+
+    Exosphere follows convention over configuration, so your configuration
+    file can exclusively contain the options you want to change.
+
+    This command allows you to see exactly what has been changed, optionally
+    in its context, using the `--full` option.
+
+    For a full config dump, use the `show` command instead.
+    """
+
+    default_config = Configuration.DEFAULTS["options"]
+    current_config = app_config["options"]
+
+    for key in set(default_config) | set(current_config):
+        if default_config.get(key, None) != current_config.get(key, None):
+            break
+    else:
+        console.print("No differences found between current and default configuration.")
+        return
+
+    lines = []
+    for key in sorted(set(default_config) | set(current_config)):
+        default_value = default_config.get(key, None)
+        current_value = current_config.get(key, None)
+
+        line: Text | None
+
+        if default_value != current_value:
+            line = Text(f"{key!r}: {current_value!r},", style="bold green")
+            line.append(f"  # default: {default_value!r}", style="yellow")
+        else:
+            line = Text(f"{key!r}: {current_value!r},", style="dim") if full else None
+
+        if line:
+            lines.append(line)
+
+    console.print("{")
+    for line in lines:
+        console.print("    ", end="")
+        console.print(line)
+    console.print("}")

exosphere/commands/host.py

@@ -0,0 +1,317 @@
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import (
+    Progress,
+    SpinnerColumn,
+    TextColumn,
+    TimeElapsedColumn,
+)
+from rich.table import Table
+from rich.text import Text
+from typing_extensions import Annotated
+
+from exosphere import app_config, context
+from exosphere.objects import Host
+
+# Steal the save function from inventory command
+from .inventory import save as save_inventory
+
+app = typer.Typer(
+    help="Host management commands",
+    no_args_is_help=True,
+)
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def _get_inventory():
+    """
+    Get the inventory from context
+    A convenience wrapper that bails if the inventory is not initialized.
+    """
+    if context.inventory is None:
+        typer.echo(
+            "Inventory is not initialized, are you running this module directly?",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    return context.inventory
+
+
+def _get_host(name: str) -> Host | None:
+    """
+    Wraps inventory.get_host() to handle displaying errors on console
+    """
+
+    inventory = _get_inventory()
+
+    host = inventory.get_host(name)
+
+    if host is None:
+        err_console.print(
+            Panel.fit(
+                f"Host '{name}' not found in inventory.",
+                title="Error",
+                style="red",
+            )
+        )
+        return None
+
+    return host
+
+
+@app.command()
+def show(
+    name: Annotated[str, typer.Argument(help="Host from inventory to show")],
+    include_updates: Annotated[
+        bool,
+        typer.Option(
+            "--updates/--no-updates",
+            "-u/-n",
+            help="Show update details for the host",
+        ),
+    ] = True,
+    security_only: Annotated[
+        bool,
+        typer.Option(
+            "--security-only",
+            "-s",
+            help="Show only security updates for the host when displaying updates",
+        ),
+    ] = False,
+) -> None:
+    """
+    Show details of a specific host.
+
+    This command retrieves the host by name from the inventory
+    and displays its details in a rich format.
+    """
+    host = _get_host(name)
+
+    if host is None:
+        raise typer.Exit(code=1)
+
+    # Color security updates count
+    security_count = (
+        f"[red]{len(host.security_updates)}[/red]" if host.security_updates else "0"
+    )
+
+    # prepare host OS details
+    host_os_details = (
+        f"{host.flavor} {host.os} {host.version}"
+        if host.flavor != host.os
+        else f"{host.os} {host.version}"
+    )
+
+    if not host.last_refresh:
+        last_refresh = "[red]Never[/red]"
+    else:
+        # Format: "Fri May 21:04:43 EDT 2025"
+        last_refresh = host.last_refresh.strftime("%a %b %d %H:%M:%S %Y")
+
+    # Display host properties in a rich panel
+    console.print(
+        Panel.fit(
+            f"[bold]Host Name:[/bold] {host.name}\n"
+            f"[bold]IP Address:[/bold] {host.ip}\n"
+            f"[bold]Port:[/bold] {host.port}\n"
+            f"[bold]Online Status:[/bold] {'[bold green]Online[/bold green]' if host.online else '[red]Offline[/red]'}\n"
+            "\n"
+            f"[bold]Last Refreshed:[/bold] {last_refresh}\n"
+            f"[bold]Stale:[/bold] {'[yellow]Yes[/yellow]' if host.is_stale else 'No'}\n"
+            "\n"
+            f"[bold]Operating System:[/bold]\n"
+            f"  {host_os_details}, using {host.package_manager}\n"
+            "\n"
+            f"[bold]Updates Available:[/bold] {len(host.updates)} updates, {security_count} security\n",
+            title=host.description if host.description else "Host Details",
+        )
+    )
+
+    if not include_updates:
+        # Warn for invalid set of arguments
+        if security_only:
+            err_console.print(
+                "[yellow]Warning: --security-only option is only valid with --updates, ignoring.[/yellow]"
+            )
+
+        raise typer.Exit(code=0)
+
+    update_list = host.updates if not security_only else host.security_updates
+
+    # Display updates in a rich table, if any
+    if not update_list:
+        console.print("[bold]No updates available for this host.[/bold]")
+        raise typer.Exit(code=0)
+
+    updates_table = Table(
+        "Name",
+        "Current Version",
+        "New Version",
+        "Security",
+        "Source",
+        title="Available Updates",
+    )
+
+    for update in update_list:
+        updates_table.add_row(
+            f"[bold]{update.name}[/bold]",
+            update.current_version if update.current_version else "(NEW)",
+            update.new_version,
+            "Yes" if update.security else "No",
+            Text(update.source or "N/A", no_wrap=True),
+            style="on bright_black" if update.security else "default",
+        )
+
+    console.print(updates_table)
+
+
+@app.command()
+def discover(
+    name: Annotated[str, typer.Argument(help="Host from inventory to discover")],
+) -> None:
+    """
+    Gather platform data for host.
+
+    This command retrieves the host by name from the inventory
+    and synchronizes its platform data.
+    """
+    host = _get_host(name)
+
+    if host is None:
+        raise typer.Exit(code=1)
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        TimeElapsedColumn(),
+    ) as progress:
+        progress.add_task(f"Discovering platform for '{host.name}'", total=None)
+        try:
+            host.discover()
+        except Exception as e:
+            progress.console.print(
+                Panel.fit(
+                    f"{str(e)}",
+                    title="[red]Error[/red]",
+                    style="red",
+                    title_align="left",
+                )
+            )
+
+    if app_config["options"]["cache_autosave"]:
+        save_inventory()
+
+
+@app.command()
+def refresh(
+    name: Annotated[str, typer.Argument(help="Host from inventory to refresh")],
+    full: Annotated[
+        bool, typer.Option("--sync", "-s", help="Also refresh package catalog")
+    ] = False,
+    discover: Annotated[
+        bool, typer.Option("--discover", "-d", help="Also refresh platform information")
+    ] = False,
+) -> None:
+    """
+    Refresh the updates for a specific host.
+
+    This command retrieves the host by name from the inventory
+    and refreshes its updates.
+    """
+    host = _get_host(name)
+
+    if host is None:
+        raise typer.Exit(code=1)
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        TimeElapsedColumn(),
+    ) as progress:
+        if discover:
+            task = progress.add_task(
+                f"Refreshing platform information for '{host.name}'", total=None
+            )
+            try:
+                host.discover()
+            except Exception as e:
+                progress.console.print(
+                    Panel.fit(
+                        f"{str(e)}",
+                        title="[red]Error[/red]",
+                        style="red",
+                        title_align="left",
+                    )
+                )
+                progress.stop_task(task)
+                raise typer.Exit(code=1)
+
+            progress.stop_task(task)
+
+        if full:
+            task = progress.add_task(
+                f"Refreshing package catalog for '{host.name}'", total=None
+            )
+            try:
+                host.refresh_catalog()
+            except Exception as e:
+                progress.console.print(
+                    Panel.fit(
+                        f"{str(e)}",
+                        title="[red]Error[/red]",
+                        style="red",
+                        title_align="left",
+                    )
+                )
+                progress.stop_task(task)
+                raise typer.Exit(code=1)
+
+            progress.stop_task(task)
+
+        task = progress.add_task(f"Refreshing updates for '{host.name}'", total=None)
+        try:
+            host.refresh_updates()
+        except Exception as e:
+            progress.console.print(
+                Panel.fit(
+                    f"{str(e)}",
+                    title="[red]Error[/red]",
+                    style="red",
+                    title_align="left",
+                )
+            )
+
+    if app_config["options"]["cache_autosave"]:
+        save_inventory()
+
+
+@app.command()
+def ping(
+    name: Annotated[str, typer.Argument(help="Host from inventory to ping")],
+) -> None:
+    """
+    Ping a specific host to check its reachability.
+
+    This command will also update a host's online status
+    based on the ping result.
+
+    The ping is is based on ssh connectivity.
+    """
+    host = _get_host(name)
+
+    if host is None:
+        raise typer.Exit(code=1)
+
+    if host.ping():
+        console.print(
+            f"Host [bold]{host.name}[/bold] is [bold green]Online[/bold green]."
+        )
+    else:
+        console.print(f"Host [bold]{host.name}[/bold] is [red]Offline[/red].")
+
+    if app_config["options"]["cache_autosave"]:
+        save_inventory()