apache-aiops 0.2.0__py3-none-any.whl

apache_aiops/__init__.py

@@ -0,0 +1,8 @@
+"""Apache AIops: governed Apache HTTP Server operations."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("apache-aiops")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

apache_aiops/cli/__init__.py

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

apache_aiops/cli/_common.py

@@ -0,0 +1,118 @@
+"""Shared helpers for apache-aiops CLI sub-modules."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+
+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.
+
+    ``BudgetExceeded`` (and the retained ``PolicyDenied`` type) are raised by
+    ``@governed_tool`` OUTSIDE the tool body, so ``tool_errors`` never sees them
+    and they never arrive as an ``{"error": ...}`` dict. Their message is the
+    teaching text (e.g. which budget was hit) — without them here such a refusal
+    reaches the CLI as a traceback instead.
+    """
+    from apache_aiops.connection import ApacheCommandError
+    from apache_aiops.governance import BudgetExceeded, PolicyDenied
+
+    return (ApacheCommandError, PolicyDenied, BudgetExceeded, 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}"
+            # Upstream text can contain "[/bold]"; unescaped, rich raises on it and the
+            # real error is replaced by a MarkupError traceback.
+            console.print(f"[red]Error: {escape(message)}[/]")
+            raise typer.Exit(1) from e
+
+    return wrapper
+
+
+#: Exit status for a write whose outcome could not be determined — kept distinct
+#: from 0 (confirmed) and 1 (failed) so a script can tell all three apart.
+EXIT_UNDETERMINED = 2
+
+
+def governed(result: Any) -> dict:
+    """Return a governed tool's result, or print its error and exit 1.
+
+    The ``apache_aiops.mcp_server.tools`` twins never raise: ``@tool_errors`` flattens every
+    failure — an unreachable service, a refused login, a bad argument — into
+    ``{"error": ...}``. A CLI command that drops that on the floor prints an empty
+    table and exits 0 as if the service had nothing to report. Route every governed
+    call through here.
+    """
+    # ``outcomeUnknown`` is judged BEFORE ``error``, matching the harness: a
+    # write whose response was lost carries BOTH keys, and it is audited
+    # `unknown` precisely because it may have taken effect. Reporting that as a
+    # plain failure would tell a script the change did not happen and invite the
+    # double-apply the payload's own note warns about.
+    if isinstance(result, dict) and result.get("outcomeUnknown"):
+        console.print(f"[yellow]Outcome undetermined: {escape(str(result.get('note') or ''))}[/]")
+        raise typer.Exit(EXIT_UNDETERMINED)
+    if isinstance(result, dict) and result.get("error"):
+        console.print(f"[red]Error: {escape(str(result['error']))}[/]")
+        raise typer.Exit(1)
+    return result if isinstance(result, dict) else {}
+
+
+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,
+    )
+
+
+def print_truncation_note(result: dict, noun: str) -> None:
+    """Print a visible warning when a listing envelope was capped.
+
+    The JSON already carries ``truncated``, but a human scrolling a long dump
+    will not spot it — and neither will a model summarising the terminal. Say
+    it in words, on the last line, where it cannot be missed.
+    """
+    if isinstance(result, dict) and result.get("truncated"):
+        console.print(
+            f"[yellow]… showing {result.get('returned')} of more {noun} — "
+            f"truncated, re-run with a higher --limit[/]"
+        )

apache_aiops/cli/_root.py

@@ -0,0 +1,206 @@
+"""Apache AIops CLI; service reads call governed MCP twins."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Annotated
+
+import typer
+import yaml
+
+from apache_aiops.cli._common import cli_errors, console, double_confirm, governed
+from apache_aiops.cli.undo import undo_app
+from apache_aiops.governance.paths import ops_home
+
+app = typer.Typer(
+    name="apache-aiops", no_args_is_help=True, help="Audited Apache HTTP Server diagnosis."
+)
+app.add_typer(undo_app, name="undo")
+Target = Annotated[str | None, typer.Option("--target", "-t", help="Configured Apache target")]
+
+
+def _print(result: dict) -> None:
+    console.print_json(json.dumps(governed(result)))
+
+
+@app.command("config-includes")
+@cli_errors
+def config_includes(target: Target = None) -> None:
+    """Show the parsed Apache config include tree."""
+    from apache_aiops.mcp_server.tools.httpd import apache_config_includes
+    _print(apache_config_includes(target=target))
+
+
+@app.command("compiled-modules")
+@cli_errors
+def compiled_modules(target: Target = None) -> None:
+    """List modules compiled into Apache."""
+    from apache_aiops.mcp_server.tools.httpd import apache_compiled_modules
+    _print(apache_compiled_modules(target=target))
+
+
+@app.command("static-directives")
+@cli_errors
+def static_directives(target: Target = None) -> None:
+    """List directives supplied by static Apache modules."""
+    from apache_aiops.mcp_server.tools.httpd import apache_static_directives
+    _print(apache_static_directives(target=target))
+
+
+@app.command("build")
+@cli_errors
+def build(target: Target = None) -> None:
+    """Show Apache build flags and paths."""
+    from apache_aiops.mcp_server.tools.httpd import apache_build
+    _print(apache_build(target=target))
+
+
+@app.command("runtime-config")
+@cli_errors
+def runtime_config(target: Target = None) -> None:
+    """Show parsed Apache runtime configuration."""
+    from apache_aiops.mcp_server.tools.httpd import apache_runtime_config
+    _print(apache_runtime_config(target=target))
+
+
+@app.command("server-status")
+@cli_errors
+def server_status(target: Target = None) -> None:
+    """Show configured mod_status auto metrics."""
+    from apache_aiops.mcp_server.tools.httpd import apache_server_status
+    _print(apache_server_status(target=target))
+
+
+@app.command("error-log")
+@cli_errors
+def error_log(limit: int = 50, target: Target = None) -> None:
+    """Tail the operator-configured Apache error log."""
+    from apache_aiops.mcp_server.tools.httpd import apache_error_log
+    _print(apache_error_log(limit=limit, target=target))
+
+
+@app.command("access-status")
+@cli_errors
+def access_status(limit: int = 200, target: Target = None) -> None:
+    """Summarize recent common/combined access-log status codes."""
+    from apache_aiops.mcp_server.tools.httpd import apache_access_status
+    _print(apache_access_status(limit=limit, target=target))
+
+
+@app.command("graceful-reload")
+@cli_errors
+def graceful_reload(dry_run: bool = False, target: Target = None) -> None:
+    """Check config and request an Apache graceful reload."""
+    from apache_aiops.mcp_server.tools.httpd import apache_graceful_reload
+    if not dry_run:
+        double_confirm("gracefully reload Apache", target or "default")
+    _print(apache_graceful_reload(dry_run=dry_run, target=target))
+
+
+@app.command("init")
+@cli_errors
+def init() -> None:
+    """Configure a local Apache HTTP Server target."""
+    from apache_aiops.config import TargetConfig
+
+    name = typer.prompt("Target name", default="local")
+    probe_url = typer.prompt("HTTP health URL (optional)", default="")
+    status_url = typer.prompt("mod_status auto URL (optional)", default="")
+    error_log = typer.prompt("Absolute error log path (optional)", default="")
+    access_log = typer.prompt("Absolute access log path (optional)", default="")
+    chosen = TargetConfig(
+        name=name, probe_url=probe_url or None, status_url=status_url or None,
+        error_log=error_log or None, access_log=access_log or None,
+    )
+    path = ops_home() / "config.yaml"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.exists():
+        raise ValueError(f"Config exists at {path}; edit it to add a target.")
+    path.write_text(
+        yaml.safe_dump({"targets": [{
+            "name": chosen.name, "probe_url": chosen.probe_url,
+            "status_url": chosen.status_url, "error_log": chosen.error_log,
+            "access_log": chosen.access_log,
+        }]})
+    )
+    path.chmod(0o600)
+    console.print(f"Configured {name} at {path}")
+
+
+@app.command("version")
+@cli_errors
+def version(target: Target = None) -> None:
+    """Show Apache version."""
+    from apache_aiops.mcp_server.tools.httpd import apache_version
+
+    _print(apache_version(target=target))
+
+
+@app.command("config-check")
+@cli_errors
+def config_check(target: Target = None) -> None:
+    """Run Apache config syntax test."""
+    from apache_aiops.mcp_server.tools.httpd import apache_config_check
+
+    _print(apache_config_check(target=target))
+
+
+@app.command("vhosts")
+@cli_errors
+def vhosts(target: Target = None) -> None:
+    """Show parsed virtual-host map."""
+    from apache_aiops.mcp_server.tools.httpd import apache_vhosts
+
+    _print(apache_vhosts(target=target))
+
+
+@app.command("modules")
+@cli_errors
+def modules(target: Target = None) -> None:
+    """List loaded Apache modules."""
+    from apache_aiops.mcp_server.tools.httpd import apache_modules
+
+    _print(apache_modules(target=target))
+
+
+@app.command("probe")
+@cli_errors
+def probe(target: Target = None) -> None:
+    """Probe configured HTTP health URL."""
+    from apache_aiops.mcp_server.tools.httpd import apache_probe
+
+    _print(apache_probe(target=target))
+
+
+@app.command("diagnose")
+@cli_errors
+def diagnose(target: Target = None) -> None:
+    """Correlate Apache config and HTTP probes."""
+    from apache_aiops.mcp_server.tools.httpd import apache_diagnose
+
+    _print(apache_diagnose(target=target))
+
+
+@app.command("doctor")
+@cli_errors
+def doctor(target: Target = None) -> None:
+    """Test access to apachectl -v."""
+    from apache_aiops.mcp_server.tools.httpd import apache_version
+
+    _print(apache_version(target=target))
+
+
+@app.command("mcp")
+@cli_errors
+def mcp_cmd() -> None:
+    """Start stdio MCP server."""
+    if sys.version_info < (3, 11):
+        raise typer.Exit(2)
+    from apache_aiops.mcp_server.server import main
+
+    main()
+
+
+if __name__ == "__main__":
+    app()

apache_aiops/cli/undo.py

@@ -0,0 +1,66 @@
+"""``apache-aiops undo`` — list recorded undo tokens and apply them.
+
+Real execution is delegated to the ``@governed_tool``-wrapped functions in
+``apache_aiops.mcp_server.tools.undo`` so an applied undo is audited on the SAME governance
+path as any other write (the inverse tool it dispatches is itself governed).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from apache_aiops.cli._common import (
+    DryRunOption,
+    TargetOption,
+    cli_errors,
+    console,
+    double_confirm,
+    dry_run_print,
+    governed,
+    print_truncation_note,
+)
+
+undo_app = typer.Typer(
+    name="undo",
+    help="List recorded undo tokens and apply their inverse operations.",
+    no_args_is_help=True,
+)
+
+UndoIdArg = Annotated[str, typer.Argument(help="Undo id from 'undo list'")]
+
+
+@undo_app.command("list")
+@cli_errors
+def undo_list_cmd(
+    limit: Annotated[int, typer.Option("--limit", help="Max tokens to show")] = 50,
+    target: TargetOption = None,
+) -> None:
+    """List recorded, not-yet-applied undo tokens."""
+    from apache_aiops.mcp_server.tools import undo as gov
+
+    result = governed(gov.undo_list(limit=limit, target=target))
+    console.print_json(json.dumps(result))
+    print_truncation_note(result, "undo tokens")
+
+
+@undo_app.command("apply")
+@cli_errors
+def undo_apply_cmd(
+    undo_id: UndoIdArg, target: TargetOption = None, dry_run: DryRunOption = False
+) -> None:
+    """Apply a recorded undo (dispatches its inverse tool; dry-run + confirm)."""
+    from apache_aiops.mcp_server.tools import undo as gov
+
+    if dry_run:
+        preview = governed(gov.undo_apply(undo_id=undo_id, dry_run=True, target=target))
+        dry_run_print(
+            operation="undo_apply",
+            api_call=f"inverse: {preview.get('wouldApply', {}).get('tool', '?')}",
+            parameters=preview.get("wouldApply", {}).get("params", {}),
+        )
+        return
+    double_confirm("apply undo", undo_id)
+    console.print_json(json.dumps(governed(gov.undo_apply(undo_id=undo_id, target=target))))

apache_aiops/config.py

@@ -0,0 +1,74 @@
+"""Local Apache HTTP Server target configuration."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import yaml
+
+from apache_aiops.governance.paths import ops_home
+
+
+@dataclass(frozen=True)
+class TargetConfig:
+    name: str
+    apachectl_bin: str = "apachectl"
+    probe_url: str | None = None
+    status_url: str | None = None
+    error_log: str | None = None
+    access_log: str | None = None
+    timeout: float = 10.0
+    verify_ssl: bool = True
+    ca_file: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.name or not self.apachectl_bin or self.apachectl_bin.startswith("-"):
+            raise ValueError("name and apachectl_bin are required.")
+        if self.timeout <= 0:
+            raise ValueError("timeout must be positive.")
+        for configured_url in (self.probe_url, self.status_url):
+            if not configured_url:
+                continue
+            url = urlsplit(configured_url)
+            if url.scheme not in ("http", "https") or not url.hostname or url.username:
+                raise ValueError("Probe/status URL must be HTTP(S) without embedded credentials.")
+        for configured_log in (self.error_log, self.access_log):
+            if not configured_log:
+                continue
+            path = Path(configured_log)
+            if not path.is_absolute():
+                raise ValueError("Log path must be an absolute operator-configured path.")
+            if path.resolve().is_relative_to(ops_home().resolve()):
+                raise ValueError("Log path cannot read this tool's audit/config directory.")
+
+    @property
+    def verify(self) -> bool | str:
+        return self.ca_file or True if self.verify_ssl else False
+
+
+@dataclass(frozen=True)
+class AppConfig:
+    targets: tuple[TargetConfig, ...] = ()
+
+    def get_target(self, name: str | None = None) -> TargetConfig:
+        if name is None:
+            if not self.targets:
+                raise ValueError("No Apache target configured. Run 'apache-aiops init'.")
+            return self.targets[0]
+        for target in self.targets:
+            if target.name == name:
+                return target
+        raise KeyError(f"Unknown Apache target '{name}'.")
+
+
+def load_config(path: Path | None = None) -> AppConfig:
+    path = path or Path(os.environ.get("APACHE_AIOPS_CONFIG", ops_home() / "config.yaml"))
+    if not path.is_file():
+        raise FileNotFoundError(f"No Apache config at {path}. Run 'apache-aiops init'.")
+    raw = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    if not isinstance(raw, dict) or not isinstance(raw.get("targets"), list):
+        raise ValueError("Apache config must have a targets list.")
+    return AppConfig(tuple(TargetConfig(**entry) for entry in raw["targets"]))