ipa-diagnose 0.1.0__py3-none-any.whl

ipa_diagnose/__init__.py

@@ -0,0 +1,10 @@
+"""ipa-diagnose: evidence-grounded diagnostic and correlation engine for FreeIPA / Red Hat IdM."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("ipa-diagnose")
+except PackageNotFoundError:  # pragma: no cover - only hit for an unpackaged checkout
+    __version__ = "0.0.0+unknown"

ipa_diagnose/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from ipa_diagnose.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

ipa_diagnose/ai/__init__.py

@@ -0,0 +1,19 @@
+from ipa_diagnose.ai.provider import (
+    AIProvider,
+    ProviderAuthError,
+    ProviderConnectionError,
+    ProviderError,
+    ProviderRateLimitError,
+    ProviderRefusalError,
+    ProviderTimeoutError,
+)
+
+__all__ = [
+    "AIProvider",
+    "ProviderAuthError",
+    "ProviderConnectionError",
+    "ProviderError",
+    "ProviderRateLimitError",
+    "ProviderRefusalError",
+    "ProviderTimeoutError",
+]

ipa_diagnose/ai/anthropic_provider.py

@@ -0,0 +1,67 @@
+"""Anthropic adapter. Requires the `anthropic` extra (`pip install ipa-diagnose[anthropic]`)."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ipa_diagnose.ai.provider import (
+    AIProvider,
+    AIRequest,
+    AIResponse,
+    ProviderAuthError,
+    ProviderConnectionError,
+    ProviderError,
+    ProviderRateLimitError,
+    ProviderRefusalError,
+    ProviderTimeoutError,
+    ProviderUnavailableError,
+)
+
+
+class AnthropicProvider(AIProvider):
+    provider_name = "anthropic"
+
+    def __init__(self, *, api_key: Optional[str], model: str, timeout: float):
+        self._api_key = api_key
+        self._model = model
+        self._timeout = timeout
+
+    def is_configured(self) -> bool:
+        return bool(self._api_key)
+
+    def generate(self, request: AIRequest) -> AIResponse:
+        if not self._api_key:
+            raise ProviderAuthError("ANTHROPIC_API_KEY is not set")
+        try:
+            import anthropic
+        except ImportError as e:
+            raise ProviderError(
+                "the 'anthropic' package is not installed (pip install 'ipa-diagnose[anthropic]')"
+            ) from e
+
+        client = anthropic.Anthropic(api_key=self._api_key, timeout=min(request.timeout, self._timeout))
+        try:
+            message = client.messages.create(
+                model=self._model,
+                max_tokens=request.max_tokens,
+                system=request.system_prompt,
+                messages=[{"role": "user", "content": request.user_prompt}],
+            )
+        except anthropic.AuthenticationError as e:
+            raise ProviderAuthError(str(e)) from e
+        except anthropic.RateLimitError as e:
+            raise ProviderRateLimitError(str(e)) from e
+        except anthropic.APITimeoutError as e:
+            raise ProviderTimeoutError(str(e)) from e
+        except anthropic.APIConnectionError as e:
+            raise ProviderConnectionError(str(e)) from e
+        except anthropic.APIStatusError as e:
+            raise ProviderUnavailableError(str(e)) from e
+
+        if getattr(message, "stop_reason", None) == "refusal":
+            raise ProviderRefusalError("Claude declined to produce a response")
+        blocks = [b.text for b in message.content if getattr(b, "type", None) == "text"]
+        text = "\n".join(blocks).strip()
+        if not text:
+            raise ProviderRefusalError("Claude returned an empty response")
+        return AIResponse(text=text, provider_name=self.provider_name, model=self._model)

ipa_diagnose/ai/bedrock_provider.py

@@ -0,0 +1,100 @@
+"""AWS Bedrock adapter (Converse API). Requires the `bedrock` extra
+(`pip install ipa-diagnose[bedrock]`, which installs boto3).
+
+Uses boto3's standard credential chain (env vars, ~/.aws, EC2/ECS instance
+role, assumed role) rather than requiring explicit keys - the realistic
+default for this tool's audience is an IAM role already attached to the
+host. See docs/ai-configuration.md for the cross-region inference-profile
+gotcha this adapter's default model id already works around.
+"""
+
+from __future__ import annotations
+
+from ipa_diagnose.ai.provider import (
+    AIProvider,
+    AIRequest,
+    AIResponse,
+    ProviderAuthError,
+    ProviderConnectionError,
+    ProviderError,
+    ProviderRateLimitError,
+    ProviderRefusalError,
+    ProviderTimeoutError,
+    ProviderUnavailableError,
+)
+
+_RETRYABLE_BUT_STILL_UNAVAILABLE = {"ServiceUnavailableException", "InternalServerError", "ModelTimeoutException"}
+
+
+class BedrockProvider(AIProvider):
+    provider_name = "bedrock"
+
+    def __init__(self, *, model_id: str, region: str, timeout: float):
+        self._model_id = model_id
+        self._region = region
+        self._timeout = timeout
+        self._client = None
+
+    def is_configured(self) -> bool:
+        try:
+            import boto3
+        except ImportError:
+            return False
+        try:
+            session = boto3.Session()
+            return session.get_credentials() is not None
+        except Exception:
+            return False
+
+    def _get_client(self):
+        if self._client is None:
+            import boto3
+            from botocore.config import Config
+
+            self._client = boto3.client(
+                "bedrock-runtime",
+                region_name=self._region,
+                config=Config(connect_timeout=self._timeout, read_timeout=self._timeout, retries={"max_attempts": 2}),
+            )
+        return self._client
+
+    def generate(self, request: AIRequest) -> AIResponse:
+        try:
+            import botocore
+        except ImportError as e:
+            raise ProviderError(
+                "the 'boto3' package is not installed (pip install 'ipa-diagnose[bedrock]')"
+            ) from e
+
+        client = self._get_client()
+        try:
+            response = client.converse(
+                modelId=self._model_id,
+                system=[{"text": request.system_prompt}],
+                messages=[{"role": "user", "content": [{"text": request.user_prompt}]}],
+                inferenceConfig={"maxTokens": request.max_tokens},
+            )
+        except botocore.exceptions.ClientError as e:
+            code = e.response.get("Error", {}).get("Code", "")
+            if code in ("AccessDeniedException", "UnrecognizedClientException"):
+                raise ProviderAuthError(str(e)) from e
+            if code == "ThrottlingException":
+                raise ProviderRateLimitError(str(e)) from e
+            if code in _RETRYABLE_BUT_STILL_UNAVAILABLE:
+                raise ProviderUnavailableError(str(e)) from e
+            if code == "ValidationException":
+                raise ProviderError(f"Bedrock rejected the request: {e}") from e
+            raise ProviderUnavailableError(str(e)) from e
+        except botocore.exceptions.ConnectTimeoutError as e:
+            raise ProviderTimeoutError(str(e)) from e
+        except botocore.exceptions.EndpointConnectionError as e:
+            raise ProviderConnectionError(str(e)) from e
+
+        stop_reason = response.get("stopReason")
+        if stop_reason == "content_filtered":
+            raise ProviderRefusalError("Bedrock content filter declined to produce a response")
+        content = response.get("output", {}).get("message", {}).get("content", [])
+        text = "\n".join(block.get("text", "") for block in content if "text" in block).strip()
+        if not text:
+            raise ProviderRefusalError("Bedrock returned an empty response")
+        return AIResponse(text=text, provider_name=self.provider_name, model=self._model_id)

ipa_diagnose/ai/openai_provider.py

@@ -0,0 +1,76 @@
+"""OpenAI adapter. Requires the `openai` extra (`pip install ipa-diagnose[openai]`).
+
+Import of the `openai` package is deferred into __init__ so this module can
+be imported (e.g. by config.py's lazy factory) without the dependency being
+installed - only actually *using* the openai provider requires it.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ipa_diagnose.ai.provider import (
+    AIProvider,
+    AIRequest,
+    AIResponse,
+    ProviderAuthError,
+    ProviderConnectionError,
+    ProviderError,
+    ProviderRateLimitError,
+    ProviderRefusalError,
+    ProviderTimeoutError,
+    ProviderUnavailableError,
+)
+
+
+class OpenAIProvider(AIProvider):
+    provider_name = "openai"
+
+    def __init__(self, *, api_key: Optional[str], model: str, timeout: float):
+        self._api_key = api_key
+        self._model = model
+        self._timeout = timeout
+
+    def is_configured(self) -> bool:
+        return bool(self._api_key)
+
+    def generate(self, request: AIRequest) -> AIResponse:
+        if not self._api_key:
+            raise ProviderAuthError("OPENAI_API_KEY is not set")
+        try:
+            import openai
+        except ImportError as e:
+            raise ProviderError(
+                "the 'openai' package is not installed (pip install 'ipa-diagnose[openai]')"
+            ) from e
+
+        client = openai.OpenAI(api_key=self._api_key, timeout=min(request.timeout, self._timeout))
+        try:
+            completion = client.chat.completions.create(
+                model=self._model,
+                max_tokens=request.max_tokens,
+                messages=[
+                    {"role": "developer", "content": request.system_prompt},
+                    {"role": "user", "content": request.user_prompt},
+                ],
+            )
+        except openai.AuthenticationError as e:
+            raise ProviderAuthError(str(e)) from e
+        except openai.RateLimitError as e:
+            raise ProviderRateLimitError(str(e)) from e
+        except openai.APITimeoutError as e:
+            raise ProviderTimeoutError(str(e)) from e
+        except openai.APIConnectionError as e:
+            raise ProviderConnectionError(str(e)) from e
+        except openai.InternalServerError as e:
+            raise ProviderUnavailableError(str(e)) from e
+        except openai.APIStatusError as e:
+            raise ProviderUnavailableError(str(e)) from e
+
+        choice = completion.choices[0] if completion.choices else None
+        if choice is None or getattr(choice, "finish_reason", None) == "content_filter":
+            raise ProviderRefusalError("OpenAI declined to produce a response (content filter)")
+        text = (choice.message.content or "").strip()
+        if not text:
+            raise ProviderRefusalError("OpenAI returned an empty response")
+        return AIResponse(text=text, provider_name=self.provider_name, model=self._model)

ipa_diagnose/ai/prompt.py

@@ -0,0 +1,98 @@
+"""Ties the privacy pipeline + AIProvider together, with a defense-in-depth
+sanitizer on the way back out.
+
+Structural safety guarantee (the important one): the rendered Actions section
+in the CLI ALWAYS comes from `Diagnosis.actions` (deterministic Action
+objects), never from AI output. An AI explanation is prose displayed
+alongside that section, never a replacement for it. `sanitize_explanation`
+below is a second, best-effort layer on top of that structural guarantee -
+it catches an AI response that ignored its instructions and tried to invent
+a new command anyway, and rejects the whole explanation rather than trying
+to strip just the bad line (a partially-sanitized AI paragraph is more
+misleading than falling back to the deterministic `why` text).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from ipa_diagnose.ai.provider import AIProvider, AIRequest, ProviderError
+from ipa_diagnose.engine.model import Diagnosis
+from ipa_diagnose.evidence.model import EvidenceBundle
+from ipa_diagnose.privacy.minimize import build_ai_payload
+
+# Deliberately NOT anchored to line-start (an earlier version was - a
+# security review found that let prose-embedded suggestions like "you could
+# try: getcert resubmit ..." slip through undetected) and deliberately a
+# broad binary/keyword list rather than an exhaustive one, since the goal is
+# "reject anything command-shaped we don't recognize as approved," not
+# "recognize every dangerous command by name."
+_COMMAND_LIKE = re.compile(
+    # Zero-width lookbehind for the boundary (start-of-string, whitespace, or
+    # a backtick) rather than a consuming group - otherwise match.group(0)
+    # includes the boundary character and would never equal an approved
+    # command string during comparison.
+    r"(?<![^\s`])(?:\$\s*)?(?:sudo\s+)?(?:/usr/(?:s?bin)/)?"
+    r"(ipa[\w-]*|getcert|kinit|klist|kvno|dsconf|dsctl|ldapmodify|ldapsearch|"
+    r"systemctl|service|reboot|shutdown|halt|poweroff|init\s+0|"
+    r"rm\b|mkfs[\w.]*|dd\b|userdel|groupdel|iptables|firewall-cmd|"
+    r"dnf|yum|rpm\b|certutil|db2index[\w.]*|chmod|chown|kill(?:all)?|"
+    r"curl|wget|python[\w.]*|perl|bash|sh\b|nc\b|ncat)\b",
+    re.IGNORECASE,
+)
+_CODE_SPAN = re.compile(r"`([^`\n]{1,200})`")
+_MAX_EXPLANATION_CHARS = 4000
+
+
+def _looks_approved(candidate: str, approved_commands: set) -> bool:
+    candidate = candidate.strip()
+    return any(candidate in cmd or cmd in candidate for cmd in approved_commands)
+
+
+def sanitize_explanation(text: str, diagnosis: Diagnosis) -> Optional[str]:
+    """Returns the explanation if it looks like prose only, else None (caller
+    must fall back to the deterministic `why` text).
+
+    Two independent checks, either of which rejects the whole response:
+    1. Any command-shaped token (see _COMMAND_LIKE) appearing anywhere in
+       the text, not just at a line's start.
+    2. Any markdown-style inline code span (`` `...` ``) whose content isn't
+       one of the diagnosis's own approved commands - this catches the
+       common AI phrasing "run `<command>`" regardless of whether the
+       command inside the backticks matches a known binary name.
+    """
+
+    if not text or not text.strip():
+        return None
+    if len(text) > _MAX_EXPLANATION_CHARS:
+        return None
+
+    approved_commands = {a.command for a in diagnosis.actions if a.command}
+
+    for span_match in _CODE_SPAN.finditer(text):
+        if not _looks_approved(span_match.group(1), approved_commands):
+            return None
+
+    for match in _COMMAND_LIKE.finditer(text):
+        if not _looks_approved(match.group(0), approved_commands):
+            return None
+
+    return text.strip()
+
+
+def explain_diagnosis(diagnosis: Diagnosis, bundle: EvidenceBundle, provider: AIProvider) -> Optional[str]:
+    """Returns an AI explanation, or None on any failure/refusal/unsafe output -
+    callers must always have a local-explanation fallback ready (Diagnosis.why),
+    ipa-diagnose must remain fully useful with this returning None."""
+
+    if not provider.is_configured():
+        return None
+    payload = build_ai_payload(bundle, diagnosis)
+    try:
+        response = provider.generate(
+            AIRequest(system_prompt=payload.system_prompt, user_prompt=payload.user_prompt)
+        )
+    except ProviderError:
+        return None
+    return sanitize_explanation(response.text, diagnosis)

ipa_diagnose/ai/provider.py

@@ -0,0 +1,101 @@
+"""AI provider abstraction.
+
+Exactly one job: turn an already-computed, deterministic Diagnosis into more
+readable prose. A provider implementation NEVER sees raw evidence beyond
+what the privacy/redaction pipeline approved (see privacy/preview.py, which
+renders the exact same payload this module sends - "ai-preview" and the real
+call must never diverge). A provider MUST NOT be asked to produce root
+causes, evidence, confidence, or commands - prompt.py's contract enforces
+this by construction (it only ever asks for an explanation of given facts),
+and render code must ignore/discard anything a provider response contains
+that looks like a new claim (see ai/prompt.py `sanitize_explanation`).
+
+Every concrete provider (OpenAI, Anthropic, Bedrock) is a thin ~20-40 line
+adapter: build client, make one call, map that SDK's specific exceptions
+into the ProviderError hierarchy below so the rest of the codebase never
+branches on provider identity. See docs/ai-configuration.md for the research
+backing the model/error-handling choices per provider.
+"""
+
+from __future__ import annotations
+
+import abc
+import dataclasses
+
+
+class ProviderError(Exception):
+    """Base class for all AI provider failures. Any of these must leave
+    ipa-diagnose fully functional in local-explanation mode - never fatal."""
+
+
+class ProviderAuthError(ProviderError):
+    """Invalid/missing API key or credentials."""
+
+
+class ProviderRateLimitError(ProviderError):
+    """Rate limited; retrying immediately will not help."""
+
+
+class ProviderTimeoutError(ProviderError):
+    """Request exceeded the configured timeout."""
+
+
+class ProviderConnectionError(ProviderError):
+    """Network/connectivity failure reaching the provider."""
+
+
+class ProviderRefusalError(ProviderError):
+    """Provider returned a content-policy refusal or empty/invalid response."""
+
+
+class ProviderUnavailableError(ProviderError):
+    """Provider-side server error (5xx) or service outage."""
+
+
+@dataclasses.dataclass(frozen=True)
+class AIRequest:
+    system_prompt: str
+    user_prompt: str
+    max_tokens: int = 700
+    timeout: float = 12.0
+
+
+@dataclasses.dataclass(frozen=True)
+class AIResponse:
+    text: str
+    provider_name: str
+    model: str
+
+
+class AIProvider(abc.ABC):
+    """Implemented by OpenAIProvider, AnthropicProvider, BedrockProvider."""
+
+    provider_name: str
+
+    @abc.abstractmethod
+    def generate(self, request: AIRequest) -> AIResponse:
+        """Returns a response, or raises a ProviderError subclass. Must never
+        raise anything else - implementations should catch their SDK's own
+        exception types and re-raise as ProviderError subclasses."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def is_configured(self) -> bool:
+        """True if required credentials/config are present, without making a
+        network call. Used to fail fast with a clear message before ever
+        reaching the provider."""
+        raise NotImplementedError
+
+
+class NoAIProvider(AIProvider):
+    """The default. Explicitly refuses to run rather than silently no-op,
+    so callers always go through the same code path (try provider, catch
+    ProviderError, fall back to local explanation)."""
+
+    provider_name = "none"
+
+    def generate(self, request: AIRequest) -> AIResponse:
+        raise ProviderError("AI explanation is disabled (--no-ai or no provider configured)")
+
+    def is_configured(self) -> bool:
+        return False

ipa_diagnose/cli.py

@@ -0,0 +1,190 @@
+"""ipa-diagnose command-line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import Dict, Optional
+
+from rich.console import Console
+
+from ipa_diagnose import __version__
+from ipa_diagnose.ai.prompt import explain_diagnosis
+from ipa_diagnose.config import AIConfig, build_provider
+from ipa_diagnose.engine.model import DiagnosisReport, PriorityBucket
+from ipa_diagnose.engine.run import run_diagnosis
+from ipa_diagnose.evidence.collect import collect_evidence
+from ipa_diagnose.evidence.model import EvidenceBundle
+from ipa_diagnose.privacy.minimize import build_ai_payload
+from ipa_diagnose.privacy.preview import render_preview
+from ipa_diagnose.render.console import render_report, render_verify
+from ipa_diagnose.render.json_output import report_to_dict
+from ipa_diagnose.verify import compare, default_state_path, load_previous_report, save_report
+
+_EXPLAINABLE_PRIORITIES = {PriorityBucket.PRIMARY, PriorityBucket.SECONDARY_INDEPENDENT}
+
+
+def _add_common_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--details", action="store_true", help="show full evidence, confidence, and all actions")
+    parser.add_argument("--json", action="store_true", help="print the report as JSON instead of formatted text")
+    parser.add_argument("--no-ai", action="store_true", help="never contact an AI provider, even if configured")
+    parser.add_argument(
+        "--ai-provider", choices=["openai", "anthropic", "bedrock"], default=None,
+        help="override IPA_DIAGNOSE_AI_PROVIDER for this run",
+    )
+    parser.add_argument(
+        "--replay", metavar="FIXTURE_DIR", default=None,
+        help="read evidence from a fixture directory instead of the live host (development/testing)",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    # A single parser with one optional positional `command`, rather than
+    # argparse subparsers: subparsers each get their own copy of the common
+    # flags' defaults, which silently clobbers a flag given *before* the
+    # subcommand name (e.g. `ipa-diagnose --replay DIR diagnose` would reset
+    # --replay back to None). One shared namespace avoids that entirely.
+    parser = argparse.ArgumentParser(prog="ipa-diagnose", description="FreeIPA / Red Hat IdM diagnostic tool")
+    parser.add_argument("--version", action="version", version=f"ipa-diagnose {__version__}")
+    parser.add_argument(
+        "command",
+        nargs="?",
+        choices=["diagnose", "verify", "ai-preview"],
+        default="diagnose",
+        help="diagnose (default): run diagnosis. verify: check if previously diagnosed problems cleared. "
+        "ai-preview: show exactly what would be sent to the AI provider.",
+    )
+    _add_common_args(parser)
+    return parser
+
+
+def _ai_config_from_args(args: argparse.Namespace) -> AIConfig:
+    return AIConfig.from_env_and_args(no_ai=args.no_ai, provider_arg=args.ai_provider)
+
+
+def _collect_and_diagnose(args: argparse.Namespace) -> tuple[EvidenceBundle, DiagnosisReport]:
+    bundle = collect_evidence(replay_dir=args.replay)
+    report = run_diagnosis(bundle)
+    return bundle, report
+
+
+def _maybe_explain(
+    report: DiagnosisReport, bundle: EvidenceBundle, args: argparse.Namespace, console: Console
+) -> Dict[str, str]:
+    explanations: Dict[str, str] = {}
+    config = _ai_config_from_args(args)
+    if config.provider == "none":
+        return explanations
+    provider = build_provider(config)
+    if not provider.is_configured():
+        console.print(
+            f"[dim](AI provider '{config.provider}' is not configured - showing local explanation)[/dim]"
+        )
+        return explanations
+    for d in report.diagnoses:
+        if d.priority not in _EXPLAINABLE_PRIORITIES:
+            continue
+        text = explain_diagnosis(d, bundle, provider)
+        if text:
+            explanations[d.diagnosis_id] = text
+        else:
+            console.print(
+                f"[dim](AI explanation unavailable for '{d.title}' - showing local explanation)[/dim]"
+            )
+    return explanations
+
+
+def cmd_diagnose(args: argparse.Namespace, console: Console) -> int:
+    bundle, report = _collect_and_diagnose(args)
+    explanations = {} if args.json else _maybe_explain(report, bundle, args, console)
+
+    if args.json:
+        print(json.dumps(report_to_dict(report, explanations), indent=2))
+    else:
+        render_report(report, console, details=args.details, ai_explanations=explanations)
+
+    save_report(default_state_path(), report)
+    return _exit_code_for(report)
+
+
+def cmd_verify(args: argparse.Namespace, console: Console) -> int:
+    bundle, report = _collect_and_diagnose(args)
+    previous = load_previous_report(default_state_path())
+    result = compare(previous, report)
+
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "previous_generated_at": result.previous_generated_at,
+                    "items": [
+                        {"diagnosis_id": i.diagnosis_id, "title": i.title, "outcome": i.outcome.value, "detail": i.detail}
+                        for i in result.items
+                    ],
+                    "new_conditions": [d.title for d in result.new_conditions],
+                    "current_report": report_to_dict(report),
+                },
+                indent=2,
+            )
+        )
+    else:
+        render_verify(result, console)
+
+    save_report(default_state_path(), report)
+    return 0
+
+
+def cmd_ai_preview(args: argparse.Namespace, console: Console) -> int:
+    bundle, report = _collect_and_diagnose(args)
+    explainable = [d for d in report.diagnoses if d.priority in _EXPLAINABLE_PRIORITIES]
+    if not explainable:
+        console.print("[green]No primary or independent problems to explain right now.[/green]")
+        return 0
+    for d in explainable:
+        payload = build_ai_payload(bundle, d)
+        render_preview(payload, console)
+        console.print()
+    return 0
+
+
+def _exit_code_for(report: DiagnosisReport) -> int:
+    from ipa_diagnose.engine.model import OverallStatus
+
+    return {
+        OverallStatus.HEALTHY: 0,
+        OverallStatus.DEGRADED: 1,
+        OverallStatus.CRITICAL: 2,
+        OverallStatus.UNKNOWN: 3,
+    }[report.overall_status]
+
+
+def main(argv: Optional[list] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    # highlight=False: rich's default ReprHighlighter auto-colors substrings
+    # that look like paths/numbers/quoted strings inside plain evidence text
+    # (e.g. a log message), which reads as noise, not signal, in this UI -
+    # all intentional styling here is explicit markup, not auto-detected.
+    console = Console(highlight=False)
+
+    command = args.command or "diagnose"
+    if os.name != "nt" and command in ("diagnose", "verify") and args.replay is None and os.geteuid() != 0:
+        console.print(
+            "[yellow]Warning: not running as root - live evidence collection (ipa-healthcheck, "
+            "journalctl, certmonger) will likely fail or be incomplete.[/yellow]\n"
+        )
+
+    try:
+        if command == "verify":
+            return cmd_verify(args, console)
+        if command == "ai-preview":
+            return cmd_ai_preview(args, console)
+        return cmd_diagnose(args, console)
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())