(** Cmdliner terms for Matrix CLI applications.

    This module provides reusable cmdliner terms and combinators for building
    Matrix client command-line interfaces. It follows the principle of
    separation: parsing logic lives here, whilst business logic should remain
    in plain OCaml functions that receive already-parsed values.

    {2 Design Principles}

    - {b Clarity}: Each option has a single, clearly stated purpose
    - {b Orthogonality}: Each flag controls one independent aspect
    - {b Discoverability}: Good --help output with defaults documented
    - {b Composability}: Terms can be combined for different CLI tools

    {2 Example Usage}

    {[
      open Cmdliner

      let run ~homeserver ~profile ~verbose () =
        (* your implementation *)
        ()

      let term =
        let open Matrix_client.Cmd in
        Term.(const run
              $ homeserver_term
              $ profile_term
              $ verbose_term)

      let cmd =
        let info = Cmd.info "myapp" ~doc:"My Matrix app" in
        Cmd.v info term
    ]} *)

open Cmdliner

(** {1 Connection Options} *)

(** Matrix homeserver URL term.

    Accepts [--homeserver URL] or [-s URL], with fallback to
    [MATRIX_HOMESERVER] environment variable.

    @return The homeserver URL as a string *)
val homeserver_term : string Term.t

(** Matrix homeserver URL term (optional).

    Like {!homeserver_term} but returns [None] if not specified.
    Useful when a stored session may provide the homeserver. *)
val homeserver_opt_term : string option Term.t

(** {1 Authentication Options} *)

(** Username term.

    Accepts [--username USER] or [-u USER], with fallback to
    [MATRIX_USERNAME] environment variable. Accepts either a
    localpart or full [@user:server] format. *)
val username_term : string Term.t

(** Username term (optional). *)
val username_opt_term : string option Term.t

(** Password term.

    Accepts [--password PASS] or [-p PASS], with fallback to
    [MATRIX_PASSWORD] environment variable.

    {b Security note}: The environment variable is preferred
    over the command-line flag to avoid password exposure in
    process listings. *)
val password_term : string Term.t

(** Password term (optional). *)
val password_opt_term : string option Term.t

(** {1 Session Management} *)

(** Profile name term.

    Accepts [--profile NAME] with default ["default"].
    Profiles are stored in [$XDG_DATA_HOME/matrix/profiles/NAME/].

    Multiple profiles allow managing several Matrix accounts
    on the same machine. *)
val profile_term : string Term.t

(** {1 Target Options} *)

(** Room ID term.

    Accepts [--room ROOM_ID] or [-r ROOM_ID].
    The room ID should be in the format [!roomid:server]. *)
val room_term : string Term.t

(** Room ID term (optional). *)
val room_opt_term : string option Term.t

(** Recipient user ID term.

    Accepts [--to USER_ID] or [-t USER_ID].
    The user ID should be in the format [@user:server].
    Used for direct messages. *)
val recipient_term : string Term.t

(** Recipient user ID term (optional). *)
val recipient_opt_term : string option Term.t

(** {1 Message Options} *)

(** Message body term.

    A positional argument for the message text to send. *)
val message_term : string Term.t

(** Message body term (optional). *)
val message_opt_term : string option Term.t

(** {1 Encryption Options} *)

(** Encrypted flag term.

    Accepts [--encrypted] or [-e].
    Enables end-to-end encryption for newly created rooms. *)
val encrypted_term : bool Term.t

(** {1 Logging Options} *)

(** Verbosity level term.

    Accepts [-v] (repeatable) for increasing verbosity:
    - No flags: warnings and errors only
    - [-v]: info messages
    - [-v -v]: debug messages

    Also respects [--color] for output styling.

    This term returns [unit] and sets up logging as a side effect
    when the term is evaluated. *)
val verbosity_term : unit Term.t

(** {1 Argument Converters} *)

(** Cmdliner converter for Matrix user IDs.

    Validates that the string is a valid user ID in the format
    [@localpart:server]. *)
val user_id_conv : Matrix_proto.Id.User_id.t Arg.conv

(** Cmdliner converter for Matrix room IDs.

    Validates that the string is a valid room ID in the format
    [!opaque_id:server]. *)
val room_id_conv : Matrix_proto.Id.Room_id.t Arg.conv

(** Cmdliner converter for URIs. *)
val uri_conv : Uri.t Arg.conv

(** {1 Parsed Types}

    Record types for collecting parsed arguments, useful for
    structuring command implementations. *)

(** Credentials for password-based login. *)
type login_credentials = {
  homeserver : string;
  username : string;
  password : string;
  profile : string;
}

(** Term that collects login credentials. *)
val login_credentials_term : login_credentials Term.t

(** Target for sending a message (room or DM). *)
type message_target =
  | Room of string      (** Room ID *)
  | Direct of string    (** Recipient user ID *)

(** Message parameters for sending. *)
type message_params = {
  target : message_target;
  body : string;
  encrypted : bool;
}

(** {1 Command Builders}

    Helper functions for building common command patterns. *)

(** Exit codes following standard conventions.

    - [exit_ok]: Success (0)
    - [exit_usage]: Usage error (64)
    - [exit_auth]: Authentication failure (77)
    - [exit_network]: Network error (69)
    - [exit_internal]: Internal error (70) *)

val exit_ok : Cmd.Exit.code
val exit_usage : Cmd.Exit.code
val exit_auth : Cmd.Exit.code
val exit_network : Cmd.Exit.code
val exit_internal : Cmd.Exit.code