(** Unified configuration for monopam.

    Configuration is stored in TOML format at [~/.config/monopam/opamverse.toml].

    The config stores:
    - Workspace root and custom paths
    - User identity (handle, knot)
    - Per-package overrides

    Standard paths derived from root:
    - [mono/] - user's monorepo
    - [src/] - git checkouts for subtrees
    - [opam-repo/] - opam overlay repository
    - [verse/] - other members' monorepos *)

(** {1 Types} *)

(** Per-package configuration overrides. *)
module Package_config : sig
  type t
  (** Package-specific settings. *)

  val branch : t -> string option
  (** [branch t] returns the branch override for this package, if set. *)
end

(** Configurable paths within the workspace.

    By default, paths are:
    - [mono = "mono"] - monorepo directory
    - [src = "src"] - source checkouts directory
    - [verse = "verse"] - verse directory

    Set [mono = "."] to have packages at the root level. *)
type paths = {
  mono : string;   (** Monorepo directory (default: "mono") *)
  src : string;    (** Source checkouts directory (default: "src") *)
  verse : string;  (** Verse directory (default: "verse") *)
}

val default_paths : paths
(** Default paths configuration. *)

type t
(** The main configuration. *)

(** {1 Accessors} *)

val root : t -> Fpath.t
(** [root t] returns the workspace root directory. *)

val handle : t -> string
(** [handle t] returns the user's handle. *)

val knot : t -> string
(** [knot t] returns the git push server hostname (e.g., "git.recoil.org").
    Used for converting tangled URLs to SSH push URLs. *)

val paths : t -> paths
(** [paths t] returns the paths configuration. *)

val packages : t -> (string * Package_config.t) list
(** [packages t] returns the list of package overrides. *)

val package_config : t -> string -> Package_config.t option
(** [package_config t name] returns package-specific configuration overrides for
    the named package, if any exist. *)

(** {1 Derived Paths} *)

val default_branch : string
(** Default git branch, always ["main"]. *)

val mono_path : t -> Fpath.t
(** [mono_path t] returns the path to the user's monorepo. *)

val src_path : t -> Fpath.t
(** [src_path t] returns the path to git checkouts. *)

val opam_repo_path : t -> Fpath.t
(** [opam_repo_path t] returns the path to the opam overlay. *)

val verse_path : t -> Fpath.t
(** [verse_path t] returns the path to tracked members' monorepos. *)

(** {1 Backwards Compatibility} *)

(** Path accessors using old naming convention. *)
module Paths : sig
  val opam_repo : t -> Fpath.t
  (** Alias for [opam_repo_path]. *)

  val checkouts : t -> Fpath.t
  (** Alias for [src_path]. *)

  val monorepo : t -> Fpath.t
  (** Alias for [mono_path]. *)
end

(** {1 XDG Paths} *)

val config_dir : unit -> Fpath.t
(** [config_dir ()] returns the XDG config directory for monopam
    (~/.config/monopam). *)

val data_dir : unit -> Fpath.t
(** [data_dir ()] returns the XDG data directory for monopam
    (~/.local/share/monopam). *)

val cache_dir : unit -> Fpath.t
(** [cache_dir ()] returns the XDG cache directory for monopam
    (~/.cache/monopam). *)

val config_file : unit -> Fpath.t
(** [config_file ()] returns the path to the config file
    (~/.config/monopam/opamverse.toml). *)

val registry_path : unit -> Fpath.t
(** [registry_path ()] returns the path to the cloned registry git repo
    (~/.local/share/monopam/opamverse-registry). *)

(** {1 Construction} *)

val create :
  root:Fpath.t ->
  handle:string ->
  ?knot:string ->
  ?packages:(string * Package_config.t) list ->
  ?paths:paths ->
  unit ->
  t
(** [create ~root ~handle ?knot ?packages ?paths ()] creates a new configuration.

    @param root Workspace root directory (absolute path)
    @param handle User's handle
    @param knot Git push server hostname. If not provided, derived from handle
    @param packages Optional list of package overrides
    @param paths Optional custom paths configuration *)

val with_package_override : t -> name:string -> ?branch:string -> unit -> t
(** [with_package_override t ~name ?branch ()] returns a new config
    with overrides for the named package. *)

(** {1 Validation} *)

type validation_error =
  | Path_not_found of string * Fpath.t
  | Not_a_directory of string * Fpath.t
  | Not_an_opam_repo of Fpath.t
  | Invalid_path of string * string
  | Relative_path of string * Fpath.t

val pp_validation_error : validation_error Fmt.t
(** [pp_validation_error] formats validation errors. *)

(** {1 Loading and Saving} *)

val load : fs:_ Eio.Path.t -> unit -> (t, string) result
(** [load ~fs ()] loads the configuration from the XDG config file.

    @param fs Eio filesystem *)

val save : fs:_ Eio.Path.t -> t -> (unit, string) result
(** [save ~fs config] saves the configuration to the XDG config file.

    @param fs Eio filesystem
    @param config Configuration to save *)

(** {1 Pretty Printing} *)

val pp : t Fmt.t
(** [pp] is a formatter for configuration. *)