"""Utilities for working with Typer context safely."""

from __future__ import annotations

import click
import typer

from ..context import CLIContext


def require_cli_context(ctx: typer.Context) -> CLIContext:
    """Return the CLI context or raise a friendly usage error."""
    if isinstance(ctx.obj, CLIContext):
        return ctx.obj

    raise click.UsageError(
        "CLI context is not initialized. Run commands via the installed `ctxme` entrypoint.",
        ctx,
    )
