"""Shared CLI constants for CleverAgents.

Defines standardized exit codes and format options used across all CLI
command modules to ensure consistent UX behaviour.
"""

from __future__ import annotations

# ---------------------------------------------------------------------------
# Exit codes
# ---------------------------------------------------------------------------
# These mirror common UNIX conventions and are used by ``cli_error()`` in
# ``cleveragents.cli.errors`` as well as individual command handlers.

EXIT_SUCCESS: int = 0
"""Command completed successfully."""

EXIT_ERROR: int = 1
"""General runtime error."""

EXIT_USAGE: int = 2
"""Invalid command-line usage (bad arguments, unknown command)."""

EXIT_NOT_FOUND: int = 3
"""Requested entity was not found."""

EXIT_CONFLICT: int = 4
"""Operation conflicts with existing state (e.g. duplicate name)."""

# ---------------------------------------------------------------------------
# Format option defaults
# ---------------------------------------------------------------------------

FORMAT_HELP: str = (
    "Output format: json, yaml, plain, table, rich, or color (default: rich)"
)
"""Reusable help text for the ``--format`` / ``-f`` option."""

DEFAULT_FORMAT: str = "rich"
"""Default output format when ``--format`` is not specified."""

VALID_FORMATS: tuple[str, ...] = ("json", "yaml", "plain", "table", "rich", "color")
"""Accepted values for the ``--format`` option."""

# ---------------------------------------------------------------------------
# Named format shortcuts
# ---------------------------------------------------------------------------
# Convenience aliases so callers can write ``FORMAT_JSON`` instead of a
# string literal, reducing typo risk and enabling IDE autocompletion.

FORMAT_TEXT: str = "plain"
"""Plain-text output (alias for ``plain``)."""

FORMAT_JSON: str = "json"
"""JSON output."""

FORMAT_TABLE: str = "table"
"""ASCII table output."""

__all__ = [
    "DEFAULT_FORMAT",
    "EXIT_CONFLICT",
    "EXIT_ERROR",
    "EXIT_NOT_FOUND",
    "EXIT_SUCCESS",
    "EXIT_USAGE",
    "FORMAT_HELP",
    "FORMAT_JSON",
    "FORMAT_TABLE",
    "FORMAT_TEXT",
    "VALID_FORMATS",
]
