exosphere-cli 3.0.0__tar.gz → 3.0.1__tar.gz

{exosphere_cli-3.0.0 → exosphere_cli-3.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: exosphere-cli
-Version: 3.0.0
+Version: 3.0.1
 Summary: CLI/TUI driven patch reporting for remote Unix-like systems.
 Author: Alexandre Gauthier
 Author-email: Alexandre Gauthier <alex@underwares.org>
@@ -149,7 +149,6 @@ uv run textual run --dev -c exosphere ui
 Congratulations! Editing any of the `.tcss` files in the `ui/` directory will
 reflect changes immediately.
 
-
 ### Documentation Editing Quick Start
 
 To edit the documentation, you can use the following commands:
@@ -188,8 +187,10 @@ tasks are defined in the `pyproject.toml` file under the `[tool.poe.tasks]` tabl
 
 | path | description |
 | ---- | ----------- |
+| `LICENSES/` | Full text of every license used by the project and its assets |
 | `docs/` | Sphinx documentation source tree |
 | `docs/source/_ext/` | Custom Sphinx extensions for the project |
+| `docs/source/changelog/` | Per-release changelog entries (markdown) and their assets |
 | `examples/` | Example configuration files and reports |
 | `scripts/` | Utilitarian scripts for dev and maintenance |
 | `src/` | Main source code for the application |
@@ -224,13 +225,16 @@ Paths below are relative to `src/exosphere/` unless otherwise noted.
 | `context.py` | Context management for shared state across commands and UI |
 | `data.py` | Data models and structures for serialization and exchange |
 | `database.py` | Cache system for serialization |
+| `editing.py` | External editor helper module, shared between CLI and UI |
 | `errors.py` | Exception classes and general error messages |
+| `fspaths.py` | Platform-appropriate filesystem paths module, for state |
 | `inventory.py` | Inventory management subsystem |
 | `migrations.py` | Cache format migration processes |
 | `objects.py` | Main objects for representing Hosts, and most of the relevant logic |
 | `pipelining.py` | SSH pipelining implementation, including reaper thread |
 | `repl.py` | REPL module for interactive CLI usage |
 | `reporting.py` | Reporting subsystem, including templates and formatters |
+| `runners.py` | SSH runners module, handles setting up remote POSIX environment |
 | `security.py` | Sudo management subsystem, including policy and utilities |
 
 Generally, most of the things Exosphere does to hosts (including connection management
@@ -245,9 +249,9 @@ Paths below are relative to `src/exosphere/` unless otherwise noted.
 | `ui/app.py` | Main Textual application class and entry point for the UI |
 | `ui/context.py` | UI Context management for shared state across UI components |
 | `ui/elements.py` | Shared UI elements, including task runners |
-| `ui/dashboard.py` | Dashboard view implementation |
-| `ui/inventory.py` | Inventory view implementation |
-| `ui/logs.py` | Logs view implementation |
+| `ui/dashboard.py` | Dashboard screen implementation |
+| `ui/inventory.py` | Inventory screen implementation |
+| `ui/logs.py` | Logs screen implementation |
 | `ui/messages.py` | Screen refresh and message passing system |
 | `ui/palette.py` | Command palette providers and implementations |
 

{exosphere_cli-3.0.0 → exosphere_cli-3.0.1}/README.md

@@ -108,7 +108,6 @@ uv run textual run --dev -c exosphere ui
 Congratulations! Editing any of the `.tcss` files in the `ui/` directory will
 reflect changes immediately.
 
-
 ### Documentation Editing Quick Start
 
 To edit the documentation, you can use the following commands:
@@ -147,8 +146,10 @@ tasks are defined in the `pyproject.toml` file under the `[tool.poe.tasks]` tabl
 
 | path | description |
 | ---- | ----------- |
+| `LICENSES/` | Full text of every license used by the project and its assets |
 | `docs/` | Sphinx documentation source tree |
 | `docs/source/_ext/` | Custom Sphinx extensions for the project |
+| `docs/source/changelog/` | Per-release changelog entries (markdown) and their assets |
 | `examples/` | Example configuration files and reports |
 | `scripts/` | Utilitarian scripts for dev and maintenance |
 | `src/` | Main source code for the application |
@@ -183,13 +184,16 @@ Paths below are relative to `src/exosphere/` unless otherwise noted.
 | `context.py` | Context management for shared state across commands and UI |
 | `data.py` | Data models and structures for serialization and exchange |
 | `database.py` | Cache system for serialization |
+| `editing.py` | External editor helper module, shared between CLI and UI |
 | `errors.py` | Exception classes and general error messages |
+| `fspaths.py` | Platform-appropriate filesystem paths module, for state |
 | `inventory.py` | Inventory management subsystem |
 | `migrations.py` | Cache format migration processes |
 | `objects.py` | Main objects for representing Hosts, and most of the relevant logic |
 | `pipelining.py` | SSH pipelining implementation, including reaper thread |
 | `repl.py` | REPL module for interactive CLI usage |
 | `reporting.py` | Reporting subsystem, including templates and formatters |
+| `runners.py` | SSH runners module, handles setting up remote POSIX environment |
 | `security.py` | Sudo management subsystem, including policy and utilities |
 
 Generally, most of the things Exosphere does to hosts (including connection management
@@ -204,9 +208,9 @@ Paths below are relative to `src/exosphere/` unless otherwise noted.
 | `ui/app.py` | Main Textual application class and entry point for the UI |
 | `ui/context.py` | UI Context management for shared state across UI components |
 | `ui/elements.py` | Shared UI elements, including task runners |
-| `ui/dashboard.py` | Dashboard view implementation |
-| `ui/inventory.py` | Inventory view implementation |
-| `ui/logs.py` | Logs view implementation |
+| `ui/dashboard.py` | Dashboard screen implementation |
+| `ui/inventory.py` | Inventory screen implementation |
+| `ui/logs.py` | Logs screen implementation |
 | `ui/messages.py` | Screen refresh and message passing system |
 | `ui/palette.py` | Command palette providers and implementations |
 

exosphere_cli-3.0.1/pyproject.toml

@@ -0,0 +1,131 @@
+[project]
+name = "exosphere-cli"
+version = "3.0.1"
+description = "CLI/TUI driven patch reporting for remote Unix-like systems."
+readme = "README.md"
+requires-python = ">=3.13"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: System Administrators",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: System :: Monitoring",
+    "Topic :: System :: Systems Administration",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+license = "MIT"
+license-files = [
+    "LICENSE",
+    "LICENSES/*",
+    "COPYRIGHT",
+]
+dependencies = [
+    "fabric>=3.2.2",
+    "textual>=6.7.0",
+    "pyyaml>=6.0.3",
+    "platformdirs>=4.3.8",
+    "prompt-toolkit>=3.0.51",
+    "jinja2>=3.1.6",
+    "packaging>=24.0",
+    "rich>=14.1.0",
+    "cyclopts>=4.16.1",
+    "filelock>=3.29.4",
+    "pydantic>=2.12",
+]
+
+[[project.authors]]
+name = "Alexandre Gauthier"
+email = "alex@underwares.org"
+
+[project.urls]
+homepage = "https://exosphere.readthedocs.io"
+repository = "https://github.com/mrdaemon/exosphere"
+issues = "https://github.com/mrdaemon/exosphere/issues"
+
+[project.scripts]
+exosphere = "exosphere.main:main"
+
+[dependency-groups]
+dev = [
+    "fabric[pytest]>=3.2.2",
+    "jsonschema>=4.25.1",
+    "poethepoet>=0.33.1",
+    "pyright>=1.1.400",
+    "pytest>=8.4.2",
+    "pytest-asyncio>=1.2.0",
+    "pytest-cov>=6.1.1",
+    "pytest-json-ctrf>=0.3.5",
+    "pytest-mock>=3.14.1",
+    "sphinx-rtd-theme>=3.0.2",
+    "ruff>=0.15.0",
+    "sphinx>=8.2.3",
+    "sphinx-autobuild>=2024.10.3",
+    "sphinx-lint>=1.0.0",
+    "sphinx-tabs>=3.4.7",
+    "sphinxcontrib-spelling>=8.0.2",
+    "textual-dev>=1.7.0",
+    "codespell>=2.4.0",
+    "myst-parser[linkify]>=4.0.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.7.19,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "exosphere"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.codespell]
+skip = "*.lock,*.woff,*.woff2,*.ttf,*.ttx,*.svg,*.png,*.gif,*.html,*.htm,docs/source/_static"
+
+[tool.poe.tasks]
+lint = "ruff check src tests scripts"
+isort = "ruff check --select I --fix src tests scripts"
+isort-check = "ruff check --select I src tests scripts --diff"
+typecheck = "pyright src tests scripts"
+ruff-format = "ruff format src tests scripts"
+ruff-format-check = "ruff format --check src tests scripts --diff"
+spellcheck = "codespell src tests scripts docs/source README.md"
+spellcheck-fix = "codespell --write-changes src tests scripts docs/source README.md"
+format = [
+    "ruff-format",
+    "isort",
+]
+format-check = [
+    "ruff-format-check",
+    "isort-check",
+]
+check = [
+    "format-check",
+    "lint",
+    "typecheck",
+    "spellcheck",
+]
+test = "pytest -v --ctrf .tests_report.json"
+coverage = "pytest --cov-report term-missing --cov-report html --cov=src tests/"
+docs-build = "sphinx-build -b html -W --keep-going docs/source docs/build/html"
+docs-lint = "sphinx-lint docs/source"
+docs-spellcheck = "sphinx-build -b spelling -W --keep-going docs/source docs/build"
+docs-linkcheck = "sphinx-build -b linkcheck docs/source docs/build/linkcheck"
+docs = [
+    "docs-lint",
+    "docs-spellcheck",
+    "docs-build",
+]
+docs-serve = "sphinx-autobuild -b html docs/source docs/build/html --port 8000 --open-browser"
+docs-mkreports = "python scripts/generate_example_reports.py"
+demo = "vhs scripts/demo.tape"
+release-preflight = "python scripts/release_preflight.py"
+release-check = [
+    "check",
+    "test",
+    "docs",
+    "release-preflight",
+]

exosphere_cli-3.0.0/pyproject.toml → exosphere_cli-3.0.1/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "exosphere-cli"
-version = "3.0.0"
+version = "3.0.1"
 description = "CLI/TUI driven patch reporting for remote Unix-like systems."
 readme = "README.md"
 authors = [
@@ -73,7 +73,7 @@ issues = "https://github.com/mrdaemon/exosphere/issues"
 exosphere = "exosphere.main:main"
 
 [build-system]
-requires = ["uv_build>=0.7.19,<0.12.0"]
+requires = ["uv_build>=0.7.19,<0.13.0"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]

{exosphere_cli-3.0.0 → exosphere_cli-3.0.1}/src/exosphere/commands/config.py

@@ -40,7 +40,7 @@ def show(
     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,
+    If ``--full`` is specified, it will show the entire configuration structure,
     including the inventory, beyond just the "options" section.
 
     Parameters
@@ -150,9 +150,9 @@ def diff(
     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.
+    in its context, using the ``--full`` option.
 
-    For a full config dump, use the `show` command instead.
+    For a full config dump, use the ``show`` command instead.
 
     Parameters
     ----------
@@ -264,7 +264,7 @@ def edit(
 
         try:
             validate_config(target)
-        except Exception as e:
+        except (ValueError, OSError) as e:
             err_console.print(f"[red]Configuration is invalid:[/red]\n{e}")
             if Confirm.ask("Re-open editor to fix?", default=True):
                 continue

{exosphere_cli-3.0.0 → exosphere_cli-3.0.1}/src/exosphere/commands/host.py

@@ -22,6 +22,7 @@ from exosphere.commands.utils import (
     err_console,
     save_inventory_state,
 )
+from exosphere.errors import DataRefreshError
 from exosphere.objects import Host
 
 # Simple spinner layout for long or pre-tasks
@@ -232,10 +233,10 @@ def discover(host: HostArg, /) -> int:
         progress.add_task(f"Discovering platform for '{host.name}'", total=None)
         try:
             host.discover()
-        except Exception as e:
+        except DataRefreshError as e:
             progress.console.print(
                 Panel.fit(
-                    f"{str(e)}",
+                    f"{e!s}",
                     title="[red]Error[/red]",
                     style="red",
                     title_align="left",
@@ -265,7 +266,7 @@ def refresh(
     This command retrieves the host by name from the inventory
     and refreshes its state and available updates.
 
-    If `--sync` is specified, the package repositories will also be
+    If ``--sync`` is specified, the package repositories will also be
     synchronized remotely.
 
     Parameters
@@ -277,17 +278,17 @@ def refresh(
     discover
         Also refresh platform information
     """
-    with Progress(transient=True, *SPINNER_ARGS) as progress:
+    with Progress(*SPINNER_ARGS, transient=True) as progress:
         if discover:
             task = progress.add_task(
                 f"Refreshing platform information for '{host.name}'", total=None
             )
             try:
                 host.discover()
-            except Exception as e:
+            except DataRefreshError as e:
                 progress.console.print(
                     Panel.fit(
-                        f"{str(e)}",
+                        f"{e!s}",
                         title="[red]Error[/red]",
                         style="red",
                         title_align="left",
@@ -304,10 +305,10 @@ def refresh(
             )
             try:
                 host.sync_repos()
-            except Exception as e:
+            except DataRefreshError as e:
                 progress.console.print(
                     Panel.fit(
-                        f"{str(e)}",
+                        f"{e!s}",
                         title="[red]Error[/red]",
                         style="red",
                         title_align="left",
@@ -321,10 +322,10 @@ def refresh(
         task = progress.add_task(f"Refreshing updates for '{host.name}'", total=None)
         try:
             host.refresh_updates()
-        except Exception as e:
+        except DataRefreshError as e:
             progress.console.print(
                 Panel.fit(
-                    f"{str(e)}",
+                    f"{e!s}",
                     title="[red]Error[/red]",
                     style="red",
                     title_align="left",

{exosphere_cli-3.0.0 → exosphere_cli-3.0.1}/src/exosphere/commands/inventory.py

@@ -27,7 +27,7 @@ from exosphere.commands.utils import (
     save_inventory_state,
 )
 from exosphere.inventory import FilterMode, Inventory, SortField
-from exosphere.objects import HostOperation
+from exosphere.objects import Host, HostOperation
 
 # Constants for display
 ERROR_STYLE = {
@@ -122,11 +122,11 @@ def refresh(
     Connects to hosts in the inventory and retrieves pending package
     updates.
 
-    If `--discover` is specified, the platform information (Operating
+    If ``--discover`` is specified, the platform information (Operating
     System flavor, version, package manager) will also be refreshed.
     Also refreshes the online status in the process.
 
-    If `--sync` is specified, the package repositories will also be
+    If ``--sync`` is specified, the package repositories will also be
     synchronized remotely.
 
     Synchronizing the package repositories involves invoking whatever mechanism
@@ -135,7 +135,7 @@ def refresh(
     with a handful of slow hosts.
 
     By default, only the progress bar is shown during the operation.
-    If `--verbose` is specified, the name and completion status of each host
+    If ``--verbose`` is specified, the name and completion status of each host
     will be shown in real time.
 
     Parameters
@@ -274,7 +274,7 @@ def ping(*names: HostArg) -> int:
                 error_count += 1
                 if exc:
                     progress.console.print(
-                        f"  Host [bold]{host.name}[/bold]: [bold red]ERROR[/bold red] - {str(exc)}",
+                        f"  Host [bold]{host.name}[/bold]: [bold red]ERROR[/bold red] - {exc!s}",
                     )
                 else:
                     progress.console.print(
@@ -342,18 +342,18 @@ def status(
     online status and whether or not the data is stale.
 
     Output can be filtered to show only hosts with pending updates
-    (`--updates-only`) or only those with pending security updates
-    (`--security-only`). These two filters are mutually exclusive.
+    (``--updates-only``) or only those with pending security updates
+    (``--security-only``). These two filters are mutually exclusive.
 
-    Output can also be sorted by any column with `--sort`, optionally
-    reversed with `--reverse`. Sorting by 'version' groups hosts by
+    Output can also be sorted by any column with ``--sort``, optionally
+    reversed with ``--reverse``. Sorting by 'version' groups hosts by
     flavor first, since versions are not comparable across flavors.
 
     When sorting by any column other than name, hosts with unknown
     or unsupported values for that column will be grouped together at the
     end.
 
-    Use `--full` to include extra columns, such as the host description.
+    Use ``--full`` to include extra columns, such as the host description.
 
     No matches when filtering will exit with code 3.
 
@@ -368,7 +368,7 @@ def status(
     sort
         Sort the table by the given column
     reverse
-        Reverse the sort order (requires `--sort`)
+        Reverse the sort order (requires ``--sort``)
     full
         Show additional columns, including host descriptions
     """
@@ -420,12 +420,22 @@ def status(
         caption_justify="right",
     )
 
+    def get_platform_value(host: Host, value: str | None) -> str:
+        """
+        Retrieve display value for host platform.
+        Will return appropriate placeholders as fallback.
+        """
+        if value:
+            return value
+        elif not host.supported:
+            return "[dim](unsupported)[/dim]"
+        else:
+            return "[dim](undiscovered)[/dim]"
+
     for host in hosts:
-        # Prepare some rendering data for suffixes and placeholders
+        # Prepare some rendering data for suffixes
         stale_suffix = " [dim]*[/dim]" if host.is_stale else ""
         reboot_suffix = " [red]![/red]" if host.needs_reboot else ""
-        undiscovered_status = "[dim](undiscovered)[/dim]"
-        unsupported_status = "[dim](unsupported)[/dim]"
         empty_placeholder = "[dim]—[/dim]"
 
         # Prepare table row data
@@ -446,22 +456,12 @@ def status(
             "[bold green]Online[/bold green]" if host.online else "[red]Offline[/red]"
         ) + reboot_suffix
 
-        # Helper function to get platform info with appropriate
-        # handling for unsupported and undiscovered hosts
-        def get_platform_info(value):
-            if value:
-                return value
-            elif not host.supported:
-                return unsupported_status
-            else:
-                return undiscovered_status
-
         # Construct table row for host
         row = [
             host.name,
-            get_platform_info(host.os),
-            get_platform_info(host.flavor),
-            get_platform_info(host.version),
+            get_platform_value(host, host.os),
+            get_platform_value(host, host.flavor),
+            get_platform_value(host, host.version),
             updates,
             security_updates,
             online_status,
@@ -537,7 +537,10 @@ def clear(
 
     try:
         inventory.clear_state()
-    except Exception as e:
+    except Exception as e:  # noqa: BLE001
+        # clear_state wraps cache errors as RuntimeError, but also
+        # re-runs init_all() afterwards, which reopens the full config
+        # and host construction surfaces, so this is broad on purpose.
         err_console.print(
             Panel.fit(
                 f"[bold red]Error clearing inventory state:[/bold red] {e}",

{exosphere_cli-3.0.0 → exosphere_cli-3.0.1}/src/exosphere/commands/report.py

@@ -102,8 +102,8 @@ def generate(
     the report will include all hosts in the inventory.
 
     It can further be narrowed to hosts with pending updates
-    (`--updates-only`) or pending security updates
-    (`--security-updates-only`), which are mutually exclusive.
+    (``--updates-only``) or pending security updates
+    (``--security-updates-only``), which are mutually exclusive.
 
     Note: Undiscovered or unsupported hosts are excluded from the report.
 
@@ -120,7 +120,7 @@ def generate(
     security_only
         Only report security updates
     tee
-        Also print report to stdout (requires `--output`)
+        Also print report to stdout (requires ``--output``)
     quiet
         Suppress informational messages
     navigation
@@ -200,7 +200,7 @@ def generate(
     if output:
         try:
             output.write_text(content, encoding="utf-8")
-        except Exception as e:
+        except (OSError, UnicodeEncodeError) as e:
             err_console.print(f"[red]Failed to write to {output}: {e}[/red]")
             return 2  # Application error
 
@@ -241,14 +241,14 @@ def schema(
     Show or write the JSON Schema for the current version of Exosphere
 
     Emits the JSON Schema (draft-07) describing the structure produced
-    by `report generate --format json`, for the currently running
+    by ``report generate --format json``, for the currently running
     version of Exosphere.
 
     This allows anyone to easily get an overview of the structure,
     validate and integrate, offline, without a local source tree or
     access to the online documentation.
 
-    By default the schema is printed to stdout. Use `--output` to
+    By default the schema is printed to stdout. Use ``--output`` to
     write it to a file instead.
 
     Parameters
@@ -267,7 +267,7 @@ def schema(
     if output:
         try:
             output.write_text(content, encoding="utf-8")
-        except Exception as e:
+        except (OSError, UnicodeEncodeError) as e:
             err_console.print(f"[red]Failed to write to {output}: {e}[/red]")
             return 2  # Application error
 

{exosphere_cli-3.0.0 → exosphere_cli-3.0.1}/src/exosphere/commands/utils.py

@@ -358,7 +358,7 @@ def run_task_with_progress(
     else:
         skipped = []
 
-    with Progress(transient=transient, *progress_args) as progress:
+    with Progress(*progress_args, transient=transient) as progress:
         task = progress.add_task(task_description, total=len(hosts))
 
         # Surface skipped hosts up front, if any. It is easier to do
@@ -381,7 +381,7 @@ def run_task_with_progress(
             if exc:
                 if immediate_error_display:
                     progress.console.print(
-                        f"{operation.label}: [red]{str(exc)}[/red]",
+                        f"{operation.label}: [red]{exc!s}[/red]",
                     )
 
                 if collect_errors:
@@ -418,7 +418,8 @@ def save_inventory_state() -> None:
         try:
             inventory.save_state()
             progress.stop_task(task)
-        except Exception as e:
+        except Exception as e:  # noqa: BLE001
+            # Persistence failure is terminal for the caller either way
             logger.error("Error saving inventory: %s", e)
             progress.stop_task(task)
             progress.console.print(

{exosphere_cli-3.0.0 → exosphere_cli-3.0.1}/src/exosphere/commands/version.py

@@ -131,6 +131,9 @@ def check(
             f"[red]Error:[/red] Unexpected response from PyPI API (missing key: {e})"
         )
         return 2  # Application error
-    except Exception as e:
+    except Exception as e:  # noqa: BLE001
+        # Tail catch for any unexpected failures, covers json garbage,
+        # network issues, or anything else under the sun.
+        # "Is there an update" shouldn't just raise at runtime.
         err_console.print(f"[red]Error:[/red] Failed to check for updates: {e}")
         return 2  # Application error