chore: import upstream snapshot with attribution

surfaces/interactive_shell/utils/error_handling/__init__.py

@@ -0,0 +1 @@
+"""Interactive shell error mapping, rendering, and reporting helpers."""

surfaces/interactive_shell/utils/error_handling/errors.py

@@ -0,0 +1,66 @@
+"""CLI rendering for structured OpenSRE errors.
+
+The frontend-agnostic error contract lives in :mod:`platform.common.errors`.
+This module adds the CLI presentation layer: a ``click.ClickException``
+subclass whose :meth:`show` renders a clean, traceback-free panel via
+:func:`render_error`. CLI code raises this subclass so Click's error path
+renders it; non-CLI code (tools, integrations) raises the platform base, and
+:mod:`cli.__main__` renders that. Catch ``platform.common.errors.OpenSREError``
+to handle both.
+
+render_error()
+--------------
+Catches any exception and displays a clean, terminal-safe error panel without
+ever surfacing a raw Python traceback. Format:
+
+  ✗  ExceptionType                       ← ERROR
+     message text                        ← TEXT
+     path/to/file.py:42 in fn_name      ← DIM
+     Run opensre doctor to diagnose      ← SECONDARY hint
+"""
+
+from __future__ import annotations
+
+import sys
+import typing as t
+
+import click
+from rich.console import Console
+
+from platform.common.errors import OpenSREError as _OpenSREError
+from platform.terminal.errors import render_error
+
+
+# ClickException.message is Final in newer Click; the platform base owns ``message``.
+class OpenSREError(_OpenSREError, click.ClickException):  # type: ignore[misc]
+    """A CLI error that renders with an optional suggestion and docs URL."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        suggestion: str | None = None,
+        docs_url: str | None = None,
+        exit_code: int = 1,
+    ) -> None:
+        # Click 8.2+ marks ``message`` final on ``ClickException``; initialize
+        # through Click and set the platform fields without reassigning ``message``.
+        click.ClickException.__init__(self, message)
+        self.suggestion = suggestion
+        self.docs_url = docs_url
+        self.exit_code = exit_code
+
+    def format_message(self) -> str:
+        return _OpenSREError.format_message(self)
+
+    def show(self, file: t.IO[t.Any] | None = None) -> None:
+        _file = file if file is not None else sys.stderr
+        console = Console(stderr=(_file is sys.stderr), highlight=False)
+        # Prefer the structured suggestion over the generic doctor hint.
+        custom_hint: str | None = None
+        if self.suggestion:
+            parts = [self.suggestion]
+            if self.docs_url:
+                parts.append(f"Docs: {self.docs_url}")
+            custom_hint = "  ".join(parts)
+        render_error(self, console=console, hint=custom_hint)

surfaces/interactive_shell/utils/error_handling/exception_reporting.py

@@ -0,0 +1,37 @@
+"""Shared exception reporting policy for CLI and interactive-shell boundaries."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import click
+
+from platform.common.errors import OpenSREError
+from platform.observability.errors.sentry import capture_exception
+
+
+def should_report_exception(exc: BaseException, *, expected: bool = False) -> bool:
+    """Return whether a caught exception should be reported to Sentry."""
+    if expected:
+        return False
+    if isinstance(exc, (KeyboardInterrupt, EOFError, OpenSREError, click.Abort)):
+        return False
+    return not isinstance(exc, click.UsageError)
+
+
+def report_exception(
+    exc: BaseException,
+    *,
+    context: str,
+    extra: Mapping[str, Any] | None = None,
+    expected: bool = False,
+) -> bool:
+    """Best-effort Sentry report for swallowed boundary exceptions."""
+    if not should_report_exception(exc, expected=expected):
+        return False
+    capture_exception(exc, context=context, extra=extra)
+    return True
+
+
+__all__ = ["report_exception", "should_report_exception"]