container-host-aiops 0.1.0__py3-none-any.whl

container_host_aiops/__init__.py

@@ -0,0 +1,9 @@
+"""container-host-aiops — governed Docker + Portainer container-host ops for AI agents.
+
+Standalone and self-contained: the governance harness (audit, token budget,
+undo-token recording, graduated risk tiers, prompt-injection sanitize) is
+bundled under ``container_host_aiops.governance`` — this package has no external
+skill-family dependency. Preview: not yet full-coverage, mock-validated only.
+"""
+
+__version__ = "0.1.0"

container_host_aiops/cli/__init__.py

@@ -0,0 +1,9 @@
+"""CLI package for container-host-aiops.
+
+Re-exports ``app`` so the pyproject entry point
+``container-host-aiops = "container_host_aiops.cli:app"`` works unchanged.
+"""
+
+from container_host_aiops.cli._root import app
+
+__all__ = ["app"]

container_host_aiops/cli/_common.py

@@ -0,0 +1,78 @@
+"""Shared helpers for container-host-aiops CLI sub-modules."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+# ─── Shared Option types ───────────────────────────────────────────────────
+
+TargetOption = Annotated[
+    str | None, typer.Option("--target", "-t", help="Target name from config")
+]
+DryRunOption = Annotated[
+    bool, typer.Option("--dry-run", help="Print the API call without executing")
+]
+
+
+def _cli_error_types() -> tuple[type[BaseException], ...]:
+    """Exceptions translated to a one-line teaching error instead of a traceback."""
+    from container_host_aiops.connection import ContainerHostApiError
+
+    return (ContainerHostApiError, KeyError, OSError, ValueError)
+
+
+def cli_errors(fn: Callable) -> Callable:
+    """Translate known exceptions into one red line + exit code 1."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except (typer.Exit, typer.Abort):
+            raise
+        except _cli_error_types() as e:
+            message = str(e)
+            if isinstance(e, KeyError):
+                message = f"Missing required key or environment variable: {message}"
+            console.print(f"[red]Error: {message}[/]")
+            raise typer.Exit(1) from e
+
+    return wrapper
+
+
+def get_connection(target: str | None, config_path: Path | None = None):
+    """Return a (conn, config) tuple for the given target."""
+    from container_host_aiops.config import load_config
+    from container_host_aiops.connection import ConnectionManager
+
+    cfg = load_config(config_path)
+    mgr = ConnectionManager(cfg)
+    return mgr.connect(target), cfg
+
+
+def dry_run_print(*, operation: str, api_call: str, parameters: dict | None = None) -> None:
+    """Print a dry-run preview of the API call that would be made."""
+    console.print("\n[bold magenta][DRY-RUN] No changes will be made.[/]")
+    console.print(f"[magenta]  Operation: {operation}[/]")
+    console.print(f"[magenta]  API Call:  {api_call}[/]")
+    for k, v in (parameters or {}).items():
+        console.print(f"[magenta]  Param:     {k} = {v}[/]")
+    console.print("[magenta]  Run without --dry-run to execute.[/]\n")
+
+
+def double_confirm(action: str, resource: str) -> None:
+    """Require two confirmations for a destructive operation."""
+    console.print(f"[bold yellow]⚠️  About to: {action} '{resource}'[/]")
+    typer.confirm(f"Confirm 1/2: {action} '{resource}'?", abort=True)
+    typer.confirm(
+        f"Confirm 2/2: really {action} '{resource}'? This may be irreversible.",
+        abort=True,
+    )

container_host_aiops/cli/_root.py

@@ -0,0 +1,70 @@
+"""Top-level Typer app: assembles sub-apps and top-level commands."""
+
+from __future__ import annotations
+
+import typer
+
+from container_host_aiops.cli._common import cli_errors
+from container_host_aiops.cli.analyze import analyze_app
+from container_host_aiops.cli.container import container_app
+from container_host_aiops.cli.doctor import doctor_cmd
+from container_host_aiops.cli.image import image_app
+from container_host_aiops.cli.init import init_cmd
+from container_host_aiops.cli.manage import manage_app
+from container_host_aiops.cli.network import network_app
+from container_host_aiops.cli.overview import overview_cmd
+from container_host_aiops.cli.secret import secret_app
+from container_host_aiops.cli.stack import stack_app
+from container_host_aiops.cli.system import system_app
+from container_host_aiops.cli.volume import volume_app
+
+app = typer.Typer(
+    name="container-host-aiops",
+    help="Governed AI-ops for Docker + Portainer container hosts: container / "
+    "image / volume / network / system reads, flagship analyses, and guarded "
+    "lifecycle + prune writes with a built-in governance harness.",
+    no_args_is_help=True,
+)
+
+app.add_typer(container_app, name="container")
+app.add_typer(image_app, name="image")
+app.add_typer(volume_app, name="volume")
+app.add_typer(network_app, name="network")
+app.add_typer(system_app, name="system")
+app.add_typer(stack_app, name="stack")
+app.add_typer(analyze_app, name="analyze")
+app.add_typer(manage_app, name="manage")
+app.add_typer(secret_app, name="secret")
+app.command("init")(init_cmd)
+app.command("overview")(overview_cmd)
+app.command("doctor")(doctor_cmd)
+
+
+@app.command("mcp")
+@cli_errors
+def mcp_cmd() -> None:
+    """Start the MCP server (stdio transport).
+
+    Single-command entry point for MCP clients (does not go through uvx/PyPI
+    resolution at launch):
+        container-host-aiops mcp
+    """
+    import sys
+
+    if sys.version_info < (3, 11):
+        typer.echo(
+            f"ERROR: container-host-aiops requires Python >= 3.11 "
+            f"(got {sys.version_info.major}.{sys.version_info.minor}).\n"
+            f"Fix: uv python install 3.12 && "
+            f"uv tool install --python 3.12 --force container-host-aiops",
+            err=True,
+        )
+        raise typer.Exit(2)
+
+    from mcp_server.server import main as _mcp_main
+
+    _mcp_main()
+
+
+if __name__ == "__main__":
+    app()

container_host_aiops/cli/analyze.py

@@ -0,0 +1,55 @@
+"""``container-host-aiops analyze`` — the flagship signature analyses."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from container_host_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+
+analyze_app = typer.Typer(
+    name="analyze",
+    help="Flagship analyses: restart-loop RCA, resource pressure, image/volume bloat.",
+    no_args_is_help=True,
+)
+
+
+@analyze_app.command("restart-loop")
+@cli_errors
+def analyze_restart_loop(
+    threshold: Annotated[int, typer.Option(help="Restart count = looping")] = 3,
+    target: TargetOption = None,
+) -> None:
+    """Find crash-looping containers and map each to a cause + action."""
+    from container_host_aiops.ops import analyses as ops
+
+    conn, _ = get_connection(target)
+    rows, logs = ops.pull_restart_data(conn)
+    console.print_json(json.dumps(ops.restart_loop_rca(rows, logs, threshold)))
+
+
+@analyze_app.command("resource-pressure")
+@cli_errors
+def analyze_resource_pressure(
+    cpu: Annotated[float, typer.Option(help="CPU%% = over pressure")] = 80.0,
+    mem: Annotated[float, typer.Option(help="Memory%% = over pressure")] = 80.0,
+    target: TargetOption = None,
+) -> None:
+    """Rank running containers by CPU/memory pressure vs their limits."""
+    from container_host_aiops.ops import analyses as ops
+
+    conn, _ = get_connection(target)
+    samples = ops.pull_resource_pressure(conn)
+    console.print_json(json.dumps(ops.resource_pressure_analysis(samples, cpu, mem)))
+
+
+@analyze_app.command("bloat")
+@cli_errors
+def analyze_bloat(target: TargetOption = None) -> None:
+    """Dangling images + volumes + build cache → prune candidates."""
+    from container_host_aiops.ops import analyses as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.pull_bloat(conn)))

container_host_aiops/cli/container.py

@@ -0,0 +1,85 @@
+"""``container-host-aiops container`` — container-scoped reads."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from container_host_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+
+container_app = typer.Typer(
+    name="container",
+    help="Containers: list, inspect, logs, stats, top, restart summary.",
+    no_args_is_help=True,
+)
+
+CidArg = Annotated[str, typer.Argument(help="Container id or name")]
+
+
+@container_app.command("list")
+@cli_errors
+def container_list(
+    running: Annotated[bool, typer.Option("--running", help="Only running")] = False,
+    target: TargetOption = None,
+) -> None:
+    """List containers (all states by default, or only running)."""
+    from container_host_aiops.ops import containers as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.list_containers(conn, all_states=not running)))
+
+
+@container_app.command("inspect")
+@cli_errors
+def container_inspect(container_id: CidArg, target: TargetOption = None) -> None:
+    """Full inspect of one container."""
+    from container_host_aiops.ops import containers as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.inspect_container(conn, container_id)))
+
+
+@container_app.command("logs")
+@cli_errors
+def container_logs(
+    container_id: CidArg,
+    tail: Annotated[int, typer.Option(help="Lines from the end (1..2000)")] = 100,
+    target: TargetOption = None,
+) -> None:
+    """Tail the last N log lines of a container."""
+    from container_host_aiops.ops import containers as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.container_logs(conn, container_id, tail)))
+
+
+@container_app.command("stats")
+@cli_errors
+def container_stats(container_id: CidArg, target: TargetOption = None) -> None:
+    """One-shot CPU%/memory% snapshot for a container."""
+    from container_host_aiops.ops import containers as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.container_stats(conn, container_id)))
+
+
+@container_app.command("top")
+@cli_errors
+def container_top(container_id: CidArg, target: TargetOption = None) -> None:
+    """Processes running inside a container."""
+    from container_host_aiops.ops import containers as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.container_top(conn, container_id)))
+
+
+@container_app.command("restarts")
+@cli_errors
+def container_restarts(target: TargetOption = None) -> None:
+    """Restart-count + exit-code summary across containers."""
+    from container_host_aiops.ops import containers as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.restart_summary(conn)))

container_host_aiops/cli/doctor.py

@@ -0,0 +1,21 @@
+"""Doctor top-level command: environment and connectivity check."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from container_host_aiops.cli._common import cli_errors
+
+
+@cli_errors
+def doctor_cmd(
+    skip_auth: Annotated[
+        bool, typer.Option("--skip-auth", help="Skip connectivity check (faster)")
+    ] = False,
+) -> None:
+    """Check environment, config, secrets, and connectivity."""
+    from container_host_aiops.doctor import run_doctor
+
+    raise typer.Exit(run_doctor(skip_auth=skip_auth))

container_host_aiops/cli/image.py

@@ -0,0 +1,61 @@
+"""``container-host-aiops image`` — image-scoped reads."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from container_host_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+
+image_app = typer.Typer(
+    name="image",
+    help="Images: list, inspect (with history), dangling, disk usage.",
+    no_args_is_help=True,
+)
+
+ImageArg = Annotated[str, typer.Argument(help="Image id or name:tag")]
+
+
+@image_app.command("list")
+@cli_errors
+def image_list(
+    all_images: Annotated[bool, typer.Option("--all", help="Include intermediate layers")] = False,
+    target: TargetOption = None,
+) -> None:
+    """List images (largest first)."""
+    from container_host_aiops.ops import images as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.list_images(conn, all_images)))
+
+
+@image_app.command("inspect")
+@cli_errors
+def image_inspect(image_id: ImageArg, target: TargetOption = None) -> None:
+    """Inspect an image plus its build history."""
+    from container_host_aiops.ops import images as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.inspect_image(conn, image_id)))
+
+
+@image_app.command("dangling")
+@cli_errors
+def image_dangling(target: TargetOption = None) -> None:
+    """Untagged (dangling) images + reclaimable bytes."""
+    from container_host_aiops.ops import images as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.dangling_images(conn)))
+
+
+@image_app.command("disk-usage")
+@cli_errors
+def image_disk_usage(target: TargetOption = None) -> None:
+    """Image disk usage from system/df."""
+    from container_host_aiops.ops import images as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.image_disk_usage(conn)))

container_host_aiops/cli/init.py

@@ -0,0 +1,126 @@
+"""``container-host-aiops init`` — a friendly, interactive onboarding wizard.
+
+Walks a new user through connecting their first container host: collects the
+non-secret connection details into ``config.yaml`` and — for a Portainer target —
+the API token into the *encrypted* store (never plaintext on disk). A direct
+Docker socket target needs no secret. Designed to be run on a terminal;
+everything it needs is prompted with sensible defaults.
+"""
+
+from __future__ import annotations
+
+import getpass
+
+import typer
+import yaml
+
+from container_host_aiops.cli._common import cli_errors, console
+from container_host_aiops.config import CONFIG_DIR, CONFIG_FILE
+from container_host_aiops.platform import (
+    DEFAULT_DOCKER_SOCKET,
+    DEFAULT_PORTAINER_PORT,
+    DOCKER,
+    PORTAINER,
+)
+from container_host_aiops.secretstore import SecretStore, resolve_master_password
+
+
+def _load_existing_targets() -> list[dict]:
+    if not CONFIG_FILE.exists():
+        return []
+    raw = yaml.safe_load(CONFIG_FILE.read_text("utf-8")) or {}
+    return list(raw.get("targets", []))
+
+
+def _write_targets(targets: list[dict]) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    try:
+        CONFIG_DIR.chmod(0o700)
+    except OSError:
+        pass
+    CONFIG_FILE.write_text(yaml.safe_dump({"targets": targets}, sort_keys=False), "utf-8")
+
+
+@cli_errors
+def init_cmd() -> None:
+    """Interactively set up your first Docker or Portainer connection."""
+    console.print("[bold cyan]Container Host AIops — setup wizard[/]")
+    console.print(
+        "This collects Docker or Portainer connection details (saved to "
+        "config.yaml). A Portainer target also stores its API token "
+        "[bold]encrypted[/] in secrets.enc; a local Docker socket needs no secret.\n"
+    )
+
+    targets = _load_existing_targets()
+    existing_names = {t.get("name") for t in targets}
+    store: SecretStore | None = None
+
+    while True:
+        console.print("\n[bold]Add a target[/]")
+        name = typer.prompt("Target name (e.g. prod1)").strip()
+        if name in existing_names:
+            if not typer.confirm(f"'{name}' already exists — overwrite?", default=False):
+                continue
+            targets = [t for t in targets if t.get("name") != name]
+
+        platform = typer.prompt(
+            f"Platform ({DOCKER} / {PORTAINER})", default=DOCKER
+        ).strip().lower()
+        if platform not in (DOCKER, PORTAINER):
+            console.print("[red]Platform must be 'docker' or 'portainer'.[/]")
+            continue
+
+        entry: dict = {"name": name, "platform": platform}
+        if platform == DOCKER:
+            use_socket = typer.confirm(
+                "Connect over a local unix socket? (No = TCP host)", default=True
+            )
+            if use_socket:
+                entry["socket_path"] = typer.prompt(
+                    "Docker socket path", default=DEFAULT_DOCKER_SOCKET
+                ).strip()
+            else:
+                entry["host"] = typer.prompt("Docker host (IP or FQDN)").strip()
+                entry["verify_ssl"] = typer.confirm(
+                    "Use TLS (https)?", default=False
+                )
+        else:  # portainer
+            entry["host"] = typer.prompt("Portainer host (IP or FQDN)").strip()
+            entry["port"] = typer.prompt(
+                "Portainer HTTPS port", default=DEFAULT_PORTAINER_PORT, type=int
+            )
+            entry["endpoint_id"] = typer.prompt(
+                "Managed Docker endpoint id (for proxied Docker reads)", default="1"
+            ).strip()
+            entry["verify_ssl"] = typer.confirm(
+                "Verify TLS certificate? (No for self-signed)", default=False
+            )
+            if store is None:
+                console.print("\n[bold]Master password[/] (encrypts secrets.enc)")
+                console.print(
+                    "[dim]Set it later via CONTAINER_HOST_AIOPS_MASTER_PASSWORD for "
+                    "non-interactive/MCP use.[/]"
+                )
+                password = resolve_master_password(confirm_if_new=True)
+                store = SecretStore.unlock(password)
+            token = getpass.getpass(f"Portainer API token for '{name}' (hidden): ")
+            store = store.set(name, token)
+
+        targets.append(entry)
+        existing_names.add(name)
+        _write_targets(targets)
+        console.print(f"[green]✓ Saved target '{name}' ({platform}).[/]")
+
+        if not typer.confirm("\nAdd another target?", default=False):
+            break
+
+    console.print(f"\n[green]✓ Setup complete.[/] Config: {CONFIG_FILE}")
+    console.print(
+        "[dim]Tip: export CONTAINER_HOST_AIOPS_MASTER_PASSWORD=... in your shell "
+        "profile so the MCP server and CLI can unlock Portainer tokens "
+        "non-interactively.[/]"
+    )
+    if typer.confirm("Run a connectivity check now (container-host-aiops doctor)?", default=True):
+        from container_host_aiops.doctor import run_doctor
+
+        raise typer.Exit(run_doctor())