gemini-cli-sdk 0.1.0

//! Client configuration.
//!
//! The primary entry point for configuring a Gemini CLI session is
//! [`ClientConfig`], built via the [`TypedBuilder`]-derived builder pattern.
//!
//! # Example
//!
//! ```rust,no_run
//! use gemini_cli_sdk::config::{ClientConfig, PermissionMode};
//!
//! let config = ClientConfig::builder()
//!     .prompt("Summarise the repo")
//!     .model("gemini-2.5-pro")
//!     .permission_mode(PermissionMode::AcceptEdits)
//!     .build();
//!
//! let args = config.to_cli_args();
//! assert!(args.contains(&"--approval-mode".to_string()));
//! ```

use std::collections::{BTreeMap, HashMap};
use std::path::PathBuf;
use std::sync::Arc;
use std::time::Duration;

use serde::{Deserialize, Serialize};
use typed_builder::TypedBuilder;

use crate::hooks::HookMatcher;
use crate::mcp::McpServers;
use crate::permissions::CanUseToolCallback;

// Re-export `MessageCallback` so callers can import it from this module,
// mirroring the claude-cli-sdk API surface.
pub use crate::callback::MessageCallback;

// ── ClientConfig ────────────────────────────────────────────────────────────

/// Full configuration for a Gemini CLI session.
///
/// Built with the [`TypedBuilder`] pattern. Only `prompt` is required; all
/// other fields have sensible defaults. Gemini-specific fields (`auth_method`,
/// `sandbox`, `extra_args`) extend the common set.
///
/// # Example
///
/// ```rust,no_run
/// use gemini_cli_sdk::config::{ClientConfig, AuthMethod};
///
/// let config = ClientConfig::builder()
///     .prompt("Hello, Gemini!")
///     .model("gemini-2.5-flash")
///     .auth_method(AuthMethod::ApiKey)
///     .verbose(true)
///     .build();
/// ```
#[derive(TypedBuilder)]
pub struct ClientConfig {
    // ── Required ────────────────────────────────────────────────────────────

    /// The prompt text sent to the CLI.
    #[builder(setter(into))]
    pub prompt: String,

    // ── CLI process ─────────────────────────────────────────────────────────

    /// Override the path to the `gemini` CLI binary.
    /// When `None`, the binary is located via `PATH` using [`which`].
    #[builder(default, setter(strip_option))]
    pub cli_path: Option<PathBuf>,

    /// Working directory for the CLI subprocess.
    /// Defaults to the current process's working directory when `None`.
    #[builder(default, setter(strip_option))]
    pub cwd: Option<PathBuf>,

    // ── Model ───────────────────────────────────────────────────────────────

    /// Gemini model identifier (e.g., `"gemini-2.5-pro"`).
    #[builder(default, setter(strip_option, into))]
    pub model: Option<String>,

    // ── Session behaviour ────────────────────────────────────────────────────

    /// Custom system prompt injected into the session.
    #[builder(default, setter(strip_option))]
    pub system_prompt: Option<SystemPrompt>,

    /// Maximum number of agentic turns before the session is terminated.
    #[builder(default, setter(strip_option))]
    pub max_turns: Option<u32>,

    // ── Tools ───────────────────────────────────────────────────────────────

    /// Tool names the CLI is explicitly permitted to use.
    /// An empty list means all tools are allowed (subject to `disallowed_tools`).
    #[builder(default)]
    pub allowed_tools: Vec<String>,

    /// Tool names that are always denied, overriding `allowed_tools`.
    #[builder(default)]
    pub disallowed_tools: Vec<String>,

    // ── Permissions ──────────────────────────────────────────────────────────

    /// Global permission mode passed to the CLI via approval-mode flags.
    #[builder(default)]
    pub permission_mode: PermissionMode,

    /// Fine-grained per-tool permission callback, evaluated before each tool
    /// execution. Takes precedence over `permission_mode` for individual calls.
    #[builder(default, setter(strip_option))]
    pub can_use_tool: Option<CanUseToolCallback>,

    // ── Session resume ───────────────────────────────────────────────────────

    /// Session ID to resume. When set, the CLI is invoked with `--resume`.
    #[builder(default, setter(strip_option, into))]
    pub resume: Option<String>,

    // ── Hooks ────────────────────────────────────────────────────────────────

    /// Event hooks that fire at defined points in the session lifecycle.
    #[builder(default)]
    pub hooks: Vec<HookMatcher>,

    // ── MCP ─────────────────────────────────────────────────────────────────

    /// MCP server configurations forwarded to the CLI at session creation.
    #[builder(default)]
    pub mcp_servers: McpServers,

    // ── Callbacks ────────────────────────────────────────────────────────────

    /// Optional callback invoked for each message before it is yielded to the
    /// stream. Suitable for logging, persistence, or UI updates.
    #[builder(default, setter(strip_option))]
    pub message_callback: Option<MessageCallback>,

    // ── Process environment ──────────────────────────────────────────────────

    /// Additional environment variables injected into the CLI subprocess.
    #[builder(default)]
    pub env: HashMap<String, String>,

    /// Enable verbose CLI output (passes the `--debug` flag, or equivalent).
    #[builder(default)]
    pub verbose: bool,

    // ── Gemini-specific ──────────────────────────────────────────────────────

    /// Authentication method for the Gemini CLI.
    ///
    /// Auth is configured via environment variables rather than CLI flags:
    /// - [`LoginWithGoogle`] — expects the user to have run `gemini auth login`.
    /// - [`ApiKey`] — reads `GEMINI_API_KEY` from the environment.
    /// - [`VertexAi`] — reads `GOOGLE_CLOUD_PROJECT` + ADC credentials.
    ///
    /// This field does **not** generate CLI arguments in `to_cli_args()`.
    ///
    /// [`LoginWithGoogle`]: AuthMethod::LoginWithGoogle
    /// [`ApiKey`]: AuthMethod::ApiKey
    /// [`VertexAi`]: AuthMethod::VertexAi
    #[builder(default, setter(strip_option))]
    pub auth_method: Option<AuthMethod>,

    /// Run the session inside a sandbox.
    #[builder(default)]
    pub sandbox: bool,

    /// Arbitrary extra CLI flags. The map key becomes `--{key}`, the optional
    /// value is appended as a separate argument when `Some`.
    #[builder(default)]
    pub extra_args: BTreeMap<String, Option<String>>,

    // ── Timeouts ─────────────────────────────────────────────────────────────

    /// Timeout for the initial JSON-RPC connection handshake.
    #[builder(default_code = "Some(Duration::from_secs(30))")]
    pub connect_timeout: Option<Duration>,

    /// Grace period allowed for the CLI process to exit cleanly on shutdown.
    #[builder(default_code = "Some(Duration::from_secs(10))")]
    pub close_timeout: Option<Duration>,

    /// Per-read timeout on the stdio transport. `None` means no timeout.
    ///
    /// **Note:** This field is accepted for forward-compatibility but is not yet
    /// enforced by the transport layer. It is reserved for a future release.
    #[builder(default)]
    pub read_timeout: Option<Duration>,

    /// Default timeout budget given to each hook execution.
    #[builder(default_code = "Duration::from_secs(30)")]
    pub default_hook_timeout: Duration,

    /// Timeout for the background CLI version check. `None` skips the check.
    ///
    /// **Note:** This field is accepted for forward-compatibility but is not yet
    /// enforced by the transport layer. It is reserved for a future release.
    #[builder(default_code = "Some(Duration::from_secs(5))")]
    pub version_check_timeout: Option<Duration>,

    // ── Diagnostics ──────────────────────────────────────────────────────────

    /// Optional callback that receives every line written to the CLI's stderr.
    /// Useful for surfacing CLI-level warnings and errors to callers.
    #[builder(default, setter(strip_option))]
    pub stderr_callback: Option<Arc<dyn Fn(String) + Send + Sync>>,
}

impl ClientConfig {
    /// Translate this configuration into CLI arguments for the Gemini binary.
    ///
    /// The ACP mode flag (`--experimental-acp`) is always prepended. Remaining
    /// flags are derived from the fields that have non-default values.
    ///
    /// # Example
    ///
    /// ```rust
    /// use gemini_cli_sdk::config::{ClientConfig, PermissionMode};
    ///
    /// let config = ClientConfig::builder()
    ///     .prompt("test")
    ///     .permission_mode(PermissionMode::BypassPermissions)
    ///     .build();
    ///
    /// let args = config.to_cli_args();
    /// assert!(args.contains(&"--yolo".to_string()));
    /// ```
    pub fn to_cli_args(&self) -> Vec<String> {
        let mut args = vec!["--experimental-acp".to_string()];

        if let Some(model) = &self.model {
            args.push("--model".to_string());
            args.push(model.clone());
        }

        if self.sandbox {
            args.push("--sandbox".to_string());
        }

        match self.permission_mode {
            PermissionMode::Default => {}
            PermissionMode::AcceptEdits => {
                args.push("--approval-mode".to_string());
                args.push("auto_edit".to_string());
            }
            PermissionMode::Plan => {
                args.push("--approval-mode".to_string());
                args.push("plan".to_string());
            }
            PermissionMode::BypassPermissions => {
                args.push("--yolo".to_string());
            }
        }

        if self.verbose {
            args.push("--debug".to_string());
        }

        if let Some(turns) = self.max_turns {
            args.push("--max-turns".to_string());
            args.push(turns.to_string());
        }

        if let Some(sp) = &self.system_prompt {
            match sp {
                SystemPrompt::Text(text) => {
                    args.push("--system-prompt".to_string());
                    args.push(text.clone());
                }
                SystemPrompt::File(path) => {
                    args.push("--system-prompt-file".to_string());
                    args.push(path.to_string_lossy().to_string());
                }
            }
        }

        if !self.allowed_tools.is_empty() {
            args.push("--allowed-tools".to_string());
            args.push(self.allowed_tools.join(","));
        }

        if !self.disallowed_tools.is_empty() {
            args.push("--disallowed-tools".to_string());
            args.push(self.disallowed_tools.join(","));
        }

        for (key, value) in &self.extra_args {
            args.push(format!("--{key}"));
            if let Some(v) = value {
                args.push(v.clone());
            }
        }

        args
    }
}

// ── AuthMethod ───────────────────────────────────────────────────────────────

/// Authentication method passed to the Gemini CLI.
///
/// Determines how the CLI authenticates with Google's APIs. The default
/// (when `None` is set on [`ClientConfig`]) defers to the CLI's own
/// credential resolution order.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum AuthMethod {
    /// Interactive OAuth 2.0 flow — opens a browser window on first run.
    LoginWithGoogle,
    /// API key passed via the `GEMINI_API_KEY` environment variable.
    ApiKey,
    /// Vertex AI service account credentials.
    VertexAi,
}

// ── PermissionMode ───────────────────────────────────────────────────────────

/// Global permission mode controlling how the CLI handles tool approval.
///
/// Corresponds to the `--approval-mode` CLI flag, with [`BypassPermissions`]
/// mapping to `--yolo` for compatibility with the Gemini CLI's flag naming.
///
/// [`BypassPermissions`]: PermissionMode::BypassPermissions
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum PermissionMode {
    /// Default interactive approval — prompts for confirmation before tools run.
    #[default]
    Default,
    /// Automatically approve edit operations without prompting.
    AcceptEdits,
    /// Plan-only mode — the CLI describes actions but does not execute them.
    Plan,
    /// Skip all approval prompts. Use with caution in automated environments.
    BypassPermissions,
}

// ── SystemPrompt ─────────────────────────────────────────────────────────────

/// System prompt configuration.
///
/// The system prompt is injected into the session before the user's first
/// message. It can be provided as inline text or as a path to a file on disk
/// (which the CLI reads at startup).
#[derive(Debug, Clone)]
pub enum SystemPrompt {
    /// Inline system prompt text.
    Text(String),
    /// Path to a file containing the system prompt.
    File(PathBuf),
}

// ── Tests ────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use std::collections::BTreeMap;

    use super::{AuthMethod, ClientConfig, PermissionMode};

    // ── Builder construction ─────────────────────────────────────────────────

    #[test]
    fn test_config_builder_minimal() {
        // Only the required `prompt` field is set — all other fields take
        // their defaults. This verifies the builder compiles and produces a
        // valid struct without panicking.
        let config = ClientConfig::builder().prompt("test").build();
        assert_eq!(config.prompt, "test");
        assert!(config.cli_path.is_none());
        assert!(config.model.is_none());
        assert!(config.cwd.is_none());
        assert!(config.allowed_tools.is_empty());
        assert!(config.disallowed_tools.is_empty());
        assert!(config.hooks.is_empty());
        assert!(config.mcp_servers.is_empty());
        assert!(!config.sandbox);
        assert!(!config.verbose);
    }

    #[test]
    fn test_config_builder_with_model() {
        let config = ClientConfig::builder()
            .prompt("hello")
            .model("gemini-2.5-pro")
            .build();

        assert_eq!(config.model.as_deref(), Some("gemini-2.5-pro"));
    }

    // ── to_cli_args ──────────────────────────────────────────────────────────

    #[test]
    fn test_to_cli_args_default() {
        // Default config produces only the mandatory ACP flag.
        let config = ClientConfig::builder().prompt("test").build();
        let args = config.to_cli_args();
        assert_eq!(args, vec!["--experimental-acp"]);
    }

    #[test]
    fn test_to_cli_args_with_model() {
        let config = ClientConfig::builder()
            .prompt("test")
            .model("gemini-2.5-flash")
            .build();
        let args = config.to_cli_args();
        assert!(
            args.contains(&"--model".to_string()),
            "expected --model flag"
        );
        assert!(
            args.contains(&"gemini-2.5-flash".to_string()),
            "expected model value"
        );
        // Flags must be adjacent: --model <value>
        let model_pos = args.iter().position(|a| a == "--model").unwrap();
        assert_eq!(args[model_pos + 1], "gemini-2.5-flash");
    }

    #[test]
    fn test_to_cli_args_accept_edits() {
        let config = ClientConfig::builder()
            .prompt("test")
            .permission_mode(PermissionMode::AcceptEdits)
            .build();
        let args = config.to_cli_args();
        assert!(
            args.contains(&"--approval-mode".to_string()),
            "expected --approval-mode"
        );
        assert!(
            args.contains(&"auto_edit".to_string()),
            "expected auto_edit value"
        );
        let pos = args.iter().position(|a| a == "--approval-mode").unwrap();
        assert_eq!(args[pos + 1], "auto_edit");
    }

    #[test]
    fn test_to_cli_args_plan_mode() {
        let config = ClientConfig::builder()
            .prompt("test")
            .permission_mode(PermissionMode::Plan)
            .build();
        let args = config.to_cli_args();
        let pos = args.iter().position(|a| a == "--approval-mode").unwrap();
        assert_eq!(args[pos + 1], "plan");
    }

    #[test]
    fn test_to_cli_args_bypass() {
        let config = ClientConfig::builder()
            .prompt("test")
            .permission_mode(PermissionMode::BypassPermissions)
            .build();
        let args = config.to_cli_args();
        assert!(
            args.contains(&"--yolo".to_string()),
            "BypassPermissions must map to --yolo"
        );
        // --yolo and --approval-mode are mutually exclusive paths — ensure no
        // approval-mode flag leaks through alongside --yolo.
        assert!(
            !args.contains(&"--approval-mode".to_string()),
            "--approval-mode must not appear alongside --yolo"
        );
    }

    #[test]
    fn test_to_cli_args_sandbox() {
        let config = ClientConfig::builder()
            .prompt("test")
            .sandbox(true)
            .build();
        let args = config.to_cli_args();
        assert!(
            args.contains(&"--sandbox".to_string()),
            "sandbox=true must emit --sandbox"
        );
    }

    #[test]
    fn test_to_cli_args_sandbox_false_omitted() {
        // sandbox defaults to false; the flag must not appear.
        let config = ClientConfig::builder().prompt("test").build();
        let args = config.to_cli_args();
        assert!(
            !args.contains(&"--sandbox".to_string()),
            "--sandbox must not appear when sandbox=false"
        );
    }

    #[test]
    fn test_to_cli_args_extra() {
        let mut extra = BTreeMap::new();
        extra.insert("temperature".to_string(), Some("0.7".to_string()));
        extra.insert("top-p".to_string(), None);

        let config = ClientConfig::builder()
            .prompt("test")
            .extra_args(extra)
            .build();
        let args = config.to_cli_args();

        assert!(
            args.contains(&"--temperature".to_string()),
            "extra key must become --<key>"
        );
        assert!(
            args.contains(&"0.7".to_string()),
            "extra value must appear as a separate arg"
        );
        assert!(
            args.contains(&"--top-p".to_string()),
            "flag-only extra arg must appear without a value"
        );
    }

    #[test]
    fn test_to_cli_args_extra_btreemap_ordering() {
        // BTreeMap is sorted alphabetically; verify the output order is stable.
        let mut extra = BTreeMap::new();
        extra.insert("zzz".to_string(), Some("last".to_string()));
        extra.insert("aaa".to_string(), Some("first".to_string()));

        let config = ClientConfig::builder()
            .prompt("test")
            .extra_args(extra)
            .build();
        let args = config.to_cli_args();

        // --experimental-acp comes first; then aaa, then zzz (alpha order).
        let aaa_pos = args.iter().position(|a| a == "--aaa").unwrap();
        let zzz_pos = args.iter().position(|a| a == "--zzz").unwrap();
        assert!(aaa_pos < zzz_pos, "--aaa must precede --zzz (BTreeMap order)");
    }

    // ── PermissionMode ───────────────────────────────────────────────────────

    #[test]
    fn test_permission_mode_default() {
        assert_eq!(
            PermissionMode::default(),
            PermissionMode::Default,
            "Default must be the zero-value for PermissionMode"
        );
    }

    #[test]
    fn test_permission_mode_debug() {
        // Ensure all variants have a Debug impl (derived).
        let _ = format!("{:?}", PermissionMode::Default);
        let _ = format!("{:?}", PermissionMode::AcceptEdits);
        let _ = format!("{:?}", PermissionMode::Plan);
        let _ = format!("{:?}", PermissionMode::BypassPermissions);
    }

    // ── AuthMethod ───────────────────────────────────────────────────────────

    #[test]
    fn test_auth_method_serde_roundtrip() {
        for variant in [
            AuthMethod::LoginWithGoogle,
            AuthMethod::ApiKey,
            AuthMethod::VertexAi,
        ] {
            let json = serde_json::to_string(&variant).expect("serialize");
            let recovered: AuthMethod = serde_json::from_str(&json).expect("deserialize");
            assert_eq!(variant, recovered, "serde roundtrip failed for {json}");
        }
    }

    #[test]
    fn test_auth_method_partial_eq() {
        assert_eq!(AuthMethod::ApiKey, AuthMethod::ApiKey);
        assert_ne!(AuthMethod::ApiKey, AuthMethod::VertexAi);
    }

    // ── Timeouts ─────────────────────────────────────────────────────────────

    #[test]
    fn test_default_timeouts() {
        let config = ClientConfig::builder().prompt("test").build();
        assert_eq!(
            config.connect_timeout,
            Some(std::time::Duration::from_secs(30)),
            "connect_timeout default must be 30 s"
        );
        assert_eq!(
            config.close_timeout,
            Some(std::time::Duration::from_secs(10)),
            "close_timeout default must be 10 s"
        );
        assert_eq!(
            config.default_hook_timeout,
            std::time::Duration::from_secs(30),
            "hook timeout default must be 30 s"
        );
        assert_eq!(
            config.version_check_timeout,
            Some(std::time::Duration::from_secs(5)),
            "version_check_timeout default must be 5 s"
        );
        assert!(
            config.read_timeout.is_none(),
            "read_timeout must default to None"
        );
    }

    // ── Verbose flag ─────────────────────────────────────────────────────────

    #[test]
    fn test_to_cli_args_verbose() {
        let config = ClientConfig::builder()
            .prompt("test")
            .verbose(true)
            .build();
        let args = config.to_cli_args();
        assert!(
            args.contains(&"--debug".to_string()),
            "verbose=true must emit --debug"
        );
    }

    #[test]
    fn test_to_cli_args_verbose_false_omitted() {
        let config = ClientConfig::builder().prompt("test").build();
        let args = config.to_cli_args();
        assert!(
            !args.contains(&"--debug".to_string()),
            "--debug must not appear when verbose=false"
        );
    }

    #[test]
    fn test_to_cli_args_max_turns() {
        let config = ClientConfig::builder()
            .prompt("test")
            .max_turns(5_u32)
            .build();
        let args = config.to_cli_args();
        let pos = args.iter().position(|a| a == "--max-turns").expect("--max-turns missing");
        assert_eq!(args[pos + 1], "5");
    }

    #[test]
    fn test_to_cli_args_system_prompt_text() {
        let config = ClientConfig::builder()
            .prompt("test")
            .system_prompt(crate::config::SystemPrompt::Text("You are helpful.".to_string()))
            .build();
        let args = config.to_cli_args();
        let pos = args.iter().position(|a| a == "--system-prompt").expect("--system-prompt missing");
        assert_eq!(args[pos + 1], "You are helpful.");
    }

    #[test]
    fn test_to_cli_args_system_prompt_file() {
        let config = ClientConfig::builder()
            .prompt("test")
            .system_prompt(crate::config::SystemPrompt::File(
                std::path::PathBuf::from("/etc/prompt.txt"),
            ))
            .build();
        let args = config.to_cli_args();
        let pos = args.iter().position(|a| a == "--system-prompt-file").expect("--system-prompt-file missing");
        assert_eq!(args[pos + 1], "/etc/prompt.txt");
    }

    #[test]
    fn test_to_cli_args_allowed_tools() {
        let config = ClientConfig::builder()
            .prompt("test")
            .allowed_tools(vec!["read_file".to_string(), "write_file".to_string()])
            .build();
        let args = config.to_cli_args();
        let pos = args.iter().position(|a| a == "--allowed-tools").expect("--allowed-tools missing");
        assert_eq!(args[pos + 1], "read_file,write_file");
    }

    #[test]
    fn test_to_cli_args_disallowed_tools() {
        let config = ClientConfig::builder()
            .prompt("test")
            .disallowed_tools(vec!["shell".to_string()])
            .build();
        let args = config.to_cli_args();
        let pos = args.iter().position(|a| a == "--disallowed-tools").expect("--disallowed-tools missing");
        assert_eq!(args[pos + 1], "shell");
    }

    #[test]
    fn test_to_cli_args_empty_tool_lists_omitted() {
        // Default (empty) lists must NOT emit any flags.
        let config = ClientConfig::builder().prompt("test").build();
        let args = config.to_cli_args();
        assert!(!args.contains(&"--allowed-tools".to_string()));
        assert!(!args.contains(&"--disallowed-tools".to_string()));
    }

    // ── experimental-acp always present ─────────────────────────────────────

    #[test]
    fn test_to_cli_args_always_has_acp_flag() {
        // Regardless of other settings, the ACP flag is always the first arg.
        let config = ClientConfig::builder()
            .prompt("p")
            .model("gemini-2.5-pro")
            .sandbox(true)
            .permission_mode(PermissionMode::BypassPermissions)
            .build();
        let args = config.to_cli_args();
        assert_eq!(
            args[0], "--experimental-acp",
            "--experimental-acp must always be the first argument"
        );
    }
}