queue-aiops 0.1.0__py3-none-any.whl

queue_aiops/cli/undo.py

@@ -0,0 +1,62 @@
+"""``queue-aiops undo`` — list recorded undo tokens and apply them.
+
+Real execution is delegated to the ``@governed_tool``-wrapped functions in
+``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 re-gated).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from queue_aiops.cli._common import (
+    DryRunOption,
+    TargetOption,
+    cli_errors,
+    console,
+    double_confirm,
+    dry_run_print,
+)
+
+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 mcp_server.tools import undo as gov
+
+    console.print_json(json.dumps(gov.undo_list(limit=limit, target=target)))
+
+
+@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 mcp_server.tools import undo as gov
+
+    if dry_run:
+        preview = 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(gov.undo_apply(undo_id=undo_id, target=target)))

queue_aiops/config.py

@@ -0,0 +1,175 @@
+"""Configuration management for Queue AIops.
+
+Loads broker connection targets from a YAML config file. Each target names its
+``platform`` — ``redis`` (RESP wire protocol via the Python client) or
+``rabbitmq`` (management HTTP API) — so one config can span a mixed estate. See
+:mod:`queue_aiops.platform` for how the platform name selects the protocol
+shape (client vs HTTP + resource paths).
+
+The secret is NEVER stored in the config file or in plaintext on disk: it lives
+in the encrypted store ``~/.queue-aiops/secrets.enc`` (see
+:mod:`queue_aiops.secretstore`). For redis the secret is the ``AUTH`` password
+— **optional**, because auth-less lab instances are common (reachability is
+then the boundary). For rabbitmq it is the management user's password that
+pairs with ``username`` (presented as HTTP Basic auth) and is required. A
+legacy env var (``QUEUE_<TARGET>_SECRET``) is honoured as a fallback.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import yaml
+
+from queue_aiops.governance.paths import ops_home
+from queue_aiops.platform import PLATFORMS, RABBITMQ, REDIS, get_platform
+from queue_aiops.secretstore import SecretStoreError, get_secret, has_store
+
+if TYPE_CHECKING:
+    from queue_aiops.platform import Platform
+
+CONFIG_DIR = ops_home()
+CONFIG_FILE = CONFIG_DIR / "config.yaml"
+ENV_FILE = CONFIG_DIR / ".env"
+
+SECRET_ENV_PREFIX = "QUEUE_"  # nosec B105 — env-var name, not a secret
+SECRET_ENV_SUFFIX = "_SECRET"  # nosec B105 — env-var name, not a secret
+
+_log = logging.getLogger("queue-aiops.config")
+
+
+def _secret_env_key(name: str) -> str:
+    """Legacy per-target secret env var name, e.g. QUEUE_CACHE1_SECRET."""
+    return f"{SECRET_ENV_PREFIX}{name.upper().replace('-', '_')}{SECRET_ENV_SUFFIX}"
+
+
+def _resolve_secret(name: str, *, required: bool) -> str:
+    """Return a target's secret: encrypted store first, then legacy env var.
+
+    ``required=False`` (redis) returns "" when no secret is stored anywhere —
+    an auth-less lab instance is a legitimate setup, not an error.
+    """
+    if has_store():
+        try:
+            return get_secret(name)
+        except SecretStoreError:
+            pass  # fall through to legacy env var
+    legacy = os.environ.get(_secret_env_key(name))
+    if legacy:
+        _log.warning(
+            "Using plaintext env var %s. Migrate to the encrypted store with "
+            "'queue-aiops secret migrate'.",
+            _secret_env_key(name),
+        )
+        return legacy
+    if not required:
+        return ""
+    raise OSError(
+        f"No secret for target '{name}'. Add one with "
+        f"'queue-aiops secret set {name}' (stored encrypted), or run "
+        f"'queue-aiops init'."
+    )
+
+
+@dataclass(frozen=True)
+class TargetConfig:
+    """A connection target for one broker.
+
+    ``platform`` is ``redis`` or ``rabbitmq`` (validated at construction).
+    ``username`` holds the rabbitmq management user (unused for redis); ``db``
+    is the redis logical database index (unused for rabbitmq). ``use_tls``
+    selects rediss:// / https://; ``verify_ssl`` governs certificate checks.
+    The secret (redis password — optional — / rabbitmq password) comes from the
+    encrypted store.
+    """
+
+    name: str
+    platform: str = REDIS
+    host: str = ""
+    port: int = 0
+    username: str = ""
+    db: int = 0
+    use_tls: bool = False
+    verify_ssl: bool = True
+
+    def __post_init__(self) -> None:
+        if self.platform not in PLATFORMS:
+            raise ValueError(
+                f"Target '{self.name}': platform must be one of {PLATFORMS}, "
+                f"got '{self.platform}'."
+            )
+        if not self.port:
+            object.__setattr__(self, "port", self.platform_obj.default_port)
+
+    @property
+    def platform_obj(self) -> Platform:
+        return get_platform(self.platform)
+
+    @property
+    def secret_required(self) -> bool:
+        """Redis auth is optional (lab instances); rabbitmq Basic auth is not."""
+        return self.platform == RABBITMQ
+
+    @property
+    def secret(self) -> str:
+        return _resolve_secret(self.name, required=self.secret_required)
+
+    @property
+    def base_url(self) -> str:
+        """HTTP base URL (rabbitmq management API)."""
+        scheme = "https" if self.use_tls else "http"
+        return f"{scheme}://{self.host}:{self.port}"
+
+
+@dataclass(frozen=True)
+class AppConfig:
+    """Top-level application config."""
+
+    targets: tuple[TargetConfig, ...] = ()
+
+    def get_target(self, name: str) -> TargetConfig:
+        for t in self.targets:
+            if t.name == name:
+                return t
+        available = ", ".join(t.name for t in self.targets) or "(none)"
+        raise KeyError(f"Target '{name}' not found. Available: {available}")
+
+    @property
+    def default_target(self) -> TargetConfig:
+        if not self.targets:
+            raise ValueError("No targets configured. Check config.yaml")
+        return self.targets[0]
+
+
+def load_config(config_path: Path | None = None) -> AppConfig:
+    """Load config from YAML; the secret comes from the encrypted store."""
+    path = config_path or CONFIG_FILE
+    if not path.exists():
+        raise FileNotFoundError(
+            f"Config file not found: {path}\n"
+            f"Run 'queue-aiops init' to set up a redis or rabbitmq target, "
+            f"or create {CONFIG_FILE} with a 'targets' list."
+        )
+
+    with open(path) as f:
+        raw = yaml.safe_load(f) or {}
+
+    targets = tuple(
+        TargetConfig(
+            name=t["name"],
+            platform=t.get("platform", REDIS),
+            host=t["host"],
+            port=t.get("port", 0),
+            username=t.get("username", ""),
+            db=t.get("db", 0),
+            use_tls=t.get("use_tls", False),
+            verify_ssl=t.get("verify_ssl", True),
+        )
+        for t in raw.get("targets", [])
+    )
+
+    return AppConfig(targets=targets)

queue_aiops/connection.py

@@ -0,0 +1,277 @@
+"""Connection management for brokers (redis + rabbitmq).
+
+A single :class:`QueueConnection` speaks the protocol of its target's platform:
+
+  * **redis** — the Redis wire protocol via the ``redis`` Python client
+    (password optional, TLS optional, 30s socket timeouts,
+    ``decode_responses=True`` so all values come back as ``str``). Typed
+    ``redis_*`` helpers cover exactly the command surface the ops layer needs —
+    INFO / SLOWLOG / CLIENT LIST / CLIENT KILL / CONFIG GET/SET /
+    MEMORY STATS/USAGE / SCAN / DBSIZE / PING. There is deliberately **no**
+    generic "run any command" passthrough, and big-key sampling is SCAN-based
+    with a hard budget — never ``KEYS *``.
+  * **rabbitmq** — the management HTTP API with HTTP Basic auth. Ops modules
+    never hard-code a path: they ask ``conn.platform.path("queues")`` for the
+    concrete URL (every interpolated segment percent-encoded, including the
+    default vhost ``/``) and ``conn.platform.rows()`` to unwrap list payloads.
+
+All failures are translated centrally into ``QueueApiError`` with a teaching
+message — protocol errors are translated at the connection layer rather than
+leaking raw tracebacks. The underlying client is injectable for tests: pass
+``client=`` a mock implementing the redis client methods (redis targets) or
+``request`` / ``close`` (rabbitmq targets). No live broker is needed in tests.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from queue_aiops.config import AppConfig, TargetConfig, load_config
+from queue_aiops.platform import RABBITMQ, REDIS
+
+_TIMEOUT = 30.0
+
+
+class QueueApiError(Exception):
+    """A broker call failed; carries a teaching message + status/context."""
+
+    def __init__(self, message: str, *, status_code: int | None = None, path: str = "") -> None:
+        self.status_code = status_code
+        self.path = path
+        super().__init__(message)
+
+
+def _teaching_message(status: int, path: str, body: str, label: str) -> str:
+    """Map a non-2xx management-API status to an actionable, teaching message."""
+    snippet = body[:200].strip()
+    if status in (401, 403):
+        return (
+            f"Authentication/authorization failed ({status}) on {label} {path}. "
+            f"Check the management user/password and that the user has the "
+            f"'monitoring' or 'management' tag (and access to the vhost). {snippet}"
+        )
+    if status == 404:
+        return (
+            f"Resource not found (404) on {label} {path}. The vhost or "
+            f"queue/policy name may be stale — list the parent collection first "
+            f"(the default vhost is '/', sent percent-encoded). {snippet}"
+        )
+    if status == 400:
+        return (
+            f"Bad request (400) on {label} {path}. The broker rejected the "
+            f"request — check required fields and value formats. {snippet}"
+        )
+    if status in (500, 502, 503, 504):
+        return (
+            f"{label} server error ({status}) on {path}. The broker may be "
+            f"busy; retry shortly. {snippet}"
+        )
+    return f"{label} API error ({status}) on {path}. {snippet}"
+
+
+class QueueConnection:
+    """A single authenticated session against one redis or rabbitmq target."""
+
+    def __init__(self, target: TargetConfig, client: Any | None = None) -> None:
+        self._target = target
+        self._client = client or self._build_client(target)
+
+    @staticmethod
+    def _build_client(target: TargetConfig) -> Any:
+        if target.platform == REDIS:
+            import redis as redis_pkg  # lazy: only redis targets need it
+
+            kwargs: dict[str, Any] = {
+                "host": target.host,
+                "port": target.port,
+                "db": target.db,
+                "socket_timeout": _TIMEOUT,
+                "socket_connect_timeout": _TIMEOUT,
+                "decode_responses": True,
+            }
+            if target.secret:
+                kwargs["password"] = target.secret
+            if target.use_tls:
+                kwargs["ssl"] = True
+                kwargs["ssl_cert_reqs"] = "required" if target.verify_ssl else "none"
+            return redis_pkg.Redis(**kwargs)
+        return httpx.Client(
+            base_url=target.base_url,
+            verify=target.verify_ssl,
+            timeout=_TIMEOUT,
+            auth=httpx.BasicAuth(target.username, target.secret),
+            headers={"Accept": "application/json", "Content-Type": "application/json"},
+        )
+
+    @property
+    def target(self) -> TargetConfig:
+        return self._target
+
+    @property
+    def platform(self) -> Any:
+        return self._target.platform_obj
+
+    def _require(self, platform_name: str) -> None:
+        """Fail fast (teaching) when an op is asked of the wrong platform."""
+        if self._target.platform != platform_name:
+            raise QueueApiError(
+                f"Target '{self._target.name}' is a {self._target.platform} "
+                f"target; this operation needs a {platform_name} target. "
+                f"Pass a {platform_name} target name, or check the config."
+            )
+
+    def close(self) -> None:
+        self._client.close()
+
+    # ── redis command helpers (typed surface, no generic passthrough) ──────
+    def _redis_call(self, description: str, method: str, *args: Any, **kwargs: Any) -> Any:
+        """Guard the platform FIRST, then resolve + run the client method."""
+        self._require(REDIS)
+        fn = getattr(self._client, method)
+        try:
+            return fn(*args, **kwargs)
+        except QueueApiError:
+            raise
+        except Exception as exc:  # redis.RedisError, socket errors — translated
+            raise QueueApiError(
+                f"Redis call failed ({description}) against "
+                f"{self._target.host}:{self._target.port}: {exc}. Check "
+                f"host/port, password (AUTH), and that the instance is up.",
+                path=description,
+            ) from exc
+
+    def redis_ping(self) -> bool:
+        return bool(self._redis_call("PING", "ping"))
+
+    def redis_info(self, section: str | None = None) -> dict:
+        out = (
+            self._redis_call(f"INFO {section}", "info", section)
+            if section
+            else self._redis_call("INFO", "info")
+        )
+        return out if isinstance(out, dict) else {}
+
+    def redis_slowlog(self, count: int = 128) -> list:
+        out = self._redis_call("SLOWLOG GET", "slowlog_get", count)
+        return out if isinstance(out, list) else []
+
+    def redis_client_list(self) -> list[dict]:
+        out = self._redis_call("CLIENT LIST", "client_list")
+        return [c for c in out if isinstance(c, dict)] if isinstance(out, list) else []
+
+    def redis_client_kill_id(self, client_id: int) -> int:
+        """CLIENT KILL ID <id>; returns the number of clients killed."""
+        out = self._redis_call(
+            "CLIENT KILL ID", "client_kill_filter", _id=str(int(client_id))
+        )
+        return int(out or 0)
+
+    def redis_client_kill_addr(self, addr: str) -> int:
+        """CLIENT KILL ADDR <addr>; returns the number of clients killed."""
+        out = self._redis_call("CLIENT KILL ADDR", "client_kill_filter", addr=str(addr))
+        return int(out or 0)
+
+    def redis_config_get(self, pattern: str) -> dict:
+        out = self._redis_call(f"CONFIG GET {pattern}", "config_get", pattern)
+        return out if isinstance(out, dict) else {}
+
+    def redis_config_set(self, param: str, value: str) -> bool:
+        return bool(self._redis_call(f"CONFIG SET {param}", "config_set", param, value))
+
+    def redis_memory_stats(self) -> dict:
+        out = self._redis_call("MEMORY STATS", "memory_stats")
+        return out if isinstance(out, dict) else {}
+
+    def redis_memory_usage(self, key: str, samples: int = 0) -> int | None:
+        out = self._redis_call("MEMORY USAGE", "memory_usage", key, samples=samples)
+        return int(out) if out is not None else None
+
+    def redis_scan(self, cursor: int = 0, count: int = 500) -> tuple[int, list[str]]:
+        """One SCAN page. The caller enforces the scan budget."""
+        out = self._redis_call("SCAN", "scan", cursor=cursor, count=count)
+        nxt, keys = (out if isinstance(out, (tuple, list)) and len(out) == 2 else (0, []))
+        return int(nxt), [str(k) for k in (keys or [])]
+
+    def redis_dbsize(self) -> int:
+        return int(self._redis_call("DBSIZE", "dbsize") or 0)
+
+    # ── rabbitmq management-API helpers (HTTP) ──────────────────────────────
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        self._require(RABBITMQ)
+        label = self._target.platform_obj.label
+        try:
+            resp = self._client.request(method, path, **kwargs)
+        except httpx.HTTPError as exc:
+            raise QueueApiError(
+                f"Could not reach {label} at {self._target.base_url} "
+                f"({method} {path}): {exc}. Check host/port and that the "
+                f"management plugin is enabled.",
+                path=path,
+            ) from exc
+        if not (200 <= resp.status_code < 300):
+            raise QueueApiError(
+                _teaching_message(resp.status_code, path, resp.text, label),
+                status_code=resp.status_code,
+                path=path,
+            )
+        if not resp.content:
+            return {}
+        try:
+            return resp.json()
+        except ValueError:
+            return {}
+
+    def get(self, path: str, **kwargs: Any) -> Any:
+        return self._request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> Any:
+        return self._request("POST", path, **kwargs)
+
+    def put(self, path: str, **kwargs: Any) -> Any:
+        return self._request("PUT", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> Any:
+        return self._request("DELETE", path, **kwargs)
+
+
+class ConnectionManager:
+    """Manages connections to multiple broker targets with session reuse."""
+
+    def __init__(self, config: AppConfig) -> None:
+        self._config = config
+        self._connections: dict[str, QueueConnection] = {}
+
+    @classmethod
+    def from_config(cls, config: AppConfig | None = None) -> ConnectionManager:
+        cfg = config or load_config()
+        return cls(cfg)
+
+    def connect(self, target_name: str | None = None) -> QueueConnection:
+        target = (
+            self._config.get_target(target_name)
+            if target_name
+            else self._config.default_target
+        )
+        cached = self._connections.get(target.name)
+        if cached is not None:
+            return cached
+        conn = QueueConnection(target)
+        self._connections[target.name] = conn
+        return conn
+
+    def disconnect(self, target_name: str) -> None:
+        conn = self._connections.pop(target_name, None)
+        if conn is not None:
+            conn.close()
+
+    def disconnect_all(self) -> None:
+        for name in list(self._connections):
+            self.disconnect(name)
+
+    def list_targets(self) -> list[str]:
+        return [t.name for t in self._config.targets]
+
+    def list_connected(self) -> list[str]:
+        return list(self._connections.keys())

queue_aiops/doctor.py

@@ -0,0 +1,98 @@
+"""Environment and connectivity diagnostics for Queue AIops."""
+
+from __future__ import annotations
+
+from rich.console import Console
+
+from queue_aiops.config import CONFIG_FILE, ENV_FILE, load_config
+from queue_aiops.platform import REDIS
+from queue_aiops.secretstore import SECRETS_FILE, check_permissions, has_store
+
+_console = Console()
+
+
+def run_doctor(skip_auth: bool = False) -> int:
+    """Check config, secrets, and (optionally) connectivity.
+
+    Returns a process exit code: 0 healthy, 1 problems found. Connectivity
+    failures are reported as status, never raised as tracebacks (a doctor must
+    survive the thing it diagnoses being unhealthy).
+    """
+    problems = 0
+
+    if not CONFIG_FILE.exists():
+        _console.print(f"[red]✗ Config file missing: {CONFIG_FILE}[/]")
+        _console.print("[yellow]  Run 'queue-aiops init' to set up your first target.[/]")
+        return 1
+    _console.print(f"[green]✓ Config file present: {CONFIG_FILE}[/]")
+
+    try:
+        config = load_config()
+    except Exception as exc:  # noqa: BLE001 — report, do not crash
+        _console.print(f"[red]✗ Config load failed: {exc}[/]")
+        return 1
+
+    if not config.targets:
+        _console.print("[red]✗ No targets configured[/]")
+        return 1
+    _console.print(f"[green]✓ {len(config.targets)} target(s) configured[/]")
+
+    if has_store():
+        _console.print(f"[green]✓ Encrypted secret store present: {SECRETS_FILE}[/]")
+        perm_warning = check_permissions()
+        if perm_warning:
+            _console.print(f"[yellow]! {perm_warning}[/]")
+    elif ENV_FILE.exists():
+        _console.print(
+            f"[yellow]! Using legacy plaintext .env ({ENV_FILE}). Migrate with "
+            f"'queue-aiops secret migrate'.[/]"
+        )
+    else:
+        _console.print(
+            "[yellow]! No secret store yet. Run 'queue-aiops init' to set up "
+            "credentials (stored encrypted).[/]"
+        )
+        problems += 1
+
+    for target in config.targets:
+        try:
+            secret = target.secret
+            if secret:
+                _console.print(
+                    f"[green]✓ Secret present for '{target.name}' ({target.platform})[/]"
+                )
+            else:
+                # Redis auth is optional: an empty secret is a valid lab setup.
+                _console.print(
+                    f"[yellow]! No secret for '{target.name}' ({target.platform}) — "
+                    f"connecting without AUTH (fine for a lab instance).[/]"
+                )
+        except OSError as exc:
+            _console.print(f"[red]✗ {exc}[/]")
+            problems += 1
+
+    if skip_auth:
+        _console.print("[dim]Skipping connectivity check (--skip-auth).[/]")
+        return 1 if problems else 0
+
+    from queue_aiops.connection import ConnectionManager
+
+    mgr = ConnectionManager(config)
+    for target in config.targets:
+        try:
+            conn = mgr.connect(target.name)
+            if target.platform == REDIS:
+                conn.redis_ping()
+                probe = "PING OK"
+            else:
+                conn.get(conn.platform.path("overview"))
+                probe = "management /api/overview OK"
+            _console.print(
+                f"[green]✓ Connected to '{target.name}' ({target.platform} "
+                f"{target.host}) — {probe}[/]"
+            )
+        except Exception as exc:  # noqa: BLE001 — connectivity is a status, not a crash
+            _console.print(f"[red]✗ Connect to '{target.name}' failed: {exc}[/]")
+            problems += 1
+
+    return 1 if problems else 0

queue_aiops/governance/__init__.py

@@ -0,0 +1,40 @@
+"""Governance harness for queue-aiops — audit, policy, budget, undo, sanitize.
+
+A self-contained, vendored governance layer. queue-aiops has NO dependency on
+any external skill family — this package is its own copy of the harness:
+
+  - ``@governed_tool`` — mandatory decorator on every MCP tool: policy pre-check,
+    token/runaway budget guard, graduated-autonomy risk-tier gate, audit logging,
+    and undo-token recording.
+  - unified SQLite audit log under ``~/.queue-aiops/`` (override with
+    ``QUEUE_AIOPS_HOME``).
+  - ``sanitize`` — output hygiene (encoding-level defense) for API-returned text.
+
+State lives under ``ops_home()`` (default ``~/.queue-aiops``).
+"""
+
+from queue_aiops.governance.audit import AuditEngine, get_engine
+from queue_aiops.governance.budget import BudgetExceeded, BudgetTracker, get_budget
+from queue_aiops.governance.decorators import PolicyDenied, governed_tool
+from queue_aiops.governance.patterns import Pattern, PatternMatch, get_pattern_engine
+from queue_aiops.governance.policy import TierDecision, get_policy_engine
+from queue_aiops.governance.sanitize import sanitize
+from queue_aiops.governance.undo import UndoStore, get_undo_store
+
+__all__ = [
+    "governed_tool",
+    "sanitize",
+    "PolicyDenied",
+    "get_engine",
+    "AuditEngine",
+    "get_policy_engine",
+    "TierDecision",
+    "get_budget",
+    "BudgetTracker",
+    "BudgetExceeded",
+    "get_undo_store",
+    "UndoStore",
+    "Pattern",
+    "PatternMatch",
+    "get_pattern_engine",
+]