hyperping 1.8.0__tar.gz → 1.8.1__tar.gz

{hyperping-1.8.0 → hyperping-1.8.1}/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.8.1] - 2026-07-14
+
+### Fixed
+
+- **`list_status_pages()` returned an empty list against the live v2 API.** The
+  `StatusPage` model required a `subdomain` field, but the API returns the hosted
+  subdomain under the key `hostedsubdomain` (and omits it entirely for custom-domain
+  pages). Every record failed validation and was silently skipped. `subdomain` is now
+  optional and aliased to `hostedsubdomain`; `hostname` and `url` are also parsed.
+
+### Added
+
+- **`create_maintenance()` now guards against the silent status-page overflow.**
+  Hyperping's v1 maintenance-windows API accepts a create with more than 51 status
+  pages (returns a uuid) but never persists the window. `create_maintenance` now raises
+  `HyperpingValidationError` when `statuspages` exceeds `MAX_STATUSPAGES_PER_MAINTENANCE`
+  (51), instead of returning a phantom window. Split larger sets across multiple windows.
+- **`create_maintenance_windows()`** (sync + async): convenience helper that splits a
+  large `statuspages` list into consecutive windows of at most 51 pages, so callers can
+  cover more pages than one window allows. Each window carries the full monitor set (the
+  API requires at least one monitor per window). `MAX_STATUSPAGES_PER_MAINTENANCE` is
+  exported for callers that chunk themselves (e.g. a broadcast-to-all-tenants command).
+
 ## [1.8.0] - 2026-05-31
 
 This is a security-focused release. It closes several credential-leak and validation gaps surfaced by an independent audit. One change is breaking for local-development workflows; see Upgrade Notes below.

{hyperping-1.8.0 → hyperping-1.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperping
-Version: 1.8.0
+Version: 1.8.1
 Summary: Python SDK for the Hyperping uptime monitoring and incident management API
 Project-URL: Homepage, https://github.com/develeap/hyperping-python
 Project-URL: Documentation, https://github.com/develeap/hyperping-python#readme
@@ -12,6 +12,7 @@ License: MIT
 License-File: LICENSE
 Keywords: api-client,httpx,hyperping,incident,monitoring,pydantic,python,sdk,status-page,uptime
 Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
@@ -25,6 +26,8 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: httpx<1.0,>=0.27
 Requires-Dist: pydantic<3.0,>=2.0
+Provides-Extra: cli
+Requires-Dist: typer[all]<1.0,>=0.12; extra == 'cli'
 Provides-Extra: dev
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pip-audit>=2.7; extra == 'dev'
@@ -33,6 +36,7 @@ Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest>=9.0.3; extra == 'dev'
 Requires-Dist: respx>=0.21; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: typer[all]<1.0,>=0.12; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # hyperping

{hyperping-1.8.0 → hyperping-1.8.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hyperping"
-version = "1.8.0"
+version = "1.8.1"
 description = "Python SDK for the Hyperping uptime monitoring and incident management API"
 readme = {file = "README.md", content-type = "text/markdown"}
 license = {text = "MIT"}
@@ -23,6 +23,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Internet :: WWW/HTTP",
     "Typing :: Typed",
+    "Environment :: Console",
 ]
 dependencies = [
     "httpx>=0.27,<1.0",
@@ -30,6 +31,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+cli = ["typer[all]>=0.12,<1.0"]
 dev = [
     "pytest>=9.0.3",
     "pytest-cov",
@@ -38,8 +40,12 @@ dev = [
     "mypy>=1.10",
     "pydantic",
     "pip-audit>=2.7",
+    "typer[all]>=0.12,<1.0",
 ]
 
+[project.scripts]
+hyp = "hyperping.cli._app:app"
+
 [project.urls]
 Homepage      = "https://github.com/develeap/hyperping-python"
 Documentation = "https://github.com/develeap/hyperping-python#readme"

{hyperping-1.8.0 → hyperping-1.8.1}/src/hyperping/__init__.py

@@ -16,6 +16,7 @@ Quick start::
 
 from hyperping._async_client import AsyncHyperpingClient
 from hyperping._async_mcp_client import AsyncHyperpingMcpClient
+from hyperping._maintenance_mixin import MAX_STATUSPAGES_PER_MAINTENANCE
 from hyperping._version import __version__
 from hyperping.client import (
     CircuitBreaker,
@@ -44,6 +45,7 @@ from hyperping.models import (
     AlertHistory,
     DnsRecordType,
     EscalationPolicy,
+    EscalationStep,
     Healthcheck,
     HealthcheckCreate,
     HealthcheckUpdate,
@@ -149,6 +151,7 @@ __all__ = [
     "IncidentStatus",
     "IncidentUpdateCreate",
     # Maintenance
+    "MAX_STATUSPAGES_PER_MAINTENANCE",
     "Maintenance",
     "MaintenanceCreate",
     "MaintenanceUpdate",
@@ -168,6 +171,7 @@ __all__ = [
     "ProbeLogResponse",
     # On-call
     "OnCallSchedule",
+    "EscalationStep",
     "EscalationPolicy",
     "TeamMember",
     # Integrations

{hyperping-1.8.0 → hyperping-1.8.1}/src/hyperping/_async_maintenance_mixin.py

@@ -9,9 +9,11 @@ from __future__ import annotations
 import logging
 from datetime import UTC, datetime
 
+from hyperping._maintenance_mixin import MAX_STATUSPAGES_PER_MAINTENANCE
 from hyperping._protocols import _AsyncClientProtocol
 from hyperping._utils import expect_dict, parse_list, unwrap_list, validate_id
 from hyperping.endpoints import Endpoint
+from hyperping.exceptions import HyperpingValidationError
 from hyperping.models import (
     Maintenance,
     MaintenanceCreate,
@@ -82,6 +84,15 @@ class AsyncMaintenanceMixin(_AsyncClientProtocol):
             v1 API returns {"uuid": "..."} on create, not the full maintenance object.
             The full maintenance window is fetched after creation.
         """
+        n_statuspages = len(maintenance.statuspages or [])
+        if n_statuspages > MAX_STATUSPAGES_PER_MAINTENANCE:
+            raise HyperpingValidationError(
+                f"A maintenance window can reference at most "
+                f"{MAX_STATUSPAGES_PER_MAINTENANCE} status pages, but {n_statuspages} "
+                f"were supplied. Above this limit Hyperping's API accepts the create "
+                f"(returns a uuid) but silently fails to persist the window. Split the "
+                f"status pages across multiple maintenance windows."
+            )
         payload = maintenance.model_dump(exclude_none=True, by_alias=True, mode="json")
         response = expect_dict(
             await self._request("POST", Endpoint.MAINTENANCE, json=payload),
@@ -91,6 +102,33 @@ class AsyncMaintenanceMixin(_AsyncClientProtocol):
             return await self.get_maintenance(response["uuid"])
         return Maintenance.model_validate(response)
 
+    async def create_maintenance_windows(
+        self,
+        maintenance: MaintenanceCreate,
+        *,
+        chunk_size: int = MAX_STATUSPAGES_PER_MAINTENANCE,
+    ) -> list[Maintenance]:
+        """Create one or more windows, splitting status pages into chunks.
+
+        Async mirror of
+        :meth:`~hyperping._maintenance_mixin.MaintenanceMixin.create_maintenance_windows`.
+        """
+        if not 1 <= chunk_size <= MAX_STATUSPAGES_PER_MAINTENANCE:
+            raise HyperpingValidationError(
+                f"chunk_size must be between 1 and "
+                f"{MAX_STATUSPAGES_PER_MAINTENANCE}, got {chunk_size}."
+            )
+        pages = list(maintenance.statuspages or [])
+        if len(pages) <= chunk_size:
+            return [await self.create_maintenance(maintenance)]
+        windows: list[Maintenance] = []
+        for start in range(0, len(pages), chunk_size):
+            chunk = maintenance.model_copy(
+                update={"statuspages": pages[start : start + chunk_size]}
+            )
+            windows.append(await self.create_maintenance(chunk))
+        return windows
+
     async def update_maintenance(
         self,
         maintenance_id: str,

{hyperping-1.8.0 → hyperping-1.8.1}/src/hyperping/_async_mcp_client.py

@@ -21,7 +21,7 @@ from pydantic import SecretStr
 from hyperping._async_mcp_transport import AsyncMcpTransport
 from hyperping.endpoints import MCP_URL
 from hyperping.models._integration_models import Integration
-from hyperping.models._monitor_models import Monitor
+from hyperping.models._monitor_models import Monitor, MonitorCreate
 from hyperping.models._observability_models import MonitorAnomaly, ProbeLogResponse
 from hyperping.models._oncall_models import EscalationPolicy, OnCallSchedule, TeamMember
 from hyperping.models._outage_models import OutageTimeline
@@ -270,3 +270,52 @@ class AsyncHyperpingMcpClient:
         data = await self._call("search_monitors_by_name", {"query": query})
         raw = data if isinstance(data, list) else []
         return [Monitor.model_validate(m) for m in raw]
+
+    async def create_monitor(self, monitor: MonitorCreate) -> Monitor:
+        """Create a new monitor.
+
+        Args:
+            monitor: Monitor configuration.
+        """
+        return Monitor.model_validate(
+            await self._call("create_monitor", monitor.model_dump(exclude_none=True))
+        )
+
+    async def update_monitor(self, monitor_uuid: str, **kwargs: Any) -> Monitor:
+        """Update an existing monitor.
+
+        Args:
+            monitor_uuid: Monitor UUID.
+            **kwargs: Fields to update.
+        """
+        return Monitor.model_validate(
+            await self._call("update_monitor", {"uuid": monitor_uuid, **kwargs})
+        )
+
+    async def pause_monitor(self, monitor_uuid: str) -> Monitor:
+        """Pause a monitor.
+
+        Args:
+            monitor_uuid: Monitor UUID.
+        """
+        return Monitor.model_validate(
+            await self._call("pause_monitor", {"uuid": monitor_uuid})
+        )
+
+    async def resume_monitor(self, monitor_uuid: str) -> Monitor:
+        """Resume a paused monitor.
+
+        Args:
+            monitor_uuid: Monitor UUID.
+        """
+        return Monitor.model_validate(
+            await self._call("resume_monitor", {"uuid": monitor_uuid})
+        )
+
+    async def delete_monitor(self, monitor_uuid: str) -> None:
+        """Delete a monitor.
+
+        Args:
+            monitor_uuid: Monitor UUID.
+        """
+        await self._call("delete_monitor", {"uuid": monitor_uuid})

{hyperping-1.8.0 → hyperping-1.8.1}/src/hyperping/_maintenance_mixin.py

@@ -12,12 +12,22 @@ from datetime import UTC, datetime
 from hyperping._protocols import _ClientProtocol
 from hyperping._utils import expect_dict, parse_list, unwrap_list, validate_id
 from hyperping.endpoints import Endpoint
+from hyperping.exceptions import HyperpingValidationError
 from hyperping.models import (
     Maintenance,
     MaintenanceCreate,
     MaintenanceUpdate,
 )
 
+# Hyperping's v1 maintenance-windows API silently drops a create when the
+# ``statuspages`` array exceeds this many entries: the POST still returns a
+# ``{"uuid": ...}`` but the window is never persisted (the follow-up GET 404s
+# and it is absent from the list). Empirically the cutoff is 51 (51 persists,
+# 52+ vanishes), verified against the live API on 2026-07-14. Guard the create
+# so callers get a clear error instead of a phantom window; split larger sets
+# across multiple windows.
+MAX_STATUSPAGES_PER_MAINTENANCE = 51
+
 logger = logging.getLogger(__name__)
 
 
@@ -88,6 +98,15 @@ class MaintenanceMixin(_ClientProtocol):
             v1 API returns {"uuid": "..."} on create, not the full maintenance object.
             The full maintenance window is fetched after creation.
         """
+        n_statuspages = len(maintenance.statuspages or [])
+        if n_statuspages > MAX_STATUSPAGES_PER_MAINTENANCE:
+            raise HyperpingValidationError(
+                f"A maintenance window can reference at most "
+                f"{MAX_STATUSPAGES_PER_MAINTENANCE} status pages, but {n_statuspages} "
+                f"were supplied. Above this limit Hyperping's API accepts the create "
+                f"(returns a uuid) but silently fails to persist the window. Split the "
+                f"status pages across multiple maintenance windows."
+            )
         payload = maintenance.model_dump(exclude_none=True, by_alias=True, mode="json")
         response = expect_dict(
             self._request("POST", Endpoint.MAINTENANCE, json=payload),
@@ -99,6 +118,50 @@ class MaintenanceMixin(_ClientProtocol):
             return self.get_maintenance(response["uuid"])
         return Maintenance.model_validate(response)
 
+    def create_maintenance_windows(
+        self,
+        maintenance: MaintenanceCreate,
+        *,
+        chunk_size: int = MAX_STATUSPAGES_PER_MAINTENANCE,
+    ) -> list[Maintenance]:
+        """Create one or more windows, splitting status pages into chunks.
+
+        Hyperping silently fails to persist a window with more than
+        :data:`MAX_STATUSPAGES_PER_MAINTENANCE` status pages (see
+        :meth:`create_maintenance`). This helper splits a large ``statuspages``
+        list into consecutive windows of at most ``chunk_size`` pages so every
+        page is covered. Each window carries the full ``monitors`` set (the API
+        rejects a window with no monitors); overlapping monitor coverage across
+        the windows is harmless.
+
+        Args:
+            maintenance: Creation data; ``statuspages`` may exceed the limit.
+            chunk_size: Max status pages per window (1..
+                :data:`MAX_STATUSPAGES_PER_MAINTENANCE`).
+
+        Returns:
+            The created windows in page order (a single window when the pages
+            fit in one chunk).
+
+        Raises:
+            HyperpingValidationError: If ``chunk_size`` is out of range.
+        """
+        if not 1 <= chunk_size <= MAX_STATUSPAGES_PER_MAINTENANCE:
+            raise HyperpingValidationError(
+                f"chunk_size must be between 1 and "
+                f"{MAX_STATUSPAGES_PER_MAINTENANCE}, got {chunk_size}."
+            )
+        pages = list(maintenance.statuspages or [])
+        if len(pages) <= chunk_size:
+            return [self.create_maintenance(maintenance)]
+        windows: list[Maintenance] = []
+        for start in range(0, len(pages), chunk_size):
+            chunk = maintenance.model_copy(
+                update={"statuspages": pages[start : start + chunk_size]}
+            )
+            windows.append(self.create_maintenance(chunk))
+        return windows
+
     def update_maintenance(
         self,
         maintenance_id: str,

hyperping-1.8.1/src/hyperping/_version.py

@@ -0,0 +1 @@
+__version__ = "1.8.1"

hyperping-1.8.1/src/hyperping/cli/_app.py

@@ -0,0 +1,52 @@
+"""Main hyp CLI application."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from hyperping._version import __version__
+from hyperping.cli._incidents import incident_app
+from hyperping.cli._monitors import monitor_app
+from hyperping.cli._statuspages import statuspage_app
+from hyperping.cli._tenant import tenant_app
+
+app = typer.Typer(
+    name="hyp",
+    help="Hyperping CLI: manage monitors, incidents, and status pages.",
+    no_args_is_help=True,
+)
+
+app.add_typer(monitor_app, name="monitor")
+app.add_typer(incident_app, name="incident")
+app.add_typer(statuspage_app, name="statuspage")
+app.add_typer(tenant_app, name="tenant")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"hyp {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    api_key: Annotated[
+        str | None,
+        typer.Option("--api-key", envvar="HYPERPING_API_KEY", help="Hyperping API key."),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Output as JSON."),
+    ] = False,
+    version: Annotated[
+        bool | None,
+        typer.Option("--version", callback=_version_callback, is_eager=True, help="Show version."),
+    ] = None,
+) -> None:
+    """Hyperping CLI."""
+    ctx.ensure_object(dict)
+    ctx.obj["api_key"] = api_key
+    ctx.obj["json"] = json_output

hyperping-1.8.1/src/hyperping/cli/_config.py

@@ -0,0 +1,24 @@
+"""CLI client factory and API key resolution."""
+
+from __future__ import annotations
+
+import os
+
+import typer
+
+from hyperping.client import HyperpingClient
+
+
+def get_client(api_key: str | None) -> HyperpingClient:
+    """Resolve API key and return a configured client.
+
+    Resolution order: explicit flag value, then HYPERPING_API_KEY env var.
+    Raises typer.BadParameter if no key is available.
+    """
+    key = api_key or os.environ.get("HYPERPING_API_KEY")
+    if not key:
+        raise typer.BadParameter(
+            "API key required. Pass --api-key or set HYPERPING_API_KEY.",
+            param_hint="--api-key",
+        )
+    return HyperpingClient(api_key=key)

hyperping-1.8.1/src/hyperping/cli/_incidents.py

@@ -0,0 +1,87 @@
+"""hyp incident subcommands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from hyperping.cli._config import get_client
+from hyperping.cli._output import print_detail, print_error, print_success, print_table
+from hyperping.exceptions import HyperpingAPIError
+from hyperping.models import Incident, IncidentCreate, IncidentType, LocalizedText
+
+incident_app = typer.Typer(name="incident", help="Manage incidents.")
+
+
+def _incident_row(i: Incident) -> list[object]:
+    return [i.uuid, i.title_en, i.type, str(i.is_resolved), i.date or ""]
+
+
+@incident_app.command("list")
+def incident_list(
+    ctx: typer.Context,
+    status: Annotated[str | None, typer.Option("--status", help="Filter by status")] = None,
+) -> None:
+    """List incidents."""
+    api_key: str | None = ctx.obj.get("api_key")
+    json_mode: bool = ctx.obj.get("json", False)
+    client = get_client(api_key)
+    incidents = client.list_incidents(status=status)
+    columns = ["uuid", "title", "type", "resolved", "date"]
+    rows = [_incident_row(i) for i in incidents]
+    print_table("Incidents", columns, rows, json_mode)
+
+
+@incident_app.command("create")
+def incident_create(
+    ctx: typer.Context,
+    title: Annotated[str, typer.Option("--title", help="Incident title (English)")],
+    text: Annotated[str, typer.Option("--text", help="Incident message (English)")],
+    statuspage: Annotated[str, typer.Option("--statuspage", help="Status page UUID")],
+    incident_type: Annotated[
+        str | None, typer.Option("--type", help="Incident type: incident or outage")
+    ] = None,
+) -> None:
+    """Create a new incident."""
+    api_key: str | None = ctx.obj.get("api_key")
+    json_mode: bool = ctx.obj.get("json", False)
+    client = get_client(api_key)
+    payload = IncidentCreate(
+        title=LocalizedText.from_string(title),
+        text=LocalizedText.from_string(text),
+        type=IncidentType(incident_type) if incident_type else IncidentType.INCIDENT,
+        statuspages=[statuspage],
+    )
+    try:
+        incident = client.create_incident(payload)
+    except HyperpingAPIError as exc:
+        print_error(str(exc))
+        raise typer.Exit(code=1) from exc
+    fields = {
+        "uuid": incident.uuid,
+        "title": incident.title_en,
+        "type": incident.type,
+        "resolved": incident.is_resolved,
+        "date": incident.date or "",
+    }
+    print_detail("Incident", fields, json_mode)
+
+
+@incident_app.command("resolve")
+def incident_resolve(
+    ctx: typer.Context,
+    incident_id: Annotated[str, typer.Argument(help="Incident UUID")],
+    message: Annotated[
+        str | None, typer.Option("--message", help="Resolution message")
+    ] = None,
+) -> None:
+    """Resolve an incident."""
+    api_key: str | None = ctx.obj.get("api_key")
+    client = get_client(api_key)
+    try:
+        incident = client.resolve_incident(incident_id, message=message)
+    except HyperpingAPIError as exc:
+        print_error(str(exc))
+        raise typer.Exit(code=1) from exc
+    print_success(f"Incident {incident.uuid} resolved.")

hyperping-1.8.1/src/hyperping/cli/_monitors.py

@@ -0,0 +1,90 @@
+"""hyp monitor subcommands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from hyperping.cli._config import get_client
+from hyperping.cli._output import print_detail, print_error, print_success, print_table
+from hyperping.exceptions import HyperpingAPIError
+from hyperping.models import Monitor
+
+monitor_app = typer.Typer(name="monitor", help="Manage monitors.")
+
+
+def _monitor_status(m: Monitor) -> str:
+    if m.paused:
+        return "paused"
+    return "down" if m.down else "up"
+
+
+@monitor_app.command("list")
+def monitor_list(ctx: typer.Context) -> None:
+    """List all monitors."""
+    api_key: str | None = ctx.obj.get("api_key")
+    json_mode: bool = ctx.obj.get("json", False)
+    client = get_client(api_key)
+    monitors = client.list_monitors()
+    columns = ["uuid", "name", "url", "protocol", "status"]
+    rows = [[m.uuid, m.name, m.url, m.protocol, _monitor_status(m)] for m in monitors]
+    print_table("Monitors", columns, rows, json_mode)
+
+
+@monitor_app.command("get")
+def monitor_get(
+    ctx: typer.Context,
+    monitor_id: Annotated[str, typer.Argument(help="Monitor UUID")],
+) -> None:
+    """Show a single monitor."""
+    api_key: str | None = ctx.obj.get("api_key")
+    json_mode: bool = ctx.obj.get("json", False)
+    client = get_client(api_key)
+    try:
+        m = client.get_monitor(monitor_id)
+    except HyperpingAPIError as exc:
+        print_error(str(exc))
+        raise typer.Exit(code=1) from exc
+    fields = {
+        "uuid": m.uuid,
+        "name": m.name,
+        "url": m.url,
+        "protocol": m.protocol,
+        "status": _monitor_status(m),
+        "check_frequency": m.check_frequency,
+        "regions": ", ".join(m.regions),
+    }
+    print_detail("Monitor", fields, json_mode)
+
+
+@monitor_app.command("pause")
+def monitor_pause(
+    ctx: typer.Context,
+    monitor_id: Annotated[str, typer.Argument(help="Monitor UUID")],
+) -> None:
+    """Pause a monitor."""
+    api_key: str | None = ctx.obj.get("api_key")
+    client = get_client(api_key)
+    try:
+        m = client.pause_monitor(monitor_id)
+    except HyperpingAPIError as exc:
+        print_error(str(exc))
+        raise typer.Exit(code=1) from exc
+    print_success(f"Monitor {m.uuid} paused (status: {_monitor_status(m)})")
+
+
+@monitor_app.command("resume")
+def monitor_resume(
+    ctx: typer.Context,
+    monitor_id: Annotated[str, typer.Argument(help="Monitor UUID")],
+) -> None:
+    """Resume a paused monitor."""
+    api_key: str | None = ctx.obj.get("api_key")
+    client = get_client(api_key)
+    try:
+        m = client.resume_monitor(monitor_id)
+    except HyperpingAPIError as exc:
+        print_error(str(exc))
+        raise typer.Exit(code=1) from exc
+    print_success(f"Monitor {m.uuid} resumed (status: {_monitor_status(m)})")

hyperping-1.8.1/src/hyperping/cli/_output.py

@@ -0,0 +1,58 @@
+"""CLI output formatters: rich tables, panels, and JSON."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+_console = Console()
+_err_console = Console(stderr=True)
+
+
+def print_table(
+    title: str,
+    columns: list[str],
+    rows: list[list[Any]],
+    json_mode: bool,
+) -> None:
+    """Render a list of rows as a rich table or a JSON array."""
+    if json_mode:
+        data = [dict(zip(columns, row)) for row in rows]
+        typer.echo(json.dumps(data, indent=2, default=str))
+        return
+
+    table = Table(title=title, show_header=True, header_style="bold")
+    for col in columns:
+        table.add_column(col)
+    for row in rows:
+        table.add_row(*[str(v) if v is not None else "" for v in row])
+    _console.print(table)
+
+
+def print_detail(
+    title: str,
+    fields: dict[str, Any],
+    json_mode: bool,
+) -> None:
+    """Render a single record as a rich panel or a JSON object."""
+    if json_mode:
+        typer.echo(json.dumps(fields, indent=2, default=str))
+        return
+
+    lines = "\n".join(f"[bold]{k}[/bold]: {v}" for k, v in fields.items())
+    _console.print(Panel(lines, title=title))
+
+
+def print_success(message: str) -> None:
+    """Print a success message."""
+    _console.print(f"[green]{message}[/green]")
+
+
+def print_error(message: str) -> None:
+    """Print an error message to stderr."""
+    _err_console.print(f"[red]{message}[/red]")